better-ship 0.4.1 → 0.6.0

package/dist/core-Cx5SeyKV.js

@@ -0,0 +1,709 @@
+import { z } from "zod";
+import { panic } from "better-result";
+import { v7 } from "uuid";
+
+//#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/authentication.error.ts
+/** A protected operation requires a session that the caller did not provide. */
+var AuthenticationError = class extends AppError {
+	_tag = "AuthenticationError";
+	classification = "terminal";
+	constructor() {
+		super("Authentication required");
+	}
+};
+
+//#endregion
+//#region src/core/rate-limit.error.ts
+/** HTTP 429 with a retry delay in seconds. A null delay means the response supplies no valid duration. */
+var RateLimitError = class extends AppError {
+	retryAfter;
+	_tag = "RateLimitError";
+	classification = "transient";
+	status = 429;
+	constructor(retryAfter) {
+		super("Too many requests");
+		this.retryAfter = retryAfter;
+	}
+};
+
+//#endregion
+//#region src/core/stale-session.error.ts
+/** A presented session cookie no longer resolves; the application owns cleanup and redirect policy. */
+var StaleSessionError = class extends AppError {
+	_tag = "StaleSessionError";
+	classification = "terminal";
+	constructor() {
+		super("Session is no longer valid. Sign in again.");
+	}
+};
+
+//#endregion
+//#region src/core/not-authorized.error.ts
+/** The authenticated caller cannot perform this operation. Ported from Porte's auth.errors.ts. */
+var NotAuthorizedError = class extends AppError {
+	_tag = "NotAuthorizedError";
+	classification = "terminal";
+	constructor() {
+		super("Not allowed");
+	}
+};
+
+//#endregion
+//#region src/core/internal.errors.ts
+/** Safe public replacement for an unknown failure, ported from Porte's internal.errors.ts. */
+var InternalServerError = class extends AppError {
+	_tag = "InternalServerError";
+	classification = "unknown";
+	constructor() {
+		super("Something went wrong");
+	}
+};
+/** Safe public replacement for a classified transient failure. */
+var ServiceUnavailableError = class extends AppError {
+	_tag = "ServiceUnavailableError";
+	classification = "transient";
+	constructor() {
+		super("Try again shortly");
+	}
+};
+
+//#endregion
+//#region src/core/request.errors.ts
+/** Invalid user input, one entry per invalid value in the RFC 9457 shape. Technical failures use another error. */
+var ValidationError = class ValidationError extends AppError {
+	errors;
+	_tag = "ValidationError";
+	classification = "terminal";
+	constructor(errors, message = "The request was not valid") {
+		super(message);
+		this.errors = errors;
+	}
+	/** Convert a Zod error. Each issue path becomes a JSON Pointer. */
+	static fromZod(error, message) {
+		return ValidationError.fromIssues(error.issues, message);
+	}
+	/** Convert issues from any validator, such as issues TanStack serialized into an error message. */
+	static fromIssues(issues, message) {
+		return new ValidationError(issues.map((issue) => ({
+			detail: issue.message,
+			pointer: jsonPointer(issue.path)
+		})), message);
+	}
+};
+/** The server cannot parse the request syntax. */
+var MalformedRequestError = class extends AppError {
+	_tag = "MalformedRequestError";
+	classification = "terminal";
+	constructor(args) {
+		super("The request was malformed", args);
+	}
+};
+/** No resource matches the requested HTTP path. */
+var ResourceNotFoundError = class extends AppError {
+	_tag = "ResourceNotFoundError";
+	classification = "terminal";
+	constructor() {
+		super("Resource not found");
+	}
+};
+/** A WebSocket route received a request without an upgrade. */
+var UpgradeRequiredError = class extends AppError {
+	_tag = "UpgradeRequiredError";
+	classification = "terminal";
+	constructor() {
+		super("WebSocket upgrade required");
+	}
+};
+/** The requested operation did not answer before its deadline. */
+var RequestTimeoutError = class extends AppError {
+	_tag = "RequestTimeoutError";
+	classification = "transient";
+	constructor() {
+		super("The request timed out");
+	}
+};
+const readablePathSchema = z.array(z.union([z.string(), z.number()]));
+function jsonPointer(path) {
+	const parsed = readablePathSchema.safeParse(path);
+	const steps = parsed.success ? parsed.data : [];
+	if (steps.length === 0) return "#";
+	return `#/${steps.map((step) => String(step).replaceAll("~", "~0").replaceAll("/", "~1")).join("/")}`;
+}
+
+//#endregion
+//#region src/core/problem-details.ts
+/**
+* The standard RFC 9457 body for a failed HTTP response.
+* The HTTP response status remains authoritative; extensions may add problem-specific data.
+* @see https://http.dev/problem-details
+*/
+const ProblemDetailsSchema = z.looseObject({
+	/**
+	* Stable URI for the problem type; use `about:blank` when the HTTP status is sufficient.
+	* @example "about:blank"
+	*/
+	type: z.string(),
+	/**
+	* Stable human-readable name for the problem type.
+	* @example "Service Unavailable"
+	*/
+	title: z.string(),
+	/**
+	* Safe human-readable explanation for this occurrence; clients must not parse it.
+	* @example "The service is unavailable."
+	*/
+	detail: z.string().optional(),
+	/**
+	* URI reference for this occurrence; omit it when no correlation resource exists.
+	* @example "/problems/occurrences/01K5F6Y7"
+	*/
+	instance: z.string().optional()
+});
+/** One invalid value in a `422` validation problem. */
+const ValidationProblemErrorSchema = z.object({
+	/**
+	* Safe explanation of why this value is invalid.
+	* @example "Must be a positive integer."
+	*/
+	detail: z.string(),
+	/**
+	* RFC 6901 JSON Pointer fragment for the invalid value.
+	* @example "#/age"
+	*/
+	pointer: z.string().regex(/^#(?:\/(?:[^~]|~[01])*)*$/u)
+});
+/** An RFC 9457 validation problem with one or more invalid content values. */
+const ValidationProblemDetailsSchema = ProblemDetailsSchema.extend({ errors: z.array(ValidationProblemErrorSchema).min(1) });
+
+//#endregion
+//#region src/core/error-table.ts
+function entriesOf(entries) {
+	return entries;
+}
+const ValidationFields = z.object({ errors: z.array(ValidationProblemErrorSchema) });
+const RateLimitFields = z.object({ retryAfter: z.number().nullable() });
+/** The errors every application can throw, with their statuses. `defineErrors` includes them. */
+const sharedErrors = entriesOf({
+	MalformedRequestError: {
+		error: MalformedRequestError,
+		status: 400
+	},
+	AuthenticationError: {
+		error: AuthenticationError,
+		status: 401
+	},
+	StaleSessionError: {
+		error: StaleSessionError,
+		status: 401
+	},
+	NotAuthorizedError: {
+		error: NotAuthorizedError,
+		status: 403
+	},
+	ResourceNotFoundError: {
+		error: ResourceNotFoundError,
+		status: 404
+	},
+	ValidationError: {
+		error: ValidationError,
+		status: 422,
+		fields: ValidationFields
+	},
+	UpgradeRequiredError: {
+		error: UpgradeRequiredError,
+		status: 426
+	},
+	RateLimitError: {
+		error: RateLimitError,
+		status: 429,
+		fields: RateLimitFields
+	},
+	InternalServerError: {
+		error: InternalServerError,
+		status: 500
+	},
+	ServiceUnavailableError: {
+		error: ServiceUnavailableError,
+		status: 503
+	},
+	RequestTimeoutError: {
+		error: RequestTimeoutError,
+		status: 504
+	}
+});
+const RemoteErrorSchema = z.object({
+	_tag: z.string(),
+	message: z.string(),
+	remote: z.literal(true)
+});
+function match(byTag, cause) {
+	if (cause instanceof AppError) {
+		const entry = byTag.get(cause._tag);
+		if (entry === void 0 || !(cause instanceof entry.error)) return null;
+		return {
+			tag: cause._tag,
+			entry,
+			error: cause
+		};
+	}
+	if (!(cause instanceof Error)) return null;
+	const remote = RemoteErrorSchema.safeParse(cause);
+	if (!remote.success) return null;
+	const entry = byTag.get(remote.data._tag);
+	return entry === void 0 ? null : {
+		tag: remote.data._tag,
+		entry,
+		error: cause
+	};
+}
+/**
+* Build the application's error table. The shared entries are always included;
+* an entry with the same key replaces the shared one.
+*/
+function defineErrors(entries) {
+	const merged = {
+		...sharedErrors,
+		...entries
+	};
+	const byTag = new Map(Object.entries(merged));
+	const resolve = (cause) => {
+		const found = match(byTag, cause);
+		if (found === null) return null;
+		const fields = found.entry.fields?.safeParse(found.error);
+		if (fields !== void 0 && !fields.success) return null;
+		const payload = {
+			_tag: found.tag,
+			message: found.error.message,
+			...fields?.data
+		};
+		return {
+			status: found.entry.status,
+			payload
+		};
+	};
+	const resolveShared = (error) => resolve(error) ?? panic(`Error table cannot resolve shared error ${error._tag}`);
+	const generic = resolveShared(new InternalServerError());
+	const unavailable = resolveShared(new ServiceUnavailableError());
+	const [first, ...rest] = [...byTag].map(([tag, entry]) => z.strictObject({
+		_tag: z.literal(tag),
+		message: z.string(),
+		...entry.fields?.shape
+	}));
+	if (first === void 0) return panic("Error table has no entries");
+	const payloadSchema = z.discriminatedUnion("_tag", [first, ...rest]).pipe(z.custom());
+	const parse = (cause) => {
+		const parsed = payloadSchema.safeParse(cause);
+		return parsed.success ? parsed.data : null;
+	};
+	return {
+		entries: merged,
+		payloadSchema,
+		generic: generic.payload,
+		parse,
+		is(cause, tag) {
+			const parsed = parse(cause);
+			return parsed !== null && parsed._tag === tag;
+		},
+		resolve,
+		fallback: (cause) => cause instanceof AppError && cause.classification === "transient" ? unavailable : generic
+	};
+}
+
+//#endregion
+//#region src/core/database.error.ts
+/** Classification describes the failure; callers must separately establish whether repetition is safe. */
+var DatabaseError = class extends AppError {
+	operation;
+	classification;
+	details;
+	_tag = "DatabaseError";
+	constructor(operation, classification, details, options) {
+		super(`Database operation failed: ${operation}`, options);
+		this.operation = operation;
+		this.classification = classification;
+		this.details = details;
+	}
+};
+
+//#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/identity.ts
+/**
+* Define an id kind the application mints: `export const CallId = defineId('CallId')`.
+* An id another system mints, such as a provider's call id, stays a plain branded schema.
+*/
+function defineId(brand) {
+	return {
+		schema: z.uuidv7({ error: `Invalid ${brand}` }).brand(),
+		create: () => v7()
+	};
+}
+
+//#endregion
+//#region src/core/define-messages.ts
+const MessageIdSchema = z.string().min(1);
+/** One full message schema: the routing fields joined to the payload. */
+function messageSchema(type, name, payload) {
+	return (type === "query" ? z.object({
+		type: z.literal(type),
+		name: z.literal(name)
+	}) : z.object({
+		type: z.literal(type),
+		name: z.literal(name),
+		id: MessageIdSchema
+	})).and(payload);
+}
+/** A union over every message of one kind. Empty when the application has none of that kind. */
+function unionOf(type, schemas) {
+	return z.union(Object.entries(schemas).map(([name, payload]) => messageSchema(type, name, payload)));
+}
+/**
+* Define an application's messages once. The key is the name; the factories add the routing
+* fields `type`, `name`, and `id`. A payload that declares one of them is a compile error.
+*/
+function defineMessages(definition) {
+	const commandSchema = unionOf("command", definition.commands);
+	const eventSchema = unionOf("event", definition.events);
+	const querySchema = unionOf("query", definition.queries);
+	return {
+		definition,
+		createCommand: (name, payload, id = v7()) => ({
+			...payload,
+			type: "command",
+			name,
+			id
+		}),
+		createEvent: (name, payload, id = v7()) => ({
+			...payload,
+			type: "event",
+			name,
+			id
+		}),
+		createQuery: (name, payload) => ({
+			...payload,
+			type: "query",
+			name
+		}),
+		commandSchema: commandSchema.pipe(z.custom()),
+		eventSchema: eventSchema.pipe(z.custom()),
+		querySchema: querySchema.pipe(z.custom()),
+		queueSchema: z.union([commandSchema, eventSchema]).pipe(z.custom())
+	};
+}
+
+//#endregion
+//#region src/core/entity.ts
+/**
+* The base of an aggregate: its identity, the events it raised, and the plain data a repository
+* stores. The subclass keeps its constructor private and declares `static restore(data: Data)`,
+* the one door a repository rebuilds it through. A repository drains the events after `save`.
+*/
+var Entity = class {
+	events = [];
+	/** Record one event with the state change that caused it. The unit of work commits both. */
+	addEvent(event) {
+		this.events.push(event);
+	}
+	/** A copy of the events raised since the last `clearEvents`. */
+	collectEvents() {
+		return [...this.events];
+	}
+	/** Forget the raised events once the boundary has taken them. */
+	clearEvents() {
+		this.events = [];
+	}
+};
+
+//#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 details,
+* 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);
+	const fields = entry.userId === void 0 ? entry.details : {
+		...entry.details,
+		userId: entry.userId
+	};
+	const details = Object.keys(fields).length === 0 ? [] : [fields];
+	if (entry.error === void 0) {
+		write(line, ...details);
+		return;
+	}
+	const { stack, ...error } = entry.error;
+	if (stack === void 0) write(line, ...details, error);
+	else write(line, ...details, 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_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_DEPTH) return {
+		name: "Error",
+		message: "[error nesting truncated]"
+	};
+	const carrier = error;
+	const kept = KEPT_ERROR_FIELDS.filter((key) => carrier[key] !== void 0);
+	const serialized = {
+		name: error.name,
+		message: error.message
+	};
+	if (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]"
+	};
+	if (error instanceof AggregateError) serialized.errors = error.errors.map((failure) => failure instanceof Error ? serializeError(failure, depth + 1) : {
+		name: "NonError",
+		message: "[non-error aggregate member]"
+	});
+	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, details, error, userId) {
+		const threshold = this.config.level ?? settings.level;
+		if (threshold === "OFF") return;
+		if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf(threshold)) return;
+		let entry = {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			level,
+			module: this.module,
+			message,
+			details
+		};
+		if (userId !== void 0) entry = {
+			...entry,
+			userId
+		};
+		logSink(error === void 0 ? entry : {
+			...entry,
+			error
+		});
+	}
+	/** Write a debug log. */
+	debug(message, details = {}) {
+		this.log(LogLevel.DEBUG, message, details);
+	}
+	/** Write an information log. */
+	info(message, details = {}) {
+		this.log(LogLevel.INFO, message, details);
+	}
+	/** Write a warning log. */
+	warn(message, details = {}) {
+		this.log(LogLevel.WARN, message, details);
+	}
+	/**
+	* 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. Both the entry and the error hook receive the supplied user ID.
+	*/
+	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, details, error, context.userId);
+		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 { StaleSessionError as A, RequestTimeoutError as C, InternalServerError as D, ValidationError as E, AuthenticationError as M, AppError as N, ServiceUnavailableError as O, MalformedRequestError as S, UpgradeRequiredError as T, defineErrors as _, createLogger as a, ValidationProblemDetailsSchema as b, isAbortError as c, Entity as d, defineMessages as f, DatabaseError as g, unreachable as h, consoleSink as i, RateLimitError as j, NotAuthorizedError as k, isTransientTransportError as l, notImplemented as m, Logger as n, setLogSink as o, defineId as p, configureLogger as r, setLoggerErrorHook as s, LogLevel as t, shouldRetryFailure as u, sharedErrors as v, ResourceNotFoundError as w, ValidationProblemErrorSchema as x, ProblemDetailsSchema as y };
+//# sourceMappingURL=core-Cx5SeyKV.js.map