@noego/testing 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,262 +1,272 @@
-import { Clock, Instant, Duration, Scheduler, ScheduleInput, ScheduledTaskHandle, ScheduledTaskId, IdGenerator, BrandedId, RandomSource, FetchRequest, FetchResponse, FetchError, FetchClient, ProcessCommand, ProcessEvent, ProcessRunner, ProcessResult, SpawnCommand, ProcessHandle, KeyValueStore, Key, Codec, PutOptions, ObjectStore, ObjectKey, StoredObject, StoredObjectInput, ObjectVersion, DomainEvent, EventBus, EventHandler, Subscription, LogSink, LogEnvelope, TelemetrySink, TelemetryEnvelope, TraceSink, TraceEnvelope } from '@noego/runtime';
+import { IContainer, ApplicationModule } from '@noego/ioc';
 
 /**
- * Deterministic clock. Time never moves unless the test moves it.
- * Defaults to a fixed instant so snapshots are stable.
- */
-declare class ManualClock extends Clock {
-    static readonly defaultStart: Instant;
-    private current;
-    constructor(start?: Instant);
-    now(): Instant;
-    set(instant: Instant): void;
-    advanceBy(duration: Duration): void;
-}
-
-interface PendingTask {
-    readonly id: ScheduledTaskId;
-    readonly label: string;
-    readonly deadline: Instant;
-}
-/**
- * Deterministic scheduler driven by a ManualClock.
+ * Lowercase `test.*` descriptors — immutable frozen values.
  *
- * Locked semantics:
- * - deadlines are (scheduledAt + delay);
- * - equal deadlines run in insertion order;
- * - cancelled tasks never execute;
- * - callbacks scheduled by callbacks are ordered deterministically (insertion
- *   sequence is global and monotonic);
- * - async callbacks settle before advancing continues;
- * - runUntilIdle fails with a bounded diagnostic on infinite reschedule loops;
- * - assertNoPendingTasks fails teardown when tasks remain, unless allowed;
- * - CHOSEN MODEL: advancing time RUNS every task whose deadline falls inside
- *   the advanced window, in deadline order. advanceBy(Duration.zero) runs
- *   tasks already due.
+ * Descriptors carry NO mutable state (no cursors, no counters, no histories);
+ * all mutable invocation state lives in the built environment, so one
+ * descriptor value is safe to share across builders and repeated builds.
  */
-declare class ManualScheduler extends Scheduler {
-    private readonly clock;
-    private readonly tasks;
-    private nextSequence;
-    private nextId;
-    constructor(clock: ManualClock);
-    schedule(input: ScheduleInput): ScheduledTaskHandle;
-    pending(): PendingTask[];
-    /** Advance the clock, running every task due inside the window in order. */
-    advanceBy(duration: Duration): Promise<void>;
-    /** Advance to the earliest pending deadline and run exactly that task. */
-    runNext(): Promise<void>;
-    /** Run tasks (advancing time as needed) until none remain. */
-    runUntilIdle(options?: {
-        maxTasks?: number;
-    }): Promise<void>;
-    /** Teardown assertion: fails when pending tasks remain, unless allowed. */
-    assertNoPendingTasks(options?: {
-        allow?: boolean;
-    }): void;
-    private live;
-    private nextDue;
-    private execute;
-    private remove;
+declare const DESCRIPTOR: unique symbol;
+/** A raw custom method wrapper: (original) => replacement. NOT auto-watched. */
+type RawMethodWrapper = (original: (...args: any[]) => any) => (...args: any[]) => any;
+interface ReturnsDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'returns';
+    readonly value: unknown;
 }
-
-/**
- * Deterministic ID generator: "<brand>-1", "<brand>-2", … per brand.
- * Fixed IDs keep snapshots stable; isolation makes collisions impossible.
- */
-declare class SequenceIdGenerator extends IdGenerator {
-    private readonly counters;
-    next<TBrand extends string>(brand: TBrand): BrandedId<TBrand>;
+interface ThrowsDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'throws';
+    readonly error: unknown;
 }
-
-/**
- * Deterministic random source (mulberry32). The same seed always yields the
- * same sequence.
- */
-declare class SeededRandomSource extends RandomSource {
-    private state;
-    constructor(seed?: number);
-    private nextUint32;
-    bytes(length: number): Uint8Array;
-    integer(minInclusive: number, maxExclusive: number): number;
+interface OriginalDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'original';
 }
-
-interface FetchScriptEntry {
-    /** Human-readable description used in failure diagnostics. */
-    readonly describe: string;
-    /** Typed predicate the incoming request must satisfy. */
-    readonly matches: (request: FetchRequest) => boolean;
-    /** Either respond or fail with a normalized FetchError. */
-    readonly respond: (request: FetchRequest) => FetchResponse | FetchError;
+interface CallsDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'calls';
+    readonly script: readonly BehaviorDescriptor[];
 }
-/**
- * Scripted FetchClient. Scripts are consumed strictly in order; an unexpected
- * or mismatched call fails immediately with a diagnostic.
- */
-declare class ScriptedFetchClient extends FetchClient {
-    private readonly script;
-    private cursor;
-    readonly executed: FetchRequest[];
-    constructor(script: readonly FetchScriptEntry[]);
-    execute(request: FetchRequest): Promise<FetchResponse>;
-    /** Teardown assertion: every scripted call must have been consumed. */
-    assertScriptConsumed(): void;
+type BehaviorDescriptor = ReturnsDescriptor | ThrowsDescriptor | OriginalDescriptor | CallsDescriptor;
+interface WatchDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'watch';
+    readonly wrapper?: RawMethodWrapper;
 }
-
-/** Spawn handle with test-only deterministic delivery control. */
-interface ScriptedSpawnHandle extends ProcessHandle {
-    /** Deliver all scripted events now (deterministic, test-controlled). */
-    flush(): void;
+interface ExpectationDescriptor {
+    readonly [DESCRIPTOR]: true;
+    readonly kind: 'expect';
+    /** Exact required call count; 0 for never(). */
+    readonly expected: number;
+    /** Behavior used for allowed calls; undefined = original effective behavior. */
+    readonly behavior?: BehaviorDescriptor;
 }
-interface ProcessScriptEntry {
-    readonly describe: string;
-    readonly matches: (command: ProcessCommand) => boolean;
-    /** Events emitted (for spawn) / folded into the result (for run). */
-    readonly events: readonly ProcessEvent[];
+/** Everything installable through .methods({...}). */
+type MethodDescriptor = BehaviorDescriptor | WatchDescriptor | ExpectationDescriptor | RawMethodWrapper;
+declare const test: {
+    /** Return the supplied value when the method is called. Auto-watches. */
+    returns(value: unknown): ReturnsDescriptor;
+    /** Throw/reject with the supplied error. Auto-watches. */
+    throws(error: unknown): ThrowsDescriptor;
+    /** Invoke the original effective method. Auto-watches. */
+    original(): OriginalDescriptor;
+    /**
+     * Per-invocation behavior script: call 1 uses entry 1, and so on. A call
+     * after exhaustion fails immediately. Unused entries do not fail verification.
+     */
+    calls(script: readonly BehaviorDescriptor[]): CallsDescriptor;
+    /**
+     * Keep original behavior and record calls. With a raw wrapper argument, the
+     * wrapper's behavior runs and is recorded.
+     */
+    watch(wrapper?: RawMethodWrapper): WatchDescriptor;
+    /** Require exactly one call; with no behavior, the original runs. */
+    once(behavior?: BehaviorDescriptor): ExpectationDescriptor;
+    /** Require exactly `count` calls; with no behavior, the original runs. */
+    times(count: number, behavior?: BehaviorDescriptor): ExpectationDescriptor;
+    /** Require zero calls; the first invocation fails and skips the original. */
+    never(): ExpectationDescriptor;
+    /** Read the recorded history for a watched method in one environment. */
+    inspect(environment: unknown, token: unknown, method: string): MethodInspection;
+};
+/** Symbol under which a built environment exposes its watch registry. */
+declare const ENV_REGISTRY: unique symbol;
+interface RecordedCall {
+    /** 1-based invocation index in this environment. */
+    readonly index: number;
+    readonly args: readonly unknown[];
+    /** Present once the call returned (resolved value for async methods). */
+    readonly result?: unknown;
+    /** Present once the call threw/rejected. */
+    readonly error?: unknown;
+    /** True while an async outcome is still pending. */
+    readonly pending: boolean;
+    readonly timestamp: number;
 }
-/**
- * Scripted ProcessRunner. Scripts are consumed in order; unexpected commands
- * fail immediately. Spawned handles emit their declared events when
- * flush() is called, keeping delivery under test control.
- */
-declare class ScriptedProcessRunner extends ProcessRunner {
-    private readonly script;
-    private cursor;
-    private readonly openHandles;
-    constructor(script: readonly ProcessScriptEntry[]);
-    private consume;
-    run(command: ProcessCommand): Promise<ProcessResult>;
-    spawn(command: SpawnCommand): ScriptedSpawnHandle;
-    /** Teardown assertion: no spawned process may remain open. */
-    assertNoOpenHandles(): void;
+interface MethodInspection {
+    readonly count: number;
+    readonly calls: readonly RecordedCall[];
 }
 
 /**
- * Deterministic in-memory KeyValueStore with clock-driven TTL semantics.
- * Passes the same contract as KV/Redis adapters.
+ * Environment-owned method behavior/observation runtime.
+ *
+ * All mutable state (histories, expectation counters, calls-script cursors)
+ * lives here, created fresh at every build(). Descriptors stay immutable.
  */
-declare class MemoryKeyValueStore extends KeyValueStore {
-    private readonly clock;
+
+interface MutableCall {
+    index: number;
+    args: readonly unknown[];
+    result?: unknown;
+    error?: unknown;
+    pending: boolean;
+    timestamp: number;
+}
+declare class MethodState {
+    readonly tokenName: string;
+    readonly method: string;
+    readonly descriptor: Exclude<MethodDescriptor, RawMethodWrapper>;
+    readonly calls: MutableCall[];
+    /** Actual invocation count (includes the call currently executing). */
+    actual: number;
+    /** Cursor into a test.calls() script. */
+    scriptCursor: number;
+    constructor(tokenName: string, method: string, descriptor: Exclude<MethodDescriptor, RawMethodWrapper>);
+    get expectation(): ExpectationDescriptor | undefined;
+    inspection(): MethodInspection;
+}
+/** One method-config entry: how it was keyed, and its per-method descriptors. */
+interface MethodConfigEntry {
+    /** Exact token (class/symbol/string) or a name string matched lazily. */
+    readonly key: unknown;
+    readonly byName: boolean;
+    readonly methods: ReadonlyMap<string, MethodDescriptor>;
+}
+declare class WatchRegistry {
+    /** entry-identity → method → state. Entries share states across instances. */
+    private readonly states;
+    private readonly nameIndex;
     private readonly entries;
-    constructor(clock: Clock);
-    get<T>(key: Key, codec: Codec<T>): Promise<T | null>;
-    put<T>(key: Key, value: T, codec: Codec<T>, options?: PutOptions): Promise<void>;
-    delete(key: Key): Promise<void>;
+    addEntry(entry: MethodConfigEntry): void;
+    private entryLabel;
+    /** Entries applying to a resolving token (exact identity or name match). */
+    matchEntries(token: unknown): MethodConfigEntry[];
+    state(entryKey: unknown, method: string): MethodState | undefined;
+    inspect(token: unknown, method: string): MethodInspection;
+    /** Repeatable snapshot check of all exact expectations. */
+    verify(): void;
 }
 
 /**
- * Deterministic in-memory ObjectStore with monotonically increasing versions.
- * Passes the same contract as R2/S3 adapters.
+ * `testIoc` — the canonical shared real-IoC test composition builder.
+ *
+ * Persistent immutable: every fluent call returns a new derived builder
+ * sharing the ordered write log structurally. Non-conflicting writes are
+ * order-insensitive; the last write to the same effective identity wins on
+ * that derived branch. `.build()` is non-consuming and creates fresh runtime,
+ * watch, and expectation state (spec 15, PBR-01..15).
  */
-declare class MemoryObjectStore extends ObjectStore {
-    private readonly objects;
-    private nextVersion;
-    read(key: ObjectKey): Promise<StoredObject | null>;
-    write(key: ObjectKey, object: StoredObjectInput): Promise<ObjectVersion>;
-    delete(key: ObjectKey): Promise<void>;
+
+type Token = unknown;
+type ClassLike = new (...args: any[]) => any;
+/** Config maps accept plain objects (string keys) or Maps (exact tokens). */
+type ConfigMap<V> = Record<string, V> | ReadonlyMap<Token, V>;
+type MethodsConfig = ConfigMap<Record<string, MethodDescriptor> | ReadonlyMap<string, MethodDescriptor>>;
+type UseInput = ApplicationModule | TestIocBuilder;
+type Write = {
+    op: 'use';
+    module: ApplicationModule;
+} | {
+    op: 'classes';
+    key: Token;
+    byName: boolean;
+    implementation: ClassLike;
+} | {
+    op: 'functions';
+    key: Token;
+    byName: boolean;
+    factory: (...args: any[]) => any;
+} | {
+    op: 'values';
+    key: Token;
+    byName: boolean;
+    value: unknown;
+} | {
+    op: 'methods';
+    key: Token;
+    byName: boolean;
+    methods: ReadonlyMap<string, MethodDescriptor>;
+};
+interface TestEnvironment {
+    readonly root: IContainer;
+    get<T>(token: unknown, params?: any[]): Promise<T> | T;
+    instance<T>(cls: new (...args: any[]) => T, params?: any[]): Promise<T> | T;
+    extend(): IContainer;
+    verify(): Promise<void>;
+    dispose(): Promise<void>;
+    readonly [ENV_REGISTRY]: WatchRegistry;
 }
+declare class TestIocBuilder {
+    private readonly log;
+    private constructor();
+    /** @internal */
+    static create(inputs: readonly UseInput[]): TestIocBuilder;
+    /** @internal — read by .use(builderPreset) */
+    get writes(): readonly Write[];
+    private derive;
+    private useAll;
+    /** Apply a reusable composition preset: an ApplicationModule or a builder. */
+    use(preset: UseInput): TestIocBuilder;
+    /** Replace the implementation for IoC class tokens in the built environment. */
+    classes(config: ConfigMap<ClassLike>): TestIocBuilder;
+    /** Replace IoC factory/provider registrations. */
+    functions(config: ConfigMap<(...args: any[]) => any>): TestIocBuilder;
+    /** Provide/replace IoC value registrations. */
+    values(config: ConfigMap<unknown>): TestIocBuilder;
+    /** Install method behavior/observation descriptors on IoC-managed instances. */
+    methods(config: MethodsConfig): TestIocBuilder;
+    /** Materialize a fresh, isolated real-IoC environment. Non-consuming. */
+    build(): Promise<TestEnvironment>;
+    /**
+     * Register a class binding. When token === implementation this is a plain
+     * class registration. Otherwise an alias factory resolves the implementation
+     * through real IoC, mirroring the implementation's effective lifetime so
+     * lifetime validation (captive-lifetime checks) stays honest.
+     */
+    private registerClassBinding;
+}
+/** Create a persistent immutable real-IoC test composition builder. */
+declare function testIoc(...inputs: UseInput[]): TestIocBuilder;
 
-type DeliveryMode = "immediate" | "queued";
 /**
- * Recording EventBus. Records exact publication order. Delivery modes:
- * - immediate (default): handlers run during publish;
- * - queued: events buffer until deliverQueued() is called.
- * Active subscriptions at teardown fail assertNoActiveSubscriptions().
+ * Diagnostics are first-class: every error names the real token/method and
+ * what was expected vs what happened, never only internal wrapper machinery.
  */
-declare class RecordingEventBus<TEvent extends DomainEvent> extends EventBus<TEvent> {
-    private readonly mode;
-    readonly published: TEvent[];
-    private readonly handlers;
-    private readonly queue;
-    constructor(mode?: DeliveryMode);
-    publish(event: TEvent): Promise<void>;
-    subscribe(handler: EventHandler<TEvent>): Subscription;
-    /** Deliver buffered events (queued mode) in publication order. */
-    deliverQueued(): Promise<void>;
-    get activeSubscriptionCount(): number;
-    assertNoActiveSubscriptions(): void;
-    private deliver;
+declare class TestingError extends Error {
+    constructor(message: string);
 }
-
-/** In-memory LogSink recording envelopes in emission order. */
-declare class RecordingLogSink extends LogSink {
-    readonly envelopes: LogEnvelope[];
-    emit(envelope: LogEnvelope): void;
+/** Thrown at build() when the installed @noego/ioc lacks the decoration seam. */
+declare class MissingIocSeamError extends TestingError {
+    constructor();
 }
-/** In-memory TraceSink recording envelopes in emission order. */
-declare class RecordingTraceSink extends TraceSink {
-    readonly envelopes: TraceEnvelope[];
-    emit(envelope: TraceEnvelope): void;
+/** test.inspect() on a method that is not watched in this environment. */
+declare class UnwatchedInspectionError extends TestingError {
+    constructor(token: string, method: string);
 }
-/** In-memory TelemetrySink recording envelopes in emission order. */
-declare class RecordingTelemetrySink extends TelemetrySink {
-    readonly envelopes: TelemetryEnvelope[];
-    emit(envelope: TelemetryEnvelope): void;
+/** A call arrived after a test.calls([...]) script was fully consumed. */
+declare class CallScriptExhaustedError extends TestingError {
+    constructor(token: string, method: string, scriptLength: number, callIndex: number);
 }
-/** LogSink that drops everything (for suites that assert nothing about logs). */
-declare class NoopLogSink extends LogSink {
-    emit(_envelope: LogEnvelope): void;
+/** An exact expectation (once/times/never) was exceeded at call time. */
+declare class ExpectationOverflowError extends TestingError {
+    constructor(token: string, method: string, expected: number, attempted: number);
 }
-
-/**
- * Behavioral contract every Clock implementation must satisfy.
- * Runs inside the caller's jest context.
- */
-declare function runClockContract(name: string, setup: () => {
-    clock: Clock;
-}): void;
-
-interface KeyValueStoreContractContext {
-    store: KeyValueStore;
-    /** Move the store's time source forward (real adapters may wait/mock). */
-    advanceBy: (duration: Duration) => Promise<void>;
-    /** Whether the implementation supports TTL expiry. */
-    supportsTtl: boolean;
+/** Aggregated under-count failures reported by env.verify(). */
+declare class VerificationError extends TestingError {
+    constructor(failures: readonly {
+        token: string;
+        method: string;
+        expected: number;
+        actual: number;
+    }[]);
 }
-/**
- * Behavioral contract every KeyValueStore implementation must satisfy —
- * memory, KV, and Redis adapters alike.
- */
-declare function runKeyValueStoreContract(name: string, setup: () => KeyValueStoreContractContext): void;
-
-/**
- * Behavioral contract every ObjectStore implementation must satisfy —
- * memory, R2, S3, and filesystem adapters alike.
- */
-declare function runObjectStoreContract(name: string, setup: () => {
-    store: ObjectStore;
-}): void;
-
-interface TestEvent extends DomainEvent {
-    readonly type: "test-event";
-    readonly value: number;
+/** .methods configured for a token whose resolved value has no such callable method. */
+declare class MethodNotCallableError extends TestingError {
+    constructor(token: string, method: string);
 }
-declare const testEvent: (value: number) => TestEvent;
-interface EventBusContractContext {
-    bus: EventBus<TestEvent>;
-    /** Force delivery of any buffered events (no-op for immediate buses). */
-    deliver: () => Promise<void>;
+/** .methods configured for a token that resolved to a non-object value. */
+declare class NonObjectMethodTargetError extends TestingError {
+    constructor(token: string);
 }
-/**
- * Behavioral contract every EventBus implementation must satisfy.
- */
-declare function runEventBusContract(name: string, setup: () => EventBusContractContext): void;
-
-interface LeakCheck {
-    /** Which resource family this check guards (timers, subscriptions, …). */
-    readonly name: string;
-    /** Returns a description per leaked resource; empty means clean. */
-    readonly check: () => readonly string[];
+/** A string configuration key could not be resolved to a known IoC token. */
+declare class UnknownTokenKeyError extends TestingError {
+    constructor(key: string, space: string, known: readonly string[]);
 }
-/**
- * Aggregates leak checks and fails teardown with one clear report listing
- * every leaked resource across all registered checks.
- */
-declare class LeakDetector {
-    private readonly checks;
-    register(check: LeakCheck): void;
-    findLeaks(): string[];
-    assertNoLeaks(): void;
+/** Invalid descriptor construction (e.g. test.times(-1)). */
+declare class InvalidDescriptorError extends TestingError {
 }
 
-export { type DeliveryMode, type EventBusContractContext, type FetchScriptEntry, type KeyValueStoreContractContext, type LeakCheck, LeakDetector, ManualClock, ManualScheduler, MemoryKeyValueStore, MemoryObjectStore, NoopLogSink, type PendingTask, type ProcessScriptEntry, RecordingEventBus, RecordingLogSink, RecordingTelemetrySink, RecordingTraceSink, ScriptedFetchClient, ScriptedProcessRunner, type ScriptedSpawnHandle, SeededRandomSource, SequenceIdGenerator, type TestEvent, runClockContract, runEventBusContract, runKeyValueStoreContract, runObjectStoreContract, testEvent };
+export { type BehaviorDescriptor, CallScriptExhaustedError, type CallsDescriptor, type ConfigMap, ENV_REGISTRY, type ExpectationDescriptor, ExpectationOverflowError, InvalidDescriptorError, type MethodDescriptor, type MethodInspection, MethodNotCallableError, type MethodsConfig, MissingIocSeamError, NonObjectMethodTargetError, type OriginalDescriptor, type RawMethodWrapper, type RecordedCall, type ReturnsDescriptor, type TestEnvironment, TestIocBuilder, TestingError, type ThrowsDescriptor, UnknownTokenKeyError, UnwatchedInspectionError, type UseInput, VerificationError, type WatchDescriptor, test, testIoc };