@gusto/baerly-storage 0.5.0 → 0.7.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/README.md +47 -124
- package/dist/API.md +161 -511
- package/dist/CHANGELOG.md +1148 -307
- package/dist/RECIPES.md +398 -80
- package/dist/THIRD-PARTY-LICENSES.txt +5 -26
- package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
- package/dist/app-config.d.ts +31 -1
- package/dist/app-config.js +1 -2
- package/dist/app-config.js.map +1 -1
- package/dist/auth.d.ts +33 -28
- package/dist/auth.js +549 -985
- package/dist/auth.js.map +1 -1
- package/dist/baerly.js +130 -138
- package/dist/baerly.js.map +1 -1
- package/dist/baerly.spec.json +97 -22
- package/dist/capacity-warning-header-BlVopyiI.js +16 -0
- package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
- package/dist/{client-Fe8CwB73.d.ts → client-CHQTXpef.d.ts} +121 -36
- package/dist/client-react.d.ts +67 -20
- package/dist/client-react.js +240 -54
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +5 -4
- package/dist/client.js +51 -16
- package/dist/client.js.map +1 -1
- package/dist/{cloudflare-DzKBrUlg.js → cloudflare-CKHYXccw.js} +504 -124
- package/dist/cloudflare-CKHYXccw.js.map +1 -0
- package/dist/cloudflare.d.ts +106 -71
- package/dist/cloudflare.js +334 -271
- package/dist/cloudflare.js.map +1 -1
- package/dist/code-resolution-CL_7L0wS.js +22 -0
- package/dist/code-resolution-CL_7L0wS.js.map +1 -0
- package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
- package/dist/config-DEzInG6M.js +4035 -0
- package/dist/config-DEzInG6M.js.map +1 -0
- package/dist/constants-D3GSH3tc.js +469 -0
- package/dist/constants-D3GSH3tc.js.map +1 -0
- package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
- package/dist/context-rlpSnHFA.js.map +1 -0
- package/dist/cost-B52llVDx.js +330 -0
- package/dist/cost-B52llVDx.js.map +1 -0
- package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
- package/dist/current-json-CC6lE4Aj.js.map +1 -0
- package/dist/db-plFUNTSF.d.ts +130 -0
- package/dist/db-read-seams-BSs0m1z1.js +3261 -0
- package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
- package/dist/{deploy-DonTr-CV.js → deploy-Obj4nE-Z.js} +12 -16
- package/dist/deploy-Obj4nE-Z.js.map +1 -0
- package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
- package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
- package/dist/dev-landing-CD-si4dW.js +50 -0
- package/dist/dev-landing-CD-si4dW.js.map +1 -0
- package/dist/dev-vite.d.ts +38 -39
- package/dist/dev-vite.js +67 -36
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +3 -2
- package/dist/dev.js +2 -1
- package/dist/doctor-BA0i-YAN.js +270 -0
- package/dist/doctor-BA0i-YAN.js.map +1 -0
- package/dist/dump-D1vX8ozg.js +133 -0
- package/dist/dump-D1vX8ozg.js.map +1 -0
- package/dist/errors-7Rk1HGCE.js +160 -0
- package/dist/errors-7Rk1HGCE.js.map +1 -0
- package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
- package/dist/export-BVL2EvYE.js.map +1 -0
- package/dist/fsck-BWkPgov4.js +145 -0
- package/dist/fsck-BWkPgov4.js.map +1 -0
- package/dist/gcs-admin-Dso1HWQj.d.ts +127 -0
- package/dist/gcs.d.ts +30 -0
- package/dist/gcs.js +1 -0
- package/dist/goog4-signer-CeLIABoE.js +331 -0
- package/dist/goog4-signer-CeLIABoE.js.map +1 -0
- package/dist/{http-DGd5tbNs.js → http-Z5rZyYMX.js} +898 -271
- package/dist/http-Z5rZyYMX.js.map +1 -0
- package/dist/http-transport-DNUM8kU-.js +1299 -0
- package/dist/http-transport-DNUM8kU-.js.map +1 -0
- package/dist/http.d.ts +366 -294
- package/dist/http.js +2 -2
- package/dist/index-JJrIu1pO.d.ts +135 -0
- package/dist/index-LEgHN0qJ.d.ts +50 -0
- package/dist/{index-CuA9Mi3K.d.ts → index-RiEYj8t0.d.ts} +291 -78
- package/dist/index.d.ts +27 -6
- package/dist/index.js +3 -5
- package/dist/inspect-BTsVYZKd.js +196 -0
- package/dist/inspect-BTsVYZKd.js.map +1 -0
- package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
- package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
- package/dist/ledger-Dj_bGgo0.js +192 -0
- package/dist/ledger-Dj_bGgo0.js.map +1 -0
- package/dist/legacy-names-DgZBtgOh.js +47 -0
- package/dist/legacy-names-DgZBtgOh.js.map +1 -0
- package/dist/log-C9W15Dfo.d.ts +94 -0
- package/dist/log-tail-DWJbneBF.js +142 -0
- package/dist/log-tail-DWJbneBF.js.map +1 -0
- package/dist/log-walk-C-vA-WGJ.js +111 -0
- package/dist/log-walk-C-vA-WGJ.js.map +1 -0
- package/dist/maintenance-Dd-Yakqj.js +1709 -0
- package/dist/maintenance-Dd-Yakqj.js.map +1 -0
- package/dist/maintenance-DevB6z4e.js +2237 -0
- package/dist/maintenance-DevB6z4e.js.map +1 -0
- package/dist/maintenance.d.ts +100 -3
- package/dist/maintenance.js +1 -3
- package/dist/node.d.ts +130 -142
- package/dist/node.js +4 -3
- package/dist/{observability-BmflLCdF.js → observability-C-ISCCLE.js} +1275 -332
- package/dist/observability-C-ISCCLE.js.map +1 -0
- package/dist/observability.d.ts +27 -3
- package/dist/observability.js +3 -3
- package/dist/path-segment-DBXG26PW.js +363 -0
- package/dist/path-segment-DBXG26PW.js.map +1 -0
- package/dist/{plan-a7PJHBCy.js → plan-BvQbaNMe.js} +19 -11
- package/dist/plan-BvQbaNMe.js.map +1 -0
- package/dist/request-CRWiTrza.js +272 -0
- package/dist/request-CRWiTrza.js.map +1 -0
- package/dist/restore-U6Im8V1V.js +1467 -0
- package/dist/restore-U6Im8V1V.js.map +1 -0
- package/dist/retry-OBtLB2GC.js +126 -0
- package/dist/retry-OBtLB2GC.js.map +1 -0
- package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
- package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec-B5mg3pHF.js} +189 -28
- package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
- package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DBC_wiCL.d.ts} +18 -10
- package/dist/s3.d.ts +20 -7
- package/dist/s3.js +4 -5
- package/dist/s3.js.map +1 -1
- package/dist/sha256-4FfGQNPw.js +22 -0
- package/dist/sha256-4FfGQNPw.js.map +1 -0
- package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
- package/dist/shared-secret-Vkur-8r0.js.map +1 -0
- package/dist/sigv4-sign-5IUflUD_.js +507 -0
- package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
- package/dist/snapshot-CknzkDM0.js +148 -0
- package/dist/snapshot-CknzkDM0.js.map +1 -0
- package/dist/{src-BL_JoPTn.js → src-Actga-bO.js} +1004 -378
- package/dist/src-Actga-bO.js.map +1 -0
- package/dist/src-D0MQfvOp.js +812 -0
- package/dist/src-D0MQfvOp.js.map +1 -0
- package/dist/src-Dr9uo3dc.js +501 -0
- package/dist/src-Dr9uo3dc.js.map +1 -0
- package/dist/{subcommand-DoDA-K7d.js → subcommand-BLoF66dG.js} +89 -16
- package/dist/subcommand-BLoF66dG.js.map +1 -0
- package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
- package/dist/time-DRxTP9iv.js.map +1 -0
- package/dist/types-suVbsEWS.d.ts +116 -0
- package/dist/{usage-DBV1eQHC.js → usage-CPzVhrQr.js} +40 -45
- package/dist/usage-CPzVhrQr.js.map +1 -0
- package/dist/uuid-BuT_c404.js +333 -0
- package/dist/uuid-BuT_c404.js.map +1 -0
- package/dist/verifier-Bmlmndzo.d.ts +95 -0
- package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
- package/dist/wire-DndvKU-K.js.map +1 -0
- package/package.json +96 -69
- package/dist/aws4fetch.esm-p7eEzLCs.js +0 -1702
- package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
- package/dist/bytes-BXdamO3L.js +0 -11
- package/dist/bytes-BXdamO3L.js.map +0 -1
- package/dist/cloudflare-DzKBrUlg.js.map +0 -1
- package/dist/config-1tv0-Yzm.js +0 -2693
- package/dist/config-1tv0-Yzm.js.map +0 -1
- package/dist/constants-CfeMWQWk.js +0 -222
- package/dist/constants-CfeMWQWk.js.map +0 -1
- package/dist/context-DRZ3tZ5l.js.map +0 -1
- package/dist/cost-DSMIVqzL.js +0 -203
- package/dist/cost-DSMIVqzL.js.map +0 -1
- package/dist/current-json-C6nhPOm1.js.map +0 -1
- package/dist/db-DsPkOVEH.d.ts +0 -254
- package/dist/deploy-DonTr-CV.js.map +0 -1
- package/dist/doctor-DSIyCDg_.js +0 -346
- package/dist/doctor-DSIyCDg_.js.map +0 -1
- package/dist/dump-Bh5k26VQ.js +0 -94
- package/dist/dump-Bh5k26VQ.js.map +0 -1
- package/dist/errors-Dfa3p78c.js +0 -78
- package/dist/errors-Dfa3p78c.js.map +0 -1
- package/dist/export-DtF5tDIM.js +0 -401
- package/dist/export-DtF5tDIM.js.map +0 -1
- package/dist/fsck-D_djMO5D.js +0 -279
- package/dist/fsck-D_djMO5D.js.map +0 -1
- package/dist/http-DGd5tbNs.js.map +0 -1
- package/dist/index-0rZcMBwy.d.ts +0 -115
- package/dist/index-BNRh23K9.d.ts +0 -162
- package/dist/index-BYk9oCNf.d.ts +0 -1112
- package/dist/indexes-Dn9hbGQG.d.ts +0 -22
- package/dist/inspect-6WZ-pC7-.js +0 -133
- package/dist/inspect-6WZ-pC7-.js.map +0 -1
- package/dist/log-tail-D98U1JBo.js +0 -522
- package/dist/log-tail-D98U1JBo.js.map +0 -1
- package/dist/maintenance-B4Dki6Ig.js +0 -2157
- package/dist/maintenance-B4Dki6Ig.js.map +0 -1
- package/dist/maintenance-B_e0T99L.d.ts +0 -537
- package/dist/maintenance-C7coQp4c.js +0 -1418
- package/dist/maintenance-C7coQp4c.js.map +0 -1
- package/dist/normalize-rjnZLwS4.js +0 -133
- package/dist/normalize-rjnZLwS4.js.map +0 -1
- package/dist/observability-BmflLCdF.js.map +0 -1
- package/dist/plan-a7PJHBCy.js.map +0 -1
- package/dist/query-rAtXNQQB.js +0 -1773
- package/dist/query-rAtXNQQB.js.map +0 -1
- package/dist/rebuild-index-BVzQSZlm.js +0 -81
- package/dist/rebuild-index-BVzQSZlm.js.map +0 -1
- package/dist/request-u0M51mhJ.js +0 -72
- package/dist/request-u0M51mhJ.js.map +0 -1
- package/dist/restore-R-4rbciV.js +0 -778
- package/dist/restore-R-4rbciV.js.map +0 -1
- package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
- package/dist/runtime-spec-Dsw2-n8S.js.map +0 -1
- package/dist/shared-secret-DgEicd3x.js.map +0 -1
- package/dist/src-BL_JoPTn.js.map +0 -1
- package/dist/src-CYHFDrKz.js +0 -536
- package/dist/src-CYHFDrKz.js.map +0 -1
- package/dist/src-DYZ4H1aF.js +0 -392
- package/dist/src-DYZ4H1aF.js.map +0 -1
- package/dist/subcommand-DoDA-K7d.js.map +0 -1
- package/dist/time-DUqvFMHq.js.map +0 -1
- package/dist/usage-DBV1eQHC.js.map +0 -1
- package/dist/validate-DtljsCh1.js.map +0 -1
- package/dist/wire-izfGZDvr.js.map +0 -1
package/dist/index-BYk9oCNf.d.ts
DELETED
|
@@ -1,1112 +0,0 @@
|
|
|
1
|
-
import { f as DocumentData, m as JSONValue, p as DocumentValue } from "./app-config-DyiFK3_k.js";
|
|
2
|
-
//#region packages/protocol/src/errors.d.ts
|
|
3
|
-
/**
|
|
4
|
-
* Discriminator for {@link BaerlyError}. Strings (not subclasses) so they
|
|
5
|
-
* survive cross-realm boundaries (e.g. a Web Worker) and so callers can
|
|
6
|
-
* pattern-match with grep-friendly equality.
|
|
7
|
-
*/
|
|
8
|
-
type BaerlyErrorCode = /** Caller-provided config or input is invalid (bad bucket, unsupported credential type, malformed URL, bucket not version-enabled when versioning was requested). */"InvalidConfig" /** Generic S3/HTTP transport failure (5xx, unexpected status, retries exhausted). */ | "NetworkError" /** S3 returned 403. Either credentials are wrong or the bucket policy denies the operation. */ | "AccessDenied" /** Server returned data that didn't parse (malformed XML, non-JSON body where JSON expected). */ | "InvalidResponse" /** Internal invariant violation — should not be reachable. File a bug. */ | "Internal"
|
|
9
|
-
/**
|
|
10
|
-
* Document body failed schema validation. Emitted by the table-API
|
|
11
|
-
* write verbs (`Collection.insert`, `Query.update`, `Collection.replace`) when
|
|
12
|
-
* the body is not valid JSON or contains an array where
|
|
13
|
-
* `DocumentValue` is required; also emitted when a collection has a
|
|
14
|
-
* declared `SchemaValidator` (via `Db.create({ collections })`) and
|
|
15
|
-
* the bound schema rejects the doc. In the schema-rejection case the
|
|
16
|
-
* error carries an `issues` array describing each failure. HTTP layer
|
|
17
|
-
* maps this to 400.
|
|
18
|
-
*/
|
|
19
|
-
| "SchemaError"
|
|
20
|
-
/**
|
|
21
|
-
* Write conflicted with current state: CAS retry budget exhausted,
|
|
22
|
-
* duplicate caller-supplied `_id`, or an already-existing guarded
|
|
23
|
-
* storage key. Check `BaerlyError.retriable` to decide whether the
|
|
24
|
-
* same logical operation should be retried.
|
|
25
|
-
*/
|
|
26
|
-
| "Conflict"
|
|
27
|
-
/**
|
|
28
|
-
* `Verifier` returned no identity. HTTP server maps to 401.
|
|
29
|
-
* Code is reserved here so the union locks.
|
|
30
|
-
*/
|
|
31
|
-
| "Unauthorized"
|
|
32
|
-
/**
|
|
33
|
-
* The addressed resource does not exist. HTTP server maps to 404.
|
|
34
|
-
* Emitted by the row-by-id read / update / delete handlers in
|
|
35
|
-
* `packages/server/src/http/router.ts` when the predicate
|
|
36
|
-
* `{ _id }` matches zero rows. Not a protocol invariant —
|
|
37
|
-
* callers may retry after creating the resource or treat as a
|
|
38
|
-
* miss depending on intent. The CLI maps this to the generic
|
|
39
|
-
* exit-2 "storage error" bucket, not the exit-3 "protocol
|
|
40
|
-
* invariant" bucket.
|
|
41
|
-
*/
|
|
42
|
-
| "NotFound"
|
|
43
|
-
/**
|
|
44
|
-
* Request body exceeded the server's size cap. HTTP server maps
|
|
45
|
-
* to 413. Cap is `MAX_BODY_BYTES` (1 MiB today; exported from
|
|
46
|
-
* `packages/server/src/http/router.ts`). The Node adapter
|
|
47
|
-
* enforces during the `node:http` stream pump so the process
|
|
48
|
-
* never materializes a multi-MiB body; Workers also rely on
|
|
49
|
-
* platform-side caps (16 MB free / 100 MB paid).
|
|
50
|
-
*/
|
|
51
|
-
| "PayloadTooLarge"
|
|
52
|
-
/**
|
|
53
|
-
* A predicate is structurally well-formed but contradicts itself —
|
|
54
|
-
* no document can match. Emitted by `validateWire` and
|
|
55
|
-
* `mergePredicateWires`. Triggers:
|
|
56
|
-
* - `{ clauses: [{op:"in", field:"priority", value:[]}] }` (empty `in` set)
|
|
57
|
-
* - an `eq` clause with a value outside the residual interval
|
|
58
|
-
* established by range clauses on the same field
|
|
59
|
-
* - merging `{op:"gt", value:10}` with `{op:"lt", value:5}` on the
|
|
60
|
-
* same field (empty interval)
|
|
61
|
-
* - merging two `in` clauses on the same field with empty intersection
|
|
62
|
-
*
|
|
63
|
-
* Conflicting equality across clauses (`eq:"open"` + `eq:"closed"` on
|
|
64
|
-
* the same field) surfaces as `InvalidConfig` rather than this code —
|
|
65
|
-
* the merger treats it as a caller-side configuration bug, not an
|
|
66
|
-
* algebraic contradiction.
|
|
67
|
-
*
|
|
68
|
-
* The HTTP layer treats this as a 400 (caller error). The distinct
|
|
69
|
-
* code lets downstream code short-circuit empty-by-construction
|
|
70
|
-
* without re-running the validator or parsing messages.
|
|
71
|
-
*/
|
|
72
|
-
| "UnsatisfiablePredicate"
|
|
73
|
-
/**
|
|
74
|
-
* A `useQuery` callback awaited a recorder terminal
|
|
75
|
-
* (`.get`/`.first`/`.all`/`.count`). The recorder runs once per
|
|
76
|
-
* render to capture the chain shape; it cannot survive an `await`
|
|
77
|
-
* because the proxy doesn't proxy across microtask boundaries. The
|
|
78
|
-
* recorder's terminal returns a thenable whose `.then` throws this
|
|
79
|
-
* error synchronously, converting what would otherwise be a silent
|
|
80
|
-
* spinner-hang into a render-time error the hook surfaces as
|
|
81
|
-
* `status: "error"`. Companion `baerly/no-await-in-use-query` lint
|
|
82
|
-
* flags the pattern at edit time. For compound reads, use
|
|
83
|
-
* `Promise.all` (parallel) or compose two `useQuery` calls with
|
|
84
|
-
* `useQuery.skip` (dependent).
|
|
85
|
-
*/
|
|
86
|
-
| "UseQueryAwaitedRecorder"
|
|
87
|
-
/**
|
|
88
|
-
* A write method (`.insert`/`.update`/`.replace`/`.delete`) was
|
|
89
|
-
* called on the recorder inside a `useQuery` callback. Writes
|
|
90
|
-
* inside reads are a programming error; the recorder rejects them
|
|
91
|
-
* synchronously from the discovery pass, before any I/O fires. Use
|
|
92
|
-
* `useMutation()` instead.
|
|
93
|
-
*/
|
|
94
|
-
| "UnexpectedWriteInQuery"
|
|
95
|
-
/**
|
|
96
|
-
* A `useMutation()` callback rejected with a non-`BaerlyError`
|
|
97
|
-
* throwable. The hook wraps the original throw under this code so
|
|
98
|
-
* the `error` slot is always a `BaerlyError`; the original value
|
|
99
|
-
* is preserved on `.cause`.
|
|
100
|
-
*/
|
|
101
|
-
| "MutationFailed";
|
|
102
|
-
/**
|
|
103
|
-
* The single error class thrown by baerly-storage. Discriminate by `code`, not
|
|
104
|
-
* `instanceof`: the code string survives `JSON.stringify` round-trips
|
|
105
|
-
* across Worker / iframe / postMessage realm boundaries, where each
|
|
106
|
-
* realm has its own `BaerlyError` constructor identity. IDB-restored
|
|
107
|
-
* writes can replay across realms, so `instanceof` would spuriously
|
|
108
|
-
* fail on a structurally-identical error from another realm.
|
|
109
|
-
*
|
|
110
|
-
* @example
|
|
111
|
-
* ```ts
|
|
112
|
-
* try {
|
|
113
|
-
* await db.collection("tickets").insert({ title: "hi" });
|
|
114
|
-
* } catch (err) {
|
|
115
|
-
* if (err instanceof BaerlyError && err.code === "Conflict") {
|
|
116
|
-
* // Check err.retriable; CAS can retry, duplicate _id cannot.
|
|
117
|
-
* }
|
|
118
|
-
* throw err;
|
|
119
|
-
* }
|
|
120
|
-
* ```
|
|
121
|
-
*/
|
|
122
|
-
declare class BaerlyError extends Error {
|
|
123
|
-
readonly code: BaerlyErrorCode;
|
|
124
|
-
readonly cause?: unknown;
|
|
125
|
-
/**
|
|
126
|
-
* Structured field-path issues, set only when `code === "SchemaError"`.
|
|
127
|
-
* Each entry's `path` is a dotted-key list (e.g. `["assignee", "team"]`
|
|
128
|
-
* or `["items", 3, "qty"]`) that targets the offending field on the
|
|
129
|
-
* input document. `message` is the validator-emitted human string.
|
|
130
|
-
*
|
|
131
|
-
* The HTTP layer's `mapError` renders these into the 400 body via
|
|
132
|
-
* the existing `HttpErrorEnvelope`; older callers that don't know
|
|
133
|
-
* about `issues` see a plain message-only error and stay correct.
|
|
134
|
-
*/
|
|
135
|
-
readonly issues?: ReadonlyArray<{
|
|
136
|
-
readonly path: ReadonlyArray<string | number>;
|
|
137
|
-
readonly message: string;
|
|
138
|
-
}>;
|
|
139
|
-
/**
|
|
140
|
-
* Raw HTTP status, set only by the client-side wire decoder when
|
|
141
|
-
* inflating an `HttpErrorEnvelope` into this class. Server-side
|
|
142
|
-
* throws never set it (the HTTP layer's `mapError` derives the
|
|
143
|
-
* outbound status from `code`). Useful for diagnostics — e.g. to
|
|
144
|
-
* distinguish 404-as-"no such row" from 404-as-"route not found".
|
|
145
|
-
* Discriminate by `code` for behavior; reach for `status` only when
|
|
146
|
-
* you genuinely need the wire value.
|
|
147
|
-
*/
|
|
148
|
-
readonly status?: number;
|
|
149
|
-
/** Canonical corrective action; crosses the wire via `HttpErrorEnvelope.error.resolution`. */
|
|
150
|
-
readonly resolution?: string;
|
|
151
|
-
private readonly retriableOverride;
|
|
152
|
-
/**
|
|
153
|
-
* Whether this error instance is retriable. Defaults from `code`, but
|
|
154
|
-
* context-sensitive throw sites can override it.
|
|
155
|
-
*/
|
|
156
|
-
get retriable(): boolean;
|
|
157
|
-
constructor(code: BaerlyErrorCode, message: string, cause?: unknown, issues?: ReadonlyArray<{
|
|
158
|
-
readonly path: ReadonlyArray<string | number>;
|
|
159
|
-
readonly message: string;
|
|
160
|
-
}>, status?: number, resolution?: string, retriableOverride?: boolean);
|
|
161
|
-
}
|
|
162
|
-
//#endregion
|
|
163
|
-
//#region packages/protocol/src/storage/types.d.ts
|
|
164
|
-
/**
|
|
165
|
-
* Object-storage abstraction. The protocol kernel writes through
|
|
166
|
-
* this and only this. Implementations: in-memory (testing), S3 HTTP
|
|
167
|
-
* (production), R2 binding (deferred), local-fs (deferred).
|
|
168
|
-
*
|
|
169
|
-
* Cancellation: every method accepts an optional AbortSignal.
|
|
170
|
-
* Implementations should respect it where feasible; consumers may
|
|
171
|
-
* ignore it. We thread it through from the start so we don't have
|
|
172
|
-
* to retrofit cancellation later.
|
|
173
|
-
*
|
|
174
|
-
* Encoding: bodies are `Uint8Array` (works in Workers + Node 24+),
|
|
175
|
-
* not `Buffer`. Result types are `readonly` — the kernel doesn't
|
|
176
|
-
* mutate what storage returns.
|
|
177
|
-
*
|
|
178
|
-
* Not-found is signalled by `null` (single discriminator), not by
|
|
179
|
-
* throwing. Other failure modes throw `BaerlyError`.
|
|
180
|
-
*/
|
|
181
|
-
interface Storage {
|
|
182
|
-
/**
|
|
183
|
-
* Fetch a single object. Returns `null` on not-found (404
|
|
184
|
-
* semantics). With `ifNoneMatch`, returns `null` if the current
|
|
185
|
-
* ETag matches (304 semantics — caller's cached copy is current).
|
|
186
|
-
* With `versionId`, fetches a specific historical version (only
|
|
187
|
-
* meaningful on a versioned S3 bucket; non-versioning impls may
|
|
188
|
-
* ignore). Other failure modes throw `BaerlyError`.
|
|
189
|
-
*/
|
|
190
|
-
get(key: string, opts?: StorageGetOptions): Promise<StorageGetResult | null>;
|
|
191
|
-
/**
|
|
192
|
-
* Write a single object. Returns the new ETag and, when the
|
|
193
|
-
* underlying transport surfaces it, the server's response time
|
|
194
|
-
* as `serverDate` (S3's `Date` header). The kernel uses
|
|
195
|
-
* `serverDate` to track adaptive clock-skew; impls may return
|
|
196
|
-
* `undefined` if no server clock is available. Use `ifMatch` for
|
|
197
|
-
* compare-and-swap (write only if the current ETag matches), or
|
|
198
|
-
* `ifNoneMatch: "*"` for create-only (write only if no object
|
|
199
|
-
* exists). Conflicts throw `BaerlyError` with HTTP 412 semantics.
|
|
200
|
-
*/
|
|
201
|
-
put(key: string, body: Uint8Array, opts?: StoragePutOptions): Promise<StoragePutResult>;
|
|
202
|
-
/**
|
|
203
|
-
* Delete a single object. Idempotent: deleting a missing key is
|
|
204
|
-
* not an error.
|
|
205
|
-
*/
|
|
206
|
-
delete(key: string, opts?: {
|
|
207
|
-
signal?: AbortSignal;
|
|
208
|
-
}): Promise<void>;
|
|
209
|
-
/**
|
|
210
|
-
* Lex-asc enumeration of keys with the given prefix. Pagination is
|
|
211
|
-
* implementation-internal; consumers iterate until exhaustion or
|
|
212
|
-
* `maxKeys`. `startAfter` (exclusive) is a strict-greater cursor.
|
|
213
|
-
*/
|
|
214
|
-
list(prefix: string, opts?: {
|
|
215
|
-
startAfter?: string;
|
|
216
|
-
maxKeys?: number;
|
|
217
|
-
signal?: AbortSignal;
|
|
218
|
-
}): AsyncIterable<StorageListEntry>;
|
|
219
|
-
}
|
|
220
|
-
interface StorageGetOptions {
|
|
221
|
-
readonly ifNoneMatch?: string;
|
|
222
|
-
/**
|
|
223
|
-
* Pin to a specific historical version. Maps to S3's
|
|
224
|
-
* `?versionId=…` query parameter on versioned buckets. Impls that
|
|
225
|
-
* don't model versions may ignore.
|
|
226
|
-
*/
|
|
227
|
-
readonly versionId?: string;
|
|
228
|
-
readonly signal?: AbortSignal;
|
|
229
|
-
}
|
|
230
|
-
interface StorageGetResult {
|
|
231
|
-
readonly body: Uint8Array;
|
|
232
|
-
readonly etag: string;
|
|
233
|
-
/**
|
|
234
|
-
* S3 `x-amz-version-id` of the returned object on versioned
|
|
235
|
-
* buckets; `undefined` for unversioned reads or impls without
|
|
236
|
-
* native versioning.
|
|
237
|
-
*/
|
|
238
|
-
readonly versionId?: string;
|
|
239
|
-
}
|
|
240
|
-
interface StoragePutResult {
|
|
241
|
-
readonly etag: string;
|
|
242
|
-
/**
|
|
243
|
-
* Server-reported response time, used by the kernel's adaptive
|
|
244
|
-
* clock-skew loop. Set by HTTP-backed impls from the response
|
|
245
|
-
* `Date` header; in-memory impls fill in the local wall clock.
|
|
246
|
-
* `undefined` if no clock signal is available.
|
|
247
|
-
*/
|
|
248
|
-
readonly serverDate?: Date;
|
|
249
|
-
/**
|
|
250
|
-
* S3 `x-amz-version-id` of the new object version on versioned
|
|
251
|
-
* buckets; `undefined` for unversioned writes or impls without
|
|
252
|
-
* native versioning.
|
|
253
|
-
*/
|
|
254
|
-
readonly versionId?: string;
|
|
255
|
-
}
|
|
256
|
-
interface StoragePutOptions {
|
|
257
|
-
/** CAS guard: write only if ETag matches. */
|
|
258
|
-
readonly ifMatch?: string;
|
|
259
|
-
/** Create-only guard: write only if no object exists. */
|
|
260
|
-
readonly ifNoneMatch?: "*";
|
|
261
|
-
readonly contentType?: string;
|
|
262
|
-
/** Cancel mid-flight; impls should respect when feasible. */
|
|
263
|
-
readonly signal?: AbortSignal;
|
|
264
|
-
}
|
|
265
|
-
interface StorageListEntry {
|
|
266
|
-
readonly key: string;
|
|
267
|
-
readonly etag: string;
|
|
268
|
-
/**
|
|
269
|
-
* Server's `Last-Modified` for the listed object, when the backend
|
|
270
|
-
* surfaces it. GC uses it to anchor a tombstone's `due_at` to the
|
|
271
|
-
* object's server-side write time (`gc.ts`); when absent, GC falls
|
|
272
|
-
* back to the local clock (`now()`). It is therefore an optional
|
|
273
|
-
* precision hint, never load-bearing for correctness — impls
|
|
274
|
-
* without a server clock (e.g. {@link MemoryStorage}) may omit it.
|
|
275
|
-
*
|
|
276
|
-
* The protocol's clock-skew handling rides on
|
|
277
|
-
* {@link StoragePutResult.serverDate} (the write-time server clock),
|
|
278
|
-
* not on this field.
|
|
279
|
-
*/
|
|
280
|
-
readonly lastModified?: Date;
|
|
281
|
-
}
|
|
282
|
-
//#endregion
|
|
283
|
-
//#region packages/protocol/src/coordination/current-json.d.ts
|
|
284
|
-
/**
|
|
285
|
-
* Per-collection control object. CAS-protected. One per
|
|
286
|
-
* `(tenant, collection)` key — for example
|
|
287
|
-
* `<tenant>/<collection>/current.json`. The compactor swaps snapshot
|
|
288
|
-
* generations by CAS-writing this object; the Writer reads it on every
|
|
289
|
-
* commit to find the snapshot pointer and a non-authoritative
|
|
290
|
-
* tail-probe floor. The numbered log create mints the next integer
|
|
291
|
-
* `seq`; no commit-path code CAS-advances `current.json`.
|
|
292
|
-
*
|
|
293
|
-
* The schema is forward-compatible: adding a new optional field is
|
|
294
|
-
* non-breaking. Renaming or removing a field requires bumping
|
|
295
|
-
* {@link CURRENT_JSON_SCHEMA_VERSION}; readers MUST reject
|
|
296
|
-
* unknown major versions with `BaerlyError{code:"InvalidResponse"}`.
|
|
297
|
-
*/
|
|
298
|
-
interface CurrentJson {
|
|
299
|
-
/**
|
|
300
|
-
* Schema version. Today: `3`. Bump on any breaking change to
|
|
301
|
-
* field semantics; readers must reject unknown major versions
|
|
302
|
-
* with `BaerlyError{code:"InvalidResponse"}`.
|
|
303
|
-
*/
|
|
304
|
-
schema_version: 3;
|
|
305
|
-
/**
|
|
306
|
-
* Pointer to the current snapshot generation. `null` before the
|
|
307
|
-
* first compaction has produced a snapshot — readers fall back
|
|
308
|
-
* to log-only replay. Shape is opaque-to-this-module; the
|
|
309
|
-
* compactor owns its interpretation.
|
|
310
|
-
*/
|
|
311
|
-
snapshot: string | null;
|
|
312
|
-
/**
|
|
313
|
-
* Non-authoritative monotone lower bound on the committed log tail.
|
|
314
|
-
* The authoritative tail is discovered by forward-probe (log-tail.ts);
|
|
315
|
-
* never trust this as the head. Durable advancement is owned by
|
|
316
|
-
* compaction folds, write-tick tail refreshes, and explicit
|
|
317
|
-
* operator/import paths; ordinary writer commits do not refresh it.
|
|
318
|
-
*/
|
|
319
|
-
tail_hint: number;
|
|
320
|
-
/**
|
|
321
|
-
* Lowest live log sequence number. Entries with `seq < log_seq_start`
|
|
322
|
-
* have been folded into the snapshot at {@link snapshot} (or, if
|
|
323
|
-
* `snapshot === null`, have been dropped because the collection was
|
|
324
|
-
* truncated). Readers walk `[log_seq_start, tail_hint)`. Always
|
|
325
|
-
* present on disk — fresh `current.json` writes via
|
|
326
|
-
* {@link createCurrentJson} set this to `0`; the compactor advances
|
|
327
|
-
* it on every fold.
|
|
328
|
-
*
|
|
329
|
-
* Invariants the compactor maintains:
|
|
330
|
-
* - `0 <= log_seq_start <= tail_hint`
|
|
331
|
-
* - `log_seq_start` advances monotonically (never decreases)
|
|
332
|
-
* - `log_seq_start > 0` implies `snapshot !== null` (the snapshot
|
|
333
|
-
* covers `[0, log_seq_start)`)
|
|
334
|
-
*/
|
|
335
|
-
log_seq_start: number;
|
|
336
|
-
/**
|
|
337
|
-
* Embedded write-fence epoch. See {@link WriterFence}.
|
|
338
|
-
*/
|
|
339
|
-
writer_fence: WriterFence;
|
|
340
|
-
/** Byte size of the snapshot pointed to by `snapshot`. */
|
|
341
|
-
snapshot_bytes: number;
|
|
342
|
-
/**
|
|
343
|
-
* Row count of the snapshot (= compactor `base.size`, free). With
|
|
344
|
-
* `tail_hint - log_seq_start` (trusted tail entries) this gives the
|
|
345
|
-
* fold's entry count for the ENTRY ceiling `E`. Seeded 0.
|
|
346
|
-
*/
|
|
347
|
-
snapshot_rows: number;
|
|
348
|
-
/**
|
|
349
|
-
* Optional compactor-stamped mean folded-entry byte size. Maintenance
|
|
350
|
-
* derives live-tail bytes as `entry_count × mean_entry_bytes` without
|
|
351
|
-
* an exact stored counter; absent until first fold.
|
|
352
|
-
*/
|
|
353
|
-
mean_entry_bytes?: number;
|
|
354
|
-
/**
|
|
355
|
-
* Baseline for rate-limiting the graduation defer-warn off SHARED
|
|
356
|
-
* durable state, not per-isolate memory. The warn fires when the
|
|
357
|
-
* observed/probed tail minus `last_warned_seq` reaches
|
|
358
|
-
* MAINTENANCE_WARN_INTERVAL_WRITES, and that firing CASes
|
|
359
|
-
* `last_warned_seq` to the observed/probed tail. Absent → 0.
|
|
360
|
-
*/
|
|
361
|
-
last_warned_seq?: number;
|
|
362
|
-
}
|
|
363
|
-
/**
|
|
364
|
-
* Fence-token sub-shape embedded in {@link CurrentJson}. The
|
|
365
|
-
* monotonically-bumped `epoch` is the only safety-critical field —
|
|
366
|
-
* `owner` is informational and may be missing in older records;
|
|
367
|
-
* `claimed_at` is the server response date at claim time, NOT the
|
|
368
|
-
* local clock; `lease_until` is reserved for manual rotation and is not
|
|
369
|
-
* consumed by the current kernel. Log entries are not stamped with this
|
|
370
|
-
* epoch; the fence is dormant authority metadata, not a reader replay
|
|
371
|
-
* filter.
|
|
372
|
-
*
|
|
373
|
-
* Borrowed from FoundationDB's `recoveryCount` on cstate, IsleDB's
|
|
374
|
-
* `writer_fence` on `manifest/CURRENT`, and TigerBeetle's VSR view
|
|
375
|
-
* number. In the earlier two-write commit design, every commit checked
|
|
376
|
-
* the epoch before continuing under `current.json` authority. Under
|
|
377
|
-
* single-write commit no production path reads or writes the fence.
|
|
378
|
-
*/
|
|
379
|
-
interface WriterFence {
|
|
380
|
-
/**
|
|
381
|
-
* Monotonic unsigned integer. Bumped only by an explicit
|
|
382
|
-
* {@link claimWriter} call — do NOT bump on every cold start, do
|
|
383
|
-
* NOT bump on every commit. Under single-write commit this is retained
|
|
384
|
-
* as an explicit admin/testing primitive only; no production commit
|
|
385
|
-
* path claims or verifies the fence.
|
|
386
|
-
*/
|
|
387
|
-
epoch: number;
|
|
388
|
-
/**
|
|
389
|
-
* Owner identifier — debug only, NOT consulted for safety.
|
|
390
|
-
* Suggested shape: `<worker_id>@<deploy_id>`. May be the empty
|
|
391
|
-
* string when claim provenance is unknown (e.g. initial
|
|
392
|
-
* creation). Safety derives from `epoch`, not from `owner`.
|
|
393
|
-
*/
|
|
394
|
-
owner: string;
|
|
395
|
-
/**
|
|
396
|
-
* ISO-8601 timestamp from the `StoragePutResult.serverDate` on
|
|
397
|
-
* the successful CAS PUT. **Never use `new Date()` or
|
|
398
|
-
* `Date.now()` to populate this field** — under multi-instance
|
|
399
|
-
* deployment the local clock may disagree with peers; the
|
|
400
|
-
* server's clock is the only one all instances share. Format
|
|
401
|
-
* via `serverDate.toISOString()`. The empty string `""` means
|
|
402
|
-
* "claim time unknown" — readers MUST treat it as such rather
|
|
403
|
-
* than parsing it.
|
|
404
|
-
*/
|
|
405
|
-
claimed_at: string;
|
|
406
|
-
/**
|
|
407
|
-
* Optional explicit lease horizon, also ISO-8601. Reserved for
|
|
408
|
-
* future manual rotation workflows; current code only writes
|
|
409
|
-
* the field through if a caller supplies it and does not read
|
|
410
|
-
* it.
|
|
411
|
-
*/
|
|
412
|
-
lease_until?: string;
|
|
413
|
-
}
|
|
414
|
-
/**
|
|
415
|
-
* Return shape from {@link readCurrentJson} et al.: the parsed JSON
|
|
416
|
-
* plus the ETag needed for a follow-up CAS write.
|
|
417
|
-
*/
|
|
418
|
-
interface CurrentJsonRead {
|
|
419
|
-
readonly json: CurrentJson;
|
|
420
|
-
readonly etag: string;
|
|
421
|
-
}
|
|
422
|
-
//#endregion
|
|
423
|
-
//#region packages/protocol/src/query/builder.d.ts
|
|
424
|
-
/**
|
|
425
|
-
* Callback-form predicate builder. Methods append clauses and
|
|
426
|
-
* return the same builder for chaining; chained calls AND-merge.
|
|
427
|
-
*
|
|
428
|
-
* The methods on this interface ARE the supported operator surface.
|
|
429
|
-
* Vocabulary additions (`or`, `not`, `regex`, `ne`, `exists`, ...)
|
|
430
|
-
* are intentionally absent — calling them is a TS2339 compile
|
|
431
|
-
* error, not a runtime rejection. The algebra is conjunction-only in
|
|
432
|
-
* perpetuity — see the API surface lock in
|
|
433
|
-
* docs/contributing/conventions/change-discipline.md.
|
|
434
|
-
*
|
|
435
|
-
* @template T - the document shape the predicate is keyed against.
|
|
436
|
-
*/
|
|
437
|
-
interface PredicateBuilder<T extends DocumentData = DocumentData> {
|
|
438
|
-
/**
|
|
439
|
-
* Strict equality on `field`. Use this for the in-callback
|
|
440
|
-
* equality clauses that the object-form would also support;
|
|
441
|
-
* mixing `q.eq(...)` with range / `in` clauses in one call is
|
|
442
|
-
* the canonical "mixed equality + range" pattern.
|
|
443
|
-
*/
|
|
444
|
-
eq<K extends Path<T>>(field: K, value: PathValue<T, K>): PredicateBuilder<T>;
|
|
445
|
-
/**
|
|
446
|
-
* Strict greater. `value` must be `string` or `number`; the
|
|
447
|
-
* intersection at the type level rejects `boolean` / `null`
|
|
448
|
-
* fields at the call site (`q.gt("done", true)` is a TS error
|
|
449
|
-
* on a `done: boolean` field).
|
|
450
|
-
*/
|
|
451
|
-
gt<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;
|
|
452
|
-
/** Inclusive greater. See {@link gt} for the value-type constraint. */
|
|
453
|
-
gte<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;
|
|
454
|
-
/** Strict less. See {@link gt} for the value-type constraint. */
|
|
455
|
-
lt<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;
|
|
456
|
-
/** Inclusive less. See {@link gt} for the value-type constraint. */
|
|
457
|
-
lte<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;
|
|
458
|
-
/**
|
|
459
|
-
* Set membership. Empty array is `UnsatisfiablePredicate` at
|
|
460
|
-
* normalise time — the validator emits the error eagerly so the
|
|
461
|
-
* caller sees it at the `.where(...)` call site, not later.
|
|
462
|
-
*/
|
|
463
|
-
in<K extends Path<T>>(field: K, values: ReadonlyArray<PathValue<T, K>>): PredicateBuilder<T>;
|
|
464
|
-
}
|
|
465
|
-
/**
|
|
466
|
-
* Argument shape accepted by `.where(...)`. Either the object-literal
|
|
467
|
-
* equality form ({@link Predicate}) or a callback that drives a
|
|
468
|
-
* {@link PredicateBuilder} and returns it (the chain terminator).
|
|
469
|
-
*/
|
|
470
|
-
type PredicateArg<T extends DocumentData> = Predicate<T> | ((q: PredicateBuilder<T>) => PredicateBuilder<T>);
|
|
471
|
-
//#endregion
|
|
472
|
-
//#region packages/protocol/src/collection-api.d.ts
|
|
473
|
-
/**
|
|
474
|
-
* Handle on one collection. The common single-row case lives
|
|
475
|
-
* here as direct verbs (`get(id)`, `update(id, patch)`,
|
|
476
|
-
* `replace(id, doc)`, `delete(id)`) plus whole-collection reads
|
|
477
|
-
* (`first()`, `all()`, `count()`). For bulk-by-predicate mutation —
|
|
478
|
-
* or for chained `.where()` / `.order()` / `.limit()` reads — call
|
|
479
|
-
* the modifier verbs to get a {@link Query} back.
|
|
480
|
-
*
|
|
481
|
-
* @template T — the document shape. Documents always carry an
|
|
482
|
-
* auto-generated `_id` (UUIDv7); the type system
|
|
483
|
-
* treats `_id` as optional on `insert` (server fills
|
|
484
|
-
* it in) and required on read.
|
|
485
|
-
*/
|
|
486
|
-
interface Collection<T extends DocumentData = DocumentData> {
|
|
487
|
-
readonly name: string;
|
|
488
|
-
/**
|
|
489
|
-
* First document in the whole collection or `undefined` when the
|
|
490
|
-
* collection is empty. Equivalent to `.where({}).first()`.
|
|
491
|
-
*
|
|
492
|
-
* @example
|
|
493
|
-
* ```ts
|
|
494
|
-
* const any = await db.collection("tickets").first();
|
|
495
|
-
* ```
|
|
496
|
-
*/
|
|
497
|
-
first(): Promise<T | undefined>;
|
|
498
|
-
/**
|
|
499
|
-
* Every document in the whole collection. Equivalent to
|
|
500
|
-
* `.where({}).all()`. No implicit cap — prefer
|
|
501
|
-
* `.where(p).limit(n).all()` on large collections.
|
|
502
|
-
*
|
|
503
|
-
* @example
|
|
504
|
-
* ```ts
|
|
505
|
-
* const all = await db.collection("tickets").all();
|
|
506
|
-
* ```
|
|
507
|
-
*/
|
|
508
|
-
all(): Promise<T[]>;
|
|
509
|
-
/**
|
|
510
|
-
* Count every row in the collection (equivalent to `.where({}).count()`).
|
|
511
|
-
*
|
|
512
|
-
* @example
|
|
513
|
-
* ```ts
|
|
514
|
-
* const total = await db.collection("tickets").count();
|
|
515
|
-
* ```
|
|
516
|
-
*/
|
|
517
|
-
count(): Promise<number>;
|
|
518
|
-
/**
|
|
519
|
-
* Fetch one document by primary key. Returns `undefined` when the
|
|
520
|
-
* id is unknown — does not throw `NotFound`.
|
|
521
|
-
*
|
|
522
|
-
* @example
|
|
523
|
-
* ```ts
|
|
524
|
-
* const ticket = await db.collection("tickets").get(id);
|
|
525
|
-
* if (ticket === undefined) {
|
|
526
|
-
* // row not in this collection
|
|
527
|
-
* }
|
|
528
|
-
* ```
|
|
529
|
-
*/
|
|
530
|
-
get(id: string): Promise<T | undefined>;
|
|
531
|
-
/**
|
|
532
|
-
* Filter rows. Two shapes:
|
|
533
|
-
*
|
|
534
|
-
* - **Object literal** — equality only. Top-level, dotted-path,
|
|
535
|
-
* or nested-literal sub-predicate.
|
|
536
|
-
* - **Callback DSL** — `q => q.eq(...).gt(...).in(...)`. The
|
|
537
|
-
* operator vocabulary (`eq` / `gt` / `gte` / `lt` / `lte` /
|
|
538
|
-
* `in`) lives here. Chained calls AND-merge inside one
|
|
539
|
-
* callback; chained `.where(...).where(...)` AND-merges
|
|
540
|
-
* across calls and across shapes.
|
|
541
|
-
*
|
|
542
|
-
* Methods that do not exist on {@link PredicateBuilder}
|
|
543
|
-
* (`or`, `not`, `regex`, `ne`, `exists`, ...) are intentionally
|
|
544
|
-
* absent — invoking them is a TS compile error.
|
|
545
|
-
*
|
|
546
|
-
* @example
|
|
547
|
-
* ```ts
|
|
548
|
-
* db.collection("tickets").where({ status: "open" }).all();
|
|
549
|
-
* db.collection("tickets").where({ "assignee.team": "platform" }).all();
|
|
550
|
-
* db.collection("tickets").where(q => q.gte("count", 1).lt("count", 10)).all();
|
|
551
|
-
* db.collection("tickets").where(q => q.in("status", ["open", "pending"])).all();
|
|
552
|
-
* db.collection("tickets")
|
|
553
|
-
* .where({ status: "open" })
|
|
554
|
-
* .where(q => q.gte("priority", 5))
|
|
555
|
-
* .all();
|
|
556
|
-
* ```
|
|
557
|
-
*/
|
|
558
|
-
where(predicate: PredicateArg<T>): Query<T>;
|
|
559
|
-
/** Order modifier; last call wins. */
|
|
560
|
-
order(spec: OrderSpec<T>): Query<T>;
|
|
561
|
-
/** Limit modifier; last call wins. */
|
|
562
|
-
limit(n: number): Query<T>;
|
|
563
|
-
/**
|
|
564
|
-
* Insert a new document. UUIDv7 auto-id on `_id`; caller can
|
|
565
|
-
* supply `_id` and the server honours it. Returns the new id.
|
|
566
|
-
*
|
|
567
|
-
* @throws BaerlyError{code: "Conflict"} — `_id` collision on
|
|
568
|
-
* caller-supplied id.
|
|
569
|
-
* @throws BaerlyError{code: "SchemaError"} — malformed JSON, or
|
|
570
|
-
* schema-validation failure (when a schema is declared
|
|
571
|
-
* for the collection via `Db.create({ collections })`).
|
|
572
|
-
*
|
|
573
|
-
* @example
|
|
574
|
-
* ```ts
|
|
575
|
-
* const { _id } = await db.collection("tickets").insert({
|
|
576
|
-
* status: "open",
|
|
577
|
-
* title: "Ship the docs",
|
|
578
|
-
* });
|
|
579
|
-
* ```
|
|
580
|
-
*/
|
|
581
|
-
insert(doc: Partial<T> & DocumentData): Promise<{
|
|
582
|
-
_id: string;
|
|
583
|
-
}>;
|
|
584
|
-
/**
|
|
585
|
-
* JSON-merge-patch (RFC 7386) applied to one row by primary key.
|
|
586
|
-
* For predicate-aware bulk mutation, use
|
|
587
|
-
* `.where(predicate).update(patch)` on {@link Query}.
|
|
588
|
-
*
|
|
589
|
-
* @throws BaerlyError{code: "Conflict"} — concurrent write lost
|
|
590
|
-
* the CAS race. Caller's choice whether to retry.
|
|
591
|
-
* @throws BaerlyError{code: "SchemaError"} — patch produced an
|
|
592
|
-
* invalid doc.
|
|
593
|
-
*
|
|
594
|
-
* @example
|
|
595
|
-
* ```ts
|
|
596
|
-
* const { modified } = await db.collection("tickets")
|
|
597
|
-
* .update(id, { status: "closed" });
|
|
598
|
-
* ```
|
|
599
|
-
*/
|
|
600
|
-
update(id: string, patch: Partial<T>): Promise<{
|
|
601
|
-
modified: number;
|
|
602
|
-
}>;
|
|
603
|
-
/**
|
|
604
|
-
* Whole-document replace on one row by primary key. Throws
|
|
605
|
-
* `BaerlyError{code:"NotFound"}` when no row exists at `id`.
|
|
606
|
-
*
|
|
607
|
-
* @example
|
|
608
|
-
* ```ts
|
|
609
|
-
* await db.collection("tickets")
|
|
610
|
-
* .replace(id, { _id: id, status: "open", title: "Rewrite" });
|
|
611
|
-
* ```
|
|
612
|
-
*/
|
|
613
|
-
replace(id: string, doc: T): Promise<void>;
|
|
614
|
-
/**
|
|
615
|
-
* Delete one row by primary key. Returns `{ deleted: 0 }` when the
|
|
616
|
-
* id is unknown rather than throwing. For predicate-aware bulk
|
|
617
|
-
* delete, use `.where(predicate).delete()` on {@link Query}.
|
|
618
|
-
*
|
|
619
|
-
* @example
|
|
620
|
-
* ```ts
|
|
621
|
-
* const { deleted } = await db.collection("tickets").delete(id);
|
|
622
|
-
* ```
|
|
623
|
-
*/
|
|
624
|
-
delete(id: string): Promise<{
|
|
625
|
-
deleted: number;
|
|
626
|
-
}>;
|
|
627
|
-
}
|
|
628
|
-
/**
|
|
629
|
-
* Decrementing depth markers for {@link Path}'s recursion cap.
|
|
630
|
-
* The default of 4 means dotted paths up to `a.b.c.d.e` are legal;
|
|
631
|
-
* `a.b.c.d.e.f` is rejected. Keeps `tsgo` recursion bounded.
|
|
632
|
-
* @internal
|
|
633
|
-
*/
|
|
634
|
-
type _PathDepth = [never, 0, 1, 2, 3, 4];
|
|
635
|
-
/**
|
|
636
|
-
* True when `V` is a value position that should terminate {@link Path}
|
|
637
|
-
* recursion. Primitives, `null`, and arrays are leaves — we do not
|
|
638
|
-
* descend into array indices via dotted-path keys (the runtime
|
|
639
|
-
* evaluator treats every segment as an object key, so `"tags.0"`
|
|
640
|
-
* would resolve to `arr["0"]`, which works but is poor DX).
|
|
641
|
-
* @internal
|
|
642
|
-
*/
|
|
643
|
-
type _IsPathLeaf<V> = V extends string | number | boolean | null ? true : V extends ReadonlyArray<unknown> ? true : false;
|
|
644
|
-
/**
|
|
645
|
-
* Strip the string index signature from `T` so {@link Path} can
|
|
646
|
-
* iterate over named keys only. Without this, `T = DocumentData &
|
|
647
|
-
* UserShape` (the canonical user-doc shape across the kernel)
|
|
648
|
-
* collapses `keyof T` to `string` and defeats narrowing.
|
|
649
|
-
*
|
|
650
|
-
* The pattern `string extends K ? never : K` is the standard TS
|
|
651
|
-
* idiom: the parameter of a `[k: string]: …` signature has type
|
|
652
|
-
* `string`, so `string extends string` is true for it (excluded);
|
|
653
|
-
* any literal key like `"status"` does not extend `string`
|
|
654
|
-
* (kept).
|
|
655
|
-
* @internal
|
|
656
|
-
*/
|
|
657
|
-
type _StripIndex<T> = { [K in keyof T as string extends K ? never : K]: T[K] };
|
|
658
|
-
/**
|
|
659
|
-
* Recursively-derived union of every legal dotted-path key over `T`.
|
|
660
|
-
* Depth-capped at 5 segments (`a.b.c.d.e` legal, `a.b.c.d.e.f` not) so
|
|
661
|
-
* the type checker doesn't blow recursion limits on deep schemas.
|
|
662
|
-
*
|
|
663
|
-
* When `T` is just `DocumentData` (the default — no user shape
|
|
664
|
-
* passed), `_StripIndex<T>` is `{}` and `_Keys<T>` is `never`. In
|
|
665
|
-
* that case we fall through to bare `string` keys, preserving
|
|
666
|
-
* today's open-keyed default behavior.
|
|
667
|
-
* @internal
|
|
668
|
-
*/
|
|
669
|
-
type _AllPaths<T, D extends _PathDepth[number] = 4> = [D] extends [never] ? never : T extends object ? keyof _StripIndex<T> & string extends never ? string : { [K in keyof _StripIndex<T> & string]: _IsPathLeaf<NonNullable<T[K]>> extends true ? K : K | `${K}.${_AllPaths<NonNullable<T[K]>, _PathDepth[D]>}` }[keyof _StripIndex<T> & string] : never;
|
|
670
|
-
/**
|
|
671
|
-
* Legal dotted-path keys over `T`, with the root-level `_id` filtered
|
|
672
|
-
* out so the top-level shape no longer accepts `{ _id: "x" }`. Nested
|
|
673
|
-
* `_id` paths (e.g. `"author._id"`) survive — only the bare `"_id"`
|
|
674
|
-
* head and any literal `"_id.<rest>"` head are excluded (no
|
|
675
|
-
* `_id.<rest>` shape exists today since `_id` is a string leaf, but
|
|
676
|
-
* the template-string guard keeps the contract intact if the doc
|
|
677
|
-
* shape ever changes).
|
|
678
|
-
*
|
|
679
|
-
* When `T = DocumentData` (no user-supplied shape), `_AllPaths<T>`
|
|
680
|
-
* degrades to bare `string` and the `Exclude<>` wrapper leaves that
|
|
681
|
-
* branch unchanged — open-keyed predicates still typecheck.
|
|
682
|
-
* @internal
|
|
683
|
-
*/
|
|
684
|
-
type Path<T, D extends _PathDepth[number] = 4> = Exclude<_AllPaths<T, D>, "_id" | `_id.${string}`>;
|
|
685
|
-
/**
|
|
686
|
-
* Resolves the leaf value type at dotted path `P` through `T`.
|
|
687
|
-
* Paired with {@link Path} to type the value side of
|
|
688
|
-
* {@link Predicate}. `NonNullable` collapses optional intermediate
|
|
689
|
-
* fields so `"a.b"` resolves through `{ a?: { b: number } }`.
|
|
690
|
-
*
|
|
691
|
-
* Falls back to `DocumentValue` when `P` does not resolve to a
|
|
692
|
-
* named key — this only happens when `Path<T> = string` (no user
|
|
693
|
-
* shape), in which case any string is legal and the value side
|
|
694
|
-
* widens to `DocumentValue` to match today's default.
|
|
695
|
-
* @internal
|
|
696
|
-
*/
|
|
697
|
-
type PathValue<T, P extends string> = P extends `${infer H}.${infer R}` ? H extends keyof T ? PathValue<NonNullable<T[H]>, R> : never : P extends keyof T ? T[P] : DocumentValue;
|
|
698
|
-
/**
|
|
699
|
-
* Recursive partial sub-predicate. The value side of a nested
|
|
700
|
-
* predicate clause: every nested key is optional, and recurses into
|
|
701
|
-
* objects. `_SubPredicate<{a: number, b: {c: string}}>` admits
|
|
702
|
-
* `{a: 1}`, `{b: {c: "x"}}`, and `{a: 1, b: {c: "x"}}` — the same
|
|
703
|
-
* open-world matching the matcher delivers at the wire level
|
|
704
|
-
* (`{ assignee: { team: "x" } }` matches docs where
|
|
705
|
-
* `assignee.team === "x"`, ignoring other keys on `assignee`).
|
|
706
|
-
*
|
|
707
|
-
* Recurses over `keyof T` directly (NOT through `Path<T>`) so the
|
|
708
|
-
* root-level `_id` exclusion does not propagate — a nested `_id`
|
|
709
|
-
* names the primary key of an embedded reference and remains
|
|
710
|
-
* queryable (`.where({ author: { _id: "u1" } })` typechecks).
|
|
711
|
-
* @internal
|
|
712
|
-
*/
|
|
713
|
-
type _SubPredicate<T> = T extends object ? T extends ReadonlyArray<unknown> ? never : { readonly [K in keyof _StripIndex<T> & string]?: T[K] | _SubPredicate<T[K]> } : never;
|
|
714
|
-
/**
|
|
715
|
-
* Equality-only predicate over a document shape. Object-form
|
|
716
|
-
* accepts:
|
|
717
|
-
*
|
|
718
|
-
* - top-level equality: `{ status: "open" }`
|
|
719
|
-
* - dotted-path equality: `{ "assignee.team": "platform" }`
|
|
720
|
-
* - nested literal sub-predicates: `{ assignee: { team: "platform" } }`
|
|
721
|
-
* — the normaliser flattens to dotted-path `eq` clauses; the
|
|
722
|
-
* nested object may carry only a subset of keys (open-world
|
|
723
|
-
* matching against the document).
|
|
724
|
-
*
|
|
725
|
-
* **Operator vocabulary moved to the callback form.** Range / `in`
|
|
726
|
-
* / mixed eq+range queries write
|
|
727
|
-
* `.where(q => q.gt("priority", 5).in("status", ["open", "pending"]))`.
|
|
728
|
-
* The methods on {@link PredicateBuilder} ARE the supported vocabulary
|
|
729
|
-
* — there is no `$`-keyed object surface, so a method we did not
|
|
730
|
-
* write cannot be called.
|
|
731
|
-
*
|
|
732
|
-
* **No top-level boolean connectives.** `or` / `not` are
|
|
733
|
-
* intentionally absent. Use:
|
|
734
|
-
* - `q.in(field, ["a", "b"])` for OR over one field.
|
|
735
|
-
* - Chained `.where(p1).where(p2)` for AND across multiple
|
|
736
|
-
* predicates — the chain AND-merges.
|
|
737
|
-
*
|
|
738
|
-
* **Depth cap.** Dotted paths are limited to 5 segments
|
|
739
|
-
* (`a.b.c.d.e` legal, `a.b.c.d.e.f` not). Real doc-DB schemas rarely
|
|
740
|
-
* exceed 2–3 levels.
|
|
741
|
-
*/
|
|
742
|
-
type Predicate<T extends DocumentData = DocumentData> = { readonly [P in Path<T>]?: PathValue<T, P> extends DocumentValue ? PathValue<T, P> | _SubPredicate<PathValue<T, P>> : DocumentValue };
|
|
743
|
-
/** Order specifier. Top-level fields only on day one. */
|
|
744
|
-
type OrderSpec<T extends DocumentData = DocumentData> = { readonly [K in keyof T]?: "asc" | "desc" };
|
|
745
|
-
/**
|
|
746
|
-
* `Collection<T>` after at least one modifier. Carries predicate /
|
|
747
|
-
* order / limit state forward. Modifiers compose; verbs are
|
|
748
|
-
* terminal. Mutation verbs here are **predicate-aware bulk** — they
|
|
749
|
-
* apply to every matching row. For the common single-row case
|
|
750
|
-
* (`{ _id }`), prefer {@link Collection.update} / {@link Collection.replace} /
|
|
751
|
-
* {@link Collection.delete}.
|
|
752
|
-
*/
|
|
753
|
-
interface Query<T extends DocumentData = DocumentData> {
|
|
754
|
-
where(predicate: PredicateArg<T>): Query<T>;
|
|
755
|
-
order(spec: OrderSpec<T>): Query<T>;
|
|
756
|
-
limit(n: number): Query<T>;
|
|
757
|
-
/**
|
|
758
|
-
* First match or `undefined`. Equivalent to `.limit(1).all()[0]`.
|
|
759
|
-
*
|
|
760
|
-
* @example
|
|
761
|
-
* ```ts
|
|
762
|
-
* const oldest = await db.collection("tickets")
|
|
763
|
-
* .where({ status: "open" })
|
|
764
|
-
* .order({ commit_ts: "asc" })
|
|
765
|
-
* .first();
|
|
766
|
-
* ```
|
|
767
|
-
*/
|
|
768
|
-
first(): Promise<T | undefined>;
|
|
769
|
-
/**
|
|
770
|
-
* Every matching document, respecting `order` and `limit`. No
|
|
771
|
-
* implicit cap — callers should always pair `.all()` with
|
|
772
|
-
* `.limit(n)` on large collections.
|
|
773
|
-
*
|
|
774
|
-
* @example
|
|
775
|
-
* ```ts
|
|
776
|
-
* const open = await db.collection("tickets")
|
|
777
|
-
* .where({ status: "open" })
|
|
778
|
-
* .order({ commit_ts: "desc" })
|
|
779
|
-
* .limit(50)
|
|
780
|
-
* .all();
|
|
781
|
-
* ```
|
|
782
|
-
*/
|
|
783
|
-
all(): Promise<T[]>;
|
|
784
|
-
/**
|
|
785
|
-
* Count matching rows. Cheaper than `(await all()).length`.
|
|
786
|
-
*
|
|
787
|
-
* @example
|
|
788
|
-
* ```ts
|
|
789
|
-
* const open = await db.collection("tickets")
|
|
790
|
-
* .where({ status: "open" })
|
|
791
|
-
* .count();
|
|
792
|
-
* ```
|
|
793
|
-
*/
|
|
794
|
-
count(): Promise<number>;
|
|
795
|
-
/**
|
|
796
|
-
* Predicate-aware bulk mutation: JSON-merge-patch (RFC 7386)
|
|
797
|
-
* applied to every matching doc. Atomic per row. `null` at any
|
|
798
|
-
* field deletes it. For the single-row case prefer
|
|
799
|
-
* {@link Collection.update}(id, patch).
|
|
800
|
-
*
|
|
801
|
-
* @throws BaerlyError{code: "Conflict"} — concurrent write lost
|
|
802
|
-
* the CAS race. Caller's choice whether to retry.
|
|
803
|
-
* @throws BaerlyError{code: "SchemaError"} — patch produced an
|
|
804
|
-
* invalid doc.
|
|
805
|
-
*
|
|
806
|
-
* @example
|
|
807
|
-
* ```ts
|
|
808
|
-
* const { modified } = await db.collection("tickets")
|
|
809
|
-
* .where({ status: "open" })
|
|
810
|
-
* .update({ status: "closed", closed_at: new Date().toISOString() });
|
|
811
|
-
* ```
|
|
812
|
-
*/
|
|
813
|
-
update(patch: Partial<T>): Promise<{
|
|
814
|
-
modified: number;
|
|
815
|
-
}>;
|
|
816
|
-
/**
|
|
817
|
-
* Predicate-aware bulk delete: every matching document. For the
|
|
818
|
-
* single-row case prefer {@link Collection.delete}(id).
|
|
819
|
-
*
|
|
820
|
-
* @example
|
|
821
|
-
* ```ts
|
|
822
|
-
* const { deleted } = await db.collection("tickets")
|
|
823
|
-
* .where({ status: "closed" })
|
|
824
|
-
* .delete();
|
|
825
|
-
* ```
|
|
826
|
-
*/
|
|
827
|
-
delete(): Promise<{
|
|
828
|
-
deleted: number;
|
|
829
|
-
}>;
|
|
830
|
-
}
|
|
831
|
-
//#endregion
|
|
832
|
-
//#region packages/protocol/src/storage/memory.d.ts
|
|
833
|
-
/** Options for {@link MemoryStorage}. */
|
|
834
|
-
interface MemoryStorageOptions {
|
|
835
|
-
/**
|
|
836
|
-
* Acknowledge the store is intentionally ephemeral — required to
|
|
837
|
-
* construct in a detected deployment ({@link isDeployedEnv}); ignored in
|
|
838
|
-
* dev/test. Env equivalent: `BAERLY_ALLOW_EPHEMERAL_STORAGE=true`.
|
|
839
|
-
*/
|
|
840
|
-
ephemeral?: boolean;
|
|
841
|
-
}
|
|
842
|
-
/**
|
|
843
|
-
* In-memory `Storage`. The randomized property test runs against
|
|
844
|
-
* this; it must be deterministic — no clocks beyond the caller's,
|
|
845
|
-
* no randomness, no I/O.
|
|
846
|
-
*
|
|
847
|
-
* ETags are a monotonically increasing hex counter formatted in the
|
|
848
|
-
* `"<hex>"` shape S3 returns (the surrounding double-quotes are part
|
|
849
|
-
* of the ETag header value). Keys are stored verbatim.
|
|
850
|
-
*
|
|
851
|
-
* **Test-confidence caveat:** every method resolves on the microtask
|
|
852
|
-
* queue with no real concurrency, so `put` reads `existing` and writes
|
|
853
|
-
* back with no interleaving. MemoryStorage therefore CANNOT exercise the
|
|
854
|
-
* compare-and-swap race the writer-fence model depends on — two writers
|
|
855
|
-
* contending on one `current.json` always serialize here, so a green run
|
|
856
|
-
* is necessary but not sufficient. That race is covered only by the
|
|
857
|
-
* randomized integration tests against real S3 / Minio
|
|
858
|
-
* (`tests/integration/randomized.test.ts`, `node-minio` variant).
|
|
859
|
-
* Relatedly, `serverDate` returns the local clock, not an independent
|
|
860
|
-
* server clock (see the `put` return below).
|
|
861
|
-
*/
|
|
862
|
-
declare class MemoryStorage implements Storage {
|
|
863
|
-
#private;
|
|
864
|
-
constructor(opts?: MemoryStorageOptions);
|
|
865
|
-
get(key: string, opts?: StorageGetOptions): Promise<StorageGetResult | null>;
|
|
866
|
-
put(key: string, body: Uint8Array, opts?: StoragePutOptions): Promise<StoragePutResult>;
|
|
867
|
-
delete(key: string, opts?: {
|
|
868
|
-
signal?: AbortSignal;
|
|
869
|
-
}): Promise<void>;
|
|
870
|
-
list(prefix: string, opts?: {
|
|
871
|
-
startAfter?: string;
|
|
872
|
-
maxKeys?: number;
|
|
873
|
-
signal?: AbortSignal;
|
|
874
|
-
}): AsyncIterable<StorageListEntry>;
|
|
875
|
-
/**
|
|
876
|
-
* Test-only: drop all objects.
|
|
877
|
-
* @internal
|
|
878
|
-
*/
|
|
879
|
-
_clear(): void;
|
|
880
|
-
}
|
|
881
|
-
//#endregion
|
|
882
|
-
//#region packages/protocol/src/verifier.d.ts
|
|
883
|
-
/**
|
|
884
|
-
* Result of a successful {@link Verifier} call. Returned when the
|
|
885
|
-
* request carries valid credentials; replaced with `null` on
|
|
886
|
-
* failure.
|
|
887
|
-
*/
|
|
888
|
-
interface VerifierResult {
|
|
889
|
-
/**
|
|
890
|
-
* Tenant identifier. Must be non-empty and contain no `/` (the
|
|
891
|
-
* key-segment separator).
|
|
892
|
-
*/
|
|
893
|
-
readonly tenantPrefix: string;
|
|
894
|
-
/**
|
|
895
|
-
* Per-Verifier identity payload. Opaque to the protocol kernel;
|
|
896
|
-
* the caller-defined shape is whatever the Verifier factory
|
|
897
|
-
* chooses to return.
|
|
898
|
-
*/
|
|
899
|
-
readonly identity: unknown;
|
|
900
|
-
}
|
|
901
|
-
/**
|
|
902
|
-
* Auth seam. Given an inbound {@link Request}, return either a
|
|
903
|
-
* {@link VerifierResult} (authenticated) or `null` (rejected).
|
|
904
|
-
*
|
|
905
|
-
* One function, one responsibility — auth in baerly is not a
|
|
906
|
-
* middleware chain. The HTTP dispatcher invokes the
|
|
907
|
-
* configured `Verifier` exactly once per request, before any
|
|
908
|
-
* `Storage` I/O, and either constructs a tenant-scoped `Db` or
|
|
909
|
-
* returns 401 `BaerlyError{code:"Unauthorized"}`.
|
|
910
|
-
*
|
|
911
|
-
* `Request` is the standard `globalThis.Request` — the same shape
|
|
912
|
-
* used by Cloudflare Workers, Node 24+, Bun, Deno, and browsers.
|
|
913
|
-
* The kernel does **not** depend on `node:http`, `R2Bucket`, or
|
|
914
|
-
* any platform binding. Preset factories that need platform
|
|
915
|
-
* primitives (e.g. CF Access reads the `Cf-Access-Jwt-Assertion`
|
|
916
|
-
* header; SigV4 verifies against a SHA-256 of the body) compose on
|
|
917
|
-
* top.
|
|
918
|
-
*
|
|
919
|
-
* **Workers-types caveat.** `@cloudflare/workers-types` augments the
|
|
920
|
-
* global `Request` with the generic parameters
|
|
921
|
-
* `Request<CfHostMetadata, Cf>`. A Worker `fetch` handler receives
|
|
922
|
-
* `req: Request<CfHostMetadata, Cf>`, but a `Verifier` declared in
|
|
923
|
-
* user code resolves to `Request<unknown, CfProperties<unknown>>` —
|
|
924
|
-
* the same runtime object, narrowed differently by the type system.
|
|
925
|
-
* `baerlyWorker` handles this internally; you only see it if you
|
|
926
|
-
* intercept routes in your own Worker `fetch` before forwarding to
|
|
927
|
-
* `baerlyWorker`. In that case call the verifier with a one-line
|
|
928
|
-
* cast: `await verifier(req as unknown as Request)`. The runtime
|
|
929
|
-
* shape is identical; the cast is purely a generic-narrowing nudge.
|
|
930
|
-
*
|
|
931
|
-
* **Errors.** A `Verifier` SHOULD return `null` for any
|
|
932
|
-
* unauthenticated outcome — missing header, bad signature, expired
|
|
933
|
-
* token, IP outside allowlist. It MAY throw an `BaerlyError` for
|
|
934
|
-
* configuration problems (the IdP's JWKS endpoint is unreachable,
|
|
935
|
-
* the shared-secret env var is missing). Throws propagate to the
|
|
936
|
-
* dispatcher, which maps them to 500 + `code:"Internal"`. The
|
|
937
|
-
* dispatcher distinguishes "auth said no" (null → 401) from "auth
|
|
938
|
-
* is broken" (throw → 500) on purpose: the first is a client
|
|
939
|
-
* problem, the second is an operator problem.
|
|
940
|
-
*
|
|
941
|
-
* **Idempotence.** A `Verifier` MUST be safe to call multiple times
|
|
942
|
-
* for the same `Request`. Preset factories that decode JWTs cache
|
|
943
|
-
* the result on the request via a `WeakMap` if the cost is
|
|
944
|
-
* material.
|
|
945
|
-
*
|
|
946
|
-
* Preset factories — `cloudflareAccess`, `bearerJwt`,
|
|
947
|
-
* `sharedSecret` — live in `@gusto/baerly-storage/auth`
|
|
948
|
-
* (`packages/server/src/auth/presets/`). The kernel owns the type;
|
|
949
|
-
* the server owns the factories.
|
|
950
|
-
*
|
|
951
|
-
* @example
|
|
952
|
-
* ```ts
|
|
953
|
-
* import type { Verifier } from "baerly-storage";
|
|
954
|
-
*
|
|
955
|
-
* // A trivial Verifier that pins every request to one tenant.
|
|
956
|
-
* // Useful for tests and single-tenant deployments instead of the
|
|
957
|
-
* // preset factories.
|
|
958
|
-
* const single: Verifier = async (_req) => ({
|
|
959
|
-
* tenantPrefix: "acme-co",
|
|
960
|
-
* identity: { kind: "static" },
|
|
961
|
-
* });
|
|
962
|
-
*
|
|
963
|
-
* // A Verifier that reads an `X-Tenant` header and rejects when
|
|
964
|
-
* // it's missing. The preset factories produce something like
|
|
965
|
-
* // this on top of a real IdP — never trust an `X-Tenant` header
|
|
966
|
-
* // in production.
|
|
967
|
-
* const headerOnly: Verifier = async (req) => {
|
|
968
|
-
* const tenant = req.headers.get("x-tenant");
|
|
969
|
-
* if (!tenant) return null;
|
|
970
|
-
* return { tenantPrefix: tenant, identity: null };
|
|
971
|
-
* };
|
|
972
|
-
* ```
|
|
973
|
-
*/
|
|
974
|
-
type Verifier = (req: Request) => Promise<VerifierResult | null>;
|
|
975
|
-
//#endregion
|
|
976
|
-
//#region packages/protocol/src/log.d.ts
|
|
977
|
-
/**
|
|
978
|
-
* Debezium-style JSON CDC envelope using pgoutput's message-tag (`I`/`U`/`D`) vocabulary. One per mutation.
|
|
979
|
-
*
|
|
980
|
-
* `LogEntry` is now a public, versionless/additive-only wire contract:
|
|
981
|
-
* 0.3.0 is the public early-access baseline. It is still pre-1.0 and
|
|
982
|
-
* soaking, so breaking changes remain possible, but only through an
|
|
983
|
-
* explicit compatibility decision, changelog/migration notes, and a
|
|
984
|
-
* versioned release. Assume external consumers may exist; do not
|
|
985
|
-
* silently rename, remove, or repurpose fields. Consumers must ignore
|
|
986
|
-
* unknown keys; new optional fields can be added in compatible releases.
|
|
987
|
-
*
|
|
988
|
-
* Field requirement matrix:
|
|
989
|
-
* - Always: `lsn`, `commit_ts`, `op`, `collection`, `session`,
|
|
990
|
-
* `seq`.
|
|
991
|
-
* - For I/U/D: `doc_id`.
|
|
992
|
-
* - For I/U: `after` (full post-image).
|
|
993
|
-
* - Optional: `before` (when `replica_identity === "FULL"`), `key_old`
|
|
994
|
-
* (U/D when `replica_identity !== "PATCH_ONLY"`), `origin`.
|
|
995
|
-
*
|
|
996
|
-
* @see docs/spec/log-entry-shape.md
|
|
997
|
-
*/
|
|
998
|
-
interface LogEntry {
|
|
999
|
-
/**
|
|
1000
|
-
* Opaque, monotonic, lex-asc cursor. Shape is
|
|
1001
|
-
* `<base32-time>_<session>_<seq>` — minted inside
|
|
1002
|
-
* `Writer.commit` (see
|
|
1003
|
-
* `packages/server/src/writer.ts`) from `timestamp()` +
|
|
1004
|
-
* the per-commit `session` + `countKey(seq)`. Consumers ack and
|
|
1005
|
-
* resume from this string.
|
|
1006
|
-
*
|
|
1007
|
-
* When you have a `LogEntry` in hand, prefer the structured
|
|
1008
|
-
* `session` / `seq` fields below over parsing this string. The
|
|
1009
|
-
* one place that *does* need to crack it open is the
|
|
1010
|
-
* `/v1/since` boundary, where a client resumes from an opaque
|
|
1011
|
-
* `next_cursor` and no `LogEntry` is in scope — that path uses
|
|
1012
|
-
* `lsnParts` (the kernel-blessed parser) rather than ad-hoc
|
|
1013
|
-
* `split("_")`.
|
|
1014
|
-
*/
|
|
1015
|
-
lsn: string;
|
|
1016
|
-
/** ISO-8601 ms timestamp. Redundant with `lsn` but cheap. */
|
|
1017
|
-
commit_ts: string;
|
|
1018
|
-
/** Insert / Update / Delete. */
|
|
1019
|
-
op: "I" | "U" | "D";
|
|
1020
|
-
/**
|
|
1021
|
-
* Collection name — the pgoutput RELATION analogue. Today this is
|
|
1022
|
-
* the collection bound to the `current.json` whose `tail_hint` minted
|
|
1023
|
-
* the entry. The table API makes collections first-class.
|
|
1024
|
-
*/
|
|
1025
|
-
collection: string;
|
|
1026
|
-
/**
|
|
1027
|
-
* The document key (`ref.key`). Required for every op — `op` is
|
|
1028
|
-
* `I | U | D` and all three carry it — so the wire type is required,
|
|
1029
|
-
* not optional, matching `log-entry-shape.md`.
|
|
1030
|
-
*/
|
|
1031
|
-
doc_id: string;
|
|
1032
|
-
/** Required for I, U. The post-image (Debezium's `after`). */
|
|
1033
|
-
after?: DocumentData;
|
|
1034
|
-
/**
|
|
1035
|
-
* The pre-image (Debezium's `before`). Present iff the
|
|
1036
|
-
* collection's `replica_identity` is `FULL`. ~2× log size on
|
|
1037
|
-
* update-heavy collections; off by default.
|
|
1038
|
-
*/
|
|
1039
|
-
before?: DocumentData;
|
|
1040
|
-
/**
|
|
1041
|
-
* Pre-image of the primary key. U/D always carry this when
|
|
1042
|
-
* `replica_identity` is not `PATCH_ONLY`. (For baerly-storage today,
|
|
1043
|
-
* `_id` is the only PK.)
|
|
1044
|
-
*/
|
|
1045
|
-
key_old?: {
|
|
1046
|
-
readonly [pk: string]: JSONValue;
|
|
1047
|
-
};
|
|
1048
|
-
/** ORIGIN analogue — the writer session id. */
|
|
1049
|
-
origin?: string;
|
|
1050
|
-
/**
|
|
1051
|
-
* Causal metadata (baerly-storage-only; no pgoutput analogue). The
|
|
1052
|
-
* session id that built the `lsn`. Surfaces here so consumers
|
|
1053
|
-
* can dedupe / order without parsing the cursor.
|
|
1054
|
-
*/
|
|
1055
|
-
session: string;
|
|
1056
|
-
/**
|
|
1057
|
-
* The `log/<seq>` slot this entry occupies — the integer in its
|
|
1058
|
-
* `log/<seq>.json` key, minted by `Writer.commit` as the forward-probed
|
|
1059
|
-
* collection-log tail (the winning `If-None-Match: "*"` create). One
|
|
1060
|
-
* entry per `session`, so this is a per-collection slot, not a
|
|
1061
|
-
* per-session counter. Also encoded (descending base-32) as the LSN's
|
|
1062
|
-
* third segment — see `lsnParts`.
|
|
1063
|
-
*/
|
|
1064
|
-
seq: number;
|
|
1065
|
-
}
|
|
1066
|
-
//#endregion
|
|
1067
|
-
//#region packages/protocol/src/metrics.d.ts
|
|
1068
|
-
/**
|
|
1069
|
-
* `MetricsRecorder` — internal emission contract for the six
|
|
1070
|
-
* load-bearing kernel metrics. Writer / compactor / GC emit through
|
|
1071
|
-
* an instance of this interface; in production the instance is the
|
|
1072
|
-
* per-request `RequestScopedMetricsRecorder` on the active
|
|
1073
|
-
* `ObservabilityContext`, and emissions flow onto the canonical line
|
|
1074
|
-
* via `summarize()`. Tests use a local `InMemoryMetricsRecorder` and
|
|
1075
|
-
* wrap their workload in `runWithContext` to attach it.
|
|
1076
|
-
*
|
|
1077
|
-
* Operators do not wire a custom sink against this interface — the
|
|
1078
|
-
* operator's view of kernel emissions is the canonical line on
|
|
1079
|
-
* stdout (one JSON object per HTTP request).
|
|
1080
|
-
*
|
|
1081
|
-
* **Naming convention** matches the load-bearing metrics:
|
|
1082
|
-
* - `db.write.class_a_ops_per_logical_write` — histogram (recommend p99 alert ~5; not gated).
|
|
1083
|
-
* Includes one Class A op per index PUT + index DELETE emitted
|
|
1084
|
-
* in the commit's fence. Idle-reader cost is unchanged.
|
|
1085
|
-
* - `db.r2.put.412_total` — counter (CAS conflict / If-Match-or-None-Match loss)
|
|
1086
|
-
* - `db.r2.put.429_total` — counter (R2 prefix-partition rate-limit)
|
|
1087
|
-
* - `db.write.index_ops_per_logical_write` — histogram.
|
|
1088
|
-
* `K (PUT) + L (DELETE)` per commit. Per-collection label.
|
|
1089
|
-
* - `db.manifest.lag_window_depth` — gauge (alert at >100)
|
|
1090
|
-
* - `db.gc.entries_swept_per_second` — gauge (livelock indicator when <writes/s)
|
|
1091
|
-
* - `db.orphan.candidate_count` — gauge (`gc/pending.json` depth)
|
|
1092
|
-
* - `db.compact.entries_folded` — histogram (entries folded per run)
|
|
1093
|
-
* - `db.gc.swept_total` — counter (labelled by reason)
|
|
1094
|
-
*
|
|
1095
|
-
* Names follow `db.<subsystem>.<metric>`, dot-separated, all-lowercase
|
|
1096
|
-
* snake_case segments. Labels are flat
|
|
1097
|
-
* `Readonly<Record<string, string>>` — no numbers, no nested objects.
|
|
1098
|
-
*
|
|
1099
|
-
* Metric emissions never throw on the hot path; the default
|
|
1100
|
-
* `noopMetricsRecorder` cannot throw.
|
|
1101
|
-
*/
|
|
1102
|
-
interface MetricsRecorder {
|
|
1103
|
-
/** Monotonically-incrementing event count. */
|
|
1104
|
-
counter(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
|
|
1105
|
-
/** Point-in-time value. */
|
|
1106
|
-
gauge(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
|
|
1107
|
-
/** Distribution sample. */
|
|
1108
|
-
histogram(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
|
|
1109
|
-
}
|
|
1110
|
-
//#endregion
|
|
1111
|
-
export { StoragePutOptions as _, MemoryStorage as a, BaerlyErrorCode as b, Predicate as c, CurrentJson as d, CurrentJsonRead as f, StorageListEntry as g, StorageGetResult as h, VerifierResult as i, Query as l, StorageGetOptions as m, LogEntry as n, Collection as o, Storage as p, Verifier as r, OrderSpec as s, MetricsRecorder as t, PredicateArg as u, StoragePutResult as v, BaerlyError as y };
|
|
1112
|
-
//# sourceMappingURL=index-BYk9oCNf.d.ts.map
|