@openverb/runtime

The execution runtime for the OpenVerb Framework - a verb-driven application architecture.

Installation

npm install @openverb/runtime

Quick Start

import { createRuntime, loadVerbs } from '@openverb/runtime'

// Load verb definitions
const verbs = loadVerbs('./verbs')

// Create runtime
const runtime = createRuntime({
  verbs,
  handlers: {
    'handlers/example': async (ctx, args) => {
      return { success: true, data: args }
    }
  },
  adapters: {
    db: myDatabaseAdapter,
    logger: console
  }
})

// Execute a verb
const result = await runtime.execute({
  verbId: 'example.action',
  args: { name: 'test' },
  actor: { type: 'user', id: 'user-123' },
  context: {
    tenantId: 'tenant-1',
    planId: 'free',
    env: 'production',
    requestId: crypto.randomUUID()
  }
})

console.log(result)
// {
//   ok: true,
//   result: { success: true, data: { name: 'test' } },
//   receipt: { ... },
//   events: [ ... ]
// }

Core Concepts

Verbs

Verbs are JSON definitions that describe actions in your application:

{
  "id": "user.create",
  "version": "1.0.0",
  "summary": "Create a new user",
  "inputSchema": { "type": "object", "properties": { ... } },
  "outputSchema": { "type": "object", "properties": { ... } },
  "effects": ["db.write", "email.send"],
  "handler": "handlers/user/create"
}

Handlers

Handler functions implement the business logic:

import type { HandlerContext } from '@openverb/runtime'

export async function handler(
  ctx: HandlerContext,
  args: { email: string; name: string }
) {
  // Access adapters
  await ctx.adapters.db.insert('users', { email: args.email })
  
  // Emit events
  ctx.emitEvent({ type: 'user.created', data: { email: args.email } })
  
  return { userId: '123', email: args.email }
}

Adapters

Adapters provide access to external services:

const adapters = {
  db: {
    insert: async (table, data) => { /* ... */ },
    query: async (sql, params) => { /* ... */ }
  },
  logger: console,
  email: emailService
}

API Reference

createRuntime(config)

Creates a new runtime instance.

Parameters:

• config.verbs - Array of verb definitions
• config.handlers - Map of handler functions
• config.adapters - External service adapters
• config.policy? - Optional policy engine

Returns: Runtime instance

loadVerbs(directory)

Loads verb definitions from a directory.

Parameters:

• directory - Path to directory containing .json verb files

Returns: Array of verb definitions

runtime.execute(request)

Executes a verb.

Parameters:

• request.verbId - ID of verb to execute
• request.args - Arguments for the verb
• request.actor - User/system making the request
• request.context - Execution context (tenant, plan, etc.)

Returns: ExecuteResponse with result, receipt, and events

Related Packages

• @openverb/policy - Policy engine for authorization
• @openverb/sdk - Client SDK with React hooks
• @openverb/cli - CLI tools for developers

License

MIT