@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.
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/templates/addons/docker/Dockerfile +7 -1
- package/dist/templates/minimal-cloudflare/AGENTS.md +23 -32
- package/dist/templates/minimal-node/AGENTS.md +23 -47
- package/dist/templates/minimal-node/README.md +9 -6
- package/dist/templates/react-cloudflare/AGENTS.md +33 -38
- package/dist/templates/react-cloudflare/src/web/App.tsx +1 -2
- package/dist/templates/react-cloudflare/src/web/NoteList.tsx +2 -2
- package/dist/templates/react-cloudflare/src/web/client.ts +8 -0
- package/dist/templates/react-node/AGENTS.md +34 -53
- package/dist/templates/react-node/README.md +9 -6
- package/dist/templates/react-node/src/server/index.ts +4 -1
- package/dist/templates/react-node/src/web/App.tsx +1 -2
- package/dist/templates/react-node/src/web/NoteList.tsx +2 -2
- package/dist/templates/react-node/src/web/client.ts +8 -0
- package/package.json +2 -2
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
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
|
|
633
|
-
: c.collection
|
|
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
|
|
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
|
-
|
|
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
|
|
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,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()
|
|
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
|
-
|
|
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_*`, `
|
|
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
|
|
580
|
-
: c.collection
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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
|
-
|
|
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,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()
|
|
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.
|
|
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": "
|
|
17
|
+
"create-baerly-storage": "dist/index.js"
|
|
18
18
|
},
|
|
19
19
|
"files": [
|
|
20
20
|
"dist"
|