@gusto/create-baerly-storage 0.2.0 → 0.4.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 (29) hide show
  1. package/LICENSE +202 -0
  2. package/dist/index.js +54 -28
  3. package/dist/index.js.map +1 -1
  4. package/dist/templates/addons/docker/Dockerfile +8 -2
  5. package/dist/templates/minimal-cloudflare/AGENTS.md +140 -101
  6. package/dist/templates/minimal-cloudflare/README.md +43 -33
  7. package/dist/templates/minimal-cloudflare/package.json +7 -7
  8. package/dist/templates/minimal-cloudflare/wrangler.jsonc +1 -1
  9. package/dist/templates/minimal-node/.baerly/scaffold.json +1 -1
  10. package/dist/templates/minimal-node/.env.example +12 -5
  11. package/dist/templates/minimal-node/AGENTS.md +135 -107
  12. package/dist/templates/minimal-node/README.md +77 -44
  13. package/dist/templates/minimal-node/package.json +5 -5
  14. package/dist/templates/minimal-node/src/server/index.ts +22 -30
  15. package/dist/templates/minimal-node/src/server/resolve-storage.ts +18 -0
  16. package/dist/templates/minimal-node/vite.config.ts +0 -2
  17. package/dist/templates/react-cloudflare/AGENTS.md +77 -52
  18. package/dist/templates/react-cloudflare/README.md +25 -16
  19. package/dist/templates/react-cloudflare/index.html +1 -1
  20. package/dist/templates/react-cloudflare/package.json +12 -12
  21. package/dist/templates/react-cloudflare/wrangler.jsonc +1 -1
  22. package/dist/templates/react-node/.env.example +12 -5
  23. package/dist/templates/react-node/AGENTS.md +117 -81
  24. package/dist/templates/react-node/README.md +67 -37
  25. package/dist/templates/react-node/package.json +10 -10
  26. package/dist/templates/react-node/src/server/index.ts +18 -29
  27. package/dist/templates/react-node/src/server/resolve-storage.ts +18 -0
  28. package/dist/templates/react-node/vite.config.ts +0 -2
  29. package/package.json +16 -11
@@ -1,13 +1,23 @@
1
1
  # minimal-node
2
2
 
3
- A baerly app scaffolded with `@gusto/create-baerly-storage` for the **Node** target —
4
- any host that runs `node server.js` (Railway, Render, Fly without
5
- Docker, Heroku, a VM, a container scheduler, your laptop). Uses
6
- `@gusto/baerly-storage/node` against an S3-compatible bucket (AWS S3, R2 via
7
- S3-compat, Minio, etc.). Ships `auth: "none"` so the day-1 happy
8
- path works with zero env vars; flip to a shared secret or wire
9
- `bearerJwt` against your OIDC IdP before deploy — see "Going to
10
- production" below.
3
+ A baerly-storage app scaffolded with `@gusto/create-baerly-storage` for
4
+ the **Node** target — any host that runs `node server.js` (Railway,
5
+ Render, Fly without Docker, Heroku, a VM, a container scheduler, your
6
+ laptop). Runs zero-config on local filesystem storage out of the box;
7
+ promote to an S3-compatible bucket via `@gusto/baerly-storage/node` for
8
+ production. AWS S3 and Cloudflare R2 are the production-supported
9
+ targets; MinIO is the local conformance target, and other endpoints
10
+ require `baerly doctor --bucket` plus owner validation. Ships
11
+ `auth: "none"` so the day-1 happy path works with zero env vars; flip
12
+ to a shared secret or wire `bearerJwt` against your OIDC IdP before
13
+ deploy — see "Going to production" below.
14
+
15
+ **In production, the S3-compatible bucket is the durable state**
16
+ (locally, a `./.baerly-data` directory stands in). The Node process is
17
+ trusted app code with bucket credentials; it applies the
18
+ baerly-storage protocol, but it is not a database server. No daemon,
19
+ lock table, scheduler, or idle database bill; maintenance is automatic
20
+ and write-triggered.
11
21
 
12
22
  To ship a production Dockerfile alongside, scaffold with
13
23
  `--with=docker` — the add-on writes a multi-stage distroless Dockerfile,
@@ -23,13 +33,13 @@ minimal-node/
23
33
  ├── tsconfig.server.json # Node server TS project (src/server)
24
34
  ├── vite.config.ts # Vite SPA build → dist/client/
25
35
  ├── index.html # SPA shell — Vite's entry point
26
- ├── .env.example # storage creds, verifier, observability
36
+ ├── .env.example # storage selection (local-fs default) + PORT
27
37
  ├── baerly.config.ts # app, tenant, target, domain
28
38
  ├── AGENTS.md # deeper guide: predicates, schemas,
29
39
  │ # auth recipes, graduation
30
40
  ├── src/
31
41
  │ ├── server/
32
- │ │ └── index.ts # baerlyNode({ app, storage, verifier, webRoot, maintenance? }).listen(PORT)
42
+ │ │ └── index.ts # baerlyNode({ config, storage, webRoot }).listen(PORT)
33
43
  │ └── web/
34
44
  │ └── main.ts # SPA client entry — bundled into dist/client/
35
45
  └── README.md
@@ -45,27 +55,43 @@ pnpm dev
45
55
  `pnpm dev` runs `vite`. `baerlyDev()` from `@gusto/baerly-storage/dev/vite`
46
56
  mounts the Node HTTP listener as Connect middleware on the same Vite
47
57
  process that serves the SPA, so `GET /` hits the SPA on
48
- `http://localhost:5173/` and anything baerly handles (e.g.
58
+ `http://localhost:5173/` and anything baerly-storage handles (e.g.
49
59
  `GET /v1/healthz`) is served on the same origin — one process, one
50
60
  port, SPA + HMR + `/v1/*` in one command. Storage is `LocalFsStorage`
51
61
  rooted at `.baerly-data/`, so first-touch needs no S3 creds, no JWKS,
52
62
  and no second process.
53
63
 
54
- For production-shaped local runs (S3 and the bundled SPA served
55
- from `dist/client/`):
64
+ For production-shaped local runs (the built SPA served from
65
+ `dist/client/` alongside `/v1/*`):
56
66
 
57
67
  ```sh
58
68
  pnpm build
69
+ pnpm start
70
+ ```
71
+
72
+ `pnpm start` defaults to `localFsStorage()` (persists to
73
+ `./.baerly-data`, zero credentials, single-node only). To opt into
74
+ S3 or R2:
75
+
76
+ ```sh
77
+ # AWS S3
59
78
  BUCKET=... AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... pnpm start
79
+
80
+ # Cloudflare R2
81
+ R2_ACCOUNT_ID=... BUCKET=... AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... pnpm start
60
82
  ```
61
83
 
62
84
  The server reads `BUCKET`, `AWS_ACCESS_KEY_ID`,
63
- `AWS_SECRET_ACCESS_KEY` at startup. The default `auth: "none"`
64
- posture needs no auth env vars; if you adopt Pattern B / C from
65
- "Going to production" below, also set `SHARED_SECRET` (Pattern B)
66
- or `JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` (Pattern C). Optional:
67
- `R2_ACCOUNT_ID` (switches the storage factory from `s3Storage` to
68
- `r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT`.
85
+ `AWS_SECRET_ACCESS_KEY` at startup; when those are absent it falls
86
+ back to `localFsStorage()` for local runs. **In a detected deployment
87
+ (`NODE_ENV=production` or a known PaaS) it refuses to start and requires
88
+ a bucket** — local-fs is local-dev only (single-process, no
89
+ cross-process CAS or crash durability). The default `auth: "none"`
90
+ posture needs no auth env vars. The default entrypoint also reads
91
+ optional `AWS_REGION` and `PORT`. There is no `WEB_ROOT` env var — the SPA
92
+ path is the hard-coded `webRoot: "dist/client"` in
93
+ `src/server/index.ts`. Auth, tenant, and maintenance env vars require
94
+ adopting the documented code/config recipe first.
69
95
 
70
96
  Maintenance (compaction + GC) is automatic and in-band: it runs
71
97
  inline on the rare write that crosses a maintenance trigger — no env
@@ -75,9 +101,9 @@ snapshot ceiling and `BAERLY_MAINTENANCE_DISABLE=1` is a kill switch.
75
101
  For an explicit out-of-band sweep, call `runScheduledMaintenance`
76
102
  from `@gusto/baerly-storage`.
77
103
 
78
- After `pnpm build`, `http://localhost:8080/` serves the built SPA
79
- out of `dist/client/` and `http://localhost:8080/v1/*` is the
80
- baerly HTTP surface — single origin, no CORS.
104
+ After `pnpm build`, `pnpm start` serves the Vite-built SPA from
105
+ `dist/client/` on `http://localhost:8080/` and the baerly-storage HTTP
106
+ surface on `http://localhost:8080/v1/*` — single origin, no CORS.
81
107
 
82
108
  `pnpm typecheck` runs `tsc -b --noEmit` across both project
83
109
  references.
@@ -87,7 +113,12 @@ references.
87
113
  This scaffold runs anywhere `node server.js` runs. The `package.json`
88
114
  exposes `build` (Vite SPA + TS check) and `start`
89
115
  (`node --experimental-strip-types src/server/index.ts`); arrange your
90
- host to run `pnpm install && pnpm build`, then `pnpm start`.
116
+ host to run `pnpm install && pnpm build`, then `pnpm start` with the
117
+ storage/auth env vars exported or configured in the process manager.
118
+ A deployment must set a durable bucket (`BUCKET` + `AWS_*`, or
119
+ `R2_ACCOUNT_ID` + creds); the server fails loud rather than running on
120
+ local-fs, which is local-dev only. Self-hosting without a cloud bucket,
121
+ run MinIO on the box or use SQLite + Litestream.
91
122
 
92
123
  Concrete shapes:
93
124
 
@@ -96,10 +127,12 @@ Concrete shapes:
96
127
  repo, set env vars from `.env.example` in the dashboard, deploy.
97
128
  The platform's buildpack detects Node and runs the root scripts.
98
129
  - **VM / bare-metal**: clone, install Node 24+, copy `.env.example`
99
- to `.env`, run `pnpm install && pnpm build && pnpm start` under
100
- your process manager of choice (systemd, pm2, etc.).
130
+ to `.env` as a template, then export those values or configure them
131
+ in your process manager (Node does not load `.env` automatically).
132
+ Run `pnpm install && pnpm build && pnpm start` under systemd, pm2,
133
+ or your process manager of choice.
101
134
  - **Container** (Docker, k8s, ECS, Fly Machines with a Dockerfile):
102
- scaffold with `pnpm create @gusto/baerly-storage@latest --target=node --with=docker` to add
135
+ scaffold with `pnpm create @gusto/baerly-storage@latest my-app --target=node --with=docker` to add
103
136
  a production Dockerfile, `.dockerignore`, and `healthcheck.js`
104
137
  alongside this shape, then `docker build .`.
105
138
 
@@ -108,34 +141,34 @@ Verify: `curl https://<your-service>/v1/healthz`.
108
141
  ## Next steps
109
142
 
110
143
  1. **Read `AGENTS.md`** for the agent-facing guide — predicates,
111
- indexes, schemas, auth recipes (JWKS setup), the in-process
112
- maintenance loop, and the graduation criteria. (Claude Code
144
+ indexes, schemas, auth recipes (JWKS setup), write-triggered
145
+ maintenance, and the graduation criteria. (Claude Code
113
146
  users: `@gusto/create-baerly-storage` mirrors `AGENTS.md` to `CLAUDE.md` at
114
147
  scaffold time.)
115
148
  2. **Declare your first collection schema** in `baerly.config.ts`
116
- via `defineConfig({ collections: { ... } })` and pass it to
117
- `Db.create({ ..., collections })`. Schema validation is live;
118
- bad inserts return 422.
149
+ via `defineConfig({ collections: { ... } })`. The Node adapter
150
+ passes that config to `Db.create({ storage, app, tenant, config })`,
151
+ so schema validation is live and bad inserts return 400.
119
152
  3. **Set up production auth** — follow `AGENTS.md` → "Going to
120
153
  production". Pattern B flips `auth: "shared-secret"` and reads
121
154
  `SHARED_SECRET` from `process.env`; Pattern C wires `bearerJwt`
122
155
  against your OIDC IdP via an env-aware factory `verifier:`
123
156
  override (`JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE`).
124
- `baerly doctor --target=node` reports any gaps.
157
+ Verify the bucket with `baerly doctor --bucket=<s3-uri>` and the
158
+ deployed service with `curl https://<your-service>/v1/healthz`.
125
159
 
126
160
  ## When to graduate
127
161
 
128
- baerly is designed for the small-to-medium operating point. Past these
129
- thresholds, S3 list-prefix latency and per-class operation pricing
130
- start to dominate, and you're better off on a real database:
162
+ baerly-storage is designed for the small-to-medium operating point.
163
+ Past these thresholds, S3 list-prefix latency and per-class operation
164
+ pricing starts to dominate, and you've outgrown the workload envelope — move to a database service:
131
165
 
132
- - **~30 writes / minute / collection**
133
- - **~10 GB / tenant**
134
- - **~100 collections / tenant**
166
+ - **~30 writes / minute / collection** — per-collection throughput estimate (CAS-livelock model)
167
+ - **>10 GB / tenant** — R2 free-tier storage cost line (a billing signal, not a protocol ceiling)
168
+ - **~100 collections / tenant** — soft fan-out guideline (linear cost, bench-grounded; nothing enforces it)
135
169
 
136
- When you cross the soft ceiling, graduation is mechanical:
137
- `baerly export --target=postgres` walks your log entries (already
138
- Postgres-logical-replication-shaped) into a real DB. If your
170
+ When you cross these signals, graduation is mechanical:
171
+ `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a database service. If your
139
172
  deploy target is Cloudflare Workers and you'll accept Cloudflare
140
173
  lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
141
174
  per-write at M-size and is a natural next step. If you're on
@@ -143,12 +176,12 @@ AWS, on-prem, or want your data portable, managed Postgres is
143
176
  the typical destination. Either way — graduation is a Baerly win,
144
177
  not a churn event.
145
178
 
146
- **Export to a real database** (swap `--target=` for `sqlite`,
179
+ **Export to a database service** (swap `--target=` for `sqlite`,
147
180
  `postgres`, or `d1`):
148
181
 
149
182
  ```sh
150
183
  baerly export --target=postgres \
151
- --bucket=minimal-node --app=minimal-node --tenant=<your-tenant> \
184
+ --bucket=s3://minimal-node --app=minimal-node --tenant=<your-tenant> \
152
185
  --collection=<collection-name> --output=./out.sql
153
186
  ```
154
187
 
@@ -164,7 +197,7 @@ with zero env vars; every request resolves to `config.tenant`.
164
197
  Before deploy, follow `AGENTS.md` → "Going to production":
165
198
 
166
199
  - **Pattern B — `auth: "shared-secret"`.** Single-tenant
167
- server-to-server callers (CI, cron, internal services). Flip
200
+ server-to-server callers (CI and internal services). Flip
168
201
  `auth` in `baerly.config.ts` and put `SHARED_SECRET` in
169
202
  `process.env` (your PaaS / secret manager).
170
203
  - **Pattern C — JWKS-backed JWT (recommended for multi-tenant).**
@@ -13,14 +13,14 @@
13
13
  },
14
14
  "dependencies": {
15
15
  "@gusto/baerly-storage": "workspace:*",
16
- "aws4fetch": "^1.0.20"
16
+ "aws4fetch": "1.0.20"
17
17
  },
18
18
  "devDependencies": {
19
- "@types/node": "^24.0.0",
20
- "happy-dom": "^20.9.0",
19
+ "@types/node": "^26.0.1",
20
+ "happy-dom": "^20.10.6",
21
21
  "typescript": "^6.0.3",
22
- "vite": "^8.0.14",
23
- "vitest": "^4.1.7"
22
+ "vite": "^8.1.2",
23
+ "vitest": "^4.1.9"
24
24
  },
25
25
  "packageManager": "pnpm@11.1.2"
26
26
  }
@@ -5,42 +5,34 @@
5
5
  * with no header check. See AGENTS.md "Going to production" for
6
6
  * the recipe to flip `auth` or wire a custom verifier.
7
7
  *
8
- * Storage: AWS S3 by default; set `R2_ACCOUNT_ID` to switch to
9
- * Cloudflare R2 via the S3-compat endpoint.
8
+ * Storage: zero-config `LocalFsStorage` rooted at ./.baerly-data for
9
+ * local development — no credentials. Set `BUCKET` (+ AWS creds) for AWS
10
+ * S3, or `R2_ACCOUNT_ID` (+ creds) for Cloudflare R2. In a detected
11
+ * deployment (NODE_ENV=production or a known PaaS) the server REFUSES to
12
+ * start without a bucket — local-fs is a local-dev convenience only
13
+ * (single-process, no cross-process CAS, no crash durability), never a
14
+ * production store — so a missing/typo'd bucket fails loud instead of
15
+ * silently losing data.
10
16
  */
11
- import { baerlyNode, r2Storage, s3Storage } from "@gusto/baerly-storage/node";
12
- import type { Storage } from "@gusto/baerly-storage";
17
+ import { baerlyNode } from "@gusto/baerly-storage/node";
13
18
  import config from "../../baerly.config.ts";
19
+ import { resolveStorage } from "./resolve-storage.ts";
14
20
 
15
- const reqEnv = (name: string): string => {
16
- const v = process.env[name];
17
- if (v === undefined || v === "") {
18
- throw new Error(`Missing required env var: ${name}`);
19
- }
20
- return v;
21
- };
21
+ // Pick the storage backend from the environment (R2 / S3 / local-fs),
22
+ // failing loud if a deployment has no bucket. The policy lives in
23
+ // `./resolve-storage.ts` — edit it there to change how your app maps
24
+ // env vars to storage.
25
+ const { storage, label: storageLabel } = resolveStorage();
22
26
 
23
- const storage: Storage =
24
- process.env["R2_ACCOUNT_ID"] !== undefined
25
- ? r2Storage({
26
- accountId: reqEnv("R2_ACCOUNT_ID"),
27
- bucket: reqEnv("BUCKET"),
28
- credentials: {
29
- accessKeyId: reqEnv("AWS_ACCESS_KEY_ID"),
30
- secretAccessKey: reqEnv("AWS_SECRET_ACCESS_KEY"),
31
- },
32
- })
33
- : s3Storage({
34
- region: process.env["AWS_REGION"] ?? "us-east-1",
35
- bucket: reqEnv("BUCKET"),
36
- credentials: {
37
- accessKeyId: reqEnv("AWS_ACCESS_KEY_ID"),
38
- secretAccessKey: reqEnv("AWS_SECRET_ACCESS_KEY"),
39
- },
40
- });
27
+ // Announce the effective backend so the chosen store (and any surprise
28
+ // local-fs fallback) is visible in the deploy logs, not a surprise.
29
+ console.log(`[baerly] storage=${storageLabel}`);
41
30
 
42
31
  const PORT = Number(process.env["PORT"] ?? 8080);
43
32
 
44
- await baerlyNode({ config, storage }).listen(PORT);
33
+ // `webRoot` serves the Vite-built SPA from `dist/client/` (the
34
+ // `vite.config.ts` `build.outDir`) in production; `/v1/*` is handled
35
+ // by the kernel, everything else falls back to the SPA shell.
36
+ await baerlyNode({ config, storage, webRoot: "dist/client" }).listen(PORT);
45
37
 
46
38
  console.log(`minimal-node listening on :${PORT}`);
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Storage selection is your app's policy, surfaced here as an editable
3
+ * seam. The default is the library's `resolveStorageFromEnv`, in priority
4
+ * order:
5
+ * 1. R2_ACCOUNT_ID set → Cloudflare R2 (S3-compat endpoint)
6
+ * 2. BUCKET set → AWS S3
7
+ * 3. neither, local dev → LocalFsStorage (zero credentials)
8
+ * 4. neither, deployed → throw. It never silently falls back to a
9
+ * non-durable store (local-fs or in-memory) in a deployment — that
10
+ * is the failure mode that loses data in production.
11
+ *
12
+ * Replace this re-export with your own `(env) => ResolvedStorage` if your
13
+ * policy differs (a custom endpoint, MinIO, GCS, …). The resolver is
14
+ * exported and tested in `@gusto/baerly-storage/node` so every app shares
15
+ * one safe default instead of hand-rolling one.
16
+ */
17
+ export { resolveStorageFromEnv as resolveStorage } from "@gusto/baerly-storage/node";
18
+ export type { ResolvedStorage } from "@gusto/baerly-storage/node";
@@ -1,4 +1,3 @@
1
- import { resolve } from "node:path";
2
1
  import { defineConfig } from "vite";
3
2
  import { baerlyDev } from "@gusto/baerly-storage/dev/vite";
4
3
  import config from "./baerly.config.ts";
@@ -9,7 +8,6 @@ export default defineConfig({
9
8
  plugins: [
10
9
  baerlyDev({
11
10
  config,
12
- dataDir: resolve(import.meta.dirname, ".baerly-data"),
13
11
  }),
14
12
  ],
15
13
  });
@@ -1,16 +1,17 @@
1
1
  ---
2
2
  title: AGENTS.md — agent guidance for react-cloudflare
3
3
  audience: agent
4
- summary: How to develop and deploy react-cloudflare, a baerly app.
5
- tags: [agent-entry, baerly]
4
+ summary: How to develop and deploy react-cloudflare, a baerly-storage app.
5
+ tags: [agent-entry, baerly-storage]
6
6
  ---
7
7
 
8
8
  # AGENTS.md
9
9
 
10
+ <!-- stop:start -->
10
11
  ## STOP — read this before writing any storage code
11
12
 
12
13
  Your training data is dense with Postgres + Prisma/Drizzle, Mongo,
13
- and Firebase patterns. **None of them apply here.** This is a baerly
14
+ and Firebase patterns. **None of them apply here.** This is a baerly-storage
14
15
  app — a small, LLM-legible document database with a narrow API on top
15
16
  of S3-compatible storage. Before writing or modifying storage code,
16
17
  read:
@@ -18,7 +19,7 @@ read:
18
19
  - **`node_modules/@gusto/baerly-storage/dist/API.md`** — hand-authored
19
20
  public-API quickref. Read first. Lists every method, every error
20
21
  code, every example. If a pattern you want to use isn't here, it
21
- doesn't exist in baerly.
22
+ doesn't exist in baerly-storage.
22
23
  - **`node_modules/@gusto/baerly-storage/dist/*.d.ts`** — authoritative type
23
24
  signatures. `Db`, `Collection<T>`, `Query<T>`, and `Predicate<T>` are
24
25
  the whole API surface.
@@ -37,11 +38,13 @@ Common anti-patterns that compile but are wrong:
37
38
  picks the index automatically from `IndexDefinition`s in
38
39
  `baerly.config.ts`. See **Indexes** below.
39
40
 
41
+ <!-- stop:end -->
40
42
  ## What this is
41
43
 
42
- `react-cloudflare` is a baerly app scaffolded with `create-baerly-storage`.
43
- The Worker-side server lives in `src/server/`; the React client lives
44
- in `src/web/`. Configuration lives in `baerly.config.ts`.
44
+ `react-cloudflare` is a baerly-storage app scaffolded with
45
+ `create-baerly-storage`. The Worker-side server lives in `src/server/`;
46
+ the React client lives in `src/web/`. Configuration lives in
47
+ `baerly.config.ts`.
45
48
 
46
49
  Single package, single `vite` process: `@cloudflare/vite-plugin` runs
47
50
  the Worker inside `workerd` alongside the SPA dev server, and
@@ -55,19 +58,18 @@ shape declared in `baerly.config.ts`. The bare server-only version is
55
58
  `pnpm create @gusto/baerly-storage <app> --target=cloudflare`; this one is
56
59
  `--target=cloudflare --starter=react`.
57
60
 
58
- Public API docs: https://docs.baerly.dev/ (the JSDoc on
59
- `baerly-storage`'s `Db` and `Collection` is the canonical reference;
60
- read it via your editor's TS LS or via the published types).
61
+ Public API docs: the JSDoc on `baerly-storage`'s `Db` and `Collection`
62
+ is the canonical reference; read it via your editor's TS LS, the
63
+ published types, or `node_modules/@gusto/baerly-storage/dist/API.md`.
61
64
 
62
65
  ## Toolchain
63
66
 
64
67
  - **Package manager:** pnpm. The emitted repo pins
65
68
  `packageManager: pnpm@11.1.2`.
66
69
  - **Test runner:** vitest.
67
- - **Type checker:** TypeScript 5.6+. (The baerly-storage monorepo
68
- itself uses TypeScript 7 via `@typescript/native-preview`; this
69
- template tracks the broadly-compatible TS major so scaffolded
70
- apps work with the wider ecosystem.)
70
+ - **Type checker:** TypeScript 6.x, as pinned in `package.json`.
71
+ (The baerly-storage monorepo itself uses TypeScript 7 via
72
+ `@typescript/native-preview`.)
71
73
  - **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the
72
74
  code stays compatible with type-stripping runtimes (Node's
73
75
  `--experimental-strip-types`, esbuild's strip path). The flag bans
@@ -86,7 +88,7 @@ read it via your editor's TS LS or via the published types).
86
88
  | `pnpm install` | One-time bootstrap — the scaffold ships without `node_modules/`, so `pnpm verify` / `pnpm dev` fail with `Cannot find package '…'` until this runs once | seconds to a minute |
87
89
  | `pnpm verify` | `pnpm run typecheck && pnpm run test` — the green-light gate; what an agent should run as the smoke check before claiming the change works | seconds |
88
90
  | `pnpm typecheck` | TS typecheck across the worker + web project references (`tsc -b --noEmit`) | seconds |
89
- | `pnpm test` | `vitest run --passWithNoTests` — standalone `vitest.config.ts` (Node env, ignores `vite.config.ts` so the Cloudflare plugin doesn't load) | seconds |
91
+ | `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env, ignores `vite.config.ts` so the Cloudflare plugin doesn't load) | seconds |
90
92
  | `pnpm dev` | Run `vite` — the Cloudflare plugin runs the Worker inside `workerd` next to the SPA dev server; same origin on :5173 | seconds to start |
91
93
  | `pnpm build` | `tsc -b && vite build` — emits `dist/client/` for the Workers Assets binding | seconds |
92
94
  | `pnpm deploy` | `wrangler deploy` — ships Worker + assets in one shipment (auto-creates R2 on first run via `--x-provision`) | seconds |
@@ -104,7 +106,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
104
106
  | Path | What it is |
105
107
  | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
106
108
  | `src/server/index.ts` | Server entry — `/v1/*` routing + SPA fallback via `env.ASSETS` |
107
- | `wrangler.jsonc` | Cloudflare Worker manifest — name, R2 binding, Assets binding, vars, triggers, limits, observability |
109
+ | `wrangler.jsonc` | Cloudflare Worker manifest — name, R2 binding, Assets binding, vars |
108
110
  | `src/web/` | React+Vite frontend. Served by the Worker via Workers Assets in production. |
109
111
  | `index.html` | SPA shell — Vite's entry point at the project root; references `/src/web/main.tsx`. |
110
112
  | `vite.config.ts` | Vite + `@vitejs/plugin-react` + `@cloudflare/vite-plugin` — runs the Worker inside `workerd` in dev |
@@ -125,22 +127,34 @@ http://localhost:5173/<path>`) before declaring the task complete.
125
127
 
126
128
  ## When editing X, read Y
127
129
 
128
- - **Typed collections** — three ways to get a typed row, in DX order:
130
+ - **Typed collections** — two ways to get a typed row, in DX order.
131
+ The generic on `client.collection<N>(name)` is the collection
132
+ **name** (constrained to `CollectionNames<typeof config>`), not the
133
+ row type — so don't pass a row type to it.
129
134
  1. **Bind the config.** This template's `src/web/client.ts`
130
135
  already passes `config` to `createBaerlyClient({ baseUrl,
131
136
  config })`, so `client.collection("notes")` returns
132
137
  `ClientCollection<Row>` with `Row` derived from the
133
138
  `NoteSchema` declared in `baerly.config.ts`. No generic
134
- needed. Use `client.collection<Note>("notes")` (with `Note`
135
- exported from `baerly.config.ts` next to the schema)
136
- only when you need the row type by name elsewhere.
137
- 2. **Explicit generic, kernel constraint.** Without a declared
138
- collection, the second overload requires the row to satisfy
139
- the kernel's `DocumentData` shape (`{ [k: string]: DocumentValue }`):
139
+ needed. When you need to name that row type elsewhere, use
140
+ `RowOf<typeof config, "notes">` (re-exported from
141
+ `@gusto/baerly-storage`) — not a generic on `.collection()`.
142
+ 2. **Cast the handle (undeclared collection).** This template's
143
+ `client` is bound to `config`, so its names narrow to the
144
+ declared collections. To reach a collection that isn't in
145
+ `config`, build an unbound client
146
+ (`createBaerlyClient({ baseUrl })` with no `config`) — its names
147
+ widen to `string` and its row defaults to `DocumentData`. Cast at
148
+ the construction site for a narrower shape that still satisfies
149
+ the kernel's `DocumentData` constraint
150
+ (`{ [k: string]: DocumentValue }`):
140
151
  ```ts
152
+ import { createBaerlyClient, type ClientCollection } from "@gusto/baerly-storage/client";
141
153
  import type { DocumentData } from "@gusto/baerly-storage";
142
154
  interface Bookmark extends DocumentData { _id: string; url: string }
143
- await client.collection<Bookmark>("bookmarks").all();
155
+ const raw = createBaerlyClient({ baseUrl: "" });
156
+ const bookmarks = raw.collection("bookmarks") as ClientCollection<Bookmark>;
157
+ await bookmarks.all();
144
158
  ```
145
159
  A plain `interface Bookmark { _id: string; url: string }`
146
160
  (no index signature) will fail with TS2344 — the constraint
@@ -266,7 +280,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
266
280
 
267
281
  On a validation failure the server throws
268
282
  `BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
269
- HTTP clients see a 422 with the same envelope. Validation runs
283
+ HTTP clients see a 400 with the same envelope. Validation runs
270
284
  on the post-image so `update` and `replace` see the full doc, not
271
285
  just the patch.
272
286
 
@@ -287,7 +301,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
287
301
  (without the `doc` wrapper) returns
288
302
  `400 SchemaError "Request body must be { doc: object }"` — the
289
303
  wording is locked by `assertJsonBodyField` in the kernel. Canonical
290
- reference: the `Routes` type and the JSDoc on `createRouter` in
304
+ reference: the JSDoc on `createRouter` in
291
305
  `baerly-storage`.
292
306
 
293
307
  - **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
@@ -353,6 +367,7 @@ export default baerlyWorker<AppEnv>((env) => ({
353
367
  verifier: cloudflareAccess({
354
368
  teamDomain: env.CF_ACCESS_TEAM_DOMAIN,
355
369
  audienceTag: env.CF_ACCESS_AUDIENCE_TAG,
370
+ tenantPrefix: config.tenant,
356
371
  }),
357
372
  }),
358
373
  }));
@@ -362,12 +377,14 @@ Set both `CF_ACCESS_TEAM_DOMAIN` and `CF_ACCESS_AUDIENCE_TAG` in
362
377
  `wrangler.jsonc:vars` for prod (they're public identifiers, not
363
378
  secrets). Dev `wrangler dev` sees them as `undefined`, the spread
364
379
  short-circuits, and `config.auth: "none"` runs. Prod sees them set
365
- and `cloudflareAccess` engages.
380
+ and `cloudflareAccess` engages. Every verified token is pinned to
381
+ `config.tenant`; pass `tenantClaim` instead only when your Access JWT
382
+ actually carries a tenant claim.
366
383
 
367
384
  <!-- pattern-a:end -->
368
385
  <!-- pattern-b:start -->
369
386
  **Pattern B — `auth: "shared-secret"`.** Single-tenant
370
- server-to-server callers (CI, cron, internal services). No factory
387
+ server-to-server callers (CI and internal services). No factory
371
388
  code changes; only `baerly.config.ts` flips:
372
389
 
373
390
  ```ts
@@ -411,10 +428,11 @@ from the runtime env.
411
428
 
412
429
  <!-- pattern-b:end -->
413
430
  - **Extending the Worker with a custom route** — `baerlyWorker(...)`
414
- owns `/v1/*` + `/healthz`. For server-side endpoints the SPA
431
+ owns `/v1/*`, including `/v1/healthz`. For server-side endpoints the SPA
415
432
  client can't run on its own (the canonical case: an endpoint that
416
- needs `db.transaction(...)`, since `createBaerlyClient` is
417
- reads + by-id mutations only), wrap the worker `fetch`:
433
+ fans a write across several documents server-side, since
434
+ `createBaerlyClient` is reads + by-id mutations only), wrap the
435
+ worker `fetch`:
418
436
 
419
437
  ```ts
420
438
  // src/server/index.ts
@@ -447,10 +465,10 @@ from the runtime env.
447
465
  tenant: config.tenant,
448
466
  config,
449
467
  });
450
- // …db.transaction(...), db.collection(...).get(id), etc.
468
+ // …db.collection(...).insert(doc), db.collection(...).get(id), etc.
451
469
  return new Response(null, { status: 204 });
452
470
  }
453
- // Fall through to the baerly cascade for /v1/* + /healthz.
471
+ // Fall through to the baerly cascade for /v1/*, including /v1/healthz.
454
472
  return baerly.fetch!(req, env, ctx);
455
473
  },
456
474
  } satisfies ExportedHandler<BaerlyEnv>;
@@ -498,7 +516,8 @@ from the runtime env.
498
516
  into the predicate so the index planner can prune
499
517
  (`db.collection("notes").where({ ... }).all()`), or maintain a
500
518
  side-projection (D1/KV/search index) populated incrementally from
501
- the `/v1/since` log feed or from a write hook — never re-scan per
519
+ the `/v1/since?collection=<name>&cursor=<opaque>` log feed or from
520
+ a write hook — never re-scan per
502
521
  request.
503
522
 
504
523
  ## Maintenance
@@ -517,7 +536,7 @@ maintenance, so the published idle-reader cost bound holds.
517
536
  A bucket maintains itself as long as it takes writes. A bucket served read-only does
518
537
  not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
519
538
  graduate once a collection is large. See docs/about/graduation.md for the per-tier
520
- envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
539
+ envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
521
540
 
522
541
  Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
523
542
  your own schedule. Not required for steady-state operation.
@@ -525,28 +544,32 @@ your own schedule. Not required for steady-state operation.
525
544
 
526
545
  ## When to graduate
527
546
 
528
- baerly is designed for the small-to-medium operating point. The cost
529
- model puts the soft ceiling at:
547
+ baerly-storage is designed for the small-to-medium operating point.
548
+ The cost model puts the soft ceiling at:
530
549
 
531
- - **~30 writes / minute / collection**
532
- - **~10 GB / tenant**
533
- - **~100 collections / tenant**
550
+ - **~30 writes / minute / collection** (throughput ceiling — model/estimate)
551
+ - **>10 GB / tenant stored** (R2 free-tier storage line — a cost signal, not a protocol ceiling)
552
+ - **~100 collections / tenant** (soft fan-out guideline — bench-grounded linear cost)
534
553
 
535
- Past those, S3 list-prefix latency, manifest fold cost, and per-class
536
- op pricing start to dominate; you're better off on a real database.
554
+ At M-size (~30 writes/min) the projected cost is ~$18/mo on R2. Past
555
+ those, per-class op pricing and fan-out scan cost start to dominate;
556
+ you've outgrown the workload envelope — move to a database service (D1 / Postgres) suited to higher scale.
537
557
  Pick your graduation target:
538
558
  - **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
539
559
  - **Off-Workers or portability matters:** managed Postgres.
540
560
  - **Single-instance Node:** SQLite via Litestream.
541
561
 
542
562
  Either way, the export below is mechanical because log entries are
543
- Postgres-logical-replication-shaped — graduation is a Baerly win,
544
- not a churn event.
563
+ Debezium-style CDC change events — graduation is a baerly-storage
564
+ win, not a churn event.
545
565
 
546
- **Estimate your current rate:** `baerly admin usage --target=...`
547
- lists recent log entries per collection and computes
548
- writes/min. Warning at 50% of the ceiling; export suggestion at
549
- 100%.
566
+ **Estimate your current rate:** for Node/self-hosted buckets,
567
+ `baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
568
+ --tenant=<tenant>` lists recent log entries per collection and computes
569
+ writes/min. On Cloudflare, use canonical logs for trend history and
570
+ `baerly cost --bucket=<bucket-uri> --collection=<collection>` for the
571
+ current operation-cost projection until the usage scanner is wired to
572
+ R2 bindings.
550
573
 
551
574
  **Export when ready:** `baerly export --target=sqlite|postgres|d1
552
575
  --bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a
@@ -629,7 +652,8 @@ const result = useQuery(
629
652
  ```
630
653
 
631
654
  `useQuery` re-runs the callback when `deps` changes OR when the
632
- `/v1/since` long-poll batches a non-empty change for any subscribed
655
+ `/v1/since?collection=<name>&cursor=<opaque>` long-poll batches a
656
+ non-empty change for any subscribed
633
657
  collection. Idle long-poll cycles (empty batches) drop at the
634
658
  `subscription-pool` layer, so a steady-state collection costs zero list
635
659
  reads. Add a `<select>` bound to `setFilter` and the list narrows live.
@@ -697,14 +721,15 @@ JSON-merge-patch (RFC 7386) semantics apply on `update()`:
697
721
  omitting `tags` from an update preserves the existing value;
698
722
  passing `tags: null` deletes the field; passing `tags: []` sets
699
723
  it to an empty array. Note that `null` is the deletion sentinel,
700
- not a storable value — `DocumentValue` doesn't include `null`,
701
- so `find()` returns deleted fields as `undefined`, not `null`.
724
+ not a storable value — `DocumentValue` doesn't include `null`, so
725
+ subsequent `get()` / query results expose deleted optional fields as
726
+ `undefined`, not `null`.
702
727
  That's why this recipe uses `.optional()` and not `.nullable()`.
703
728
 
704
729
  ## Pointers
705
730
 
706
731
  - `baerly.config.ts` — app config + `NoteSchema` + inferred `Note` type.
707
732
  - `src/server/index.ts` — Worker entry.
708
- - `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars, cron, observability).
733
+ - `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars).
709
734
  - `vite.config.ts` — Vite + `@vitejs/plugin-react` + `@cloudflare/vite-plugin`.
710
735
  - `package.json` — root scripts + dependencies.