@streetjs/storage 1.0.0

package/dist/tests/contract.js

@@ -0,0 +1,222 @@
+/**
+ * @streetjs/storage — the shared, parameterized contract-conformance suite.
+ *
+ * Requirement 2 states that every provider implements one `StorageDriver`
+ * contract with identical observable behavior: object existence, content bytes,
+ * and returned metadata must be equivalent across drivers (Requirement 2.1,
+ * 2.3), and a missing key must be reported the same way everywhere
+ * (Requirement 2.4). This module encodes the observable core of that contract
+ * as a **reusable, driver-agnostic conformance suite** so the exact same checks
+ * can be run against any {@link StorageDriver} — the zero-dependency Memory and
+ * Local drivers, the in-process testing doubles, and every cloud driver.
+ *
+ * The suite is designed to be consumed in two ways from one definition:
+ *
+ * - **Programmatically** (returns pass/fail results). {@link runStorageDriverContract}
+ *   runs every check against a freshly constructed driver and returns a
+ *   {@link ContractReport} describing which checks passed. This is what the
+ *   `storage:verify` CLI command (task 24.2) uses to report whether the
+ *   configured driver satisfies the contract, and what Property 19 (task 27.3)
+ *   uses to assert that every driver conforms.
+ * - **As node:test tests**. {@link registerStorageDriverContractTests} turns each
+ *   check into a `node:test` case using a caller-supplied `test` function, so a
+ *   thin `*.test.js` can run the suite against Memory + Local without this
+ *   support module importing `node:test` itself (keeping it importable from the
+ *   CLI, which has no test runner in scope).
+ *
+ * Each check receives its **own freshly constructed driver** (from the supplied
+ * factory) so checks are fully isolated and order-independent. Assertions use
+ * `node:assert/strict`; a check throws on failure and returns normally on
+ * success. The checked behaviors are:
+ *
+ * 1. **existence** — `put` then `exists(key)` is `true`; `exists(other)` is `false`.
+ * 2. **byte round-trip** — `put(key, bytes)` then `get(key)` yields
+ *    `{ found: true }` with content bytes exactly equal to the input.
+ * 3. **not-found (get)** — `get(missing)` yields `{ found: false }`.
+ * 4. **not-found (stat)** — `stat(missing)` yields `null`.
+ * 5. **metadata shape** — `put` returns the complete typed
+ *    {@link StorageObjectMetadata} field set with correctly typed values.
+ *
+ * This module is a support module under `src/tests/` (not itself a `*.test.js`
+ * picked up by the default test glob); it is imported by tests and by the CLI.
+ *
+ * _Requirements: 2.1, 2.3, 2.4_
+ */
+import assert from "node:assert/strict";
+import { STORAGE_METADATA_FIELDS } from "../metadata.js";
+// ── Test fixtures ─────────────────────────────────────────────────────────────
+/** Encode a UTF-8 string into a Uint8Array for storage. */
+function bytesOf(str) {
+    return new TextEncoder().encode(str);
+}
+/** The full set of access levels, used to validate the `accessLevel` field. */
+const ACCESS_LEVELS = [
+    "public",
+    "private",
+    "signed",
+    "authenticated",
+    "role-based",
+    "tenant-aware",
+];
+/**
+ * Assert that `metadata` carries the complete typed {@link StorageObjectMetadata}
+ * field set with correctly typed values. Uses {@link STORAGE_METADATA_FIELDS} as
+ * the single source of truth for the required field names so this check tracks
+ * the canonical shape automatically (Requirement 2.1, 10.1).
+ */
+function assertMetadataShape(metadata, expected) {
+    assert.ok(metadata !== null && typeof metadata === "object", "put must return a metadata object");
+    // Every canonical field must be present as an own key.
+    for (const field of STORAGE_METADATA_FIELDS) {
+        assert.ok(field in metadata, `metadata is missing required field "${field}"`);
+    }
+    // Identity / value fields must be correctly typed.
+    assert.equal(metadata.key, expected.key, "metadata.key must equal the stored key");
+    assert.equal(metadata.size, expected.size, "metadata.size must equal the byte length");
+    assert.equal(typeof metadata.contentType, "string", "metadata.contentType must be a string");
+    assert.equal(typeof metadata.etag, "string", "metadata.etag must be a string");
+    assert.equal(typeof metadata.checksum, "string", "metadata.checksum must be a string");
+    assert.equal(typeof metadata.createdAt, "number", "metadata.createdAt must be a number");
+    assert.equal(typeof metadata.updatedAt, "number", "metadata.updatedAt must be a number");
+    assert.ok(metadata.custom !== null && typeof metadata.custom === "object", "metadata.custom must be an object");
+    assert.ok(ACCESS_LEVELS.includes(metadata.accessLevel), `metadata.accessLevel must be a valid AccessLevel (got "${metadata.accessLevel}")`);
+    // owner/tenant are optional: absent (undefined) or a string.
+    if (metadata.owner !== undefined) {
+        assert.equal(typeof metadata.owner, "string", "metadata.owner must be a string when present");
+    }
+    if (metadata.tenant !== undefined) {
+        assert.equal(typeof metadata.tenant, "string", "metadata.tenant must be a string when present");
+    }
+}
+// ── The checks ────────────────────────────────────────────────────────────────
+/**
+ * The ordered set of observable-behavior checks that make up the driver
+ * contract-conformance suite. Exported so consumers can inspect, subset, or
+ * extend the list; most callers use {@link runStorageDriverContract} or
+ * {@link registerStorageDriverContractTests} instead.
+ */
+export const storageDriverContractChecks = [
+    {
+        name: "existence: put then exists reports presence and absence",
+        requirement: "2.1",
+        async run(driver) {
+            const key = "contract/existence.txt";
+            assert.equal(await driver.exists(key), false, "exists must be false before the object is stored");
+            await driver.put(key, bytesOf("present"), {});
+            assert.equal(await driver.exists(key), true, "exists must be true after put");
+            assert.equal(await driver.exists("contract/never-written.txt"), false, "exists must be false for an unrelated key");
+        },
+    },
+    {
+        name: "byte round-trip: get returns the stored bytes unchanged",
+        requirement: "2.1",
+        async run(driver) {
+            const key = "contract/round-trip.bin";
+            // Include boundary byte values so a lossy round-trip is caught.
+            const content = new Uint8Array([0, 1, 127, 128, 254, 255, 65, 66, 67]);
+            await driver.put(key, content, {});
+            const result = await driver.get(key);
+            assert.equal(result.found, true, "get must report found:true for a stored key");
+            assert.ok(result.found === true, "narrowing: result must be the found variant");
+            assert.deepEqual(result.bytes, content, "get must return the exact stored bytes");
+        },
+    },
+    {
+        name: "not-found (get): missing key reports found:false",
+        requirement: "2.4",
+        async run(driver) {
+            const result = await driver.get("contract/absent-get.txt");
+            assert.equal(result.found, false, "get on a missing key must report found:false");
+            assert.ok(result.found === false, "the not-found result must be the { found: false } variant");
+        },
+    },
+    {
+        name: "not-found (stat): missing key reports null",
+        requirement: "2.4",
+        async run(driver) {
+            const meta = await driver.stat("contract/absent-stat.txt");
+            assert.equal(meta, null, "stat on a missing key must return null");
+        },
+    },
+    {
+        name: "metadata shape: put returns the complete typed field set",
+        requirement: "2.1",
+        async run(driver) {
+            const key = "contract/metadata-shape.txt";
+            const content = bytesOf("shape check");
+            const metadata = await driver.put(key, content, {
+                contentType: "text/plain",
+                owner: "user-1",
+                tenant: "tenant-a",
+                accessLevel: "public",
+                custom: { label: "invoice" },
+            });
+            assertMetadataShape(metadata, { key, size: content.byteLength });
+        },
+    },
+];
+/**
+ * Run the contract-conformance suite against a driver and return a pass/fail
+ * {@link ContractReport}. Each check is executed against a freshly constructed
+ * driver from `makeDriver` so the checks never interfere with one another.
+ *
+ * This never throws for a contract violation — a failing check is captured as a
+ * `passed: false` entry with its error message — so a consumer such as the
+ * `storage:verify` CLI (task 24.2) can render every result. Property 19
+ * (task 27.3) uses the returned {@link ContractReport.passed} to assert
+ * conformance across drivers.
+ *
+ * @param makeDriver Factory producing a fresh driver for each check.
+ * @param options Optional override of the checks to run.
+ */
+export async function runStorageDriverContract(makeDriver, options) {
+    const checks = options?.checks ?? storageDriverContractChecks;
+    const results = [];
+    let driverName = "unknown";
+    for (const check of checks) {
+        const driver = await makeDriver();
+        driverName = driver.name;
+        try {
+            await check.run(driver);
+            results.push({ name: check.name, requirement: check.requirement, passed: true });
+        }
+        catch (error) {
+            results.push({
+                name: check.name,
+                requirement: check.requirement,
+                passed: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return {
+        driver: driverName,
+        passed: results.every((result) => result.passed),
+        results,
+    };
+}
+// ── node:test integration ─────────────────────────────────────────────────────
+/**
+ * Register each contract check as an individual `node:test` case using the
+ * supplied `test` runner. A thin `*.test.js` passes `test` from `node:test` and
+ * a driver factory; each check runs against a fresh driver and fails the test if
+ * the driver violates the contract.
+ *
+ * Taking the runner as a parameter keeps this module free of a hard `node:test`
+ * import, so it remains importable from non-test contexts (e.g. the CLI's
+ * `storage:verify`).
+ *
+ * @param label Prefix for each generated test name (e.g. the driver label).
+ * @param makeDriver Factory producing a fresh driver for each check.
+ * @param runner The `test` function from `node:test` (or a compatible runner).
+ * @param checks Optional override of the checks to run.
+ */
+export function registerStorageDriverContractTests(label, makeDriver, runner, checks = storageDriverContractChecks) {
+    for (const check of checks) {
+        runner(`${label}: ${check.name}`, async () => {
+            const driver = await makeDriver();
+            await check.run(driver);
+        });
+    }
+}
+//# sourceMappingURL=contract.js.map

package/dist/tests/contract.js.map

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

package/dist/tests/contract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.test.d.ts.map

package/dist/tests/contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.test.d.ts","sourceRoot":"","sources":["../../src/tests/contract.test.ts"],"names":[],"mappings":""}

package/dist/tests/contract.test.js

@@ -0,0 +1,110 @@
+// Contract-conformance suite run against the two zero-dependency drivers.
+//
+// Exercises the shared, parameterized suite from `./contract.js` (task 27.1)
+// against MemoryStorageDriver and LocalStorageDriver, verifying both directions
+// it is consumed in production:
+//
+//   - as node:test cases via registerStorageDriverContractTests (what a driver's
+//     own test file would do), and
+//   - programmatically via runStorageDriverContract (what `storage:verify` and
+//     Property 19 use), asserting the returned report passes for every check.
+//
+// Each check receives a freshly constructed driver from the supplied factory;
+// the Local driver gets a fresh temp directory per instance so checks stay
+// isolated. Executed via `node --test dist/tests/*.test.js`.
+//
+// Requirements: 2.1, 2.3, 2.4
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runStorageDriverContract, registerStorageDriverContractTests, storageDriverContractChecks, } from "./contract.js";
+import { MemoryStorageDriver } from "../drivers/memory.js";
+import { LocalStorageDriver } from "../drivers/local.js";
+/** A fixed clock for deterministic timestamps. */
+const fixedClock = () => 1_700_000_000_000;
+/** Factory: a fresh in-memory driver per call. */
+function makeMemoryDriver() {
+    return new MemoryStorageDriver({ clock: fixedClock });
+}
+/** Temp roots allocated for Local drivers, cleaned up after the run. */
+const tempRoots = [];
+/** Factory: a fresh filesystem driver rooted at a unique temp dir per call. */
+function makeLocalDriver() {
+    const root = mkdtempSync(join(tmpdir(), "streetjs-storage-contract-"));
+    tempRoots.push(root);
+    return new LocalStorageDriver({ root, clock: fixedClock });
+}
+test.after(() => {
+    for (const root of tempRoots) {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+// ── As node:test cases (per-driver, per-check) ────────────────────────────────
+registerStorageDriverContractTests("memory driver contract", makeMemoryDriver, test);
+registerStorageDriverContractTests("local driver contract", makeLocalDriver, test);
+// ── Programmatically (the storage:verify / Property 19 consumption path) ──────
+test("runStorageDriverContract reports a full pass for the memory driver", async () => {
+    const report = await runStorageDriverContract(makeMemoryDriver);
+    assert.equal(report.driver, "memory");
+    assert.equal(report.passed, true);
+    assert.equal(report.results.length, storageDriverContractChecks.length);
+    assert.ok(report.results.every((result) => result.passed), `all checks must pass, got: ${JSON.stringify(report.results)}`);
+});
+test("runStorageDriverContract reports a full pass for the local driver", async () => {
+    const report = await runStorageDriverContract(makeLocalDriver);
+    assert.equal(report.driver, "local");
+    assert.equal(report.passed, true);
+    assert.equal(report.results.length, storageDriverContractChecks.length);
+    assert.ok(report.results.every((result) => result.passed), `all checks must pass, got: ${JSON.stringify(report.results)}`);
+});
+test("a non-conforming driver is reported as failed, not thrown", async () => {
+    // A driver that always reports a missing object exists violates the
+    // not-found and round-trip checks; the runner must capture this as failures
+    // rather than throwing.
+    const brokenDriver = {
+        name: "broken",
+        async put(key, bytes) {
+            return {
+                key,
+                size: bytes.byteLength,
+                contentType: "application/octet-stream",
+                etag: "x",
+                checksum: "x",
+                accessLevel: "private",
+                createdAt: 0,
+                updatedAt: 0,
+                custom: {},
+            };
+        },
+        async get() {
+            return { found: false };
+        },
+        async exists() {
+            return false;
+        },
+        async delete() { },
+        async stat() {
+            return null;
+        },
+        async list() {
+            return [];
+        },
+        async putStream(key, _stream, _metadata) {
+            return this.put(key, new Uint8Array(), {});
+        },
+        async getStream() {
+            throw new Error("unsupported");
+        },
+    };
+    const report = await runStorageDriverContract(() => brokenDriver);
+    assert.equal(report.driver, "broken");
+    assert.equal(report.passed, false);
+    // existence and byte round-trip must fail (get always reports not-found);
+    // the two not-found checks and metadata shape still pass.
+    const failed = report.results.filter((result) => !result.passed).map((r) => r.name);
+    assert.ok(failed.some((name) => name.startsWith("existence")), "existence check should fail for the broken driver");
+    assert.ok(failed.some((name) => name.startsWith("byte round-trip")), "byte round-trip check should fail for the broken driver");
+});
+//# sourceMappingURL=contract.test.js.map

package/dist/tests/contract.test.js.map

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

package/dist/tests/directory.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=directory.test.d.ts.map

package/dist/tests/directory.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.test.d.ts","sourceRoot":"","sources":["../../src/tests/directory.test.ts"],"names":[],"mappings":""}

package/dist/tests/directory.test.js

@@ -0,0 +1,125 @@
+// Unit tests for the Directory API wired into the storage facade (task 17.1).
+//
+// Verifies the Requirement 15 semantics over the zero-dependency `memory`
+// provider, exercised through `storage.directory`:
+//
+//  - mkdir(path) makes the path available as a directory prefix (15.1).
+//  - listDirectory(path) returns only the IMMEDIATE children, collapsing
+//    deeper keys into a single sub-directory entry (15.2).
+//  - removeDirectory(path) removes every object under the prefix (15.3), and is
+//    a success no-op returning { removed: false } for an empty/missing prefix
+//    (15.6).
+//  - walk(path) returns every object key beneath the prefix (15.4).
+//
+// Uses the Node.js built-in test runner (node:test); executed via
+// `node --test dist/tests/*.test.js`.
+//
+// Requirements: 15.1, 15.2, 15.3, 15.4, 15.5, 15.6
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStorage } from "../facade.js";
+import { MemoryStorageDriver } from "../drivers/memory.js";
+/** Build a facade backed by a fresh in-memory driver. */
+function makeStorage() {
+    const driver = new MemoryStorageDriver({});
+    return createStorage({ provider: "memory", driver });
+}
+/** Seed the store with a small hierarchy of objects. */
+async function seed(storage) {
+    await storage.put("photos/a.jpg", "a");
+    await storage.put("photos/b.jpg", "bb");
+    await storage.put("photos/2024/c.jpg", "ccc");
+    await storage.put("photos/2024/holidays/d.jpg", "dddd");
+    await storage.put("docs/readme.txt", "hello");
+}
+test("directory getter returns a working, cached DirectoryApi", () => {
+    const storage = makeStorage();
+    const dir = storage.directory;
+    assert.equal(typeof dir.mkdir, "function");
+    assert.equal(typeof dir.listDirectory, "function");
+    assert.equal(typeof dir.removeDirectory, "function");
+    assert.equal(typeof dir.walk, "function");
+    // Same instance is reused across accesses (lazily constructed once).
+    assert.equal(storage.directory, dir);
+});
+test("mkdir makes the path available as a directory prefix (15.1)", async () => {
+    const storage = makeStorage();
+    await storage.directory.mkdir("uploads");
+    // The marker key exists so the empty directory is discoverable.
+    assert.equal(await storage.exists("uploads/"), true);
+    // A freshly-made directory has no child entries yet.
+    const listing = await storage.directory.listDirectory("uploads");
+    assert.deepEqual(listing, []);
+});
+test("mkdir on the root/empty path is a no-op (15.1)", async () => {
+    const storage = makeStorage();
+    await storage.directory.mkdir("");
+    await storage.directory.mkdir("/");
+    // No marker keys were written for the root.
+    const keys = await storage.directory.walk("");
+    assert.deepEqual(keys, []);
+});
+test("listDirectory returns only immediate children (15.2)", async () => {
+    const storage = makeStorage();
+    await seed(storage);
+    const listing = await storage.directory.listDirectory("photos");
+    const keys = listing.map((item) => item.key).sort();
+    // Immediate children of photos/: two files and one sub-directory entry;
+    // deeper keys (photos/2024/holidays/...) collapse into photos/2024/.
+    assert.deepEqual(keys, ["photos/2024/", "photos/a.jpg", "photos/b.jpg"]);
+    // The sub-directory entry is synthesized with size 0.
+    const subdir = listing.find((item) => item.key === "photos/2024/");
+    assert.equal(subdir.size, 0);
+    // File entries carry their real byte sizes.
+    const fileA = listing.find((item) => item.key === "photos/a.jpg");
+    assert.equal(fileA.size, 1);
+    const fileB = listing.find((item) => item.key === "photos/b.jpg");
+    assert.equal(fileB.size, 2);
+});
+test("listDirectory accepts leading/trailing delimiters equivalently (15.2)", async () => {
+    const storage = makeStorage();
+    await seed(storage);
+    const a = (await storage.directory.listDirectory("photos")).map((i) => i.key).sort();
+    const b = (await storage.directory.listDirectory("/photos/")).map((i) => i.key).sort();
+    assert.deepEqual(a, b);
+});
+test("walk returns every object key beneath the prefix (15.4)", async () => {
+    const storage = makeStorage();
+    await seed(storage);
+    const keys = (await storage.directory.walk("photos")).sort();
+    assert.deepEqual(keys, [
+        "photos/2024/c.jpg",
+        "photos/2024/holidays/d.jpg",
+        "photos/a.jpg",
+        "photos/b.jpg",
+    ]);
+    // walk excludes the directory's own marker key.
+    await storage.directory.mkdir("photos");
+    const withMarker = (await storage.directory.walk("photos")).sort();
+    assert.equal(withMarker.includes("photos/"), false);
+});
+test("removeDirectory removes every object under the prefix (15.3)", async () => {
+    const storage = makeStorage();
+    await seed(storage);
+    const result = await storage.directory.removeDirectory("photos");
+    assert.deepEqual(result, { removed: true });
+    // Nothing remains beneath photos/.
+    assert.deepEqual(await storage.directory.walk("photos"), []);
+    assert.equal(await storage.exists("photos/a.jpg"), false);
+    assert.equal(await storage.exists("photos/2024/holidays/d.jpg"), false);
+    // Sibling directories are untouched.
+    assert.equal(await storage.exists("docs/readme.txt"), true);
+});
+test("removeDirectory of an empty/missing prefix is a success no-op (15.6)", async () => {
+    const storage = makeStorage();
+    await seed(storage);
+    // Missing prefix: no objects removed, success result, siblings intact.
+    const missing = await storage.directory.removeDirectory("does-not-exist");
+    assert.deepEqual(missing, { removed: false });
+    assert.equal(await storage.exists("docs/readme.txt"), true);
+    // Removing twice: second call finds nothing and reports removed: false.
+    await storage.directory.removeDirectory("docs");
+    const second = await storage.directory.removeDirectory("docs");
+    assert.deepEqual(second, { removed: false });
+});
+//# sourceMappingURL=directory.test.js.map

package/dist/tests/directory.test.js.map

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

package/dist/tests/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/tests/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../src/tests/errors.test.ts"],"names":[],"mappings":""}

package/dist/tests/errors.test.js

@@ -0,0 +1,93 @@
+// Unit tests for the typed error hierarchy of @streetjs/storage.
+//
+// Verifies that every concrete error subclass derives from both StorageError
+// and the native Error (so consumers can catch the whole family or discriminate
+// on a subclass), that each carries its descriptive typed fields, and that each
+// sets `name` correctly. Uses the Node.js built-in test runner (node:test) and
+// is executed via `node --test dist/tests/*.test.js`.
+//
+// Requirements: 1.5, 9.4, 11.3
+import test from "node:test";
+import assert from "node:assert/strict";
+import { StorageError, StorageConfigError, NotFoundError, ValidationError, AuthorizationError, UnsupportedImageError, } from "../index.js";
+test("StorageError is a native Error and sets its name", () => {
+    const err = new StorageError("boom");
+    assert.ok(err instanceof Error);
+    assert.ok(err instanceof StorageError);
+    assert.equal(err.name, "StorageError");
+    assert.equal(err.message, "boom");
+});
+test("StorageError carries an optional cause", () => {
+    const underlying = new Error("root cause");
+    const err = new StorageError("wrapped", { cause: underlying });
+    assert.equal(err.cause, underlying);
+});
+test("StorageConfigError is instanceof StorageError and Error", () => {
+    const err = new StorageConfigError("bad config", { provider: "s3" });
+    assert.ok(err instanceof Error);
+    assert.ok(err instanceof StorageError);
+    assert.ok(err instanceof StorageConfigError);
+});
+test("StorageConfigError carries provider and name", () => {
+    const err = new StorageConfigError("unknown provider", { provider: "nope" });
+    assert.equal(err.name, "StorageConfigError");
+    assert.equal(err.provider, "nope");
+});
+test("NotFoundError is instanceof StorageError and Error", () => {
+    const err = new NotFoundError("photos/1.png");
+    assert.ok(err instanceof Error);
+    assert.ok(err instanceof StorageError);
+    assert.ok(err instanceof NotFoundError);
+});
+test("NotFoundError carries key, name, and default message", () => {
+    const err = new NotFoundError("photos/1.png");
+    assert.equal(err.name, "NotFoundError");
+    assert.equal(err.key, "photos/1.png");
+    assert.equal(err.message, 'Object not found for key "photos/1.png"');
+});
+test("ValidationError is instanceof StorageError and Error", () => {
+    const err = new ValidationError("file too large");
+    assert.ok(err instanceof Error);
+    assert.ok(err instanceof StorageError);
+    assert.ok(err instanceof ValidationError);
+});
+test("ValidationError carries validationError, optional key, and name", () => {
+    const err = new ValidationError("file too large", { key: "uploads/big.zip" });
+    assert.equal(err.name, "ValidationError");
+    assert.equal(err.validationError, "file too large");
+    assert.equal(err.key, "uploads/big.zip");
+    assert.equal(err.message, "Upload validation failed: file too large");
+});
+test("AuthorizationError is instanceof StorageError and Error", () => {
+    const err = new AuthorizationError("denied");
+    assert.ok(err instanceof Error);
+    assert.ok(err instanceof StorageError);
+    assert.ok(err instanceof AuthorizationError);
+});
+test("AuthorizationError carries key, operation, accessLevel, and name", () => {
+    const err = new AuthorizationError("access denied", {
+        key: "private/secret.txt",
+        operation: "read",
+        accessLevel: "private",
+    });
+    assert.equal(err.name, "AuthorizationError");
+    assert.equal(err.key, "private/secret.txt");
+    assert.equal(err.operation, "read");
+    assert.equal(err.accessLevel, "private");
+});
+test("UnsupportedImageError is instanceof StorageError and Error", () => {
+    const err = new UnsupportedImageError("cannot process");
+    assert.ok(err instanceof Error);
+    assert.ok(err instanceof StorageError);
+    assert.ok(err instanceof UnsupportedImageError);
+});
+test("UnsupportedImageError carries format, key, and name", () => {
+    const err = new UnsupportedImageError("unsupported format", {
+        format: "image/tiff",
+        key: "images/scan.tiff",
+    });
+    assert.equal(err.name, "UnsupportedImageError");
+    assert.equal(err.format, "image/tiff");
+    assert.equal(err.key, "images/scan.tiff");
+});
+//# sourceMappingURL=errors.test.js.map

package/dist/tests/errors.test.js.map

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

package/dist/tests/events-bridge.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=events-bridge.test.d.ts.map

package/dist/tests/events-bridge.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-bridge.test.d.ts","sourceRoot":"","sources":["../../src/tests/events-bridge.test.ts"],"names":[],"mappings":""}