@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
|
@@ -0,0 +1,1001 @@
|
|
|
1
|
+
import { f as DocumentData, h as MergePatch, p as DocumentValue } from "./app-config-C6qW7m8S.js";
|
|
2
|
+
/**
|
|
3
|
+
* Discriminator for {@link BaerlyError}. Strings (not subclasses) so they
|
|
4
|
+
* survive cross-realm boundaries (e.g. a Web Worker) and so callers can
|
|
5
|
+
* pattern-match with grep-friendly equality.
|
|
6
|
+
*/
|
|
7
|
+
type BaerlyErrorCode =
|
|
8
|
+
/** Caller-provided config or input is invalid (bad bucket, unsupported credential type, malformed URL, bucket not version-enabled when versioning was requested, a write whose document would encode to more than `MAX_DOCUMENT_BYTES` = 1 MiB). HTTP maps this code to 400. */
|
|
9
|
+
"InvalidConfig" |
|
|
10
|
+
/** Generic S3/HTTP transport failure (5xx, unexpected status, retries exhausted). */
|
|
11
|
+
"NetworkError" |
|
|
12
|
+
/** S3 returned 403. Either credentials are wrong or the bucket policy denies the operation. */
|
|
13
|
+
"AccessDenied" |
|
|
14
|
+
/** Server returned data that didn't parse (malformed XML, non-JSON body where JSON expected). */
|
|
15
|
+
"InvalidResponse" |
|
|
16
|
+
/** Internal invariant violation — should not be reachable. File a bug. */
|
|
17
|
+
"Internal" |
|
|
18
|
+
/**
|
|
19
|
+
* Document body failed schema validation. Emitted by the table-API
|
|
20
|
+
* write verbs (`Collection.insert`, `Query.update`, `Collection.replace`) when
|
|
21
|
+
* the body is not valid JSON or contains an array where
|
|
22
|
+
* `DocumentValue` is required; also emitted when a collection has a
|
|
23
|
+
* declared `SchemaValidator` (via `Db.create({ collections })`) and
|
|
24
|
+
* the bound schema rejects the doc. In the schema-rejection case the
|
|
25
|
+
* error carries an `issues` array describing each failure. HTTP layer
|
|
26
|
+
* maps this to 400.
|
|
27
|
+
*/
|
|
28
|
+
"SchemaError" |
|
|
29
|
+
/**
|
|
30
|
+
* Another write won a race this call needed to win, and the losing commit
|
|
31
|
+
* did not land. Re-read, then retry; `retriable` is `true`. Each
|
|
32
|
+
* `Collection` / `Query` verb re-reads on every call, so re-issuing the same
|
|
33
|
+
* call is the retry. The writer makes one commit attempt and resolves a
|
|
34
|
+
* log-create race inside it, so this surfaces from a write only for a
|
|
35
|
+
* rejected precondition the writer does not resolve. Maintenance passes
|
|
36
|
+
* (`compact`, `runGc`, log retirement) raise it when a concurrent pass or
|
|
37
|
+
* writer moved `current.json` first; the next pass retries. HTTP maps this
|
|
38
|
+
* code to 409 with a generic message.
|
|
39
|
+
*
|
|
40
|
+
* `Storage` implementations throw this code for every rejected
|
|
41
|
+
* precondition: a stale `ifMatch`, an `ifMatch` against a missing key, or
|
|
42
|
+
* an `ifNoneMatch: "*"` create over an existing key. For a create-only put
|
|
43
|
+
* that followed an attempt of unknown outcome, the occupant may be this
|
|
44
|
+
* call's own earlier write. Callers that care read the key back.
|
|
45
|
+
*/
|
|
46
|
+
"WriteConflict" |
|
|
47
|
+
/**
|
|
48
|
+
* The thing being created already exists, so the same request can never
|
|
49
|
+
* succeed; `retriable` is `false`. `Collection.insert` raises it when a
|
|
50
|
+
* live row already holds the `_id`, including one a concurrent insert
|
|
51
|
+
* committed first: of concurrent inserts of one `_id`, at most one
|
|
52
|
+
* commits and the others raise this. Insert under a different `_id`,
|
|
53
|
+
* omit `_id` to mint one, or change the stored row with `update` /
|
|
54
|
+
* `replace` — unless this follows a same-`_id` retry after
|
|
55
|
+
* `AmbiguousCommit`, where the stored row may be the first attempt:
|
|
56
|
+
* re-read it instead of inserting under a new `_id`.
|
|
57
|
+
* `baerly admin restore` raises it when the target collection already
|
|
58
|
+
* exists and `--force` was not passed. HTTP maps this code to 409 and
|
|
59
|
+
* keeps the message, which names the id and collection.
|
|
60
|
+
*/
|
|
61
|
+
"AlreadyExists" |
|
|
62
|
+
/**
|
|
63
|
+
* A write's commit outcome cannot be resolved: one or more committing
|
|
64
|
+
* `log/<seq>` creates may already be durable, but the writer cannot adopt or
|
|
65
|
+
* report a confirmed commit. This includes an unresolved create acknowledgement
|
|
66
|
+
* after the occupant readback, and a create that landed below the
|
|
67
|
+
* certified delete floor (`seq < min(log_delete_floor, log_seq_start)`).
|
|
68
|
+
*
|
|
69
|
+
* `BaerlyError._id` names the affected row, including an auto-ID insert's
|
|
70
|
+
* minted id. Re-read that row and compare it with the intended state before
|
|
71
|
+
* deciding what to do. A matching row helps reconcile the outcome; absence
|
|
72
|
+
* does not prove that a create failed, since a send may still complete or its
|
|
73
|
+
* effect may have been superseded. Retrying is an explicit at-least-once
|
|
74
|
+
* choice and may repeat logical work. Retry an insert with the same `_id`:
|
|
75
|
+
* a second create then targets the same row instead of minting a second
|
|
76
|
+
* document, and commits only if no live row holds that `_id`. An
|
|
77
|
+
* `AlreadyExists` on that retry means a row with that `_id` is committed:
|
|
78
|
+
* re-read it and compare with the intended state rather than inserting
|
|
79
|
+
* under a new `_id`. `retriable` is `false` so generic retry wrappers do
|
|
80
|
+
* not repeat the operation silently. HTTP maps this code to 409.
|
|
81
|
+
*/
|
|
82
|
+
"AmbiguousCommit" |
|
|
83
|
+
/**
|
|
84
|
+
* The work this request needs is more than the host serving it does in
|
|
85
|
+
* one request, so the request was refused whole; `retriable` is `false`.
|
|
86
|
+
* The refusal is decided per request from the collection's current
|
|
87
|
+
* state and clears by itself once that state changes. Reads and writes
|
|
88
|
+
* both raise it.
|
|
89
|
+
*
|
|
90
|
+
* A refused write commits nothing; a batch refused part-way (a
|
|
91
|
+
* concurrent write filled the room between its check and a row's
|
|
92
|
+
* commit) keeps the rows it already committed. Near the limit only
|
|
93
|
+
* growth is refused (an insert, or an update that makes a row larger):
|
|
94
|
+
* deletes and same-size or shrinking updates still commit, and once
|
|
95
|
+
* maintenance absorbs them, growth is accepted again. When the
|
|
96
|
+
* collection is already more than this host can maintain (for example
|
|
97
|
+
* one grown on a larger host and now served by a smaller one), every
|
|
98
|
+
* write is refused until the collection moves to a larger host or is
|
|
99
|
+
* exported with `baerly admin dump`. Moving hosts is a deployment
|
|
100
|
+
* decision, not an app setting.
|
|
101
|
+
*
|
|
102
|
+
* A refused read returns no rows, never a truncated answer, and writes
|
|
103
|
+
* nothing. Its `resolution` names the remedy for the bound it hit:
|
|
104
|
+
* narrow the predicate or add a limit when the answer is too wide;
|
|
105
|
+
* delete or shrink rows when the collection is too large to read in one
|
|
106
|
+
* request; or retry once maintenance has absorbed pending writes. HTTP
|
|
107
|
+
* maps this code to 409 and keeps the message, which names the
|
|
108
|
+
* collection and the case.
|
|
109
|
+
*/
|
|
110
|
+
"CapacityExceeded" |
|
|
111
|
+
/**
|
|
112
|
+
* Background maintenance is behind on this collection, so this write was
|
|
113
|
+
* refused and not committed (a batch refused part-way keeps the rows it
|
|
114
|
+
* already committed); `retriable` is `true`. The refusal
|
|
115
|
+
* clears by itself once maintenance catches up. {@link BaerlyError.retryAfter}
|
|
116
|
+
* carries the suggested delay in seconds; wait that long, then repeat the
|
|
117
|
+
* call. HTTP maps this code to 503 with a `Retry-After` header and keeps
|
|
118
|
+
* the message.
|
|
119
|
+
*/
|
|
120
|
+
"MaintenancePending" |
|
|
121
|
+
/**
|
|
122
|
+
* A `/v1/since` cursor can no longer resume, so the long-poll was
|
|
123
|
+
* refused; `retriable` is `false`, because the same cursor never
|
|
124
|
+
* succeeds again. Either the changes after it are no longer retained
|
|
125
|
+
* (maintenance retired them), or it was minted in a generation that
|
|
126
|
+
* `baerly admin restore --force` has since truncated. Re-read the rows
|
|
127
|
+
* the subscriber shows, then resume with `cursor: ""`: the changes
|
|
128
|
+
* between the dead cursor and the restart are not replayed. A
|
|
129
|
+
* malformed cursor is `SchemaError` instead. HTTP maps this code to 410
|
|
130
|
+
* and keeps the message.
|
|
131
|
+
*/
|
|
132
|
+
"CursorExpired" |
|
|
133
|
+
/**
|
|
134
|
+
* `Verifier` returned no identity. HTTP server maps to 401.
|
|
135
|
+
* Code is reserved here so the union locks.
|
|
136
|
+
*/
|
|
137
|
+
"Unauthorized" |
|
|
138
|
+
/**
|
|
139
|
+
* The addressed resource does not exist. HTTP server maps to 404.
|
|
140
|
+
* Emitted by the row-by-id read / update / delete handlers in
|
|
141
|
+
* `packages/server/src/http/router.ts` when the predicate
|
|
142
|
+
* `{ _id }` matches zero rows. Not a protocol invariant —
|
|
143
|
+
* callers may retry after creating the resource or treat as a
|
|
144
|
+
* miss depending on intent. The CLI maps this to the generic
|
|
145
|
+
* exit-2 "storage error" bucket, not the exit-3 "protocol
|
|
146
|
+
* invariant" bucket.
|
|
147
|
+
*/
|
|
148
|
+
"NotFound" |
|
|
149
|
+
/**
|
|
150
|
+
* Request body exceeded the server's size cap. HTTP server maps
|
|
151
|
+
* to 413. Cap is `MAX_BODY_BYTES` (1 MiB today; exported from
|
|
152
|
+
* `packages/server/src/http/router.ts`). The router counts bytes
|
|
153
|
+
* while it reads a chunked body and stops at the cap on every
|
|
154
|
+
* host; the Node adapter also enforces it during the `node:http`
|
|
155
|
+
* stream pump and drains the rest of the upload.
|
|
156
|
+
*/
|
|
157
|
+
"PayloadTooLarge" |
|
|
158
|
+
/**
|
|
159
|
+
* A body-bearing HTTP route (`POST`, `PATCH`, `PUT`) got a request
|
|
160
|
+
* whose `Content-Type` is missing or is not `application/json` or a
|
|
161
|
+
* `+json` type. HTTP server maps to 415 and refuses before reading
|
|
162
|
+
* the body. Parameters such as `charset` are allowed. The JSON-only
|
|
163
|
+
* rule is the CSRF defense for ambient auth: a `text/plain` or
|
|
164
|
+
* form-encoded POST is a CORS-simple request another origin can send.
|
|
165
|
+
*/
|
|
166
|
+
"UnsupportedMediaType" |
|
|
167
|
+
/**
|
|
168
|
+
* A predicate is structurally well-formed but contradicts itself —
|
|
169
|
+
* no document can match. Emitted by `validateWire` and
|
|
170
|
+
* `mergePredicateWires`. Triggers:
|
|
171
|
+
* - `{ clauses: [{op:"in", field:"priority", value:[]}] }` (empty `in` set)
|
|
172
|
+
* - an `eq` clause with a value outside the residual interval
|
|
173
|
+
* established by range clauses on the same field
|
|
174
|
+
* - merging `{op:"gt", value:10}` with `{op:"lt", value:5}` on the
|
|
175
|
+
* same field (empty interval)
|
|
176
|
+
* - merging two `in` clauses on the same field with empty intersection
|
|
177
|
+
*
|
|
178
|
+
* Conflicting equality across clauses (`eq:"open"` + `eq:"closed"` on
|
|
179
|
+
* the same field) surfaces as `InvalidConfig` rather than this code —
|
|
180
|
+
* the merger treats it as a caller-side configuration bug, not an
|
|
181
|
+
* algebraic contradiction.
|
|
182
|
+
*
|
|
183
|
+
* The HTTP layer treats this as a 400 (caller error). The distinct
|
|
184
|
+
* code lets downstream code short-circuit empty-by-construction
|
|
185
|
+
* without re-running the validator or parsing messages.
|
|
186
|
+
*/
|
|
187
|
+
"UnsatisfiablePredicate" |
|
|
188
|
+
/**
|
|
189
|
+
* A `useQuery` callback awaited a recorder terminal
|
|
190
|
+
* (`.get`/`.first`/`.all`/`.count`). The recorder runs once per
|
|
191
|
+
* render to capture the chain shape; it cannot survive an `await`
|
|
192
|
+
* because the proxy doesn't proxy across microtask boundaries. The
|
|
193
|
+
* recorder's terminal returns a thenable whose `.then` throws this
|
|
194
|
+
* error synchronously, converting what would otherwise be a silent
|
|
195
|
+
* spinner-hang into a render-time error the hook surfaces as
|
|
196
|
+
* `status: "error"`. Companion `baerly/no-await-in-use-query` lint
|
|
197
|
+
* flags the pattern at edit time. For compound reads, use
|
|
198
|
+
* `Promise.all` (parallel) or compose two `useQuery` calls with
|
|
199
|
+
* `useQuery.skip` (dependent).
|
|
200
|
+
*/
|
|
201
|
+
"UseQueryAwaitedRecorder" |
|
|
202
|
+
/**
|
|
203
|
+
* A write method (`.insert`/`.update`/`.replace`/`.delete`) was
|
|
204
|
+
* called on the recorder inside a `useQuery` callback. Writes
|
|
205
|
+
* inside reads are a programming error; the recorder rejects them
|
|
206
|
+
* synchronously from the discovery pass, before any I/O fires. Use
|
|
207
|
+
* `useMutation()` instead.
|
|
208
|
+
*/
|
|
209
|
+
"UnexpectedWriteInQuery" |
|
|
210
|
+
/**
|
|
211
|
+
* A `useMutation()` callback rejected with a non-`BaerlyError`
|
|
212
|
+
* throwable. The hook wraps the original throw under this code so
|
|
213
|
+
* the `error` slot is always a `BaerlyError`; the original value
|
|
214
|
+
* is preserved on `.cause`.
|
|
215
|
+
*/
|
|
216
|
+
"MutationFailed";
|
|
217
|
+
/**
|
|
218
|
+
* Optional fields for {@link BaerlyError}, the third constructor argument.
|
|
219
|
+
* Each field lands on the same-named property of the error; an omitted
|
|
220
|
+
* field leaves that property `undefined`.
|
|
221
|
+
*/
|
|
222
|
+
interface BaerlyErrorOptions {
|
|
223
|
+
/**
|
|
224
|
+
* The underlying throwable, or a structured detail object. Kept on
|
|
225
|
+
* `error.cause`. A `Storage` adapter reports `cause.notApplied` /
|
|
226
|
+
* `cause.throttled` this way; see the `Storage.put` contract.
|
|
227
|
+
*/
|
|
228
|
+
readonly cause?: unknown;
|
|
229
|
+
/** Field-path issues; set only with `code: "SchemaError"`. Lands on {@link BaerlyError.issues}. */
|
|
230
|
+
readonly issues?: ReadonlyArray<{
|
|
231
|
+
readonly path: ReadonlyArray<string | number>;
|
|
232
|
+
readonly message: string;
|
|
233
|
+
}>;
|
|
234
|
+
/** Raw HTTP status; set only by the client-side wire decoder. Lands on {@link BaerlyError.status}. */
|
|
235
|
+
readonly status?: number;
|
|
236
|
+
/** Canonical corrective action. Lands on {@link BaerlyError.resolution}. */
|
|
237
|
+
readonly resolution?: string;
|
|
238
|
+
/** The affected row's `_id`; set only with `code: "AmbiguousCommit"`. Lands on {@link BaerlyError._id}. */
|
|
239
|
+
readonly _id?: string;
|
|
240
|
+
/** Suggested delay in seconds before retrying; set only with `code: "MaintenancePending"`. Lands on {@link BaerlyError.retryAfter}. */
|
|
241
|
+
readonly retryAfter?: number;
|
|
242
|
+
/**
|
|
243
|
+
* Never set. This object is not an `Error`: `Error` requires `message`, so
|
|
244
|
+
* this field makes `new BaerlyError(code, msg, err)` fail to compile. To
|
|
245
|
+
* chain an error, pass `{ cause: err }`.
|
|
246
|
+
*/
|
|
247
|
+
readonly message?: never;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* The single error class thrown by baerly-storage. Discriminate by `code`, not
|
|
251
|
+
* `instanceof`: the code string survives `JSON.stringify` round-trips
|
|
252
|
+
* across Worker / iframe / postMessage realm boundaries, where each
|
|
253
|
+
* realm has its own `BaerlyError` constructor identity. IDB-restored
|
|
254
|
+
* writes can replay across realms, so `instanceof` would spuriously
|
|
255
|
+
* fail on a structurally-identical error from another realm.
|
|
256
|
+
*
|
|
257
|
+
* @example
|
|
258
|
+
* ```ts
|
|
259
|
+
* try {
|
|
260
|
+
* await db.collection("tickets").insert({ _id: "t-1", title: "hi" });
|
|
261
|
+
* } catch (err) {
|
|
262
|
+
* if (!(err instanceof BaerlyError)) throw err;
|
|
263
|
+
* if (err.code === "AlreadyExists") {
|
|
264
|
+
* // t-1 is taken; retrying cannot succeed.
|
|
265
|
+
* } else if (err.code === "AmbiguousCommit") {
|
|
266
|
+
* // May have landed: re-read err._id before deciding.
|
|
267
|
+
* } else if (err.retriable) {
|
|
268
|
+
* // WriteConflict or NetworkError: retry with bounded backoff.
|
|
269
|
+
* } else {
|
|
270
|
+
* throw err;
|
|
271
|
+
* }
|
|
272
|
+
* }
|
|
273
|
+
* ```
|
|
274
|
+
*/
|
|
275
|
+
declare class BaerlyError extends Error {
|
|
276
|
+
readonly code: BaerlyErrorCode;
|
|
277
|
+
readonly cause?: unknown;
|
|
278
|
+
/**
|
|
279
|
+
* Structured field-path issues, set only when `code === "SchemaError"`.
|
|
280
|
+
* Each entry's `path` is a dotted-key list (e.g. `["assignee", "team"]`
|
|
281
|
+
* or `["items", 3, "qty"]`) that targets the offending field on the
|
|
282
|
+
* input document. `message` is the validator-emitted human string.
|
|
283
|
+
*
|
|
284
|
+
* The HTTP layer's `mapError` renders these into the 400 body via
|
|
285
|
+
* the existing `HttpErrorEnvelope`; older callers that don't know
|
|
286
|
+
* about `issues` see a plain message-only error and stay correct.
|
|
287
|
+
*/
|
|
288
|
+
readonly issues?: ReadonlyArray<{
|
|
289
|
+
readonly path: ReadonlyArray<string | number>;
|
|
290
|
+
readonly message: string;
|
|
291
|
+
}>;
|
|
292
|
+
/**
|
|
293
|
+
* The `_id` of the row whose commit outcome is unknown, set only when
|
|
294
|
+
* `code === "AmbiguousCommit"`. For an auto-ID insert it is the minted
|
|
295
|
+
* id, so the caller can re-read the row and retry with the same `_id`
|
|
296
|
+
* rather than mint a second document. A missing row does not prove the
|
|
297
|
+
* write failed. The HTTP layer carries it in `HttpErrorEnvelope`.
|
|
298
|
+
*/
|
|
299
|
+
readonly _id?: string;
|
|
300
|
+
/**
|
|
301
|
+
* Raw HTTP status, set only by the client-side wire decoder when
|
|
302
|
+
* inflating an `HttpErrorEnvelope` into this class. Server-side
|
|
303
|
+
* throws never set it (the HTTP layer's `mapError` derives the
|
|
304
|
+
* outbound status from `code`). Useful for diagnostics — e.g. to
|
|
305
|
+
* distinguish 404-as-"no such row" from 404-as-"route not found".
|
|
306
|
+
* Discriminate by `code` for behavior; reach for `status` only when
|
|
307
|
+
* you genuinely need the wire value.
|
|
308
|
+
*/
|
|
309
|
+
readonly status?: number;
|
|
310
|
+
/** Canonical corrective action; crosses the wire via `HttpErrorEnvelope.error.resolution`. */
|
|
311
|
+
readonly resolution?: string;
|
|
312
|
+
/** Suggested delay in seconds before retrying; set only for `MaintenancePending`. Crosses the wire via `HttpErrorEnvelope.error.retryAfter` and the `Retry-After` header. */
|
|
313
|
+
readonly retryAfter?: number;
|
|
314
|
+
/**
|
|
315
|
+
* `true` iff re-running the operation from its read step can succeed:
|
|
316
|
+
* `NetworkError` (retry with backoff) and `WriteConflict` (re-read, then
|
|
317
|
+
* write again). A `Collection` / `Query` verb re-reads on every call, so
|
|
318
|
+
* calling it again is the retry; a blind resend of the same conditional
|
|
319
|
+
* `Storage` put loses again. A pure function of `code`
|
|
320
|
+
* ({@link isRetriableCode}): every instance of a code gives the same
|
|
321
|
+
* answer. `AmbiguousCommit` is `false` because the write may have landed;
|
|
322
|
+
* reconcile by `_id` first.
|
|
323
|
+
*/
|
|
324
|
+
get retriable(): boolean;
|
|
325
|
+
/**
|
|
326
|
+
* `code` and `message` are positional; everything else goes in `options`,
|
|
327
|
+
* as with `new Error(message, { cause })`. Passing an `Error` (or any
|
|
328
|
+
* non-options value) as the third argument does not compile; the
|
|
329
|
+
* options object is where `cause` goes.
|
|
330
|
+
*
|
|
331
|
+
* @example
|
|
332
|
+
* ```ts
|
|
333
|
+
* throw new BaerlyError("NetworkError", "PUT failed", { cause: err });
|
|
334
|
+
* throw new BaerlyError("AmbiguousCommit", "commit outcome unknown", { _id: "t-1" });
|
|
335
|
+
* ```
|
|
336
|
+
*/
|
|
337
|
+
constructor(code: BaerlyErrorCode, message: string, options?: BaerlyErrorOptions);
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* Callback-form predicate builder. Methods append clauses and
|
|
341
|
+
* return the same builder for chaining; chained calls AND-merge.
|
|
342
|
+
*
|
|
343
|
+
* The methods on this interface ARE the supported operator surface.
|
|
344
|
+
* Vocabulary additions (`or`, `not`, `regex`, `ne`, `exists`, ...)
|
|
345
|
+
* are intentionally absent — calling them is a TS2339 compile
|
|
346
|
+
* error, not a runtime rejection. The algebra is conjunction-only in
|
|
347
|
+
* perpetuity — see the API surface lock in
|
|
348
|
+
* docs/contributing/conventions/change-discipline.md.
|
|
349
|
+
*
|
|
350
|
+
* @template T - the document shape the predicate is keyed against.
|
|
351
|
+
*/
|
|
352
|
+
interface PredicateBuilder<T extends DocumentData = DocumentData> {
|
|
353
|
+
/**
|
|
354
|
+
* Strict equality on `field`. Use this for the in-callback
|
|
355
|
+
* equality clauses that the object-form would also support;
|
|
356
|
+
* mixing `q.eq(...)` with range / `in` clauses in one call is
|
|
357
|
+
* the canonical "mixed equality + range" pattern.
|
|
358
|
+
*/
|
|
359
|
+
eq<K extends Path<T>>(field: K, value: PathValue<T, K>): PredicateBuilder<T>;
|
|
360
|
+
/**
|
|
361
|
+
* Strict greater. `value` must be `string` or `number`; the
|
|
362
|
+
* intersection at the type level rejects `boolean` / `null`
|
|
363
|
+
* fields at the call site (`q.gt("done", true)` is a TS error
|
|
364
|
+
* on a `done: boolean` field).
|
|
365
|
+
*/
|
|
366
|
+
gt<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;
|
|
367
|
+
/** Inclusive greater. See {@link gt} for the value-type constraint. */
|
|
368
|
+
gte<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;
|
|
369
|
+
/** Strict less. See {@link gt} for the value-type constraint. */
|
|
370
|
+
lt<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;
|
|
371
|
+
/** Inclusive less. See {@link gt} for the value-type constraint. */
|
|
372
|
+
lte<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;
|
|
373
|
+
/**
|
|
374
|
+
* Set membership. Empty array is `UnsatisfiablePredicate` at
|
|
375
|
+
* normalise time — the validator emits the error eagerly so the
|
|
376
|
+
* caller sees it at the `.where(...)` call site, not later.
|
|
377
|
+
*/
|
|
378
|
+
in<K extends Path<T>>(field: K, values: ReadonlyArray<PathValue<T, K>>): PredicateBuilder<T>;
|
|
379
|
+
}
|
|
380
|
+
/**
|
|
381
|
+
* Argument shape accepted by `.where(...)`. Either the object-literal
|
|
382
|
+
* equality form ({@link Predicate}) or a callback that drives a
|
|
383
|
+
* {@link PredicateBuilder} and returns it (the chain terminator).
|
|
384
|
+
*/
|
|
385
|
+
type PredicateArg<T extends DocumentData> = Predicate<T> | ((q: PredicateBuilder<T>) => PredicateBuilder<T>);
|
|
386
|
+
/**
|
|
387
|
+
* Handle on one collection. The common single-row case lives
|
|
388
|
+
* here as direct verbs (`get(id)`, `update(id, patch)`,
|
|
389
|
+
* `replace(id, doc)`, `delete(id)`) plus whole-collection reads
|
|
390
|
+
* (`first()`, `all()`, `count()`). For bulk-by-predicate mutation —
|
|
391
|
+
* or for chained `.where()` / `.order()` / `.limit()` reads — call
|
|
392
|
+
* the modifier verbs to get a {@link Query} back.
|
|
393
|
+
*
|
|
394
|
+
* @template T — the document shape. Documents always carry an
|
|
395
|
+
* auto-generated `_id` (UUIDv7); the type system
|
|
396
|
+
* treats `_id` as optional on `insert` (server fills
|
|
397
|
+
* it in) and required on read.
|
|
398
|
+
*/
|
|
399
|
+
interface Collection<T extends DocumentData = DocumentData> {
|
|
400
|
+
readonly name: string;
|
|
401
|
+
/**
|
|
402
|
+
* First document in the whole collection or `undefined` when the
|
|
403
|
+
* collection is empty. Equivalent to `.where({}).first()`.
|
|
404
|
+
*
|
|
405
|
+
* @example
|
|
406
|
+
* ```ts
|
|
407
|
+
* const any = await db.collection("tickets").first();
|
|
408
|
+
* ```
|
|
409
|
+
*/
|
|
410
|
+
first(): Promise<(T & {
|
|
411
|
+
_id: string;
|
|
412
|
+
}) | undefined>;
|
|
413
|
+
/**
|
|
414
|
+
* Every document in the whole collection. Equivalent to
|
|
415
|
+
* `.where({}).all()`. No implicit cap — prefer
|
|
416
|
+
* `.where(p).limit(n).all()` on large collections.
|
|
417
|
+
*
|
|
418
|
+
* @example
|
|
419
|
+
* ```ts
|
|
420
|
+
* const all = await db.collection("tickets").all();
|
|
421
|
+
* ```
|
|
422
|
+
*/
|
|
423
|
+
all(): Promise<(T & {
|
|
424
|
+
_id: string;
|
|
425
|
+
})[]>;
|
|
426
|
+
/**
|
|
427
|
+
* Count every row in the collection (equivalent to `.where({}).count()`).
|
|
428
|
+
*
|
|
429
|
+
* @example
|
|
430
|
+
* ```ts
|
|
431
|
+
* const total = await db.collection("tickets").count();
|
|
432
|
+
* ```
|
|
433
|
+
*/
|
|
434
|
+
count(): Promise<number>;
|
|
435
|
+
/**
|
|
436
|
+
* Fetch one document by primary key. Returns `undefined` when the
|
|
437
|
+
* id is unknown — does not throw `NotFound`.
|
|
438
|
+
*
|
|
439
|
+
* `id` need not be NFC, so a row an earlier release stored under a
|
|
440
|
+
* non-NFC id stays readable.
|
|
441
|
+
*
|
|
442
|
+
* @throws BaerlyError{code: "InvalidConfig"} — `id` is not a valid
|
|
443
|
+
* `_id`: empty, over 256 UTF-8 bytes, containing `/` or a
|
|
444
|
+
* control character, a leading `_`, or `.` / `..` (HTTP 400).
|
|
445
|
+
* No row can be stored under such an id; nothing was read.
|
|
446
|
+
*
|
|
447
|
+
* @example
|
|
448
|
+
* ```ts
|
|
449
|
+
* const ticket = await db.collection("tickets").get(id);
|
|
450
|
+
* if (ticket === undefined) {
|
|
451
|
+
* // row not in this collection
|
|
452
|
+
* }
|
|
453
|
+
* ```
|
|
454
|
+
*/
|
|
455
|
+
get(id: string): Promise<(T & {
|
|
456
|
+
_id: string;
|
|
457
|
+
}) | undefined>;
|
|
458
|
+
/**
|
|
459
|
+
* Filter rows. Two shapes:
|
|
460
|
+
*
|
|
461
|
+
* - **Object literal** — equality only. Top-level, dotted-path,
|
|
462
|
+
* or nested-literal sub-predicate.
|
|
463
|
+
* - **Callback DSL** — `q => q.eq(...).gt(...).in(...)`. The
|
|
464
|
+
* operator vocabulary (`eq` / `gt` / `gte` / `lt` / `lte` /
|
|
465
|
+
* `in`) lives here. Chained calls AND-merge inside one
|
|
466
|
+
* callback; chained `.where(...).where(...)` AND-merges
|
|
467
|
+
* across calls and across shapes.
|
|
468
|
+
*
|
|
469
|
+
* Operator vocabulary is locked to {@link PredicateBuilder}'s
|
|
470
|
+
* method list; invoking anything else is a TS compile error.
|
|
471
|
+
*
|
|
472
|
+
* @example
|
|
473
|
+
* ```ts
|
|
474
|
+
* db.collection("tickets").where({ status: "open" }).all();
|
|
475
|
+
* db.collection("tickets").where({ "assignee.team": "platform" }).all();
|
|
476
|
+
* db.collection("tickets").where(q => q.gte("count", 1).lt("count", 10)).all();
|
|
477
|
+
* db.collection("tickets").where(q => q.in("status", ["open", "pending"])).all();
|
|
478
|
+
* db.collection("tickets")
|
|
479
|
+
* .where({ status: "open" })
|
|
480
|
+
* .where(q => q.gte("priority", 5))
|
|
481
|
+
* .all();
|
|
482
|
+
* ```
|
|
483
|
+
*/
|
|
484
|
+
where(predicate: PredicateArg<T>): Query<T>;
|
|
485
|
+
/** Order modifier; last call wins. */
|
|
486
|
+
order(spec: OrderSpec<T>): Query<T>;
|
|
487
|
+
/** Limit modifier; last call wins. */
|
|
488
|
+
limit(n: number): Query<T>;
|
|
489
|
+
/**
|
|
490
|
+
* Insert a new document. UUIDv7 auto-id when `_id` is absent,
|
|
491
|
+
* `undefined` or `""`; caller can supply `_id` and the server honours
|
|
492
|
+
* it. Returns the new id.
|
|
493
|
+
*
|
|
494
|
+
* A supplied `_id` must be a string; any other present value (`null`,
|
|
495
|
+
* a number, a boolean, an object) throws rather than being replaced
|
|
496
|
+
* by a generated id. A non-empty one must be of at most 256 UTF-8
|
|
497
|
+
* bytes with no `/`, no control characters, no leading `_`, not `.` or
|
|
498
|
+
* `..`, with no unpaired UTF-16 surrogate (`id.isWellFormed()`), and
|
|
499
|
+
* in Unicode Normalization Form C
|
|
500
|
+
* (`id === id.normalize("NFC")`). Ids that differ only by case are
|
|
501
|
+
* distinct.
|
|
502
|
+
*
|
|
503
|
+
* @throws BaerlyError{code: "InvalidConfig"} — the supplied `_id`
|
|
504
|
+
* is not a string or breaks one of those rules; nothing was
|
|
505
|
+
* written. Pass `id.normalize("NFC")` for a non-NFC id.
|
|
506
|
+
* @throws BaerlyError{code: "InvalidConfig"} — the document, with its
|
|
507
|
+
* `_id`, encodes to more than 1 MiB (1,048,576 bytes) of JSON;
|
|
508
|
+
* nothing was written. Split large or growing data into rows
|
|
509
|
+
* of their own.
|
|
510
|
+
* @throws BaerlyError{code: "SchemaError"} — the document nests
|
|
511
|
+
* deeper than 100 levels (each object or array is a level, the
|
|
512
|
+
* document itself included); nothing was written.
|
|
513
|
+
* @throws BaerlyError{code: "AlreadyExists"} — caller-supplied `_id`
|
|
514
|
+
* is held by a live row, including one a concurrent insert
|
|
515
|
+
* committed first: of concurrent inserts of one `_id`, exactly
|
|
516
|
+
* one commits and the others throw this, committing nothing.
|
|
517
|
+
* Not retriable: insert under another `_id`, omit `_id`, or use
|
|
518
|
+
* `update` / `replace`.
|
|
519
|
+
* @throws BaerlyError{code: "WriteConflict"} — concurrent write won
|
|
520
|
+
* the CAS race and this commit did not land. Retriable.
|
|
521
|
+
* @throws BaerlyError{code: "AmbiguousCommit"} — a committing
|
|
522
|
+
* create may be durable, but its outcome could not be
|
|
523
|
+
* resolved, so the row may or may not have been inserted.
|
|
524
|
+
* `err._id` is the row's id, minted or supplied: re-read it
|
|
525
|
+
* (absence is not proof of failure), and retry with that same
|
|
526
|
+
* `_id` so a retry cannot mint a second document.
|
|
527
|
+
* Not retriable-by-default; handle the code explicitly.
|
|
528
|
+
* @throws BaerlyError{code: "CapacityExceeded"} — the collection is
|
|
529
|
+
* at the serving host's fold ceiling and this write would
|
|
530
|
+
* grow it (or no fold can make progress on this host); nothing
|
|
531
|
+
* was committed. Not retriable unchanged; see RECIPES.md.
|
|
532
|
+
* @throws BaerlyError{code: "MaintenancePending"} — maintenance is behind
|
|
533
|
+
* on this collection; nothing was committed. Retriable: wait
|
|
534
|
+
* `err.retryAfter` seconds, then repeat the call.
|
|
535
|
+
* @throws BaerlyError{code: "SchemaError"} — malformed JSON, or
|
|
536
|
+
* schema-validation failure (when a schema is declared
|
|
537
|
+
* for the collection via `Db.create({ collections })`).
|
|
538
|
+
*
|
|
539
|
+
* @example
|
|
540
|
+
* ```ts
|
|
541
|
+
* const { _id } = await db.collection("tickets").insert({
|
|
542
|
+
* status: "open",
|
|
543
|
+
* title: "Ship the docs",
|
|
544
|
+
* });
|
|
545
|
+
* ```
|
|
546
|
+
*/
|
|
547
|
+
insert(doc: Partial<T> & DocumentData & {
|
|
548
|
+
_id?: string;
|
|
549
|
+
}): Promise<{
|
|
550
|
+
_id: string;
|
|
551
|
+
}>;
|
|
552
|
+
/**
|
|
553
|
+
* JSON-merge-patch (RFC 7386) applied to one row by primary key.
|
|
554
|
+
* `null` deletes an optional field; a required field is removed with
|
|
555
|
+
* `replace` (see {@link MergePatch}). For predicate-aware bulk
|
|
556
|
+
* mutation, use `.where(predicate).update(patch)` on {@link Query}.
|
|
557
|
+
*
|
|
558
|
+
* Returns `{ modified: 0 }` when no row exists at `id` (over HTTP,
|
|
559
|
+
* `404 NotFound`).
|
|
560
|
+
*
|
|
561
|
+
* **Concurrent writes to the row.** The patch is applied to the row's
|
|
562
|
+
* newest committed version, not to the version this call read: if
|
|
563
|
+
* another write to `id` commits between the read and this commit, the
|
|
564
|
+
* patch is re-applied on top of it, so neither write's fields are lost.
|
|
565
|
+
* If the row was deleted in between, nothing is committed and the call
|
|
566
|
+
* returns `{ modified: 0 }` (even if the `_id` was inserted again
|
|
567
|
+
* since: that is a new row this call never read). No error is thrown
|
|
568
|
+
* for either race (PostgreSQL READ COMMITTED semantics).
|
|
569
|
+
*
|
|
570
|
+
* @throws BaerlyError{code: "WriteConflict"} — part of the log this
|
|
571
|
+
* commit had to check was retired by maintenance before it
|
|
572
|
+
* could be read, or a storage precondition was rejected;
|
|
573
|
+
* nothing was committed. Retriable: re-run the call.
|
|
574
|
+
* @throws BaerlyError{code: "AmbiguousCommit"} — a committing
|
|
575
|
+
* create may be durable, but its outcome could not be
|
|
576
|
+
* resolved, so the update may or may not have been applied.
|
|
577
|
+
* Re-read by `id` (also `err._id`); absence is not proof of failure.
|
|
578
|
+
* Not retriable-by-default; handle the code explicitly.
|
|
579
|
+
* @throws BaerlyError{code: "CapacityExceeded"} — the collection is
|
|
580
|
+
* at the serving host's fold ceiling and this write would
|
|
581
|
+
* grow it (or no fold can make progress on this host); nothing
|
|
582
|
+
* was committed. Not retriable unchanged; see RECIPES.md.
|
|
583
|
+
* @throws BaerlyError{code: "MaintenancePending"} — maintenance is behind
|
|
584
|
+
* on this collection; nothing was committed. Retriable: wait
|
|
585
|
+
* `err.retryAfter` seconds, then repeat the call.
|
|
586
|
+
* @throws BaerlyError{code: "SchemaError"} — patch produced an
|
|
587
|
+
* invalid doc.
|
|
588
|
+
* @throws BaerlyError{code: "InvalidConfig"} — the patch's
|
|
589
|
+
* top-level `_id` is present and is not the row's `_id`
|
|
590
|
+
* (`null` included). A patch cannot re-key or strip a row;
|
|
591
|
+
* omit `_id`, or pass the row's own `_id`. Also thrown when
|
|
592
|
+
* the row's `_id` is not NFC or holds an unpaired UTF-16
|
|
593
|
+
* surrogate (stored by an earlier release): such a row can be
|
|
594
|
+
* read and deleted but not updated. Insert a
|
|
595
|
+
* copy under a fresh NFC id that is not canonically equivalent
|
|
596
|
+
* to the original (for example, omit `_id` for a UUID), then
|
|
597
|
+
* delete the original.
|
|
598
|
+
* @throws BaerlyError{code: "InvalidConfig"} — the merged row would
|
|
599
|
+
* encode to more than 1 MiB of JSON; nothing was committed. A
|
|
600
|
+
* row already stored larger (by an earlier release) can still
|
|
601
|
+
* be read, deleted, or updated down under the cap.
|
|
602
|
+
* @throws BaerlyError{code: "SchemaError"} — the patch or the merged
|
|
603
|
+
* row nests deeper than 100 levels; nothing was committed. A
|
|
604
|
+
* row already stored deeper can still be read, deleted, or
|
|
605
|
+
* updated down under the limit.
|
|
606
|
+
* @throws BaerlyError{code: "InvalidResponse"} — the stored row's
|
|
607
|
+
* `_id` is not the string `id`. Repair it with
|
|
608
|
+
* `replace(id, doc)`.
|
|
609
|
+
*
|
|
610
|
+
* @example
|
|
611
|
+
* ```ts
|
|
612
|
+
* const { modified } = await db.collection("tickets")
|
|
613
|
+
* .update(id, { status: "closed", note: null }); // `null` deletes `note`
|
|
614
|
+
* ```
|
|
615
|
+
*/
|
|
616
|
+
update(id: string, patch: MergePatch<T>): Promise<{
|
|
617
|
+
modified: number;
|
|
618
|
+
}>;
|
|
619
|
+
/**
|
|
620
|
+
* Whole-document replace on one row by primary key. Throws
|
|
621
|
+
* `BaerlyError{code:"NotFound"}` when no row exists at `id`.
|
|
622
|
+
*
|
|
623
|
+
* **Concurrent writes to the row.** Last writer wins: an update that
|
|
624
|
+
* commits between this call's read and its commit is overwritten by
|
|
625
|
+
* `doc`. A delete that commits there is not undone: nothing is
|
|
626
|
+
* committed and the call throws `NotFound`.
|
|
627
|
+
*
|
|
628
|
+
* @throws BaerlyError{code: "NotFound"} — no row exists at `id`,
|
|
629
|
+
* including one a concurrent delete removed after this call
|
|
630
|
+
* read it. Nothing was committed.
|
|
631
|
+
* @throws BaerlyError{code: "WriteConflict"} — part of the log this
|
|
632
|
+
* commit had to check was retired by maintenance before it
|
|
633
|
+
* could be read, or a storage precondition was rejected;
|
|
634
|
+
* nothing was committed. Retriable: re-run the call.
|
|
635
|
+
* @throws BaerlyError{code: "AmbiguousCommit"} — a committing
|
|
636
|
+
* create may be durable, but its outcome could not be
|
|
637
|
+
* resolved, so the replace may or may not have been applied.
|
|
638
|
+
* Re-read by `id` (also `err._id`); absence is not proof of failure.
|
|
639
|
+
* Not retriable-by-default; handle the code explicitly.
|
|
640
|
+
* @throws BaerlyError{code: "CapacityExceeded"} — the collection is
|
|
641
|
+
* at the serving host's fold ceiling and this write would
|
|
642
|
+
* grow it (or no fold can make progress on this host); nothing
|
|
643
|
+
* was committed. Not retriable unchanged; see RECIPES.md.
|
|
644
|
+
* @throws BaerlyError{code: "MaintenancePending"} — maintenance is behind
|
|
645
|
+
* on this collection; nothing was committed. Retriable: wait
|
|
646
|
+
* `err.retryAfter` seconds, then repeat the call.
|
|
647
|
+
* @throws BaerlyError{code: "InvalidConfig"} — `id` breaks the `_id`
|
|
648
|
+
* rules on {@link Collection.insert}, including NFC and
|
|
649
|
+
* well-formed UTF-16; nothing
|
|
650
|
+
* was written.
|
|
651
|
+
* @throws BaerlyError{code: "InvalidConfig"} — `doc`, with `_id: id`,
|
|
652
|
+
* encodes to more than 1 MiB of JSON; nothing was written.
|
|
653
|
+
* @throws BaerlyError{code: "SchemaError"} — `doc` nests deeper than
|
|
654
|
+
* 100 levels; nothing was written.
|
|
655
|
+
*
|
|
656
|
+
* @example
|
|
657
|
+
* ```ts
|
|
658
|
+
* await db.collection("tickets")
|
|
659
|
+
* .replace(id, { _id: id, status: "open", title: "Rewrite" });
|
|
660
|
+
* ```
|
|
661
|
+
*/
|
|
662
|
+
replace(id: string, doc: T): Promise<void>;
|
|
663
|
+
/**
|
|
664
|
+
* Delete one row by primary key. Returns `{ deleted: 0 }` when the
|
|
665
|
+
* id is unknown rather than throwing. For predicate-aware bulk
|
|
666
|
+
* delete, use `.where(predicate).delete()` on {@link Query}. `id`
|
|
667
|
+
* need not be NFC, so a row stored under a non-NFC id by an earlier
|
|
668
|
+
* release can still be deleted.
|
|
669
|
+
*
|
|
670
|
+
* **Concurrent writes to the row.** A delete applies to the row this
|
|
671
|
+
* call read. If that row was deleted between the read and this commit
|
|
672
|
+
* (by a racing delete, even if its `_id` was inserted again since),
|
|
673
|
+
* nothing is committed and the call returns `{ deleted: 0 }`, so of two
|
|
674
|
+
* racing deletes one reports `1` and the other `0`. A concurrent update
|
|
675
|
+
* does not stop it: the row is deleted.
|
|
676
|
+
*
|
|
677
|
+
* @throws BaerlyError{code: "WriteConflict"} — part of the log this
|
|
678
|
+
* commit had to check was retired by maintenance before it
|
|
679
|
+
* could be read, or a storage precondition was rejected;
|
|
680
|
+
* nothing was committed. Retriable: re-run the call.
|
|
681
|
+
* @throws BaerlyError{code: "AmbiguousCommit"} — a committing
|
|
682
|
+
* create may be durable, but its outcome could not be
|
|
683
|
+
* resolved, so the tombstone may or may not have been
|
|
684
|
+
* applied. Re-read by `id` (also `err._id`); absence is not
|
|
685
|
+
* proof of failure. Not retriable-by-default; handle the code
|
|
686
|
+
* explicitly.
|
|
687
|
+
* @throws BaerlyError{code: "CapacityExceeded"} — the collection is
|
|
688
|
+
* at the serving host's fold ceiling and this write would
|
|
689
|
+
* grow it (or no fold can make progress on this host); nothing
|
|
690
|
+
* was committed. Not retriable unchanged; see RECIPES.md.
|
|
691
|
+
* @throws BaerlyError{code: "InvalidResponse"} — the stored row's
|
|
692
|
+
* `_id` is not the string `id` (left by an older release
|
|
693
|
+
* that let a patch strip or re-key `_id`). Repair it with
|
|
694
|
+
* `replace(id, doc)`.
|
|
695
|
+
*
|
|
696
|
+
* @example
|
|
697
|
+
* ```ts
|
|
698
|
+
* const { deleted } = await db.collection("tickets").delete(id);
|
|
699
|
+
* ```
|
|
700
|
+
*/
|
|
701
|
+
delete(id: string): Promise<{
|
|
702
|
+
deleted: number;
|
|
703
|
+
}>;
|
|
704
|
+
}
|
|
705
|
+
/**
|
|
706
|
+
* Decrementing depth markers for {@link Path}'s recursion cap.
|
|
707
|
+
* The default of 4 means dotted paths up to `a.b.c.d.e` are legal;
|
|
708
|
+
* `a.b.c.d.e.f` is rejected. Keeps `tsc` recursion bounded.
|
|
709
|
+
* @internal
|
|
710
|
+
*/
|
|
711
|
+
type _PathDepth = [never, 0, 1, 2, 3, 4];
|
|
712
|
+
/**
|
|
713
|
+
* True when `V` is a value position that should terminate {@link Path}
|
|
714
|
+
* recursion. Primitives, `null`, and arrays are leaves — we do not
|
|
715
|
+
* descend into array indices via dotted-path keys (the runtime
|
|
716
|
+
* evaluator treats every segment as an object key, so `"tags.0"`
|
|
717
|
+
* would resolve to `arr["0"]`, which works but is poor DX).
|
|
718
|
+
* @internal
|
|
719
|
+
*/
|
|
720
|
+
type _IsPathLeaf<V> = V extends string | number | boolean | null ? true : V extends ReadonlyArray<unknown> ? true : false;
|
|
721
|
+
/**
|
|
722
|
+
* Strip the string index signature from `T` so {@link Path} can
|
|
723
|
+
* iterate over named keys only. Without this, `T = DocumentData &
|
|
724
|
+
* UserShape` (the canonical user-doc shape across the kernel)
|
|
725
|
+
* collapses `keyof T` to `string` and defeats narrowing.
|
|
726
|
+
*
|
|
727
|
+
* The pattern `string extends K ? never : K` is the standard TS
|
|
728
|
+
* idiom: the parameter of a `[k: string]: …` signature has type
|
|
729
|
+
* `string`, so `string extends string` is true for it (excluded);
|
|
730
|
+
* any literal key like `"status"` does not extend `string`
|
|
731
|
+
* (kept).
|
|
732
|
+
* @internal
|
|
733
|
+
*/
|
|
734
|
+
type _StripIndex<T> = { [K in keyof T as string extends K ? never : K]: T[K]; };
|
|
735
|
+
/**
|
|
736
|
+
* Recursively-derived union of every legal dotted-path key over `T`.
|
|
737
|
+
* Depth-capped at 5 segments (`a.b.c.d.e` legal, `a.b.c.d.e.f` not) so
|
|
738
|
+
* the type checker doesn't blow recursion limits on deep schemas.
|
|
739
|
+
*
|
|
740
|
+
* When `T` is just `DocumentData` (the default — no user shape
|
|
741
|
+
* passed), `_StripIndex<T>` is `{}` and `_Keys<T>` is `never`. In
|
|
742
|
+
* that case we fall through to bare `string` keys, preserving
|
|
743
|
+
* today's open-keyed default behavior.
|
|
744
|
+
* @internal
|
|
745
|
+
*/
|
|
746
|
+
type _AllPaths<T, D extends _PathDepth[number] = 4> = [D] extends [never] ? never : T extends object ? keyof _StripIndex<T> & string extends never ? string : { [K in keyof _StripIndex<T> & string]: _IsPathLeaf<NonNullable<T[K]>> extends true ? K : K | `${K}.${_AllPaths<NonNullable<T[K]>, _PathDepth[D]>}`; }[keyof _StripIndex<T> & string] : never;
|
|
747
|
+
/**
|
|
748
|
+
* Legal dotted-path keys over `T`, with the root-level `_id` filtered
|
|
749
|
+
* out so the top-level shape no longer accepts `{ _id: "x" }`. Nested
|
|
750
|
+
* `_id` paths (e.g. `"author._id"`) survive — only the bare `"_id"`
|
|
751
|
+
* head and any literal `"_id.<rest>"` head are excluded (no
|
|
752
|
+
* `_id.<rest>` shape exists today since `_id` is a string leaf, but
|
|
753
|
+
* the template-string guard keeps the contract intact if the doc
|
|
754
|
+
* shape ever changes).
|
|
755
|
+
*
|
|
756
|
+
* When `T = DocumentData` (no user-supplied shape), `_AllPaths<T>`
|
|
757
|
+
* degrades to bare `string` and the `Exclude<>` wrapper leaves that
|
|
758
|
+
* branch unchanged — open-keyed predicates still typecheck.
|
|
759
|
+
* @internal
|
|
760
|
+
*/
|
|
761
|
+
type Path<T, D extends _PathDepth[number] = 4> = Exclude<_AllPaths<T, D>, "_id" | `_id.${string}`>;
|
|
762
|
+
/**
|
|
763
|
+
* Resolves the leaf value type at dotted path `P` through `T`.
|
|
764
|
+
* Paired with {@link Path} to type the value side of
|
|
765
|
+
* {@link Predicate}. `NonNullable` collapses optional intermediate
|
|
766
|
+
* fields so `"a.b"` resolves through `{ a?: { b: number } }`.
|
|
767
|
+
*
|
|
768
|
+
* Falls back to `DocumentValue` when `P` does not resolve to a
|
|
769
|
+
* named key — this only happens when `Path<T> = string` (no user
|
|
770
|
+
* shape), in which case any string is legal and the value side
|
|
771
|
+
* widens to `DocumentValue` to match today's default.
|
|
772
|
+
* @internal
|
|
773
|
+
*/
|
|
774
|
+
type PathValue<T, P extends string> = P extends `${infer H}.${infer R}` ? H extends keyof T ? PathValue<NonNullable<T[H]>, R> : never : P extends keyof T ? T[P] : DocumentValue;
|
|
775
|
+
/**
|
|
776
|
+
* Recursive partial sub-predicate. The value side of a nested
|
|
777
|
+
* predicate clause: every nested key is optional, and recurses into
|
|
778
|
+
* objects. `_SubPredicate<{a: number, b: {c: string}}>` admits
|
|
779
|
+
* `{a: 1}`, `{b: {c: "x"}}`, and `{a: 1, b: {c: "x"}}` — the same
|
|
780
|
+
* open-world matching the matcher delivers at the wire level
|
|
781
|
+
* (`{ assignee: { team: "x" } }` matches docs where
|
|
782
|
+
* `assignee.team === "x"`, ignoring other keys on `assignee`).
|
|
783
|
+
*
|
|
784
|
+
* Recurses over `keyof T` directly (NOT through `Path<T>`) so the
|
|
785
|
+
* root-level `_id` exclusion does not propagate — a nested `_id`
|
|
786
|
+
* names the primary key of an embedded reference and remains
|
|
787
|
+
* queryable (`.where({ author: { _id: "u1" } })` typechecks).
|
|
788
|
+
* @internal
|
|
789
|
+
*/
|
|
790
|
+
type _SubPredicate<T> = T extends object ? T extends ReadonlyArray<unknown> ? never : { readonly [K in keyof _StripIndex<T> & string]?: T[K] | _SubPredicate<T[K]>; } : never;
|
|
791
|
+
/**
|
|
792
|
+
* Equality-only predicate over a document shape. Object-form
|
|
793
|
+
* accepts:
|
|
794
|
+
*
|
|
795
|
+
* - top-level equality: `{ status: "open" }`
|
|
796
|
+
* - dotted-path equality: `{ "assignee.team": "platform" }`
|
|
797
|
+
* - nested literal sub-predicates: `{ assignee: { team: "platform" } }`
|
|
798
|
+
* — the normaliser flattens to dotted-path `eq` clauses; the
|
|
799
|
+
* nested object may carry only a subset of keys (open-world
|
|
800
|
+
* matching against the document).
|
|
801
|
+
*
|
|
802
|
+
* **Operators live on the callback form only.** Range / `in` /
|
|
803
|
+
* mixed eq+range queries write
|
|
804
|
+
* `.where(q => q.gt("priority", 5).in("status", ["open", "pending"]))`.
|
|
805
|
+
* That vocabulary lives on {@link PredicateBuilder} (see there for
|
|
806
|
+
* the locked method list); object-form has no `$`-keyed surface, so
|
|
807
|
+
* an operator we never implemented cannot be invoked from either
|
|
808
|
+
* shape. For OR/AND:
|
|
809
|
+
* - `q.in(field, ["a", "b"])` for OR over one field.
|
|
810
|
+
* - Chained `.where(p1).where(p2)` for AND across multiple
|
|
811
|
+
* predicates — the chain AND-merges.
|
|
812
|
+
*
|
|
813
|
+
* **Depth cap.** Dotted paths are limited to 5 segments
|
|
814
|
+
* (`a.b.c.d.e` legal, `a.b.c.d.e.f` not). Real doc-DB schemas rarely
|
|
815
|
+
* exceed 2–3 levels.
|
|
816
|
+
*/
|
|
817
|
+
type Predicate<T extends DocumentData = DocumentData> = { readonly [P in Path<T>]?: PathValue<T, P> extends DocumentValue ? PathValue<T, P> | _SubPredicate<PathValue<T, P>> : DocumentValue; };
|
|
818
|
+
/** Order specifier. Top-level fields only on day one. */
|
|
819
|
+
type OrderSpec<T extends DocumentData = DocumentData> = { readonly [K in keyof T]?: "asc" | "desc"; };
|
|
820
|
+
/**
|
|
821
|
+
* `Collection<T>` after at least one modifier. Carries predicate /
|
|
822
|
+
* order / limit state forward. Modifiers compose; verbs are
|
|
823
|
+
* terminal. Mutation verbs here are **predicate-aware bulk** — they
|
|
824
|
+
* apply to every matching row. For the common single-row case
|
|
825
|
+
* (`{ _id }`), prefer {@link Collection.update} / {@link Collection.replace} /
|
|
826
|
+
* {@link Collection.delete}.
|
|
827
|
+
*/
|
|
828
|
+
interface Query<T extends DocumentData = DocumentData> {
|
|
829
|
+
where(predicate: PredicateArg<T>): Query<T>;
|
|
830
|
+
order(spec: OrderSpec<T>): Query<T>;
|
|
831
|
+
limit(n: number): Query<T>;
|
|
832
|
+
/**
|
|
833
|
+
* First match or `undefined`. Equivalent to `.limit(1).all()[0]`.
|
|
834
|
+
*
|
|
835
|
+
* @example
|
|
836
|
+
* ```ts
|
|
837
|
+
* const oldest = await db.collection("tickets")
|
|
838
|
+
* .where({ status: "open" })
|
|
839
|
+
* .order({ commit_ts: "asc" })
|
|
840
|
+
* .first();
|
|
841
|
+
* ```
|
|
842
|
+
*/
|
|
843
|
+
first(): Promise<(T & {
|
|
844
|
+
_id: string;
|
|
845
|
+
}) | undefined>;
|
|
846
|
+
/**
|
|
847
|
+
* Every matching document, respecting `order` and `limit`. No
|
|
848
|
+
* implicit cap — callers should always pair `.all()` with
|
|
849
|
+
* `.limit(n)` on large collections.
|
|
850
|
+
*
|
|
851
|
+
* @example
|
|
852
|
+
* ```ts
|
|
853
|
+
* const open = await db.collection("tickets")
|
|
854
|
+
* .where({ status: "open" })
|
|
855
|
+
* .order({ commit_ts: "desc" })
|
|
856
|
+
* .limit(50)
|
|
857
|
+
* .all();
|
|
858
|
+
* ```
|
|
859
|
+
*/
|
|
860
|
+
all(): Promise<(T & {
|
|
861
|
+
_id: string;
|
|
862
|
+
})[]>;
|
|
863
|
+
/**
|
|
864
|
+
* Count matching rows. Cheaper than `(await all()).length`.
|
|
865
|
+
*
|
|
866
|
+
* @example
|
|
867
|
+
* ```ts
|
|
868
|
+
* const open = await db.collection("tickets")
|
|
869
|
+
* .where({ status: "open" })
|
|
870
|
+
* .count();
|
|
871
|
+
* ```
|
|
872
|
+
*/
|
|
873
|
+
count(): Promise<number>;
|
|
874
|
+
/**
|
|
875
|
+
* Predicate-aware bulk mutation: JSON-merge-patch (RFC 7386)
|
|
876
|
+
* applied to every matching doc. `null` deletes an optional field;
|
|
877
|
+
* a required field is removed with `replace` (see {@link MergePatch}).
|
|
878
|
+
* For the single-row case prefer {@link Collection.update}(id, patch).
|
|
879
|
+
*
|
|
880
|
+
* Each row commits on its own (there is no multi-row transaction): a
|
|
881
|
+
* failure part-way leaves the rows before it applied. `modified`
|
|
882
|
+
* counts the rows this call committed.
|
|
883
|
+
*
|
|
884
|
+
* **Concurrent writes to a matched row.** Each row's patch is applied
|
|
885
|
+
* to its newest committed version, not to the version this call read.
|
|
886
|
+
* If another write to the row commits between the read and the row's
|
|
887
|
+
* commit, the predicate is evaluated again on that newest version
|
|
888
|
+
* (`order` and `limit` are not): if it still matches, the patch is
|
|
889
|
+
* re-applied on top of it, so neither write's fields are lost; if not,
|
|
890
|
+
* the row is skipped. A row deleted in between is skipped too (even if
|
|
891
|
+
* its `_id` was inserted again since). Skipped rows are not counted in
|
|
892
|
+
* `modified`, and no error is thrown (PostgreSQL READ COMMITTED
|
|
893
|
+
* semantics).
|
|
894
|
+
*
|
|
895
|
+
* @throws BaerlyError{code: "WriteConflict"} — part of the log one
|
|
896
|
+
* row's commit had to check was retired by maintenance before
|
|
897
|
+
* it could be read, or a storage precondition was rejected; that
|
|
898
|
+
* row did not commit. Rows before it may already be applied;
|
|
899
|
+
* re-issuing the call is safe (it re-reads and re-matches).
|
|
900
|
+
* Retriable.
|
|
901
|
+
* @throws BaerlyError{code: "AmbiguousCommit"} — one row's
|
|
902
|
+
* committing create may be durable, but its outcome could
|
|
903
|
+
* not be resolved. Rows before it are already applied; the
|
|
904
|
+
* partial-progress `modified` count is NOT returned. `err._id`
|
|
905
|
+
* names that row; absence is not proof of failure.
|
|
906
|
+
* @throws BaerlyError{code: "CapacityExceeded"} — the collection is
|
|
907
|
+
* at the serving host's fold ceiling and the batch would grow
|
|
908
|
+
* it (or no fold can make progress on this host). Decided for the
|
|
909
|
+
* whole batch before any row commits, and again at a row's commit
|
|
910
|
+
* if a concurrent write landed since; rows before that one are
|
|
911
|
+
* then already applied. Not retriable unchanged; see RECIPES.md.
|
|
912
|
+
* Also thrown when the request runs out of storage calls
|
|
913
|
+
* part-way: rows before the refused one are applied, it and the
|
|
914
|
+
* rows after it are not; re-running the call on a new request is
|
|
915
|
+
* safe (it re-reads and re-matches).
|
|
916
|
+
* @throws BaerlyError{code: "MaintenancePending"} — maintenance is behind
|
|
917
|
+
* on this collection; the refused row and the rows after it were
|
|
918
|
+
* not committed. Retriable: wait `err.retryAfter` seconds, then
|
|
919
|
+
* repeat the call.
|
|
920
|
+
* @throws BaerlyError{code: "SchemaError"} — patch produced an
|
|
921
|
+
* invalid doc, including when re-applied to a row's newest
|
|
922
|
+
* version at its commit (rows before it are then applied), or
|
|
923
|
+
* the patch or a merged row nests deeper than 100 levels.
|
|
924
|
+
* @throws BaerlyError{code: "InvalidConfig"} — the patch's
|
|
925
|
+
* top-level `_id` is present and is not a matched row's
|
|
926
|
+
* `_id` (`null` included), or a matched row's `_id` is not
|
|
927
|
+
* NFC or not well-formed (see {@link Collection.update}). Checked for every
|
|
928
|
+
* matched row before any row commits.
|
|
929
|
+
* @throws BaerlyError{code: "InvalidConfig"} — a matched row's merged
|
|
930
|
+
* post-image would encode to more than 1 MiB of JSON (see
|
|
931
|
+
* {@link Collection.update}). Checked for every matched row
|
|
932
|
+
* before any row commits.
|
|
933
|
+
* @throws BaerlyError{code: "InvalidResponse"} — a matched stored
|
|
934
|
+
* row's `_id` is not the string it is stored under (left by
|
|
935
|
+
* an older release). Checked for every matched row before any
|
|
936
|
+
* row commits. Repair it with `replace(id, doc)`.
|
|
937
|
+
*
|
|
938
|
+
* @example
|
|
939
|
+
* ```ts
|
|
940
|
+
* const { modified } = await db.collection("tickets")
|
|
941
|
+
* .where({ status: "open" })
|
|
942
|
+
* .update({ status: "closed", closed_at: new Date().toISOString() });
|
|
943
|
+
* ```
|
|
944
|
+
*/
|
|
945
|
+
update(patch: MergePatch<T>): Promise<{
|
|
946
|
+
modified: number;
|
|
947
|
+
}>;
|
|
948
|
+
/**
|
|
949
|
+
* Predicate-aware bulk delete: every matching document. For the
|
|
950
|
+
* single-row case prefer {@link Collection.delete}(id).
|
|
951
|
+
*
|
|
952
|
+
* Each row commits on its own; `deleted` counts the rows this call
|
|
953
|
+
* deleted.
|
|
954
|
+
*
|
|
955
|
+
* **Concurrent writes to a matched row.** If another write to a matched
|
|
956
|
+
* row commits between this call's read and the row's commit, the
|
|
957
|
+
* predicate is evaluated again on that newest version (`order` and
|
|
958
|
+
* `limit` are not), and the row is deleted only if it still matches. A
|
|
959
|
+
* row already deleted in between (even if its `_id` was inserted again
|
|
960
|
+
* since) is skipped. Skipped rows are not counted in `deleted`, and no
|
|
961
|
+
* error is thrown (PostgreSQL READ COMMITTED semantics).
|
|
962
|
+
*
|
|
963
|
+
* @throws BaerlyError{code: "WriteConflict"} — part of the log one
|
|
964
|
+
* row's commit had to check was retired by maintenance before
|
|
965
|
+
* it could be read, or a storage precondition was rejected; that
|
|
966
|
+
* row did not commit. Rows before it may already be tombstoned;
|
|
967
|
+
* re-issuing the call is safe (it re-reads and re-matches).
|
|
968
|
+
* Retriable.
|
|
969
|
+
* @throws BaerlyError{code: "AmbiguousCommit"} — one row's
|
|
970
|
+
* committing create may be durable, but its outcome could
|
|
971
|
+
* not be resolved. Rows before it are already tombstoned;
|
|
972
|
+
* the partial-progress `deleted` count is NOT returned.
|
|
973
|
+
* `err._id` names that row; re-read before deciding whether
|
|
974
|
+
* to resume.
|
|
975
|
+
* @throws BaerlyError{code: "CapacityExceeded"} — the collection is
|
|
976
|
+
* at the serving host's fold ceiling and the batch would grow
|
|
977
|
+
* it (or no fold can make progress on this host). Decided for the
|
|
978
|
+
* whole batch before any row commits, and again at a row's commit
|
|
979
|
+
* if a concurrent write landed since; rows before that one are
|
|
980
|
+
* then already applied. Not retriable unchanged; see RECIPES.md.
|
|
981
|
+
* Also thrown when the request runs out of storage calls
|
|
982
|
+
* part-way: rows before the refused one are tombstoned, it and
|
|
983
|
+
* the rows after it are not; re-running the call on a new request
|
|
984
|
+
* is safe.
|
|
985
|
+
* @throws BaerlyError{code: "InvalidResponse"} — a matched stored
|
|
986
|
+
* row's `_id` is not the string it is stored under (left by
|
|
987
|
+
* an older release). Checked for every matched row before any
|
|
988
|
+
* row commits. Repair it with `replace(id, doc)`.
|
|
989
|
+
*
|
|
990
|
+
* @example
|
|
991
|
+
* ```ts
|
|
992
|
+
* const { deleted } = await db.collection("tickets")
|
|
993
|
+
* .where({ status: "closed" })
|
|
994
|
+
* .delete();
|
|
995
|
+
* ```
|
|
996
|
+
*/
|
|
997
|
+
delete(): Promise<{
|
|
998
|
+
deleted: number;
|
|
999
|
+
}>;
|
|
1000
|
+
}
|
|
1001
|
+
export { PredicateArg as a, BaerlyErrorOptions as c, Query as i, OrderSpec as n, BaerlyError as o, Predicate as r, BaerlyErrorCode as s, Collection as t };
|