better-ship 0.3.2 → 0.4.0

package/src/infrastructure/postgres/postgres-database-types.ts

@@ -0,0 +1,27 @@
+import type { ExtractTablesWithRelations } from 'drizzle-orm'
+import type { drizzle, PostgresJsDatabase, PostgresJsTransaction } from 'drizzle-orm/postgres-js'
+
+import type { DrizzleSchema } from '../drizzle-schema.ts'
+
+/** The postgres.js client passed to Drizzle, including clients configured through Hyperdrive. */
+export type PostgresConnection = ReturnType<typeof drizzle>['$client']
+
+/** The application's Drizzle Postgres database, preserving its schema and relational query types. */
+export type PostgresDb<Schema extends DrizzleSchema> = PostgresJsDatabase<Schema>
+
+/** Exposes Drizzle query methods without insert, update, delete, transaction, or raw execution methods. */
+export type PostgresReadDb<Schema extends DrizzleSchema> = Pick<
+  PostgresDb<Schema>,
+  'select' | 'selectDistinct' | 'selectDistinctOn' | 'query'
+>
+
+/** The native Drizzle transaction with the application's full schema and derived relation types. */
+export type PostgresDbTransaction<Schema extends DrizzleSchema> = PostgresJsTransaction<
+  Schema,
+  ExtractTablesWithRelations<Schema>
+>
+
+/** The database transaction supplied to participating repositories by the Postgres adapter. */
+export type PostgresTx<Schema extends DrizzleSchema> = {
+  readonly db: PostgresDbTransaction<Schema>
+}

package/src/infrastructure/postgres/postgres-message-store.ts

@@ -0,0 +1,32 @@
+import {
+  MessageAlreadyProcessedError,
+  type Event,
+  type IMessageStore,
+  type MessageId,
+} from '@/application'
+
+import type { DrizzleSchema } from '../drizzle-schema.ts'
+import type { PostgresDbTransaction } from './postgres-database-types.ts'
+import { messageOutbox, processedMessages } from './postgres-schema.ts'
+
+/** Processed messages and outbox events share the active Postgres transaction; the insert result establishes the claim. */
+export class PostgresMessageStore<Schema extends DrizzleSchema> implements IMessageStore {
+  constructor(private readonly db: PostgresDbTransaction<Schema>) {}
+
+  async claim(messageId: MessageId): Promise<void> {
+    const claimed = await this.db
+      .insert(processedMessages)
+      .values({ messageId })
+      .onConflictDoNothing()
+      .returning({ messageId: processedMessages.messageId })
+    // Thrown inside the transaction, so drizzle rolls back everything written before the claim.
+    if (claimed.length === 0) throw new MessageAlreadyProcessedError(messageId)
+  }
+
+  async persistEvents(events: ReadonlyArray<Event>): Promise<void> {
+    if (events.length === 0) return
+    await this.db
+      .insert(messageOutbox)
+      .values(events.map((event) => ({ id: event.id, payload: event })))
+  }
+}

package/src/infrastructure/postgres/postgres-schema.ts

@@ -0,0 +1,33 @@
+import { isNull } from 'drizzle-orm'
+import { index, integer, jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core'
+
+import type { Event } from '@/application'
+
+/** One row per committed message. The primary key is the idempotency claim. */
+export const processedMessages = pgTable('processed_messages', {
+  messageId: text('message_id').primaryKey(),
+  processedAt: timestamp('processed_at', { withTimezone: true }).notNull().defaultNow(),
+})
+
+/** Events committed with their state change, waiting for the relay to deliver them. */
+export const messageOutbox = pgTable(
+  'message_outbox',
+  {
+    id: text('id').primaryKey(),
+    payload: jsonb('payload').$type<Event>().notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    availableAt: timestamp('available_at', { withTimezone: true }).notNull().defaultNow(),
+    attempts: integer('attempts').notNull().default(0),
+    claimToken: text('claim_token'),
+    claimExpiresAt: timestamp('claim_expires_at', { withTimezone: true }),
+    publishedAt: timestamp('published_at', { withTimezone: true }),
+    failedAt: timestamp('failed_at', { withTimezone: true }),
+    lastError: text('last_error'),
+  },
+  (table) => [
+    index('idx_message_outbox_due')
+      .on(table.availableAt, table.createdAt)
+      .where(isNull(table.publishedAt)),
+    index('idx_message_outbox_claim_token').on(table.claimToken),
+  ],
+)

package/src/infrastructure/postgres/postgres-transaction.ts

@@ -0,0 +1,22 @@
+import type { ITransaction } from '@/application'
+
+import type { DrizzleSchema } from '../drizzle-schema.ts'
+import { runWithUnitOfWorkContext } from '../unit-of-work-context.ts'
+import { executeDatabase } from './postgres-database-execution.ts'
+import type { PostgresDb, PostgresTx } from './postgres-database-types.ts'
+
+/**
+ * The Postgres transaction boundary uses native Drizzle transactions through postgres.js.
+ * Drizzle commits when `work` returns and rolls back when it throws.
+ */
+export class PostgresTransaction<Schema extends DrizzleSchema> implements ITransaction<
+  PostgresTx<Schema>
+> {
+  constructor(private readonly db: PostgresDb<Schema>) {}
+
+  transaction<T>(work: (tx: PostgresTx<Schema>) => Promise<T>): Promise<T> {
+    return runWithUnitOfWorkContext('postgres', () =>
+      executeDatabase('unit of work transaction', () => this.db.transaction((db) => work({ db }))),
+    )
+  }
+}

package/src/infrastructure/unit-of-work-context.ts

@@ -0,0 +1,55 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+import { panic } from 'better-result'
+import type { BatchItem } from 'drizzle-orm/batch'
+
+import { UnitOfWorkAlreadyActiveError, type Event, type IEventCollector } from '@/application'
+
+type UnitOfWorkContext = { readonly events: Event[] } & (
+  | { readonly database: 'd1'; readonly statements: BatchItem<'sqlite'>[] }
+  | { readonly database: 'postgres' }
+)
+
+// One async scope isolates events and D1 statements and rejects nesting across both adapters.
+const storage = new AsyncLocalStorage<UnitOfWorkContext>()
+
+/** Reject nested transactions before database work starts; preserve independent concurrent execution. */
+export async function runWithUnitOfWorkContext<T>(
+  database: UnitOfWorkContext['database'],
+  work: () => Promise<T>,
+): Promise<T> {
+  if (storage.getStore() !== undefined) throw new UnitOfWorkAlreadyActiveError()
+  const context: UnitOfWorkContext =
+    database === 'd1' ? { database, events: [], statements: [] } : { database, events: [] }
+  return storage.run(context, work)
+}
+
+/** Inject this shared scope into the unit of work and expose its emitter to application handlers. */
+export const eventCollector: IEventCollector = {
+  emit(event) {
+    currentContext().events.push(event)
+  },
+  collect() {
+    return [...currentContext().events]
+  },
+}
+
+/** Queue one native D1 statement for the active batch; other contexts cannot accept D1 writes. */
+export function stageD1Statement(statement: BatchItem<'sqlite'>): void {
+  d1Context().statements.push(statement)
+}
+
+/** Read the active D1 batch in staging order for commit. */
+export function collectD1Statements(): ReadonlyArray<BatchItem<'sqlite'>> {
+  return [...d1Context().statements]
+}
+
+function d1Context(): Extract<UnitOfWorkContext, { database: 'd1' }> {
+  const context = currentContext()
+  if (context.database !== 'd1') return panic('D1 statements require a D1 unit of work')
+  return context
+}
+
+function currentContext(): UnitOfWorkContext {
+  return storage.getStore() ?? panic('operation requires an active unit of work')
+}

package/dist/application.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"application.d.ts","names":[],"sources":["../src/application/messages.ts","../src/application/message-bus.errors.ts","../src/application/handlers.ts","../src/application/registry.ts","../src/application/message-bus.ts"],"mappings":";;;;;;;;;KAOY;;KAGA,QAAQ;WACT;WACA,MAAM;WACN,IAAI;;;KAIH,MAAM;WACP;WACA,MAAM;;;KAIL,MAAM;WACP;WACA,MAAM;WACN,IAAI;;;KAIH,UAAU,UAAU,QAAQ;;;;;;;qBCtB3B,8BAA8B;WAIpB,WAAW;WAHvB;WACA;EAET,YAAqB,WAAW;;;;;;;;KCNtB,eAAe,iBAAiB,SAAS,MAAM,UACzD,SAAS,UACT,MAAM,SACH,QAAQ;;;;;KAMD,aAAa,eAAe,OAAO,WAAW,UACxD,OAAO,QACP,MAAM,cACH,QAAQ;;KAGD,aAAa,eAAe,OAAO,SAAS,OAAO,QAAQ,MAAM,SAAS;;;;KCjB1E,gBAAgB,iBAAiB,SAAS,oBAC1C,KAAK,YAAY,YAAY,eAAe,GAAG;;KAI/C,cAAc,eAAe,OAAO,yBACpC,KAAK,UAAU,YAAY,aAAa,GAAG;;;;;KAO3C,cAAc,eAAe,OAAO,oBACpC,KAAK,UAAU,aAAa,cAAc,aAAa,GAAG;;;;;;KAQ1D,gBAAgB,iBAAiB,SAAS,aAAa,WAAW;WACnE,UAAU,gBAAgB,QAAQ,UAAU,UAAU;WACtD,SAAS,cAAc,QAAQ,UAAU,QAAQ;WACjD,QAAQ,cAAc,QAAQ,UAAU,QAAQ;;KAKtD,KAAK;EAAU,OAAO,SAAS,SAAS,MAAM,OAAO;;KACrD,aAAa;EAAU,OAAO,OAAO,OAAO,MAAM,OAAO;;;;;;KAMlD,SAAS;WACV,UAAU,SAAS,eAAe,KAAK;WACvC,SAAS,SAAS,eAAe,KAAK;WACtC,QAAQ,SAAS,QAAQ,eAAe,cAAc,aAAa;;KAGzE,YAAY,UAAU,WAAW,QAAQ,aAAa,SAAS;KAE/D,oBAAoB,UACvB,YAAY,aAAa,iBAAiB,oBAAoB,iBAC1D,WAAW,QAAQ,eAAe;;KAI5B,gBAAgB,kBAAkB,mBAC1C,YAAY,yBACZ,YAAY,wBACZ,oBAAoB;KAEnB,UAAU,QAAQ,wBAAwB,oBAAoB,SAC/D,QAAQ,WAAW,QAAQ,OAAO,QAAQ;;KAIlC,cACV,iBAAiB,SACjB,kBAAkB,mBAChB,iBAAiB,UACjB,UAAU,uBAAuB,oBACjC,iBAAiB,QACf,UAAU,sBAAsB;;;;UC5DrB,YAAY,kBAAkB;EAC7C,OAAO,iBAAiB,UAAU,gBAAgB,YAChD,SAAS,WACR,QAAQ,cAAc,UAAU;;;;;;qBAOxB,WAAW,MAAM,kBAAkB,SAAS,kBAAkB,YAAY;mBAElE;mBACA;EAFnB,YACmB,MAAM,MACN,UAAU;;EAIvB,OAAO,iBAAiB,UAAU,gBAAgB,YACtD,SAAS,WACR,QAAQ,cAAc,UAAU;UAM3B;UASA;UASA;;;;;;UAWM"}

package/dist/application.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"application.js","names":[],"sources":["../src/application/message-bus.errors.ts","../src/application/message-bus.ts"],"sourcesContent":["import { AppError } from '@/core'\n\nimport type { MessageId } from './messages.ts'\n\n/**\n * The unit of work throws this when a message's effects already committed.\n * The bus counts an event subscriber that throws it as delivered. From a command it reaches the caller.\n */\nexport class DuplicateMessageError extends AppError {\n  readonly _tag = 'DuplicateMessageError'\n  readonly classification = 'terminal'\n\n  constructor(readonly messageId: MessageId) {\n    super(`message ${messageId} already committed`)\n  }\n}\n","import { panic } from 'better-result'\n\nimport { createLogger, unreachable } from '@/core'\n\nimport { DuplicateMessageError } from './message-bus.errors.ts'\nimport type { Command, Event, Message, Query } from './messages.ts'\nimport type { Handlers, MessageResult, RegistryMessage } from './registry.ts'\n\nconst logger = createLogger('message-bus')\n\n/** The port an entrypoint dispatches through. `AppDeps` names this as `IMessageBus<typeof registry>`. */\nexport interface IMessageBus<TRegistry extends Handlers<never>> {\n  handle<TMessage extends Message & RegistryMessage<TRegistry>>(\n    message: TMessage,\n  ): Promise<MessageResult<TMessage, TRegistry>>\n}\n\n/**\n * Routes one message to its slot. The bus opens no transaction and keeps no outbox:\n * a handler that writes opens the unit of work itself.\n */\nexport class MessageBus<Deps, TRegistry extends Handlers<Deps>> implements IMessageBus<TRegistry> {\n  constructor(\n    private readonly deps: Deps,\n    private readonly registry: TRegistry,\n  ) {}\n\n  /** Resolves to the handler's own value for a command or query, and to void for an event. */\n  async handle<TMessage extends Message & RegistryMessage<TRegistry>>(\n    message: TMessage,\n  ): Promise<MessageResult<TMessage, TRegistry>> {\n    // SAFETY: the slot for this name is what `MessageResult` names, and dispatch returns its value.\n    return (await this.dispatch(message)) as MessageResult<TMessage, TRegistry>\n  }\n\n  // oxlint-disable-next-line anti-slop/no-unknown-returns -- one table holds every slot's value; `handle` names it.\n  private dispatch(message: Message): Promise<unknown> {\n    if (message.type === 'command') return this.handleCommand(message)\n    if (message.type === 'query') return this.handleQuery(message)\n    if (message.type === 'event') return this.handleEvent(message)\n    // A message parsed at a boundary cannot reach here; one that does must not resolve silently.\n    return unreachable(message)\n  }\n\n  // oxlint-disable-next-line anti-slop/no-unknown-returns -- see dispatch.\n  private handleCommand(command: Command): Promise<unknown> {\n    // `satisfies` proved the registry complete, so a missing slot is a broken registry object.\n    const handler = this.registry.commands[command.name]\n    if (handler === undefined) return panic(`No handler for command ${command.name}`)\n    logger.debug('handling_command', { name: command.name, id: command.id })\n    return handler(command, this.deps)\n  }\n\n  // oxlint-disable-next-line anti-slop/no-unknown-returns -- see dispatch.\n  private handleQuery(query: Query): Promise<unknown> {\n    const handler = this.registry.queries[query.name]\n    if (handler === undefined) return panic(`No handler for query ${query.name}`)\n    return handler(query, this.deps)\n  }\n\n  /**\n   * Every subscriber runs to completion. One failure is rethrown as is. Several are thrown as\n   * one `AggregateError`. A `DuplicateMessageError` means that subscriber already committed on\n   * an earlier delivery, so it counts as delivered.\n   */\n  private async handleEvent(event: Event): Promise<void> {\n    const subscriptions = this.registry.events[event.name] ?? []\n    const outcomes = await Promise.allSettled(\n      subscriptions.map((subscription) => subscription(event, this.deps)),\n    )\n    const failures: unknown[] = []\n    for (const [subscriber, outcome] of outcomes.entries()) {\n      if (outcome.status === 'fulfilled') continue\n      if (outcome.reason instanceof DuplicateMessageError) {\n        // The bus swallows this error, so this line is the only record that the skip happened.\n        logger.info('duplicate_subscriber_ignored', { event: event.name, id: event.id, subscriber })\n        continue\n      }\n      failures.push(outcome.reason)\n    }\n    if (failures.length === 1) throw failures[0]\n    if (failures.length > 1) {\n      throw new AggregateError(failures, `${event.name}: ${failures.length} subscribers failed`)\n    }\n  }\n}\n"],"mappings":";;;;;;;;AAQA,IAAa,wBAAb,cAA2C,SAAS;CAI7B;CAHrB,AAAS,OAAO;CAChB,AAAS,iBAAiB;CAE1B,YAAY,AAAS,WAAsB;EACzC,MAAM,WAAW,UAAU,mBAAmB;EAD3B;CAErB;AACF;;;;ACPA,MAAM,SAAS,aAAa,aAAa;;;;;AAazC,IAAa,aAAb,MAAkG;CAE7E;CACA;CAFnB,YACE,AAAiB,MACjB,AAAiB,UACjB;EAFiB;EACA;CAChB;;CAGH,MAAM,OACJ,SAC6C;EAE7C,OAAQ,MAAM,KAAK,SAAS,OAAO;CACrC;CAGA,AAAQ,SAAS,SAAoC;EACnD,IAAI,QAAQ,SAAS,WAAW,OAAO,KAAK,cAAc,OAAO;EACjE,IAAI,QAAQ,SAAS,SAAS,OAAO,KAAK,YAAY,OAAO;EAC7D,IAAI,QAAQ,SAAS,SAAS,OAAO,KAAK,YAAY,OAAO;EAE7D,OAAO,YAAY,OAAO;CAC5B;CAGA,AAAQ,cAAc,SAAoC;EAExD,MAAM,UAAU,KAAK,SAAS,SAAS,QAAQ;EAC/C,IAAI,YAAY,QAAW,OAAO,MAAM,0BAA0B,QAAQ,MAAM;EAChF,OAAO,MAAM,oBAAoB;GAAE,MAAM,QAAQ;GAAM,IAAI,QAAQ;EAAG,CAAC;EACvE,OAAO,QAAQ,SAAS,KAAK,IAAI;CACnC;CAGA,AAAQ,YAAY,OAAgC;EAClD,MAAM,UAAU,KAAK,SAAS,QAAQ,MAAM;EAC5C,IAAI,YAAY,QAAW,OAAO,MAAM,wBAAwB,MAAM,MAAM;EAC5E,OAAO,QAAQ,OAAO,KAAK,IAAI;CACjC;;;;;;CAOA,MAAc,YAAY,OAA6B;EACrD,MAAM,gBAAgB,KAAK,SAAS,OAAO,MAAM,SAAS,CAAC;EAC3D,MAAM,WAAW,MAAM,QAAQ,WAC7B,cAAc,KAAK,iBAAiB,aAAa,OAAO,KAAK,IAAI,CAAC,CACpE;EACA,MAAM,WAAsB,CAAC;EAC7B,KAAK,MAAM,CAAC,YAAY,YAAY,SAAS,QAAQ,GAAG;GACtD,IAAI,QAAQ,WAAW,aAAa;GACpC,IAAI,QAAQ,kBAAkB,uBAAuB;IAEnD,OAAO,KAAK,gCAAgC;KAAE,OAAO,MAAM;KAAM,IAAI,MAAM;KAAI;IAAW,CAAC;IAC3F;GACF;GACA,SAAS,KAAK,QAAQ,MAAM;EAC9B;EACA,IAAI,SAAS,WAAW,GAAG,MAAM,SAAS;EAC1C,IAAI,SAAS,SAAS,GACpB,MAAM,IAAI,eAAe,UAAU,GAAG,MAAM,KAAK,IAAI,SAAS,OAAO,oBAAoB;CAE7F;AACF"}

package/dist/core-D0asUCvq.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"core-D0asUCvq.js","names":[],"sources":["../src/core/app-error.ts","../src/core/defects.ts","../src/core/failure-classification.ts","../src/core/transport-classification.ts","../src/core/logger.ts"],"sourcesContent":["import type { FailureClassification } from './failure-classification.ts'\n\n/**\n * The base of every expected failure. A subclass declares its tag and its classification,\n * so no boundary has to guess what kind of failure it holds. A boundary tells our errors from\n * raw throws with `instanceof AppError`; a value that fails it was never judged.\n *\n * A `readonly` field with a literal initializer keeps the literal type, so\n * `readonly _tag = 'StoreUnavailable'` is enough for `Result` unions and `matchError`.\n */\nexport abstract class AppError extends Error {\n  abstract readonly _tag: string\n  abstract readonly classification: FailureClassification\n\n  override get name(): string {\n    return this._tag\n  }\n}\n","import { panic } from 'better-result'\n\n/**\n * Mark a line the types say cannot run. A union member without a branch stops compilation here.\n *\n * @throws Panic when a value outside the union arrives at runtime.\n */\nexport function unreachable(value: never): never {\n  return panic(`Unreachable: ${String(value)}`)\n}\n\n/**\n * Mark a body that is not written yet. A defect, not an expected failure.\n *\n * @param what - The behavior the body will provide, such as `invoice export`.\n * @throws Panic always.\n */\nexport function notImplemented(what: string): never {\n  return panic(`Not implemented: ${what}`)\n}\n","/**\n * What one failure is, before any policy decides what to do about it.\n *\n * `transient`: the world may differ on the next attempt. `terminal`: repeating gives the\n * same answer. `unknown`: nobody judged this error, so it came from outside unwrapped.\n */\nexport type FailureClassification = 'transient' | 'terminal' | 'unknown'\n\n/**\n * Who is asking to repeat the work.\n *\n * An immediate owner holds a caller and a socket open. A durable owner already stored the\n * work, so it can afford to try again on a failure nobody classified.\n */\nexport type RetryOwner = 'immediate' | 'durable'\n\n/** Decide whether one retry owner may repeat a failed operation. */\nexport function shouldRetryFailure(args: {\n  readonly classification: FailureClassification\n  readonly repeatSafe: boolean\n  readonly owner: RetryOwner\n}): boolean {\n  if (!args.repeatSafe) return false\n  if (args.classification === 'transient') return true\n  if (args.classification === 'terminal') return false\n  return args.owner === 'durable'\n}\n","/**\n * Messages that the platform-neutral transports raise for a failure that may pass.\n *\n * A boundary that knows its own runtime adds its own patterns before these.\n */\nconst TRANSIENT_TRANSPORT_PATTERNS = [\n  /network/,\n  /fetch failed/,\n  /timeout/,\n  /timed?\\s*out/,\n  /connection.*(lost|reset|refused|closed|aborted)/,\n  /econnreset/,\n  /econnrefused/,\n  /etimedout/,\n  /eai_again/,\n]\n\n/** Cancellation is a decision, not a failure to repeat. */\nexport function isAbortError(cause: unknown): boolean {\n  return cause instanceof Error && cause.name === 'AbortError'\n}\n\n/** Match known transient transport messages while excluding explicit cancellation. */\nexport function isTransientTransportError(cause: unknown): boolean {\n  if (!(cause instanceof Error) || isAbortError(cause)) return false\n  const message = cause.message.toLowerCase()\n  return TRANSIENT_TRANSPORT_PATTERNS.some((pattern) => pattern.test(message))\n}\n","/**\n * Module-scoped logging for every host.\n *\n * A logger emits one plain-data entry per log. The default sink hands it to `console` as an\n * entry object for a log service or as a colored line for a person, selected at startup.\n */\n\n/** A value a log entry may carry. Errors enter only through `Logger.error`. */\nexport type LogValue =\n  | string\n  | number\n  | boolean\n  | null\n  | undefined\n  | ReadonlyArray<LogValue>\n  | LogFields\n\n/** Named log values. */\nexport type LogFields = { readonly [key: string]: LogValue }\n\n/**\n * The supported log severity levels, in ascending order.\n *\n * A const object, not an enum, so a parsed environment value typed `'INFO'` is a `LogLevel`.\n */\nexport const LogLevel = {\n  DEBUG: 'DEBUG',\n  INFO: 'INFO',\n  WARN: 'WARN',\n  ERROR: 'ERROR',\n} as const\nexport type LogLevel = (typeof LogLevel)[keyof typeof LogLevel]\n\n/** An error as plain data: name, message, stack, allowlisted fields, and the cause chain. */\nexport type SerializedError = {\n  readonly name: string\n  readonly message: string\n  readonly stack?: string\n  readonly fields?: LogFields\n  readonly cause?: SerializedError\n}\n\n/** One log, as the sink receives it. Plain data, safe to stringify. */\nexport type LogEntry = {\n  readonly timestamp: string\n  readonly level: LogLevel\n  readonly module: string\n  readonly message: string\n  readonly data: ReadonlyArray<LogValue>\n  /** Present on `Logger.error` entries that carried an error. */\n  readonly error?: SerializedError\n}\n\n/** The context an error log carries. */\nexport type ErrorLogContext = {\n  readonly error?: unknown\n  readonly userId?: string\n  readonly details?: LogFields\n}\n\n/** What a logger lets through: a level and everything above it, or nothing. */\nexport type LogThreshold = LogLevel | 'OFF'\n\n/** Overrides the application settings for one logger. */\nexport interface LoggerConfig {\n  readonly level?: LogThreshold\n}\n\n/** `json` writes the entry object. `pretty` writes one readable line for a person. */\nexport type LogFormat = 'json' | 'pretty'\n\n/**\n * The application settings, set once at the composition root.\n *\n * An omitted field keeps its default. An explicit `undefined` is a compile error, so the root\n * parses an environment value before passing it. The logger reads no environment itself.\n */\nexport interface LoggerSettings extends LoggerConfig {\n  readonly format?: LogFormat\n}\n\n// The production server setting, so a root that never configures still logs safely.\nconst DEFAULT_SETTINGS: Required<LoggerSettings> = {\n  level: LogLevel.INFO,\n  format: 'json',\n}\n\n// The application configures once at startup; loggers can exist before startup completes.\nlet settings = DEFAULT_SETTINGS\n\n/**\n * Set application settings, including for existing loggers. Per-logger overrides take priority.\n * Call at startup, never per request. An omitted field resets to INFO and JSON output.\n */\nexport function configureLogger(config: LoggerSettings): void {\n  settings = {\n    level: config.level ?? DEFAULT_SETTINGS.level,\n    format: config.format ?? DEFAULT_SETTINGS.format,\n  }\n}\n\n/** The error data sent to the configured error hook. */\nexport interface ErrorCaptureEntry {\n  readonly error: unknown\n  readonly distinctId: string | undefined\n  readonly context: LogFields\n}\n\n/** A function that forwards one logged error to an error service. */\nexport type LoggerErrorHook = (entry: ErrorCaptureEntry) => void\n\n/** Where every log entry goes. */\nexport type LogSink = (entry: LogEntry) => void\n\nlet errorHook: LoggerErrorHook | null = null\n\n/**\n * Register the function that receives each logged error.\n *\n * Set once at the process entry point. A later call replaces the earlier hook.\n */\nexport function setLoggerErrorHook(fn: LoggerErrorHook): void {\n  errorHook = fn\n}\n\n// One console method per level, so a host that filters by method can tell them apart.\nconst CONSOLE_METHOD = {\n  [LogLevel.DEBUG]: 'debug',\n  [LogLevel.INFO]: 'info',\n  [LogLevel.WARN]: 'warn',\n  [LogLevel.ERROR]: 'error',\n} as const satisfies Record<LogLevel, 'debug' | 'info' | 'warn' | 'error'>\n\n// Built from the code point so no raw control character sits in the source.\nconst ESC = String.fromCharCode(27)\nconst ANSI_RESET = `${ESC}[0m`\nconst ANSI_GRAY = `${ESC}[90m`\nconst ANSI_BLUE = `${ESC}[34m`\n\n// Severity reads at a glance: quiet levels stay dim, and an error is the only bold line.\nconst LEVEL_ANSI = {\n  DEBUG: `${ESC}[2;36m`,\n  INFO: ANSI_BLUE,\n  WARN: `${ESC}[33m`,\n  ERROR: `${ESC}[1;31m`,\n} satisfies Record<LogLevel, string>\n\nfunction prettyLine(entry: LogEntry): string {\n  // Node prints debug and info exactly like log, so the level must be in the text too.\n  const level = `[${entry.level}]`\n  const module = `[${entry.module}]`\n  // A browser console colors by method on its own; a terminal needs ANSI to do the same.\n  if ('window' in globalThis) return `${entry.timestamp} ${level} ${module} ${entry.message}`\n  const timestamp = `${ANSI_GRAY}${entry.timestamp}${ANSI_RESET}`\n  const coloredLevel = `${LEVEL_ANSI[entry.level]}${level}${ANSI_RESET}`\n  const coloredModule = `${ANSI_BLUE}${module}${ANSI_RESET}`\n  return `${timestamp} ${coloredLevel} ${coloredModule} ${entry.message}`\n}\n\n/**\n * JSON format writes the entry object. Pretty format writes one line, then the data,\n * the error, and the stack as separate console arguments.\n */\nexport const consoleSink: LogSink = (entry) => {\n  // Resolved per call, so a console replaced after import still receives the output.\n  const write = console[CONSOLE_METHOD[entry.level]]\n  if (settings.format === 'json') {\n    write(entry)\n    return\n  }\n  const line = prettyLine(entry)\n  if (entry.error === undefined) {\n    write(line, ...entry.data)\n    return\n  }\n  // A stack inside an object prints as one quoted string; as its own argument it prints as lines.\n  const { stack, ...error } = entry.error\n  if (stack === undefined) write(line, ...entry.data, error)\n  else write(line, ...entry.data, error, `\\n${stack}`)\n}\n\nlet logSink: LogSink = consoleSink\n\n/**\n * Send every log entry somewhere other than `console`.\n *\n * Set once at the process entry point, never per module. A logger is created\n * by name and nothing else, so its destination is a fact about the process.\n */\nexport function setLogSink(fn: LogSink): void {\n  logSink = fn\n}\n\nconst LOG_LEVELS = Object.values(LogLevel)\nconst MAX_ERROR_CAUSE_DEPTH = 3\n\n/**\n * Diagnostics worth keeping off an error, named one by one.\n *\n * An allowlist rather than every own property: an error raised by a library we\n * do not control may hang a request or a user payload off itself, and a log is\n * the wrong place to discover that. `_tag` and `classification` are what every `AppError`\n * declares. `remote` and the three flags after it are the ones workerd sets itself.\n */\nconst KEPT_ERROR_FIELDS = [\n  '_tag',\n  'classification',\n  'code',\n  'operation',\n  'status',\n  'statusCode',\n  'remote',\n  'retryable',\n  'overloaded',\n  'durableObjectReset',\n] as const\n\ntype ErrorDiagnostics = Error & { readonly [K in (typeof KEPT_ERROR_FIELDS)[number]]?: LogValue }\n\ntype MutableSerializedError = { -readonly [K in keyof SerializedError]: SerializedError[K] }\n\nconst serializeError = (error: Error, depth = 0): SerializedError => {\n  if (depth > MAX_ERROR_CAUSE_DEPTH) return { name: 'Error', message: '[cause chain truncated]' }\n\n  // Every field is optional, so an `Error` is already one of these.\n  const carrier: ErrorDiagnostics = error\n  const kept = KEPT_ERROR_FIELDS.filter((key) => carrier[key] !== undefined)\n  const serialized: MutableSerializedError = { name: error.name, message: error.message }\n  if (depth === 0 && error.stack !== undefined) serialized.stack = error.stack\n  if (kept.length > 0)\n    serialized.fields = Object.fromEntries(kept.map((key) => [key, carrier[key]]))\n  if (error.cause instanceof Error) serialized.cause = serializeError(error.cause, depth + 1)\n  else if (error.cause !== undefined)\n    serialized.cause = { name: 'Error', message: '[non-error cause]' }\n  return serialized\n}\n\n/** Write module-scoped logs with application defaults and optional overrides. */\nexport class Logger {\n  private readonly config: LoggerConfig\n\n  /** Create a logger for one module. */\n  constructor(\n    private readonly module: string,\n    overrideConfig?: LoggerConfig,\n  ) {\n    this.config = { ...overrideConfig }\n  }\n\n  private log(\n    level: LogLevel,\n    message: string,\n    data: ReadonlyArray<LogValue>,\n    error?: SerializedError,\n  ): void {\n    const threshold = this.config.level ?? settings.level\n    if (threshold === 'OFF') return\n    if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf(threshold)) return\n\n    const entry = { timestamp: new Date().toISOString(), level, module: this.module, message, data }\n    logSink(error === undefined ? entry : { ...entry, error })\n  }\n\n  /** Write a debug log. */\n  debug(message: string, ...values: ReadonlyArray<LogValue>): void {\n    this.log(LogLevel.DEBUG, message, values)\n  }\n\n  /** Write an information log. */\n  info(message: string, ...values: ReadonlyArray<LogValue>): void {\n    this.log(LogLevel.INFO, message, values)\n  }\n\n  /** Write a warning log. */\n  warn(message: string, ...values: ReadonlyArray<LogValue>): void {\n    this.log(LogLevel.WARN, message, values)\n  }\n\n  /**\n   * Write an error log and send the error to the configured hook.\n   *\n   * The details say which call this was, and the error says what went wrong\n   * inside it. The entry carries the details as data and the error beside them.\n   */\n  error(message: string, context: ErrorLogContext = {}): void {\n    const details = context.details ?? {}\n    const thrown = context.error\n    let error: SerializedError | undefined\n    if (thrown instanceof Error) {\n      error = serializeError(thrown)\n    } else if (thrown !== undefined) {\n      // Not an `Error`, so there is no name or stack to keep, only its JSON form.\n      let json: string\n      try {\n        json = JSON.stringify(thrown)\n      } catch {\n        json = '[non-serializable error]'\n      }\n      error = { name: 'NonError', message: json }\n    }\n    this.log(LogLevel.ERROR, message, context.details === undefined ? [] : [details], error)\n\n    if (errorHook !== null && thrown !== undefined) {\n      errorHook({ error: thrown, distinctId: context.userId, context: details })\n    }\n  }\n}\n\n/** Create a logger for one module. */\nexport function createLogger(module: string, config?: LoggerConfig): Logger {\n  return new Logger(module, config)\n}\n"],"mappings":"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"}

package/dist/index-eL4vb02m.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-eL4vb02m.d.ts","names":[],"sources":["../src/core/failure-classification.ts","../src/core/app-error.ts","../src/core/defects.ts","../src/core/transport-classification.ts","../src/core/logger.ts"],"mappings":";;;;;;;KAMY;;;;;;;KAQA;;iBAGI,mBAAmB;WACxB,gBAAgB;WAChB;WACA,OAAO;;;;;;;;;;;;uBCVI,iBAAiB;oBACnB;oBACA,gBAAgB;MAErB;;;;;;;;;iBCPC,YAAY;;;;;;;iBAUZ,eAAe;;;;iBCCf,aAAa;;iBAKb,0BAA0B;;;;;;;;;;KCf9B,0DAMR,cAAc,YACd;;KAGQ;YAAwB,cAAc;;;;;;;cAOrC;WACX;WACA;WACA;WACA;;KAEU,mBAAmB,uBAAuB;;KAG1C;WACD;WACA;WACA;WACA,SAAS;WACT,QAAQ;;;KAIP;WACD;WACA,OAAO;WACP;WACA;WACA,MAAM,cAAc;;WAEpB,QAAQ;;;KAIP;WACD;WACA;WACA,UAAU;;;KAIT,eAAe;;UAGV;WACN,QAAQ;;;KAIP;;;;;;;UAQK,uBAAuB;WAC7B,SAAS;;;;;;iBAgBJ,gBAAgB,QAAQ;;UAQvB;WACN;WACA;WACA,SAAS;;;KAIR,mBAAmB,OAAO;;KAG1B,WAAW,OAAO;;;;;;iBASd,mBAAmB,IAAI;;;;;cA0C1B,aAAa;;;;;;;iBA0BV,WAAW,IAAI;;cAiDlB;mBAKQ;mBAJF;;EAGjB,YACmB,gBACjB,iBAAiB;UAKX;;EAeR,MAAM,oBAAoB,QAAQ,cAAc;;EAKhD,KAAK,oBAAoB,QAAQ,cAAc;;EAK/C,KAAK,oBAAoB,QAAQ,cAAc;;;;;;;EAU/C,MAAM,iBAAiB,UAAS;;;iBAyBlB,aAAa,gBAAgB,SAAS,eAAe"}

package/src/application/message-bus.errors.ts

@@ -1,16 +0,0 @@
-import { AppError } from '@/core'
-
-import type { MessageId } from './messages.ts'
-
-/**
- * The unit of work throws this when a message's effects already committed.
- * The bus counts an event subscriber that throws it as delivered. From a command it reaches the caller.
- */
-export class DuplicateMessageError extends AppError {
-  readonly _tag = 'DuplicateMessageError'
-  readonly classification = 'terminal'
-
-  constructor(readonly messageId: MessageId) {
-    super(`message ${messageId} already committed`)
-  }
-}