Skip to main content

​
Installation

Install the iii SDK via npm: 
npm install iii-sdk
Or with yarn: 
yarn add iii-sdk

​
Quick Start

Here’s a simple example that creates a function and exposes it via HTTP: 
import { init } from 'iii-sdk';

const iii = init('ws://localhost:49134');

iii.registerFunction({ id: 'math.add' }, async (input) => {
  return { sum: input.a + input.b };
});

iii.registerTrigger({
  type: 'http',
  function_id: 'math.add',
  config: { api_path: 'add', http_method: 'POST' },
});
Your function is now live at http://localhost:3111/add.

​
Connection

​
Initialize the SDK

Connect to the iii engine using the WebSocket URL: 
import { init } from 'iii-sdk';

const iii = init('ws://localhost:49134');
The SDK automatically connects to the engine and maintains the connection.

​
Environment Variables

You can configure the connection URL using environment variables: 
const iii = init(process.env.III_ENGINE_URL || 'ws://localhost:49134');

​
Registering Functions

​
Basic Function Registration

Register a function that can be invoked by the engine: 
iii.registerFunction({ id: 'greet.user' }, async (input) => {
  const name = input.name || 'World';
  return { message: `Hello, ${name}!` };
});

​
Function with Description

Provide metadata about your function: 
iii.registerFunction(
  {
    id: 'user.create',
    description: 'Create a new user in the database',
  },
  async (input) => {
    // Create user logic
    const user = await createUser(input);
    return { user_id: user.id, created: true };
  }
);

​
Async Operations

All function handlers support async/await: 
iii.registerFunction({ id: 'data.fetch' }, async (input) => {
  const response = await fetch(input.url);
  const data = await response.json();
  return { data };
});

​
Error Handling

Handle errors gracefully in your functions: 
iii.registerFunction({ id: 'divide' }, async (input) => {
  if (input.b === 0) {
    throw new Error('Division by zero');
  }
  return { result: input.a / input.b };
});

​
Registering Triggers

Triggers determine when and how functions are invoked. iii supports multiple trigger types.
Expose functions as HTTP endpoints:
iii.registerTrigger({
  type: 'http',
  function_id: 'math.add',
  config: {
    api_path: 'add',
    http_method: 'POST'
  },
});
Configuration options:
  • api_path: The URL path (e.g., ‘add’ → /add)
  • http_method: HTTP method (GET, POST, PUT, DELETE, PATCH)
Dynamic routes:
iii.registerTrigger({
  type: 'http',
  function_id: 'user.get',
  config: {
    api_path: 'users/:id',
    http_method: 'GET'
  },
});

​
Invoking Functions

You can invoke functions directly from your code: 
// Invoke a function and wait for the result
const result = await iii.invoke('math.add', { a: 5, b: 3 });
console.log(result.sum); // 8

​
Fire-and-Forget Invocations

Invoke a function without waiting for the result: 
// Send the invocation and continue immediately
iii.invoke('log.event', { event: 'user_login' }, { fireAndForget: true });

​
Complete Example

Here’s a full example demonstrating multiple features: 
import { init } from 'iii-sdk';

const iii = init('ws://localhost:49134');

// Register a greeting function
iii.registerFunction(
  {
    id: 'greet',
    description: 'Generate a personalized greeting',
  },
  async (input) => {
    const { name } = input;
    return { greeting: `Hello, ${name}!`, timestamp: new Date() };
  }
);

// Expose via HTTP GET
iii.registerTrigger({
  type: 'http',
  function_id: 'greet',
  config: { api_path: 'greet', http_method: 'GET' },
});

// Register a background job
iii.registerFunction(
  { id: 'process.data' },
  async (input) => {
    console.log('Processing:', input);
    // Process data...
    return { processed: true };
  }
);

// Trigger on queue messages
iii.registerTrigger({
  type: 'queue',
  function_id: 'process.data',
  config: { topic: 'data-processing' },
});

// Schedule a daily cleanup
iii.registerFunction(
  { id: 'cleanup' },
  async () => {
    console.log('Running daily cleanup...');
    // Cleanup logic
    return { cleaned: true };
  }
);

iii.registerTrigger({
  type: 'cron',
  function_id: 'cleanup',
  config: { schedule: '0 0 * * *' },
});

console.log('Worker connected and ready!');

​
API Reference

​
init(url: string)

Initialize the SDK and connect to the iii engine. Parameters:
  • url: WebSocket URL of the iii engine (default: ws://localhost:49134)
Returns: SDK instance

​
registerFunction(request, handler)

Register a function with the engine. Parameters:
  • request.id: Unique function identifier
  • request.description: Optional description
  • handler: Async function that receives input and returns output

​
registerTrigger(trigger)

Register a trigger for a function. Parameters:
  • trigger.type: Trigger type (http, queue, cron, stream)
  • trigger.function_id: ID of the function to invoke
  • trigger.config: Trigger-specific configuration

​
invoke(functionId, input, options?)

Invoke a function programmatically. Parameters:
  • functionId: ID of the function to invoke
  • input: Input data for the function
  • options.fireAndForget: Don’t wait for result (optional)
Returns: Promise resolving to function result

​
Best Practices

Use namespaced IDs like user.create, email.send, data.transform to organize your functions.
Always handle errors in your functions and return meaningful error messages.
Each function should do one thing well. Use function invocations to compose complex workflows.
The SDK supports TypeScript for better type checking and IDE support.

​
Next Steps

Python SDK

Learn about the Python SDK

Rust SDK

Learn about the Rust SDK

HTTP Module

Deep dive into HTTP triggers

Queue Module

Learn about queue-based triggers

Build docs developers (and LLMs) love

Get started for freeTalk to us