@gusto/baerly-storage 0.3.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.
- package/README.md +157 -92
- package/dist/API.md +64 -32
- package/dist/CHANGELOG.md +295 -5
- package/dist/RECIPES.md +125 -0
- package/dist/THIRD-PARTY-LICENSES.txt +22 -96
- package/dist/{app-config-BIzyAKzy.d.ts → app-config-DyiFK3_k.d.ts} +43 -11
- package/dist/app-config.d.ts +1 -1
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +13 -13
- package/dist/auth.js.map +1 -1
- package/dist/aws4fetch.esm-p7eEzLCs.js +1702 -0
- package/dist/aws4fetch.esm-p7eEzLCs.js.map +1 -0
- package/dist/baerly.js +35 -15
- package/dist/baerly.js.map +1 -1
- package/dist/baerly.spec.json +342 -0
- package/dist/{client-BJXF3XJA.d.ts → client-Fe8CwB73.d.ts} +3 -3
- package/dist/client-react.d.ts +3 -3
- package/dist/client-react.js +4 -4
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +4 -4
- package/dist/client.js +3 -3
- package/dist/{cloudflare-Cn2ibODt.js → cloudflare-DzKBrUlg.js} +2 -2
- package/dist/{cloudflare-Cn2ibODt.js.map → cloudflare-DzKBrUlg.js.map} +1 -1
- package/dist/cloudflare.d.ts +49 -6
- package/dist/cloudflare.js +55 -21
- package/dist/cloudflare.js.map +1 -1
- package/dist/config-1tv0-Yzm.js +2693 -0
- package/dist/config-1tv0-Yzm.js.map +1 -0
- package/dist/constants-CfeMWQWk.js +222 -0
- package/dist/constants-CfeMWQWk.js.map +1 -0
- package/dist/{cost-BZ_MDBmn.js → cost-DSMIVqzL.js} +42 -43
- package/dist/cost-DSMIVqzL.js.map +1 -0
- package/dist/{current-json-DsN7FNY1.js → current-json-C6nhPOm1.js} +6 -204
- package/dist/current-json-C6nhPOm1.js.map +1 -0
- package/dist/{db-CCT6tDfY.d.ts → db-DsPkOVEH.d.ts} +3 -3
- package/dist/{deploy-BKKyGlSJ.js → deploy-DonTr-CV.js} +4 -4
- package/dist/{deploy-BKKyGlSJ.js.map → deploy-DonTr-CV.js.map} +1 -1
- package/dist/dev-vite.d.ts +9 -5
- package/dist/dev-vite.js +5 -4
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +1 -1
- package/dist/dev.js +1 -1
- package/dist/{doctor-BVU4GNXN.js → doctor-DSIyCDg_.js} +5 -8
- package/dist/{doctor-BVU4GNXN.js.map → doctor-DSIyCDg_.js.map} +1 -1
- package/dist/{dump-DPEAKub6.js → dump-Bh5k26VQ.js} +9 -32
- package/dist/dump-Bh5k26VQ.js.map +1 -0
- package/dist/{errors-DOdL95kK.js → errors-Dfa3p78c.js} +25 -5
- package/dist/errors-Dfa3p78c.js.map +1 -0
- package/dist/{export-BcuCLFFe.js → export-DtF5tDIM.js} +9 -32
- package/dist/{export-BcuCLFFe.js.map → export-DtF5tDIM.js.map} +1 -1
- package/dist/{fsck-RXgLOaJG.js → fsck-D_djMO5D.js} +10 -33
- package/dist/fsck-D_djMO5D.js.map +1 -0
- package/dist/{http-Bd4byR4n.js → http-DxM9MflO.js} +123 -35
- package/dist/http-DxM9MflO.js.map +1 -0
- package/dist/http.d.ts +42 -26
- package/dist/http.js +3 -2
- package/dist/{index-DnBGSeuU.d.ts → index-0rZcMBwy.d.ts} +2 -2
- package/dist/{index-Cmsxx-ZN.d.ts → index-B6oexfOB.d.ts} +7 -7
- package/dist/{index-BDceQQi-.d.ts → index-BNRh23K9.d.ts} +4 -4
- package/dist/{index-DW7GT6M2.d.ts → index-BYk9oCNf.d.ts} +193 -163
- package/dist/index.d.ts +6 -6
- package/dist/index.js +4 -4
- package/dist/{indexes-Cx7uMXm0.d.ts → indexes-Dn9hbGQG.d.ts} +2 -2
- package/dist/{inspect-DhI49PSi.js → inspect-6WZ-pC7-.js} +10 -33
- package/dist/inspect-6WZ-pC7-.js.map +1 -0
- package/dist/key-Di6yyxFu.js +35 -0
- package/dist/key-Di6yyxFu.js.map +1 -0
- package/dist/{log-tail-DXeDkWEp.js → log-tail-D98U1JBo.js} +31 -7
- package/dist/log-tail-D98U1JBo.js.map +1 -0
- package/dist/{maintenance-CWBQpZ2y.js → maintenance-B4Dki6Ig.js} +77 -22
- package/dist/maintenance-B4Dki6Ig.js.map +1 -0
- package/dist/{maintenance-BkhUr72A.d.ts → maintenance-B_e0T99L.d.ts} +28 -5
- package/dist/{maintenance-C_KSkVjd.js → maintenance-C7coQp4c.js} +17 -16
- package/dist/maintenance-C7coQp4c.js.map +1 -0
- package/dist/maintenance.d.ts +3 -3
- package/dist/maintenance.js +3 -3
- package/dist/node.d.ts +168 -65
- package/dist/node.js +3 -2
- package/dist/{normalize-XWY25_sG.js → normalize-rjnZLwS4.js} +2 -2
- package/dist/normalize-rjnZLwS4.js.map +1 -0
- package/dist/{observability-BYd-RzEx.js → observability-wzs3-BL_.js} +233 -71
- package/dist/observability-wzs3-BL_.js.map +1 -0
- package/dist/observability.d.ts +2 -2
- package/dist/observability.js +1 -1
- package/dist/{plan-DIu_B6fy.js → plan-a7PJHBCy.js} +2 -2
- package/dist/{plan-DIu_B6fy.js.map → plan-a7PJHBCy.js.map} +1 -1
- package/dist/{query-sQNO5vU_.js → query-rAtXNQQB.js} +96 -207
- package/dist/query-rAtXNQQB.js.map +1 -0
- package/dist/{rebuild-index-DP4CqSSs.js → rebuild-index-BVzQSZlm.js} +9 -32
- package/dist/rebuild-index-BVzQSZlm.js.map +1 -0
- package/dist/{request-BEF_OvMh.js → request-u0M51mhJ.js} +3 -3
- package/dist/{request-BEF_OvMh.js.map → request-u0M51mhJ.js.map} +1 -1
- package/dist/{restore-DpQYef6r.js → restore-R-4rbciV.js} +73 -100
- package/dist/restore-R-4rbciV.js.map +1 -0
- package/dist/runtime-spec-qL3_lTTU.js +391 -0
- package/dist/runtime-spec-qL3_lTTU.js.map +1 -0
- package/dist/s3-http-B-z8th6O.d.ts +60 -0
- package/dist/s3.d.ts +47 -0
- package/dist/s3.js +45 -0
- package/dist/s3.js.map +1 -0
- package/dist/{shared-secret-BJdSwpgw.js → shared-secret-DgEicd3x.js} +13 -5
- package/dist/shared-secret-DgEicd3x.js.map +1 -0
- package/dist/src-BG20LZs7.js +2271 -0
- package/dist/src-BG20LZs7.js.map +1 -0
- package/dist/{src-Db4-qVtM.js → src-CYHFDrKz.js} +51 -8
- package/dist/src-CYHFDrKz.js.map +1 -0
- package/dist/{src-CWpkSbvJ.js → src-DYZ4H1aF.js} +6 -5
- package/dist/src-DYZ4H1aF.js.map +1 -0
- package/dist/{subcommand-CP9NY2J4.js → subcommand-DoDA-K7d.js} +44 -6
- package/dist/subcommand-DoDA-K7d.js.map +1 -0
- package/dist/time-DUqvFMHq.js +119 -0
- package/dist/time-DUqvFMHq.js.map +1 -0
- package/dist/{usage-CTfDq9HR.js → usage-DBV1eQHC.js} +7 -22
- package/dist/usage-DBV1eQHC.js.map +1 -0
- package/dist/wire-izfGZDvr.js.map +1 -1
- package/package.json +52 -28
- package/dist/config-CGyBopy3.js +0 -5326
- package/dist/config-CGyBopy3.js.map +0 -1
- package/dist/cost-BZ_MDBmn.js.map +0 -1
- package/dist/current-json-DsN7FNY1.js.map +0 -1
- package/dist/dump-DPEAKub6.js.map +0 -1
- package/dist/errors-DOdL95kK.js.map +0 -1
- package/dist/fsck-RXgLOaJG.js.map +0 -1
- package/dist/http-Bd4byR4n.js.map +0 -1
- package/dist/inspect-DhI49PSi.js.map +0 -1
- package/dist/log-tail-DXeDkWEp.js.map +0 -1
- package/dist/maintenance-CWBQpZ2y.js.map +0 -1
- package/dist/maintenance-C_KSkVjd.js.map +0 -1
- package/dist/normalize-XWY25_sG.js.map +0 -1
- package/dist/observability-BYd-RzEx.js.map +0 -1
- package/dist/query-sQNO5vU_.js.map +0 -1
- package/dist/rebuild-index-DP4CqSSs.js.map +0 -1
- package/dist/restore-DpQYef6r.js.map +0 -1
- package/dist/shared-secret-BJdSwpgw.js.map +0 -1
- package/dist/src-CWpkSbvJ.js.map +0 -1
- package/dist/src-D24wDpzR.js +0 -6247
- package/dist/src-D24wDpzR.js.map +0 -1
- package/dist/src-Db4-qVtM.js.map +0 -1
- package/dist/subcommand-CP9NY2J4.js.map +0 -1
- package/dist/usage-CTfDq9HR.js.map +0 -1
- /package/dist/{chunk-EAsCxrDo.js → rolldown-runtime-EAsCxrDo.js} +0 -0
package/README.md
CHANGED
|
@@ -1,60 +1,74 @@
|
|
|
1
1
|
# baerly-storage
|
|
2
2
|
|
|
3
|
-
**
|
|
4
|
-
|
|
5
|
-
> _Open source (Apache-2.0). Published as
|
|
6
|
-
> [`@gusto/baerly-storage`](https://www.npmjs.com/package/@gusto/baerly-storage)
|
|
7
|
-
> on npm._
|
|
8
|
-
|
|
9
|
-
`baerly-storage` is a library that turns AWS S3, Cloudflare R2, or a
|
|
10
|
-
conformant S3-compatible bucket into a document database. **There is
|
|
11
|
-
no runtime. None.** No Baerly daemon, no leader, no scheduler, no
|
|
12
|
-
catalog, no database service bill, no on-call. Coordination rides the
|
|
13
|
-
request path — Cloudflare can finish bounded maintenance with `ctx.waitUntil`,
|
|
14
|
-
Node runs it inline — and the only persistent component is your bucket.
|
|
15
|
-
|
|
16
|
-
The server bundles is ~100 KB gzipped, and the browser client is ~5 KB gzipped.
|
|
17
|
-
The whole public API fits in a single ~12k-token `dist/API.md` — small enough
|
|
18
|
-
that an LLM can hold it in context.
|
|
19
|
-
|
|
20
|
-
[S3 does the hard parts](https://aws.amazon.com/blogs/aws/amazon-s3-update-strong-read-after-write-consistency/),
|
|
21
|
-
`baerly-storage` is the coordination that fixes the API. Built like git:
|
|
22
|
-
content-addressed documents, immutable numbered log entries, and one
|
|
23
|
-
conditional log create as the commit, per collection. Document model,
|
|
24
|
-
live queries, snapshot isolation — the whole surface in a `.d.ts`
|
|
25
|
-
designed for zero-shot use.
|
|
26
|
-
|
|
27
|
-
Apps sized for this primitive — small, server-only writes, ~10 GB
|
|
28
|
-
ceiling, mechanical exit to Postgres when they cross it — get a tool
|
|
29
|
-
that matches their shape instead of a stack that doesn't.
|
|
3
|
+
**A database with no server. No daemon. No database runtime. Just your app and a bucket.**
|
|
30
4
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
5
|
+
A document database that lives _in_ an S3/R2 bucket you already own. No new vendor to clear, nothing resident to keep running, and an API small enough for an open-weights LLM to zero-shot.
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
before: client → app handler → database server (a server)
|
|
9
|
+
after: client → app handler → S3/R2 bucket (just storage)
|
|
35
10
|
```
|
|
36
11
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
12
|
+
The trick is to cram the entire database execution layer inside an HTTP
|
|
13
|
+
request. There is no server, daemon, or coordinator: each read or
|
|
14
|
+
write runs as library code inside your request handler, the bucket
|
|
15
|
+
holds the data, and the protocol supplies the commit rules.
|
|
16
|
+
|
|
17
|
+
The load-bearing operation is narrow — one conditional create of the next
|
|
18
|
+
log object commits a write. When the request ends, baerly-storage is gone. Poof!
|
|
19
|
+
|
|
20
|
+
- **An API small enough to hold in your context.** No DDL, no raw SQL —
|
|
21
|
+
8 verbs and a ~12k-token surface you can hand to an LLM or a
|
|
22
|
+
non-engineer and walk away.
|
|
23
|
+
- **Idle rounds to zero.** No database process to keep warm, and no
|
|
24
|
+
per-app database floor across a fleet of small internal tools.
|
|
25
|
+
- **No data hostage.** `baerly export --target=postgres` gives you a
|
|
26
|
+
per-collection SQL snapshot. Crossing the envelope is the graduation
|
|
27
|
+
signal; the data exit is mechanical.
|
|
28
|
+
- **No new vendor.** Your S3/R2 bucket cleared security review years
|
|
29
|
+
ago; every hosted alternative means a fresh vendor review and an IT
|
|
30
|
+
ticket for a new managed-DB SKU.
|
|
31
|
+
- **Nothing to go down.** No resident service in your critical path, one
|
|
32
|
+
fewer failure domain. Servers that don't exist can't go down.
|
|
33
|
+
- **Built like git.** Content-addressed documents, immutable numbered log
|
|
34
|
+
entries, and one conditional log create as the commit, per collection.
|
|
35
|
+
|
|
36
|
+
<!-- Hero demo: render `docs/assets/demo.gif` from `docs/assets/demo.tape`
|
|
37
|
+
(`vhs docs/assets/demo.tape`) against a real bucket, then uncomment:
|
|
38
|
+

|
|
39
|
+
-->
|
|
40
40
|
|
|
41
41
|
## Quick start
|
|
42
42
|
|
|
43
43
|
```sh
|
|
44
|
-
pnpm create @gusto/baerly-storage@latest
|
|
45
|
-
cd my-app && pnpm install && pnpm dev
|
|
44
|
+
pnpm create @gusto/baerly-storage@latest
|
|
46
45
|
```
|
|
47
46
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
47
|
+
The wizard asks for a project name, target, and starter, then prints the
|
|
48
|
+
dev command. First run needs no bucket credentials: local dev uses local
|
|
49
|
+
storage and serves the UI plus `/v1/*` from one origin.
|
|
51
50
|
|
|
52
|
-
For
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
51
|
+
For a runnable multi-tab demo see
|
|
52
|
+
[`examples/react-node/`](./examples/react-node); for the full set of
|
|
53
|
+
production-shaped scaffolds see [`examples/`](./examples).
|
|
54
|
+
|
|
55
|
+
## In code
|
|
56
|
+
|
|
57
|
+
The public surface is a small document API. The scaffolds wire `db` on
|
|
58
|
+
the server and `useQuery` in React; the calls look like this:
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
// server — writes land in your object-storage bucket
|
|
62
|
+
await db.collection("tickets").insert({ title: "Onboard Alex", status: "open" });
|
|
63
|
+
|
|
64
|
+
// client — reactive over your trusted handler, across every open tab
|
|
65
|
+
const open = useQuery((c) => c.collection("tickets").where({ status: "open" }).all(), []);
|
|
66
|
+
// open.status → "loading" | "refreshing" | "ok" | "skipped" | "error"
|
|
67
|
+
// open.data is present for "ok" / "refreshing"
|
|
68
|
+
```
|
|
56
69
|
|
|
57
|
-
|
|
70
|
+
Application auth and tenant choice stay explicit in the handler. What
|
|
71
|
+
disappears is the database service and its surrounding machinery:
|
|
58
72
|
|
|
59
73
|
```diff
|
|
60
74
|
- docker-compose.yml
|
|
@@ -69,25 +83,15 @@ Railway, Render, Fly, Docker, bare VMs, on-prem boxes.
|
|
|
69
83
|
+ // baerly.config.ts
|
|
70
84
|
+ export default defineConfig({
|
|
71
85
|
+ app: "tickets",
|
|
86
|
+
+ tenant: "main",
|
|
72
87
|
+ collections: { tickets: {} },
|
|
73
88
|
+ target: "cloudflare",
|
|
89
|
+
+ auth: "none", // dev; production supplies a verifier
|
|
74
90
|
+ });
|
|
75
91
|
```
|
|
76
92
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
ordinary schema shape changes.
|
|
80
|
-
|
|
81
|
-
## In code
|
|
82
|
-
|
|
83
|
-
```ts
|
|
84
|
-
// server — writes land in your R2 bucket
|
|
85
|
-
await db.collection("tickets").insert({ title: "Onboard Alex", status: "open" });
|
|
86
|
-
|
|
87
|
-
// client — reactive across every open tab
|
|
88
|
-
const open = useQuery((c) => c.collection("tickets").where({ status: "open" }).all(), []);
|
|
89
|
-
// open.status → "loading" | "ok" | "error"; open.data → your rows
|
|
90
|
-
```
|
|
93
|
+
Ordinary schema shape changes are TypeScript or config edits — no DDL, no
|
|
94
|
+
SQL strings, no generated migration ceremony.
|
|
91
95
|
|
|
92
96
|
## Cheat sheet
|
|
93
97
|
|
|
@@ -108,48 +112,109 @@ db.collection("tickets").where({ status: "closed" }).delete();
|
|
|
108
112
|
| Surface | Vocabulary |
|
|
109
113
|
| ------------- | ------------------------------------------------------------------------------------- |
|
|
110
114
|
| **Verbs** | `first` `all` `count` `get` · `insert` `update` `replace` `delete` |
|
|
111
|
-
| **Modifiers** | `where` `order` `limit`
|
|
112
|
-
| **Operators** | `eq` `gt` `gte` `lt` `lte` `in`
|
|
115
|
+
| **Modifiers** | `where` `order` `limit` |
|
|
116
|
+
| **Operators** | `eq` `gt` `gte` `lt` `lte` `in` |
|
|
113
117
|
| **Errors** | one `BaerlyError`, discriminate by `.code` (`Conflict`, `NotFound`, `SchemaError`, …) |
|
|
114
118
|
|
|
115
|
-
Full reference: [`docs/guide/cheatsheet.md`](./docs/guide/cheatsheet.md),
|
|
116
|
-
`cat node_modules/@gusto/baerly-storage/dist/API.md` in an installed
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
[
|
|
140
|
-
|
|
119
|
+
Full reference: [`docs/guide/cheatsheet.md`](./docs/guide/cheatsheet.md),
|
|
120
|
+
or `cat node_modules/@gusto/baerly-storage/dist/API.md` in an installed
|
|
121
|
+
app.
|
|
122
|
+
|
|
123
|
+
## How it works
|
|
124
|
+
|
|
125
|
+
**The hard part of a database-in-a-bucket is the commit.** A bucket can
|
|
126
|
+
store objects; it cannot run a transaction coordinator. So one writer must
|
|
127
|
+
win each race, and every reader must be able to tell what won. [S3's strong consistency][s3-strong] makes object
|
|
128
|
+
storage usable as shared state; conditional writes supply the
|
|
129
|
+
one-writer-wins operation.
|
|
130
|
+
|
|
131
|
+
Concretely, a write drops new immutable objects in the bucket and then
|
|
132
|
+
creates the next numbered log entry for that collection with
|
|
133
|
+
create-if-absent (`If-None-Match: "*"`). Two writers racing the same slot
|
|
134
|
+
cannot both win; the loser reads the winner and retries at the next slot.
|
|
135
|
+
That create _is_ the commit. There is no resident coordinator: each
|
|
136
|
+
request reads bucket state, tries that create, and leaves no required
|
|
137
|
+
process behind. A read follows `current.json` to the snapshot and folds
|
|
138
|
+
the committed log tail into rows.
|
|
139
|
+
|
|
140
|
+
baerly-storage shares the immutable-artifact foundation of table formats
|
|
141
|
+
like Apache Iceberg and Delta Lake, but commits with a narrower step: no
|
|
142
|
+
metadata-pointer swap and no separate coordinator — just that one log
|
|
143
|
+
create. See [prior art and lineage](docs/spec/prior-art.md) for how it
|
|
144
|
+
relates to Iceberg, Delta Lake, Litestream, and Turbopuffer.
|
|
145
|
+
|
|
146
|
+
Each collection has its own ordered log, so **writes are per-collection
|
|
147
|
+
linearizable** — the `If-None-Match` log create linearizes every commit.
|
|
148
|
+
Cross-collection writes are unordered and non-atomic; that boundary is
|
|
149
|
+
part of the contract (see [When (not) to use it](#when-not-to-use-it)).
|
|
150
|
+
|
|
151
|
+
The durable contract is the bucket layout plus the conditional-write
|
|
152
|
+
rules. Another language could speak it by writing the same layout and
|
|
153
|
+
honoring the same rules. See
|
|
154
|
+
[`storage-compatibility.md`](./docs/spec/storage-compatibility.md).
|
|
155
|
+
|
|
156
|
+
[s3-strong]: https://aws.amazon.com/blogs/aws/amazon-s3-update-strong-read-after-write-consistency/
|
|
157
|
+
|
|
158
|
+
### Security model
|
|
159
|
+
|
|
160
|
+
Bucket credentials never leave the server. Browsers talk only to your
|
|
161
|
+
trusted handler, which authenticates the caller, chooses the tenant
|
|
162
|
+
prefix, and applies the protocol against the bucket. Production recipes
|
|
163
|
+
support Cloudflare Access and JWKS bearer verification; shared-secret
|
|
164
|
+
auth is for service-to-service calls and dev. See
|
|
165
|
+
[`client-auth.md`](./docs/guide/client-auth.md).
|
|
166
|
+
|
|
167
|
+
## When (not) to use it
|
|
168
|
+
|
|
169
|
+
Before you count rows or price reads, ask one question:
|
|
170
|
+
|
|
171
|
+
> Can the app's most important work be done from one collection?
|
|
172
|
+
|
|
173
|
+
If yes, baerly-storage may fit; then check query shape, atomicity, size,
|
|
174
|
+
and cost. A todo list, a single board's kanban, an event's RSVPs, one
|
|
175
|
+
channel's chat — each maps to one collection. The shape is narrow on
|
|
176
|
+
purpose: production-shaped for small workloads with a specific access
|
|
177
|
+
pattern, not a general-purpose database. If the core screen is a view
|
|
178
|
+
_across_ many collections, users, or tenants ("my pull requests," "all
|
|
179
|
+
code search," a cross-org dashboard), baerly-storage
|
|
180
|
+
should not be the only query engine for it.
|
|
181
|
+
|
|
182
|
+
It is **deliberately not** a few things:
|
|
183
|
+
|
|
184
|
+
- **No SQL, no joins.** Equality + dotted-path predicates, operators
|
|
185
|
+
added one at a time. The small surface is part of the contract.
|
|
186
|
+
- **Not a D1 / Postgres replacement.** Those are graduation targets, not
|
|
187
|
+
competitors — baerly-storage keeps the experiment cheap until you know
|
|
188
|
+
whether it's worth graduating.
|
|
189
|
+
- **Browser-direct multi-writer is out.** Trusted server-side app code is
|
|
190
|
+
the design center.
|
|
191
|
+
- **Realtime is long-poll first.** Polling is always correct; a WebSocket
|
|
192
|
+
tier would be a future opt-in.
|
|
193
|
+
|
|
194
|
+
None of these are apologies — baerly-storage names its envelope so
|
|
195
|
+
graduation is a feature, not a surprise: `baerly export
|
|
196
|
+
--target=postgres` makes the exit mechanical.
|
|
197
|
+
The shape test lives in
|
|
198
|
+
[workload-fit.md](./docs/about/workload-fit.md); the numeric envelope in
|
|
199
|
+
[graduation.md](./docs/about/graduation.md).
|
|
141
200
|
|
|
142
201
|
## Go deeper
|
|
143
202
|
|
|
203
|
+
- ✨ **Why baerly-storage** —
|
|
204
|
+
[`docs/about/why-baerly.md`](./docs/about/why-baerly.md)
|
|
144
205
|
- 🧭 **How it works** —
|
|
145
|
-
[`docs/about/how-it-works.md`](./docs/about/how-it-works.md) (
|
|
146
|
-
|
|
206
|
+
[`docs/about/how-it-works.md`](./docs/about/how-it-works.md) (bucket +
|
|
207
|
+
conditional log create)
|
|
147
208
|
- 🧱 **Product thesis** — [`docs/about/thesis.md`](./docs/about/thesis.md)
|
|
148
|
-
- 🏗️ **Architecture** —
|
|
209
|
+
- 🏗️ **Architecture** —
|
|
210
|
+
[`docs/architecture.md`](./docs/architecture.md)
|
|
149
211
|
- 🔧 **Embed by hand** —
|
|
150
|
-
[`packages/server/API.md`](./packages/server/API.md) (
|
|
151
|
-
|
|
152
|
-
|
|
212
|
+
[`packages/server/API.md`](./packages/server/API.md) (embed-by-hand +
|
|
213
|
+
custom-routes recipes; ships as `dist/API.md` in the package)
|
|
214
|
+
- 📊 **Alternatives** —
|
|
215
|
+
[`docs/about/alternatives.md`](./docs/about/alternatives.md) (how
|
|
216
|
+
baerly-storage compares to Firebase, Supabase, Convex, and Cloudflare
|
|
217
|
+
D1)
|
|
153
218
|
|
|
154
219
|
## Where things live
|
|
155
220
|
|
package/dist/API.md
CHANGED
|
@@ -34,6 +34,8 @@ import {
|
|
|
34
34
|
MemoryStorage, // in-memory `Storage`; canonical for tests
|
|
35
35
|
type Collection,
|
|
36
36
|
type Query,
|
|
37
|
+
type Predicate, // equality-object `.where(...)` form
|
|
38
|
+
type PredicateArg, // `.where(...)` arg: object or builder callback
|
|
37
39
|
type DocumentData,
|
|
38
40
|
type RowOf,
|
|
39
41
|
type CollectionNames, // row-shape inference from a bound config
|
|
@@ -59,6 +61,8 @@ import {
|
|
|
59
61
|
type ClientQuery,
|
|
60
62
|
type TerminalOptions,
|
|
61
63
|
type Fetcher,
|
|
64
|
+
type Predicate,
|
|
65
|
+
type PredicateArg,
|
|
62
66
|
} from "@gusto/baerly-storage/client";
|
|
63
67
|
|
|
64
68
|
// Auth verifiers
|
|
@@ -81,6 +85,8 @@ import { LocalFsStorage } from "@gusto/baerly-storage/dev";
|
|
|
81
85
|
|
|
82
86
|
## `Db.create({ storage, app, tenant, config? })`
|
|
83
87
|
|
|
88
|
+
*When NOT to use: in a browser/SPA — use `createBaerlyClient` (HTTP) instead; `Db` is the in-process server surface.*
|
|
89
|
+
|
|
84
90
|
One `Db` per `(app, tenant)` request. The constructor is private —
|
|
85
91
|
always go through `Db.create`. Collections are auto-provisioned on first
|
|
86
92
|
write (no `ensureCollection` step).
|
|
@@ -141,6 +147,8 @@ overloads as the inferred return; `Db` (no parameter) widens to
|
|
|
141
147
|
|
|
142
148
|
## `db.collection(name)` → `Collection<T>`
|
|
143
149
|
|
|
150
|
+
*When NOT to use: from the browser — call collection verbs over HTTP via `createBaerlyClient`.*
|
|
151
|
+
|
|
144
152
|
`Collection<T>` carries the common-case verbs directly (collection-level
|
|
145
153
|
reads plus by-primary-key mutations). Modifiers (`where`, `order`,
|
|
146
154
|
`limit`) return a `Query<T>` for bulk-by-predicate work. Terminals fire
|
|
@@ -182,7 +190,8 @@ interface Query<T> extends /* Collection<T>'s modifiers */ {
|
|
|
182
190
|
`replace` is by-id only — `Collection<T>.replace(id, doc)` throws
|
|
183
191
|
`NotFound` on missing id. There is no predicate-form `.replace(doc)`
|
|
184
192
|
on `Query<T>`: a strict-cardinality-1 verb is redundant ceremony to
|
|
185
|
-
the by-id form (
|
|
193
|
+
the by-id form (the public surface is additive-only locked, so a second
|
|
194
|
+
type-valid path to one capability is redundancy).
|
|
186
195
|
|
|
187
196
|
### Predicates
|
|
188
197
|
|
|
@@ -330,7 +339,7 @@ try {
|
|
|
330
339
|
await db.collection("tickets").insert({ title: "hi" });
|
|
331
340
|
} catch (err) {
|
|
332
341
|
if (err instanceof BaerlyError && err.code === "Conflict") {
|
|
333
|
-
// CAS
|
|
342
|
+
// Check err.retriable: CAS conflicts can retry; duplicate _id cannot.
|
|
334
343
|
}
|
|
335
344
|
}
|
|
336
345
|
```
|
|
@@ -377,10 +386,16 @@ app.post("/notes", async (c) => {
|
|
|
377
386
|
});
|
|
378
387
|
```
|
|
379
388
|
|
|
380
|
-
`mapError` accepts any thrown value
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
389
|
+
`mapError` accepts any thrown value. Caller-facing errors such as
|
|
390
|
+
`SchemaError`, `NotFound`, `PayloadTooLarge`, predicate `InvalidConfig`,
|
|
391
|
+
and non-retriable caller `Conflict`s keep their actionable message.
|
|
392
|
+
Storage/server diagnostics such as `Internal`, `NetworkError`,
|
|
393
|
+
`InvalidResponse`, storage `AccessDenied`, storage `InvalidConfig`, and
|
|
394
|
+
retriable CAS/storage `Conflict`s keep their code/status/retriable shape
|
|
395
|
+
but use a generic wire message; the full thrown error is logged via the
|
|
396
|
+
observability channel. Non-`BaerlyError` throws fall through to
|
|
397
|
+
`500 Internal` with the message redacted. The HTTP status / envelope shape
|
|
398
|
+
is locked.
|
|
384
399
|
|
|
385
400
|
## `defineConfig({ app, tenant, target, collections })`
|
|
386
401
|
|
|
@@ -416,7 +431,9 @@ Schemas: any [StandardSchema v1](https://standardschema.dev) validator
|
|
|
416
431
|
(Zod 3.24+, Valibot 0.36+, ArkType 2.0+). Validation runs on the
|
|
417
432
|
post-image: `update` and `replace` see the full doc, not just the
|
|
418
433
|
patch. Failures → `BaerlyError{code:"SchemaError", issues:[…]}`,
|
|
419
|
-
mapped to HTTP 400.
|
|
434
|
+
mapped to HTTP 400. Validation is write-path only — reads, export, and
|
|
435
|
+
replay never re-validate, so a schema change never retroactively rejects
|
|
436
|
+
existing rows.
|
|
420
437
|
|
|
421
438
|
**Author `_id` as required, not `.optional()`.** The validator runs
|
|
422
439
|
on the post-image — by the time it fires, the server has already
|
|
@@ -443,6 +460,8 @@ preserved).
|
|
|
443
460
|
|
|
444
461
|
## `createBaerlyClient` (browser / Node HTTP client)
|
|
445
462
|
|
|
463
|
+
*When NOT to use: server-side in the same process as `Db` — call `Db`/`Collection` directly; the client is for out-of-process / browser callers.*
|
|
464
|
+
|
|
446
465
|
```ts
|
|
447
466
|
import type config from "./baerly.config"; // type-only — server adapter stays out of the SPA bundle
|
|
448
467
|
const client = createBaerlyClient<typeof config>({
|
|
@@ -627,6 +646,16 @@ If your probe path is fixed to something else (a k8s readiness path,
|
|
|
627
646
|
say), put a custom route in front of the kernel (see "Recipe — custom
|
|
628
647
|
routes in front of `baerlyNode`" below).
|
|
629
648
|
|
|
649
|
+
### Machine contract (`GET /v1/spec`)
|
|
650
|
+
|
|
651
|
+
`baerlyWorker` and `baerlyNode` both mount an anonymous
|
|
652
|
+
`GET /v1/spec` → the machine-readable contract IR (error codes +
|
|
653
|
+
HTTP status, predicate operators, method/route tables) — the same
|
|
654
|
+
data shipped as `dist/baerly.spec.json`. It runs the verifier
|
|
655
|
+
tolerantly: an unauthenticated probe gets the static contract (no
|
|
656
|
+
401), and a request that the verifier accepts additionally gets a
|
|
657
|
+
`collections` array of declared collection + index names.
|
|
658
|
+
|
|
630
659
|
### Read modifiers (query params)
|
|
631
660
|
|
|
632
661
|
`GET /v1/c/:collection` accepts three JSON-encoded query params; all are
|
|
@@ -647,6 +676,8 @@ client.
|
|
|
647
676
|
|
|
648
677
|
## Adapter factories
|
|
649
678
|
|
|
679
|
+
*On Cloudflare Workers use `r2BindingStorage(env.BUCKET)` (the R2 binding), NOT the S3-credentials factory — credential-based factories assume `fetch` + Node TLS, not the Workers runtime.*
|
|
680
|
+
|
|
650
681
|
```ts
|
|
651
682
|
// Cloudflare Worker entry
|
|
652
683
|
import { baerlyWorker } from "@gusto/baerly-storage/cloudflare";
|
|
@@ -655,8 +686,18 @@ export default baerlyWorker((env) => ({
|
|
|
655
686
|
// scheduled?: (controller, env, ctx) => … // opt-in cron handler
|
|
656
687
|
}));
|
|
657
688
|
|
|
658
|
-
// Node listener entry (any host that runs `node server.js`)
|
|
659
|
-
|
|
689
|
+
// Node listener entry (any host that runs `node server.js`).
|
|
690
|
+
// resolveStorageFromEnv() is the safe default selector: R2_ACCOUNT_ID → R2,
|
|
691
|
+
// BUCKET → S3, else local-fs (dev only). It REFUSES to start in a detected
|
|
692
|
+
// deployment with no bucket — never a silent in-memory/local-fs fallback,
|
|
693
|
+
// which is how hand-rolled selectors ship data loss to production.
|
|
694
|
+
// (assertStorageReachable(storage) adds an opt-in boot-time CAS probe.)
|
|
695
|
+
import { baerlyNode, resolveStorageFromEnv } from "@gusto/baerly-storage/node";
|
|
696
|
+
const { storage, label } = resolveStorageFromEnv();
|
|
697
|
+
baerlyNode({ storage, webRoot: "dist/client" }).listen(PORT); // webRoot optional
|
|
698
|
+
|
|
699
|
+
// Or select the store yourself (custom endpoint, MinIO, GCS, …):
|
|
700
|
+
import { s3Storage } from "@gusto/baerly-storage/node";
|
|
660
701
|
baerlyNode({
|
|
661
702
|
storage: s3Storage({ bucket: "…", credentials: { … } }),
|
|
662
703
|
verifier: bearerJwt({ jwks, issuer, audience }),
|
|
@@ -709,12 +750,7 @@ export default baerlyWorker(() => ({ config }));
|
|
|
709
750
|
`s3Storage` / `r2Storage` / `minioStorage` / `gcsStorage` from
|
|
710
751
|
`@gusto/baerly-storage/node` are re-exports of one factory family — same
|
|
711
752
|
shape (bucket + credentials), all hide `aws4fetch` / `@xmldom/xmldom`
|
|
712
|
-
behind the package boundary.
|
|
713
|
-
`r2BindingStorage` from `@gusto/baerly-storage/cloudflare`**: that one takes
|
|
714
|
-
the platform-bound `R2Bucket` directly (`r2BindingStorage(env.BUCKET)`)
|
|
715
|
-
and is the only storage factory a Worker should reach for — the
|
|
716
|
-
credential-based factories assume `fetch` + Node TLS, not the Workers
|
|
717
|
-
runtime.
|
|
753
|
+
behind the package boundary.
|
|
718
754
|
|
|
719
755
|
### Verifier presets
|
|
720
756
|
|
|
@@ -743,8 +779,9 @@ Signature, audience, and expiry checks are still enforced; only
|
|
|
743
779
|
tenant derivation is replaced.
|
|
744
780
|
|
|
745
781
|
**Why a function and not a class?** The source repo's
|
|
746
|
-
`docs/
|
|
747
|
-
|
|
782
|
+
`docs/guide/auth.md` records the properties the shape upholds and the
|
|
783
|
+
rejected alternatives (class hierarchy, middleware chain, closed enum,
|
|
784
|
+
kernel-side composition).
|
|
748
785
|
|
|
749
786
|
## Observability
|
|
750
787
|
|
|
@@ -880,13 +917,14 @@ export default {
|
|
|
880
917
|
|
|
881
918
|
The client reads via the normal `GET /v1/c/messages` route and tails
|
|
882
919
|
via `GET /v1/since?collection=messages&cursor=…` — both still served by
|
|
883
|
-
`inner`. Only writes go through `/api/messages`.
|
|
920
|
+
`inner`. Only writes go through `/api/messages`. Reads stay uncapped and
|
|
921
|
+
tenant-wide — scope and clamp them in your route too (see RECIPES.md).
|
|
884
922
|
|
|
885
923
|
**Known limitations of this recipe.** The custom-route `Db.create` is
|
|
886
924
|
a second instance — it doesn't share `baerlyWorker`'s
|
|
887
925
|
`observableStorage(...)` wrapping (so custom-route writes don't land
|
|
888
926
|
in the canonical-line storage counters) or the read-cache invalidation
|
|
889
|
-
helper. For
|
|
927
|
+
helper. For small chat-shaped apps this is acceptable; the
|
|
890
928
|
observability gap is being tracked as a follow-up. If you also need
|
|
891
929
|
PATCH/PUT/DELETE on the same collection, repeat steps (1) and (2) for
|
|
892
930
|
each verb.
|
|
@@ -1046,22 +1084,16 @@ once. Pick by what you want to observe.
|
|
|
1046
1084
|
|
|
1047
1085
|
## Anti-patterns
|
|
1048
1086
|
|
|
1049
|
-
|
|
1050
|
-
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
- Don't put `SHARED_SECRET` in the SPA bundle
|
|
1054
|
-
server-to-server-only; the dev path uses `baerlyDevAuth` to inject
|
|
1055
|
-
it server-side, the prod path uses CF Access (CF target) or
|
|
1056
|
-
`bearerJwt` (Node target).
|
|
1057
|
-
- Don't mutate `VerifierResult.tenantPrefix` between the verifier
|
|
1058
|
-
and `Db.create`. The dispatcher pins the tenant from the
|
|
1059
|
-
verifier's return value.
|
|
1087
|
+
A few that compile but are wrong (full list, keyed by the exact error
|
|
1088
|
+
string you see: `cat node_modules/@gusto/baerly-storage/dist/RECIPES.md`):
|
|
1089
|
+
|
|
1090
|
+
- Don't widen branded types (`UUID`, `ContentVersionId`) with `as string`.
|
|
1091
|
+
- Don't put `SHARED_SECRET` in the SPA bundle — it's server-to-server only.
|
|
1060
1092
|
|
|
1061
1093
|
## Where to look next
|
|
1062
1094
|
|
|
1063
1095
|
- **A call you expected doesn't type-check?** The public surface is
|
|
1064
|
-
additive-only locked
|
|
1096
|
+
additive-only locked, but the rare breaking change carries an
|
|
1065
1097
|
old→new migration in `dist/CHANGELOG.md` (`cat dist/CHANGELOG.md`). The
|
|
1066
1098
|
`.d.ts` types are canonical; the changelog is the recovery path.
|
|
1067
1099
|
- Per-symbol JSDoc: read the `.d.ts` chunks in this directory
|
|
@@ -1069,4 +1101,4 @@ once. Pick by what you want to observe.
|
|
|
1069
1101
|
splits them; `cat dist/*.d.ts` gives the union.
|
|
1070
1102
|
- Theoretical foundations + cost model: the repository's `docs/`
|
|
1071
1103
|
tree (`docs/about/`, `docs/spec/`).
|
|
1072
|
-
-
|
|
1104
|
+
- Common mistakes & recipes: `cat node_modules/@gusto/baerly-storage/dist/RECIPES.md`; deeper guides in the repo's `docs/guide/`.
|