implement tagged template string support for inlining d.ts

[frank-dspeed]

Suggestion

🔍 Search Terms

tagged template string literal declaration inline d.ts js javascript ecmascript

✅ Viability Checklist

My suggestion meets these guidelines:

• 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 feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

the jsdoc format is not multi-line capable out of history with tagged template strings for example html``
lets implement typescriptDefinition`` or something similar uniqe make it a exclusive word and allow common typescript declaration syntax inside that. also rank that higher then external .d.ts

📃 Motivating Example

we can more easy bundle our types directly inside the resulting .js file without additional lockups while we can transpile them away if needed or even use them to build runtime checks.

a tagged template string literal is simply a function that accepts unlimited arguments so it is a noOp by default while it is parse able it is not as light wight as a comment but it is still not adding much overhead.

💻 Use Cases

inline typescript declaration syntax where jsdoc is not the best solution or even impossible. also more easy Adopt and preserve typescript syntax when transpiling or bundling. The need for a extra file is always complicated and .ts files are simply not run able without removing the typescript boilerplate.

this should close the gap maybe.
example.js

typescriptDefinition`export function getArrayLength(arr: any[]): number;
export const maxInterval: 12;`

const maxInterval = 12;
function getArrayLength(arr) {
  return arr.length;
}
module.exports = {
  getArrayLength,
  maxInterval,
};

example2.js

typescriptDefinition`export const maxInterval: 12;`;
const maxInterval = 12;

typescriptDefinition`export function getArrayLength(arr: any[]): number;`;
function getArrayLength(arr) {
  return arr.length;
}

module.exports = {
  getArrayLength,
  maxInterval,
};

Local only type definition example:
example3.js

typescriptDefinition`const _private: 33;`;
const _private = 33

js files containing the typescriptDefinition tagged template string literal should get handled like js files but with already existing.d.ts file if there is a d.ts file simply rank it lower then the existing local definitions and merge none existing.

to illustrate that lets take example3.js and translate it to its representation 1:1

typescriptDefinition`const _private: 33;`; // example3.d.ts
const _private = 33 // example3.js

Missing part

we need to create the taggedTemplateStringLiteral with a import able no oOp helper like
node_modules/typescript/definition.js

/** @type {(args: any)=>void} */
export const typescriptDefinition = (...args) => {};

so that it exists in userSpace without the need for a global so a bit like import type {}

import { typescriptDefinition } from 'typescript/definition';
typescriptDefinition`const _private: 33;`; // example3.d.ts
const _private = 33 // example3.js

[fatcerberus]

This isn’t even how .d.ts files work. You can’t use external definitions to type unannotated locals within a file (like what you’re trying to do there with const _private), inlining the definitions won’t solve that.

[frank-dspeed]

@fatcerberus ok all i wanted is to have the same content that gets storred to corrosponding .d.ts file to be supported as if it would be in the d.ts file

[DanielRosenwasser]

There's a separate issue around being able to describe the types of a .ts file using a .d.ts file, kind of like a signature file in OCaml and Standard ML - but I can't find it.

In any case, I don't think that the idea of putting corresponding declarations (the signatures and annotations) for actual definitions in a template string is one that we have an appetite for.

[MartinJohns]

There's a separate issue around being able to describe the types of a .ts file using a .d.ts file, kind of like a signature file in OCaml and Standard ML - but I can't find it.

You probably mean #30304 and #29056.

[frank-dspeed]

@MartinJohns that where really helpfull issues they pointed me to the main problem there is a chicken egg problem with .js + d.ts and .js + jsdoc as also .ts

thanks for enlighten me i will come up with a much better issue.