Node.js SDK

API reference for the iii SDK for Node.js / TypeScript.

Installation

npm install iii-sdk

Initialization

registerWorker

Creates and returns a connected SDK instance. The WebSocket connection is established automatically — there is no separate connect() call.

Signature

registerWorker(address: string, options: InitOptions) => IIIClient

Parameters

Name	Type	Required	Description
address	string	Yes	WebSocket URL of the III engine (e.g. ws://localhost:49134).
options	InitOptions	Yes	Optional InitOptions for worker name, timeouts, reconnection, and OTel.

Example

import { registerWorker } from 'iii-sdk'

const worker = registerWorker(process.env.III_URL ?? 'ws://localhost:49134', {
  workerName: 'my-worker',
})

Methods

registerTrigger

Registers a new trigger. A trigger is a way to invoke a function when a certain event occurs.

Signature

registerTrigger(trigger: RegisterTriggerInput) => Trigger

Parameters

Name	Type	Required	Description
trigger	RegisterTriggerInput	Yes	The trigger to register

Example

const trigger = worker.registerTrigger({
  type: 'cron',
  function_id: 'my-service::process-batch',
  config: { expression: '0 */5 * * * * *' },
})

// Later, remove the trigger
trigger.unregister()

registerFunction

Registers a new function with a local handler or an HTTP invocation config.

Signature

registerFunction(functionId: string, handler: HttpInvocationConfig | RemoteFunctionHandler<any, any>, options: RegisterFunctionOptions) => FunctionRef

Parameters

Name	Type	Required	Description
functionId	string	Yes	Unique function identifier
handler	HttpInvocationConfig | RemoteFunctionHandler<any, any>	Yes	Async handler for local execution, or an HTTP invocation config for external functions (Lambda, Cloudflare Workers, etc.)
options	RegisterFunctionOptions	Yes	Optional function registration options (description, request/response formats, metadata)

Example

// Local handler
const ref = worker.registerFunction(
  'greet',
  async (data: { name: string }) => ({ message: `Hello, ${data.name}!` }),
  { description: 'Returns a greeting' },
)

// HTTP invocation
const lambdaRef = worker.registerFunction(
  'external::my-lambda',
  {
    url: 'https://abc123.lambda-url.us-east-1.on.aws',
    method: 'POST',
    timeout_ms: 30_000,
    auth: { type: 'bearer', token_key: 'LAMBDA_AUTH_TOKEN' },
  },
  { description: 'Proxied Lambda function' },
)

// Later, remove the function
ref.unregister()

trigger

Invokes a function using a request object.

Signature

trigger(request: TriggerRequest<TInput>) => Promise<TOutput>

Parameters

Name	Type	Required	Description
request	TriggerRequest<TInput>	Yes	The trigger request containing function_id, payload, and optional action/timeout

Example

// Synchronous invocation
const result = await worker.trigger<{ name: string }, { message: string }>({
  function_id: 'greet',
  payload: { name: 'World' },
  timeoutMs: 5000,
})
console.log(result.message) // "Hello, World!"

// Fire-and-forget
await worker.trigger({
  function_id: 'send-email',
  payload: { to: '[e-mail]' },
  action: TriggerAction.Void(),
})

// Enqueue for async processing
const receipt = await worker.trigger({
  function_id: 'process-order',
  payload: { orderId: '123' },
  action: TriggerAction.Enqueue({ queue: 'orders' }),
})

registerTriggerType

Registers a new trigger type. A trigger type is a way to invoke a function when a certain event occurs.

Signature

registerTriggerType(triggerType: RegisterTriggerTypeInput, handler: TriggerHandler<TConfig>) => TriggerTypeRef<TConfig>

Parameters

Name	Type	Required	Description
triggerType	RegisterTriggerTypeInput	Yes	The trigger type to register
handler	TriggerHandler<TConfig>	Yes	The handler for the trigger type

Example

type CronConfig = { expression: string }

worker.registerTriggerType<CronConfig>(
  { id: 'cron', description: 'Fires on a cron schedule' },
  {
    async registerTrigger({ id, function_id, config }) {
      startCronJob(id, config.expression, () =>
        worker.trigger({ function_id, payload: {} }),
      )
    },
    async unregisterTrigger({ id }) {
      stopCronJob(id)
    },
  },
)

unregisterTriggerType

Unregisters a trigger type.

Signature

unregisterTriggerType(triggerType: RegisterTriggerTypeInput) => void

Parameters

Name	Type	Required	Description
triggerType	RegisterTriggerTypeInput	Yes	The trigger type to unregister

Example

worker.unregisterTriggerType({ id: 'cron', description: 'Fires on a cron schedule' })

shutdown

Gracefully shutdown the iii, cleaning up all resources.

Signature

shutdown() => Promise<void>

Example

process.on('SIGTERM', async () => {
  await worker.shutdown()
  process.exit(0)
})

Subpath Exports

The iii-sdk package provides additional entry points:

Import path	Contents
iii-sdk/channel	Channel, ChannelReader, ChannelWriter, StreamChannelRef
iii-sdk/engine	EngineFunctions, EngineTriggers, RemoteFunctionHandler
iii-sdk/errors	InvocationError, InvocationErrorInit, isErrorBody
iii-sdk/helpers	ChannelDirection, ChannelItem, createChannel, createStream, extractChannelRefs, isChannelRef
iii-sdk	EnqueueResult, IIIClient, InitOptions, JsonValue, MiddlewareFunctionInput, StreamRequest, StreamResponse, TelemetryOptions, TriggerAction, registerWorker
iii-sdk/internal	InternalHttpRequest
iii-sdk/protocol	ErrorBody, MessageType, RegisterFunctionFormat, RegisterFunctionInput, RegisterFunctionMessage, RegisterFunctionOptions, RegisterTriggerInput, RegisterTriggerMessage, RegisterTriggerTypeInput, RegisterTriggerTypeMessage, etc.
iii-sdk/runtime	FunctionRef, IIIConnectionState, TriggerTypeRef
iii-sdk/state	IState, StateDeleteInput, StateDeleteResult, StateEventData, StateEventType, StateGetInput, StateListInput, StateSetInput, StateSetResult, StateUpdateInput, etc.
iii-sdk/stream	IStream
iii-sdk/trigger	Trigger, TriggerConfig, TriggerHandler

Types

iii-sdk

EnqueueResult · InitOptions · JsonValue · MiddlewareFunctionInput · StreamRequest · StreamResponse · TelemetryOptions

EnqueueResult

Result returned when a function is invoked with TriggerAction.Enqueue.

Name	Type	Required	Description
messageReceiptId	string	Yes	Unique receipt ID for the enqueued message.

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.
workerDescription	string	No	One-line, human/LLM-readable summary of what this worker does. Surfaces in engine::workers::list / engine::workers::info.
workerName	string	No	Display name for this worker. Defaults to hostname:pid.

JsonValue

Any JSON value: the TypeScript equivalent of the engine’s arbitrary-JSON wire values (Rust serde_json::Value). Used where the wire contract is “any JSON”, e.g. per-invocation metadata.

type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue }

MiddlewareFunctionInput

Input passed to the RBAC middleware function on every function invocation through the RBAC port. The middleware can inspect, modify, or reject the call before it reaches the target function.

Name	Type	Required	Description
action	TriggerAction	No	Routing action, if any.
context	Record<string, unknown>	Yes	Auth context returned by the auth function for this session.
function_id	string	Yes	ID of the function being invoked.
payload	Record<string, unknown>	Yes	Payload sent by the caller.

StreamRequest

Incoming streaming request received by a function registered with a stream trigger.

type StreamRequest = Omit<InternalHttpRequest<TBody>, "response">

StreamResponse

Response object passed to streaming function handlers. Use status() and headers() to set response metadata, write to stream for streaming responses, and call close() when done.

Name	Type	Required	Description
close	() => void	Yes	Close the response.
headers	(headers: Record<string, string>) => void	Yes	Set response headers.
status	(statusCode: number) => void	Yes	Set the HTTP status code.
stream	NodeJS.WritableStream	Yes	Writable stream for the response body.

TelemetryOptions

Worker labels reported to the engine (language, framework, project).

Name	Type	Required	Description
amplitude_api_key	string	No	-
framework	string	No	-
language	string	No	-
project_name	string	No	-

iii-sdk/channel

Channel · ChannelReader · ChannelWriter · StreamChannelRef

Channel

A streaming channel pair for worker-to-worker data transfer. Created via the createChannel helper from iii-sdk/helpers.

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

ChannelReader

Read end of a streaming channel. Provides both a Node.js Readable 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.js Writable stream and a sendMessage method for sending structured text messages.

Name	Type	Required	Description
stream	Writable	Yes	Node.js Writable stream for binary data.

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.

iii-sdk/engine

RemoteFunctionHandler

RemoteFunctionHandler

Async function handler for a registered function. Receives the invocation payload and an optional per-invocation metadata value, and returns the result.

metadata is arbitrary JSON travelling on a separate channel from the payload. It is undefined when the caller did not attach any. Existing single-argument handlers keep working — they ignore the extra argument.

type RemoteFunctionHandler = (data: TInput, metadata?: JsonValue) => Promise<TOutput>

iii-sdk/errors

InvocationError · InvocationErrorInit

InvocationError

Name	Type	Required	Description
code	string	Yes	-
function_id	string	No	-
stacktrace	string	No	-

InvocationErrorInit

Typed error surfaced when an invocation dispatched over the SDK fails, RBAC rejection (FORBIDDEN), handler-level failure, or a timeout waiting for the engine to respond. Wraps the wire ErrorBody shape plus the function_id that was targeted, so callers get a single error type across all failure modes and can disambiguate via err.code.

Before this existed, rejection values were plain ErrorBody-shaped objects, which printed as [object Object] when stringified, leaving developers to grep through SDK source to figure out what tripped. The class name, code prefix in the message, and function_id field together make a rejection self-describing.

Name	Type	Required	Description
code	string	Yes	-
function_id	string	No	-
message	string	Yes	-
stacktrace	string	No	-

iii-sdk/helpers

ChannelDirection · ChannelItem

ChannelDirection

Direction of a streaming channel endpoint. Mirrors the Rust SDK’s ChannelDirection enum and matches the literal values used by StreamChannelRef.direction.

type ChannelDirection = typeof ChannelDirection[keyof typeof ChannelDirection]

ChannelItem

Discriminated runtime tag for an item observed on a streaming channel. Mirrors the Rust SDK’s ChannelItem enum (Text / Binary). Carrier for factory + type-guard helpers so callers can construct and discriminate channel items without depending on Rust-specific shape.

type ChannelItem = { type: "text"; value: string } | { type: "binary"; value: Uint8Array }

iii-sdk/internal

InternalHttpRequest

InternalHttpRequest

Name	Type	Required	Description
body	TBody	Yes	-
headers	Record<string, string | string[]>	Yes	-
method	string	Yes	-
path_params	Record<string, string>	Yes	-
query_params	Record<string, string | string[]>	Yes	-
request_body	ChannelReader	Yes	-
response	ChannelWriter	Yes	-

iii-sdk/protocol

ErrorBody · MessageType · RegisterFunctionFormat · RegisterFunctionInput · RegisterFunctionMessage · RegisterFunctionOptions · RegisterTriggerInput · RegisterTriggerMessage · RegisterTriggerTypeInput · RegisterTriggerTypeMessage · TriggerRequest

ErrorBody

Name	Type	Required	Description
code	string	Yes	-
message	string	Yes	-
stacktrace	string	No	-

MessageType

Name	Type	Required	Description
InvocationResult	"invocationresult"	Yes	-
InvokeFunction	"invokefunction"	Yes	-
RegisterFunction	"registerfunction"	Yes	-
RegisterTrigger	"registertrigger"	Yes	-
RegisterTriggerType	"registertriggertype"	Yes	-
TriggerRegistrationResult	"triggerregistrationresult"	Yes	-
UnregisterFunction	"unregisterfunction"	Yes	-
UnregisterTrigger	"unregistertrigger"	Yes	-
UnregisterTriggerType	"unregistertriggertype"	Yes	-
WorkerRegistered	"workerregistered"	Yes	-

RegisterFunctionFormat

Name	Type	Required	Description
description	string	No	The description of the parameter
items	unknown	No	The items of the parameter (for arrays)
name	string	No	The name of the parameter
properties	Record<string, unknown>	No	The body of the parameter (for objects)
required	string[]	No	Whether the parameter is required
type	"string" | "number" | "boolean" | "object" | "array" | "null" | "map" | "integer"	No	The type of the parameter

RegisterFunctionInput

type RegisterFunctionInput = Omit<RegisterFunctionMessage, "message_type">

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

RegisterFunctionOptions

type RegisterFunctionOptions = Omit<RegisterFunctionMessage, "message_type" | "id">

RegisterTriggerInput

type RegisterTriggerInput = Omit<RegisterTriggerMessage, "message_type" | "id">

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

type RegisterTriggerTypeInput = Omit<RegisterTriggerTypeMessage, "message_type">

RegisterTriggerTypeMessage

Name	Type	Required	Description
description	string	Yes	-
id	string	Yes	-
message_type	MessageType.RegisterTriggerType	Yes	-

TriggerRequest

Request object passed to IIIClient.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.
metadata	unknown	No	Optional per-invocation metadata (arbitrary JSON). Travels as a separate channel from the payload and is surfaced to the target handler as a dedicated argument. Omitted from the wire message when undefined.
payload	TInput	Yes	Payload to pass to the function.
timeoutMs	number	No	Override the default invocation timeout in milliseconds.

iii-sdk/runtime

FunctionRef · IIIConnectionState · TriggerTypeRef

FunctionRef

Handle returned by IIIClient.registerFunction. Contains the function’s id and an unregister() method.

Name	Type	Required	Description
id	string	Yes	The unique function identifier.
unregister	() => void	Yes	Removes this function from the engine.

IIIConnectionState

Connection state for the III WebSocket

type IIIConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting" | "failed"

TriggerTypeRef

Typed handle returned by IIIClient.registerTriggerType.

Provides convenience methods to register triggers and functions scoped to this trigger type, so callers don’t need to repeat the type 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.

iii-sdk/state

IState · StateDeleteInput · StateDeleteResult · StateEventData · StateEventType · StateGetInput · StateListInput · StateSetInput · StateSetResult · StateUpdateInput · StateUpdateResult

IState

Interface for state management operations. Available via the iii-sdk/state subpath export.

Name	Type	Required	Description
delete	Promise<StateDeleteResult>	Yes	Delete a state value.
get	Promise<TData | null>	Yes	Retrieve a value by scope and key.
list	Promise<TData[]>	Yes	List all values in a scope.
set	Promise<StateSetResult<TData> | null>	Yes	Set (create or overwrite) a state value.
update	Promise<StateUpdateResult<TData> | null>	Yes	Apply atomic update operations to a state value.

StateDeleteInput

Input for deleting a state value.

Name	Type	Required	Description
key	string	Yes	Key within the scope.
scope	string	Yes	State scope (namespace).

StateDeleteResult

Result of a state delete operation.

Name	Type	Required	Description
old_value	any	No	Previous value (if it existed).

StateEventData

Payload for state change events.

Name	Type	Required	Description
event_type	StateEventType	Yes	Type of state change.
key	string	Yes	Key within the scope.
new_value	TData	No	New value (for create/update events).
old_value	TData	No	Previous value (for update/delete events).
scope	string	Yes	State scope (namespace).
type	"state"	Yes	-

StateEventType

Types of state change events.

Name	Type	Required	Description
Created	"state:created"	Yes	-
Deleted	"state:deleted"	Yes	-
Updated	"state:updated"	Yes	-

StateGetInput

Input for retrieving a state value.

Name	Type	Required	Description
key	string	Yes	Key within the scope.
scope	string	Yes	State scope (namespace).

StateListInput

Input for listing all values in a state scope.

Name	Type	Required	Description
scope	string	Yes	State scope (namespace).

StateSetInput

Input for setting a state value.

Name	Type	Required	Description
key	string	Yes	Key within the scope.
scope	string	Yes	State scope (namespace).
value	any	Yes	Value to store.

StateSetResult

Result of a state set operation.

Name	Type	Required	Description
new_value	TData	Yes	New value that was stored.
old_value	TData	No	Previous value (if it existed).

StateUpdateInput

Input for atomically updating a state value.

Name	Type	Required	Description
key	string	Yes	Key within the scope.
ops	UpdateOp[]	Yes	Ordered list of update operations to apply atomically.
scope	string	Yes	State scope (namespace).

StateUpdateResult

Result of a state update operation.

Name	Type	Required	Description
errors	UpdateOpError[]	No	Per-op errors. Currently emitted only by the merge op when input violates the validation bounds. See UpdateOpError and the UpdateMerge JSDoc in ./stream for the error codes. Field is omitted from the JSON wire when empty.
new_value	TData	Yes	New value after the update.
old_value	TData	No	Previous value (if it existed).

iii-sdk/stream

IStream

IStream

Interface for custom stream implementations. Passed to IIIClient.createStream to override the engine’s built-in stream storage.

Name	Type	Required	Description
delete	Promise<StreamDeleteResult>	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.

iii-sdk/trigger

Trigger · TriggerConfig · TriggerHandler

Trigger

Handle returned by IIIClient.registerTrigger. Use unregister() to remove the trigger from the engine.

Name	Type	Required	Description
unregister	void	Yes	Removes this trigger from the engine.

TriggerConfig

Configuration passed to a trigger handler when a trigger instance is registered or unregistered.

Name	Type	Required	Description
config	TConfig	Yes	Trigger-specific configuration.
function_id	string	Yes	Function to invoke when the trigger fires.
id	string	Yes	Trigger instance ID.
metadata	Record<string, unknown>	No	Arbitrary metadata attached to the trigger.

TriggerHandler

Handler interface for custom trigger types. Passed to IIIClient.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.