How to cast as const with JSDoc (equivalent to as const in TS)

[voxpelli]

I didn't find a topic on this in here so I'm adding it.

TypeScript 3.4 introduced the concept of "const assertions" through microsoft/TypeScript#29510

Turns out that we can actually make use of this in the very same way as we do type casting/type assertions in JSDoc (as showed in #18) and just like in TS simply use const instead of a type (as documented here):

// type is number[]
const arr1 = [1, 2, 3]

// type is readonly [1, 2, 3]
const arr2 = /** @type {const} */ ([1, 2, 3])

Example taken from @AustinGil here: microsoft/TypeScript#30445 (comment)

This also works for eg. objects:

// type is { foo: string; abc: number; }
const obj1 = { foo: 'bar', abc: 123 }

// type is { readonly foo: "bar"; readonly abc: 123; }
const obj2 = /** @type {const} */ ({ foo: 'bar', abc: 123 })

This can help with eg. literal inference and in the creation of enum-style definitions.

Previously I at times felt the need to separately define the type to get a similar type to work with:

/**
 * @typedef Obj2
 * @property {'bar'} foo
 * @property {123} abc
 */

/** @type {Obj2} */
const obj2 = ({ foo: 'bar', abc: 123 })

Simply doing const obj2 = /** @type {const} */ ({ foo: 'bar', abc: 123 }) is much easier and more DRY.

[tzkmx]

How could we take advantage of the already declared as const-like object, to build an Union Type from the values of the object when it is used as a more flexible enum?

I refer to this pattern:

const AuthMethod = {
  Basic: 'BASIC',
  OAuth1: 'OAuth1',
  OAuth2: 'OAuth2'
} as const;

type AuthMethod = typeof AuthMethod[keyof typeof AuthMethod];

function authenticate(method: AuthMethod) {}

[tzkmx]

I've tried to use simply the dynamic union type declaration but it's losing its values, it correctly validates only a literal union type.

/** @typedef { typeof AuthMethod[keyof typeof AuthMethod] } AuthMethodLosy */
/** @typedef { 'Basic' | 'OAuth1' | 'OAuth2' } AuthMethod */

authenticateFromUnion('Basic'); // works
authenticateFromUnion(/** @type AuthMethod */(AuthMethod.Basic)); // now I need to cast the value with `as AuthMethod` equivalent :(
try {
  authenticateFromUnion('hawk');
} catch (/** @type {*} */e) {
  console.warn(`catched correctly ${e.message}`)
}

authenticateFromTypeKeyof('hawk'); // it should not be accepted
authenticateFromTypeKeyof(AuthMethod.Basic); // accepted, but this form accepts any string

/**
 * @param {AuthMethodLosy} method
 */
function authenticateFromTypeKeyof(method) {
  console.log(method);
}

/**
* @param {AuthMethod} type
*/
function authenticateFromUnion(type) {
  assertIsValidAuthMethod(type);
  
  console.log(type);
}

/**
 * @param {?} value
 * @returns {asserts value is AuthMethod}
 */
function assertIsValidAuthMethod(value) {
  if (!Object.values(AuthMethod).includes(value)) {
    throw new TypeError(`Invalid authMethod: ${value}`)
  }
}

I leave you the TS Playground I tried with.