@streetjs/storage 1.0.0

package/dist/drivers/r2.js

@@ -0,0 +1,240 @@
+/**
+ * @streetjs/storage — CloudflareR2Driver (submodule `@streetjs/storage/r2`).
+ *
+ * Cloudflare R2 speaks the S3 API, so this driver is a thin **endpoint/credential
+ * specialization** of the shared S3-style base ({@link createS3StyleDriver} in
+ * `s3-base.ts`). It differs from `s3.ts` only in how the underlying client is
+ * built — R2 uses an account-specific endpoint
+ * (`https://<accountId>.r2.cloudflarestorage.com`) with `region: "auto"` — never
+ * in how the {@link StorageDriver} contract is satisfied.
+ *
+ * ## Two ways to obtain a driver
+ *
+ * - {@link createCloudflareR2Driver} wraps an **already-constructed, injected**
+ *   structural {@link S3ClientLike} and returns a driver synchronously. This is
+ *   the SDK-free path: no provider SDK is touched, so it is fully testable with
+ *   an in-memory fake and needs no `@aws-sdk/*` install.
+ * - {@link connectCloudflareR2Driver} **builds its own client** from R2
+ *   connection config. It resolves the S3-compatible SDK through a **lazy
+ *   dynamic `import()` performed inside the function** (never at module top
+ *   level), so the optional peer dependency is only required when this path is
+ *   actually used. If the SDK is not installed and no client was injected, it
+ *   throws {@link StorageConfigError} (Requirement 1.5).
+ *
+ * ## SDK isolation (Requirements 2.1, 3.3)
+ *
+ * This module imports **no provider SDK at the top level** — only this package's
+ * own base/types/errors. The AWS S3 SDK (which R2 uses) is referenced solely via
+ * a dynamic `import()` with a non-literal specifier inside
+ * {@link connectCloudflareR2Driver}, so `tsc` never requires the SDK to be
+ * present and `streetjs` stays the only runtime dependency. This driver is a
+ * submodule-only export (`./r2` → `dist/drivers/r2.js`); it is intentionally not
+ * re-exported from the package's main `index.ts`.
+ *
+ * _Requirements: 2.1, 2.3, 3.3_
+ */
+import { StorageConfigError } from "../errors.js";
+import { createS3StyleDriver, S3StyleDriver, } from "./s3-base.js";
+/** The stable driver name surfaced as {@link StorageDriver.name} for R2. */
+const R2_DRIVER_NAME = "r2";
+/**
+ * The CloudflareR2 {@link StorageDriver}: the shared S3-style base pinned to the
+ * `"r2"` provider name. Construction is identical to the base — supply an
+ * {@link S3ClientLike} — the only difference is the fixed name.
+ */
+export class CloudflareR2Driver extends S3StyleDriver {
+    constructor(client, options = {}) {
+        super(client, { ...options, name: R2_DRIVER_NAME });
+    }
+}
+/**
+ * Wrap an injected {@link S3ClientLike} as an R2 driver, delegating to
+ * {@link createS3StyleDriver} with the name `"r2"`. Synchronous and SDK-free:
+ * the caller supplies the client, so no provider SDK is resolved here.
+ */
+export function createCloudflareR2Driver(client, options = {}) {
+    return createS3StyleDriver(client, { ...options, name: R2_DRIVER_NAME });
+}
+/**
+ * Build an R2 driver that owns its client, resolving the S3-compatible SDK
+ * lazily.
+ *
+ * The SDK is loaded through a dynamic `import()` with a non-literal specifier so
+ * it is never a static/top-level dependency: `tsc` does not require it to be
+ * installed, and it is only resolved when this function runs. When the SDK
+ * cannot be resolved, a {@link StorageConfigError} is thrown (Requirement 1.5) —
+ * callers that cannot install the SDK should use {@link createCloudflareR2Driver}
+ * with their own {@link S3ClientLike} instead.
+ */
+export async function connectCloudflareR2Driver(config) {
+    const { accountId, bucket, accessKeyId, secretAccessKey } = config;
+    if (!accountId || !bucket || !accessKeyId || !secretAccessKey) {
+        throw new StorageConfigError("CloudflareR2 requires accountId, bucket, accessKeyId, and secretAccessKey.", { provider: R2_DRIVER_NAME });
+    }
+    const endpoint = config.endpoint ?? `https://${accountId}.r2.cloudflarestorage.com`;
+    const region = config.region ?? "auto";
+    // Lazy, non-literal dynamic import so the S3 SDK stays an optional peer that
+    // `tsc` never resolves statically and Node only loads on this path.
+    const specifier = "@aws-sdk/client-s3";
+    let sdk;
+    try {
+        sdk = (await import(specifier));
+    }
+    catch (cause) {
+        throw new StorageConfigError('CloudflareR2 driver requires the optional peer dependency "@aws-sdk/client-s3". ' +
+            "Install it, or inject your own S3ClientLike via createCloudflareR2Driver().", { provider: R2_DRIVER_NAME, cause });
+    }
+    const s3 = new sdk.S3Client({
+        region,
+        endpoint,
+        credentials: { accessKeyId, secretAccessKey },
+        forcePathStyle: true,
+    });
+    const client = adaptAwsS3Client(s3, sdk, bucket);
+    return createCloudflareR2Driver(client, {
+        clock: config.clock,
+        capabilities: config.capabilities,
+    });
+}
+// ── AWS S3 SDK adapter ─────────────────────────────────────────────────────────
+/**
+ * Adapt an AWS S3 v3 client into the structural {@link S3ClientLike} the base
+ * depends on, binding every call to `bucket`. Only the methods the base uses are
+ * mapped; the AWS response shapes are narrowed through the local structural
+ * types below so this module never imports concrete SDK types.
+ */
+function adaptAwsS3Client(s3, sdk, bucket) {
+    return {
+        async putObject(input) {
+            const res = await s3.send(new sdk.PutObjectCommand({
+                Bucket: bucket,
+                Key: input.key,
+                Body: input.body,
+                ContentType: input.contentType,
+                Metadata: input.metadata,
+            }));
+            return { etag: res.ETag ?? "" };
+        },
+        async getObject(input) {
+            let res;
+            try {
+                res = await s3.send(new sdk.GetObjectCommand({ Bucket: bucket, Key: input.key }));
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+            const body = res.Body ? await res.Body.transformToByteArray() : new Uint8Array(0);
+            return {
+                body,
+                contentType: res.ContentType,
+                etag: res.ETag,
+                size: res.ContentLength ?? body.byteLength,
+                lastModified: toEpochMs(res.LastModified),
+                metadata: res.Metadata,
+            };
+        },
+        async deleteObject(input) {
+            await s3.send(new sdk.DeleteObjectCommand({ Bucket: bucket, Key: input.key }));
+        },
+        async listObjects(input) {
+            const res = await s3.send(new sdk.ListObjectsV2Command({
+                Bucket: bucket,
+                Prefix: input.prefix,
+                MaxKeys: input.limit,
+                ContinuationToken: input.cursor,
+                Delimiter: input.delimiter === true ? "/" : undefined,
+            }));
+            const contents = res.Contents ?? [];
+            return contents.map((item) => ({
+                key: item.Key ?? "",
+                size: item.Size ?? 0,
+                updatedAt: toEpochMs(item.LastModified) ?? 0,
+            }));
+        },
+        async headObject(input) {
+            let res;
+            try {
+                res = await s3.send(new sdk.HeadObjectCommand({ Bucket: bucket, Key: input.key }));
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+            return {
+                contentType: res.ContentType,
+                etag: res.ETag,
+                size: res.ContentLength,
+                lastModified: toEpochMs(res.LastModified),
+                metadata: res.Metadata,
+            };
+        },
+        async createMultipartUpload(input) {
+            const res = await s3.send(new sdk.CreateMultipartUploadCommand({
+                Bucket: bucket,
+                Key: input.key,
+                ContentType: input.contentType,
+                Metadata: input.metadata,
+            }));
+            return { uploadId: res.UploadId ?? "" };
+        },
+        async uploadPart(input) {
+            const res = await s3.send(new sdk.UploadPartCommand({
+                Bucket: bucket,
+                Key: input.key,
+                UploadId: input.uploadId,
+                PartNumber: input.partNumber,
+                Body: input.body,
+            }));
+            return { etag: res.ETag ?? "" };
+        },
+        async completeMultipartUpload(input) {
+            const res = await s3.send(new sdk.CompleteMultipartUploadCommand({
+                Bucket: bucket,
+                Key: input.key,
+                UploadId: input.uploadId,
+                MultipartUpload: {
+                    Parts: input.parts.map((part) => ({
+                        PartNumber: part.partNumber,
+                        ETag: part.etag,
+                    })),
+                },
+            }));
+            return { etag: res.ETag ?? "" };
+        },
+        async abortMultipartUpload(input) {
+            await s3.send(new sdk.AbortMultipartUploadCommand({
+                Bucket: bucket,
+                Key: input.key,
+                UploadId: input.uploadId,
+            }));
+        },
+    };
+}
+/**
+ * Recognize the "no such key / not found" conditions the S3 API reports so
+ * `getObject`/`headObject` can return `null` (Requirement 4.2/4.10) rather than
+ * throwing. Matches the SDK's error `name` and the HTTP 404 status.
+ */
+function isNotFound(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    const record = error;
+    if (record.name === "NoSuchKey" || record.name === "NotFound") {
+        return true;
+    }
+    if (record.Code === "NoSuchKey" || record.Code === "NotFound") {
+        return true;
+    }
+    return record.$metadata?.httpStatusCode === 404;
+}
+/** Convert an SDK `Date` (or undefined) to epoch milliseconds. */
+function toEpochMs(value) {
+    return value instanceof Date ? value.getTime() : undefined;
+}
+//# sourceMappingURL=r2.js.map

package/dist/drivers/r2.js.map

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

package/dist/drivers/s3-base.d.ts

@@ -0,0 +1,270 @@
+/**
+ * @streetjs/storage — the shared S3-style driver base and {@link S3ClientLike}.
+ *
+ * S3-compatible providers (Amazon S3, Cloudflare R2, MinIO, and the Backblaze B2
+ * S3 API) share one wire shape: a small set of object operations
+ * (`putObject`/`getObject`/`deleteObject`/`listObjects`) plus optional
+ * multipart and presign calls. This module captures that shape as the structural
+ * {@link S3ClientLike} interface and maps the {@link StorageDriver} contract onto
+ * it, so `s3.ts`, `r2.ts`, `minio.ts`, and `backblaze.ts` (tasks 28.2–28.5) only
+ * differ in how they build/configure the client, never in how the contract is
+ * satisfied.
+ *
+ * ## 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. The base accepts an **injected** {@link S3ClientLike}; it never
+ * resolves an SDK itself. The concrete submodules that *can* construct their own
+ * client do so with a **lazy dynamic `import()`** performed inside that submodule
+ * at construction time, so the optional peer SDK is resolved only when that
+ * submodule is actually imported. `streetjs` therefore stays the only runtime
+ * dependency.
+ *
+ * ## Capability delegation (Requirement 2.3)
+ *
+ * The base implements the **mandatory primitives** (`put`/`get`/`exists`/
+ * `delete`/`stat`/`list`/`putStream`/`getStream`) by mapping onto
+ * {@link S3ClientLike}, producing every {@link StorageObjectMetadata} through the
+ * shared metadata layer ({@link buildObjectMetadata}) so the field set is
+ * identical to Memory/Local, and reporting a missing key consistently
+ * ({@link MaybeObject} `{ found: false }` for `get`, `null` for `stat`,
+ * {@link NotFoundError} for `getStream`).
+ *
+ * Advanced capabilities are **delegated to the client when available, otherwise
+ * left `undefined` so the facade simulates them over the primitives**
+ * (Requirement 2, keeping behavior identical across providers):
+ *
+ * - **Multipart** is wired only when the client exposes the full SDK-shaped
+ *   multipart method set; the base adapts those calls into a
+ *   {@link MultipartCapability}, tracking the `uploadId → key` mapping the S3 API
+ *   requires.
+ * - **Versioning / lifecycle / signed URLs** are delegated only when a native
+ *   capability object is supplied through `options.capabilities`; otherwise they
+ *   are left `undefined`. (A provider's presigned URLs are verified by the
+ *   provider, not locally, so the base does not synthesize a
+ *   {@link SignedUrlCapability} from a bare `presignUrl` — the facade's HMAC
+ *   simulation is used instead unless a full native capability is injected.)
+ *
+ * _Requirements: 2.3, 3.1, 3.3_
+ */
+import { type Clock } from "streetjs";
+import type { MaybeObject, MultipartCapability, NodeReadable, StorageDriver, VersioningCapability, SignedUrlCapability, LifecycleCapability } from "../driver.js";
+import type { ListOptions, StorageListItem, StorageObjectMetadata, WriteMetadata } from "../types.js";
+/** Input to {@link S3ClientLike.putObject}. */
+export interface S3PutObjectInput {
+    readonly key: string;
+    readonly body: Uint8Array;
+    readonly contentType?: string;
+    /** Provider "user metadata" (string→string), used to carry typed metadata. */
+    readonly metadata?: Record<string, string>;
+}
+/** Result of {@link S3ClientLike.putObject}. */
+export interface S3PutObjectOutput {
+    readonly etag: string;
+}
+/** Result of {@link S3ClientLike.getObject} (the object body plus attributes). */
+export interface S3GetObjectOutput {
+    readonly body: Uint8Array;
+    readonly contentType?: string;
+    readonly etag?: string;
+    readonly size?: number;
+    /** Last-modified time as epoch ms. */
+    readonly lastModified?: number;
+    readonly metadata?: Record<string, string>;
+}
+/** Result of {@link S3ClientLike.headObject} (attributes only, no body). */
+export interface S3HeadObjectOutput {
+    readonly contentType?: string;
+    readonly etag?: string;
+    readonly size?: number;
+    readonly lastModified?: number;
+    readonly metadata?: Record<string, string>;
+}
+/** A single entry returned by {@link S3ClientLike.listObjects}. */
+export interface S3ListItem {
+    readonly key: string;
+    readonly size: number;
+    /** Last-modified time as epoch ms. */
+    readonly updatedAt: number;
+}
+/** Options passed to {@link S3ClientLike.listObjects}. */
+export interface S3ListInput {
+    readonly prefix: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly delimiter?: boolean;
+}
+/**
+ * The **minimal, SDK-shaped structural interface** an S3-style driver depends on.
+ *
+ * It describes just the provider calls the driver needs — never any concrete
+ * SDK type — so the actual SDK stays an optional peer concern of the consumer
+ * (Requirement 3.1). The four object operations are mandatory; `headObject`,
+ * the multipart method set, and `presignUrl` are optional and unlock the
+ * corresponding native paths when present.
+ */
+export interface S3ClientLike {
+    /** Store `body` under `key` with optional content type and user metadata. */
+    putObject(input: S3PutObjectInput): Promise<S3PutObjectOutput>;
+    /** Fetch the object at `key`, or `null` when it does not exist. */
+    getObject(input: {
+        readonly key: string;
+    }): Promise<S3GetObjectOutput | null>;
+    /** Delete the object at `key` (a no-op when it is already absent). */
+    deleteObject(input: {
+        readonly key: string;
+    }): Promise<void>;
+    /** List objects whose key begins with `prefix`. */
+    listObjects(input: S3ListInput): Promise<readonly S3ListItem[]>;
+    /** Fetch object attributes without the body, or `null` when absent (optional). */
+    headObject?(input: {
+        readonly key: string;
+    }): Promise<S3HeadObjectOutput | null>;
+    createMultipartUpload?(input: {
+        readonly key: string;
+        readonly contentType?: string;
+        readonly metadata?: Record<string, string>;
+    }): Promise<{
+        readonly uploadId: string;
+    }>;
+    uploadPart?(input: {
+        readonly key: string;
+        readonly uploadId: string;
+        readonly partNumber: number;
+        readonly body: Uint8Array;
+    }): Promise<{
+        readonly etag: string;
+    }>;
+    completeMultipartUpload?(input: {
+        readonly key: string;
+        readonly uploadId: string;
+        readonly parts: readonly {
+            readonly partNumber: number;
+            readonly etag: string;
+        }[];
+    }): Promise<{
+        readonly etag: string;
+    }>;
+    abortMultipartUpload?(input: {
+        readonly key: string;
+        readonly uploadId: string;
+    }): Promise<void>;
+    /**
+     * Mint a provider presigned URL for `key` (optional). Consumed by concrete
+     * provider drivers that expose native presigned URLs; the base does not build
+     * a {@link SignedUrlCapability} from it because provider URLs are verified by
+     * the provider, not locally.
+     */
+    presignUrl?(input: {
+        readonly key: string;
+        readonly op: "GET" | "PUT" | "DELETE";
+        readonly expiresInMs: number;
+    }): Promise<string>;
+}
+/** Native capability objects a provider driver may inject for delegation. */
+export interface S3NativeCapabilities {
+    readonly versioning?: VersioningCapability;
+    readonly lifecycle?: LifecycleCapability;
+    readonly signedUrl?: SignedUrlCapability;
+}
+/** Options for {@link createS3StyleDriver} / {@link S3StyleDriver}. */
+export interface S3StyleDriverOptions {
+    /** Stable driver name surfaced as {@link StorageDriver.name}. Default `"s3"`. */
+    readonly name?: string;
+    /** Injected clock for deterministic timestamps in tests. Default `systemClock`. */
+    readonly clock?: Clock;
+    /**
+     * Native capability objects to delegate to. Any capability omitted here (and
+     * not derivable from the client) is left `undefined` so the facade simulates
+     * it over the primitives.
+     */
+    readonly capabilities?: S3NativeCapabilities;
+}
+/**
+ * Maps the {@link StorageDriver} contract onto an injected {@link S3ClientLike}.
+ *
+ * This class is provider-agnostic: every S3-compatible driver (S3, R2, MinIO,
+ * Backblaze) is this base with a differently-constructed client. It imports no
+ * provider SDK; the client is supplied by the caller (typically a submodule that
+ * lazily `import()`s its SDK).
+ */
+export declare class S3StyleDriver implements StorageDriver {
+    readonly name: string;
+    private readonly client;
+    private readonly clock;
+    /** Tracks the `key` for each in-flight multipart `uploadId` (S3 needs both). */
+    private readonly multipartKeys;
+    multipart?: MultipartCapability;
+    versioning?: VersioningCapability;
+    signedUrl?: SignedUrlCapability;
+    lifecycle?: LifecycleCapability;
+    constructor(client: S3ClientLike, options?: S3StyleDriverOptions);
+    /**
+     * 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 provider's user-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 provider attributes and encoded user metadata via the
+     * shared metadata 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). Uses `headObject` when available, else falls back to a
+     * body fetch.
+     */
+    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>;
+    /**
+     * Best-effort read of an object's existing metadata (used to preserve
+     * `createdAt` on overwrite). Returns `null` when the object does not exist.
+     */
+    private readMeta;
+    /**
+     * Rebuild the typed {@link StorageObjectMetadata} field set from provider
+     * attributes and the encoded user-metadata map, applying the shared layer's
+     * canonical defaults. Provider-supplied values are used as best-effort
+     * fallbacks when the encoded fields are absent (e.g. an object written outside
+     * this base): `etag`/`size`/`lastModified` back-fill the identity/timestamp
+     * fields, keeping the shape consistent across providers.
+     */
+    private decodeMeta;
+    /**
+     * Adapt the client's SDK-shaped multipart calls into a
+     * {@link MultipartCapability}. The S3 API requires the object key on every
+     * part/complete/abort call, so the `uploadId → key` mapping is tracked here.
+     */
+    private buildMultipartCapability;
+}
+/**
+ * Construct an S3-style {@link StorageDriver} over an injected
+ * {@link S3ClientLike}. This is the entry point consumed by the concrete
+ * provider submodules (`s3.ts`/`r2.ts`/`minio.ts`/`backblaze.ts`), each of which
+ * supplies a differently-constructed client.
+ */
+export declare function createS3StyleDriver(client: S3ClientLike, options?: S3StyleDriverOptions): StorageDriver;
+//# sourceMappingURL=s3-base.d.ts.map

package/dist/drivers/s3-base.d.ts.map

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