const assertions in JSDoc

[ajafff]

Search Terms

const jsdoc

Suggestion

v3.4 added support for as const to mark a literal expression as immutable and disable type widening. This feature uses the TypeScript type assertion syntax {} as const or <const>{}.

In JS files you can use JSDoc to do type assertions: /** @type {T} */(v)
Unfortunately that doesn't work with const assertions.

// @ts-check
const foo = /** @type {const} */([1]); // Error: cannot find name 'const'

This proposes adding support for /** @type {const} */([1]).

An alternative could be /** @const */([1]).

Use Cases

The same as for const assertions in TS files.

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

[texastoland]

It's a small difference, but /** @const */ would be much nicer than /** @type {TypeIOnlyDefinedToMakeThisReadable} */. I see the consistency with /** @type {const} */, too.

[MrEfrem]

When is planning to implement this?

[grrowl]

Not sure if it suits typescript's "value as const" pattern but JSDoc already includes the @constant annotation: https://jsdoc.app/tags-constant.html

/** @constant
    @type {string}
    @default
*/
const RED = 'FF0000';

/** @constant {number} */
var ONE = 1;

[pastelmind]

As a workaround, you can use identity functions to coerce string and number literals to literal types:

/**
 * Identity function. Coerces string/number literals to literal types.
 * @template {string | number} T
 * @param {T} v
 * @return {T}
 */
function c(v) {
  return v;
}

/**
 * Creates a tuple (array) from the given arguments.
 * @template {any[]} T
 * @param {T} v
 * @return {T}
 */
function t(...v) {
  return v;
}

const MyLiteralObject = {
  string_before: "foo bar",          // string
  string_after: c("foo bar"),        // "foo bar"
  number_before: 42,                 // number
  number_after: c(42),               // 42
  array_before: [2, "dog"],          // (string | number)[]
  array_after: t(c(2), c("dog")),    // [2, "dog"]
  empty_array: [],                   // any[]
  empty_tuple: t(),                  // []
};

[intptr-t]

@pastelmind's idea one solution, but I'm concerned about the overhead.
I think we need a way to prevent c and v from being executed.

As a workaround, you can use identity functions to coerce string and number literals to literal types:

/**
 * Identity function. Coerces string/number literals to literal types.
 * @template {string | number} T
 * @param {T} v
 * @return {T}
 */
function c(v) {
  return v;
}

/**
 * Creates a tuple (array) from the given arguments.
 * @template {any[]} T
 * @param {T} v
 * @return {T}
 */
function t(...v) {
  return v;
}

const MyLiteralObject = {
  string_before: "foo bar",          // string
  string_after: c("foo bar"),        // "foo bar"
  number_before: 42,                 // number
  number_after: c(42),               // 42
  array_before: [2, "dog"],          // (string | number)[]
  array_after: t(c(2), c("dog")),    // [2, "dog"]
  empty_array: [],                   // any[]
  empty_tuple: t(),                  // []
};

I think ajafff's idea is a good one.

I'm sorry I didn't have an idea,
I think we need an approach that can deal with more complex patterns.

// @ts-check
// ---- Substitute cases
const foo = /** @type {[1]} */ ([1]); // Good: foo is type [1]
foo[0] = 2; // <- ERROR: Type checking is working well!!

// ---- Cases that alternative solutions cannot handle
const complex1 = {
    /** @type {1} */
    item: 1, // <- Type check ERROR: 1 is a number
};

/** @constant */
const complex2 = {
    /** @constant {1} */
    item: 2, // <- Type check ERROR: 1 is a number
};
complex2.item = 3; // Type checking is not working.

[AlCalzone]

I want to provide an additional use case, now that #41631 was reopened and the official workaround is to use as const, which is not available in JS.

💻 Use Cases

In iobroker, objects in the database have different types that can be distinguished by how the ID is shaped. The different object types take different properties, so type-checking this would go a long way to reduce errors.

The type declarations already reflect this:
https://github.com/DefinitelyTyped/DefinitelyTyped/blob/81e930ed9983d081271ebf1978551b1e4c8b5b16/types/iobroker/iobroker-tests.ts#L649-L707
but this feature is limited to TypeScript devs who can use as const.

While these tests are hard-coded for string literals, in the real world most of our developers use JS and IDs are often built on the fly, e.g.

const id = `my-tree.0.${someString}`; // inferred as string
setObject(id, { /* I could really use a better type for this object */ });

If id was instead typed as my-tree.0.${string}, the object type in setObject could be more specific to the purpose it actually serves.

[MrEfrem]

It's more one use case: https://github.com/ThomasAribart/json-schema-to-ts. It doesn't work with JSDoc types without as const.
I use JSON schemas in most of my backends and I have to create JSDoc types for payload manually every time.