@velajs/storage 0.2.0 → 0.3.1

package/README.md

@@ -52,5 +52,26 @@ class AppModule {}
 | R2 (HTTP + hybrid) | `@velajs/storage/drivers/r2-http` | ✅ | ✅ |
 | storagesdk bridge | `@velajs/storage/storagesdk` | Node/Bun only | depends on adapter |
 
+## Testing
+
+There's no separate storage fake — the **memory driver IS the fake**. Build a disk in one line and
+assert against it with the helpers from `@velajs/storage/testing`:
+
+```ts
+import { createStorage } from '@velajs/storage';
+import { memoryDriver } from '@velajs/storage/drivers/memory';
+import { assertExists, assertMissing, assertCount } from '@velajs/storage/testing';
+
+const storage = createStorage({ driver: memoryDriver() });
+await storage.upload('avatars/1.png', bytes);
+
+await assertExists(storage, 'avatars/1.png');
+await assertMissing(storage, 'avatars/2.png');
+await assertCount(storage, 'avatars/', 1); // or assertCount(storage, 1) for the whole disk
+```
+
+The helpers accept anything memory-backed — a `Storage` facade or an injected `StorageService`.
+For DI/integration tests, register the same driver instead: `StorageModule.forRoot({ driver: memoryDriver() })`.
+
 See the docs site for presigned uploads, the HTTP upload controller + browser client, middleware,
 multi-bucket, and the full capability matrix.

package/dist/drivers/s3/s3.driver.js

@@ -58,7 +58,10 @@ function toError(status, code, message, key) {
     const retryable = mapped === 'Provider' || mapped === 'RateLimited' || mapped === 'Timeout' || mapped === 'Network';
     return new StorageError(mapped, message ?? code ?? `S3 error${key ? ` (${key})` : ''}`, {
         status: status >= 400 ? status : undefined,
-        retryable
+        retryable,
+        // `message`/`code` are the provider's own <Message>/<Code> — never client-safe,
+        // even on a 4xx status (e.g. AccessDenied/NoSuchKey text can carry internal detail).
+        internal: true
     });
 }
 async function s3Error(res, key) {

package/dist/storage.controller.js

@@ -47,10 +47,16 @@ import { clampExpiry, dispositionHeader, mapError, parseRange, serializeStored }
         fail(c, e) {
             const err = e instanceof StorageError ? e : StorageError.wrap(e);
             const { wire, status } = mapError(err.code);
+            // Never echo a provider/transport/wrapped message to the client: those are
+            // flagged `internal` (driver <Message>/<Code>, StorageError.wrap, fromStatus)
+            // and can carry host/bucket/credential detail — including on a 4xx status.
+            // Redact internal errors at any status, plus all upstream (5xx) responses;
+            // 4xx codes with an author-vouched message echo it.
+            const message = err.internal || status >= 500 ? 'storage backend error' : err.message;
             return c.json({
                 error: {
                     code: wire,
-                    message: err.message
+                    message
                 }
             }, status);
         }

package/dist/storage.error.d.ts

@@ -12,12 +12,22 @@ export interface StorageErrorOptions {
     status?: number;
     /** Override the default retryability implied by {@link StorageErrorCode}. */
     retryable?: boolean;
+    /**
+     * True when `message` came from a provider/transport/wrapped source rather
+     * than being authored as client-safe text. The HTTP controller redacts such
+     * messages so raw provider detail never reaches a client. Default false —
+     * a bare `new StorageError(code, msg)` is the author's vouch that `msg` is
+     * client-safe; driver/wrap code MUST set this when echoing provider text.
+     */
+    internal?: boolean;
 }
 export declare class StorageError extends Error {
     name: string;
     readonly code: StorageErrorCode;
     readonly retryable: boolean;
     readonly status: number | undefined;
+    /** Whether `message` is non-client-safe (provider/transport/wrapped origin). */
+    readonly internal: boolean;
     constructor(code: StorageErrorCode, message: string, options?: StorageErrorOptions);
     /** Wrap an arbitrary thrown value as a `StorageError` (idempotent). */
     static wrap(e: unknown): StorageError;

package/dist/storage.error.js

@@ -15,6 +15,7 @@ export class StorageError extends Error {
     code;
     retryable;
     status;
+    /** Whether `message` is non-client-safe (provider/transport/wrapped origin). */ internal;
     constructor(code, message, options){
         super(message, options?.cause !== undefined ? {
             cause: options.cause
@@ -22,14 +23,17 @@ export class StorageError extends Error {
         this.code = code;
         this.status = options?.status;
         this.retryable = options?.retryable ?? RETRYABLE.has(code);
+        this.internal = options?.internal ?? false;
     }
     /** Wrap an arbitrary thrown value as a `StorageError` (idempotent). */ static wrap(e) {
         if (e instanceof StorageError) return e;
         if (isAbort(e)) return new StorageError('Aborted', 'operation aborted', {
             cause: e
         });
+        // The wrapped message is arbitrary provider/host text — never client-safe.
         return new StorageError('Provider', e instanceof Error ? e.message : String(e), {
-            cause: e
+            cause: e,
+            internal: true
         });
     }
     /** Map a transport status code to a `StorageError` (5xx/429 retryable). */ static fromStatus(status, message, cause) {
@@ -37,7 +41,9 @@ export class StorageError extends Error {
         return new StorageError(code, message, {
             status,
             cause,
-            retryable: status === 429 || status >= 500
+            retryable: status === 429 || status >= 500,
+            // Message came off a transport response — treat as non-client-safe.
+            internal: true
         });
     }
 }

package/dist/testing/index.d.ts

@@ -0,0 +1,17 @@
+import type { ListOptions, ListResult, OperationOptions } from '../storage.types';
+/**
+ * The read surface the assertions need. Satisfied by `StorageService`, the
+ * `Storage` facade, and a bare `StorageDriver` — anything memory-backed works.
+ */
+export interface StorageTarget {
+    exists(key: string, opts?: OperationOptions): Promise<boolean>;
+    list(opts?: ListOptions): Promise<ListResult>;
+}
+/** Assert an object exists at `key`; throws a diagnostic `Error` otherwise. */
+export declare function assertExists(storage: StorageTarget, key: string): Promise<void>;
+/** Assert nothing is stored at `key`; throws a diagnostic `Error` otherwise. */
+export declare function assertMissing(storage: StorageTarget, key: string): Promise<void>;
+/** Assert the disk holds exactly `expected` objects. */
+export declare function assertCount(storage: StorageTarget, expected: number): Promise<void>;
+/** Assert exactly `expected` objects exist under `prefix`. */
+export declare function assertCount(storage: StorageTarget, prefix: string, expected: number): Promise<void>;

package/dist/testing/index.js

@@ -0,0 +1,57 @@
+// @velajs/storage/testing — assertion helpers for tests.
+//
+// Vela has no separate storage fake: the in-package **memory driver IS the
+// fake**. Build a test disk in one obvious line and assert against it —
+// no bootstrap, no subclass:
+//
+//   import { createStorage } from '@velajs/storage';
+//   import { memoryDriver } from '@velajs/storage/drivers/memory';
+//   import { assertExists, assertCount } from '@velajs/storage/testing';
+//
+//   const storage = createStorage({ driver: memoryDriver() });
+//   await storage.upload('avatar.png', bytes);
+//   await assertExists(storage, 'avatar.png');
+//   await assertCount(storage, 'avatars/', 1);
+//
+// For DI/integration tests, register the same driver on the module instead —
+// `StorageModule.forRoot({ driver: memoryDriver() })` — then inject the
+// `StorageService` and pass it to these helpers. Both a `Storage` facade and a
+// `StorageService` satisfy the {@link StorageTarget} surface below.
+//
+// The helpers are thin and framework-free: they throw a plain `Error` with a
+// diagnostic message on failure (no vitest/`expect` dependency), and drive the
+// public `exists`/`list` API so prefix scoping and drivers stay honest.
+/** Assert an object exists at `key`; throws a diagnostic `Error` otherwise. */ export async function assertExists(storage, key) {
+    if (!await storage.exists(key)) {
+        const keys = await collectKeys(storage);
+        throw new Error(`assertExists: expected an object at "${key}" to exist, but it is missing. ` + `Stored: ${keys.length ? keys.join(', ') : '(none)'}`);
+    }
+}
+/** Assert nothing is stored at `key`; throws a diagnostic `Error` otherwise. */ export async function assertMissing(storage, key) {
+    if (await storage.exists(key)) {
+        throw new Error(`assertMissing: expected no object at "${key}", but one exists`);
+    }
+}
+export async function assertCount(storage, prefixOrExpected, maybeExpected) {
+    const prefix = typeof prefixOrExpected === 'string' ? prefixOrExpected : undefined;
+    const expected = typeof prefixOrExpected === 'number' ? prefixOrExpected : maybeExpected;
+    const keys = await collectKeys(storage, prefix);
+    if (keys.length !== expected) {
+        const scope = prefix ? ` under prefix "${prefix}"` : '';
+        const found = keys.length ? `: ${keys.join(', ')}` : '';
+        throw new Error(`assertCount: expected ${expected} object(s)${scope}, but found ${keys.length}${found}`);
+    }
+}
+/** Walk every listing page (following the cursor) and collect the object keys. */ async function collectKeys(storage, prefix) {
+    const keys = [];
+    let cursor;
+    do {
+        const page = await storage.list({
+            prefix,
+            cursor
+        });
+        for (const item of page.items)keys.push(item.key);
+        cursor = page.cursor;
+    }while (cursor)
+    return keys;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/storage",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Edge-first, driver-based object/file storage for the Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,6 +37,10 @@
     "./storagesdk": {
       "types": "./dist/storagesdk/index.d.ts",
       "import": "./dist/storagesdk/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
     }
   },
   "files": [
@@ -45,14 +49,6 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
-  "scripts": {
-    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
-    "test": "vitest run",
-    "test:workers": "vitest run --config vitest.config.workers.ts",
-    "typecheck": "tsc --noEmit",
-    "prepare": "swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
-    "prepublishOnly": "pnpm run typecheck && pnpm test"
-  },
   "sideEffects": false,
   "keywords": [
     "vela",
@@ -105,12 +101,10 @@
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.1.9"
   },
-  "packageManager": "pnpm@10.20.0",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "@swc/core",
-      "esbuild",
-      "workerd"
-    ]
+  "scripts": {
+    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "test:workers": "vitest run --config vitest.config.workers.ts",
+    "typecheck": "tsc --noEmit"
   }
-}
+}