Documentation
    Preparing search index...

    Class EffectRunner

    Executes effects with per-runner state.

    A runner owns the mutable behavior around otherwise inert effect descriptors: validated input memoization, same-input in-flight deduplication, microtask collection, fixed-window rate limiters, nested effect calls, optional persistent cache access, and lightweight stats. Create separate runners when you want separate memo/cache state for tests, tenants, requests, or isolated workflows.

    Index
    constructor
    call clear getStats

    • Creates a new isolated effect runner.

      Provide kv to enable persistent cache reads/writes for effects created with cache: true. Without kv, the runner still deduplicates in-flight calls and memoizes completed values in memory for its lifetime.

      Parameters

      • Optionaloptions: RunnerOptions = {}

        Optional iso-kv compatible cache and logger used by effect handlers.

      Returns EffectRunner

    • Calls an effect with validated input and returns its validated output.

      The call pipeline is:

      1. validate and normalize input through the effect's input schema;
      2. derive a stable cache key from the normalized input;
      3. return an in-memory value or in-flight promise for same-input calls;
      4. queue the call until the next microtask so simultaneous callers coalesce;
      5. read and validate persistent cache when enabled;
      6. wait for rate-limit capacity, execute the handler, validate output, and persist the result unless context.cache was set to false.

      Type Parameters

      • Input
      • Output

      Parameters

      • effect: Effect<Input, Output>

        Effect descriptor created with createEffect.

      • input: Input

        Raw input value to validate with the effect schema.

      Returns Promise<Output>

    • Clears runner-local memoized outputs.

      This only clears completed in-memory values. In-flight promises continue to resolve normally, rate-limit windows are preserved, and persistent iso-kv cache entries are intentionally left untouched.

      Parameters

      • Optionaleffect: Effect<any, any>

        Optional effect to clear. Omit to clear memoized outputs for all effects registered in this runner.

      Returns void

    • Returns a snapshot of this runner's counters for an effect.

      The returned object is a copy, so mutating it will not affect runner state. Counters are scoped to this runner and do not include activity from other runners using the same effect descriptor.

      Parameters

      • effect: Effect<any, any>

        Effect whose stats should be returned.

      Returns {
          cacheHits: number;
          cacheWrites: number;
          calls: number;
          dedupHits: number;
          errors: number;
          invalidations: number;
          memoHits: number;
      }

      • cacheHits: number

        Persistent cache reads that produced valid output.

      • cacheWrites: number

        Persistent cache writes.

      • calls: number

        Handler executions. Cache and memo hits do not increment this counter.

      • dedupHits: number

        Calls that reused an in-flight same-input promise.

      • errors: number

        Calls rejected because validation, cache, or handler execution failed.

      • invalidations: number

        Persistent cache entries removed because output validation failed.

      • memoHits: number

        Calls served from runner-local memory.

    Settings
    Member Visibility

    On This Page
    Constructors
    Methods