@streetjs/storage 1.0.0

package/dist/integrations/events.js

@@ -0,0 +1,111 @@
+/**
+ * @streetjs/storage — the Events integration bridge.
+ *
+ * This module publishes typed storage lifecycle events (`storage.uploaded`,
+ * `storage.deleted`, `storage.updated`, `storage.moved`, `storage.restored`,
+ * `storage.expired`) through an events layer, each payload carrying the affected
+ * object key and (when available) its {@link StorageObjectMetadata}
+ * (Requirements 18.1, 18.2). Lifecycle-rule actions publish through this same
+ * bridge (Requirement 13.4).
+ *
+ * Following the events package's structural-interface pattern, the bridge
+ * depends only on the minimal {@link EventsLike} shape declared in `types.ts`
+ * (any object exposing `publish(event, payload)`), never on the concrete
+ * `@streetjs/events` package, so there is no hard dependency and no circular
+ * dependency (Requirements 18.3, 28.3). {@link EventsLike} is re-exported here
+ * for convenience; it is intentionally the single definition that lives in
+ * `types.ts`.
+ *
+ * **Never throws into the operation path.** Every publish is wrapped so that a
+ * synchronous throw or an asynchronous rejection from the underlying events
+ * layer is swallowed: a publish failure must never break the storage operation
+ * that triggered it. This mirrors the graceful-degradation guarantee the Queue
+ * and Realtime bridges also uphold.
+ *
+ * The facade constructs a {@link StorageEventPublisher} via
+ * {@link bridgeStorageEvents} only when `config.bridges?.events` is provided;
+ * when it is absent the facade holds no publisher and event publication is a
+ * complete no-op.
+ *
+ * _Requirements: 13.4, 18.1, 18.2, 18.3, 28.3_
+ */
+/**
+ * Map an applied {@link LifecycleOutcome} action onto its typed storage event
+ * name. `archived` is surfaced as `storage.moved` because archiving relocates
+ * the object under the reserved archive prefix; the original action is retained
+ * in the payload so listeners can still tell the two apart.
+ */
+const LIFECYCLE_EVENT_BY_ACTION = {
+    deleted: "storage.deleted",
+    expired: "storage.expired",
+    moved: "storage.moved",
+    archived: "storage.moved",
+};
+/**
+ * Isolate a single publish call. A synchronous throw is caught; a returned
+ * promise has its rejection swallowed. Either way nothing propagates back to the
+ * storage operation that triggered the event, satisfying the "never throw into
+ * the operation path" guarantee.
+ */
+function safePublish(events, event, payload) {
+    try {
+        const result = events.publish(event, payload);
+        if (result !== undefined && result !== null && typeof result.then === "function") {
+            // Fire-and-forget: absorb any asynchronous rejection.
+            result.then(undefined, () => {
+                /* swallow — a publish failure must not break the storage op */
+            });
+        }
+    }
+    catch {
+        // swallow — a publish failure must not break the storage op
+    }
+}
+/**
+ * Create a {@link StorageEventPublisher} that publishes typed storage events
+ * through the supplied structural {@link EventsLike} bridge.
+ *
+ * The returned publisher is what the facade wires into its object operations
+ * (`put` → uploaded/updated, `delete` → deleted, `move`/`rename` → moved,
+ * `restoreVersion` → restored) and its lifecycle evaluation (`applyLifecycle`
+ * → deleted/expired/moved via {@link StorageEventPublisher.lifecycle}). Every
+ * method is guaranteed never to throw into the caller.
+ *
+ * ```ts
+ * const publisher = bridgeStorageEvents(events);
+ * publisher.uploaded(metadata); // publishes "storage.uploaded" — never throws
+ * ```
+ */
+export function bridgeStorageEvents(events) {
+    const publish = (event, payload) => {
+        safePublish(events, event, payload);
+    };
+    return {
+        publish,
+        uploaded(metadata) {
+            publish("storage.uploaded", { key: metadata.key, metadata });
+        },
+        updated(metadata) {
+            publish("storage.updated", { key: metadata.key, metadata });
+        },
+        deleted(key, metadata) {
+            publish("storage.deleted", { key, metadata });
+        },
+        moved(metadata) {
+            publish("storage.moved", { key: metadata.key, metadata });
+        },
+        restored(metadata) {
+            publish("storage.restored", { key: metadata.key, metadata });
+        },
+        expired(key, metadata) {
+            publish("storage.expired", { key, metadata });
+        },
+        lifecycle(outcome) {
+            publish(LIFECYCLE_EVENT_BY_ACTION[outcome.action], {
+                key: outcome.key,
+                action: outcome.action,
+            });
+        },
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/integrations/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/integrations/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAmFH;;;;;GAKG;AACH,MAAM,yBAAyB,GAAmE;IAChG,OAAO,EAAE,iBAAiB;IAC1B,OAAO,EAAE,iBAAiB;IAC1B,KAAK,EAAE,eAAe;IACtB,QAAQ,EAAE,eAAe;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,SAAS,WAAW,CAAC,MAAkB,EAAE,KAAuB,EAAE,OAA4B;IAC5F,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,OAAQ,MAAwB,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACpG,sDAAsD;YACrD,MAAwB,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;gBAC7C,+DAA+D;YACjE,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAkB;IACpD,MAAM,OAAO,GAAG,CAAC,KAAuB,EAAE,OAA4B,EAAQ,EAAE;QAC9E,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC,CAAC;IAEF,OAAO;QACL,OAAO;QACP,QAAQ,CAAC,QAAQ;YACf,OAAO,CAAC,kBAAkB,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,CAAC,QAAQ;YACd,OAAO,CAAC,iBAAiB,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO,CAAC,GAAG,EAAE,QAAQ;YACnB,OAAO,CAAC,iBAAiB,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QAChD,CAAC;QACD,KAAK,CAAC,QAAQ;YACZ,OAAO,CAAC,eAAe,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,QAAQ,CAAC,QAAQ;YACf,OAAO,CAAC,kBAAkB,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,CAAC,GAAG,EAAE,QAAQ;YACnB,OAAO,CAAC,iBAAiB,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QAChD,CAAC;QACD,SAAS,CAAC,OAAO;YACf,OAAO,CAAC,yBAAyB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;gBACjD,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/integrations/queue.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @streetjs/storage — the Queue integration bridge.
+ *
+ * This module hands heavy, out-of-band work off to a background queue so that
+ * storage operations never block on it: thumbnail generation, virus scanning,
+ * OCR, PDF processing, transcoding, image optimization, and archive creation
+ * (Requirement 17.1). Each job is dispatched through the minimal
+ * {@link QueueLike} shape declared in `types.ts` (any object exposing
+ * `dispatch(job, payload)`), never through the concrete `@streetjs/queue`
+ * package, so there is no hard dependency and no circular dependency
+ * (Requirements 17.2, 28.3). {@link QueueLike} is re-exported here for
+ * convenience; it is intentionally the single definition that lives in
+ * `types.ts`.
+ *
+ * **Never throws into the operation path.** Every dispatch is wrapped so that a
+ * synchronous throw or an asynchronous rejection from the underlying queue is
+ * swallowed: a dispatch failure must never break the storage operation that
+ * triggered it (Requirement 17.4). Equally, when no queue bridge is configured
+ * the facade holds no publisher and job dispatch is a complete no-op — storage
+ * operations proceed unaffected (Requirement 17.3). This mirrors the
+ * graceful-degradation guarantee the Events and Realtime bridges also uphold.
+ *
+ * The facade constructs a {@link StorageQueuePublisher} via
+ * {@link bridgeStorageQueue} only when `config.bridges?.queue` is provided.
+ *
+ * _Requirements: 17.1, 17.2, 17.3, 17.4, 28.3_
+ */
+import type { QueueLike } from "../types.js";
+export type { QueueLike } from "../types.js";
+/**
+ * The exhaustive set of background job names the storage framework dispatches
+ * (Requirement 17.1). Every heavy, out-of-band task maps onto exactly one of
+ * these names.
+ */
+export type StorageJobName = "storage.thumbnail" | "storage.virus-scan" | "storage.ocr" | "storage.pdf-process" | "storage.transcode" | "storage.image-optimize" | "storage.archive";
+/**
+ * The payload dispatched with every storage job. It always carries the affected
+ * object `key` and, when the triggering operation has it in hand, arbitrary
+ * job-specific `options` the worker uses to perform the task.
+ */
+export interface StorageJobPayload {
+    /** The affected object key (always present). */
+    readonly key: string;
+    /** Job-specific options passed through to the worker (optional). */
+    readonly options?: Record<string, unknown>;
+}
+/**
+ * The publisher the facade holds and can call to hand heavy work to the queue.
+ * Every method is fire-and-forget and guaranteed never to throw into the
+ * caller: the underlying dispatch is isolated so a failing (or absent) queue
+ * cannot break a storage operation (Requirements 17.3, 17.4).
+ */
+export interface StorageQueuePublisher {
+    /**
+     * Dispatch an already-named background job with the given payload. Never
+     * throws. The typed convenience methods below are thin wrappers over this.
+     */
+    dispatch(job: StorageJobName, payload: StorageJobPayload): void;
+    /** Dispatch a thumbnail-generation job for an object. */
+    thumbnail(key: string, options?: Record<string, unknown>): void;
+    /** Dispatch a virus-scan job for an object. */
+    virusScan(key: string, options?: Record<string, unknown>): void;
+    /** Dispatch an OCR (text-extraction) job for an object. */
+    ocr(key: string, options?: Record<string, unknown>): void;
+    /** Dispatch a PDF-processing job for an object. */
+    pdfProcess(key: string, options?: Record<string, unknown>): void;
+    /** Dispatch a media-transcoding job for an object. */
+    transcode(key: string, options?: Record<string, unknown>): void;
+    /** Dispatch an image-optimization job for an object. */
+    imageOptimize(key: string, options?: Record<string, unknown>): void;
+    /** Dispatch an archive-creation job for an object. */
+    archive(key: string, options?: Record<string, unknown>): void;
+}
+/**
+ * Create a {@link StorageQueuePublisher} that dispatches background jobs through
+ * the supplied structural {@link QueueLike} bridge.
+ *
+ * The returned publisher is what the facade wires into any heavy, out-of-band
+ * work (thumbnail generation, virus scanning, OCR, PDF processing, transcoding,
+ * image optimization, archive creation). Every method is guaranteed never to
+ * throw into the caller.
+ *
+ * ```ts
+ * const publisher = bridgeStorageQueue(queue);
+ * publisher.thumbnail("photo.png"); // dispatches "storage.thumbnail" — never throws
+ * ```
+ */
+export declare function bridgeStorageQueue(queue: QueueLike): StorageQueuePublisher;
+//# sourceMappingURL=queue.d.ts.map

package/dist/integrations/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/integrations/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAK7C,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB,mBAAmB,GACnB,oBAAoB,GACpB,aAAa,GACb,qBAAqB,GACrB,mBAAmB,GACnB,wBAAwB,GACxB,iBAAiB,CAAC;AAEtB;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAEhE,yDAAyD;IACzD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEhE,+CAA+C;IAC/C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEhE,2DAA2D;IAC3D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE1D,mDAAmD;IACnD,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEjE,sDAAsD;IACtD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEhE,wDAAwD;IACxD,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEpE,sDAAsD;IACtD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC/D;AAsBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,qBAAqB,CA6B1E"}

package/dist/integrations/queue.js

@@ -0,0 +1,91 @@
+/**
+ * @streetjs/storage — the Queue integration bridge.
+ *
+ * This module hands heavy, out-of-band work off to a background queue so that
+ * storage operations never block on it: thumbnail generation, virus scanning,
+ * OCR, PDF processing, transcoding, image optimization, and archive creation
+ * (Requirement 17.1). Each job is dispatched through the minimal
+ * {@link QueueLike} shape declared in `types.ts` (any object exposing
+ * `dispatch(job, payload)`), never through the concrete `@streetjs/queue`
+ * package, so there is no hard dependency and no circular dependency
+ * (Requirements 17.2, 28.3). {@link QueueLike} is re-exported here for
+ * convenience; it is intentionally the single definition that lives in
+ * `types.ts`.
+ *
+ * **Never throws into the operation path.** Every dispatch is wrapped so that a
+ * synchronous throw or an asynchronous rejection from the underlying queue is
+ * swallowed: a dispatch failure must never break the storage operation that
+ * triggered it (Requirement 17.4). Equally, when no queue bridge is configured
+ * the facade holds no publisher and job dispatch is a complete no-op — storage
+ * operations proceed unaffected (Requirement 17.3). This mirrors the
+ * graceful-degradation guarantee the Events and Realtime bridges also uphold.
+ *
+ * The facade constructs a {@link StorageQueuePublisher} via
+ * {@link bridgeStorageQueue} only when `config.bridges?.queue` is provided.
+ *
+ * _Requirements: 17.1, 17.2, 17.3, 17.4, 28.3_
+ */
+/**
+ * Isolate a single dispatch call. A synchronous throw is caught; a returned
+ * promise has its rejection swallowed. Either way nothing propagates back to the
+ * storage operation that triggered the job, satisfying the "never throw into the
+ * operation path" guarantee (Requirement 17.4).
+ */
+function safeDispatch(queue, job, payload) {
+    try {
+        const result = queue.dispatch(job, payload);
+        if (result !== undefined && result !== null && typeof result.then === "function") {
+            // Fire-and-forget: absorb any asynchronous rejection.
+            result.then(undefined, () => {
+                /* swallow — a dispatch failure must not break the storage op */
+            });
+        }
+    }
+    catch {
+        // swallow — a dispatch failure must not break the storage op
+    }
+}
+/**
+ * Create a {@link StorageQueuePublisher} that dispatches background jobs through
+ * the supplied structural {@link QueueLike} bridge.
+ *
+ * The returned publisher is what the facade wires into any heavy, out-of-band
+ * work (thumbnail generation, virus scanning, OCR, PDF processing, transcoding,
+ * image optimization, archive creation). Every method is guaranteed never to
+ * throw into the caller.
+ *
+ * ```ts
+ * const publisher = bridgeStorageQueue(queue);
+ * publisher.thumbnail("photo.png"); // dispatches "storage.thumbnail" — never throws
+ * ```
+ */
+export function bridgeStorageQueue(queue) {
+    const dispatch = (job, payload) => {
+        safeDispatch(queue, job, payload);
+    };
+    return {
+        dispatch,
+        thumbnail(key, options) {
+            dispatch("storage.thumbnail", { key, options });
+        },
+        virusScan(key, options) {
+            dispatch("storage.virus-scan", { key, options });
+        },
+        ocr(key, options) {
+            dispatch("storage.ocr", { key, options });
+        },
+        pdfProcess(key, options) {
+            dispatch("storage.pdf-process", { key, options });
+        },
+        transcode(key, options) {
+            dispatch("storage.transcode", { key, options });
+        },
+        imageOptimize(key, options) {
+            dispatch("storage.image-optimize", { key, options });
+        },
+        archive(key, options) {
+            dispatch("storage.archive", { key, options });
+        },
+    };
+}
+//# sourceMappingURL=queue.js.map

package/dist/integrations/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/integrations/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAsEH;;;;;GAKG;AACH,SAAS,YAAY,CAAC,KAAgB,EAAE,GAAmB,EAAE,OAA0B;IACrF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC5C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,OAAQ,MAAwB,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACpG,sDAAsD;YACrD,MAAwB,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;gBAC7C,gEAAgE;YAClE,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;IAC/D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAgB;IACjD,MAAM,QAAQ,GAAG,CAAC,GAAmB,EAAE,OAA0B,EAAQ,EAAE;QACzE,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC;IAEF,OAAO;QACL,QAAQ;QACR,SAAS,CAAC,GAAG,EAAE,OAAO;YACpB,QAAQ,CAAC,mBAAmB,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,SAAS,CAAC,GAAG,EAAE,OAAO;YACpB,QAAQ,CAAC,oBAAoB,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QACnD,CAAC;QACD,GAAG,CAAC,GAAG,EAAE,OAAO;YACd,QAAQ,CAAC,aAAa,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QAC5C,CAAC;QACD,UAAU,CAAC,GAAG,EAAE,OAAO;YACrB,QAAQ,CAAC,qBAAqB,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,SAAS,CAAC,GAAG,EAAE,OAAO;YACpB,QAAQ,CAAC,mBAAmB,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,aAAa,CAAC,GAAG,EAAE,OAAO;YACxB,QAAQ,CAAC,wBAAwB,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,CAAC,GAAG,EAAE,OAAO;YAClB,QAAQ,CAAC,iBAAiB,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QAChD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/integrations/realtime.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @streetjs/storage — the Realtime integration bridge.
+ *
+ * This module broadcasts live upload-lifecycle events — `upload.started`,
+ * `upload.progress`, `upload.completed`, `upload.failed` — as an upload changes
+ * state, so connected clients can display live progress (Requirement 19.1).
+ * Each broadcast goes out through the minimal {@link RealtimeLike} shape
+ * declared in `types.ts` (any object exposing
+ * `broadcast(channel, event, payload)`), never through the concrete
+ * `@streetjs/realtime` package, so there is no hard dependency and no circular
+ * dependency (Requirements 19.2, 28.3). {@link RealtimeLike} is re-exported here
+ * for convenience; it is intentionally the single definition that lives in
+ * `types.ts`.
+ *
+ * **Never throws into the operation path.** Every broadcast is wrapped so that a
+ * synchronous throw or an asynchronous rejection from the underlying realtime
+ * layer is swallowed: a broadcast failure must never break the upload that
+ * triggered it (Requirement 19.3). Equally, when no realtime bridge is
+ * configured the facade holds no publisher and broadcasting is a complete no-op
+ * — uploads proceed unaffected (Requirement 19.3). This mirrors the
+ * graceful-degradation guarantee the Events and Queue bridges also uphold.
+ *
+ * The facade constructs a {@link StorageRealtimePublisher} via
+ * {@link bridgeStorageRealtime} only when `config.bridges?.realtime` is
+ * provided.
+ *
+ * _Requirements: 19.1, 19.2, 19.3, 28.3_
+ */
+import type { RealtimeLike } from "../types.js";
+export type { RealtimeLike } from "../types.js";
+/**
+ * The channel every upload-lifecycle event is broadcast on. A single channel
+ * keeps the client subscription surface simple; the typed
+ * {@link StorageRealtimeEventName} distinguishes the state transitions, and the
+ * payload's `key` distinguishes the upload.
+ */
+export declare const STORAGE_UPLOAD_CHANNEL: "storage.uploads";
+/**
+ * The exhaustive set of upload-lifecycle event names the storage framework
+ * broadcasts (Requirement 19.1). Every upload state transition maps onto
+ * exactly one of these names.
+ */
+export type StorageRealtimeEventName = "upload.started" | "upload.progress" | "upload.completed" | "upload.failed";
+/**
+ * The payload broadcast with every upload-lifecycle event. It always carries the
+ * affected object `key` and, depending on the transition, optional progress
+ * counters or an error description.
+ */
+export interface StorageRealtimeEventPayload {
+    /** The affected object key (always present). */
+    readonly key: string;
+    /** Bytes transferred so far, present on `upload.progress`. */
+    readonly bytesTransferred?: number;
+    /** Total expected bytes when known, present on `upload.progress`. */
+    readonly totalBytes?: number;
+    /** A human-readable failure reason, present on `upload.failed`. */
+    readonly error?: string;
+}
+/**
+ * The publisher the facade holds and calls at each upload state transition.
+ * Every method is fire-and-forget and guaranteed never to throw into the caller:
+ * the underlying broadcast is isolated so a failing (or absent) realtime layer
+ * cannot break an upload (Requirement 19.3).
+ */
+export interface StorageRealtimePublisher {
+    /**
+     * Broadcast an already-named upload event with the given payload. Never
+     * throws. The typed convenience methods below are thin wrappers over this.
+     */
+    broadcast(event: StorageRealtimeEventName, payload: StorageRealtimeEventPayload): void;
+    /** Broadcast `upload.started` when an upload begins. */
+    started(key: string): void;
+    /** Broadcast `upload.progress` as bytes transfer. */
+    progress(key: string, bytesTransferred: number, totalBytes?: number): void;
+    /** Broadcast `upload.completed` when an upload finishes successfully. */
+    completed(key: string): void;
+    /** Broadcast `upload.failed` when an upload errors out. */
+    failed(key: string, error?: string): void;
+}
+/**
+ * Create a {@link StorageRealtimePublisher} that broadcasts upload-lifecycle
+ * events through the supplied structural {@link RealtimeLike} bridge.
+ *
+ * The returned publisher is what the facade wires into its streaming/resumable
+ * upload paths (`putStream`/`resumeUpload` → started/completed, and failed on
+ * error). Every method is guaranteed never to throw into the caller.
+ *
+ * ```ts
+ * const publisher = bridgeStorageRealtime(realtime);
+ * publisher.started("video.mp4");   // broadcasts "upload.started" — never throws
+ * publisher.completed("video.mp4"); // broadcasts "upload.completed" — never throws
+ * ```
+ */
+export declare function bridgeStorageRealtime(realtime: RealtimeLike): StorageRealtimePublisher;
+//# sourceMappingURL=realtime.d.ts.map

package/dist/integrations/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/integrations/realtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAG,iBAA0B,CAAC;AAEjE;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,CAAC;AAEpB;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,wBAAwB,EAAE,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAEvF,wDAAwD;IACxD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3E,yEAAyE;IACzE,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,2DAA2D;IAC3D,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AA0BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,wBAAwB,CAoBtF"}

package/dist/integrations/realtime.js

@@ -0,0 +1,90 @@
+/**
+ * @streetjs/storage — the Realtime integration bridge.
+ *
+ * This module broadcasts live upload-lifecycle events — `upload.started`,
+ * `upload.progress`, `upload.completed`, `upload.failed` — as an upload changes
+ * state, so connected clients can display live progress (Requirement 19.1).
+ * Each broadcast goes out through the minimal {@link RealtimeLike} shape
+ * declared in `types.ts` (any object exposing
+ * `broadcast(channel, event, payload)`), never through the concrete
+ * `@streetjs/realtime` package, so there is no hard dependency and no circular
+ * dependency (Requirements 19.2, 28.3). {@link RealtimeLike} is re-exported here
+ * for convenience; it is intentionally the single definition that lives in
+ * `types.ts`.
+ *
+ * **Never throws into the operation path.** Every broadcast is wrapped so that a
+ * synchronous throw or an asynchronous rejection from the underlying realtime
+ * layer is swallowed: a broadcast failure must never break the upload that
+ * triggered it (Requirement 19.3). Equally, when no realtime bridge is
+ * configured the facade holds no publisher and broadcasting is a complete no-op
+ * — uploads proceed unaffected (Requirement 19.3). This mirrors the
+ * graceful-degradation guarantee the Events and Queue bridges also uphold.
+ *
+ * The facade constructs a {@link StorageRealtimePublisher} via
+ * {@link bridgeStorageRealtime} only when `config.bridges?.realtime` is
+ * provided.
+ *
+ * _Requirements: 19.1, 19.2, 19.3, 28.3_
+ */
+/**
+ * The channel every upload-lifecycle event is broadcast on. A single channel
+ * keeps the client subscription surface simple; the typed
+ * {@link StorageRealtimeEventName} distinguishes the state transitions, and the
+ * payload's `key` distinguishes the upload.
+ */
+export const STORAGE_UPLOAD_CHANNEL = "storage.uploads";
+/**
+ * Isolate a single broadcast call. A synchronous throw is caught; a returned
+ * promise has its rejection swallowed. Either way nothing propagates back to the
+ * upload that triggered the event, satisfying the "never throw into the
+ * operation path" guarantee (Requirement 19.3).
+ */
+function safeBroadcast(realtime, event, payload) {
+    try {
+        const result = realtime.broadcast(STORAGE_UPLOAD_CHANNEL, event, payload);
+        if (result !== undefined && result !== null && typeof result.then === "function") {
+            // Fire-and-forget: absorb any asynchronous rejection.
+            result.then(undefined, () => {
+                /* swallow — a broadcast failure must not break the upload */
+            });
+        }
+    }
+    catch {
+        // swallow — a broadcast failure must not break the upload
+    }
+}
+/**
+ * Create a {@link StorageRealtimePublisher} that broadcasts upload-lifecycle
+ * events through the supplied structural {@link RealtimeLike} bridge.
+ *
+ * The returned publisher is what the facade wires into its streaming/resumable
+ * upload paths (`putStream`/`resumeUpload` → started/completed, and failed on
+ * error). Every method is guaranteed never to throw into the caller.
+ *
+ * ```ts
+ * const publisher = bridgeStorageRealtime(realtime);
+ * publisher.started("video.mp4");   // broadcasts "upload.started" — never throws
+ * publisher.completed("video.mp4"); // broadcasts "upload.completed" — never throws
+ * ```
+ */
+export function bridgeStorageRealtime(realtime) {
+    const broadcast = (event, payload) => {
+        safeBroadcast(realtime, event, payload);
+    };
+    return {
+        broadcast,
+        started(key) {
+            broadcast("upload.started", { key });
+        },
+        progress(key, bytesTransferred, totalBytes) {
+            broadcast("upload.progress", { key, bytesTransferred, totalBytes });
+        },
+        completed(key) {
+            broadcast("upload.completed", { key });
+        },
+        failed(key, error) {
+            broadcast("upload.failed", { key, error });
+        },
+    };
+}
+//# sourceMappingURL=realtime.js.map

package/dist/integrations/realtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.js","sourceRoot":"","sources":["../../src/integrations/realtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AASH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,iBAA0B,CAAC;AAuDjE;;;;;GAKG;AACH,SAAS,aAAa,CACpB,QAAsB,EACtB,KAA+B,EAC/B,OAAoC;IAEpC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,sBAAsB,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAC1E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,OAAQ,MAAwB,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACpG,sDAAsD;YACrD,MAAwB,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;gBAC7C,6DAA6D;YAC/D,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;IAC5D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAsB;IAC1D,MAAM,SAAS,GAAG,CAAC,KAA+B,EAAE,OAAoC,EAAQ,EAAE;QAChG,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC,CAAC;IAEF,OAAO;QACL,SAAS;QACT,OAAO,CAAC,GAAG;YACT,SAAS,CAAC,gBAAgB,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,QAAQ,CAAC,GAAG,EAAE,gBAAgB,EAAE,UAAU;YACxC,SAAS,CAAC,iBAAiB,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,SAAS,CAAC,GAAG;YACX,SAAS,CAAC,kBAAkB,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QACzC,CAAC;QACD,MAAM,CAAC,GAAG,EAAE,KAAK;YACf,SAAS,CAAC,eAAe,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @streetjs/storage — the lifecycle engine.
+ *
+ * Lifecycle rules act on objects automatically based on their age or state, so
+ * stored objects are cleaned up, archived, or tiered over time (Requirement
+ * 13). {@link LifecycleEngine} evaluates a single {@link LifecycleRule} and
+ * applies its action to every qualifying object in a **provider-agnostic** way:
+ *
+ * - When the backing {@link StorageDriver} implements the optional native
+ *   `lifecycle` capability, the engine delegates evaluation to the driver so a
+ *   provider with first-class lifecycle policies (e.g. S3 lifecycle
+ *   configuration) is used directly.
+ * - Otherwise the engine **simulates** the rule over the mandatory driver
+ *   primitives (`list`/`stat`/`get`/`put`/`delete`). It enumerates candidate
+ *   keys with `list`, reads each object's `createdAt` with `stat`, computes the
+ *   object's age relative to the injected {@link Clock}, and applies the rule's
+ *   action to the objects whose age meets the rule's threshold. This is what
+ *   lets the zero-dependency drivers simulate lifecycle entirely in memory /
+ *   over the local filesystem (Requirement 13.3).
+ *
+ * Supported rule types (Requirement 13.1):
+ * - `delete-after-days` — delete objects older than `days`.
+ * - `archive-after-months` — archive objects older than `months` by relocating
+ *   them under the reserved {@link ARCHIVE_KEY_PREFIX}.
+ * - `expire-temp-uploads` — delete transient multipart-part / resumable-session
+ *   state older than `afterMs` (the reserved temp-upload key spaces).
+ * - `move-to-cold` — relocate objects older than `afterDays` under `coldPrefix`.
+ *
+ * **Exactly-once (Requirement 13.2).** Each action removes the qualifying object
+ * from the space that a subsequent evaluation scans: `delete`/`expire` remove
+ * the object outright, and `archive`/`move-to-cold` relocate it to a prefix that
+ * the scan excludes (the reserved archive prefix, or `coldPrefix`). Because the
+ * relocated copy is written with a fresh `createdAt` at the evaluation instant,
+ * it is also too young to re-qualify at the same `now`. The net effect is that a
+ * second evaluation produces no further action on an already-actioned object.
+ *
+ * The module depends only on the driver contract, the shared type surface, the
+ * metadata layer, and the core `Clock`, keeping the dependency direction
+ * acyclic. Event publication for applied actions (Requirement 13.4) is wired
+ * separately by the Events bridge (task 21.1); this engine only performs the
+ * actions and returns their {@link LifecycleOutcome} descriptors.
+ *
+ * _Requirements: 13.1, 13.2, 13.3_
+ */
+import { type Clock } from "streetjs";
+import type { StorageDriver } from "./driver.js";
+import type { LifecycleOutcome, LifecycleRule } from "./types.js";
+/**
+ * Reserved key prefix under which objects archived by an `archive-after-months`
+ * rule are relocated. An archived `<key>` lives at `${ARCHIVE_KEY_PREFIX}<key>`.
+ * The prefix is excluded from every lifecycle scan so an archived object is
+ * never re-actioned (Requirement 13.2).
+ */
+export declare const ARCHIVE_KEY_PREFIX = ".archive/";
+/** Options for constructing a {@link LifecycleEngine}. */
+export interface LifecycleEngineOptions {
+    /** The driver every action is delegated to or simulated over. */
+    readonly driver: StorageDriver;
+    /**
+     * Injected clock used to compute object age at evaluation time. Default
+     * `systemClock`, so time is deterministic in tests (Requirement 13.3).
+     */
+    readonly clock?: Clock;
+}
+/**
+ * Provider-agnostic lifecycle engine 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 `lifecycle` capability) is stable across every call.
+ */
+export declare class LifecycleEngine {
+    /** The driver every action is delegated to or simulated over. */
+    private readonly driver;
+    /** Injected clock used to compute object age at evaluation time. */
+    private readonly clock;
+    constructor(options: LifecycleEngineOptions);
+    /** The driver's native lifecycle capability, when present. */
+    private get native();
+    /**
+     * Evaluate `rule` against the current object set and apply its action to every
+     * qualifying object, returning one {@link LifecycleOutcome} per actioned
+     * object (Requirements 13.1, 13.2). Object age is measured relative to `now`,
+     * which defaults to the injected clock. When the driver exposes a native
+     * `lifecycle` capability the evaluation is delegated to it; otherwise the rule
+     * is simulated over the driver primitives.
+     */
+    apply(rule: LifecycleRule, now?: number): Promise<LifecycleOutcome[]>;
+    /**
+     * Delete every managed object under `prefix` whose age is at least
+     * `thresholdMs`. The deletion removes the object from the scanned space, so a
+     * repeated evaluation finds nothing further to delete (Requirement 13.2).
+     */
+    private applyDelete;
+    /**
+     * Archive every managed object under `prefix` whose age is at least
+     * `thresholdMs` by relocating it under {@link ARCHIVE_KEY_PREFIX}. The archive
+     * prefix is excluded from the scan, so an archived object is never re-archived
+     * (Requirement 13.2).
+     */
+    private applyArchive;
+    /**
+     * Expire (delete) transient upload state older than `afterMs` across the
+     * reserved temp-upload key spaces (multipart parts and resumable session
+     * bytes). Because expiration deletes the state, a repeated evaluation finds
+     * nothing further to expire (Requirement 13.2).
+     */
+    private applyExpire;
+    /**
+     * Relocate every managed object under `prefix` whose age is at least
+     * `thresholdMs` to `${coldPrefix}<key>`. Keys already residing under
+     * `coldPrefix` are excluded from the scan, so a repeated evaluation does not
+     * move an already-tiered object again (Requirement 13.2).
+     */
+    private applyMoveToCold;
+    /**
+     * List candidate keys under `prefix`, keep those accepted by `accept`, and
+     * return the subset whose age (`now - createdAt`, read via `stat`) is at least
+     * `thresholdMs`. Keys that vanish between `list` and `stat` are skipped.
+     */
+    private collectQualifying;
+    /**
+     * Move the object at `sourceKey` to `destinationKey` over the driver
+     * primitives: the content and preserved write-time metadata are written to the
+     * destination and the source is then removed. Returns `false` without writing
+     * when the source has vanished.
+     */
+    private relocate;
+    /**
+     * Report whether `key` is an application-visible object (as opposed to
+     * internal bookkeeping such as version snapshots, multipart parts, resumable
+     * session bytes, or already-archived copies). Age-based rules act only on
+     * managed keys.
+     */
+    private isManagedKey;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,UAAU,CAAC;AAEnD,OAAO,KAAK,EAAuB,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAalE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAwB9C,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;gBAElB,OAAO,EAAE,sBAAsB;IAK3C,8DAA8D;IAC9D,OAAO,KAAK,MAAM,GAEjB;IAED;;;;;;;OAOG;IACG,KAAK,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,GAAE,MAAqB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAsBzF;;;;OAIG;YACW,WAAW;IAgBzB;;;;;OAKG;YACW,YAAY;IAkB1B;;;;;OAKG;YACW,WAAW;IAczB;;;;;OAKG;YACW,eAAe;IAsB7B;;;;OAIG;YACW,iBAAiB;IAuB/B;;;;;OAKG;YACW,QAAQ;IAUtB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;CAGrB"}