@bjornpagen/bumbledb 0.1.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.
- package/LICENSE +12 -0
- package/README.md +84 -0
- package/dist/brand.d.ts +59 -0
- package/dist/brand.d.ts.map +1 -0
- package/dist/brand.js +47 -0
- package/dist/brand.js.map +1 -0
- package/dist/closed.d.ts +97 -0
- package/dist/closed.d.ts.map +1 -0
- package/dist/closed.js +107 -0
- package/dist/closed.js.map +1 -0
- package/dist/count.d.ts +55 -0
- package/dist/count.d.ts.map +1 -0
- package/dist/count.js +92 -0
- package/dist/count.js.map +1 -0
- package/dist/db.d.ts +341 -0
- package/dist/db.d.ts.map +1 -0
- package/dist/db.js +1016 -0
- package/dist/db.js.map +1 -0
- package/dist/exhume.d.ts +130 -0
- package/dist/exhume.d.ts.map +1 -0
- package/dist/exhume.js +145 -0
- package/dist/exhume.js.map +1 -0
- package/dist/face.d.ts +91 -0
- package/dist/face.d.ts.map +1 -0
- package/dist/face.js +69 -0
- package/dist/face.js.map +1 -0
- package/dist/fields.d.ts +187 -0
- package/dist/fields.d.ts.map +1 -0
- package/dist/fields.js +204 -0
- package/dist/fields.js.map +1 -0
- package/dist/index.d.ts +49 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +31 -0
- package/dist/index.js.map +1 -0
- package/dist/lower.d.ts +34 -0
- package/dist/lower.d.ts.map +1 -0
- package/dist/lower.js +105 -0
- package/dist/lower.js.map +1 -0
- package/dist/marshal.d.ts +79 -0
- package/dist/marshal.d.ts.map +1 -0
- package/dist/marshal.js +167 -0
- package/dist/marshal.js.map +1 -0
- package/dist/native.d.ts +532 -0
- package/dist/native.d.ts.map +1 -0
- package/dist/native.js +64 -0
- package/dist/native.js.map +1 -0
- package/dist/query/atom.d.ts +285 -0
- package/dist/query/atom.d.ts.map +1 -0
- package/dist/query/atom.js +281 -0
- package/dist/query/atom.js.map +1 -0
- package/dist/query/lower.d.ts +145 -0
- package/dist/query/lower.d.ts.map +1 -0
- package/dist/query/lower.js +604 -0
- package/dist/query/lower.js.map +1 -0
- package/dist/query/predicate.d.ts +101 -0
- package/dist/query/predicate.d.ts.map +1 -0
- package/dist/query/predicate.js +85 -0
- package/dist/query/predicate.js.map +1 -0
- package/dist/query/run.d.ts +30 -0
- package/dist/query/run.d.ts.map +1 -0
- package/dist/query/run.js +94 -0
- package/dist/query/run.js.map +1 -0
- package/dist/query/scope.d.ts +168 -0
- package/dist/query/scope.d.ts.map +1 -0
- package/dist/query/scope.js +134 -0
- package/dist/query/scope.js.map +1 -0
- package/dist/query/select.d.ts +106 -0
- package/dist/query/select.d.ts.map +1 -0
- package/dist/query/select.js +69 -0
- package/dist/query/select.js.map +1 -0
- package/dist/relation.d.ts +120 -0
- package/dist/relation.d.ts.map +1 -0
- package/dist/relation.js +108 -0
- package/dist/relation.js.map +1 -0
- package/dist/schema.d.ts +50 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +235 -0
- package/dist/schema.js.map +1 -0
- package/dist/spec.d.ts +218 -0
- package/dist/spec.d.ts.map +1 -0
- package/dist/spec.js +154 -0
- package/dist/spec.js.map +1 -0
- package/dist/statements.d.ts +91 -0
- package/dist/statements.d.ts.map +1 -0
- package/dist/statements.js +101 -0
- package/dist/statements.js.map +1 -0
- package/package.json +66 -0
- package/src/brand.ts +82 -0
- package/src/closed.ts +228 -0
- package/src/count.ts +117 -0
- package/src/db.ts +1519 -0
- package/src/exhume.ts +243 -0
- package/src/face.ts +161 -0
- package/src/fields.ts +385 -0
- package/src/index.ts +185 -0
- package/src/lower.ts +118 -0
- package/src/marshal.ts +220 -0
- package/src/native.ts +576 -0
- package/src/query/atom.ts +556 -0
- package/src/query/lower.ts +855 -0
- package/src/query/predicate.ts +195 -0
- package/src/query/run.ts +106 -0
- package/src/query/scope.ts +301 -0
- package/src/query/select.ts +140 -0
- package/src/relation.ts +252 -0
- package/src/schema.ts +297 -0
- package/src/spec.ts +325 -0
- package/src/statements.ts +148 -0
package/dist/db.d.ts
ADDED
|
@@ -0,0 +1,341 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `Db` — the living half of the SDK (PRD-07): open/create a store from a
|
|
3
|
+
* `Schema`, write typed facts through delta transactions with race-free
|
|
4
|
+
* final-state point reads, receive rejections as typed violation VALUES
|
|
5
|
+
* keyed to statements, read through scoped snapshots, and run the witnessed
|
|
6
|
+
* read-compute-write loop — all typed by the schema's relations record.
|
|
7
|
+
*
|
|
8
|
+
* ZERO CLOSABLES: no value this module returns carries a close, dispose, or
|
|
9
|
+
* release spelling. `Db` values are CACHED per canonical path for the life
|
|
10
|
+
* of the process (a best-effort exit hook closes the cached environments;
|
|
11
|
+
* correctness never depends on it — the engine fsyncs every commit, so a
|
|
12
|
+
* process that dies without the hook loses nothing that was committed).
|
|
13
|
+
* Snapshots are internal: `read(fn)` opens one before `fn` and closes it
|
|
14
|
+
* after unconditionally, and the {@link ReadScope} handed to `fn` is
|
|
15
|
+
* invalidated the moment `fn` returns. Prepared plans are plain values whose
|
|
16
|
+
* engine-side half is reclaimed by a GC finalizer — reclamation only, never
|
|
17
|
+
* correctness.
|
|
18
|
+
*
|
|
19
|
+
* PROCESS MODEL: one process, one exclusive-lock handle per store. The
|
|
20
|
+
* cached `Db` value owns the LMDB environment's exclusive lock until
|
|
21
|
+
* process exit; a second engine-level open of the same store (an aliased
|
|
22
|
+
* path spelling, or another process) is refused by the engine. The
|
|
23
|
+
* run-store process model (PRD-16) depends on this being true: resume =
|
|
24
|
+
* reopen, which is either this process's cached value or a fresh process's
|
|
25
|
+
* open.
|
|
26
|
+
*
|
|
27
|
+
* REJECTION IS DATA: a rejected commit is a domain outcome (it becomes the
|
|
28
|
+
* LLM repair prompt downstream), returned as a {@link WriteResult} carrying
|
|
29
|
+
* {@link Violation} values. Genuine failures — I/O, used-after-scope,
|
|
30
|
+
* marshal shape — throw `@superbuilders/errors` wrapped errors instead.
|
|
31
|
+
*/
|
|
32
|
+
import { phantom } from "#brand.ts";
|
|
33
|
+
import type { Exhumed } from "#exhume.ts";
|
|
34
|
+
import { type KeyFact, type Minted } from "#marshal.ts";
|
|
35
|
+
import type { FactValue, Staleness, StatementKindTag } from "#native.ts";
|
|
36
|
+
import type { Query } from "#query/lower.ts";
|
|
37
|
+
import type { ParamsRecord } from "#query/scope.ts";
|
|
38
|
+
import type { AnyRelation, Fact, InsertFact } from "#relation.ts";
|
|
39
|
+
import type { Schema, SchemaRelations } from "#schema.ts";
|
|
40
|
+
import type { KeyStatement, Statement } from "#statements.ts";
|
|
41
|
+
/**
|
|
42
|
+
* The ordinary (writable, scannable) relations of a schema's record — the
|
|
43
|
+
* only values the runtime methods accept: closed relations lack the
|
|
44
|
+
* relation shape entirely, so passing one is a type error.
|
|
45
|
+
*/
|
|
46
|
+
type MemberRelation<Rels extends SchemaRelations> = Extract<Rels[keyof Rels], AnyRelation>;
|
|
47
|
+
/**
|
|
48
|
+
* The key object of a key-statement-selected `get`: exactly the selected
|
|
49
|
+
* `key()` statement's projection fields, each carrying the relation's own
|
|
50
|
+
* branded value type — the {@link KeyFact} rule generalized from the
|
|
51
|
+
* primary key to ANY declared key statement.
|
|
52
|
+
*/
|
|
53
|
+
type DeclaredKeyFact<R extends AnyRelation, Projection extends readonly string[]> = {
|
|
54
|
+
readonly [K in Projection[number] & keyof Fact<R>]: Fact<R>[K];
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* One offending fact of a violation: the cited relation's name (a member
|
|
58
|
+
* of the schema's record) and the fact decoded to a named natural-value
|
|
59
|
+
* object — partial exactly as the engine cites it.
|
|
60
|
+
*/
|
|
61
|
+
interface OffendingFact<Rels extends SchemaRelations> {
|
|
62
|
+
readonly relation: keyof Rels & string;
|
|
63
|
+
readonly fact: Readonly<Record<string, FactValue>>;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* One violated statement of a rejected commit, as a typed value.
|
|
67
|
+
* `statement` is the IDENTICAL SDK statement value the schema declared —
|
|
68
|
+
* consumers `===`-match it against their own constants; it is `undefined`
|
|
69
|
+
* exactly for the engine-materialized fresh-implied and closed auto-keys,
|
|
70
|
+
* which have no declared spelling (`schema()` rejects an explicit
|
|
71
|
+
* duplicate of them). `canonical` is the ENGINE's rendering of the
|
|
72
|
+
* violated materialized statement — for a `mirrors` statement BOTH
|
|
73
|
+
* materialized slots render as the one `==` utterance in the written
|
|
74
|
+
* orientation (identical strings; the engine's `render.rs` renders each
|
|
75
|
+
* partner of a mirrored pair as the `==` spelling, never a bare `<=`
|
|
76
|
+
* direction). `direction` (`sourceUnsatisfied` | `targetRequired`) and
|
|
77
|
+
* `count` are the containment/window form payloads, passed through from
|
|
78
|
+
* the engine VERBATIM — `direction` is relative to the violated SLOT's
|
|
79
|
+
* own orientation, so for a `mirrors` statement it alone cannot say which
|
|
80
|
+
* side of the `==` was violated: the slot identity is carried by
|
|
81
|
+
* `orientation`, present exactly for `mirrors` slots — `written` is the
|
|
82
|
+
* `source <= target` slot as the statement was spelled, `mirrored` the
|
|
83
|
+
* engine-materialized `target <= source` partner.
|
|
84
|
+
*/
|
|
85
|
+
interface Violation<Rels extends SchemaRelations> {
|
|
86
|
+
readonly statement: Statement | undefined;
|
|
87
|
+
readonly kind: StatementKindTag;
|
|
88
|
+
readonly canonical: string;
|
|
89
|
+
readonly direction?: "sourceUnsatisfied" | "targetRequired";
|
|
90
|
+
readonly orientation?: "written" | "mirrored";
|
|
91
|
+
readonly count?: bigint;
|
|
92
|
+
readonly facts: readonly OffendingFact<Rels>[];
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* A commit's domain outcome: the committed generation, or the COMPLETE
|
|
96
|
+
* violation set (every violated statement cited once, per direction for a
|
|
97
|
+
* containment, in materialized statement order). Narrows on `.ok`.
|
|
98
|
+
*/
|
|
99
|
+
type WriteResult<Rels extends SchemaRelations> = {
|
|
100
|
+
readonly ok: true;
|
|
101
|
+
readonly generation: bigint;
|
|
102
|
+
} | {
|
|
103
|
+
readonly ok: false;
|
|
104
|
+
readonly violations: readonly Violation<Rels>[];
|
|
105
|
+
};
|
|
106
|
+
/** The delta-building callback of a write: runs synchronously against the live transaction. */
|
|
107
|
+
type DeltaBuild<Rels extends SchemaRelations> = (tx: Tx<Rels>) => void;
|
|
108
|
+
/**
|
|
109
|
+
* The runtime discriminant of {@link Abandon} values — a property probe is
|
|
110
|
+
* how `writeWitnessed` distinguishes "abort without committing" from an
|
|
111
|
+
* ordinary callback result, never a guess about the host's own value shapes.
|
|
112
|
+
*/
|
|
113
|
+
declare const abandonMark: unique symbol;
|
|
114
|
+
/**
|
|
115
|
+
* The abandon sentinel {@link abandon} builds: returning one from a
|
|
116
|
+
* `writeWitnessed` callback aborts the attempt WITHOUT committing (no empty
|
|
117
|
+
* commit is ever issued) and surfaces the payload as
|
|
118
|
+
* `{ ok: false, abandoned: payload }`.
|
|
119
|
+
*/
|
|
120
|
+
interface Abandon<P> {
|
|
121
|
+
readonly [abandonMark]: true;
|
|
122
|
+
readonly payload: P;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Wraps a payload in the {@link Abandon} sentinel — the one way a
|
|
126
|
+
* `writeWitnessed` callback declines to commit: `return abandon(payload)`
|
|
127
|
+
* aborts the delta (nothing is committed, not even an empty commit) and the
|
|
128
|
+
* write resolves to `{ ok: false, abandoned: payload }`.
|
|
129
|
+
*/
|
|
130
|
+
declare function abandon<P>(payload: P): Abandon<P>;
|
|
131
|
+
/**
|
|
132
|
+
* The abandon payload type a `writeWitnessed` callback's return type
|
|
133
|
+
* implies: the payload of its `Abandon` arm, `never` when the callback can
|
|
134
|
+
* never abandon (the `abandoned` outcome is then statically unreachable).
|
|
135
|
+
*/
|
|
136
|
+
type AbandonedPayload<R> = R extends Abandon<infer P> ? P : never;
|
|
137
|
+
/**
|
|
138
|
+
* `writeWitnessed`'s domain outcome: the committed generation, the COMPLETE
|
|
139
|
+
* engine violation set (rejection-as-data, exactly {@link WriteResult}'s
|
|
140
|
+
* false arm), or the callback's own abandon payload. Narrows on `.ok`, then
|
|
141
|
+
* on `"violations" in result`.
|
|
142
|
+
*/
|
|
143
|
+
type WitnessedWriteResult<Rels extends SchemaRelations, R> = {
|
|
144
|
+
readonly ok: true;
|
|
145
|
+
readonly generation: bigint;
|
|
146
|
+
} | {
|
|
147
|
+
readonly ok: false;
|
|
148
|
+
readonly violations: readonly Violation<Rels>[];
|
|
149
|
+
} | {
|
|
150
|
+
readonly ok: false;
|
|
151
|
+
readonly abandoned: AbandonedPayload<R>;
|
|
152
|
+
};
|
|
153
|
+
/**
|
|
154
|
+
* One live write transaction: the submitted delta with the engine's
|
|
155
|
+
* FINAL-STATE point-read view (base + pending delta — the exact state the
|
|
156
|
+
* commit judgment judges, so check-then-act is race-free by construction).
|
|
157
|
+
* Spent when its owning `write`/`writeWitnessed` call resolves the attempt;
|
|
158
|
+
* any later use throws.
|
|
159
|
+
*/
|
|
160
|
+
interface Tx<Rels extends SchemaRelations> {
|
|
161
|
+
/**
|
|
162
|
+
* Records one insert. Omitted fresh fields are MINTED through the
|
|
163
|
+
* engine's alloc lane and returned branded; supplying them instead
|
|
164
|
+
* preserves identity (the resupply idiom). Returns the relation's
|
|
165
|
+
* fresh cells, minted or resupplied.
|
|
166
|
+
*/
|
|
167
|
+
insert<R extends MemberRelation<Rels>>(relation: R, fact: InsertFact<R>): Minted<R>;
|
|
168
|
+
/** Records one delete; `true` iff the final state changed. */
|
|
169
|
+
delete<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean;
|
|
170
|
+
/** Final-state membership of one complete fact. */
|
|
171
|
+
contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean;
|
|
172
|
+
/**
|
|
173
|
+
* Final-state point lookup through the relation's primary key (the
|
|
174
|
+
* {@link KeyFact} rule); `undefined` on a miss.
|
|
175
|
+
*/
|
|
176
|
+
get<R extends MemberRelation<Rels>>(relation: R, key: KeyFact<R>): Fact<R> | undefined;
|
|
177
|
+
/**
|
|
178
|
+
* Final-state point lookup through a DECLARED `key()` statement of this
|
|
179
|
+
* schema — the key object is typed by the statement's own projection;
|
|
180
|
+
* `undefined` on a miss.
|
|
181
|
+
*/
|
|
182
|
+
get<R extends MemberRelation<Rels>, const P extends readonly string[]>(relation: R, keyStatement: KeyStatement<R, P>, key: DeclaredKeyFact<R, P>): Fact<R> | undefined;
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* The read view one `db.read(fn)` call scopes: an MVCC snapshot pinned at
|
|
186
|
+
* its generation, valid EXACTLY for the synchronous extent of `fn`. The
|
|
187
|
+
* value is invalidated when `fn` returns — every later verb call throws a
|
|
188
|
+
* typed used-after-scope error; the underlying snapshot (and its LMDB
|
|
189
|
+
* reader slot) is already closed. No close spelling exists here because
|
|
190
|
+
* there is nothing the host could ever need to close.
|
|
191
|
+
*/
|
|
192
|
+
interface ReadScope<Rels extends SchemaRelations> {
|
|
193
|
+
/**
|
|
194
|
+
* The committed generation this scope witnessed — captured atomically
|
|
195
|
+
* with the snapshot: writes are synchronous and this process holds the
|
|
196
|
+
* store's only write handle, so nothing can commit between the snapshot
|
|
197
|
+
* open and the generation read.
|
|
198
|
+
*/
|
|
199
|
+
readonly generation: bigint;
|
|
200
|
+
/** Full-relation export in row-id order, decoded to branded facts. */
|
|
201
|
+
scan<R extends MemberRelation<Rels>>(relation: R): Fact<R>[];
|
|
202
|
+
/**
|
|
203
|
+
* Committed-state point lookup through the relation's primary key
|
|
204
|
+
* (the {@link KeyFact} rule); `undefined` on a miss.
|
|
205
|
+
*/
|
|
206
|
+
get<R extends MemberRelation<Rels>>(relation: R, key: KeyFact<R>): Fact<R> | undefined;
|
|
207
|
+
/**
|
|
208
|
+
* Committed-state point lookup through a DECLARED `key()` statement of
|
|
209
|
+
* this schema — the key object is typed by the statement's own
|
|
210
|
+
* projection; `undefined` on a miss.
|
|
211
|
+
*/
|
|
212
|
+
get<R extends MemberRelation<Rels>, const P extends readonly string[]>(relation: R, keyStatement: KeyStatement<R, P>, key: DeclaredKeyFact<R, P>): Fact<R> | undefined;
|
|
213
|
+
/** Committed-state membership of one complete fact. */
|
|
214
|
+
contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean;
|
|
215
|
+
/**
|
|
216
|
+
* Executes a prepared query against this scope's snapshot with the
|
|
217
|
+
* typed params object; returns the answer SET as plain rows with
|
|
218
|
+
* branded values (no order — the host sorts). This is the ONE
|
|
219
|
+
* execution spelling ({@link Prepared} carries no `execute`).
|
|
220
|
+
*/
|
|
221
|
+
execute<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Row[];
|
|
222
|
+
}
|
|
223
|
+
/**
|
|
224
|
+
* One prepared query as a plain VALUE: explicit visible compilation
|
|
225
|
+
* (`db.prepare(q)` lowers, pins the plan, and surfaces every engine roster
|
|
226
|
+
* refusal), no lifecycle. Execution happens ONLY through
|
|
227
|
+
* `snap.execute(prepared, params)` / `db.execute(prepared, params)` — the
|
|
228
|
+
* symmetry rule's one spelling. The engine-side plan is reclaimed by a GC
|
|
229
|
+
* finalizer when this value becomes unreachable (reclamation only, never
|
|
230
|
+
* correctness — an unreclaimed plan is idle memory, and process exit frees
|
|
231
|
+
* everything).
|
|
232
|
+
*/
|
|
233
|
+
interface Prepared<Rels extends SchemaRelations, Row, Params extends ParamsRecord> {
|
|
234
|
+
/**
|
|
235
|
+
* The pull-based plan-drift report against a read scope's snapshot —
|
|
236
|
+
* engine-policy-free: no threshold exists engine-side; the host owns
|
|
237
|
+
* re-prepare.
|
|
238
|
+
*/
|
|
239
|
+
staleness(snap: ReadScope<Rels>): Staleness;
|
|
240
|
+
readonly [phantom]?: {
|
|
241
|
+
readonly row: Row;
|
|
242
|
+
readonly params: Params;
|
|
243
|
+
};
|
|
244
|
+
}
|
|
245
|
+
/**
|
|
246
|
+
* An open store, cached per canonical path for the life of the process.
|
|
247
|
+
* There is no close: read through `read`/the read sugar, write through
|
|
248
|
+
* `write`/`writeWitnessed`, and let the process own the environment's
|
|
249
|
+
* lifetime (the engine fsyncs every commit, so durability never waits on a
|
|
250
|
+
* close).
|
|
251
|
+
*/
|
|
252
|
+
interface Db<Rels extends SchemaRelations> {
|
|
253
|
+
/** The theory this store was opened with (fingerprint-verified by the engine). */
|
|
254
|
+
readonly schema: Schema<Rels>;
|
|
255
|
+
/**
|
|
256
|
+
* One scoped snapshot read: opens an MVCC snapshot, runs `fn`
|
|
257
|
+
* SYNCHRONOUSLY against it, and closes the snapshot unconditionally
|
|
258
|
+
* before returning `fn`'s result. The {@link ReadScope} is invalidated
|
|
259
|
+
* when `fn` returns — a used-after-scope call throws a typed error.
|
|
260
|
+
*/
|
|
261
|
+
read<T>(fn: (snap: ReadScope<Rels>) => T): T;
|
|
262
|
+
/** `db.scan(r)` === `db.read(snap => snap.scan(r))` — the symmetry rule. */
|
|
263
|
+
scan<R extends MemberRelation<Rels>>(relation: R): Fact<R>[];
|
|
264
|
+
/** `db.get(r, k)` === `db.read(snap => snap.get(r, k))` — the symmetry rule. */
|
|
265
|
+
get<R extends MemberRelation<Rels>>(relation: R, key: KeyFact<R>): Fact<R> | undefined;
|
|
266
|
+
/** `db.get(r, s, k)` === `db.read(snap => snap.get(r, s, k))` — the symmetry rule, keyed form. */
|
|
267
|
+
get<R extends MemberRelation<Rels>, const P extends readonly string[]>(relation: R, keyStatement: KeyStatement<R, P>, key: DeclaredKeyFact<R, P>): Fact<R> | undefined;
|
|
268
|
+
/** `db.contains(r, f)` === `db.read(snap => snap.contains(r, f))` — the symmetry rule. */
|
|
269
|
+
contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean;
|
|
270
|
+
/** `db.execute(p, params)` === `db.read(snap => snap.execute(p, params))` — the symmetry rule. */
|
|
271
|
+
execute<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Row[];
|
|
272
|
+
/**
|
|
273
|
+
* One delta transaction: builds the delta synchronously through `fn`,
|
|
274
|
+
* commits, and returns the domain outcome. A throw from `fn` aborts
|
|
275
|
+
* the delta (LMDB untouched) and rethrows wrapped.
|
|
276
|
+
*/
|
|
277
|
+
write(fn: DeltaBuild<Rels>): WriteResult<Rels>;
|
|
278
|
+
/**
|
|
279
|
+
* The ONE witnessed-write form: snapshot → `fn` (premise reads via
|
|
280
|
+
* `snap`, delta via `tx`) → witnessed commit, which lands only if no
|
|
281
|
+
* state-changing commit intervened since the snapshot. On a moved
|
|
282
|
+
* generation the WHOLE `fn` reruns on a fresh snapshot, unbounded: this
|
|
283
|
+
* process holds the store's only write handle, so every generation move
|
|
284
|
+
* is self-inflicted by the host's own interleaved writes — contention
|
|
285
|
+
* is bounded by the host's own progress, and any retry cap would be an
|
|
286
|
+
* invented limit (the house no-limits law). `fn` may decline to commit
|
|
287
|
+
* by returning {@link abandon}`(payload)` — the outcome is then
|
|
288
|
+
* `{ ok: false, abandoned: payload }` and NO commit (not even an empty
|
|
289
|
+
* one) is issued.
|
|
290
|
+
*/
|
|
291
|
+
writeWitnessed<R>(fn: (snap: ReadScope<Rels>, tx: Tx<Rels>) => R): WitnessedWriteResult<Rels, R>;
|
|
292
|
+
/**
|
|
293
|
+
* Prepares a query value built against THIS schema (identity is the
|
|
294
|
+
* membership rule): lowers it to the engine IR, pins the plan, and
|
|
295
|
+
* returns the typed {@link Prepared} value. Every IR roster refusal —
|
|
296
|
+
* rule caps, strata legality, type rules — is the ENGINE's typed
|
|
297
|
+
* judgment and throws here carrying its message intact.
|
|
298
|
+
*/
|
|
299
|
+
prepare<Row, Params extends ParamsRecord>(q: Query<Rels, Row, Params>): Prepared<Rels, Row, Params>;
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* The store lifecycle — `Db.create(path, schema)` / `Db.open(path, schema)`.
|
|
303
|
+
* Create refuses an already-initialized directory; open verifies format
|
|
304
|
+
* version, store kind, and the schema fingerprint. Both return values
|
|
305
|
+
* CACHED per canonical path: a second open of the same path with the
|
|
306
|
+
* identical theory value returns the SAME `Db`, and a different theory on
|
|
307
|
+
* a cached path is a typed fingerprint error. There is no close anywhere:
|
|
308
|
+
* the process owns every cached environment until exit (a best-effort exit
|
|
309
|
+
* hook closes them; durability is the engine's per-commit fsync). One
|
|
310
|
+
* store kind exists: durable — resume = reopen, meaning this process's
|
|
311
|
+
* cached value or a fresh process's open.
|
|
312
|
+
*/
|
|
313
|
+
declare const Db: Readonly<{
|
|
314
|
+
/** Creates a fresh durable store at `path` from the schema; the value is cached for every later open. */
|
|
315
|
+
create<Rels extends SchemaRelations>(path: string, theory: Schema<Rels>): Promise<Db<Rels>>;
|
|
316
|
+
/**
|
|
317
|
+
* Opens an existing durable store at `path` with the same theory — the
|
|
318
|
+
* cached value when this process already holds it. A fingerprint-matching
|
|
319
|
+
* open also BACK-FILLS the store's persisted schema descriptor when it is
|
|
320
|
+
* absent (self-describing stores, engine 50-storage.md § the `_meta`
|
|
321
|
+
* block), so a legacy store becomes exhumable after one ordinary open —
|
|
322
|
+
* adoption is automatic, never a separate verb.
|
|
323
|
+
*/
|
|
324
|
+
open<Rels extends SchemaRelations>(path: string, theory: Schema<Rels>): Promise<Db<Rels>>;
|
|
325
|
+
/**
|
|
326
|
+
* Opens a store READ-ONLY from its own persisted descriptor — the SDK's
|
|
327
|
+
* one schema-independent read path (no theory, no fingerprint check; the
|
|
328
|
+
* store rebirth tool's entry). Lives beside `open`/`create` so the path
|
|
329
|
+
* law stays in one place: the same `node:path.resolve` canonicalization,
|
|
330
|
+
* applied here. The value is NOT cached and carries no close: the
|
|
331
|
+
* engine-side handle (and the store's exclusive lock) is reclaimed by GC
|
|
332
|
+
* — reclamation only, never correctness. A store not yet adopted rejects
|
|
333
|
+
* with the typed `ErrExhumeNoDescriptor` (the remedy: one
|
|
334
|
+
* fingerprint-matching `Db.open` under the creating schema back-fills
|
|
335
|
+
* the descriptor).
|
|
336
|
+
*/
|
|
337
|
+
exhume(storePath: string): Promise<Exhumed>;
|
|
338
|
+
}>;
|
|
339
|
+
export type { Abandon, DeclaredKeyFact, DeltaBuild, MemberRelation, OffendingFact, Prepared, ReadScope, Tx, Violation, WitnessedWriteResult, WriteResult };
|
|
340
|
+
export { abandon, Db };
|
|
341
|
+
//# sourceMappingURL=db.d.ts.map
|
package/dist/db.d.ts.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"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"}
|