Node.js SDK

pnpm add iii-sdk
# or: npm install iii-sdk

import { registerWorker } from 'iii-sdk'

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

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

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(streamName: string, stream: IStream<TData>) => void

const redisStream: IStream<UserSession> = {
  async get({ group_id, item_id }) {
    return JSON.parse(await redis.get(`${group_id}:${item_id}`) ?? 'null')
  },
  async set({ group_id, item_id, data }) {
    const old = await this.get({ stream_name: 'sessions', group_id, item_id })
    await redis.set(`${group_id}:${item_id}`, JSON.stringify(data))
    return { old_value: old ?? undefined, new_value: data }
  },
  async delete({ group_id, item_id }) {
    const old = await this.get({ stream_name: 'sessions', group_id, item_id })
    await redis.del(`${group_id}:${item_id}`)
    return { old_value: old ?? undefined }
  },
  async list({ group_id }) { return [] },
  async listGroups() { return [] },
  async update({ group_id, item_id, ops }) { return { new_value: {} } },
}

iii.createStream('sessions', redisStream)

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

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

// HTTP invocation
const lambdaRef = iii.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()

registerService(message: RegisterServiceInput) => void

registerTrigger(trigger: RegisterTriggerInput) => Trigger

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

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

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

type CronConfig = { expression: string }

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

shutdown() => Promise<void>

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

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

// 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: 'user@example.com' },
  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(triggerType: RegisterTriggerTypeInput) => void

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

debug(message: string, data: unknown) => void

logger.debug('Cache lookup', { key: 'user:42', hit: false })

error(message: string, data: unknown) => void

logger.error('Payment failed', { orderId: 'ord_123', gateway: 'stripe', errorCode: 'card_declined' })

info(message: string, data: unknown) => void

logger.info('Order processed', { orderId: 'ord_123', status: 'completed' })

warn(message: string, data: unknown) => void

logger.warn('Retry attempt', { attempt: 3, maxRetries: 5, endpoint: '/api/charge' })

type HttpAuthConfig = unknown | unknown | unknown

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

type RegisterServiceInput = Omit<RegisterServiceMessage, "message_type">

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

type RegisterTriggerTypeInput = Omit<RegisterTriggerTypeMessage, "message_type">

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