@orkestrel/scaffold 0.0.119 → 0.0.121
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 +19 -19
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +52 -51
- package/dist/host/claude/rules/tests.md +2 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +148 -144
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +64 -909
- package/dist/src/core/index.cjs +128 -181
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +213 -213
- package/dist/src/core/index.d.ts +213 -213
- package/dist/src/core/index.js +117 -170
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +35 -34
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +62 -58
- package/dist/src/server/index.d.ts +62 -58
- package/dist/src/server/index.js +36 -35
- package/dist/src/server/index.js.map +1 -1
- package/package.json +13 -13
|
@@ -173,7 +173,6 @@ directly.
|
|
|
173
173
|
| `extractSignature` | function | `(code: string, source: string) => SurfaceSymbol \| undefined` | Extracts one emitted declaration's signature: the symbol its column-zero `export` head names, carrying the type text the compiler emitted for it. |
|
|
174
174
|
| `extractSignatures` | function | `(declaration: string) => readonly SurfaceSymbol[]` | Extracts every signature one compiler-emitted declaration file declares: each column-zero `export` head read through `extractSignature`, an overload set's emitted heads joined in order as an intersection of parenthesized signatures. |
|
|
175
175
|
| `joinHead` | function | `(lines: readonly string[], start: number) => DeclarationHead \| undefined` | Joins the declaration head starting at `start` into one space-separated line, consuming lines until the first that opens a body: one that ends with `{`, or one that closes an empty body with `{}` or `{ }`. |
|
|
176
|
-
| `escapeRegExp` | function | `(value: string) => string` | Escapes every regex metacharacter in a literal string so it reads as text inside a larger `RegExp` source rather than as syntax. |
|
|
177
176
|
| `collectDeclarations` | function | `(source: string) => ReadonlyMap<string, Declaration>` | Collects every `export class` / `export interface` declaration one file's source text declares, each keyed `${keyword} ${name}` and carrying the body lines and the base identifiers read from its own head, so a body and a heritage clause always come from the same declaration. |
|
|
178
177
|
| `extractDeclaration` | function | `(source: string, keyword: DeclarationKeyword, name: string) => Declaration \| undefined` | Locates the named `export class` / `export interface` declaration in one file's source text and returns its body lines and its base identifiers read from that one head, so a body and a heritage clause always come from the same declaration, or `undefined` when the file declares no such head. |
|
|
179
178
|
| `extractMemberMethods` | function | `(lines: readonly string[]) => readonly MethodEntry[]` | Selects the member lines declaring a callable member: plain, `async`, generator (`*`), and optional (`records?(`) methods all count; getters, setters, `static` members, and `#` privates never do (their keyword or `#` breaks the `name(` shape). The grammar is `collectKeys`'s, read once over `extractBodyLines`'s projection of the body, so commented method-like payload never becomes eligible and each member keys to the owner head that projection supplies. Each member carries its own doc block's description paragraph, read through `collectSummaries`; the first declaration of a name answers for it. |
|
package/dist/host/guides/html.md
CHANGED
|
@@ -13,7 +13,7 @@ That totality statement governs document parsing. `parseStartTag` is the separat
|
|
|
13
13
|
|
|
14
14
|
### Types
|
|
15
15
|
|
|
16
|
-
The full node shape and handle contract, from [`types.ts`](../src/core/types.ts). `category` is the discriminant every node carries; absence is always `undefined`, never a sentinel. A
|
|
16
|
+
The full node shape and handle contract, from [`types.ts`](../src/core/types.ts). `category` is the discriminant every node carries; absence is always `undefined`, never a sentinel. A member's type never appears in a cell, because the declaration carries it and the row's name reaches it. A generic declaration carries its parameter binding beside its literal, so a `TNode` or a `T` in a cell is that declaration's own parameter. The node categories are worked through in § [The AST model](#the-ast-model), and the option interfaces in § [The sanitize floor](#the-sanitize-floor) and § [The distill pass](#the-distill-pass).
|
|
17
17
|
|
|
18
18
|
| Name | Kind | Signature | Summary |
|
|
19
19
|
| --------------------- | --------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -45,7 +45,7 @@ The full node shape and handle contract, from [`types.ts`](../src/core/types.ts)
|
|
|
45
45
|
|
|
46
46
|
### Constants
|
|
47
47
|
|
|
48
|
-
The element vocabularies, allowlists, entity table, and depth bound every engine reads, from [`constants.ts`](../src/core/constants.ts). Every collection is a frozen array, or — for the keyed tables — a frozen record read through `Object.hasOwn`, so nothing a consumer can reach changes what an engine sees (§ [The sanitize floor](#the-sanitize-floor)).
|
|
48
|
+
The element vocabularies, allowlists, entity table, and depth bound every engine reads, from [`constants.ts`](../src/core/constants.ts). Every collection is a frozen array, or — for the keyed tables — a frozen record read through `Object.hasOwn`, so nothing a consumer can reach changes what an engine sees (§ [The sanitize floor](#the-sanitize-floor)). The depth bound's degrade behavior is § [Depth degrade semantics](#depth-degrade-semantics).
|
|
49
49
|
|
|
50
50
|
| Name | Kind | Signature | Summary |
|
|
51
51
|
| ---------------------- | ----- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -73,8 +73,6 @@ The element vocabularies, allowlists, entity table, and depth bound every engine
|
|
|
73
73
|
|
|
74
74
|
The from-unknown guards, from [`validators.ts`](../src/core/validators.ts). A guard validates an entire untrusted value from scratch — a deserialized AST, a value crossing a process boundary — and is total: a cycle, a hostile prototype, a revoked proxy, or 10,000 levels of nesting returns `false` rather than throwing. The name, element, and URL predicates the engines consult narrow nothing, so they are not guards: they sit with the other pure leaves in [`helpers.ts`](../src/core/helpers.ts) (§ [Helpers](#helpers)).
|
|
75
75
|
|
|
76
|
-
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
77
|
-
|
|
78
76
|
| Name | Kind | Signature | Summary |
|
|
79
77
|
| ----------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
80
78
|
| `isHTMLAttribute` | const | `Guard<HTMLAttribute>` | Determines whether an arbitrary value is a structurally valid HTML attribute - exactly a string name, optionally a string value, and nothing else. |
|
|
@@ -163,12 +161,10 @@ resolveDerivations([[node, node]]).get(node) // node
|
|
|
163
161
|
|
|
164
162
|
Declarative `ContractShape` values (from `@orkestrel/contract`) in [`shapers.ts`](../src/core/shapers.ts) — `createContract` compiles one shape into a JSON Schema, a guard, a coercing parser, and a seeded generator that can never drift apart. A shape tree has no lazy or self-referential node, so only the leaves of this AST shape here; `ElementNode` and `HTMLDocument` recurse into `HTMLNode` and therefore stay hand-written, cycle- and depth-capped guards in `validators.ts`.
|
|
165
163
|
|
|
166
|
-
A `Shape` cell holds the constant's declared type.
|
|
167
|
-
|
|
168
164
|
| Name | Kind | Signature | Summary |
|
|
169
165
|
| ---------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
170
166
|
| `attributeShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; value: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of an `HTMLAttribute` - an element attribute's name and, when the source wrote one, its value. `value` is optional: its absence is what distinguishes `<input disabled>` from `<input disabled="">`. |
|
|
171
|
-
| `
|
|
167
|
+
| `textNodeShape` | const | `import("@orkestrel/contract").ObjectShape<{ category: import("@orkestrel/contract").LiteralShape<readonly ["text"]>; value: import("@orkestrel/contract").StringShape; }, false>` | Describes the shape of a `TextNode` - the decoded character-data leaf. |
|
|
172
168
|
| `commentShape` | const | `import("@orkestrel/contract").ObjectShape<{ category: import("@orkestrel/contract").LiteralShape<readonly ["comment"]>; value: import("@orkestrel/contract").StringShape; }, false>` | Describes the shape of a `CommentNode` - the verbatim, never-decoded comment leaf a bogus comment also recovers to. |
|
|
173
169
|
| `doctypeShape` | const | `import("@orkestrel/contract").ObjectShape<{ category: import("@orkestrel/contract").LiteralShape<readonly ["doctype"]>; name: import("@orkestrel/contract").StringShape; public: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; system: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of a `DoctypeNode` - the declared root name plus the optional public and system identifiers of a legacy declaration. |
|
|
174
170
|
|
|
@@ -64,8 +64,8 @@ transparent proxies, unbranded look-alikes, and plain branded objects fail.
|
|
|
64
64
|
| `supportsIndexedDB` | function | `() => boolean` | Checks whether IndexedDB is available in this environment. |
|
|
65
65
|
| `promisifyRequest` | function | `<T>(request: IDBRequest<T>) => Promise<T>` | Resolves an `IDBRequest` to its result, rejecting with an `IndexedDBError`. |
|
|
66
66
|
| `promisifyTransaction` | function | `(transaction: IDBTransaction) => Promise<void>` | Resolves after an `IDBTransaction` commits, rejecting if it errors or aborts. |
|
|
67
|
-
| `readRecord` | function | `(source: IDBObjectStore \| IDBIndex, key: IDBValidKey) => Promise<
|
|
68
|
-
| `readRecords` | function | `(source: IDBObjectStore \| IDBIndex, query?: IDBKeyRange \| IDBValidKey, count?: number) => Promise<readonly
|
|
67
|
+
| `readRecord` | function | `(source: IDBObjectStore \| IDBIndex, key: IDBValidKey) => Promise<StoreRecord \| undefined>` | Reads one record by key from a store or index, narrowing it to a `StoreRecord`. |
|
|
68
|
+
| `readRecords` | function | `(source: IDBObjectStore \| IDBIndex, query?: IDBKeyRange \| IDBValidKey, count?: number) => Promise<readonly StoreRecord[]>` | Reads many records from a store or index over an optional key range, narrowing each to a `StoreRecord`. |
|
|
69
69
|
| `hasKey` | function | `(source: IDBObjectStore \| IDBIndex, key: IDBValidKey) => Promise<boolean>` | Checks whether a key is present in a store or index. |
|
|
70
70
|
| `createIndex` | function | `(store: IDBObjectStore, definition: IndexDefinition) => void` | Creates a secondary index on a store from its `IndexDefinition`. |
|
|
71
71
|
| `wrapCall` | function | `<T>(action: () => T) => T` | Runs a synchronous native IndexedDB call, wrapping a thrown `DOMException` into a typed `IndexedDBError`. |
|
|
@@ -74,29 +74,25 @@ transparent proxies, unbranded look-alikes, and plain branded objects fail.
|
|
|
74
74
|
| `rangeBelowKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range strictly below one key. |
|
|
75
75
|
| `rangeToKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range ending at and including one key. |
|
|
76
76
|
| `rangePrefix` | function | `(value: string) => IDBKeyRange` | Builds a key range containing every string with one prefix. |
|
|
77
|
-
| `
|
|
77
|
+
| `wrapDOMException` | function | `(error: DOMException \| null) => IndexedDBError` | Maps a native IndexedDB `DOMException` to a typed `IndexedDBError`. |
|
|
78
78
|
| `IndexedDBError` | class | `new (code: IndexedDBErrorCode, message: string, cause?: unknown, context?: Readonly<Record<string, unknown>>) => IndexedDBError` | Represents an error thrown by the IndexedDB wrapper, carrying a machine-readable `code` and an optional `context` beside the native cause. |
|
|
79
79
|
| `isIndexedDBError` | function | `(value: unknown) => value is IndexedDBError` | Checks whether a value is an `IndexedDBError`. |
|
|
80
80
|
|
|
81
|
-
`supportsIndexedDB` reads `globalThis.indexedDB`, and `hasKey` is a native `count` greater than 0. `createIndex` is the shared index-DDL leaf both the built-in schema pass and `context.indexes.create` run. `
|
|
81
|
+
`supportsIndexedDB` reads `globalThis.indexedDB`, and `hasKey` is a native `count` greater than 0. `createIndex` is the shared index-DDL leaf both the built-in schema pass and `context.indexes.create` run. `wrapDOMException` is the request boundary every bridge maps a native `DOMException` through.
|
|
82
82
|
|
|
83
83
|
### Constants
|
|
84
84
|
|
|
85
|
-
A `Shape` cell holds the constant's declared type.
|
|
86
|
-
|
|
87
85
|
| Name | Kind | Signature | Summary |
|
|
88
86
|
| ------------- | ----- | ---------------------------------------------- | --------------------------------------------------------------------- |
|
|
89
87
|
| `ERROR_CODES` | const | `Readonly<Record<string, IndexedDBErrorCode>>` | Maps native `DOMException.name` → the wrapper's `IndexedDBErrorCode`. |
|
|
90
88
|
|
|
91
|
-
`
|
|
89
|
+
`wrapDOMException` reads this frozen map at the request boundary, falling back to `UNKNOWN` for a native name it does not carry.
|
|
92
90
|
|
|
93
91
|
### Types
|
|
94
92
|
|
|
95
|
-
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.
|
|
96
|
-
|
|
97
93
|
| Name | Kind | Signature | Summary |
|
|
98
94
|
| --------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
99
|
-
| `
|
|
95
|
+
| `StoreRecord` | type | `Record<string, unknown>` | Represents a record stored in, and read from, an object store. |
|
|
100
96
|
| `KeyPath` | type | `string \| readonly string[]` | Represents a key path — one field, or several for a compound key. |
|
|
101
97
|
| `IndexDefinition` | interface | `{ name, path, unique?, multiple? }` | Represents the declaration of a secondary index — its name, key path, and uniqueness. |
|
|
102
98
|
| `StoreDefinition` | interface | `{ path?, increment?, indexes? }` | Represents the declaration of one object store — its key path, key generation, and secondary indexes. |
|
|
@@ -115,13 +111,13 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
115
111
|
| `IndexedDBTransactionInterface` | interface | `{ transaction, mode, stores, active, finished, error, store(), abort(), commit() }` | Represents the contract of an explicit transaction over one or more stores. |
|
|
116
112
|
| `IndexedDBTransactionStoreInterface` | interface | `{ store }` | Represents the contract of an object store bound to an explicit transaction. |
|
|
117
113
|
|
|
118
|
-
Values are this package's own `
|
|
114
|
+
Values are this package's own `StoreRecord` (a record), narrowed from IndexedDB's structured clone with `isRecord` (from `@orkestrel/contract`) at the read boundary — an `as`-free bridge. Keys are the full native `IDBValidKey`, so the wrapper speaks IndexedDB's whole key space.
|
|
119
115
|
|
|
120
116
|
A database connects **lazily**: the first store operation (or an explicit `connect`) opens it; you never wire up `onsuccess` yourself. `version` controls schema creation: pin an explicit number to create any missing stores on a bump, or **omit it** for auto-managed mode, where the database opens at its current version and bumps once on its own to create any declared store the stored schema lacks — so adding a store never needs a manual version bump.
|
|
121
117
|
|
|
122
118
|
## Methods
|
|
123
119
|
|
|
124
|
-
The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. Each interface's `readonly` data members are named in the `
|
|
120
|
+
The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. Each interface's `readonly` data members are named in the `Signature` column of the [Types](#types) table, earlier. Each class implements its interface exactly, so this doubles as the per-instance method surface (`AGENTS.md` § Documentation contract).
|
|
125
121
|
|
|
126
122
|
`IndexedDBUpgradeContext` carries only readonly data, so no Methods table follows for it. Its managers carry the upgrade's schema verbs: `context.stores` is the store manager, while `IndexedDBDatabaseInterface.stores` is the plain name list.
|
|
127
123
|
|
|
@@ -142,9 +138,9 @@ The keyed record surface `IndexedDBStoreInterface` and `IndexedDBTransactionStor
|
|
|
142
138
|
|
|
143
139
|
| Method | Returns | Summary |
|
|
144
140
|
| --------- | ------------------------------------------- | ---------------------------------------------------------------------- |
|
|
145
|
-
| `get` | `Promise<
|
|
146
|
-
| `resolve` | `Promise<
|
|
147
|
-
| `records` | `Promise<readonly
|
|
141
|
+
| `get` | `Promise<StoreRecord \| undefined>` | Reads the record at a primary key, or `undefined` on a miss. |
|
|
142
|
+
| `resolve` | `Promise<StoreRecord>` | Reads the record at a primary key, throwing `NOT_FOUND` on a miss. |
|
|
143
|
+
| `records` | `Promise<readonly StoreRecord[]>` | Reads the stored records over an optional key range. |
|
|
148
144
|
| `keys` | `Promise<readonly IDBValidKey[]>` | Lists the stored primary keys over an optional key range. |
|
|
149
145
|
| `has` | `Promise<boolean>` | Checks whether a primary key is present. |
|
|
150
146
|
| `count` | `Promise<number>` | Counts the stored records within an optional key range. |
|
|
@@ -160,9 +156,9 @@ The keyed record surface `IndexedDBStoreInterface` and `IndexedDBTransactionStor
|
|
|
160
156
|
|
|
161
157
|
| Method | Returns | Summary |
|
|
162
158
|
| --------- | ------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
163
|
-
| `get` | `Promise<
|
|
164
|
-
| `resolve` | `Promise<
|
|
165
|
-
| `records` | `Promise<readonly
|
|
159
|
+
| `get` | `Promise<StoreRecord \| undefined>` | Reads the record at a primary key, or `undefined` on a miss. |
|
|
160
|
+
| `resolve` | `Promise<StoreRecord>` | Reads the record at a primary key, throwing `NOT_FOUND` on a miss. |
|
|
161
|
+
| `records` | `Promise<readonly StoreRecord[]>` | Reads the stored records over an optional key range. |
|
|
166
162
|
| `keys` | `Promise<readonly IDBValidKey[]>` | Lists the stored primary keys over an optional key range. |
|
|
167
163
|
| `has` | `Promise<boolean>` | Checks whether a primary key is present. |
|
|
168
164
|
| `count` | `Promise<number>` | Counts the stored records within an optional key range. |
|
|
@@ -177,9 +173,9 @@ The keyed record surface `IndexedDBStoreInterface` and `IndexedDBTransactionStor
|
|
|
177
173
|
|
|
178
174
|
| Method | Returns | Summary |
|
|
179
175
|
| --------- | ------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
180
|
-
| `get` | `Promise<
|
|
181
|
-
| `resolve` | `Promise<
|
|
182
|
-
| `records` | `Promise<readonly
|
|
176
|
+
| `get` | `Promise<StoreRecord \| undefined>` | Reads the first record for an index key, or `undefined` on a miss. |
|
|
177
|
+
| `resolve` | `Promise<StoreRecord>` | Reads the first record for an index key, throwing `NOT_FOUND` on a miss. |
|
|
178
|
+
| `records` | `Promise<readonly StoreRecord[]>` | Reads the matching records over an optional index-key range. |
|
|
183
179
|
| `keys` | `Promise<readonly IDBValidKey[]>` | Lists the primary keys of the matching records over an optional index-key range. |
|
|
184
180
|
| `primary` | `Promise<IDBValidKey \| undefined>` | Reads the primary key an index key maps to, or `undefined` on a miss. |
|
|
185
181
|
| `has` | `Promise<boolean>` | Checks whether an index key is present. |
|
|
@@ -212,9 +208,9 @@ Each readonly data member is a snapshot of the position the cursor stopped on, b
|
|
|
212
208
|
|
|
213
209
|
| Method | Returns | Summary |
|
|
214
210
|
| --------- | ------------------------------------------- | ---------------------------------------------------------------------- |
|
|
215
|
-
| `get` | `Promise<
|
|
216
|
-
| `resolve` | `Promise<
|
|
217
|
-
| `records` | `Promise<readonly
|
|
211
|
+
| `get` | `Promise<StoreRecord \| undefined>` | Reads the record at a primary key, or `undefined` on a miss. |
|
|
212
|
+
| `resolve` | `Promise<StoreRecord>` | Reads the record at a primary key, throwing `NOT_FOUND` on a miss. |
|
|
213
|
+
| `records` | `Promise<readonly StoreRecord[]>` | Reads the stored records over an optional key range. |
|
|
218
214
|
| `keys` | `Promise<readonly IDBValidKey[]>` | Lists the stored primary keys over an optional key range. |
|
|
219
215
|
| `has` | `Promise<boolean>` | Checks whether a primary key is present. |
|
|
220
216
|
| `count` | `Promise<number>` | Counts the stored records within an optional key range. |
|
|
@@ -249,11 +245,11 @@ These invariants hold across `src/browser` ↔ `indexeddb.md`:
|
|
|
249
245
|
|
|
250
246
|
1. **DOC ↔ SOURCE bijection.** Every row in the `## Surface` tables is a real export of the wrapper, and every export appears as a Surface row — exhaustive, both directions (`AGENTS.md` § Documentation contract).
|
|
251
247
|
2. **Native, not a query engine.** The wrapper exposes only what raw IndexedDB offers natively — object stores, secondary indexes, key-range helpers, cursors, and multi-store transactions. It has **no** `where` / `filter` / `order` / aggregate builder; that stays out of scope entirely, deliberately, so the wrapper never grows into a second query DSL.
|
|
252
|
-
3. **`
|
|
253
|
-
4. **In-line or out-of-line keys.** A store with a `path` keys
|
|
248
|
+
3. **`StoreRecord` values, `IDBValidKey` keys.** Reads return this package's own `StoreRecord` (narrowed with `isRecord`, never an unchecked cast); writes take a `StoreRecord`. Keys are the native `IDBValidKey`.
|
|
249
|
+
4. **In-line or out-of-line keys.** A store with a `path` keys records by that field; a store with no `path` is out-of-line and takes an explicit key on `set` / `add` (`set(record, key)`).
|
|
254
250
|
5. **Batch by the array overload, array-first.** `get` / `resolve` / `has` / `remove` / `set` / `add` take one value for one result or an array for an array of results (`.claude/rules/patterns.md` § Managers § Batch operations). The array overload is declared first because an array is itself both a record and a compound `IDBValidKey`; to act on a single compound key, pass `IDBKeyRange.only([…])` to `records` / `count`.
|
|
255
251
|
6. **Each standalone call is its own transaction; `read` / `write` are atomic.** A store method opens and commits its own implicit transaction; `db.read` / `db.write` run a scope across stores that commits on resolve and rolls back on a throw. The completion listener is attached BEFORE the scope runs (not after it resolves), so a scope whose last step is a non-IDB `await` — letting the native transaction auto-commit while the scope is still on the stack — still settles `read` / `write` instead of hanging: `complete` can otherwise fire before a listener attached only after the scope returns would ever be wired.
|
|
256
|
-
7. **`get` / `records` narrow to records; `count` / `has` / `keys` operate on keys.** A store or index counts, tests presence, and lists keys over every stored value regardless of shape, but `get` / `resolve` / `records` narrow each value with `isRecord` — so a store holding a non-record value shows `count` greater than `records().length`, and `has` reads `true` for a key `get` reads back as `undefined` (a miss and a non-record value both read as `undefined` from `get`). A cursor reports the same boundary the same way: `cursor.value` is `
|
|
252
|
+
7. **`get` / `records` narrow to records; `count` / `has` / `keys` operate on keys.** A store or index counts, tests presence, and lists keys over every stored value regardless of shape, but `get` / `resolve` / `records` narrow each value with `isRecord` — so a store holding a non-record value shows `count` greater than `records().length`, and `has` reads `true` for a key `get` reads back as `undefined` (a miss and a non-record value both read as `undefined` from `get`). A cursor reports the same boundary the same way: `cursor.value` is `StoreRecord | undefined` and reads `undefined` for a non-record stored value — see Cursor streaming and in-place mutation, later in this guide.
|
|
257
253
|
8. **DOC ↔ SOURCE method bijection.** Every method in a `## Methods` table is a real call-signature member of that interface in source, and every public method of each behavioral interface is documented — exhaustive, both directions; and each implementing class exposes exactly its interface's public methods, no more (`AGENTS.md` § Documentation contract).
|
|
258
254
|
|
|
259
255
|
9. **One atomic upgrade boundary.** The built-in create-missing-stores pass and the custom `upgrade` callback run inside the same versionchange transaction and failure boundary. A synchronous built-in/custom fault, or a custom rejection captured while that transaction remains active, aborts the whole upgrade and rejects `connect()` with `UPGRADE`; no partially created store, index, or migration survives. Its `cause` preserves the initiating value even when that value is `undefined`, and a native schema failure retains the nested typed chain (`UPGRADE` → `CONSTRAINT` → native `ConstraintError`). A failed open clears only its attempt-local state, so the same handle can retry. If auto-commit already occurred but the browser reports success after a failure was recorded, the wrapper closes that result before rejecting, preventing an orphan connection; closing cannot undo the already-committed schema.
|
|
@@ -319,7 +315,7 @@ while (cursor) {
|
|
|
319
315
|
}
|
|
320
316
|
```
|
|
321
317
|
|
|
322
|
-
A `store` cursor runs in a `readwrite` transaction, so `update` / `remove` work; an `index` cursor is read-only and rejects them with a typed `IndexedDBError` (`code: 'READONLY'`, native `ReadOnlyError`). Iterate promptly — an unrelated `await` between `continue` steps lets the transaction auto-commit and ends the loop. `cursor.value` is `
|
|
318
|
+
A `store` cursor runs in a `readwrite` transaction, so `update` / `remove` work; an `index` cursor is read-only and rejects them with a typed `IndexedDBError` (`code: 'READONLY'`, native `ReadOnlyError`). Iterate promptly — an unrelated `await` between `continue` steps lets the transaction auto-commit and ends the loop. `cursor.value` is `StoreRecord | undefined`: it narrows the stored value with `isRecord` exactly as `get` does, so a non-record stored value reads `undefined` while the cursor still stops on that position and still exposes its `key` and `primary`. Test `value` before you dereference it.
|
|
323
319
|
|
|
324
320
|
### Seeking an index cursor to one primary key
|
|
325
321
|
|
|
@@ -391,18 +387,18 @@ import {
|
|
|
391
387
|
readRecord,
|
|
392
388
|
readRecords,
|
|
393
389
|
wrapCall,
|
|
394
|
-
|
|
390
|
+
wrapDOMException,
|
|
395
391
|
} from '@orkestrel/indexeddb'
|
|
396
392
|
|
|
397
393
|
await db.read('users', async (transaction) => {
|
|
398
394
|
const native = transaction.store('users').store
|
|
399
395
|
await promisifyRequest(wrapCall(() => native.get('u1'))) // sync throw → IndexedDBError too
|
|
400
|
-
await readRecord(native, 'u1') // narrowed to
|
|
396
|
+
await readRecord(native, 'u1') // narrowed to StoreRecord (or undefined) with isRecord
|
|
401
397
|
await readRecords(native) // every record, narrowed the same way
|
|
402
398
|
await hasKey(native, 'u1') // a native count() > 0
|
|
403
399
|
await promisifyTransaction(native.transaction) // resolves after the transaction commits
|
|
404
400
|
})
|
|
405
|
-
|
|
401
|
+
wrapDOMException(null) // the same DOMException → IndexedDBError mapping every bridge uses
|
|
406
402
|
|
|
407
403
|
// createIndex is the leaf `context.indexes.create` delegates to inside
|
|
408
404
|
// onupgradeneeded — call it directly only if you are hand-rolling a raw
|
|
@@ -493,7 +489,7 @@ await db.connect()
|
|
|
493
489
|
## Tests
|
|
494
490
|
|
|
495
491
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/browser` bijection, the `## Methods` ↔ interface bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Feature-detecting before opening a database` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline.
|
|
496
|
-
- [`tests/src/browser/helpers.test.ts`](../tests/src/browser/helpers.test.ts) — the `supportsIndexedDB` probe, the key-range helpers asserted on the bounds they return, the shared read primitives (`readRecord` / `readRecords` / `hasKey`) over a real store / index (including the non-record `isRecord` boundary), `createIndex` translating an `IndexDefinition` into a native `createIndex` call inside a real `onupgradeneeded` (honouring `unique` / `multiple`), the `promisifyRequest` / `promisifyTransaction` bridges (success + `IndexedDBError` rejection), `wrapCall` over each of its three paths (a returned value passing through, a thrown `DOMException` surfacing as the mapped `IndexedDBError` with the native error as `cause`, and a non-`DOMException` throw rethrown by identity), the `context` an `IndexedDBError` carries beside its `code`, `
|
|
492
|
+
- [`tests/src/browser/helpers.test.ts`](../tests/src/browser/helpers.test.ts) — the `supportsIndexedDB` probe, the key-range helpers asserted on the bounds they return, the shared read primitives (`readRecord` / `readRecords` / `hasKey`) over a real store / index (including the non-record `isRecord` boundary), `createIndex` translating an `IndexDefinition` into a native `createIndex` call inside a real `onupgradeneeded` (honouring `unique` / `multiple`), the `promisifyRequest` / `promisifyTransaction` bridges (success + `IndexedDBError` rejection), `wrapCall` over each of its three paths (a returned value passing through, a thrown `DOMException` surfacing as the mapped `IndexedDBError` with the native error as `cause`, and a non-`DOMException` throw rethrown by identity), the `context` an `IndexedDBError` carries beside its `code`, `wrapDOMException` (including `INACTIVE` / `INVALID`), and `isIndexedDBError`.
|
|
497
493
|
- [`tests/src/browser/IndexedDBDatabase.test.ts`](../tests/src/browser/IndexedDBDatabase.test.ts) — the database handle in real Chromium: lazy connect and state, the `store` accessor, atomic `read` / `write` scopes (including settling when the scope ends on a trailing non-IDB `await`, the auto-commit race), `close` / `drop`, the auto-managed schema path, persistence across reopen, the `upgrade` hook (dropping a store, indexing an existing store and a same-upgrade `context.stores.create`d store through `context.indexes.create` — honouring `unique` / `multiple` — removing an index through `context.indexes.drop`, data migration through `context.stores.store`, `context.stores.create`, `old` / `version` / `stores.names`, an async `upgrade` rejection cleanly failing `connect()` with `UPGRADE`, and a synchronous `wrapCall` fault from `context.stores.drop` / `context.indexes.drop` targeting a missing store/index likewise failing `connect()` with `UPGRADE`), built-in auto-managed missing-store creation containing duplicate index names as `UPGRADE` → `CONSTRAINT` → native `ConstraintError` on two distinct same-handle `connect()` retries while suppressing the custom callback, atomic rollback of the version, sentinel data, and failed store, deletion without an orphan connection, synchronous `throw undefined` and asynchronous `Promise.reject(undefined)` failures retaining a present `cause` property, raw blockers proving a versioned open and deletion remain pending until release, repeated blocked connects share one Promise and produce one upgrade/owned connection, `close()` during blocked explicit or auto-managed second opens rejecting `CLOSED` after release without orphaning the native result, and `drop()` directly retiring a pending blocked open before deletion completes without leaving an orphan, a live connection yielding to a second connection's `versionchange`, that yielded handle lazily reconnecting at the new version on its next operation, and an ABNORMAL (non-self-initiated) `onclose` likewise leaving the handle able to lazily reconnect instead of staying invalid forever.
|
|
498
494
|
- [`tests/src/browser/IndexedDBStore.test.ts`](../tests/src/browser/IndexedDBStore.test.ts) — the store reached through `db.store(name)`: metadata getters, the keyed CRUD surface with array-first batch overloads, key-range reads, `index` / `cursor` access, and the `NOT_FOUND` / `CONSTRAINT` / `DATA` (a non-cloneable value) faults.
|
|
499
495
|
- [`tests/src/browser/IndexedDBIndex.test.ts`](../tests/src/browser/IndexedDBIndex.test.ts) — the index reached through `store.index(name)`: metadata getters, the read surface (`get` / `resolve` / `records` / `keys` / `primary` / `has` / `count` / `cursor`), the unique-index lookup + constraint, and the `multiple` (multiEntry) array index.
|