III Client

Initialize and configure the III SDK client

init()

Initialize a new III SDK instance and connect to the engine.

import { init } from 'iii-sdk'

const iii = init(address, options?)

address · string · required

WebSocket URL of the III Engine (e.g., ws://localhost:49199)

options · InitOptions

Optional configuration for the SDK instance

Show InitOptions properties

workerName · string

Custom worker name for identification. Defaults to hostname:pid

enableMetricsReporting · boolean · default: "true"

Enable automatic worker metrics reporting via OpenTelemetry

invocationTimeoutMs · number · default: "120000"

Default timeout for function invocations in milliseconds (2 minutes)

reconnectionConfig · Partial<IIIReconnectionConfig>

WebSocket reconnection behavior configuration

Show Reconnection config properties

initialDelayMs · number · default: "1000"

Initial delay before first reconnection attempt

maxDelayMs · number · default: "30000"

Maximum delay between reconnection attempts

backoffMultiplier · number · default: "2"

Exponential backoff multiplier for reconnection delays

jitterFactor · number · default: "0.3"

Random jitter factor (0-1) to prevent thundering herd

maxRetries · number · default: "-1"

Maximum retry attempts (-1 for infinite)

otel · OtelConfig

OpenTelemetry configuration. OTel is enabled by default.

Show OpenTelemetry config properties

enabled · boolean · default: "true"

Enable OpenTelemetry. Set to false or env OTEL_ENABLED=false to disable

serviceName · string · default: "iii-node"

Service name for telemetry (also reads OTEL_SERVICE_NAME env var)

serviceVersion · string · default: "unknown"

Service version (also reads SERVICE_VERSION env var)

metricsEnabled · boolean · default: "true"

Enable metrics export (also reads OTEL_METRICS_ENABLED env var)

metricsExportIntervalMs · number · default: "60000"

Metrics export interval in milliseconds

fetchInstrumentationEnabled · boolean · default: "true"

Auto-instrument fetch() calls for HTTP client tracing

instrumentations · Instrumentation[]

Custom OpenTelemetry instrumentations (e.g., PrismaInstrumentation)

telemetry · TelemetryOptions

Additional telemetry metadata

Show Telemetry options

language · string

Language/locale for telemetry

project_name · string

Project name for telemetry grouping

framework · string

Framework name (e.g., “express”, “fastify”)

iii · ISdk

An initialized III SDK instance

Example

import { init } from 'iii-sdk'

const iii = init('ws://localhost:49199', {
  workerName: 'api-worker-1',
  invocationTimeoutMs: 30000, // 30 seconds
  reconnectionConfig: {
    maxRetries: 10,
    initialDelayMs: 500
  },
  otel: {
    serviceName: 'my-api-service',
    serviceVersion: '1.0.0',
    metricsEnabled: true
  }
})

Connection Management

getConnectionState()

Get the current connection state.

const state = iii.getConnectionState()

state · IIIConnectionState

Current connection state: 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed'

onConnectionStateChange()

Register a callback to be notified of connection state changes.

const unsubscribe = iii.onConnectionStateChange((state) => {
  console.log('Connection state:', state)
})

// Later: unsubscribe
unsubscribe()

callback · (state: IIIConnectionState) => void · required

Function called when connection state changes

unsubscribe · () => void

Function to unregister the callback

Example: Connection State Handling

import { init } from 'iii-sdk'

const iii = init('ws://localhost:49199')

iii.onConnectionStateChange((state) => {
  switch (state) {
    case 'connected':
      console.log('✓ Connected to III Engine')
      break
    case 'reconnecting':
      console.warn('⟳ Reconnecting...')
      break
    case 'failed':
      console.error('✗ Connection failed')
      break
  }
})

Lifecycle Management

shutdown()

Gracefully shutdown the SDK, cleaning up all resources.

await iii.shutdown()

This method:

• Stops all metrics reporting
• Flushes and shuts down OpenTelemetry
• Rejects all pending invocations
• Closes the WebSocket connection
• Clears all callbacks

Example: Graceful Shutdown

import { init } from 'iii-sdk'

const iii = init('ws://localhost:49199')

// Handle shutdown signals
process.on('SIGINT', async () => {
  console.log('Shutting down...')
  await iii.shutdown()
  process.exit(0)
})

process.on('SIGTERM', async () => {
  console.log('Shutting down...')
  await iii.shutdown()
  process.exit(0)
})

Engine Queries

listFunctions()

List all functions registered across the III network.

const functions = await iii.listFunctions()

functions · FunctionInfo[]

Array of registered function information

Show FunctionInfo properties

function_id · string

Function ID/path

description · string

Function description

request_format · RegisterFunctionFormat

Input schema definition

response_format · RegisterFunctionFormat

Output schema definition

metadata · Record<string, unknown>

Custom function metadata

listWorkers()

List all workers connected to the engine.

const workers = await iii.listWorkers()

workers · WorkerInfo[]

Array of connected worker information

Show WorkerInfo properties

id · string

Worker unique ID

name · string

Worker name

runtime · string

Runtime identifier (e.g., “node”)

version · string

SDK version

status · WorkerStatus

Worker status: 'connected' | 'available' | 'busy' | 'disconnected'

function_count · number

Number of functions registered by this worker

active_invocations · number

Number of currently executing invocations

Example: Service Discovery

// Discover available functions
const functions = await iii.listFunctions()

console.log('Available functions:')
for (const fn of functions) {
  console.log(`- ${fn.function_id}: ${fn.description || 'No description'}`)
}

// Monitor worker health
const workers = await iii.listWorkers()

console.log(`\n${workers.length} workers online`)
for (const worker of workers) {
  console.log(`- ${worker.name}: ${worker.function_count} functions, ${worker.active_invocations} active`)
}