Quickstart

Get started with the III Node.js SDK in minutes

Initialize the SDK

Connect to the III Engine by initializing the SDK with your engine’s WebSocket URL:

import { init } from 'iii-sdk'

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

The SDK automatically:

• Establishes a WebSocket connection to the engine
• Initializes OpenTelemetry for distributed tracing
• Sets up automatic reconnection on connection loss

Register a Function

Functions are the building blocks of III applications. Register a function to make it callable by other services:

const echoFunction = iii.registerFunction(
  { id: 'my_service::echo' },
  async (data: { message: string }) => {
    return { echoed: data.message }
  }
)

Use :: to namespace your functions (e.g., service::function_name). This helps organize functions by service.

Call a Function

Call any registered function across the III network:

const result = await iii.call<{ message: string }, { echoed: string }>(
  'my_service::echo',
  { message: 'Hello, III!' }
)

console.log(result.echoed) // "Hello, III!"

Access Context

Every function handler has access to a context with a logger and trace span:

import { getContext } from 'iii-sdk'

iii.registerFunction(
  { id: 'my_service::process' },
  async (data: { items: string[] }) => {
    const { logger, trace } = getContext()
    
    logger.info('Processing items', { count: data.items.length })
    
    // Add custom trace attributes
    trace?.setAttribute('item.count', data.items.length)
    
    return { processed: data.items.length }
  }
)

Register an HTTP Trigger

Expose functions as HTTP endpoints:

// Register the function
const apiFunction = iii.registerFunction(
  { id: 'api::get_user' },
  async (req: HttpRequest): Promise<ApiResponse> => {
    const userId = req.path_params.id
    
    return {
      status_code: 200,
      body: { id: userId, name: 'John Doe' }
    }
  }
)

// Register the HTTP trigger
const trigger = iii.registerTrigger({
  type: 'http',
  function_id: 'api::get_user',
  config: {
    api_path: 'users/:id',
    http_method: 'GET'
  }
})

The endpoint will be available at http://localhost:3199/users/:id (default engine HTTP port).

Complete Example

Here’s a complete application that registers a function and an HTTP endpoint:

import { init, getContext, type HttpRequest, type ApiResponse } from 'iii-sdk'

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

// Business logic function
iii.registerFunction(
  { 
    id: 'tasks::create',
    description: 'Create a new task'
  },
  async (data: { title: string; description: string }) => {
    const { logger } = getContext()
    
    logger.info('Creating task', { title: data.title })
    
    const task = {
      id: crypto.randomUUID(),
      title: data.title,
      description: data.description,
      created_at: new Date().toISOString()
    }
    
    return task
  }
)

// HTTP endpoint
iii.registerFunction(
  { id: 'api::create_task' },
  async (req: HttpRequest): Promise<ApiResponse> => {
    const body = req.body as { title: string; description: string }
    
    // Call the business logic function
    const task = await iii.call('tasks::create', body)
    
    return {
      status_code: 201,
      body: task
    }
  }
)

iii.registerTrigger({
  type: 'http',
  function_id: 'api::create_task',
  config: {
    api_path: 'tasks',
    http_method: 'POST'
  }
})

console.log('Service started! Available endpoints:')
console.log('POST http://localhost:3199/tasks')

Next Steps

Functions

Learn about function handlers and registration

Triggers

Explore trigger types and HTTP endpoints

Context

Use context for logging and tracing

Channels

Stream data between functions