Interface IKosTopicHandlerParams<Response, Model, TransformedResponse>

The topic or array of topics to which the handler should respond.

A conditional function that determines whether the handler should be invoked based on the received payload and the Kos Data Model instance. If not provided, the handler will always be invoked when a matching topic is received.

Returns

true if the handler should be invoked, false otherwise.

A transformation function that converts the raw response payload into a desired format. If not provided, the payload will be used as is.

Returns

The transformed payload in the desired format.

Indicates whether the topic handler should listen for WebSocket messages. If set to true, the handler will be invoked when WebSocket messages with matching topics are received. Default is false.

Debounce events - only emit after a period of inactivity

Example

debounce: 1000 // Wait 1 second after last event
Copy

Example

debounce: { delay: 1000, discardIntermediate: true } // Only keep last value
Copy

Throttle events - limit emissions to once per interval

Example

throttle: 500 // At most once every 500ms
Copy

Example

throttle: { interval: 500, discardIntermediate: true } // Only keep first value in window
Copy

Buffer events and emit them as an array after time window or max size

Filter events based on a predicate function Note: This operates on the raw payload before transformation

Only handle the event once, then automatically unsubscribe

Replay the last N events to new handlers

Named wildcard capture for trailing /* patterns. When enabled, the portion after the /* is parsed and passed to the handler. You can optionally specify a name for the captured segment.

Example

@kosTopicHandler({
  topic: "/config/system/*",
  websocket: true,
  wildcardName: "configPath"
})
handleConfigUpdate(payload: ConfigData, raw: ApiCallbackWithWildcard<any>) {
  // raw.wildcardCapture.configPath contains everything after "/config/system/"
}
Copy

Advanced flow control options using async iterators internally. Enables sophisticated event processing patterns like batching, backpressure, on-the-fly transforms, and rate limiting.

Example

@kosTopicHandler({
  topic: 'sensor.data',
  websocket: true,
  flow: {
    batch: { size: 50, window: 1000 },
    transform: (events) => aggregateEvents(events),
    backpressure: { maxConcurrent: 3 }
  }
})
handleProcessedEvents(aggregatedData) {
  // Receives transformed, batched data with backpressure control
}
Copy

Baseline dependency configuration for baseline-delta race condition handling. When specified, this handler will wait for the baseline service request to complete before processing events, and will intelligently replay queued events based on temporal comparison with the baseline request/response timing.

Example

@kosTopicHandler({
  topic: TOPIC_INGREDIENT_UPDATE,
  websocket: true,
  lifecycle: DependencyLifecycle.READY,
  requiresBaseline: {
    path: PATH_INGREDIENTS,
    method: 'get',
    replayStrategy: 'after-request'
  }
})
handleIngredientUpdate(payload: IngredientUpdatePayload) {
  // Framework guarantees:
  // 1. Baseline loaded before this handler executes
  // 2. Queued events replayed with temporal filtering
  // 3. Only events newer than baseline are processed
}
Copy