@gusto/baerly-storage 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/NOTICE +29 -0
- package/README.md +93 -52
- package/dist/API.md +151 -109
- package/dist/CHANGELOG.md +144 -0
- package/dist/THIRD-PARTY-LICENSES.txt +312 -0
- package/dist/{app-config-C0Bbw_Z6.d.ts → app-config-BIzyAKzy.d.ts} +14 -2
- package/dist/app-config.d.ts +1 -1
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +288 -288
- package/dist/auth.js.map +1 -1
- package/dist/baerly.js +10 -10
- package/dist/baerly.js.map +1 -1
- package/dist/bytes-BXdamO3L.js.map +1 -1
- package/dist/{client-DYZfoZb9.d.ts → client-BJXF3XJA.d.ts} +10 -10
- package/dist/client-react.d.ts +3 -3
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +3 -3
- package/dist/client.js.map +1 -1
- package/dist/{cloudflare-CINJPKCW.js → cloudflare-Cn2ibODt.js} +178 -2
- package/dist/cloudflare-Cn2ibODt.js.map +1 -0
- package/dist/cloudflare.d.ts +4 -4
- package/dist/cloudflare.js +10 -11
- package/dist/cloudflare.js.map +1 -1
- package/dist/{subcommand-DZcHcsYp.js → config-CGyBopy3.js} +643 -439
- package/dist/config-CGyBopy3.js.map +1 -0
- package/dist/context-DRZ3tZ5l.js.map +1 -1
- package/dist/{cost-CQt1YRkA.js → cost-BZ_MDBmn.js} +6 -4
- package/dist/cost-BZ_MDBmn.js.map +1 -0
- package/dist/{current-json-C-EyJqs0.js → current-json-DsN7FNY1.js} +47 -13
- package/dist/current-json-DsN7FNY1.js.map +1 -0
- package/dist/{db-BM3y2JQw.d.ts → db-CCT6tDfY.d.ts} +26 -108
- package/dist/{deploy-CrAbfgCq.js → deploy-BKKyGlSJ.js} +11 -4
- package/dist/deploy-BKKyGlSJ.js.map +1 -0
- package/dist/dev-vite.d.ts +5 -5
- package/dist/dev-vite.js +5 -5
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +1 -1
- package/dist/dev.js +1 -1
- package/dist/{doctor-Db-hzPmE.js → doctor-BVU4GNXN.js} +13 -132
- package/dist/doctor-BVU4GNXN.js.map +1 -0
- package/dist/{dump-BYA55NLP.js → dump-DPEAKub6.js} +5 -3
- package/dist/dump-DPEAKub6.js.map +1 -0
- package/dist/errors-DOdL95kK.js.map +1 -1
- package/dist/{export-Bhbz90-z.js → export-BcuCLFFe.js} +6 -4
- package/dist/{export-Bhbz90-z.js.map → export-BcuCLFFe.js.map} +1 -1
- package/dist/{fsck-CPPZWt9p.js → fsck-RXgLOaJG.js} +23 -11
- package/dist/fsck-RXgLOaJG.js.map +1 -0
- package/dist/{http-Cw8p6y5b.js → http-Bd4byR4n.js} +45 -61
- package/dist/http-Bd4byR4n.js.map +1 -0
- package/dist/http.d.ts +15 -15
- package/dist/http.js +1 -1
- package/dist/{index-cUY-36AN.d.ts → index-BDceQQi-.d.ts} +20 -4
- package/dist/{index-C3JAH1Yo.d.ts → index-Cmsxx-ZN.d.ts} +9 -9
- package/dist/{index-DSvwEUeF.d.ts → index-DW7GT6M2.d.ts} +50 -42
- package/dist/{index-DwDTWPSU.d.ts → index-DnBGSeuU.d.ts} +10 -7
- package/dist/index.d.ts +6 -6
- package/dist/index.js +4 -4
- package/dist/{indexes-DAu2AkTW.d.ts → indexes-Cx7uMXm0.d.ts} +2 -2
- package/dist/{inspect-Bdbzvi-_.js → inspect-DhI49PSi.js} +16 -8
- package/dist/inspect-DhI49PSi.js.map +1 -0
- package/dist/{snapshot-SS8USDUF.js → log-tail-DXeDkWEp.js} +154 -83
- package/dist/log-tail-DXeDkWEp.js.map +1 -0
- package/dist/{maintenance-BRrThz8V.d.ts → maintenance-BkhUr72A.d.ts} +91 -26
- package/dist/{maintenance-ClzBC1Vv.js → maintenance-CWBQpZ2y.js} +368 -161
- package/dist/maintenance-CWBQpZ2y.js.map +1 -0
- package/dist/{maintenance-BvOv6BMM.js → maintenance-C_KSkVjd.js} +204 -82
- package/dist/maintenance-C_KSkVjd.js.map +1 -0
- package/dist/maintenance.d.ts +3 -2
- package/dist/maintenance.js +3 -2
- package/dist/node.d.ts +13 -8
- package/dist/node.js +1 -1
- package/dist/normalize-XWY25_sG.js.map +1 -1
- package/dist/{observability-CpOiEN0k.js → observability-BYd-RzEx.js} +63 -55
- package/dist/observability-BYd-RzEx.js.map +1 -0
- package/dist/observability.d.ts +3 -3
- package/dist/observability.js +1 -1
- package/dist/{plan-DOTl21vq.js → plan-DIu_B6fy.js} +7 -4
- package/dist/plan-DIu_B6fy.js.map +1 -0
- package/dist/{query-BmiQy328.js → query-sQNO5vU_.js} +1071 -1099
- package/dist/query-sQNO5vU_.js.map +1 -0
- package/dist/{rebuild-index-DC_nR6wP.js → rebuild-index-DP4CqSSs.js} +5 -4
- package/dist/rebuild-index-DP4CqSSs.js.map +1 -0
- package/dist/{restore-C6IcmLeA.js → restore-DpQYef6r.js} +362 -328
- package/dist/restore-DpQYef6r.js.map +1 -0
- package/dist/shared-secret-BJdSwpgw.js.map +1 -1
- package/dist/{src-QQ7jDeL2.js → src-CWpkSbvJ.js} +40 -20
- package/dist/src-CWpkSbvJ.js.map +1 -0
- package/dist/{src-DU1sCMlr.js → src-D24wDpzR.js} +269 -258
- package/dist/src-D24wDpzR.js.map +1 -0
- package/dist/{src-zhEAmmF7.js → src-Db4-qVtM.js} +36 -96
- package/dist/src-Db4-qVtM.js.map +1 -0
- package/dist/subcommand-CP9NY2J4.js +159 -0
- package/dist/subcommand-CP9NY2J4.js.map +1 -0
- package/dist/{usage-CLjirdD-.js → usage-CTfDq9HR.js} +3 -3
- package/dist/{usage-CLjirdD-.js.map → usage-CTfDq9HR.js.map} +1 -1
- package/dist/{validate-DCq_0DIn.js → validate-DtljsCh1.js} +51 -51
- package/dist/{validate-DCq_0DIn.js.map → validate-DtljsCh1.js.map} +1 -1
- package/package.json +40 -29
- package/dist/cloudflare-CINJPKCW.js.map +0 -1
- package/dist/config-DVfDGyw1.js +0 -278
- package/dist/config-DVfDGyw1.js.map +0 -1
- package/dist/cost-CQt1YRkA.js.map +0 -1
- package/dist/current-json-C-EyJqs0.js.map +0 -1
- package/dist/deploy-CrAbfgCq.js.map +0 -1
- package/dist/doctor-Db-hzPmE.js.map +0 -1
- package/dist/dump-BYA55NLP.js.map +0 -1
- package/dist/fsck-CPPZWt9p.js.map +0 -1
- package/dist/http-Cw8p6y5b.js.map +0 -1
- package/dist/inspect-Bdbzvi-_.js.map +0 -1
- package/dist/maintenance-BvOv6BMM.js.map +0 -1
- package/dist/maintenance-ClzBC1Vv.js.map +0 -1
- package/dist/observability-CpOiEN0k.js.map +0 -1
- package/dist/plan-DOTl21vq.js.map +0 -1
- package/dist/query-BmiQy328.js.map +0 -1
- package/dist/rebuild-index-DC_nR6wP.js.map +0 -1
- package/dist/restore-C6IcmLeA.js.map +0 -1
- package/dist/snapshot-SS8USDUF.js.map +0 -1
- package/dist/src-DU1sCMlr.js.map +0 -1
- package/dist/src-QQ7jDeL2.js.map +0 -1
- package/dist/src-zhEAmmF7.js.map +0 -1
- package/dist/subcommand-DZcHcsYp.js.map +0 -1
package/dist/API.md
CHANGED
|
@@ -17,18 +17,29 @@ directory remain the source of truth (the bundler chunks them across
|
|
|
17
17
|
noisy to read flat — read this first, drop into the `.d.ts` chunks
|
|
18
18
|
only for exact signatures).
|
|
19
19
|
|
|
20
|
+
The public surface is intentionally small and **closed**: the absence
|
|
21
|
+
of a method is a design choice, not an undocumented gap. Every
|
|
22
|
+
unsupported operation is a compile error — the type system enforces the
|
|
23
|
+
vocabulary rather than surfacing a runtime "not implemented", so an agent
|
|
24
|
+
reaches the correct call zero-shot without inventing ceremony the kernel
|
|
25
|
+
doesn't support. The predicate operator set is the concrete example
|
|
26
|
+
(see [Predicates](#predicates)).
|
|
27
|
+
|
|
20
28
|
## Imports cheat sheet
|
|
21
29
|
|
|
22
30
|
```ts
|
|
23
31
|
// Server kernel
|
|
24
32
|
import {
|
|
25
33
|
Db,
|
|
26
|
-
MemoryStorage,
|
|
27
|
-
type Collection,
|
|
34
|
+
MemoryStorage, // in-memory `Storage`; canonical for tests
|
|
35
|
+
type Collection,
|
|
36
|
+
type Query,
|
|
28
37
|
type DocumentData,
|
|
29
|
-
type RowOf,
|
|
30
|
-
|
|
31
|
-
|
|
38
|
+
type RowOf,
|
|
39
|
+
type CollectionNames, // row-shape inference from a bound config
|
|
40
|
+
BaerlyError,
|
|
41
|
+
type BaerlyErrorCode,
|
|
42
|
+
defineConfig, // narrower; root barrel
|
|
32
43
|
} from "@gusto/baerly-storage";
|
|
33
44
|
|
|
34
45
|
// Scaffold-aware config (`app`, `tenant`, `target`, `domain`, …)
|
|
@@ -43,18 +54,25 @@ import { createRouter, mapError } from "@gusto/baerly-storage/http";
|
|
|
43
54
|
// Browser / Node client (HTTP)
|
|
44
55
|
import {
|
|
45
56
|
createBaerlyClient,
|
|
46
|
-
type BaerlyClient,
|
|
47
|
-
type
|
|
57
|
+
type BaerlyClient,
|
|
58
|
+
type ClientCollection,
|
|
59
|
+
type ClientQuery,
|
|
60
|
+
type TerminalOptions,
|
|
61
|
+
type Fetcher,
|
|
48
62
|
} from "@gusto/baerly-storage/client";
|
|
49
63
|
|
|
50
64
|
// Auth verifiers
|
|
51
|
-
import {
|
|
52
|
-
sharedSecret, cloudflareAccess, bearerJwt,
|
|
53
|
-
} from "@gusto/baerly-storage/auth";
|
|
65
|
+
import { sharedSecret, cloudflareAccess, bearerJwt } from "@gusto/baerly-storage/auth";
|
|
54
66
|
|
|
55
67
|
// Adapters
|
|
56
68
|
import { baerlyWorker, r2BindingStorage } from "@gusto/baerly-storage/cloudflare";
|
|
57
|
-
import {
|
|
69
|
+
import {
|
|
70
|
+
baerlyNode,
|
|
71
|
+
s3Storage,
|
|
72
|
+
r2Storage,
|
|
73
|
+
minioStorage,
|
|
74
|
+
gcsStorage,
|
|
75
|
+
} from "@gusto/baerly-storage/node";
|
|
58
76
|
|
|
59
77
|
// Dev helpers (Vite, local-fs storage)
|
|
60
78
|
import { baerlyDevAuth, loadDevVars } from "@gusto/baerly-storage/dev/vite";
|
|
@@ -72,11 +90,11 @@ import { Db, MemoryStorage } from "@gusto/baerly-storage";
|
|
|
72
90
|
import config from "./baerly.config";
|
|
73
91
|
|
|
74
92
|
const db = Db.create({
|
|
75
|
-
storage: new MemoryStorage(),
|
|
93
|
+
storage: new MemoryStorage(), // or `s3Storage(...)`, `r2BindingStorage(env.BUCKET)`, …
|
|
76
94
|
app: "tickets",
|
|
77
95
|
tenant: "acme-co",
|
|
78
|
-
config,
|
|
79
|
-
|
|
96
|
+
config, // ← optional. Wires schemas + indexes
|
|
97
|
+
// AND narrows `db.collection(name)` types.
|
|
80
98
|
});
|
|
81
99
|
|
|
82
100
|
await db.collection("tickets").insert({ title: "first ticket", status: "open" });
|
|
@@ -88,7 +106,7 @@ backs an independent in-process bucket — two `Db` instances built
|
|
|
88
106
|
against two `new MemoryStorage()`s see two empty, isolated stores.
|
|
89
107
|
This is what makes it the canonical test fixture: one fresh instance
|
|
90
108
|
per test gives a hermetic bucket without `beforeEach` cleanup. Pass
|
|
91
|
-
the
|
|
109
|
+
the _same_ `MemoryStorage` instance to multiple `Db` constructors
|
|
92
110
|
when you want two writers contending on one bucket.
|
|
93
111
|
|
|
94
112
|
Full `Db.create` config:
|
|
@@ -112,7 +130,9 @@ import type { Db } from "@gusto/baerly-storage";
|
|
|
112
130
|
import type config from "./baerly.config";
|
|
113
131
|
|
|
114
132
|
let cached: Db<typeof config> | undefined;
|
|
115
|
-
export function setDbForTesting(db: Db<typeof config>) {
|
|
133
|
+
export function setDbForTesting(db: Db<typeof config>) {
|
|
134
|
+
cached = db;
|
|
135
|
+
}
|
|
116
136
|
```
|
|
117
137
|
|
|
118
138
|
The narrowed `Db<typeof config>` carries the same `collection(name)`
|
|
@@ -135,7 +155,7 @@ interface Collection<T extends DocumentData = DocumentData> {
|
|
|
135
155
|
count(): Promise<number>;
|
|
136
156
|
get(id: string): Promise<T | undefined>;
|
|
137
157
|
// Modifiers — return Query<T>.
|
|
138
|
-
where(predicate: PredicateArg<T>): Query<T>;
|
|
158
|
+
where(predicate: PredicateArg<T>): Query<T>; // PredicateArg = Predicate<T> | (q => PredicateBuilder<T>)
|
|
139
159
|
order(spec: OrderSpec<T>): Query<T>;
|
|
140
160
|
limit(n: number): Query<T>;
|
|
141
161
|
// Writes — by primary key.
|
|
@@ -189,11 +209,15 @@ paths (`author._id`) on referenced documents are still allowed.
|
|
|
189
209
|
```ts
|
|
190
210
|
db.collection("tickets").where({ status: "open" }).all();
|
|
191
211
|
db.collection("tickets").where({ "assignee.team": "platform" }).all();
|
|
192
|
-
db.collection("tickets")
|
|
193
|
-
|
|
212
|
+
db.collection("tickets")
|
|
213
|
+
.where((q) => q.gte("count", 1).lt("count", 10))
|
|
214
|
+
.all();
|
|
215
|
+
db.collection("tickets")
|
|
216
|
+
.where((q) => q.in("status", ["open", "pending"]))
|
|
217
|
+
.all();
|
|
194
218
|
db.collection("tickets")
|
|
195
219
|
.where({ status: "open" })
|
|
196
|
-
.where(q => q.gte("priority", 5))
|
|
220
|
+
.where((q) => q.gte("priority", 5))
|
|
197
221
|
.all();
|
|
198
222
|
```
|
|
199
223
|
|
|
@@ -204,10 +228,12 @@ db.collection("tickets")
|
|
|
204
228
|
```ts
|
|
205
229
|
interface PredicateClause {
|
|
206
230
|
readonly op: "eq" | "gt" | "gte" | "lt" | "lte" | "in";
|
|
207
|
-
readonly field: string;
|
|
208
|
-
readonly value: DocumentValue | ReadonlyArray<DocumentValue>;
|
|
231
|
+
readonly field: string; // top-level or dotted path
|
|
232
|
+
readonly value: DocumentValue | ReadonlyArray<DocumentValue>; // array iff op === "in"
|
|
233
|
+
}
|
|
234
|
+
interface PredicateWire {
|
|
235
|
+
readonly clauses: ReadonlyArray<PredicateClause>;
|
|
209
236
|
}
|
|
210
|
-
interface PredicateWire { readonly clauses: ReadonlyArray<PredicateClause>; }
|
|
211
237
|
```
|
|
212
238
|
|
|
213
239
|
Example: `.where({ status: "open" })` → `{"clauses":[{"op":"eq","field":"status","value":"open"}]}`.
|
|
@@ -227,7 +253,9 @@ await db.collection("tickets").update("01HQ...", { status: "closed" });
|
|
|
227
253
|
// → { modified: 1 } (JSON-merge-patch RFC 7386; `null` deletes a field)
|
|
228
254
|
|
|
229
255
|
await db.collection("tickets").replace("01HQ...", {
|
|
230
|
-
_id: "01HQ...",
|
|
256
|
+
_id: "01HQ...",
|
|
257
|
+
status: "open",
|
|
258
|
+
title: "rewrite",
|
|
231
259
|
});
|
|
232
260
|
// → void (whole-document overwrite)
|
|
233
261
|
|
|
@@ -235,7 +263,8 @@ await db.collection("tickets").delete("01HQ...");
|
|
|
235
263
|
// → { deleted: 1 } (or `{ deleted: 0 }` if the id is unknown)
|
|
236
264
|
|
|
237
265
|
// Bulk-by-predicate (Query<T>):
|
|
238
|
-
await db
|
|
266
|
+
await db
|
|
267
|
+
.collection("tickets")
|
|
239
268
|
.where({ status: "open" })
|
|
240
269
|
.update({ status: "closed", closed_at: new Date().toISOString() });
|
|
241
270
|
// → { modified: N }
|
|
@@ -280,7 +309,10 @@ Two ways to get a typed row:
|
|
|
280
309
|
the construction site for a narrower row shape:
|
|
281
310
|
```ts
|
|
282
311
|
import type { Collection, DocumentData } from "@gusto/baerly-storage";
|
|
283
|
-
interface Bookmark extends DocumentData {
|
|
312
|
+
interface Bookmark extends DocumentData {
|
|
313
|
+
_id: string;
|
|
314
|
+
url: string;
|
|
315
|
+
}
|
|
284
316
|
const bookmarks = db.collection("bookmarks") as Collection<Bookmark>;
|
|
285
317
|
await bookmarks.all();
|
|
286
318
|
```
|
|
@@ -303,18 +335,18 @@ try {
|
|
|
303
335
|
}
|
|
304
336
|
```
|
|
305
337
|
|
|
306
|
-
| `code` | HTTP | When
|
|
307
|
-
| ------------------------ | ---- |
|
|
308
|
-
| `InvalidConfig` | 400 | Caller config/input is invalid (bad bucket, malformed predicate, …)
|
|
309
|
-
| `NetworkError` | 502 | Transport (S3 5xx, retries exhausted)
|
|
310
|
-
| `AccessDenied` | 403 | S3 403 or bucket policy denied
|
|
311
|
-
| `InvalidResponse` | 502 | Server returned unparseable body
|
|
312
|
-
| `Internal` | 500 | Invariant violation — file a bug
|
|
313
|
-
| `SchemaError` |
|
|
314
|
-
| `Conflict` | 409 | CAS retry budget exhausted, or `insert` `_id` collision
|
|
315
|
-
| `Unauthorized` | 401 | Verifier returned no identity
|
|
316
|
-
| `NotFound` | 404 | Row by id not found
|
|
317
|
-
| `PayloadTooLarge` | 413 | Body > 1 MiB cap
|
|
338
|
+
| `code` | HTTP | When |
|
|
339
|
+
| ------------------------ | ---- | ---------------------------------------------------------------------- |
|
|
340
|
+
| `InvalidConfig` | 400 | Caller config/input is invalid (bad bucket, malformed predicate, …) |
|
|
341
|
+
| `NetworkError` | 502 | Transport (S3 5xx, retries exhausted) |
|
|
342
|
+
| `AccessDenied` | 403 | S3 403 or bucket policy denied |
|
|
343
|
+
| `InvalidResponse` | 502 | Server returned unparseable body |
|
|
344
|
+
| `Internal` | 500 | Invariant violation — file a bug |
|
|
345
|
+
| `SchemaError` | 400 | JSON shape invalid or bound schema rejected the doc |
|
|
346
|
+
| `Conflict` | 409 | CAS retry budget exhausted, or `insert` `_id` collision |
|
|
347
|
+
| `Unauthorized` | 401 | Verifier returned no identity |
|
|
348
|
+
| `NotFound` | 404 | Row by id not found |
|
|
349
|
+
| `PayloadTooLarge` | 413 | Body > 1 MiB cap |
|
|
318
350
|
| `UnsatisfiablePredicate` | 400 | Predicate is well-formed but contradicts itself (empty `in` set, etc.) |
|
|
319
351
|
|
|
320
352
|
### Mapping errors to HTTP yourself
|
|
@@ -361,7 +393,7 @@ import { defineConfig } from "@gusto/baerly-storage/config";
|
|
|
361
393
|
import { z } from "zod";
|
|
362
394
|
|
|
363
395
|
const TicketSchema = z.object({
|
|
364
|
-
_id: z.string(),
|
|
396
|
+
_id: z.string(), // required — see callout below
|
|
365
397
|
status: z.enum(["open", "closed"]),
|
|
366
398
|
title: z.string().min(1),
|
|
367
399
|
tags: z.array(z.string()).optional(),
|
|
@@ -373,8 +405,8 @@ export default defineConfig({
|
|
|
373
405
|
target: "cloudflare",
|
|
374
406
|
collections: {
|
|
375
407
|
tickets: {
|
|
376
|
-
schema: TicketSchema,
|
|
377
|
-
indexes: [{ name: "by_status", on: "status" }],
|
|
408
|
+
schema: TicketSchema, // StandardSchema v1
|
|
409
|
+
indexes: [{ name: "by_status", on: "status" }], // single-field equality
|
|
378
410
|
},
|
|
379
411
|
},
|
|
380
412
|
});
|
|
@@ -384,7 +416,7 @@ Schemas: any [StandardSchema v1](https://standardschema.dev) validator
|
|
|
384
416
|
(Zod 3.24+, Valibot 0.36+, ArkType 2.0+). Validation runs on the
|
|
385
417
|
post-image: `update` and `replace` see the full doc, not just the
|
|
386
418
|
patch. Failures → `BaerlyError{code:"SchemaError", issues:[…]}`,
|
|
387
|
-
mapped to HTTP
|
|
419
|
+
mapped to HTTP 400.
|
|
388
420
|
|
|
389
421
|
**Author `_id` as required, not `.optional()`.** The validator runs
|
|
390
422
|
on the post-image — by the time it fires, the server has already
|
|
@@ -396,7 +428,7 @@ still accepts a doc without `_id` (the public signature is
|
|
|
396
428
|
required does not break the "omit and let the server mint it" path.
|
|
397
429
|
The win is on the read side: `db.collection("tickets").all()` is
|
|
398
430
|
typed `Ticket[]` with `_id: string` (required), so route handlers
|
|
399
|
-
and response schemas don't need a parallel "_id-required" row type.
|
|
431
|
+
and response schemas don't need a parallel "\_id-required" row type.
|
|
400
432
|
|
|
401
433
|
`_id` is server-minted (UUIDv7, sorts by mint time) — there is no
|
|
402
434
|
exported id generator, and minting one client-side is unsupported.
|
|
@@ -412,11 +444,11 @@ preserved).
|
|
|
412
444
|
## `createBaerlyClient` (browser / Node HTTP client)
|
|
413
445
|
|
|
414
446
|
```ts
|
|
415
|
-
import type config from "./baerly.config";
|
|
447
|
+
import type config from "./baerly.config"; // type-only — server adapter stays out of the SPA bundle
|
|
416
448
|
const client = createBaerlyClient<typeof config>({
|
|
417
|
-
baseUrl: "",
|
|
418
|
-
headers: { Authorization: "Bearer …" },
|
|
419
|
-
fetch: customFetcher,
|
|
449
|
+
baseUrl: "", // same-origin
|
|
450
|
+
headers: { Authorization: "Bearer …" }, // wrap `fetch` for per-call refresh
|
|
451
|
+
fetch: customFetcher, // optional Fetcher middleware
|
|
420
452
|
});
|
|
421
453
|
|
|
422
454
|
await client.collection("tickets").where({ status: "open" }).all();
|
|
@@ -427,7 +459,7 @@ trailing `TerminalOptions`:
|
|
|
427
459
|
|
|
428
460
|
```ts
|
|
429
461
|
interface TerminalOptions {
|
|
430
|
-
signal?: AbortSignal;
|
|
462
|
+
signal?: AbortSignal; // cancels this specific request
|
|
431
463
|
}
|
|
432
464
|
|
|
433
465
|
await client.collection("tickets").all({ signal: ac.signal });
|
|
@@ -453,12 +485,12 @@ interface SinceResponse {
|
|
|
453
485
|
}
|
|
454
486
|
|
|
455
487
|
interface LogEntry {
|
|
456
|
-
readonly lsn: string;
|
|
457
|
-
readonly commit_ts: string;
|
|
488
|
+
readonly lsn: string; // opaque cursor; lex-asc, monotonic
|
|
489
|
+
readonly commit_ts: string; // ISO-8601 ms
|
|
458
490
|
readonly op: "I" | "U" | "D";
|
|
459
491
|
readonly collection: string;
|
|
460
|
-
readonly doc_id: string;
|
|
461
|
-
readonly after?: DocumentData;
|
|
492
|
+
readonly doc_id: string; // I/U/D only
|
|
493
|
+
readonly after?: DocumentData; // I/U — post-image (Debezium's `after`)
|
|
462
494
|
readonly session: string;
|
|
463
495
|
readonly seq: number;
|
|
464
496
|
// `before` / `key_old` / `origin` are optional; see `LogEntry` JSDoc.
|
|
@@ -466,7 +498,7 @@ interface LogEntry {
|
|
|
466
498
|
```
|
|
467
499
|
|
|
468
500
|
**Cursor priming.** First call: pass `cursor=` (empty string). The
|
|
469
|
-
server's fast path returns immediately
|
|
501
|
+
server's fast path returns immediately _iff_ the log already has
|
|
470
502
|
entries for this collection — you get `events: [...]` and the
|
|
471
503
|
last entry's `lsn` as `next_cursor`. **If the collection is empty,
|
|
472
504
|
the first call blocks for the full long-poll budget (~25 s) before
|
|
@@ -498,10 +530,12 @@ shrink `sinceTimeoutMs` in production code paths — it multiplies the
|
|
|
498
530
|
R2 class-A op count per idle long-poll connection.
|
|
499
531
|
|
|
500
532
|
React applications use `@gusto/baerly-storage/client/react` (see next
|
|
501
|
-
section) instead of poking `/v1/since` by hand
|
|
502
|
-
subscribers in other UI frameworks
|
|
503
|
-
|
|
504
|
-
|
|
533
|
+
section) instead of poking `/v1/since` by hand. Hand-rolled
|
|
534
|
+
subscribers in other UI frameworks `fetch` this endpoint directly:
|
|
535
|
+
loop, `fetch`-ing with `cursor=` (empty) first, then threading the
|
|
536
|
+
returned `next_cursor` back as `cursor` on each subsequent call (the
|
|
537
|
+
cursor is opaque — treat it as a string). The wire shape above is the
|
|
538
|
+
public contract; there is no exported cursor-tailing helper.
|
|
505
539
|
|
|
506
540
|
## React: `createBaerlyReact`
|
|
507
541
|
|
|
@@ -523,8 +557,7 @@ import { createBaerlyReact } from "@gusto/baerly-storage/client/react";
|
|
|
523
557
|
import config from "../../baerly.config.ts";
|
|
524
558
|
|
|
525
559
|
export const client = createBaerlyClient({ baseUrl: "", config });
|
|
526
|
-
export const { BaerlyProvider, useQuery, useMutation } =
|
|
527
|
-
createBaerlyReact<typeof config>();
|
|
560
|
+
export const { BaerlyProvider, useQuery, useMutation } = createBaerlyReact<typeof config>();
|
|
528
561
|
```
|
|
529
562
|
|
|
530
563
|
```tsx
|
|
@@ -534,7 +567,7 @@ import { BaerlyProvider, client, useMutation, useQuery } from "./client.ts";
|
|
|
534
567
|
// 1. Wrap your app once.
|
|
535
568
|
<BaerlyProvider client={client}>
|
|
536
569
|
<App />
|
|
537
|
-
</BaerlyProvider
|
|
570
|
+
</BaerlyProvider>;
|
|
538
571
|
|
|
539
572
|
// 2. useQuery(cb, deps) — the callback receives the bound client and
|
|
540
573
|
// returns a ClientCollection / ClientQuery chain. Re-runs on deps
|
|
@@ -548,9 +581,7 @@ const result = useQuery((c) => c.collection("notes").all(), []);
|
|
|
548
581
|
// 3. useQuery.skip — short-circuit to status: "skipped", no
|
|
549
582
|
// subscription. Use for conditional or dependent reads.
|
|
550
583
|
const filtered = useQuery(
|
|
551
|
-
(c) => filter === "all"
|
|
552
|
-
? useQuery.skip
|
|
553
|
-
: c.collection("notes").where({ status: filter }).all(),
|
|
584
|
+
(c) => (filter === "all" ? useQuery.skip : c.collection("notes").where({ status: filter }).all()),
|
|
554
585
|
[filter],
|
|
555
586
|
);
|
|
556
587
|
|
|
@@ -572,12 +603,12 @@ await mutate((c) => c.collection("notes").insert({ body }));
|
|
|
572
603
|
The JS SDK is the canonical path. Reach for `curl` only when
|
|
573
604
|
debugging. Mutation bodies are wrapped:
|
|
574
605
|
|
|
575
|
-
| Route
|
|
576
|
-
|
|
|
577
|
-
| `POST /v1/c/:collection`
|
|
578
|
-
| `PATCH /v1/c/:collection/:id`
|
|
579
|
-
| `PUT /v1/c/:collection/:id`
|
|
580
|
-
| `DELETE /v1/c/:collection/:id`
|
|
606
|
+
| Route | Body | Response |
|
|
607
|
+
| ------------------------------ | ----------------- | ---------------- |
|
|
608
|
+
| `POST /v1/c/:collection` | `{"doc":{...}}` | `201 {_id}` |
|
|
609
|
+
| `PATCH /v1/c/:collection/:id` | `{"patch":{...}}` | `200 {modified}` |
|
|
610
|
+
| `PUT /v1/c/:collection/:id` | `{"doc":{...}}` | `200 {modified}` |
|
|
611
|
+
| `DELETE /v1/c/:collection/:id` | — | `204` |
|
|
581
612
|
|
|
582
613
|
Reads (`GET /v1/c/:collection[/:id]`, `GET /v1/count?collection=…`,
|
|
583
614
|
`GET /v1/since?collection=…&cursor=…`) take no body and return
|
|
@@ -601,11 +632,11 @@ routes in front of `baerlyNode`" below).
|
|
|
601
632
|
`GET /v1/c/:collection` accepts three JSON-encoded query params; all are
|
|
602
633
|
optional and compose:
|
|
603
634
|
|
|
604
|
-
| Param
|
|
605
|
-
|
|
|
606
|
-
| `?where=`
|
|
607
|
-
| `?order=`
|
|
608
|
-
| `?limit=`
|
|
635
|
+
| Param | Encodes | Wire example |
|
|
636
|
+
| --------- | ----------------------------------------- | ----------------------------------------- |
|
|
637
|
+
| `?where=` | `PredicateWire` (see "Wire format" above) | `?where=%7B%22clauses%22%3A%5B%5D%7D` |
|
|
638
|
+
| `?order=` | `{ [field]: "asc" \| "desc" }` | `?order=%7B%22sent_at%22%3A%22desc%22%7D` |
|
|
639
|
+
| `?limit=` | bare integer (no JSON wrapper) | `?limit=50` |
|
|
609
640
|
|
|
610
641
|
`?order=` and `?where=` are JSON, **not** Rails-style `field:asc` —
|
|
611
642
|
the kernel `JSON.parse`s them and returns `400 SchemaError` on a flat
|
|
@@ -664,7 +695,9 @@ export default defineConfig({
|
|
|
664
695
|
tenant: "main",
|
|
665
696
|
target: "cloudflare",
|
|
666
697
|
auth: "none", // dev only — production swaps to "shared-secret" or a custom Verifier
|
|
667
|
-
collections: {
|
|
698
|
+
collections: {
|
|
699
|
+
/* … */
|
|
700
|
+
},
|
|
668
701
|
});
|
|
669
702
|
|
|
670
703
|
// src/server/index.ts
|
|
@@ -673,7 +706,6 @@ import config from "../../baerly.config.ts";
|
|
|
673
706
|
export default baerlyWorker(() => ({ config }));
|
|
674
707
|
```
|
|
675
708
|
|
|
676
|
-
|
|
677
709
|
`s3Storage` / `r2Storage` / `minioStorage` / `gcsStorage` from
|
|
678
710
|
`@gusto/baerly-storage/node` are re-exports of one factory family — same
|
|
679
711
|
shape (bucket + credentials), all hide `aws4fetch` / `@xmldom/xmldom`
|
|
@@ -692,11 +724,11 @@ returns `VerifierResult | null` (null = 401 unauth; thrown
|
|
|
692
724
|
`BaerlyError` = 500 operator fault — the dispatcher splits the
|
|
693
725
|
codes deliberately so on-call paging targets operator faults only).
|
|
694
726
|
|
|
695
|
-
| Preset | Identity source
|
|
696
|
-
| ------------------ |
|
|
697
|
-
| `sharedSecret` | `Authorization: Bearer <secret>` with constant-time compare
|
|
698
|
-
| `bearerJwt` | JWT over JWKS, `iss` + `aud` + `alg` allowlist
|
|
699
|
-
| `cloudflareAccess` | `Cf-Access-Jwt-Assertion` header (thin shim over `bearerJwt`)
|
|
727
|
+
| Preset | Identity source | Tenant derivation |
|
|
728
|
+
| ------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
|
729
|
+
| `sharedSecret` | `Authorization: Bearer <secret>` with constant-time compare | `tenantPrefix:` option (single-tenant only) |
|
|
730
|
+
| `bearerJwt` | JWT over JWKS, `iss` + `aud` + `alg` allowlist | Configurable `tenantClaim` (default `"tenant"`) or fixed `tenantPrefix:` override |
|
|
731
|
+
| `cloudflareAccess` | `Cf-Access-Jwt-Assertion` header (thin shim over `bearerJwt`) | Same as `bearerJwt` |
|
|
700
732
|
|
|
701
733
|
```ts
|
|
702
734
|
import { sharedSecret, bearerJwt, cloudflareAccess } from "@gusto/baerly-storage/auth";
|
|
@@ -744,20 +776,20 @@ options.
|
|
|
744
776
|
|
|
745
777
|
### Field reference
|
|
746
778
|
|
|
747
|
-
| Field
|
|
748
|
-
|
|
|
749
|
-
| `request_id`
|
|
750
|
-
| `method` / `path` / `status`
|
|
751
|
-
| `cache_status`
|
|
752
|
-
| `duration_ms`
|
|
753
|
-
| `outcome`
|
|
754
|
-
| `db.storage.class_a_ops_total`
|
|
755
|
-
| `db.storage.class_b_ops_total`
|
|
756
|
-
| `db.storage.<op>.calls_total`
|
|
757
|
-
| `db.storage.<op>.duration_ms_sum` / `_count
|
|
758
|
-
| `db.write.class_a_ops_per_logical_write_*`
|
|
759
|
-
| `db.r2.put.412_total` / `429_total`
|
|
760
|
-
| `error.code` / `error.message` / `error.stack` | Failure-path only. `error.code` is `BaerlyErrorCode`.
|
|
779
|
+
| Field | Meaning |
|
|
780
|
+
| ---------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
781
|
+
| `request_id` | Correlation key. Set from `X-Request-Id` if provided, else minted fresh. |
|
|
782
|
+
| `method` / `path` / `status` | HTTP request line + response code. |
|
|
783
|
+
| `cache_status` | `"hit" \| "miss" \| "bypass"` — Cloudflare adapter only. Node adapter omits. |
|
|
784
|
+
| `duration_ms` | `performance.now()` delta, monotonic wall-clock. |
|
|
785
|
+
| `outcome` | `"read"` (GET <400), `"committed"` (non-GET <400), `"conflict"` (409), or `"error"`. |
|
|
786
|
+
| `db.storage.class_a_ops_total` | PUT + DELETE + LIST count. S3-pricing Class A — cost-dominant. |
|
|
787
|
+
| `db.storage.class_b_ops_total` | GET count. S3-pricing Class B. |
|
|
788
|
+
| `db.storage.<op>.calls_total` | Per-op breakdown for `get` / `put` / `delete` / `list`. |
|
|
789
|
+
| `db.storage.<op>.duration_ms_sum` / `_count` | Per-call duration histogram. |
|
|
790
|
+
| `db.write.class_a_ops_per_logical_write_*` | Writer's per-`commit()` Class-A-op count. |
|
|
791
|
+
| `db.r2.put.412_total` / `429_total` | CAS conflicts (412) and storage rate-limit hits (429). |
|
|
792
|
+
| `error.code` / `error.message` / `error.stack` | Failure-path only. `error.code` is `BaerlyErrorCode`. |
|
|
761
793
|
|
|
762
794
|
Class-A / Class-B totals are the load-bearing fields — the cost
|
|
763
795
|
model puts a per-request ceiling on Class-A ops and the canonical
|
|
@@ -765,12 +797,12 @@ line is how you verify a deployed service stays under it.
|
|
|
765
797
|
|
|
766
798
|
### Log levels
|
|
767
799
|
|
|
768
|
-
| Level | What lands
|
|
769
|
-
| ------- |
|
|
770
|
-
| `error` | `status >= 500` or an exception was thrown.
|
|
771
|
-
| `warn` | Adds 4xx canonical lines and explicit `warn` records.
|
|
772
|
-
| `info` | Default. Adds 2xx canonical lines and lifecycle events.
|
|
773
|
-
| `debug` | Adds per-storage-op events. **High volume**; off in production.
|
|
800
|
+
| Level | What lands |
|
|
801
|
+
| ------- | --------------------------------------------------------------- |
|
|
802
|
+
| `error` | `status >= 500` or an exception was thrown. |
|
|
803
|
+
| `warn` | Adds 4xx canonical lines and explicit `warn` records. |
|
|
804
|
+
| `info` | Default. Adds 2xx canonical lines and lifecycle events. |
|
|
805
|
+
| `debug` | Adds per-storage-op events. **High volume**; off in production. |
|
|
774
806
|
|
|
775
807
|
Set `LOG_LEVEL` env var or the typed `observability.level` factory
|
|
776
808
|
option. Sink wiring (Workers Analytics Engine, OTel, Datadog) lives
|
|
@@ -885,15 +917,13 @@ const inner = baerlyNode({
|
|
|
885
917
|
serve({
|
|
886
918
|
port: Number(process.env["PORT"] ?? 8080),
|
|
887
919
|
fetch: (req) =>
|
|
888
|
-
new URL(req.url).pathname === "/health-check"
|
|
889
|
-
? Response.json({ ok: true })
|
|
890
|
-
: inner.fetch(req),
|
|
920
|
+
new URL(req.url).pathname === "/health-check" ? Response.json({ ok: true }) : inner.fetch(req),
|
|
891
921
|
});
|
|
892
922
|
```
|
|
893
923
|
|
|
894
924
|
The handle's `fetch` is the documented embedding seam (it's also what
|
|
895
925
|
the Vite dev middleware and tests consume) — there's no separate
|
|
896
|
-
`createApp` to reach for. If you don't need a
|
|
926
|
+
`createApp` to reach for. If you don't need a _custom_ probe path,
|
|
897
927
|
skip all of this and point your platform at the built-in
|
|
898
928
|
`GET /v1/healthz` (see above).
|
|
899
929
|
|
|
@@ -924,7 +954,12 @@ the network. Three recipes cover the common cases.
|
|
|
924
954
|
```ts
|
|
925
955
|
import { createBaerlyClient, type Fetcher } from "@gusto/baerly-storage/client";
|
|
926
956
|
|
|
927
|
-
const withHooks =
|
|
957
|
+
const withHooks =
|
|
958
|
+
(
|
|
959
|
+
next: Fetcher,
|
|
960
|
+
onSuccess: (req: Request, res: Response) => void,
|
|
961
|
+
onError: (req: Request, err: unknown) => void,
|
|
962
|
+
): Fetcher =>
|
|
928
963
|
async (req) => {
|
|
929
964
|
try {
|
|
930
965
|
const res = await next(req);
|
|
@@ -938,7 +973,8 @@ const withHooks = (next: Fetcher, onSuccess: (req: Request, res: Response) => vo
|
|
|
938
973
|
|
|
939
974
|
const client = createBaerlyClient({
|
|
940
975
|
baseUrl: "https://api.example.com",
|
|
941
|
-
fetch: withHooks(
|
|
976
|
+
fetch: withHooks(
|
|
977
|
+
globalThis.fetch,
|
|
942
978
|
(req, res) => log.info({ url: req.url, status: res.status }),
|
|
943
979
|
(req, err) => log.error({ url: req.url, err }),
|
|
944
980
|
),
|
|
@@ -952,7 +988,8 @@ const client = createBaerlyClient({
|
|
|
952
988
|
### Retry on transient failures (GET only)
|
|
953
989
|
|
|
954
990
|
```ts
|
|
955
|
-
const withRetry =
|
|
991
|
+
const withRetry =
|
|
992
|
+
(next: Fetcher, max = 3, baseMs = 100): Fetcher =>
|
|
956
993
|
async (req) => {
|
|
957
994
|
for (let i = 0; i < max - 1; i++) {
|
|
958
995
|
const res = await next(req.clone());
|
|
@@ -973,7 +1010,8 @@ one-shot stream.
|
|
|
973
1010
|
### Refresh credentials on 401
|
|
974
1011
|
|
|
975
1012
|
```ts
|
|
976
|
-
const withAuthRefresh =
|
|
1013
|
+
const withAuthRefresh =
|
|
1014
|
+
(next: Fetcher, refresh: () => Promise<string>): Fetcher =>
|
|
977
1015
|
async (req) => {
|
|
978
1016
|
const res = await next(req.clone());
|
|
979
1017
|
if (res.status !== 401) return res;
|
|
@@ -1022,6 +1060,10 @@ once. Pick by what you want to observe.
|
|
|
1022
1060
|
|
|
1023
1061
|
## Where to look next
|
|
1024
1062
|
|
|
1063
|
+
- **A call you expected doesn't type-check?** The public surface is
|
|
1064
|
+
additive-only locked (ADR-002), but the rare breaking change carries an
|
|
1065
|
+
old→new migration in `dist/CHANGELOG.md` (`cat dist/CHANGELOG.md`). The
|
|
1066
|
+
`.d.ts` types are canonical; the changelog is the recovery path.
|
|
1025
1067
|
- Per-symbol JSDoc: read the `.d.ts` chunks in this directory
|
|
1026
1068
|
(`db-*.d.ts`, `index-*.d.ts`, `client-*.d.ts`, …) — the bundler
|
|
1027
1069
|
splits them; `cat dist/*.d.ts` gives the union.
|