electron-direct-ipc - v2.2.3
    Preparing search index...

    Class DirectIpcThrottled<TMessageMap, TInvokeMap, TIdentifierStrings>

    Note: You typically access this via directIpc.throttled rather than creating instances directly. DirectIpcRenderer automatically creates a throttled instance.

    Provides automatic message throttling using microtask coalescing. This is a lossy communication pattern where intermediate messages are dropped, keeping only the latest message per event loop tick.

    Send-side coalescing:

    • Multiple sends to the same target+channel in one tick → only last message sent
    • Sends are batched and dispatched on next microtask (~1ms)
    • All pending sends dispatched in parallel for maximum throughput

    Receive-side coalescing:

    • Multiple receives on same channel in one tick → listeners called once with latest
    • Received messages queued and dispatched on next microtask
    • All listeners receive the same (latest) coalesced value

    ✅ Use directIpc.throttled when:

    • Sending high-frequency state updates (position, volume, progress)
    • Only the latest value matters (replaceable state, not events)
    • You're experiencing backpressure (sender faster than receiver)
    • UI updates that can safely skip intermediate frames
    • Real-time data feeds where staleness is unacceptable

    ❌ Use regular directIpc when:

    • Every message is unique and important (user actions, commands)
    • Messages represent discrete events (not continuous state)
    • Order of messages matters for correctness
    • You need guaranteed delivery of every message
    • Messages trigger side effects that can't be skipped
    • Using invoke/handle pattern (already request-response, no throttling needed)

    Before using .throttled, verify ALL of these are true:

    • [ ] Your message represents replaceable state (not unique events)
    • [ ] Only the latest value matters (intermediate values can be lost)
    • [ ] Missing intermediate updates is acceptable for your use case
    • [ ] You're experiencing backpressure or very high message rates (>60Hz)
    • [ ] The message is idempotent (same value sent twice = same effect as once)

    If ANY of these are false, use regular directIpc methods instead.

    // Setup - throttled is automatically available
    const directIpc = DirectIpcRenderer.instance<MyMessages>({ identifier: 'controller' })

    // ✅ GOOD: High-frequency state updates (throttled)
    // Only the final position (1000) will be sent
    for (let i = 0; i <= 1000; i++) {
      directIpc.throttled.send({ identifier: 'output' }, 'playback-position', i)
    }

    // ✅ GOOD: Receive high-frequency updates (throttled)
    // Listener called once per microtask with latest value
    directIpc.throttled.on('volume-level', (sender, level) => {
      updateVolumeUI(level) // Only latest level shown
    })

    // ✅ GOOD: Important user actions (NOT throttled)
    directIpc.send({ identifier: 'output' }, 'play-button-clicked')

    // ✅ GOOD: Unique events (NOT throttled)
    directIpc.send({ identifier: 'output' }, 'clip-added', clip)

    // ✅ GOOD: Mix throttled and non-throttled for different channels
    directIpc.throttled.send({ identifier: 'output' }, 'position-update', position)
    directIpc.send({ identifier: 'output' }, 'song-changed', songId)
    • Latency: ~1ms added latency (one microtask delay)
    • Throughput: High - parallel sends after coalescing
    • Message loss: 0% for latest value, 100% for intermediate values
    • Memory: O(channels) - one pending message per unique target+channel

    This class is designed for single-threaded use within one renderer process. It is NOT thread-safe across Web Workers or multiple processes.

    // Access via directIpc.throttled property
    const directIpc = DirectIpcRenderer.instance<Messages>({ identifier: 'my-window' })

    // Send throttled messages
    directIpc.throttled.send({ identifier: 'output' }, 'cursor-position', x, y)

    // Receive throttled messages
    directIpc.throttled.on('mouse-move', (sender, x, y) => {
      updateCursor(x, y)
    })

    Type Parameters

    • TMessageMap extends EventMap = EventMap

      Map of message channels to handler signatures (WITHOUT sender)

    • TInvokeMap extends InvokeMap = InvokeMap

      Map of invoke channels to handler signatures (WITHOUT sender)

    • TIdentifierStrings extends string = string

      Union of allowed identifier strings

    Index

    Constructors

    constructor

    Properties

    directIpc getDefaultTimeout getMap getMyIdentifier handle invoke refreshMap removeHandler resolveTargetToWebContentsId setDefaultTimeout setIdentifier

    Accessors

    localEvents

    Methods

    off on send

    Constructors

    Properties

    directIpc: DirectIpcRenderer<TMessageMap, TInvokeMap, TIdentifierStrings>

    The underlying DirectIpcRenderer instance Use this for non-throttled operations like invoke/handle

    getDefaultTimeout: () => number

    Type Declaration

      • (): number

      • Get the current default timeout

        Returns number

    getMap: () => DirectIpcTarget[]

    Type Declaration

    getMyIdentifier: () => TIdentifierStrings | undefined

    Type Declaration

    handle: <T extends string | number | symbol>(
        channel: T,
        handler: WithSender<TInvokeMap>[T],
    ) => void

    Proxy methods (bound in constructor)

    Type Declaration

      • <T extends string | number | symbol>(
            channel: T,
            handler: WithSender<TInvokeMap>[T],
        ): void

      • Register a handler for invoke calls on a specific channel

        Type Parameters

        • T extends string | number | symbol

        Parameters

        Returns void

    invoke: <T extends string | number | symbol>(
        target: Omit<
            TargetSelector<TIdentifierStrings>,
            "allIdentifiers" | "allUrls",
        >,
        channel: T,
        ...args: [
            ...params: (TInvokeMap[T] extends (...args: P) => any ? P : never)[],
            options?: InvokeOptions,
        ],
    ) => Promise<
        TInvokeMap[T] extends (...args: any[]) => R ? Awaited<R> : unknown,
    >

    Type Declaration

      • <T extends string | number | symbol>(
            target: Omit<
                TargetSelector<TIdentifierStrings>,
                "allIdentifiers" | "allUrls",
            >,
            channel: T,
            ...args: [
                ...params: (TInvokeMap[T] extends (...args: P) => any ? P : never)[],
                options?: InvokeOptions,
            ],
        ): Promise<
            TInvokeMap[T] extends (...args: any[]) => R ? Awaited<R> : unknown,
        >

      • Invoke a handler on a remote renderer using a TargetSelector Note: Only single-target selectors are supported (not allIdentifiers/allUrls)

        Type Parameters

        • T extends string | number | symbol

        Parameters

        Returns Promise<TInvokeMap[T] extends (...args: any[]) => R ? Awaited<R> : unknown>

        // Invoke on specific webContentsId
        const result = await directIpc.invoke({ webContentsId: 123 }, 'get-data', arg1, arg2)

        // Invoke on identifier (throws if multiple matches)
        const result = await directIpc.invoke({ identifier: 'output' }, 'get-data', arg1, arg2)

        // Invoke on URL pattern (throws if multiple matches)
        const result = await directIpc.invoke({ url: /^https://example/ }, 'get-data', arg1, arg2)

        // With timeout option
        const result = await directIpc.invoke({ identifier: 'output' }, 'get-data', arg1, { timeout: 5000 })
    refreshMap: () => Promise<DirectIpcTarget[]>

    Type Declaration

    removeHandler: <T extends string | number | symbol>(channel: T) => void

    Type Declaration

      • <T extends string | number | symbol>(channel: T): void

      • Remove a handler for a specific channel

        Type Parameters

        • T extends string | number | symbol

        Parameters

        • channel: T

        Returns void

    resolveTargetToWebContentsId: (
        target: {
            identifier?: RegExp | TIdentifierStrings;
            url?: string | RegExp;
            webContentsId?: number;
        },
    ) => number
    | undefined

    Type Declaration

      • (
            target: {
                identifier?: RegExp | TIdentifierStrings;
                url?: string | RegExp;
                webContentsId?: number;
            },
        ): number
        | undefined

      • Resolve a target to its webContentsId using the local map

        Parameters

        • target: {
              identifier?: RegExp | TIdentifierStrings;
              url?: string | RegExp;
              webContentsId?: number;
          }

        Returns number | undefined

        Use resolveTargetToProcessId instead

    setDefaultTimeout: (ms: number) => void

    Type Declaration

      • (ms: number): void

      • Set the default timeout for invoke calls

        Parameters

        • ms: number

        Returns void

    setIdentifier: (identifier: TIdentifierStrings) => Promise<void>

    Type Declaration

      • (identifier: TIdentifierStrings): Promise<void>

      • Set or update this renderer's identifier

        Parameters

        • identifier: TIdentifierStrings

          The identifier string to set (must be one of TIdentifierStrings)

        Returns Promise<void>

    Accessors

    Methods

    • Register a listener for throttled message reception

      Multiple messages on the same channel received in one tick will be coalesced, and the listener will be called once with the latest value on the next microtask.

      Type Parameters

      • E extends string | number | symbol

      Parameters

      • event: E

        Channel name to listen on

      • listener: WithSender<TMessageMap>[E]

        Handler function (receives sender + message args)

      Returns this

      This instance for chaining

    • Send a message to target renderer(s) using a TargetSelector (throttled)

      Multiple calls to the same target+channel in one tick will be coalesced, keeping only the latest message. The message is sent on the next microtask.

      Type Parameters

      • T extends string | number | symbol

      Parameters

      Returns Promise<void>

      // Send to single identifier (throttled)
      directIpc.throttled.send({ identifier: 'output' }, 'cursor-position', x, y)

      // Send to webContentsId (throttled)
      directIpc.throttled.send({ webContentsId: 123 }, 'update', data)

      // Send to all matching identifiers (throttled)
      directIpc.throttled.send({ allIdentifiers: /^output/ }, 'broadcast', msg)

    Settings

    Member Visibility

    On This Page

    DirectIpcThrottled - Lossy Message Coalescing
    Constructors
    Properties
    Accessors
    Methods