@zudojs/testing 1.1.1 → 1.2.0

package/dist/testMessageBus/testMessageBus.core.d.ts

@@ -1,9 +1,10 @@
 /**
  * Test message bus helpers.
  *
- * Wraps the real MessageBus with recording and assertion support.
+ * A real in-memory MessageBus that records every dispatch, whichever
+ * method it came through.
  */
-import type { Message, MessageInput, MessageBus, MessageBusOptions, DispatchResult, DispatchOptions } from "@zudojs/messaging";
+import type { Message, MessageBus, MessageBusOptions, DispatchResult } from "@zudojs/messaging";
 /**
  * A recorded message dispatch.
  */
@@ -13,48 +14,43 @@ export interface RecordedMessage<TPayload = unknown> {
     readonly timestamp: Date;
 }
 /**
- * A test message bus with recording capabilities.
+ * A test message bus: a `MessageBus` (so it can be handed to any code
+ * that takes one) that records every dispatch.
+ *
+ * `send` and `dispatch` both record, whether called on the test bus or on
+ * `bus` (the same instance).
  */
-export interface TestMessageBus {
+export interface TestMessageBus extends MessageBus {
+    /** This bus. Kept for code written against the earlier wrapper. */
     readonly bus: MessageBus;
     /**
-     * All recorded dispatches.
+     * All recorded dispatches, oldest first.
      */
     readonly dispatched: readonly RecordedMessage[];
-    /**
-     * Send a message and record the result.
-     */
-    send: <TPayload>(input: MessageInput<TPayload>, options?: DispatchOptions) => Promise<DispatchResult>;
     /**
      * Find dispatched messages by type.
      */
-    findByType: (type: string) => readonly RecordedMessage[];
+    findByType(type: string): readonly RecordedMessage[];
     /**
      * Clear recorded dispatches.
      */
-    clear: () => void;
-    /**
-     * Dispose the message bus.
-     */
-    dispose: () => void;
+    clear(): void;
 }
 /**
- * Creates a test message bus with recording.
+ * Creates a test message bus that records every dispatch.
  *
  * @param options - MessageBus options.
- * @returns A TestMessageBus instance.
+ * @returns A TestMessageBus, which is itself a `MessageBus`.
  *
  * @example
  * ```ts
- * const testBus = createTestMessageBus();
- *
- * testBus.bus.on("user.created", handler);
- * await testBus.send({ type: "user.created", payload: { id: "123" } });
+ * const messages = createTestMessageBus();
+ * messages.on("user.created", handler);
  *
- * expect(testBus.dispatched).toHaveLength(1);
- * expect(testBus.findByType("user.created")).toHaveLength(1);
+ * await notifier.run(messages); // takes a MessageBus, calls send(...)
  *
- * testBus.dispose();
+ * expect(messages.findByType("user.created")).toHaveLength(1);
+ * messages.dispose();
  * ```
  */
 export declare function createTestMessageBus(options?: MessageBusOptions): TestMessageBus;

package/dist/testMessageBus/testMessageBus.core.js

@@ -1,64 +1,62 @@
 /**
  * Test message bus helpers.
  *
- * Wraps the real MessageBus with recording and assertion support.
+ * A real in-memory MessageBus that records every dispatch, whichever
+ * method it came through.
  */
-import { createMessageBus } from "@zudojs/messaging";
-import { randomUUID } from "node:crypto";
+import { InMemoryMessageBus } from "@zudojs/messaging";
 /**
- * Creates a test message bus with recording.
+ * InMemoryMessageBus subclass that records at `dispatch`, the entry point
+ * `send` funnels into.
+ */
+class RecordingMessageBus extends InMemoryMessageBus {
+    recorded = [];
+    constructor(options) {
+        super(options);
+        // Bound, so destructured methods keep working as they did with the
+        // earlier closure-based wrapper.
+        this.send = this.send.bind(this);
+        this.dispatch = this.dispatch.bind(this);
+        this.findByType = this.findByType.bind(this);
+        this.clear = this.clear.bind(this);
+        this.dispose = this.dispose.bind(this);
+    }
+    get bus() {
+        return this;
+    }
+    get dispatched() {
+        return [...this.recorded];
+    }
+    async dispatch(message, options) {
+        const result = await super.dispatch(message, options);
+        this.recorded.push(Object.freeze({ message, result, timestamp: new Date() }));
+        return result;
+    }
+    findByType(type) {
+        return this.recorded.filter((entry) => entry.message.type === type);
+    }
+    clear() {
+        this.recorded.length = 0;
+    }
+}
+/**
+ * Creates a test message bus that records every dispatch.
  *
  * @param options - MessageBus options.
- * @returns A TestMessageBus instance.
+ * @returns A TestMessageBus, which is itself a `MessageBus`.
  *
  * @example
  * ```ts
- * const testBus = createTestMessageBus();
- *
- * testBus.bus.on("user.created", handler);
- * await testBus.send({ type: "user.created", payload: { id: "123" } });
+ * const messages = createTestMessageBus();
+ * messages.on("user.created", handler);
  *
- * expect(testBus.dispatched).toHaveLength(1);
- * expect(testBus.findByType("user.created")).toHaveLength(1);
+ * await notifier.run(messages); // takes a MessageBus, calls send(...)
  *
- * testBus.dispose();
+ * expect(messages.findByType("user.created")).toHaveLength(1);
+ * messages.dispose();
  * ```
  */
 export function createTestMessageBus(options = {}) {
-    const bus = createMessageBus(options);
-    const dispatched = [];
-    const send = async (input, dispatchOptions) => {
-        const message = {
-            id: `msg_${randomUUID()}`,
-            type: input.type,
-            payload: input.payload,
-            timestamp: new Date(),
-            ...(input.metadata ? { metadata: input.metadata } : {}),
-        };
-        const result = await bus.send(message, dispatchOptions);
-        dispatched.push({
-            message,
-            result,
-            timestamp: new Date(),
-        });
-        return result;
-    };
-    const findByType = (type) => dispatched.filter((d) => d.message.type === type);
-    const clear = () => {
-        dispatched.length = 0;
-    };
-    const dispose = () => {
-        bus.dispose();
-    };
-    return {
-        bus,
-        get dispatched() {
-            return [...dispatched];
-        },
-        send,
-        findByType,
-        clear,
-        dispose,
-    };
+    return new RecordingMessageBus(options);
 }
 //# sourceMappingURL=testMessageBus.core.js.map

package/dist/testQueue/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * Test queue helpers.
  *
- * InMemoryQueue with recording and assertion support.
+ * A `Queue` backed by a real InMemoryQueue that records every job added.
  */
 export { createTestQueue } from "./testQueue.core.js";
-export type { RecordedJob, TestQueue } from "./testQueue.core.js";
+export type { RecordedJob, TestQueue } from "./testQueue.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/testQueue/index.js

@@ -1,7 +1,7 @@
 /**
  * Test queue helpers.
  *
- * InMemoryQueue with recording and assertion support.
+ * A `Queue` backed by a real InMemoryQueue that records every job added.
  */
 export { createTestQueue } from "./testQueue.core.js";
 //# sourceMappingURL=index.js.map

package/dist/testQueue/testQueue.core.d.ts

@@ -1,46 +1,27 @@
 /**
  * Test queue helpers.
  *
- * Wraps the real InMemoryQueue with recording and assertion support.
+ * A real InMemoryQueue that records every job added to it.
  */
-import { InMemoryQueue } from "@zudojs/queue";
-import type { Job, QueueName, QueueOptions, QueueStats, JobOptions } from "@zudojs/queue";
+import type { QueueName, QueueOptions } from "@zudojs/queue";
+import type { TestQueue } from "./testQueue.type.js";
+export type { RecordedJob, TestQueue } from "./testQueue.type.js";
 /**
- * A recorded job addition.
- */
-export interface RecordedJob<TData = unknown> {
-    readonly job: Job<TData>;
-    readonly timestamp: Date;
-}
-/**
- * A test queue with recording capabilities.
+ * Creates a test queue that records every job added to it.
+ *
+ * @param name - Queue name.
+ * @param options - Queue options.
+ * @returns A TestQueue, which is itself a `Queue`.
+ *
+ * @example
+ * ```ts
+ * const reminders = createTestQueue<{ taskId: number }>(createQueueName("reminders"));
+ *
+ * await scheduler.remind(reminders, 7); // takes a Queue, calls add(...)
+ *
+ * expect(reminders.findByName("remind")).toHaveLength(1);
+ * await reminders.close();
+ * ```
  */
-export interface TestQueue<TData = unknown> {
-    readonly queue: InMemoryQueue<TData>;
-    /**
-     * All recorded jobs.
-     */
-    readonly jobs: readonly RecordedJob<TData>[];
-    /**
-     * Add a job and record it.
-     */
-    add: (name: string, data: TData, options?: JobOptions) => Promise<Job<TData>>;
-    /**
-     * Find jobs by name.
-     */
-    findByName: (name: string) => readonly RecordedJob<TData>[];
-    /**
-     * Get all job states.
-     */
-    getStats: () => Promise<QueueStats>;
-    /**
-     * Clear recorded jobs.
-     */
-    clear: () => void;
-    /**
-     * Close the queue.
-     */
-    close: () => Promise<void>;
-}
 export declare function createTestQueue<TData = unknown>(name: QueueName, options?: QueueOptions): TestQueue<TData>;
 //# sourceMappingURL=testQueue.core.d.ts.map

package/dist/testQueue/testQueue.core.js

@@ -1,38 +1,42 @@
 /**
  * Test queue helpers.
  *
- * Wraps the real InMemoryQueue with recording and assertion support.
+ * A real InMemoryQueue that records every job added to it.
+ */
+import { InMemoryQueue } from "@zudojs/queue";
+import { RecordingQueueView } from "./testQueue.view.js";
+/**
+ * Creates a test queue that records every job added to it.
+ *
+ * @param name - Queue name.
+ * @param options - Queue options.
+ * @returns A TestQueue, which is itself a `Queue`.
+ *
+ * @example
+ * ```ts
+ * const reminders = createTestQueue<{ taskId: number }>(createQueueName("reminders"));
+ *
+ * await scheduler.remind(reminders, 7); // takes a Queue, calls add(...)
+ *
+ * expect(reminders.findByName("remind")).toHaveLength(1);
+ * await reminders.close();
+ * ```
  */
-import { createInMemoryQueue, InMemoryQueue } from "@zudojs/queue";
 export function createTestQueue(name, options) {
-    const queue = createInMemoryQueue(name, options);
-    const recordedJobs = [];
-    const add = async (jobName, data, jobOptions) => {
-        const job = await queue.add(jobName, data, jobOptions);
-        recordedJobs.push({
-            job,
-            timestamp: new Date(),
-        });
-        return job;
-    };
-    const findByName = (name) => recordedJobs.filter((r) => r.job.name === name);
-    const getStats = async () => queue.getStats();
-    const clear = () => {
-        recordedJobs.length = 0;
-    };
-    const close = async () => {
-        await queue.close();
-    };
-    return {
-        queue,
-        get jobs() {
-            return [...recordedJobs];
+    const queue = new InMemoryQueue(name, options);
+    const recorded = [];
+    // Recorded on the queue instance itself, so `testQueue.queue.add(...)`,
+    // and code that was handed `queue`, record too.
+    const add = queue.add.bind(queue);
+    Object.defineProperty(queue, "add", {
+        configurable: true,
+        writable: true,
+        value: async (jobName, data, jobOptions) => {
+            const job = await add(jobName, data, jobOptions);
+            recorded.push(Object.freeze({ job, timestamp: new Date() }));
+            return job;
         },
-        add,
-        findByName,
-        getStats,
-        clear,
-        close,
-    };
+    });
+    return new RecordingQueueView(queue, recorded);
 }
 //# sourceMappingURL=testQueue.core.js.map

package/dist/testQueue/testQueue.type.d.ts

@@ -0,0 +1,30 @@
+import type { InMemoryQueue, Job, Queue } from "@zudojs/queue";
+/**
+ * A recorded job addition.
+ */
+export interface RecordedJob<TData = unknown> {
+    readonly job: Job<TData>;
+    readonly timestamp: Date;
+}
+/**
+ * A test queue: a `Queue` (so it can be handed to any code that takes
+ * one) backed by a real `InMemoryQueue`, recording every job added to it,
+ * whether `add` is called on the test queue or on the underlying `queue`.
+ */
+export interface TestQueue<TData = unknown> extends Queue<TData> {
+    /** The underlying `InMemoryQueue`; `add` on it records too. */
+    readonly queue: InMemoryQueue<TData>;
+    /**
+     * All recorded jobs, oldest first.
+     */
+    readonly jobs: readonly RecordedJob<TData>[];
+    /**
+     * Find jobs by name.
+     */
+    findByName(name: string): readonly RecordedJob<TData>[];
+    /**
+     * Clear recorded jobs.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=testQueue.type.d.ts.map

package/dist/testQueue/testQueue.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=testQueue.type.js.map

package/dist/testQueue/testQueue.view.d.ts

@@ -0,0 +1,37 @@
+import type { DeadLetterJob, InMemoryQueue, Job, JobId, JobOptions, Processor, Queue, QueueEventEmitter, QueueName, QueueStats } from "@zudojs/queue";
+import type { RecordedJob, TestQueue } from "./testQueue.type.js";
+type RunJobOptions<TData> = Parameters<Queue<TData>["runJob"]>[1];
+/**
+ * The `TestQueue` handed to tests: every `Queue` member delegates to the
+ * underlying `InMemoryQueue` (whose `add` records), plus the recording
+ * accessors. Members are arrow functions, so they survive destructuring.
+ */
+export declare class RecordingQueueView<TData> implements TestQueue<TData> {
+    readonly queue: InMemoryQueue<TData>;
+    private readonly recorded;
+    constructor(queue: InMemoryQueue<TData>, recorded: RecordedJob<TData>[]);
+    get name(): QueueName;
+    get events(): QueueEventEmitter;
+    get jobs(): readonly RecordedJob<TData>[];
+    readonly findByName: (name: string) => readonly RecordedJob<TData>[];
+    readonly clear: () => void;
+    readonly add: (name: string, data: TData, options?: JobOptions) => Promise<Job<TData>>;
+    readonly process: (name: string, processor: Processor<TData>) => void;
+    readonly getJob: (jobId: JobId) => Promise<Job<TData> | null>;
+    readonly getNextJob: () => Promise<Job<TData> | null>;
+    readonly claimNextJob: () => Promise<Job<TData> | null>;
+    readonly releaseJob: (jobId: JobId) => Promise<boolean>;
+    readonly runJob: (job: Job<TData>, options?: RunJobOptions<TData>) => Promise<void>;
+    readonly getProcessor: (name: string) => Processor<TData> | undefined;
+    readonly getStats: () => Promise<QueueStats>;
+    readonly pause: () => Promise<void>;
+    readonly resume: () => Promise<void>;
+    readonly isPaused: () => boolean;
+    readonly isDisposed: () => boolean;
+    readonly getDeadLetterJobs: () => Promise<readonly DeadLetterJob<TData>[]>;
+    readonly close: () => Promise<void>;
+    readonly onJobReady: (listener: () => void) => (() => void);
+    readonly setAutoProcess: (enabled: boolean) => void;
+}
+export {};
+//# sourceMappingURL=testQueue.view.d.ts.map

package/dist/testQueue/testQueue.view.js

@@ -0,0 +1,44 @@
+/**
+ * The `TestQueue` handed to tests: every `Queue` member delegates to the
+ * underlying `InMemoryQueue` (whose `add` records), plus the recording
+ * accessors. Members are arrow functions, so they survive destructuring.
+ */
+export class RecordingQueueView {
+    queue;
+    recorded;
+    constructor(queue, recorded) {
+        this.queue = queue;
+        this.recorded = recorded;
+    }
+    get name() {
+        return this.queue.name;
+    }
+    get events() {
+        return this.queue.events;
+    }
+    get jobs() {
+        return [...this.recorded];
+    }
+    findByName = (name) => this.recorded.filter((entry) => entry.job.name === name);
+    clear = () => {
+        this.recorded.length = 0;
+    };
+    add = (name, data, options) => this.queue.add(name, data, options);
+    process = (name, processor) => this.queue.process(name, processor);
+    getJob = (jobId) => this.queue.getJob(jobId);
+    getNextJob = () => this.queue.getNextJob();
+    claimNextJob = () => this.queue.claimNextJob();
+    releaseJob = (jobId) => this.queue.releaseJob(jobId);
+    runJob = (job, options) => this.queue.runJob(job, options);
+    getProcessor = (name) => this.queue.getProcessor(name);
+    getStats = () => this.queue.getStats();
+    pause = () => this.queue.pause();
+    resume = () => this.queue.resume();
+    isPaused = () => this.queue.isPaused();
+    isDisposed = () => this.queue.isDisposed();
+    getDeadLetterJobs = () => this.queue.getDeadLetterJobs();
+    close = () => this.queue.close();
+    onJobReady = (listener) => this.queue.onJobReady(listener);
+    setAutoProcess = (enabled) => this.queue.setAutoProcess(enabled);
+}
+//# sourceMappingURL=testQueue.view.js.map

package/dist/testStorage/testStorageMemory.core.d.ts

@@ -22,9 +22,20 @@ export declare class InMemoryTestStorage {
      * test needs to distinguish.
      */
     get<T = unknown>(key: string): T | null;
-    /** Set a value with optional TTL in milliseconds. */
+    /**
+     * Set a value with optional TTL in milliseconds.
+     *
+     * Only an omitted (or `undefined`) TTL means "never expires". A TTL of `0`
+     * is a real deadline of now, so the entry is already expired on the next
+     * read — a cache test writing `0` to mean "already stale" gets that.
+     * `Infinity` never expires, a negative TTL is already expired, and `NaN`
+     * throws (it used to produce an invalid deadline that never expired).
+     */
     set(key: string, value: unknown, ttlMs?: number): void;
-    /** Delete a value by key. Returns true if deleted. */
+    /**
+     * Delete a value by key. Returns true if a live value was deleted; an
+     * expired entry counts as absent, matching `has()`.
+     */
     delete(key: string): boolean;
     /** Check if a key exists and is not expired, whatever its value. */
     has(key: string): boolean;

package/dist/testStorage/testStorageMemory.core.js

@@ -36,14 +36,30 @@ export class InMemoryTestStorage {
             return null;
         return (entry.value ?? null);
     }
-    /** Set a value with optional TTL in milliseconds. */
+    /**
+     * Set a value with optional TTL in milliseconds.
+     *
+     * Only an omitted (or `undefined`) TTL means "never expires". A TTL of `0`
+     * is a real deadline of now, so the entry is already expired on the next
+     * read — a cache test writing `0` to mean "already stale" gets that.
+     * `Infinity` never expires, a negative TTL is already expired, and `NaN`
+     * throws (it used to produce an invalid deadline that never expired).
+     */
     set(key, value, ttlMs) {
-        const expiresAt = ttlMs ? new Date(Date.now() + ttlMs) : null;
+        if (ttlMs !== undefined && Number.isNaN(ttlMs)) {
+            throw new RangeError(`TTL for "${key}" is NaN; pass a number of milliseconds or omit it.`);
+        }
+        const expiresAt = ttlMs === undefined || ttlMs === Infinity
+            ? null
+            : new Date(Math.max(0, Date.now() + ttlMs));
         this.store.set(key, { value, expiresAt });
     }
-    /** Delete a value by key. Returns true if deleted. */
+    /**
+     * Delete a value by key. Returns true if a live value was deleted; an
+     * expired entry counts as absent, matching `has()`.
+     */
     delete(key) {
-        return this.store.delete(key);
+        return this.live(key) !== undefined && this.store.delete(key);
     }
     /** Check if a key exists and is not expired, whatever its value. */
     has(key) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/testing",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Test helpers, fixtures, mocks, and utilities for testing Zudojs applications.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,24 +19,24 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/config": "1.1.0",
-    "@zudojs/constants": "1.1.0",
-    "@zudojs/container": "1.1.1",
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/events": "1.1.0",
-    "@zudojs/http": "1.2.0",
-    "@zudojs/logger": "1.2.0",
-    "@zudojs/messaging": "1.0.2",
-    "@zudojs/middleware": "1.0.2",
-    "@zudojs/queue": "1.2.0",
-    "@zudojs/security": "1.1.0",
-    "@zudojs/serialization": "1.1.0",
-    "@zudojs/storage": "1.1.1",
-    "@zudojs/types": "1.1.0"
+    "@zudojs/config": "1.3.0",
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/container": "1.2.0",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/events": "1.3.0",
+    "@zudojs/http": "1.4.0",
+    "@zudojs/logger": "1.4.0",
+    "@zudojs/messaging": "1.2.0",
+    "@zudojs/middleware": "1.1.0",
+    "@zudojs/queue": "1.4.0",
+    "@zudojs/security": "1.3.0",
+    "@zudojs/serialization": "1.2.0",
+    "@zudojs/storage": "1.2.0",
+    "@zudojs/types": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -56,7 +56,7 @@
     "fixtures",
     "vitest"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-testing",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },