better-ship 0.3.2

package/dist/core-D0asUCvq.js

@@ -0,0 +1,282 @@
+import { panic } from "better-result";
+
+//#region src/core/app-error.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`.
+*/
+var AppError = class extends Error {
+	get name() {
+		return this._tag;
+	}
+};
+
+//#endregion
+//#region src/core/defects.ts
+/**
+* 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.
+*/
+function unreachable(value) {
+	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.
+*/
+function notImplemented(what) {
+	return panic(`Not implemented: ${what}`);
+}
+
+//#endregion
+//#region src/core/failure-classification.ts
+/** Decide whether one retry owner may repeat a failed operation. */
+function shouldRetryFailure(args) {
+	if (!args.repeatSafe) return false;
+	if (args.classification === "transient") return true;
+	if (args.classification === "terminal") return false;
+	return args.owner === "durable";
+}
+
+//#endregion
+//#region src/core/transport-classification.ts
+/**
+* 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. */
+function isAbortError(cause) {
+	return cause instanceof Error && cause.name === "AbortError";
+}
+/** Match known transient transport messages while excluding explicit cancellation. */
+function isTransientTransportError(cause) {
+	if (!(cause instanceof Error) || isAbortError(cause)) return false;
+	const message = cause.message.toLowerCase();
+	return TRANSIENT_TRANSPORT_PATTERNS.some((pattern) => pattern.test(message));
+}
+
+//#endregion
+//#region src/core/logger.ts
+/**
+* The supported log severity levels, in ascending order.
+*
+* A const object, not an enum, so a parsed environment value typed `'INFO'` is a `LogLevel`.
+*/
+const LogLevel = {
+	DEBUG: "DEBUG",
+	INFO: "INFO",
+	WARN: "WARN",
+	ERROR: "ERROR"
+};
+const DEFAULT_SETTINGS = {
+	level: LogLevel.INFO,
+	format: "json"
+};
+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.
+*/
+function configureLogger(config) {
+	settings = {
+		level: config.level ?? DEFAULT_SETTINGS.level,
+		format: config.format ?? DEFAULT_SETTINGS.format
+	};
+}
+let errorHook = null;
+/**
+* Register the function that receives each logged error.
+*
+* Set once at the process entry point. A later call replaces the earlier hook.
+*/
+function setLoggerErrorHook(fn) {
+	errorHook = fn;
+}
+const CONSOLE_METHOD = {
+	[LogLevel.DEBUG]: "debug",
+	[LogLevel.INFO]: "info",
+	[LogLevel.WARN]: "warn",
+	[LogLevel.ERROR]: "error"
+};
+const ESC = String.fromCharCode(27);
+const ANSI_RESET = `${ESC}[0m`;
+const ANSI_GRAY = `${ESC}[90m`;
+const ANSI_BLUE = `${ESC}[34m`;
+const LEVEL_ANSI = {
+	DEBUG: `${ESC}[2;36m`,
+	INFO: ANSI_BLUE,
+	WARN: `${ESC}[33m`,
+	ERROR: `${ESC}[1;31m`
+};
+function prettyLine(entry) {
+	const level = `[${entry.level}]`;
+	const module = `[${entry.module}]`;
+	if ("window" in globalThis) return `${entry.timestamp} ${level} ${module} ${entry.message}`;
+	return `${`${ANSI_GRAY}${entry.timestamp}${ANSI_RESET}`} ${`${LEVEL_ANSI[entry.level]}${level}${ANSI_RESET}`} ${`${ANSI_BLUE}${module}${ANSI_RESET}`} ${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.
+*/
+const consoleSink = (entry) => {
+	const write = console[CONSOLE_METHOD[entry.level]];
+	if (settings.format === "json") {
+		write(entry);
+		return;
+	}
+	const line = prettyLine(entry);
+	if (entry.error === void 0) {
+		write(line, ...entry.data);
+		return;
+	}
+	const { stack, ...error } = entry.error;
+	if (stack === void 0) write(line, ...entry.data, error);
+	else write(line, ...entry.data, error, `\n${stack}`);
+};
+let 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.
+*/
+function setLogSink(fn) {
+	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"
+];
+const serializeError = (error, depth = 0) => {
+	if (depth > MAX_ERROR_CAUSE_DEPTH) return {
+		name: "Error",
+		message: "[cause chain truncated]"
+	};
+	const carrier = error;
+	const kept = KEPT_ERROR_FIELDS.filter((key) => carrier[key] !== void 0);
+	const serialized = {
+		name: error.name,
+		message: error.message
+	};
+	if (depth === 0 && error.stack !== void 0) 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 !== void 0) serialized.cause = {
+		name: "Error",
+		message: "[non-error cause]"
+	};
+	return serialized;
+};
+/** Write module-scoped logs with application defaults and optional overrides. */
+var Logger = class {
+	module;
+	config;
+	/** Create a logger for one module. */
+	constructor(module, overrideConfig) {
+		this.module = module;
+		this.config = { ...overrideConfig };
+	}
+	log(level, message, data, error) {
+		const threshold = this.config.level ?? settings.level;
+		if (threshold === "OFF") return;
+		if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf(threshold)) return;
+		const entry = {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			level,
+			module: this.module,
+			message,
+			data
+		};
+		logSink(error === void 0 ? entry : {
+			...entry,
+			error
+		});
+	}
+	/** Write a debug log. */
+	debug(message, ...values) {
+		this.log(LogLevel.DEBUG, message, values);
+	}
+	/** Write an information log. */
+	info(message, ...values) {
+		this.log(LogLevel.INFO, message, values);
+	}
+	/** Write a warning log. */
+	warn(message, ...values) {
+		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, context = {}) {
+		const details = context.details ?? {};
+		const thrown = context.error;
+		let error;
+		if (thrown instanceof Error) error = serializeError(thrown);
+		else if (thrown !== void 0) {
+			let json;
+			try {
+				json = JSON.stringify(thrown);
+			} catch {
+				json = "[non-serializable error]";
+			}
+			error = {
+				name: "NonError",
+				message: json
+			};
+		}
+		this.log(LogLevel.ERROR, message, context.details === void 0 ? [] : [details], error);
+		if (errorHook !== null && thrown !== void 0) errorHook({
+			error: thrown,
+			distinctId: context.userId,
+			context: details
+		});
+	}
+};
+/** Create a logger for one module. */
+function createLogger(module, config) {
+	return new Logger(module, config);
+}
+
+//#endregion
+export { createLogger as a, isAbortError as c, notImplemented as d, unreachable as f, consoleSink as i, isTransientTransportError as l, Logger as n, setLogSink as o, AppError as p, configureLogger as r, setLoggerErrorHook as s, LogLevel as t, shouldRetryFailure as u };
+//# sourceMappingURL=core-D0asUCvq.js.map

package/dist/core-D0asUCvq.js.map

@@ -0,0 +1 @@
+{"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/core.d.ts

@@ -0,0 +1,2 @@
+import { C as unreachable, D as shouldRetryFailure, E as RetryOwner, S as notImplemented, T as FailureClassification, _ as createLogger, a as LogFormat, b as isAbortError, c as LogThreshold, d as LoggerConfig, f as LoggerErrorHook, g as consoleSink, h as configureLogger, i as LogFields, l as LogValue, m as SerializedError, n as ErrorLogContext, o as LogLevel, p as LoggerSettings, r as LogEntry, s as LogSink, t as ErrorCaptureEntry, u as Logger, v as setLogSink, w as AppError, x as isTransientTransportError, y as setLoggerErrorHook } from "./index-eL4vb02m.js";
+export { AppError, type ErrorCaptureEntry, type ErrorLogContext, type FailureClassification, type LogEntry, type LogFields, type LogFormat, LogLevel, type LogSink, type LogThreshold, type LogValue, Logger, type LoggerConfig, type LoggerErrorHook, type LoggerSettings, type RetryOwner, type SerializedError, configureLogger, consoleSink, createLogger, isAbortError, isTransientTransportError, notImplemented, setLogSink, setLoggerErrorHook, shouldRetryFailure, unreachable };

package/dist/core.js

@@ -0,0 +1,3 @@
+import { a as createLogger, c as isAbortError, d as notImplemented, f as unreachable, i as consoleSink, l as isTransientTransportError, n as Logger, o as setLogSink, p as AppError, r as configureLogger, s as setLoggerErrorHook, t as LogLevel, u as shouldRetryFailure } from "./core-D0asUCvq.js";
+
+export { AppError, LogLevel, Logger, configureLogger, consoleSink, createLogger, isAbortError, isTransientTransportError, notImplemented, setLogSink, setLoggerErrorHook, shouldRetryFailure, unreachable };

package/dist/index-eL4vb02m.d.ts

@@ -0,0 +1,183 @@
+//#region src/core/failure-classification.d.ts
+/**
+ * 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.
+ */
+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.
+ */
+type RetryOwner = 'immediate' | 'durable';
+/** Decide whether one retry owner may repeat a failed operation. */
+declare function shouldRetryFailure(args: {
+  readonly classification: FailureClassification;
+  readonly repeatSafe: boolean;
+  readonly owner: RetryOwner;
+}): boolean;
+//#endregion
+//#region src/core/app-error.d.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`.
+ */
+declare abstract class AppError extends Error {
+  abstract readonly _tag: string;
+  abstract readonly classification: FailureClassification;
+  get name(): string;
+}
+//#endregion
+//#region src/core/defects.d.ts
+/**
+ * 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.
+ */
+declare function unreachable(value: never): never;
+/**
+ * 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.
+ */
+declare function notImplemented(what: string): never;
+//#endregion
+//#region src/core/transport-classification.d.ts
+/** Cancellation is a decision, not a failure to repeat. */
+declare function isAbortError(cause: unknown): boolean;
+/** Match known transient transport messages while excluding explicit cancellation. */
+declare function isTransientTransportError(cause: unknown): boolean;
+//#endregion
+//#region src/core/logger.d.ts
+/**
+ * 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`. */
+type LogValue = string | number | boolean | null | undefined | ReadonlyArray<LogValue> | LogFields;
+/** Named log values. */
+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`.
+ */
+declare const LogLevel: {
+  readonly DEBUG: 'DEBUG';
+  readonly INFO: 'INFO';
+  readonly WARN: 'WARN';
+  readonly ERROR: 'ERROR';
+};
+type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+/** An error as plain data: name, message, stack, allowlisted fields, and the cause chain. */
+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. */
+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. */
+type ErrorLogContext = {
+  readonly error?: unknown;
+  readonly userId?: string;
+  readonly details?: LogFields;
+};
+/** What a logger lets through: a level and everything above it, or nothing. */
+type LogThreshold = LogLevel | 'OFF';
+/** Overrides the application settings for one logger. */
+interface LoggerConfig {
+  readonly level?: LogThreshold;
+}
+/** `json` writes the entry object. `pretty` writes one readable line for a person. */
+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.
+ */
+interface LoggerSettings extends LoggerConfig {
+  readonly format?: LogFormat;
+}
+/**
+ * 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.
+ */
+declare function configureLogger(config: LoggerSettings): void;
+/** The error data sent to the configured error hook. */
+interface ErrorCaptureEntry {
+  readonly error: unknown;
+  readonly distinctId: string | undefined;
+  readonly context: LogFields;
+}
+/** A function that forwards one logged error to an error service. */
+type LoggerErrorHook = (entry: ErrorCaptureEntry) => void;
+/** Where every log entry goes. */
+type LogSink = (entry: LogEntry) => void;
+/**
+ * Register the function that receives each logged error.
+ *
+ * Set once at the process entry point. A later call replaces the earlier hook.
+ */
+declare function setLoggerErrorHook(fn: LoggerErrorHook): void;
+/**
+ * JSON format writes the entry object. Pretty format writes one line, then the data,
+ * the error, and the stack as separate console arguments.
+ */
+declare const consoleSink: LogSink;
+/**
+ * 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.
+ */
+declare function setLogSink(fn: LogSink): void;
+/** Write module-scoped logs with application defaults and optional overrides. */
+declare class Logger {
+  private readonly module;
+  private readonly config;
+  /** Create a logger for one module. */
+  constructor(module: string, overrideConfig?: LoggerConfig);
+  private log;
+  /** Write a debug log. */
+  debug(message: string, ...values: ReadonlyArray<LogValue>): void;
+  /** Write an information log. */
+  info(message: string, ...values: ReadonlyArray<LogValue>): void;
+  /** Write a warning log. */
+  warn(message: string, ...values: ReadonlyArray<LogValue>): void;
+  /**
+   * 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;
+}
+/** Create a logger for one module. */
+declare function createLogger(module: string, config?: LoggerConfig): Logger;
+//#endregion
+export { unreachable as C, shouldRetryFailure as D, RetryOwner as E, notImplemented as S, FailureClassification as T, createLogger as _, LogFormat as a, isAbortError as b, LogThreshold as c, LoggerConfig as d, LoggerErrorHook as f, consoleSink as g, configureLogger as h, LogFields as i, LogValue as l, SerializedError as m, ErrorLogContext as n, LogLevel as o, LoggerSettings as p, LogEntry as r, LogSink as s, ErrorCaptureEntry as t, Logger as u, setLogSink as v, AppError as w, isTransientTransportError as x, setLoggerErrorHook as y };
+//# sourceMappingURL=index-eL4vb02m.d.ts.map

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

@@ -0,0 +1 @@
+{"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/dist/postgres.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/tanstack.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/ui.d.ts

@@ -0,0 +1 @@
+export {}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://www.schemastore.org/package.json",
+  "name": "better-ship",
+  "version": "0.3.2",
+  "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexander-zuev/better-ship.git",
+    "directory": "packages/better-ship"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    "./application": "./dist/application.js",
+    "./cloudflare": "./dist/cloudflare.js",
+    "./core": "./dist/core.js",
+    "./postgres": "./dist/postgres.js",
+    "./tanstack": "./dist/tanstack.js",
+    "./ui": "./dist/ui.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "better-result": "3.0.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "5.20260905.1",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit && tsc -p tests/tsconfig.json",
+    "lint": "oxlint . --quiet",
+    "lint:fix": "oxlint . --fix --quiet",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/src/application/handlers.ts

@@ -0,0 +1,22 @@
+import type { Command, Event, Query } from './messages.ts'
+
+/**
+ * Handles one command with the dependency container and returns the caller's value.
+ * A handler that writes inside a transaction opens the unit of work itself. Failures throw.
+ */
+export type CommandHandler<TCommand extends Command, Deps, Value> = (
+  command: TCommand,
+  deps: Deps,
+) => Promise<Value>
+
+/**
+ * Handles one query with the read-only view of the container.
+ * The view is a type over the same object, so a query cannot name a write capability.
+ */
+export type QueryHandler<TQuery extends Query, QueryDeps, Value> = (
+  query: TQuery,
+  deps: QueryDeps,
+) => Promise<Value>
+
+/** Completes one subscriber's work for an event. Failures throw. */
+export type EventHandler<TEvent extends Event, Deps> = (event: TEvent, deps: Deps) => Promise<void>

package/src/application/index.ts

@@ -0,0 +1,13 @@
+export { DuplicateMessageError } from './message-bus.errors.ts'
+export type { CommandHandler, EventHandler, QueryHandler } from './handlers.ts'
+export type { Command, Event, Message, MessageId, Query } from './messages.ts'
+export { MessageBus, type IMessageBus } from './message-bus.ts'
+export type {
+  CommandRegistry,
+  EventRegistry,
+  Handlers,
+  MessageRegistry,
+  MessageResult,
+  QueryRegistry,
+  RegistryMessage,
+} from './registry.ts'

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

@@ -0,0 +1,16 @@
+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`)
+  }
+}