@orkestrel/scaffold 0.0.119 → 0.0.120
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 +15 -15
- 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 +27 -26
- 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/budget.md +1 -5
- package/dist/host/guides/codec.md +18 -3
- 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/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +136 -136
- 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/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/manifest.json +39 -464
- package/dist/src/core/index.cjs +162 -177
- 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 +151 -166
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +25 -25
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +50 -50
- package/dist/src/server/index.d.ts +50 -50
- package/dist/src/server/index.js +26 -26
- package/dist/src/server/index.js.map +1 -1
- package/package.json +9 -9
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.
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# JSON-RPC 2.0
|
|
2
|
+
|
|
3
|
+
> The JSON-RPC 2.0 wire contract the Orkestrel protocol packages share: the message types, total
|
|
4
|
+
> structural guards that place every parsed JSON value in at most one message arm, the reserved
|
|
5
|
+
> error codes, and the response builders.
|
|
6
|
+
|
|
7
|
+
Source: [`src/core`](../src/core). Published through `@orkestrel/jsonrpc`.
|
|
8
|
+
|
|
9
|
+
## Messages
|
|
10
|
+
|
|
11
|
+
A JSON-RPC 2.0 message is an invocation or a response. An invocation is a `JSONRPCRequest`, which
|
|
12
|
+
carries an `id` and requires a response, or a `JSONRPCNotification`, which carries no `id` member
|
|
13
|
+
and permits none. A response is a `JSONRPCResultResponse`, which echoes the request's `id` beside a
|
|
14
|
+
`result`, or a `JSONRPCErrorResponse`, which carries a `JSONRPCError` under `error`.
|
|
15
|
+
`JSONRPCInvocation`, `JSONRPCResponse`, and `JSONRPCMessage` name the unions.
|
|
16
|
+
|
|
17
|
+
A `JSONRPCId` is a string or a finite integer, and never `null`. An error response always carries an
|
|
18
|
+
`id` member, and the member holds `null` when the request's id could not be read. A request and a
|
|
19
|
+
result response always carry an id.
|
|
20
|
+
|
|
21
|
+
The package carries parameters by name only: a present `params` member is a record, and the guards
|
|
22
|
+
refuse a by-position array.
|
|
23
|
+
|
|
24
|
+
The guards partition every value whose presence checks and member reads agree. An invocation guard
|
|
25
|
+
refuses a value carrying a `result` or `error` member, a response guard refuses a value carrying a
|
|
26
|
+
`method` member, the notification guard refuses any `id` member, the result-response guard refuses
|
|
27
|
+
an `error` member, and the error-response guard refuses a `result` member. A value carrying both an
|
|
28
|
+
invocation's and a response's members is no message. A `Proxy` whose `has` and `get` traps
|
|
29
|
+
disagree can satisfy several arms: a `has` trap that denies every member lets one value pass as a
|
|
30
|
+
notification and as an error response.
|
|
31
|
+
|
|
32
|
+
### Classify a message
|
|
33
|
+
|
|
34
|
+
Pass any parsed value to a guard. Each guard answers for one arm, and `isJSONRPCMessage` answers
|
|
35
|
+
for all of them:
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import { isJSONRPCInvocation, isJSONRPCMessage, isJSONRPCResponse } from '@orkestrel/jsonrpc'
|
|
39
|
+
|
|
40
|
+
const hybrid: unknown = JSON.parse('{"jsonrpc":"2.0","id":1,"method":"ping","result":null}')
|
|
41
|
+
|
|
42
|
+
isJSONRPCMessage(hybrid) // false
|
|
43
|
+
isJSONRPCInvocation({ jsonrpc: '2.0', method: 'initialized' }) // true
|
|
44
|
+
isJSONRPCResponse({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) // true
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Responses
|
|
48
|
+
|
|
49
|
+
`buildJSONRPCResult` echoes a request's id beside a result. The id must be an integer or a string
|
|
50
|
+
and the result a JSON value, and the builder checks neither. `buildJSONRPCError` writes the
|
|
51
|
+
id it is given, `null` included, and omits `data` from the error object when the argument is
|
|
52
|
+
absent. The five `JSONRPC_*` constants are the codes JSON-RPC 2.0 reserves for a parse failure, an
|
|
53
|
+
invalid request, an unknown method, invalid parameters, and an internal failure. The package throws
|
|
54
|
+
no error of its own.
|
|
55
|
+
|
|
56
|
+
### Answer a request
|
|
57
|
+
|
|
58
|
+
Parse the payload, answer an unreadable or invalid request with `id: null`, and echo the id of every
|
|
59
|
+
request the guard accepts:
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
import type { JSONRPCResponse } from '@orkestrel/jsonrpc'
|
|
63
|
+
import {
|
|
64
|
+
buildJSONRPCError,
|
|
65
|
+
buildJSONRPCResult,
|
|
66
|
+
isJSONRPCRequest,
|
|
67
|
+
JSONRPC_INVALID_REQUEST,
|
|
68
|
+
JSONRPC_METHOD_NOT_FOUND,
|
|
69
|
+
JSONRPC_PARSE_ERROR,
|
|
70
|
+
} from '@orkestrel/jsonrpc'
|
|
71
|
+
|
|
72
|
+
function answer(text: string): JSONRPCResponse {
|
|
73
|
+
let value: unknown
|
|
74
|
+
try {
|
|
75
|
+
value = JSON.parse(text)
|
|
76
|
+
} catch {
|
|
77
|
+
return buildJSONRPCError(null, JSONRPC_PARSE_ERROR, 'Parse error')
|
|
78
|
+
}
|
|
79
|
+
if (!isJSONRPCRequest(value)) {
|
|
80
|
+
return buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, 'Invalid Request')
|
|
81
|
+
}
|
|
82
|
+
if (value.method !== 'ping') {
|
|
83
|
+
return buildJSONRPCError(value.id, JSONRPC_METHOD_NOT_FOUND, 'Method not found')
|
|
84
|
+
}
|
|
85
|
+
return buildJSONRPCResult(value.id, 'pong')
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
answer('{') // { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }
|
|
89
|
+
answer('{"jsonrpc":"2.0","id":7,"method":"ping"}') // { jsonrpc: '2.0', id: 7, result: 'pong' }
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Validation
|
|
93
|
+
|
|
94
|
+
Every guard takes `unknown` and never throws. `isJSONRPCId` accepts a string or a finite integer,
|
|
95
|
+
and every other guard returns `false` for a value that is not a plain record. A guard reads members
|
|
96
|
+
through property access, so an accessor or a `Proxy` with no traps passes when the members it
|
|
97
|
+
yields pass. A member that throws on read fails the value, except a `data` member and a member the
|
|
98
|
+
contract does not name: no guard reads either, so a throwing accessor there passes. A guard accepts
|
|
99
|
+
members the contract does not name.
|
|
100
|
+
|
|
101
|
+
- `isJSONRPCId` accepts a string, the empty string included, and a finite integer.
|
|
102
|
+
- `isJSONRPCError` requires an integer `code` and a string `message`, and accepts any `data`.
|
|
103
|
+
- `isJSONRPCRequest` requires `jsonrpc: '2.0'`, an id, and a string `method`.
|
|
104
|
+
- `isJSONRPCNotification` requires `jsonrpc: '2.0'` and a string `method`, and refuses an `id`
|
|
105
|
+
member whatever it holds, `undefined` and `null` included.
|
|
106
|
+
- `isJSONRPCResultResponse` requires `jsonrpc: '2.0'`, an id, and a `result` member holding any
|
|
107
|
+
value but `undefined`, which JSON cannot carry.
|
|
108
|
+
- `isJSONRPCErrorResponse` requires `jsonrpc: '2.0'`, an `id` member holding an id or `null`, and
|
|
109
|
+
an `error` that `isJSONRPCError` accepts.
|
|
110
|
+
- `isJSONRPCInvocation`, `isJSONRPCResponse`, and `isJSONRPCMessage` accept what their arms accept.
|
|
111
|
+
|
|
112
|
+
The following calls show each boundary:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
import {
|
|
116
|
+
isJSONRPCError,
|
|
117
|
+
isJSONRPCErrorResponse,
|
|
118
|
+
isJSONRPCId,
|
|
119
|
+
isJSONRPCNotification,
|
|
120
|
+
isJSONRPCResultResponse,
|
|
121
|
+
} from '@orkestrel/jsonrpc'
|
|
122
|
+
|
|
123
|
+
isJSONRPCId(1.5) // false
|
|
124
|
+
isJSONRPCError({ code: -32601, message: 'Method not found', data: { method: 'ping' } }) // true
|
|
125
|
+
isJSONRPCNotification({ jsonrpc: '2.0', method: 'log', id: undefined }) // false
|
|
126
|
+
isJSONRPCResultResponse({ jsonrpc: '2.0', id: 1, result: null }) // true
|
|
127
|
+
isJSONRPCErrorResponse({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' } }) // false
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Surface
|
|
131
|
+
|
|
132
|
+
### Message types
|
|
133
|
+
|
|
134
|
+
The package provides these message contracts.
|
|
135
|
+
|
|
136
|
+
| Name | Kind | Signature | Summary |
|
|
137
|
+
| ----------------------- | --------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
138
|
+
| `JSONRPCId` | type | `string \| number` | Identifies a JSON-RPC 2.0 request and the response that answers it. |
|
|
139
|
+
| `JSONRPCRequest` | interface | `{ jsonrpc, id, method, params? }` | Describes a JSON-RPC 2.0 method call that requires a response. |
|
|
140
|
+
| `JSONRPCNotification` | interface | `{ jsonrpc, method, id?, params? }` | Describes a JSON-RPC 2.0 method call that permits no response. |
|
|
141
|
+
| `JSONRPCInvocation` | type | `JSONRPCRequest \| JSONRPCNotification` | Describes one inbound JSON-RPC 2.0 call, a request or a notification. |
|
|
142
|
+
| `JSONRPCError` | interface | `{ code, message, data? }` | Describes the error object a JSON-RPC 2.0 error response carries. |
|
|
143
|
+
| `JSONRPCResultResponse` | interface | `{ jsonrpc, id, result, error? }` | Describes a successful JSON-RPC 2.0 response. |
|
|
144
|
+
| `JSONRPCErrorResponse` | interface | `{ jsonrpc, id, error, result? }` | Describes a failed JSON-RPC 2.0 response, with `id` set to `null` when the request's id could not be read. |
|
|
145
|
+
| `JSONRPCResponse` | type | `JSONRPCResultResponse \| JSONRPCErrorResponse` | Describes either outcome of a JSON-RPC 2.0 request. |
|
|
146
|
+
| `JSONRPCMessage` | type | `JSONRPCInvocation \| JSONRPCResponse` | Describes one complete JSON-RPC 2.0 wire message. |
|
|
147
|
+
|
|
148
|
+
### Error codes
|
|
149
|
+
|
|
150
|
+
The package provides these reserved error codes.
|
|
151
|
+
|
|
152
|
+
| Name | Kind | Signature | Summary |
|
|
153
|
+
| -------------------------- | ----- | --------- | ------------------------------------------------------------------------ |
|
|
154
|
+
| `JSONRPC_PARSE_ERROR` | const | `-32700` | Identifies a payload that is not valid JSON, `-32700`. |
|
|
155
|
+
| `JSONRPC_INVALID_REQUEST` | const | `-32600` | Identifies a payload that is not a valid JSON-RPC 2.0 request, `-32600`. |
|
|
156
|
+
| `JSONRPC_METHOD_NOT_FOUND` | const | `-32601` | Identifies a method the receiver does not provide, `-32601`. |
|
|
157
|
+
| `JSONRPC_INVALID_PARAMS` | const | `-32602` | Identifies invalid method parameters, `-32602`. |
|
|
158
|
+
| `JSONRPC_INTERNAL_ERROR` | const | `-32603` | Identifies an internal receiver failure, `-32603`. |
|
|
159
|
+
|
|
160
|
+
### Guards
|
|
161
|
+
|
|
162
|
+
The package provides these guards.
|
|
163
|
+
|
|
164
|
+
| Name | Kind | Signature | Summary |
|
|
165
|
+
| ------------------------- | -------- | ---------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
166
|
+
| `isJSONRPCId` | function | `(value: unknown) => value is JSONRPCId` | Checks whether a value is a JSON-RPC 2.0 id, a string or a finite integer. |
|
|
167
|
+
| `isJSONRPCError` | function | `(value: unknown) => value is JSONRPCError` | Checks whether a value is a JSON-RPC 2.0 error object. |
|
|
168
|
+
| `isJSONRPCRequest` | function | `(value: unknown) => value is JSONRPCRequest` | Checks whether a value is a JSON-RPC 2.0 request. |
|
|
169
|
+
| `isJSONRPCNotification` | function | `(value: unknown) => value is JSONRPCNotification` | Checks whether a value is a JSON-RPC 2.0 notification. |
|
|
170
|
+
| `isJSONRPCInvocation` | function | `(value: unknown) => value is JSONRPCInvocation` | Checks whether a value is a JSON-RPC 2.0 request or notification. |
|
|
171
|
+
| `isJSONRPCResultResponse` | function | `(value: unknown) => value is JSONRPCResultResponse` | Checks whether a value is a successful JSON-RPC 2.0 response. |
|
|
172
|
+
| `isJSONRPCErrorResponse` | function | `(value: unknown) => value is JSONRPCErrorResponse` | Checks whether a value is a failed JSON-RPC 2.0 response. |
|
|
173
|
+
| `isJSONRPCResponse` | function | `(value: unknown) => value is JSONRPCResponse` | Checks whether a value is a JSON-RPC 2.0 response. |
|
|
174
|
+
| `isJSONRPCMessage` | function | `(value: unknown) => value is JSONRPCMessage` | Checks whether a value is a JSON-RPC 2.0 message. |
|
|
175
|
+
|
|
176
|
+
### Builders
|
|
177
|
+
|
|
178
|
+
The package provides these response builders.
|
|
179
|
+
|
|
180
|
+
| Name | Kind | Signature | Summary |
|
|
181
|
+
| -------------------- | -------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
|
|
182
|
+
| `buildJSONRPCResult` | function | `(id: JSONRPCId, result: unknown) => JSONRPCResultResponse` | Builds a successful JSON-RPC 2.0 response that echoes the request's id. |
|
|
183
|
+
| `buildJSONRPCError` | function | `(id: JSONRPCId \| null, code: number, message: string, data?: unknown) => JSONRPCErrorResponse` | Builds a failed JSON-RPC 2.0 response, omitting `data` when it is absent. |
|
|
184
|
+
|
|
185
|
+
## Tests
|
|
186
|
+
|
|
187
|
+
[`tests/src/core`](../tests/src/core) proves the guards, the builders, and the barrel.
|