Browser SDK

API reference for the iii SDK for Browser / TypeScript.

Installation

npm install iii-browser-sdk

Initialization

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

import { registerWorker } from 'iii-browser-sdk'

const iii = registerWorker('ws://localhost:49135')

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.

Signature

createChannel(bufferSize: number) => Promise<Channel>

Parameters

Name	Type	Required	Description
bufferSize	number	Yes	Optional buffer size for the channel (default: 64)

Example

const channel = await iii.createChannel()

// Pass the writer ref to another function
await iii.trigger({
  function_id: 'stream-producer',
  payload: { outputChannel: channel.writerRef },
})

// Read data locally
channel.reader.onMessage((msg) => {
  console.log('Received:', msg)
})

createStream

Creates a new stream implementation.

This overrides the default stream implementation.

Signature

createStream(streamName: string, stream: IStream<TData>) => void

Parameters

Name	Type	Required	Description
streamName	string	Yes	The name of the stream
stream	IStream<TData>	Yes	The stream implementation

Example

iii.createStream('sessions', {
  async get({ group_id, item_id }) { return null },
  async set({ group_id, item_id, data }) { return { new_value: data } },
  async delete({ group_id, item_id }) { return {} },
  async list({ group_id }) { return [] },
  async listGroups() { return [] },
  async update() { return null },
})

listFunctions

Lists all registered functions.

Signature

listFunctions() => Promise<FunctionInfo[]>

Example

const functions = await iii.listFunctions()
for (const fn of functions) {
  console.log(`${fn.function_id}: ${fn.description}`)
}

listTriggers

Lists all registered triggers.

Signature

listTriggers(includeInternal: boolean) => Promise<TriggerInfo[]>

Parameters

Name	Type	Required	Description
includeInternal	boolean	Yes	Whether to include internal triggers (default: false)

listTriggerTypes

Lists all trigger types registered with the engine.

Signature

listTriggerTypes(includeInternal: boolean) => Promise<TriggerTypeInfo[]>

Parameters

Name	Type	Required	Description
includeInternal	boolean	Yes	Whether to include internal trigger types (default: false)

Example

const triggerTypes = await iii.listTriggerTypes()
for (const tt of triggerTypes) {
  console.log(`${tt.id}: ${tt.description}`)
}

onFunctionsAvailable

Registers a callback to receive the current functions list when the engine announces changes.

Signature

onFunctionsAvailable(callback: FunctionsAvailableCallback) => () => void

Parameters

Name	Type	Required	Description
callback	FunctionsAvailableCallback	Yes	-

Example

const unsubscribe = iii.onFunctionsAvailable((functions) => {
  console.log(`${functions.length} functions available:`)
  for (const fn of functions) {
    console.log(`  - ${fn.function_id}`)
  }
})

// Later, stop listening
unsubscribe()

registerFunction

Signature

registerFunction(func: RegisterFunctionInput, handler: RemoteFunctionHandler) => FunctionRef

Parameters

Name	Type	Required	Description
func	RegisterFunctionInput	Yes	-
handler	RemoteFunctionHandler	Yes	-

registerService

Registers a new service.

Signature

registerService(message: RegisterServiceInput) => void

Parameters

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.

Signature

registerTrigger(trigger: RegisterTriggerInput) => Trigger

Parameters

Name	Type	Required	Description
trigger	RegisterTriggerInput	Yes	The trigger to register

Example

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

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

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 = { schedule: string }

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

shutdown

Gracefully shutdown the iii, cleaning up all resources.

Signature

shutdown() => Promise<void>

Example

await iii.shutdown()

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 iii.trigger<{ name: string }, { message: string }>({
  function_id: 'greet',
  payload: { name: 'World' },
  timeoutMs: 5000,
})
console.log(result.message) // "Hello, World!"

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

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

unregisterTriggerType

Unregisters a trigger type.

Signature

unregisterTriggerType(triggerType: RegisterTriggerTypeInput) => void

Parameters

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

Example

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

Subpath Exports

The iii-sdk package provides additional entry points:

Import path	Contents
iii-sdk	MessageType, ChannelReader, ChannelWriter, ISdk, ApiRequest, ApiResponse, AuthInput, AuthResult, Channel, EnqueueResult, 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.

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

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. Uses native browser WebSocket.

ChannelWriter

Write end of a streaming channel. Uses native browser WebSocket.

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

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.

type HttpAuthConfig = unknown | unknown | unknown

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
headers	Record<string, string>	No	Custom headers are not supported by browser WebSocket. Use query parameters or cookies for auth.
invocationTimeoutMs	number	No	Default timeout for trigger() in milliseconds. Defaults to 30000.
reconnectionConfig	Partial<IIIReconnectionConfig>	No	WebSocket reconnection behavior.

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

RegisterServiceInput

type RegisterServiceInput = Omit<RegisterServiceMessage, "message_type">

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

RemoteFunctionHandler

Async function handler for a registered function. Receives the invocation payload and returns the result.

type RemoteFunctionHandler = (data: TInput) => Promise<TOutput>

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. Use unregister() 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 to ISdk.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.
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 by ISdk.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 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.

IStream

Interface for custom stream implementations. Passed to ISdk.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).