@directive-run/core 0.4.0 → 0.4.2

package/dist/testing.d.cts

@@ -12,8 +12,12 @@ import { p as ModulesMap, q as CreateSystemOptionsNamed, R as Requirement, N as
  */
 
 /**
- * Flush all pending microtasks.
- * Call this after advancing fake timers to ensure all Promise callbacks run.
+ * Flush all pending microtasks by awaiting multiple rounds of `Promise.resolve()`.
+ *
+ * Call this after advancing fake timers to ensure all Promise callbacks
+ * (including nested microtasks) have run before making assertions.
+ *
+ * @returns A promise that resolves after all pending microtasks have been drained.
  *
  * @example
  * ```typescript
@@ -24,15 +28,22 @@ import { p as ModulesMap, q as CreateSystemOptionsNamed, R as Requirement, N as
  * vi.advanceTimersByTime(100); // Advance resolver delay
  * await flushMicrotasks(); // Let resolver complete
  * ```
+ *
+ * @public
  */
 declare function flushMicrotasks(): Promise<void>;
 /**
  * Wait for the system to settle with fake timers enabled.
- * Combines timer advancement with microtask flushing.
  *
- * @param system - The Directive system
- * @param advanceTime - Function to advance fake timers (e.g., vi.advanceTimersByTime)
- * @param options - Configuration options
+ * Repeatedly advances fake timers in discrete steps while flushing microtasks,
+ * until no resolvers remain inflight or the time budget is exhausted.
+ *
+ * @param system - The Directive system to wait on (must expose {@link SystemInspection} via `inspect()`).
+ * @param advanceTime - Function that advances fake timers by a given number of milliseconds (e.g., `vi.advanceTimersByTime`).
+ * @param options - Configuration for total time budget, step size, and iteration limit.
+ * @returns A promise that resolves once the system is idle.
+ *
+ * @throws Error if the system does not settle within the configured time budget.
  *
  * @example
  * ```typescript
@@ -48,6 +59,8 @@ declare function flushMicrotasks(): Promise<void>;
  *
  * expect(system.facts.result).toBe("done");
  * ```
+ *
+ * @public
  */
 declare function settleWithFakeTimers(system: {
     inspect(): SystemInspection;
@@ -59,41 +72,77 @@ declare function settleWithFakeTimers(system: {
     /** Maximum iterations before giving up (default: 1000) */
     maxIterations?: number;
 }): Promise<void>;
+/**
+ * Standalone fake timer controller for tests that do not use Vitest/Jest fake timers.
+ *
+ * @remarks
+ * For most tests, prefer Vitest's `vi.useFakeTimers()` paired with
+ * {@link settleWithFakeTimers} for better integration. Use this interface
+ * only when you need a lightweight, framework-independent timer mock.
+ *
+ * @public
+ */
 interface FakeTimers {
-    /** Advance time by a number of milliseconds */
+    /** Advance time by a number of milliseconds, firing any timers that fall within the window. */
     advance(ms: number): Promise<void>;
-    /** Advance to the next scheduled timer */
+    /** Advance to the next scheduled timer and fire its callback. */
     next(): Promise<void>;
-    /** Run all pending timers */
+    /** Run all pending timers in chronological order. */
     runAll(): Promise<void>;
-    /** Get current fake time */
+    /** Get the current fake time in milliseconds. */
     now(): number;
-    /** Reset to time 0 */
+    /** Reset the clock to time 0 and discard all scheduled timers. */
     reset(): void;
 }
 /**
- * Create standalone fake timers for testing.
- * Note: For most tests, prefer using Vitest's vi.useFakeTimers() with
- * settleWithFakeTimers() for better integration.
+ * Create standalone fake timers for testing without a framework timer mock.
+ *
+ * @remarks
+ * For most tests, prefer Vitest's `vi.useFakeTimers()` paired with
+ * {@link settleWithFakeTimers}. This factory is useful when you need an
+ * isolated timer that does not interfere with global timer state.
+ *
+ * @returns A {@link FakeTimers} controller with `advance`, `next`, `runAll`, `now`, and `reset` methods.
+ *
+ * @example
+ * ```typescript
+ * const timers = createFakeTimers();
+ * // schedule work, then:
+ * await timers.advance(500);
+ * expect(timers.now()).toBe(500);
+ * ```
+ *
+ * @public
  */
 declare function createFakeTimers(): FakeTimers;
-/** Context passed to mock resolver resolve functions */
+/**
+ * Context passed to mock resolver resolve functions.
+ *
+ * @public
+ */
 interface MockResolverContext {
     /** Facts object (use type assertion for specific facts) */
     facts: any;
     /** Abort signal for cancellation */
     signal: AbortSignal;
 }
+/**
+ * Configuration for a simple mock resolver created via {@link createMockResolver}.
+ *
+ * @typeParam R - The requirement type this resolver handles.
+ *
+ * @public
+ */
 interface MockResolverOptions<R extends Requirement = Requirement> {
-    /** Predicate to check if this resolver handles a requirement */
+    /** Predicate to check if this resolver handles a given requirement. */
     requirement?: (req: Requirement) => req is R;
-    /** Mock implementation */
+    /** Mock implementation invoked when the resolver runs. */
     resolve?: (req: R, ctx: MockResolverContext) => void | Promise<void>;
-    /** Delay before resolving (ms) */
+    /** Artificial delay in milliseconds before the resolver completes. */
     delay?: number;
-    /** Simulate an error */
+    /** Error (or message string) to throw, simulating a resolver failure. */
     error?: Error | string;
-    /** Track calls */
+    /** Array that receives every requirement passed to this resolver. */
     calls?: R[];
 }
 /** Internal resolver definition type for mock resolvers */
@@ -102,12 +151,32 @@ interface MockResolverDef {
     resolve: (req: Requirement, ctx: MockResolverContext) => Promise<void>;
 }
 /**
- * Create a mock resolver for testing.
+ * Create a simple mock resolver that matches requirements by type and optionally
+ * records calls, injects delays, or throws errors.
+ *
+ * @param typeOrOptions - A requirement type string, or a full {@link MockResolverOptions} object.
+ * @returns A resolver definition that can be spread into a module's `resolvers` map.
+ *
+ * @example
+ * ```typescript
+ * const calls: Requirement[] = [];
+ * const mock = createMockResolver({ requirement: (r): r is MyReq => r.type === "LOAD", calls });
+ * ```
+ *
+ * @public
  */
 declare function createMockResolver<R extends Requirement = Requirement>(typeOrOptions: string | MockResolverOptions<R>): MockResolverDef;
 /**
  * A mock resolver that captures requirements for manual resolution.
- * Use this when you need fine-grained control over when and how requirements resolve.
+ *
+ * @remarks
+ * Use this when you need fine-grained control over when and how requirements
+ * resolve. Requirements are queued in `pending` and stay unresolved until you
+ * explicitly call `resolve()` or `reject()`.
+ *
+ * @typeParam R - The requirement type this resolver handles.
+ *
+ * @public
  */
 interface MockResolver<R extends Requirement = Requirement> {
     /** All requirements received by this resolver */
@@ -130,8 +199,11 @@ interface MockResolver<R extends Requirement = Requirement> {
     reset(): void;
 }
 /**
- * Create a mock resolver that captures requirements instead of resolving them.
- * This gives you manual control over requirement resolution in tests.
+ * Create a mock resolver that captures requirements instead of resolving them,
+ * giving you manual control over when and how each requirement completes.
+ *
+ * @param _requirementType - The requirement `type` string this mock handles (used for documentation; matching is done by the test harness).
+ * @returns A {@link MockResolver} with a `handler` function suitable for passing to {@link createTestSystem} mocks.
  *
  * @example
  * ```typescript
@@ -159,12 +231,18 @@ interface MockResolver<R extends Requirement = Requirement> {
  *
  * expect(system.facts.user).toEqual({ name: "John" });
  * ```
+ *
+ * @public
  */
 declare function mockResolver<R extends Requirement = Requirement>(_requirementType: string): MockResolver<R> & {
     /** Handler that can be passed to createTestSystem mocks */
     handler: (req: Requirement, ctx: MockResolverContext) => Promise<void>;
 };
-/** Record of a single fact change */
+/**
+ * Record of a single fact change captured by the test tracking plugin.
+ *
+ * @public
+ */
 interface FactChangeRecord {
     /** The fact key that changed (without namespace prefix for namespaced systems) */
     key: string;
@@ -179,6 +257,17 @@ interface FactChangeRecord {
     /** Timestamp of the change */
     timestamp: number;
 }
+/**
+ * A Directive system augmented with testing utilities.
+ *
+ * @remarks
+ * Extends {@link NamespacedSystem} with event/resolver/fact tracking, idle
+ * waiting, and assertion helpers. Created via {@link createTestSystem}.
+ *
+ * @typeParam Modules - The modules map that defines the system's schema.
+ *
+ * @public
+ */
 interface TestSystem<Modules extends ModulesMap> extends NamespacedSystem<Modules> {
     /**
      * Wait for all pending operations to complete.
@@ -219,6 +308,14 @@ interface TestSystem<Modules extends ModulesMap> extends NamespacedSystem<Module
      */
     assertFactChanges(key: string, times: number): void;
 }
+/**
+ * Options for {@link createTestSystem}, extending the standard system options
+ * with mock resolver injection and automatic tracking.
+ *
+ * @typeParam Modules - The modules map that defines the system's schema.
+ *
+ * @public
+ */
 interface CreateTestSystemOptions<Modules extends ModulesMap> extends Omit<CreateSystemOptionsNamed<Modules>, "plugins"> {
     /** Mock resolvers by type */
     mocks?: {
@@ -228,7 +325,26 @@ interface CreateTestSystemOptions<Modules extends ModulesMap> extends Omit<Creat
     plugins?: Array<any>;
 }
 /**
- * Create a test system with additional testing utilities.
+ * Create a Directive system instrumented for testing.
+ *
+ * Wraps {@link createSystem} with an automatic tracking plugin that records
+ * dispatched events, resolver calls, fact changes, and generated requirements.
+ * Mock resolvers can be injected via `options.mocks.resolvers` to replace
+ * real resolvers by requirement type.
+ *
+ * @param options - System configuration with optional mock resolvers and additional plugins.
+ * @returns A {@link TestSystem} with assertion helpers, idle waiting, and history tracking.
+ *
+ * @example
+ * ```typescript
+ * const system = createTestSystem({
+ *   modules: { counter: counterModule },
+ *   mocks: { resolvers: { INCREMENT: { resolve: (req, context) => { context.facts.count++; } } } },
+ * });
+ * system.start();
+ * ```
+ *
+ * @public
  */
 declare function createTestSystem<Modules extends ModulesMap>(options: CreateTestSystemOptions<Modules>): TestSystem<Modules>;
 

package/dist/testing.d.ts

@@ -12,8 +12,12 @@ import { p as ModulesMap, q as CreateSystemOptionsNamed, R as Requirement, N as
  */
 
 /**
- * Flush all pending microtasks.
- * Call this after advancing fake timers to ensure all Promise callbacks run.
+ * Flush all pending microtasks by awaiting multiple rounds of `Promise.resolve()`.
+ *
+ * Call this after advancing fake timers to ensure all Promise callbacks
+ * (including nested microtasks) have run before making assertions.
+ *
+ * @returns A promise that resolves after all pending microtasks have been drained.
  *
  * @example
  * ```typescript
@@ -24,15 +28,22 @@ import { p as ModulesMap, q as CreateSystemOptionsNamed, R as Requirement, N as
  * vi.advanceTimersByTime(100); // Advance resolver delay
  * await flushMicrotasks(); // Let resolver complete
  * ```
+ *
+ * @public
  */
 declare function flushMicrotasks(): Promise<void>;
 /**
  * Wait for the system to settle with fake timers enabled.
- * Combines timer advancement with microtask flushing.
  *
- * @param system - The Directive system
- * @param advanceTime - Function to advance fake timers (e.g., vi.advanceTimersByTime)
- * @param options - Configuration options
+ * Repeatedly advances fake timers in discrete steps while flushing microtasks,
+ * until no resolvers remain inflight or the time budget is exhausted.
+ *
+ * @param system - The Directive system to wait on (must expose {@link SystemInspection} via `inspect()`).
+ * @param advanceTime - Function that advances fake timers by a given number of milliseconds (e.g., `vi.advanceTimersByTime`).
+ * @param options - Configuration for total time budget, step size, and iteration limit.
+ * @returns A promise that resolves once the system is idle.
+ *
+ * @throws Error if the system does not settle within the configured time budget.
  *
  * @example
  * ```typescript
@@ -48,6 +59,8 @@ declare function flushMicrotasks(): Promise<void>;
  *
  * expect(system.facts.result).toBe("done");
  * ```
+ *
+ * @public
  */
 declare function settleWithFakeTimers(system: {
     inspect(): SystemInspection;
@@ -59,41 +72,77 @@ declare function settleWithFakeTimers(system: {
     /** Maximum iterations before giving up (default: 1000) */
     maxIterations?: number;
 }): Promise<void>;
+/**
+ * Standalone fake timer controller for tests that do not use Vitest/Jest fake timers.
+ *
+ * @remarks
+ * For most tests, prefer Vitest's `vi.useFakeTimers()` paired with
+ * {@link settleWithFakeTimers} for better integration. Use this interface
+ * only when you need a lightweight, framework-independent timer mock.
+ *
+ * @public
+ */
 interface FakeTimers {
-    /** Advance time by a number of milliseconds */
+    /** Advance time by a number of milliseconds, firing any timers that fall within the window. */
     advance(ms: number): Promise<void>;
-    /** Advance to the next scheduled timer */
+    /** Advance to the next scheduled timer and fire its callback. */
     next(): Promise<void>;
-    /** Run all pending timers */
+    /** Run all pending timers in chronological order. */
     runAll(): Promise<void>;
-    /** Get current fake time */
+    /** Get the current fake time in milliseconds. */
     now(): number;
-    /** Reset to time 0 */
+    /** Reset the clock to time 0 and discard all scheduled timers. */
     reset(): void;
 }
 /**
- * Create standalone fake timers for testing.
- * Note: For most tests, prefer using Vitest's vi.useFakeTimers() with
- * settleWithFakeTimers() for better integration.
+ * Create standalone fake timers for testing without a framework timer mock.
+ *
+ * @remarks
+ * For most tests, prefer Vitest's `vi.useFakeTimers()` paired with
+ * {@link settleWithFakeTimers}. This factory is useful when you need an
+ * isolated timer that does not interfere with global timer state.
+ *
+ * @returns A {@link FakeTimers} controller with `advance`, `next`, `runAll`, `now`, and `reset` methods.
+ *
+ * @example
+ * ```typescript
+ * const timers = createFakeTimers();
+ * // schedule work, then:
+ * await timers.advance(500);
+ * expect(timers.now()).toBe(500);
+ * ```
+ *
+ * @public
  */
 declare function createFakeTimers(): FakeTimers;
-/** Context passed to mock resolver resolve functions */
+/**
+ * Context passed to mock resolver resolve functions.
+ *
+ * @public
+ */
 interface MockResolverContext {
     /** Facts object (use type assertion for specific facts) */
     facts: any;
     /** Abort signal for cancellation */
     signal: AbortSignal;
 }
+/**
+ * Configuration for a simple mock resolver created via {@link createMockResolver}.
+ *
+ * @typeParam R - The requirement type this resolver handles.
+ *
+ * @public
+ */
 interface MockResolverOptions<R extends Requirement = Requirement> {
-    /** Predicate to check if this resolver handles a requirement */
+    /** Predicate to check if this resolver handles a given requirement. */
     requirement?: (req: Requirement) => req is R;
-    /** Mock implementation */
+    /** Mock implementation invoked when the resolver runs. */
     resolve?: (req: R, ctx: MockResolverContext) => void | Promise<void>;
-    /** Delay before resolving (ms) */
+    /** Artificial delay in milliseconds before the resolver completes. */
     delay?: number;
-    /** Simulate an error */
+    /** Error (or message string) to throw, simulating a resolver failure. */
     error?: Error | string;
-    /** Track calls */
+    /** Array that receives every requirement passed to this resolver. */
     calls?: R[];
 }
 /** Internal resolver definition type for mock resolvers */
@@ -102,12 +151,32 @@ interface MockResolverDef {
     resolve: (req: Requirement, ctx: MockResolverContext) => Promise<void>;
 }
 /**
- * Create a mock resolver for testing.
+ * Create a simple mock resolver that matches requirements by type and optionally
+ * records calls, injects delays, or throws errors.
+ *
+ * @param typeOrOptions - A requirement type string, or a full {@link MockResolverOptions} object.
+ * @returns A resolver definition that can be spread into a module's `resolvers` map.
+ *
+ * @example
+ * ```typescript
+ * const calls: Requirement[] = [];
+ * const mock = createMockResolver({ requirement: (r): r is MyReq => r.type === "LOAD", calls });
+ * ```
+ *
+ * @public
  */
 declare function createMockResolver<R extends Requirement = Requirement>(typeOrOptions: string | MockResolverOptions<R>): MockResolverDef;
 /**
  * A mock resolver that captures requirements for manual resolution.
- * Use this when you need fine-grained control over when and how requirements resolve.
+ *
+ * @remarks
+ * Use this when you need fine-grained control over when and how requirements
+ * resolve. Requirements are queued in `pending` and stay unresolved until you
+ * explicitly call `resolve()` or `reject()`.
+ *
+ * @typeParam R - The requirement type this resolver handles.
+ *
+ * @public
  */
 interface MockResolver<R extends Requirement = Requirement> {
     /** All requirements received by this resolver */
@@ -130,8 +199,11 @@ interface MockResolver<R extends Requirement = Requirement> {
     reset(): void;
 }
 /**
- * Create a mock resolver that captures requirements instead of resolving them.
- * This gives you manual control over requirement resolution in tests.
+ * Create a mock resolver that captures requirements instead of resolving them,
+ * giving you manual control over when and how each requirement completes.
+ *
+ * @param _requirementType - The requirement `type` string this mock handles (used for documentation; matching is done by the test harness).
+ * @returns A {@link MockResolver} with a `handler` function suitable for passing to {@link createTestSystem} mocks.
  *
  * @example
  * ```typescript
@@ -159,12 +231,18 @@ interface MockResolver<R extends Requirement = Requirement> {
  *
  * expect(system.facts.user).toEqual({ name: "John" });
  * ```
+ *
+ * @public
  */
 declare function mockResolver<R extends Requirement = Requirement>(_requirementType: string): MockResolver<R> & {
     /** Handler that can be passed to createTestSystem mocks */
     handler: (req: Requirement, ctx: MockResolverContext) => Promise<void>;
 };
-/** Record of a single fact change */
+/**
+ * Record of a single fact change captured by the test tracking plugin.
+ *
+ * @public
+ */
 interface FactChangeRecord {
     /** The fact key that changed (without namespace prefix for namespaced systems) */
     key: string;
@@ -179,6 +257,17 @@ interface FactChangeRecord {
     /** Timestamp of the change */
     timestamp: number;
 }
+/**
+ * A Directive system augmented with testing utilities.
+ *
+ * @remarks
+ * Extends {@link NamespacedSystem} with event/resolver/fact tracking, idle
+ * waiting, and assertion helpers. Created via {@link createTestSystem}.
+ *
+ * @typeParam Modules - The modules map that defines the system's schema.
+ *
+ * @public
+ */
 interface TestSystem<Modules extends ModulesMap> extends NamespacedSystem<Modules> {
     /**
      * Wait for all pending operations to complete.
@@ -219,6 +308,14 @@ interface TestSystem<Modules extends ModulesMap> extends NamespacedSystem<Module
      */
     assertFactChanges(key: string, times: number): void;
 }
+/**
+ * Options for {@link createTestSystem}, extending the standard system options
+ * with mock resolver injection and automatic tracking.
+ *
+ * @typeParam Modules - The modules map that defines the system's schema.
+ *
+ * @public
+ */
 interface CreateTestSystemOptions<Modules extends ModulesMap> extends Omit<CreateSystemOptionsNamed<Modules>, "plugins"> {
     /** Mock resolvers by type */
     mocks?: {
@@ -228,7 +325,26 @@ interface CreateTestSystemOptions<Modules extends ModulesMap> extends Omit<Creat
     plugins?: Array<any>;
 }
 /**
- * Create a test system with additional testing utilities.
+ * Create a Directive system instrumented for testing.
+ *
+ * Wraps {@link createSystem} with an automatic tracking plugin that records
+ * dispatched events, resolver calls, fact changes, and generated requirements.
+ * Mock resolvers can be injected via `options.mocks.resolvers` to replace
+ * real resolvers by requirement type.
+ *
+ * @param options - System configuration with optional mock resolvers and additional plugins.
+ * @returns A {@link TestSystem} with assertion helpers, idle waiting, and history tracking.
+ *
+ * @example
+ * ```typescript
+ * const system = createTestSystem({
+ *   modules: { counter: counterModule },
+ *   mocks: { resolvers: { INCREMENT: { resolve: (req, context) => { context.facts.count++; } } } },
+ * });
+ * system.start();
+ * ```
+ *
+ * @public
  */
 declare function createTestSystem<Modules extends ModulesMap>(options: CreateTestSystemOptions<Modules>): TestSystem<Modules>;