better-ship 0.3.2

package/src/application/message-bus.ts

@@ -0,0 +1,86 @@
+import { panic } from 'better-result'
+
+import { createLogger, unreachable } from '@/core'
+
+import { DuplicateMessageError } from './message-bus.errors.ts'
+import type { Command, Event, Message, Query } from './messages.ts'
+import type { Handlers, MessageResult, RegistryMessage } from './registry.ts'
+
+const logger = createLogger('message-bus')
+
+/** The port an entrypoint dispatches through. `AppDeps` names this as `IMessageBus<typeof registry>`. */
+export interface IMessageBus<TRegistry extends Handlers<never>> {
+  handle<TMessage extends Message & RegistryMessage<TRegistry>>(
+    message: TMessage,
+  ): Promise<MessageResult<TMessage, TRegistry>>
+}
+
+/**
+ * Routes one message to its slot. The bus opens no transaction and keeps no outbox:
+ * a handler that writes opens the unit of work itself.
+ */
+export class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMessageBus<TRegistry> {
+  constructor(
+    private readonly deps: Deps,
+    private readonly registry: TRegistry,
+  ) {}
+
+  /** Resolves to the handler's own value for a command or query, and to void for an event. */
+  async handle<TMessage extends Message & RegistryMessage<TRegistry>>(
+    message: TMessage,
+  ): Promise<MessageResult<TMessage, TRegistry>> {
+    // SAFETY: the slot for this name is what `MessageResult` names, and dispatch returns its value.
+    return (await this.dispatch(message)) as MessageResult<TMessage, TRegistry>
+  }
+
+  // oxlint-disable-next-line anti-slop/no-unknown-returns -- one table holds every slot's value; `handle` names it.
+  private dispatch(message: Message): Promise<unknown> {
+    if (message.type === 'command') return this.handleCommand(message)
+    if (message.type === 'query') return this.handleQuery(message)
+    if (message.type === 'event') return this.handleEvent(message)
+    // A message parsed at a boundary cannot reach here; one that does must not resolve silently.
+    return unreachable(message)
+  }
+
+  // oxlint-disable-next-line anti-slop/no-unknown-returns -- see dispatch.
+  private handleCommand(command: Command): Promise<unknown> {
+    // `satisfies` proved the registry complete, so a missing slot is a broken registry object.
+    const handler = this.registry.commands[command.name]
+    if (handler === undefined) return panic(`No handler for command ${command.name}`)
+    logger.debug('handling_command', { name: command.name, id: command.id })
+    return handler(command, this.deps)
+  }
+
+  // oxlint-disable-next-line anti-slop/no-unknown-returns -- see dispatch.
+  private handleQuery(query: Query): Promise<unknown> {
+    const handler = this.registry.queries[query.name]
+    if (handler === undefined) return panic(`No handler for query ${query.name}`)
+    return handler(query, this.deps)
+  }
+
+  /**
+   * Every subscriber runs to completion. One failure is rethrown as is. Several are thrown as
+   * one `AggregateError`. A `DuplicateMessageError` means that subscriber already committed on
+   * an earlier delivery, so it counts as delivered.
+   */
+  private async handleEvent(event: Event): Promise<void> {
+    const subscriptions = this.registry.events[event.name] ?? []
+    const outcomes = await Promise.allSettled(
+      subscriptions.map((subscription) => subscription(event, this.deps)),
+    )
+    const failures: unknown[] = []
+    for (const [subscriber, outcome] of outcomes.entries()) {
+      if (outcome.status === 'fulfilled') continue
+      if (outcome.reason instanceof DuplicateMessageError) {
+        // The bus swallows this error, so this line is the only record that the skip happened.
+        logger.info('duplicate_subscriber_ignored', { event: event.name, id: event.id, subscriber })
+        continue
+      }
+      failures.push(outcome.reason)
+    }
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) {
+      throw new AggregateError(failures, `${event.name}: ${failures.length} subscribers failed`)
+    }
+  }
+}

package/src/application/messages.ts

@@ -0,0 +1,31 @@
+/**
+ * The identity of a command or event. Receipts and the outbox are keyed by it.
+ *
+ * Internal messages use UUID v7, so receipts sort by creation. External messages use the
+ * provider's own key, `stripe:event:evt_123`, so a redelivered webhook is a duplicate by
+ * construction. The app parses and generates ids; this package only carries them.
+ */
+export type MessageId = string
+
+/** An action to perform. One handler, returns a value. The product adds its payload. */
+export type Command<Name extends string = string> = {
+  readonly type: 'command'
+  readonly name: Name
+  readonly id: MessageId
+}
+
+/** A request for data. One handler, returns a value. No id: nothing claims a read. */
+export type Query<Name extends string = string> = {
+  readonly type: 'query'
+  readonly name: Name
+}
+
+/** A fact that happened. Zero or more subscribers, returns nothing. The product adds its payload. */
+export type Event<Name extends string = string> = {
+  readonly type: 'event'
+  readonly name: Name
+  readonly id: MessageId
+}
+
+/** The routing fields the bus reads. `type` selects the table, `name` selects the slot. */
+export type Message = Command | Event | Query

package/src/application/registry.ts

@@ -0,0 +1,73 @@
+import type { CommandHandler, EventHandler, QueryHandler } from './handlers.ts'
+import type { Command, Event, Message, Query } from './messages.ts'
+
+/** One slot per command. `unknown` keeps the slot covariant; `MessageResult` recovers the value. */
+export type CommandRegistry<TCommand extends Command, Deps> = {
+  readonly [M in TCommand as M['name']]: CommandHandler<M, Deps, unknown>
+}
+
+/** One slot per query, typed with the read-only view of the container. */
+export type QueryRegistry<TQuery extends Query, QueryDeps> = {
+  readonly [M in TQuery as M['name']]: QueryHandler<M, QueryDeps, unknown>
+}
+
+/**
+ * Zero or more subscribers per event. Annotate the object with this type rather than
+ * `satisfies`, so an event with no subscribers is still a message the bus accepts.
+ */
+export type EventRegistry<TEvent extends Event, Deps> = {
+  readonly [M in TEvent as M['name']]?: ReadonlyArray<EventHandler<M, Deps>>
+}
+
+/**
+ * The app's three tables. `satisfies MessageRegistry<AppMessage, AppDeps, AppQueryDeps>`
+ * makes a missing handler a compile error. `Deps extends QueryDeps` is checked here, the one
+ * place both types meet: the read view must be a subset of the container.
+ */
+export type MessageRegistry<TMessage extends Message, Deps extends QueryDeps, QueryDeps> = {
+  readonly commands: CommandRegistry<Extract<TMessage, Command>, Deps>
+  readonly queries: QueryRegistry<Extract<TMessage, Query>, QueryDeps>
+  readonly events: EventRegistry<Extract<TMessage, Event>, Deps>
+}
+
+// Method syntax makes the parameters bivariant, so an app's slot, typed for one message, fits.
+// oxlint-disable-next-line anti-slop/no-unknown-returns -- one table holds every slot's value; `MessageResult` names it.
+type Slot<Deps> = { handle(message: Message, deps: Deps): Promise<unknown> }['handle']
+type Subscription<Deps> = { handle(event: Event, deps: Deps): Promise<void> }['handle']
+
+/**
+ * The registry as the bus routes it: each table keyed by name. The app's names are unknown
+ * inside the package, so this is what a runtime string can index.
+ */
+export type Handlers<Deps> = {
+  readonly commands: Readonly<Record<string, Slot<Deps>>>
+  readonly queries: Readonly<Record<string, Slot<Deps>>>
+  readonly events: Readonly<Partial<Record<string, ReadonlyArray<Subscription<Deps>>>>>
+}
+
+type SlotMessage<TSlots> = Parameters<Extract<TSlots[keyof TSlots], Slot<never>>>[0]
+
+type SubscriptionMessage<TSlots> =
+  NonNullable<TSlots[keyof TSlots]> extends ReadonlyArray<infer TSubscription>
+    ? Parameters<Extract<TSubscription, Subscription<never>>>[0]
+    : never
+
+/** The messages a registry has a slot for, read off each slot's first parameter. */
+export type RegistryMessage<TRegistry extends Handlers<never>> =
+  | SlotMessage<TRegistry['commands']>
+  | SlotMessage<TRegistry['queries']>
+  | SubscriptionMessage<TRegistry['events']>
+
+type SlotValue<TSlots, TName extends string> = TName extends keyof TSlots
+  ? Awaited<ReturnType<Extract<TSlots[TName], Slot<never>>>>
+  : never
+
+/** The value `bus.handle(message)` resolves to: the slot's own return type, or void for an event. */
+export type MessageResult<
+  TMessage extends Message,
+  TRegistry extends Handlers<never>,
+> = TMessage extends Command
+  ? SlotValue<TRegistry['commands'], TMessage['name']>
+  : TMessage extends Query
+    ? SlotValue<TRegistry['queries'], TMessage['name']>
+    : void

package/src/core/app-error.ts

@@ -0,0 +1,18 @@
+import type { FailureClassification } from './failure-classification.ts'
+
+/**
+ * The base of every expected failure. A subclass declares its tag and its classification,
+ * so no boundary has to guess what kind of failure it holds. A boundary tells our errors from
+ * raw throws with `instanceof AppError`; a value that fails it was never judged.
+ *
+ * A `readonly` field with a literal initializer keeps the literal type, so
+ * `readonly _tag = 'StoreUnavailable'` is enough for `Result` unions and `matchError`.
+ */
+export abstract class AppError extends Error {
+  abstract readonly _tag: string
+  abstract readonly classification: FailureClassification
+
+  override get name(): string {
+    return this._tag
+  }
+}

package/src/core/defects.ts

@@ -0,0 +1,20 @@
+import { panic } from 'better-result'
+
+/**
+ * Mark a line the types say cannot run. A union member without a branch stops compilation here.
+ *
+ * @throws Panic when a value outside the union arrives at runtime.
+ */
+export function unreachable(value: never): never {
+  return panic(`Unreachable: ${String(value)}`)
+}
+
+/**
+ * Mark a body that is not written yet. A defect, not an expected failure.
+ *
+ * @param what - The behavior the body will provide, such as `invoice export`.
+ * @throws Panic always.
+ */
+export function notImplemented(what: string): never {
+  return panic(`Not implemented: ${what}`)
+}

package/src/core/failure-classification.ts

@@ -0,0 +1,27 @@
+/**
+ * What one failure is, before any policy decides what to do about it.
+ *
+ * `transient`: the world may differ on the next attempt. `terminal`: repeating gives the
+ * same answer. `unknown`: nobody judged this error, so it came from outside unwrapped.
+ */
+export type FailureClassification = 'transient' | 'terminal' | 'unknown'
+
+/**
+ * Who is asking to repeat the work.
+ *
+ * An immediate owner holds a caller and a socket open. A durable owner already stored the
+ * work, so it can afford to try again on a failure nobody classified.
+ */
+export type RetryOwner = 'immediate' | 'durable'
+
+/** Decide whether one retry owner may repeat a failed operation. */
+export function shouldRetryFailure(args: {
+  readonly classification: FailureClassification
+  readonly repeatSafe: boolean
+  readonly owner: RetryOwner
+}): boolean {
+  if (!args.repeatSafe) return false
+  if (args.classification === 'transient') return true
+  if (args.classification === 'terminal') return false
+  return args.owner === 'durable'
+}

package/src/core/index.ts

@@ -0,0 +1,29 @@
+export { AppError } from './app-error.ts'
+export { notImplemented, unreachable } from './defects.ts'
+export {
+  shouldRetryFailure,
+  type FailureClassification,
+  type RetryOwner,
+} from './failure-classification.ts'
+export { isAbortError, isTransientTransportError } from './transport-classification.ts'
+export {
+  configureLogger,
+  consoleSink,
+  createLogger,
+  Logger,
+  LogLevel,
+  setLoggerErrorHook,
+  setLogSink,
+  type ErrorCaptureEntry,
+  type ErrorLogContext,
+  type LogEntry,
+  type LogFields,
+  type LogFormat,
+  type LoggerConfig,
+  type LoggerErrorHook,
+  type LoggerSettings,
+  type LogSink,
+  type LogThreshold,
+  type LogValue,
+  type SerializedError,
+} from './logger.ts'

package/src/core/logger.ts

@@ -0,0 +1,312 @@
+/**
+ * Module-scoped logging for every host.
+ *
+ * A logger emits one plain-data entry per log. The default sink hands it to `console` as an
+ * entry object for a log service or as a colored line for a person, selected at startup.
+ */
+
+/** A value a log entry may carry. Errors enter only through `Logger.error`. */
+export type LogValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | ReadonlyArray<LogValue>
+  | LogFields
+
+/** Named log values. */
+export type LogFields = { readonly [key: string]: LogValue }
+
+/**
+ * The supported log severity levels, in ascending order.
+ *
+ * A const object, not an enum, so a parsed environment value typed `'INFO'` is a `LogLevel`.
+ */
+export const LogLevel = {
+  DEBUG: 'DEBUG',
+  INFO: 'INFO',
+  WARN: 'WARN',
+  ERROR: 'ERROR',
+} as const
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel]
+
+/** An error as plain data: name, message, stack, allowlisted fields, and the cause chain. */
+export type SerializedError = {
+  readonly name: string
+  readonly message: string
+  readonly stack?: string
+  readonly fields?: LogFields
+  readonly cause?: SerializedError
+}
+
+/** One log, as the sink receives it. Plain data, safe to stringify. */
+export type LogEntry = {
+  readonly timestamp: string
+  readonly level: LogLevel
+  readonly module: string
+  readonly message: string
+  readonly data: ReadonlyArray<LogValue>
+  /** Present on `Logger.error` entries that carried an error. */
+  readonly error?: SerializedError
+}
+
+/** The context an error log carries. */
+export type ErrorLogContext = {
+  readonly error?: unknown
+  readonly userId?: string
+  readonly details?: LogFields
+}
+
+/** What a logger lets through: a level and everything above it, or nothing. */
+export type LogThreshold = LogLevel | 'OFF'
+
+/** Overrides the application settings for one logger. */
+export interface LoggerConfig {
+  readonly level?: LogThreshold
+}
+
+/** `json` writes the entry object. `pretty` writes one readable line for a person. */
+export type LogFormat = 'json' | 'pretty'
+
+/**
+ * The application settings, set once at the composition root.
+ *
+ * An omitted field keeps its default. An explicit `undefined` is a compile error, so the root
+ * parses an environment value before passing it. The logger reads no environment itself.
+ */
+export interface LoggerSettings extends LoggerConfig {
+  readonly format?: LogFormat
+}
+
+// The production server setting, so a root that never configures still logs safely.
+const DEFAULT_SETTINGS: Required<LoggerSettings> = {
+  level: LogLevel.INFO,
+  format: 'json',
+}
+
+// The application configures once at startup; loggers can exist before startup completes.
+let settings = DEFAULT_SETTINGS
+
+/**
+ * Set application settings, including for existing loggers. Per-logger overrides take priority.
+ * Call at startup, never per request. An omitted field resets to INFO and JSON output.
+ */
+export function configureLogger(config: LoggerSettings): void {
+  settings = {
+    level: config.level ?? DEFAULT_SETTINGS.level,
+    format: config.format ?? DEFAULT_SETTINGS.format,
+  }
+}
+
+/** The error data sent to the configured error hook. */
+export interface ErrorCaptureEntry {
+  readonly error: unknown
+  readonly distinctId: string | undefined
+  readonly context: LogFields
+}
+
+/** A function that forwards one logged error to an error service. */
+export type LoggerErrorHook = (entry: ErrorCaptureEntry) => void
+
+/** Where every log entry goes. */
+export type LogSink = (entry: LogEntry) => void
+
+let errorHook: LoggerErrorHook | null = null
+
+/**
+ * Register the function that receives each logged error.
+ *
+ * Set once at the process entry point. A later call replaces the earlier hook.
+ */
+export function setLoggerErrorHook(fn: LoggerErrorHook): void {
+  errorHook = fn
+}
+
+// One console method per level, so a host that filters by method can tell them apart.
+const CONSOLE_METHOD = {
+  [LogLevel.DEBUG]: 'debug',
+  [LogLevel.INFO]: 'info',
+  [LogLevel.WARN]: 'warn',
+  [LogLevel.ERROR]: 'error',
+} as const satisfies Record<LogLevel, 'debug' | 'info' | 'warn' | 'error'>
+
+// Built from the code point so no raw control character sits in the source.
+const ESC = String.fromCharCode(27)
+const ANSI_RESET = `${ESC}[0m`
+const ANSI_GRAY = `${ESC}[90m`
+const ANSI_BLUE = `${ESC}[34m`
+
+// Severity reads at a glance: quiet levels stay dim, and an error is the only bold line.
+const LEVEL_ANSI = {
+  DEBUG: `${ESC}[2;36m`,
+  INFO: ANSI_BLUE,
+  WARN: `${ESC}[33m`,
+  ERROR: `${ESC}[1;31m`,
+} satisfies Record<LogLevel, string>
+
+function prettyLine(entry: LogEntry): string {
+  // Node prints debug and info exactly like log, so the level must be in the text too.
+  const level = `[${entry.level}]`
+  const module = `[${entry.module}]`
+  // A browser console colors by method on its own; a terminal needs ANSI to do the same.
+  if ('window' in globalThis) return `${entry.timestamp} ${level} ${module} ${entry.message}`
+  const timestamp = `${ANSI_GRAY}${entry.timestamp}${ANSI_RESET}`
+  const coloredLevel = `${LEVEL_ANSI[entry.level]}${level}${ANSI_RESET}`
+  const coloredModule = `${ANSI_BLUE}${module}${ANSI_RESET}`
+  return `${timestamp} ${coloredLevel} ${coloredModule} ${entry.message}`
+}
+
+/**
+ * JSON format writes the entry object. Pretty format writes one line, then the data,
+ * the error, and the stack as separate console arguments.
+ */
+export const consoleSink: LogSink = (entry) => {
+  // Resolved per call, so a console replaced after import still receives the output.
+  const write = console[CONSOLE_METHOD[entry.level]]
+  if (settings.format === 'json') {
+    write(entry)
+    return
+  }
+  const line = prettyLine(entry)
+  if (entry.error === undefined) {
+    write(line, ...entry.data)
+    return
+  }
+  // A stack inside an object prints as one quoted string; as its own argument it prints as lines.
+  const { stack, ...error } = entry.error
+  if (stack === undefined) write(line, ...entry.data, error)
+  else write(line, ...entry.data, error, `\n${stack}`)
+}
+
+let logSink: LogSink = consoleSink
+
+/**
+ * Send every log entry somewhere other than `console`.
+ *
+ * Set once at the process entry point, never per module. A logger is created
+ * by name and nothing else, so its destination is a fact about the process.
+ */
+export function setLogSink(fn: LogSink): void {
+  logSink = fn
+}
+
+const LOG_LEVELS = Object.values(LogLevel)
+const MAX_ERROR_CAUSE_DEPTH = 3
+
+/**
+ * Diagnostics worth keeping off an error, named one by one.
+ *
+ * An allowlist rather than every own property: an error raised by a library we
+ * do not control may hang a request or a user payload off itself, and a log is
+ * the wrong place to discover that. `_tag` and `classification` are what every `AppError`
+ * declares. `remote` and the three flags after it are the ones workerd sets itself.
+ */
+const KEPT_ERROR_FIELDS = [
+  '_tag',
+  'classification',
+  'code',
+  'operation',
+  'status',
+  'statusCode',
+  'remote',
+  'retryable',
+  'overloaded',
+  'durableObjectReset',
+] as const
+
+type ErrorDiagnostics = Error & { readonly [K in (typeof KEPT_ERROR_FIELDS)[number]]?: LogValue }
+
+type MutableSerializedError = { -readonly [K in keyof SerializedError]: SerializedError[K] }
+
+const serializeError = (error: Error, depth = 0): SerializedError => {
+  if (depth > MAX_ERROR_CAUSE_DEPTH) return { name: 'Error', message: '[cause chain truncated]' }
+
+  // Every field is optional, so an `Error` is already one of these.
+  const carrier: ErrorDiagnostics = error
+  const kept = KEPT_ERROR_FIELDS.filter((key) => carrier[key] !== undefined)
+  const serialized: MutableSerializedError = { name: error.name, message: error.message }
+  if (depth === 0 && error.stack !== undefined) serialized.stack = error.stack
+  if (kept.length > 0)
+    serialized.fields = Object.fromEntries(kept.map((key) => [key, carrier[key]]))
+  if (error.cause instanceof Error) serialized.cause = serializeError(error.cause, depth + 1)
+  else if (error.cause !== undefined)
+    serialized.cause = { name: 'Error', message: '[non-error cause]' }
+  return serialized
+}
+
+/** Write module-scoped logs with application defaults and optional overrides. */
+export class Logger {
+  private readonly config: LoggerConfig
+
+  /** Create a logger for one module. */
+  constructor(
+    private readonly module: string,
+    overrideConfig?: LoggerConfig,
+  ) {
+    this.config = { ...overrideConfig }
+  }
+
+  private log(
+    level: LogLevel,
+    message: string,
+    data: ReadonlyArray<LogValue>,
+    error?: SerializedError,
+  ): void {
+    const threshold = this.config.level ?? settings.level
+    if (threshold === 'OFF') return
+    if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf(threshold)) return
+
+    const entry = { timestamp: new Date().toISOString(), level, module: this.module, message, data }
+    logSink(error === undefined ? entry : { ...entry, error })
+  }
+
+  /** Write a debug log. */
+  debug(message: string, ...values: ReadonlyArray<LogValue>): void {
+    this.log(LogLevel.DEBUG, message, values)
+  }
+
+  /** Write an information log. */
+  info(message: string, ...values: ReadonlyArray<LogValue>): void {
+    this.log(LogLevel.INFO, message, values)
+  }
+
+  /** Write a warning log. */
+  warn(message: string, ...values: ReadonlyArray<LogValue>): void {
+    this.log(LogLevel.WARN, message, values)
+  }
+
+  /**
+   * Write an error log and send the error to the configured hook.
+   *
+   * The details say which call this was, and the error says what went wrong
+   * inside it. The entry carries the details as data and the error beside them.
+   */
+  error(message: string, context: ErrorLogContext = {}): void {
+    const details = context.details ?? {}
+    const thrown = context.error
+    let error: SerializedError | undefined
+    if (thrown instanceof Error) {
+      error = serializeError(thrown)
+    } else if (thrown !== undefined) {
+      // Not an `Error`, so there is no name or stack to keep, only its JSON form.
+      let json: string
+      try {
+        json = JSON.stringify(thrown)
+      } catch {
+        json = '[non-serializable error]'
+      }
+      error = { name: 'NonError', message: json }
+    }
+    this.log(LogLevel.ERROR, message, context.details === undefined ? [] : [details], error)
+
+    if (errorHook !== null && thrown !== undefined) {
+      errorHook({ error: thrown, distinctId: context.userId, context: details })
+    }
+  }
+}
+
+/** Create a logger for one module. */
+export function createLogger(module: string, config?: LoggerConfig): Logger {
+  return new Logger(module, config)
+}

package/src/core/transport-classification.ts

@@ -0,0 +1,28 @@
+/**
+ * Messages that the platform-neutral transports raise for a failure that may pass.
+ *
+ * A boundary that knows its own runtime adds its own patterns before these.
+ */
+const TRANSIENT_TRANSPORT_PATTERNS = [
+  /network/,
+  /fetch failed/,
+  /timeout/,
+  /timed?\s*out/,
+  /connection.*(lost|reset|refused|closed|aborted)/,
+  /econnreset/,
+  /econnrefused/,
+  /etimedout/,
+  /eai_again/,
+]
+
+/** Cancellation is a decision, not a failure to repeat. */
+export function isAbortError(cause: unknown): boolean {
+  return cause instanceof Error && cause.name === 'AbortError'
+}
+
+/** Match known transient transport messages while excluding explicit cancellation. */
+export function isTransientTransportError(cause: unknown): boolean {
+  if (!(cause instanceof Error) || isAbortError(cause)) return false
+  const message = cause.message.toLowerCase()
+  return TRANSIENT_TRANSPORT_PATTERNS.some((pattern) => pattern.test(message))
+}