@gusto/baerly-storage 0.5.0 → 0.7.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 +47 -124
- package/dist/API.md +161 -511
- package/dist/CHANGELOG.md +1148 -307
- package/dist/RECIPES.md +398 -80
- package/dist/THIRD-PARTY-LICENSES.txt +5 -26
- package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
- package/dist/app-config.d.ts +31 -1
- package/dist/app-config.js +1 -2
- package/dist/app-config.js.map +1 -1
- package/dist/auth.d.ts +33 -28
- package/dist/auth.js +549 -985
- package/dist/auth.js.map +1 -1
- package/dist/baerly.js +130 -138
- package/dist/baerly.js.map +1 -1
- package/dist/baerly.spec.json +97 -22
- package/dist/capacity-warning-header-BlVopyiI.js +16 -0
- package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
- package/dist/{client-Fe8CwB73.d.ts → client-CHQTXpef.d.ts} +121 -36
- package/dist/client-react.d.ts +67 -20
- package/dist/client-react.js +240 -54
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +5 -4
- package/dist/client.js +51 -16
- package/dist/client.js.map +1 -1
- package/dist/{cloudflare-DzKBrUlg.js → cloudflare-CKHYXccw.js} +504 -124
- package/dist/cloudflare-CKHYXccw.js.map +1 -0
- package/dist/cloudflare.d.ts +106 -71
- package/dist/cloudflare.js +334 -271
- package/dist/cloudflare.js.map +1 -1
- package/dist/code-resolution-CL_7L0wS.js +22 -0
- package/dist/code-resolution-CL_7L0wS.js.map +1 -0
- package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
- package/dist/config-DEzInG6M.js +4035 -0
- package/dist/config-DEzInG6M.js.map +1 -0
- package/dist/constants-D3GSH3tc.js +469 -0
- package/dist/constants-D3GSH3tc.js.map +1 -0
- package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
- package/dist/context-rlpSnHFA.js.map +1 -0
- package/dist/cost-B52llVDx.js +330 -0
- package/dist/cost-B52llVDx.js.map +1 -0
- package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
- package/dist/current-json-CC6lE4Aj.js.map +1 -0
- package/dist/db-plFUNTSF.d.ts +130 -0
- package/dist/db-read-seams-BSs0m1z1.js +3261 -0
- package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
- package/dist/{deploy-DonTr-CV.js → deploy-Obj4nE-Z.js} +12 -16
- package/dist/deploy-Obj4nE-Z.js.map +1 -0
- package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
- package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
- package/dist/dev-landing-CD-si4dW.js +50 -0
- package/dist/dev-landing-CD-si4dW.js.map +1 -0
- package/dist/dev-vite.d.ts +38 -39
- package/dist/dev-vite.js +67 -36
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +3 -2
- package/dist/dev.js +2 -1
- package/dist/doctor-BA0i-YAN.js +270 -0
- package/dist/doctor-BA0i-YAN.js.map +1 -0
- package/dist/dump-D1vX8ozg.js +133 -0
- package/dist/dump-D1vX8ozg.js.map +1 -0
- package/dist/errors-7Rk1HGCE.js +160 -0
- package/dist/errors-7Rk1HGCE.js.map +1 -0
- package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
- package/dist/export-BVL2EvYE.js.map +1 -0
- package/dist/fsck-BWkPgov4.js +145 -0
- package/dist/fsck-BWkPgov4.js.map +1 -0
- package/dist/gcs-admin-Dso1HWQj.d.ts +127 -0
- package/dist/gcs.d.ts +30 -0
- package/dist/gcs.js +1 -0
- package/dist/goog4-signer-CeLIABoE.js +331 -0
- package/dist/goog4-signer-CeLIABoE.js.map +1 -0
- package/dist/{http-DGd5tbNs.js → http-Z5rZyYMX.js} +898 -271
- package/dist/http-Z5rZyYMX.js.map +1 -0
- package/dist/http-transport-DNUM8kU-.js +1299 -0
- package/dist/http-transport-DNUM8kU-.js.map +1 -0
- package/dist/http.d.ts +366 -294
- package/dist/http.js +2 -2
- package/dist/index-JJrIu1pO.d.ts +135 -0
- package/dist/index-LEgHN0qJ.d.ts +50 -0
- package/dist/{index-CuA9Mi3K.d.ts → index-RiEYj8t0.d.ts} +291 -78
- package/dist/index.d.ts +27 -6
- package/dist/index.js +3 -5
- package/dist/inspect-BTsVYZKd.js +196 -0
- package/dist/inspect-BTsVYZKd.js.map +1 -0
- package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
- package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
- package/dist/ledger-Dj_bGgo0.js +192 -0
- package/dist/ledger-Dj_bGgo0.js.map +1 -0
- package/dist/legacy-names-DgZBtgOh.js +47 -0
- package/dist/legacy-names-DgZBtgOh.js.map +1 -0
- package/dist/log-C9W15Dfo.d.ts +94 -0
- package/dist/log-tail-DWJbneBF.js +142 -0
- package/dist/log-tail-DWJbneBF.js.map +1 -0
- package/dist/log-walk-C-vA-WGJ.js +111 -0
- package/dist/log-walk-C-vA-WGJ.js.map +1 -0
- package/dist/maintenance-Dd-Yakqj.js +1709 -0
- package/dist/maintenance-Dd-Yakqj.js.map +1 -0
- package/dist/maintenance-DevB6z4e.js +2237 -0
- package/dist/maintenance-DevB6z4e.js.map +1 -0
- package/dist/maintenance.d.ts +100 -3
- package/dist/maintenance.js +1 -3
- package/dist/node.d.ts +130 -142
- package/dist/node.js +4 -3
- package/dist/{observability-BmflLCdF.js → observability-C-ISCCLE.js} +1275 -332
- package/dist/observability-C-ISCCLE.js.map +1 -0
- package/dist/observability.d.ts +27 -3
- package/dist/observability.js +3 -3
- package/dist/path-segment-DBXG26PW.js +363 -0
- package/dist/path-segment-DBXG26PW.js.map +1 -0
- package/dist/{plan-a7PJHBCy.js → plan-BvQbaNMe.js} +19 -11
- package/dist/plan-BvQbaNMe.js.map +1 -0
- package/dist/request-CRWiTrza.js +272 -0
- package/dist/request-CRWiTrza.js.map +1 -0
- package/dist/restore-U6Im8V1V.js +1467 -0
- package/dist/restore-U6Im8V1V.js.map +1 -0
- package/dist/retry-OBtLB2GC.js +126 -0
- package/dist/retry-OBtLB2GC.js.map +1 -0
- package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
- package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec-B5mg3pHF.js} +189 -28
- package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
- package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DBC_wiCL.d.ts} +18 -10
- package/dist/s3.d.ts +20 -7
- package/dist/s3.js +4 -5
- package/dist/s3.js.map +1 -1
- package/dist/sha256-4FfGQNPw.js +22 -0
- package/dist/sha256-4FfGQNPw.js.map +1 -0
- package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
- package/dist/shared-secret-Vkur-8r0.js.map +1 -0
- package/dist/sigv4-sign-5IUflUD_.js +507 -0
- package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
- package/dist/snapshot-CknzkDM0.js +148 -0
- package/dist/snapshot-CknzkDM0.js.map +1 -0
- package/dist/{src-BL_JoPTn.js → src-Actga-bO.js} +1004 -378
- package/dist/src-Actga-bO.js.map +1 -0
- package/dist/src-D0MQfvOp.js +812 -0
- package/dist/src-D0MQfvOp.js.map +1 -0
- package/dist/src-Dr9uo3dc.js +501 -0
- package/dist/src-Dr9uo3dc.js.map +1 -0
- package/dist/{subcommand-DoDA-K7d.js → subcommand-BLoF66dG.js} +89 -16
- package/dist/subcommand-BLoF66dG.js.map +1 -0
- package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
- package/dist/time-DRxTP9iv.js.map +1 -0
- package/dist/types-suVbsEWS.d.ts +116 -0
- package/dist/{usage-DBV1eQHC.js → usage-CPzVhrQr.js} +40 -45
- package/dist/usage-CPzVhrQr.js.map +1 -0
- package/dist/uuid-BuT_c404.js +333 -0
- package/dist/uuid-BuT_c404.js.map +1 -0
- package/dist/verifier-Bmlmndzo.d.ts +95 -0
- package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
- package/dist/wire-DndvKU-K.js.map +1 -0
- package/package.json +96 -69
- package/dist/aws4fetch.esm-p7eEzLCs.js +0 -1702
- package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
- package/dist/bytes-BXdamO3L.js +0 -11
- package/dist/bytes-BXdamO3L.js.map +0 -1
- package/dist/cloudflare-DzKBrUlg.js.map +0 -1
- package/dist/config-1tv0-Yzm.js +0 -2693
- package/dist/config-1tv0-Yzm.js.map +0 -1
- package/dist/constants-CfeMWQWk.js +0 -222
- package/dist/constants-CfeMWQWk.js.map +0 -1
- package/dist/context-DRZ3tZ5l.js.map +0 -1
- package/dist/cost-DSMIVqzL.js +0 -203
- package/dist/cost-DSMIVqzL.js.map +0 -1
- package/dist/current-json-C6nhPOm1.js.map +0 -1
- package/dist/db-DsPkOVEH.d.ts +0 -254
- package/dist/deploy-DonTr-CV.js.map +0 -1
- package/dist/doctor-DSIyCDg_.js +0 -346
- package/dist/doctor-DSIyCDg_.js.map +0 -1
- package/dist/dump-Bh5k26VQ.js +0 -94
- package/dist/dump-Bh5k26VQ.js.map +0 -1
- package/dist/errors-Dfa3p78c.js +0 -78
- package/dist/errors-Dfa3p78c.js.map +0 -1
- package/dist/export-DtF5tDIM.js +0 -401
- package/dist/export-DtF5tDIM.js.map +0 -1
- package/dist/fsck-D_djMO5D.js +0 -279
- package/dist/fsck-D_djMO5D.js.map +0 -1
- package/dist/http-DGd5tbNs.js.map +0 -1
- package/dist/index-0rZcMBwy.d.ts +0 -115
- package/dist/index-BNRh23K9.d.ts +0 -162
- package/dist/index-BYk9oCNf.d.ts +0 -1112
- package/dist/indexes-Dn9hbGQG.d.ts +0 -22
- package/dist/inspect-6WZ-pC7-.js +0 -133
- package/dist/inspect-6WZ-pC7-.js.map +0 -1
- package/dist/log-tail-D98U1JBo.js +0 -522
- package/dist/log-tail-D98U1JBo.js.map +0 -1
- package/dist/maintenance-B4Dki6Ig.js +0 -2157
- package/dist/maintenance-B4Dki6Ig.js.map +0 -1
- package/dist/maintenance-B_e0T99L.d.ts +0 -537
- package/dist/maintenance-C7coQp4c.js +0 -1418
- package/dist/maintenance-C7coQp4c.js.map +0 -1
- package/dist/normalize-rjnZLwS4.js +0 -133
- package/dist/normalize-rjnZLwS4.js.map +0 -1
- package/dist/observability-BmflLCdF.js.map +0 -1
- package/dist/plan-a7PJHBCy.js.map +0 -1
- package/dist/query-rAtXNQQB.js +0 -1773
- package/dist/query-rAtXNQQB.js.map +0 -1
- package/dist/rebuild-index-BVzQSZlm.js +0 -81
- package/dist/rebuild-index-BVzQSZlm.js.map +0 -1
- package/dist/request-u0M51mhJ.js +0 -72
- package/dist/request-u0M51mhJ.js.map +0 -1
- package/dist/restore-R-4rbciV.js +0 -778
- package/dist/restore-R-4rbciV.js.map +0 -1
- package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
- package/dist/runtime-spec-Dsw2-n8S.js.map +0 -1
- package/dist/shared-secret-DgEicd3x.js.map +0 -1
- package/dist/src-BL_JoPTn.js.map +0 -1
- package/dist/src-CYHFDrKz.js +0 -536
- package/dist/src-CYHFDrKz.js.map +0 -1
- package/dist/src-DYZ4H1aF.js +0 -392
- package/dist/src-DYZ4H1aF.js.map +0 -1
- package/dist/subcommand-DoDA-K7d.js.map +0 -1
- package/dist/time-DUqvFMHq.js.map +0 -1
- package/dist/usage-DBV1eQHC.js.map +0 -1
- package/dist/validate-DtljsCh1.js.map +0 -1
- package/dist/wire-izfGZDvr.js.map +0 -1
package/README.md
CHANGED
|
@@ -9,29 +9,16 @@ before: client → app handler → database server (a server)
|
|
|
9
9
|
after: client → app handler → S3/R2 bucket (just storage)
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
The trick is to cram the entire database execution layer inside an HTTP
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- **
|
|
21
|
-
|
|
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.
|
|
12
|
+
The trick is to cram the entire database execution layer inside an HTTP request. There is no server, daemon, or coordinator: each read or write runs as library code inside your request handler, the bucket holds the data, and the protocol supplies the commit rules.
|
|
13
|
+
|
|
14
|
+
The load-bearing operation is narrow — one conditional create of the next log object commits a write. When the request ends, baerly-storage is gone. Poof!
|
|
15
|
+
|
|
16
|
+
- **An API small enough to hold in your context.** No DDL, no raw SQL — 8 verbs and a ~12k-token surface you can hand to an LLM or a non-engineer and walk away.
|
|
17
|
+
- **Idle rounds to zero.** No database process to keep warm, and no per-app database floor across a fleet of small internal tools.
|
|
18
|
+
- **No data hostage.** `baerly export --target=postgres` gives you a per-collection SQL snapshot. Crossing the envelope is the graduation signal; the data exit is mechanical.
|
|
19
|
+
- **No new vendor.** Your S3/R2 bucket cleared security review years ago; every hosted alternative means a fresh vendor review and an IT ticket for a new managed-DB SKU.
|
|
20
|
+
- **Nothing to go down.** No resident service in your critical path, one fewer failure domain. Servers that don't exist can't go down.
|
|
21
|
+
- **Built like git.** Content-addressed snapshots, immutable numbered log entries, and one conditional log create as the commit, per collection.
|
|
35
22
|
|
|
36
23
|
<!-- Hero demo: render `docs/assets/demo.gif` from `docs/assets/demo.tape`
|
|
37
24
|
(`vhs docs/assets/demo.tape`) against a real bucket, then uncomment:
|
|
@@ -44,18 +31,13 @@ log object commits a write. When the request ends, baerly-storage is gone. Poof!
|
|
|
44
31
|
pnpm create @gusto/baerly-storage@latest
|
|
45
32
|
```
|
|
46
33
|
|
|
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.
|
|
34
|
+
The wizard asks for a project name, target, and starter, then prints the dev command. First run needs no bucket credentials: local dev uses local storage and serves the UI plus `/v1/*` from one origin.
|
|
50
35
|
|
|
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).
|
|
36
|
+
For a runnable multi-tab demo see [`examples/react-node/`](./examples/react-node); for the full set of production-shaped scaffolds see [`examples/`](./examples).
|
|
54
37
|
|
|
55
38
|
## In code
|
|
56
39
|
|
|
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:
|
|
40
|
+
The public surface is a small document API. The scaffolds wire `db` on the server and `useQuery` in React; the calls look like this:
|
|
59
41
|
|
|
60
42
|
```ts
|
|
61
43
|
// server — writes land in your object-storage bucket
|
|
@@ -67,8 +49,7 @@ const open = useQuery((c) => c.collection("tickets").where({ status: "open" }).a
|
|
|
67
49
|
// open.data is present for "ok" / "refreshing"
|
|
68
50
|
```
|
|
69
51
|
|
|
70
|
-
Application auth and tenant choice stay explicit in the handler. What
|
|
71
|
-
disappears is the database service and its surrounding machinery:
|
|
52
|
+
Application auth and tenant choice stay explicit in the handler. What disappears is the database service and its surrounding machinery:
|
|
72
53
|
|
|
73
54
|
```diff
|
|
74
55
|
- docker-compose.yml
|
|
@@ -90,8 +71,7 @@ disappears is the database service and its surrounding machinery:
|
|
|
90
71
|
+ });
|
|
91
72
|
```
|
|
92
73
|
|
|
93
|
-
Ordinary schema shape changes are TypeScript or config edits — no DDL, no
|
|
94
|
-
SQL strings, no generated migration ceremony.
|
|
74
|
+
Ordinary schema shape changes are TypeScript or config edits — no DDL, no SQL strings, no generated migration ceremony.
|
|
95
75
|
|
|
96
76
|
## Cheat sheet
|
|
97
77
|
|
|
@@ -109,60 +89,32 @@ db.collection("tickets").update(id, { status: "closed" }); // merge-patch
|
|
|
109
89
|
db.collection("tickets").where({ status: "closed" }).delete();
|
|
110
90
|
```
|
|
111
91
|
|
|
112
|
-
| Surface
|
|
113
|
-
|
|
|
114
|
-
| **Verbs**
|
|
115
|
-
| **Modifiers** | `where` `order` `limit`
|
|
116
|
-
| **Operators** | `eq` `gt` `gte` `lt` `lte` `in`
|
|
117
|
-
| **Errors**
|
|
92
|
+
| Surface | Vocabulary |
|
|
93
|
+
| --- | --- |
|
|
94
|
+
| **Verbs** | `first` `all` `count` `get` · `insert` `update` `replace` `delete` |
|
|
95
|
+
| **Modifiers** | `where` `order` `limit` |
|
|
96
|
+
| **Operators** | `eq` `gt` `gte` `lt` `lte` `in` |
|
|
97
|
+
| **Errors** | one `BaerlyError`, discriminate by `.code` (`WriteConflict`, `NotFound`, `SchemaError`, …) |
|
|
118
98
|
|
|
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.
|
|
99
|
+
Full reference: [`docs/guide/cheatsheet.md`](./docs/guide/cheatsheet.md), or `cat node_modules/@gusto/baerly-storage/dist/API.md` in an installed app.
|
|
122
100
|
|
|
123
101
|
## How it works
|
|
124
102
|
|
|
125
|
-
**The hard part of a database-in-a-bucket is the commit.** A bucket can
|
|
126
|
-
|
|
127
|
-
win each
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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).
|
|
103
|
+
**The hard part of a database-in-a-bucket is the commit.** A bucket can store objects; it cannot run a transaction coordinator. So one writer must win each race, and every reader must be able to tell what won. [S3's strong consistency][s3-strong] makes object storage usable as shared state; conditional writes supply the one-writer-wins operation.
|
|
104
|
+
|
|
105
|
+
Concretely, a write drops new immutable objects in the bucket and then creates the next numbered log entry for that collection with create-if-absent (`If-None-Match: "*"`). Two writers racing the same slot cannot both win; the loser reads the winner and retries at the next slot. That create _is_ the commit. There is no resident coordinator: each request reads bucket state, tries that create, and leaves no required process behind. A read follows `current.json` to the snapshot and folds the committed log tail into rows.
|
|
106
|
+
|
|
107
|
+
baerly-storage shares the immutable-artifact foundation of table formats like Apache Iceberg and Delta Lake, but commits with a narrower step: no metadata-pointer swap and no separate coordinator — just that one log create. See [prior art and lineage](docs/spec/prior-art.md) for how it relates to Iceberg, Delta Lake, Litestream, and Turbopuffer.
|
|
108
|
+
|
|
109
|
+
Each collection has its own ordered log, so **writes are per-collection linearizable** — the `If-None-Match` log create linearizes every commit. Cross-collection writes are unordered and non-atomic; that boundary is part of the contract (see [When (not) to use it](#when-not-to-use-it)).
|
|
110
|
+
|
|
111
|
+
The durable contract is the bucket layout plus the conditional-write rules. Another language could speak it by writing the same layout and honoring the same rules. See [`storage-compatibility.md`](./docs/spec/storage-compatibility.md).
|
|
155
112
|
|
|
156
113
|
[s3-strong]: https://aws.amazon.com/blogs/aws/amazon-s3-update-strong-read-after-write-consistency/
|
|
157
114
|
|
|
158
115
|
### Security model
|
|
159
116
|
|
|
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).
|
|
117
|
+
Bucket credentials never leave the server. Browsers talk only to your trusted handler, which authenticates the caller, chooses the tenant prefix, and applies the protocol against the bucket. Production recipes support Cloudflare Access and JWKS bearer verification; shared-secret auth is for service-to-service calls and dev. See [`client-auth.md`](./docs/guide/client-auth.md).
|
|
166
118
|
|
|
167
119
|
## When (not) to use it
|
|
168
120
|
|
|
@@ -170,60 +122,31 @@ Before you count rows or price reads, ask one question:
|
|
|
170
122
|
|
|
171
123
|
> Can the app's most important work be done from one collection?
|
|
172
124
|
|
|
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.
|
|
125
|
+
If yes, baerly-storage may fit; then check query shape, atomicity, size, and cost. A todo list, a single board's kanban, an event's RSVPs, one channel's chat — each maps to one collection. The shape is narrow on purpose: production-shaped for small workloads with a specific access pattern, not a general-purpose database. If the core screen is a view _across_ many collections, users, or tenants ("my pull requests," "all code search," a cross-org dashboard), baerly-storage should not be the only query engine for it.
|
|
181
126
|
|
|
182
127
|
It is **deliberately not** a few things:
|
|
183
128
|
|
|
184
|
-
- **No SQL, no joins.** Equality + dotted-path predicates, operators
|
|
185
|
-
|
|
186
|
-
- **
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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).
|
|
129
|
+
- **No SQL, no joins.** Equality + dotted-path predicates, operators added one at a time. The small surface is part of the contract.
|
|
130
|
+
- **Not a D1 / Postgres replacement.** Those are graduation targets, not competitors — baerly-storage keeps the experiment cheap until you know whether it's worth graduating.
|
|
131
|
+
- **Browser-direct multi-writer is out.** Trusted server-side app code is the design center.
|
|
132
|
+
- **Realtime is long-poll first.** Polling is always correct; a WebSocket tier would be a future opt-in.
|
|
133
|
+
|
|
134
|
+
None of these are apologies — baerly-storage names its envelope so graduation is a feature, not a surprise: `baerly export --target=postgres` makes the exit mechanical. The shape test lives in [workload-fit.md](./docs/about/workload-fit.md); the numeric envelope in [graduation.md](./docs/about/graduation.md).
|
|
200
135
|
|
|
201
136
|
## Go deeper
|
|
202
137
|
|
|
203
|
-
- ✨ **Why baerly-storage** —
|
|
204
|
-
|
|
205
|
-
- 🧭 **How it works** —
|
|
206
|
-
[`docs/about/how-it-works.md`](./docs/about/how-it-works.md) (bucket +
|
|
207
|
-
conditional log create)
|
|
138
|
+
- ✨ **Why baerly-storage** — [`docs/about/why-baerly.md`](./docs/about/why-baerly.md)
|
|
139
|
+
- 🧭 **How it works** — [`docs/about/how-it-works.md`](./docs/about/how-it-works.md) (bucket + conditional log create)
|
|
208
140
|
- 🧱 **Product thesis** — [`docs/about/thesis.md`](./docs/about/thesis.md)
|
|
209
|
-
- 🏗️ **Architecture** —
|
|
210
|
-
|
|
211
|
-
-
|
|
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)
|
|
141
|
+
- 🏗️ **Architecture** — [`docs/architecture.md`](./docs/architecture.md)
|
|
142
|
+
- 🔧 **Embed by hand** — [`packages/server/API.md`](./packages/server/API.md) (embed-by-hand + custom-routes recipes; ships as `dist/API.md` in the package)
|
|
143
|
+
- 📊 **Alternatives** — [`docs/about/alternatives.md`](./docs/about/alternatives.md) (how baerly-storage compares to Firebase, Supabase, Convex, and Cloudflare D1)
|
|
218
144
|
|
|
219
145
|
## Where things live
|
|
220
146
|
|
|
221
|
-
- [`CLAUDE.md`](./CLAUDE.md) — agent + contributor entry point (the
|
|
222
|
-
|
|
223
|
-
- [`
|
|
224
|
-
conventions, ADRs, protocol specs, operating procedures.
|
|
225
|
-
- [`examples/`](./examples) — runnable scaffolds + the `react-node/`
|
|
226
|
-
multi-tab demo.
|
|
147
|
+
- [`CLAUDE.md`](./CLAUDE.md) — agent + contributor entry point (the fastest map for humans too). `AGENTS.md` is a symlink.
|
|
148
|
+
- [`docs/README.md`](./docs/README.md) — topic map: architecture, conventions, ADRs, protocol specs, operating procedures.
|
|
149
|
+
- [`examples/`](./examples) — runnable scaffolds + the `react-node/` multi-tab demo.
|
|
227
150
|
|
|
228
151
|
## License
|
|
229
152
|
|