@avelonjs/core 0.1.0

package/src/index.ts

@@ -0,0 +1,22 @@
+export * from './adapter'
+export * from './drivers/common'
+export * from './drivers/ai'
+export * from './drivers/database'
+export * from './drivers/flags'
+export * from './drivers/identity'
+export * from './drivers/cache'
+export * from './drivers/logs'
+export * from './drivers/mail'
+export * from './drivers/notifications'
+export * from './drivers/payments'
+export * from './drivers/queue'
+export * from './drivers/ratelimit'
+export * from './drivers/realtime'
+export * from './drivers/search'
+export * from './drivers/social'
+export * from './drivers/storage'
+export * from './drivers/tokens'
+export * from './errors'
+export * from './events'
+export * from './query'
+export * from './runtime'

package/src/query.ts

@@ -0,0 +1,86 @@
+/** Comparison operators with portable SQL three-valued semantics. */
+export type CompareOp = '=' | '!=' | '<' | '<=' | '>' | '>=' | 'like' | 'ilike'
+
+/** A stable ordering term for a query or relation load. */
+export interface OrderTerm {
+  /** Column to order by. */
+  column: string
+  /** Sort direction. */
+  direction: 'asc' | 'desc'
+  /** Explicit placement for null values. */
+  nulls?: 'first' | 'last'
+}
+
+/** A relation the database driver should load with the parent query. */
+export interface RelationLoad {
+  /** Relation name declared on the model and used as the result key. */
+  relation: string
+  /** Cardinality of the declared relation. */
+  kind: 'belongsTo' | 'hasOne' | 'hasMany'
+  /** Related table resolved by the model layer. */
+  table: string
+  /** Column on the parent row. */
+  localKey: string
+  /** Column on the related table. */
+  foreignKey: string
+  /** Columns to return from the related table. */
+  select: string[] | '*'
+  /** Predicate applied to related rows, or null when unfiltered. */
+  where: Predicate | null
+  /** Stable ordering applied to related rows. */
+  order: OrderTerm[]
+  /** Maximum related rows to load per parent. */
+  limit?: number
+  /** Nested relation loads checked against the driver's maximum depth. */
+  relations: RelationLoad[]
+}
+
+/**
+ * Serializable query representation produced by the model layer and compiled by a database
+ * driver.
+ */
+export interface QueryIR {
+  /** Table the operation targets. */
+  table: string
+  /**
+   * Operation to compile. Count mode matches `where` AND `ward`; `select`, `relations`, and `order`
+   * must be empty, while `limit` and `offset` must be absent.
+   */
+  mode: 'select' | 'count' | 'insert' | 'update' | 'delete' | 'upsert'
+  /** Columns to select. */
+  select: string[] | '*'
+  /** Predicates composed with AND. */
+  where: Predicate[]
+  /** Relations to eager load. */
+  relations: RelationLoad[]
+  /** Stable ordering terms applied in sequence. */
+  order: OrderTerm[]
+  /** Maximum number of rows to return. */
+  limit?: number
+  /** Number of rows to skip. */
+  offset?: number
+  /** Values used by insert, update, and upsert operations. */
+  values?: Record<string, unknown> | Record<string, unknown>[]
+  /** Columns returned after a write. */
+  returning?: string[] | '*'
+  /**
+   * Explicit conflict target and update columns required by upserts. `update: '*'` updates every
+   * supplied value column not named in `conflict.columns`.
+   */
+  conflict?: { columns: [string, ...string[]]; update: [string, ...string[]] | '*' }
+  /** Ward predicate injected by the ward compiler and ANDed with `where`. Never author-supplied. */
+  ward?: Predicate
+}
+
+/**
+ * Portable predicate tree. Empty AND is true, empty OR is false, and an empty IN list is false
+ * unless negated.
+ */
+export type Predicate =
+  | { kind: 'const'; value: boolean }
+  | { kind: 'compare'; column: string; op: CompareOp; value: unknown }
+  | { kind: 'null'; column: string; negated: boolean }
+  | { kind: 'in'; column: string; values: unknown[]; negated: boolean }
+  | { kind: 'and'; predicates: Predicate[] }
+  | { kind: 'or'; predicates: Predicate[] }
+  | { kind: 'not'; predicate: Predicate }

package/src/runtime/config.ts

@@ -0,0 +1,231 @@
+import type { Adapter, RequestCookies } from '../adapter'
+import type { DatabaseDriver } from '../drivers/database'
+import type { IdentityDriver } from '../drivers/identity'
+import type { MailDriver } from '../drivers/mail'
+import type { QueueDriver } from '../drivers/queue'
+import type { StorageDriver } from '../drivers/storage'
+import { Invalid, Unavailable } from '../errors'
+
+/** Named driver registry resolved by facades such as `DB.connection` and `Mail.mailer`. */
+export interface NamedDrivers<TDriver> {
+  /** Name of the default instance. Unknown names never fall back to this value. */
+  readonly default: string
+  /** Drivers keyed by instance name. Also accepts `connections`, `mailers`, or `disks`. */
+  readonly instances?: Readonly<Record<string, TDriver>>
+  /** Database named-connection map. */
+  readonly connections?: Readonly<Record<string, TDriver>>
+  /** Mail named-mailer map. */
+  readonly mailers?: Readonly<Record<string, TDriver>>
+  /** Storage named-disk map. */
+  readonly disks?: Readonly<Record<string, TDriver>>
+}
+
+/** A single driver or a named registry of drivers. */
+export type MaybeNamed<TDriver> = TDriver | NamedDrivers<TDriver>
+
+/** Driver wiring accepted by {@link defineConfig}. Every contract is optional until configured. */
+export interface AvelonDrivers {
+  database?: MaybeNamed<DatabaseDriver>
+  identity?: (cookies: RequestCookies) => IdentityDriver
+  mail?: MaybeNamed<MailDriver>
+  storage?: MaybeNamed<StorageDriver>
+  queue?: MaybeNamed<QueueDriver>
+}
+
+/** Application configuration accepted by the service registry. */
+export interface AvelonConfig {
+  /** Application name used in diagnostics. */
+  name?: string
+  /** Optional adapter. Wave C mounts routes; Wave B only stores the reference. */
+  adapter?: Adapter
+  /** Driver wiring for the current environment. */
+  drivers: AvelonDrivers
+}
+
+let activeConfig: AvelonConfig | undefined
+
+function isNamedDrivers<TDriver>(value: MaybeNamed<TDriver>): value is NamedDrivers<TDriver> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'default' in value &&
+    typeof Reflect.get(value, 'default') === 'string' &&
+    (Reflect.has(value, 'instances') ||
+      Reflect.has(value, 'connections') ||
+      Reflect.has(value, 'mailers') ||
+      Reflect.has(value, 'disks'))
+  )
+}
+
+function namedMap<TDriver>(registry: NamedDrivers<TDriver>): Readonly<Record<string, TDriver>> {
+  return registry.instances ?? registry.connections ?? registry.mailers ?? registry.disks ?? {}
+}
+
+/**
+ * Resolves a named driver. An unknown name is `Invalid`; it never silently uses the default.
+ */
+export function resolveNamedDriver<TDriver extends object>(
+  value: MaybeNamed<TDriver> | undefined,
+  name: string | undefined,
+  kind: string,
+): TDriver {
+  if (value === undefined) {
+    throw new Unavailable(`${kind} is not configured.`, {
+      metadata: { service: kind },
+    })
+  }
+  if (!isNamedDrivers(value)) {
+    const instance = Reflect.get(value, 'instance')
+    const resolvedName = name ?? (typeof instance === 'string' ? instance : 'default')
+    if (typeof instance === 'string' && instance !== resolvedName) {
+      throw new Invalid(`Unknown ${kind} '${resolvedName}'.`, {
+        metadata: { fields: { [kind]: [`${resolvedName} is not a configured ${kind}.`] } },
+      })
+    }
+    if (name !== undefined && name !== 'default' && instance !== name) {
+      throw new Invalid(`Unknown ${kind} '${name}'.`, {
+        metadata: { fields: { [kind]: [`${name} is not a configured ${kind}.`] } },
+      })
+    }
+    return value
+  }
+  const map = namedMap(value)
+  const key = name ?? value.default
+  const driver = map[key]
+  if (driver === undefined) {
+    throw new Invalid(`Unknown ${kind} '${key}'.`, {
+      metadata: { fields: { [kind]: [`${key} is not a configured ${kind}.`] } },
+    })
+  }
+  return driver
+}
+
+function mergeConfig(base: AvelonConfig, overlay: Partial<AvelonConfig>): AvelonConfig {
+  return {
+    ...base,
+    ...overlay,
+    drivers: {
+      ...base.drivers,
+      ...overlay.drivers,
+    },
+  }
+}
+
+/**
+ * Registers process-wide configuration. The optional overlay is merged on top so per-environment
+ * files can replace driver wiring without copying the whole config.
+ */
+export function defineConfig<T extends AvelonConfig>(
+  config: T,
+  environment: Partial<AvelonConfig> = {},
+): T {
+  activeConfig = mergeConfig(config, environment)
+  return activeConfig as T
+}
+
+/** Returns the active configuration or throws when wiring is missing. */
+export function getConfig(): AvelonConfig {
+  if (activeConfig === undefined) {
+    throw new Unavailable('Avelon config has not been defined.', {
+      metadata: { service: 'config' },
+    })
+  }
+  return activeConfig
+}
+
+/** Clears config state. Intended for tests. */
+export function resetConfig(): void {
+  activeConfig = undefined
+}
+
+/** Database facade bound to the configured driver, including named connections. */
+export const DB = {
+  /** Returns the configured database driver for `name`, or the default connection. */
+  connection(name?: string): DatabaseDriver {
+    return resolveNamedDriver(getConfig().drivers.database, name, 'connection')
+  },
+  /** Default database driver. */
+  get driver(): DatabaseDriver {
+    return DB.connection()
+  },
+  execute: (...args: Parameters<DatabaseDriver['execute']>) => DB.connection().execute(...args),
+  rpc: (...args: Parameters<DatabaseDriver['rpc']>) => DB.connection().rpc(...args),
+  plan: () => DB.connection().plan(),
+  apply: () => DB.connection().apply(),
+  rollback: (steps?: number) => DB.connection().rollback(steps),
+  status: () => DB.connection().status(),
+  // bailiff-disable-next-line no-raw-outside-drivers -- facade passthrough; app raw() stays banned
+  raw: () => DB.connection().raw(),
+}
+
+/** Mail facade that resolves named mailers without falling back on unknown names. */
+export const mailers = {
+  /** Returns the configured mailer for `name`, or the default mailer. */
+  mailer(name?: string): MailDriver {
+    return resolveNamedDriver(getConfig().drivers.mail, name, 'mailer')
+  },
+}
+
+/** Storage facade that resolves named disks without falling back on unknown names. */
+export const disks = {
+  /** Returns the configured disk for `name`, or the default disk. */
+  disk(name?: string): StorageDriver {
+    return resolveNamedDriver(getConfig().drivers.storage, name, 'disk')
+  },
+}
+
+/** Queue facade that resolves named connections without falling back on unknown names. */
+export const queues = {
+  /** Returns the configured queue connection for `name`, or the default connection. */
+  connection(name?: string): QueueDriver {
+    return resolveNamedDriver(getConfig().drivers.queue, name, 'queue')
+  },
+}
+
+/**
+ * Creates the request-scoped identity driver from configured wiring.
+ *
+ * Named `auth` rather than `Auth` so it does not collide with the `Auth` type alias exported from
+ * the identity contract.
+ */
+export function auth(cookies: RequestCookies): IdentityDriver {
+  const factory = getConfig().drivers.identity
+  if (factory === undefined) {
+    throw new Unavailable('identity is not configured.', { metadata: { service: 'identity' } })
+  }
+  return factory(cookies)
+}
+
+/** Literal capability matrix for every configured driver instance. */
+export function capabilityMatrix(
+  config: AvelonConfig = getConfig(),
+): Readonly<Record<string, Readonly<Record<string, unknown>>>> {
+  const matrix: Record<string, Record<string, unknown>> = {}
+
+  const collect = (contract: string, value: MaybeNamed<DriverLike> | undefined): void => {
+    if (value === undefined) return
+    if (!isNamedDrivers(value)) {
+      matrix[contract] = {
+        [value.instance]: { name: value.name, capabilities: value.capabilities },
+      }
+      return
+    }
+    const instances: Record<string, unknown> = {}
+    for (const [key, driver] of Object.entries(namedMap(value))) {
+      instances[key] = { name: driver.name, capabilities: driver.capabilities }
+    }
+    matrix[contract] = { default: value.default, instances }
+  }
+
+  collect('database', config.drivers.database)
+  collect('mail', config.drivers.mail)
+  collect('storage', config.drivers.storage)
+  collect('queue', config.drivers.queue)
+  return matrix
+}
+
+interface DriverLike {
+  readonly name: string
+  readonly instance: string
+  readonly capabilities: object
+}

package/src/runtime/dispatcher.ts

@@ -0,0 +1,335 @@
+import type { QueueDriver } from '../drivers/queue'
+import {
+  Event,
+  type EventConstructor,
+  type EventDispatchOptions,
+  type EventDispatcher,
+  type EventSerializer,
+  type EventSubscriber,
+  type ListenerDefinition,
+  type ListenerResult,
+  type QueuedEventEnvelope,
+  type SerializedEvent,
+} from '../events'
+import { backoffSeconds, jobBoard } from './jobs'
+import { holdUntilCommit, isInTransaction } from './transaction'
+
+interface StoredRegistration {
+  event?: EventConstructor
+  pattern?: string
+  listener: ListenerDefinition<Event>
+}
+
+class JsonEventSerializer implements EventSerializer {
+  readonly #constructors = new Map<string, EventConstructor>()
+
+  register(event: EventConstructor): void {
+    this.#constructors.set(event.name, event)
+  }
+
+  async serialize(event: Event): Promise<SerializedEvent> {
+    const payload: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(event as unknown as Record<string, unknown>)) {
+      payload[key] = value
+    }
+    return { name: event.constructor.name, payload, references: [] }
+  }
+
+  async deserialize(serialized: SerializedEvent): Promise<Event> {
+    const ctor = this.#constructors.get(serialized.name)
+    const event = ctor === undefined ? new Event() : Object.assign(new Event(), serialized.payload)
+    if (ctor !== undefined) Object.setPrototypeOf(event, ctor.prototype)
+    return event
+  }
+}
+
+function matchesPattern(pattern: string, name: string): boolean {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replaceAll('*', '.*')
+  return new RegExp(`^${escaped}$`).test(name)
+}
+
+function isFalse(result: ListenerResult): result is false {
+  return result === false
+}
+
+/** In-process event dispatcher implementing the frozen `EventDispatcher` contract. */
+export class InProcessEventDispatcher implements EventDispatcher {
+  readonly #registrations: StoredRegistration[] = []
+  readonly #after: Array<() => Promise<void>> = []
+  readonly #serializer: JsonEventSerializer
+  #queue: QueueDriver | undefined
+
+  constructor(options: { queue?: QueueDriver; serializer?: EventSerializer } = {}) {
+    this.#queue = options.queue
+    this.#serializer = new JsonEventSerializer()
+  }
+
+  /** Wires a queue driver for `delivery: 'queued'` listeners. Omitting `queue` uses the memory board. */
+  bindQueue(queue?: QueueDriver): void {
+    this.#queue = queue
+  }
+
+  listen<TEvent extends Event>(
+    event: EventConstructor<TEvent> | string,
+    listeners:
+      | ListenerDefinition<TEvent>
+      | readonly ListenerDefinition<TEvent>[]
+      | ListenerDefinition<Event>,
+  ): void {
+    if (typeof event === 'string') {
+      this.#registrations.push({
+        pattern: event,
+        listener: listeners as ListenerDefinition<Event>,
+      })
+      return
+    }
+    this.#serializer.register(event)
+    const list = Array.isArray(listeners) ? listeners : [listeners]
+    for (const listener of list) {
+      this.#registrations.push({
+        event,
+        listener: listener as ListenerDefinition<Event>,
+      })
+    }
+  }
+
+  subscribe(subscriber: EventSubscriber): void {
+    for (const registration of subscriber.listeners()) {
+      this.listen(registration.event, registration.listener)
+    }
+  }
+
+  async dispatch<TEvent extends Event>(
+    event: TEvent,
+    options: EventDispatchOptions = {},
+  ): Promise<void> {
+    if (options.afterCommit && isInTransaction()) {
+      const captured = event
+      holdUntilCommit(() => this.#dispatchNow(captured, false))
+      return
+    }
+    await this.#dispatchNow(event, false)
+  }
+
+  async dispatchAfterResponse<TEvent extends Event>(event: TEvent): Promise<void> {
+    await this.#dispatchNow(event, true)
+  }
+
+  async until<TResult, TEvent extends Event>(
+    event: TEvent,
+    options: EventDispatchOptions = {},
+  ): Promise<TResult | null> {
+    if (options.afterCommit && isInTransaction()) {
+      return new Promise<TResult | null>((resolve, reject) => {
+        holdUntilCommit(async () => {
+          try {
+            resolve(await this.#untilNow<TResult>(event))
+          } catch (error) {
+            reject(error)
+          }
+        })
+      })
+    }
+    return this.#untilNow<TResult>(event)
+  }
+
+  /** Runs listeners scheduled for post-response delivery. */
+  async flushAfterResponse(): Promise<void> {
+    const pending = this.#after.splice(0, this.#after.length)
+    for (const job of pending) await job()
+  }
+
+  /** Drains queued listeners from the wired queue driver, or the process-local job board. */
+  async flushQueued(now = Date.now()): Promise<number> {
+    if (this.#queue !== undefined) {
+      return this.#queue.drain(async (receipt) => {
+        await this.#deliverQueued(receipt)
+      })
+    }
+    const receipts = jobBoard().take({ now, name: 'avelon.listener' })
+    let handled = 0
+    for (const receipt of receipts) {
+      if (receipt.job.name !== 'avelon.listener') continue
+      try {
+        await this.#deliverQueued(receipt)
+        handled += 1
+      } catch (error) {
+        const envelope = queuedEnvelope(receipt.job.payload)
+        if (envelope !== undefined && receipt.attempt < envelope.tries) {
+          jobBoard().enqueue(receipt.job, {
+            attempt: receipt.attempt,
+            availableAt: now + backoffSeconds(envelope.backoff, receipt.attempt) * 1000,
+            tries: envelope.tries,
+            backoff: envelope.backoff,
+          })
+        } else {
+          jobBoard().fail(receipt, error)
+        }
+      }
+    }
+    return handled
+  }
+
+  /** Clears registrations, the wired queue, and scheduled work. Intended for tests. */
+  reset(): void {
+    this.#registrations.length = 0
+    this.#after.length = 0
+    this.#queue = undefined
+    jobBoard().flush()
+  }
+
+  #matching(event: Event): StoredRegistration[] {
+    return this.#registrations
+      .filter((entry) => {
+        if (entry.event !== undefined) return event instanceof entry.event
+        if (entry.pattern !== undefined)
+          return matchesPattern(entry.pattern, event.constructor.name)
+        return false
+      })
+      .sort((left, right) => (left.listener.priority ?? 0) - (right.listener.priority ?? 0))
+  }
+
+  async #dispatchNow(event: Event, forceAfter: boolean): Promise<void> {
+    for (const entry of this.#matching(event)) {
+      if (event.isPropagationStopped()) return
+      const delivery = forceAfter ? 'after' : (entry.listener.delivery ?? 'sync')
+      if (delivery === 'sync') {
+        const result = await entry.listener.handle(event, { delivery: 'sync' })
+        if (isFalse(result)) {
+          event.stopPropagation()
+          return
+        }
+        continue
+      }
+      if (delivery === 'after') {
+        const captured = event
+        const listener = entry.listener
+        this.#after.push(async () => {
+          if (captured.isPropagationStopped()) return
+          const result = await listener.handle(captured, { delivery: 'after' })
+          if (isFalse(result)) captured.stopPropagation()
+        })
+        continue
+      }
+      await this.#enqueueQueued(event, entry)
+    }
+  }
+
+  async #untilNow<TResult>(event: Event): Promise<TResult | null> {
+    for (const entry of this.#matching(event)) {
+      if (event.isPropagationStopped()) return null
+      const delivery = entry.listener.delivery ?? 'sync'
+      if (delivery !== 'sync') continue
+      const result = await entry.listener.handle(event, { delivery: 'sync' })
+      if (isFalse(result)) {
+        event.stopPropagation()
+        return null
+      }
+      if (result !== undefined && result !== null) {
+        event.stopPropagation()
+        return result as TResult
+      }
+    }
+    return null
+  }
+
+  async #deliverQueued(receipt: {
+    job: { name: string; payload: unknown }
+    attempt: number
+  }): Promise<void> {
+    if (receipt.job.name !== 'avelon.listener') return
+    const envelope = queuedEnvelope(receipt.job.payload)
+    if (envelope === undefined) return
+    const event = await this.#serializer.deserialize(envelope.event)
+    const registration = this.#registrations.find(
+      (entry) =>
+        entry.listener.delivery === 'queued' &&
+        entry.listener.queue === envelope.queue &&
+        (entry.event?.name === envelope.eventName ||
+          (entry.pattern !== undefined && matchesPattern(entry.pattern, envelope.eventName))),
+    )
+    if (registration === undefined || registration.listener.delivery !== 'queued') return
+    await registration.listener.handle(event, {
+      delivery: 'queued',
+      queue: envelope.queue,
+      attempt: receipt.attempt,
+      tries: envelope.tries,
+    })
+  }
+
+  async #enqueueQueued(event: Event, entry: StoredRegistration): Promise<void> {
+    if (entry.listener.delivery !== 'queued') return
+    const listener = entry.listener
+    const serialized = await this.#serializer.serialize(event)
+    const queue = listener.queue ?? 'default'
+    const tries = listener.tries ?? 1
+    const backoff = listener.backoff ?? 0
+    const envelope: QueuedEventEnvelope & {
+      tries: number
+      backoff: number | readonly number[]
+      eventName: string
+    } = {
+      event: serialized,
+      listener: entry.event?.name ?? entry.pattern ?? event.constructor.name,
+      queue,
+      attempt: 0,
+      availableAt: Date.now(),
+      tries,
+      backoff,
+      eventName: event.constructor.name,
+    }
+    const job = { name: 'avelon.listener', payload: envelope, queue }
+    if (this.#queue !== undefined) {
+      await this.#queue.enqueue(job)
+      return
+    }
+    jobBoard().enqueue(job, { tries, backoff })
+  }
+}
+
+type QueuedEnvelope = QueuedEventEnvelope & {
+  tries: number
+  backoff: number | readonly number[]
+  eventName: string
+}
+
+function queuedEnvelope(payload: unknown): QueuedEnvelope | undefined {
+  if (typeof payload !== 'object' || payload === null) return undefined
+  if (!('event' in payload) || !('queue' in payload) || !('eventName' in payload)) return undefined
+  const envelope = payload as QueuedEnvelope
+  if (typeof envelope.eventName !== 'string' || typeof envelope.queue !== 'string') return undefined
+  return envelope
+}
+
+const defaultDispatcher = new InProcessEventDispatcher()
+
+/** Process-wide dispatcher used by the `Events` facade. */
+export function eventDispatcher(): InProcessEventDispatcher {
+  return defaultDispatcher
+}
+
+/** Creates an isolated dispatcher, used when a test or worker needs its own bus. */
+export function createEventDispatcher(options?: {
+  queue?: QueueDriver
+  serializer?: EventSerializer
+}): InProcessEventDispatcher {
+  return new InProcessEventDispatcher(options)
+}
+
+/** Application-facing event bus. The frozen `Event` class is unchanged. */
+export const Events: EventDispatcher & {
+  flushAfterResponse: () => Promise<void>
+  flushQueued: (now?: number) => Promise<number>
+  bindQueue: (queue?: QueueDriver) => void
+  reset: () => void
+} = {
+  listen: defaultDispatcher.listen.bind(defaultDispatcher),
+  subscribe: defaultDispatcher.subscribe.bind(defaultDispatcher),
+  dispatch: defaultDispatcher.dispatch.bind(defaultDispatcher),
+  dispatchAfterResponse: defaultDispatcher.dispatchAfterResponse.bind(defaultDispatcher),
+  until: defaultDispatcher.until.bind(defaultDispatcher),
+  flushAfterResponse: () => defaultDispatcher.flushAfterResponse(),
+  flushQueued: (now) => defaultDispatcher.flushQueued(now),
+  bindQueue: (queue) => defaultDispatcher.bindQueue(queue),
+  reset: () => defaultDispatcher.reset(),
+}