@streetjs/storage 1.0.0

package/dist/lifecycle.js

@@ -0,0 +1,240 @@
+/**
+ * @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 { systemClock } from "streetjs";
+import { toWriteMetadata } from "./metadata.js";
+/** Milliseconds in a single day, used to convert day-based thresholds. */
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * The number of days used to approximate one month when converting a
+ * month-based threshold to milliseconds. Lifecycle thresholds are coarse
+ * age policies rather than calendar arithmetic, so a fixed 30-day month keeps
+ * the simulation deterministic and provider-agnostic.
+ */
+const DAYS_PER_MONTH = 30;
+/**
+ * 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 const ARCHIVE_KEY_PREFIX = ".archive/";
+/**
+ * Reserved key prefixes that hold transient upload state (multipart parts and
+ * resumable session bytes), mirroring the `.multipart/<uploadId>/…` and
+ * `.resumable/<sessionId>` layouts used by the session managers. These are the
+ * key spaces an `expire-temp-uploads` rule scans and expires.
+ */
+const TEMP_UPLOAD_PREFIXES = [".multipart/", ".resumable/"];
+/**
+ * Reserved key prefixes that are internal bookkeeping rather than
+ * application-visible objects. Age-based rules (`delete-after-days`,
+ * `archive-after-months`, `move-to-cold`) never touch keys under these prefixes
+ * so lifecycle policies act only on real objects, not on version snapshots,
+ * multipart parts, resumable session bytes, or already-archived copies.
+ */
+const RESERVED_KEY_PREFIXES = [
+    ".versions/",
+    ".multipart/",
+    ".resumable/",
+    ARCHIVE_KEY_PREFIX,
+];
+/**
+ * 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 class LifecycleEngine {
+    /** The driver every action is delegated to or simulated over. */
+    driver;
+    /** Injected clock used to compute object age at evaluation time. */
+    clock;
+    constructor(options) {
+        this.driver = options.driver;
+        this.clock = options.clock ?? systemClock;
+    }
+    /** The driver's native lifecycle capability, when present. */
+    get native() {
+        return this.driver.lifecycle;
+    }
+    /**
+     * 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.
+     */
+    async apply(rule, now = this.clock()) {
+        if (this.native !== undefined) {
+            return this.native.apply(rule, now);
+        }
+        switch (rule.type) {
+            case "delete-after-days":
+                return this.applyDelete(rule.prefix ?? "", rule.days * MS_PER_DAY, now);
+            case "archive-after-months":
+                return this.applyArchive(rule.prefix ?? "", rule.months * DAYS_PER_MONTH * MS_PER_DAY, now);
+            case "expire-temp-uploads":
+                return this.applyExpire(rule.afterMs, now);
+            case "move-to-cold":
+                return this.applyMoveToCold(rule.prefix ?? "", rule.coldPrefix, rule.afterDays * MS_PER_DAY, now);
+        }
+    }
+    /**
+     * 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).
+     */
+    async applyDelete(prefix, thresholdMs, now) {
+        const keys = await this.collectQualifying(prefix, thresholdMs, now, (key) => this.isManagedKey(key));
+        const outcomes = [];
+        for (const key of keys) {
+            await this.driver.delete(key);
+            outcomes.push({ key, action: "deleted" });
+        }
+        return outcomes;
+    }
+    /**
+     * 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).
+     */
+    async applyArchive(prefix, thresholdMs, now) {
+        const keys = await this.collectQualifying(prefix, thresholdMs, now, (key) => this.isManagedKey(key));
+        const outcomes = [];
+        for (const key of keys) {
+            const moved = await this.relocate(key, `${ARCHIVE_KEY_PREFIX}${key}`);
+            if (moved) {
+                outcomes.push({ key, action: "archived" });
+            }
+        }
+        return outcomes;
+    }
+    /**
+     * 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).
+     */
+    async applyExpire(afterMs, now) {
+        const outcomes = [];
+        for (const prefix of TEMP_UPLOAD_PREFIXES) {
+            // Every key under a temp-upload prefix is transient state, so no further
+            // managed-key filtering is applied here.
+            const keys = await this.collectQualifying(prefix, afterMs, now, () => true);
+            for (const key of keys) {
+                await this.driver.delete(key);
+                outcomes.push({ key, action: "expired" });
+            }
+        }
+        return outcomes;
+    }
+    /**
+     * 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).
+     */
+    async applyMoveToCold(prefix, coldPrefix, thresholdMs, now) {
+        const keys = await this.collectQualifying(prefix, thresholdMs, now, (key) => this.isManagedKey(key) && !key.startsWith(coldPrefix));
+        const outcomes = [];
+        for (const key of keys) {
+            const moved = await this.relocate(key, `${coldPrefix}${key}`);
+            if (moved) {
+                outcomes.push({ key, action: "moved" });
+            }
+        }
+        return outcomes;
+    }
+    /**
+     * 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.
+     */
+    async collectQualifying(prefix, thresholdMs, now, accept) {
+        const items = await this.driver.list(prefix);
+        const qualifying = [];
+        for (const item of items) {
+            if (!accept(item.key)) {
+                continue;
+            }
+            const metadata = await this.driver.stat(item.key);
+            if (metadata === null) {
+                continue;
+            }
+            if (now - metadata.createdAt >= thresholdMs) {
+                qualifying.push(item.key);
+            }
+        }
+        return qualifying;
+    }
+    /**
+     * 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.
+     */
+    async relocate(sourceKey, destinationKey) {
+        const result = await this.driver.get(sourceKey);
+        if (!result.found) {
+            return false;
+        }
+        await this.driver.put(destinationKey, result.bytes, toWriteMetadata(result.metadata));
+        await this.driver.delete(sourceKey);
+        return true;
+    }
+    /**
+     * 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.
+     */
+    isManagedKey(key) {
+        return !RESERVED_KEY_PREFIXES.some((reserved) => key.startsWith(reserved));
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

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

package/dist/metadata.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @streetjs/storage — the typed metadata layer (single source of truth).
+ *
+ * Every stored object carries a typed {@link StorageObjectMetadata} field set:
+ * `key`, `size`, `contentType`, `etag`, `checksum`, `owner`, `tenant`,
+ * `accessLevel`, `createdAt`, `updatedAt`, `custom` (and an optional
+ * `versionId`). Requirement 10 states this field set must be **complete**,
+ * **consistent across providers**, and must **round-trip** through write and
+ * read unchanged. Historically each driver assembled that object literal on its
+ * own and duplicated the field defaults (`contentType` →
+ * `application/octet-stream`, `accessLevel` → `private`, `custom` → `{}`), which
+ * risked the shape drifting between drivers over time.
+ *
+ * This module centralizes that shape in one place so it is preserved
+ * identically no matter which {@link StorageDriver} backs the facade:
+ *
+ * - {@link buildObjectMetadata} is the single constructor for the metadata
+ *   field set. Drivers compute the provider-specific identity fields
+ *   (`etag`/`checksum`/`size`) and timestamps (`createdAt`/`updatedAt`) and hand
+ *   them here together with the caller's {@link WriteMetadata}; this function
+ *   applies the canonical defaults and produces the complete, typed object. It
+ *   never recomputes the identity fields, so driver-computed values are the
+ *   source of truth for content hashing (Requirement 10.1, 10.2).
+ * - {@link normalizeMetadata} guarantees the full field set is present on any
+ *   metadata surfaced by the facade (`put`/`stat`/`get`), filling the canonical
+ *   defaults for any field a driver (e.g. a future cloud driver) left
+ *   unpopulated while leaving identity/timestamp fields untouched. It is
+ *   idempotent for metadata already produced by {@link buildObjectMetadata}
+ *   (Requirement 10.1, 10.3).
+ * - {@link toWriteMetadata} projects a stored object's metadata back onto the
+ *   write-time subset, used when copying/moving so the destination preserves the
+ *   source's content type, ownership, tenancy, access level, and custom fields.
+ *
+ * The module depends only on the shared type surface (`types.ts`), keeping the
+ * dependency direction acyclic (leaf module → types).
+ *
+ * _Requirements: 10.1, 10.2, 10.3_
+ */
+import type { AccessLevel, StorageObjectMetadata, WriteMetadata } from "./types.js";
+/** Default content type applied when a write does not specify one. */
+export declare const DEFAULT_CONTENT_TYPE: "application/octet-stream";
+/** Default access level applied when a write does not specify one. */
+export declare const DEFAULT_ACCESS_LEVEL: AccessLevel;
+/**
+ * The canonical, ordered set of typed metadata field names every object carries
+ * (Requirement 10.1). `versionId` is intentionally excluded — it is an optional
+ * field present only on versioned objects, not part of the guaranteed base set.
+ */
+export declare const STORAGE_METADATA_FIELDS: readonly ["key", "size", "contentType", "etag", "checksum", "owner", "tenant", "accessLevel", "createdAt", "updatedAt", "custom"];
+/**
+ * The inputs a driver supplies to build an object's metadata. The driver is
+ * responsible for the provider-specific identity fields and timestamps; this
+ * layer owns the field-set shape and the caller-facing defaults.
+ */
+export interface BuildMetadataInput {
+    /** The object key. */
+    readonly key: string;
+    /** Byte length of the stored content, computed by the driver. */
+    readonly size: number;
+    /** Content hash (e.g. sha-256 hex), computed by the driver. */
+    readonly checksum: string;
+    /** Entity tag; defaults to {@link checksum} when the driver omits it. */
+    readonly etag?: string;
+    /** Creation timestamp (epoch ms) from the injected clock. */
+    readonly createdAt: number;
+    /** Last-updated timestamp (epoch ms) from the injected clock. */
+    readonly updatedAt: number;
+    /** The caller-supplied write-time metadata. */
+    readonly write: WriteMetadata;
+    /** Optional version identifier for versioned objects. */
+    readonly versionId?: string;
+}
+/**
+ * Build the complete, typed {@link StorageObjectMetadata} field set from the
+ * driver-computed identity/timestamp values and the caller's
+ * {@link WriteMetadata}. This is the single place the metadata shape and its
+ * defaults are defined, so every driver produces an identical field set
+ * (Requirement 10.1, 10.2, 10.3).
+ *
+ * The identity fields (`etag`/`checksum`/`size`) and timestamps are used exactly
+ * as provided — this function never recomputes them — so the driver's computed
+ * values remain the source of truth and cannot diverge from what was persisted.
+ */
+export declare function buildObjectMetadata(input: BuildMetadataInput): StorageObjectMetadata;
+/**
+ * Return a copy of `metadata` with the complete typed field set guaranteed
+ * present, applying the canonical defaults for any missing `contentType`,
+ * `accessLevel`, or `custom` field while preserving the driver-computed
+ * identity fields (`etag`/`checksum`/`size`) and timestamps untouched
+ * (Requirement 10.1, 10.3).
+ *
+ * The facade runs the metadata it surfaces on `put`/`stat`/`get` through this
+ * function so the full field set is consistently present regardless of which
+ * driver produced it. It is idempotent for metadata already built by
+ * {@link buildObjectMetadata}, so wiring it in adds no behavioral change for the
+ * zero-dependency drivers while shielding the public surface from a future
+ * driver that returns a partially populated record.
+ */
+export declare function normalizeMetadata(metadata: StorageObjectMetadata): StorageObjectMetadata;
+/**
+ * Project a stored object's {@link StorageObjectMetadata} onto the write-time
+ * {@link WriteMetadata} subset. Used when copying/moving an object so the
+ * destination preserves the source's content type, ownership, tenancy, access
+ * level, and custom fields. The identity/timestamp fields (`etag`/`checksum`/
+ * `size`/`createdAt`/`updatedAt`) are intentionally omitted — the driver
+ * recomputes them for the destination object.
+ */
+export declare function toWriteMetadata(metadata: StorageObjectMetadata): WriteMetadata;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIpF,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,EAAG,0BAAmC,CAAC;AAExE,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,EAAE,WAAuB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,mIAY1B,CAAC;AAIX;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,sBAAsB;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,qBAAqB,CAiBpF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,qBAAqB,CAgBxF;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,qBAAqB,GAAG,aAAa,CAQ9E"}

package/dist/metadata.js

@@ -0,0 +1,139 @@
+/**
+ * @streetjs/storage — the typed metadata layer (single source of truth).
+ *
+ * Every stored object carries a typed {@link StorageObjectMetadata} field set:
+ * `key`, `size`, `contentType`, `etag`, `checksum`, `owner`, `tenant`,
+ * `accessLevel`, `createdAt`, `updatedAt`, `custom` (and an optional
+ * `versionId`). Requirement 10 states this field set must be **complete**,
+ * **consistent across providers**, and must **round-trip** through write and
+ * read unchanged. Historically each driver assembled that object literal on its
+ * own and duplicated the field defaults (`contentType` →
+ * `application/octet-stream`, `accessLevel` → `private`, `custom` → `{}`), which
+ * risked the shape drifting between drivers over time.
+ *
+ * This module centralizes that shape in one place so it is preserved
+ * identically no matter which {@link StorageDriver} backs the facade:
+ *
+ * - {@link buildObjectMetadata} is the single constructor for the metadata
+ *   field set. Drivers compute the provider-specific identity fields
+ *   (`etag`/`checksum`/`size`) and timestamps (`createdAt`/`updatedAt`) and hand
+ *   them here together with the caller's {@link WriteMetadata}; this function
+ *   applies the canonical defaults and produces the complete, typed object. It
+ *   never recomputes the identity fields, so driver-computed values are the
+ *   source of truth for content hashing (Requirement 10.1, 10.2).
+ * - {@link normalizeMetadata} guarantees the full field set is present on any
+ *   metadata surfaced by the facade (`put`/`stat`/`get`), filling the canonical
+ *   defaults for any field a driver (e.g. a future cloud driver) left
+ *   unpopulated while leaving identity/timestamp fields untouched. It is
+ *   idempotent for metadata already produced by {@link buildObjectMetadata}
+ *   (Requirement 10.1, 10.3).
+ * - {@link toWriteMetadata} projects a stored object's metadata back onto the
+ *   write-time subset, used when copying/moving so the destination preserves the
+ *   source's content type, ownership, tenancy, access level, and custom fields.
+ *
+ * The module depends only on the shared type surface (`types.ts`), keeping the
+ * dependency direction acyclic (leaf module → types).
+ *
+ * _Requirements: 10.1, 10.2, 10.3_
+ */
+// ── Canonical field-set defaults ──────────────────────────────────────────────
+/** Default content type applied when a write does not specify one. */
+export const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/** Default access level applied when a write does not specify one. */
+export const DEFAULT_ACCESS_LEVEL = "private";
+/**
+ * The canonical, ordered set of typed metadata field names every object carries
+ * (Requirement 10.1). `versionId` is intentionally excluded — it is an optional
+ * field present only on versioned objects, not part of the guaranteed base set.
+ */
+export const STORAGE_METADATA_FIELDS = [
+    "key",
+    "size",
+    "contentType",
+    "etag",
+    "checksum",
+    "owner",
+    "tenant",
+    "accessLevel",
+    "createdAt",
+    "updatedAt",
+    "custom",
+];
+/**
+ * Build the complete, typed {@link StorageObjectMetadata} field set from the
+ * driver-computed identity/timestamp values and the caller's
+ * {@link WriteMetadata}. This is the single place the metadata shape and its
+ * defaults are defined, so every driver produces an identical field set
+ * (Requirement 10.1, 10.2, 10.3).
+ *
+ * The identity fields (`etag`/`checksum`/`size`) and timestamps are used exactly
+ * as provided — this function never recomputes them — so the driver's computed
+ * values remain the source of truth and cannot diverge from what was persisted.
+ */
+export function buildObjectMetadata(input) {
+    const { key, size, checksum, createdAt, updatedAt, write, versionId } = input;
+    const metadata = {
+        key,
+        size,
+        contentType: write.contentType ?? DEFAULT_CONTENT_TYPE,
+        etag: input.etag ?? checksum,
+        checksum,
+        owner: write.owner,
+        tenant: write.tenant,
+        accessLevel: write.accessLevel ?? DEFAULT_ACCESS_LEVEL,
+        createdAt,
+        updatedAt,
+        custom: write.custom ?? {},
+        ...(versionId !== undefined ? { versionId } : {}),
+    };
+    return metadata;
+}
+/**
+ * Return a copy of `metadata` with the complete typed field set guaranteed
+ * present, applying the canonical defaults for any missing `contentType`,
+ * `accessLevel`, or `custom` field while preserving the driver-computed
+ * identity fields (`etag`/`checksum`/`size`) and timestamps untouched
+ * (Requirement 10.1, 10.3).
+ *
+ * The facade runs the metadata it surfaces on `put`/`stat`/`get` through this
+ * function so the full field set is consistently present regardless of which
+ * driver produced it. It is idempotent for metadata already built by
+ * {@link buildObjectMetadata}, so wiring it in adds no behavioral change for the
+ * zero-dependency drivers while shielding the public surface from a future
+ * driver that returns a partially populated record.
+ */
+export function normalizeMetadata(metadata) {
+    const normalized = {
+        key: metadata.key,
+        size: metadata.size,
+        contentType: metadata.contentType ?? DEFAULT_CONTENT_TYPE,
+        etag: metadata.etag,
+        checksum: metadata.checksum,
+        owner: metadata.owner,
+        tenant: metadata.tenant,
+        accessLevel: metadata.accessLevel ?? DEFAULT_ACCESS_LEVEL,
+        createdAt: metadata.createdAt,
+        updatedAt: metadata.updatedAt,
+        custom: metadata.custom ?? {},
+        ...(metadata.versionId !== undefined ? { versionId: metadata.versionId } : {}),
+    };
+    return normalized;
+}
+/**
+ * Project a stored object's {@link StorageObjectMetadata} onto the write-time
+ * {@link WriteMetadata} subset. Used when copying/moving an object so the
+ * destination preserves the source's content type, ownership, tenancy, access
+ * level, and custom fields. The identity/timestamp fields (`etag`/`checksum`/
+ * `size`/`createdAt`/`updatedAt`) are intentionally omitted — the driver
+ * recomputes them for the destination object.
+ */
+export function toWriteMetadata(metadata) {
+    return {
+        contentType: metadata.contentType,
+        owner: metadata.owner,
+        tenant: metadata.tenant,
+        accessLevel: metadata.accessLevel,
+        custom: metadata.custom,
+    };
+}
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,iFAAiF;AAEjF,sEAAsE;AACtE,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAAmC,CAAC;AAExE,sEAAsE;AACtE,MAAM,CAAC,MAAM,oBAAoB,GAAgB,SAAS,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,KAAK;IACL,MAAM;IACN,aAAa;IACb,MAAM;IACN,UAAU;IACV,OAAO;IACP,QAAQ;IACR,aAAa;IACb,WAAW;IACX,WAAW;IACX,QAAQ;CACA,CAAC;AA4BX;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAyB;IAC3D,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IAC9E,MAAM,QAAQ,GAA0B;QACtC,GAAG;QACH,IAAI;QACJ,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,oBAAoB;QACtD,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,QAAQ;QAC5B,QAAQ;QACR,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,oBAAoB;QACtD,SAAS;QACT,SAAS;QACT,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;QAC1B,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClD,CAAC;IACF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAA+B;IAC/D,MAAM,UAAU,GAA0B;QACxC,GAAG,EAAE,QAAQ,CAAC,GAAG;QACjB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,WAAW,EAAE,QAAQ,CAAC,WAAW,IAAI,oBAAoB;QACzD,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,WAAW,EAAE,QAAQ,CAAC,WAAW,IAAI,oBAAoB;QACzD,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,MAAM,EAAE,QAAQ,CAAC,MAAM,IAAI,EAAE;QAC7B,GAAG,CAAC,QAAQ,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/E,CAAC;IACF,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,QAA+B;IAC7D,OAAO;QACL,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;KACxB,CAAC;AACJ,CAAC"}

package/dist/multipart.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @streetjs/storage — the multipart upload manager.
+ *
+ * A {@link Multipart_Upload} splits a large object into independently uploaded
+ * parts that are later assembled into a single object whose content equals the
+ * concatenation of those parts in order (Requirement 6). {@link MultipartManager}
+ * provides this capability in a **provider-agnostic** way:
+ *
+ * - When the backing {@link StorageDriver} implements the optional native
+ *   `multipart` capability, the manager delegates each operation to the driver
+ *   so a provider that has first-class multipart support (e.g. S3) is used
+ *   directly.
+ * - Otherwise the manager **simulates** multipart over the mandatory driver
+ *   primitives (`put`/`get`/`putStream`/`delete`). Each `uploadPart` persists
+ *   the part bytes under a reserved key derived from `(uploadId, partNumber)`
+ *   (mirroring the design's `.multipart/<uploadId>/<partNumber>` layout), and
+ *   `complete` streams the persisted parts back in the supplied order into the
+ *   final object. Because completion assembles the object by reading one part at
+ *   a time into a `Readable` and piping it through `driver.putStream`, the whole
+ *   object is never required to be materialized in a single buffer by this
+ *   layer — the design streams the concatenation and therefore imposes **no
+ *   artificial size cap** (objects of a gigabyte or more are supported,
+ *   Requirement 6.5).
+ *
+ * Semantics (Requirement 6):
+ * - {@link MultipartManager.create} mints and returns an upload identifier.
+ * - {@link MultipartManager.uploadPart} persists a part keyed by
+ *   `(uploadId, partNumber)` and returns a {@link StoredPart} descriptor.
+ * - {@link MultipartManager.complete} concatenates the parts in the supplied
+ *   order into the final object — equivalent to a single `put` of the
+ *   concatenation — and returns the resulting metadata.
+ * - {@link MultipartManager.abort} discards every persisted part and creates no
+ *   object.
+ *
+ * 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: 6.1, 6.2, 6.3, 6.4, 6.5_
+ */
+import type { StorageDriver, StoredPart } from "./driver.js";
+import type { StorageObjectMetadata, WriteMetadata } from "./types.js";
+/**
+ * Provider-agnostic multipart 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 `multipart` capability) is stable across every call for a
+ * given upload identifier.
+ */
+export declare class MultipartManager {
+    /** The driver every operation is delegated to or simulated over. */
+    private readonly driver;
+    /**
+     * In-progress simulated sessions keyed by upload id. Empty when the driver
+     * provides a native `multipart` capability (that path keeps no local state).
+     */
+    private readonly sessions;
+    constructor(driver: StorageDriver);
+    /** The driver's native multipart capability, when present. */
+    private get native();
+    /**
+     * Begin a multipart upload for `key` and return its upload identifier
+     * (Requirement 6.1). When the driver has a native capability the driver mints
+     * the id; otherwise a fresh id is generated and a local session records the
+     * target key and its write-time metadata for assembly at completion.
+     */
+    create(key: string, metadata: WriteMetadata): Promise<string>;
+    /**
+     * Persist a single part for `uploadId` and return its {@link StoredPart}
+     * descriptor (Requirement 6.2). The part bytes are copied defensively before
+     * persistence so later mutation of the caller's buffer cannot corrupt a stored
+     * part. The returned `etag` is the sha-256 hex digest of the part bytes,
+     * matching the checksum scheme the drivers use elsewhere.
+     */
+    uploadPart(uploadId: string, partNumber: number, bytes: Uint8Array): Promise<StoredPart>;
+    /**
+     * Assemble the supplied `parts` in order into the final object and return its
+     * metadata (Requirement 6.3). The assembled content equals the concatenation
+     * of the parts in the given order — equivalent to a single `put` of that
+     * concatenation.
+     *
+     * For the simulated path the parts are streamed back one at a time from the
+     * driver into a `Readable` piped through `driver.putStream`, so this layer
+     * never buffers the full object at once (Requirement 6.5). Every persisted
+     * part (whether or not it appears in `parts`) is discarded afterward and the
+     * session is closed.
+     */
+    complete(uploadId: string, parts: readonly StoredPart[]): Promise<StorageObjectMetadata>;
+    /**
+     * Discard every persisted part for `uploadId` and create no completed object
+     * (Requirement 6.4). Delegates to the native capability when present; for the
+     * simulated path it deletes all recorded part keys and closes the session. An
+     * unknown/already-finalized upload id is treated as an idempotent no-op.
+     */
+    abort(uploadId: string): Promise<void>;
+    /** Delete every persisted part for a simulated upload id. */
+    private discardParts;
+    /** The reserved driver key a simulated part is persisted under. */
+    private partKey;
+    /**
+     * Resolve the simulated session for `uploadId`, throwing a descriptive
+     * {@link StorageError} when the id is unknown or the upload has already been
+     * finalized.
+     */
+    private requireSession;
+}
+//# sourceMappingURL=multipart.d.ts.map

package/dist/multipart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../src/multipart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAMH,OAAO,KAAK,EAAuB,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGlF,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA6BvE;;;;;;;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;;;;;OAKG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IASnE;;;;;;OAMG;IACG,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,UAAU,CAAC;IActB;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAmC9F;;;;;OAKG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5C,6DAA6D;YAC/C,YAAY;IAM1B,mEAAmE;IACnE,OAAO,CAAC,OAAO;IAIf;;;;OAIG;IACH,OAAO,CAAC,cAAc;CASvB"}