shelving 1.316.0 → 1.317.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,8 +5,8 @@
5
5
  - Extends: `FileExtractor`
6
6
 
7
7
  File extractor that parses a TypeScript source file into a tree element.
8
- - Uses the native TypeScript compiler's API (`typescript/unstable/async` — TypeScript 7+) to parse the AST.
9
- - Parsing runs on a shared native compiler server, spawned on demand into a virtual filesystem and closed again after a short idle — callers never manage its lifecycle.
8
+ - Uses the native TypeScript compiler's API (`typescript/async` — TypeScript 7.1+) to parse the AST with `API.createSourceFile()`.
9
+ - Parsing runs on a shared native compiler server, spawned on demand and closed again after a short idle — callers never manage its lifecycle.
10
10
  - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
11
11
  - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`. When a function (or constructor) is overloaded, the implementation declaration (the "base definition") is dropped entirely — only the overload signatures are documented.
12
12
  - A `@param name {Type}` (or `@returns {Type}`) whose `{Type}` is given is canonical: it supersedes the inferred type from the base definition and any overloads. Multiple `@param name` tags for one parameter each emit a row, letting a single parameter be documented as several typed variants.
@@ -9014,8 +9014,8 @@ extract(input: I): O | Promise<O>
9014
9014
  - Extends: `FileExtractor`
9015
9015
 
9016
9016
  File extractor that parses a TypeScript source file into a tree element.
9017
- - Uses the native TypeScript compiler's API (`typescript/unstable/async` — TypeScript 7+) to parse the AST.
9018
- - Parsing runs on a shared native compiler server, spawned on demand into a virtual filesystem and closed again after a short idle — callers never manage its lifecycle.
9017
+ - Uses the native TypeScript compiler's API (`typescript/async` — TypeScript 7.1+) to parse the AST with `API.createSourceFile()`.
9018
+ - Parsing runs on a shared native compiler server, spawned on demand and closed again after a short idle — callers never manage its lifecycle.
9019
9019
  - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
9020
9020
  - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`. When a function (or constructor) is overloaded, the implementation declaration (the "base definition") is dropped entirely — only the overload signatures are documented.
9021
9021
  - A `@param name {Type}` (or `@returns {Type}`) whose `{Type}` is given is canonical: it supersedes the inferred type from the base definition and any overloads. Multiple `@param name` tags for one parameter each emit a row, letting a single parameter be documented as several typed variants.
@@ -2,8 +2,8 @@ import type { TreeElementProps } from "../util/tree.js";
2
2
  import { FileExtractor } from "./FileExtractor.js";
3
3
  /**
4
4
  * File extractor that parses a TypeScript source file into a tree element.
5
- * - Uses the native TypeScript compiler's API (`typescript/unstable/async` — TypeScript 7+) to parse the AST.
6
- * - Parsing runs on a shared native compiler server, spawned on demand into a virtual filesystem and closed again after a short idle — callers never manage its lifecycle.
5
+ * - Uses the native TypeScript compiler's API (`typescript/async` — TypeScript 7.1+) to parse the AST with `API.createSourceFile()`.
6
+ * - Parsing runs on a shared native compiler server, spawned on demand and closed again after a short idle — callers never manage its lifecycle.
7
7
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
8
8
  * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`. When a function (or constructor) is overloaded, the implementation declaration (the "base definition") is dropped entirely — only the overload signatures are documented.
9
9
  * - A `@param name {Type}` (or `@returns {Type}`) whose `{Type}` is given is canonical: it supersedes the inferred type from the base definition and any overloads. Multiple `@param name` tags for one parameter each emit a row, letting a single parameter be documented as several typed variants.
@@ -1,13 +1,13 @@
1
- import { getTextOfJSDocComment, isArrayBindingPattern, isBindingElement, isClassDeclaration, isConstructorDeclaration, isEnumDeclaration, isFunctionDeclaration, isGetAccessorDeclaration, isIdentifier, isInterfaceDeclaration, isJSDoc, isJSDocParameterTag, isJSDocReturnTag, isJSDocSeeTag, isJSDocThrowsTag, isJSDocTypeExpression, isMethodDeclaration, isMethodSignatureDeclaration, isObjectBindingPattern, isPropertyDeclaration, isPropertySignatureDeclaration, isSetAccessorDeclaration, isTypeAliasDeclaration, isTypeLiteralNode, isTypeReferenceNode, isVariableStatement, SyntaxKind, } from "typescript/unstable/ast";
2
- import { API } from "typescript/unstable/async";
1
+ import { getTextOfJSDocComment, isArrayBindingPattern, isBindingElement, isClassDeclaration, isConstructorDeclaration, isEnumDeclaration, isFunctionDeclaration, isGetAccessorDeclaration, isIdentifier, isInterfaceDeclaration, isJSDoc, isJSDocParameterTag, isJSDocReturnTag, isJSDocSeeTag, isJSDocThrowsTag, isJSDocTypeExpression, isMethodDeclaration, isMethodSignatureDeclaration, isObjectBindingPattern, isPropertyDeclaration, isPropertySignatureDeclaration, isSetAccessorDeclaration, isTypeAliasDeclaration, isTypeLiteralNode, isTypeReferenceNode, isVariableStatement, SyntaxKind, } from "typescript/ast";
2
+ import { API } from "typescript/async";
3
3
  import { ValueError } from "../error/ValueError.js";
4
4
  import { BLACKHOLE } from "../util/function.js";
5
5
  import { FileExtractor } from "./FileExtractor.js";
6
6
  import { extractMarkdownProps } from "./MarkupExtractor.js";
7
7
  /**
8
8
  * File extractor that parses a TypeScript source file into a tree element.
9
- * - Uses the native TypeScript compiler's API (`typescript/unstable/async` — TypeScript 7+) to parse the AST.
10
- * - Parsing runs on a shared native compiler server, spawned on demand into a virtual filesystem and closed again after a short idle — callers never manage its lifecycle.
9
+ * - Uses the native TypeScript compiler's API (`typescript/async` — TypeScript 7.1+) to parse the AST with `API.createSourceFile()`.
10
+ * - Parsing runs on a shared native compiler server, spawned on demand and closed again after a short idle — callers never manage its lifecycle.
11
11
  * - Extracts exported, public, non-`_`-prefixed declarations as `tree-documentation` children.
12
12
  * - Overloaded declarations sharing a name are merged into a single `tree-documentation` with multiple `signatures`. When a function (or constructor) is overloaded, the implementation declaration (the "base definition") is dropped entirely — only the overload signatures are documented.
13
13
  * - A `@param name {Type}` (or `@returns {Type}`) whose `{Type}` is given is canonical: it supersedes the inferred type from the base definition and any overloads. Multiple `@param name` tags for one parameter each emit a row, letting a single parameter be documented as several typed variants.
@@ -55,93 +55,56 @@ export class TypescriptExtractor extends FileExtractor {
55
55
  }
56
56
  }
57
57
  // Constants.
58
- const _DIR = "/shelving-typescript-extractor";
59
- const _TSCONFIG_PATH = `${_DIR}/tsconfig.json`;
60
- const _TSCONFIG_JSON = JSON.stringify({ compilerOptions: { noEmit: true }, include: ["**/*.ts"] });
61
58
  const _IDLE_CLOSE_MS = 500;
62
- let _server;
63
- let _queue = Promise.resolve();
59
+ let _api;
64
60
  let _timer;
61
+ let _pending = 0;
65
62
  let _count = 0;
66
- let _previous;
67
- /** Is a path inside the virtual directory the compiler server is rooted in? */
68
- function _isVirtual(path) {
69
- return path === _DIR || path.startsWith(`${_DIR}/`);
70
- }
71
- /** Get the shared compiler server, spawning it on demand with a virtual filesystem rooted at `_DIR`. */
72
- function _getServer() {
73
- if (_server)
74
- return _server;
75
- const files = new Map([[_TSCONFIG_PATH, _TSCONFIG_JSON]]);
76
- // Paths outside the virtual directory return `undefined` so the server falls back to the real filesystem (e.g. bundled libs).
77
- const fs = {
78
- fileExists: f => (_isVirtual(f) ? files.has(f) : undefined),
79
- readFile: f => (_isVirtual(f) ? (files.get(f) ?? null) : undefined),
80
- directoryExists: d => (d === _DIR ? true : _isVirtual(d) ? false : undefined),
81
- getAccessibleEntries: d => d === _DIR
82
- ? { files: Array.from(files.keys(), f => f.slice(_DIR.length + 1)), directories: [] }
83
- : _isVirtual(d)
84
- ? { files: [], directories: [] }
85
- : undefined,
86
- realpath: p => (_isVirtual(p) ? p : undefined),
87
- };
88
- _server = { api: new API({ cwd: _DIR, fs }), files };
89
- return _server;
63
+ /** Get the shared compiler server, and spawn it if it does not exist. */
64
+ function _getAPI() {
65
+ if (_timer)
66
+ clearTimeout(_timer);
67
+ _timer = undefined;
68
+ _api ??= new API();
69
+ return _api;
90
70
  }
91
71
  /** Close the shared compiler server after a short idle, so the process can exit without callers managing the lifecycle. */
92
- async function _scheduleClose() {
72
+ function _scheduleClose() {
93
73
  if (_timer)
94
74
  clearTimeout(_timer);
95
75
  _timer = setTimeout(() => {
96
- const server = _server;
97
- _server = undefined;
98
- _previous = undefined;
76
+ const api = _api;
77
+ _api = undefined;
99
78
  _timer = undefined;
100
- try {
101
- void server?.api.close();
102
- }
103
- catch {
104
- // Closing can reject in-flight bookkeeping requests — harmless on shutdown.
105
- }
79
+ api?.close().catch(BLACKHOLE); // Closing can reject in-flight bookkeeping requests — harmless on shutdown.
106
80
  }, _IDLE_CLOSE_MS);
107
81
  }
108
82
  /**
109
83
  * Parse TypeScript source text into a `SourceFile` via the shared native compiler server.
110
- * - Each call writes the text as a fresh virtual file, snapshots the project, and materialises the file's AST.
111
- * - Calls are serialised through a queue so concurrent extractions don't interleave snapshot updates.
84
+ * - Uses `API.createSourceFile()` (TypeScript 7.1+), which parses one file without a project, a program, or a filesystem.
85
+ * - The server closes after a short idle when no parse is in progress.
112
86
  *
113
87
  * @throws `ValueError` If the server fails to produce a source file for the text.
114
88
  */
115
- function _parseSourceFile(text) {
116
- const task = async () => {
117
- if (_timer)
118
- clearTimeout(_timer);
119
- const { api, files } = _getServer();
120
- const path = `${_DIR}/${_count++}.ts`;
121
- files.set(path, text);
122
- // Drop the previous parse's file so the virtual project stays a single file (keeps snapshots cheap).
123
- const deleted = _previous;
124
- if (deleted)
125
- files.delete(deleted);
126
- _previous = path;
127
- const snapshot = await api.updateSnapshot({
128
- openProjects: [_TSCONFIG_PATH],
129
- fileChanges: { created: [path], ...(deleted ? { deleted: [deleted] } : {}) },
130
- });
89
+ async function _parseSourceFile(text) {
90
+ const api = _getAPI();
91
+ _pending++;
92
+ try {
93
+ const retained = await api.createSourceFile(`/${_count++}.ts`, text);
131
94
  try {
132
- const source = await snapshot.getProject(_TSCONFIG_PATH)?.program.getSourceFile(path);
95
+ const source = retained.sourceFile;
133
96
  if (!source)
134
97
  throw new ValueError("Unable to parse TypeScript source", { received: text });
135
98
  return source;
136
99
  }
137
100
  finally {
138
- await snapshot.dispose();
139
- await _scheduleClose();
101
+ await retained.dispose();
140
102
  }
141
- };
142
- const result = _queue.then(task, task);
143
- _queue = result.catch(BLACKHOLE);
144
- return result;
103
+ }
104
+ finally {
105
+ if (--_pending === 0)
106
+ _scheduleClose();
107
+ }
145
108
  }
146
109
  /** Read a node's modifiers (excluding decorators), or `undefined` when it has none. */
147
110
  function _getModifiers(node) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.316.0",
3
+ "version": "1.317.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -16,7 +16,7 @@
16
16
  "@types/react-dom": "^19.3.0",
17
17
  "stylelint": "^17.16.0",
18
18
  "stylelint-config-standard": "^40.0.0",
19
- "typescript": "^7.0.2"
19
+ "typescript": "7.1.0-beta"
20
20
  },
21
21
  "peerDependencies": {
22
22
  "@heroicons/react": ">=2.0.0"
package/test/basics.d.ts CHANGED
@@ -14,10 +14,10 @@ export declare const BASIC_SCHEMA: import("../schema/DataSchema.js").DataSchema<
14
14
  odd: boolean;
15
15
  even: boolean;
16
16
  sub: {
17
- str: /*elided*/ any;
18
- num: /*elided*/ any;
19
- odd: /*elided*/ any;
20
- even: /*elided*/ any;
17
+ str: string;
18
+ num: number;
19
+ odd: boolean;
20
+ even: boolean;
21
21
  };
22
22
  }>;
23
23
  /**
@@ -111,9 +111,9 @@ export declare const BASICS_COLLECTION: Collection<"basics", string, {
111
111
  odd: boolean;
112
112
  even: boolean;
113
113
  sub: {
114
- str: /*elided*/ any;
115
- num: /*elided*/ any;
116
- odd: /*elided*/ any;
117
- even: /*elided*/ any;
114
+ str: string;
115
+ num: number;
116
+ odd: boolean;
117
+ even: boolean;
118
118
  };
119
119
  }>;
package/test/people.d.ts CHANGED
@@ -8,8 +8,8 @@ import type { ValidatorType } from "../util/validate.js";
8
8
  */
9
9
  export declare const PERSON_SCHEMA: import("../schema/DataSchema.js").DataSchema<{
10
10
  name: {
11
- first: /*elided*/ any;
12
- last: /*elided*/ any;
11
+ first: string;
12
+ last: string;
13
13
  };
14
14
  birthday: string | null;
15
15
  }>;
@@ -68,8 +68,8 @@ export declare const people: ReadonlyArray<PersonItem>;
68
68
  */
69
69
  export declare const PEOPLE_COLLECTION: Collection<"people", string, {
70
70
  name: {
71
- first: /*elided*/ any;
72
- last: /*elided*/ any;
71
+ first: string;
72
+ last: string;
73
73
  };
74
74
  birthday: string | null;
75
75
  }>;
@@ -5,7 +5,7 @@ import type { TreeElements } from "../../util/tree.js";
5
5
  *
6
6
  * @see https://shelving.cc/ui/TreeCardMapping
7
7
  */
8
- export declare const TreeCardMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, TreeCardMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>;
8
+ export declare const [TreeCardMapping, TreeCardMapper]: [Mapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, Mapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>];
9
9
  /**
10
10
  * Props for the `TreeCards` component — the tree elements to render as cards.
11
11
  *
@@ -29,7 +29,7 @@ export declare function TreeMenuItem({ path, name, title, children }: TreeElemen
29
29
  *
30
30
  * @see https://shelving.cc/ui/TreeMenuMapping
31
31
  */
32
- export declare const TreeMenuMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, TreeMenuMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>;
32
+ export declare const [TreeMenuMapping, TreeMenuMapper]: [Mapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, Mapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>];
33
33
  /**
34
34
  * Props for the `TreeMenu` component — the root tree element plus its URL path.
35
35
  *
@@ -5,7 +5,7 @@ import type { PossibleMeta } from "../util/index.js";
5
5
  *
6
6
  * @see https://shelving.cc/ui/TreeRouterMapping
7
7
  */
8
- export declare const TreeRouterMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, TreeRouterMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>;
8
+ export declare const [TreeRouterMapping, TreeRouterMapper]: [Mapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps>, Mapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps>];
9
9
  /**
10
10
  * Props for the `TreeRouter` component — the tree to route plus an optional fallback and app meta.
11
11
  *