Installation
Initialization
Creates and returns a connected SDK instance. The WebSocket connection is established automatically — there is no separateconnect() call.
Methods
createChannel
Creates a streaming channel pair for worker-to-worker data transfer. Returns a Channel with a local writer/reader and serializable refs that can be passed as fields in the invocation data to other functions. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
bufferSize | number | Yes | Optional buffer size for the channel (default: 64) |
Example
createStream
Creates a new stream implementation. This overrides the default stream implementation. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
streamName | string | Yes | The name of the stream |
stream | IStream<TData> | Yes | The stream implementation |
Example
listFunctions
Lists all registered functions. SignatureExample
listTriggers
Lists all registered triggers. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
includeInternal | boolean | Yes | Whether to include internal triggers (default: false) |
listTriggerTypes
Lists all trigger types registered with the engine. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
includeInternal | boolean | Yes | Whether to include internal trigger types (default: false) |
Example
onFunctionsAvailable
Registers a callback to receive the current functions list when the engine announces changes. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
callback | FunctionsAvailableCallback | Yes | - |
Example
registerFunction
SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
func | RegisterFunctionInput | Yes | - |
handler | RemoteFunctionHandler | Yes | - |
registerService
Registers a new service. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
message | RegisterServiceInput | Yes | The service to register |
registerTrigger
Registers a new trigger. A trigger is a way to invoke a function when a certain event occurs. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
trigger | RegisterTriggerInput | Yes | The trigger to register |
Example
registerTriggerType
Registers a new trigger type. A trigger type is a way to invoke a function when a certain event occurs. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
triggerType | RegisterTriggerTypeInput | Yes | The trigger type to register |
handler | TriggerHandler<TConfig> | Yes | The handler for the trigger type |
Example
shutdown
Gracefully shutdown the iii, cleaning up all resources. SignatureExample
trigger
Invokes a function using a request object. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
request | TriggerRequest<TInput> | Yes | The trigger request containing function_id, payload, and optional action/timeout |
Example
unregisterTriggerType
Unregisters a trigger type. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
triggerType | RegisterTriggerTypeInput | Yes | The trigger type to unregister |
Example
Subpath Exports
Theiii-sdk package provides additional entry points:
| Import path | Contents |
|---|---|
iii-sdk | MessageType, ChannelReader, ChannelWriter, Logger, ISdk, ApiRequest, ApiResponse, AuthInput, AuthResult, Channel, etc. |
iii-sdk/stream | IStream, StreamAuthInput, StreamAuthResult, StreamChangeEvent, StreamJoinLeaveEvent, StreamJoinLeaveTriggerConfig, StreamJoinResult, StreamTriggerConfig, DeleteResult, StreamContext, etc. |
iii-sdk/state | StateEventType, IState, StateEventData, DeleteResult, StateDeleteInput, StateDeleteResult, StateGetInput, StateListInput, StateSetInput, StateSetResult, etc. |
iii-sdk/telemetry | WorkerMetricsCollector, IIIReconnectionConfig, OtelConfig, ReconnectionConfig, WorkerGaugesOptions, WorkerMetricsCollectorOptions, FunctionInfo, FunctionsAvailableCallback, IIIConnectionState, OtelLogEvent, etc. |
Logger
Structured logger that emits logs as OpenTelemetry LogRecords. Every log call automatically captures the active trace and span context, correlating your logs with distributed traces without any manual wiring. When OTel is not initialized, Logger gracefully falls back toconsole.*.
Pass structured data as the second argument to any log method. Using an
object of key-value pairs (instead of string interpolation) lets you
filter, aggregate, and build dashboards in your observability backend.
debug
Log a debug-level message. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Human-readable log message. |
data | unknown | Yes | Structured context attached as OTel log attributes. Use key-value objects to enable filtering and aggregation in your observability backend (e.g. Grafana, Datadog, New Relic). |
Example
error
Log an error-level message. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Human-readable log message. |
data | unknown | Yes | Structured context attached as OTel log attributes. Use key-value objects to enable filtering and aggregation in your observability backend (e.g. Grafana, Datadog, New Relic). |
Example
info
Log an info-level message. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Human-readable log message. |
data | unknown | Yes | Structured context attached as OTel log attributes. Use key-value objects to enable filtering and aggregation in your observability backend (e.g. Grafana, Datadog, New Relic). |
Example
warn
Log a warning-level message. SignatureParameters
| Name | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Human-readable log message. |
data | unknown | Yes | Structured context attached as OTel log attributes. Use key-value objects to enable filtering and aggregation in your observability backend (e.g. Grafana, Datadog, New Relic). |
Example
Types
MessageType · ChannelReader · ChannelWriter · Channel · FunctionRef · HttpAuthConfig · HttpInvocationConfig · InitOptions · RegisterFunctionInput · RegisterFunctionMessage · RegisterServiceInput · RegisterTriggerInput · RegisterTriggerMessage · RegisterTriggerTypeInput · RegisterTriggerTypeMessage · RemoteFunctionHandler · StreamChannelRef · Trigger · TriggerHandler · TriggerInfo · TriggerRequest · TriggerTypeInfo · TriggerTypeRef · IStream · DeleteResult · StreamSetResult · StreamUpdateResult · DeleteResult · IIIReconnectionConfig · OtelConfig · ReconnectionConfig · FunctionInfo · FunctionsAvailableCallback · RegisterFunctionFormat
MessageType
| Name | Type | Required | Description |
|---|---|---|---|
InvocationResult | "invocationresult" | Yes | - |
InvokeFunction | "invokefunction" | Yes | - |
RegisterFunction | "registerfunction" | Yes | - |
RegisterService | "registerservice" | Yes | - |
RegisterTrigger | "registertrigger" | Yes | - |
RegisterTriggerType | "registertriggertype" | Yes | - |
TriggerRegistrationResult | "triggerregistrationresult" | Yes | - |
UnregisterFunction | "unregisterfunction" | Yes | - |
UnregisterTrigger | "unregistertrigger" | Yes | - |
UnregisterTriggerType | "unregistertriggertype" | Yes | - |
WorkerRegistered | "workerregistered" | Yes | - |
ChannelReader
Read end of a streaming channel. Provides both a Node.jsReadable stream
for binary data and an onMessage callback for structured text messages.
| Name | Type | Required | Description |
|---|---|---|---|
stream | Readable | Yes | Node.js Readable stream for binary data. |
ChannelWriter
Write end of a streaming channel. Provides both a Node.jsWritable stream
and a sendMessage method for sending structured text messages.
| Name | Type | Required | Description |
|---|---|---|---|
stream | Writable | Yes | Node.js Writable stream for binary data. |
Channel
A streaming channel pair for worker-to-worker data transfer. Created via ISdk.createChannel.| Name | Type | Required | Description |
|---|---|---|---|
reader | ChannelReader | Yes | Reader end of the channel. |
readerRef | StreamChannelRef | Yes | Serializable reference to the reader (can be sent to other workers). |
writer | ChannelWriter | Yes | Writer end of the channel. |
writerRef | StreamChannelRef | Yes | Serializable reference to the writer (can be sent to other workers). |
FunctionRef
Handle returned by ISdk.registerFunction. Contains the function’sid and an unregister() method.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The unique function identifier. |
unregister | () => void | Yes | Removes this function from the engine. |
HttpAuthConfig
Authentication configuration for HTTP-invoked functions.hmac— HMAC signature verification using a shared secret.bearer— Bearer token authentication.api_key— API key sent via a custom header.
HttpInvocationConfig
Configuration for registering an HTTP-invoked function (Lambda, Cloudflare Workers, etc.) instead of a local handler.| Name | Type | Required | Description |
|---|---|---|---|
auth | HttpAuthConfig | No | Authentication configuration. |
headers | Record<string, string> | No | Custom headers to send with the request. |
method | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | No | HTTP method. Defaults to POST. |
timeout_ms | number | No | Timeout in milliseconds. |
url | string | Yes | URL to invoke. |
InitOptions
Configuration options passed to registerWorker.| Name | Type | Required | Description |
|---|---|---|---|
enableMetricsReporting | boolean | No | Enable worker metrics via OpenTelemetry. Defaults to true. |
headers | Record<string, string> | No | Custom HTTP headers sent during the WebSocket handshake. |
invocationTimeoutMs | number | No | Default timeout for trigger() in milliseconds. Defaults to 30000. |
otel | Omit<OtelConfig, “engineWsUrl”> | No | OpenTelemetry configuration. OTel is initialized automatically by default. Set { enabled: false } or env OTEL_ENABLED=false/0/no/off to disable.The engineWsUrl is set automatically from the III address. |
reconnectionConfig | Partial<IIIReconnectionConfig> | No | WebSocket reconnection behavior. |
workerName | string | No | Display name for this worker. Defaults to hostname:pid. |
RegisterFunctionInput
RegisterFunctionMessage
| Name | Type | Required | Description |
|---|---|---|---|
description | string | No | The description of the function |
id | string | Yes | The path of the function (use :: for namespacing, e.g. external::my_lambda) |
invocation | HttpInvocationConfig | No | HTTP invocation config for external HTTP functions (Lambda, Cloudflare Workers, etc.) |
message_type | MessageType.RegisterFunction | Yes | - |
metadata | Record<string, unknown> | No | - |
request_format | RegisterFunctionFormat | No | The request format of the function |
response_format | RegisterFunctionFormat | No | The response format of the function |
RegisterServiceInput
RegisterTriggerInput
RegisterTriggerMessage
| Name | Type | Required | Description |
|---|---|---|---|
config | unknown | Yes | - |
function_id | string | Yes | - |
id | string | Yes | - |
message_type | MessageType.RegisterTrigger | Yes | - |
metadata | Record<string, unknown> | No | - |
type | string | Yes | - |
RegisterTriggerTypeInput
RegisterTriggerTypeMessage
| Name | Type | Required | Description |
|---|---|---|---|
description | string | Yes | - |
id | string | Yes | - |
message_type | MessageType.RegisterTriggerType | Yes | - |
RemoteFunctionHandler
Async function handler for a registered function. Receives the invocation payload and returns the result.StreamChannelRef
Serializable reference to one end of a streaming channel. Can be included in invocation payloads to pass channel endpoints between workers.| Name | Type | Required | Description |
|---|---|---|---|
access_key | string | Yes | Access key for authentication. |
channel_id | string | Yes | Unique channel identifier. |
direction | "read" | "write" | Yes | Whether this ref is for reading or writing. |
Trigger
Handle returned by ISdk.registerTrigger. Useunregister() to
remove the trigger from the engine.
| Name | Type | Required | Description |
|---|---|---|---|
unregister | void | Yes | Removes this trigger from the engine. |
TriggerHandler
Handler interface for custom trigger types. Passed toISdk.registerTriggerType.
| Name | Type | Required | Description |
|---|---|---|---|
registerTrigger | Promise<void> | Yes | Called when a trigger instance is registered. |
unregisterTrigger | Promise<void> | Yes | Called when a trigger instance is unregistered. |
TriggerInfo
Information about a registered trigger.| Name | Type | Required | Description |
|---|---|---|---|
config | unknown | No | Trigger-specific configuration. |
function_id | string | Yes | ID of the function this trigger is bound to. |
id | string | Yes | Unique trigger identifier. |
metadata | Record<string, unknown> | No | Arbitrary metadata attached to the trigger. |
trigger_type | string | Yes | Type of the trigger (e.g. http, cron, queue). |
TriggerRequest
Request object passed to ISdk.trigger.| Name | Type | Required | Description |
|---|---|---|---|
action | TriggerAction | No | Routing action. Omit for synchronous request/response. |
function_id | string | Yes | ID of the function to invoke. |
payload | TInput | Yes | Payload to pass to the function. |
timeoutMs | number | No | Override the default invocation timeout in milliseconds. |
TriggerTypeInfo
Information about a registered trigger type, returned byISdk.listTriggerTypes.
| Name | Type | Required | Description |
|---|---|---|---|
call_request_format | unknown | No | JSON Schema for the call request payload. |
description | string | Yes | Human-readable description of the trigger type. |
id | string | Yes | Trigger type identifier (e.g. http, cron, queue). |
trigger_request_format | unknown | No | JSON Schema for the trigger configuration. |
TriggerTypeRef
Typed handle returned by ISdk.registerTriggerType. Provides convenience methods to register triggers and functions scoped to this trigger type, so callers don’t need to repeat thetype field.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The trigger type identifier. |
registerFunction | FunctionRef | Yes | Register a function and immediately bind it to this trigger type. |
registerTrigger | Trigger | Yes | Register a trigger bound to this trigger type. |
unregister | void | Yes | Unregister this trigger type from the engine. |
IStream
Interface for custom stream implementations. Passed toISdk.createStream
to override the engine’s built-in stream storage.
| Name | Type | Required | Description |
|---|---|---|---|
delete | Promise<DeleteResult> | Yes | Delete a stream item. |
get | Promise<TData | null> | Yes | Retrieve a single item by group and item ID. |
list | Promise<TData[]> | Yes | List all items in a group. |
listGroups | Promise<string[]> | Yes | List all group IDs in a stream. |
set | Promise<StreamSetResult<TData> | null> | Yes | Set (create or overwrite) a stream item. |
update | Promise<StreamUpdateResult<TData> | null> | Yes | Apply atomic update operations to a stream item. |
DeleteResult
Result of a stream delete operation.| Name | Type | Required | Description |
|---|---|---|---|
old_value | any | No | Previous value (if it existed). |
StreamSetResult
Result of a stream set operation.| Name | Type | Required | Description |
|---|---|---|---|
new_value | TData | Yes | New value that was stored. |
old_value | TData | No | Previous value (if it existed). |
StreamUpdateResult
Result of a stream update operation.| Name | Type | Required | Description |
|---|---|---|---|
new_value | TData | Yes | New value after the update. |
old_value | TData | No | Previous value (if it existed). |
DeleteResult
Result of a state delete operation.| Name | Type | Required | Description |
|---|---|---|---|
old_value | any | No | Previous value (if it existed). |
IIIReconnectionConfig
Configuration for WebSocket reconnection behavior| Name | Type | Required | Description |
|---|---|---|---|
backoffMultiplier | number | Yes | Exponential backoff multiplier (default: 2) |
initialDelayMs | number | Yes | Starting delay in milliseconds (default: 1000ms) |
jitterFactor | number | Yes | Random jitter factor 0-1 (default: 0.3) |
maxDelayMs | number | Yes | Maximum delay cap in milliseconds (default: 30000ms) |
maxRetries | number | Yes | Maximum retry attempts, -1 for infinite (default: -1) |
OtelConfig
Configuration for OpenTelemetry initialization.| Name | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | Whether OpenTelemetry export is enabled. Defaults to true. Set to false or OTEL_ENABLED=false/0/no/off to disable. |
engineWsUrl | string | No | III Engine WebSocket URL. Defaults to III_URL or “ws://localhost:49134”. |
fetchInstrumentationEnabled | boolean | No | Whether to auto-instrument globalThis.fetch calls. Defaults to true. Works on Node.js, Bun, and Deno. Set to false to disable. |
instrumentations | Instrumentation<InstrumentationConfig>[] | No | OpenTelemetry instrumentations to register (e.g., PrismaInstrumentation). |
logsBatchSize | number | No | Maximum number of log records exported per batch. Defaults to 1. |
logsFlushIntervalMs | number | No | Log processor flush delay in milliseconds. Defaults to 100ms. |
metricsEnabled | boolean | No | Whether OpenTelemetry metrics export is enabled. Defaults to true. Set to false or OTEL_METRICS_ENABLED=false/0/no/off to disable. |
metricsExportIntervalMs | number | No | Metrics export interval in milliseconds. Defaults to 60000 (60 seconds). |
reconnectionConfig | Partial<ReconnectionConfig> | No | Optional reconnection configuration for the WebSocket connection. |
serviceInstanceId | string | No | The service instance ID to report. Defaults to SERVICE_INSTANCE_ID env var or auto-generated UUID. |
serviceName | string | No | The service name to report. Defaults to OTEL_SERVICE_NAME or “iii-node”. |
serviceNamespace | string | No | The service namespace to report. Defaults to SERVICE_NAMESPACE env var. |
serviceVersion | string | No | The service version to report. Defaults to SERVICE_VERSION env var or “unknown”. |
ReconnectionConfig
Configuration for WebSocket reconnection behavior| Name | Type | Required | Description |
|---|---|---|---|
backoffMultiplier | number | Yes | Exponential backoff multiplier (default: 2) |
initialDelayMs | number | Yes | Starting delay in milliseconds (default: 1000ms) |
jitterFactor | number | Yes | Random jitter factor 0-1 (default: 0.3) |
maxDelayMs | number | Yes | Maximum delay cap in milliseconds (default: 30000ms) |
maxRetries | number | Yes | Maximum retry attempts, -1 for infinite (default: -1) |
FunctionInfo
Metadata about a registered function, returned byISdk.listFunctions.
| Name | Type | Required | Description |
|---|---|---|---|
description | string | No | Human-readable description. |
function_id | string | Yes | Unique function identifier. |
metadata | Record<string, unknown> | No | Arbitrary metadata attached to the function. |
request_format | RegisterFunctionFormat | No | Schema describing expected request format. |
response_format | RegisterFunctionFormat | No | Schema describing expected response format. |
FunctionsAvailableCallback
RegisterFunctionFormat
| Name | Type | Required | Description |
|---|---|---|---|
description | string | No | The description of the parameter |
items | RegisterFunctionFormat | No | The items of the parameter |
name | string | No | The name of the parameter |
properties | Record<string, RegisterFunctionFormat> | No | The body of the parameter |
required | string[] | No | Whether the parameter is required |
type | "string" | "number" | "boolean" | "object" | "array" | "null" | "map" | Yes | The type of the parameter |