@avelonjs/core 0.1.0

package/src/drivers/search.ts

@@ -0,0 +1,92 @@
+import type { DriverContract } from './common'
+
+/** Literal search features used to constrain query options. */
+export interface SearchCapabilities {
+  /** Whether queries may request facet counts. */
+  readonly facets: boolean
+}
+
+/** Search document with a stable identifier and indexable fields. */
+export interface SearchDocument {
+  /** Stable document identifier. */
+  id: string
+  /** Indexable document fields. */
+  fields: Readonly<Record<string, unknown>>
+}
+
+/** Portable search query options. */
+export interface SearchOptions {
+  /** Maximum hits to return. */
+  limit?: number
+  /** Number of hits to skip. */
+  offset?: number
+  /** Exact filters applied by the driver. */
+  filters?: Readonly<Record<string, unknown>>
+  /** Fields for which facet counts should be returned. */
+  facets?: readonly string[]
+}
+
+/** One search hit and its normalized relevance score. */
+export interface SearchHit<TDocument extends SearchDocument = SearchDocument> {
+  /** Matching document. */
+  document: TDocument
+  /** Driver-normalized relevance score. */
+  score: number
+}
+
+/** Portable search response. */
+export interface SearchResult<TDocument extends SearchDocument = SearchDocument> {
+  /** Ordered matching documents. */
+  hits: readonly SearchHit<TDocument>[]
+  /** Total matches before pagination. */
+  total: number
+  /** Requested facet counts when supported. */
+  facets?: Readonly<Record<string, Readonly<Record<string, number>>>>
+}
+
+/** Search indexing and query contract. */
+export interface SearchDriver<
+  TCapabilities extends SearchCapabilities = SearchCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Adds or replaces documents in a named index. */
+  index(name: string, documents: readonly SearchDocument[]): Promise<void>
+  /** Removes documents from a named index. */
+  remove(name: string, ids: readonly string[]): Promise<void>
+  /** Queries a named index. */
+  query<TDocument extends SearchDocument = SearchDocument>(
+    name: string,
+    query: string,
+    options?: SearchOptions,
+  ): Promise<SearchResult<TDocument>>
+}
+
+type SearchOptionsFor<TCapabilities extends SearchCapabilities> =
+  TCapabilities['facets'] extends true
+    ? SearchOptions
+    : Omit<SearchOptions, 'facets'> & { facets?: never }
+
+/** Search facade narrowed to its driver's facet capability. */
+export interface SearchSurface<TDriver extends SearchDriver> {
+  /** Driver implementation name. */
+  readonly name: TDriver['name']
+  /** Configured search index connection name. */
+  readonly instance: TDriver['instance']
+  /** Exact search capability declaration. */
+  readonly capabilities: TDriver['capabilities']
+  /** Adds or replaces documents in an index. */
+  index(name: string, documents: readonly SearchDocument[]): Promise<void>
+  /** Removes documents from an index. */
+  remove(name: string, ids: readonly string[]): Promise<void>
+  /** Queries an index using only supported options. */
+  query<TDocument extends SearchDocument = SearchDocument>(
+    name: string,
+    query: string,
+    options?: SearchOptionsFor<TDriver['capabilities']>,
+  ): Promise<SearchResult<TDocument>>
+  /** Returns the driver's typed underlying client. */
+  raw(): ReturnType<TDriver['raw']>
+}
+
+/** Search facade narrowed to its driver's exact capabilities. */
+export type Search<TDriver extends SearchDriver> = SearchSurface<TDriver>

package/src/drivers/social.ts

@@ -0,0 +1,63 @@
+import type { CapabilityMembers, DriverContract } from './common'
+
+/** Literal social authentication providers accepted by a driver instance. */
+export interface SocialCapabilities<TProvider extends string = string> {
+  /** Provider identifiers retained as a literal readonly list. */
+  readonly providers: readonly TProvider[]
+}
+
+/** Identity data returned after a social authorization callback. */
+export interface SocialIdentity<TProfile = unknown> {
+  /** Driver-independent provider identifier. */
+  provider: string
+  /** Stable provider-side subject identifier. */
+  subject: string
+  /** Provider profile normalized by the driver. */
+  profile: TProfile
+}
+
+/** OAuth redirect and callback contract. */
+export interface SocialDriver<
+  TCapabilities extends SocialCapabilities = SocialCapabilities,
+  TRaw = unknown,
+  TProfile = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Builds the authorization URL for a configured provider. */
+  redirect(provider: string, callbackUrl: string, state?: string): Promise<string>
+  /** Verifies `state` and exchanges the callback `code` for normalized social identity data. */
+  callback(
+    provider: string,
+    params: Readonly<Record<string, string>>,
+    callbackUrl: string,
+  ): Promise<SocialIdentity<TProfile>>
+}
+
+type SocialProfileOf<TDriver extends SocialDriver> =
+  TDriver extends SocialDriver<SocialCapabilities, unknown, infer TProfile> ? TProfile : never
+
+/** Social facade restricted to the configured provider literals. */
+export interface SocialSurface<TDriver extends SocialDriver> {
+  /** Driver implementation name. */
+  readonly name: TDriver['name']
+  /** Configured social connection name. */
+  readonly instance: TDriver['instance']
+  /** Exact provider capability list. */
+  readonly capabilities: TDriver['capabilities']
+  /** Builds an authorization URL for a configured provider. */
+  redirect(
+    provider: CapabilityMembers<TDriver['capabilities']['providers']>,
+    callbackUrl: string,
+    state?: string,
+  ): Promise<string>
+  /** Verifies `state` and exchanges the configured provider's callback `code`. */
+  callback(
+    provider: CapabilityMembers<TDriver['capabilities']['providers']>,
+    params: Readonly<Record<string, string>>,
+    callbackUrl: string,
+  ): Promise<SocialIdentity<SocialProfileOf<TDriver>>>
+  /** Returns the driver's typed underlying client. */
+  raw(): ReturnType<TDriver['raw']>
+}
+
+/** Social authentication facade narrowed to configured provider literals. */
+export type Social<TDriver extends SocialDriver> = SocialSurface<TDriver>

package/src/drivers/storage.ts

@@ -0,0 +1,78 @@
+import type { CapabilityMembers, CapabilitySurface, DriverContract } from './common'
+
+/** Portable transform operations a storage driver may advertise. */
+export type StorageTransform = 'resize' | 'crop' | 'format'
+
+/** Literal storage features used to narrow file operations. */
+export interface StorageCapabilities<TTransform extends StorageTransform = StorageTransform> {
+  /** Whether temporary signed URLs are available. */
+  readonly signedUrls: boolean
+  /** Transform operations retained as a literal readonly list. */
+  readonly transforms: readonly TTransform[]
+}
+
+/** Metadata returned for a stored object. */
+export interface StorageObject {
+  /** Object path within the configured disk. */
+  path: string
+  /** Object size in bytes. */
+  size: number
+  /** Media type when known. */
+  contentType?: string
+  /** Driver-independent entity tag when available. */
+  etag?: string
+}
+
+/** Portable image or document transform request. */
+export interface StorageTransformOptions {
+  /** Requested output width in pixels. */
+  width?: number
+  /** Requested output height in pixels. */
+  height?: number
+  /** Requested output media subtype. */
+  format?: string
+}
+
+/** Base file storage contract. */
+export interface StorageDriver<
+  TCapabilities extends StorageCapabilities = StorageCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Stores bytes at a path and returns normalized metadata. */
+  put(
+    path: string,
+    contents: Uint8Array | AsyncIterable<Uint8Array>,
+    options?: { readonly contentType?: string },
+  ): Promise<StorageObject>
+  /** Reads an object's bytes. */
+  get(path: string): Promise<Uint8Array>
+  /** Deletes an object if it exists. */
+  delete(path: string): Promise<void>
+  /** Reports whether an object exists. */
+  exists(path: string): Promise<boolean>
+}
+
+/** Signed URL methods exposed only by drivers that support them. */
+export interface SignedUrlStorageSurface {
+  /** Creates a temporary URL for reading a stored object. */
+  signedUrl(path: string, expiresInSeconds: number): Promise<string>
+}
+
+/** Transform methods restricted to a driver's literal operation list. */
+export interface TransformStorageSurface<TTransform extends StorageTransform> {
+  /** Creates a URL or derivative for one supported transform operation. */
+  transform(path: string, operation: TTransform, options: StorageTransformOptions): Promise<string>
+}
+
+type StorageTransformFor<TCapabilities extends StorageCapabilities> =
+  TCapabilities['transforms'] extends readonly []
+    ? object
+    : TransformStorageSurface<CapabilityMembers<TCapabilities['transforms']>>
+
+/** Storage facade narrowed to signed URL and literal transform capabilities. */
+export type Storage<TDriver extends StorageDriver> = Pick<
+  TDriver,
+  'name' | 'instance' | 'capabilities' | 'put' | 'get' | 'delete' | 'exists' | 'raw'
+> &
+  CapabilitySurface<TDriver['capabilities']['signedUrls'], SignedUrlStorageSurface> &
+  StorageTransformFor<TDriver['capabilities']>

package/src/drivers/tokens.ts

@@ -0,0 +1,87 @@
+import type { DriverContract } from './common'
+
+/** Literal API-token features used to constrain token issuance. */
+export interface TokenCapabilities {
+  /** Whether issued tokens may carry ability restrictions. */
+  readonly abilities: boolean
+  /** Whether issued tokens may expire automatically. */
+  readonly expiration: boolean
+}
+
+/** Options accepted when issuing an API token. */
+export interface TokenIssueOptions {
+  /** Abilities granted to the token. */
+  abilities?: readonly string[]
+  /** Time after which the token is rejected. */
+  expiresAt?: Date
+}
+
+/** API-token metadata safe to persist or display. */
+export interface TokenRecord {
+  /** Stable token identifier. */
+  id: string
+  /** Stable application subject authenticated by the token. */
+  subject: string
+  /** User-facing token name. */
+  name: string
+  /** Granted ability names. */
+  abilities: readonly string[]
+  /** Issuance time. */
+  createdAt: Date
+  /** Expiration time, or null for a non-expiring token. */
+  expiresAt: Date | null
+}
+
+/** One-time plaintext token returned only at issuance. */
+export interface IssuedToken extends TokenRecord {
+  /** Secret token value that must not be returned by later list operations. */
+  plainText: string
+}
+
+/** API token authentication, issuance, listing, and revocation contract. */
+export interface TokenDriver<
+  TCapabilities extends TokenCapabilities = TokenCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /**
+   * Authenticates a plaintext token, throwing `Unauthenticated` when it is missing, revoked, or
+   * expired.
+   */
+  verify(plainText: string): Promise<TokenRecord>
+  /** Issues a named API token. */
+  issue(name: string, options?: TokenIssueOptions): Promise<IssuedToken>
+  /** Lists metadata for the current actor's tokens. */
+  list(): Promise<readonly TokenRecord[]>
+  /** Revokes one token by its stable identifier. */
+  revoke(id: string): Promise<void>
+}
+
+type TokenOptionsFor<TCapabilities extends TokenCapabilities> =
+  (TCapabilities['abilities'] extends true ? object : { abilities?: never }) &
+    (TCapabilities['expiration'] extends true ? object : { expiresAt?: never })
+
+/** Token facade narrowed to the configured issuance features. */
+export interface TokenSurface<TDriver extends TokenDriver> {
+  /** Driver implementation name. */
+  readonly name: TDriver['name']
+  /** Configured token issuer name. */
+  readonly instance: TDriver['instance']
+  /** Exact token capability declaration. */
+  readonly capabilities: TDriver['capabilities']
+  /**
+   * Authenticates a plaintext token, throwing `Unauthenticated` when it is missing, revoked, or
+   * expired.
+   */
+  verify(plainText: string): Promise<TokenRecord>
+  /** Issues a token using only options supported by the driver. */
+  issue(name: string, options?: TokenOptionsFor<TDriver['capabilities']>): Promise<IssuedToken>
+  /** Lists token metadata without plaintext secrets. */
+  list(): Promise<readonly TokenRecord[]>
+  /** Revokes one token. */
+  revoke(id: string): Promise<void>
+  /** Returns the driver's typed underlying client. */
+  raw(): ReturnType<TDriver['raw']>
+}
+
+/** API-token facade narrowed to its driver's exact capabilities. */
+export type Tokens<TDriver extends TokenDriver> = TokenSurface<TDriver>

package/src/errors.ts

@@ -0,0 +1,166 @@
+/** Stable machine-readable codes for framework and normalized driver failures. */
+export type ErrorCode =
+  | 'NOT_FOUND'
+  | 'CONFLICT'
+  | 'UNAUTHENTICATED'
+  | 'FORBIDDEN'
+  | 'RATE_LIMITED'
+  | 'INVALID'
+  | 'UNAVAILABLE'
+  | 'DRIVER_FAULT'
+
+/** Constructor options shared by every framework error. */
+export interface AvelonErrorOptions<TMetadata extends object> {
+  /** Stable framework metadata without vendor response shapes. */
+  metadata: TMetadata
+  /** Original failure retained through standard error chaining. */
+  cause?: unknown
+}
+
+/** Base error carrying a stable code, typed metadata, and a standard cause. */
+export class AvelonError<TMetadata extends object> extends Error {
+  /** Stable machine-readable error code. */
+  readonly code: ErrorCode
+
+  /** Framework-owned metadata safe to inspect across driver changes. */
+  readonly metadata: Readonly<TMetadata>
+
+  /** Creates an error with a fixed code and typed metadata. */
+  constructor(
+    name: string,
+    code: ErrorCode,
+    message: string,
+    options: AvelonErrorOptions<TMetadata>,
+  ) {
+    super(message, { cause: options.cause })
+    this.name = name
+    this.code = code
+    this.metadata = options.metadata
+  }
+}
+
+/** Metadata identifying a resource lookup that failed. */
+export interface NotFoundMetadata {
+  /** Resource type that could not be found. */
+  resource: string
+  /** Requested identifier when one is safe to expose. */
+  identifier?: string | number
+}
+
+/** Failure raised when a requested resource does not exist. */
+export class NotFound extends AvelonError<NotFoundMetadata> {
+  /** Creates a not-found failure. */
+  constructor(message: string, options: AvelonErrorOptions<NotFoundMetadata>) {
+    super('NotFound', 'NOT_FOUND', message, options)
+  }
+}
+
+/** Metadata describing a framework-level state conflict. */
+export interface ConflictMetadata {
+  /** Resource involved in the conflict. */
+  resource?: string
+  /** Framework-owned conflict key, never a vendor constraint shape. */
+  key?: string
+}
+
+/** Failure raised when an operation conflicts with existing state. */
+export class Conflict extends AvelonError<ConflictMetadata> {
+  /** Creates a conflict failure. */
+  constructor(message: string, options: AvelonErrorOptions<ConflictMetadata>) {
+    super('Conflict', 'CONFLICT', message, options)
+  }
+}
+
+/** Metadata describing the authentication boundary that rejected a request. */
+export interface UnauthenticatedMetadata {
+  /** Authentication guard or context used by the application. */
+  guard?: string
+}
+
+/** Failure raised when an operation requires an authenticated actor. */
+export class Unauthenticated extends AvelonError<UnauthenticatedMetadata> {
+  /** Creates an unauthenticated failure. */
+  constructor(message: string, options: AvelonErrorOptions<UnauthenticatedMetadata>) {
+    super('Unauthenticated', 'UNAUTHENTICATED', message, options)
+  }
+}
+
+/** Metadata describing an authorization denial. */
+export interface ForbiddenMetadata {
+  /** Ability or action that was denied. */
+  ability?: string
+  /** Resource type involved in the authorization check. */
+  resource?: string
+}
+
+/** Failure raised when an authenticated actor lacks permission. */
+export class Forbidden extends AvelonError<ForbiddenMetadata> {
+  /** Creates a forbidden failure. */
+  constructor(message: string, options: AvelonErrorOptions<ForbiddenMetadata>) {
+    super('Forbidden', 'FORBIDDEN', message, options)
+  }
+}
+
+/** Metadata describing a rate-limit decision. */
+export interface RateLimitedMetadata {
+  /** Stable application key that was limited. */
+  key?: string
+  /** Milliseconds until another attempt may succeed. */
+  retryAfterMs?: number
+  /** Limit applied during the current window. */
+  limit?: number
+}
+
+/** Failure raised when an operation exceeds its allowed rate. */
+export class RateLimited extends AvelonError<RateLimitedMetadata> {
+  /** Creates a rate-limited failure. */
+  constructor(message: string, options: AvelonErrorOptions<RateLimitedMetadata>) {
+    super('RateLimited', 'RATE_LIMITED', message, options)
+  }
+}
+
+/** Metadata describing invalid input in framework-owned terms. */
+export interface InvalidMetadata {
+  /** Field-keyed validation messages. */
+  fields?: Readonly<Record<string, readonly string[]>>
+}
+
+/** Failure raised when supplied input is invalid. */
+export class Invalid extends AvelonError<InvalidMetadata> {
+  /** Creates an invalid-input failure. */
+  constructor(message: string, options: AvelonErrorOptions<InvalidMetadata>) {
+    super('Invalid', 'INVALID', message, options)
+  }
+}
+
+/** Metadata describing a temporarily unavailable framework service. */
+export interface UnavailableMetadata {
+  /** Framework service or capability that is unavailable. */
+  service?: string
+  /** Milliseconds after which retrying may succeed. */
+  retryAfterMs?: number
+}
+
+/** Failure raised when a required service is temporarily unavailable. */
+export class Unavailable extends AvelonError<UnavailableMetadata> {
+  /** Creates an unavailable failure. */
+  constructor(message: string, options: AvelonErrorOptions<UnavailableMetadata>) {
+    super('Unavailable', 'UNAVAILABLE', message, options)
+  }
+}
+
+/** Metadata identifying a normalized driver failure. */
+export interface DriverFaultMetadata {
+  /** Driver contract that failed, such as `database` or `mail`. */
+  driver: string
+  /** Framework operation being attempted. */
+  operation: string
+}
+
+/** Failure raised when a driver returns an otherwise unmapped failure. */
+export class DriverFault extends AvelonError<DriverFaultMetadata> {
+  /** Creates a normalized driver fault. */
+  constructor(message: string, options: AvelonErrorOptions<DriverFaultMetadata>) {
+    super('DriverFault', 'DRIVER_FAULT', message, options)
+  }
+}

package/src/events.ts

@@ -0,0 +1,185 @@
+/** Listener delivery strategies supported by the event dispatcher. */
+export type DeliveryMode = 'sync' | 'after' | 'queued'
+
+/** Base event with explicit, dispatcher-readable propagation state. */
+export class Event {
+  #propagationStopped = false
+
+  /** Stops remaining listeners, including queued listeners not yet scheduled. */
+  stopPropagation(): void {
+    this.#propagationStopped = true
+  }
+
+  /** Reports whether a listener has stopped the current dispatch chain. */
+  isPropagationStopped(): boolean {
+    return this.#propagationStopped
+  }
+}
+
+/** Constructable event class used when registering listeners. */
+export interface EventConstructor<TEvent extends Event = Event> {
+  /** Creates an event instance from its declared constructor arguments. */
+  new (...args: never[]): TEvent
+  /** Runtime class name used for event discovery. */
+  readonly name: string
+}
+
+/** Options controlling one event dispatch. */
+export interface EventDispatchOptions {
+  /** Holds dispatch until the enclosing transaction commits and drops it on rollback. */
+  afterCommit?: boolean
+}
+
+/** Stable reference extracted while serializing a queued event. */
+export interface SerializedReference<TId extends string | number = string | number> {
+  /** Framework registry type used to rehydrate the reference. */
+  type: string
+  /** Identifier resolved when the queued listener runs. */
+  id: TId
+}
+
+/** Serialized event payload crossing the queue boundary. */
+export interface SerializedEvent {
+  /** Registered event name. */
+  name: string
+  /** Serializable event data with references replaced by tokens. */
+  payload: unknown
+  /** References rehydrated against current state in the worker. */
+  references: readonly SerializedReference[]
+}
+
+/** Serializer boundary supplied by the model/event integration layer. */
+export interface EventSerializer<TEvent extends Event = Event> {
+  /** Converts an event into a queue-safe payload and explicit references. */
+  serialize(event: TEvent): Promise<SerializedEvent>
+  /** Rehydrates an event and its references from a queued payload. */
+  deserialize(serialized: SerializedEvent): Promise<TEvent>
+}
+
+/** Context passed to an inline listener. */
+export interface SyncListenerContext {
+  /** Actual delivery mode. */
+  delivery: 'sync'
+}
+
+/** Context passed to a best-effort post-response listener. */
+export interface AfterListenerContext {
+  /** Actual delivery mode. */
+  delivery: 'after'
+}
+
+/** Worker context for a durable listener; actors must be carried explicitly on the event. */
+export interface QueuedListenerContext {
+  /** Actual delivery mode. */
+  delivery: 'queued'
+  /** Named queue processing the listener. */
+  queue: string
+  /** One-based execution attempt. */
+  attempt: number
+  /** Maximum attempts before the payload moves to failed storage. */
+  tries: number
+}
+
+/** Delivery-specific listener context with no implicit request or actor. */
+export type ListenerContext<TDelivery extends DeliveryMode = DeliveryMode> =
+  TDelivery extends 'sync'
+    ? SyncListenerContext
+    : TDelivery extends 'after'
+      ? AfterListenerContext
+      : QueuedListenerContext
+
+/** Result accepted from a listener; false stops propagation. */
+export type ListenerResult<TResult = unknown> = TResult | false | null | void
+
+type QueueOptions<TDelivery extends DeliveryMode> = TDelivery extends 'queued'
+  ? {
+      queue: string
+      tries: number
+      backoff: number | readonly number[]
+    }
+  : {
+      queue?: never
+      tries?: never
+      backoff?: never
+    }
+
+type DeliveryOption<TDelivery extends DeliveryMode> = TDelivery extends 'sync'
+  ? { delivery?: 'sync' }
+  : { delivery: TDelivery }
+
+/** Declarative listener contract with delivery-specific retry and queue settings. */
+export type ListenerDefinition<
+  TEvent extends Event,
+  TResult = unknown,
+  TDelivery extends DeliveryMode = DeliveryMode,
+> = {
+  /** Ascending execution priority. Lower values run first. */
+  priority?: number
+  /** Handles the event in a context determined by its actual delivery mode. */
+  handle(
+    event: TEvent,
+    context: ListenerContext<TDelivery>,
+  ): ListenerResult<TResult> | Promise<ListenerResult<TResult>>
+} & DeliveryOption<TDelivery> &
+  QueueOptions<TDelivery>
+
+/** Creates a listener definition while preserving literal delivery and retry information. */
+export function defineListener<
+  TEvent extends Event,
+  TResult = unknown,
+  const TDelivery extends DeliveryMode = 'sync',
+>(
+  definition: ListenerDefinition<TEvent, TResult, TDelivery>,
+): ListenerDefinition<TEvent, TResult, TDelivery> {
+  return definition
+}
+
+/** Registration joining an event class to one listener definition. */
+export interface ListenerRegistration<TEvent extends Event = Event> {
+  /** Event class this registration handles. */
+  event: EventConstructor<TEvent>
+  /** Listener invoked for that event. */
+  listener: ListenerDefinition<TEvent>
+}
+
+/** Multi-event subscriber contract registered through a provider. */
+export interface EventSubscriber {
+  /** Returns every event/listener pair owned by the subscriber. */
+  listeners(): readonly ListenerRegistration[]
+}
+
+/** Durable queue envelope with explicit execution context and no implicit actor. */
+export interface QueuedEventEnvelope {
+  /** Serialized event data. */
+  event: SerializedEvent
+  /** Stable listener registration name. */
+  listener: string
+  /** Named queue receiving the event. */
+  queue: string
+  /** One-based attempt number. */
+  attempt: number
+  /** Earliest epoch time in milliseconds at which the listener may run. */
+  availableAt: number
+}
+
+/** Event bus contract supporting ordered, post-response, queued, and result-seeking dispatch. */
+export interface EventDispatcher {
+  /** Registers one or more listeners for a typed event class. */
+  listen<TEvent extends Event>(
+    event: EventConstructor<TEvent>,
+    listeners: ListenerDefinition<TEvent> | readonly ListenerDefinition<TEvent>[],
+  ): void
+  /** Registers one listener for an event-name pattern such as `post.*`. */
+  listen(pattern: string, listener: ListenerDefinition<Event>): void
+  /** Registers every listener exposed by a multi-event subscriber. */
+  subscribe(subscriber: EventSubscriber): void
+  /** Runs synchronous listeners in priority order before scheduling later delivery modes. */
+  dispatch<TEvent extends Event>(event: TEvent, options?: EventDispatchOptions): Promise<void>
+  /** Runs every listener after the response regardless of its declared mode. */
+  dispatchAfterResponse<TEvent extends Event>(event: TEvent): Promise<void>
+  /** Returns the first non-null listener result and stops dispatching. */
+  until<TResult, TEvent extends Event>(
+    event: TEvent,
+    options?: EventDispatchOptions,
+  ): Promise<TResult | null>
+}