@streetjs/storage 1.0.0

package/dist/drivers/gcs.js

@@ -0,0 +1,454 @@
+/**
+ * @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 { createHash } from "node:crypto";
+import { Readable, Writable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { systemClock } from "streetjs";
+import { NotFoundError, StorageConfigError } from "../errors.js";
+import { buildObjectMetadata } from "../metadata.js";
+/** The stable driver name surfaced as {@link StorageDriver.name} for GCS. */
+const GCS_DRIVER_NAME = "gcs";
+// ── Reserved user-metadata keys ────────────────────────────────────────────────
+/**
+ * Reserved custom-metadata keys used to round-trip the typed metadata field set
+ * through GCS's string→string object-metadata map. Prefixed so they never
+ * collide with a caller's own custom fields.
+ */
+const MK = {
+    checksum: "x-street-checksum",
+    createdAt: "x-street-created-at",
+    updatedAt: "x-street-updated-at",
+    owner: "x-street-owner",
+    tenant: "x-street-tenant",
+    accessLevel: "x-street-access-level",
+    custom: "x-street-custom",
+};
+// ── The GCS driver ─────────────────────────────────────────────────────────────
+/**
+ * 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 class GoogleCloudStorageDriver {
+    /** Stable driver name. */
+    name = GCS_DRIVER_NAME;
+    client;
+    clock;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.clock = options.clock ?? systemClock;
+    }
+    // ── Mandatory primitives ──────────────────────────────────────────────────
+    /**
+     * 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).
+     */
+    async put(key, bytes, metadata) {
+        const stored = bytes.slice();
+        const checksum = sha256Hex(stored);
+        const now = this.clock();
+        const existing = await this.stat(key);
+        const objectMetadata = buildObjectMetadata({
+            key,
+            size: stored.byteLength,
+            checksum,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+            write: metadata,
+        });
+        await this.client.save(key, stored, {
+            contentType: objectMetadata.contentType,
+            metadata: encodeUserMetadata(objectMetadata),
+        });
+        return objectMetadata;
+    }
+    /**
+     * 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.
+     */
+    async get(key) {
+        const bytes = await this.client.download(key);
+        if (bytes === null) {
+            return { found: false };
+        }
+        const attributes = await this.client.getMetadata(key);
+        const metadata = this.decodeMeta(key, bytes.byteLength, attributes);
+        return { found: true, bytes: bytes.slice(), metadata };
+    }
+    /** Report whether an object is stored under `key` (Requirement 4.3). */
+    async exists(key) {
+        return this.client.exists(key);
+    }
+    /** Delete the object at `key`; deleting a missing key is a no-op (Requirement 4.4). */
+    async delete(key) {
+        await this.client.delete(key);
+    }
+    /**
+     * Return the metadata for `key` without its content, or `null` when absent
+     * (Requirement 4.10).
+     */
+    async stat(key) {
+        const attributes = await this.client.getMetadata(key);
+        if (attributes === null) {
+            return null;
+        }
+        const size = parseSize(attributes.size);
+        return this.decodeMeta(key, size, attributes);
+    }
+    /**
+     * 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 `/`).
+     */
+    async list(prefix, options) {
+        const entries = await this.client.getFiles({
+            prefix,
+            delimiter: options?.delimiter === true ? "/" : undefined,
+        });
+        let items = entries
+            .filter((entry) => typeof entry.name === "string")
+            .map((entry) => ({
+            key: entry.name,
+            size: parseSize(entry.attributes?.size),
+            updatedAt: parseIso(entry.attributes?.updated) ?? 0,
+        }))
+            .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+        const cursor = options?.cursor;
+        if (cursor !== undefined) {
+            items = items.filter((item) => item.key > cursor);
+        }
+        return typeof options?.limit === "number" ? items.slice(0, options.limit) : items;
+    }
+    // ── Streaming ───────────────────────────────────────────────────────────────
+    /**
+     * 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}.
+     */
+    async putStream(key, stream, metadata) {
+        const chunks = [];
+        const collector = new Writable({
+            write(chunk, _encoding, callback) {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                callback();
+            },
+        });
+        await pipeline(stream, collector);
+        return this.put(key, new Uint8Array(Buffer.concat(chunks)), metadata);
+    }
+    /**
+     * Return a Node {@link Readable} of the stored bytes at `key` (Requirement
+     * 5.2). Throws {@link NotFoundError} for a missing key (Requirement 5.5).
+     */
+    async getStream(key) {
+        const bytes = await this.client.download(key);
+        if (bytes === null) {
+            throw new NotFoundError(key);
+        }
+        return Readable.from([Buffer.from(bytes)]);
+    }
+    // ── Internal helpers ──────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    decodeMeta(key, size, attributes) {
+        const attrs = attributes ?? {};
+        const um = attrs.metadata ?? {};
+        const now = this.clock();
+        const checksum = um[MK.checksum] ?? attrs.etag ?? attrs.md5Hash ?? "";
+        const createdAt = parseEpoch(um[MK.createdAt]) ?? parseIso(attrs.timeCreated) ?? now;
+        const updatedAt = parseEpoch(um[MK.updatedAt]) ?? parseIso(attrs.updated) ?? createdAt;
+        const write = {
+            contentType: attrs.contentType,
+            owner: um[MK.owner],
+            tenant: um[MK.tenant],
+            accessLevel: decodeAccessLevel(um[MK.accessLevel]),
+            custom: parseCustom(um[MK.custom]),
+        };
+        return buildObjectMetadata({
+            key,
+            size,
+            checksum,
+            etag: attrs.etag ?? checksum,
+            createdAt,
+            updatedAt,
+            write,
+        });
+    }
+}
+/**
+ * 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 function createGoogleCloudStorageDriver(client, options = {}) {
+    if (client === undefined || client === null) {
+        throw new StorageConfigError("createGoogleCloudStorageDriver requires an injected GcsClientLike. " +
+            "Pass a structural client, or use connectGoogleCloudStorageDriver(config) " +
+            "to build one from a bucket using the optional '@google-cloud/storage' peer dependency.", { provider: GCS_DRIVER_NAME });
+    }
+    return new GoogleCloudStorageDriver(client, options);
+}
+/**
+ * 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 async function connectGoogleCloudStorageDriver(config) {
+    if (!config.bucket) {
+        throw new StorageConfigError("GoogleCloudStorage requires a bucket name.", { provider: GCS_DRIVER_NAME });
+    }
+    // Lazy, non-literal dynamic import so the GCS SDK stays an optional peer that
+    // `tsc` never resolves statically and Node only loads on this path.
+    const specifier = "@google-cloud/storage";
+    let sdk;
+    try {
+        sdk = (await import(specifier));
+    }
+    catch (cause) {
+        throw new StorageConfigError('GoogleCloudStorage driver requires the optional peer dependency "@google-cloud/storage". ' +
+            "Install it, or inject your own GcsClientLike via createGoogleCloudStorageDriver().", { provider: GCS_DRIVER_NAME, cause });
+    }
+    let storage;
+    try {
+        storage = new sdk.Storage({
+            projectId: config.projectId,
+            keyFilename: config.keyFilename,
+            credentials: config.credentials,
+            apiEndpoint: config.apiEndpoint,
+        });
+    }
+    catch (cause) {
+        throw new StorageConfigError(`Failed to construct a Google Cloud Storage client for bucket "${config.bucket}".`, { provider: GCS_DRIVER_NAME, cause });
+    }
+    const client = adaptGcsSdkBucket(storage.bucket(config.bucket));
+    return createGoogleCloudStorageDriver(client, { clock: config.clock });
+}
+// ── SDK → GcsClientLike adapter ────────────────────────────────────────────────
+/**
+ * Adapt a `@google-cloud/storage` `Bucket` into the structural
+ * {@link GcsClientLike} this driver consumes. Only the methods the driver uses
+ * are mapped; the SDK response shapes are narrowed through the local structural
+ * types below so this module never imports concrete SDK types. A missing object
+ * (`code === 404`) is mapped to `null` so not-found semantics stay consistent.
+ */
+function adaptGcsSdkBucket(bucket) {
+    return {
+        async save(name, bytes, options) {
+            await bucket.file(name).save(Buffer.from(bytes), {
+                contentType: options?.contentType,
+                metadata: { metadata: options?.metadata },
+            });
+        },
+        async download(name) {
+            try {
+                const [buffer] = await bucket.file(name).download();
+                return new Uint8Array(buffer);
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async delete(name) {
+            await bucket.file(name).delete({ ignoreNotFound: true });
+        },
+        async exists(name) {
+            const [exists] = await bucket.file(name).exists();
+            return exists;
+        },
+        async getMetadata(name) {
+            try {
+                const [metadata] = await bucket.file(name).getMetadata();
+                return metadata;
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async getFiles(input) {
+            const [files] = await bucket.getFiles({
+                prefix: input.prefix,
+                delimiter: input.delimiter,
+                maxResults: input.maxResults,
+            });
+            return files.map((file) => ({
+                name: file.name,
+                attributes: file.metadata,
+            }));
+        },
+    };
+}
+/**
+ * Recognize the GCS "object does not exist" condition so `download`/`getMetadata`
+ * can return `null` (Requirement 4.2/4.10) rather than throwing. GCS surfaces a
+ * `code === 404` on the ApiError.
+ */
+function isNotFound(error) {
+    if (error === null || typeof error !== "object") {
+        return false;
+    }
+    const code = error.code;
+    return code === 404;
+}
+// ── Module-private encoding helpers ────────────────────────────────────────────
+/** Compute the lowercase sha-256 hex digest of `bytes`. */
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Encode a built object's typed metadata into the GCS custom-metadata map. */
+function encodeUserMetadata(metadata) {
+    const map = {
+        [MK.checksum]: metadata.checksum,
+        [MK.createdAt]: String(metadata.createdAt),
+        [MK.updatedAt]: String(metadata.updatedAt),
+        [MK.accessLevel]: metadata.accessLevel,
+        [MK.custom]: JSON.stringify(metadata.custom ?? {}),
+    };
+    if (metadata.owner !== undefined) {
+        map[MK.owner] = metadata.owner;
+    }
+    if (metadata.tenant !== undefined) {
+        map[MK.tenant] = metadata.tenant;
+    }
+    return map;
+}
+/** Parse a GCS `size` (numeric string or number), defaulting to `0`. */
+function parseSize(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : 0;
+    }
+    if (typeof value === "string") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    return 0;
+}
+/** Parse an epoch-ms string, returning `undefined` when absent or non-numeric. */
+function parseEpoch(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/** Parse an RFC-3339 / ISO-8601 timestamp to epoch ms, or `undefined`. */
+function parseIso(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/** Parse the encoded custom-field JSON, tolerating malformed values. */
+function parseCustom(value) {
+    if (value === undefined) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through to the empty default on malformed JSON.
+    }
+    return {};
+}
+/** The recognized access levels, used to validate the decoded value. */
+const ACCESS_LEVELS = [
+    "public",
+    "private",
+    "signed",
+    "authenticated",
+    "role-based",
+    "tenant-aware",
+];
+/** Decode an access-level string, returning `undefined` for an unknown value. */
+function decodeAccessLevel(value) {
+    if (value !== undefined && ACCESS_LEVELS.includes(value)) {
+        return value;
+    }
+    return undefined;
+}
+//# sourceMappingURL=gcs.js.map

package/dist/drivers/gcs.js.map

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

package/dist/drivers/local.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @streetjs/storage — LocalStorageDriver (zero-dependency).
+ *
+ * A filesystem-backed implementation of the {@link StorageDriver} contract that
+ * uses only Node's built-in `fs` module (part of the runtime, not an external
+ * dependency — Requirement 3.2). Object bytes are written to `root/<key>` and
+ * the computed {@link StorageObjectMetadata} is persisted alongside them in a
+ * sidecar file at `root/<key>.meta.json`. Parent directories are created on
+ * demand so nested key paths (e.g. `a/b/c.txt`) work transparently.
+ *
+ * The Local driver is observationally equivalent to
+ * {@link MemoryStorageDriver} (Requirement 2.2): identical `etag`/`checksum`
+ * (sha-256 hex of the stored bytes via `node:crypto`), `size` (byte length),
+ * timestamps sourced from an injected {@link Clock} (default `systemClock` from
+ * `streetjs`), and defaults (`contentType` `application/octet-stream`,
+ * `accessLevel` `private`, `custom` `{}`). Overwriting a key preserves the
+ * original `createdAt` and only advances `updatedAt` (Requirements 4.1, 10.1).
+ *
+ * This module (task 4.1) implements the mandatory primitive object operations:
+ * `put` / `get` / `exists` / `delete` / `stat` / `list`. `get` returns a
+ * discriminated {@link MaybeObject} so absence is reported consistently rather
+ * than thrown (Requirements 4.2, 2.4). `list` returns {@link StorageListItem}s
+ * sorted by key and never surfaces the `.meta.json` sidecar files as objects
+ * (Requirement 4.9).
+ *
+ * Streaming (task 4.2) uses `fs.createReadStream` / `fs.createWriteStream` so
+ * large files are never fully buffered in memory (Requirement 5.3). `putStream`
+ * pipes the incoming stream through a sha-256 hash on the way to disk, tallying
+ * the byte length as it goes, then writes the sidecar with the same metadata
+ * semantics as `put` (preserving the original `createdAt` on overwrite).
+ * `getStream` returns a `fs.createReadStream` of the object and throws
+ * {@link NotFoundError} for a missing key (Requirement 5.5).
+ *
+ * _Requirements: 2.1, 2.2, 3.2, 4.1, 4.2, 4.3, 4.4, 4.9, 4.10, 5.1, 5.2, 5.3, 5.5, 10.1_
+ */
+import { type Clock } from "streetjs";
+import type { MaybeObject, NodeReadable, StorageDriver } from "../driver.js";
+import type { ListOptions, StorageListItem, StorageObjectMetadata, WriteMetadata } from "../types.js";
+/** Options for constructing a {@link LocalStorageDriver}. */
+export interface LocalStorageDriverOptions {
+    /** Filesystem root under which object bytes and sidecars are stored. */
+    readonly root: string;
+    /** Injected clock for deterministic timestamps in tests. Default `systemClock`. */
+    readonly clock?: Clock;
+}
+/**
+ * Zero-dependency filesystem {@link StorageDriver}.
+ *
+ * Object bytes live at `root/<key>`; their metadata is persisted in a sidecar
+ * `root/<key>.meta.json`. Observable behavior matches
+ * {@link MemoryStorageDriver} so the two drivers are interchangeable.
+ */
+export declare class LocalStorageDriver implements StorageDriver {
+    /** Stable driver name. */
+    readonly name = "local";
+    /** Filesystem root under which objects are stored. */
+    private readonly root;
+    /** Injected clock used for `createdAt` / `updatedAt` timestamps. */
+    private readonly clock;
+    constructor(options: LocalStorageDriverOptions);
+    /**
+     * Persist `bytes` under `key`, computing size, sha-256 checksum/etag, and
+     * timestamps. Parent directories are created as needed for nested keys. When
+     * overwriting an existing key, the original `createdAt` is preserved and only
+     * `updatedAt` advances (Requirements 4.1, 10.1).
+     */
+    put(key: string, bytes: Uint8Array, metadata: WriteMetadata): Promise<StorageObjectMetadata>;
+    /**
+     * Read the object at `key`. Returns a discriminated {@link MaybeObject} so
+     * absence is reported consistently rather than thrown (Requirements 4.2, 2.4).
+     */
+    get(key: string): Promise<MaybeObject>;
+    /** Report whether an object is stored under `key` (Requirement 4.3). */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Remove the object at `key` and its metadata sidecar. Deleting a missing key
+     * is a no-op so that a subsequent `exists` returns false either way
+     * (Requirement 4.4).
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Return the metadata for `key` without its content, or `null` if absent
+     * (Requirement 4.10).
+     */
+    stat(key: string): Promise<StorageObjectMetadata | null>;
+    /**
+     * Return list items for every key beginning with `prefix`, sorted by key for
+     * deterministic ordering (Requirement 4.9). Metadata sidecar files
+     * (`.meta.json`) are never surfaced as objects. Honors optional `cursor`
+     * (exclusive resume point), `limit`, and `delimiter` (collapse to immediate
+     * children on `/`) when supplied, matching {@link MemoryStorageDriver}.
+     */
+    list(prefix: string, options?: ListOptions): Promise<StorageListItem[]>;
+    /**
+     * Persist a streamed upload to `root/<key>` using `fs.createWriteStream` so
+     * the object is never fully buffered in memory (Requirements 5.1, 5.3).
+     * Parent directories are created on demand. As bytes flow to disk they are
+     * piped through a sha-256 hash and the running byte count is tallied, giving
+     * the `checksum`/`etag`/`size` without a second pass. Once the stream is
+     * drained the metadata sidecar is written with the same semantics as
+     * {@link put}: an existing key's original `createdAt` is preserved and only
+     * `updatedAt` advances (Requirements 4.1, 10.1).
+     */
+    putStream(key: string, stream: NodeReadable, metadata: WriteMetadata): Promise<StorageObjectMetadata>;
+    /**
+     * Return a `fs.createReadStream` of the object at `key` so readers pull bytes
+     * incrementally without buffering the whole object (Requirements 5.2, 5.3).
+     * Throws {@link NotFoundError} when the key is missing (Requirement 5.5).
+     */
+    getStream(key: string): Promise<NodeReadable>;
+    /** Absolute filesystem path to the object bytes for `key`. */
+    private objectPath;
+    /** Absolute filesystem path to the metadata sidecar for `key`. */
+    private metaPath;
+    /** Read and parse the metadata sidecar for `key`, or `null` when absent. */
+    private readMeta;
+    /** Unlink a path, ignoring the case where it does not exist. */
+    private unlinkIfExists;
+    /**
+     * Walk the storage root and return every object key (the relative path from
+     * `root`, using `/` separators). Metadata sidecar files are excluded so they
+     * are never surfaced as objects.
+     */
+    private collectKeys;
+}
+//# sourceMappingURL=local.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/drivers/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAQH,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,UAAU,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7E,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,aAAa,EACd,MAAM,aAAa,CAAC;AAErB,6DAA6D;AAC7D,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAKD;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACtD,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,WAAW;IAExB,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAE9B,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;gBAElB,OAAO,EAAE,yBAAyB;IAO9C;;;;;OAKG;IACG,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,qBAAqB,CAAC;IA2BjC;;;OAGG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAiB5C,wEAAwE;IAClE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS3C;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxC;;;OAGG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAI9D;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAgD7E;;;;;;;;;OASG;IACG,SAAS,CACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,qBAAqB,CAAC;IA+CjC;;;;OAIG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAenD,8DAA8D;IAC9D,OAAO,CAAC,UAAU;IAIlB,kEAAkE;IAClE,OAAO,CAAC,QAAQ;IAIhB,4EAA4E;YAC9D,QAAQ;IAatB,gEAAgE;YAClD,cAAc;IAU5B;;;;OAIG;YACW,WAAW;CAoB1B"}