API Reference

import {
  // Builder
  Builder,
  AfterlogError,
  normalize,
  extractTraceId,

  // Types
  WideEvent,
  BaseWideEvent,
  HttpWideEvent,
  WideEventError,
  Lifecycle,
  TimingStats,
  State,
  Finalized,

  // Singleton
  afterlog,
  Afterlog,
  AfterlogNotConfiguredError,
  SingletonConfig,

  // Sampling
  SamplingEngine,
  errorRule,
  createLatencyRule,
  createRandomRule,
  createConsistentRule,
  SamplingDecision,
  SamplingRule,
  SamplingConfig,
  LatencyConfig,
  ConsistentConfig,

  // Adapters
  AdapterManager,
  createConsoleAdapter,
  ConsoleAdapterOptions,
  LoggerAdapter,
  AdapterMetrics,
  EmitHook,
  ErrorHook,
} from "afterlog"

afterlog.configure(config: SingletonConfig<T>): void

afterlog.createBuilder(init?: Init): Builder<T>

afterlog.finalize(builder: Builder<T>): Promise<void>

afterlog.flush(): Promise<void>

afterlog.destroy(): Promise<void>

afterlog.isHealthy(): Promise<boolean>

afterlog.getMetrics(): AdapterMetrics | null

interface WideEvent extends HttpWideEvent {
  [key: string]: unknown
}

interface BaseWideEvent {
  readonly request_id: UUID
  readonly trace_id: UUID
  readonly timestamp: string
  readonly service?: string
  readonly version?: string
  readonly region?: string
  readonly deployment_id?: string
  readonly environment?: string
}

interface HttpWideEvent extends BaseWideEvent {
  http_method?: string
  path?: string
  query?: Record<string, string>
  http_status_code?: number
  request_duration_ms?: number
  request_outcome?: "success" | "error" | "timeout" | "cancelled"
  request_bytes?: number
  response_bytes?: number
  error?: WideEventError
  timings?: Record<string, number>
}

interface WideEventError {
  type: string
  message: string
  code?: string | null
  stack?: string | null
  retriable?: boolean
  context?: Record<string, unknown>
}

interface SingletonConfig<T extends BaseWideEvent> {
  adapter: LoggerAdapter<T>
  sampling?: SamplingConfig
  service: string
  version?: string
  region?: string
  deployment_id?: string
  environment?: string
  clock?: Clock
  timeout_ms?: number
}

interface Clock {
  now(): number
  elapsed(start: number): number
}

type Enricher<T extends BaseWideEvent> = (
  event: Partial<T>,
  meta: Map<string, unknown>,
) => Partial<T> | void

interface Config<T extends BaseWideEvent> {
  service?: string
  version?: string
  region?: string
  deployment_id?: string
  environment?: string
  clock?: Clock
  enrichers?: Enricher<T>[]
  timeout_ms?: number
}

interface Init {
  request_id?: UUID
  trace_id?: UUID
  parent_span_id?: string
  method?: string
  path?: string
  headers?: Record<string, string>
}

type Lifecycle = "created" | "building" | "finalizing" | "emitted" | "dropped"

interface TimingStats {
  count: number
  total_ms: number
  min_ms: number
  max_ms: number
  avg_ms: number
}

interface State<T extends BaseWideEvent> {
  readonly id: UUID
  lifecycle: Lifecycle
  readonly startTime: number
  readonly base: { ... }
  context: Partial<T>
  timers: Map<string, number>
  timings: Map<string, TimingStats>
  errors: NormalizedError[]
  meta: Map<string, unknown>
}

type Finalized<T extends BaseWideEvent> = Readonly<
  T & {
    readonly duration_ms: number
    readonly outcome: "success" | "error" | "timeout" | "cancelled"
  }
>

interface NormalizedError extends WideEventError {
  original: unknown
}

interface LoggerAdapter<T extends BaseWideEvent> {
  emit(event: Finalized<T>): void | Promise<void>
  flush?(): Promise<void>
  destroy?(): Promise<void>
  isHealthy?(): boolean | Promise<boolean>
}

interface AdapterMetrics {
  eventsEmitted: number
  eventsFailed: number
  bytesEmitted: number
  lastEmitTime: Date | null
  lastErrorTime: Date | null
  averageEmitDurationMs: number
}

type EmitHook<T extends BaseWideEvent> = (event: Finalized<T>) => void | Promise<void>

type ErrorHook<T extends BaseWideEvent> = (
  error: Error,
  event?: Finalized<T>,
) => void | Promise<void>

interface SamplingDecision {
  sampled: boolean
  rate: number
  reason: string
  metadata?: Record<string, unknown>
}

interface SamplingRule<T extends BaseWideEvent> {
  readonly name: string
  readonly priority: number
  evaluate(event: T): SamplingDecision | undefined
}

interface SamplingConfig<T extends BaseWideEvent> {
  rules: SamplingRule<T>[]
  defaultRate?: number
  addSamplingMetadata?: boolean
}

interface LatencyConfig {
  alwaysSampleAbove?: number
  thresholds?: Array<{ durationMs: number; rate: number }>
}

interface ConsistentConfig {
  rate: number
  hashField?: string
}

interface ConsoleAdapterOptions {
  method?: "log" | "info" | "warn" | "error" | "debug"
  pretty?: boolean
  includeTimestamp?: boolean
}

type UUID = string & { readonly __brand: unique symbol }