@streetjs/storage 1.0.0

package/dist/plugin.js

@@ -0,0 +1,100 @@
+// src/plugin.ts
+// @streetjs/storage — plugin registration entry point (reuses the core
+// PluginModule / SandboxedApp).
+//
+// `StoragePlugin.onLoad` constructs the facade via `createStorage`, which wires
+// observability (health check + metrics) against the `metrics` / `health`
+// registries supplied on the plugin options, applies the declarative bridge
+// wiring, and exposes the live facade through the `storage` accessor.
+// `onUnload` detaches the bridges and closes the facade gracefully
+// (`storage.close()` stops the observability refresh timer).
+//
+// The `SandboxedApp` handed to a plugin exposes only `use` / `on` — it has no
+// registry to attach to — so the health / metrics registries are resolved from
+// the plugin options (mirroring how the events / queue / realtime plugins
+// resolve theirs). The plugin never touches any existing public API: it only
+// consumes the already-public `createStorage` surface (Requirements 20.1,
+// 20.2, 20.3).
+import { PluginModule } from "streetjs";
+import { createStorage } from "./facade.js";
+/**
+ * Plugin entry point that constructs and wires the application storage layer.
+ *
+ * Compatible with the core {@link PluginModule} and safe to register with a
+ * `SandboxedApp` (Requirements 20.1, 20.2). Once loaded, the application
+ * retrieves the live {@link Storage} facade through the {@link storage}
+ * accessor without any existing public API being modified (Requirement 20.3).
+ *
+ * @typeParam T - Optional per-application custom metadata map.
+ */
+export class StoragePlugin extends PluginModule {
+    name = "@streetjs/storage";
+    version = "1.0.0";
+    options;
+    storageInstance;
+    bridgeDetachers = [];
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    /**
+     * The constructed facade, or `undefined` before load / after unload. Because
+     * the `SandboxedApp` has no registry to attach to, the application retrieves
+     * the live {@link Storage} facade through this accessor after the plugin
+     * loads (Requirement 20.3).
+     */
+    get storage() {
+        return this.storageInstance;
+    }
+    /**
+     * Construct the facade (which wires observability from the configured
+     * `metrics` / `health` registries and the structural bridges), apply the
+     * declarative bridge wiring collecting any detach functions, and expose the
+     * facade. Idempotent per load: a second `onLoad` without an intervening
+     * `onUnload` reuses the already-constructed facade.
+     */
+    async onLoad(_app) {
+        if (this.storageInstance) {
+            return;
+        }
+        // `createStorage` resolves the driver and, when `metrics` / `health` are
+        // present on the config, registers storage observability against those
+        // registries and primes the gauges — so passing the plugin options through
+        // as the StorageConfig wires observability from the plugin-option
+        // registries (Requirement 23.1, 23.3). The structural events / queue /
+        // realtime bridges on `options.bridges` are likewise wired by the facade.
+        const storage = createStorage(this.options);
+        this.storageInstance = storage;
+        // Apply declarative bridge wiring, collecting any detach functions so
+        // onUnload can tear them down.
+        for (const attach of this.options.wireBridges ?? []) {
+            const detach = attach(storage);
+            if (typeof detach === "function") {
+                this.bridgeDetachers.push(detach);
+            }
+        }
+    }
+    /**
+     * Detach the declarative bridges and close the facade gracefully (which stops
+     * the observability refresh timer). Safe if never loaded.
+     */
+    async onUnload(_app) {
+        const storage = this.storageInstance;
+        const detachers = this.bridgeDetachers;
+        this.storageInstance = undefined;
+        this.bridgeDetachers = [];
+        // Detach bridges first so no bridge fires during/after teardown.
+        for (const detach of detachers) {
+            try {
+                detach();
+            }
+            catch {
+                /* best-effort detach */
+            }
+        }
+        if (storage) {
+            await storage.close();
+        }
+    }
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,uEAAuE;AACvE,gCAAgC;AAChC,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,4EAA4E;AAC5E,sEAAsE;AACtE,mEAAmE;AACnE,6DAA6D;AAC7D,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,0EAA0E;AAC1E,6EAA6E;AAC7E,0EAA0E;AAC1E,eAAe;AAEf,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EAAE,aAAa,EAAgB,MAAM,aAAa,CAAC;AA4C1D;;;;;;;;;GASG;AACH,MAAM,OAAO,aAEX,SAAQ,YAAY;IACX,IAAI,GAAG,mBAAmB,CAAC;IAC3B,OAAO,GAAG,OAAO,CAAC;IAER,OAAO,CAA0B;IAE5C,eAAe,CAAc;IAC7B,eAAe,GAAsB,EAAE,CAAC;IAEhD,YAAY,OAAgC;QAC1C,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACM,KAAK,CAAC,MAAM,CAAC,IAAkB;QACtC,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,OAAO;QACT,CAAC;QAED,yEAAyE;QACzE,uEAAuE;QACvE,2EAA2E;QAC3E,kEAAkE;QAClE,uEAAuE;QACvE,0EAA0E;QAC1E,MAAM,OAAO,GAAG,aAAa,CAAI,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC;QAE/B,sEAAsE;QACtE,+BAA+B;QAC/B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;YACpD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;YAC/B,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;gBACjC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACM,KAAK,CAAC,QAAQ,CAAC,IAAkB;QACxC,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC;QACrC,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC;QACvC,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;QACjC,IAAI,CAAC,eAAe,GAAG,EAAE,CAAC;QAC1B,iEAAiE;QACjE,KAAK,MAAM,MAAM,IAAI,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC;YACX,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;QACH,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;CACF"}

package/dist/resumable.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @streetjs/storage — the resumable upload manager.
+ *
+ * A {@link Resumable_Upload} is an upload session that can be interrupted and
+ * continued from the last persisted byte offset without restarting from the
+ * beginning (Requirement 7). {@link ResumableManager} provides this capability
+ * in a **provider-agnostic** way, mirroring {@link MultipartManager}:
+ *
+ * - When the backing {@link StorageDriver} implements the optional native
+ *   `resumable` capability, the manager delegates to the driver so a provider
+ *   with first-class resumable support (e.g. GCS resumable uploads) is used
+ *   directly.
+ * - Otherwise the manager **simulates** resumable sessions over the mandatory
+ *   driver primitives (`put`/`get`/`delete`). The accumulated bytes for a
+ *   session are persisted under a reserved key derived from the session id
+ *   (mirroring the design's `.resumable/<sessionId>` layout), and the persisted
+ *   byte offset is simply the length of that accumulated content.
+ *
+ * Semantics (Requirement 7):
+ * - {@link ResumableManager.start} creates a session and returns a session id
+ *   (Requirement 7.1); the persisted offset begins at zero.
+ * - {@link ResumableManager.resume} continues the upload from the last persisted
+ *   offset (Requirement 7.2). The supplied stream carries the object's **full**
+ *   intended content from offset zero; the manager appends only the portion of
+ *   the stream that lies beyond the already-persisted offset and skips the bytes
+ *   it already holds. Because the final object is exactly the full stream
+ *   content regardless of how many times the upload was interrupted and resumed,
+ *   completion yields an object byte-identical to an equivalent uninterrupted
+ *   upload (Requirement 7.3).
+ * - {@link ResumableManager.cancel} discards the session and its persisted data,
+ *   creating no object (Requirement 7.4) — **unless** the session is already
+ *   completing (its stream has been fully consumed and the final object is being
+ *   written), in which case the cancel is ignored and the upload is allowed to
+ *   finish and create the object (Requirement 7.5).
+ *
+ * The module depends only on the driver contract, the shared type surface, the
+ * error hierarchy, and the metadata layer, keeping the dependency direction
+ * acyclic.
+ *
+ * _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5_
+ */
+import type { NodeReadable, StorageDriver } from "./driver.js";
+import type { StorageObjectMetadata, WriteMetadata } from "./types.js";
+/**
+ * Provider-agnostic resumable upload manager built on the driver contract.
+ *
+ * A single instance is held by the facade and bound to one {@link StorageDriver}
+ * for its lifetime, so the native-vs-simulated decision (based on whether the
+ * driver exposes a `resumable` capability) is stable across every call for a
+ * given session id.
+ */
+export declare class ResumableManager {
+    /** The driver every operation is delegated to or simulated over. */
+    private readonly driver;
+    /**
+     * In-progress simulated sessions keyed by session id. Empty when the driver
+     * provides a native `resumable` capability (that path keeps no local state).
+     */
+    private readonly sessions;
+    constructor(driver: StorageDriver);
+    /** The driver's native resumable capability, when present. */
+    private get native();
+    /**
+     * Create a resumable upload session for `key` and return its session id
+     * (Requirement 7.1). When the driver has a native capability the driver mints
+     * the id and initializes the offset; otherwise a fresh id is generated and a
+     * local session records the target key and its write-time metadata. No
+     * reserved key is written yet — the persisted offset is zero until the first
+     * `resume` appends content.
+     */
+    start(key: string, metadata: WriteMetadata): Promise<string>;
+    /**
+     * Continue the upload for `sessionId` from the last persisted offset and, on
+     * completion, create the final object and return its metadata (Requirements
+     * 7.2, 7.3).
+     *
+     * `stream` carries the object's full intended content from offset zero. The
+     * manager appends only the bytes lying beyond the already-persisted offset —
+     * bytes it already holds are skipped — so the final object equals the full
+     * stream content and is byte-identical to an equivalent uninterrupted upload
+     * regardless of how many prior interruptions occurred.
+     *
+     * Once the stream is fully consumed the session enters its completing phase;
+     * from that point a concurrent {@link cancel} is ignored so the object is
+     * still created (Requirement 7.5). If a cancel arrives *before* completion,
+     * the in-progress resume aborts and creates no object (Requirement 7.4).
+     */
+    resume(sessionId: string, stream: NodeReadable): Promise<StorageObjectMetadata>;
+    /**
+     * Discard the session `sessionId` and its persisted data, creating no object
+     * (Requirement 7.4). If the session is already completing — its stream has
+     * been fully consumed and the final object is being written — the cancel is
+     * ignored so the upload finishes and creates the object (Requirement 7.5). An
+     * unknown/already-finalized session id is treated as an idempotent no-op.
+     */
+    cancel(sessionId: string): Promise<void>;
+    /**
+     * Native-capability resume: drive the driver's `offset`/`append`/`finish`
+     * primitives. As in the simulated path, `stream` carries the full content and
+     * only the portion beyond the driver's reported offset is appended, so the
+     * finished object is byte-identical to an uninterrupted upload.
+     */
+    private resumeNative;
+    /**
+     * Read the accumulated bytes persisted for a simulated session, returning an
+     * empty buffer when nothing has been persisted yet (offset zero).
+     */
+    private readPersisted;
+    /** The reserved driver key a simulated session's accumulated bytes live under. */
+    private sessionKey;
+    /**
+     * Resolve the simulated session for `sessionId`, throwing a descriptive
+     * {@link StorageError} when the id is unknown or the session has already been
+     * finalized or cancelled.
+     */
+    private requireSession;
+}
+//# sourceMappingURL=resumable.d.ts.map

package/dist/resumable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumable.d.ts","sourceRoot":"","sources":["../src/resumable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAuB,aAAa,EAAE,MAAM,aAAa,CAAC;AAGpF,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAqCvE;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IAC3B,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;gBAEpD,MAAM,EAAE,aAAa;IAIjC,8DAA8D;IAC9D,OAAO,KAAK,MAAM,GAEjB;IAED;;;;;;;OAOG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IASlE;;;;;;;;;;;;;;;OAeG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAqDrF;;;;;;OAMG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB9C;;;;;OAKG;YACW,YAAY;IAsB1B;;;OAGG;YACW,aAAa;IAK3B,kFAAkF;IAClF,OAAO,CAAC,UAAU;IAIlB;;;;OAIG;IACH,OAAO,CAAC,cAAc;CASvB"}

package/dist/resumable.js

@@ -0,0 +1,223 @@
+/**
+ * @streetjs/storage — the resumable upload manager.
+ *
+ * A {@link Resumable_Upload} is an upload session that can be interrupted and
+ * continued from the last persisted byte offset without restarting from the
+ * beginning (Requirement 7). {@link ResumableManager} provides this capability
+ * in a **provider-agnostic** way, mirroring {@link MultipartManager}:
+ *
+ * - When the backing {@link StorageDriver} implements the optional native
+ *   `resumable` capability, the manager delegates to the driver so a provider
+ *   with first-class resumable support (e.g. GCS resumable uploads) is used
+ *   directly.
+ * - Otherwise the manager **simulates** resumable sessions over the mandatory
+ *   driver primitives (`put`/`get`/`delete`). The accumulated bytes for a
+ *   session are persisted under a reserved key derived from the session id
+ *   (mirroring the design's `.resumable/<sessionId>` layout), and the persisted
+ *   byte offset is simply the length of that accumulated content.
+ *
+ * Semantics (Requirement 7):
+ * - {@link ResumableManager.start} creates a session and returns a session id
+ *   (Requirement 7.1); the persisted offset begins at zero.
+ * - {@link ResumableManager.resume} continues the upload from the last persisted
+ *   offset (Requirement 7.2). The supplied stream carries the object's **full**
+ *   intended content from offset zero; the manager appends only the portion of
+ *   the stream that lies beyond the already-persisted offset and skips the bytes
+ *   it already holds. Because the final object is exactly the full stream
+ *   content regardless of how many times the upload was interrupted and resumed,
+ *   completion yields an object byte-identical to an equivalent uninterrupted
+ *   upload (Requirement 7.3).
+ * - {@link ResumableManager.cancel} discards the session and its persisted data,
+ *   creating no object (Requirement 7.4) — **unless** the session is already
+ *   completing (its stream has been fully consumed and the final object is being
+ *   written), in which case the cancel is ignored and the upload is allowed to
+ *   finish and create the object (Requirement 7.5).
+ *
+ * The module depends only on the driver contract, the shared type surface, the
+ * error hierarchy, and the metadata layer, keeping the dependency direction
+ * acyclic.
+ *
+ * _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5_
+ */
+import { Buffer } from "node:buffer";
+import { randomUUID } from "node:crypto";
+import { StorageError } from "./errors.js";
+import { normalizeMetadata } from "./metadata.js";
+/**
+ * Reserved key prefix under which a simulated session's accumulated bytes are
+ * persisted via the driver primitives. Session content lives at
+ * `${SESSION_KEY_PREFIX}<sessionId>` and is removed on completion/cancel, so it
+ * never remains visible after a resumable upload finalizes.
+ */
+const SESSION_KEY_PREFIX = ".resumable/";
+/** Write metadata used when persisting a session's (transient) accumulated bytes. */
+const SESSION_WRITE_METADATA = { contentType: "application/octet-stream" };
+/**
+ * Provider-agnostic resumable upload manager built on the driver contract.
+ *
+ * A single instance is held by the facade and bound to one {@link StorageDriver}
+ * for its lifetime, so the native-vs-simulated decision (based on whether the
+ * driver exposes a `resumable` capability) is stable across every call for a
+ * given session id.
+ */
+export class ResumableManager {
+    /** The driver every operation is delegated to or simulated over. */
+    driver;
+    /**
+     * In-progress simulated sessions keyed by session id. Empty when the driver
+     * provides a native `resumable` capability (that path keeps no local state).
+     */
+    sessions = new Map();
+    constructor(driver) {
+        this.driver = driver;
+    }
+    /** The driver's native resumable capability, when present. */
+    get native() {
+        return this.driver.resumable;
+    }
+    /**
+     * Create a resumable upload session for `key` and return its session id
+     * (Requirement 7.1). When the driver has a native capability the driver mints
+     * the id and initializes the offset; otherwise a fresh id is generated and a
+     * local session records the target key and its write-time metadata. No
+     * reserved key is written yet — the persisted offset is zero until the first
+     * `resume` appends content.
+     */
+    async start(key, metadata) {
+        if (this.native !== undefined) {
+            return this.native.start(key, metadata);
+        }
+        const sessionId = randomUUID();
+        this.sessions.set(sessionId, { key, metadata, completing: false, cancelled: false });
+        return sessionId;
+    }
+    /**
+     * Continue the upload for `sessionId` from the last persisted offset and, on
+     * completion, create the final object and return its metadata (Requirements
+     * 7.2, 7.3).
+     *
+     * `stream` carries the object's full intended content from offset zero. The
+     * manager appends only the bytes lying beyond the already-persisted offset —
+     * bytes it already holds are skipped — so the final object equals the full
+     * stream content and is byte-identical to an equivalent uninterrupted upload
+     * regardless of how many prior interruptions occurred.
+     *
+     * Once the stream is fully consumed the session enters its completing phase;
+     * from that point a concurrent {@link cancel} is ignored so the object is
+     * still created (Requirement 7.5). If a cancel arrives *before* completion,
+     * the in-progress resume aborts and creates no object (Requirement 7.4).
+     */
+    async resume(sessionId, stream) {
+        if (this.native !== undefined) {
+            return this.resumeNative(this.native, sessionId, stream);
+        }
+        const session = this.requireSession(sessionId);
+        const reservedKey = this.sessionKey(sessionId);
+        // The persisted content (and therefore the offset) is the single source of
+        // truth for how many bytes have already been stored for this session.
+        let persisted = await this.readPersisted(reservedKey);
+        let seen = 0;
+        for await (const chunk of stream) {
+            // A cancel that arrived before completion aborts the resume and leaves no
+            // final object (Requirement 7.4); the reserved data has already been
+            // discarded by cancel, but delete again defensively in case this resume
+            // wrote after the cancel began.
+            if (session.cancelled) {
+                await this.driver.delete(reservedKey);
+                throw new StorageError(`Resumable upload session "${sessionId}" was cancelled during resume.`);
+            }
+            const buf = toBuffer(chunk);
+            const chunkEnd = seen + buf.byteLength;
+            // Append only the portion of this chunk that lies beyond the persisted
+            // offset; bytes at positions already persisted are skipped.
+            if (chunkEnd > persisted.byteLength) {
+                const skip = Math.max(0, persisted.byteLength - seen);
+                const toAppend = buf.subarray(skip);
+                persisted = Buffer.concat([persisted, toAppend]);
+                await this.driver.put(reservedKey, new Uint8Array(persisted), SESSION_WRITE_METADATA);
+            }
+            seen = chunkEnd;
+        }
+        // Completion phase: from here the upload is committing, so a concurrent
+        // cancel is ignored and the object is still created (Requirement 7.5).
+        session.completing = true;
+        const metadata = await this.driver.put(session.key, new Uint8Array(persisted), session.metadata);
+        await this.driver.delete(reservedKey);
+        this.sessions.delete(sessionId);
+        return normalizeMetadata(metadata);
+    }
+    /**
+     * Discard the session `sessionId` and its persisted data, creating no object
+     * (Requirement 7.4). If the session is already completing — its stream has
+     * been fully consumed and the final object is being written — the cancel is
+     * ignored so the upload finishes and creates the object (Requirement 7.5). An
+     * unknown/already-finalized session id is treated as an idempotent no-op.
+     */
+    async cancel(sessionId) {
+        if (this.native !== undefined) {
+            await this.native.cancel(sessionId);
+            return;
+        }
+        const session = this.sessions.get(sessionId);
+        if (session === undefined) {
+            return;
+        }
+        // Already committing — let the in-flight resume finish and create the object.
+        if (session.completing) {
+            return;
+        }
+        session.cancelled = true;
+        await this.driver.delete(this.sessionKey(sessionId));
+        this.sessions.delete(sessionId);
+    }
+    /**
+     * Native-capability resume: drive the driver's `offset`/`append`/`finish`
+     * primitives. As in the simulated path, `stream` carries the full content and
+     * only the portion beyond the driver's reported offset is appended, so the
+     * finished object is byte-identical to an uninterrupted upload.
+     */
+    async resumeNative(native, sessionId, stream) {
+        let offset = await native.offset(sessionId);
+        let seen = 0;
+        for await (const chunk of stream) {
+            const buf = toBuffer(chunk);
+            const chunkEnd = seen + buf.byteLength;
+            if (chunkEnd > offset) {
+                const skip = Math.max(0, offset - seen);
+                const toAppend = buf.subarray(skip);
+                offset = await native.append(sessionId, new Uint8Array(toAppend), offset);
+            }
+            seen = chunkEnd;
+        }
+        return normalizeMetadata(await native.finish(sessionId));
+    }
+    /**
+     * Read the accumulated bytes persisted for a simulated session, returning an
+     * empty buffer when nothing has been persisted yet (offset zero).
+     */
+    async readPersisted(reservedKey) {
+        const result = await this.driver.get(reservedKey);
+        return result.found ? Buffer.from(result.bytes) : Buffer.alloc(0);
+    }
+    /** The reserved driver key a simulated session's accumulated bytes live under. */
+    sessionKey(sessionId) {
+        return `${SESSION_KEY_PREFIX}${sessionId}`;
+    }
+    /**
+     * Resolve the simulated session for `sessionId`, throwing a descriptive
+     * {@link StorageError} when the id is unknown or the session has already been
+     * finalized or cancelled.
+     */
+    requireSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session === undefined) {
+            throw new StorageError(`Unknown or already-finalized resumable upload session "${sessionId}".`);
+        }
+        return session;
+    }
+}
+/** Normalize a stream chunk to a `Buffer` without copying when already one. */
+function toBuffer(chunk) {
+    return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+}
+//# sourceMappingURL=resumable.js.map

package/dist/resumable.js.map

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

package/dist/search.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @streetjs/storage — attribute search / filtering over the flat key space
+ * (task 18.1).
+ *
+ * Object stores expose only a flat key space plus per-object metadata, so
+ * search is implemented as a provider-agnostic filter over the two mandatory
+ * driver primitives {@link StorageDriver.list} and {@link StorageDriver.stat}:
+ *
+ * 1. Enumerate candidate keys with `driver.list(prefix)` (the prefix filter is
+ *    pushed down to the driver; an absent prefix lists the whole key space).
+ * 2. For each candidate, read its typed metadata with `driver.stat(key)`.
+ * 3. Keep the object only when it satisfies **every** supplied filter
+ *    (conjunctive / AND semantics — Requirement 16.2); when no object satisfies
+ *    the filters the result is the empty set (Requirement 16.3).
+ *
+ * The supported filters mirror {@link SearchFilters} (Requirement 16.1):
+ *
+ * - `prefix`         — key begins with the prefix (pushed to `driver.list`).
+ * - `contentType`    — exact content-type match.
+ * - `owner`          — exact owner match.
+ * - `tenant`         — exact tenant match.
+ * - `minSize`        — size ≥ minSize (inclusive lower bound).
+ * - `maxSize`        — size ≤ maxSize (inclusive upper bound).
+ * - `updatedAfter`   — updatedAt ≥ updatedAfter (inclusive lower time bound).
+ * - `updatedBefore`  — updatedAt ≤ updatedBefore (inclusive upper time bound).
+ * - `metadata`       — every supplied custom field deep-equals the object's
+ *                      corresponding `custom` field.
+ *
+ * Reserved internal key spaces used by the cross-cutting layers
+ * (`.versions/`, `.multipart/`, `.resumable/`, `.archive/`) are excluded from
+ * results unless the supplied `prefix` explicitly targets one of them, so a
+ * broad search returns only user-visible objects and never leaks framework
+ * bookkeeping keys.
+ *
+ * The result preserves the {@link StorageListItem} shape returned by
+ * `driver.list`, so `search` composes with the rest of the facade surface.
+ *
+ * _Requirements: 16.1, 16.2, 16.3_
+ */
+import type { StorageDriver } from "./driver.js";
+import type { SearchFilters, StorageListItem } from "./types.js";
+/**
+ * Return the stored objects that satisfy **every** supplied filter, evaluated
+ * over `driver.list` + `driver.stat`.
+ *
+ * The prefix filter is delegated to `driver.list`; the remaining filters are
+ * applied against each candidate's metadata. Objects whose metadata cannot be
+ * read (e.g. removed concurrently between `list` and `stat`) are skipped. When
+ * no object satisfies the filters, an empty array is returned (Requirement
+ * 16.3).
+ *
+ * @param driver  The storage driver to search over.
+ * @param filters The conjunctive set of {@link SearchFilters} to apply.
+ * @returns The matching objects as {@link StorageListItem}s.
+ */
+export declare function searchObjects(driver: StorageDriver, filters?: SearchFilters): Promise<StorageListItem[]>;
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAyB,MAAM,YAAY,CAAC;AAcxF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,eAAe,EAAE,CAAC,CA2B5B"}