Logos DX
    Preparing search index...

    Class SingleFlight<T>

    A generic coordinator for cache and in-flight request deduplication.

    SingleFlight is a state manager that provides primitives for:

    • Caching values with TTL and stale-while-revalidate (SWR)
    • Tracking in-flight promises to prevent duplicate concurrent executions

    It does NOT handle execution - callers control the flow and use SingleFlight as a coordination layer.

    Core principles:

    • Generic - No knowledge of HTTP, routes, methods, etc. Just keys and values.
    • Primitives, not executor - Provides building blocks, caller orchestrates.
    • Reusable - Can be used in FetchEngine, database queries, memoize, anywhere.
    • Composable - Consumers add their own routing, serialization, events.
    • Async-first - All cache operations are async for adapter flexibility.
    // Basic usage - deduplication only
    const flight = new SingleFlight();

    async function fetchUser(id: string) {
        const key = `user:${id}`;

        // Check in-flight
        const inflight = flight.getInflight(key);
        if (inflight) {
            flight.joinInflight(key);
            return inflight.promise;
        }

        // Start new request
        const promise = api.fetchUser(id);
        const cleanup = flight.trackInflight(key, promise);

        try {
            return await promise;
        }
        finally {
            cleanup();
        }
    }

    // With caching and SWR
    const flight = new SingleFlight<UserData>({
        defaultTtl: 60000,     // 1 minute cache
        defaultStaleIn: 30000  // Stale after 30 seconds
    });

    async function fetchUser(id: string) {
        const key = `user:${id}`;

        // Check cache first
        const cached = await flight.getCache(key);
        if (cached && !cached.isStale) {
            return cached.value;
        }

        // Check in-flight
        const inflight = flight.getInflight(key);
        if (inflight) {
            flight.joinInflight(key);
            return inflight.promise;
        }

        // Return stale immediately, revalidate in background
        if (cached?.isStale) {
            const promise = api.fetchUser(id);
            const cleanup = flight.trackInflight(key, promise);
            promise
                .then(value => flight.setCache(key, value))
                .finally(cleanup);
            return cached.value;
        }

        // Fresh fetch
        const promise = api.fetchUser(id);
        const cleanup = flight.trackInflight(key, promise);
        try {
            const value = await promise;
            await flight.setCache(key, value);
            return value;
        }
        finally {
            cleanup();
        }
    }

    Type Parameters

    • T = unknown

      The type of values to cache/track

    Index

    Constructors

    constructor

    Methods

    clear clearCache deleteCache getCache getInflight hasCache hasInflight invalidateCache joinInflight setCache stats trackInflight

    Constructors

    Methods

    • Clear all state (cache + in-flight).

      Returns Promise<void>

    • Clear only cache entries.

      Returns Promise<void>

    • Delete a cache entry.

      Parameters

      • key: string

        Cache key

      Returns Promise<boolean>

      true if entry existed

    • Get cached value if exists and not expired.

      Returns null if not cached or expired. Returns { isStale: true } if past staleAt but before expiresAt.

      Parameters

      • key: string

        Cache key

      Returns Promise<CacheEntry<T> | null>

      Cache entry or null if not found/expired

    • Get in-flight entry if exists.

      Parameters

      • key: string

        Request key

      Returns InflightEntry<T> | null

      In-flight entry or null if not in-flight

    • Check if key is cached (without returning value).

      Note: May return true for expired items if adapter doesn't clean eagerly.

      Parameters

      • key: string

        Cache key

      Returns Promise<boolean>

      true if key exists in cache

    • Check if key has in-flight request.

      Parameters

      • key: string

        Request key

      Returns boolean

      true if request is in-flight

    • Invalidate cache entries matching a predicate.

      Uses adapter's keys() method if available (MapCacheAdapter has it). Returns 0 if adapter doesn't support key iteration.

      Parameters

      • predicate: (key: string) => boolean

        Function that returns true for keys to delete

      Returns Promise<number>

      Number of entries deleted

      // Delete all user-related entries
      const count = await flight.invalidateCache(key => key.startsWith('user:'));

    • Join an existing in-flight request.

      Increments waitingCount and returns new count.

      Parameters

      • key: string

        Request key

      Returns number

      New waiting count, or 0 if no in-flight request

    • Set a cache entry.

      Parameters

      • key: string

        Cache key

      • value: T

        Value to cache

      • Optionalopts: SetCacheOptions

        Optional TTL and staleIn overrides

      Returns Promise<void>

    • Get statistics about current state.

      Returns SingleFlightStats

      Cache size and in-flight count

    • Track an in-flight promise.

      Returns cleanup function to call on completion.

      Parameters

      • key: string

        Request key

      • promise: Promise<T>

        The promise to track

      Returns () => void

      Cleanup function

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods