@anabranch/storage-s3 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Frodi Karlsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @anabranch/storage-s3
+
+S3 storage adapter for the anabranch ecosystem. Works with AWS S3, Minio,
+LocalStack, and other S3-compatible APIs.
+
+## Usage
+
+```ts
+import { createS3 } from "@anabranch/storage-s3";
+import { Storage } from "@anabranch/storage";
+
+const connector = createS3({
+  bucket: "my-bucket",
+  region: "us-east-1",
+  credentials: {
+    accessKeyId: "...",
+    secretAccessKey: "...",
+  },
+});
+
+const storage = new Storage(await connector.connect());
+
+await storage.put("hello.txt", "world").run();
+
+const content = await storage.get("hello.txt").run();
+console.log(await new Response(content.body).text());
+```
+
+## Features
+
+- **Concurrent Operations**: Leverage anabranch streams for high-throughput
+  listing and bulk transfers.
+- **Retry & Timeouts**: Composable `Task` primitives allow for robust network
+  resilience.
+- **Prefix Isolation**: Easily scope storage access to a specific path.
+- **Presigned URLs**: Support for temporary GET/PUT access.

package/esm/connector.d.ts

@@ -0,0 +1,23 @@
+import type { StorageConnector, StorageOptions } from "@anabranch/storage";
+/** Options for creating an S3 storage connector. */
+export interface S3StorageOptions extends StorageOptions {
+    bucket: string;
+    region?: string;
+    endpoint?: string;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    forcePathStyle?: boolean;
+    /**
+     * Whether to use connection pooling. Defaults to true.
+     * Disable this in tests to avoid TCP resource leaks.
+     */
+    pooled?: boolean;
+}
+/**
+ * Creates a {@link StorageConnector} for AWS S3 and compatible services.
+ */
+export declare function createS3(options: S3StorageOptions): StorageConnector;
+//# sourceMappingURL=connector.d.ts.map

package/esm/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../src/connector.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAG3E,oDAAoD;AACpD,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE;QACZ,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAwBpE"}

package/esm/connector.js

@@ -0,0 +1,28 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import { NodeHttpHandler } from "@smithy/node-http-handler";
+import { Agent } from "node:https";
+import { Agent as HttpAgent } from "node:http";
+import { S3Adapter } from "./s3.js";
+/**
+ * Creates a {@link StorageConnector} for AWS S3 and compatible services.
+ */
+export function createS3(options) {
+    const pooled = options.pooled ?? true;
+    const client = new S3Client({
+        region: options.region ?? "us-east-1",
+        endpoint: options.endpoint,
+        credentials: options.credentials,
+        forcePathStyle: options.forcePathStyle,
+        requestHandler: pooled ? undefined : new NodeHttpHandler({
+            httpAgent: new HttpAgent({ keepAlive: false }),
+            httpsAgent: new Agent({ keepAlive: false }),
+        }),
+    });
+    return {
+        connect: () => Promise.resolve(new S3Adapter(client, options.bucket, options.prefix ?? "")),
+        end: () => {
+            client.destroy();
+            return Promise.resolve();
+        },
+    };
+}

package/esm/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @anabranch/storage-s3
+ *
+ * S3 adapter for @anabranch/storage using @aws-sdk/client-s3.
+ * Supports presigned URLs, multipart uploads, and all storage operations.
+ *
+ * ## Connector vs Adapter
+ *
+ * A **StorageConnector** produces connected **StorageAdapter** instances. Use
+ * `createS3()` for production code to properly manage S3 connections.
+ *
+ * ## Core Types
+ *
+ * - {@linkcode StorageConnector} - Connection factory for S3
+ * - {@linkcode StorageAdapter} - Low-level storage operations (put, get, delete, head, list)
+ * - {@linkcode PresignableAdapter} - Extended interface with presign() for presigned URLs
+ *
+ * ## Error Types
+ *
+ * All errors are typed for catchable handling:
+ * - {@linkcode StorageObjectNotFound} - Object does not exist
+ * - {@linkcode StoragePutFailed} - Put operation failed
+ * - {@linkcode StorageGetFailed} - Get operation failed
+ * - {@linkcode StorageDeleteFailed} - Delete operation failed
+ * - {@linkcode StorageHeadFailed} - Head operation failed
+ * - {@linkcode StorageListFailed} - List operation failed
+ * - {@linkcode StoragePresignFailed} - Presign operation failed
+ * - {@linkcode StoragePresignNotSupported} - Adapter doesn't support presigning
+ *
+ * @example Concurrent uploads with retry and backpressure
+ * ```ts
+ * import { Task, createS3 } from "@anabranch/storage-s3";
+ * import { Storage } from "@anabranch/storage";
+ *
+ * const connector = createS3({ bucket: "uploads", region: "us-east-1" });
+ * const storage = await Storage.connect(connector).run();
+ *
+ * const files = ["a.txt", "b.txt", "c.txt"];
+ *
+ * await Task.all(
+ *   files.map((file) =>
+ *     storage.put(file, Deno.readFileSync(`./${file}`))
+ *       .retry({ attempts: 3, delay: (i) => 500 * Math.pow(2, i) })
+ *       .timeout(30_000)
+ *   )
+ * ).run();
+ * ```
+ *
+ * @example Upload with presigned URL and result handling
+ * ```ts
+ * import { Task, createS3 } from "@anabranch/storage-s3";
+ * import { Storage } from "@anabranch/storage";
+ *
+ * const connector = createS3({ bucket: "images", region: "us-east-1" });
+ * const storage = await Storage.connect(connector).run();
+ *
+ * const result = await storage
+ *   .presign("photo.jpg", { method: "PUT", expiresIn: 3600 })
+ *   .result();
+ *
+ * if (result.type === "error") {
+ *   console.error("Failed to generate upload URL:", result.error);
+ *   return;
+ * }
+ *
+ * const uploadUrl = result.value;
+ *
+ * await Task.of(async () => {
+ *   const response = await fetch(uploadUrl, {
+ *     method: "PUT",
+ *     body: await Deno.readFile("photo.jpg"),
+ *     headers: { "Content-Type": "image/jpeg" },
+ *   });
+ *   if (!response.ok) throw new Error("Upload failed");
+ * })
+ * .retry({ attempts: 3 })
+ * .timeout(60_000)
+ * .run();
+ * ```
+ *
+ * @example Process list results with concurrency limits
+ * ```ts
+ * const storage = await Storage.connect(
+ *   createS3({ bucket: "logs", prefix: "archive/" })
+ * ).run();
+ *
+ * const { successes, errors } = await storage.list()
+ *   .withConcurrency(10)
+ *   .map(async (entry) => {
+ *     const obj = await storage.get(entry.key).run();
+ *     const text = await new Response(obj.body).text();
+ *     return { key: entry.key, lines: text.split("\n").length };
+ *   })
+ *   .tapErr((err) => console.error("Failed processing:", err))
+ *   .partition();
+ *
+ * console.log(`Processed ${successes.length} files with ${errors.length} errors`);
+ * ```
+ *
+ * @module
+ */
+export { S3Adapter } from "./s3.js";
+export { createS3 } from "./connector.js";
+export type { S3StorageOptions } from "./connector.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/esm/index.js

@@ -0,0 +1,103 @@
+/**
+ * @anabranch/storage-s3
+ *
+ * S3 adapter for @anabranch/storage using @aws-sdk/client-s3.
+ * Supports presigned URLs, multipart uploads, and all storage operations.
+ *
+ * ## Connector vs Adapter
+ *
+ * A **StorageConnector** produces connected **StorageAdapter** instances. Use
+ * `createS3()` for production code to properly manage S3 connections.
+ *
+ * ## Core Types
+ *
+ * - {@linkcode StorageConnector} - Connection factory for S3
+ * - {@linkcode StorageAdapter} - Low-level storage operations (put, get, delete, head, list)
+ * - {@linkcode PresignableAdapter} - Extended interface with presign() for presigned URLs
+ *
+ * ## Error Types
+ *
+ * All errors are typed for catchable handling:
+ * - {@linkcode StorageObjectNotFound} - Object does not exist
+ * - {@linkcode StoragePutFailed} - Put operation failed
+ * - {@linkcode StorageGetFailed} - Get operation failed
+ * - {@linkcode StorageDeleteFailed} - Delete operation failed
+ * - {@linkcode StorageHeadFailed} - Head operation failed
+ * - {@linkcode StorageListFailed} - List operation failed
+ * - {@linkcode StoragePresignFailed} - Presign operation failed
+ * - {@linkcode StoragePresignNotSupported} - Adapter doesn't support presigning
+ *
+ * @example Concurrent uploads with retry and backpressure
+ * ```ts
+ * import { Task, createS3 } from "@anabranch/storage-s3";
+ * import { Storage } from "@anabranch/storage";
+ *
+ * const connector = createS3({ bucket: "uploads", region: "us-east-1" });
+ * const storage = await Storage.connect(connector).run();
+ *
+ * const files = ["a.txt", "b.txt", "c.txt"];
+ *
+ * await Task.all(
+ *   files.map((file) =>
+ *     storage.put(file, Deno.readFileSync(`./${file}`))
+ *       .retry({ attempts: 3, delay: (i) => 500 * Math.pow(2, i) })
+ *       .timeout(30_000)
+ *   )
+ * ).run();
+ * ```
+ *
+ * @example Upload with presigned URL and result handling
+ * ```ts
+ * import { Task, createS3 } from "@anabranch/storage-s3";
+ * import { Storage } from "@anabranch/storage";
+ *
+ * const connector = createS3({ bucket: "images", region: "us-east-1" });
+ * const storage = await Storage.connect(connector).run();
+ *
+ * const result = await storage
+ *   .presign("photo.jpg", { method: "PUT", expiresIn: 3600 })
+ *   .result();
+ *
+ * if (result.type === "error") {
+ *   console.error("Failed to generate upload URL:", result.error);
+ *   return;
+ * }
+ *
+ * const uploadUrl = result.value;
+ *
+ * await Task.of(async () => {
+ *   const response = await fetch(uploadUrl, {
+ *     method: "PUT",
+ *     body: await Deno.readFile("photo.jpg"),
+ *     headers: { "Content-Type": "image/jpeg" },
+ *   });
+ *   if (!response.ok) throw new Error("Upload failed");
+ * })
+ * .retry({ attempts: 3 })
+ * .timeout(60_000)
+ * .run();
+ * ```
+ *
+ * @example Process list results with concurrency limits
+ * ```ts
+ * const storage = await Storage.connect(
+ *   createS3({ bucket: "logs", prefix: "archive/" })
+ * ).run();
+ *
+ * const { successes, errors } = await storage.list()
+ *   .withConcurrency(10)
+ *   .map(async (entry) => {
+ *     const obj = await storage.get(entry.key).run();
+ *     const text = await new Response(obj.body).text();
+ *     return { key: entry.key, lines: text.split("\n").length };
+ *   })
+ *   .tapErr((err) => console.error("Failed processing:", err))
+ *   .partition();
+ *
+ * console.log(`Processed ${successes.length} files with ${errors.length} errors`);
+ * ```
+ *
+ * @module
+ */
+export { S3Adapter } from "./s3.js";
+export { createS3 } from "./connector.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/s3.d.ts

@@ -0,0 +1,24 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import type { BodyInput, PresignableAdapter, PresignOptions, PutOptions, StorageEntry, StorageMetadata, StorageObject } from "@anabranch/storage";
+/**
+ * Adapter for AWS S3 and compatible services (Minio, LocalStack, etc.).
+ */
+export declare class S3Adapter implements PresignableAdapter {
+    private readonly client;
+    private readonly bucket;
+    private readonly prefix;
+    constructor(client: S3Client, bucket: string, prefix: string);
+    put(key: string, body: BodyInput, options?: PutOptions): Promise<void>;
+    get(key: string): Promise<StorageObject>;
+    /**
+     * Deletes an object from S3. This operation is idempotent; it returns
+     * successfully even if the object does not exist.
+     */
+    delete(key: string): Promise<void>;
+    head(key: string): Promise<StorageMetadata>;
+    list(prefix?: string): AsyncIterable<StorageEntry>;
+    presign(key: string, options: PresignOptions): Promise<string>;
+    close(): Promise<void>;
+    private isNotFound;
+}
+//# sourceMappingURL=s3.d.ts.map

package/esm/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EACV,SAAS,EACT,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,YAAY,EACZ,eAAe,EACf,aAAa,EACd,MAAM,oBAAoB,CAAC;AAW5B;;GAEG;AACH,qBAAa,SAAU,YAAW,kBAAkB;IAEhD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;IAG3B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBtE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAqC9C;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBlC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA8BjD,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC;IA0C5C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBpE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,OAAO,CAAC,UAAU;CAWnB"}

package/esm/s3.js

@@ -0,0 +1,167 @@
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { StorageDeleteFailed, StorageGetFailed, StorageHeadFailed, StorageListFailed, StorageObjectNotFound, StoragePresignFailed, StoragePutFailed, } from "@anabranch/storage";
+/**
+ * Adapter for AWS S3 and compatible services (Minio, LocalStack, etc.).
+ */
+export class S3Adapter {
+    constructor(client, bucket, prefix) {
+        Object.defineProperty(this, "client", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: client
+        });
+        Object.defineProperty(this, "bucket", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: bucket
+        });
+        Object.defineProperty(this, "prefix", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: prefix
+        });
+    }
+    async put(key, body, options) {
+        const fullKey = this.prefix + key;
+        try {
+            await this.client.send(new PutObjectCommand({
+                Bucket: this.bucket,
+                Key: fullKey,
+                Body: body,
+                ContentType: options?.contentType,
+                Metadata: options?.custom,
+            }));
+        }
+        catch (error) {
+            throw new StoragePutFailed(key, error instanceof Error ? error.message : String(error), error);
+        }
+    }
+    async get(key) {
+        const fullKey = this.prefix + key;
+        try {
+            const response = await this.client.send(new GetObjectCommand({
+                Bucket: this.bucket,
+                Key: fullKey,
+            }));
+            if (!response.Body) {
+                throw new Error("Empty body in S3 response");
+            }
+            return {
+                body: response.Body.transformToWebStream(),
+                metadata: {
+                    key,
+                    size: response.ContentLength ?? 0,
+                    etag: response.ETag,
+                    lastModified: response.LastModified ?? new Date(),
+                    contentType: response.ContentType,
+                    custom: response.Metadata,
+                },
+            };
+        }
+        catch (error) {
+            if (this.isNotFound(error)) {
+                throw new StorageObjectNotFound(key);
+            }
+            throw new StorageGetFailed(key, error instanceof Error ? error.message : String(error), error);
+        }
+    }
+    /**
+     * Deletes an object from S3. This operation is idempotent; it returns
+     * successfully even if the object does not exist.
+     */
+    async delete(key) {
+        const fullKey = this.prefix + key;
+        try {
+            await this.client.send(new DeleteObjectCommand({
+                Bucket: this.bucket,
+                Key: fullKey,
+            }));
+        }
+        catch (error) {
+            throw new StorageDeleteFailed(key, error instanceof Error ? error.message : String(error), error);
+        }
+    }
+    async head(key) {
+        const fullKey = this.prefix + key;
+        try {
+            const response = await this.client.send(new HeadObjectCommand({
+                Bucket: this.bucket,
+                Key: fullKey,
+            }));
+            return {
+                key,
+                size: response.ContentLength ?? 0,
+                etag: response.ETag,
+                lastModified: response.LastModified ?? new Date(),
+                contentType: response.ContentType,
+                custom: response.Metadata,
+            };
+        }
+        catch (error) {
+            if (this.isNotFound(error)) {
+                throw new StorageObjectNotFound(key);
+            }
+            throw new StorageHeadFailed(key, error instanceof Error ? error.message : String(error), error);
+        }
+    }
+    list(prefix) {
+        const searchPrefix = this.prefix + (prefix ?? "");
+        const client = this.client;
+        const bucket = this.bucket;
+        const rootPrefix = this.prefix;
+        return (async function* () {
+            let continuationToken;
+            try {
+                do {
+                    const response = await client.send(new ListObjectsV2Command({
+                        Bucket: bucket,
+                        Prefix: searchPrefix,
+                        ContinuationToken: continuationToken,
+                    }));
+                    if (response.Contents) {
+                        for (const item of response.Contents) {
+                            if (item.Key) {
+                                yield {
+                                    key: item.Key.slice(rootPrefix.length),
+                                    size: item.Size ?? 0,
+                                    lastModified: item.LastModified ?? new Date(),
+                                };
+                            }
+                        }
+                    }
+                    continuationToken = response.NextContinuationToken;
+                } while (continuationToken);
+            }
+            catch (error) {
+                throw new StorageListFailed(searchPrefix, error instanceof Error ? error.message : String(error), error);
+            }
+        })();
+    }
+    async presign(key, options) {
+        const fullKey = this.prefix + key;
+        try {
+            const command = options.method === "PUT"
+                ? new PutObjectCommand({ Bucket: this.bucket, Key: fullKey })
+                : new GetObjectCommand({ Bucket: this.bucket, Key: fullKey });
+            return await getSignedUrl(this.client, command, {
+                expiresIn: options.expiresIn,
+            });
+        }
+        catch (error) {
+            throw new StoragePresignFailed(key, error instanceof Error ? error.message : String(error), error);
+        }
+    }
+    close() {
+        return Promise.resolve();
+    }
+    isNotFound(error) {
+        const err = error;
+        return (err.name === "NoSuchKey" ||
+            err.name === "NotFound" ||
+            err.$metadata?.httpStatusCode === 404);
+    }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@anabranch/storage-s3",
+  "version": "0.1.0",
+  "description": "S3 storage adapter for the anabranch ecosystem",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frodi-karlsson/anabranch.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/frodi-karlsson/anabranch.git"
+  },
+  "module": "./esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./esm/index.js"
+    }
+  },
+  "scripts": {},
+  "dependencies": {
+    "@anabranch/storage": "^0",
+    "@aws-sdk/client-s3": "^3",
+    "@aws-sdk/s3-request-presigner": "^3",
+    "@smithy/node-http-handler": "*",
+    "anabranch": "^0"
+  },
+  "_generatedBy": "dnt@dev"
+}