@velajs/storage 0.2.0 → 0.3.0

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/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.0",
   "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"
   }
-}
+}