@streetjs/storage 1.0.0

package/dist/directory.js

@@ -0,0 +1,148 @@
+/**
+ * @streetjs/storage — the Directory API over a flat key space (task 17.1).
+ *
+ * Object stores have a flat key space with no real directories. This module
+ * implements a directory-style API entirely over that flat key space using
+ * `/`-delimited prefixes, so the same code runs unchanged on every
+ * {@link StorageDriver} — including prefix-only cloud providers (Requirement
+ * 15.5). The facade exposes the constructed instance as `storage.directory`.
+ *
+ * The four operations map onto driver primitives (`list`/`put`/`delete`) as
+ * follows:
+ *
+ * - `mkdir(path)` records an empty marker key `path/`, making the path
+ *   available as a directory prefix (Requirement 15.1). A root/empty path needs
+ *   no marker and is a no-op.
+ * - `listDirectory(path)` calls `driver.list(path/)` and collapses the results
+ *   to the **immediate** children by splitting each key on the next `/` after
+ *   the prefix: keys with no further `/` are file entries, keys with a further
+ *   `/` contribute a single synthesized sub-directory entry (Requirement 15.2).
+ * - `removeDirectory(path)` deletes every key under the prefix; when the prefix
+ *   contains no objects it is a success no-op that removes nothing
+ *   (Requirements 15.3, 15.6).
+ * - `walk(path)` returns every object key strictly beneath the prefix
+ *   (Requirement 15.4).
+ *
+ * The public {@link DirectoryApi} type is owned by `facade.ts` (and re-exported
+ * from `index.ts`); it is imported here type-only so there is no runtime import
+ * cycle between the two modules.
+ *
+ * _Requirements: 15.1, 15.2, 15.3, 15.4, 15.5, 15.6_
+ */
+/** The directory delimiter used to derive prefixes from paths. */
+const DELIMITER = "/";
+/**
+ * A {@link DirectoryApi} implementation over any {@link StorageDriver}'s flat
+ * key space. It holds only the driver and derives every directory operation
+ * from `/`-delimited prefixes, so it behaves identically across providers.
+ */
+export class StorageDirectoryApi {
+    driver;
+    constructor(driver) {
+        this.driver = driver;
+    }
+    /**
+     * Normalize a directory `path` to a prefix ending in the delimiter. The root
+     * (`""` or `"/"`) normalizes to the empty prefix (which matches every key),
+     * and any leading delimiter is dropped so `"/photos"` and `"photos"` refer to
+     * the same directory. A path that already ends with the delimiter is left
+     * unchanged.
+     */
+    toPrefix(path) {
+        let p = path;
+        while (p.startsWith(DELIMITER)) {
+            p = p.slice(DELIMITER.length);
+        }
+        if (p === "") {
+            return "";
+        }
+        return p.endsWith(DELIMITER) ? p : p + DELIMITER;
+    }
+    /**
+     * List the keys stored under `prefix`, defensively re-filtering by the prefix
+     * so drivers that interpret `list` loosely never leak keys from outside the
+     * directory into a directory operation.
+     */
+    async keysUnder(prefix) {
+        const items = await this.driver.list(prefix);
+        if (prefix === "") {
+            return items;
+        }
+        return items.filter((item) => item.key.startsWith(prefix));
+    }
+    /**
+     * Make `path` available as a directory prefix by recording an empty marker
+     * key `path/` (Requirement 15.1). The root/empty path requires no marker and
+     * is a no-op.
+     */
+    async mkdir(path) {
+        const prefix = this.toPrefix(path);
+        if (prefix === "") {
+            return;
+        }
+        await this.driver.put(prefix, new Uint8Array(0), {});
+    }
+    /**
+     * Return the immediate child entries under `path` (Requirement 15.2). Each
+     * key under the prefix is split on the next delimiter: a key with no further
+     * delimiter is returned as its file entry; keys sharing a further path
+     * segment collapse into a single synthesized sub-directory entry (key
+     * `path/child/`, `size` 0). The directory's own marker (a key equal to the
+     * prefix) is not reported as a child.
+     */
+    async listDirectory(path) {
+        const prefix = this.toPrefix(path);
+        const items = await this.keysUnder(prefix);
+        const files = [];
+        const directories = new Map();
+        for (const item of items) {
+            const remainder = item.key.slice(prefix.length);
+            if (remainder === "") {
+                // The directory's own marker key — not one of its children.
+                continue;
+            }
+            const slash = remainder.indexOf(DELIMITER);
+            if (slash === -1) {
+                // Immediate file child.
+                files.push(item);
+                continue;
+            }
+            // Immediate sub-directory child: collapse everything sharing this segment
+            // into a single directory entry, tracking the most recent update time.
+            const dirKey = prefix + remainder.slice(0, slash) + DELIMITER;
+            const existing = directories.get(dirKey);
+            if (existing === undefined || item.updatedAt > existing.updatedAt) {
+                directories.set(dirKey, { key: dirKey, size: 0, updatedAt: item.updatedAt });
+            }
+        }
+        return [...directories.values(), ...files];
+    }
+    /**
+     * Remove every object stored under `path` (Requirement 15.3). When the prefix
+     * contains no objects — because the directory does not exist or is already
+     * empty — nothing is removed and a success result of `{ removed: false }` is
+     * returned without throwing (Requirement 15.6). When at least one object is
+     * removed the result is `{ removed: true }`.
+     */
+    async removeDirectory(path) {
+        const prefix = this.toPrefix(path);
+        const items = await this.keysUnder(prefix);
+        if (items.length === 0) {
+            return { removed: false };
+        }
+        for (const item of items) {
+            await this.driver.delete(item.key);
+        }
+        return { removed: true };
+    }
+    /**
+     * Return every object key strictly beneath `path` (Requirement 15.4),
+     * excluding the directory's own marker key (a key equal to the prefix).
+     */
+    async walk(path) {
+        const prefix = this.toPrefix(path);
+        const items = await this.keysUnder(prefix);
+        return items.map((item) => item.key).filter((key) => key !== prefix);
+    }
+}
+//# sourceMappingURL=directory.js.map

package/dist/directory.js.map

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

package/dist/driver.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @streetjs/storage — the single driver contract.
+ *
+ * `StorageDriver` is the one interface every provider implements. The storage
+ * facade never assumes a provider; it only calls the methods defined here.
+ * Mandatory methods are the primitive object operations (`put`/`get`/`exists`/
+ * `delete`/`stat`/`list`) plus streaming (`putStream`/`getStream`). Advanced
+ * capabilities (`multipart`/`resumable`/`versioning`/`signedUrl`/`lifecycle`)
+ * are **optional**; when a driver does not implement one natively, the facade's
+ * cross-cutting layer supplies a provider-agnostic simulation built on the
+ * mandatory primitives, keeping observable behavior identical across providers.
+ *
+ * Requirements: 2.1, 2.3, 2.4, 4.6, 5.5
+ */
+import type { Readable } from "node:stream";
+import type { StorageObjectMetadata, WriteMetadata, StorageListItem, ListOptions, VersionInfo, SignedOperation, SignedUrlOptions, SignedUrlVerification, LifecycleRule, LifecycleOutcome, DriverProbe } from "./types.js";
+/** Node's `Readable` stream, used for streaming uploads/downloads. */
+export type NodeReadable = Readable;
+/** Result of a lookup that may be absent, distinguishing "not found" from errors. */
+export type MaybeObject = {
+    readonly found: true;
+    readonly bytes: Uint8Array;
+    readonly metadata: StorageObjectMetadata;
+} | {
+    readonly found: false;
+};
+/** A single stored part for multipart assembly. */
+export interface StoredPart {
+    readonly partNumber: number;
+    readonly etag: string;
+    readonly size: number;
+}
+/**
+ * The single contract every provider implements. Mandatory methods are the
+ * primitive object operations; capability methods are optional and, when
+ * absent, are simulated by the facade over the primitives.
+ */
+export interface StorageDriver {
+    /** Stable driver name (e.g. "memory", "local", "s3"). */
+    readonly name: string;
+    put(key: string, bytes: Uint8Array, metadata: WriteMetadata): Promise<StorageObjectMetadata>;
+    get(key: string): Promise<MaybeObject>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    stat(key: string): Promise<StorageObjectMetadata | null>;
+    list(prefix: string, options?: ListOptions): Promise<StorageListItem[]>;
+    putStream(key: string, stream: NodeReadable, metadata: WriteMetadata): Promise<StorageObjectMetadata>;
+    getStream(key: string): Promise<NodeReadable>;
+    multipart?: MultipartCapability;
+    resumable?: ResumableCapability;
+    versioning?: VersioningCapability;
+    signedUrl?: SignedUrlCapability;
+    lifecycle?: LifecycleCapability;
+    /** Best-effort connectivity/quota probe for health checks. */
+    probe?(): Promise<DriverProbe>;
+}
+export interface MultipartCapability {
+    create(key: string, metadata: WriteMetadata): Promise<string>;
+    uploadPart(uploadId: string, partNumber: number, bytes: Uint8Array): Promise<StoredPart>;
+    complete(uploadId: string, parts: readonly StoredPart[]): Promise<StorageObjectMetadata>;
+    abort(uploadId: string): Promise<void>;
+}
+export interface ResumableCapability {
+    start(key: string, metadata: WriteMetadata): Promise<string>;
+    append(sessionId: string, bytes: Uint8Array, offset: number): Promise<number>;
+    offset(sessionId: string): Promise<number>;
+    finish(sessionId: string): Promise<StorageObjectMetadata>;
+    cancel(sessionId: string): Promise<void>;
+}
+export interface VersioningCapability {
+    snapshot(key: string): Promise<string | null>;
+    list(key: string): Promise<VersionInfo[]>;
+    restore(key: string, versionId: string): Promise<StorageObjectMetadata>;
+    deleteVersion(key: string, versionId: string): Promise<void>;
+}
+export interface SignedUrlCapability {
+    sign(key: string, op: SignedOperation, options: SignedUrlOptions): Promise<string>;
+    verify(url: string, now: number): SignedUrlVerification;
+}
+export interface LifecycleCapability {
+    apply(rule: LifecycleRule, now: number): Promise<LifecycleOutcome[]>;
+}
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}

package/dist/driver.js

@@ -0,0 +1,16 @@
+/**
+ * @streetjs/storage — the single driver contract.
+ *
+ * `StorageDriver` is the one interface every provider implements. The storage
+ * facade never assumes a provider; it only calls the methods defined here.
+ * Mandatory methods are the primitive object operations (`put`/`get`/`exists`/
+ * `delete`/`stat`/`list`) plus streaming (`putStream`/`getStream`). Advanced
+ * capabilities (`multipart`/`resumable`/`versioning`/`signedUrl`/`lifecycle`)
+ * are **optional**; when a driver does not implement one natively, the facade's
+ * cross-cutting layer supplies a provider-agnostic simulation built on the
+ * mandatory primitives, keeping observable behavior identical across providers.
+ *
+ * Requirements: 2.1, 2.3, 2.4, 4.6, 5.5
+ */
+export {};
+//# sourceMappingURL=driver.js.map

package/dist/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/drivers/azure.d.ts

@@ -0,0 +1,239 @@
+/**
+ * @streetjs/storage — Azure Blob Storage driver submodule (`@streetjs/storage/azure`).
+ *
+ * Azure Blob Storage does **not** speak the S3 wire shape, so — unlike
+ * `s3.ts`/`r2.ts`/`minio.ts`/`backblaze.ts`, which specialize the shared
+ * {@link createS3StyleDriver} base — this driver maps the {@link StorageDriver}
+ * contract **directly** onto a structural Azure Blob client
+ * ({@link AzureBlobClientLike}). It computes object identity fields
+ * (`size`/`checksum`/`etag`) and timestamps locally and assembles every
+ * {@link StorageObjectMetadata} through the shared metadata layer
+ * ({@link buildObjectMetadata}) so the field set is identical to Memory/Local
+ * and every other provider (Requirement 2.1, 10.1).
+ *
+ * ## SDK isolation (Requirements 3.1, 3.3)
+ *
+ * This module imports **no provider SDK** at the top level — only Node built-ins,
+ * `streetjs` (for the injected {@link Clock}), and this package's own type
+ * surface. There are two ways to obtain a driver:
+ *
+ * 1. **Inject a structural client.** {@link createAzureBlobDriver} accepts an
+ *    already-built {@link AzureBlobClientLike} (real SDK adapter or a test
+ *    double) and maps the contract onto it. The `@azure/storage-blob` SDK stays
+ *    an optional peer concern of the consumer and is never touched by this
+ *    package.
+ *
+ * 2. **Let the driver build its own client.** {@link connectAzureBlobDriver}
+ *    resolves the optional `@azure/storage-blob` peer SDK with a **lazy dynamic
+ *    `import()`** performed *inside the function* (never at module top level),
+ *    constructs a container-scoped client, adapts it to
+ *    {@link AzureBlobClientLike}, and hands it to {@link createAzureBlobDriver}.
+ *    If the SDK is absent, it throws {@link StorageConfigError} rather than a raw
+ *    module-resolution error.
+ *
+ * Because the driver lives behind the `./azure` subpath export
+ * (`dist/drivers/azure.js`) and is *not* re-exported from the package index, a
+ * consumer only loads this code — and any SDK it lazily resolves — when they
+ * import `@streetjs/storage/azure`. `package.json` lists `@azure/storage-blob`
+ * as an optional peer dependency, never a runtime dependency, keeping `streetjs`
+ * the only runtime dependency.
+ *
+ * ## Capability delegation (Requirement 2.3)
+ *
+ * Only the **mandatory primitives** (`put`/`get`/`exists`/`delete`/`stat`/
+ * `list`/`putStream`/`getStream`) are implemented. The advanced capabilities
+ * (`multipart`/`resumable`/`versioning`/`signedUrl`/`lifecycle`) are left
+ * `undefined` so the facade's cross-cutting layer supplies a provider-agnostic
+ * simulation over the primitives, keeping observable behavior identical across
+ * providers.
+ *
+ * _Requirements: 2.1, 2.3, 3.3_
+ */
+import { type Clock } from "streetjs";
+import type { MaybeObject, NodeReadable, StorageDriver } from "../driver.js";
+import type { ListOptions, StorageListItem, StorageObjectMetadata, WriteMetadata } from "../types.js";
+/** Input to {@link AzureBlobClientLike.upload}. */
+export interface AzureUploadInput {
+    /** The blob name (object key) within the container. */
+    readonly blobName: string;
+    /** The bytes to store. */
+    readonly body: Uint8Array;
+    /** Blob content type, mapped to `blobHTTPHeaders.blobContentType`. */
+    readonly contentType?: string;
+    /** Blob metadata (string→string); used to round-trip the typed field set. */
+    readonly metadata?: Record<string, string>;
+}
+/** Result of {@link AzureBlobClientLike.upload}. */
+export interface AzureUploadResult {
+    /** The blob's entity tag, when the service returns one. */
+    readonly etag?: string;
+}
+/** Blob attributes shared by download and property reads. */
+export interface AzureBlobProperties {
+    /** Blob content type (`blobContentType`). */
+    readonly contentType?: string;
+    /** The blob's entity tag. */
+    readonly etag?: string;
+    /** Byte length of the blob content (`contentLength`). */
+    readonly contentLength?: number;
+    /** Last-modified time as epoch ms. */
+    readonly lastModified?: number;
+    /** Blob metadata (string→string). */
+    readonly metadata?: Record<string, string>;
+}
+/** Result of {@link AzureBlobClientLike.download} — attributes plus the body. */
+export interface AzureBlobDownloadResult extends AzureBlobProperties {
+    /** The blob's content bytes. */
+    readonly body: Uint8Array;
+}
+/** A single entry returned by {@link AzureBlobClientLike.listBlobs}. */
+export interface AzureBlobListItem {
+    /** The blob name (object key). */
+    readonly name: string;
+    /** Byte length of the blob content. */
+    readonly contentLength: number;
+    /** Last-modified time as epoch ms. */
+    readonly lastModified: number;
+}
+/** Options passed to {@link AzureBlobClientLike.listBlobs}. */
+export interface AzureListInput {
+    /** Only blobs whose name begins with this prefix are returned. */
+    readonly prefix: string;
+    /** Maximum number of blobs to return. */
+    readonly limit?: number;
+}
+/**
+ * The **minimal, container-scoped structural interface** the Azure Blob driver
+ * depends on.
+ *
+ * It describes just the blob operations the driver needs — never any concrete
+ * `@azure/storage-blob` type — so the actual SDK stays an optional peer concern
+ * of the consumer (Requirement 3.1). Every call is scoped to a single container
+ * (the adapter built by {@link connectAzureBlobDriver} closes over the container
+ * name), so the driver only ever passes blob names.
+ */
+export interface AzureBlobClientLike {
+    /** Upload `body` to `blobName` with optional content type and metadata. */
+    upload(input: AzureUploadInput): Promise<AzureUploadResult>;
+    /** Download the blob at `blobName`, or `null` when it does not exist. */
+    download(input: {
+        readonly blobName: string;
+    }): Promise<AzureBlobDownloadResult | null>;
+    /** Read blob attributes without the body, or `null` when absent. */
+    getProperties(input: {
+        readonly blobName: string;
+    }): Promise<AzureBlobProperties | null>;
+    /** Delete the blob at `blobName` (a no-op when it is already absent). */
+    deleteBlob(input: {
+        readonly blobName: string;
+    }): Promise<void>;
+    /** Report whether a blob exists at `blobName`. */
+    exists(input: {
+        readonly blobName: string;
+    }): Promise<boolean>;
+    /** List blobs whose name begins with `prefix`. */
+    listBlobs(input: AzureListInput): Promise<readonly AzureBlobListItem[]>;
+}
+/** Options for {@link createAzureBlobDriver} / {@link AzureBlobDriver}. */
+export interface AzureBlobDriverOptions {
+    /** Injected clock for deterministic timestamps in tests. Default `systemClock`. */
+    readonly clock?: Clock;
+}
+/**
+ * Maps the {@link StorageDriver} contract directly onto an injected
+ * {@link AzureBlobClientLike}.
+ *
+ * Unlike the S3-compatible providers, Azure Blob does not share the S3 wire
+ * shape, so this driver does not build on {@link createS3StyleDriver}. It
+ * computes size/checksum/etag and timestamps locally, encodes the typed metadata
+ * into the blob metadata map so it round-trips on read, and reports a missing
+ * key consistently ({@link MaybeObject} `{ found: false }` for `get`, `null` for
+ * `stat`, {@link NotFoundError} for `getStream`).
+ */
+export declare class AzureBlobDriver implements StorageDriver {
+    /** Stable driver name. */
+    readonly name = "azure";
+    private readonly client;
+    private readonly clock;
+    constructor(client: AzureBlobClientLike, options?: AzureBlobDriverOptions);
+    /**
+     * Store `bytes` under `key`, computing size and sha-256 checksum locally and
+     * taking timestamps from the injected clock. When overwriting, the original
+     * `createdAt` is preserved (a preceding attribute read). The typed metadata is
+     * encoded into the blob metadata map so it round-trips on read
+     * (Requirements 4.1, 10.1, 10.2).
+     */
+    put(key: string, bytes: Uint8Array, metadata: WriteMetadata): Promise<StorageObjectMetadata>;
+    /**
+     * Read the object at `key`, returning a discriminated {@link MaybeObject} so
+     * absence is reported rather than thrown (Requirements 4.2, 2.4). Metadata is
+     * rebuilt from the blob attributes and encoded metadata via the shared layer.
+     */
+    get(key: string): Promise<MaybeObject>;
+    /** Report whether an object is stored under `key` (Requirement 4.3). */
+    exists(key: string): Promise<boolean>;
+    /** Delete the object at `key`; deleting a missing key is a no-op (Requirement 4.4). */
+    delete(key: string): Promise<void>;
+    /**
+     * Return the metadata for `key` without its content, or `null` when absent
+     * (Requirement 4.10).
+     */
+    stat(key: string): Promise<StorageObjectMetadata | null>;
+    /** List objects whose key begins with `prefix` (Requirement 4.9). */
+    list(prefix: string, options?: ListOptions): Promise<StorageListItem[]>;
+    /**
+     * Consume a Node {@link Readable} and persist the assembled bytes under `key`
+     * with the same computed metadata as {@link put} (Requirement 5.1). Chunks are
+     * drained through a `pipeline` (correct backpressure and error propagation),
+     * then handed to {@link put}.
+     */
+    putStream(key: string, stream: NodeReadable, metadata: WriteMetadata): Promise<StorageObjectMetadata>;
+    /**
+     * Return a Node {@link Readable} of the stored bytes at `key` (Requirement
+     * 5.2). Throws {@link NotFoundError} for a missing key (Requirement 5.5).
+     */
+    getStream(key: string): Promise<NodeReadable>;
+    /**
+     * Rebuild the typed {@link StorageObjectMetadata} field set from blob
+     * attributes and the encoded metadata map, applying the shared layer's
+     * canonical defaults. Provider-supplied values back-fill identity/timestamp
+     * fields when the encoded ones are absent (e.g. a blob written outside this
+     * driver), keeping the shape consistent across providers.
+     */
+    private decodeMeta;
+}
+/**
+ * Create an Azure-Blob-backed {@link StorageDriver} over an **injected**
+ * structural {@link AzureBlobClientLike}.
+ *
+ * This is the primary, SDK-free entry point: the caller supplies a client that
+ * already speaks the {@link AzureBlobClientLike} shape (built from
+ * `@azure/storage-blob`, or a test double), and this function maps the contract
+ * onto it. No provider SDK is imported.
+ *
+ * @throws {StorageConfigError} when no client is injected — use
+ *   {@link connectAzureBlobDriver} to build a client from connection options.
+ */
+export declare function createAzureBlobDriver(client: AzureBlobClientLike, options?: AzureBlobDriverOptions): StorageDriver;
+/** Connection options for building an Azure Blob client via {@link connectAzureBlobDriver}. */
+export interface AzureBlobConnectionOptions {
+    /** The blob container the driver operates within (required). */
+    readonly container: string;
+    /** An Azure Storage connection string (e.g. from the portal). */
+    readonly connectionString: string;
+}
+/**
+ * Build an Azure-Blob-backed {@link StorageDriver}, constructing the underlying
+ * client from `connection` options using the optional `@azure/storage-blob` peer
+ * SDK.
+ *
+ * The SDK is resolved with a **lazy dynamic `import()`** performed inside this
+ * function, so the peer dependency is only touched when a caller actually asks
+ * the driver to build its own client. The resolved SDK client is adapted to the
+ * structural {@link AzureBlobClientLike} and handed to {@link createAzureBlobDriver}.
+ *
+ * @throws {StorageConfigError} when the `@azure/storage-blob` SDK is not
+ *   installed, or when the client cannot be constructed from the supplied options.
+ */
+export declare function connectAzureBlobDriver(connection: AzureBlobConnectionOptions, options?: AzureBlobDriverOptions): Promise<StorageDriver>;
+//# sourceMappingURL=azure.d.ts.map

package/dist/drivers/azure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"azure.d.ts","sourceRoot":"","sources":["../../src/drivers/azure.ts"],"names":[],"mappings":"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"}