@gusto/baerly-storage 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/README.md +157 -92
  2. package/dist/API.md +64 -32
  3. package/dist/CHANGELOG.md +295 -5
  4. package/dist/RECIPES.md +125 -0
  5. package/dist/THIRD-PARTY-LICENSES.txt +22 -96
  6. package/dist/{app-config-BIzyAKzy.d.ts → app-config-DyiFK3_k.d.ts} +43 -11
  7. package/dist/app-config.d.ts +1 -1
  8. package/dist/auth.d.ts +1 -1
  9. package/dist/auth.js +13 -13
  10. package/dist/auth.js.map +1 -1
  11. package/dist/aws4fetch.esm-p7eEzLCs.js +1702 -0
  12. package/dist/aws4fetch.esm-p7eEzLCs.js.map +1 -0
  13. package/dist/baerly.js +35 -15
  14. package/dist/baerly.js.map +1 -1
  15. package/dist/baerly.spec.json +342 -0
  16. package/dist/{client-BJXF3XJA.d.ts → client-Fe8CwB73.d.ts} +3 -3
  17. package/dist/client-react.d.ts +3 -3
  18. package/dist/client-react.js +4 -4
  19. package/dist/client-react.js.map +1 -1
  20. package/dist/client.d.ts +4 -4
  21. package/dist/client.js +3 -3
  22. package/dist/{cloudflare-Cn2ibODt.js → cloudflare-DzKBrUlg.js} +2 -2
  23. package/dist/{cloudflare-Cn2ibODt.js.map → cloudflare-DzKBrUlg.js.map} +1 -1
  24. package/dist/cloudflare.d.ts +49 -6
  25. package/dist/cloudflare.js +55 -21
  26. package/dist/cloudflare.js.map +1 -1
  27. package/dist/config-1tv0-Yzm.js +2693 -0
  28. package/dist/config-1tv0-Yzm.js.map +1 -0
  29. package/dist/constants-CfeMWQWk.js +222 -0
  30. package/dist/constants-CfeMWQWk.js.map +1 -0
  31. package/dist/{cost-BZ_MDBmn.js → cost-DSMIVqzL.js} +42 -43
  32. package/dist/cost-DSMIVqzL.js.map +1 -0
  33. package/dist/{current-json-DsN7FNY1.js → current-json-C6nhPOm1.js} +6 -204
  34. package/dist/current-json-C6nhPOm1.js.map +1 -0
  35. package/dist/{db-CCT6tDfY.d.ts → db-DsPkOVEH.d.ts} +3 -3
  36. package/dist/{deploy-BKKyGlSJ.js → deploy-DonTr-CV.js} +4 -4
  37. package/dist/{deploy-BKKyGlSJ.js.map → deploy-DonTr-CV.js.map} +1 -1
  38. package/dist/dev-vite.d.ts +9 -5
  39. package/dist/dev-vite.js +5 -4
  40. package/dist/dev-vite.js.map +1 -1
  41. package/dist/dev.d.ts +1 -1
  42. package/dist/dev.js +1 -1
  43. package/dist/{doctor-BVU4GNXN.js → doctor-DSIyCDg_.js} +5 -8
  44. package/dist/{doctor-BVU4GNXN.js.map → doctor-DSIyCDg_.js.map} +1 -1
  45. package/dist/{dump-DPEAKub6.js → dump-Bh5k26VQ.js} +9 -32
  46. package/dist/dump-Bh5k26VQ.js.map +1 -0
  47. package/dist/{errors-DOdL95kK.js → errors-Dfa3p78c.js} +25 -5
  48. package/dist/errors-Dfa3p78c.js.map +1 -0
  49. package/dist/{export-BcuCLFFe.js → export-DtF5tDIM.js} +9 -32
  50. package/dist/{export-BcuCLFFe.js.map → export-DtF5tDIM.js.map} +1 -1
  51. package/dist/{fsck-RXgLOaJG.js → fsck-D_djMO5D.js} +10 -33
  52. package/dist/fsck-D_djMO5D.js.map +1 -0
  53. package/dist/{http-Bd4byR4n.js → http-DxM9MflO.js} +123 -35
  54. package/dist/http-DxM9MflO.js.map +1 -0
  55. package/dist/http.d.ts +42 -26
  56. package/dist/http.js +3 -2
  57. package/dist/{index-DnBGSeuU.d.ts → index-0rZcMBwy.d.ts} +2 -2
  58. package/dist/{index-Cmsxx-ZN.d.ts → index-B6oexfOB.d.ts} +7 -7
  59. package/dist/{index-BDceQQi-.d.ts → index-BNRh23K9.d.ts} +4 -4
  60. package/dist/{index-DW7GT6M2.d.ts → index-BYk9oCNf.d.ts} +193 -163
  61. package/dist/index.d.ts +6 -6
  62. package/dist/index.js +4 -4
  63. package/dist/{indexes-Cx7uMXm0.d.ts → indexes-Dn9hbGQG.d.ts} +2 -2
  64. package/dist/{inspect-DhI49PSi.js → inspect-6WZ-pC7-.js} +10 -33
  65. package/dist/inspect-6WZ-pC7-.js.map +1 -0
  66. package/dist/key-Di6yyxFu.js +35 -0
  67. package/dist/key-Di6yyxFu.js.map +1 -0
  68. package/dist/{log-tail-DXeDkWEp.js → log-tail-D98U1JBo.js} +31 -7
  69. package/dist/log-tail-D98U1JBo.js.map +1 -0
  70. package/dist/{maintenance-CWBQpZ2y.js → maintenance-B4Dki6Ig.js} +77 -22
  71. package/dist/maintenance-B4Dki6Ig.js.map +1 -0
  72. package/dist/{maintenance-BkhUr72A.d.ts → maintenance-B_e0T99L.d.ts} +28 -5
  73. package/dist/{maintenance-C_KSkVjd.js → maintenance-C7coQp4c.js} +17 -16
  74. package/dist/maintenance-C7coQp4c.js.map +1 -0
  75. package/dist/maintenance.d.ts +3 -3
  76. package/dist/maintenance.js +3 -3
  77. package/dist/node.d.ts +168 -65
  78. package/dist/node.js +3 -2
  79. package/dist/{normalize-XWY25_sG.js → normalize-rjnZLwS4.js} +2 -2
  80. package/dist/normalize-rjnZLwS4.js.map +1 -0
  81. package/dist/{observability-BYd-RzEx.js → observability-wzs3-BL_.js} +233 -71
  82. package/dist/observability-wzs3-BL_.js.map +1 -0
  83. package/dist/observability.d.ts +2 -2
  84. package/dist/observability.js +1 -1
  85. package/dist/{plan-DIu_B6fy.js → plan-a7PJHBCy.js} +2 -2
  86. package/dist/{plan-DIu_B6fy.js.map → plan-a7PJHBCy.js.map} +1 -1
  87. package/dist/{query-sQNO5vU_.js → query-rAtXNQQB.js} +96 -207
  88. package/dist/query-rAtXNQQB.js.map +1 -0
  89. package/dist/{rebuild-index-DP4CqSSs.js → rebuild-index-BVzQSZlm.js} +9 -32
  90. package/dist/rebuild-index-BVzQSZlm.js.map +1 -0
  91. package/dist/{request-BEF_OvMh.js → request-u0M51mhJ.js} +3 -3
  92. package/dist/{request-BEF_OvMh.js.map → request-u0M51mhJ.js.map} +1 -1
  93. package/dist/{restore-DpQYef6r.js → restore-R-4rbciV.js} +73 -100
  94. package/dist/restore-R-4rbciV.js.map +1 -0
  95. package/dist/runtime-spec-qL3_lTTU.js +391 -0
  96. package/dist/runtime-spec-qL3_lTTU.js.map +1 -0
  97. package/dist/s3-http-B-z8th6O.d.ts +60 -0
  98. package/dist/s3.d.ts +47 -0
  99. package/dist/s3.js +45 -0
  100. package/dist/s3.js.map +1 -0
  101. package/dist/{shared-secret-BJdSwpgw.js → shared-secret-DgEicd3x.js} +13 -5
  102. package/dist/shared-secret-DgEicd3x.js.map +1 -0
  103. package/dist/src-BG20LZs7.js +2271 -0
  104. package/dist/src-BG20LZs7.js.map +1 -0
  105. package/dist/{src-Db4-qVtM.js → src-CYHFDrKz.js} +51 -8
  106. package/dist/src-CYHFDrKz.js.map +1 -0
  107. package/dist/{src-CWpkSbvJ.js → src-DYZ4H1aF.js} +6 -5
  108. package/dist/src-DYZ4H1aF.js.map +1 -0
  109. package/dist/{subcommand-CP9NY2J4.js → subcommand-DoDA-K7d.js} +44 -6
  110. package/dist/subcommand-DoDA-K7d.js.map +1 -0
  111. package/dist/time-DUqvFMHq.js +119 -0
  112. package/dist/time-DUqvFMHq.js.map +1 -0
  113. package/dist/{usage-CTfDq9HR.js → usage-DBV1eQHC.js} +7 -22
  114. package/dist/usage-DBV1eQHC.js.map +1 -0
  115. package/dist/wire-izfGZDvr.js.map +1 -1
  116. package/package.json +52 -28
  117. package/dist/config-CGyBopy3.js +0 -5326
  118. package/dist/config-CGyBopy3.js.map +0 -1
  119. package/dist/cost-BZ_MDBmn.js.map +0 -1
  120. package/dist/current-json-DsN7FNY1.js.map +0 -1
  121. package/dist/dump-DPEAKub6.js.map +0 -1
  122. package/dist/errors-DOdL95kK.js.map +0 -1
  123. package/dist/fsck-RXgLOaJG.js.map +0 -1
  124. package/dist/http-Bd4byR4n.js.map +0 -1
  125. package/dist/inspect-DhI49PSi.js.map +0 -1
  126. package/dist/log-tail-DXeDkWEp.js.map +0 -1
  127. package/dist/maintenance-CWBQpZ2y.js.map +0 -1
  128. package/dist/maintenance-C_KSkVjd.js.map +0 -1
  129. package/dist/normalize-XWY25_sG.js.map +0 -1
  130. package/dist/observability-BYd-RzEx.js.map +0 -1
  131. package/dist/query-sQNO5vU_.js.map +0 -1
  132. package/dist/rebuild-index-DP4CqSSs.js.map +0 -1
  133. package/dist/restore-DpQYef6r.js.map +0 -1
  134. package/dist/shared-secret-BJdSwpgw.js.map +0 -1
  135. package/dist/src-CWpkSbvJ.js.map +0 -1
  136. package/dist/src-D24wDpzR.js +0 -6247
  137. package/dist/src-D24wDpzR.js.map +0 -1
  138. package/dist/src-Db4-qVtM.js.map +0 -1
  139. package/dist/subcommand-CP9NY2J4.js.map +0 -1
  140. package/dist/usage-CTfDq9HR.js.map +0 -1
  141. /package/dist/{chunk-EAsCxrDo.js → rolldown-runtime-EAsCxrDo.js} +0 -0
package/dist/node.d.ts CHANGED
@@ -1,64 +1,9 @@
1
- import { n as BaerlyAppConfig } from "./app-config-BIzyAKzy.js";
2
- import { _ as StorageGetResult, b as StoragePutResult, g as StorageGetOptions, h as Storage, r as Verifier, v as StorageListEntry, y as StoragePutOptions } from "./index-DW7GT6M2.js";
3
- import { i as DevLandingOptions } from "./index-DnBGSeuU.js";
4
- import { d as ObservabilityConfig } from "./index-Cmsxx-ZN.js";
1
+ import { n as BaerlyAppConfig } from "./app-config-DyiFK3_k.js";
2
+ import { p as Storage, r as Verifier } from "./index-BYk9oCNf.js";
3
+ import { i as DevLandingOptions } from "./index-0rZcMBwy.js";
4
+ import { d as ObservabilityConfig } from "./index-B6oexfOB.js";
5
+ import { n as S3HttpStorageOptions, t as S3HttpStorage } from "./s3-http-B-z8th6O.js";
5
6
 
6
- //#region packages/adapter-node/src/s3-http.d.ts
7
- /**
8
- * Construction-time options for {@link S3HttpStorage}. Everything is
9
- * optional except `endpoint` and `bucket`; the consumer chooses how
10
- * to satisfy `fetch` (browser/Node global vs. injected) and `sign`
11
- * (anonymous Minio vs. SigV4-signed via aws4fetch).
12
- */
13
- interface S3HttpStorageOptions {
14
- /**
15
- * S3 endpoint URL, e.g. `https://s3.us-east-1.amazonaws.com` or
16
- * `http://127.0.0.1:9102` (Minio). Trailing slashes are trimmed.
17
- */
18
- endpoint: string;
19
- /** S3 bucket name. */
20
- bucket: string;
21
- /**
22
- * `fetch` implementation. Defaults to `globalThis.fetch.bind(globalThis)`.
23
- * Tests pass a `vi.fn()` stub.
24
- */
25
- fetch?: typeof fetch;
26
- /**
27
- * Signs requests before send. Pass `undefined` for anonymous
28
- * (Minio without creds). The seam is `(req) => Promise<req>` so
29
- * SigV4 implementations like `aws4fetch.AwsClient.sign` plug in
30
- * directly.
31
- */
32
- sign?: (req: Request) => Promise<Request>;
33
- /** Max retries for transient (non-permanent) failures. */
34
- retries?: number;
35
- /** Initial backoff in ms. */
36
- backoffMs?: number;
37
- }
38
- /**
39
- * `Storage` impl that speaks the S3 REST API directly. Works against
40
- * any S3-compatible endpoint — AWS S3, R2 (S3-compat), GCS (S3-compat),
41
- * Minio. Does not depend on any AWS SDK.
42
- *
43
- * Authentication is plugged in via the `sign` callback; this class
44
- * itself does no SigV4. For Cloudflare Workers, the R2 binding fast
45
- * path lives in `@baerly/adapter-cloudflare`.
46
- */
47
- declare class S3HttpStorage implements Storage {
48
- #private;
49
- constructor(options: S3HttpStorageOptions);
50
- get(key: string, opts?: StorageGetOptions): Promise<StorageGetResult | null>;
51
- put(key: string, body: Uint8Array, opts?: StoragePutOptions): Promise<StoragePutResult>;
52
- delete(key: string, opts?: {
53
- signal?: AbortSignal;
54
- }): Promise<void>;
55
- list(prefix: string, opts?: {
56
- startAfter?: string;
57
- maxKeys?: number;
58
- signal?: AbortSignal;
59
- }): AsyncIterable<StorageListEntry>;
60
- }
61
- //#endregion
62
7
  //#region packages/adapter-node/src/credentials/types.d.ts
63
8
  /**
64
9
  * Temporary or static AWS-shaped credentials. Field shape matches
@@ -119,14 +64,14 @@ type CredentialsProvider = () => Promise<Credentials>;
119
64
  * });
120
65
  * ```
121
66
  *
122
- * @example EKS Pod Identity (refreshing)
67
+ * @example EKS (refreshing) — auto-detects Pod Identity or IRSA
123
68
  * ```ts
124
- * import { s3Storage, fromEksPodIdentity } from "@gusto/baerly-storage/node";
69
+ * import { s3Storage, fromEks } from "@gusto/baerly-storage/node";
125
70
  *
126
71
  * const storage = s3Storage({
127
72
  * region: process.env["AWS_REGION"] ?? "us-east-1",
128
73
  * bucket: process.env["BUCKET"]!,
129
- * credentials: fromEksPodIdentity(),
74
+ * credentials: fromEks(),
130
75
  * });
131
76
  * ```
132
77
  */
@@ -205,7 +150,7 @@ declare function minioStorage(opts: {
205
150
  * Whether GCS's interop layer enforces S3-style conditional *writes* is
206
151
  * unverified — run `baerly doctor --bucket=<your-gcs-bucket>` before
207
152
  * relying on it; a backend that fails the CAS probe is not a safe baerly
208
- * store. See ADR-004.
153
+ * store. See ADR-002.
209
154
  *
210
155
  * @example
211
156
  * ```ts
@@ -225,6 +170,140 @@ declare function gcsStorage(opts: {
225
170
  credentials: Credentials | CredentialsProvider;
226
171
  }): Storage;
227
172
  //#endregion
173
+ //#region packages/adapter-node/src/local-fs-storage.d.ts
174
+ interface LocalFsStorageFactoryOptions {
175
+ /**
176
+ * Root data directory. Resolution order: this option →
177
+ * `$BAERLY_DATA_DIR` → `<cwd>/.baerly-data`.
178
+ */
179
+ readonly dataDir?: string;
180
+ }
181
+ /**
182
+ * Zero-config local `Storage` for single-node dev / self-hosted runs.
183
+ * Persists to the filesystem (content-addressed, atomic writes), so data
184
+ * survives process restarts — unlike `MemoryStorage`, which is per-process
185
+ * and lost on exit.
186
+ *
187
+ * NOT for multi-instance production: `LocalFsStorage`'s `ifMatch` CAS is
188
+ * in-process TOCTOU only (cross-process `current.json` CAS-advance is not
189
+ * atomic — see its class JSDoc). For horizontally-scaled deploys use
190
+ * `s3Storage` / `r2Storage`, whose cross-process guarantee the no-lease
191
+ * maintenance fold relies on.
192
+ *
193
+ * @example
194
+ * ```ts
195
+ * import { baerlyNode, localFsStorage } from "@gusto/baerly-storage/node";
196
+ * import config from "./baerly.config.ts";
197
+ *
198
+ * // Runs with zero credentials; persists to ./.baerly-data.
199
+ * await baerlyNode({ config, storage: localFsStorage() }).listen(8080);
200
+ * ```
201
+ */
202
+ declare const localFsStorage: (opts?: LocalFsStorageFactoryOptions) => Storage;
203
+ //#endregion
204
+ //#region packages/adapter-node/src/resolve-storage.d.ts
205
+ /** Result of {@link resolveStorageFromEnv}. */
206
+ interface ResolvedStorage {
207
+ readonly storage: Storage;
208
+ /** Human-readable backend label for a startup log line. */
209
+ readonly label: string;
210
+ }
211
+ /**
212
+ * Choose a Node `Storage` backend from environment variables, in priority
213
+ * order:
214
+ * 1. `R2_ACCOUNT_ID` set → Cloudflare R2 (S3-compat endpoint)
215
+ * 2. `BUCKET` set → AWS S3
216
+ * 3. neither, local dev → `localFsStorage` (zero credentials)
217
+ * 4. neither, deployed → throw
218
+ *
219
+ * This is the safe default the example scaffolds use, exported so apps
220
+ * don't hand-roll their own selector and reintroduce the silent
221
+ * in-memory / local-fs fallback this library exists to prevent. There is
222
+ * deliberately **no** fallback to a non-durable store in a deployment:
223
+ * local-fs is single-process with no cross-process CAS and no crash
224
+ * durability, and in-memory storage loses all data on restart, so a
225
+ * deployed environment with no bucket fails loud instead.
226
+ *
227
+ * `env` is injectable for testing; it defaults to `process.env`.
228
+ *
229
+ * @throws BaerlyError `InvalidConfig` when {@link isDeployedEnv} is true
230
+ * and no bucket is configured, or when a configured bucket is missing its
231
+ * credentials.
232
+ *
233
+ * @example
234
+ * ```ts
235
+ * import { baerlyNode, resolveStorageFromEnv } from "@gusto/baerly-storage/node";
236
+ * import config from "./baerly.config.ts";
237
+ *
238
+ * const { storage, label } = resolveStorageFromEnv();
239
+ * console.log(`[baerly] storage=${label}`);
240
+ * await baerlyNode({ config, storage }).listen(Number(process.env["PORT"] ?? 8080));
241
+ * ```
242
+ */
243
+ declare const resolveStorageFromEnv: (env?: Record<string, string | undefined>) => ResolvedStorage;
244
+ //#endregion
245
+ //#region packages/adapter-node/src/assert-storage-reachable.d.ts
246
+ /** Options for {@link assertStorageReachable}. */
247
+ interface AssertStorageReachableOptions {
248
+ /** Key prefix for the throwaway probe sentinels. Default `""`. */
249
+ keyPrefix?: string;
250
+ signal?: AbortSignal;
251
+ }
252
+ /**
253
+ * Boot-time readiness check: confirm a live `Storage` backend is both
254
+ * reachable and honours the conditional writes the protocol depends on.
255
+ * `await` it at startup (or from a `/readyz` handler wired to your
256
+ * platform's readiness probe) to fail closed on a misconfigured backend —
257
+ * an unreachable or non-existent bucket, denied/missing credentials (wrong
258
+ * endpoint/region), or an S3-compatible store that silently ignores
259
+ * `If-Match`/`If-None-Match` (the CAS the protocol depends on) — instead
260
+ * of discovering it on the first user write. It cannot detect a
261
+ * wrong-but-writable bucket: a typo to another reachable bucket you own
262
+ * boots clean, because the probe can only tell that *a* bucket is reachable
263
+ * and CAS-correct, not that it is the *intended* one. This complements
264
+ * `resolveStorageFromEnv`, which catches a *missing* configuration:
265
+ * `assertStorageReachable` additionally catches an
266
+ * unreachable/access-denied/CAS-broken backend at boot instead of on the
267
+ * first write.
268
+ *
269
+ * Opt-in by design: it performs a handful of live round-trips (writes and
270
+ * deletes throwaway sentinels under `keyPrefix`), so it is never run
271
+ * automatically on every boot. Reuses the same `probeCas` machinery as
272
+ * `baerly doctor --bucket`.
273
+ *
274
+ * @throws BaerlyError `NetworkError` if the backend is unreachable, or
275
+ * `InvalidConfig` if it is reachable but fails a required CAS check.
276
+ *
277
+ * @example
278
+ * ```ts
279
+ * const { storage, label } = resolveStorageFromEnv();
280
+ * await assertStorageReachable(storage); // throws before we serve traffic
281
+ * console.log(`[baerly] storage=${label} (reachable)`);
282
+ * ```
283
+ */
284
+ declare const assertStorageReachable: (storage: Storage, opts?: AssertStorageReachableOptions) => Promise<void>;
285
+ //#endregion
286
+ //#region packages/adapter-node/src/credentials/from-eks.d.ts
287
+ /**
288
+ * Resolve AWS credentials on EKS regardless of which identity mechanism the
289
+ * cluster uses, so callers don't have to know. EKS injects credentials one of
290
+ * two ways:
291
+ *
292
+ * - **Pod Identity** (2023+): `AWS_CONTAINER_CREDENTIALS_FULL_URI` +
293
+ * `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` → {@link fromEksPodIdentity}.
294
+ * - **IRSA** (web-identity token): `AWS_ROLE_ARN` +
295
+ * `AWS_WEB_IDENTITY_TOKEN_FILE` → {@link fromWebIdentity}.
296
+ *
297
+ * Detection runs on every resolve (Pod Identity preferred when both are
298
+ * present), so the right mechanism is picked even if the env is populated late
299
+ * and re-checked on each refresh. Use this instead of the mechanism-specific
300
+ * providers unless you have a reason to pin one.
301
+ */
302
+ declare function fromEks(opts?: {
303
+ fetch?: typeof fetch;
304
+ readFile?: (path: string, encoding: "utf8") => Promise<string>;
305
+ }): CredentialsProvider;
306
+ //#endregion
228
307
  //#region packages/adapter-node/src/credentials/from-eks-pod-identity.d.ts
229
308
  /**
230
309
  * Resolve AWS credentials from the EKS Pod Identity agent (the 2023
@@ -246,6 +325,30 @@ declare function fromEksPodIdentity(opts?: {
246
325
  readFile?: (path: string, encoding: "utf8") => Promise<string>;
247
326
  }): CredentialsProvider;
248
327
  //#endregion
328
+ //#region packages/adapter-node/src/credentials/from-web-identity.d.ts
329
+ /**
330
+ * Resolve AWS credentials via IRSA (IAM Roles for Service Accounts) — the
331
+ * web-identity-token flow, distinct from the EKS Pod Identity agent that
332
+ * {@link fromEksPodIdentity} handles. EKS projects a signed service-account
333
+ * token into the pod and the app exchanges it for short-lived credentials by
334
+ * calling STS `AssumeRoleWithWebIdentity` directly (the token *is* the auth, so
335
+ * the call is unsigned — no chicken-and-egg credential bootstrap).
336
+ *
337
+ * Env vars (set by EKS when the pod's service account is annotated with a role):
338
+ * - `AWS_ROLE_ARN` — the role to assume.
339
+ * - `AWS_WEB_IDENTITY_TOKEN_FILE` — path to the projected SA token.
340
+ * - `AWS_ROLE_SESSION_NAME` — optional session name (defaults to `baerly-storage`).
341
+ * - `AWS_REGION` / `AWS_DEFAULT_REGION` — optional; selects the regional STS
342
+ * endpoint (falls back to the global endpoint).
343
+ *
344
+ * STS credentials expire (~1 h); the returned provider reports `expiration`, so
345
+ * the signing layer re-resolves before they lapse.
346
+ */
347
+ declare function fromWebIdentity(opts?: {
348
+ fetch?: typeof fetch;
349
+ readFile?: (path: string, encoding: "utf8") => Promise<string>;
350
+ }): CredentialsProvider;
351
+ //#endregion
249
352
  //#region packages/adapter-node/src/baerly-node.d.ts
250
353
  /**
251
354
  * Options for {@link baerlyNode}. Composes the {@link createApp}
@@ -364,5 +467,5 @@ interface BaerlyNodeHandle {
364
467
  */
365
468
  declare function baerlyNode(opts: BaerlyNodeOptions): BaerlyNodeHandle;
366
469
  //#endregion
367
- export { type BaerlyNodeHandle, type BaerlyNodeOptions, type Credentials, type CredentialsProvider, S3HttpStorage, type S3HttpStorageOptions, baerlyNode, fromEksPodIdentity, gcsStorage, minioStorage, r2Storage, s3Storage };
470
+ export { type AssertStorageReachableOptions, type BaerlyNodeHandle, type BaerlyNodeOptions, type Credentials, type CredentialsProvider, type LocalFsStorageFactoryOptions, type ResolvedStorage, S3HttpStorage, type S3HttpStorageOptions, assertStorageReachable, baerlyNode, fromEks, fromEksPodIdentity, fromWebIdentity, gcsStorage, localFsStorage, minioStorage, r2Storage, resolveStorageFromEnv, s3Storage };
368
471
  //# sourceMappingURL=node.d.ts.map
package/dist/node.js CHANGED
@@ -1,2 +1,3 @@
1
- import { a as minioStorage, c as S3HttpStorage, i as gcsStorage, o as r2Storage, r as fromEksPodIdentity, s as s3Storage, t as baerlyNode } from "./src-D24wDpzR.js";
2
- export { S3HttpStorage, baerlyNode, fromEksPodIdentity, gcsStorage, minioStorage, r2Storage, s3Storage };
1
+ import { a as fromEksPodIdentity, c as localFsStorage, d as r2Storage, f as s3Storage, i as fromWebIdentity, l as gcsStorage, o as assertStorageReachable, r as fromEks, s as resolveStorageFromEnv, t as baerlyNode, u as minioStorage } from "./src-BG20LZs7.js";
2
+ import { n as S3HttpStorage } from "./aws4fetch.esm-p7eEzLCs.js";
3
+ export { S3HttpStorage, assertStorageReachable, baerlyNode, fromEks, fromEksPodIdentity, fromWebIdentity, gcsStorage, localFsStorage, minioStorage, r2Storage, resolveStorageFromEnv, s3Storage };
@@ -1,4 +1,4 @@
1
- import { t as BaerlyError } from "./errors-DOdL95kK.js";
1
+ import { t as BaerlyError } from "./errors-Dfa3p78c.js";
2
2
  //#region packages/protocol/src/query/builder.ts
3
3
  /**
4
4
  * Build a fresh `PredicateBuilder<T>` along with the clause-list
@@ -130,4 +130,4 @@ const normalizePredicateArg = (arg) => {
130
130
  //#endregion
131
131
  export { normalizePredicateArg as t };
132
132
 
133
- //# sourceMappingURL=normalize-XWY25_sG.js.map
133
+ //# sourceMappingURL=normalize-rjnZLwS4.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"normalize-rjnZLwS4.js","names":[],"sources":["../packages/protocol/src/query/builder.ts","../packages/protocol/src/query/normalize.ts"],"sourcesContent":["/**\n * Callback-form predicate DSL. `q.eq(\"status\", \"open\").gt(\"priority\",\n * 5)` builds a {@link PredicateWire} via methods on the\n * {@link PredicateBuilder} handle. Each method appends one\n * {@link PredicateClause} to a private list and returns the same\n * handle for chaining.\n *\n * Why a builder, not imported helpers? The methods that exist on\n * the type ARE the supported vocabulary — there is no\n * \"what we don't support\" page to maintain. The agent cannot call\n * `q.regex(...)` because there is no `regex` method; the compiler\n * surfaces the error before the request is sent.\n *\n * Companion modules: `./normalize.ts` (object → wire),\n * `./wire.ts` (wire types).\n */\n\nimport type { DocumentData, DocumentValue } from \"../json.ts\";\nimport type { Path, PathValue, Predicate } from \"../collection-api.ts\";\n\nimport type { PredicateClause, PredicateWire } from \"./wire.ts\";\n\n/**\n * Callback-form predicate builder. Methods append clauses and\n * return the same builder for chaining; chained calls AND-merge.\n *\n * The methods on this interface ARE the supported operator surface.\n * Vocabulary additions (`or`, `not`, `regex`, `ne`, `exists`, ...)\n * are intentionally absent — calling them is a TS2339 compile\n * error, not a runtime rejection. The algebra is conjunction-only in\n * perpetuity — see the API surface lock in\n * docs/contributing/conventions/change-discipline.md.\n *\n * @template T - the document shape the predicate is keyed against.\n */\nexport interface PredicateBuilder<T extends DocumentData = DocumentData> {\n /**\n * Strict equality on `field`. Use this for the in-callback\n * equality clauses that the object-form would also support;\n * mixing `q.eq(...)` with range / `in` clauses in one call is\n * the canonical \"mixed equality + range\" pattern.\n */\n eq<K extends Path<T>>(field: K, value: PathValue<T, K>): PredicateBuilder<T>;\n\n /**\n * Strict greater. `value` must be `string` or `number`; the\n * intersection at the type level rejects `boolean` / `null`\n * fields at the call site (`q.gt(\"done\", true)` is a TS error\n * on a `done: boolean` field).\n */\n gt<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;\n\n /** Inclusive greater. See {@link gt} for the value-type constraint. */\n gte<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;\n\n /** Strict less. See {@link gt} for the value-type constraint. */\n lt<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;\n\n /** Inclusive less. See {@link gt} for the value-type constraint. */\n lte<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;\n\n /**\n * Set membership. Empty array is `UnsatisfiablePredicate` at\n * normalise time — the validator emits the error eagerly so the\n * caller sees it at the `.where(...)` call site, not later.\n */\n in<K extends Path<T>>(field: K, values: ReadonlyArray<PathValue<T, K>>): PredicateBuilder<T>;\n}\n\n/**\n * Argument shape accepted by `.where(...)`. Either the object-literal\n * equality form ({@link Predicate}) or a callback that drives a\n * {@link PredicateBuilder} and returns it (the chain terminator).\n */\nexport type PredicateArg<T extends DocumentData> =\n | Predicate<T>\n | ((q: PredicateBuilder<T>) => PredicateBuilder<T>);\n\n/**\n * Build a fresh `PredicateBuilder<T>` along with the clause-list\n * cell it appends to. Internal — `./normalize.ts` drives this.\n *\n * @internal\n */\nexport const makeBuilder = <T extends DocumentData>(): {\n builder: PredicateBuilder<T>;\n clauses: PredicateClause[];\n} => {\n const clauses: PredicateClause[] = [];\n const push = (clause: PredicateClause): PredicateBuilder<T> => {\n clauses.push(clause);\n return builder;\n };\n const builder: PredicateBuilder<T> = {\n eq: (field, value) => push({ op: \"eq\", field: String(field), value: value as DocumentValue }),\n gt: (field, value) => push({ op: \"gt\", field: String(field), value: value as DocumentValue }),\n gte: (field, value) => push({ op: \"gte\", field: String(field), value: value as DocumentValue }),\n lt: (field, value) => push({ op: \"lt\", field: String(field), value: value as DocumentValue }),\n lte: (field, value) => push({ op: \"lte\", field: String(field), value: value as DocumentValue }),\n in: (field, values) =>\n push({\n op: \"in\",\n field: String(field),\n value: [...(values as ReadonlyArray<DocumentValue>)],\n }),\n };\n return { builder, clauses };\n};\n\n/**\n * Tighter wire-form type after running through the builder helper —\n * not part of the public surface; `./normalize.ts` returns a plain\n * {@link PredicateWire}.\n *\n * @internal\n */\nexport const wireFromBuilder = <T extends DocumentData>(\n cb: (q: PredicateBuilder<T>) => PredicateBuilder<T>,\n): PredicateWire => {\n const { builder, clauses } = makeBuilder<T>();\n cb(builder);\n return { clauses };\n};\n","/**\n * Object-form → wire normaliser. Walks a `Predicate<T>` object\n * literal, flattens nested sub-predicates to dotted-path `eq`\n * clauses, and returns a {@link PredicateWire}. Rejects any\n * `$`-prefixed key as `InvalidConfig` — the operator vocabulary\n * lives on the callback DSL only.\n *\n * Semantic invariant: a sub-predicate object (every value is itself\n * an object) flattens to one `eq` clause per leaf — the same\n * open-world matching today's matcher delivers at\n * `./matches.ts:matchesValue` for sub-predicates.\n *\n * Companion modules: `./builder.ts` (callback → wire),\n * `./wire.ts` (types).\n */\n\nimport { BaerlyError } from \"../errors.ts\";\nimport type { DocumentData } from \"../json.ts\";\n\nimport { type PredicateArg, type PredicateBuilder, wireFromBuilder } from \"./builder.ts\";\nimport type { PredicateClause, PredicateWire } from \"./wire.ts\";\n\n// Inlined so the normaliser's chunk does not pull in `_internals.ts`\n// (which carries the merger/validator's heavier comparator helpers\n// the client never executes). Keeping a tiny local copy of formatPath\n// keeps the SPA bundle's predicate footprint to normalize+wire only.\nconst formatPath = (path: ReadonlyArray<string>): string =>\n path.length === 0 ? \"<root>\" : path.map((p) => JSON.stringify(p)).join(\".\");\n\n/**\n * Walk an object-literal predicate, emit one `PredicateClause[]`.\n * Pure primitive values become `eq` clauses at the current path;\n * nested objects recurse, flattening to dotted-path clauses.\n *\n * @internal Tested via the public `normalizePredicateArg` and the\n * normalize.test.ts suite.\n */\nexport const normalizeObject = (\n obj: DocumentData,\n basePath: ReadonlyArray<string>,\n): PredicateClause[] => {\n const out: PredicateClause[] = [];\n for (const key of Object.keys(obj)) {\n const path = [...basePath, key];\n if (key.startsWith(\"$\")) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Unsupported predicate operator ${JSON.stringify(key)} at ${formatPath(basePath)} — operator vocabulary moved to the callback form (.where(q => q.gt(field, value))). $-keys are not accepted in object-form predicates.`,\n );\n }\n if (key === \"__proto__\" || key === \"constructor\" || key === \"prototype\") {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Reserved key ${JSON.stringify(key)} not allowed in a predicate at ${formatPath(basePath)}.`,\n );\n }\n const value: unknown = (obj as Record<string, unknown>)[key];\n if (value === null || value === undefined) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Predicate value at ${formatPath(path)} is ${value === null ? \"null\" : \"undefined\"} — terminal values must be string / number / boolean / nested object.`,\n );\n }\n if (Array.isArray(value)) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Predicate value at ${formatPath(path)} is an array — match nested objects with a sub-predicate or use callback form (q.in(field, values)) for set membership.`,\n );\n }\n const t = typeof value;\n if (t === \"object\") {\n // Sub-predicate — recurse, accumulating dotted path. Object-form\n // predicates have NO operator vocabulary, so a nested object is\n // unambiguously a literal sub-predicate. Empty object `{}` at a\n // nested position is a match-all sub-clause: it emits zero\n // clauses for that subtree, which matches the matcher's\n // pre-redesign behaviour for `{ assignee: {} }` (an empty\n // sub-predicate accepts any non-null object actual).\n const inner = normalizeObject(value as DocumentData, path);\n for (const c of inner) {\n out.push(c);\n }\n continue;\n }\n if (t !== \"string\" && t !== \"number\" && t !== \"boolean\") {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Predicate value at ${formatPath(path)} has unsupported type ${JSON.stringify(t)} — must be string / number / boolean / nested object.`,\n );\n }\n if (t === \"number\" && !Number.isFinite(value as number)) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Predicate value at ${formatPath(path)} is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`,\n );\n }\n out.push({ op: \"eq\", field: path.join(\".\"), value: value as string | number | boolean });\n }\n return out;\n};\n\n/**\n * Dispatch the two-shape `.where(...)` argument to a\n * {@link PredicateWire}. The object-form is walked by\n * {@link normalizeObject}; the callback form is invoked with a\n * fresh {@link PredicateBuilder}.\n *\n * @internal — every consumer (`Db.collection().where`,\n * `ClientCollection.where`, `parseWhereParam`'s wire-arrival\n * path) routes through this single seam so the wire\n * format has exactly one parser path.\n */\nexport const normalizePredicateArg = <T extends DocumentData>(\n arg: PredicateArg<T>,\n): PredicateWire => {\n if (typeof arg === \"function\") {\n return wireFromBuilder<T>(arg as (q: PredicateBuilder<T>) => PredicateBuilder<T>);\n }\n return { clauses: normalizeObject(arg as DocumentData, []) };\n};\n"],"mappings":";;;;;;;;AAoFA,MAAa,oBAGR;CACH,MAAM,UAA6B,CAAC;CACpC,MAAM,QAAQ,WAAiD;EAC7D,QAAQ,KAAK,MAAM;EACnB,OAAO;CACT;CACA,MAAM,UAA+B;EACnC,KAAK,OAAO,UAAU,KAAK;GAAE,IAAI;GAAM,OAAO,OAAO,KAAK;GAAU;EAAuB,CAAC;EAC5F,KAAK,OAAO,UAAU,KAAK;GAAE,IAAI;GAAM,OAAO,OAAO,KAAK;GAAU;EAAuB,CAAC;EAC5F,MAAM,OAAO,UAAU,KAAK;GAAE,IAAI;GAAO,OAAO,OAAO,KAAK;GAAU;EAAuB,CAAC;EAC9F,KAAK,OAAO,UAAU,KAAK;GAAE,IAAI;GAAM,OAAO,OAAO,KAAK;GAAU;EAAuB,CAAC;EAC5F,MAAM,OAAO,UAAU,KAAK;GAAE,IAAI;GAAO,OAAO,OAAO,KAAK;GAAU;EAAuB,CAAC;EAC9F,KAAK,OAAO,WACV,KAAK;GACH,IAAI;GACJ,OAAO,OAAO,KAAK;GACnB,OAAO,CAAC,GAAI,MAAuC;EACrD,CAAC;CACL;CACA,OAAO;EAAE;EAAS;CAAQ;AAC5B;;;;;;;;AASA,MAAa,mBACX,OACkB;CAClB,MAAM,EAAE,SAAS,YAAY,YAAe;CAC5C,GAAG,OAAO;CACV,OAAO,EAAE,QAAQ;AACnB;;;;;;;;;;;;;;;;;;AChGA,MAAM,cAAc,SAClB,KAAK,WAAW,IAAI,WAAW,KAAK,KAAK,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG;;;;;;;;;AAU5E,MAAa,mBACX,KACA,aACsB;CACtB,MAAM,MAAyB,CAAC;CAChC,KAAK,MAAM,OAAO,OAAO,KAAK,GAAG,GAAG;EAClC,MAAM,OAAO,CAAC,GAAG,UAAU,GAAG;EAC9B,IAAI,IAAI,WAAW,GAAG,GACpB,MAAM,IAAI,YACR,iBACA,kCAAkC,KAAK,UAAU,GAAG,EAAE,MAAM,WAAW,QAAQ,EAAE,wIACnF;EAEF,IAAI,QAAQ,eAAe,QAAQ,iBAAiB,QAAQ,aAC1D,MAAM,IAAI,YACR,iBACA,gBAAgB,KAAK,UAAU,GAAG,EAAE,iCAAiC,WAAW,QAAQ,EAAE,EAC5F;EAEF,MAAM,QAAkB,IAAgC;EACxD,IAAI,UAAU,QAAQ,UAAU,KAAA,GAC9B,MAAM,IAAI,YACR,iBACA,sBAAsB,WAAW,IAAI,EAAE,MAAM,UAAU,OAAO,SAAS,YAAY,sEACrF;EAEF,IAAI,MAAM,QAAQ,KAAK,GACrB,MAAM,IAAI,YACR,iBACA,sBAAsB,WAAW,IAAI,EAAE,wHACzC;EAEF,MAAM,IAAI,OAAO;EACjB,IAAI,MAAM,UAAU;GAQlB,MAAM,QAAQ,gBAAgB,OAAuB,IAAI;GACzD,KAAK,MAAM,KAAK,OACd,IAAI,KAAK,CAAC;GAEZ;EACF;EACA,IAAI,MAAM,YAAY,MAAM,YAAY,MAAM,WAC5C,MAAM,IAAI,YACR,iBACA,sBAAsB,WAAW,IAAI,EAAE,wBAAwB,KAAK,UAAU,CAAC,EAAE,sDACnF;EAEF,IAAI,MAAM,YAAY,CAAC,OAAO,SAAS,KAAe,GACpD,MAAM,IAAI,YACR,iBACA,sBAAsB,WAAW,IAAI,EAAE,MAAM,OAAO,KAAK,EAAE,wEAC7D;EAEF,IAAI,KAAK;GAAE,IAAI;GAAM,OAAO,KAAK,KAAK,GAAG;GAAU;EAAmC,CAAC;CACzF;CACA,OAAO;AACT;;;;;;;;;;;;AAaA,MAAa,yBACX,QACkB;CAClB,IAAI,OAAO,QAAQ,YACjB,OAAO,gBAAmB,GAAsD;CAElF,OAAO,EAAE,SAAS,gBAAgB,KAAqB,CAAC,CAAC,EAAE;AAC7D"}