@anabranch/storage 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,6 @@
+# @anabranch/storage
+
+Object storage primitives with Task/Stream semantics for error-tolerant
+operations.
+
+See [index.ts](./index.ts) for full documentation and examples.

package/esm/adapter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Input body types for put operations.
+ */
+export type BodyInput = Uint8Array | ReadableStream | string;
+/**
+ * Object metadata returned by head operations and included with get results.
+ */
+export interface StorageMetadata {
+    key: string;
+    size: number;
+    etag?: string;
+    lastModified: Date;
+    contentType?: string;
+    custom?: Record<string, string>;
+}
+/**
+ * Object returned by get operations, containing a body stream and metadata.
+ */
+export interface StorageObject {
+    body: ReadableStream;
+    metadata: StorageMetadata;
+}
+/**
+ * Entry returned by list operations.
+ */
+export interface StorageEntry {
+    key: string;
+    size: number;
+    lastModified: Date;
+}
+/** Options for put operations. */
+export interface PutOptions {
+    contentType?: string;
+    custom?: Record<string, string>;
+}
+/** Options for presign operations. */
+export interface PresignOptions {
+    expiresIn: number;
+    method?: "GET" | "PUT";
+}
+/**
+ * Low-level storage adapter interface.
+ * Implement this to create drivers for specific storage backends.
+ */
+export interface StorageAdapter {
+    /** Put an object into storage. */
+    put(key: string, body: BodyInput, options?: PutOptions): Promise<void>;
+    /** Get an object from storage. */
+    get(key: string): Promise<StorageObject>;
+    /** Delete an object from storage. */
+    delete(key: string): Promise<void>;
+    /** Get metadata without fetching the body. */
+    head(key: string): Promise<StorageMetadata>;
+    /** List objects with optional prefix. */
+    list(prefix?: string): AsyncIterable<StorageEntry>;
+    /** Release the connection back to its source. */
+    close(): Promise<void>;
+}
+/**
+ * Extended adapter interface for backends that support presigned URLs.
+ */
+export interface PresignableAdapter extends StorageAdapter {
+    /** Generate a presigned URL for direct access. */
+    presign(key: string, options?: PresignOptions): Promise<string>;
+}
+/** Connector that produces connected StorageAdapter instances. */
+export interface StorageConnector {
+    /** Acquire a connected adapter. */
+    connect(signal?: AbortSignal): Promise<StorageAdapter>;
+    /** Close all connections and clean up resources. */
+    end(): Promise<void>;
+}
+/** Storage configuration options. */
+export interface StorageOptions {
+    /** Prefix for all keys in this storage. */
+    prefix?: string;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/esm/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,cAAc,GAAG,MAAM,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,IAAI,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,IAAI,CAAC;CACpB;AAED,kCAAkC;AAClC,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kCAAkC;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACzC,qCAAqC;IACrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,8CAA8C;IAC9C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5C,yCAAyC;IACzC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IACnD,iDAAiD;IACjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,kDAAkD;IAClD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACjE;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACvD,oDAAoD;IACpD,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/esm/adapter.js

@@ -0,0 +1 @@
+export {};

package/esm/connector.d.ts

@@ -0,0 +1,14 @@
+import type { StorageConnector, StorageOptions } from "./adapter.js";
+/**
+ * Creates an in-memory storage connector for testing.
+ * Data is stored in memory and lost when the process ends.
+ *
+ * @example
+ * ```ts
+ * const connector = createMemory({ prefix: "files/" });
+ * const storage = await connector.connect();
+ * await storage.put("test.txt", "Hello");
+ * ```
+ */
+export declare function createMemory(options?: StorageOptions): 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":"AAAA,OAAO,KAAK,EAGV,gBAAgB,EAEhB,cAAc,EACf,MAAM,cAAc,CAAC;AAKtB;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,gBAAgB,CAuFvE"}

package/esm/connector.js

@@ -0,0 +1,114 @@
+import { StorageObjectNotFound } from "./errors.js";
+const encoder = new TextEncoder();
+/**
+ * Creates an in-memory storage connector for testing.
+ * Data is stored in memory and lost when the process ends.
+ *
+ * @example
+ * ```ts
+ * const connector = createMemory({ prefix: "files/" });
+ * const storage = await connector.connect();
+ * await storage.put("test.txt", "Hello");
+ * ```
+ */
+export function createMemory(options) {
+    const prefix = options?.prefix ?? "";
+    const data = new Map();
+    const metadata = new Map();
+    return {
+        connect: () => {
+            return Promise.resolve({
+                put: async (key, body, opts) => {
+                    const fullKey = prefix + key;
+                    const bytes = typeof body === "string"
+                        ? encoder.encode(body)
+                        : body instanceof ReadableStream
+                            ? await bytesFromStream(body)
+                            : body;
+                    data.set(fullKey, bytes);
+                    const size = bytes.length;
+                    const lastModified = new Date();
+                    metadata.set(fullKey, {
+                        key: fullKey,
+                        size,
+                        lastModified,
+                        contentType: opts?.contentType,
+                        custom: opts?.custom,
+                    });
+                },
+                get: (key) => {
+                    const fullKey = prefix + key;
+                    const bytes = data.get(fullKey);
+                    if (!bytes) {
+                        return Promise.reject(new StorageObjectNotFound(key));
+                    }
+                    const meta = metadata.get(fullKey);
+                    if (!meta) {
+                        return Promise.reject(new StorageObjectNotFound(key));
+                    }
+                    return Promise.resolve({
+                        body: new ReadableStream({
+                            start(controller) {
+                                controller.enqueue(bytes);
+                                controller.close();
+                            },
+                        }),
+                        metadata: { ...meta },
+                    });
+                },
+                delete: (key) => {
+                    const fullKey = prefix + key;
+                    data.delete(fullKey);
+                    metadata.delete(fullKey);
+                    return Promise.resolve();
+                },
+                head: (key) => {
+                    const fullKey = prefix + key;
+                    const meta = metadata.get(fullKey);
+                    if (!meta) {
+                        return Promise.reject(new StorageObjectNotFound(key));
+                    }
+                    return Promise.resolve({ ...meta });
+                },
+                list: (p) => {
+                    const searchPrefix = prefix + (p ?? "");
+                    return (async function* () {
+                        for (const [key, meta] of metadata) {
+                            if (key.startsWith(searchPrefix)) {
+                                yield {
+                                    key,
+                                    size: meta.size,
+                                    lastModified: meta.lastModified,
+                                };
+                            }
+                        }
+                    })();
+                },
+                close: () => Promise.resolve(),
+            });
+        },
+        end: () => {
+            data.clear();
+            metadata.clear();
+            return Promise.resolve();
+        },
+    };
+}
+async function bytesFromStream(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+    }
+    const total = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+    const result = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return result;
+}

package/esm/errors.d.ts

@@ -0,0 +1,37 @@
+export declare class StorageConnectionFailed extends Error {
+    name: string;
+    constructor(message: string, cause?: unknown);
+}
+export declare class StorageObjectNotFound extends Error {
+    name: string;
+    constructor(key: string);
+}
+export declare class StorageCloseFailed extends Error {
+    name: string;
+    constructor(message: string, cause?: unknown);
+}
+export declare class StoragePutFailed extends Error {
+    name: string;
+    constructor(key: string, message: string, cause?: unknown);
+}
+export declare class StorageGetFailed extends Error {
+    name: string;
+    constructor(key: string, message: string, cause?: unknown);
+}
+export declare class StorageDeleteFailed extends Error {
+    name: string;
+    constructor(key: string, message: string, cause?: unknown);
+}
+export declare class StorageHeadFailed extends Error {
+    name: string;
+    constructor(key: string, message: string, cause?: unknown);
+}
+export declare class StoragePresignFailed extends Error {
+    name: string;
+    constructor(key: string, message: string, cause?: unknown);
+}
+export declare class StorageListFailed extends Error {
+    name: string;
+    constructor(prefix: string | undefined, message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,uBAAwB,SAAQ,KAAK;IACvC,IAAI,SAA6B;gBAExC,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAIlB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IACrC,IAAI,SAA2B;gBAC5B,GAAG,EAAE,MAAM;CAGxB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAClC,IAAI,SAAwB;gBAEnC,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAIlB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,SAAsB;gBAEjC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAIlB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,SAAsB;gBAEjC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAIlB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IACnC,IAAI,SAAyB;gBAEpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAIlB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IACjC,IAAI,SAAuB;gBAElC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAIlB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IACpC,IAAI,SAA0B;gBAErC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAIlB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IACjC,IAAI,SAAuB;gBAElC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CASlB"}

package/esm/errors.js

@@ -0,0 +1,99 @@
+export class StorageConnectionFailed extends Error {
+    constructor(message, cause) {
+        super(`Storage connection failed: ${message}`, { cause });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "StorageConnectionFailed"
+        });
+    }
+}
+export class StorageObjectNotFound extends Error {
+    constructor(key) {
+        super(`Storage object not found: ${key}`);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "StorageObjectNotFound"
+        });
+    }
+}
+export class StorageCloseFailed extends Error {
+    constructor(message, cause) {
+        super(`Storage close failed: ${message}`, { cause });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "StorageCloseFailed"
+        });
+    }
+}
+export class StoragePutFailed extends Error {
+    constructor(key, message, cause) {
+        super(`Failed to put object ${key}: ${message}`, { cause });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "StoragePutFailed"
+        });
+    }
+}
+export class StorageGetFailed extends Error {
+    constructor(key, message, cause) {
+        super(`Failed to get object ${key}: ${message}`, { cause });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "StorageGetFailed"
+        });
+    }
+}
+export class StorageDeleteFailed extends Error {
+    constructor(key, message, cause) {
+        super(`Failed to delete object ${key}: ${message}`, { cause });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "StorageDeleteFailed"
+        });
+    }
+}
+export class StorageHeadFailed extends Error {
+    constructor(key, message, cause) {
+        super(`Failed to head object ${key}: ${message}`, { cause });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "StorageHeadFailed"
+        });
+    }
+}
+export class StoragePresignFailed extends Error {
+    constructor(key, message, cause) {
+        super(`Failed to presign object ${key}: ${message}`, { cause });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "StoragePresignFailed"
+        });
+    }
+}
+export class StorageListFailed extends Error {
+    constructor(prefix, message, cause) {
+        super(`Failed to list objects${prefix ? ` with prefix "${prefix}"` : ""}: ${message}`, { cause });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "StorageListFailed"
+        });
+    }
+}

package/esm/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @anabranch/storage
+ *
+ * Storage primitives with Task/Stream semantics for error-tolerant object operations.
+ * Integrates with anabranch's {@linkcode Task}, {@linkcode Stream}, {@linkcode Source},
+ * and {@linkcode Channel} types for composable error handling and concurrent processing.
+ *
+ * ## Adapters vs Connectors
+ *
+ * A **StorageConnector** produces connected **StorageAdapter** instances. Use connectors
+ * for production code to properly manage connection lifecycles:
+ *
+ * - **Connector**: Manages connection pool/lifecycle, produces adapters
+ * - **Adapter**: Low-level put/get/delete/list interface
+ * - **Storage**: High-level wrapper with Task/Stream methods
+ *
+ * ## Core Types
+ *
+ * - {@link StorageConnector} - Interface for connection factories
+ * - {@link StorageAdapter} - Low-level storage operations interface
+ * - {@link StorageObject} - Retrieved object with body stream and metadata
+ * - {@link StorageMetadata} - Object metadata (size, contentType, etag, etc.)
+ *
+ * ## Error Types
+ *
+ * All errors are typed for catchable handling:
+ * - {@link StorageConnectionFailed} - Connection establishment failed
+ * - {@link StorageObjectNotFound} - Object does not exist
+ * - {@link StoragePutFailed} - Put operation failed
+ * - {@link StorageGetFailed} - Get operation failed
+ * - {@link StorageDeleteFailed} - Delete operation failed
+ * - {@link StorageHeadFailed} - Head operation failed
+ *
+ * @example Basic put/get operations with Storage wrapper
+ * ```ts
+ * import { Storage, createMemory } from "@anabranch/storage";
+ *
+ * const connector = createMemory({ prefix: "files/" });
+ * const storage = await Storage.connect(connector).run();
+ *
+ * await storage.put("hello.txt", "Hello, World!").run();
+ * const object = await storage.get("hello.txt").run();
+ * console.log(await new Response(object.body).text());
+ * ```
+ *
+ * @example Stream listing with concurrent processing
+ * ```ts
+ * const connector = createMemory();
+ * const storage = await Storage.connect(connector).run();
+ *
+ * await storage.put("users/1.json", '{"name": "Alice"}');
+ * await storage.put("users/2.json", '{"name": "Bob"}');
+ *
+ * const { successes, errors } = await storage.list("users/")
+ *   .withConcurrency(5)
+ *   .map(async (entry) => await processEntry(entry))
+ *   .tapErr((err) => console.error("Failed:", err))
+ *   .partition();
+ * ```
+ *
+ * @example Head request for metadata
+ * ```ts
+ * import { Storage, createMemory } from "@anabranch/storage";
+ *
+ * const connector = createMemory();
+ * const storage = await Storage.connect(connector).run();
+ *
+ * await storage.put("image.png", imageBytes, { contentType: "image/png" }).run();
+ * const metadata = await storage.head("image.png").run();
+ * console.log(metadata.contentType, metadata.size);
+ * ```
+ *
+ * @example With retry and timeout
+ * ```ts
+ * await storage.put("important.txt", data)
+ *   .retry({ attempts: 3, delay: (attempt) => 100 * Math.pow(2, attempt) })
+ *   .timeout(30_000)
+ *   .run();
+ * ```
+ *
+ * @module
+ */
+export { Storage } from "./storage.js";
+export type { BodyInput, PresignableAdapter, PresignOptions, PutOptions, StorageAdapter, StorageConnector, StorageEntry, StorageMetadata, StorageObject, StorageOptions, } from "./adapter.js";
+export * from "./errors.js";
+export { createMemory } 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EACV,SAAS,EACT,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/esm/index.js

@@ -0,0 +1,85 @@
+/**
+ * @anabranch/storage
+ *
+ * Storage primitives with Task/Stream semantics for error-tolerant object operations.
+ * Integrates with anabranch's {@linkcode Task}, {@linkcode Stream}, {@linkcode Source},
+ * and {@linkcode Channel} types for composable error handling and concurrent processing.
+ *
+ * ## Adapters vs Connectors
+ *
+ * A **StorageConnector** produces connected **StorageAdapter** instances. Use connectors
+ * for production code to properly manage connection lifecycles:
+ *
+ * - **Connector**: Manages connection pool/lifecycle, produces adapters
+ * - **Adapter**: Low-level put/get/delete/list interface
+ * - **Storage**: High-level wrapper with Task/Stream methods
+ *
+ * ## Core Types
+ *
+ * - {@link StorageConnector} - Interface for connection factories
+ * - {@link StorageAdapter} - Low-level storage operations interface
+ * - {@link StorageObject} - Retrieved object with body stream and metadata
+ * - {@link StorageMetadata} - Object metadata (size, contentType, etag, etc.)
+ *
+ * ## Error Types
+ *
+ * All errors are typed for catchable handling:
+ * - {@link StorageConnectionFailed} - Connection establishment failed
+ * - {@link StorageObjectNotFound} - Object does not exist
+ * - {@link StoragePutFailed} - Put operation failed
+ * - {@link StorageGetFailed} - Get operation failed
+ * - {@link StorageDeleteFailed} - Delete operation failed
+ * - {@link StorageHeadFailed} - Head operation failed
+ *
+ * @example Basic put/get operations with Storage wrapper
+ * ```ts
+ * import { Storage, createMemory } from "@anabranch/storage";
+ *
+ * const connector = createMemory({ prefix: "files/" });
+ * const storage = await Storage.connect(connector).run();
+ *
+ * await storage.put("hello.txt", "Hello, World!").run();
+ * const object = await storage.get("hello.txt").run();
+ * console.log(await new Response(object.body).text());
+ * ```
+ *
+ * @example Stream listing with concurrent processing
+ * ```ts
+ * const connector = createMemory();
+ * const storage = await Storage.connect(connector).run();
+ *
+ * await storage.put("users/1.json", '{"name": "Alice"}');
+ * await storage.put("users/2.json", '{"name": "Bob"}');
+ *
+ * const { successes, errors } = await storage.list("users/")
+ *   .withConcurrency(5)
+ *   .map(async (entry) => await processEntry(entry))
+ *   .tapErr((err) => console.error("Failed:", err))
+ *   .partition();
+ * ```
+ *
+ * @example Head request for metadata
+ * ```ts
+ * import { Storage, createMemory } from "@anabranch/storage";
+ *
+ * const connector = createMemory();
+ * const storage = await Storage.connect(connector).run();
+ *
+ * await storage.put("image.png", imageBytes, { contentType: "image/png" }).run();
+ * const metadata = await storage.head("image.png").run();
+ * console.log(metadata.contentType, metadata.size);
+ * ```
+ *
+ * @example With retry and timeout
+ * ```ts
+ * await storage.put("important.txt", data)
+ *   .retry({ attempts: 3, delay: (attempt) => 100 * Math.pow(2, attempt) })
+ *   .timeout(30_000)
+ *   .run();
+ * ```
+ *
+ * @module
+ */
+export { Storage } from "./storage.js";
+export * from "./errors.js";
+export { createMemory } from "./connector.js";

package/esm/package.json

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

package/esm/storage.d.ts

@@ -0,0 +1,108 @@
+import { Source, Task } from "anabranch";
+import type { BodyInput, PutOptions, StorageAdapter, StorageConnector, StorageEntry, StorageMetadata, StorageObject } from "./adapter.js";
+import { StorageCloseFailed, StorageConnectionFailed, StorageDeleteFailed, StorageGetFailed, StorageHeadFailed, StorageListFailed, StorageObjectNotFound, StoragePutFailed } from "./errors.js";
+/**
+ * Storage wrapper with Task/Stream semantics for error-tolerant object operations.
+ *
+ * @example Basic put/get operations
+ * ```ts
+ * import { Storage, createMemory } from "@anabranch/storage";
+ *
+ * const connector = createMemory();
+ * const storage = await Storage.connect(connector).run();
+ *
+ * await storage.put("hello.txt", "Hello, World!").run();
+ * const object = await storage.get("hello.txt").run();
+ * ```
+ *
+ * @example Stream listing objects
+ * ```ts
+ * const { successes, errors } = await storage.list("users/")
+ *   .withConcurrency(5)
+ *   .map(async (entry) => await processEntry(entry))
+ *   .tapErr((err) => console.error("Failed:", err))
+ *   .partition();
+ * ```
+ *
+ * @example With retry and timeout
+ * ```ts
+ * await storage.put("important.txt", data)
+ *   .retry({ attempts: 3, delay: (attempt) => 100 * Math.pow(2, attempt) })
+ *   .timeout(30_000)
+ *   .run();
+ * ```
+ */
+export declare class Storage {
+    private readonly adapter;
+    constructor(adapter: StorageAdapter);
+    /**
+     * Connect to storage via a connector.
+     *
+     * @example
+     * ```ts
+     * const storage = await Storage.connect(createMemory()).run();
+     * ```
+     */
+    static connect(connector: StorageConnector): Task<Storage, StorageConnectionFailed>;
+    /**
+     * Release the connection back to its source (e.g., pool).
+     *
+     * @example
+     * ```ts
+     * await storage.close().run();
+     * ```
+     */
+    close(): Task<void, StorageCloseFailed>;
+    /**
+     * Put an object into storage.
+     *
+     * @example
+     * ```ts
+     * await storage.put("image.png", imageBytes, { contentType: "image/png" }).run();
+     * ```
+     */
+    put(key: string, body: BodyInput, options?: PutOptions): Task<void, StoragePutFailed>;
+    /**
+     * Get an object from storage.
+     *
+     * @example
+     * ```ts
+     * const object = await storage.get("file.txt").run();
+     * const text = await new Response(object.body).text();
+     * ```
+     */
+    get(key: string): Task<StorageObject, StorageGetFailed | StorageObjectNotFound>;
+    /**
+     * Delete an object from storage.
+     *
+     * @example
+     * ```ts
+     * await storage.delete("old-file.txt").run();
+     * ```
+     */
+    delete(key: string): Task<void, StorageDeleteFailed>;
+    /**
+     * Get metadata for an object without fetching the body.
+     *
+     * @example
+     * ```ts
+     * const metadata = await storage.head("file.txt").run();
+     * console.log(metadata.size, metadata.contentType);
+     * ```
+     */
+    head(key: string): Task<StorageMetadata, StorageHeadFailed | StorageObjectNotFound>;
+    /**
+     * List objects in storage with optional prefix.
+     *
+     * @example
+     * ```ts
+     * const { successes, errors } = await storage.list("images/")
+     *   .withConcurrency(10)
+     *   .map(async (entry) => await processImage(entry))
+     *   .tapErr((err) => console.error("Failed:", err))
+     *   .partition();
+     * ```
+     */
+    list(prefix?: string): Source<StorageEntry, StorageListFailed>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/esm/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,aAAa,EACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,CACZ,SAAS,EAAE,gBAAgB,GAC1B,IAAI,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAazC;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAavC;;;;;;;OAOG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAc/B;;;;;;;;OAQG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,GACV,IAAI,CAAC,aAAa,EAAE,gBAAgB,GAAG,qBAAqB,CAAC;IAiBhE;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAcpD;;;;;;;;OAQG;IACH,IAAI,CACF,GAAG,EAAE,MAAM,GACV,IAAI,CAAC,eAAe,EAAE,iBAAiB,GAAG,qBAAqB,CAAC;IAiBnE;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,YAAY,EAAE,iBAAiB,CAAC;CAkB/D"}

package/esm/storage.js

@@ -0,0 +1,184 @@
+import { Source, Task } from "anabranch";
+import { StorageCloseFailed, StorageConnectionFailed, StorageDeleteFailed, StorageGetFailed, StorageHeadFailed, StorageListFailed, StorageObjectNotFound, StoragePutFailed, } from "./errors.js";
+/**
+ * Storage wrapper with Task/Stream semantics for error-tolerant object operations.
+ *
+ * @example Basic put/get operations
+ * ```ts
+ * import { Storage, createMemory } from "@anabranch/storage";
+ *
+ * const connector = createMemory();
+ * const storage = await Storage.connect(connector).run();
+ *
+ * await storage.put("hello.txt", "Hello, World!").run();
+ * const object = await storage.get("hello.txt").run();
+ * ```
+ *
+ * @example Stream listing objects
+ * ```ts
+ * const { successes, errors } = await storage.list("users/")
+ *   .withConcurrency(5)
+ *   .map(async (entry) => await processEntry(entry))
+ *   .tapErr((err) => console.error("Failed:", err))
+ *   .partition();
+ * ```
+ *
+ * @example With retry and timeout
+ * ```ts
+ * await storage.put("important.txt", data)
+ *   .retry({ attempts: 3, delay: (attempt) => 100 * Math.pow(2, attempt) })
+ *   .timeout(30_000)
+ *   .run();
+ * ```
+ */
+export class Storage {
+    constructor(adapter) {
+        Object.defineProperty(this, "adapter", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: adapter
+        });
+    }
+    /**
+     * Connect to storage via a connector.
+     *
+     * @example
+     * ```ts
+     * const storage = await Storage.connect(createMemory()).run();
+     * ```
+     */
+    static connect(connector) {
+        return Task.of(async () => {
+            try {
+                return new Storage(await connector.connect());
+            }
+            catch (error) {
+                throw new StorageConnectionFailed(error instanceof Error ? error.message : String(error), error);
+            }
+        });
+    }
+    /**
+     * Release the connection back to its source (e.g., pool).
+     *
+     * @example
+     * ```ts
+     * await storage.close().run();
+     * ```
+     */
+    close() {
+        return Task.of(async () => {
+            try {
+                await this.adapter.close();
+            }
+            catch (error) {
+                throw new StorageCloseFailed(error instanceof Error ? error.message : String(error), error);
+            }
+        });
+    }
+    /**
+     * Put an object into storage.
+     *
+     * @example
+     * ```ts
+     * await storage.put("image.png", imageBytes, { contentType: "image/png" }).run();
+     * ```
+     */
+    put(key, body, options) {
+        return Task.of(async () => {
+            try {
+                await this.adapter.put(key, body, options);
+            }
+            catch (error) {
+                throw new StoragePutFailed(key, error instanceof Error ? error.message : String(error), error);
+            }
+        });
+    }
+    /**
+     * Get an object from storage.
+     *
+     * @example
+     * ```ts
+     * const object = await storage.get("file.txt").run();
+     * const text = await new Response(object.body).text();
+     * ```
+     */
+    get(key) {
+        return Task.of(async () => {
+            try {
+                return await this.adapter.get(key);
+            }
+            catch (error) {
+                if (error instanceof StorageObjectNotFound) {
+                    throw error;
+                }
+                throw new StorageGetFailed(key, error instanceof Error ? error.message : String(error), error);
+            }
+        });
+    }
+    /**
+     * Delete an object from storage.
+     *
+     * @example
+     * ```ts
+     * await storage.delete("old-file.txt").run();
+     * ```
+     */
+    delete(key) {
+        return Task.of(async () => {
+            try {
+                await this.adapter.delete(key);
+            }
+            catch (error) {
+                throw new StorageDeleteFailed(key, error instanceof Error ? error.message : String(error), error);
+            }
+        });
+    }
+    /**
+     * Get metadata for an object without fetching the body.
+     *
+     * @example
+     * ```ts
+     * const metadata = await storage.head("file.txt").run();
+     * console.log(metadata.size, metadata.contentType);
+     * ```
+     */
+    head(key) {
+        return Task.of(async () => {
+            try {
+                return await this.adapter.head(key);
+            }
+            catch (error) {
+                if (error instanceof StorageObjectNotFound) {
+                    throw error;
+                }
+                throw new StorageHeadFailed(key, error instanceof Error ? error.message : String(error), error);
+            }
+        });
+    }
+    /**
+     * List objects in storage with optional prefix.
+     *
+     * @example
+     * ```ts
+     * const { successes, errors } = await storage.list("images/")
+     *   .withConcurrency(10)
+     *   .map(async (entry) => await processImage(entry))
+     *   .tapErr((err) => console.error("Failed:", err))
+     *   .partition();
+     * ```
+     */
+    list(prefix) {
+        const adapter = this.adapter;
+        return Source.from(async function* () {
+            try {
+                for await (const entry of adapter.list(prefix)) {
+                    yield entry;
+                }
+            }
+            catch (error) {
+                throw new StorageListFailed(prefix, error instanceof Error ? error.message : String(error), error);
+            }
+        });
+    }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@anabranch/storage",
+  "version": "0.1.0",
+  "description": "TODO: Add description",
+  "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": "^0"
+  },
+  "_generatedBy": "dnt@dev"
+}