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.
- package/docs/extract/TypescriptExtractor.md +2 -2
- package/docs/llms-full.txt +2 -2
- package/extract/TypescriptExtractor.d.ts +2 -2
- package/extract/TypescriptExtractor.js +31 -68
- package/package.json +2 -2
- package/test/basics.d.ts +8 -8
- package/test/people.d.ts +4 -4
- package/ui/tree/TreeCards.d.ts +1 -1
- package/ui/tree/TreeMenu.d.ts +1 -1
- package/ui/tree/TreeRouter.d.ts +1 -1
|
@@ -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/
|
|
9
|
-
- Parsing runs on a shared native compiler server, spawned on demand
|
|
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.
|
package/docs/llms-full.txt
CHANGED
|
@@ -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/
|
|
9018
|
-
- Parsing runs on a shared native compiler server, spawned on demand
|
|
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/
|
|
6
|
-
* - Parsing runs on a shared native compiler server, spawned on demand
|
|
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/
|
|
2
|
-
import { API } from "typescript/
|
|
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/
|
|
10
|
-
* - Parsing runs on a shared native compiler server, spawned on demand
|
|
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
|
|
63
|
-
let _queue = Promise.resolve();
|
|
59
|
+
let _api;
|
|
64
60
|
let _timer;
|
|
61
|
+
let _pending = 0;
|
|
65
62
|
let _count = 0;
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
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
|
-
|
|
72
|
+
function _scheduleClose() {
|
|
93
73
|
if (_timer)
|
|
94
74
|
clearTimeout(_timer);
|
|
95
75
|
_timer = setTimeout(() => {
|
|
96
|
-
const
|
|
97
|
-
|
|
98
|
-
_previous = undefined;
|
|
76
|
+
const api = _api;
|
|
77
|
+
_api = undefined;
|
|
99
78
|
_timer = undefined;
|
|
100
|
-
|
|
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
|
-
* -
|
|
111
|
-
* -
|
|
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
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
const
|
|
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 =
|
|
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
|
|
139
|
-
await _scheduleClose();
|
|
101
|
+
await retained.dispose();
|
|
140
102
|
}
|
|
141
|
-
}
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
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.
|
|
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": "
|
|
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:
|
|
18
|
-
num:
|
|
19
|
-
odd:
|
|
20
|
-
even:
|
|
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:
|
|
115
|
-
num:
|
|
116
|
-
odd:
|
|
117
|
-
even:
|
|
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:
|
|
12
|
-
last:
|
|
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:
|
|
72
|
-
last:
|
|
71
|
+
first: string;
|
|
72
|
+
last: string;
|
|
73
73
|
};
|
|
74
74
|
birthday: string | null;
|
|
75
75
|
}>;
|
package/ui/tree/TreeCards.d.ts
CHANGED
|
@@ -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>,
|
|
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
|
*
|
package/ui/tree/TreeMenu.d.ts
CHANGED
|
@@ -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>,
|
|
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
|
*
|
package/ui/tree/TreeRouter.d.ts
CHANGED
|
@@ -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>,
|
|
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
|
*
|