@streetjs/storage 1.0.0

package/dist/drivers/backblaze.js

@@ -0,0 +1,279 @@
+/**
+ * @streetjs/storage — the Backblaze B2 driver submodule (`@streetjs/storage/backblaze`).
+ *
+ * Backblaze B2 exposes a **fully S3-compatible API**, so this driver is a thin
+ * specialization of the shared S3-style base ({@link createS3StyleDriver} in
+ * `s3-base.ts`): it only differs in how the underlying client is
+ * built/configured (a B2 S3 endpoint and B2 application-key credentials), never
+ * in how the {@link StorageDriver} contract is satisfied. The driver name is
+ * fixed to `"backblaze"`.
+ *
+ * ## SDK isolation (Requirements 3.1, 3.3)
+ *
+ * This module imports **no provider SDK at the top level** — only this package's
+ * own type surface and the shared S3-style base. It supports two construction
+ * modes:
+ *
+ * 1. **Injected structural client** — the caller passes an {@link S3ClientLike}
+ *    (the minimal, SDK-shaped structural interface the base depends on). The SDK
+ *    is then entirely a concern of the caller; this package resolves nothing.
+ *    ({@link createBackblazeB2Driver} with a client, synchronous.)
+ * 2. **Self-built client from connection config** — the driver constructs its own
+ *    S3-compatible client for the B2 endpoint using a **lazy dynamic `import()`**
+ *    performed inside the factory at construction time (never at module top
+ *    level), so `@aws-sdk/client-s3` is resolved only when this submodule is
+ *    actually used to build a client. If that optional peer SDK is absent (and no
+ *    client was injected), a descriptive {@link StorageConfigError} is thrown.
+ *    ({@link createBackblazeB2Driver} with a config, asynchronous.)
+ *
+ * Because this driver lives behind the `./backblaze` subpath export and the base
+ * package never imports it, `streetjs` stays the only runtime dependency and the
+ * B2/S3 SDK remains an optional peer dependency.
+ *
+ * _Requirements: 2.1, 2.3, 3.3_
+ */
+import { Buffer } from "node:buffer";
+import { systemClock } from "streetjs";
+import { StorageConfigError } from "../errors.js";
+import { createS3StyleDriver, S3StyleDriver, } from "./s3-base.js";
+/** The stable driver name surfaced as {@link StorageDriver.name}. */
+export const BACKBLAZE_DRIVER_NAME = "backblaze";
+/** Peer SDK specifier resolved lazily when the driver builds its own client. */
+const BACKBLAZE_SDK_SPECIFIER = "@aws-sdk/client-s3";
+export function createBackblazeB2Driver(clientOrConfig, options = {}) {
+    if (isS3ClientLike(clientOrConfig)) {
+        return buildDriver(clientOrConfig, options);
+    }
+    return buildFromConnectionConfig(clientOrConfig);
+}
+/**
+ * A Backblaze B2 driver as a concrete class over an injected {@link S3ClientLike},
+ * for callers who prefer `new` construction. Equivalent to
+ * {@link createBackblazeB2Driver} with an injected client; the name defaults to
+ * `"backblaze"`.
+ */
+export class BackblazeB2Driver extends S3StyleDriver {
+    constructor(client, options = {}) {
+        super(client, {
+            name: options.name ?? BACKBLAZE_DRIVER_NAME,
+            clock: options.clock ?? systemClock,
+            capabilities: options.capabilities,
+        });
+    }
+}
+// ── Internal construction helpers ───────────────────────────────────────────
+/** Delegate to the shared S3-style base, fixing the name to `"backblaze"`. */
+function buildDriver(client, options) {
+    return createS3StyleDriver(client, {
+        name: options.name ?? BACKBLAZE_DRIVER_NAME,
+        clock: options.clock ?? systemClock,
+        capabilities: options.capabilities,
+    });
+}
+/**
+ * Build a B2 S3-compatible client via a lazy dynamic `import()` of the optional
+ * peer SDK, then wrap it in {@link S3ClientLike} and hand it to the base. Throws
+ * a descriptive {@link StorageConfigError} when the SDK cannot be resolved.
+ */
+async function buildFromConnectionConfig(config) {
+    const client = await buildBackblazeS3Client(config);
+    return buildDriver(client, config);
+}
+/**
+ * Structural guard distinguishing an injected {@link S3ClientLike} from a
+ * connection config: only a client exposes the mandatory `putObject` method.
+ */
+function isS3ClientLike(value) {
+    return typeof value.putObject === "function";
+}
+// ── The lazily-built S3-compatible client for Backblaze B2 ──────────────────────
+/**
+ * Resolve `@aws-sdk/client-s3` lazily and adapt it into an {@link S3ClientLike}
+ * bound to the B2 bucket/endpoint. The specifier is held in a variable so the
+ * static build never requires the optional peer dependency to be installed; it
+ * is resolved only at call time.
+ */
+async function buildBackblazeS3Client(config) {
+    // Lazy dynamic import — never a top-level import. An indirection variable keeps
+    // the specifier non-literal so the module is not required at build time.
+    const specifier = BACKBLAZE_SDK_SPECIFIER;
+    let sdk;
+    try {
+        sdk = (await import(specifier));
+    }
+    catch (cause) {
+        throw new StorageConfigError(`The Backblaze B2 driver requires the optional peer dependency "${BACKBLAZE_SDK_SPECIFIER}". ` +
+            `Install it, or pass a pre-constructed S3ClientLike to createBackblazeB2Driver().`, { provider: BACKBLAZE_DRIVER_NAME, cause });
+    }
+    const bucket = config.bucket;
+    const raw = new sdk.S3Client({
+        endpoint: config.endpoint,
+        region: config.region ?? "auto",
+        credentials: {
+            accessKeyId: config.credentials.accessKeyId,
+            secretAccessKey: config.credentials.secretAccessKey,
+        },
+        forcePathStyle: config.forcePathStyle ?? false,
+    });
+    const send = (command) => raw.send(command);
+    return {
+        async putObject(input) {
+            const result = await send(new sdk.PutObjectCommand({
+                Bucket: bucket,
+                Key: input.key,
+                Body: input.body,
+                ContentType: input.contentType,
+                Metadata: input.metadata,
+            }));
+            return { etag: normalizeEtag(result.ETag) };
+        },
+        async getObject({ key }) {
+            let result;
+            try {
+                result = await send(new sdk.GetObjectCommand({ Bucket: bucket, Key: key }));
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+            const body = await collectBody(result.Body);
+            return {
+                body,
+                contentType: result.ContentType,
+                etag: normalizeEtag(result.ETag),
+                size: result.ContentLength ?? body.byteLength,
+                lastModified: toEpochMs(result.LastModified),
+                metadata: result.Metadata,
+            };
+        },
+        async headObject({ key }) {
+            let result;
+            try {
+                result = await send(new sdk.HeadObjectCommand({ Bucket: bucket, Key: key }));
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+            return {
+                contentType: result.ContentType,
+                etag: normalizeEtag(result.ETag),
+                size: result.ContentLength,
+                lastModified: toEpochMs(result.LastModified),
+                metadata: result.Metadata,
+            };
+        },
+        async deleteObject({ key }) {
+            await send(new sdk.DeleteObjectCommand({ Bucket: bucket, Key: key }));
+        },
+        async listObjects({ prefix, limit, cursor, delimiter }) {
+            const result = await send(new sdk.ListObjectsV2Command({
+                Bucket: bucket,
+                Prefix: prefix,
+                MaxKeys: limit,
+                ContinuationToken: cursor,
+                Delimiter: delimiter === true ? "/" : undefined,
+            }));
+            const contents = result.Contents ?? [];
+            return contents.map((entry) => ({
+                key: entry.Key ?? "",
+                size: entry.Size ?? 0,
+                updatedAt: toEpochMs(entry.LastModified) ?? 0,
+            }));
+        },
+        async createMultipartUpload({ key, contentType, metadata }) {
+            const result = await send(new sdk.CreateMultipartUploadCommand({
+                Bucket: bucket,
+                Key: key,
+                ContentType: contentType,
+                Metadata: metadata,
+            }));
+            if (typeof result.UploadId !== "string") {
+                throw new StorageConfigError("Backblaze B2 did not return an upload id for the multipart upload.", {
+                    provider: BACKBLAZE_DRIVER_NAME,
+                });
+            }
+            return { uploadId: result.UploadId };
+        },
+        async uploadPart({ key, uploadId, partNumber, body }) {
+            const result = await send(new sdk.UploadPartCommand({
+                Bucket: bucket,
+                Key: key,
+                UploadId: uploadId,
+                PartNumber: partNumber,
+                Body: body,
+            }));
+            return { etag: normalizeEtag(result.ETag) };
+        },
+        async completeMultipartUpload({ key, uploadId, parts }) {
+            const result = await send(new sdk.CompleteMultipartUploadCommand({
+                Bucket: bucket,
+                Key: key,
+                UploadId: uploadId,
+                MultipartUpload: {
+                    Parts: parts.map((part) => ({ PartNumber: part.partNumber, ETag: part.etag })),
+                },
+            }));
+            return { etag: normalizeEtag(result.ETag) };
+        },
+        async abortMultipartUpload({ key, uploadId }) {
+            await send(new sdk.AbortMultipartUploadCommand({ Bucket: bucket, Key: key, UploadId: uploadId }));
+        },
+    };
+}
+// ── Adapter utilities ───────────────────────────────────────────────────────
+/** Strip the surrounding quotes S3 wraps around ETags; tolerate an absent value. */
+function normalizeEtag(etag) {
+    if (typeof etag !== "string") {
+        return "";
+    }
+    return etag.replace(/^"|"$/g, "");
+}
+/** Coerce an S3 `LastModified` (Date or epoch ms) into epoch ms, if present. */
+function toEpochMs(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return value instanceof Date ? value.getTime() : value;
+}
+/** `true` when an AWS SDK error represents a missing key (404 / NoSuchKey / NotFound). */
+function isNotFound(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    const err = error;
+    if (err.name === "NoSuchKey" || err.name === "NotFound") {
+        return true;
+    }
+    return err.$metadata?.httpStatusCode === 404;
+}
+/**
+ * Collect an AWS SDK response body (a streaming blob) into a `Uint8Array`,
+ * supporting the SDK's `transformToByteArray()` helper as well as Node streams
+ * and already-buffered values.
+ */
+async function collectBody(body) {
+    if (body === undefined || body === null) {
+        return new Uint8Array(0);
+    }
+    const maybe = body;
+    if (typeof maybe.transformToByteArray === "function") {
+        return maybe.transformToByteArray();
+    }
+    if (body instanceof Uint8Array) {
+        return body;
+    }
+    if (typeof maybe[Symbol.asyncIterator] === "function") {
+        const chunks = [];
+        for await (const chunk of body) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        return new Uint8Array(Buffer.concat(chunks));
+    }
+    return new Uint8Array(Buffer.from(body));
+}
+//# sourceMappingURL=backblaze.js.map

package/dist/drivers/backblaze.js.map

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

package/dist/drivers/gcs.d.ts

@@ -0,0 +1,239 @@
+/**
+ * @streetjs/storage — GoogleCloudStorageDriver (submodule `@streetjs/storage/gcs`).
+ *
+ * Google Cloud Storage is **not** an S3-wire-compatible provider — its SDK
+ * exposes a bucket/file object model (`bucket.file(name).save/download/delete/
+ * exists/getMetadata`, `bucket.getFiles({ prefix })`) rather than the
+ * `putObject`/`getObject` verbs the S3-style base is built on. So, unlike
+ * `r2.ts`/`minio.ts`/`backblaze.ts`, this driver does **not** extend the shared
+ * S3 base ({@link ../drivers/s3-base}); it maps the {@link StorageDriver}
+ * contract directly onto a purpose-built structural {@link GcsClientLike} that
+ * mirrors just the GCS calls it needs.
+ *
+ * ## Two ways to obtain a driver
+ *
+ * - {@link createGoogleCloudStorageDriver} wraps an **already-constructed,
+ *   injected** {@link GcsClientLike} 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 `@google-cloud/storage` install.
+ * - {@link connectGoogleCloudStorageDriver} **builds its own client** from GCS
+ *   connection config. It resolves `@google-cloud/storage` 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).
+ *
+ * ## Capability delegation (Requirement 2.3)
+ *
+ * The driver implements only the **mandatory primitives** (`put`/`get`/`exists`/
+ * `delete`/`stat`/`list`/`putStream`/`getStream`), producing every
+ * {@link StorageObjectMetadata} through the shared metadata layer
+ * ({@link buildObjectMetadata}) so the field set is identical to Memory/Local/S3,
+ * and reporting a missing key consistently ({@link MaybeObject} `{ found: false }`
+ * for `get`, `null` for `stat`, {@link NotFoundError} for `getStream`). Advanced
+ * capabilities (`multipart`/`resumable`/`versioning`/`signedUrl`/`lifecycle`) are
+ * intentionally left `undefined` so the facade simulates them over the
+ * primitives, keeping behavior identical across providers.
+ *
+ * ## SDK isolation (Requirements 2.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. `@google-cloud/storage` is referenced solely via a dynamic `import()`
+ * with a non-literal specifier inside {@link connectGoogleCloudStorageDriver}, so
+ * `tsc` never requires the SDK to be present and `streetjs` stays the only
+ * runtime dependency. This driver is a submodule-only export
+ * (`./gcs` → `dist/drivers/gcs.js`); it is intentionally not re-exported from the
+ * package's main `index.ts`.
+ *
+ * _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";
+/**
+ * Object attributes as surfaced by the GCS object model (`file.getMetadata()` /
+ * entries from `bucket.getFiles`). Every field is optional and loosely typed
+ * because GCS returns `size` as a numeric string and timestamps as RFC-3339
+ * strings; the driver normalizes them. Caller-supplied user metadata lives under
+ * the nested {@link metadata} map (GCS's "custom metadata").
+ */
+export interface GcsObjectAttributes {
+    /** Byte length. GCS returns this as a numeric string; a number is tolerated. */
+    readonly size?: number | string;
+    /** Declared content type. */
+    readonly contentType?: string;
+    /** Entity tag. */
+    readonly etag?: string;
+    /** Base64 MD5 hash of the content, when present. */
+    readonly md5Hash?: string;
+    /** Creation time as an RFC-3339 / ISO-8601 string. */
+    readonly timeCreated?: string;
+    /** Last-updated time as an RFC-3339 / ISO-8601 string. */
+    readonly updated?: string;
+    /** Caller-supplied custom metadata (string→string), GCS's "metadata" map. */
+    readonly metadata?: Record<string, string>;
+}
+/** Options accepted by {@link GcsClientLike.save}. */
+export interface GcsSaveOptions {
+    /** Content type to persist alongside the object. */
+    readonly contentType?: string;
+    /** Custom metadata (string→string) to persist as GCS object metadata. */
+    readonly metadata?: Record<string, string>;
+}
+/** Options accepted by {@link GcsClientLike.getFiles}. */
+export interface GcsListInput {
+    /** Only list objects whose name begins with this prefix. */
+    readonly prefix: string;
+    /** When set, collapse results on this delimiter (GCS directory semantics). */
+    readonly delimiter?: string;
+    /** Best-effort maximum number of results the caller wants. */
+    readonly maxResults?: number;
+}
+/** A single object entry returned by {@link GcsClientLike.getFiles}. */
+export interface GcsFileEntry {
+    /** The object name (full key). */
+    readonly name: string;
+    /** The entry's attributes, when the listing includes them. */
+    readonly attributes?: GcsObjectAttributes;
+}
+/**
+ * The **minimal, GCS-shaped structural interface** this driver depends on.
+ *
+ * It is bucket-scoped (the concrete adapter binds a bucket) and describes just
+ * the object operations the driver needs — never any concrete
+ * `@google-cloud/storage` type — so the SDK stays an optional peer concern of the
+ * consumer (Requirement 3.1). `download`/`getMetadata` return `null` for a
+ * missing object so not-found maps to the contract's consistent semantics rather
+ * than a thrown error.
+ */
+export interface GcsClientLike {
+    /** Store `bytes` under `name` with optional content type and custom metadata. */
+    save(name: string, bytes: Uint8Array, options?: GcsSaveOptions): Promise<void>;
+    /** Download the object's bytes, or `null` when it does not exist. */
+    download(name: string): Promise<Uint8Array | null>;
+    /** Delete the object at `name` (a no-op when it is already absent). */
+    delete(name: string): Promise<void>;
+    /** Report whether an object exists at `name`. */
+    exists(name: string): Promise<boolean>;
+    /** Fetch the object's attributes, or `null` when it does not exist. */
+    getMetadata(name: string): Promise<GcsObjectAttributes | null>;
+    /** List objects whose name begins with `input.prefix`. */
+    getFiles(input: GcsListInput): Promise<readonly GcsFileEntry[]>;
+}
+/**
+ * Options for the GCS driver. The provider name is fixed to `"gcs"` and is not
+ * caller-configurable, so provider identity stays stable.
+ */
+export interface GoogleCloudStorageDriverOptions {
+    /** Injected clock for deterministic timestamps in tests. Default `systemClock`. */
+    readonly clock?: Clock;
+}
+/**
+ * Maps the {@link StorageDriver} contract onto an injected {@link GcsClientLike}.
+ *
+ * Object identity fields (`etag`/`checksum`/`size`) and timestamps are computed
+ * locally at write time — the checksum/etag are the sha-256 hex digest of the
+ * stored bytes, the size is the byte length, and timestamps come from the
+ * injected {@link Clock} — then encoded into the object's custom metadata so they
+ * round-trip on read. Advanced capabilities are left `undefined` for facade
+ * simulation.
+ */
+export declare class GoogleCloudStorageDriver implements StorageDriver {
+    /** Stable driver name. */
+    readonly name = "gcs";
+    private readonly client;
+    private readonly clock;
+    constructor(client: GcsClientLike, options?: GoogleCloudStorageDriverOptions);
+    /**
+     * 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 object's custom-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 object's attributes and encoded custom 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).
+     */
+    stat(key: string): Promise<StorageObjectMetadata | null>;
+    /**
+     * List objects whose key begins with `prefix`, sorted by key for deterministic
+     * ordering (Requirement 4.9). Honors optional `cursor` (exclusive resume
+     * point), `limit`, and `delimiter` (collapse to immediate children on `/`).
+     */
+    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 the object's
+     * attributes and the encoded custom-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 driver): `etag`/`md5Hash`/`timeCreated`/`updated` back-fill the
+     * identity/timestamp fields, keeping the shape consistent across providers.
+     */
+    private decodeMeta;
+}
+/**
+ * Wrap an injected {@link GcsClientLike} as a GCS driver. Synchronous and
+ * SDK-free: the caller supplies the client, so no provider SDK is resolved here.
+ *
+ * @throws {StorageConfigError} when no client is injected — use
+ *   {@link connectGoogleCloudStorageDriver} to build a client from connection
+ *   options instead.
+ */
+export declare function createGoogleCloudStorageDriver(client: GcsClientLike, options?: GoogleCloudStorageDriverOptions): StorageDriver;
+/**
+ * Connection configuration for {@link connectGoogleCloudStorageDriver}. These are
+ * forwarded to the `@google-cloud/storage` `Storage` constructor (except
+ * `bucket`, which scopes the resulting client).
+ */
+export interface GoogleCloudStorageConfig extends GoogleCloudStorageDriverOptions {
+    /** The GCS bucket the driver operates within (required). */
+    readonly bucket: string;
+    /** GCP project id. */
+    readonly projectId?: string;
+    /** Path to a service-account key file. */
+    readonly keyFilename?: string;
+    /** Inline service-account credentials. */
+    readonly credentials?: Record<string, unknown>;
+    /** Custom API endpoint (e.g. a fake/emulator host). */
+    readonly apiEndpoint?: string;
+}
+/**
+ * Build a GCS driver that owns its client, resolving `@google-cloud/storage`
+ * 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 createGoogleCloudStorageDriver} with their own {@link GcsClientLike}
+ * instead.
+ */
+export declare function connectGoogleCloudStorageDriver(config: GoogleCloudStorageConfig): Promise<StorageDriver>;
+//# sourceMappingURL=gcs.d.ts.map

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

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