@spidunno/desmos-types 1.13.4 → 1.13.6

package/README.md

@@ -6,11 +6,11 @@ the graphing calculator, geometry tool, 3D calculator, and the four-function and
 ## Install
 
 ```sh
-npm install --save-dev @spidunno/desmos-types@~1.13.4
+npm install --save-dev @spidunno/desmos-types@~1.13.6
 ```
 
 The package's major and minor version match the Desmos API version it describes; patch releases
-are fixes to the types. Use a tilde range (`~1.13.4`), not npm's default caret (`^`), so you only
+are fixes to the types. Use a tilde range (`~1.13.6`), not npm's default caret (`^`), so you only
 get type fixes for the API version you load.
 
 ## Usage
@@ -53,6 +53,30 @@ the API only exists as the global that `calculator.js` creates.
 import type { GraphingCalculator, GraphState } from '@spidunno/desmos-types';
 ```
 
+### Without a global
+
+Importing from `@spidunno/desmos-types` (or `/internals`) still declares the global `Desmos`, so
+code that uses the global type-checks even when the program never loaded `calculator.js` as a
+script. If you load the API some other way, for example into a scope of your own so that
+`window.Desmos` never exists, use the module-only entry points instead. They declare the same
+types, but nothing global:
+
+```ts
+import type { Desmos } from '@spidunno/desmos-types/module'; // or '/module/internals'
+
+async function loadDesmos(): Promise<typeof Desmos> {
+  /* ... */
+}
+
+const api = await loadDesmos();
+const calculator: Desmos.GraphingCalculator = api.GraphingCalculator(element);
+```
+
+`Desmos` is a type-only export, since the package contains no JavaScript: using it as a value is a
+compile error, and editors auto-import it with `import type` (or with a plain import that
+TypeScript removes, unless `verbatimModuleSyntax` is on). Don't also include the default entry
+points (in `compilerOptions.types` or a `/// <reference>`), or the global comes back.
+
 ## Layout
 
 | File | Contents |
@@ -75,6 +99,7 @@ import type { GraphingCalculator, GraphState } from '@spidunno/desmos-types';
 | `types/mathquill.d.ts` | The bundled MathQuill fork |
 | `types/desmos.d.ts` | `enabledFeatures`, `supportedLanguages`, `imageFileToDataURL`, `version`, `Window.Desmos` |
 | `internals/` | Opt-in internals (see [Internals](#internals)); `internals/generated/` is generated |
+| `module/` | Module-only copies of `index.d.ts` and `internals/index.d.ts` (see [Without a global](#without-a-global)), built by `npm run build:module` |
 | `scripts/extract-internals.cjs` | Regenerates `internals/generated/` from a bundle |
 
 ## Sources and conventions
@@ -140,10 +165,20 @@ Everything here is internal to Desmos and changes between builds, even within v1
 | Hand-written | `internals/*.d.ts` | Precise types for the parts mods use, checked against the bundle source |
 
 In the generated layer, property types come from observed values. A method's return type comes from
-static analysis of its source (nothing returned → `void`, only booleans returned → `boolean`), or from
-calling side-effect-free getters such as `get*` and `is*`. Anything that couldn't be determined is
-`unknown`, and parameters are `unknown` because the bundle is minified. Action payload field names are
-reliable, but their value types are often inferred from the field name. A property is optional if it
+calling side-effect-free getters such as `get*` and `is*`, or from what its source returns: literals,
+operators, object literals, `this.x` (typed as `this["x"]`, so refinements of `x` carry over), and
+calls to other methods and bundle functions, whose return types are inferred the same way. A return
+type stays `unknown` if any returned value can't be typed. Anything that couldn't be determined is
+`unknown`. Action payload field names are reliable, but their value types are often inferred from the
+field name.
+
+The bundle is minified, so parameter names are recovered from how each method uses them:
+`this.x = p` and `{ x: p }` name it `x`, `dispatch({ type, x: p })` also copies the action field's
+type, and passing `p` to another method or bundle function (`this.getItemModel(p)`) reuses that
+function's inferred name and type. Defaults, arithmetic, exhaustive `switch`es and `.type`
+comparisons give types (`id: string`, `index: number`, `'selected' | 'tentatively-selected'`, item
+models). A parameter is optional if it has a default, is checked against `undefined`, or some call
+in the bundle leaves it out. What can't be recovered stays `argN: unknown`. A property is optional if it
 held `undefined` or was added after the calculator loaded (for example, by the first animation frame
 or a UI interaction).