@furystack/s3-blob-store 1.0.0

package/README.md

@@ -0,0 +1,76 @@
+# @furystack/s3-blob-store
+
+S3-compatible adapter for `@furystack/blob-store`. Targets AWS S3,
+MinIO, Cloudflare R2, Backblaze B2, and any backend that speaks the v3
+S3 API. v1 uses single-part `PutObject` for uploads (5 GiB cap on AWS
+S3). Apps with very-large blobs that need resumable multipart can
+compose `@aws-sdk/lib-storage`'s `Upload` themselves on the underlying
+client; v1.x will lift this into a multipart-aware `put` variant.
+Presigned URLs ride on `@aws-sdk/s3-request-presigner`.
+
+## Installation
+
+```bash
+yarn add @furystack/s3-blob-store
+```
+
+The adapter has hard dependencies on the matching `@aws-sdk/*` v3
+packages — they are listed as regular dependencies, not peers, so they
+install transitively.
+
+## Usage
+
+The caller owns the `S3Client` lifecycle; the adapter never closes it.
+
+```ts
+import { S3Client } from '@aws-sdk/client-s3'
+import { BlobStore } from '@furystack/blob-store'
+import { defineS3BlobStore } from '@furystack/s3-blob-store'
+
+const client = new S3Client({
+  region: 'eu-central-1',
+  credentials: { accessKeyId, secretAccessKey },
+})
+
+injector.bind(
+  BlobStore,
+  defineS3BlobStore({
+    client,
+    bucket: 'my-app-blobs',
+    keyPrefix: 'tenant-a/',
+  }),
+)
+```
+
+### Lifecycle management
+
+By default, on first `put`, the adapter installs a bucket lifecycle
+rule that aborts incomplete multipart uploads after 24h to avoid
+runaway storage costs from interrupted clients. Disable with
+`manageLifecycle: false` (recommended for buckets the app lacks
+`s3:PutLifecycleConfiguration` on). Surface failures via
+`onLifecycleError`.
+
+### Capabilities
+
+- `presignedUrls: true`
+- `multipart: false` (v1 — single-part `PutObject` only)
+- `range: true`
+- `crossNodeAccessible: true`
+- `maxObjectBytes: 5 GiB` (AWS S3 single-part cap)
+
+### Integration tests
+
+The package ships unit tests against a stubbed `S3Client` plus an
+integration suite that requires a reachable MinIO (or any S3-compatible)
+endpoint. The repo's root `docker-compose.yml` exposes one on
+`http://localhost:9000`. Run locally via:
+
+```bash
+docker compose up -d
+yarn vitest run --project Service packages/s3-blob-store
+```
+
+Override the endpoint and credentials with `MINIO_URL`,
+`MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY` when targeting a different
+backend.

package/esm/define-s3-blob-store.d.ts

@@ -0,0 +1,36 @@
+import type { BlobStore } from '@furystack/blob-store';
+import type { ServiceFactory } from '@furystack/inject';
+import { type S3BlobStoreOptions } from './s3-blob-store.js';
+/**
+ * Returns a {@link ServiceFactory} bound to the {@link BlobStore} token,
+ * resolving an {@link S3BlobStore} on first access. The caller still
+ * owns the lifecycle of the supplied `S3Client`.
+ *
+ * @example
+ * ```ts
+ * import { S3Client } from '@aws-sdk/client-s3'
+ * import { createInjector } from '@furystack/inject'
+ * import { BlobStore } from '@furystack/blob-store'
+ * import { defineS3BlobStore } from '@furystack/s3-blob-store'
+ *
+ * const client = new S3Client({
+ *   region: 'eu-central-1',
+ *   credentials: {
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   },
+ * })
+ *
+ * await using injector = createInjector()
+ * injector.bind(
+ *   BlobStore,
+ *   defineS3BlobStore({
+ *     client,
+ *     bucket: 'my-app-blobs',
+ *     keyPrefix: 'tenant-a/',
+ *   }),
+ * )
+ * ```
+ */
+export declare const defineS3BlobStore: (options: S3BlobStoreOptions) => ServiceFactory<BlobStore>;
+//# sourceMappingURL=define-s3-blob-store.d.ts.map

package/esm/define-s3-blob-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-s3-blob-store.d.ts","sourceRoot":"","sources":["../src/define-s3-blob-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,kBAAkB,KAAG,cAAc,CAAC,SAAS,CAOvF,CAAA"}

package/esm/define-s3-blob-store.js

@@ -0,0 +1,41 @@
+import { S3BlobStore } from './s3-blob-store.js';
+/**
+ * Returns a {@link ServiceFactory} bound to the {@link BlobStore} token,
+ * resolving an {@link S3BlobStore} on first access. The caller still
+ * owns the lifecycle of the supplied `S3Client`.
+ *
+ * @example
+ * ```ts
+ * import { S3Client } from '@aws-sdk/client-s3'
+ * import { createInjector } from '@furystack/inject'
+ * import { BlobStore } from '@furystack/blob-store'
+ * import { defineS3BlobStore } from '@furystack/s3-blob-store'
+ *
+ * const client = new S3Client({
+ *   region: 'eu-central-1',
+ *   credentials: {
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   },
+ * })
+ *
+ * await using injector = createInjector()
+ * injector.bind(
+ *   BlobStore,
+ *   defineS3BlobStore({
+ *     client,
+ *     bucket: 'my-app-blobs',
+ *     keyPrefix: 'tenant-a/',
+ *   }),
+ * )
+ * ```
+ */
+export const defineS3BlobStore = (options) => {
+    return ({ onDispose }) => {
+        const store = new S3BlobStore(options);
+        // eslint-disable-next-line furystack/prefer-using-wrapper -- delegated to onDispose
+        onDispose(() => store[Symbol.dispose]());
+        return store;
+    };
+};
+//# sourceMappingURL=define-s3-blob-store.js.map

package/esm/define-s3-blob-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-s3-blob-store.js","sourceRoot":"","sources":["../src/define-s3-blob-store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAA2B,MAAM,oBAAoB,CAAA;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAA2B,EAA6B,EAAE;IAC1F,OAAO,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE;QACvB,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,CAAA;QACtC,oFAAoF;QACpF,SAAS,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QACxC,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;AACH,CAAC,CAAA"}

package/esm/define-s3-blob-store.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=define-s3-blob-store.spec.d.ts.map

package/esm/define-s3-blob-store.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-s3-blob-store.spec.d.ts","sourceRoot":"","sources":["../src/define-s3-blob-store.spec.ts"],"names":[],"mappings":""}

package/esm/define-s3-blob-store.spec.js

@@ -0,0 +1,86 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { describe, expect, it } from 'vitest';
+import { BlobStore } from '@furystack/blob-store';
+import { createInjector } from '@furystack/inject';
+import { defineS3BlobStore } from './define-s3-blob-store.js';
+import { S3BlobStore } from './s3-blob-store.js';
+describe('defineS3BlobStore', () => {
+    it('binds an S3BlobStore on the BlobStore token', async () => {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const injector = __addDisposableResource(env_1, createInjector(), true);
+            injector.bind(BlobStore, defineS3BlobStore({ client: {}, bucket: 'tests', name: 'bound' }));
+            const store = injector.get(BlobStore);
+            expect(store).toBeInstanceOf(S3BlobStore);
+            expect(store.storeName).toBe('bound');
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
+    });
+    it('disposes the store when the injector tears down', async () => {
+        const injector = createInjector();
+        injector.bind(BlobStore, defineS3BlobStore({ client: {}, bucket: 'tests' }));
+        const store = injector.get(BlobStore);
+        await injector[Symbol.asyncDispose]();
+        await expect(store.head('any')).rejects.toMatchObject({ code: 'io-error' });
+    });
+});
+//# sourceMappingURL=define-s3-blob-store.spec.js.map

package/esm/define-s3-blob-store.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-s3-blob-store.spec.js","sourceRoot":"","sources":["../src/define-s3-blob-store.spec.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;;;YAC3D,MAAY,QAAQ,kCAAG,cAAc,EAAE,OAAA,CAAA;YACvC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,MAAM,EAAE,EAAc,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;YACvG,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;YACrC,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAA;YACzC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;;;;;;;;;;;KACtC,CAAC,CAAA;IAEF,EAAE,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;QAC/D,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAA;QACjC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,MAAM,EAAE,EAAc,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;QACxF,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QACrC,MAAM,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAA;QACrC,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAA;IAC7E,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/esm/ensure-bucket-lifecycle.d.ts

@@ -0,0 +1,24 @@
+import { type S3Client } from '@aws-sdk/client-s3';
+/**
+ * Default rule id used when {@link S3BlobStoreOptions.manageLifecycle} is
+ * enabled. Stable, greppable, and easy to remove out-of-band via the AWS
+ * console / CLI.
+ */
+export declare const DEFAULT_LIFECYCLE_RULE_ID = "furystack-blob-store-abort-incomplete-multipart";
+export type EnsureBucketLifecycleOptions = {
+    client: S3Client;
+    bucket: string;
+    ruleId: string;
+    /** Invoked when the lifecycle PUT fails (e.g. missing IAM permission). */
+    onError?: (error: unknown) => void;
+};
+/**
+ * Best-effort bootstrap of the bucket's "abort incomplete multipart" rule.
+ * Swallows errors and forwards them to `onError` — apps surface them via
+ * their own telemetry / logger sink.
+ *
+ * Idempotent at the call site: callers track whether the bootstrap has
+ * been attempted and only call this helper on first put.
+ */
+export declare const ensureBucketLifecycle: (options: EnsureBucketLifecycleOptions) => Promise<void>;
+//# sourceMappingURL=ensure-bucket-lifecycle.d.ts.map

package/esm/ensure-bucket-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-bucket-lifecycle.d.ts","sourceRoot":"","sources":["../src/ensure-bucket-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0C,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAE1F;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,oDAAoD,CAAA;AAE1F,MAAM,MAAM,4BAA4B,GAAG;IACzC,MAAM,EAAE,QAAQ,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CACnC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAU,SAAS,4BAA4B,KAAG,OAAO,CAAC,IAAI,CAqB/F,CAAA"}

package/esm/ensure-bucket-lifecycle.js

@@ -0,0 +1,37 @@
+import { PutBucketLifecycleConfigurationCommand } from '@aws-sdk/client-s3';
+/**
+ * Default rule id used when {@link S3BlobStoreOptions.manageLifecycle} is
+ * enabled. Stable, greppable, and easy to remove out-of-band via the AWS
+ * console / CLI.
+ */
+export const DEFAULT_LIFECYCLE_RULE_ID = 'furystack-blob-store-abort-incomplete-multipart';
+/**
+ * Best-effort bootstrap of the bucket's "abort incomplete multipart" rule.
+ * Swallows errors and forwards them to `onError` — apps surface them via
+ * their own telemetry / logger sink.
+ *
+ * Idempotent at the call site: callers track whether the bootstrap has
+ * been attempted and only call this helper on first put.
+ */
+export const ensureBucketLifecycle = async (options) => {
+    const { client, bucket, ruleId, onError } = options;
+    try {
+        await client.send(new PutBucketLifecycleConfigurationCommand({
+            Bucket: bucket,
+            LifecycleConfiguration: {
+                Rules: [
+                    {
+                        ID: ruleId,
+                        Status: 'Enabled',
+                        Filter: {},
+                        AbortIncompleteMultipartUpload: { DaysAfterInitiation: 1 },
+                    },
+                ],
+            },
+        }));
+    }
+    catch (error) {
+        onError?.(error);
+    }
+};
+//# sourceMappingURL=ensure-bucket-lifecycle.js.map

package/esm/ensure-bucket-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-bucket-lifecycle.js","sourceRoot":"","sources":["../src/ensure-bucket-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sCAAsC,EAAiB,MAAM,oBAAoB,CAAA;AAE1F;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,iDAAiD,CAAA;AAU1F;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,EAAE,OAAqC,EAAiB,EAAE;IAClG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IACnD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CACf,IAAI,sCAAsC,CAAC;YACzC,MAAM,EAAE,MAAM;YACd,sBAAsB,EAAE;gBACtB,KAAK,EAAE;oBACL;wBACE,EAAE,EAAE,MAAM;wBACV,MAAM,EAAE,SAAS;wBACjB,MAAM,EAAE,EAAE;wBACV,8BAA8B,EAAE,EAAE,mBAAmB,EAAE,CAAC,EAAE;qBAC3D;iBACF;aACF;SACF,CAAC,CACH,CAAA;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;IAClB,CAAC;AACH,CAAC,CAAA"}

package/esm/index.d.ts

@@ -0,0 +1,3 @@
+export { defineS3BlobStore } from './define-s3-blob-store.js';
+export { S3BlobStore, S3_MAX_OBJECT_BYTES, type S3BlobStoreOptions } from './s3-blob-store.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAA"}

package/esm/index.js

@@ -0,0 +1,3 @@
+export { defineS3BlobStore } from './define-s3-blob-store.js';
+export { S3BlobStore, S3_MAX_OBJECT_BYTES } from './s3-blob-store.js';
+//# sourceMappingURL=index.js.map

package/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAA2B,MAAM,oBAAoB,CAAA"}

package/esm/s3-blob-store.d.ts

@@ -0,0 +1,82 @@
+import { type S3Client } from '@aws-sdk/client-s3';
+import { type BlobDownloadUrlOptions, type BlobGetResult, type BlobListOptions, type BlobListResult, type BlobMetadata, type BlobPutInput, type BlobPutOptions, type BlobRef, type BlobStore, type BlobStoreCapabilities, type BlobUploadUrl, type BlobUploadUrlOptions } from '@furystack/blob-store';
+/**
+ * 5 TiB — the per-object limit AWS S3 enforces. Other S3-compatible
+ * backends (MinIO, R2) advertise smaller caps in practice; the value
+ * is a soft hint per
+ * {@link BlobStoreCapabilities.maxObjectBytes}.
+ */
+export declare const S3_MAX_OBJECT_BYTES = 5497558138880;
+/**
+ * Options accepted by {@link S3BlobStore}.
+ */
+export type S3BlobStoreOptions = {
+    /**
+     * Caller-owned `S3Client` instance. The adapter never closes it;
+     * connection lifecycle stays with the application.
+     */
+    client: S3Client;
+    /** Bucket every operation runs against. */
+    bucket: string;
+    /**
+     * Optional key prefix prepended to every blob key on the wire. Useful
+     * for tenant scoping inside a shared bucket. Stored without the
+     * prefix in {@link BlobRef.key} so apps round-trip cleanly.
+     */
+    keyPrefix?: string;
+    /**
+     * Adapter binding name. Defaults to `'s3'`. Set to a stable string
+     * when the same injector binds multiple S3 stores so {@link BlobRef}
+     * entries stay distinguishable.
+     */
+    name?: string;
+    /**
+     * When true (default), installs a bucket lifecycle rule that aborts
+     * incomplete multipart uploads older than 24h on first put. Avoids
+     * orphan-multipart cost surprises. Disable for buckets the app
+     * lacks lifecycle permissions on.
+     */
+    manageLifecycle?: boolean;
+    /**
+     * Override the rule id used by `manageLifecycle`. Defaults to
+     * `'furystack-blob-store-abort-incomplete-multipart'` so the rule is
+     * easy to inspect and remove out-of-band.
+     */
+    lifecycleRuleId?: string;
+    /**
+     * Async callback invoked when the lifecycle setup attempt fails.
+     * Defaults to silent — apps wire this into their telemetry / logging
+     * sink to surface permission issues.
+     */
+    onLifecycleError?: (error: unknown) => void;
+};
+/**
+ * S3-compatible {@link BlobStore} adapter. Targets AWS S3, MinIO,
+ * Cloudflare R2, Backblaze B2, and any other backend exposing the v3
+ * S3 API. The caller owns the underlying `S3Client` instance.
+ *
+ * Multipart uploads run automatically via `@aws-sdk/lib-storage`'s
+ * `Upload`; single-part PUT is used for known-small payloads when
+ * `contentLength` is supplied at put time.
+ */
+export declare class S3BlobStore implements BlobStore {
+    #private;
+    readonly capabilities: BlobStoreCapabilities;
+    readonly storeName: string;
+    constructor(options: S3BlobStoreOptions);
+    put(key: string, payload: BlobPutInput, options?: BlobPutOptions): Promise<BlobRef>;
+    get(key: string): Promise<BlobGetResult>;
+    head(key: string): Promise<BlobMetadata | undefined>;
+    delete(key: string): Promise<void>;
+    list(prefix: string, options?: BlobListOptions): Promise<BlobListResult>;
+    getDownloadUrl(key: string, options: BlobDownloadUrlOptions): Promise<string>;
+    getUploadUrl(key: string, options: BlobUploadUrlOptions): Promise<BlobUploadUrl>;
+    [Symbol.dispose](): void;
+    /**
+     * Public helper for tests / advanced consumers: drains a `Body` from an
+     * S3 response into a single `Uint8Array`. Memory-bound — only safe
+     * when the caller knows the payload fits in RAM.
+     */
+    static bodyToBuffer(body: unknown): Promise<Uint8Array>;
+}
+//# sourceMappingURL=s3-blob-store.d.ts.map

package/esm/s3-blob-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-blob-store.d.ts","sourceRoot":"","sources":["../src/s3-blob-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,QAAQ,EACd,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC1B,MAAM,uBAAuB,CAAA;AAI9B;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,gBAAoB,CAAA;AAsBpD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;OAGG;IACH,MAAM,EAAE,QAAQ,CAAA;IAChB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAC5C,CAAA;AAoBD;;;;;;;;GAQG;AACH,qBAAa,WAAY,YAAW,SAAS;;IAC3C,SAAgB,YAAY,EAAE,qBAAqB,CAAe;IAClE,SAAgB,SAAS,EAAE,MAAM,CAAA;gBAWrB,OAAO,EAAE,kBAAkB;IAa1B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IA+CvF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA6BxC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAyBpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAoC5E,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ7E,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IAuBtF,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAI/B;;;;OAIG;WACiB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;CA4BrE"}

package/esm/s3-blob-store.integration.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=s3-blob-store.integration.spec.d.ts.map

package/esm/s3-blob-store.integration.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-blob-store.integration.spec.d.ts","sourceRoot":"","sources":["../src/s3-blob-store.integration.spec.ts"],"names":[],"mappings":""}

package/esm/s3-blob-store.integration.spec.js

@@ -0,0 +1,71 @@
+import { CreateBucketCommand, DeleteBucketCommand, S3Client } from '@aws-sdk/client-s3';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { S3BlobStore } from './s3-blob-store.js';
+const MINIO_URL = process.env.MINIO_URL ?? 'http://localhost:9000';
+const ACCESS_KEY = process.env.MINIO_ACCESS_KEY ?? 'minioadmin';
+const SECRET_KEY = process.env.MINIO_SECRET_KEY ?? 'minioadmin';
+const decode = (data) => new TextDecoder().decode(data);
+const collect = async (stream) => {
+    const reader = stream.getReader();
+    const chunks = [];
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+    }
+    reader.releaseLock();
+    const total = chunks.reduce((acc, c) => acc + c.byteLength, 0);
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return merged;
+};
+describe('S3BlobStore (integration, requires MinIO at $MINIO_URL or http://localhost:9000)', () => {
+    const bucket = `furystack-blob-test-${Date.now()}`;
+    let client;
+    let store;
+    beforeAll(async () => {
+        client = new S3Client({
+            endpoint: MINIO_URL,
+            region: 'us-east-1',
+            forcePathStyle: true,
+            credentials: { accessKeyId: ACCESS_KEY, secretAccessKey: SECRET_KEY },
+        });
+        await client.send(new CreateBucketCommand({ Bucket: bucket }));
+        store = new S3BlobStore({ client, bucket, manageLifecycle: false });
+    });
+    afterAll(async () => {
+        try {
+            const listing = await store.list('');
+            await Promise.all(listing.items.map((item) => store.delete(item.key)));
+            await client.send(new DeleteBucketCommand({ Bucket: bucket }));
+        }
+        finally {
+            store[Symbol.dispose]();
+            client.destroy();
+        }
+    });
+    it('round-trips a buffer payload', async () => {
+        await store.put('greeting.txt', Buffer.from('hello-minio'), { contentType: 'text/plain' });
+        const result = await store.get('greeting.txt');
+        expect(result.contentType).toBe('text/plain');
+        expect(decode(await collect(result.stream))).toBe('hello-minio');
+    });
+    it('lists by prefix', async () => {
+        await store.put('list/a', Buffer.from('1'));
+        await store.put('list/b', Buffer.from('1'));
+        const result = await store.list('list/');
+        expect(result.items.map((i) => i.key).sort()).toEqual(['list/a', 'list/b']);
+    });
+    it('returns not-found on missing get', async () => {
+        await expect(store.get('absent')).rejects.toMatchObject({ code: 'not-found' });
+    });
+    it('returns undefined head for missing keys', async () => {
+        expect(await store.head('absent')).toBeUndefined();
+    });
+});
+//# sourceMappingURL=s3-blob-store.integration.spec.js.map

package/esm/s3-blob-store.integration.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-blob-store.integration.spec.js","sourceRoot":"","sources":["../src/s3-blob-store.integration.spec.ts"],"names":[],"mappings":"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"}