I'm trying to write a Typescript library that I'd like to be able to include when targeting both the browser and Node. I have two problems: referring to platform-specific types in the body of the code, and the inclusion of those types in the generated .d.ts declarations that accompany the transpiled JS.
In the first case, I want to write something like
if (typeof window === "undefined") {
// Do some Node-y fallback thing
} else {
// Do something with `window`
}
This fails to compile if I don't include "dom" in my lib compiler option (that is, if I just say lib: ["es2016"] in tsconfig), because the global window is not defined. (Using window is just an example of something out of lib.dom.d.ts, it may also be fetch or a Response or Blob, etc.) The point is that the code should already be safe at runtime by checking for the existence of the global object before using it, it's the type side that I can't figure out.
In the second case, I'm getting an error trying to include the library after it builds. I can build the library using "dom" in the lib option, and the resulting output includes typings with e.g. declare export function foo(x: string | Blob): void. The problem is, if the consuming code doesn't include a definition for Blob (no "dom" lib), it fails to compile, even though it's only actually calling foo with a string (or not using foo at all!).
I don't want my library (or the consumer) to try to pollute the global namespace with fake window or Blob declarations if I can help it. More isometric libraries have been popping up but I haven't found a good Typescript example to follow. (If it's too complex a topic for SO, I'd still greatly appreciate a pointer to documentation or an article/blog post.)
I think that this is a classic case for abstraction and a straightforward one. That is, you code against a IPlatform interface and refer to that interface in your code. The interface in turn hides all the platform specific implementations.
You can also additionally expose APIs so that consumers can easily initialize the "platform", usually with the appropriate "global" object. Employ dependency injection to inject the correct (platform-specific) instance of IPlatform to your code. This should reduce branching in your code severely and keep your code cleaner. You don't have to pollute your code with fake declarations with that approach, as you have pointed out in your question.
Optionally, you can also export the IPlatform instance from your package so that the consumers can also reap the benefit of that.
The second problem you mentioned:
The problem is, if the consuming code doesn't include a definition for Blob (no "dom" lib), it fails to compile, even though it's only actually calling foo with a string (or not using foo at all!).
I think this can be easily countered by installing @types/node as devDependency on the consumer side. That should be of relatively low footprint, as that will not add to a consumer's bundle.
Unfortunately, there isn't a great way to do this currently.
The approach suggested by members of the TypeScript team is to take advantage of the interface merging feature of TypeScript, and "forward declare" interfaces in the global scope which can potentially merge with the declarations of the same interface in the consuming environment.
One common example of this might be the Buffer type built into Node.js. A library that operates in both browser and Node.js contexts can state that it handles a Buffer if given one, but the capabilities of Buffer aren't important to the declarations.
export declare function printStuff(str: string): void; /** * NOTE: Only works in Node.js */ export declare function printStuff(buff: Buffer): void;One technique to get around this is to "forward declare" Buffer with an empty interface in the global scope which can later be merged.
declare global { interface Buffer {} } export declare function printStuff(str: string): void; /** * NOTE: Only works in Node.js */ export declare function printStuff(buff: Buffer): void;
This approach has some problems, as elaborated on in the issue linked above:
The TypeScript team has proposed a new feature called "Placeholder Type Declarations" to address these issues, but it doesn't appear to be on the roadmap currently.