@gusto/create-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.
@@ -18,17 +18,17 @@
18
18
  "zod": "^4.4.3"
19
19
  },
20
20
  "devDependencies": {
21
- "@cloudflare/vite-plugin": "^1.39.0",
21
+ "@cloudflare/vite-plugin": "^1.40.1",
22
22
  "@cloudflare/workers-types": "^4",
23
- "@types/node": "^24.0.0",
24
- "@types/react": "^19.2.15",
23
+ "@types/node": "^25.9.2",
24
+ "@types/react": "^19.2.17",
25
25
  "@types/react-dom": "^19.0.0",
26
26
  "@vitejs/plugin-react": "^6.0.2",
27
- "happy-dom": "^20.9.0",
27
+ "happy-dom": "^20.10.2",
28
28
  "typescript": "^6.0.3",
29
- "vite": "^8.0.14",
30
- "vitest": "^4.1.7",
31
- "wrangler": "^4.95.0"
29
+ "vite": "^8.0.16",
30
+ "vitest": "^4.1.8",
31
+ "wrangler": "^4.99.0"
32
32
  },
33
33
  "packageManager": "pnpm@11.1.2"
34
34
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  // Cloudflare Worker manifest. See `AGENTS.md` for what each field
3
- // drives (R2 binding, assets, vars, cron, observability) and how
3
+ // drives (R2 binding, assets, vars) and how
4
4
  // the verifier consumes the vars.
5
5
  "$schema": "node_modules/wrangler/config-schema.json",
6
6
  "name": "react-cloudflare",
@@ -135,22 +135,34 @@ http://localhost:5173/<path>`) before declaring the task complete.
135
135
 
136
136
  ## When editing X, read Y
137
137
 
138
- - **Typed collections** — three ways to get a typed row, in DX order:
138
+ - **Typed collections** — two ways to get a typed row, in DX order.
139
+ The generic on `client.collection<N>(name)` is the collection
140
+ **name** (constrained to `CollectionNames<typeof config>`), not the
141
+ row type — so don't pass a row type to it.
139
142
  1. **Bind the config.** This template's `src/web/client.ts`
140
143
  already passes `config` to `createBaerlyClient({ baseUrl,
141
144
  config })`, so `client.collection("notes")` returns
142
145
  `ClientCollection<Row>` with `Row` derived from the
143
146
  `NoteSchema` declared in `baerly.config.ts`. No generic
144
- needed. Use `client.collection<Note>("notes")` (with `Note`
145
- exported from `baerly.config.ts` next to the schema)
146
- only when you need the row type by name elsewhere.
147
- 2. **Explicit generic, kernel constraint.** Without a declared
148
- collection, the second overload requires the row to satisfy
149
- the kernel's `DocumentData` shape (`{ [k: string]: DocumentValue }`):
147
+ needed. When you need to name that row type elsewhere, use
148
+ `RowOf<typeof config, "notes">` (re-exported from
149
+ `@gusto/baerly-storage`) — not a generic on `.collection()`.
150
+ 2. **Cast the handle (undeclared collection).** This template's
151
+ `client` is bound to `config`, so its names narrow to the
152
+ declared collections. To reach a collection that isn't in
153
+ `config`, build an unbound client
154
+ (`createBaerlyClient({ baseUrl })` with no `config`) — its names
155
+ widen to `string` and its row defaults to `DocumentData`. Cast at
156
+ the construction site for a narrower shape that still satisfies
157
+ the kernel's `DocumentData` constraint
158
+ (`{ [k: string]: DocumentValue }`):
150
159
  ```ts
160
+ import { createBaerlyClient, type ClientCollection } from "@gusto/baerly-storage/client";
151
161
  import type { DocumentData } from "@gusto/baerly-storage";
152
162
  interface Bookmark extends DocumentData { _id: string; url: string }
153
- await client.collection<Bookmark>("bookmarks").all();
163
+ const raw = createBaerlyClient({ baseUrl: "" });
164
+ const bookmarks = raw.collection("bookmarks") as ClientCollection<Bookmark>;
165
+ await bookmarks.all();
154
166
  ```
155
167
  A plain `interface Bookmark { _id: string; url: string }`
156
168
  (no index signature) will fail with TS2344 — the constraint
@@ -273,7 +285,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
273
285
 
274
286
  On a validation failure the server throws
275
287
  `BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
276
- HTTP clients see a 422 with the same envelope. Validation runs
288
+ HTTP clients see a 400 with the same envelope. Validation runs
277
289
  on the post-image so `update` and `replace` see the full doc, not
278
290
  just the patch.
279
291
 
@@ -302,9 +314,11 @@ http://localhost:5173/<path>`) before declaring the task complete.
302
314
  is ignored. The adapter reads `config.auth` to pick its verifier;
303
315
  a `verifier:` on `baerlyNode({ ... })` overrides it. The schema-
304
316
  bound `notes` collection (`baerly.config.ts:NoteSchema`) runs
305
- server-side regardless of the auth posture. `baerly doctor
306
- --target=node` warns on `"none"` for deploy targets. See "Going to
307
- production" below for the two production-fit recipes.
317
+ server-side regardless of the auth posture. There is no `baerly
318
+ doctor --target=node` backend today; verify bucket CAS with
319
+ `baerly doctor --bucket=<s3-uri>` and probe `/v1/healthz` after
320
+ deploy. See "Going to production" below for the two production-fit
321
+ recipes.
308
322
 
309
323
  ### Going to production
310
324
 
@@ -324,9 +338,9 @@ auth: "shared-secret", // ← flip from "none"
324
338
 
325
339
  Dev: put `SHARED_SECRET=dev-shared-secret` in `.env`. Prod: set
326
340
  `SHARED_SECRET` in the process environment (your PaaS / secret
327
- manager). `baerly doctor --target=node` FAILs if
328
- `auth: "shared-secret"` is set without `SHARED_SECRET` reachable from
329
- `process.env`.
341
+ manager). The Node process fails closed if `auth: "shared-secret"`
342
+ is set without `SHARED_SECRET` reachable from `process.env`; verify
343
+ the live bucket separately with `baerly doctor --bucket=<s3-uri>`.
330
344
 
331
345
  <!-- pattern-b:end -->
332
346
  <!-- pattern-c:start -->
@@ -360,6 +374,7 @@ await baerlyNode({
360
374
  jwks: process.env["JWKS_URL"],
361
375
  issuer: process.env["JWT_ISSUER"]!,
362
376
  audience: process.env["JWT_AUDIENCE"]!,
377
+ tenantPrefix: config.tenant, // or tenantClaim: "tenant"
363
378
  }),
364
379
  }),
365
380
  }).listen(Number(process.env["PORT"] ?? 8080));
@@ -367,7 +382,9 @@ await baerlyNode({
367
382
 
368
383
  Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
369
384
  `config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` +
370
- `JWT_AUDIENCE` and `bearerJwt` engages.
385
+ `JWT_AUDIENCE` and `bearerJwt` engages. Use `tenantClaim` when your
386
+ IdP issues one tenant per token; use `tenantPrefix` for single-tenant
387
+ apps or tenancy enforced outside Baerly.
371
388
 
372
389
  <!-- pattern-c:end -->
373
390
  - **Storage backend** — `src/server/index.ts` picks between
@@ -431,7 +448,8 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
431
448
  into the predicate so the index planner can prune
432
449
  (`db.collection("notes").where({ ... }).all()`), or maintain a
433
450
  side-projection (Postgres/SQLite/search index) populated
434
- incrementally from the `/v1/since` log feed or from a write hook —
451
+ incrementally from the `/v1/since?collection=<name>&cursor=<opaque>`
452
+ log feed or from a write hook —
435
453
  never re-scan per request.
436
454
 
437
455
  ## Maintenance
@@ -450,7 +468,7 @@ maintenance, so the published idle-reader cost bound holds.
450
468
  A bucket maintains itself as long as it takes writes. A bucket served read-only does
451
469
  not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
452
470
  graduate once a collection is large. See docs/about/graduation.md for the per-tier
453
- envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
471
+ envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
454
472
 
455
473
  Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
456
474
  your own schedule. Not required for steady-state operation.
@@ -465,7 +483,7 @@ model puts the soft ceiling at:
465
483
  - **~10 GB / tenant**
466
484
  - **~100 collections / tenant**
467
485
 
468
- Past those, S3 list-prefix latency, manifest fold cost, and per-class
486
+ Past those, S3 list-prefix latency, snapshot fold cost, and per-class
469
487
  op pricing start to dominate; you're better off on a real database.
470
488
  Pick your graduation target:
471
489
  - **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
@@ -473,13 +491,16 @@ Pick your graduation target:
473
491
  - **Single-instance Node:** SQLite via Litestream.
474
492
 
475
493
  Either way, the export below is mechanical because log entries are
476
- Postgres-logical-replication-shaped — graduation is a Baerly win,
494
+ Debezium-style CDC change events — graduation is a Baerly win,
477
495
  not a churn event.
478
496
 
479
- **Estimate your current rate:** `baerly admin usage --target=...`
480
- lists recent log entries per collection and computes
481
- writes/min. Warning at 50% of the ceiling; export suggestion at
482
- 100%.
497
+ **Estimate your current rate:** for Node/self-hosted buckets,
498
+ `baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
499
+ --tenant=<tenant>` lists recent log entries per collection and computes
500
+ writes/min. On Cloudflare, use canonical logs for trend history and
501
+ `baerly cost --bucket=<bucket-uri> --collection=<collection>` for the
502
+ current operation-cost projection until the usage scanner is wired to
503
+ R2 bindings.
483
504
 
484
505
  **Export when ready:** `baerly export --target=sqlite|postgres|d1
485
506
  --bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a
@@ -562,7 +583,8 @@ const result = useQuery(
562
583
  ```
563
584
 
564
585
  `useQuery` re-runs the callback when `deps` changes OR when the
565
- `/v1/since` long-poll batches a non-empty change for any subscribed
586
+ `/v1/since?collection=<name>&cursor=<opaque>` long-poll batches a
587
+ non-empty change for any subscribed
566
588
  collection. Idle long-poll cycles (empty batches) drop at the
567
589
  `subscription-pool` layer, so a steady-state collection costs zero list
568
590
  reads. Add a `<select>` bound to `setFilter` and the list narrows live.
@@ -10,6 +10,8 @@ one-collection `notes` schema you extend; flip to a shared secret
10
10
  or wire `bearerJwt` against your OIDC IdP before deploy — see
11
11
  "Production auth" below.
12
12
 
13
+ **The only persistent component is your S3-compatible bucket** — there is no separate database server or daemon to deploy alongside the node process, no idle bill, and maintenance is automatic and write-triggered (no cron, no sidecar, no scheduler).
14
+
13
15
  To ship a production Dockerfile alongside, scaffold with
14
16
  `--with=docker` — the add-on writes a multi-stage distroless Dockerfile,
15
17
  `.dockerignore`, and `healthcheck.js` into this same shape.
@@ -30,7 +32,7 @@ react-node/
30
32
  ├── CLAUDE.md # same content (Claude Code reads this)
31
33
  ├── src/
32
34
  │ ├── server/
33
- │ │ └── index.ts # baerlyNode({ app, storage, verifier, webRoot, maintenance? }).listen(PORT)
35
+ │ │ └── index.ts # baerlyNode({ config, storage, verifier, webRoot }).listen(PORT)
34
36
  │ └── web/
35
37
  │ ├── main.tsx # React entry
36
38
  │ ├── App.tsx # Provider + new-note form (useMutation)
@@ -51,14 +53,14 @@ pnpm dev
51
53
  mounts the Node HTTP listener as Connect middleware on the same Vite
52
54
  process that serves the SPA, so `GET /` hits the SPA on
53
55
  `http://localhost:5173/` and anything baerly handles (e.g.
54
- `GET /v1/healthz`, `POST /v1/notes`) is served on the same origin —
56
+ `GET /v1/healthz`, `POST /v1/c/notes`) is served on the same origin —
55
57
  one process, one port, SPA + HMR + `/v1/*` in one command. Storage is
56
58
  `LocalFsStorage` rooted at `.baerly-data/`, so first-touch needs no
57
59
  S3 creds, no JWKS, and no second process.
58
60
 
59
61
  Open <http://localhost:5173>. Type a note, hit "Add note." Open a
60
62
  second tab — inserts, edits, and deletes in one tab appear in the
61
- other over the `/v1/since` long-poll.
63
+ other over the `/v1/since?collection=notes&cursor=...` long-poll.
62
64
 
63
65
  For production-shaped local runs (S3 and the bundled SPA served
64
66
  from `dist/client/`):
@@ -137,7 +139,7 @@ the `NoteSchema` still validates writes server-side. Before deploy,
137
139
  follow `AGENTS.md` → "Going to production":
138
140
 
139
141
  - **Pattern B — `auth: "shared-secret"`.** Single-tenant
140
- server-to-server callers (CI, cron, internal services). Flip
142
+ server-to-server callers (CI and internal services). Flip
141
143
  `auth` in `baerly.config.ts` and put `SHARED_SECRET` in
142
144
  `process.env` (your PaaS / secret manager).
143
145
  - **Pattern C — JWKS-backed JWT (recommended for multi-tenant).**
@@ -158,8 +160,7 @@ start to dominate, and you're better off on a real database:
158
160
  - **~100 collections / tenant**
159
161
 
160
162
  When you cross the soft ceiling, graduation is mechanical:
161
- `baerly export --target=postgres` walks your log entries (already
162
- Postgres-logical-replication-shaped) into a real DB. If your
163
+ `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a real DB. If your
163
164
  deploy target is Cloudflare Workers and you'll accept Cloudflare
164
165
  lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
165
166
  per-write at M-size and is a natural next step. If you're on
@@ -172,7 +173,7 @@ not a churn event.
172
173
 
173
174
  ```sh
174
175
  baerly export --target=postgres \
175
- --bucket=react-node --app=react-node --tenant=<your-tenant> \
176
+ --bucket=s3://react-node --app=react-node --tenant=<your-tenant> \
176
177
  --collection=<collection-name> --output=./out.sql
177
178
  ```
178
179
 
@@ -19,14 +19,14 @@
19
19
  "zod": "^4.4.3"
20
20
  },
21
21
  "devDependencies": {
22
- "@types/node": "^24.0.0",
23
- "@types/react": "^19.2.15",
22
+ "@types/node": "^25.9.2",
23
+ "@types/react": "^19.2.17",
24
24
  "@types/react-dom": "^19.0.0",
25
25
  "@vitejs/plugin-react": "^6.0.2",
26
- "happy-dom": "^20.9.0",
26
+ "happy-dom": "^20.10.2",
27
27
  "typescript": "^6.0.3",
28
- "vite": "^8.0.14",
29
- "vitest": "^4.1.7"
28
+ "vite": "^8.0.16",
29
+ "vitest": "^4.1.8"
30
30
  },
31
31
  "packageManager": "pnpm@11.1.2"
32
32
  }
package/package.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "@gusto/create-baerly-storage",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Scaffold a new baerly-storage app. Run via `pnpm create @gusto/baerly-storage@latest -- my-app --target=cloudflare`.",
5
5
  "homepage": "https://github.com/Gusto/baerly-storage#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Gusto/baerly-storage/issues"
8
8
  },
9
- "license": "MIT",
9
+ "license": "Apache-2.0",
10
10
  "author": "Eric Baer",
11
11
  "repository": {
12
12
  "type": "git",
@@ -20,17 +20,11 @@
20
20
  "dist"
21
21
  ],
22
22
  "type": "module",
23
- "exports": {
24
- ".": {
25
- "types": "./src/index.ts",
26
- "import": "./src/index.ts"
27
- }
28
- },
29
23
  "publishConfig": {
30
- "access": "restricted"
24
+ "access": "public"
31
25
  },
32
26
  "dependencies": {
33
- "@clack/prompts": "^1.4.0",
27
+ "@clack/prompts": "^1.5.1",
34
28
  "citty": "^0.2.2",
35
29
  "picocolors": "^1.1.1"
36
30
  },