@jarenjs/db 0.49.2 → 0.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/ARCHITECTURE.md +27 -15
  2. package/README.md +141 -41
  3. package/docs/JOBS-FORMAT.md +24 -8
  4. package/docs/LIVE-FORMAT.md +38 -9
  5. package/docs/MIGRATION-FORMAT.md +118 -36
  6. package/docs/MODEL-FORMAT.md +232 -30
  7. package/package.json +4 -5
  8. package/schemas/jaren-migration.draft-07.schema.json +73 -0
  9. package/schemas/jaren-migration.schema.json +73 -0
  10. package/src/capture.js +66 -28
  11. package/src/cli.js +225 -44
  12. package/src/ddl.js +23 -3
  13. package/src/dialects/sqlite.js +2 -1
  14. package/src/driver.js +63 -16
  15. package/src/drivers/wasm.js +1 -0
  16. package/src/emit-model.js +14 -0
  17. package/src/emit.js +10 -3
  18. package/src/entity.js +92 -47
  19. package/src/errors.js +25 -0
  20. package/src/index.js +2 -2
  21. package/src/jobs.js +40 -5
  22. package/src/live-time.js +12 -3
  23. package/src/live.js +11 -1
  24. package/src/migrate.js +397 -191
  25. package/src/model.js +173 -8
  26. package/src/plan.js +135 -38
  27. package/src/query.js +138 -13
  28. package/src/store.js +221 -66
  29. package/src/tracker.js +173 -48
  30. package/types/index.d.ts +152 -10
  31. package/types/node.d.ts +3 -1
  32. package/types/typed.d.ts +58 -2
  33. package/types/wasm.d.ts +7 -0
  34. package/dist/types/algebra.d.ts +0 -230
  35. package/dist/types/app.d.ts +0 -49
  36. package/dist/types/capture.d.ts +0 -85
  37. package/dist/types/cli.d.ts +0 -2
  38. package/dist/types/dag-job.d.ts +0 -40
  39. package/dist/types/ddl.d.ts +0 -229
  40. package/dist/types/derive.d.ts +0 -250
  41. package/dist/types/dialect.d.ts +0 -154
  42. package/dist/types/dialects/sqlite.d.ts +0 -9
  43. package/dist/types/driver.d.ts +0 -110
  44. package/dist/types/drivers/bun.d.ts +0 -47
  45. package/dist/types/drivers/node.d.ts +0 -37
  46. package/dist/types/drivers/wasm.d.ts +0 -65
  47. package/dist/types/emit-model.d.ts +0 -44
  48. package/dist/types/emit.d.ts +0 -75
  49. package/dist/types/entity.d.ts +0 -23
  50. package/dist/types/errors.d.ts +0 -170
  51. package/dist/types/graph.d.ts +0 -28
  52. package/dist/types/index.d.ts +0 -37
  53. package/dist/types/jobs.d.ts +0 -140
  54. package/dist/types/knn.d.ts +0 -69
  55. package/dist/types/live-time.d.ts +0 -141
  56. package/dist/types/live.d.ts +0 -64
  57. package/dist/types/migrate.d.ts +0 -170
  58. package/dist/types/model.d.ts +0 -36
  59. package/dist/types/patch-sql.d.ts +0 -37
  60. package/dist/types/plan.d.ts +0 -142
  61. package/dist/types/profile.d.ts +0 -80
  62. package/dist/types/query.d.ts +0 -112
  63. package/dist/types/residual.d.ts +0 -64
  64. package/dist/types/series.d.ts +0 -227
  65. package/dist/types/store.d.ts +0 -60
  66. package/dist/types/tracker.d.ts +0 -43
  67. package/dist/types/typed.d.ts +0 -15
  68. package/dist/types/types.d.ts +0 -26
  69. package/dist/types/udf.d.ts +0 -75
  70. package/dist/types/window.d.ts +0 -52
@@ -1,229 +0,0 @@
1
- /**
2
- * @file DDL planning: a normalized collection becomes one physical
3
- * table — a key column, a JSON document column, a virtual generated
4
- * column per indexed path, and the declared indexes — with every byte
5
- * of SQL rendered by the dialect.
6
- *
7
- * Index paths are JSONPath expressions analyzed through the engine's
8
- * PUBLISHED AST (`analyzeQuery`): a path is indexable exactly when the
9
- * analysis says it is singular and every segment is a plain member or
10
- * index selection. That reuses the one grammar authority instead of
11
- * re-parsing, and it fails loudly (`JD0004`) on everything else —
12
- * wildcards, slices, filters, descendants, functions — rather than
13
- * silently indexing the wrong thing.
14
- */
15
- /** The fixed physical column names of the 0.1 mapping. */
16
- export declare const KEY_COLUMN = "key";
17
- export declare const DOC_COLUMN = "doc";
18
- /**
19
- * Analyze one index path expression down to typed segments.
20
- * @param {string} expression - A JSONPath expression (`$.email`)
21
- * @param {string} docPath - Model-document pointer for diagnostics
22
- * @returns {{ segments: import('./dialect.js').JsonPathSegment[],
23
- * canonical: string }}
24
- */
25
- export declare function compileIndexPath(expression: string, docPath: string): {
26
- segments: import('./dialect.js').JsonPathSegment[];
27
- canonical: string;
28
- };
29
- /**
30
- * The schema subschema at a segment path, walked structurally through
31
- * `properties` / `items` / `prefixItems`. The collection's schema is
32
- * the type source — that is why the physical mapping needs no
33
- * engine-side inference. `undefined` where the walk leaves the schema.
34
- * @param {any} schema
35
- * @param {import('./dialect.js').JsonPathSegment[]} segments
36
- * @returns {any}
37
- */
38
- export declare function schemaNodeAt(schema: any, segments: import('./dialect.js').JsonPathSegment[]): any;
39
- /**
40
- * The declared schema type at a segment path: the first non-`null`
41
- * member of a union, which is the type a COLUMN takes its storage
42
- * from. A caller that must know the whole union (a promotion refusing
43
- * a member that may also be `null`) reads {@link schemaNodeAt}.
44
- * @param {any} schema
45
- * @param {import('./dialect.js').JsonPathSegment[]} segments
46
- * @returns {string | undefined}
47
- */
48
- export declare function schemaTypeAt(schema: any, segments: import('./dialect.js').JsonPathSegment[]): string | undefined;
49
- /**
50
- * Plan one collection's physical shape: the DDL statements to create
51
- * it and the structural facts an existing table must match (the
52
- * `JD0002` comparison set).
53
- * A derived index (`derive: 'geohash' | 'bbox'`) maps to the same
54
- * shape through a registered deterministic function, EXCEPT where the
55
- * driver cannot index one (`capabilities.deterministicIndexableFunctions`
56
- * is false): there the columns are ordinary ones the store writes. The
57
- * two mappings produce different declared text on purpose — a database
58
- * built under one and opened under the other really does disagree, and
59
- * `verifyShape` says so rather than papering over it. A
60
- * `derive: 'vector'` column is the stored shape under BOTH mappings
61
- * (`derivedMappingFor`), so for it the two agree.
62
- * @param {string} name - The collection name (also the table name)
63
- * @param {{ schema: any, keySegments: { name: string }[] | null,
64
- * identity: string, indexes: { name: string, paths: string[],
65
- * unique: boolean, derive?: string | null, precision?: number,
66
- * dims?: number, docPath: string }[] }} collection - normalized
67
- * @param {any} dialect
68
- * @param {{ derived?: 'virtual' | 'stored', rtree?: boolean }} [options]
69
- * - `derived` is the physical mapping for derived columns:
70
- * `'virtual'` (a generated column over a registered function) unless
71
- * the driver says it cannot index one. `rtree` is whether the driver
72
- * carries the R\*Tree module; when it does not, a column set that
73
- * declared `physical: 'rtree'` falls back to the B-tree over its
74
- * columns and `explain().prefilters[].via` reports which shape ran
75
- * (MODEL-FORMAT §4) — a report, not a silent degradation
76
- * @returns {{
77
- * table: string, keyColumn: string, docColumn: string,
78
- * keyType: string,
79
- * generated: { name: string, type: string, pathText: string,
80
- * canonical: string }[],
81
- * derived: { name: string, derive: string, precision?: number,
82
- * component?: string, dims?: number, segments: any[] }[],
83
- * columnByCanonical: Map<string, string>,
84
- * createSql: string[],
85
- * virtualTables: { stem: string, name: string, columns: string[],
86
- * edges: string[], createSql: string, fillSql: string,
87
- * triggers: { name: string, sql: string }[] }[],
88
- * expected: { columns: { name: string, type: string,
89
- * generated: boolean }[], indexes: { name: string, unique: boolean,
90
- * columns: string[] }[] },
91
- * }}
92
- */
93
- export declare function planCollection(name: string, collection: {
94
- schema: any;
95
- keySegments: {
96
- name: string;
97
- }[] | null;
98
- identity: string;
99
- indexes: {
100
- name: string;
101
- paths: string[];
102
- unique: boolean;
103
- derive?: string | null;
104
- precision?: number;
105
- dims?: number;
106
- docPath: string;
107
- }[];
108
- }, dialect: any, options?: {
109
- derived?: 'virtual' | 'stored';
110
- rtree?: boolean;
111
- }): {
112
- table: string;
113
- keyColumn: string;
114
- docColumn: string;
115
- keyType: string;
116
- generated: {
117
- name: string;
118
- type: string;
119
- pathText: string;
120
- canonical: string;
121
- }[];
122
- derived: {
123
- name: string;
124
- derive: string;
125
- precision?: number;
126
- component?: string;
127
- dims?: number;
128
- segments: any[];
129
- }[];
130
- columnByCanonical: Map<string, string>;
131
- createSql: string[];
132
- virtualTables: {
133
- stem: string;
134
- name: string;
135
- columns: string[];
136
- edges: string[];
137
- createSql: string;
138
- fillSql: string;
139
- triggers: {
140
- name: string;
141
- sql: string;
142
- }[];
143
- }[];
144
- expected: {
145
- columns: {
146
- name: string;
147
- type: string;
148
- generated: boolean;
149
- }[];
150
- indexes: {
151
- name: string;
152
- unique: boolean;
153
- columns: string[];
154
- }[];
155
- };
156
- };
157
- /**
158
- * Normalize a stored `CREATE` statement for comparison: collapse runs of
159
- * whitespace, drop whitespace around punctuation, and strip the
160
- * `IF NOT EXISTS` SQLite does not keep. What survives is every token that
161
- * carries meaning, so two statements compare equal exactly when they
162
- * declare the same physical object.
163
- * @param {string} sql
164
- * @returns {string}
165
- */
166
- export declare function normalizeDeclaredSql(sql: string): string;
167
- /**
168
- * A comparable form of one `CREATE` statement.
169
- *
170
- * For a TABLE the column definitions compare as a SET, because
171
- * `ALTER TABLE … ADD COLUMN` can only append — so a migrated table and a
172
- * freshly built one legitimately differ in column order, and this store
173
- * never reads a column positionally. Everything else is exact: each
174
- * column's full definition (type, `PRIMARY KEY`, `NOT NULL`, `DEFAULT`,
175
- * `CHECK`, `GENERATED … AS`, `REFERENCES … ON DELETE …`), the table
176
- * constraints, and the trailing table options (`STRICT`,
177
- * `WITHOUT ROWID`).
178
- *
179
- * For an INDEX the text compares whole, because an index IS its order —
180
- * `(a,b)` and `(b,a)` serve different lookups — as are its partial
181
- * predicate and each term's collation and direction.
182
- * @param {string} sql
183
- * @returns {string}
184
- */
185
- export declare function comparableDeclaredSql(sql: string): string;
186
- /**
187
- * Verify an existing table against the planned shape; any difference
188
- * is `JD0002` and nothing is altered. Shared by the store's open path
189
- * and the migration engine's shadow validation.
190
- * @param {any} connection
191
- * @param {any} plan
192
- * @param {string} collection
193
- * @param {string} docPath
194
- * @returns {any} value-or-promise
195
- */
196
- export declare function verifyShape(connection: any, plan: any, collection: string, docPath: string): any;
197
- /**
198
- * Plan one ENTITY's physical shape from the mapping data
199
- * `explainMapping` derived: the relational table (typed columns,
200
- * checks, foreign keys, the JSONB document column), its indexes, and
201
- * the structural facts an existing table must match. One verify path
202
- * serves both document kinds.
203
- * @param {string} name
204
- * @param {any} entityMapping - `explainMapping(model).entities[name]`
205
- * @param {any} entities - the full `explainMapping` result (key types
206
- * come from the referenced entity's columns)
207
- * @param {any} dialect
208
- * @returns {{ table: string, createSql: string[], expected: any,
209
- * columnNames: Set<string> }}
210
- */
211
- export declare function planEntity(name: string, entityMapping: any, entities: any, dialect: any): {
212
- table: string;
213
- createSql: string[];
214
- expected: any;
215
- columnNames: Set<string>;
216
- };
217
- /**
218
- * Plan a many-to-many join table.
219
- * @param {string} tableName
220
- * @param {any} join - `explainMapping(model).joinTables[tableName]`
221
- * @param {any} entities - the full mapping
222
- * @param {any} dialect
223
- * @returns {{ table: string, createSql: string[], expected: any }}
224
- */
225
- export declare function planJoinTable(tableName: string, join: any, entities: any, dialect: any): {
226
- table: string;
227
- createSql: string[];
228
- expected: any;
229
- };
@@ -1,250 +0,0 @@
1
- /**
2
- * @file Derived index columns: the one place a declared
3
- * `indexes[].derive` becomes a value. A spatial member is an array of
4
- * numbers or an object, and a generated column must be a scalar, so a
5
- * geohash cell or a bounding-box edge is what actually gets indexed;
6
- * an embedding is an array of hundreds of numbers, and what gets
7
- * stored is its packed, l2-normalized Float32 form.
8
- *
9
- * Every cell and every box comes from `@jarenjs/core/geo`, and every
10
- * normalization and packing from `@jarenjs/core/vector`; nothing here
11
- * computes arithmetic of its own. The spatial functions serve BOTH
12
- * physical mappings — registered as deterministic SQL functions inside
13
- * a virtual generated column's expression where the driver can index
14
- * them, and called directly on the write path where it cannot — so
15
- * the two branches cannot drift into different answers. The vector
16
- * kind has ONE mapping, stored everywhere (`DERIVE_MAPPING`), and
17
- * registers no function at all: a whole array re-derived per row as a
18
- * host call is the cost the spatial work measured at 150×, a stored
19
- * column is readable without any registration, and bun has no
20
- * function API — one mapping is the only way every driver agrees.
21
- *
22
- * It is also this package's ONLY seam onto `@jarenjs/core/geo` (D1 —
23
- * one home for spatial arithmetic, grep-proven by test) and onto
24
- * `@jarenjs/core/vector` (the same rule, one home for vector
25
- * arithmetic): the planner's probe geometry — the box of a literal or
26
- * bound region, the box of a bounded-distance circle, a cell's
27
- * neighbourhood — and the k-nearest plan's probe vector and column
28
- * score are computed by the helpers below rather than by an import of
29
- * their own.
30
- *
31
- * The switches over the kind are EXHAUSTIVE: a kind with no rule
32
- * throws, here and in the dialect, so that adding a kind without
33
- * teaching both is a failure at the first call rather than a bbox
34
- * edge of the first two floats and `jaren_bbox_undefined(...)` SQL.
35
- *
36
- * Determinism is the contract, not a convenience: a value here is a
37
- * pure function of the document bytes. Nothing reads the clock, a
38
- * random source or store state, because an INDEX over a function that
39
- * did would make the database unreadable from a connection whose
40
- * function answered differently — and unreadable, not merely wrong:
41
- * a connection that has not registered the function at all cannot even
42
- * SELECT the table (probed). That hazard is why the mapping is
43
- * capability-gated rather than always-on.
44
- */
45
- /** The closed set of derive kinds. */
46
- export declare const DERIVE_KINDS: Set<string>;
47
- /**
48
- * The per-kind PHYSICAL MAPPING override. A spatial kind takes the
49
- * mapping the driver's capability selects (`null` here); the vector
50
- * kind is `'stored'` on every driver, for the three reasons in the
51
- * file header, and never joins `registerDeriveFunctions`.
52
- * @type {Readonly<Record<string, 'stored' | null>>}
53
- */
54
- export declare const DERIVE_MAPPING: Readonly<Record<string, 'stored' | null>>;
55
- /**
56
- * The physical mapping one derived column takes: the kind's override
57
- * where it has one, the driver's mapping otherwise.
58
- * @param {string} kind
59
- * @param {'virtual' | 'stored'} driverMapping
60
- * @returns {'virtual' | 'stored'}
61
- */
62
- export declare function derivedMappingFor(kind: string, driverMapping: 'virtual' | 'stored'): 'virtual' | 'stored';
63
- /**
64
- * The closed set of PHYSICAL realizations a `derive: 'bbox'` index may
65
- * ask for. `'columns'` is the default and what an absent member means:
66
- * four generated columns under one B-tree. `'rtree'` is the same four
67
- * columns (they stay the box's one definition) beside a SQLite R\*Tree
68
- * virtual table kept in sync by declared triggers, with no B-tree over
69
- * them. The LOGICAL meaning of `derive: 'bbox'` is identical either
70
- * way — same rows, same answers — which is the whole point of naming
71
- * the shape separately from the derivation.
72
- */
73
- export declare const PHYSICAL_KINDS: Set<string>;
74
- /** A bbox index's four columns, in the order they are declared —
75
- * `[west, south, east, north]`, the order the kernel's boxes carry. */
76
- export declare const BBOX_COMPONENTS: readonly string[];
77
- /**
78
- * The order a bbox index COVERS its four columns, which is not the
79
- * order they are declared in: an intersection test reads
80
- * `w <= ? AND e >= ? AND s <= ? AND n >= ?`, so the two longitude
81
- * bounds sit together at the front of the index where a leading-column
82
- * range can use them. `(a,b)` and `(b,a)` are different indexes.
83
- */
84
- export declare const BBOX_INDEX_ORDER: readonly string[];
85
- /** The declared geohash precision range (characters). */
86
- export declare const PRECISION_MIN = 1;
87
- export declare const PRECISION_MAX = 12;
88
- /** The declared vector width range (components). */
89
- export declare const DIMS_MIN = 1;
90
- export declare const DIMS_MAX = 8192;
91
- /**
92
- * The geohash cell of a value at a precision, or null when the value
93
- * carries no bounded position.
94
- * @param {any} value
95
- * @param {number} precision
96
- * @returns {string | null}
97
- */
98
- export declare function deriveGeohash(value: any, precision: number): string | null;
99
- /**
100
- * One edge of a value's bounding box, or null when it has none —
101
- * including the D6 case where a non-finite coordinate refuses the box
102
- * rather than producing one that does not bound its input.
103
- * @param {any} value
104
- * @param {string} component - `'w'`, `'s'`, `'e'` or `'n'`
105
- * @returns {number | null}
106
- */
107
- export declare function deriveBboxEdge(value: any, component: string): number | null;
108
- /**
109
- * The value of a `derive: 'vector'` column for a document member — the
110
- * ONE seam from this package onto `@jarenjs/core/vector`. The member
111
- * round-trips through its stored form first, exactly as the spatial
112
- * kinds do: a `Float32Array` in the document is held as an object and
113
- * a `NaN` as `null`, and the column must be a function of what is
114
- * held, so that a write, a migration backfill and a second open can
115
- * never disagree about one row.
116
- * @param {any} member - the value at the index path, or `undefined`
117
- * @param {number} dims - the declared width
118
- * @returns {Uint8Array | null} `4·dims` bytes, or `null` when the
119
- * member is not a vector of that width
120
- */
121
- export declare function deriveVector(member: any, dims: number): Uint8Array | null;
122
- /**
123
- * A member as the database will hold it. A derived value must be a
124
- * function of the STORED document, not of the object handed to the
125
- * write: JSON has no `NaN` and no `Infinity`, so a non-finite
126
- * coordinate becomes `null` on the way in and is no longer a position
127
- * at all. Computing from the in-memory value would make the two
128
- * physical mappings answer differently for the same document, which is
129
- * the one thing they may never do.
130
- *
131
- * Only the indexed MEMBER round-trips, not the whole document — it is
132
- * the only part a derived column reads.
133
- * @param {any} member
134
- * @returns {any} the member as stored, or `undefined` when there is none
135
- */
136
- export declare function storedMemberForm(member: any): any;
137
- /**
138
- * The value of one derived column for a document member, which the
139
- * caller hands over in its STORED form (`storedMemberForm`): the write
140
- * path round-trips it, and a migration backfill reads it from the row.
141
- * Exhaustive over the kind — see the file header.
142
- * @param {{ derive: string, precision?: number, component?: string,
143
- * dims?: number }} column
144
- * @param {any} member - the stored value at the index path, or `undefined`
145
- * @returns {string | number | Uint8Array | null}
146
- */
147
- export declare function derivedValue(column: {
148
- derive: string;
149
- precision?: number;
150
- component?: string;
151
- dims?: number;
152
- }, member: any): string | number | Uint8Array | null;
153
- /**
154
- * Read the member one derived column is computed from, walking the
155
- * same typed segments the physical mapping was planned over.
156
- * @param {any} doc
157
- * @param {import('./dialect.js').JsonPathSegment[]} segments
158
- * @returns {any} the member, or `undefined`
159
- */
160
- export declare function memberAt(doc: any, segments: import('./dialect.js').JsonPathSegment[]): any;
161
- /**
162
- * Register the deterministic functions the virtual generated columns
163
- * call. Idempotent per connection by SQLite's own semantics (a second
164
- * registration replaces the first with the identical implementation),
165
- * and a no-op where the driver cannot index a registered function —
166
- * that branch stores the columns instead.
167
- *
168
- * The four bbox edges share a one-entry memo of the last text they
169
- * were asked about, because they are called back to back with the same
170
- * argument for one row and the box costs a full walk of the geometry.
171
- * The memo is keyed on the argument itself, so it changes no answer.
172
- * @param {any} connection
173
- * @returns {any} value-or-promise
174
- */
175
- export declare function registerDeriveFunctions(connection: any): any;
176
- /**
177
- * The bounding box of a probe value, or `null` when it has none — the
178
- * D6 refusal included, which is what makes an unbounded probe divert to
179
- * the full scan instead of narrowing with a box that does not bound it.
180
- * @param {any} value - a GeoJSON value or a `[lon, lat]` position
181
- * @returns {number[] | null} `[west, south, east, north]`
182
- */
183
- export declare function probeBox(value: any): number[] | null;
184
- /**
185
- * The representative position §8.14 measures a probe value by — the
186
- * same rule the derived columns use, so the pushed filter and the
187
- * engine cannot disagree about where a value IS. `null` when it has no
188
- * bounded position.
189
- * @param {any} value
190
- * @returns {number[] | null}
191
- */
192
- export declare function probePosition(value: any): number[] | null;
193
- /**
194
- * The bounding box of the circle of `metres` around a position — the
195
- * box a `$distance <= r` predicate narrows with, on the same sphere and
196
- * the same radius constant the engine measures with. `null` when the
197
- * radius is not a finite non-negative number, or when the circle
198
- * reaches a pole, where there is no longitude bound to give.
199
- * @param {number[]} position
200
- * @param {number} metres
201
- * @returns {number[] | null} `[west, south, east, north]`, NOT wrapped
202
- * into `[-180, 180]`: a circle spanning the antimeridian answers a
203
- * west below -180, which is how the planner detects it
204
- */
205
- export declare function probeCircleBox(position: number[], metres: number): number[] | null;
206
- /**
207
- * A cell and its neighbours, the nine-cell probe D7 requires — a single
208
- * prefix is bucketing, never proximity.
209
- * @param {string} cell
210
- * @returns {string[]} up to nine cells (fewer past a pole)
211
- */
212
- export declare function cellNeighbourhood(cell: string): string[];
213
- /**
214
- * The value one DERIVED parameter slot binds: an axis of a bound
215
- * external's bounding box, computed at bind time because a GeoJSON
216
- * object is not a value any database can bind. `null` when the value
217
- * has no box, which is what tells the caller to divert.
218
- * @param {{ kind: string, external: string, axis: string }} derived
219
- * @param {any} value - the bound external
220
- * @returns {number | null}
221
- */
222
- export declare function derivedSlotValue(derived: {
223
- kind: string;
224
- external: string;
225
- axis: string;
226
- }, value: any): number | null;
227
- /**
228
- * The probe a k-nearest plan scores the column against: a literal or
229
- * bound vector, l2-normalized once, so that its dot product with the
230
- * column's normalized form IS the cosine of the raw vectors. `null`
231
- * when the value is not a vector of exactly `dims` finite numbers —
232
- * the binder's signal to divert the call to the residual, where the
233
- * engine answers what it answers everywhere for such a probe (empty
234
- * keys for another width, its own refusal for a non-array).
235
- * @param {unknown} value
236
- * @param {number} dims - the column's declared width
237
- * @returns {Float32Array | null}
238
- */
239
- export declare function probeVector(value: unknown, dims: number): Float32Array | null;
240
- /**
241
- * One row's column score against a prepared probe: the packed column
242
- * unpacked at the declared width and dotted with the probe. `null` for
243
- * a row whose column holds no vector — SQL `NULL`, or bytes of another
244
- * length — because such a row is unrankable and 0 is a real score.
245
- * @param {unknown} bytes - the column value as the driver returns it
246
- * @param {number} dims
247
- * @param {Float32Array} probe - from {@link probeVector}
248
- * @returns {number | null}
249
- */
250
- export declare function columnScore(bytes: unknown, dims: number, probe: Float32Array): number | null;
@@ -1,154 +0,0 @@
1
- /**
2
- * @file The dialect seam: the ONLY place SQL text is produced. A
3
- * dialect is data plus a small emitter — a spelling spec (how to quote
4
- * an identifier, reference a parameter, extract a JSON member, open a
5
- * savepoint) composed by {@link createDialect} into the DDL and DML
6
- * statement builders the store consumes. Nothing outside a dialect
7
- * concatenates SQL; that costs one indirection now, and without it a
8
- * second backend is a rewrite.
9
- *
10
- * Deliberately NOT in the dialect, because they are behavioural rather
11
- * than syntactic: whether functions can be registered per connection,
12
- * whether change capture exists and in what form, and whether tables
13
- * can be restructured in place. Those are capabilities on the
14
- * connection.
15
- */
16
- export type JsonPathSegment = {
17
- name: string;
18
- } | {
19
- index: number;
20
- };
21
- /**
22
- * A typed member path into the JSON document column: name segments for
23
- * object members, index segments for array positions. Produced by the
24
- * DDL planner (from analyzed index paths) and the patch translator
25
- * (from pointers discriminated against the live document).
26
- * @typedef {{ name: string } | { index: number }} JsonPathSegment
27
- */
28
- /**
29
- * Compose a dialect from its spelling spec. Every statement the store
30
- * ever runs is built here from the spec's primitives, so a spec with
31
- * different quoting or parameter style produces correspondingly
32
- * different SQL from the same model — the property the test-double
33
- * dialect pins.
34
- * @param {{
35
- * name: string,
36
- * capabilities: Record<string, any>,
37
- * tableSuffix: string,
38
- * docColumnType: string,
39
- * packedVectorType: string,
40
- * quoteIdentifier: (s: string) => string,
41
- * parameterRef: (i: number, name: string) => string,
42
- * stringLiteral: (s: string) => string,
43
- * booleanLiteral: (b: boolean) => string,
44
- * typeFor: (schemaType: string | undefined, hint: string) => string,
45
- * limitClause: (limit: number, offset?: number) => string,
46
- * jsonPathText: (segments: JsonPathSegment[]) => string | null,
47
- * jsonExtract: (columnSql: string, pathText: string) => string,
48
- * derivedExpression?: (memberSql: string, column: { derive: string,
49
- * precision?: number, component?: string, dims?: number }) => string,
50
- * jsonSet: (exprSql: string, pathText: string, valueSql: string) => string,
51
- * jsonRemove: (exprSql: string, pathText: string) => string,
52
- * jsonAppend: (exprSql: string, arrayPathText: string, valueSql: string) => string,
53
- * jsonEncode: (paramSql: string) => string,
54
- * jsonText: (columnSql: string) => string,
55
- * jsonAgg: (exprSql: string) => string,
56
- * jsonTypeOf: (columnSql: string, pathText: string) => string,
57
- * valueTypeOf: (paramSql: string) => string,
58
- * strStartsWith: (valueSql: string, lowerParamSql: string, upperParamSql: string) => string,
59
- * strStartsWithExact: (valueSql: string, patternA: string, patternB: string) => string,
60
- * strEndsWith: (valueSql: string, patternA: string, patternB: string, patternC: string) => string,
61
- * strContains: (valueSql: string, patternSql: string) => string,
62
- * orderNulls: (nullsFirst: boolean) => string,
63
- * timeBucket: (instantSql: string, originSql: string, everyA: string,
64
- * everyB: string, everyC: string) => string,
65
- * groupAggregate: (fn: string, valueSql: string | null) => string,
66
- * rowIdentity: () => string,
67
- * identityIn: (identitySql: string, paramSqls: string[]) => string,
68
- * rtree?: { module: string, columns: readonly string[] },
69
- * explainQuery: (sql: string) => string,
70
- * excludedRef: (columnSql: string) => string,
71
- * tx: { begin: string, beginImmediate: string, commit: string,
72
- * rollback: string,
73
- * savepoint: (n: string) => string, release: (n: string) => string,
74
- * rollbackTo: (n: string) => string },
75
- * pragma: { busyTimeout: (ms: number) => string,
76
- * journalMode: (mode: string) => string,
77
- * foreignKeys: (on: boolean) => string },
78
- * introspect: { version: () => string, compileOptions: () => string,
79
- * tableExists: () => string, columns: (table: string) => string,
80
- * indexes: (table: string) => string,
81
- * indexColumns: (index: string) => string,
82
- * foreignKeysOn: () => string,
83
- * foreignKeyList: (table: string) => string },
84
- * }} spec
85
- * @returns {any} the frozen dialect
86
- */
87
- export declare function createDialect(spec: {
88
- name: string;
89
- capabilities: Record<string, any>;
90
- tableSuffix: string;
91
- docColumnType: string;
92
- packedVectorType: string;
93
- quoteIdentifier: (s: string) => string;
94
- parameterRef: (i: number, name: string) => string;
95
- stringLiteral: (s: string) => string;
96
- booleanLiteral: (b: boolean) => string;
97
- typeFor: (schemaType: string | undefined, hint: string) => string;
98
- limitClause: (limit: number, offset?: number) => string;
99
- jsonPathText: (segments: JsonPathSegment[]) => string | null;
100
- jsonExtract: (columnSql: string, pathText: string) => string;
101
- derivedExpression?: (memberSql: string, column: {
102
- derive: string;
103
- precision?: number;
104
- component?: string;
105
- dims?: number;
106
- }) => string;
107
- jsonSet: (exprSql: string, pathText: string, valueSql: string) => string;
108
- jsonRemove: (exprSql: string, pathText: string) => string;
109
- jsonAppend: (exprSql: string, arrayPathText: string, valueSql: string) => string;
110
- jsonEncode: (paramSql: string) => string;
111
- jsonText: (columnSql: string) => string;
112
- jsonAgg: (exprSql: string) => string;
113
- jsonTypeOf: (columnSql: string, pathText: string) => string;
114
- valueTypeOf: (paramSql: string) => string;
115
- strStartsWith: (valueSql: string, lowerParamSql: string, upperParamSql: string) => string;
116
- strStartsWithExact: (valueSql: string, patternA: string, patternB: string) => string;
117
- strEndsWith: (valueSql: string, patternA: string, patternB: string, patternC: string) => string;
118
- strContains: (valueSql: string, patternSql: string) => string;
119
- orderNulls: (nullsFirst: boolean) => string;
120
- timeBucket: (instantSql: string, originSql: string, everyA: string, everyB: string, everyC: string) => string;
121
- groupAggregate: (fn: string, valueSql: string | null) => string;
122
- rowIdentity: () => string;
123
- identityIn: (identitySql: string, paramSqls: string[]) => string;
124
- rtree?: {
125
- module: string;
126
- columns: readonly string[];
127
- };
128
- explainQuery: (sql: string) => string;
129
- excludedRef: (columnSql: string) => string;
130
- tx: {
131
- begin: string;
132
- beginImmediate: string;
133
- commit: string;
134
- rollback: string;
135
- savepoint: (n: string) => string;
136
- release: (n: string) => string;
137
- rollbackTo: (n: string) => string;
138
- };
139
- pragma: {
140
- busyTimeout: (ms: number) => string;
141
- journalMode: (mode: string) => string;
142
- foreignKeys: (on: boolean) => string;
143
- };
144
- introspect: {
145
- version: () => string;
146
- compileOptions: () => string;
147
- tableExists: () => string;
148
- columns: (table: string) => string;
149
- indexes: (table: string) => string;
150
- indexColumns: (index: string) => string;
151
- foreignKeysOn: () => string;
152
- foreignKeyList: (table: string) => string;
153
- };
154
- }): any;
@@ -1,9 +0,0 @@
1
- /**
2
- * @file The SQLite dialect — the first spelling of the dialect
3
- * contract, not the only conceivable one. Documents are stored JSONB
4
- * in a BLOB column of a STRICT table; indexed paths become virtual
5
- * generated columns over `jsonb_extract`; reads render back to text
6
- * through `json()`. Parameters are positional (`?`) because every
7
- * binding this package ships binds arrays.
8
- */
9
- export declare const sqliteDialect: any;