Getting Started

Installation

npm install @yellatech/conduit

Conduit includes the Engine as a dependency: no separate install needed.

Hello World

import { createConduit } from '@yellatech/conduit'

const app = createConduit()

app.process({
  name: 'greet',
  on: 'user:signup',
  run: async (ctx) => {
    const { name } = ctx.payload as { name: string }
    console.log(`Welcome, ${name}!`)
    return { success: true }
  },
})

await app.emitAndWait('user:signup', { name: 'Alice' })
await app.stop()

Without any connectors, Conduit behaves like a plain Engine. The power comes when you add connectors.

Adding a Connector

import { createConduit, defineConnector } from '@yellatech/conduit'

const app = createConduit({
  engine: { store: { type: 'sqlite', path: './app.db' } },
})

await app.connector(defineConnector({
  name: 'webhook',
  version: '1.0.0',
  events: { received: { description: 'Inbound webhook payload' } },
  setup: (ctx) => ({
    start() {
      ctx.routes.post('/hook', async (c) => {
        ctx.emit('received', await c.req.json())
        return c.json({ ok: true })
      })
    },
  }),
}))

app.process({
  name: 'handle-webhook',
  on: 'webhook:received',
  run: async (ctx) => {
    await ctx.effect('process', () => processPayload(ctx.payload))
    return { success: true, payload: { processed: true } }
  },
})

await app.listen(3000)

POST to http://localhost:3000/hook and the payload flows through the engine with full persistence, retry, and durable effects.

What Just Happened

  1. createConduit() wraps the Engine with connector management and an HTTP server.
  2. defineConnector() declares a connector with named events and a setup function. The setup callback receives a context with emit() for producing events and routes for registering HTTP endpoints.
  3. Event prefixing: connector events arrive as connectorName:eventName. The webhook connector emits received, which becomes webhook:received in your process handlers.
  4. ctx.effect(key, fn) provides durable side effects: same as the Engine. If a run retries, effects replay their stored result instead of re-executing.
  5. app.listen(3000) starts the HTTP server. The dashboard is available at http://localhost:3000/.

Next Steps