Types documentation

See also agoric-sdk repo's TypeScript doc.

We use JSDoc with Typescript extensions so that the types written in comments are checked statically.

Part of our Coding Style is to use TypeScript to annotate code. The code remains Javascript code, not TypeScript code, with the types defines in JSDoc.

There are some .d.ts files for when the JSDoc supported types don't suffice. (For example, - adding globals).

Rules

No Google Closure syntax

For optional parameters use brackets:

 @param {number} [optionalNumber]

not the Google Closure syntax

 @param {number=} optionalNumber NOPE

See also https://github.com/Agoric/agoric-sdk/wiki/Express-optional-parameters-in-both-JS-and-JSDoc-TS-syntax

Guidance

Prefer type declarations at code sites

When type annotations were introduced they were mostly kept out of the code in a types.js file. Over time we've found that it's better to have the annotations with the code.

Prefer explicit imports of types

Many types are still defined in the types.js and available implicitly through imports. Over time we've found that it's better to explicitly import types that are needed. E.g.,

/** @typedef {import('child_process').ChildProcess} ChildProcess */

Prefer unknown to any

Use unknown rather than any in type declarations (or document justification for any) SES-shim/issues/600

Prefer ts-expect-error to ts-ignore

ts-ignore can be ignored forever but ts-expect-error will notify us when the suppression is no longer necessary, so we can clean it up. E.g. https://github.com/Agoric/agoric-sdk/pull/4759/commits/d9b0717d9a0b3691b7fe813c5ba7a99293eb4291

There's a gotcha though with using either, which is that if you suppress on a key in an object the whole object is suppressed. In that case you may want to use any. E.g. https://github.com/Agoric/agoric-sdk/pull/4764

avoid ambient types

WIP

swingset is a good model.

client code:

  /** @type {import('@agoric/swingset-vat').CreateVatResults} */

https://github.com/Agoric/agoric-sdk/blob/8da963736b2cf147063787e811b9fe2da0b7e71e/packages/SwingSet/src/index.js https://github.com/Agoric/agoric-sdk/issues/6512

---

see also:

• https://github.com/Agoric/agoric-sdk/blob/master/docs/typescript.md
• Add global variables to ESLint and JSDoc annotations validated by Typescript
• http://properjs.org/