@orkestrel/scaffold 0.0.115 → 0.0.117
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/dist/bin/main.js +138 -16
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -1
- package/dist/host/claude/agents/orkestrel.md +2 -2
- package/dist/host/claude/rules/names.md +3 -1
- package/dist/host/guides/abort.md +17 -17
- package/dist/host/guides/agent.md +445 -445
- package/dist/host/guides/brief.md +143 -143
- package/dist/host/guides/browser.md +731 -731
- package/dist/host/guides/budget.md +39 -39
- package/dist/host/guides/capture.md +298 -298
- package/dist/host/guides/console.md +109 -109
- package/dist/host/guides/contract.md +335 -335
- package/dist/host/guides/csv.md +30 -30
- package/dist/host/guides/database.md +163 -163
- package/dist/host/guides/emitter.md +17 -17
- package/dist/host/guides/form.md +99 -99
- package/dist/host/guides/guide.md +368 -183
- package/dist/host/guides/html.md +49 -49
- package/dist/host/guides/indexeddb.md +40 -40
- package/dist/host/guides/interpret.md +139 -139
- package/dist/host/guides/lsp.md +114 -114
- package/dist/host/guides/markdown.md +68 -68
- package/dist/host/guides/mcp.md +3745 -3745
- package/dist/host/guides/middleware.md +170 -170
- package/dist/host/guides/msg.md +95 -95
- package/dist/host/guides/ndjson.md +8 -8
- package/dist/host/guides/ollama.md +56 -56
- package/dist/host/guides/pool.md +21 -21
- package/dist/host/guides/probe.md +82 -82
- package/dist/host/guides/process.md +99 -99
- package/dist/host/guides/program.md +98 -96
- package/dist/host/guides/qualifier.md +70 -70
- package/dist/host/guides/queue.md +37 -37
- package/dist/host/guides/rater.md +38 -38
- package/dist/host/guides/reason.md +308 -308
- package/dist/host/guides/relation.md +50 -50
- package/dist/host/guides/router.md +58 -58
- package/dist/host/guides/scaffold.md +558 -419
- package/dist/host/guides/sea.md +128 -128
- package/dist/host/guides/server.md +100 -100
- package/dist/host/guides/sqlite.md +28 -28
- package/dist/host/guides/sse.md +20 -20
- package/dist/host/guides/study.md +444 -444
- package/dist/host/guides/table.md +82 -82
- package/dist/host/guides/template.md +41 -41
- package/dist/host/guides/terminal.md +121 -121
- package/dist/host/guides/test.md +273 -273
- package/dist/host/guides/timeout.md +18 -18
- package/dist/host/guides/tool.md +27 -27
- package/dist/host/guides/toolbox.md +166 -166
- package/dist/host/guides/websocket.md +54 -54
- package/dist/host/guides/worker.md +24 -24
- package/dist/host/guides/workflow.md +187 -187
- package/dist/host/guides/workspace.md +55 -55
- package/dist/host/manifest.json +55 -55
- package/dist/host/tests/setupPolicy.ts +5 -3
- package/dist/src/core/index.cjs +90 -4
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +229 -144
- package/dist/src/core/index.d.ts +229 -144
- package/dist/src/core/index.js +88 -5
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +295 -66
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +193 -6
- package/dist/src/server/index.d.ts +193 -6
- package/dist/src/server/index.js +290 -69
- package/dist/src/server/index.js.map +1 -1
- package/package.json +5 -4
|
@@ -70,24 +70,24 @@ table.view.map((row) => row.name) // ['Grace', 'Alan'] — page one, oldest firs
|
|
|
70
70
|
|
|
71
71
|
These declarations belong to the browser entry.
|
|
72
72
|
|
|
73
|
-
|
|
|
74
|
-
| ----------------------- | --------- |
|
|
75
|
-
| `TableBinding` | class | `TableBindingInterface`
|
|
76
|
-
| `TableBindingInterface` | interface | `{ element, document, destroyed, emitter
|
|
77
|
-
| `TableBindingOptions` | interface | `{ row?, detail?, scope?, describe
|
|
78
|
-
| `TableRange` | interface | `{ first, last, count, page, pages, limit }`
|
|
79
|
-
| `TableSortDescription` | interface | `{ column, direction, priority, count }`
|
|
80
|
-
| `TableExpansion` | interface | `{ key, expanded }`
|
|
81
|
-
| `TableBindingEventMap` | type | `{ sort: readonly [event: CustomEvent<readonly TableOrder[]>]; expand: readonly [event: CustomEvent<readonly TableExpansion[]>]; render: readonly []; error: readonly [error: unknown] }` | Announces cancelable sorting and expanding, completed rendering, and failed DOM operations. |
|
|
82
|
-
| `TableRenderHandler` | type | `(element: HTMLTableRowElement, row: TableRow) => void`
|
|
83
|
-
| `TableProjection` | interface | `{ schema, rows }`
|
|
84
|
-
| `TableBindingErrorCode` | type | `'STRUCTURE'`
|
|
85
|
-
| `TableBindingError` | class | `new (code: TableBindingErrorCode, message: string) => TableBindingError`
|
|
86
|
-
| `isTableBindingError` | function | `(value: unknown) => value is TableBindingError`
|
|
87
|
-
| `createTableBinding` | function | `(element: HTMLTableElement, document: TableInterface, options?: TableBindingOptions) => TableBindingInterface`
|
|
88
|
-
| `readTable` | function | `(element: HTMLTableElement) => TableProjection`
|
|
89
|
-
| `readTableSchema` | function | `(element: HTMLTableElement) => TableSchema`
|
|
90
|
-
| `readTableRows` | function | `(schema: TableSchema, elements: readonly HTMLTableRowElement[]) => readonly TableRow[]`
|
|
73
|
+
| Name | Kind | Signature | Summary |
|
|
74
|
+
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
|
|
75
|
+
| `TableBinding` | class | `new (element: HTMLTableElement, document: TableInterface, options?: TableBindingOptions) => TableBindingInterface` | Retains keyed native rows while projecting every core table manager. |
|
|
76
|
+
| `TableBindingInterface` | interface | `{ element, document, destroyed, emitter, refresh(), destroy() }` | Binds native table elements to a borrowed core document. |
|
|
77
|
+
| `TableBindingOptions` | interface | `{ row?, detail?, scope?, describe?, on?, error? }` | Configures row ownership, detail presentation, scoped controls, and event listeners. |
|
|
78
|
+
| `TableRange` | interface | `{ first, last, count, page, pages, limit }` | Describes the displayed page within the filtered rows. |
|
|
79
|
+
| `TableSortDescription` | interface | `{ column, direction, priority, count }` | Describes a column's direction and one-based priority among active sort orders. |
|
|
80
|
+
| `TableExpansion` | interface | `{ key, expanded }` | Proposes one row's next expansion state in a cancelable expand request. |
|
|
81
|
+
| `TableBindingEventMap` | type | `{ readonly sort: readonly [event: CustomEvent<readonly TableOrder[]>]; readonly expand: readonly [event: CustomEvent<readonly TableExpansion[]>]; readonly render: readonly []; readonly error: readonly [error: unknown]; }` | Announces cancelable sorting and expanding, completed rendering, and failed DOM operations. |
|
|
82
|
+
| `TableRenderHandler` | type | `(element: HTMLTableRowElement, row: TableRow) => void` | Patches the contents of a retained row without moving or replacing that row. |
|
|
83
|
+
| `TableProjection` | interface | `{ schema, rows }` | Holds a validated native table projection for constructing a core document. |
|
|
84
|
+
| `TableBindingErrorCode` | type | `'STRUCTURE'` | Names a native binding failure at its structure, rendering, or lifecycle boundary. |
|
|
85
|
+
| `TableBindingError` | class | `new (code: TableBindingErrorCode, message: string) => TableBindingError` | Represents a native table binding failure with a machine-readable code. |
|
|
86
|
+
| `isTableBindingError` | function | `(value: unknown) => value is TableBindingError` | Checks whether a caught value is a native table binding error. |
|
|
87
|
+
| `createTableBinding` | function | `(element: HTMLTableElement, document: TableInterface, options?: TableBindingOptions) => TableBindingInterface` | Creates a native table binding with one retained row owner. |
|
|
88
|
+
| `readTable` | function | `(element: HTMLTableElement) => TableProjection` | Reads declared header metadata and explicit row keys into a validated core projection. |
|
|
89
|
+
| `readTableSchema` | function | `(element: HTMLTableElement) => TableSchema` | Reads and validates explicit native header metadata. |
|
|
90
|
+
| `readTableRows` | function | `(schema: TableSchema, elements: readonly HTMLTableRowElement[]) => readonly TableRow[]` | Reads explicit keys and declared direct cells against a core schema. |
|
|
91
91
|
|
|
92
92
|
### Enhance authored rows
|
|
93
93
|
|
|
@@ -264,7 +264,7 @@ table.selection.keys.has('ash') // true
|
|
|
264
264
|
|
|
265
265
|
This helper belongs to the core entry.
|
|
266
266
|
|
|
267
|
-
|
|
|
267
|
+
| Name | Kind | Signature | Summary |
|
|
268
268
|
| ----------------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
269
269
|
| `matchesTableRow` | function | `(left: TableRow \| undefined, right: TableRow) => boolean` | Compares complete row values independently of their snapshot identities. |
|
|
270
270
|
|
|
@@ -274,7 +274,7 @@ The document itself — what a table declares and what one row of it holds. All
|
|
|
274
274
|
|
|
275
275
|
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
|
|
276
276
|
|
|
277
|
-
|
|
|
277
|
+
| Name | Kind | Signature | Summary |
|
|
278
278
|
| -------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
279
279
|
| `TableKey` | type | `string` | Represents a row's identity — a `string`, carried in the cell the schema's `key` names. |
|
|
280
280
|
| `TableCell` | type | `string \| number \| boolean` | Represents every value a cell can hold — a `string`, a `number`, or a `boolean`. |
|
|
@@ -282,10 +282,10 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
282
282
|
| `ColumnCell` | type | `'text' \| 'number' \| 'flag' \| 'choice'` | Names what a column's cells hold — the discriminant that fixes the column's options, its comparison, and the filters that apply to it. |
|
|
283
283
|
| `ColumnChoice` | interface | `{ value, label, help? }` | Represents one value a `choice` column offers — `value` is stored, `label` is read, and `help` explains. |
|
|
284
284
|
| `ColumnBase` | interface | `{ key, label?, help?, hidden?, meta? }` | Describes what every column carries, whatever its cells hold — the name a row's cell uses, the text a reader sees, whether a host draws the column, and the metadata a host attaches to it. |
|
|
285
|
-
| `TextColumn` | interface | `
|
|
286
|
-
| `NumberColumn` | interface | `
|
|
287
|
-
| `FlagColumn` | interface | `
|
|
288
|
-
| `ChoiceColumn` | interface | `
|
|
285
|
+
| `TextColumn` | interface | `{ cell }` | Represents a column of text, compared lexically. Carries a date, a time, and a timestamp as ISO strings. |
|
|
286
|
+
| `NumberColumn` | interface | `{ cell }` | Represents a column of numbers, compared by magnitude. |
|
|
287
|
+
| `FlagColumn` | interface | `{ cell }` | Represents a column of yes-or-no answers, compared false before true. |
|
|
288
|
+
| `ChoiceColumn` | interface | `{ cell, choices }` | Represents a column drawn from a declared list, compared by the order that list declares. It requires `choices`. |
|
|
289
289
|
| `TableColumn` | type | `TextColumn \| NumberColumn \| FlagColumn \| ChoiceColumn` | Represents any column a schema can declare — the union discriminated on `cell`. |
|
|
290
290
|
| `TableSchema` | interface | `{ name?, label?, help?, key, columns }` | Holds everything a table declares about itself — how the table is described, which column carries row identity, and the columns it declares, in the order it declares them. |
|
|
291
291
|
|
|
@@ -295,7 +295,7 @@ The axes a table reads its rows through, and the slots that replace what a colum
|
|
|
295
295
|
|
|
296
296
|
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
|
|
297
297
|
|
|
298
|
-
|
|
|
298
|
+
| Name | Kind | Signature | Summary |
|
|
299
299
|
| ---------------- | --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
300
300
|
| `TableTerm` | interface | `{ column }` | Represents one entry of a lens list — the `column` it names. A sort term and a filter each hold one, which is why the two share a list engine. |
|
|
301
301
|
| `TableDirection` | type | `'ascending' \| 'descending'` | Names which way a column sorts. A column nobody has sorted carries no term at all. |
|
|
@@ -314,22 +314,22 @@ The entity, its managers, its factory, its contract, and the error it raises.
|
|
|
314
314
|
|
|
315
315
|
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
316
316
|
|
|
317
|
-
|
|
|
318
|
-
| ---------------------------- | --------- |
|
|
319
|
-
| `Table` | class | `TableInterface`
|
|
320
|
-
| `TableInterface` | interface | `{ emitter, schema, rows, sort, filter, selection, expansion, pagination, view, count, destroyed
|
|
321
|
-
| `createTable` | function | `(schema: TableSchema, options?: TableOptions) => TableInterface`
|
|
322
|
-
| `TableOptions` | interface | `{ on?, error?, rows?, comparators?, matchers?, limit? }`
|
|
323
|
-
| `TableEventMap` | type | `{ write
|
|
324
|
-
| `RowManagerInterface` | interface | `{
|
|
325
|
-
| `SortManagerInterface` | interface | `{
|
|
326
|
-
| `FilterManagerInterface` | interface | `{
|
|
327
|
-
| `SelectionManagerInterface` | interface | `{ keys
|
|
328
|
-
| `ExpansionManagerInterface` | interface | `{ keys
|
|
329
|
-
| `PaginationManagerInterface` | interface | `{ page, limit, offset, count
|
|
330
|
-
| `TableError` | class | `new (code: TableErrorCode, message: string, context?: JSONRecord) => TableError`
|
|
331
|
-
| `TableErrorCode` | type | `'SCHEMA' \| 'COLUMN' \| 'KEY' \| 'CELL' \| 'DESTROYED'`
|
|
332
|
-
| `isTableError` | function | `TableError`
|
|
317
|
+
| Name | Kind | Signature | Summary |
|
|
318
|
+
| ---------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
319
|
+
| `Table` | class | `new (schema: TableSchema, options?: TableOptions) => TableInterface` | Holds a schema, its rows, and the lens through which they are read, implementing `TableInterface` exactly. |
|
|
320
|
+
| `TableInterface` | interface | `{ emitter, schema, rows, sort, filter, selection, expansion, pagination, view, count, destroyed, clear(), destroy() }` | Represents a table: what it declares, the rows it holds, and the lens it reads them through. |
|
|
321
|
+
| `createTable` | function | `(schema: TableSchema, options?: TableOptions) => TableInterface` | Opens a table against a schema. The schema is copied, and the copy is what the table declares. |
|
|
322
|
+
| `TableOptions` | interface | `{ on?, error?, rows?, comparators?, matchers?, limit? }` | Describes how to open a table — the listeners wired at construction and where a throw from one goes, the rows seeded into it, the per-column comparison and test replacements, and the page size. |
|
|
323
|
+
| `TableEventMap` | type | `{ readonly write: readonly [key: TableKey]; readonly remove: readonly [key: TableKey]; readonly sort: readonly [orders: readonly TableOrder[]]; readonly filter: readonly [filters: readonly TableFilter[]]; readonly select: readonly [keys: ReadonlySet<TableKey>]; readonly expand: readonly [keys: ReadonlySet<TableKey>]; readonly paginate: readonly [page: number]; readonly clear: readonly []; }` | Lists everything a table announces, mapping each event to the payload its listeners receive. |
|
|
324
|
+
| `RowManagerInterface` | interface | `{ row(), rows(), add(), update(), replace(), move(), remove() }` | Manages the rows a table holds, in the order it holds them. |
|
|
325
|
+
| `SortManagerInterface` | interface | `{ order(), orders(), set(), remove() }` | Manages the order a table reads its rows in. |
|
|
326
|
+
| `FilterManagerInterface` | interface | `{ filter(), filters(), set(), remove() }` | Manages which rows a table keeps. |
|
|
327
|
+
| `SelectionManagerInterface` | interface | `{ keys, select(), clear(), toggle() }` | Manages the rows somebody has picked. |
|
|
328
|
+
| `ExpansionManagerInterface` | interface | `{ keys, expand(), clear(), toggle() }` | Manages the rows somebody has opened up. |
|
|
329
|
+
| `PaginationManagerInterface` | interface | `{ page, limit, offset, count, move(), resize() }` | Manages which stretch of the filtered rows the view shows. |
|
|
330
|
+
| `TableError` | class | `new (code: TableErrorCode, message: string, context?: JSONRecord) => TableError` | Represents an error raised by the table domain — a machine-readable `code` and optional structured `context`. |
|
|
331
|
+
| `TableErrorCode` | type | `'SCHEMA' \| 'COLUMN' \| 'KEY' \| 'CELL' \| 'DESTROYED'` | Names the reason a `TableError` carries — the machine-readable code a `catch` branches on. |
|
|
332
|
+
| `isTableError` | function | `(input: unknown) => input is TableError` | Determines whether a caught value is a table error, so a `catch` branches on `code` without an assertion. |
|
|
333
333
|
|
|
334
334
|
`TableInterface`'s readonly data members stay here, in its `Shape` cell, rather than in
|
|
335
335
|
`## Methods`, and each manager's own readonly members sit in that manager's cell. Every
|
|
@@ -352,15 +352,15 @@ under a consumer.
|
|
|
352
352
|
|
|
353
353
|
A `Shape` cell holds the constant's declared type.
|
|
354
354
|
|
|
355
|
-
|
|
|
355
|
+
| Name | Kind | Signature | Summary |
|
|
356
356
|
| -------------- | ----- | ----------------------- | --------------------------------------------------------------------------------------------- |
|
|
357
357
|
| `COLUMN_CELLS` | const | `readonly ColumnCell[]` | Lists every column cell, in the order declared by the public contract. |
|
|
358
|
-
| `COLUMN_LIMIT` | const | `
|
|
359
|
-
| `CHOICE_LIMIT` | const | `
|
|
360
|
-
| `NAME_LIMIT` | const | `
|
|
361
|
-
| `STRING_LIMIT` | const | `
|
|
362
|
-
| `TEXT_LIMIT` | const | `
|
|
363
|
-
| `NODE_LIMIT` | const | `
|
|
358
|
+
| `COLUMN_LIMIT` | const | `256` | Names the maximum number of columns one schema may declare: 256. |
|
|
359
|
+
| `CHOICE_LIMIT` | const | `1024` | Names the maximum number of choices one `choice` column may offer: 1024. |
|
|
360
|
+
| `NAME_LIMIT` | const | `128` | Names the maximum length of a schema name or column key: 128 UTF-16 code units. |
|
|
361
|
+
| `STRING_LIMIT` | const | `65536` | Names the maximum length of any single retained string: 65536 UTF-16 code units. |
|
|
362
|
+
| `TEXT_LIMIT` | const | `1048576` | Names the maximum total length of every string one schema retains: 1048576 UTF-16 code units. |
|
|
363
|
+
| `NODE_LIMIT` | const | `16384` | Names the maximum total number of records, arrays, and leaves one schema retains: 16384. |
|
|
364
364
|
|
|
365
365
|
### Guards
|
|
366
366
|
|
|
@@ -369,15 +369,15 @@ anything off-shape — including an unexpected prototype, a symbol key, or a cyc
|
|
|
369
369
|
|
|
370
370
|
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
371
371
|
|
|
372
|
-
|
|
|
373
|
-
| ------------------------- | -------- |
|
|
374
|
-
| `isTableCell` | function | `TableCell` | Determines whether an unknown value has a table cell shape — a string, a finite number, or a boolean. |
|
|
375
|
-
| `isTableRow` | function | `TableRow` | Determines whether an unknown value is a record whose every own key is a string and every value a `TableCell`. |
|
|
376
|
-
| `isColumnCell` | function | `ColumnCell` | Determines whether an unknown value is a declared column cell. |
|
|
377
|
-
| `isColumnChoice` | function | `ColumnChoice` | Determines whether an unknown value is one exact `ColumnChoice` record; an unknown member refuses it. |
|
|
378
|
-
| `isTableColumn` | function | `TableColumn` | Determines whether an unknown value is one exact discriminated `TableColumn`, checked against its cell's own options. |
|
|
379
|
-
| `isStructuralTableSchema` | function | `TableSchema` | Determines whether an unknown value has the exact shape of a `TableSchema` — the shape alone, with no domain check. |
|
|
380
|
-
| `isTableSchema` | function | `TableSchema` | Determines whether an unknown value is a `TableSchema` a table can be opened against — the exact shape, and an audit that finds nothing. |
|
|
372
|
+
| Name | Kind | Signature | Summary |
|
|
373
|
+
| ------------------------- | -------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
|
374
|
+
| `isTableCell` | function | `(input: unknown) => input is TableCell` | Determines whether an unknown value has a table cell shape — a string, a finite number, or a boolean. |
|
|
375
|
+
| `isTableRow` | function | `(input: unknown) => input is TableRow` | Determines whether an unknown value is a record whose every own key is a string and every value a `TableCell`. |
|
|
376
|
+
| `isColumnCell` | function | `(input: unknown) => input is ColumnCell` | Determines whether an unknown value is a declared column cell. |
|
|
377
|
+
| `isColumnChoice` | function | `(input: unknown) => input is ColumnChoice` | Determines whether an unknown value is one exact `ColumnChoice` record; an unknown member refuses it. |
|
|
378
|
+
| `isTableColumn` | function | `(input: unknown) => input is TableColumn` | Determines whether an unknown value is one exact discriminated `TableColumn`, checked against its cell's own options. |
|
|
379
|
+
| `isStructuralTableSchema` | function | `(input: unknown) => input is TableSchema` | Determines whether an unknown value has the exact shape of a `TableSchema` — the shape alone, with no domain check. |
|
|
380
|
+
| `isTableSchema` | function | `(input: unknown) => input is TableSchema` | Determines whether an unknown value is a `TableSchema` a table can be opened against — the exact shape, and an audit that finds nothing. |
|
|
381
381
|
|
|
382
382
|
The schema guards answer about a schema, and which one to reach for is which question you are asking.
|
|
383
383
|
`isStructuralTableSchema` asks whether the shape is exact: every declared member present and typed,
|
|
@@ -409,23 +409,23 @@ propagate exceptions from supplied callbacks; `serializeTable` raises `SCHEMA` f
|
|
|
409
409
|
can own. The other helpers are total over ordinary declared inputs, subject to the core's
|
|
410
410
|
reflection-failure boundary described later.
|
|
411
411
|
|
|
412
|
-
|
|
|
413
|
-
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
414
|
-
| `extractColumn` | function | Finds one column by key; `undefined` when the schema declares no such column. |
|
|
415
|
-
| `extractKey` | function | Reads one row's declared identity; `undefined` when its key cell is missing, empty, or not a string. |
|
|
416
|
-
| `computeKeys` | function | Computes one atomic 0/1/N membership change over the keys a caller may address — the engine selection and expansion share. |
|
|
417
|
-
| `mergeTerms` | function | Merges lens terms into a column-keyed list, replacing the entry that names the same column — the `set` write. |
|
|
418
|
-
| `removeTerms` | function | Removes every lens term naming one of the given columns — the drop `sort.remove` and `filter.remove` share. |
|
|
419
|
-
| `matchesTerms` | function | Checks whether two lens lists hold the same terms in the same order, with the supplied test deciding the operands. |
|
|
420
|
-
| `matchesCell` | function | Checks whether one column can hold a value — the shape gate every write and every seed passes through. |
|
|
421
|
-
| `compareCells` | function | Compares two of one column's cells the way its `cell` fixes, describing ascending order. |
|
|
422
|
-
| `admitsFilter` | function | Checks whether one column admits a filter and every operand it carries — the gate `filter.set` and `matchesFilter` share. |
|
|
423
|
-
| `matchesFilter` | function | Tests one of a column's cells against one filter the way its `cell` fixes. |
|
|
424
|
-
| `filterRows` | function | Keeps the rows every filter accepts, in the order given; a supplied `CellMatcher` replaces the default per column. |
|
|
425
|
-
| `sortRows` | function | Orders rows by the terms given, stably; a supplied `CellComparator` replaces the default per column. |
|
|
426
|
-
| `auditTable` | function | Audits a structurally valid schema for domain faults and budget breaches, returning human diagnostics. |
|
|
427
|
-
| `serializeTable` | function | Projects a schema into JSON in declaration order, dropping every absent member; raises `SCHEMA` for a `meta` it cannot own. |
|
|
428
|
-
| `serializeRows` | function | Projects rows into JSON with each row's cells in the schema's column order, dropping every absent cell. |
|
|
412
|
+
| Name | Kind | Signature | Summary |
|
|
413
|
+
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
414
|
+
| `extractColumn` | function | `(schema: TableSchema, key: string) => TableColumn \| undefined` | Finds one column by key; `undefined` when the schema declares no such column. |
|
|
415
|
+
| `extractKey` | function | `(schema: TableSchema, row: TableRow) => TableKey \| undefined` | Reads one row's declared identity; `undefined` when its key cell is missing, empty, or not a string. |
|
|
416
|
+
| `computeKeys` | function | `(known: readonly TableKey[], current: ReadonlySet<TableKey>, input: TableKey \| readonly TableKey[] \| undefined, include: (included: boolean) => boolean) => ReadonlySet<TableKey> \| undefined` | Computes one atomic 0/1/N membership change over the keys a caller may address — the engine selection and expansion share. |
|
|
417
|
+
| `mergeTerms` | function | `<Term extends TableTerm>(current: readonly Term[], requested: readonly Term[]) => readonly Term[]` | Merges lens terms into a column-keyed list, replacing the entry that names the same column — the `set` write. |
|
|
418
|
+
| `removeTerms` | function | `<Term extends TableTerm>(current: readonly Term[], columns: readonly string[]) => readonly Term[]` | Removes every lens term naming one of the given columns — the drop `sort.remove` and `filter.remove` share. |
|
|
419
|
+
| `matchesTerms` | function | `<Term extends TableTerm>(left: readonly Term[], right: readonly Term[], equal: (left: Term, right: Term) => boolean) => boolean` | Checks whether two lens lists hold the same terms in the same order, with the supplied test deciding the operands. |
|
|
420
|
+
| `matchesCell` | function | `(column: TableColumn, value: unknown) => value is TableCell` | Checks whether one column can hold a value — the shape gate every write and every seed passes through. |
|
|
421
|
+
| `compareCells` | function | `(column: TableColumn, left: TableCell \| undefined, right: TableCell \| undefined) => number` | Compares two of one column's cells the way its `cell` fixes, describing ascending order. |
|
|
422
|
+
| `admitsFilter` | function | `(column: TableColumn, filter: TableFilter) => boolean` | Checks whether one column admits a filter and every operand it carries — the gate `filter.set` and `matchesFilter` share. |
|
|
423
|
+
| `matchesFilter` | function | `(column: TableColumn, cell: TableCell \| undefined, filter: TableFilter) => boolean` | Tests one of a column's cells against one filter the way its `cell` fixes. |
|
|
424
|
+
| `filterRows` | function | `(schema: TableSchema, rows: readonly TableRow[], filters: readonly TableFilter[], matchers?: Readonly<Record<string, CellMatcher>>) => readonly TableRow[]` | Keeps the rows every filter accepts, in the order given; a supplied `CellMatcher` replaces the default per column. |
|
|
425
|
+
| `sortRows` | function | `(schema: TableSchema, rows: readonly TableRow[], orders: readonly TableOrder[], comparators?: Readonly<Record<string, CellComparator>>) => readonly TableRow[]` | Orders rows by the terms given, stably; a supplied `CellComparator` replaces the default per column. |
|
|
426
|
+
| `auditTable` | function | `(schema: TableSchema) => readonly string[]` | Audits a structurally valid schema for domain faults and budget breaches, returning human diagnostics. |
|
|
427
|
+
| `serializeTable` | function | `(schema: TableSchema) => JSONRecord` | Projects a schema into JSON in declaration order, dropping every absent member; raises `SCHEMA` for a `meta` it cannot own. |
|
|
428
|
+
| `serializeRows` | function | `(schema: TableSchema, rows: readonly TableRow[]) => readonly JSONRecord[]` | Projects rows into JSON with each row's cells in the schema's column order, dropping every absent cell. |
|
|
429
429
|
|
|
430
430
|
### Cloners
|
|
431
431
|
|
|
@@ -433,10 +433,10 @@ Owned frozen snapshots. The table takes one of the schema at construction and on
|
|
|
433
433
|
admission, so a later edit to the object a caller passed changes nothing inside the table, and no
|
|
434
434
|
row the table hands back is a live internal reference.
|
|
435
435
|
|
|
436
|
-
|
|
|
437
|
-
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
438
|
-
| `cloneRow` | function | Clones one row into an owned frozen snapshot. |
|
|
439
|
-
| `cloneSchema` | function | Clones a whole schema into an owned frozen snapshot, freezing every nested column, choice list, choice, and `meta`; raises `SCHEMA` for a `meta` it cannot own. |
|
|
436
|
+
| Name | Kind | Signature | Summary |
|
|
437
|
+
| ------------- | -------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
438
|
+
| `cloneRow` | function | `(row: TableRow) => TableRow` | Clones one row into an owned frozen snapshot. |
|
|
439
|
+
| `cloneSchema` | function | `(schema: TableSchema) => TableSchema` | Clones a whole schema into an owned frozen snapshot, freezing every nested column, choice list, choice, and `meta`; raises `SCHEMA` for a `meta` it cannot own. |
|
|
440
440
|
|
|
441
441
|
`cloneRow` cannot fail for an ordinary row record, subject to the core's reflection-failure boundary
|
|
442
442
|
described later. `cloneSchema` can also fail when a column's `meta` holds something no clone can own, such as a
|
|
@@ -453,10 +453,10 @@ serializing a schema on its own meets, and `serializeTable` refuses the same val
|
|
|
453
453
|
The wire boundary. Each returns `undefined` on refusal rather than throwing, and each returns an
|
|
454
454
|
owned value rather than the caller's.
|
|
455
455
|
|
|
456
|
-
|
|
|
457
|
-
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
458
|
-
| `parseTable` | function | Parses unknown wire data into an owned, structurally valid, semantically sound table schema. |
|
|
459
|
-
| `parseRows` | function | Parses unknown wire data into owned rows against one table schema, coercing a numeric string and `'true'` / `'false'`. |
|
|
456
|
+
| Name | Kind | Signature | Summary |
|
|
457
|
+
| ------------ | -------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
458
|
+
| `parseTable` | function | `(input: unknown) => TableSchema \| undefined` | Parses unknown wire data into an owned, structurally valid, semantically sound table schema. |
|
|
459
|
+
| `parseRows` | function | `(schema: TableSchema, input: unknown) => readonly TableRow[] \| undefined` | Parses unknown wire data into owned rows against one table schema, coercing a numeric string and `'true'` / `'false'`. |
|
|
460
460
|
|
|
461
461
|
**Reflection failures.** A TypeScript shape does not guarantee that reflection succeeds. An ordinary
|
|
462
462
|
helper or cloner may propagate a throw from a proxy trap or accessor. Guards and parsers contain that
|
|
@@ -35,34 +35,34 @@ escaped `\{{` always emits a literal `{{`, regardless of policy.
|
|
|
35
35
|
|
|
36
36
|
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
|
|
37
37
|
|
|
38
|
-
|
|
|
39
|
-
| -------------------------- | --------- |
|
|
40
|
-
| `MissingPolicy` | type | `'error' \| 'empty' \| 'literal'`
|
|
41
|
-
| `TemplateFillValues` | type | `Readonly<Record<string, unknown>>`
|
|
42
|
-
| `TemplateManagerEventMap` | type | `{ register
|
|
43
|
-
| `TemplateErrorCode` | type | `'MISSING' \| 'NOTFOUND' \| 'INVALID' \| 'CONFLICT'`
|
|
44
|
-
| `TemplatePlaceholder` | interface | `{ name, path?, required?, fallback?, description? }`
|
|
45
|
-
| `TemplateDefinition` | interface | `{ id, name, content, placeholders, summary?, description?, category?, tags? }`
|
|
46
|
-
| `TemplateFillOptions` | interface | `{ missing?, locale? }`
|
|
47
|
-
| `TemplateFillContext` | interface | `
|
|
48
|
-
| `TemplateTokenResolution` | interface | `{ value, declared, required }`
|
|
49
|
-
| `TemplateRegisterOptions` | interface | `{ replace? }`
|
|
50
|
-
| `TemplateValidationResult` | interface | `{ valid, missing, extra }`
|
|
51
|
-
| `TemplateOptions` | interface | `{ id?, name, content, placeholders?, summary?, description?, category?, tags?, missing?, locale? }`
|
|
52
|
-
| `TemplateQuery` | interface | `{ name?, category?, tag? }`
|
|
53
|
-
| `TemplateInterface` | interface | `{ id, name, content, placeholders, summary?, description?, category?, tags
|
|
54
|
-
| `TemplateManagerOptions` | interface | `{ templates?, missing?, locale?, on?, error? }`
|
|
55
|
-
| `TemplateManagerInterface` | interface | `{ emitter, count
|
|
38
|
+
| Name | Kind | Signature | Summary |
|
|
39
|
+
| -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
40
|
+
| `MissingPolicy` | type | `'error' \| 'empty' \| 'literal'` | Names how `TemplateInterface#fill` handles an unresolved required placeholder. |
|
|
41
|
+
| `TemplateFillValues` | type | `Readonly<Record<string, unknown>>` | Represents the values a `TemplateInterface#fill` / `#validate` call resolves placeholders against. |
|
|
42
|
+
| `TemplateManagerEventMap` | type | `{ readonly register: readonly [template: TemplateInterface]; readonly remove: readonly [template: TemplateInterface]; readonly clear: readonly []; }` | Declares the push observation surface of a `TemplateManagerInterface` — an id-keyed registry, so `register` / `remove` are the events (never ordered-list `append`/`prepend`). |
|
|
43
|
+
| `TemplateErrorCode` | type | `'MISSING' \| 'NOTFOUND' \| 'INVALID' \| 'CONFLICT'` | Names the coded misuse / failure conditions thrown as a `TemplateError`. |
|
|
44
|
+
| `TemplatePlaceholder` | interface | `{ name, path?, required?, fallback?, description? }` | Represents one placeholder a `TemplateDefinition`'s `content` declares — its lookup name, an optional field path into the values record, whether it is required, and a literal fallback. |
|
|
45
|
+
| `TemplateDefinition` | interface | `{ id, name, content, placeholders, summary?, description?, category?, tags? }` | Represents a named, versionable template record — pure data, no behavior. |
|
|
46
|
+
| `TemplateFillOptions` | interface | `{ missing?, locale? }` | Carries the per-call options for `TemplateInterface#fill` / `TemplateManagerInterface#fill`. |
|
|
47
|
+
| `TemplateFillContext` | interface | `{ placeholders? }` | Carries the full option bag `fillTemplate` takes — the per-call `TemplateFillOptions` plus the declared placeholders tokens resolve against. |
|
|
48
|
+
| `TemplateTokenResolution` | interface | `{ value, declared, required }` | Represents one `{{name}}` token's resolution — the single token rule `fillTemplate` and `TemplateInterface#validate` share. |
|
|
49
|
+
| `TemplateRegisterOptions` | interface | `{ replace? }` | Carries the options for `TemplateManagerInterface#register`. |
|
|
50
|
+
| `TemplateValidationResult` | interface | `{ valid, missing, extra }` | Reports the outcome of `TemplateInterface#validate` — which required placeholders are unresolved, and which supplied values are unused. |
|
|
51
|
+
| `TemplateOptions` | interface | `{ id?, name, content, placeholders?, summary?, description?, category?, tags?, missing?, locale? }` | Carries the options for `createTemplate` / the `Template` constructor. |
|
|
52
|
+
| `TemplateQuery` | interface | `{ name?, category?, tag? }` | Represents a query for `TemplateManagerInterface#find` — every supplied field must match. |
|
|
53
|
+
| `TemplateInterface` | interface | `{ id, name, content, placeholders, summary?, description?, category?, tags?, definition(), fill(), validate(), parameters() }` | Declares the template contract a consumer holds — the readonly template record and the `definition`, `fill`, `validate`, and `parameters` calls over it. |
|
|
54
|
+
| `TemplateManagerOptions` | interface | `{ templates?, missing?, locale?, on?, error? }` | Carries the options for `createTemplateManager` / the `TemplateManager` constructor. |
|
|
55
|
+
| `TemplateManagerInterface` | interface | `{ emitter, count, register(), template(), templates(), find(), has(), remove(), clear(), destroy(), fill(), validate(), parameters() }` | Declares the registry contract a consumer holds — a self-owning, id-keyed record-holder with singular and plural accessors over the templates it registers. |
|
|
56
56
|
|
|
57
57
|
### Constants
|
|
58
58
|
|
|
59
59
|
A `Shape` cell holds the constant's declared type.
|
|
60
60
|
|
|
61
|
-
|
|
|
61
|
+
| Name | Kind | Signature | Summary |
|
|
62
62
|
| ------------------------ | ----- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
63
63
|
| `FILL_PATTERN` | const | `RegExp` | Holds the single-pass `{{name}}` substitution pattern shared by `Template#fill` and `Template#validate`. |
|
|
64
64
|
| `DEFAULT_MISSING_POLICY` | const | `MissingPolicy` | Holds `'error'`, the default `missing` policy for `Template#fill` / `TemplateManager#fill` when unspecified. |
|
|
65
|
-
| `DEFAULT_LOCALE` | const | `
|
|
65
|
+
| `DEFAULT_LOCALE` | const | `"en-US"` | Holds `'en-US'`, the default `locale` for `Template#fill` / `TemplateManager#fill` when unspecified. |
|
|
66
66
|
| `UNSAFE_FIELD_SEGMENTS` | const | `readonly string[]` | Lists the prototype-pollution-unsafe field-path segments `'__proto__'`, `'constructor'`, and `'prototype'` — a fill lookup refuses to resolve a path containing one of them, treating the placeholder as unresolved. |
|
|
67
67
|
|
|
68
68
|
```ts
|
|
@@ -84,10 +84,10 @@ FILL_PATTERN.source // the `{{name}}` / `\{{` substitution pattern
|
|
|
84
84
|
The guard recognizes self-branded errors across package copies and subclasses.
|
|
85
85
|
It refuses transparent proxies and unbranded look-alikes.
|
|
86
86
|
|
|
87
|
-
|
|
|
88
|
-
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
89
|
-
| `TemplateError` | class | Represents an error thrown by the template layer — a machine-readable `TemplateErrorCode` and an optional `context` record naming the offending id or placeholder name. |
|
|
90
|
-
| `isTemplateError` | function | Narrows an unknown caught value to a `TemplateError`. |
|
|
87
|
+
| Name | Kind | Signature | Summary |
|
|
88
|
+
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
89
|
+
| `TemplateError` | class | `new (code: TemplateErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => TemplateError` | Represents an error thrown by the template layer — a machine-readable `TemplateErrorCode` and an optional `context` record naming the offending id or placeholder name. |
|
|
90
|
+
| `isTemplateError` | function | `(value: unknown) => value is TemplateError` | Narrows an unknown caught value to a `TemplateError`. |
|
|
91
91
|
|
|
92
92
|
```ts
|
|
93
93
|
import { isTemplateError, TemplateError } from '@orkestrel/template'
|
|
@@ -104,12 +104,12 @@ try {
|
|
|
104
104
|
Pure, exported utility functions — the referentially-transparent leaves behind
|
|
105
105
|
`Template#fill` / `#validate`.
|
|
106
106
|
|
|
107
|
-
|
|
|
108
|
-
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
109
|
-
| `formatValue` | function | Formats a resolved fill value for substitution into a template's `content`. |
|
|
110
|
-
| `resolveSafeField` | function | Resolves a field path against a fill-values record, refusing any path that touches a prototype-pollution-unsafe segment. |
|
|
111
|
-
| `resolveToken` | function | Resolves one `{{name}}` token against the declared placeholders and the fill-values record. |
|
|
112
|
-
| `fillTemplate` | function | Substitutes every `{{name}}` token in `content` in a single pass. |
|
|
107
|
+
| Name | Kind | Signature | Summary |
|
|
108
|
+
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
109
|
+
| `formatValue` | function | `(value: unknown, locale: string) => string` | Formats a resolved fill value for substitution into a template's `content`. |
|
|
110
|
+
| `resolveSafeField` | function | `(record: TemplateFillValues, path: FieldPath) => unknown` | Resolves a field path against a fill-values record, refusing any path that touches a prototype-pollution-unsafe segment. |
|
|
111
|
+
| `resolveToken` | function | `(record: TemplateFillValues, placeholders: readonly TemplatePlaceholder[], token: string) => TemplateTokenResolution` | Resolves one `{{name}}` token against the declared placeholders and the fill-values record. |
|
|
112
|
+
| `fillTemplate` | function | `(content: string, values?: TemplateFillValues, options?: TemplateFillContext) => string` | Substitutes every `{{name}}` token in `content` in a single pass. |
|
|
113
113
|
|
|
114
114
|
```ts
|
|
115
115
|
import { fillTemplate, formatValue, resolveSafeField, resolveToken } from '@orkestrel/template'
|
|
@@ -129,9 +129,9 @@ fillTemplate('Limit {{limit}}', { limit: 5010 }, { missing: 'empty' }) // 'Limit
|
|
|
129
129
|
The `@orkestrel/contract` shape values built from declared template data —
|
|
130
130
|
above the helper leaves, consuming them and never consumed by them.
|
|
131
131
|
|
|
132
|
-
|
|
|
133
|
-
| ------------------ | -------- | -------------------------------------------------------------------------------------------- |
|
|
134
|
-
| `placeholderShape` | function | Builds the `@orkestrel/contract` object shape describing a template's declared placeholders. |
|
|
132
|
+
| Name | Kind | Signature | Summary |
|
|
133
|
+
| ------------------ | -------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
134
|
+
| `placeholderShape` | function | `(placeholders: readonly TemplatePlaceholder[]) => ContractShape` | Builds the `@orkestrel/contract` object shape describing a template's declared placeholders. |
|
|
135
135
|
|
|
136
136
|
```ts
|
|
137
137
|
import { placeholderShape } from '@orkestrel/template'
|
|
@@ -141,10 +141,10 @@ placeholderShape([{ name: 'city' }]) // an object ContractShape with a `city` st
|
|
|
141
141
|
|
|
142
142
|
### Factories
|
|
143
143
|
|
|
144
|
-
|
|
|
145
|
-
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
146
|
-
| `createTemplate` | function | Creates a working `TemplateInterface` from a `TemplateOptions` bag, backed by the `Template` class. |
|
|
147
|
-
| `createTemplateManager` | function | Creates a working `TemplateManagerInterface`, optionally seeded with the templates the options carry, backed by the `TemplateManager` class. |
|
|
144
|
+
| Name | Kind | Signature | Summary |
|
|
145
|
+
| ----------------------- | -------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
146
|
+
| `createTemplate` | function | `(options: TemplateOptions) => TemplateInterface` | Creates a working `TemplateInterface` from a `TemplateOptions` bag, backed by the `Template` class. |
|
|
147
|
+
| `createTemplateManager` | function | `(options?: TemplateManagerOptions) => TemplateManagerInterface` | Creates a working `TemplateManagerInterface`, optionally seeded with the templates the options carry, backed by the `TemplateManager` class. |
|
|
148
148
|
|
|
149
149
|
#### Create a template and a registry
|
|
150
150
|
|
|
@@ -171,10 +171,10 @@ templates.has('missing') // false
|
|
|
171
171
|
|
|
172
172
|
### Classes
|
|
173
173
|
|
|
174
|
-
|
|
|
175
|
-
| ----------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
176
|
-
| `Template` | class | Represents a named, versionable template — `{{name}}` tokens in `content`, filled against a values record — implementing `TemplateInterface` exactly. |
|
|
177
|
-
| `TemplateManager` | class | Represents the template registry — a self-owning, id-keyed record-holder for the `TemplateInterface` instances a consumer registers, looks up, fills, and validates by id — implementing `TemplateManagerInterface` exactly. |
|
|
174
|
+
| Name | Kind | Signature | Summary |
|
|
175
|
+
| ----------------- | ----- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
176
|
+
| `Template` | class | `new (options: TemplateOptions) => TemplateInterface` | Represents a named, versionable template — `{{name}}` tokens in `content`, filled against a values record — implementing `TemplateInterface` exactly. |
|
|
177
|
+
| `TemplateManager` | class | `new (options?: TemplateManagerOptions) => TemplateManagerInterface` | Represents the template registry — a self-owning, id-keyed record-holder for the `TemplateInterface` instances a consumer registers, looks up, fills, and validates by id — implementing `TemplateManagerInterface` exactly. |
|
|
178
178
|
|
|
179
179
|
## Methods
|
|
180
180
|
|