Since the types are separated from their implementations, it makes sense to gather all of the public API types in a single file. This makes it easy to maintain the public API since it is not scattered in multiple files.

The single file that contains the public API can in fact be a manually created index.d.ts file, and hence reduce the need for .d.ts files generation. The files that define the implementations of the public API will derive their corresponding types from index.d.ts so that they can conform to it.

index.d.ts can act as documentation. The documentation section of the README.md of a project can just link to index.d.ts. This makes documentation generation libraries for the most cases redundant.

Here is an example:

• ./index.d.ts

  /**
   * @description
   * My super function.
  */
  export declare const add : (a : number,b : number) => number;

• ./privateApi.ts

  import {add} from "index";
  
  export type IAdd = typeof add;

• ./add.ts

  import type {IAdd} from "./privateApi";
  
  export const add : IAdd = (a,b) => a+b;

• ./index.ts

  export {add} from "./add";

Notice that both the types and the JSDoc descriptions are contained in index.d.ts, that means that imports from index show (or can be made to show) both the type and the JSDoc description of index.d.ts in the IDE documentation popup window, when you hover over the imported variable.

You can put the most important types in the top of index.d.ts, and the least important in the bottom. You can manually edit the format, define types and IDE collapsible regions for the sole purpose of improving public API readability for both the library maintainer but also the library consumer. Finally index.d.ts opens in your IDE, with the font, syntax highlighting, theme and keyboard shortcuts your are familiar with. It is not trivial to do these with documentation generation libraries (e.g. typedoc).

Many times, I find myself trying to bundle a library to an esm index.js file with its associated index.d.ts file. From the previous points it can be seen that there will be a reduced need for .d.ts bundlers. Just make sure that index.d.ts is indeed acting like a public API, i.e. it does not depend on the private API and hence imports nothing from it.

You just need these two things:

• type imports

  import type {IAdd} from "./index";

• type annotations for variable declarations

  export const add : IAdd = (a,b) => a+b;

Although this point might initially seem not that much of a big deal, it is actually the gateway to the next section.

Not only the public API, but also the private API can be contained in a single file, or at least a few files. This, combined with the fact of minimum syntax reservation, makes the migration (automated or manual) from one type system to another, easier.

A direct result of reserving the least possible syntax. They no longer need to enable mix of implementation and indent.

A direct result of reserving the least possible syntax.

A direct result of reserving the least possible syntax.

A direct result of reserving the least possible syntax.

More specifically, when you write the implementation of a type you will have to frequently switch between the implementation file and the abstraction file, because you want to see the type. This is not valid since the IDE will show you the type of an implementation by hovering on its annotation. Also the IDE will highlight the parts of the implementation that do not conform to the type.

More specifically because the files for types can grow large, that will make it hard to find the types. This is not valid since if you know where the implementation of the type is, then you can use the go to type definition feature of your IDE to find it.

Multiple .ts files can be used to segregate the common space. Here is a possible example:

• index.d.ts is used to define the public API
• privateApi.ts is used to define the private API
• types.ts is used to define types shared in privateApi.ts
• trivialApi.ts is used to define less complex types (e.g. string[],number etc.)
• testApi.ts is used to define types that are used only in test files
• typeFunctions.ts is used to define type functions
• dicApi.ts is used to define the types of the dependency graph of the DIC

If the public API depends on te private API, then reverse the dependency, and make the private API depend on the public API.

Type assertions[link] are a bad practice since they override the type checker. It is true that the override is safer than //@ts-ignore, but that does not change the fact that it is an override. This:

const myVariable = myValues as number;

can be replaced with this:

if (typeof myValue !== "number") throw Error();
const myVariable = myValues;

leading to safer static type checking. It is the ability to use type assertions that leads to loss in static typing, not the inability to use them.

Since TypeScript 5.0, instead of using const type assertion you can do something like:

• ./privateApi

  export type IAsConstArray = <const T extends readonly unknown[]>(array : T) => T;

• index.js

  /**@type {import("./privateApi").IAsConstArray}*/
  const asConstArray = (array) => array;
  
  const myData = asConstArray([1,2]);

Consider using a library that was written in TypeScript with the following public API:

• ./index.d.ts:

  /**
   * @description 
   *`DLL` stands for Double Linked List.
  */
  export declare function DLLFactory<T>() : IDLL<T>;
  
  type IDLLNode<T> = {
      value    : T;
      next     : IDLLNode<T> | null;
      previous : IDLLNode<T> | null;
  };
  type IDLL<T> = {
      tail   : IDLLNode<T> | null;
      head   : IDLLNode<T> | null;
      length : number;
  };

Here is how to pass a type parameter to DLLFactory using the complement method:

• ./privateApi.ts

  import {DLLFactory} from "./index";
  
  // works with typescript 4.7
  export type IMyDllFactory = typeof DLLFactory<number>;

• ./myDLL.js

  import {DLLFactory} from "./index.js";
  
  /**
   * @type {import("./privateApi").IMyDllFactory}
   * Hover over `myDLLFactory` to see that the type parameter is `number`.
   */
  const myDLLFactory = DLLFactory;

Something that should be noted here, is that this is not possible with older versions of TypeScript. Given that TypeScript is mostly used as a super set, it makes sense for features that mainly benefit the complement method to not have been requested, e.g. type parameters extraction[link]. So whenever we are faced in a situation that challenges the complement method, we should question whether this is an intrinsic inability of the complement method or a matter of support from the type system.

This is not an intrinsic inability of the complement method, since[link]:

Enums are one of the few features TypeScript has which is not a type-level extension of EcmaScript.

So it is both a matter of support from the type system but also EcmaScript.

Objectively speaking, knowing the type of a concretion makes it easier to read the code. How can someone know the type of a concretions when writing code in EcmaScript, i.e. the complement method? Hovering over any implementation, will make the IDE to show its type. Do super sets need that help from the IDE? Yes they do, because of type aliases.

Given that help from the IDE, it becomes subjective which code base is more readable. From my personal experience the more I get exposed to a certain code style, the more readable I find it. So if you think that the complement method is not readable, I suggest you, to ask yourself the same question after some months you have been exposed to it. Eventually you will get used to it and readability will not be an issue.

Regarding verbosity, strictly speaking, a super set can always be made less verbose when compared to a complement, since a complement is forced to use the already existing comment syntax, while a super set reserves syntax outside of existing comment syntax. However, from my experience with the complement and super set methods of TypeScript, there is no practical impact in the developer experience. In fact when comparing them, it is not actually clear which method is less verbose, because in some cases, the complement method is less verbose while in other cases the super set method is less verbose.

This is a logical fallacy called argumentum ad populum[link]. The fact, that something has be chosen by the majority, does not prove it is the best choice.

If we want to know which method is preferred by the community, then we have to ask people, that have tried both complement and super set methods, and have no misconceptions about them. Any statistical inference based on something different from that, is intrinsically biased.

Lets look at the topic from a historical perspective:

• 1999 JSDoc[link]
• 2009 Closure Compiler[link]
• 2012 TypeScript[link]
• 2014 Flow[link]
• 2018 TypeScript supports /**@type {import("./some/path").IMyType}*/[link]
• 2022 TypeScript supports type IMyFn = typeof fn<IMyType>[link]
• 2022 TypeScript feature request for extracting type parameters[link]
• 2023 TypeScript supports const generics[link]

Why people use TypeScript instead of plain JSDoc?

Regarding static typing, JSDoc syntax is verbose when compared to TypeScript. This should not surprise us since JSDoc syntax was made to favor documentation, while TypeScript syntax was made to favor static typing. Finally JSDoc lacks in static typing support when compared to TypeScript.

Why people use TypeScript instead of Google's closure compiler?

Same arguments that were used about JSDoc apply here as well.

Why people use TypeScript instead of Flow?

Typescript "hit the market" first when compared to Flow.

Why people use TypeScript as a super set and not as a complement?

That is because TypeScript as a complement has been possible only very recently. To add to that, statically typed complements have never been promoted.

Why the TypeScript creators decide to go for super set instead of complement?

I do not know. The TypeScript creators have to answer that.