@streetjs/storage 1.0.0

package/dist/errors.js

@@ -0,0 +1,131 @@
+/**
+ * @streetjs/storage — typed error hierarchy
+ *
+ * Every error thrown by the storage framework derives from {@link StorageError},
+ * so consumers can catch the whole family with a single `instanceof StorageError`
+ * check while still discriminating on concrete subclasses for specific handling.
+ *
+ * Each subclass carries descriptive, strongly typed fields appropriate to its
+ * purpose (the offending key, the validation message, the access context, the
+ * unsupported image source, etc.) and sets `this.name`. Because TypeScript emits
+ * to ES2022 with `Error` subclassing, we call `Object.setPrototypeOf` in every
+ * constructor to keep the prototype chain intact for `instanceof` under ESM/TS.
+ *
+ * _Requirements: 1.5, 5.5, 9.4, 11.3, 14.4_
+ */
+/**
+ * Base class for every error raised by `@streetjs/storage`.
+ *
+ * Catch this to handle any storage failure; narrow to a subclass for specific
+ * cases. Carries an optional `cause` (the underlying error, when this error
+ * wraps another) following the standard `Error` `cause` convention.
+ */
+export class StorageError extends Error {
+    /** The underlying error this error wraps, when applicable. */
+    cause;
+    constructor(message, options) {
+        super(message);
+        this.name = "StorageError";
+        if (options && "cause" in options) {
+            this.cause = options.cause;
+        }
+        Object.setPrototypeOf(this, StorageError.prototype);
+    }
+}
+/**
+ * Raised when `createStorage` (or another configuration step) receives an
+ * invalid or unusable configuration — for example an unknown provider name.
+ *
+ * Carries the optional `provider` that triggered the failure so callers can
+ * surface a precise, descriptive configuration error (Requirement 1.5).
+ */
+export class StorageConfigError extends StorageError {
+    /** The provider name (or other config value) that was rejected, if known. */
+    provider;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "StorageConfigError";
+        this.provider = options?.provider;
+        Object.setPrototypeOf(this, StorageConfigError.prototype);
+    }
+}
+/**
+ * Raised when an operation targets an object key that does not exist — for
+ * example `getStream` on a missing key (Requirement 5.5).
+ *
+ * Carries the offending `key` so callers know exactly which object was absent.
+ */
+export class NotFoundError extends StorageError {
+    /** The object key that was not found. */
+    key;
+    constructor(key, message, options) {
+        super(message ?? `Object not found for key "${key}"`, options);
+        this.name = "NotFoundError";
+        this.key = key;
+        Object.setPrototypeOf(this, NotFoundError.prototype);
+    }
+}
+/**
+ * Raised when the validation pipeline rejects an upload before any content is
+ * persisted, leaving no partial object stored (Requirement 9.4).
+ *
+ * Carries the human-readable `validationError` text describing why the upload
+ * was rejected, plus the optional `key` the upload targeted.
+ */
+export class ValidationError extends StorageError {
+    /** The descriptive text explaining why validation failed. */
+    validationError;
+    /** The object key the rejected upload targeted, when known. */
+    key;
+    constructor(validationError, options) {
+        super(options?.message ?? `Upload validation failed: ${validationError}`, options);
+        this.name = "ValidationError";
+        this.validationError = validationError;
+        this.key = options?.key;
+        Object.setPrototypeOf(this, ValidationError.prototype);
+    }
+}
+/**
+ * Raised when a caller lacks the access required by an object's access level,
+ * denying the operation (Requirement 11.3).
+ *
+ * Carries the access context — the `key`, the attempted `operation`, and the
+ * object's `accessLevel` — so the denial can be logged and explained precisely.
+ */
+export class AuthorizationError extends StorageError {
+    /** The object key the denied operation targeted, when known. */
+    key;
+    /** The operation that was denied (e.g. "read", "write", "delete"). */
+    operation;
+    /** The access level that governed the denied object, when known. */
+    accessLevel;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "AuthorizationError";
+        this.key = options?.key;
+        this.operation = options?.operation;
+        this.accessLevel = options?.accessLevel;
+        Object.setPrototypeOf(this, AuthorizationError.prototype);
+    }
+}
+/**
+ * Raised when the image processor is asked to transform a source that is not a
+ * supported image format; the source object is left unmodified (Requirement 14.4).
+ *
+ * Carries the offending source `format` and/or `key` so the error precisely
+ * identifies what could not be processed.
+ */
+export class UnsupportedImageError extends StorageError {
+    /** The detected/declared source format that is not supported, when known. */
+    format;
+    /** The source object key that could not be processed, when known. */
+    key;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "UnsupportedImageError";
+        this.format = options?.format;
+        this.key = options?.key;
+        Object.setPrototypeOf(this, UnsupportedImageError.prototype);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/examples/storage-demo.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @streetjs/storage — runnable end-to-end example (task 31.1).
+ *
+ * This is the example application required by Requirement 25. It demonstrates
+ * the storage framework working end to end **entirely in-process**: it uses a
+ * Zero_Dependency_Driver (the in-memory provider) with no external services,
+ * no network calls, and no real image library (Requirements 25.1, 25.2, 25.3).
+ *
+ * The demo walks through the full "avatar" lifecycle a typical application
+ * exercises:
+ *
+ * 1. Upload an avatar (`put`).
+ * 2. Download it back and confirm the bytes round-trip (`get`).
+ * 3. Replace the avatar with new content (`put` over the same key).
+ * 4. List stored objects (`list`).
+ * 5. Delete an object (`delete`).
+ * 6. Generate a signed URL (`signedUrl`, backed by `config.signingSecret`).
+ * 7. Show upload progress — both via a Realtime bridge that logs
+ *    `upload.*` events and via a per-chunk progress callback feeding
+ *    `putStream`.
+ * 8. Resize an image (`images.transform` with `resize`).
+ * 9. Generate a thumbnail (`images.transform` with `thumbnail`).
+ * 10. Inspect metadata (`stat`).
+ *
+ * Image work is delegated to a tiny in-process **fake** {@link ImageCodec}
+ * (`config.imageCodec`) so resize/thumbnail run without a real image library.
+ * The codec simply records the requested transform in the produced bytes; it is
+ * illustrative, not a real encoder.
+ *
+ * The module exports {@link runStorageDemo} so the smoke test (task 31.2) can
+ * import and run it, and it is directly runnable via `npm run example`
+ * (`node dist/examples/storage-demo.js`).
+ *
+ * _Requirements: 25.1, 25.2, 25.3_
+ */
+/**
+ * Run the storage demo end to end against the zero-dependency in-memory
+ * provider. Accepts an optional `log` sink (defaults to `console.log`) so the
+ * smoke test can capture output. Returns a small summary of the demonstrated
+ * operations so callers can assert on the outcome (Requirement 25.3).
+ */
+export declare function runStorageDemo(log?: (line: string) => void): Promise<{
+    readonly downloaded: string;
+    readonly replaced: string;
+    readonly listedKeys: readonly string[];
+    readonly deletedKey: string;
+    readonly signedUrl: string;
+    readonly progressUpdates: number;
+    readonly resizedKey: string;
+    readonly thumbnailKey: string;
+    readonly avatarSize: number;
+}>;
+//# sourceMappingURL=storage-demo.d.ts.map

package/dist/examples/storage-demo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-demo.d.ts","sourceRoot":"","sources":["../../src/examples/storage-demo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAoFH;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkC,GACxD,OAAO,CAAC;IACT,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC,CAgJD"}

package/dist/examples/storage-demo.js

@@ -0,0 +1,242 @@
+/**
+ * @streetjs/storage — runnable end-to-end example (task 31.1).
+ *
+ * This is the example application required by Requirement 25. It demonstrates
+ * the storage framework working end to end **entirely in-process**: it uses a
+ * Zero_Dependency_Driver (the in-memory provider) with no external services,
+ * no network calls, and no real image library (Requirements 25.1, 25.2, 25.3).
+ *
+ * The demo walks through the full "avatar" lifecycle a typical application
+ * exercises:
+ *
+ * 1. Upload an avatar (`put`).
+ * 2. Download it back and confirm the bytes round-trip (`get`).
+ * 3. Replace the avatar with new content (`put` over the same key).
+ * 4. List stored objects (`list`).
+ * 5. Delete an object (`delete`).
+ * 6. Generate a signed URL (`signedUrl`, backed by `config.signingSecret`).
+ * 7. Show upload progress — both via a Realtime bridge that logs
+ *    `upload.*` events and via a per-chunk progress callback feeding
+ *    `putStream`.
+ * 8. Resize an image (`images.transform` with `resize`).
+ * 9. Generate a thumbnail (`images.transform` with `thumbnail`).
+ * 10. Inspect metadata (`stat`).
+ *
+ * Image work is delegated to a tiny in-process **fake** {@link ImageCodec}
+ * (`config.imageCodec`) so resize/thumbnail run without a real image library.
+ * The codec simply records the requested transform in the produced bytes; it is
+ * illustrative, not a real encoder.
+ *
+ * The module exports {@link runStorageDemo} so the smoke test (task 31.2) can
+ * import and run it, and it is directly runnable via `npm run example`
+ * (`node dist/examples/storage-demo.js`).
+ *
+ * _Requirements: 25.1, 25.2, 25.3_
+ */
+import { Buffer } from "node:buffer";
+import { Readable } from "node:stream";
+import { pathToFileURL } from "node:url";
+import { createStorage } from "../index.js";
+/**
+ * A minimal, dependency-free fake image codec. A real deployment would supply
+ * a `sharp`/`jimp`-backed codec here; for the demo we only need something that
+ * proves the framework's resize/thumbnail/format orchestration works without a
+ * real image library. It returns new bytes that encode the requested operation
+ * so the produced variant is deterministic and distinguishable from the source.
+ */
+const fakeImageCodec = {
+    transform(bytes, operation) {
+        const width = operation.resize?.width ?? "auto";
+        const height = operation.resize?.height ?? "auto";
+        const format = operation.format ?? "png";
+        const quality = operation.quality ?? "default";
+        // The "encoded" variant: a small header describing the transform followed by
+        // a length-scaled slice of the source bytes. Purely illustrative.
+        const header = Buffer.from(`FAKE-IMG;format=${format};w=${width};h=${height};q=${quality};src=${bytes.byteLength}\n`, "utf8");
+        return Buffer.concat([header, Buffer.from(bytes.slice(0, 16))]);
+    },
+};
+/**
+ * A tiny in-process Realtime bridge that just logs every broadcast. In a real
+ * app this would be the `@streetjs/realtime` server; here it demonstrates that
+ * upload state transitions (`upload.started` / `upload.completed` / ...) flow
+ * through the configured bridge with no external service.
+ */
+function loggingRealtimeBridge(log) {
+    return {
+        broadcast(channel, event, payload) {
+            log(`  [realtime] ${channel} → ${event} ${JSON.stringify(payload)}`);
+        },
+    };
+}
+/**
+ * Build a Node Readable stream from `data`, emitting it in fixed-size chunks and
+ * invoking `onProgress(bytesSoFar, total)` as each chunk is produced. This is
+ * how the demo surfaces byte-level upload progress via a progress callback,
+ * complementing the Realtime bridge's state-transition events.
+ */
+function chunkedStream(data, chunkSize, onProgress) {
+    let offset = 0;
+    const total = data.byteLength;
+    return new Readable({
+        read() {
+            if (offset >= total) {
+                this.push(null);
+                return;
+            }
+            const end = Math.min(offset + chunkSize, total);
+            const chunk = Buffer.from(data.slice(offset, end));
+            offset = end;
+            onProgress(offset, total);
+            this.push(chunk);
+        },
+    });
+}
+/** A trivial deterministic PNG-ish payload for the demo avatar (not a real PNG). */
+function makeAvatarBytes(label, size) {
+    const bytes = Buffer.alloc(size);
+    // Fake PNG signature so it reads as image-like content; content type is what
+    // actually drives the image processor, but this keeps the payload plausible.
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(bytes, 0);
+    Buffer.from(label, "utf8").copy(bytes, 8);
+    return bytes;
+}
+/**
+ * Run the storage demo end to end against the zero-dependency in-memory
+ * provider. Accepts an optional `log` sink (defaults to `console.log`) so the
+ * smoke test can capture output. Returns a small summary of the demonstrated
+ * operations so callers can assert on the outcome (Requirement 25.3).
+ */
+export async function runStorageDemo(log = (line) => console.log(line)) {
+    log("=== @streetjs/storage demo (zero-dependency, no external services) ===\n");
+    const realtimeLog = [];
+    // 1. Construct the facade against the in-memory provider. A signing secret
+    //    enables signed URLs; the fake codec enables image processing; the
+    //    realtime bridge surfaces upload progress — all in-process.
+    const storage = createStorage({
+        provider: "memory",
+        signingSecret: "demo-signing-secret-not-for-production",
+        imageCodec: fakeImageCodec,
+        bridges: {
+            realtime: loggingRealtimeBridge((line) => {
+                realtimeLog.push(line);
+                log(line);
+            }),
+        },
+    });
+    const avatarKey = "avatars/user-42.png";
+    // 2. Upload an avatar.
+    log("1. Uploading avatar…");
+    const original = makeAvatarBytes("original-avatar", 128);
+    const uploaded = await storage.put(avatarKey, original, {
+        contentType: "image/png",
+        owner: "user-42",
+    });
+    log(`   uploaded ${uploaded.key} (${uploaded.size} bytes, etag=${uploaded.etag})\n`);
+    // 3. Download it back and confirm the round-trip.
+    log("2. Downloading avatar…");
+    const got = await storage.get(avatarKey);
+    if (!got.found || got.bytes === undefined) {
+        throw new Error("demo failed: uploaded avatar could not be downloaded");
+    }
+    const downloadedMatches = Buffer.from(got.bytes).equals(Buffer.from(original));
+    log(`   downloaded ${got.bytes.byteLength} bytes, matches upload: ${downloadedMatches}\n`);
+    if (!downloadedMatches) {
+        throw new Error("demo failed: downloaded avatar bytes did not match the upload");
+    }
+    // 4. Replace the avatar with new content (same key).
+    log("3. Replacing avatar…");
+    const replacement = makeAvatarBytes("replacement-avatar", 256);
+    const replaced = await storage.put(avatarKey, replacement, {
+        contentType: "image/png",
+        owner: "user-42",
+    });
+    log(`   replaced ${replaced.key} → now ${replaced.size} bytes (etag=${replaced.etag})\n`);
+    // 5. Upload a second object then list everything.
+    log("4. Listing objects…");
+    await storage.put("avatars/user-7.png", makeAvatarBytes("seven", 64), {
+        contentType: "image/png",
+        owner: "user-7",
+    });
+    const listed = await storage.list("avatars/");
+    for (const item of listed) {
+        log(`   • ${item.key} (${item.size} bytes)`);
+    }
+    log("");
+    const listedKeys = listed.map((item) => item.key);
+    // 6. Delete an object.
+    log("5. Deleting an object…");
+    const deletedKey = "avatars/user-7.png";
+    await storage.delete(deletedKey);
+    const stillThere = await storage.exists(deletedKey);
+    log(`   deleted ${deletedKey}, still exists: ${stillThere}\n`);
+    // 7. Generate a signed URL for the avatar.
+    log("6. Generating a signed URL…");
+    const url = await storage.signedUrl(avatarKey, "GET", { expiresInMs: 60_000 });
+    log(`   signed URL: ${url}\n`);
+    // 8. Show upload progress via putStream: the Realtime bridge logs the
+    //    started/completed transitions, and the chunked stream reports byte-level
+    //    progress through the callback below.
+    log("7. Streaming upload with progress…");
+    let progressUpdates = 0;
+    const streamData = makeAvatarBytes("streamed-upload", 200);
+    const stream = chunkedStream(streamData, 32, (transferred, total) => {
+        progressUpdates += 1;
+        log(`  [progress] ${transferred}/${total} bytes`);
+    });
+    const streamedKey = "avatars/user-42-streamed.png";
+    const streamed = await storage.putStream(streamedKey, stream, {
+        contentType: "image/png",
+        owner: "user-42",
+    });
+    log(`   streamed ${streamed.key} (${streamed.size} bytes) in ${progressUpdates} chunks\n`);
+    // 9. Resize the avatar image (through the fake codec).
+    log("8. Resizing the avatar image…");
+    const resized = await storage.images.transform(avatarKey, {
+        resize: { width: 128, height: 128 },
+        format: "webp",
+    });
+    log(`   resized variant: ${resized.key} (${resized.size} bytes, ${resized.contentType})\n`);
+    // 10. Generate a thumbnail.
+    log("9. Generating a thumbnail…");
+    const thumbnail = await storage.images.transform(avatarKey, {
+        thumbnail: { size: 32 },
+        format: "png",
+    });
+    log(`   thumbnail variant: ${thumbnail.key} (${thumbnail.size} bytes, ${thumbnail.contentType})\n`);
+    // 11. Inspect metadata for the avatar.
+    log("10. Inspecting metadata…");
+    const metadata = await storage.stat(avatarKey);
+    if (metadata === null) {
+        throw new Error("demo failed: avatar metadata could not be inspected");
+    }
+    log(`   ${metadata.key}: size=${metadata.size}, contentType=${metadata.contentType}, ` +
+        `owner=${metadata.owner ?? "-"}, access=${metadata.accessLevel}, ` +
+        `checksum=${metadata.checksum.slice(0, 12)}…`);
+    log(`   createdAt=${metadata.createdAt}, updatedAt=${metadata.updatedAt}\n`);
+    // Surface the in-flight stats gathered along the way.
+    const stats = storage.stats();
+    log(`Stats: uploads=${stats.uploads}, downloads=${stats.downloads}, ` +
+        `bytesUploaded=${stats.bytesUploaded}, storageUsage=${stats.storageUsage}`);
+    await storage.close();
+    log("\n=== demo complete ===");
+    return {
+        downloaded: downloadedMatches ? "ok" : "mismatch",
+        replaced: replaced.key,
+        listedKeys,
+        deletedKey,
+        signedUrl: url,
+        progressUpdates,
+        resizedKey: resized.key,
+        thumbnailKey: thumbnail.key,
+        avatarSize: metadata.size,
+    };
+}
+// Make the module runnable directly: `node dist/examples/storage-demo.js`.
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    runStorageDemo().catch((error) => {
+        console.error("storage demo failed:", error);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=storage-demo.js.map

package/dist/examples/storage-demo.js.map

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

package/dist/facade.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @streetjs/storage — the storage facade and configuration-driven construction.
+ *
+ * Application code talks only to the {@link Storage} facade returned by
+ * {@link createStorage}. The facade presents one public surface that is
+ * identical no matter which {@link StorageDriver} backs it, delegating the
+ * actual byte persistence to the driver while running (in later tasks) the
+ * cross-cutting layers (validation, access control, versioning, lifecycle,
+ * streaming/multipart/resumable sessions, signed URLs, images, directory,
+ * search, observability, integration bridges).
+ *
+ * This module (task 5.1) implements **construction and provider selection**:
+ *
+ * - A built-in driver registry resolves the zero-dependency providers `memory`
+ *   ({@link MemoryStorageDriver}) and `local` ({@link LocalStorageDriver},
+ *   which requires `config.root`).
+ * - Cloud providers are supplied as an already-constructed `config.driver`
+ *   instance (imported from the relevant submodule), which takes precedence and
+ *   works for any provider name.
+ * - An unknown provider name with no supplied driver yields a descriptive
+ *   {@link StorageConfigError} and **no** {@link Storage} instance is produced
+ *   (Requirement 1.5). Because the error is simply thrown (never caught and
+ *   swallowed into a fabricated instance), if constructing the error object
+ *   itself fails for some unexpected internal reason, that internal failure
+ *   surfaces as a thrown error and, again, no instance is produced
+ *   (Requirement 1.6).
+ *
+ * The object-operation method bodies (`put`/`get`/`exists`/`delete`/`copy`/
+ * `move`/`rename`/`list`/`stat`), streaming, multipart, resumable, signed URLs,
+ * versioning, images, directory, search, and observability are implemented in
+ * later tasks (5.2 onward). They are stubbed here so the file compiles, while
+ * the facade is structured as a class holding the resolved `driver` + `config`
+ * so those tasks can fill in the behavior cleanly.
+ *
+ * _Requirements: 1.1, 1.2, 1.4, 1.5, 1.6_
+ */
+import type { NodeReadable, StoredPart } from "./driver.js";
+import type { CopyResult, GetResult, LifecycleOutcome, LifecycleRule, ListOptions, MoveResult, SearchFilters, SignedOperation, SignedUrlOptions, StorageConfig, StorageListItem, StorageMetadataMap, StorageObjectMetadata, StorageStats, DriverProbe, VersionInfo, WriteMetadata } from "./types.js";
+/**
+ * Options accepted by write operations (`put`/`putStream`/`createMultipartUpload`/
+ * `startUpload`). These are the write-time metadata fields carried onto the
+ * stored object (Requirement 4.1). Additional write-time concerns (validation
+ * overrides, versioning toggles) are layered on by later tasks.
+ */
+export interface PutOptions extends WriteMetadata {
+}
+/**
+ * The output image formats the {@link ImageProcessor} can emit (Requirement
+ * 14.2).
+ */
+export type ImageFormat = "webp" | "avif" | "png" | "jpeg";
+/** A resize transformation: at least one of width/height (pixels). */
+export interface ImageResize {
+    readonly width?: number;
+    readonly height?: number;
+}
+/** A crop transformation: a rectangular region (pixels) of the source. */
+export interface ImageCrop {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A fit transformation: fit the image within a bounding box (pixels). */
+export interface ImageFit {
+    readonly width: number;
+    readonly height: number;
+    /** Optional fit strategy hint for codecs that support it. */
+    readonly mode?: "cover" | "contain" | "fill" | "inside" | "outside";
+}
+/**
+ * The transformation / format-conversion parameters accepted by
+ * {@link ImageProcessor.transform}. Every field is optional so a caller
+ * combines only the operations they need; all supported transformations
+ * (resize, crop, rotate, fit, thumbnail, compress — Requirement 14.1) and the
+ * output `format` selection (Requirement 14.2) are expressed here.
+ */
+export interface ImageOperations {
+    /** Resize to the given width/height. */
+    readonly resize?: ImageResize;
+    /** Crop to the given rectangle. */
+    readonly crop?: ImageCrop;
+    /** Rotate by the given number of degrees. */
+    readonly rotate?: number;
+    /** Fit within the given bounding box. */
+    readonly fit?: ImageFit;
+    /** Produce a square thumbnail of the given edge size (pixels). */
+    readonly thumbnail?: {
+        readonly size: number;
+    };
+    /** Compress at the given quality (0–100). */
+    readonly compress?: {
+        readonly quality: number;
+    };
+    /** Convert the output to this format (defaults to the source format). */
+    readonly format?: ImageFormat;
+    /** Output quality (0–100) applied by the codec when it supports it. */
+    readonly quality?: number;
+}
+/**
+ * The image processing surface exposed as `storage.images` (Requirement 14).
+ *
+ * The concrete implementation lives in `src/image.ts`
+ * ({@link StorageImageProcessor}); this interface is the stable public type,
+ * owned here so it re-exports cleanly from `index.ts`. It supports the
+ * resize/crop/rotate/fit/thumbnail/compress transformations and webp/avif/png/
+ * jpeg output formats, performed through the optional structural
+ * `config.imageCodec`.
+ */
+export interface ImageProcessor {
+    /**
+     * Produce a transformed / reformatted variant of the image stored at `key`,
+     * returning the variant's {@link StorageObjectMetadata}. A non-image source
+     * yields a descriptive error without modifying the source object
+     * (Requirement 14.4).
+     */
+    transform(key: string, operations: ImageOperations): Promise<StorageObjectMetadata>;
+}
+/**
+ * Placeholder for the directory surface exposed as `storage.directory`.
+ *
+ * The full {@link DirectoryApi} is implemented in `src/directory.ts` (task 17),
+ * at which point this facade imports it from that module. It is declared here
+ * only so the {@link Storage} interface type-checks in the interim.
+ */
+export interface DirectoryApi {
+    mkdir(path: string): Promise<void>;
+    listDirectory(path: string): Promise<StorageListItem[]>;
+    removeDirectory(path: string): Promise<{
+        readonly removed: boolean;
+    }>;
+    walk(path: string): Promise<string[]>;
+}
+/**
+ * The single public storage surface. Every method signature is identical across
+ * all providers so switching the configured driver never changes application
+ * code (Requirement 1.4). Backed by exactly one {@link StorageDriver}.
+ *
+ * @typeParam T - Optional per-application custom metadata map.
+ */
+export interface Storage<T extends StorageMetadataMap = StorageMetadataMap> {
+    put(key: string, content: Uint8Array | string, options?: PutOptions): Promise<StorageObjectMetadata>;
+    get(key: string): Promise<GetResult>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    copy(source: string, destination: string): Promise<CopyResult>;
+    move(source: string, destination: string): Promise<MoveResult>;
+    rename(key: string, newKey: string): Promise<MoveResult>;
+    list(prefix: string, options?: ListOptions): Promise<StorageListItem[]>;
+    stat(key: string): Promise<StorageObjectMetadata | null>;
+    putStream(key: string, stream: NodeReadable, options?: PutOptions): Promise<StorageObjectMetadata>;
+    getStream(key: string): Promise<NodeReadable>;
+    createMultipartUpload(key: string, options?: PutOptions): Promise<string>;
+    uploadPart(uploadId: string, partNumber: number, content: Uint8Array): Promise<StoredPart>;
+    completeMultipartUpload(uploadId: string, parts: readonly StoredPart[]): Promise<StorageObjectMetadata>;
+    abortMultipartUpload(uploadId: string): Promise<void>;
+    startUpload(key: string, options?: PutOptions): Promise<string>;
+    resumeUpload(sessionId: string, stream: NodeReadable): Promise<StorageObjectMetadata>;
+    cancelUpload(sessionId: string): Promise<void>;
+    signedUrl(key: string, op: SignedOperation, options?: SignedUrlOptions): Promise<string>;
+    listVersions(key: string): Promise<VersionInfo[]>;
+    restoreVersion(key: string, versionId: string): Promise<StorageObjectMetadata>;
+    deleteVersion(key: string, versionId: string): Promise<void>;
+    applyLifecycle(rule: LifecycleRule): Promise<LifecycleOutcome[]>;
+    readonly images: ImageProcessor;
+    readonly directory: DirectoryApi;
+    search(filters: SearchFilters): Promise<StorageListItem[]>;
+    stats(): StorageStats;
+    probe(): Promise<DriverProbe>;
+    close(): Promise<void>;
+}
+/**
+ * Construct a {@link Storage} instance backed by the driver selected in `config`
+ * (Requirements 1.1, 1.2). The returned facade exposes an identical public
+ * method set for every provider (Requirement 1.4).
+ *
+ * Provider selection:
+ * - `config.driver`, when supplied, is used directly (cloud providers imported
+ *   from `@streetjs/storage/*` submodules).
+ * - Otherwise `config.provider` selects a built-in zero-dependency driver
+ *   (`memory` or `local`; `local` requires `config.root`).
+ *
+ * @throws StorageConfigError when the provider name is unknown and no `driver`
+ *   is supplied — no {@link Storage} instance is produced (Requirement 1.5). If
+ *   constructing that error object itself fails unexpectedly, the internal
+ *   failure surfaces as a thrown error and, likewise, no instance is produced
+ *   (Requirement 1.6).
+ *
+ * @typeParam T - Optional per-application custom metadata map.
+ */
+export declare function createStorage<T extends StorageMetadataMap = StorageMetadataMap>(config: StorageConfig): Storage<T>;
+//# sourceMappingURL=facade.d.ts.map

package/dist/facade.d.ts.map

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