Class DirectIpcUtilityThrottled<TMessageMap, TInvokeMap, TIdentifierStrings>

DirectIpcUtilityThrottled - Lossy Message Coalescing for Utility Processes

Note: You typically access this via directIpc.throttled rather than creating instances directly. DirectIpcUtility 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.

How It Works

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

When to Use Throttled Messages

✅ 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)
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)

Checklist for Correct Usage

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.

Performance Characteristics

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

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

new DirectIpcUtilityThrottled<
    TMessageMap extends EventMap = EventMap,
    TInvokeMap extends InvokeMap = InvokeMap,
    TIdentifierStrings extends string = string,
>(
    directIpc: DirectIpcUtility<TMessageMap, TInvokeMap, TIdentifierStrings>,
    options?: { log?: DirectIpcLogger },
): DirectIpcUtilityThrottled<TMessageMap, TInvokeMap, TIdentifierStrings>
Create a new throttled wrapper around a DirectIpcUtility instance
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
Parameters
- directIpc: DirectIpcUtility<TMessageMap, TInvokeMap, TIdentifierStrings>
  The DirectIpcUtility instance to wrap
- options: { log?: DirectIpcLogger } = {}
  Optional configuration
Returns DirectIpcUtilityThrottled<TMessageMap, TInvokeMap, TIdentifierStrings>
- Defined in src/utility/DirectIpcUtilityThrottled.ts:166

Properties

`Readonly`directIpc

directIpc: DirectIpcUtility<TMessageMap, TInvokeMap, TIdentifierStrings>

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

`Readonly`getDefaultTimeout

getDefaultTimeout: () => number

Type Declaration

- (): number
- Get the current default timeout
  
  Returns number

`Readonly`getMap

getMap: () => DirectIpcTarget[]

Type Declaration

- (): DirectIpcTarget[]
- Get the current array of all registered target processes
  
  Returns DirectIpcTarget[]

`Readonly`getMyIdentifier

getMyIdentifier: () => TIdentifierStrings | undefined

Type Declaration

- (): TIdentifierStrings | undefined
- Get this process's identifier
  
  Returns TIdentifierStrings | undefined
  The identifier string or undefined if not set

`Readonly`getRegistrationState

getRegistrationState: () => RegistrationState

Type Declaration

- (): RegistrationState
- Get current registration state
  
  Returns RegistrationState

`Readonly`handle

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
  - channel: T
  - handler: WithSender<TInvokeMap>[T]
  Returns void

`Readonly`invoke

invoke: <K extends string | number | symbol>(
    target: Omit<
        TargetSelector<TIdentifierStrings>,
        "allIdentifiers" | "allUrls",
    >,
    channel: K,
    ...argsWithOptions: any[],
) => Promise<Awaited<ReturnType<TInvokeMap[K]>>>

Type Declaration

- <K extends string | number | symbol>(
      target: Omit<
          TargetSelector<TIdentifierStrings>,
          "allIdentifiers" | "allUrls",
      >,
      channel: K,
      ...argsWithOptions: any[],
  ): Promise<Awaited<ReturnType<TInvokeMap[K]>>>
- Invoke a handler on another process
  Type Parameters
  - K extends string | number | symbol
  Parameters
  - target: Omit<TargetSelector<TIdentifierStrings>, "allIdentifiers" | "allUrls">
  - channel: K
  - ...argsWithOptions: any[]
  Returns Promise<Awaited<ReturnType<TInvokeMap[K]>>>

`Readonly`removeHandler

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

`Readonly`setDefaultTimeout

setDefaultTimeout: (ms: number) => void

Type Declaration

- (ms: number): void
- Set the default timeout for invoke calls
  Parameters
  - ms: number
  Returns void

Accessors

localEvents

get localEvents(): TypedEventEmitter<DirectIpcEventMap>
Access to localEvents emitter for non-throttled DirectIpc internal events (target-added, target-removed, map-updated, message)

Returns TypedEventEmitter<DirectIpcEventMap>
- Defined in src/utility/DirectIpcUtilityThrottled.ts:468

Methods

off

off<E extends string | number | symbol>(
event: E,
listener: WithSender<TMessageMap>[E],
): this
Remove a throttled listener
Type Parameters
- E extends string | number | symbol
Parameters
- event: E
  Channel name
- listener: WithSender<TMessageMap>[E]
  Handler function to remove
Returns this
This instance for chaining
- Defined in src/utility/DirectIpcUtilityThrottled.ts:372

on

on<E extends string | number | symbol>(
event: E,
listener: WithSender<TMessageMap>[E],
): this
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
- Defined in src/utility/DirectIpcUtilityThrottled.ts:344

send

send<T extends string | number | symbol>(
    target: TargetSelector<TIdentifierStrings>,
    message: T,
    ...args: TMessageMap[T] extends (...args: P) => unknown ? P : never,
): Promise<void>
Send a message to target process(es) 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
- target: TargetSelector<TIdentifierStrings>
  TargetSelector specifying which process(es) to send to
- message: T
  Message channel name
- ...args: TMessageMap[T] extends (...args: P) => unknown ? P : never
  Message arguments
Returns Promise<void>
Example
```
// Send to single identifier (throttled)
directIpc.throttled.send({ identifier: 'renderer' }, '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: /^renderer/ }, 'broadcast', msg)
```
- Defined in src/utility/DirectIpcUtilityThrottled.ts:215

Class DirectIpcUtilityThrottled<TMessageMap, TInvokeMap, TIdentifierStrings>

DirectIpcUtilityThrottled - Lossy Message Coalescing for Utility Processes

How It Works

When to Use Throttled Messages

Checklist for Correct Usage

Performance Characteristics

Type Parameters

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns DirectIpcUtilityThrottled<TMessageMap, TInvokeMap, TIdentifierStrings>

Properties

ReadonlydirectIpc

ReadonlygetDefaultTimeout

Type Declaration

Returns number

ReadonlygetMap

Type Declaration

Returns DirectIpcTarget[]

ReadonlygetMyIdentifier

Type Declaration

Returns TIdentifierStrings | undefined

ReadonlygetRegistrationState

Type Declaration

Returns RegistrationState

Readonlyhandle

Type Declaration

Type Parameters

Parameters

Returns void

Readonlyinvoke

Type Declaration

Type Parameters

Parameters

Returns Promise<Awaited<ReturnType<TInvokeMap[K]>>>

ReadonlyremoveHandler

Type Declaration

Type Parameters

Parameters

Returns void

ReadonlysetDefaultTimeout

Type Declaration

Parameters

Returns void

Accessors

localEvents

Returns TypedEventEmitter<DirectIpcEventMap>

Methods

off

Type Parameters

Parameters

Returns this

on

Type Parameters

Parameters

Returns this

send

Type Parameters

Parameters

Returns Promise<void>

Example

Settings

On This Page

`Readonly`directIpc

`Readonly`getDefaultTimeout

`Readonly`getMap

`Readonly`getMyIdentifier

`Readonly`getRegistrationState

`Readonly`handle

`Readonly`invoke

`Readonly`removeHandler

`Readonly`setDefaultTimeout