@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.
Files changed (215) hide show
  1. package/README.md +47 -124
  2. package/dist/API.md +161 -511
  3. package/dist/CHANGELOG.md +1148 -307
  4. package/dist/RECIPES.md +398 -80
  5. package/dist/THIRD-PARTY-LICENSES.txt +5 -26
  6. package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
  7. package/dist/app-config.d.ts +31 -1
  8. package/dist/app-config.js +1 -2
  9. package/dist/app-config.js.map +1 -1
  10. package/dist/auth.d.ts +33 -28
  11. package/dist/auth.js +549 -985
  12. package/dist/auth.js.map +1 -1
  13. package/dist/baerly.js +130 -138
  14. package/dist/baerly.js.map +1 -1
  15. package/dist/baerly.spec.json +97 -22
  16. package/dist/capacity-warning-header-BlVopyiI.js +16 -0
  17. package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
  18. package/dist/{client-Fe8CwB73.d.ts → client-CHQTXpef.d.ts} +121 -36
  19. package/dist/client-react.d.ts +67 -20
  20. package/dist/client-react.js +240 -54
  21. package/dist/client-react.js.map +1 -1
  22. package/dist/client.d.ts +5 -4
  23. package/dist/client.js +51 -16
  24. package/dist/client.js.map +1 -1
  25. package/dist/{cloudflare-DzKBrUlg.js → cloudflare-CKHYXccw.js} +504 -124
  26. package/dist/cloudflare-CKHYXccw.js.map +1 -0
  27. package/dist/cloudflare.d.ts +106 -71
  28. package/dist/cloudflare.js +334 -271
  29. package/dist/cloudflare.js.map +1 -1
  30. package/dist/code-resolution-CL_7L0wS.js +22 -0
  31. package/dist/code-resolution-CL_7L0wS.js.map +1 -0
  32. package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
  33. package/dist/config-DEzInG6M.js +4035 -0
  34. package/dist/config-DEzInG6M.js.map +1 -0
  35. package/dist/constants-D3GSH3tc.js +469 -0
  36. package/dist/constants-D3GSH3tc.js.map +1 -0
  37. package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
  38. package/dist/context-rlpSnHFA.js.map +1 -0
  39. package/dist/cost-B52llVDx.js +330 -0
  40. package/dist/cost-B52llVDx.js.map +1 -0
  41. package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
  42. package/dist/current-json-CC6lE4Aj.js.map +1 -0
  43. package/dist/db-plFUNTSF.d.ts +130 -0
  44. package/dist/db-read-seams-BSs0m1z1.js +3261 -0
  45. package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
  46. package/dist/{deploy-DonTr-CV.js → deploy-Obj4nE-Z.js} +12 -16
  47. package/dist/deploy-Obj4nE-Z.js.map +1 -0
  48. package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
  49. package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
  50. package/dist/dev-landing-CD-si4dW.js +50 -0
  51. package/dist/dev-landing-CD-si4dW.js.map +1 -0
  52. package/dist/dev-vite.d.ts +38 -39
  53. package/dist/dev-vite.js +67 -36
  54. package/dist/dev-vite.js.map +1 -1
  55. package/dist/dev.d.ts +3 -2
  56. package/dist/dev.js +2 -1
  57. package/dist/doctor-BA0i-YAN.js +270 -0
  58. package/dist/doctor-BA0i-YAN.js.map +1 -0
  59. package/dist/dump-D1vX8ozg.js +133 -0
  60. package/dist/dump-D1vX8ozg.js.map +1 -0
  61. package/dist/errors-7Rk1HGCE.js +160 -0
  62. package/dist/errors-7Rk1HGCE.js.map +1 -0
  63. package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
  64. package/dist/export-BVL2EvYE.js.map +1 -0
  65. package/dist/fsck-BWkPgov4.js +145 -0
  66. package/dist/fsck-BWkPgov4.js.map +1 -0
  67. package/dist/gcs-admin-Dso1HWQj.d.ts +127 -0
  68. package/dist/gcs.d.ts +30 -0
  69. package/dist/gcs.js +1 -0
  70. package/dist/goog4-signer-CeLIABoE.js +331 -0
  71. package/dist/goog4-signer-CeLIABoE.js.map +1 -0
  72. package/dist/{http-DGd5tbNs.js → http-Z5rZyYMX.js} +898 -271
  73. package/dist/http-Z5rZyYMX.js.map +1 -0
  74. package/dist/http-transport-DNUM8kU-.js +1299 -0
  75. package/dist/http-transport-DNUM8kU-.js.map +1 -0
  76. package/dist/http.d.ts +366 -294
  77. package/dist/http.js +2 -2
  78. package/dist/index-JJrIu1pO.d.ts +135 -0
  79. package/dist/index-LEgHN0qJ.d.ts +50 -0
  80. package/dist/{index-CuA9Mi3K.d.ts → index-RiEYj8t0.d.ts} +291 -78
  81. package/dist/index.d.ts +27 -6
  82. package/dist/index.js +3 -5
  83. package/dist/inspect-BTsVYZKd.js +196 -0
  84. package/dist/inspect-BTsVYZKd.js.map +1 -0
  85. package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
  86. package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
  87. package/dist/ledger-Dj_bGgo0.js +192 -0
  88. package/dist/ledger-Dj_bGgo0.js.map +1 -0
  89. package/dist/legacy-names-DgZBtgOh.js +47 -0
  90. package/dist/legacy-names-DgZBtgOh.js.map +1 -0
  91. package/dist/log-C9W15Dfo.d.ts +94 -0
  92. package/dist/log-tail-DWJbneBF.js +142 -0
  93. package/dist/log-tail-DWJbneBF.js.map +1 -0
  94. package/dist/log-walk-C-vA-WGJ.js +111 -0
  95. package/dist/log-walk-C-vA-WGJ.js.map +1 -0
  96. package/dist/maintenance-Dd-Yakqj.js +1709 -0
  97. package/dist/maintenance-Dd-Yakqj.js.map +1 -0
  98. package/dist/maintenance-DevB6z4e.js +2237 -0
  99. package/dist/maintenance-DevB6z4e.js.map +1 -0
  100. package/dist/maintenance.d.ts +100 -3
  101. package/dist/maintenance.js +1 -3
  102. package/dist/node.d.ts +130 -142
  103. package/dist/node.js +4 -3
  104. package/dist/{observability-BmflLCdF.js → observability-C-ISCCLE.js} +1275 -332
  105. package/dist/observability-C-ISCCLE.js.map +1 -0
  106. package/dist/observability.d.ts +27 -3
  107. package/dist/observability.js +3 -3
  108. package/dist/path-segment-DBXG26PW.js +363 -0
  109. package/dist/path-segment-DBXG26PW.js.map +1 -0
  110. package/dist/{plan-a7PJHBCy.js → plan-BvQbaNMe.js} +19 -11
  111. package/dist/plan-BvQbaNMe.js.map +1 -0
  112. package/dist/request-CRWiTrza.js +272 -0
  113. package/dist/request-CRWiTrza.js.map +1 -0
  114. package/dist/restore-U6Im8V1V.js +1467 -0
  115. package/dist/restore-U6Im8V1V.js.map +1 -0
  116. package/dist/retry-OBtLB2GC.js +126 -0
  117. package/dist/retry-OBtLB2GC.js.map +1 -0
  118. package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
  119. package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec-B5mg3pHF.js} +189 -28
  120. package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
  121. package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DBC_wiCL.d.ts} +18 -10
  122. package/dist/s3.d.ts +20 -7
  123. package/dist/s3.js +4 -5
  124. package/dist/s3.js.map +1 -1
  125. package/dist/sha256-4FfGQNPw.js +22 -0
  126. package/dist/sha256-4FfGQNPw.js.map +1 -0
  127. package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
  128. package/dist/shared-secret-Vkur-8r0.js.map +1 -0
  129. package/dist/sigv4-sign-5IUflUD_.js +507 -0
  130. package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
  131. package/dist/snapshot-CknzkDM0.js +148 -0
  132. package/dist/snapshot-CknzkDM0.js.map +1 -0
  133. package/dist/{src-BL_JoPTn.js → src-Actga-bO.js} +1004 -378
  134. package/dist/src-Actga-bO.js.map +1 -0
  135. package/dist/src-D0MQfvOp.js +812 -0
  136. package/dist/src-D0MQfvOp.js.map +1 -0
  137. package/dist/src-Dr9uo3dc.js +501 -0
  138. package/dist/src-Dr9uo3dc.js.map +1 -0
  139. package/dist/{subcommand-DoDA-K7d.js → subcommand-BLoF66dG.js} +89 -16
  140. package/dist/subcommand-BLoF66dG.js.map +1 -0
  141. package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
  142. package/dist/time-DRxTP9iv.js.map +1 -0
  143. package/dist/types-suVbsEWS.d.ts +116 -0
  144. package/dist/{usage-DBV1eQHC.js → usage-CPzVhrQr.js} +40 -45
  145. package/dist/usage-CPzVhrQr.js.map +1 -0
  146. package/dist/uuid-BuT_c404.js +333 -0
  147. package/dist/uuid-BuT_c404.js.map +1 -0
  148. package/dist/verifier-Bmlmndzo.d.ts +95 -0
  149. package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
  150. package/dist/wire-DndvKU-K.js.map +1 -0
  151. package/package.json +96 -69
  152. package/dist/aws4fetch.esm-p7eEzLCs.js +0 -1702
  153. package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
  154. package/dist/bytes-BXdamO3L.js +0 -11
  155. package/dist/bytes-BXdamO3L.js.map +0 -1
  156. package/dist/cloudflare-DzKBrUlg.js.map +0 -1
  157. package/dist/config-1tv0-Yzm.js +0 -2693
  158. package/dist/config-1tv0-Yzm.js.map +0 -1
  159. package/dist/constants-CfeMWQWk.js +0 -222
  160. package/dist/constants-CfeMWQWk.js.map +0 -1
  161. package/dist/context-DRZ3tZ5l.js.map +0 -1
  162. package/dist/cost-DSMIVqzL.js +0 -203
  163. package/dist/cost-DSMIVqzL.js.map +0 -1
  164. package/dist/current-json-C6nhPOm1.js.map +0 -1
  165. package/dist/db-DsPkOVEH.d.ts +0 -254
  166. package/dist/deploy-DonTr-CV.js.map +0 -1
  167. package/dist/doctor-DSIyCDg_.js +0 -346
  168. package/dist/doctor-DSIyCDg_.js.map +0 -1
  169. package/dist/dump-Bh5k26VQ.js +0 -94
  170. package/dist/dump-Bh5k26VQ.js.map +0 -1
  171. package/dist/errors-Dfa3p78c.js +0 -78
  172. package/dist/errors-Dfa3p78c.js.map +0 -1
  173. package/dist/export-DtF5tDIM.js +0 -401
  174. package/dist/export-DtF5tDIM.js.map +0 -1
  175. package/dist/fsck-D_djMO5D.js +0 -279
  176. package/dist/fsck-D_djMO5D.js.map +0 -1
  177. package/dist/http-DGd5tbNs.js.map +0 -1
  178. package/dist/index-0rZcMBwy.d.ts +0 -115
  179. package/dist/index-BNRh23K9.d.ts +0 -162
  180. package/dist/index-BYk9oCNf.d.ts +0 -1112
  181. package/dist/indexes-Dn9hbGQG.d.ts +0 -22
  182. package/dist/inspect-6WZ-pC7-.js +0 -133
  183. package/dist/inspect-6WZ-pC7-.js.map +0 -1
  184. package/dist/log-tail-D98U1JBo.js +0 -522
  185. package/dist/log-tail-D98U1JBo.js.map +0 -1
  186. package/dist/maintenance-B4Dki6Ig.js +0 -2157
  187. package/dist/maintenance-B4Dki6Ig.js.map +0 -1
  188. package/dist/maintenance-B_e0T99L.d.ts +0 -537
  189. package/dist/maintenance-C7coQp4c.js +0 -1418
  190. package/dist/maintenance-C7coQp4c.js.map +0 -1
  191. package/dist/normalize-rjnZLwS4.js +0 -133
  192. package/dist/normalize-rjnZLwS4.js.map +0 -1
  193. package/dist/observability-BmflLCdF.js.map +0 -1
  194. package/dist/plan-a7PJHBCy.js.map +0 -1
  195. package/dist/query-rAtXNQQB.js +0 -1773
  196. package/dist/query-rAtXNQQB.js.map +0 -1
  197. package/dist/rebuild-index-BVzQSZlm.js +0 -81
  198. package/dist/rebuild-index-BVzQSZlm.js.map +0 -1
  199. package/dist/request-u0M51mhJ.js +0 -72
  200. package/dist/request-u0M51mhJ.js.map +0 -1
  201. package/dist/restore-R-4rbciV.js +0 -778
  202. package/dist/restore-R-4rbciV.js.map +0 -1
  203. package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
  204. package/dist/runtime-spec-Dsw2-n8S.js.map +0 -1
  205. package/dist/shared-secret-DgEicd3x.js.map +0 -1
  206. package/dist/src-BL_JoPTn.js.map +0 -1
  207. package/dist/src-CYHFDrKz.js +0 -536
  208. package/dist/src-CYHFDrKz.js.map +0 -1
  209. package/dist/src-DYZ4H1aF.js +0 -392
  210. package/dist/src-DYZ4H1aF.js.map +0 -1
  211. package/dist/subcommand-DoDA-K7d.js.map +0 -1
  212. package/dist/time-DUqvFMHq.js.map +0 -1
  213. package/dist/usage-DBV1eQHC.js.map +0 -1
  214. package/dist/validate-DtljsCh1.js.map +0 -1
  215. package/dist/wire-izfGZDvr.js.map +0 -1
@@ -1,14 +1,45 @@
1
- import { a as CollectionNames, f as DocumentData, o as RowOf, r as BaerlyConfig, s as UnboundConfig } from "./app-config-DyiFK3_k.js";
2
- import { s as OrderSpec, u as PredicateArg } from "./index-BYk9oCNf.js";
3
-
4
- //#region packages/client/src/request.d.ts
1
+ import { a as CollectionNames, f as DocumentData, h as MergePatch, o as RowOf, r as BaerlyConfig, s as UnboundConfig } from "./app-config-C6qW7m8S.js";
2
+ import { a as PredicateArg, n as OrderSpec } from "./collection-api-DbyhLAY8.js";
5
3
  /**
6
4
  * Pluggable fetch implementation. Defaults to `globalThis.fetch`;
7
5
  * tests override with a {@link MockFetch}.
8
6
  */
9
7
  type Fetcher = (req: Request) => Promise<Response>;
10
- //#endregion
11
- //#region packages/client/src/client.d.ts
8
+ /**
9
+ * A warning the server attached to a successful response, passed to
10
+ * `BaerlyClientOptions.onWarning`. The request itself succeeded and its
11
+ * result is unchanged.
12
+ *
13
+ * `code` is the kind of warning. `"CapacityWarning"` (the
14
+ * `Baerly-Capacity-Warning` response header) means the write was
15
+ * committed but left its collection at 90% or more of what the host can
16
+ * hold, so inserts and growing updates will soon be refused with
17
+ * `CapacityExceeded`; `message` is the server's text, naming the state
18
+ * and the app-side remedy.
19
+ */
20
+ interface BaerlyWarning {
21
+ readonly code: "CapacityWarning";
22
+ /** The server's warning text, verbatim. */
23
+ readonly message: string;
24
+ /** The request that drew the warning. */
25
+ readonly method: RequestOptions["method"];
26
+ /** The request path, e.g. `/v1/c/tickets`. */
27
+ readonly path: string;
28
+ }
29
+ interface RequestOptions {
30
+ readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
31
+ readonly path: string;
32
+ readonly body?: unknown;
33
+ readonly signal?: AbortSignal;
34
+ /** `false` makes the request single-attempt, for callers that own their own retry loop. */
35
+ readonly retry?: false;
36
+ /**
37
+ * Marks a `POST` insert whose `_id` the SDK minted and sent as `mintedId`
38
+ * (E2). Only such a request may be resent after a transport failure: if the
39
+ * first attempt had committed, the server replays its `201 { _id }`.
40
+ */
41
+ readonly mintedInsert?: true;
42
+ }
12
43
  /**
13
44
  * Public options for {@link createBaerlyClient}.
14
45
  *
@@ -28,11 +59,15 @@ interface BaerlyClientOptions<TConfig extends BaerlyConfig = UnboundConfig> {
28
59
  readonly baseUrl: string;
29
60
  /**
30
61
  * Optional. Defaults to `globalThis.fetch`. Wrap your own to add
31
- * logging, retries, tracing, or auth-refresh — the entire client
32
- * routes every request through this one function. This is the
62
+ * logging, tracing, or auth-refresh — the entire client routes every
63
+ * request through this one function, once per attempt. This is the
33
64
  * `link` middleware story (tRPC) and the `interceptor` story
34
65
  * (axios) without new API surface.
35
66
  *
67
+ * Don't add retries here: the client already retries `GET`s and
68
+ * auto-ID inserts on transport failures, and every verb on
69
+ * `MaintenancePending`, so a retrying wrapper multiplies attempts.
70
+ *
36
71
  * @example
37
72
  * ```ts
38
73
  * // Log every request + response.
@@ -43,34 +78,48 @@ interface BaerlyClientOptions<TConfig extends BaerlyConfig = UnboundConfig> {
43
78
  * return res;
44
79
  * };
45
80
  *
46
- * // Retry idempotent reads on 5xx (max 3 total attempts, 100ms backoff).
47
- * const withRetry = (next: Fetcher): Fetcher => async (req) => {
48
- * for (let i = 0; i < 2; i++) {
49
- * const res = await next(req.clone());
50
- * if (res.ok || res.status < 500 || req.method !== "GET") return res;
51
- * await new Promise((r) => setTimeout(r, 100 * (i + 1)));
52
- * }
53
- * return next(req);
54
- * };
55
- *
56
81
  * const client = createBaerlyClient({
57
82
  * baseUrl: "https://api.example.com",
58
- * fetch: withRetry(withLogging),
83
+ * fetch: withLogging,
59
84
  * });
60
85
  * ```
61
86
  *
62
- * See `dist/API.md` → "Recipe — wrapping the client `fetch`"
63
- * for `onSuccess` / `onError` helpers and a composition pattern.
87
+ * See `dist/RECIPES.md` → "Recipe — wrapping the client `fetch`"
88
+ * for `onSuccess` / `onError` hooks, 401 auth refresh, and
89
+ * composition order.
64
90
  */
65
91
  readonly fetch?: Fetcher;
66
92
  /**
67
93
  * Optional. Forwarded on every request. Typically
68
94
  * `{ Authorization: "Bearer <token>" }`. For credential refresh
69
95
  * (fresh JWT per call, 401-driven re-issue, etc.) wrap
70
- * {@link BaerlyClientOptions.fetch} instead — see the retry +
71
- * logging examples above.
96
+ * {@link BaerlyClientOptions.fetch} instead — see the logging
97
+ * example above.
72
98
  */
73
99
  readonly headers?: Headers | Record<string, string>;
100
+ /**
101
+ * Optional. Called once for each successful response that carries a
102
+ * server warning; see {@link BaerlyWarning}. Today that is the
103
+ * capacity warning: a write that committed but left its collection at
104
+ * 90% or more of what the host can hold, so inserts and growing
105
+ * updates will soon be refused with `CapacityExceeded`. The write's
106
+ * own result is unchanged, and a callback that throws (or returns a
107
+ * rejected promise) cannot fail it. Without this option warnings are
108
+ * dropped.
109
+ *
110
+ * Cross-origin browser apps also need the server's CORS layer to list
111
+ * `Baerly-Capacity-Warning` in `Access-Control-Expose-Headers`, or the
112
+ * browser hides the header from the client.
113
+ *
114
+ * @example
115
+ * ```ts
116
+ * const client = createBaerlyClient({
117
+ * baseUrl: "https://api.example.com",
118
+ * onWarning: (w) => console.warn(`${w.method} ${w.path}: ${w.message}`),
119
+ * });
120
+ * ```
121
+ */
122
+ readonly onWarning?: (warning: BaerlyWarning) => void;
74
123
  /**
75
124
  * Optional. **Type-only** — the runtime client does not read this
76
125
  * field; it exists so `client.collection(name)` can narrow `name` to
@@ -129,13 +178,19 @@ interface TerminalOptions {
129
178
  interface ClientCollection<T extends DocumentData = DocumentData> {
130
179
  readonly name: string;
131
180
  /** First document in the whole collection or `undefined`. */
132
- first(opts?: TerminalOptions): Promise<T | undefined>;
181
+ first(opts?: TerminalOptions): Promise<(T & {
182
+ _id: string;
183
+ }) | undefined>;
133
184
  /** Every document in the whole collection. Pair with `.where(...).limit(n)` on large collections. */
134
- all(opts?: TerminalOptions): Promise<T[]>;
185
+ all(opts?: TerminalOptions): Promise<(T & {
186
+ _id: string;
187
+ })[]>;
135
188
  /** Count every row in the collection (equivalent to `.where({}).count()`). */
136
189
  count(opts?: TerminalOptions): Promise<number>;
137
190
  /** Fetch one document by primary key. Returns `undefined` when the id is unknown. */
138
- get(id: string, opts?: TerminalOptions): Promise<T | undefined>;
191
+ get(id: string, opts?: TerminalOptions): Promise<(T & {
192
+ _id: string;
193
+ }) | undefined>;
139
194
  /**
140
195
  * Filter rows. Two shapes:
141
196
  *
@@ -150,12 +205,36 @@ interface ClientCollection<T extends DocumentData = DocumentData> {
150
205
  order(spec: OrderSpec<T>): ClientQuery<T>;
151
206
  /** Limit modifier; last call wins. */
152
207
  limit(n: number): ClientQuery<T>;
153
- /** Insert a new document. Returns the server-assigned `_id`. */
154
- insert(doc: Partial<T> & DocumentData, opts?: TerminalOptions): Promise<{
208
+ /**
209
+ * Insert a new document. Returns its `_id`.
210
+ *
211
+ * A non-empty string `_id` is caller-chosen and sent as-is; a second
212
+ * insert of the same `_id` rejects with `AlreadyExists`. A present
213
+ * `_id` that is not a string (`null` included) throws `InvalidConfig`
214
+ * before any request is sent. When `_id` is omitted or `""`, the client
215
+ * mints a UUIDv7 before the request is sent and flags it as minted, so
216
+ * the server answers a retransmission of that same request with the
217
+ * original `{ _id }` while the stored row still matches, instead of a
218
+ * duplicate row.
219
+ *
220
+ * A minted insert is resent with the same body, and so the same minted
221
+ * `_id`, after a transport failure (a thrown `fetch`, or a 5xx, 408 or
222
+ * 429 response with no error envelope) and after a `MaintenancePending`
223
+ * refusal. An insert with a caller-chosen `_id` is resent only after
224
+ * `MaintenancePending`. Calling `insert(doc)` again mints a new auto-ID
225
+ * and is a new insert. The caller's `doc` is not modified.
226
+ */
227
+ insert(doc: Partial<T> & DocumentData & {
228
+ _id?: string;
229
+ }, opts?: TerminalOptions): Promise<{
155
230
  readonly _id: string;
156
231
  }>;
157
- /** JSON-merge-patch applied to one row by primary key. */
158
- update(id: string, patch: Partial<T>, opts?: TerminalOptions): Promise<{
232
+ /**
233
+ * JSON-merge-patch (RFC 7386) applied to one row by primary key.
234
+ * `null` deletes an optional field; a required field is removed with
235
+ * `replace` (see {@link MergePatch}).
236
+ */
237
+ update(id: string, patch: MergePatch<T>, opts?: TerminalOptions): Promise<{
159
238
  readonly modified: number;
160
239
  }>;
161
240
  /** Whole-document replace on one row by primary key. */
@@ -178,10 +257,18 @@ interface ClientQuery<T extends DocumentData = DocumentData> {
178
257
  order(spec: OrderSpec<T>): ClientQuery<T>;
179
258
  limit(n: number): ClientQuery<T>;
180
259
  /** First match or `undefined`. Issues `GET /v1/c/:collection?...&limit=1`. */
181
- first(opts?: TerminalOptions): Promise<T | undefined>;
260
+ first(opts?: TerminalOptions): Promise<(T & {
261
+ _id: string;
262
+ }) | undefined>;
182
263
  /** Every matching document. Pair with `.limit(n)` on large collections. */
183
- all(opts?: TerminalOptions): Promise<T[]>;
184
- /** Count matching rows. Issues `GET /v1/count?collection=&where=`; server returns a scalar. */
264
+ all(opts?: TerminalOptions): Promise<(T & {
265
+ _id: string;
266
+ })[]>;
267
+ /**
268
+ * Count matching rows, at most `limit` when one is set (as the server
269
+ * SDK's `count()` does). Issues `GET /v1/count?collection=&where=&limit=`;
270
+ * server returns a scalar.
271
+ */
185
272
  count(opts?: TerminalOptions): Promise<number>;
186
273
  }
187
274
  /**
@@ -228,6 +315,4 @@ interface BaerlyClient<TConfig extends BaerlyConfig = UnboundConfig> {
228
315
  * ```
229
316
  */
230
317
  declare const createBaerlyClient: <TConfig extends BaerlyConfig = UnboundConfig>(options: BaerlyClientOptions<TConfig>) => BaerlyClient<TConfig>;
231
- //#endregion
232
- export { TerminalOptions as a, ClientQuery as i, BaerlyClientOptions as n, createBaerlyClient as o, ClientCollection as r, Fetcher as s, BaerlyClient as t };
233
- //# sourceMappingURL=client-Fe8CwB73.d.ts.map
318
+ export { TerminalOptions as a, Fetcher as c, ClientQuery as i, BaerlyClientOptions as n, createBaerlyClient as o, ClientCollection as r, BaerlyWarning as s, BaerlyClient as t };
@@ -1,9 +1,37 @@
1
- import { r as BaerlyConfig, s as UnboundConfig } from "./app-config-DyiFK3_k.js";
2
- import { y as BaerlyError } from "./index-BYk9oCNf.js";
3
- import { t as BaerlyClient } from "./client-Fe8CwB73.js";
1
+ /**
2
+ * React bindings for `@baerly/client`. Call {@link createBaerlyReact}
3
+ * once with your config type to get a fully typed
4
+ * `{ BaerlyProvider, useQuery, useMutation, useBaerlyClient }` set,
5
+ * then export and import those from your own module:
6
+ *
7
+ * ```ts
8
+ * // src/web/client.ts
9
+ * export const { BaerlyProvider, useQuery, useMutation } =
10
+ * createBaerlyReact<typeof config>();
11
+ * ```
12
+ *
13
+ * This is the only React entry point. The hooks are not exported
14
+ * loose: an unbound hook can't see the config, so `c.collection(name)`
15
+ * would silently degrade to `DocumentData` rows and force casts.
16
+ * Binding once at the factory keeps every callback inferred.
17
+ *
18
+ * **Reads:** `useQuery(callback, deps?, options?)` — live by default.
19
+ * Subscribes to every collection the callback touches and re-runs on
20
+ * log events or `deps` change. Pass `{ live: false }` for initial and
21
+ * dependency-driven reads without `/v1/since`; call the stable
22
+ * `result.refetch()` for an explicit refresh. Return `useQuery.skip`
23
+ * to defer / conditional-render.
24
+ *
25
+ * **Mutations:** `useMutation()` → `[mutate, { isPending, error }]`.
26
+ * `mutate(callback)` runs the callback against the real client.
27
+ *
28
+ * **Escape hatch:** `useBaerlyClient()` — the raw bound
29
+ * {@link BaerlyClient} for imperative use.
30
+ */
31
+ import { r as BaerlyConfig, s as UnboundConfig } from "./app-config-C6qW7m8S.js";
32
+ import { t as BaerlyClient } from "./client-CHQTXpef.js";
33
+ import { o as BaerlyError } from "./collection-api-DbyhLAY8.js";
4
34
  import { ReactNode } from "react";
5
-
6
- //#region packages/client/src/react/use-mutation.d.ts
7
35
  /**
8
36
  * Tuple returned by {@link useMutation}. Positionally mirrors React
9
37
  * 19's `useActionState`: `[mutate, state]`. `mutate` is stable across
@@ -14,16 +42,16 @@ type UseMutationTuple<TConfig extends BaerlyConfig = UnboundConfig> = readonly [
14
42
  readonly isPending: boolean;
15
43
  readonly error: BaerlyError | undefined;
16
44
  }];
17
- //#endregion
18
- //#region packages/client/src/react/use-query.d.ts
19
45
  /**
20
46
  * Result handed back by {@link useQuery}. Discriminate on `status` —
21
47
  * narrowing into `"ok"` / `"refreshing"` gives `data: T`; narrowing
22
48
  * into `"loading"` / `"skipped"` gives `data: undefined`; narrowing
23
49
  * into `"error"` gives `data: T | undefined` (the prior successful
24
50
  * read survives across errors so the UI can keep rendering).
51
+ * Every state also carries the same stable `refetch()` function, which
52
+ * starts an explicit refresh without changing the declared dependencies.
25
53
  */
26
- type UseQueryResult<T> = {
54
+ type UseQueryResult<T> = ({
27
55
  readonly status: "loading";
28
56
  readonly data: undefined;
29
57
  readonly error: undefined;
@@ -43,9 +71,19 @@ type UseQueryResult<T> = {
43
71
  readonly status: "error";
44
72
  readonly data: T | undefined;
45
73
  readonly error: Error;
74
+ }) & {
75
+ /** Re-run this query without changing its declared dependencies. */
76
+ readonly refetch: () => void;
46
77
  };
47
- //#endregion
48
- //#region packages/client/src/react/create-react.d.ts
78
+ /** Options for a {@link useQuery} read. */
79
+ interface UseQueryOptions {
80
+ /**
81
+ * Subscribe to collection changes through `/v1/since`. Defaults to
82
+ * `true`. Set `false` for an initial/dependency-driven read that only
83
+ * refreshes when {@link UseQueryResult.refetch} is called.
84
+ */
85
+ readonly live?: boolean;
86
+ }
49
87
  /**
50
88
  * Props for the config-bound `BaerlyProvider` returned by
51
89
  * {@link createBaerlyReact}. `client` is typed `BaerlyClient<TConfig>`
@@ -67,12 +105,15 @@ interface BaerlyReact<TConfig extends BaerlyConfig> {
67
105
  /** Wrap your app once; provides the bound client to every hook below it. */
68
106
  readonly BaerlyProvider: (props: BaerlyProviderProps<TConfig>) => React.JSX.Element;
69
107
  /**
70
- * Reactive read. The callback receives `BaerlyClient<TConfig>`, so
71
- * the chain is fully typed. `useQuery.skip` short-circuits to
72
- * `{ status: "skipped" }`.
108
+ * Read, live by default. The callback receives
109
+ * `BaerlyClient<TConfig>`, so the chain is fully typed.
110
+ * `useQuery.skip` short-circuits to `{ status: "skipped" }`.
111
+ * Pass `{ live: false }` as the third argument for an initial and
112
+ * dependency-driven read with no `/v1/since` subscription. Every
113
+ * result state includes a stable `refetch()` function.
73
114
  */
74
115
  readonly useQuery: {
75
- <T>(callback: (client: BaerlyClient<TConfig>) => Promise<T> | symbol, deps?: ReadonlyArray<unknown>): UseQueryResult<T>;
116
+ <T>(callback: (client: BaerlyClient<TConfig>) => Promise<T> | symbol, deps?: ReadonlyArray<unknown>, options?: UseQueryOptions): UseQueryResult<T>;
76
117
  /**
77
118
  * Sentinel — return it from the callback to defer the read
78
119
  * (`{ status: "skipped" }`, no subscription). Typed `symbol` (not
@@ -110,13 +151,19 @@ interface BaerlyReact<TConfig extends BaerlyConfig> {
110
151
  * import { useQuery } from "./client.ts";
111
152
  * const notes = useQuery((c) => c.collection("notes").all(), []);
112
153
  * // ^? UseQueryResult<Note[]> — no cast
154
+ *
155
+ * const report = useQuery(
156
+ * (c) => c.collection("notes").all(),
157
+ * [],
158
+ * { live: false },
159
+ * );
160
+ * // report.refetch() re-runs the read without enabling live updates.
113
161
  * ```
114
162
  *
115
163
  * Omit the type parameter (`createBaerlyReact()`) for an unbound app;
116
- * collection names widen to `string` and rows to `DocumentData`,
117
- * matching the in-process `Db.collection` fallback.
164
+ * collection names widen to `string` and rows to
165
+ * `DocumentData & { _id: string }`, matching the in-process
166
+ * `Db.collection` fallback.
118
167
  */
119
- declare const createBaerlyReact: <TConfig extends BaerlyConfig = UnboundConfig>() => BaerlyReact<TConfig>;
120
- //#endregion
121
- export { type BaerlyProviderProps, type BaerlyReact, type UseMutationTuple, type UseQueryResult, createBaerlyReact };
122
- //# sourceMappingURL=client-react.d.ts.map
168
+ export declare const createBaerlyReact: <TConfig extends BaerlyConfig = UnboundConfig>() => BaerlyReact<TConfig>;
169
+ export type { BaerlyProviderProps, BaerlyReact, UseMutationTuple, UseQueryOptions, UseQueryResult };