Align with TypeScript declaration maps feature?

[justingrant]

TypeScript has a feature called declaration maps which is to .d.ts declaration files what a source map is to a JS file. The declaration map file allows IDEs to navigate from a TS declaration to the transpiled JS that implement that declaration. This allows a developer in VS Code to right-click on a library method, pick "Go To Implementation" from the context menu, and be navigated to the TS file in node_modules that implements that method.

It may be worth connecting with someone on the TS team to understand how they're using the source map spec, and to avoid breaking them with future changes to the source maps spec.

I'm not sure how declaration maps interact with source maps, if at all. For example, the simple index.d.ts.map file example below works great if the npm package includes its src directory in the package. But what if ../src/index.ts only exists as sources and sourcesContent in index.js.map? How will VS Code know to look for that file's TS source in an inline sourcesContent source map if the sources files are not present on disk?

{
  "version": 3,
  "file": "index.d.ts",
  "sourceRoot": "",
  "sources": [
    "../src/index.ts"
  ],
  "names": [],
  "mappings": "AAMA,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,iBAGvC"
}

[rbuckton]

TypeScript generates declaration maps to improve build and editor performance in multi-project workspaces that use project references. Rather than parse and type check the original source files of a project reference, we are able to use the built .d.ts output of the project instead, which can be parsed and checked far faster. We use declaration maps to enable editor features like "Find References" and "Go To Definition" across projects so that when using these capabilities to navigate to a declaration from a declaration file, we can instead navigate to the original source location in the referenced project.

Declaration maps act like any other source map and contain no extensions or additional capabilities.
The following table describes what source map fields are supported by declaration maps:

Field	Emits	Supports	Notes
"version"	yes	required	Must be the value 3
"file"	yes	required	Used in path calculations
"sourceRoot"	yes	supported	Used in path calculations
"sources"	yes	required	Used in path calculations
"sourcesContent"	no	no*	The file cannot be used as a declaration map if present
"names"	no*	ignored	* Emits [], but is otherwise unused
"mappings"	yes*	required*	* Does not emit, or use, the "names" offset

Additionally, declaration maps support //# sourceMappingURL= per the following rules:

• Relative paths are supported
• Posix, DOS, and UNC absolute paths are supported
• data: URLs are supported with restrictions:
  • Content type must be application/json
  • Charset must be utf-8 if specified
  • Data format must be base64
• Other URLs are only supported if the host provided to the TypeScript language server provides support for them. They are not supported by default and the API does not support asynchronous loading, so non-local resources (i.e., accessed via https://, etc.) are not supported unless already cached locally.

Declaration maps do not support index maps.