@orkestrel/scaffold 0.0.114 → 0.0.116
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 +137 -15
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -3
- package/dist/host/agents/platforms/windows.md +1 -0
- package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +9 -3
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/astra.md +2 -2
- package/dist/host/claude/agents/builder.md +4 -4
- package/dist/host/claude/agents/opus.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +5 -7
- package/dist/host/claude/agents/planner.md +8 -2
- package/dist/host/claude/rules/campaign.md +2 -1
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/names.md +3 -1
- package/dist/host/claude/rules/tests.md +7 -4
- package/dist/host/claude/rules/writing.md +1 -0
- package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +8 -5
- package/dist/host/codex/agents/astra.toml +4 -5
- package/dist/host/codex/agents/builder.toml +5 -5
- package/dist/host/codex/agents/opus.toml +3 -4
- package/dist/host/codex/agents/orkestrel.toml +2 -1
- package/dist/host/codex/agents/planner.toml +8 -5
- package/dist/host/codex/agents/reviewer.toml +5 -4
- 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 +361 -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 +554 -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 +93 -93
- package/dist/host/tests/setupPolicy.ts +5 -3
- package/dist/src/core/index.cjs +89 -3
- 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 +87 -4
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +292 -66
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +188 -6
- package/dist/src/server/index.d.ts +188 -6
- package/dist/src/server/index.js +287 -69
- package/dist/src/server/index.js.map +1 -1
- package/package.json +4 -3
|
@@ -73,41 +73,41 @@ produces the JSON Schema, and seeds fixtures.
|
|
|
73
73
|
|
|
74
74
|
### Factories
|
|
75
75
|
|
|
76
|
-
|
|
|
77
|
-
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
78
|
-
| `createDatabase` | function | Creates a database over a driver and a declared `tables` schema. |
|
|
79
|
-
| `createMemoryDriver` | function | Creates the in-memory reference `DriverInterface`. |
|
|
80
|
-
| `createJSONDriver` | function | Creates a persistent JSON-file `DriverInterface` for a given path. |
|
|
81
|
-
| `createSQLiteDriver` | function | Creates a trusted-mode, server-native SQLite `DriverInterface` for a database path, or for `:memory:` when the options bag omits one. |
|
|
82
|
-
| `createIndexedDBDriver` | function | Creates a persistent IndexedDB `DriverInterface` for a browser database name. |
|
|
76
|
+
| Name | Kind | Signature | Summary |
|
|
77
|
+
| ----------------------- | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
78
|
+
| `createDatabase` | function | `<const T extends TableMap>(options: DatabaseOptions<T>) => DatabaseInterface<T>` | Creates a database over a driver and a declared `tables` schema. |
|
|
79
|
+
| `createMemoryDriver` | function | `() => DriverInterface` | Creates the in-memory reference `DriverInterface`. |
|
|
80
|
+
| `createJSONDriver` | function | `(path: string) => DriverInterface` | Creates a persistent JSON-file `DriverInterface` for a given path. |
|
|
81
|
+
| `createSQLiteDriver` | function | `(options?: SQLiteDriverOptions) => DriverInterface` | Creates a trusted-mode, server-native SQLite `DriverInterface` for a database path, or for `:memory:` when the options bag omits one. |
|
|
82
|
+
| `createIndexedDBDriver` | function | `(name: string) => DriverInterface` | Creates a persistent IndexedDB `DriverInterface` for a browser database name. |
|
|
83
83
|
|
|
84
84
|
### Classes
|
|
85
85
|
|
|
86
|
-
|
|
|
87
|
-
| ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
88
|
-
| `Database` | class | Exposes a typed view over one shared internal lifecycle and storage context. |
|
|
89
|
-
| `DriverIterator` | class | Forms the internal continuation boundary for a root driver async iterator. |
|
|
90
|
-
| `MemoryDriver` | class | Implements the reference `DriverInterface` — nested maps, no I/O. |
|
|
91
|
-
| `JSONDriver` | class | Implements a persistent `DriverInterface` backed by a single JSON file — the reference `MemoryDriver` plus file load / flush. |
|
|
92
|
-
| `SQLiteDriver` | class | Implements the `DriverInterface` over SQLite — the server-native, trusted-mode backend built on the published `@orkestrel/sqlite` synchronous wrapper. |
|
|
93
|
-
| `IndexedDBDriver` | class | Implements the `DriverInterface` over IndexedDB — the persistent browser backend, built on the published `@orkestrel/indexeddb` wrapper. |
|
|
94
|
-
| `StreamPage` | class | Tracks the matching-row position of one streaming page. |
|
|
95
|
-
| `JSONTransaction` | class | Owns the isolated memory store and schema of one JSON transaction. |
|
|
96
|
-
| `SQLiteTransaction` | class | Owns the candidate schema and table identities of one SQLite transaction. |
|
|
86
|
+
| Name | Kind | Signature | Summary |
|
|
87
|
+
| ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
88
|
+
| `Database` | class | `new <T extends TableMap = TableMap>(options: DatabaseOptions<T>) => DatabaseInterface<T>` | Exposes a typed view over one shared internal lifecycle and storage context. |
|
|
89
|
+
| `DriverIterator` | class | `new <T>(source: AsyncIterator<T>, guard: () => void) => AsyncIterableIterator<T>` | Forms the internal continuation boundary for a root driver async iterator. |
|
|
90
|
+
| `MemoryDriver` | class | `new () => DriverInterface` | Implements the reference `DriverInterface` — nested maps, no I/O. |
|
|
91
|
+
| `JSONDriver` | class | `new (path: string) => DriverInterface` | Implements a persistent `DriverInterface` backed by a single JSON file — the reference `MemoryDriver` plus file load / flush. |
|
|
92
|
+
| `SQLiteDriver` | class | `new (options?: SQLiteDriverOptions) => DriverInterface` | Implements the `DriverInterface` over SQLite — the server-native, trusted-mode backend built on the published `@orkestrel/sqlite` synchronous wrapper. |
|
|
93
|
+
| `IndexedDBDriver` | class | `new (name: string) => DriverInterface` | Implements the `DriverInterface` over IndexedDB — the persistent browser backend, built on the published `@orkestrel/indexeddb` wrapper. |
|
|
94
|
+
| `StreamPage` | class | `new (offset: number) => StreamPage` | Tracks the matching-row position of one streaming page. |
|
|
95
|
+
| `JSONTransaction` | class | `new (memory: MemoryDriver, schema: readonly TableSchema[], identities: ReadonlyMap<string, object>) => JSONTransaction` | Owns the isolated memory store and schema of one JSON transaction. |
|
|
96
|
+
| `SQLiteTransaction` | class | `new (schema: ReadonlyMap<string, TableSchema>, identities: ReadonlyMap<string, object>) => SQLiteTransaction` | Owns the candidate schema and table identities of one SQLite transaction. |
|
|
97
97
|
|
|
98
98
|
### Server
|
|
99
99
|
|
|
100
|
-
|
|
|
101
|
-
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
102
|
-
| `METADATA_TABLE` | const | Names the reserved metadata table the `SQLiteDriver` creates on `open` to persist its stamped `DriverMetadata` (`version` + declared schema JSON) — the SQLite realization of the `metadata` / `stamp` driver hooks. |
|
|
103
|
-
| `matchesConditionExactly` | function | Reports whether one `Condition` compiles to SQL that is provably identical to the core engine's `matchesCondition` for every value its column's declared type can store. |
|
|
104
|
-
| `matchesOrderExactly` | function | Reports whether one `Order` term's column compiles to an `ORDER BY` that matches the engine's `sortRows` exactly. |
|
|
105
|
-
| `matchesQueryExactly` | function | Reports whether a whole `QueryInput` is exact — every condition and every order term is exact. `limit` / `offset` never affect exactness (SQL `LIMIT` / `OFFSET` are always engine-identical). |
|
|
106
|
-
| `matchesDeclaredStorage` | function | Reports whether a value's runtime type matches a column's declared exact type — the operand side of the declared-type-trust proof. |
|
|
107
|
-
| `EXACT_COLUMN_STORAGE` | const | Lists the declared `ColumnStorage`s whose SQL equality comparisons (`equals` / `not` / `any` / `none`) and `starts` / `ends` compiles are provably engine-exact under declared-type trust — `text` / `integer` / `real` / `boolean`; a `json` or `blob` column always refines instead. |
|
|
108
|
-
| `EXACT_RANGE_COLUMN_STORAGE` | const | Lists the declared `ColumnStorage`s whose SQL range comparisons (`above` / `below` / `from` / `to` / `between`) and `ORDER BY` compiles are provably engine-exact — `integer` / `real` / `boolean` only. `text` is excluded: see `EXACT_COLUMN_STORAGE`'s remarks for the BINARY-collation (code-point) vs. JS `<` (code-unit) divergence on supplementary-plane characters. |
|
|
109
|
-
| `extractValues` | function | Extracts a stored row's values in a declared positional order. |
|
|
110
|
-
| `deriveSQLiteIndexName` | function | Builds a collision-free SQL index name for a table + column-group index — shared by the compiler module's `schemaToIndexes` and `stepToSQL`, so a plan-built index name always matches one `open` would have created. |
|
|
100
|
+
| Name | Kind | Signature | Summary |
|
|
101
|
+
| ---------------------------- | -------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
102
|
+
| `METADATA_TABLE` | const | `"_metadata"` | Names the reserved metadata table the `SQLiteDriver` creates on `open` to persist its stamped `DriverMetadata` (`version` + declared schema JSON) — the SQLite realization of the `metadata` / `stamp` driver hooks. |
|
|
103
|
+
| `matchesConditionExactly` | function | `(condition: Condition, schema: TableSchema) => boolean` | Reports whether one `Condition` compiles to SQL that is provably identical to the core engine's `matchesCondition` for every value its column's declared type can store. |
|
|
104
|
+
| `matchesOrderExactly` | function | `(order: Order, schema: TableSchema) => boolean` | Reports whether one `Order` term's column compiles to an `ORDER BY` that matches the engine's `sortRows` exactly. |
|
|
105
|
+
| `matchesQueryExactly` | function | `(input: QueryInput, schema: TableSchema) => boolean` | Reports whether a whole `QueryInput` is exact — every condition and every order term is exact. `limit` / `offset` never affect exactness (SQL `LIMIT` / `OFFSET` are always engine-identical). |
|
|
106
|
+
| `matchesDeclaredStorage` | function | `(value: unknown, storage: ColumnStorage) => boolean` | Reports whether a value's runtime type matches a column's declared exact type — the operand side of the declared-type-trust proof. |
|
|
107
|
+
| `EXACT_COLUMN_STORAGE` | const | `readonly ColumnStorage[]` | Lists the declared `ColumnStorage`s whose SQL equality comparisons (`equals` / `not` / `any` / `none`) and `starts` / `ends` compiles are provably engine-exact under declared-type trust — `text` / `integer` / `real` / `boolean`; a `json` or `blob` column always refines instead. |
|
|
108
|
+
| `EXACT_RANGE_COLUMN_STORAGE` | const | `readonly ColumnStorage[]` | Lists the declared `ColumnStorage`s whose SQL range comparisons (`above` / `below` / `from` / `to` / `between`) and `ORDER BY` compiles are provably engine-exact — `integer` / `real` / `boolean` only. `text` is excluded: see `EXACT_COLUMN_STORAGE`'s remarks for the BINARY-collation (code-point) vs. JS `<` (code-unit) divergence on supplementary-plane characters. |
|
|
109
|
+
| `extractValues` | function | `(row: SQLiteRow, names: readonly string[], table: string) => readonly SQLiteValue[]` | Extracts a stored row's values in a declared positional order. |
|
|
110
|
+
| `deriveSQLiteIndexName` | function | `(table: string, columns: readonly string[]) => string` | Builds a collision-free SQL index name for a table + column-group index — shared by the compiler module's `schemaToIndexes` and `stepToSQL`, so a plan-built index name always matches one `open` would have created. |
|
|
111
111
|
|
|
112
112
|
### SQL compilation
|
|
113
113
|
|
|
@@ -115,30 +115,30 @@ Pure, server-only functions that turn a core `QueryInput` / `TableSchema` into
|
|
|
115
115
|
parameterized SQL text — the native-query payoff for a SQLite-backed driver.
|
|
116
116
|
None of these import a SQLite package; they speak strings and values only.
|
|
117
117
|
|
|
118
|
-
|
|
|
119
|
-
| ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
120
|
-
| `inferValueStorage` | function | Reads the storage type a nested (`json_extract`) operand encodes as from its runtime value, never as `json`. |
|
|
121
|
-
| `compileJSONTypeSQL` | function | Compiles a nested `FieldPath` to the `json_type(<col>, <path>)` SQL expression — the `compileFieldSQL` `json_extract` sibling used to tell a present JSON `null` apart from an absent path (both read back as SQL `NULL` through `json_extract`, but `json_type` reports `'null'` for the former and SQL `NULL` for the latter). |
|
|
122
|
-
| `compileConditionSQL` | function | Compiles one condition to its `<column> <operator>` SQL fragment and the parameters it binds — engine-exact under SQL's three-valued NULL logic. |
|
|
123
|
-
| `compileWhereSQL` | function | Folds the conditions into one WHERE clause, parenthesizing progressively left-to-right so the grouping matches the engine's `matchesQuery` fold. |
|
|
124
|
-
| `compileOrderSQL` | function | Compiles the ORDER BY clause from the order terms, always ending with the primary key as the final determinant. |
|
|
125
|
-
| `compilePageSQL` | function | Compiles the LIMIT / OFFSET clause. |
|
|
126
|
-
| `compileQuerySQL` | function | Compiles a `QueryInput` into the SQL clause that follows a table name, with its bound parameters in clause order. |
|
|
127
|
-
| `quoteIdentifier` | function | Quotes a SQL identifier (a table or column name) so any characters are literal. |
|
|
128
|
-
| `compileFieldSQL` | function | Compiles a `FieldPath` to the SQL expression that reads it. |
|
|
129
|
-
| `compileColumnSQL` | function | Maps a portable `ColumnStorage` to its SQLite column type. |
|
|
130
|
-
| `compileAggregateSQL` | function | Compiles an `AggregateOperation` over a `FieldPath`. |
|
|
131
|
-
| `matchesAggregateExactly` | function | Reports whether SQLite can execute an aggregate exactly like the core engine. |
|
|
132
|
-
| `matchesSQLiteAffinity` | function | Checks a declared SQLite type against a portable storage affinity. |
|
|
133
|
-
| `matchesAbsentPath` | function | Reports whether a caught filesystem error says that nothing is there to read. |
|
|
134
|
-
| `encodeValue` | function | Encodes a JS value to its stored `SQLiteValue` for a declared column. |
|
|
135
|
-
| `decodeValue` | function | Decodes a stored `SQLiteValue` back to its JS value for a declared column — the exact inverse of `encodeValue`. |
|
|
136
|
-
| `encodeRow` | function | Encodes a whole `Row` to a `SQLiteRow` by its table's schema. |
|
|
137
|
-
| `decodeRow` | function | Decodes a stored `SQLiteRow` back to a `Row` by its table's schema. |
|
|
138
|
-
| `schemaToTable` | function | Projects a `TableSchema` to its `CREATE TABLE IF NOT EXISTS` statement. |
|
|
139
|
-
| `schemaToIndexes` | function | Projects a `TableSchema` to its declared SQLite indexes. |
|
|
140
|
-
| `stepToSQL` | function | Projects one `MigrationStep` to SQLite DDL. |
|
|
141
|
-
| `compileBoundSQL` | function | Encodes condition operands for a SQL fragment using their declared or inferred storage. |
|
|
118
|
+
| Name | Kind | Signature | Summary |
|
|
119
|
+
| ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
120
|
+
| `inferValueStorage` | function | `(value: unknown) => ColumnStorage` | Reads the storage type a nested (`json_extract`) operand encodes as from its runtime value, never as `json`. |
|
|
121
|
+
| `compileJSONTypeSQL` | function | `(path: readonly string[]) => string` | Compiles a nested `FieldPath` to the `json_type(<col>, <path>)` SQL expression — the `compileFieldSQL` `json_extract` sibling used to tell a present JSON `null` apart from an absent path (both read back as SQL `NULL` through `json_extract`, but `json_type` reports `'null'` for the former and SQL `NULL` for the latter). |
|
|
122
|
+
| `compileConditionSQL` | function | `(condition: Condition, schema: TableSchema) => CompiledSQL` | Compiles one condition to its `<column> <operator>` SQL fragment and the parameters it binds — engine-exact under SQL's three-valued NULL logic. |
|
|
123
|
+
| `compileWhereSQL` | function | `(conditions: readonly Condition[], schema: TableSchema) => CompiledSQL` | Folds the conditions into one WHERE clause, parenthesizing progressively left-to-right so the grouping matches the engine's `matchesQuery` fold. |
|
|
124
|
+
| `compileOrderSQL` | function | `(order: readonly Order[] \| undefined, schema: TableSchema) => string` | Compiles the ORDER BY clause from the order terms, always ending with the primary key as the final determinant. |
|
|
125
|
+
| `compilePageSQL` | function | `(limit: number \| undefined, offset: number \| undefined) => CompiledSQL` | Compiles the LIMIT / OFFSET clause. |
|
|
126
|
+
| `compileQuerySQL` | function | `(input: QueryInput \| undefined, schema: TableSchema) => CompiledSQL` | Compiles a `QueryInput` into the SQL clause that follows a table name, with its bound parameters in clause order. |
|
|
127
|
+
| `quoteIdentifier` | function | `(identifier: string) => string` | Quotes a SQL identifier (a table or column name) so any characters are literal. |
|
|
128
|
+
| `compileFieldSQL` | function | `(path: FieldPath) => string` | Compiles a `FieldPath` to the SQL expression that reads it. |
|
|
129
|
+
| `compileColumnSQL` | function | `(storage: ColumnStorage) => string` | Maps a portable `ColumnStorage` to its SQLite column type. |
|
|
130
|
+
| `compileAggregateSQL` | function | `(operation: AggregateOperation, column: FieldPath) => string` | Compiles an `AggregateOperation` over a `FieldPath`. |
|
|
131
|
+
| `matchesAggregateExactly` | function | `(operation: AggregateOperation, column: FieldPath, schema: TableSchema) => boolean` | Reports whether SQLite can execute an aggregate exactly like the core engine. |
|
|
132
|
+
| `matchesSQLiteAffinity` | function | `(declared: unknown, storage: ColumnStorage) => boolean` | Checks a declared SQLite type against a portable storage affinity. |
|
|
133
|
+
| `matchesAbsentPath` | function | `(error: unknown) => boolean` | Reports whether a caught filesystem error says that nothing is there to read. |
|
|
134
|
+
| `encodeValue` | function | `(value: unknown, column: ColumnSchema) => SQLiteValue` | Encodes a JS value to its stored `SQLiteValue` for a declared column. |
|
|
135
|
+
| `decodeValue` | function | `(value: SQLiteValue, column: ColumnSchema) => unknown` | Decodes a stored `SQLiteValue` back to its JS value for a declared column — the exact inverse of `encodeValue`. |
|
|
136
|
+
| `encodeRow` | function | `(row: Row, schema: TableSchema) => SQLiteRow` | Encodes a whole `Row` to a `SQLiteRow` by its table's schema. |
|
|
137
|
+
| `decodeRow` | function | `(row: SQLiteRow, schema: TableSchema) => Row` | Decodes a stored `SQLiteRow` back to a `Row` by its table's schema. |
|
|
138
|
+
| `schemaToTable` | function | `(schema: TableSchema) => string` | Projects a `TableSchema` to its `CREATE TABLE IF NOT EXISTS` statement. |
|
|
139
|
+
| `schemaToIndexes` | function | `(schema: TableSchema) => readonly string[]` | Projects a `TableSchema` to its declared SQLite indexes. |
|
|
140
|
+
| `stepToSQL` | function | `(step: MigrationStep) => readonly string[]` | Projects one `MigrationStep` to SQLite DDL. |
|
|
141
|
+
| `compileBoundSQL` | function | `(sql: string, values: readonly unknown[], nested: boolean, declared: ColumnSchema \| undefined) => CompiledSQL` | Encodes condition operands for a SQL fragment using their declared or inferred storage. |
|
|
142
142
|
|
|
143
143
|
### Browser
|
|
144
144
|
|
|
@@ -146,23 +146,23 @@ Pure functions behind the IndexedDB driver's key-range pushdown planner — a
|
|
|
146
146
|
candidate superset the core engine then refines to the exact result, never
|
|
147
147
|
lossy.
|
|
148
148
|
|
|
149
|
-
|
|
|
150
|
-
| -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
151
|
-
| `selectPlan` | function | Plans an IndexedDB read for a `QueryInput` — picks the index (or the primary store) and `IDBKeyRange` to narrow by, falling back to a full scan. |
|
|
152
|
-
| `conditionToRange` | function | Translates one `Condition` to the `IDBKeyRange` it maps to, when its operator is one of the exact key comparisons over scalar operands; otherwise returns `undefined`. |
|
|
153
|
-
| `INDEXABLE_STORAGE` | const | Lists the declared `ColumnStorage`s that are valid, orderable IndexedDB keys. |
|
|
154
|
-
| `METADATA_STORE` | const | Names the reserved out-of-line store `__metadata__` the `IndexedDBDriver` stamps its `DriverMetadata` into. |
|
|
155
|
-
| `mapIndexedDBError` | function | Maps a backend `IndexedDBError` to the portable `DatabaseError` taxonomy — the default mapping used everywhere except inside `migrate()`. |
|
|
156
|
-
| `mapMigrationError` | function | Maps a backend `IndexedDBError` to the portable `DatabaseError` taxonomy for use inside `migrate()` — the one context where `UPGRADE` means the migration itself failed, not a generic driver fault. |
|
|
157
|
-
| `deriveIndexedDBIndexName` | function | Derives an IndexedDB index name for a declared column group — a bare column name for a single-column index, a deterministic collision-free encoding for a compound one. |
|
|
158
|
-
| `schemaToStore` | function | Projects a table schema into the IndexedDB wrapper's store definition. |
|
|
149
|
+
| Name | Kind | Signature | Summary |
|
|
150
|
+
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
151
|
+
| `selectPlan` | function | `(input: QueryInput \| undefined, schema: TableSchema, available: readonly string[]) => QueryPlan` | Plans an IndexedDB read for a `QueryInput` — picks the index (or the primary store) and `IDBKeyRange` to narrow by, falling back to a full scan. |
|
|
152
|
+
| `conditionToRange` | function | `(condition: Condition) => IDBKeyRange \| undefined` | Translates one `Condition` to the `IDBKeyRange` it maps to, when its operator is one of the exact key comparisons over scalar operands; otherwise returns `undefined`. |
|
|
153
|
+
| `INDEXABLE_STORAGE` | const | `readonly ColumnStorage[]` | Lists the declared `ColumnStorage`s that are valid, orderable IndexedDB keys. |
|
|
154
|
+
| `METADATA_STORE` | const | `"__metadata__"` | Names the reserved out-of-line store `__metadata__` the `IndexedDBDriver` stamps its `DriverMetadata` into. |
|
|
155
|
+
| `mapIndexedDBError` | function | `(error: IndexedDBError) => DatabaseError` | Maps a backend `IndexedDBError` to the portable `DatabaseError` taxonomy — the default mapping used everywhere except inside `migrate()`. |
|
|
156
|
+
| `mapMigrationError` | function | `(error: IndexedDBError) => DatabaseError` | Maps a backend `IndexedDBError` to the portable `DatabaseError` taxonomy for use inside `migrate()` — the one context where `UPGRADE` means the migration itself failed, not a generic driver fault. |
|
|
157
|
+
| `deriveIndexedDBIndexName` | function | `(columns: readonly string[]) => string` | Derives an IndexedDB index name for a declared column group — a bare column name for a single-column index, a deterministic collision-free encoding for a compound one. |
|
|
158
|
+
| `schemaToStore` | function | `(schema: TableSchema) => StoreDefinition` | Projects a table schema into the IndexedDB wrapper's store definition. |
|
|
159
159
|
|
|
160
160
|
### Errors
|
|
161
161
|
|
|
162
|
-
|
|
|
163
|
-
| ----------------- | -------- | ----------------------------------------------------- |
|
|
164
|
-
| `DatabaseError` | class | Represents an error thrown by the database layer. |
|
|
165
|
-
| `isDatabaseError` | function | Narrows an unknown caught value to a `DatabaseError`. |
|
|
162
|
+
| Name | Kind | Signature | Summary |
|
|
163
|
+
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
164
|
+
| `DatabaseError` | class | `new (code: DatabaseErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => DatabaseError` | Represents an error thrown by the database layer. |
|
|
165
|
+
| `isDatabaseError` | function | `(value: unknown) => value is DatabaseError` | Narrows an unknown caught value to a `DatabaseError`. |
|
|
166
166
|
|
|
167
167
|
The constructor installs an own, non-enumerable, non-writable
|
|
168
168
|
`Symbol.for('@orkestrel/database.DatabaseError')` property whose value is the
|
|
@@ -176,24 +176,24 @@ and plain objects carrying only the brand.
|
|
|
176
176
|
The portable semantics every backend shares — pure, total functions the
|
|
177
177
|
driver never re-implements.
|
|
178
178
|
|
|
179
|
-
|
|
|
180
|
-
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
181
|
-
| `compareValues` | function | Compares two arbitrary values under one total order — the comparator behind sorting and the range operators. |
|
|
182
|
-
| `matchesCondition` | function | Evaluates one `Condition` against a row — the per-operator predicate. |
|
|
183
|
-
| `matchesQuery` | function | Folds a row through a list of conditions, joining each by its connector. |
|
|
184
|
-
| `sortRows` | function | Sorts rows by an ordering specification, leaving the input untouched. |
|
|
185
|
-
| `applyQuery` | function | Applies a `QueryInput` to rows — filter, then sort, then page. |
|
|
186
|
-
| `validatePage` | function | Validates the paging fields of a portable query. |
|
|
187
|
-
| `computeAggregate` | function | Computes an aggregate over a column across rows. |
|
|
188
|
-
| `extractKey` | function | Reads a row's primary key from a column, when it is a usable `Key`. |
|
|
189
|
-
| `bindRowKey` | function | Returns a fresh row whose primary column is authoritatively bound to its storage key. |
|
|
190
|
-
| `shapeToColumnSchema` | function | Projects one contract shape into a portable column schema. |
|
|
191
|
-
| `findColumn` | function | Reads one flat column's declaration out of a table schema. |
|
|
192
|
-
| `resolvePrimary` | function | Resolves the primary-key column one table keys its rows by. |
|
|
193
|
-
| `requireColumns` | function | Requires one declared table's columns out of a table map. |
|
|
194
|
-
| `shapeToColumnStorage` | function | Maps a column's `ContractShape` to its portable `ColumnStorage` — the value a `TableSchema` carries so a native backend can declare a real column. |
|
|
195
|
-
| `filterRows` | function | Filters rows by a list of conditions — the shared basis for a table's count and aggregate paths (no sort/page, unlike `applyQuery`). |
|
|
196
|
-
| `equalsValue` | function | Compares two values structurally by SameValueZero leaves — the comparator behind conformance checks and any test/fixture that needs "same data", not "same reference". |
|
|
179
|
+
| Name | Kind | Signature | Summary |
|
|
180
|
+
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
181
|
+
| `compareValues` | function | `(left: unknown, right: unknown) => number` | Compares two arbitrary values under one total order — the comparator behind sorting and the range operators. |
|
|
182
|
+
| `matchesCondition` | function | `(row: Row, condition: Condition) => boolean` | Evaluates one `Condition` against a row — the per-operator predicate. |
|
|
183
|
+
| `matchesQuery` | function | `(row: Row, conditions: readonly Condition[]) => boolean` | Folds a row through a list of conditions, joining each by its connector. |
|
|
184
|
+
| `sortRows` | function | `(rows: readonly Row[], order: readonly Order[]) => readonly Row[]` | Sorts rows by an ordering specification, leaving the input untouched. |
|
|
185
|
+
| `applyQuery` | function | `(rows: readonly Row[], input?: QueryInput) => readonly Row[]` | Applies a `QueryInput` to rows — filter, then sort, then page. |
|
|
186
|
+
| `validatePage` | function | `(input?: QueryInput) => void` | Validates the paging fields of a portable query. |
|
|
187
|
+
| `computeAggregate` | function | `(rows: readonly unknown[], operation: AggregateOperation, column: FieldPath) => number \| undefined` | Computes an aggregate over a column across rows. |
|
|
188
|
+
| `extractKey` | function | `(row: Row, column: string) => Key \| undefined` | Reads a row's primary key from a column, when it is a usable `Key`. |
|
|
189
|
+
| `bindRowKey` | function | `(row: Row, primary: string, key: Key) => Row` | Returns a fresh row whose primary column is authoritatively bound to its storage key. |
|
|
190
|
+
| `shapeToColumnSchema` | function | `(name: string, shape: ContractShape) => ColumnSchema` | Projects one contract shape into a portable column schema. |
|
|
191
|
+
| `findColumn` | function | `(name: string, schema: TableSchema) => ColumnSchema \| undefined` | Reads one flat column's declaration out of a table schema. |
|
|
192
|
+
| `resolvePrimary` | function | `(primary: PrimaryMap, name: string) => string` | Resolves the primary-key column one table keys its rows by. |
|
|
193
|
+
| `requireColumns` | function | `(<T extends TableMap, K extends keyof T & string>(tables: T, name: K) => T[K]) & ((tables: TableMap, name: string) => ColumnMap)` | Requires one declared table's columns out of a table map. |
|
|
194
|
+
| `shapeToColumnStorage` | function | `(shape: ContractShape) => ColumnStorage` | Maps a column's `ContractShape` to its portable `ColumnStorage` — the value a `TableSchema` carries so a native backend can declare a real column. |
|
|
195
|
+
| `filterRows` | function | `(rows: readonly Row[], conditions: readonly Condition[]) => readonly Row[]` | Filters rows by a list of conditions — the shared basis for a table's count and aggregate paths (no sort/page, unlike `applyQuery`). |
|
|
196
|
+
| `equalsValue` | function | `(left: unknown, right: unknown) => boolean` | Compares two values structurally by SameValueZero leaves — the comparator behind conformance checks and any test/fixture that needs "same data", not "same reference". |
|
|
197
197
|
|
|
198
198
|
For `minimum` and `maximum`, `computeAggregate` compares each numeric value
|
|
199
199
|
with a scalar `Math.min` or `Math.max` call. The helper never passes a
|
|
@@ -201,9 +201,9 @@ row-sized argument list.
|
|
|
201
201
|
|
|
202
202
|
### Abort
|
|
203
203
|
|
|
204
|
-
|
|
|
205
|
-
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
206
|
-
| `checkAbort` | function | Throws when an `AbortSignal` has fired — the shared abort gate checked at operation boundaries and between streamed rows. |
|
|
204
|
+
| Name | Kind | Signature | Summary |
|
|
205
|
+
| ------------ | -------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
206
|
+
| `checkAbort` | function | `(signal: AbortSignal \| undefined) => void` | Throws when an `AbortSignal` has fired — the shared abort gate checked at operation boundaries and between streamed rows. |
|
|
207
207
|
|
|
208
208
|
### Migrations
|
|
209
209
|
|
|
@@ -211,52 +211,52 @@ Caller-driven schema migration — a pure structural diff plus a pure row
|
|
|
211
211
|
transform. Versioning drivers persist reconciliation metadata through the paired
|
|
212
212
|
`metadata` / `stamp` hooks.
|
|
213
213
|
|
|
214
|
-
|
|
|
215
|
-
| ------------------------ | -------- | ------------------------------------------------------------------------------- |
|
|
216
|
-
| `planMigration` | function | Diffs a deployed and a declared table set structurally into a `Migration` plan. |
|
|
217
|
-
| `migrateRows` | function | Applies one table's `MigrationStep`s to its rows — a pure row transform. |
|
|
218
|
-
| `projectMigrationSchema` | function | Projects migration steps sequentially over a canonical validated owned schema. |
|
|
219
|
-
| `normalizeDriverSchema` | function | Canonicalizes an unknown driver schema into a distinct deeply frozen snapshot. |
|
|
214
|
+
| Name | Kind | Signature | Summary |
|
|
215
|
+
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
216
|
+
| `planMigration` | function | `(deployed: readonly TableSchema[], declared: readonly TableSchema[], from?: number, to?: number) => Migration` | Diffs a deployed and a declared table set structurally into a `Migration` plan. |
|
|
217
|
+
| `migrateRows` | function | `(rows: readonly Row[], steps: readonly MigrationStep[]) => readonly Row[]` | Applies one table's `MigrationStep`s to its rows — a pure row transform. |
|
|
218
|
+
| `projectMigrationSchema` | function | `(schema: readonly TableSchema[], steps: readonly MigrationStep[]) => readonly TableSchema[]` | Projects migration steps sequentially over a canonical validated owned schema. |
|
|
219
|
+
| `normalizeDriverSchema` | function | `(value: unknown) => readonly TableSchema[]` | Canonicalizes an unknown driver schema into a distinct deeply frozen snapshot. |
|
|
220
220
|
|
|
221
221
|
### Conformance
|
|
222
222
|
|
|
223
|
-
|
|
|
224
|
-
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
225
|
-
| `conformDriver` | function | Runs the driver-conformance battery, throwing on the first violated invariant — the fail-fast entry point most callers (test setup, CI smoke checks) want. |
|
|
226
|
-
| `scanDriver` | function | Walks the driver-conformance battery against a fresh `DriverInterface` per phase, yielding one `ConformanceFinding` per violated invariant — the shared invariant suite every backend (in-memory, SQLite, IndexedDB) must uphold to be a drop-in `DriverInterface`. |
|
|
227
|
-
| `auditDriver` | function | Runs the full driver-conformance battery and collects every violation — the audit entry point for a driver author who wants a complete report rather than a single fail-fast throw. |
|
|
223
|
+
| Name | Kind | Signature | Summary |
|
|
224
|
+
| --------------- | -------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
225
|
+
| `conformDriver` | function | `(factory: () => DriverInterface) => Promise<void>` | Runs the driver-conformance battery, throwing on the first violated invariant — the fail-fast entry point most callers (test setup, CI smoke checks) want. |
|
|
226
|
+
| `scanDriver` | function | `(factory: () => DriverInterface) => AsyncIterable<ConformanceFinding>` | Walks the driver-conformance battery against a fresh `DriverInterface` per phase, yielding one `ConformanceFinding` per violated invariant — the shared invariant suite every backend (in-memory, SQLite, IndexedDB) must uphold to be a drop-in `DriverInterface`. |
|
|
227
|
+
| `auditDriver` | function | `(factory: () => DriverInterface) => Promise<readonly ConformanceFinding[]>` | Runs the full driver-conformance battery and collects every violation — the audit entry point for a driver author who wants a complete report rather than a single fail-fast throw. |
|
|
228
228
|
|
|
229
229
|
### Helpers & guards
|
|
230
230
|
|
|
231
231
|
Pure helpers behind the query engine's pattern matching.
|
|
232
232
|
|
|
233
|
-
|
|
|
234
|
-
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
235
|
-
| `cloneDriverMetadata` | function | Clones unknown driver metadata into a distinct deeply frozen snapshot. |
|
|
236
|
-
| `matchesWildcardPattern` | function | Matches a value against a wildcard pattern in linear time — the shared, ReDoS-safe engine behind `matchesLikePattern` and `matchesGlobPattern`. |
|
|
237
|
-
| `matchesWildcardSegment` | function | Checks whether a fixed-length wildcard segment matches a value at an offset. |
|
|
238
|
-
| `matchesLikePattern` | function | Matches a value against a SQL `LIKE` pattern, folding case. |
|
|
239
|
-
| `matchesGlobPattern` | function | Matches a value against a `GLOB` pattern, preserving case. |
|
|
240
|
-
| `isDriverMetadata` | function | Checks whether a value is persisted driver metadata. |
|
|
241
|
-
| `isDriverSchema` | function | Checks whether a value is a complete portable driver schema. |
|
|
242
|
-
| `isColumnSchema` | function | Checks whether a value is a portable column schema. |
|
|
243
|
-
| `isTableSchema` | function | Checks whether a value is a portable table schema. |
|
|
244
|
-
| `isMigrationStep` | function | Checks whether a value is one ordered migration step. |
|
|
245
|
-
| `isMigration` | function | Checks whether a value is an ordered migration plan. |
|
|
246
|
-
| `isMigrationInput` | function | Checks whether a value is one atomic migration request. |
|
|
247
|
-
| `isKey` | function | Checks whether a value is a usable database key. |
|
|
248
|
-
| `cloneDriverSchema` | function | Clones unknown driver schema into a distinct deeply frozen snapshot. |
|
|
249
|
-
| `cloneMigrationInput` | function | Clones unknown migration input into a distinct deeply frozen snapshot. |
|
|
250
|
-
| `captureFailure` | function | Captures the exact rejection or synchronous throw from a driver conformance operation. |
|
|
233
|
+
| Name | Kind | Signature | Summary |
|
|
234
|
+
| ------------------------ | -------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
235
|
+
| `cloneDriverMetadata` | function | `(value: unknown) => DriverMetadata` | Clones unknown driver metadata into a distinct deeply frozen snapshot. |
|
|
236
|
+
| `matchesWildcardPattern` | function | `(value: string, pattern: string, any: string, single: string, fold: boolean) => boolean` | Matches a value against a wildcard pattern in linear time — the shared, ReDoS-safe engine behind `matchesLikePattern` and `matchesGlobPattern`. |
|
|
237
|
+
| `matchesWildcardSegment` | function | `(value: string, segment: string, at: number, single: string) => boolean` | Checks whether a fixed-length wildcard segment matches a value at an offset. |
|
|
238
|
+
| `matchesLikePattern` | function | `(value: string, pattern: string) => boolean` | Matches a value against a SQL `LIKE` pattern, folding case. |
|
|
239
|
+
| `matchesGlobPattern` | function | `(value: string, pattern: string) => boolean` | Matches a value against a `GLOB` pattern, preserving case. |
|
|
240
|
+
| `isDriverMetadata` | function | `(value: unknown) => value is DriverMetadata` | Checks whether a value is persisted driver metadata. |
|
|
241
|
+
| `isDriverSchema` | function | `(value: unknown) => value is readonly TableSchema[]` | Checks whether a value is a complete portable driver schema. |
|
|
242
|
+
| `isColumnSchema` | function | `(value: unknown) => value is ColumnSchema` | Checks whether a value is a portable column schema. |
|
|
243
|
+
| `isTableSchema` | function | `(value: unknown) => value is TableSchema` | Checks whether a value is a portable table schema. |
|
|
244
|
+
| `isMigrationStep` | function | `(value: unknown) => value is MigrationStep` | Checks whether a value is one ordered migration step. |
|
|
245
|
+
| `isMigration` | function | `(value: unknown) => value is Migration` | Checks whether a value is an ordered migration plan. |
|
|
246
|
+
| `isMigrationInput` | function | `(value: unknown) => value is MigrationInput` | Checks whether a value is one atomic migration request. |
|
|
247
|
+
| `isKey` | function | `(value: unknown) => value is Key` | Checks whether a value is a usable database key. |
|
|
248
|
+
| `cloneDriverSchema` | function | `(value: unknown) => readonly TableSchema[]` | Clones unknown driver schema into a distinct deeply frozen snapshot. |
|
|
249
|
+
| `cloneMigrationInput` | function | `(value: unknown) => MigrationInput` | Clones unknown migration input into a distinct deeply frozen snapshot. |
|
|
250
|
+
| `captureFailure` | function | `(operation: () => Promise<unknown>) => Promise<unknown>` | Captures the exact rejection or synchronous throw from a driver conformance operation. |
|
|
251
251
|
|
|
252
252
|
### Constants
|
|
253
253
|
|
|
254
254
|
A `Shape` cell holds the constant's declared type.
|
|
255
255
|
|
|
256
|
-
|
|
|
256
|
+
| Name | Kind | Signature | Summary |
|
|
257
257
|
| -------------------------- | ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
|
|
258
|
-
| `DEFAULT_PRIMARY` | const | `
|
|
259
|
-
| `MAX_PATTERN_LENGTH` | const | `
|
|
258
|
+
| `DEFAULT_PRIMARY` | const | `"id"` | Supplies the primary-key column, `'id'`, assumed when `PrimaryMap` does not name one. |
|
|
259
|
+
| `MAX_PATTERN_LENGTH` | const | `1024` | Sets the longest `LIKE` / `GLOB` pattern the wildcard matcher accepts, 1024 characters, before rejecting it. |
|
|
260
260
|
| `CONFORMANCE_USERS_SCHEMA` | const | `TableSchema` | Describes the `users` table the driver-conformance battery opens — keyed by the default `id` primary column. |
|
|
261
261
|
| `CONFORMANCE_POSTS_SCHEMA` | const | `TableSchema` | Describes the `posts` table the driver-conformance battery opens — keyed by a non-`id` `slug` primary column. |
|
|
262
262
|
| `CONFORMANCE_SCHEMA` | const | `readonly TableSchema[]` | Holds the fixed `users` and `posts` schema every driver-conformance phase opens. |
|
|
@@ -265,49 +265,49 @@ A `Shape` cell holds the constant's declared type.
|
|
|
265
265
|
|
|
266
266
|
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.
|
|
267
267
|
|
|
268
|
-
|
|
|
269
|
-
| -------------------------- | --------- |
|
|
270
|
-
| `Key` | type | `string \| number`
|
|
271
|
-
| `KeyFunction` | type | `() => Key`
|
|
272
|
-
| `Row` | type | `Record<string, unknown>`
|
|
273
|
-
| `ConditionOperator` | type | `'equals' \| 'not' \| 'above' \| 'below' \| 'from' \| 'to' \| 'between' \| 'like' \| 'glob' \| 'starts' \| 'ends' \| 'any' \| 'none' \| 'absent' \| 'present'`
|
|
274
|
-
| `ConditionConnector` | type | `'and' \| 'or'`
|
|
275
|
-
| `Condition` | interface | `{ column, operator, values, connector }`
|
|
276
|
-
| `OrderDirection` | type | `'ascending' \| 'descending'`
|
|
277
|
-
| `Order` | interface | `{ column, direction }`
|
|
278
|
-
| `QueryInput` | interface | `{ conditions?, order?, limit?, offset? }`
|
|
279
|
-
| `AggregateOperation` | type | `'count' \| 'sum' \| 'average' \| 'minimum' \| 'maximum'`
|
|
280
|
-
| `OperationOptions` | interface | `{ signal? }`
|
|
281
|
-
| `DatabaseStatus` | type | `'idle' \| 'open' \| 'closed'`
|
|
282
|
-
| `AdmissionInterface` | interface | `{ accepting }
|
|
283
|
-
| `DatabaseErrorCode` | type | `'CLOSED' \| 'NOT_FOUND' \| 'CONFLICT' \| 'VALIDATION' \| 'ABORTED' \| 'MIGRATION' \| 'CONFORMANCE' \| 'DRIVER'`
|
|
284
|
-
| `ConformanceFinding` | interface | `{ check, message, context }`
|
|
285
|
-
| `DatabaseEventMap` | type | `{ open
|
|
286
|
-
| `TableEventMap` | type | `{ write
|
|
287
|
-
| `ColumnMap` | type | `Readonly<Record<string, ContractShape>>`
|
|
288
|
-
| `TableMap` | type | `Readonly<Record<string, ColumnMap>>`
|
|
289
|
-
| `RowOf` | type | `Infer<{ category: 'object'; properties: C }>`
|
|
290
|
-
| `PrimaryMap` | type | `Readonly<Record<string, string>>`
|
|
291
|
-
| `IndexMap` | type | `Readonly<Record<string, ReadonlyArray<readonly string[]>>>`
|
|
292
|
-
| `ColumnStorage` | type | `'text' \| 'integer' \| 'real' \| 'boolean' \| 'json' \| 'blob'`
|
|
293
|
-
| `ColumnSchema` | interface | `{ name, storage, optional, nullable }`
|
|
294
|
-
| `TableSchema` | interface | `{ name, primary, columns, indexes }`
|
|
295
|
-
| `MigrationStep` | type | `{ operation: 'table.add'
|
|
296
|
-
| `Migration` | interface | `{ from, to, steps }`
|
|
297
|
-
| `MigrationInput` | interface | `{ plan, metadata? }`
|
|
298
|
-
| `StorageInterface` | interface | `{
|
|
299
|
-
| `DriverMetadata` | interface | `{ version, schema }`
|
|
300
|
-
| `DriverInterface` | interface | `
|
|
301
|
-
| `DatabaseOptions` | interface | `{ on?, error?, driver, tables, primary?, indexes?, name?, generator?, version? }`
|
|
302
|
-
| `CompiledSQL` | interface | `{ sql, parameters }`
|
|
303
|
-
| `SQLiteDriverOptions` | interface | `{ path?, readonly?, timeout?, references?, pragmas? }`
|
|
304
|
-
| `QueryPlan` | interface | `{ index?, range? }`
|
|
305
|
-
| `TableDefinition` | interface | `{ primary, columns, schema }`
|
|
306
|
-
| `DatabaseStorageInterface` | interface | `{
|
|
307
|
-
| `DatabaseInterface` | interface | `{ emitter, name, status
|
|
308
|
-
| `TableInterface` | interface | `{ emitter, name, primary, contract
|
|
309
|
-
| `QueryInterface` | interface | `{
|
|
310
|
-
| `CursorInterface` | interface | `{ value, index, done
|
|
268
|
+
| Name | Kind | Signature | Summary |
|
|
269
|
+
| -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
270
|
+
| `Key` | type | `string \| number` | Represents a primary key — the value identifying a row within its table. |
|
|
271
|
+
| `KeyFunction` | type | `() => Key` | Represents a key-generating function. |
|
|
272
|
+
| `Row` | type | `Record<string, unknown>` | Represents a table row — a plain record of column values keyed by column name. |
|
|
273
|
+
| `ConditionOperator` | type | `'equals' \| 'not' \| 'above' \| 'below' \| 'from' \| 'to' \| 'between' \| 'like' \| 'glob' \| 'starts' \| 'ends' \| 'any' \| 'none' \| 'absent' \| 'present'` | Represents a WHERE operator — the comparison a single `Condition` applies. |
|
|
274
|
+
| `ConditionConnector` | type | `'and' \| 'or'` | Names how a `Condition` joins to the running result of the conditions before it. |
|
|
275
|
+
| `Condition` | interface | `{ column, operator, values, connector }` | Represents one compiled WHERE condition. |
|
|
276
|
+
| `OrderDirection` | type | `'ascending' \| 'descending'` | Names a sort direction. |
|
|
277
|
+
| `Order` | interface | `{ column, direction }` | Represents one ordering term — a column (`FieldPath`, flat or nested) and its direction. |
|
|
278
|
+
| `QueryInput` | interface | `{ conditions?, order?, limit?, offset? }` | Represents a serializable read specification — everything a backend needs to compile one read, free of JS callbacks so any backend can honor it. |
|
|
279
|
+
| `AggregateOperation` | type | `'count' \| 'sum' \| 'average' \| 'minimum' \| 'maximum'` | Names an aggregate computed over a numeric column. |
|
|
280
|
+
| `OperationOptions` | interface | `{ signal? }` | Options for an abortable operation. |
|
|
281
|
+
| `DatabaseStatus` | type | `'idle' \| 'open' \| 'closed'` | Names the lifecycle state of a `DatabaseInterface`. |
|
|
282
|
+
| `AdmissionInterface` | interface | `{ accepting, track() }` | Represents the admission boundary a scoped operation enters before it runs. |
|
|
283
|
+
| `DatabaseErrorCode` | type | `'CLOSED' \| 'NOT_FOUND' \| 'CONFLICT' \| 'VALIDATION' \| 'ABORTED' \| 'MIGRATION' \| 'CONFORMANCE' \| 'DRIVER'` | Names a machine-readable `DatabaseError` code. |
|
|
284
|
+
| `ConformanceFinding` | interface | `{ check, message, context }` | Represents one violated invariant from the driver-conformance battery. |
|
|
285
|
+
| `DatabaseEventMap` | type | `{ readonly open: readonly []; readonly close: readonly []; readonly transaction: readonly []; readonly commit: readonly []; readonly rollback: readonly [error: unknown]; readonly migrate: readonly [migration: Migration]; }` | Describes the push observation surface of a `DatabaseInterface` — the connection + transaction lifecycle a fire-and-forget observer (logging, metrics, tracing, cache invalidation) subscribes to. |
|
|
286
|
+
| `TableEventMap` | type | `{ readonly write: readonly [key: Key]; readonly remove: readonly [key: Key]; readonly clear: readonly []; }` | Describes the push observation surface of a `TableInterface` — the per-row mutation moments a fire-and-forget observer (cache invalidation, sync, an audit log) subscribes to, alongside the database-level `DatabaseEventMap`. |
|
|
287
|
+
| `ColumnMap` | type | `Readonly<Record<string, ContractShape>>` | Represents one table's columns — a map of column name to its value `ContractShape`. |
|
|
288
|
+
| `TableMap` | type | `Readonly<Record<string, ColumnMap>>` | Represents a database's table schema — a map of table name to its `ColumnMap`. |
|
|
289
|
+
| `RowOf` | type | `Infer<{ readonly category: 'object'; readonly properties: C; }>` | Represents the row type a table's `ColumnMap` describe — `Infer` of the `objectShape` the database wraps them in. |
|
|
290
|
+
| `PrimaryMap` | type | `Readonly<Record<string, string>>` | Holds per-table primary-key column overrides — `{ [table]: column }`. |
|
|
291
|
+
| `IndexMap` | type | `Readonly<Record<string, ReadonlyArray<readonly string[]>>>` | Holds per-table secondary indexes — `{ [table]: groups }`, each group one (possibly compound) index of column names. |
|
|
292
|
+
| `ColumnStorage` | type | `'text' \| 'integer' \| 'real' \| 'boolean' \| 'json' \| 'blob'` | Names a portable storage type for a column — the backend maps it to its native type (SQLite affinity, an IndexedDB value). Derived from a column's `ContractShape` by `shapeToColumnStorage`; `json` covers object/array/union/raw values a backend stores as JSON text and can `json_extract` for nested-field queries. |
|
|
293
|
+
| `ColumnSchema` | interface | `{ name, storage, optional, nullable }` | Represents one column of a `TableSchema` — its name, portable `ColumnStorage`, and whether it independently accepts absence (`optional`) and explicit `null` (`nullable`). |
|
|
294
|
+
| `TableSchema` | interface | `{ name, primary, columns, indexes }` | Represents a backend-agnostic description of one table — what `open` hands each driver so a native backend can create real tables and indexes. |
|
|
295
|
+
| `MigrationStep` | type | `{ readonly operation: 'table.add'; readonly table: TableSchema; } \| { readonly operation: 'table.remove'; readonly table: string; } \| { readonly operation: 'column.add'; readonly table: string; readonly column: ColumnSchema; } \| { readonly operation: 'column.remove'; readonly table: string; readonly column: string; } \| { readonly operation: 'index.add'; readonly table: string; readonly index: readonly string[]; } \| { readonly operation: 'index.remove'; readonly table: string; readonly index: readonly string[]; }` | Represents one step of a `Migration` plan — a single schema change applied to one table. |
|
|
296
|
+
| `Migration` | interface | `{ from, to, steps }` | Represents a schema migration plan — an ordered set of `MigrationStep`s moving a database from one schema version to another. |
|
|
297
|
+
| `MigrationInput` | interface | `{ plan, metadata? }` | Represents one atomic migration request. |
|
|
298
|
+
| `StorageInterface` | interface | `{ read(), write(), insert(), delete(), keys(), scan(), clear(), records?(), aggregate?(), stream?(), migrate?(), metadata?(), stamp?() }` | Declares the storage operations available only inside a driver's transaction scope. |
|
|
299
|
+
| `DriverMetadata` | interface | `{ version, schema }` | Represents persisted schema metadata a versioning driver owns as an immutable snapshot. |
|
|
300
|
+
| `DriverInterface` | interface | `{ open(), close(), snapshot(), transaction?() }` | Declares the storage primitive every backend implements — the whole of the bridge. |
|
|
301
|
+
| `DatabaseOptions` | interface | `{ on?, error?, driver, tables, primary?, indexes?, name?, generator?, version? }` | Options for `createDatabase`. |
|
|
302
|
+
| `CompiledSQL` | interface | `{ sql, parameters }` | Represents a parameterized SQL fragment or statement plus its bind values. The `@orkestrel/database/server` entry point exports this type. |
|
|
303
|
+
| `SQLiteDriverOptions` | interface | `{ path?, readonly?, timeout?, references?, pragmas? }` | Configures `createSQLiteDriver`. The `@orkestrel/database/server` entry point exports this type. |
|
|
304
|
+
| `QueryPlan` | interface | `{ index?, range? }` | Represents a pushdown plan — an optional index and optional `IDBKeyRange` used to narrow a read. An omitted `index` selects the primary store; an omitted `range` performs a full scan. The plan is always a superset of the matching rows; the core engine refines it to the exact result. An empty plan (`{}`) is a primary-store full scan. The `@orkestrel/database/browser` entry point exports this type. |
|
|
305
|
+
| `TableDefinition` | interface | `{ primary, columns, schema }` | Represents one table's portable definition, produced by `export` — the unit of schema / migration exchange across environments. |
|
|
306
|
+
| `DatabaseStorageInterface` | interface | `{ table() }` | Represents a database view valid only inside one `DatabaseInterface.transaction` scope. |
|
|
307
|
+
| `DatabaseInterface` | interface | `{ emitter, name, status, table(), import(), export(), open(), close(), transaction(), migrate() }` | Represents a database — the ergonomic entry point that owns the driver and its tables. |
|
|
308
|
+
| `TableInterface` | interface | `{ emitter, name, primary, contract, get(), resolve(), has(), keys(), records(), count(), aggregate(), scan(), set(), add(), update(), remove(), clear(), query(), cursor() }` | Exposes typed keyed CRUD plus fluent query and cursor access. |
|
|
309
|
+
| `QueryInterface` | interface | `{ condition(), order(), filter(), limit(), offset(), collect(), find(), count(), stream(), aggregate() }` | Builds a read through a fluent chain. |
|
|
310
|
+
| `CursorInterface` | interface | `{ value, index, done, next(), update(), remove(), close() }` | Walks a table's rows forward for bulk in-place mutation. |
|
|
311
311
|
|
|
312
312
|
### Operation state
|
|
313
313
|
|