@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.
Files changed (215) hide show
  1. package/README.md +47 -124
  2. package/dist/API.md +161 -511
  3. package/dist/CHANGELOG.md +1148 -307
  4. package/dist/RECIPES.md +398 -80
  5. package/dist/THIRD-PARTY-LICENSES.txt +5 -26
  6. package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
  7. package/dist/app-config.d.ts +31 -1
  8. package/dist/app-config.js +1 -2
  9. package/dist/app-config.js.map +1 -1
  10. package/dist/auth.d.ts +33 -28
  11. package/dist/auth.js +549 -985
  12. package/dist/auth.js.map +1 -1
  13. package/dist/baerly.js +130 -138
  14. package/dist/baerly.js.map +1 -1
  15. package/dist/baerly.spec.json +97 -22
  16. package/dist/capacity-warning-header-BlVopyiI.js +16 -0
  17. package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
  18. package/dist/{client-Fe8CwB73.d.ts → client-CHQTXpef.d.ts} +121 -36
  19. package/dist/client-react.d.ts +67 -20
  20. package/dist/client-react.js +240 -54
  21. package/dist/client-react.js.map +1 -1
  22. package/dist/client.d.ts +5 -4
  23. package/dist/client.js +51 -16
  24. package/dist/client.js.map +1 -1
  25. package/dist/{cloudflare-DzKBrUlg.js → cloudflare-CKHYXccw.js} +504 -124
  26. package/dist/cloudflare-CKHYXccw.js.map +1 -0
  27. package/dist/cloudflare.d.ts +106 -71
  28. package/dist/cloudflare.js +334 -271
  29. package/dist/cloudflare.js.map +1 -1
  30. package/dist/code-resolution-CL_7L0wS.js +22 -0
  31. package/dist/code-resolution-CL_7L0wS.js.map +1 -0
  32. package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
  33. package/dist/config-DEzInG6M.js +4035 -0
  34. package/dist/config-DEzInG6M.js.map +1 -0
  35. package/dist/constants-D3GSH3tc.js +469 -0
  36. package/dist/constants-D3GSH3tc.js.map +1 -0
  37. package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
  38. package/dist/context-rlpSnHFA.js.map +1 -0
  39. package/dist/cost-B52llVDx.js +330 -0
  40. package/dist/cost-B52llVDx.js.map +1 -0
  41. package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
  42. package/dist/current-json-CC6lE4Aj.js.map +1 -0
  43. package/dist/db-plFUNTSF.d.ts +130 -0
  44. package/dist/db-read-seams-BSs0m1z1.js +3261 -0
  45. package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
  46. package/dist/{deploy-DonTr-CV.js → deploy-Obj4nE-Z.js} +12 -16
  47. package/dist/deploy-Obj4nE-Z.js.map +1 -0
  48. package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
  49. package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
  50. package/dist/dev-landing-CD-si4dW.js +50 -0
  51. package/dist/dev-landing-CD-si4dW.js.map +1 -0
  52. package/dist/dev-vite.d.ts +38 -39
  53. package/dist/dev-vite.js +67 -36
  54. package/dist/dev-vite.js.map +1 -1
  55. package/dist/dev.d.ts +3 -2
  56. package/dist/dev.js +2 -1
  57. package/dist/doctor-BA0i-YAN.js +270 -0
  58. package/dist/doctor-BA0i-YAN.js.map +1 -0
  59. package/dist/dump-D1vX8ozg.js +133 -0
  60. package/dist/dump-D1vX8ozg.js.map +1 -0
  61. package/dist/errors-7Rk1HGCE.js +160 -0
  62. package/dist/errors-7Rk1HGCE.js.map +1 -0
  63. package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
  64. package/dist/export-BVL2EvYE.js.map +1 -0
  65. package/dist/fsck-BWkPgov4.js +145 -0
  66. package/dist/fsck-BWkPgov4.js.map +1 -0
  67. package/dist/gcs-admin-Dso1HWQj.d.ts +127 -0
  68. package/dist/gcs.d.ts +30 -0
  69. package/dist/gcs.js +1 -0
  70. package/dist/goog4-signer-CeLIABoE.js +331 -0
  71. package/dist/goog4-signer-CeLIABoE.js.map +1 -0
  72. package/dist/{http-DGd5tbNs.js → http-Z5rZyYMX.js} +898 -271
  73. package/dist/http-Z5rZyYMX.js.map +1 -0
  74. package/dist/http-transport-DNUM8kU-.js +1299 -0
  75. package/dist/http-transport-DNUM8kU-.js.map +1 -0
  76. package/dist/http.d.ts +366 -294
  77. package/dist/http.js +2 -2
  78. package/dist/index-JJrIu1pO.d.ts +135 -0
  79. package/dist/index-LEgHN0qJ.d.ts +50 -0
  80. package/dist/{index-CuA9Mi3K.d.ts → index-RiEYj8t0.d.ts} +291 -78
  81. package/dist/index.d.ts +27 -6
  82. package/dist/index.js +3 -5
  83. package/dist/inspect-BTsVYZKd.js +196 -0
  84. package/dist/inspect-BTsVYZKd.js.map +1 -0
  85. package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
  86. package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
  87. package/dist/ledger-Dj_bGgo0.js +192 -0
  88. package/dist/ledger-Dj_bGgo0.js.map +1 -0
  89. package/dist/legacy-names-DgZBtgOh.js +47 -0
  90. package/dist/legacy-names-DgZBtgOh.js.map +1 -0
  91. package/dist/log-C9W15Dfo.d.ts +94 -0
  92. package/dist/log-tail-DWJbneBF.js +142 -0
  93. package/dist/log-tail-DWJbneBF.js.map +1 -0
  94. package/dist/log-walk-C-vA-WGJ.js +111 -0
  95. package/dist/log-walk-C-vA-WGJ.js.map +1 -0
  96. package/dist/maintenance-Dd-Yakqj.js +1709 -0
  97. package/dist/maintenance-Dd-Yakqj.js.map +1 -0
  98. package/dist/maintenance-DevB6z4e.js +2237 -0
  99. package/dist/maintenance-DevB6z4e.js.map +1 -0
  100. package/dist/maintenance.d.ts +100 -3
  101. package/dist/maintenance.js +1 -3
  102. package/dist/node.d.ts +130 -142
  103. package/dist/node.js +4 -3
  104. package/dist/{observability-BmflLCdF.js → observability-C-ISCCLE.js} +1275 -332
  105. package/dist/observability-C-ISCCLE.js.map +1 -0
  106. package/dist/observability.d.ts +27 -3
  107. package/dist/observability.js +3 -3
  108. package/dist/path-segment-DBXG26PW.js +363 -0
  109. package/dist/path-segment-DBXG26PW.js.map +1 -0
  110. package/dist/{plan-a7PJHBCy.js → plan-BvQbaNMe.js} +19 -11
  111. package/dist/plan-BvQbaNMe.js.map +1 -0
  112. package/dist/request-CRWiTrza.js +272 -0
  113. package/dist/request-CRWiTrza.js.map +1 -0
  114. package/dist/restore-U6Im8V1V.js +1467 -0
  115. package/dist/restore-U6Im8V1V.js.map +1 -0
  116. package/dist/retry-OBtLB2GC.js +126 -0
  117. package/dist/retry-OBtLB2GC.js.map +1 -0
  118. package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
  119. package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec-B5mg3pHF.js} +189 -28
  120. package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
  121. package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DBC_wiCL.d.ts} +18 -10
  122. package/dist/s3.d.ts +20 -7
  123. package/dist/s3.js +4 -5
  124. package/dist/s3.js.map +1 -1
  125. package/dist/sha256-4FfGQNPw.js +22 -0
  126. package/dist/sha256-4FfGQNPw.js.map +1 -0
  127. package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
  128. package/dist/shared-secret-Vkur-8r0.js.map +1 -0
  129. package/dist/sigv4-sign-5IUflUD_.js +507 -0
  130. package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
  131. package/dist/snapshot-CknzkDM0.js +148 -0
  132. package/dist/snapshot-CknzkDM0.js.map +1 -0
  133. package/dist/{src-BL_JoPTn.js → src-Actga-bO.js} +1004 -378
  134. package/dist/src-Actga-bO.js.map +1 -0
  135. package/dist/src-D0MQfvOp.js +812 -0
  136. package/dist/src-D0MQfvOp.js.map +1 -0
  137. package/dist/src-Dr9uo3dc.js +501 -0
  138. package/dist/src-Dr9uo3dc.js.map +1 -0
  139. package/dist/{subcommand-DoDA-K7d.js → subcommand-BLoF66dG.js} +89 -16
  140. package/dist/subcommand-BLoF66dG.js.map +1 -0
  141. package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
  142. package/dist/time-DRxTP9iv.js.map +1 -0
  143. package/dist/types-suVbsEWS.d.ts +116 -0
  144. package/dist/{usage-DBV1eQHC.js → usage-CPzVhrQr.js} +40 -45
  145. package/dist/usage-CPzVhrQr.js.map +1 -0
  146. package/dist/uuid-BuT_c404.js +333 -0
  147. package/dist/uuid-BuT_c404.js.map +1 -0
  148. package/dist/verifier-Bmlmndzo.d.ts +95 -0
  149. package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
  150. package/dist/wire-DndvKU-K.js.map +1 -0
  151. package/package.json +96 -69
  152. package/dist/aws4fetch.esm-p7eEzLCs.js +0 -1702
  153. package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
  154. package/dist/bytes-BXdamO3L.js +0 -11
  155. package/dist/bytes-BXdamO3L.js.map +0 -1
  156. package/dist/cloudflare-DzKBrUlg.js.map +0 -1
  157. package/dist/config-1tv0-Yzm.js +0 -2693
  158. package/dist/config-1tv0-Yzm.js.map +0 -1
  159. package/dist/constants-CfeMWQWk.js +0 -222
  160. package/dist/constants-CfeMWQWk.js.map +0 -1
  161. package/dist/context-DRZ3tZ5l.js.map +0 -1
  162. package/dist/cost-DSMIVqzL.js +0 -203
  163. package/dist/cost-DSMIVqzL.js.map +0 -1
  164. package/dist/current-json-C6nhPOm1.js.map +0 -1
  165. package/dist/db-DsPkOVEH.d.ts +0 -254
  166. package/dist/deploy-DonTr-CV.js.map +0 -1
  167. package/dist/doctor-DSIyCDg_.js +0 -346
  168. package/dist/doctor-DSIyCDg_.js.map +0 -1
  169. package/dist/dump-Bh5k26VQ.js +0 -94
  170. package/dist/dump-Bh5k26VQ.js.map +0 -1
  171. package/dist/errors-Dfa3p78c.js +0 -78
  172. package/dist/errors-Dfa3p78c.js.map +0 -1
  173. package/dist/export-DtF5tDIM.js +0 -401
  174. package/dist/export-DtF5tDIM.js.map +0 -1
  175. package/dist/fsck-D_djMO5D.js +0 -279
  176. package/dist/fsck-D_djMO5D.js.map +0 -1
  177. package/dist/http-DGd5tbNs.js.map +0 -1
  178. package/dist/index-0rZcMBwy.d.ts +0 -115
  179. package/dist/index-BNRh23K9.d.ts +0 -162
  180. package/dist/index-BYk9oCNf.d.ts +0 -1112
  181. package/dist/indexes-Dn9hbGQG.d.ts +0 -22
  182. package/dist/inspect-6WZ-pC7-.js +0 -133
  183. package/dist/inspect-6WZ-pC7-.js.map +0 -1
  184. package/dist/log-tail-D98U1JBo.js +0 -522
  185. package/dist/log-tail-D98U1JBo.js.map +0 -1
  186. package/dist/maintenance-B4Dki6Ig.js +0 -2157
  187. package/dist/maintenance-B4Dki6Ig.js.map +0 -1
  188. package/dist/maintenance-B_e0T99L.d.ts +0 -537
  189. package/dist/maintenance-C7coQp4c.js +0 -1418
  190. package/dist/maintenance-C7coQp4c.js.map +0 -1
  191. package/dist/normalize-rjnZLwS4.js +0 -133
  192. package/dist/normalize-rjnZLwS4.js.map +0 -1
  193. package/dist/observability-BmflLCdF.js.map +0 -1
  194. package/dist/plan-a7PJHBCy.js.map +0 -1
  195. package/dist/query-rAtXNQQB.js +0 -1773
  196. package/dist/query-rAtXNQQB.js.map +0 -1
  197. package/dist/rebuild-index-BVzQSZlm.js +0 -81
  198. package/dist/rebuild-index-BVzQSZlm.js.map +0 -1
  199. package/dist/request-u0M51mhJ.js +0 -72
  200. package/dist/request-u0M51mhJ.js.map +0 -1
  201. package/dist/restore-R-4rbciV.js +0 -778
  202. package/dist/restore-R-4rbciV.js.map +0 -1
  203. package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
  204. package/dist/runtime-spec-Dsw2-n8S.js.map +0 -1
  205. package/dist/shared-secret-DgEicd3x.js.map +0 -1
  206. package/dist/src-BL_JoPTn.js.map +0 -1
  207. package/dist/src-CYHFDrKz.js +0 -536
  208. package/dist/src-CYHFDrKz.js.map +0 -1
  209. package/dist/src-DYZ4H1aF.js +0 -392
  210. package/dist/src-DYZ4H1aF.js.map +0 -1
  211. package/dist/subcommand-DoDA-K7d.js.map +0 -1
  212. package/dist/time-DUqvFMHq.js.map +0 -1
  213. package/dist/usage-DBV1eQHC.js.map +0 -1
  214. package/dist/validate-DtljsCh1.js.map +0 -1
  215. package/dist/wire-izfGZDvr.js.map +0 -1
@@ -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