Allow content-mappers to return declarations instead of source files

🔍 Search Terms

content mapper

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

I would like to be able to opt out of lint-like TypeScript errors for content-mappers. For example, I might want to use ESM syntax in a CJS context, even if verbatimModuleSyntax is allowed. Or I would like to use export =, even is module is set to esnext.

A context where these rules don’t apply, are declaration files.

📃 Motivating Example

Content mapper authors can now return a .d.ts, .d.cts, or .d.mts extension as part of the transform response.

💻 Use Cases

I realized you can sort of categorize content mappers into two categories.

The first category is files with embedded JavaScript/TypeScript content. This includes Astro, Ember, MDX, Svelte, and Vue. This is the typical use case for content mappers. In this case it makes sense for the format to be opiniated about the module format.

The second category is static data that can be imported, but has a known shape. I just published css-modules-content-mapper. This always exports a value whose type matches Record<string, string>, but the keys are known. Other formats in this category are JSON5, TOML, YAML, XML, etc. These formats can always be written using type declarations only.

For this second category, I would really like to not care about the module format used. I want to use export = and tell TypeScript to treat it as a .d.${ext}.cts file.

A workaround is to add an @ts-ignore comment to the export = line, but that seems less ideal.