@avelon/core

@avelon/core defines the framework-neutral contracts shared by Avelon applications, adapters, and drivers. It gives you a serializable query IR, a portable request dispatcher boundary, capability-narrowed driver facades, normalized errors, and event/listener primitives. Reach for this package when you implement a driver or adapter, or when application code needs a contract without importing an implementation.

Installation

bun add @avelon/core

Basic Usage

Build a query once and pass it to a database facade whose available operations come from literal driver capabilities.

import type { Database, DatabaseDriver, QueryIR } from '@avelon/core'

type AppDatabaseDriver = DatabaseDriver<{
  transactions: true
  rowSecurity: true
  maxRelationDepth: 4
  fullTextSearch: true
  upsert: true
  returning: true
  windowFunctions: true
  jsonOperators: true
}>

export async function latestPublishedPosts(db: Database<AppDatabaseDriver>) {
  const query = {
    table: 'posts',
    mode: 'select',
    select: ['id', 'title', 'published_at'],
    where: [{ kind: 'null', column: 'published_at', negated: true }],
    relations: [],
    order: [{ column: 'published_at', direction: 'desc' }],
    limit: 20,
  } satisfies QueryIR & { mode: 'select'; conflict?: never }

  return db.execute<{ id: string; title: string; published_at: string }>(query)
}

Query IR

QueryIR is serializable and has one meaning across database compilers. Top-level where entries compose with AND, and the ward compiler injects ward as another AND predicate; application code never supplies it. Empty AND is true, empty OR is false, an empty IN list is false unless negated, and a false ward short-circuits without a database round trip. Upserts require an explicit conflict target and update list before execution. Count mode returns the number of rows matching where and ward as QueryResult.count.

import type { QueryIR } from '@avelon/core'

export const updatePost: QueryIR = {
  table: 'posts',
  mode: 'update',
  select: '*',
  where: [{ kind: 'compare', column: 'id', op: '=', value: 'post-7' }],
  relations: [],
  order: [],
  values: { title: 'Frozen contracts' },
  returning: ['id', 'title'],
}

Adapters And Kernel Dispatch

Adapters translate native requests and responses at three seams: mount, request conversion, and response conversion. Every mounted route delegates middleware, binding, validation mapping, controller dispatch, and exception mapping to Kernel. HttpRequest.rawBody() preserves signature-verification bytes, and streaming adapters accept StreamResult. A POST route exists whether the adapter uses a server action or an ordinary HTTP POST, and the adapter alone interprets an opaque view reference.

import type { Adapter, Kernel, RouteManifest } from '@avelon/core'

export async function mountApplication(
  adapter: Adapter<string, string>,
  kernel: Kernel<string, string>,
) {
  const manifest: RouteManifest<string> = {
    version: '2026-08-02',
    routes: [
      {
        name: 'posts.store',
        method: 'POST',
        path: '/posts',
        controller: 'PostController',
        action: 'store',
        middleware: ['auth'],
        bindings: {},
        api: false,
      },
    ],
  }

  return adapter.mount(manifest, { kernel })
}

Capability-Narrowed Drivers

Every driver declares literal capabilities and a named instance. Boolean capabilities add or remove method surfaces; spectra retain exact providers, MFA factors, transforms, channels, algorithms, modes, and relation depth. raw() returns the driver's generic client type without exposing an implementation in core.

import type { Storage, StorageDriver } from '@avelon/core'

type ImageDiskDriver = StorageDriver<{
  signedUrls: true
  transforms: readonly ['resize', 'format']
}>

export async function avatarUrl(storage: Storage<ImageDiskDriver>, path: string) {
  await storage.put(path, new Uint8Array([137, 80, 78, 71]), {
    contentType: 'image/png',
  })

  return storage.transform(path, 'resize', { width: 256, height: 256 })
}

Use supports() only when configuration is resolved dynamically. Static configuration should rely on the narrowed facade so unsupported methods never enter application code.

Normalized Errors

Drivers map failures into the fixed taxonomy. Each error has a stable code, framework-owned metadata, and the original failure on the standard cause property.

import { Conflict } from '@avelon/core'

export function normalizeDuplicateSlug(cause: unknown) {
  return new Conflict('A post already uses this slug.', {
    metadata: { resource: 'Post', key: 'slug' },
    cause,
  })
}

Events And Listeners

Synchronous listeners run by ascending priority and may stop propagation by returning false or calling stopPropagation(). after listeners run post-response without retry. queued listeners declare a queue, attempts, and backoff, and receive no implicit request or actor; authorization-sensitive events must carry an actor explicitly.

import { Event, defineListener } from '@avelon/core'

class PostPublished extends Event {
  constructor(
    readonly postId: string,
    readonly actorId: string,
  ) {
    super()
  }
}

export const IndexPublishedPost = defineListener<PostPublished, void, 'queued'>({
  delivery: 'queued',
  queue: 'search',
  priority: 20,
  tries: 3,
  backoff: [10, 60, 300],
  async handle(event, context) {
    console.info('indexing post', event.postId, context.attempt)
  },
})

Runtime Facades

Wave B implements the frozen contracts as process-local facades. You wire drivers with defineConfig, dispatch events through Events, authorize with Gate, validate with defineRequest, inject wards with injectWard, and run background work through Errands. Named mailers, disks, and connections never fall back to the default when the name is unknown.

import {
  DB,
  Event,
  Events,
  defineConfig,
  defineListener,
  definePolicy,
  defineWard,
  injectWard,
  mailers,
  type DatabaseDriver,
  type MailDriver,
} from '@avelon/core'

class Post {
  static readonly name = 'Post'
  static readonly table = 'posts'
}

class PostPublished extends Event {
  constructor(readonly postId: string) {
    super()
  }
}

export function boot(
  databaseDriver: DatabaseDriver,
  transactionalMail: MailDriver,
  marketingMail: MailDriver,
) {
  defineConfig({
    name: 'app',
    drivers: {
      database: databaseDriver,
      mail: {
        default: 'transactional',
        mailers: { transactional: transactionalMail, marketing: marketingMail },
      },
    },
  })

  Events.listen(
    PostPublished,
    defineListener({
      handle: (event) => {
        console.info('published', event.postId)
      },
    }),
  )

  definePolicy(Post, {
    update: (actor, post) => actor?.id === (post as { user_id: string }).user_id,
  })

  defineWard(Post, {
    read: (actor) =>
      actor ? { or: [{ published: true }, { user_id: actor.id }] } : { published: true },
    insert: (actor) => (actor ? { user_id: actor.id } : false),
    update: (actor) => (actor ? { user_id: actor.id } : false),
    delete: (actor) => (actor ? { user_id: actor.id } : false),
  })
}

export async function publishedPosts() {
  return DB.execute(
    injectWard(
      {
        table: 'posts',
        mode: 'select',
        select: '*',
        where: [],
        relations: [],
        order: [],
      },
      { published: true },
    ),
  )
}

export async function notifyMarketing() {
  return mailers.mailer('marketing').send({
    to: 'reader@example.test',
    subject: 'Published',
    text: 'A post is live.',
  })
}

The Event class stays the frozen primitive. Events is the dispatcher so application code does not add static methods to that class. mailers.mailer, disks.disk, and queues.connection exist because Mail, Storage, and Queue are frozen type aliases.

Method Reference

The table lists every public export. Capability surface interfaces describe methods that appear only when the corresponding literal capability enables them.

Testing

Driver packages provide certified fakes. When you test a package that only consumes the contract, a small structural fake keeps the exact same method surface.

import { expect, test } from 'bun:test'
import type { MailDriver } from '@avelon/core'

const sent: string[] = []
const mail = {
  name: 'memory',
  instance: 'default',
  capabilities: { templates: false } as const,
  async send(message) {
    const recipients = typeof message.to === 'string' ? [message.to] : message.to
    sent.push(...recipients)
    return { id: `message-${sent.length}`, accepted: recipients }
  },
  raw() {
    return null
  },
} satisfies MailDriver<{ templates: false }, null>

test('sends the welcome message', async () => {
  await mail.send({
    to: 'reader@example.com',
    subject: 'Welcome',
    text: 'Your account is ready.',
  })

  expect(sent).toEqual(['reader@example.com'])
})

Run the package's runtime and type-level contract tests together:

bun test
bun run typecheck