@go-go-scope/testing 2.0.0

package/README.md

@@ -0,0 +1,70 @@
+# @go-go-scope/testing
+
+Testing utilities for go-go-scope - mocks, spies, time control, and test helpers.
+
+## Installation
+
+```bash
+npm install -D @go-go-scope/testing
+```
+
+## Usage
+
+### Mock Scope
+
+```typescript
+import { createMockScope } from '@go-go-scope/testing'
+
+const s = createMockScope({
+  autoAdvanceTimers: true,
+  deterministic: true
+})
+
+const [err, result] = await s.task(() => Promise.resolve('done'))
+expect(result).toBe('done')
+```
+
+### Spies
+
+```typescript
+import { createSpy } from '@go-go-scope/testing'
+
+const spy = createSpy().mockReturnValue('mocked')
+const result = spy()
+expect(result).toBe('mocked')
+expect(spy.wasCalled()).toBe(true)
+```
+
+### Time Control
+
+```typescript
+import { createTimeTravelController } from '@go-go-scope/testing'
+
+const time = createTimeTravelController()
+
+// Schedule operations
+const results: number[] = []
+time.setTimeout(() => results.push(1), 100)
+time.setTimeout(() => results.push(2), 200)
+
+// Jump to specific time
+time.jumpTo(150)
+expect(results).toEqual([1]) // Only first timer fired
+```
+
+### Mock Channels
+
+```typescript
+import { createMockChannel } from '@go-go-scope/testing'
+
+const mockCh = createMockChannel<number>()
+mockCh.setReceiveValues([1, 2, 3])
+
+const ch = mockCh.channel
+const value = await ch.receive()
+expect(value).toBe(1)
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,422 @@
+import * as go_go_scope from 'go-go-scope';
+import { Scope, TaskOptions } from 'go-go-scope';
+
+/**
+ * Time travel testing utilities for go-go-scope
+ *
+ * Allows controlling time in tests for deterministic timeout and retry testing.
+ */
+/**
+ * A controller for manipulating time in tests.
+ * Use this to fast-forward through delays and timeouts without waiting.
+ *
+ * @example
+ * ```typescript
+ * const time = createTimeController()
+ *
+ * await using s = scope({ timeout: 5000 })
+ * const taskPromise = s.task(() => longOperation(), { timeout: 10000 })
+ *
+ * // Fast forward 10 seconds instantly
+ * time.advance(10000)
+ *
+ * // Task will have timed out
+ * const [err] = await taskPromise
+ * expect(err?.message).toContain('timeout')
+ * ```
+ */
+interface TimeController {
+    /** Current simulated time in milliseconds */
+    readonly now: number;
+    /**
+     * Advance time by the specified amount.
+     * Any pending timeouts scheduled within this time window will fire.
+     */
+    advance(ms: number): void;
+    /**
+     * Jump to a specific absolute time.
+     * All pending timeouts up to that point will fire.
+     */
+    jumpTo(timestamp: number): void;
+    /**
+     * Run all pending timeouts immediately.
+     */
+    runAll(): void;
+    /**
+     * Reset time to 0 and clear all pending timeouts.
+     */
+    reset(): void;
+    /**
+     * Create a Promise that resolves after the specified delay.
+     * Respects time control.
+     */
+    delay(ms: number): Promise<void>;
+    /**
+     * Install this controller as the global time source.
+     * Call `uninstall()` to restore original behavior.
+     */
+    install(): void;
+    /**
+     * Uninstall this controller and restore original global time.
+     */
+    uninstall(): void;
+}
+/**
+ * Create a time controller for testing.
+ *
+ * @example
+ * ```typescript
+ * describe('with time control', () => {
+ *   const time = createTimeController()
+ *
+ *   afterEach(() => {
+ *     time.reset()
+ *   })
+ *
+ *   test('timeouts work', async () => {
+ *     await using s = scope({ timeout: 5000 })
+ *
+ *     // Fast forward past timeout
+ *     time.advance(5001)
+ *
+ *     expect(s.signal.aborted).toBe(true)
+ *   })
+ * })
+ * ```
+ */
+declare function createTimeController(): TimeController;
+/**
+ * Test helper that creates a scope with time control enabled.
+ * Useful for testing timeout and retry logic.
+ *
+ * @example
+ * ```typescript
+ * test('task retries', async () => {
+ *   const { scope, time } = createTestScope({ timeout: 5000 })
+ *
+ *   let attempts = 0
+ *   const task = scope.task(() => {
+ *     attempts++
+ *     if (attempts < 3) throw new Error('fail')
+ *     return 'success'
+ *   }, { retry: { maxRetries: 3, delay: 1000 } })
+ *
+ *   // Fast forward through retries
+ *   time.advance(1000) // First retry
+ *   time.advance(1000) // Second retry
+ *
+ *   const [err, result] = await task
+ *   expect(result).toBe('success')
+ * })
+ * ```
+ */
+declare function createTestScope(options?: {
+    timeout?: number;
+    concurrency?: number;
+}): Promise<{
+    scope: go_go_scope.Scope;
+    time: TimeController;
+}>;
+
+/**
+ * Test utilities for go-go-scope
+ *
+ * Provides helper functions and mocks for testing code that uses go-go-scope.
+ *
+ * @example
+ * ```typescript
+ * import { createMockScope } from '@go-go-scope/testing'
+ *
+ * const s = createMockScope({
+ *   autoAdvanceTimers: true,
+ *   deterministic: true
+ * })
+ *
+ * await s.task(() => fetchData())
+ * ```
+ */
+
+/**
+ * Options for creating a mock scope
+ */
+interface MockScopeOptions {
+    /** Automatically advance timers for async operations */
+    autoAdvanceTimers?: boolean;
+    /** Use deterministic random seeds for reproducible tests */
+    deterministic?: boolean;
+    /** Pre-configured services to inject */
+    services?: Record<string, unknown>;
+    /** Services to override (for mocking existing services) */
+    overrides?: Record<string, unknown>;
+    /** Initial aborted state */
+    aborted?: boolean;
+    /** Abort reason if aborted */
+    abortReason?: unknown;
+}
+/**
+ * Task call record for tracking
+ */
+interface TaskCall {
+    fn: (ctx: {
+        services: Record<string, never>;
+        signal: AbortSignal;
+    }) => Promise<unknown>;
+    options?: TaskOptions;
+}
+/**
+ * Extended Scope with mock capabilities
+ */
+interface MockScope extends Scope<Record<string, never>> {
+    /** Record of task calls made to this scope */
+    taskCalls: TaskCall[];
+    /** Options used to create this mock scope */
+    options: MockScopeOptions;
+    /** Abort the scope with optional reason */
+    abort: (reason?: unknown) => void;
+    /** Get all recorded task calls */
+    getTaskCalls: () => TaskCall[];
+    /** Clear recorded task calls */
+    clearTaskCalls: () => void;
+    /** Override a service with a mock implementation */
+    mockService: <K extends string, T>(key: K, value: T) => MockScope;
+}
+/**
+ * Creates a mock scope for testing purposes.
+ *
+ * The mock scope provides:
+ * - Controlled timer advancement
+ * - Deterministic execution
+ * - Easy cancellation testing
+ * - Spy capabilities on task execution
+ *
+ * @example
+ * ```typescript
+ * import { createMockScope } from '@go-go-scope/testing'
+ * import { describe, test, expect } from 'vitest'
+ *
+ * describe('my feature', () => {
+ *   test('should complete task', async () => {
+ *     const s = createMockScope()
+ *
+ *     const [err, result] = await s.task(() => Promise.resolve('done'))
+ *
+ *     expect(err).toBeUndefined()
+ *     expect(result).toBe('done')
+ *   })
+ * })
+ * ```
+ */
+declare function createMockScope(options?: MockScopeOptions): MockScope;
+/**
+ * Creates a controlled timer environment for testing async operations.
+ * Useful for testing timeout and retry logic.
+ *
+ * @example
+ * ```typescript
+ * import { createControlledTimer } from '@go-go-scope/testing'
+ *
+ * const timer = createControlledTimer()
+ *
+ * // In your test
+ * timer.advance(1000) // Advance by 1 second
+ * await timer.flush() // Flush all pending timers
+ * ```
+ */
+declare function createControlledTimer(): {
+    /** Current simulated time */
+    readonly currentTime: number;
+    /** Schedule a callback to run after delay */
+    setTimeout(callback: () => void, delay: number): number;
+    /** Cancel a scheduled callback */
+    clearTimeout(id: number): void;
+    /** Advance time by specified milliseconds */
+    advance(ms: number): void;
+    /** Run all pending timers immediately */
+    flush(): Promise<void>;
+    /** Reset all timers */
+    reset(): void;
+};
+/**
+ * Waits for all promises in the scope to settle.
+ * Useful for testing async operations.
+ *
+ * @example
+ * ```typescript
+ * import { flushPromises } from '@go-go-scope/testing'
+ *
+ * test('async operation', async () => {
+ *   const promise = s.task(async () => {
+ *     await delay(100)
+ *     return 'done'
+ *   })
+ *
+ *   await flushPromises()
+ *
+ *   const [err, result] = await promise
+ *   expect(result).toBe('done')
+ * })
+ * ```
+ */
+declare function flushPromises(): Promise<void>;
+/**
+ * Creates a spy function for testing.
+ * Tracks calls and can return mock values.
+ *
+ * @example
+ * ```typescript
+ * import { createSpy } from '@go-go-scope/testing'
+ *
+ * const spy = createSpy().mockReturnValue('mocked')
+ *
+ * const result = spy()
+ * expect(result).toBe('mocked')
+ * expect(spy).toHaveBeenCalledTimes(1)
+ * ```
+ */
+interface Spy<TArgs extends unknown[], TReturn> {
+    (...args: TArgs): TReturn;
+    calls: {
+        args: TArgs;
+        result: TReturn;
+    }[];
+    mockImplementation: (fn: (...args: TArgs) => TReturn) => Spy<TArgs, TReturn>;
+    mockReturnValue: (value: TReturn) => Spy<TArgs, TReturn>;
+    mockReset: () => Spy<TArgs, TReturn>;
+    getCalls: () => {
+        args: TArgs;
+        result: TReturn;
+    }[];
+    wasCalled: () => boolean;
+    wasCalledWith: (...expectedArgs: TArgs) => boolean;
+}
+declare function createSpy<TArgs extends unknown[], TReturn>(): Spy<TArgs, TReturn>;
+/**
+ * Asserts that a scope has been properly disposed.
+ * Checks that all resources are cleaned up.
+ *
+ * @example
+ * ```typescript
+ * import { assertScopeDisposed } from '@go-go-scope/testing'
+ *
+ * test('should dispose properly', async () => {
+ *   const s = scope()
+ *   s.task(() => doSomething())
+ *
+ *   await assertScopeDisposed(s)
+ * })
+ * ```
+ */
+declare function assertScopeDisposed(scope: Scope): Promise<void>;
+/**
+ * Mock channel for testing.
+ * Provides fine-grained control over channel behavior.
+ */
+interface MockChannel<T> {
+    /** The channel instance */
+    channel: {
+        send: (value: T) => Promise<boolean>;
+        receive: () => Promise<T | undefined>;
+        close: () => void;
+        [Symbol.asyncIterator]: () => AsyncIterator<T>;
+    };
+    /** Pre-configured values to be received */
+    mockReceiveValues: T[];
+    /** Record of sent values */
+    sentValues: T[];
+    /** Whether the channel is closed */
+    isClosed: boolean;
+    /** Set values to be received */
+    setReceiveValues: (values: T[]) => void;
+    /** Simulate receiving a value */
+    mockReceive: (value: T) => void;
+    /** Get all sent values */
+    getSentValues: () => T[];
+    /** Clear sent values */
+    clearSentValues: () => void;
+    /** Close the mock channel */
+    close: () => void;
+    /** Reset to initial state */
+    reset: () => void;
+}
+/**
+ * Creates a mock channel for testing.
+ * Useful for testing code that uses channels without actual async operations.
+ *
+ * @example
+ * ```typescript
+ * import { createMockChannel } from '@go-go-scope/testing'
+ *
+ * test('channel communication', async () => {
+ *   const mockCh = createMockChannel<number>()
+ *   mockCh.setReceiveValues([1, 2, 3])
+ *
+ *   const ch = mockCh.channel
+ *   const value = await ch.receive()
+ *   expect(value).toBe(1)
+ * })
+ * ```
+ */
+declare function createMockChannel<T>(): MockChannel<T>;
+/**
+ * Time travel controller for deterministic testing of time-based operations.
+ * More powerful than createControlledTimer - allows jumping to specific times,
+ * rewinding, and inspecting the timeline.
+ *
+ * @example
+ * ```typescript
+ * import { createTimeTravelController } from '@go-go-scope/testing'
+ *
+ * test('time-based operations', async () => {
+ *   const time = createTimeTravelController()
+ *
+ *   // Schedule operations
+ *   const results: number[] = []
+ *   time.setTimeout(() => results.push(1), 100)
+ *   time.setTimeout(() => results.push(2), 200)
+ *
+ *   // Jump to specific time
+ *   time.jumpTo(150)
+ *   expect(results).toEqual([1]) // Only first timer fired
+ *
+ *   // Continue to end
+ *   time.advance(100)
+ *   expect(results).toEqual([1, 2])
+ * })
+ * ```
+ */
+declare function createTimeTravelController(): {
+    /** Current simulated time in milliseconds */
+    readonly now: number;
+    /** Get the event timeline (sorted by time) */
+    readonly timeline: Array<{
+        id: number;
+        time: number;
+        description?: string;
+    }>;
+    /** Get the execution history */
+    readonly history: {
+        time: number;
+        action: string;
+    }[];
+    /** Schedule a callback to run after delay */
+    setTimeout(callback: () => void, delay: number, description?: string): number;
+    /** Cancel a scheduled callback */
+    clearTimeout(id: number): boolean;
+    /** Set an interval that repeats */
+    setInterval(callback: () => void, delay: number, description?: string): number;
+    /** Advance time by specified milliseconds */
+    advance(ms: number): void;
+    /** Jump to a specific absolute time */
+    jumpTo(targetTime: number): void;
+    /** Get the next scheduled event time, or Infinity if none */
+    nextEventTime(): number;
+    /** Run all events until no more remain */
+    runAll(): void;
+    /** Reset to initial state */
+    reset(): void;
+    /** Print the timeline for debugging */
+    printTimeline(): void;
+};
+
+export { assertScopeDisposed, createControlledTimer, createMockChannel, createMockScope, createSpy, createTestScope, createTimeController, createTimeTravelController, flushPromises };
+export type { MockChannel, MockScope, MockScopeOptions, Spy, TaskCall };

package/dist/index.mjs

@@ -0,0 +1,442 @@
+import { Scope } from 'go-go-scope';
+
+function createTimeController() {
+  let currentTime = 0;
+  const pendingTimeouts = [];
+  let nextId = 1;
+  let originalDateNow;
+  let originalSetTimeout;
+  let originalClearTimeout;
+  let installed = false;
+  const processTimeouts = (upToTime) => {
+    pendingTimeouts.sort((a, b) => a.time - b.time);
+    while (pendingTimeouts.length > 0) {
+      const next = pendingTimeouts[0];
+      if (!next || next.time > upToTime) break;
+      pendingTimeouts.shift();
+      currentTime = next.time;
+      next.callback();
+    }
+  };
+  return {
+    get now() {
+      return currentTime;
+    },
+    advance(ms) {
+      const targetTime = currentTime + ms;
+      processTimeouts(targetTime);
+      currentTime = targetTime;
+    },
+    jumpTo(timestamp) {
+      if (timestamp < currentTime) {
+        throw new Error(
+          `Cannot jump backwards in time: ${timestamp} < ${currentTime}`
+        );
+      }
+      processTimeouts(timestamp);
+      currentTime = timestamp;
+    },
+    runAll() {
+      if (pendingTimeouts.length === 0) return;
+      pendingTimeouts.sort((a, b) => a.time - b.time);
+      const lastTimeout = pendingTimeouts.at(-1);
+      if (lastTimeout) {
+        processTimeouts(lastTimeout.time);
+      }
+    },
+    reset() {
+      pendingTimeouts.length = 0;
+      currentTime = 0;
+      nextId = 1;
+    },
+    delay(ms) {
+      return new Promise((resolve) => {
+        const id = nextId++;
+        pendingTimeouts.push({
+          id,
+          callback: resolve,
+          time: currentTime + ms
+        });
+      });
+    },
+    install() {
+      if (installed) return;
+      installed = true;
+      originalDateNow = Date.now;
+      originalSetTimeout = globalThis.setTimeout;
+      originalClearTimeout = globalThis.clearTimeout;
+      Date.now = () => currentTime;
+      globalThis.setTimeout = (callback, delay = 0) => {
+        const id = nextId++;
+        pendingTimeouts.push({
+          id,
+          callback,
+          time: currentTime + delay
+        });
+        return id;
+      };
+      globalThis.clearTimeout = (id) => {
+        const index = pendingTimeouts.findIndex(
+          (t) => t.id === id
+        );
+        if (index !== -1) {
+          pendingTimeouts.splice(index, 1);
+        }
+      };
+    },
+    uninstall() {
+      if (!installed) return;
+      installed = false;
+      if (originalDateNow) Date.now = originalDateNow;
+      if (originalSetTimeout) globalThis.setTimeout = originalSetTimeout;
+      if (originalClearTimeout) globalThis.clearTimeout = originalClearTimeout;
+    }
+  };
+}
+async function createTestScope(options) {
+  const time = createTimeController();
+  time.install();
+  const { scope } = await import('go-go-scope');
+  const s = scope(options);
+  return { scope: s, time };
+}
+
+function createMockScope(options = {}) {
+  const scopeOptions = {
+    name: "mock-scope"
+  };
+  const baseScope = new Scope(scopeOptions);
+  const mockScope = baseScope;
+  mockScope.taskCalls = [];
+  mockScope.options = options;
+  const originalTask = baseScope.task.bind(baseScope);
+  mockScope.task = (fn, taskOptions) => {
+    mockScope.taskCalls.push({ fn, options: taskOptions });
+    return originalTask(fn, taskOptions);
+  };
+  mockScope.abort = (reason) => {
+    baseScope.abortController.abort(reason);
+  };
+  mockScope.getTaskCalls = function() {
+    return this.taskCalls;
+  };
+  mockScope.clearTaskCalls = function() {
+    this.taskCalls = [];
+  };
+  if (options.services) {
+    for (const [key, value] of Object.entries(options.services)) {
+      mockScope[key] = value;
+    }
+  }
+  if (options.overrides) {
+    for (const [key, value] of Object.entries(options.overrides)) {
+      mockScope[key] = value;
+    }
+  }
+  mockScope.mockService = function(key, value) {
+    this[key] = value;
+    return this;
+  };
+  if (options.aborted) {
+    mockScope.abort(options.abortReason);
+  }
+  return mockScope;
+}
+function createControlledTimer() {
+  let currentTime = 0;
+  const pendingTimers = [];
+  let nextId = 1;
+  return {
+    /** Current simulated time */
+    get currentTime() {
+      return currentTime;
+    },
+    /** Schedule a callback to run after delay */
+    setTimeout(callback, delay) {
+      const id = nextId++;
+      pendingTimers.push({
+        id,
+        callback,
+        time: currentTime + delay
+      });
+      pendingTimers.sort((a, b) => a.time - b.time);
+      return id;
+    },
+    /** Cancel a scheduled callback */
+    clearTimeout(id) {
+      const index = pendingTimers.findIndex((t) => t.id === id);
+      if (index !== -1) {
+        pendingTimers.splice(index, 1);
+      }
+    },
+    /** Advance time by specified milliseconds */
+    advance(ms) {
+      const targetTime = currentTime + ms;
+      while (pendingTimers.length > 0) {
+        const timer = pendingTimers[0];
+        if (!timer || timer.time > targetTime) break;
+        pendingTimers.shift();
+        currentTime = timer.time;
+        timer.callback();
+      }
+      currentTime = targetTime;
+    },
+    /** Run all pending timers immediately */
+    flush() {
+      while (pendingTimers.length > 0) {
+        const timer = pendingTimers.shift();
+        if (timer) {
+          currentTime = timer.time;
+          timer.callback();
+        }
+      }
+      return Promise.resolve();
+    },
+    /** Reset all timers */
+    reset() {
+      pendingTimers.length = 0;
+      currentTime = 0;
+      nextId = 1;
+    }
+  };
+}
+async function flushPromises() {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+function createSpy() {
+  const calls = [];
+  let mockImplementation;
+  let mockReturnValue;
+  let returnValueSet = false;
+  const spy = function(...args) {
+    let result;
+    if (mockImplementation) {
+      result = mockImplementation(...args);
+    } else if (returnValueSet) {
+      result = mockReturnValue;
+    } else {
+      result = void 0;
+    }
+    calls.push({ args, result });
+    return result;
+  };
+  spy.calls = calls;
+  spy.mockImplementation = (fn) => {
+    mockImplementation = fn;
+    return spy;
+  };
+  spy.mockReturnValue = (value) => {
+    mockReturnValue = value;
+    returnValueSet = true;
+    return spy;
+  };
+  spy.mockReset = () => {
+    calls.length = 0;
+    mockImplementation = void 0;
+    mockReturnValue = void 0;
+    returnValueSet = false;
+    return spy;
+  };
+  spy.getCalls = () => calls;
+  spy.wasCalled = () => calls.length > 0;
+  spy.wasCalledWith = (...expectedArgs) => calls.some(
+    (call) => JSON.stringify(call.args) === JSON.stringify(expectedArgs)
+  );
+  return spy;
+}
+async function assertScopeDisposed(scope) {
+  await scope[Symbol.asyncDispose]();
+  if (!scope.signal.aborted) {
+    throw new Error("Scope signal was not aborted after disposal");
+  }
+  if (!scope.isDisposed) {
+    throw new Error("Scope did not report as disposed");
+  }
+}
+function createMockChannel() {
+  const sentValues = [];
+  let receiveValues = [];
+  let receiveIndex = 0;
+  let closed = false;
+  const mockChannel = {
+    channel: {
+      send: async (value) => {
+        if (closed) return false;
+        sentValues.push(value);
+        return true;
+      },
+      receive: async () => {
+        if (closed) return void 0;
+        if (receiveIndex < receiveValues.length) {
+          return receiveValues[receiveIndex++];
+        }
+        return void 0;
+      },
+      close: () => {
+        closed = true;
+      },
+      [Symbol.asyncIterator]: () => ({
+        async next() {
+          if (closed || receiveIndex >= receiveValues.length) {
+            return { done: true, value: void 0 };
+          }
+          return { done: false, value: receiveValues[receiveIndex++] };
+        },
+        async return() {
+          return { done: true, value: void 0 };
+        }
+      })
+    },
+    mockReceiveValues: receiveValues,
+    get sentValues() {
+      return sentValues;
+    },
+    get isClosed() {
+      return closed;
+    },
+    setReceiveValues: (values) => {
+      receiveValues = values;
+      receiveIndex = 0;
+    },
+    mockReceive: (value) => {
+      receiveValues.push(value);
+    },
+    getSentValues: () => [...sentValues],
+    clearSentValues: () => {
+      sentValues.length = 0;
+    },
+    close: () => {
+      closed = true;
+    },
+    reset: () => {
+      sentValues.length = 0;
+      receiveValues = [];
+      receiveIndex = 0;
+      closed = false;
+    }
+  };
+  return mockChannel;
+}
+function createTimeTravelController() {
+  let currentTime = 0;
+  const timeline = [];
+  const history = [];
+  let nextId = 1;
+  return {
+    /** Current simulated time in milliseconds */
+    get now() {
+      return currentTime;
+    },
+    /** Get the event timeline (sorted by time) */
+    get timeline() {
+      return [...timeline].sort((a, b) => a.time - b.time).map((e) => ({ id: e.id, time: e.time, description: e.description }));
+    },
+    /** Get the execution history */
+    get history() {
+      return [...history];
+    },
+    /** Schedule a callback to run after delay */
+    setTimeout(callback, delay, description) {
+      const id = nextId++;
+      timeline.push({
+        id,
+        time: currentTime + delay,
+        callback,
+        description
+      });
+      return id;
+    },
+    /** Cancel a scheduled callback */
+    clearTimeout(id) {
+      const index = timeline.findIndex((e) => e.id === id);
+      if (index !== -1) {
+        timeline.splice(index, 1);
+        return true;
+      }
+      return false;
+    },
+    /** Set an interval that repeats */
+    setInterval(callback, delay, description) {
+      const id = nextId++;
+      let nextTime = currentTime + delay;
+      const scheduleNext = () => {
+        timeline.push({
+          id,
+          time: nextTime,
+          callback: () => {
+            callback();
+            nextTime += delay;
+            scheduleNext();
+          },
+          description: `${description || "interval"} (repeat)`
+        });
+      };
+      scheduleNext();
+      return id;
+    },
+    /** Advance time by specified milliseconds */
+    advance(ms) {
+      const targetTime = currentTime + ms;
+      this.jumpTo(targetTime);
+    },
+    /** Jump to a specific absolute time */
+    jumpTo(targetTime) {
+      if (targetTime < currentTime) {
+        throw new Error(
+          `Cannot jump backwards from ${currentTime} to ${targetTime}`
+        );
+      }
+      timeline.sort((a, b) => a.time - b.time);
+      while (timeline.length > 0) {
+        const event = timeline[0];
+        if (!event || event.time > targetTime) break;
+        timeline.shift();
+        currentTime = event.time;
+        history.push({
+          time: currentTime,
+          action: event.description || `event-${event.id}`
+        });
+        event.callback();
+      }
+      currentTime = targetTime;
+    },
+    /** Get the next scheduled event time, or Infinity if none */
+    nextEventTime() {
+      if (timeline.length === 0) return Infinity;
+      timeline.sort((a, b) => a.time - b.time);
+      return timeline[0]?.time ?? Infinity;
+    },
+    /** Run all events until no more remain */
+    runAll() {
+      while (timeline.length > 0) {
+        timeline.sort((a, b) => a.time - b.time);
+        const event = timeline.shift();
+        if (event) {
+          currentTime = event.time;
+          history.push({
+            time: currentTime,
+            action: event.description || `event-${event.id}`
+          });
+          event.callback();
+        }
+      }
+    },
+    /** Reset to initial state */
+    reset() {
+      timeline.length = 0;
+      history.length = 0;
+      currentTime = 0;
+      nextId = 1;
+    },
+    /** Print the timeline for debugging */
+    printTimeline() {
+      const sorted = [...timeline].sort((a, b) => a.time - b.time);
+      console.log("Timeline:");
+      sorted.forEach((e) => {
+        console.log(`  ${e.time}ms: ${e.description || `event-${e.id}`}`);
+      });
+    }
+  };
+}
+
+export { assertScopeDisposed, createControlledTimer, createMockChannel, createMockScope, createSpy, createTestScope, createTimeController, createTimeTravelController, flushPromises };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@go-go-scope/testing",
+  "version": "2.0.0",
+  "description": "Testing utilities for go-go-scope - mocks, spies, and time control",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "pkgroll --clean-dist",
+    "lint": "biome check --write src/",
+    "test": "echo 'No tests yet'",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "testing",
+    "mocks",
+    "spies",
+    "go-go-scope",
+    "test-utilities"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "author": "thelinuxlich",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thelinuxlich/go-go-scope.git",
+    "directory": "packages/testing"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "go-go-scope": "workspace:*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@types/node": "^24",
+    "pkgroll": "^2.26.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}