@gusto/create-baerly-storage 0.1.1 → 0.2.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.
@@ -5,7 +5,13 @@
5
5
  # Runtime path: node --experimental-strip-types src/server/index.ts.
6
6
  # No `tsc` emit at runtime — the server runs straight off TS source.
7
7
  # The SPA bundle (vite build) lives under dist/client/ and is served
8
- # by createListener({ webRoot }).
8
+ # by baerlyNode({ webRoot }).
9
+ #
10
+ # If you diverge and compile the server with `tsc -b` instead of
11
+ # strip-types, exclude `*.tsbuildinfo` from the build context (or run
12
+ # `tsc -b --force`): a stale tsbuildinfo copied in lets incremental
13
+ # `tsc -b` skip emit, and the container then crashes on a missing
14
+ # dist/server/*.js.
9
15
 
10
16
  # Base images are tag-pinned (not digest-pinned) so this template
11
17
  # stays fresh as new patch images ship. Once you vendor this file,
@@ -29,7 +29,7 @@ Common anti-patterns that compile but are wrong:
29
29
  `db.collection(name).insert(row)` and `.where({ ... }).all()`.
30
30
  - `z.string().nullable()` in a schema — `DocumentValue` excludes
31
31
  `null`. Use `.optional()`; `null` in an update patch is the RFC
32
- 7396 deletion sentinel, not a storable value.
32
+ 7386 deletion sentinel, not a storable value.
33
33
  - Raw SQL strings, `WHERE` clauses, hand-built query AST — the only
34
34
  query surface is `db.collection(...).where({ field: value }).all()` or
35
35
  `.where(q => q.gte("count", 1))`. See **Predicates** below.
@@ -456,37 +456,6 @@ from the runtime env.
456
456
  only, so setting them via `wrangler secret put` would silently
457
457
  defeat the doctor check.
458
458
 
459
- - **Maintenance loop (Cloudflare)** — opt-in. Add
460
- `"triggers": { "crons": ["* * * * *"] }` to `wrangler.jsonc` and
461
- wire `scheduled` on the options the factory returns from `baerlyWorker((env) => ({ ... }))`. The
462
- handler is your code, so you choose what to call
463
- (`runScheduledMaintenance`, `compact`, `runGc`) and which
464
- `current.json` keys to target. Multi-tenant deployments iterate
465
- their own keys; single-tenant deployments call once with a fixed
466
- key. See the JSDoc on `WorkerScheduledHandler` in
467
- `@gusto/baerly-storage/cloudflare` and `runScheduledMaintenance` in
468
- `@gusto/baerly-storage/maintenance` for the wiring + free-vs-paid-tier
469
- subrequest-budget guidance.
470
-
471
- Maintenance emits one canonical info line per run on stdout
472
- (Workers Logs ingestion). Filter your log stream on
473
- `"unit_of_work": "maintenance"` and read these fields:
474
-
475
- - `compact_written` — log entries folded into the new snapshot
476
- this tick (`0` when the live tail was below
477
- `minEntriesToCompact`). Only set when the tick called
478
- `runScheduledMaintenance` or `compact` directly; isolated
479
- `runGc` ticks emit their own `unit_of_work: "gc"` line.
480
- - `gc_swept` — keys deleted this tick (`0` when no candidates
481
- aged out). Only set when the tick called
482
- `runScheduledMaintenance` or `runGc` directly.
483
- - The kernel also emits the recorder-bag fields alongside:
484
- `db.compact.entries_folded_p50` / `_p99` / `_count` / `_sum`,
485
- `db.manifest.lag_window_depth`, `db.orphan.candidate_count`,
486
- `db.gc.entries_swept_per_second`, `db.gc.swept_total`.
487
- Useful for dashboards; the four explicit fields above are
488
- the at-a-glance summary.
489
-
490
459
  - **Deploy** — `baerly deploy --target=cloudflare` runs
491
460
  `wrangler deploy --x-provision --x-auto-create` (Wrangler 4.10+)
492
461
  to auto-create the declared R2 buckets and ship the Worker. When
@@ -513,6 +482,28 @@ from the runtime env.
513
482
  the `/v1/since` log feed or from a write hook — never re-scan per
514
483
  request.
515
484
 
485
+ ## Maintenance
486
+
487
+ <!-- pattern-d:start -->
488
+ Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
489
+ timer, no lock, no app-config knob — identical on every host. Every write runs a
490
+ bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
491
+ whose default is safe on every tier. A size-ratio threshold means idle buckets pay
492
+ nothing. Concurrent folds are safe without coordination: the commit is a
493
+ compare-and-swap, so a fold that loses to a concurrent write is simply discarded and
494
+ its leftover swept by GC. On Cloudflare the fold is deferred past the response via
495
+ ctx.waitUntil; everywhere else it runs inline. **Reads are pure** — they never run
496
+ maintenance, so the published idle-reader cost bound holds.
497
+
498
+ A bucket maintains itself as long as it takes writes. A bucket served read-only does
499
+ not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
500
+ graduate once a collection is large. See docs/about/graduation.md for the per-tier
501
+ envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
502
+
503
+ Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
504
+ your own schedule. Not required for steady-state operation.
505
+ <!-- pattern-d:end -->
506
+
516
507
  ## When to graduate
517
508
 
518
509
  baerly is designed for the small-to-medium operating point. The cost
@@ -29,7 +29,7 @@ Common anti-patterns that compile but are wrong:
29
29
  `db.collection(name).insert(row)` and `.where({ ... }).all()`.
30
30
  - `z.string().nullable()` in a schema — `DocumentValue` excludes
31
31
  `null`. Use `.optional()`; `null` in an update patch is the RFC
32
- 7396 deletion sentinel, not a storable value.
32
+ 7386 deletion sentinel, not a storable value.
33
33
  - Raw SQL strings, `WHERE` clauses, hand-built query AST — the only
34
34
  query surface is `db.collection(...).where({ field: value }).all()` or
35
35
  `.where(q => q.gte("count", 1))`. See **Predicates** below.
@@ -364,52 +364,6 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
364
364
  `() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
365
365
  factory through the seam.
366
366
 
367
- - **Maintenance loop (Node)** — `src/server/index.ts` passes a
368
- `maintenance: { collections, tenants }` option to `baerlyNode`.
369
- Each tick (hourly by default; override via
370
- `maintenance.intervalMs`) runs one compact+GC pass per
371
- `(tenant, collection)` pair against the engine's default
372
- unbounded maintenance profile (folds the entire live tail; sweeps
373
- every aged-out candidate the GC marks).
374
-
375
- Opt-in via the `MAINTENANCE_COLLECTIONS` env var — a comma-
376
- separated list of collection slugs:
377
-
378
- ```sh
379
- MAINTENANCE_COLLECTIONS=tickets,comments
380
- ```
381
-
382
- When unset, the entry passes `maintenance: undefined` to
383
- `baerlyNode` and no in-process loop runs. Operators who prefer
384
- external scheduling can wire a separate cron trigger (PaaS cron,
385
- k8s CronJob, systemd timer) per collection that invokes
386
- `runMaintenanceTick` directly — that function stays exported
387
- from `@gusto/baerly-storage/node`.
388
-
389
- The template is single-tenant by default (`tenants: [TENANT]`).
390
- Multi-tenant deployments override the `tenants` array in
391
- `src/server/index.ts`; the cross-product `tenants × collections`
392
- defines the work per tick. A separate `runMaintenanceTick` call
393
- fires per pair, and a failure on one pair logs to stderr without
394
- crashing the process or blocking the others.
395
-
396
- Maintenance emits one canonical info line per `(tenant,
397
- collection)` run on stdout.
398
- Filter your log stream on `"unit_of_work": "maintenance"` and
399
- read these fields:
400
-
401
- - `compact_written` — log entries folded into the new snapshot
402
- this tick (`0` when the live tail was below
403
- `minEntriesToCompact`).
404
- - `gc_swept` — keys deleted this tick (`0` when no candidates
405
- aged out).
406
- - The kernel also emits the recorder-bag fields alongside:
407
- `db.compact.entries_folded_p50` / `_p99` / `_count` / `_sum`,
408
- `db.manifest.lag_window_depth`, `db.orphan.candidate_count`,
409
- `db.gc.entries_swept_per_second`, `db.gc.swept_total`.
410
- Useful for dashboards; the four explicit fields above are
411
- the at-a-glance summary.
412
-
413
367
  - **Deploy** — runs anywhere `node server.js` runs. The
414
368
  `package.json`'s `start` script is
415
369
  `node --experimental-strip-types src/server/index.ts`. Arrange the
@@ -445,6 +399,28 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
445
399
  incrementally from the `/v1/since` log feed or from a write hook —
446
400
  never re-scan per request.
447
401
 
402
+ ## Maintenance
403
+
404
+ <!-- pattern-d:start -->
405
+ Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
406
+ timer, no lock, no app-config knob — identical on every host. Every write runs a
407
+ bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
408
+ whose default is safe on every tier. A size-ratio threshold means idle buckets pay
409
+ nothing. Concurrent folds are safe without coordination: the commit is a
410
+ compare-and-swap, so a fold that loses to a concurrent write is simply discarded and
411
+ its leftover swept by GC. On Cloudflare the fold is deferred past the response via
412
+ ctx.waitUntil; everywhere else it runs inline. **Reads are pure** — they never run
413
+ maintenance, so the published idle-reader cost bound holds.
414
+
415
+ A bucket maintains itself as long as it takes writes. A bucket served read-only does
416
+ not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
417
+ graduate once a collection is large. See docs/about/graduation.md for the per-tier
418
+ envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
419
+
420
+ Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
421
+ your own schedule. Not required for steady-state operation.
422
+ <!-- pattern-d:end -->
423
+
448
424
  ## When to graduate
449
425
 
450
426
  baerly is designed for the small-to-medium operating point. The cost
@@ -65,12 +65,15 @@ posture needs no auth env vars; if you adopt Pattern B / C from
65
65
  "Going to production" below, also set `SHARED_SECRET` (Pattern B)
66
66
  or `JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` (Pattern C). Optional:
67
67
  `R2_ACCOUNT_ID` (switches the storage factory from `s3Storage` to
68
- `r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT`,
69
- `MAINTENANCE_COLLECTIONS` (comma-separated collection slugs — when
70
- set, `baerlyNode` runs one compact+GC pass per `(tenant, collection)`
71
- pair on its hourly tick; leave unset to skip the in-process loop and
72
- schedule maintenance externally — a PaaS cron, k8s CronJob, systemd
73
- timer).
68
+ `r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT`.
69
+
70
+ Maintenance (compaction + GC) is automatic and in-band: it runs
71
+ inline on the rare write that crosses a maintenance trigger — no env
72
+ var, no tick, no `setInterval`, no operator scheduler. Two ops-plane
73
+ env vars tune it: `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` raises the
74
+ snapshot ceiling and `BAERLY_MAINTENANCE_DISABLE=1` is a kill switch.
75
+ For an explicit out-of-band sweep, call `runScheduledMaintenance`
76
+ from `@gusto/baerly-storage`.
74
77
 
75
78
  After `pnpm build`, `http://localhost:8080/` serves the built SPA
76
79
  out of `dist/client/` and `http://localhost:8080/v1/*` is the
@@ -29,7 +29,7 @@ Common anti-patterns that compile but are wrong:
29
29
  `db.collection(name).insert(row)` and `.where({ ... }).all()`.
30
30
  - `z.string().nullable()` in a schema — `DocumentValue` excludes
31
31
  `null`. Use `.optional()`; `null` in an update patch is the RFC
32
- 7396 deletion sentinel, not a storable value.
32
+ 7386 deletion sentinel, not a storable value.
33
33
  - Raw SQL strings, `WHERE` clauses, hand-built query AST — the only
34
34
  query surface is `db.collection(...).where({ field: value }).all()` or
35
35
  `.where(q => q.gte("count", 1))`. See **Predicates** below.
@@ -475,37 +475,6 @@ from the runtime env.
475
475
  only, so setting them via `wrangler secret put` would silently
476
476
  defeat the doctor check.
477
477
 
478
- - **Maintenance loop (Cloudflare)** — opt-in. Add
479
- `"triggers": { "crons": ["* * * * *"] }` to `wrangler.jsonc` and
480
- wire `scheduled` on the options the factory returns from `baerlyWorker((env) => ({ ... }))`. The
481
- handler is your code, so you choose what to call
482
- (`runScheduledMaintenance`, `compact`, `runGc`) and which
483
- `current.json` keys to target. Multi-tenant deployments iterate
484
- their own keys; single-tenant deployments call once with a fixed
485
- key. See the JSDoc on `WorkerScheduledHandler` in
486
- `@gusto/baerly-storage/cloudflare` and `runScheduledMaintenance` in
487
- `@gusto/baerly-storage/maintenance` for the wiring + free-vs-paid-tier
488
- subrequest-budget guidance.
489
-
490
- Maintenance emits one canonical info line per run on stdout
491
- (Workers Logs ingestion). Filter your log stream on
492
- `"unit_of_work": "maintenance"` and read these fields:
493
-
494
- - `compact_written` — log entries folded into the new snapshot
495
- this tick (`0` when the live tail was below
496
- `minEntriesToCompact`). Only set when the tick called
497
- `runScheduledMaintenance` or `compact` directly; isolated
498
- `runGc` ticks emit their own `unit_of_work: "gc"` line.
499
- - `gc_swept` — keys deleted this tick (`0` when no candidates
500
- aged out). Only set when the tick called
501
- `runScheduledMaintenance` or `runGc` directly.
502
- - The kernel also emits the recorder-bag fields alongside:
503
- `db.compact.entries_folded_p50` / `_p99` / `_count` / `_sum`,
504
- `db.manifest.lag_window_depth`, `db.orphan.candidate_count`,
505
- `db.gc.entries_swept_per_second`, `db.gc.swept_total`.
506
- Useful for dashboards; the four explicit fields above are
507
- the at-a-glance summary.
508
-
509
478
  - **Deploy** — `baerly deploy --target=cloudflare` runs
510
479
  `wrangler deploy --x-provision --x-auto-create` (Wrangler 4.10+)
511
480
  to auto-create the declared R2 buckets and ship the Worker. When
@@ -532,6 +501,28 @@ from the runtime env.
532
501
  the `/v1/since` log feed or from a write hook — never re-scan per
533
502
  request.
534
503
 
504
+ ## Maintenance
505
+
506
+ <!-- pattern-d:start -->
507
+ Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
508
+ timer, no lock, no app-config knob — identical on every host. Every write runs a
509
+ bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
510
+ whose default is safe on every tier. A size-ratio threshold means idle buckets pay
511
+ nothing. Concurrent folds are safe without coordination: the commit is a
512
+ compare-and-swap, so a fold that loses to a concurrent write is simply discarded and
513
+ its leftover swept by GC. On Cloudflare the fold is deferred past the response via
514
+ ctx.waitUntil; everywhere else it runs inline. **Reads are pure** — they never run
515
+ maintenance, so the published idle-reader cost bound holds.
516
+
517
+ A bucket maintains itself as long as it takes writes. A bucket served read-only does
518
+ not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
519
+ 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).
521
+
522
+ Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
523
+ your own schedule. Not required for steady-state operation.
524
+ <!-- pattern-d:end -->
525
+
535
526
  ## When to graduate
536
527
 
537
528
  baerly is designed for the small-to-medium operating point. The cost
@@ -620,17 +611,19 @@ the cache key changes when the filter does:
620
611
 
621
612
  ```tsx
622
613
  import { useState } from "react";
623
- import { useQuery } from "@gusto/baerly-storage/client/react";
624
614
  import { STATUSES, type Note } from "../../baerly.config.ts";
615
+ import { useQuery } from "./client.ts";
625
616
 
626
617
  type Filter = "all" | Note["status"];
627
618
 
628
619
  const [filter, setFilter] = useState<Filter>("all");
620
+ // `useQuery` comes from the bound factory in `client.ts`, so
621
+ // `c.collection("notes")` infers the `Note` row — no `<Note>`, no cast.
629
622
  const result = useQuery(
630
623
  (c) =>
631
624
  filter === "all"
632
- ? c.collection<Note>("notes").all()
633
- : c.collection<Note>("notes").where({ status: filter }).all(),
625
+ ? c.collection("notes").all()
626
+ : c.collection("notes").where({ status: filter }).all(),
634
627
  [filter],
635
628
  );
636
629
  ```
@@ -650,7 +643,7 @@ const filtered = useQuery(
650
643
  (c) =>
651
644
  filter === "all"
652
645
  ? useQuery.skip
653
- : c.collection<Note>("notes").where({ status: filter }).all(),
646
+ : c.collection("notes").where({ status: filter }).all(),
654
647
  [filter],
655
648
  );
656
649
  if (filtered.status === "skipped") return <FullList />;
@@ -660,7 +653,9 @@ For dependent reads, compose two `useQuery` calls — the second one
660
653
  returns `useQuery.skip` until the first resolves to `"ok"`:
661
654
 
662
655
  ```tsx
663
- const parent = useQuery((c) => c.collection<Note>("notes").get(id), [id]);
656
+ // `comments` must be declared in baerly.config.ts — the bound hooks
657
+ // only know your declared collections (an undeclared name is a type error).
658
+ const parent = useQuery((c) => c.collection("notes").get(id), [id]);
664
659
  const replies = useQuery(
665
660
  (c) =>
666
661
  parent.status === "ok"
@@ -698,7 +693,7 @@ export const NoteSchema = z.object({
698
693
 
699
694
  The Zod-inferred `Note` type reflects the shape (`tags?: string[]`)
700
695
  and call sites pick it up through `import type { Note }`.
701
- JSON-merge-patch (RFC 7396) semantics apply on `update()`:
696
+ JSON-merge-patch (RFC 7386) semantics apply on `update()`:
702
697
  omitting `tags` from an update preserves the existing value;
703
698
  passing `tags: null` deletes the field; passing `tags: []` sets
704
699
  it to an empty array. Note that `null` is the deletion sentinel,
@@ -1,5 +1,4 @@
1
- import { BaerlyProvider, useMutation } from "@gusto/baerly-storage/client/react";
2
- import { client } from "./client.ts";
1
+ import { BaerlyProvider, client, useMutation } from "./client.ts";
3
2
  import { NoteList } from "./NoteList.tsx";
4
3
 
5
4
  const NewNoteForm = () => {
@@ -1,6 +1,6 @@
1
1
  import { useState } from "react";
2
- import { useMutation, useQuery } from "@gusto/baerly-storage/client/react";
3
2
  import type { Note } from "../../baerly.config.ts";
3
+ import { useMutation, useQuery } from "./client.ts";
4
4
 
5
5
  const NoteRow = ({ note }: { note: Note }) => {
6
6
  const [isEditing, setIsEditing] = useState(false);
@@ -68,7 +68,7 @@ const NoteRow = ({ note }: { note: Note }) => {
68
68
  };
69
69
 
70
70
  export const NoteList = () => {
71
- const result = useQuery((c) => c.collection("notes").all() as Promise<Note[]>, []);
71
+ const result = useQuery((c) => c.collection("notes").all(), []);
72
72
  if (result.status === "error") {
73
73
  return <p className="error">Error: {result.error.message}</p>;
74
74
  }
@@ -1,4 +1,5 @@
1
1
  import { createBaerlyClient } from "@gusto/baerly-storage/client";
2
+ import { createBaerlyReact } from "@gusto/baerly-storage/client/react";
2
3
  import config from "../../baerly.config.ts";
3
4
 
4
5
  // Same-origin baseUrl works in both dev and production. With
@@ -11,3 +12,10 @@ export const client = createBaerlyClient({
11
12
  baseUrl: "",
12
13
  config,
13
14
  });
15
+
16
+ // The bound React surface. `createBaerlyReact<typeof config>()` pins
17
+ // every hook to your collections, so inside a `useQuery` /
18
+ // `useMutation` callback `c.collection("notes")` infers the `Note`
19
+ // row type — no casts. Import these hooks from this module (not from
20
+ // the package) so they stay bound.
21
+ export const { BaerlyProvider, useQuery, useMutation } = createBaerlyReact<typeof config>();
@@ -29,7 +29,7 @@ Common anti-patterns that compile but are wrong:
29
29
  `db.collection(name).insert(row)` and `.where({ ... }).all()`.
30
30
  - `z.string().nullable()` in a schema — `DocumentValue` excludes
31
31
  `null`. Use `.optional()`; `null` in an update patch is the RFC
32
- 7396 deletion sentinel, not a storable value.
32
+ 7386 deletion sentinel, not a storable value.
33
33
  - Raw SQL strings, `WHERE` clauses, hand-built query AST — the only
34
34
  query surface is `db.collection(...).where({ field: value }).all()` or
35
35
  `.where(q => q.gte("count", 1))`. See **Predicates** below.
@@ -121,7 +121,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
121
121
  | `tsconfig.app.json` | Client TS project (`src/web/`, DOM lib, `jsx: react-jsx`) |
122
122
  | `tsconfig.server.json` | Node server TS project (`src/server/`, Node lib) |
123
123
  | `baerly.config.ts` | App config — `app`, `tenant`, `target`, `collections` (schemas live here). Also exports the inferred `Note` row type used by the web client. |
124
- | `.env.example` | Source of truth for env vars the Node entry reads (`BUCKET`, `AWS_*`, `MAINTENANCE_COLLECTIONS`, etc.; `SHARED_SECRET` / `JWKS_URL` only needed if you adopt the "Going to production" auth recipes) |
124
+ | `.env.example` | Source of truth for env vars the Node entry reads (`BUCKET`, `AWS_*`, the optional `BAERLY_MAINTENANCE_*` ops-plane tuners, etc.; `SHARED_SECRET` / `JWKS_URL` only needed if you adopt the "Going to production" auth recipes) |
125
125
 
126
126
  > **`baerly.config.ts` is dual-included.** Both `tsconfig.app.json`
127
127
  > and `tsconfig.server.json` `include` this file, so it must only
@@ -395,51 +395,6 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
395
395
  `() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
396
396
  factory through the seam.
397
397
 
398
- - **Maintenance loop (Node)** — `src/server/index.ts` passes a
399
- `maintenance: { collections, tenants }` option to `baerlyNode`.
400
- Each tick (hourly by default; override via
401
- `maintenance.intervalMs`) runs one compact+GC pass per
402
- `(tenant, collection)` pair against the engine's default
403
- unbounded maintenance profile (folds the entire live tail; sweeps
404
- every aged-out candidate the GC marks).
405
-
406
- Opt-in via the `MAINTENANCE_COLLECTIONS` env var — a comma-
407
- separated list of collection slugs:
408
-
409
- ```sh
410
- MAINTENANCE_COLLECTIONS=notes
411
- ```
412
-
413
- When unset, the entry passes `maintenance: undefined` to
414
- `baerlyNode` and no in-process loop runs. Operators who prefer
415
- external scheduling can wire a separate cron trigger (PaaS cron,
416
- k8s CronJob, systemd timer) per collection that invokes
417
- `runMaintenanceTick` directly — that function stays exported
418
- from `@gusto/baerly-storage/node`.
419
-
420
- The template is single-tenant by default (`tenants: [TENANT]`).
421
- Multi-tenant deployments override the `tenants` array in
422
- `src/server/index.ts`; the cross-product `tenants × collections`
423
- defines the work per tick. A separate `runMaintenanceTick` call
424
- fires per pair, and a failure on one pair logs to stderr without
425
- crashing the process or blocking the others.
426
-
427
- Maintenance emits one canonical info line per `(tenant,
428
- collection)` run on stdout. Filter your log stream on
429
- `"unit_of_work": "maintenance"` and read these fields:
430
-
431
- - `compact_written` — log entries folded into the new snapshot
432
- this tick (`0` when the live tail was below
433
- `minEntriesToCompact`).
434
- - `gc_swept` — keys deleted this tick (`0` when no candidates
435
- aged out).
436
- - The kernel also emits the recorder-bag fields alongside:
437
- `db.compact.entries_folded_p50` / `_p99` / `_count` / `_sum`,
438
- `db.manifest.lag_window_depth`, `db.orphan.candidate_count`,
439
- `db.gc.entries_swept_per_second`, `db.gc.swept_total`.
440
- Useful for dashboards; the four explicit fields above are
441
- the at-a-glance summary.
442
-
443
398
  - **Deploy** — runs anywhere `node server.js` runs. The
444
399
  `package.json`'s `start` script is
445
400
  `node --experimental-strip-types src/server/index.ts`. Arrange the
@@ -479,6 +434,28 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
479
434
  incrementally from the `/v1/since` log feed or from a write hook —
480
435
  never re-scan per request.
481
436
 
437
+ ## Maintenance
438
+
439
+ <!-- pattern-d:start -->
440
+ Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
441
+ timer, no lock, no app-config knob — identical on every host. Every write runs a
442
+ bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
443
+ whose default is safe on every tier. A size-ratio threshold means idle buckets pay
444
+ nothing. Concurrent folds are safe without coordination: the commit is a
445
+ compare-and-swap, so a fold that loses to a concurrent write is simply discarded and
446
+ its leftover swept by GC. On Cloudflare the fold is deferred past the response via
447
+ ctx.waitUntil; everywhere else it runs inline. **Reads are pure** — they never run
448
+ maintenance, so the published idle-reader cost bound holds.
449
+
450
+ A bucket maintains itself as long as it takes writes. A bucket served read-only does
451
+ not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
452
+ 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).
454
+
455
+ Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
456
+ your own schedule. Not required for steady-state operation.
457
+ <!-- pattern-d:end -->
458
+
482
459
  ## When to graduate
483
460
 
484
461
  baerly is designed for the small-to-medium operating point. The cost
@@ -567,17 +544,19 @@ the cache key changes when the filter does:
567
544
 
568
545
  ```tsx
569
546
  import { useState } from "react";
570
- import { useQuery } from "@gusto/baerly-storage/client/react";
571
547
  import { STATUSES, type Note } from "../../baerly.config.ts";
548
+ import { useQuery } from "./client.ts";
572
549
 
573
550
  type Filter = "all" | Note["status"];
574
551
 
575
552
  const [filter, setFilter] = useState<Filter>("all");
553
+ // `useQuery` comes from the bound factory in `client.ts`, so
554
+ // `c.collection("notes")` infers the `Note` row — no `<Note>`, no cast.
576
555
  const result = useQuery(
577
556
  (c) =>
578
557
  filter === "all"
579
- ? c.collection<Note>("notes").all()
580
- : c.collection<Note>("notes").where({ status: filter }).all(),
558
+ ? c.collection("notes").all()
559
+ : c.collection("notes").where({ status: filter }).all(),
581
560
  [filter],
582
561
  );
583
562
  ```
@@ -597,7 +576,7 @@ const filtered = useQuery(
597
576
  (c) =>
598
577
  filter === "all"
599
578
  ? useQuery.skip
600
- : c.collection<Note>("notes").where({ status: filter }).all(),
579
+ : c.collection("notes").where({ status: filter }).all(),
601
580
  [filter],
602
581
  );
603
582
  if (filtered.status === "skipped") return <FullList />;
@@ -607,7 +586,9 @@ For dependent reads, compose two `useQuery` calls — the second one
607
586
  returns `useQuery.skip` until the first resolves to `"ok"`:
608
587
 
609
588
  ```tsx
610
- const parent = useQuery((c) => c.collection<Note>("notes").get(id), [id]);
589
+ // `comments` must be declared in baerly.config.ts — the bound hooks
590
+ // only know your declared collections (an undeclared name is a type error).
591
+ const parent = useQuery((c) => c.collection("notes").get(id), [id]);
611
592
  const replies = useQuery(
612
593
  (c) =>
613
594
  parent.status === "ok"
@@ -645,7 +626,7 @@ export const NoteSchema = z.object({
645
626
 
646
627
  The Zod-inferred `Note` type reflects the shape (`tags?: string[]`)
647
628
  and call sites pick it up through `import type { Note }`.
648
- JSON-merge-patch (RFC 7396) semantics apply on `update()`:
629
+ JSON-merge-patch (RFC 7386) semantics apply on `update()`:
649
630
  omitting `tags` from an update preserves the existing value;
650
631
  passing `tags: null` deletes the field; passing `tags: []` sets
651
632
  it to an empty array. Note that `null` is the deletion sentinel,
@@ -74,12 +74,15 @@ posture needs no auth env vars; if you adopt Pattern B / C from
74
74
  "Production auth" below, also set `SHARED_SECRET` (Pattern B) or
75
75
  `JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` (Pattern C). Optional:
76
76
  `R2_ACCOUNT_ID` (switches the storage factory from `s3Storage` to
77
- `r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT`,
78
- `MAINTENANCE_COLLECTIONS` (comma-separated collection slugs — when
79
- set, `baerlyNode` runs one compact+GC pass per `(tenant, collection)`
80
- pair on its hourly tick; leave unset to skip the in-process loop
81
- and schedule maintenance externally — a PaaS cron, k8s CronJob,
82
- systemd timer).
77
+ `r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT`.
78
+
79
+ Maintenance (compaction + GC) is automatic and in-band: it runs
80
+ inline on the rare write that crosses a maintenance trigger — no env
81
+ var, no tick, no `setInterval`, no operator scheduler. Two ops-plane
82
+ env vars tune it: `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` raises the
83
+ snapshot ceiling and `BAERLY_MAINTENANCE_DISABLE=1` is a kill switch.
84
+ For an explicit out-of-band sweep, call `runScheduledMaintenance`
85
+ from `@gusto/baerly-storage`.
83
86
 
84
87
  After `pnpm build`, `http://localhost:8080/` serves the built SPA
85
88
  out of `dist/client/` and `http://localhost:8080/v1/*` is the
@@ -43,6 +43,9 @@ const storage: Storage =
43
43
 
44
44
  const PORT = Number(process.env["PORT"] ?? 8080);
45
45
 
46
- await baerlyNode({ config, storage }).listen(PORT);
46
+ // `webRoot` serves the Vite-built SPA from `dist/client/` (the
47
+ // `vite.config.ts` `build.outDir`) in production; `/v1/*` is handled
48
+ // by the kernel, everything else falls back to the SPA shell.
49
+ await baerlyNode({ config, storage, webRoot: "dist/client" }).listen(PORT);
47
50
 
48
51
  console.log(`react-node listening on :${PORT}`);
@@ -1,5 +1,4 @@
1
- import { BaerlyProvider, useMutation } from "@gusto/baerly-storage/client/react";
2
- import { client } from "./client.ts";
1
+ import { BaerlyProvider, client, useMutation } from "./client.ts";
3
2
  import { NoteList } from "./NoteList.tsx";
4
3
 
5
4
  const NewNoteForm = () => {
@@ -1,6 +1,6 @@
1
1
  import { useState } from "react";
2
- import { useMutation, useQuery } from "@gusto/baerly-storage/client/react";
3
2
  import type { Note } from "../../baerly.config.ts";
3
+ import { useMutation, useQuery } from "./client.ts";
4
4
 
5
5
  const NoteRow = ({ note }: { note: Note }) => {
6
6
  const [isEditing, setIsEditing] = useState(false);
@@ -68,7 +68,7 @@ const NoteRow = ({ note }: { note: Note }) => {
68
68
  };
69
69
 
70
70
  export const NoteList = () => {
71
- const result = useQuery((c) => c.collection("notes").all() as Promise<Note[]>, []);
71
+ const result = useQuery((c) => c.collection("notes").all(), []);
72
72
  if (result.status === "error") {
73
73
  return <p className="error">Error: {result.error.message}</p>;
74
74
  }
@@ -1,4 +1,5 @@
1
1
  import { createBaerlyClient } from "@gusto/baerly-storage/client";
2
+ import { createBaerlyReact } from "@gusto/baerly-storage/client/react";
2
3
  import config from "../../baerly.config.ts";
3
4
 
4
5
  // Same-origin baseUrl works in both dev and production. With
@@ -11,3 +12,10 @@ export const client = createBaerlyClient({
11
12
  baseUrl: "",
12
13
  config,
13
14
  });
15
+
16
+ // The bound React surface. `createBaerlyReact<typeof config>()` pins
17
+ // every hook to your collections, so inside a `useQuery` /
18
+ // `useMutation` callback `c.collection("notes")` infers the `Note`
19
+ // row type — no casts. Import these hooks from this module (not from
20
+ // the package) so they stay bound.
21
+ export const { BaerlyProvider, useQuery, useMutation } = createBaerlyReact<typeof config>();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gusto/create-baerly-storage",
3
- "version": "0.1.1",
3
+ "version": "0.2.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": {
@@ -14,7 +14,7 @@
14
14
  "directory": "packages/create-baerly-storage"
15
15
  },
16
16
  "bin": {
17
- "create-baerly-storage": "./dist/index.js"
17
+ "create-baerly-storage": "dist/index.js"
18
18
  },
19
19
  "files": [
20
20
  "dist"