wellcrafted 0.36.0 → 0.37.0

package/dist/error/index.d.ts

@@ -1,4 +1,4 @@
 import "../result-DKwq9BCr.js";
 import { AnyTaggedError, DefineErrorsReturn, ErrorBody, ErrorsConfig, InferError, InferErrors, ValidatedConfig } from "../types-tXXk7K9Q.js";
-import { defineErrors, extractErrorMessage } from "../index-B9PnZCTt.js";
-export { AnyTaggedError, DefineErrorsReturn, ErrorBody, ErrorsConfig, InferError, InferErrors, ValidatedConfig, defineErrors, extractErrorMessage };
+import { DefineHttpErrorsReturn, HttpErrorFactory, HttpErrorsConfig, InferHttpError, InferHttpErrors, ValidatedHttpConfig, defineErrors, defineHttpErrors, extractErrorMessage } from "../index-BNWUFJ69.js";
+export { AnyTaggedError, DefineErrorsReturn, DefineHttpErrorsReturn, ErrorBody, ErrorsConfig, HttpErrorFactory, HttpErrorsConfig, InferError, InferErrors, InferHttpError, InferHttpErrors, ValidatedConfig, ValidatedHttpConfig, defineErrors, defineHttpErrors, extractErrorMessage };

package/dist/error/index.js

@@ -1,4 +1,4 @@
 import "../result-C5cJ1_WU.js";
-import { defineErrors, extractErrorMessage } from "../error-Dy9wXt5_.js";
+import { defineErrors, defineHttpErrors, extractErrorMessage } from "../error-DLVm7dsh.js";
 
-export { defineErrors, extractErrorMessage };
+export { defineErrors, defineHttpErrors, extractErrorMessage };

package/dist/{error-Dy9wXt5_.js → error-DLVm7dsh.js}

@@ -66,6 +66,49 @@ function defineErrors(config) {
 	return result;
 }
 
+//#endregion
+//#region src/error/defineHttpErrors.ts
+/**
+* Defines a set of typed HTTP error factories, each paired with its HTTP
+* status code.
+*
+* Like `defineErrors`, each factory stamps `name` onto the error and wraps it
+* in `Err`. Unlike `defineErrors`, each factory function carries a static
+* `.status` property with the literal HTTP status code — the status is never
+* included in the serialized error body.
+*
+* @example
+* ```ts
+* const AssetError = defineHttpErrors({
+*   MissingFile:          [400, () => ({ message: 'Missing file' })],
+*   FileTooLarge:         [413, ({ size }: { size: number }) => ({ message: `File too large: ${size}`, size })],
+*   StorageLimitExceeded: [402, () => ({ message: 'Storage limit exceeded' })],
+* });
+*
+* type AssetError = InferHttpErrors<typeof AssetError>;
+*
+* // In a Hono route handler:
+* return c.json(AssetError.MissingFile(), AssetError.MissingFile.status);
+* // wire body: { error: { name: 'MissingFile', message: 'Missing file' }, data: null }
+* // http status: 400
+* ```
+*/
+function defineHttpErrors(config) {
+	const result = {};
+	for (const [name, [status, factory]] of Object.entries(config)) {
+		const fn = (...args) => {
+			const body = factory(...args);
+			return Err(Object.freeze({
+				...body,
+				name
+			}));
+		};
+		fn.status = status;
+		result[name] = fn;
+	}
+	return result;
+}
+
 //#endregion
 //#region src/error/extractErrorMessage.ts
 /**
@@ -103,5 +146,5 @@ function extractErrorMessage(error) {
 }
 
 //#endregion
-export { defineErrors, extractErrorMessage };
-//# sourceMappingURL=error-Dy9wXt5_.js.map
+export { defineErrors, defineHttpErrors, extractErrorMessage };
+//# sourceMappingURL=error-DLVm7dsh.js.map

package/dist/error-DLVm7dsh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-DLVm7dsh.js","names":["config: TConfig & ValidatedConfig<TConfig>","result: Record<string, unknown>","config: TConfig & ValidatedHttpConfig<TConfig>","result: Record<string, unknown>","error: unknown"],"sources":["../src/error/defineErrors.ts","../src/error/defineHttpErrors.ts","../src/error/extractErrorMessage.ts"],"sourcesContent":["import { Err } from \"../result/result.js\";\nimport type {\n\tDefineErrorsReturn,\n\tErrorsConfig,\n\tValidatedConfig,\n} from \"./types.js\";\n\n/**\n * Defines a set of typed error factories using Rust-style namespaced variants.\n *\n * Each key is a short variant name (the namespace provides context). Every\n * factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch\n * handlers. The variant name is stamped as `name` on the error object.\n *\n * @example\n * ```ts\n * const HttpError = defineErrors({\n *   Connection: ({ cause }: { cause: unknown }) => ({\n *     message: `Failed to connect: ${extractErrorMessage(cause)}`,\n *     cause,\n *   }),\n *   Response: ({ status }: { status: number; bodyMessage?: string }) => ({\n *     message: `HTTP ${status}`,\n *     status,\n *   }),\n *   Parse: ({ cause }: { cause: unknown }) => ({\n *     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,\n *     cause,\n *   }),\n * });\n *\n * type HttpError = InferErrors<typeof HttpError>;\n *\n * const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>\n * ```\n *\n * Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The\n * mapping is nearly 1:1:\n *\n * - `enum HttpError` → `const HttpError = defineErrors(...)`\n * - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`\n * - `#[error(\"Failed: {cause}\")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``\n * - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`\n * - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`\n *\n * The equivalent Rust `thiserror` enum:\n * ```rust\n * #[derive(Error, Debug)]\n * enum HttpError {\n *     #[error(\"Failed to connect: {cause}\")]\n *     Connection { cause: String },\n *\n *     #[error(\"HTTP {status}\")]\n *     Response { status: u16, body_message: Option<String> },\n *\n *     #[error(\"Failed to parse response body: {cause}\")]\n *     Parse { cause: String },\n * }\n * ```\n */\nexport function defineErrors<const TConfig extends ErrorsConfig>(\n\tconfig: TConfig & ValidatedConfig<TConfig>,\n): DefineErrorsReturn<TConfig> {\n\tconst result: Record<string, unknown> = {};\n\n\tfor (const [name, ctor] of Object.entries(config)) {\n\t\tresult[name] = (...args: unknown[]) => {\n\t\t\tconst body = (ctor as (...a: unknown[]) => Record<string, unknown>)(\n\t\t\t\t...args,\n\t\t\t);\n\t\t\treturn Err(Object.freeze({ ...body, name }));\n\t\t};\n\t}\n\n\treturn result as DefineErrorsReturn<TConfig>;\n}\n","import { Err } from \"../result/result.js\";\nimport type { ErrorBody } from \"./types.js\";\n\n// =============================================================================\n// Config types\n// =============================================================================\n\n/** Config: each key maps to `[httpStatus, factory]`. */\n// biome-ignore lint/suspicious/noExplicitAny: required for TypeScript's function type inference\nexport type HttpErrorsConfig = Record<string, [number, (...args: any[]) => ErrorBody]>;\n\n/**\n * Per-key validation applied to the factory portion of each tuple.\n * Mirrors `ValidatedConfig` from `defineErrors`: prevents `name` in the\n * factory return body since the factory key is stamped as `name`.\n */\ntype ValidateHttpErrorBody<K extends string> = {\n\tmessage: string;\n\tname?: `The 'name' key is reserved as '${K}'. Remove it.`;\n};\n\nexport type ValidatedHttpConfig<T extends HttpErrorsConfig> = {\n\t// biome-ignore lint/suspicious/noExplicitAny: required for TypeScript's function type inference\n\t[K in keyof T & string]: T[K] extends [infer TStatus, (...args: infer A) => infer R]\n\t\t? [TStatus, (...args: A) => R & ValidateHttpErrorBody<K>]\n\t\t: T[K];\n};\n\n// =============================================================================\n// Return types\n// =============================================================================\n\n/**\n * A factory function with a static `.status` property holding the literal\n * HTTP status code. The status is never included in the serialized error body.\n */\n// biome-ignore lint/suspicious/noExplicitAny: required for TypeScript's function type inference\nexport type HttpErrorFactory<TName extends string, TStatus extends number, TFn extends (...args: any[]) => ErrorBody> =\n\t((...args: Parameters<TFn>) => Err<Readonly<{ name: TName } & ReturnType<TFn>>>) & {\n\t\treadonly status: TStatus;\n\t};\n\n/** Return type of `defineHttpErrors`. Maps each config key to its `HttpErrorFactory`. */\nexport type DefineHttpErrorsReturn<TConfig extends HttpErrorsConfig> = {\n\t// biome-ignore lint/suspicious/noExplicitAny: required for conditional type inference\n\t[K in keyof TConfig & string]: TConfig[K] extends [infer TStatus extends number, infer TFn extends (...args: any[]) => ErrorBody]\n\t\t? HttpErrorFactory<K, TStatus, TFn>\n\t\t: never;\n};\n\n// =============================================================================\n// Type utilities\n// =============================================================================\n\n/** Extract the error instance type from a single `HttpErrorFactory`. */\n// biome-ignore lint/suspicious/noExplicitAny: required for conditional type inference\nexport type InferHttpError<T> = T extends (...args: any[]) => Err<infer R> ? R : never;\n\n/** Extract the union of all error instance types from a `defineHttpErrors` return. */\nexport type InferHttpErrors<T> = {\n\t// biome-ignore lint/suspicious/noExplicitAny: required for conditional type inference\n\t[K in keyof T]: T[K] extends (...args: any[]) => Err<infer R> ? R : never;\n}[keyof T];\n\n// =============================================================================\n// Implementation\n// =============================================================================\n\n/**\n * Defines a set of typed HTTP error factories, each paired with its HTTP\n * status code.\n *\n * Like `defineErrors`, each factory stamps `name` onto the error and wraps it\n * in `Err`. Unlike `defineErrors`, each factory function carries a static\n * `.status` property with the literal HTTP status code — the status is never\n * included in the serialized error body.\n *\n * @example\n * ```ts\n * const AssetError = defineHttpErrors({\n *   MissingFile:          [400, () => ({ message: 'Missing file' })],\n *   FileTooLarge:         [413, ({ size }: { size: number }) => ({ message: `File too large: ${size}`, size })],\n *   StorageLimitExceeded: [402, () => ({ message: 'Storage limit exceeded' })],\n * });\n *\n * type AssetError = InferHttpErrors<typeof AssetError>;\n *\n * // In a Hono route handler:\n * return c.json(AssetError.MissingFile(), AssetError.MissingFile.status);\n * // wire body: { error: { name: 'MissingFile', message: 'Missing file' }, data: null }\n * // http status: 400\n * ```\n */\nexport function defineHttpErrors<const TConfig extends HttpErrorsConfig>(\n\tconfig: TConfig & ValidatedHttpConfig<TConfig>,\n): DefineHttpErrorsReturn<TConfig> {\n\tconst result: Record<string, unknown> = {};\n\n\tfor (const [name, [status, factory]] of Object.entries(config)) {\n\t\tconst fn = (...args: unknown[]) => {\n\t\t\tconst body = (factory as (...a: unknown[]) => Record<string, unknown>)(\n\t\t\t\t...args,\n\t\t\t);\n\t\t\treturn Err(Object.freeze({ ...body, name }));\n\t\t};\n\t\t(fn as unknown as { status: number }).status = status;\n\t\tresult[name] = fn;\n\t}\n\n\treturn result as unknown as DefineHttpErrorsReturn<TConfig>;\n}\n","/**\n * Extracts a readable error message from an unknown error value\n *\n * @param error - The unknown error to extract a message from\n * @returns A string representation of the error\n */\nexport function extractErrorMessage(error: unknown): string {\n\t// Handle Error instances\n\tif (error instanceof Error) {\n\t\treturn error.message;\n\t}\n\n\t// Handle primitives\n\tif (typeof error === \"string\") return error;\n\tif (\n\t\ttypeof error === \"number\" ||\n\t\ttypeof error === \"boolean\" ||\n\t\ttypeof error === \"bigint\"\n\t)\n\t\treturn String(error);\n\tif (typeof error === \"symbol\") return error.toString();\n\tif (error === null) return \"null\";\n\tif (error === undefined) return \"undefined\";\n\n\t// Handle arrays\n\tif (Array.isArray(error)) return JSON.stringify(error);\n\n\t// Handle plain objects\n\tif (typeof error === \"object\") {\n\t\tconst errorObj = error as Record<string, unknown>;\n\n\t\t// Check common error properties\n\t\tconst messageProps = [\n\t\t\t\"message\",\n\t\t\t\"error\",\n\t\t\t\"description\",\n\t\t\t\"title\",\n\t\t\t\"reason\",\n\t\t\t\"details\",\n\t\t] as const;\n\t\tfor (const prop of messageProps) {\n\t\t\tif (prop in errorObj && typeof errorObj[prop] === \"string\") {\n\t\t\t\treturn errorObj[prop];\n\t\t\t}\n\t\t}\n\n\t\t// Fallback to JSON stringification\n\t\ttry {\n\t\t\treturn JSON.stringify(error);\n\t\t} catch {\n\t\t\treturn String(error);\n\t\t}\n\t}\n\n\t// Final fallback\n\treturn String(error);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,SAAgB,aACfA,QAC8B;CAC9B,MAAMC,SAAkC,CAAE;AAE1C,MAAK,MAAM,CAAC,MAAM,KAAK,IAAI,OAAO,QAAQ,OAAO,CAChD,QAAO,QAAQ,CAAC,GAAG,SAAoB;EACtC,MAAM,OAAO,AAAC,KACb,GAAG,KACH;AACD,SAAO,IAAI,OAAO,OAAO;GAAE,GAAG;GAAM;EAAM,EAAC,CAAC;CAC5C;AAGF,QAAO;AACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACkBD,SAAgB,iBACfC,QACkC;CAClC,MAAMC,SAAkC,CAAE;AAE1C,MAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,QAAQ,CAAC,IAAI,OAAO,QAAQ,OAAO,EAAE;EAC/D,MAAM,KAAK,CAAC,GAAG,SAAoB;GAClC,MAAM,OAAO,AAAC,QACb,GAAG,KACH;AACD,UAAO,IAAI,OAAO,OAAO;IAAE,GAAG;IAAM;GAAM,EAAC,CAAC;EAC5C;AACD,EAAC,GAAqC,SAAS;AAC/C,SAAO,QAAQ;CACf;AAED,QAAO;AACP;;;;;;;;;;ACxGD,SAAgB,oBAAoBC,OAAwB;AAE3D,KAAI,iBAAiB,MACpB,QAAO,MAAM;AAId,YAAW,UAAU,SAAU,QAAO;AACtC,YACQ,UAAU,mBACV,UAAU,oBACV,UAAU,SAEjB,QAAO,OAAO,MAAM;AACrB,YAAW,UAAU,SAAU,QAAO,MAAM,UAAU;AACtD,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,iBAAqB,QAAO;AAGhC,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,KAAK,UAAU,MAAM;AAGtD,YAAW,UAAU,UAAU;EAC9B,MAAM,WAAW;EAGjB,MAAM,eAAe;GACpB;GACA;GACA;GACA;GACA;GACA;EACA;AACD,OAAK,MAAM,QAAQ,aAClB,KAAI,QAAQ,mBAAmB,SAAS,UAAU,SACjD,QAAO,SAAS;AAKlB,MAAI;AACH,UAAO,KAAK,UAAU,MAAM;EAC5B,QAAO;AACP,UAAO,OAAO,MAAM;EACpB;CACD;AAGD,QAAO,OAAO,MAAM;AACpB"}

package/dist/index-BNWUFJ69.d.ts

@@ -0,0 +1,129 @@
+import { Err } from "./result-DKwq9BCr.js";
+import { DefineErrorsReturn, ErrorBody, ErrorsConfig, ValidatedConfig } from "./types-tXXk7K9Q.js";
+
+//#region src/error/defineErrors.d.ts
+
+/**
+ * Defines a set of typed error factories using Rust-style namespaced variants.
+ *
+ * Each key is a short variant name (the namespace provides context). Every
+ * factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch
+ * handlers. The variant name is stamped as `name` on the error object.
+ *
+ * @example
+ * ```ts
+ * const HttpError = defineErrors({
+ *   Connection: ({ cause }: { cause: unknown }) => ({
+ *     message: `Failed to connect: ${extractErrorMessage(cause)}`,
+ *     cause,
+ *   }),
+ *   Response: ({ status }: { status: number; bodyMessage?: string }) => ({
+ *     message: `HTTP ${status}`,
+ *     status,
+ *   }),
+ *   Parse: ({ cause }: { cause: unknown }) => ({
+ *     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,
+ *     cause,
+ *   }),
+ * });
+ *
+ * type HttpError = InferErrors<typeof HttpError>;
+ *
+ * const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>
+ * ```
+ *
+ * Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The
+ * mapping is nearly 1:1:
+ *
+ * - `enum HttpError` → `const HttpError = defineErrors(...)`
+ * - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`
+ * - `#[error("Failed: {cause}")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``
+ * - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`
+ * - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`
+ *
+ * The equivalent Rust `thiserror` enum:
+ * ```rust
+ * #[derive(Error, Debug)]
+ * enum HttpError {
+ *     #[error("Failed to connect: {cause}")]
+ *     Connection { cause: String },
+ *
+ *     #[error("HTTP {status}")]
+ *     Response { status: u16, body_message: Option<String> },
+ *
+ *     #[error("Failed to parse response body: {cause}")]
+ *     Parse { cause: String },
+ * }
+ * ```
+ */
+declare function defineErrors<const TConfig extends ErrorsConfig>(config: TConfig & ValidatedConfig<TConfig>): DefineErrorsReturn<TConfig>;
+//# sourceMappingURL=defineErrors.d.ts.map
+//#endregion
+//#region src/error/defineHttpErrors.d.ts
+/** Config: each key maps to `[httpStatus, factory]`. */
+type HttpErrorsConfig = Record<string, [number, (...args: any[]) => ErrorBody]>;
+/**
+ * Per-key validation applied to the factory portion of each tuple.
+ * Mirrors `ValidatedConfig` from `defineErrors`: prevents `name` in the
+ * factory return body since the factory key is stamped as `name`.
+ */
+type ValidateHttpErrorBody<K extends string> = {
+  message: string;
+  name?: `The 'name' key is reserved as '${K}'. Remove it.`;
+};
+type ValidatedHttpConfig<T extends HttpErrorsConfig> = { [K in keyof T & string]: T[K] extends [infer TStatus, (...args: infer A) => infer R] ? [TStatus, (...args: A) => R & ValidateHttpErrorBody<K>] : T[K] };
+/**
+ * A factory function with a static `.status` property holding the literal
+ * HTTP status code. The status is never included in the serialized error body.
+ */
+type HttpErrorFactory<TName extends string, TStatus extends number, TFn extends (...args: any[]) => ErrorBody> = ((...args: Parameters<TFn>) => Err<Readonly<{
+  name: TName;
+} & ReturnType<TFn>>>) & {
+  readonly status: TStatus;
+};
+/** Return type of `defineHttpErrors`. Maps each config key to its `HttpErrorFactory`. */
+type DefineHttpErrorsReturn<TConfig extends HttpErrorsConfig> = { [K in keyof TConfig & string]: TConfig[K] extends [infer TStatus extends number, infer TFn extends (...args: any[]) => ErrorBody] ? HttpErrorFactory<K, TStatus, TFn> : never };
+/** Extract the error instance type from a single `HttpErrorFactory`. */
+type InferHttpError<T> = T extends ((...args: any[]) => Err<infer R>) ? R : never;
+/** Extract the union of all error instance types from a `defineHttpErrors` return. */
+type InferHttpErrors<T> = { [K in keyof T]: T[K] extends ((...args: any[]) => Err<infer R>) ? R : never }[keyof T];
+/**
+ * Defines a set of typed HTTP error factories, each paired with its HTTP
+ * status code.
+ *
+ * Like `defineErrors`, each factory stamps `name` onto the error and wraps it
+ * in `Err`. Unlike `defineErrors`, each factory function carries a static
+ * `.status` property with the literal HTTP status code — the status is never
+ * included in the serialized error body.
+ *
+ * @example
+ * ```ts
+ * const AssetError = defineHttpErrors({
+ *   MissingFile:          [400, () => ({ message: 'Missing file' })],
+ *   FileTooLarge:         [413, ({ size }: { size: number }) => ({ message: `File too large: ${size}`, size })],
+ *   StorageLimitExceeded: [402, () => ({ message: 'Storage limit exceeded' })],
+ * });
+ *
+ * type AssetError = InferHttpErrors<typeof AssetError>;
+ *
+ * // In a Hono route handler:
+ * return c.json(AssetError.MissingFile(), AssetError.MissingFile.status);
+ * // wire body: { error: { name: 'MissingFile', message: 'Missing file' }, data: null }
+ * // http status: 400
+ * ```
+ */
+declare function defineHttpErrors<const TConfig extends HttpErrorsConfig>(config: TConfig & ValidatedHttpConfig<TConfig>): DefineHttpErrorsReturn<TConfig>;
+//#endregion
+//#region src/error/extractErrorMessage.d.ts
+/**
+ * Extracts a readable error message from an unknown error value
+ *
+ * @param error - The unknown error to extract a message from
+ * @returns A string representation of the error
+ */
+declare function extractErrorMessage(error: unknown): string;
+//# sourceMappingURL=extractErrorMessage.d.ts.map
+
+//#endregion
+export { DefineHttpErrorsReturn, HttpErrorFactory, HttpErrorsConfig, InferHttpError, InferHttpErrors, ValidatedHttpConfig, defineErrors, defineHttpErrors, extractErrorMessage };
+//# sourceMappingURL=index-BNWUFJ69.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-BNWUFJ69.d.ts","names":[],"sources":["../src/error/defineErrors.ts","../src/error/defineHttpErrors.ts","../src/error/extractErrorMessage.ts"],"sourcesContent":[],"mappings":";;;;;;;;AA4DA;;;;;;;;AAEqB;;;;ACrDrB;;;;AAAqC;AAAkD;AAYvF;;;;;;;;;;;;;AAIO;AAYP;;;;;;;;;;;AAE0B;AAI1B;;;;;;AAEwH,iBDexG,YCfwG,CAAA,sBDerE,YCfqE,CAAA,CAAA,MAAA,EDgB/G,OChB+G,GDgBrG,eChBqG,CDgBrF,OChBqF,CAAA,CAAA,EDiBrH,kBCjBqH,CDiBlG,OCjBkG,CAAA;;;;;KApC5G,gBAAA,GAAmB,4CAA4C;ADmD3E;;;;;KC5CK,qBD6Cc,CAAA,UAAA,MAAA,CAAA,GAAA;EAAe,OACZ,EAAA,MAAA;EAAO,IAA1B,CAAA,EAAA,kCC5CuC,CD4CvC,eAAA;AAAkB,CAAA;KCzCT,8BAA8B,kCAE7B,aAAa,EAAE,6DACvB,mBAAmB,MAAM,IAAI,sBAAsB,MACpD,EAAE;AAhBN;;;;AAAqC,KA4BzB,gBA5ByB,CAAA,cAAA,MAAA,EAAA,gBAAA,MAAA,EAAA,YAAA,CAAA,GAAA,IAAA,EAAA,GAAA,EAAA,EAAA,GA4BsE,SA5BtE,CAAA,GAAA,CAAA,CAAA,GAAA,IAAA,EA6BzB,UA7ByB,CA6Bd,GA7Bc,CAAA,EAAA,GA6BL,GA7BK,CA6BD,QA7BC,CAAA;EAOhC,IAAA,EAsBgD,KAtBhD;AAKL,CAAA,GAiB+D,UAjBnD,CAiB8D,GAjB9D,CAAA,CAAA,CAAA,CAAA,GAAA;EAAmB,SAAA,MAAA,EAkBZ,OAlBY;CAAA;;AAEL,KAoBd,sBApBc,CAAA,gBAoByB,gBApBzB,CAAA,GAAA,QAAE,MAsBf,OAtBe,GAAA,MAAA,GAsBI,OAtBJ,CAsBY,CAtBZ,CAAA,SAAA,CAAA,KAAA,iBAAA,MAAA,EAAA,KAAA,aAAA,CAAA,GAAA,IAAA,EAAA,GAAA,EAAA,EAAA,GAsB4F,SAtB5F,CAAA,GAuBxB,gBAvBwB,CAuBP,CAvBO,EAuBJ,OAvBI,EAuBK,GAvBL,CAAA,GAAA,KAAA,EAAC;;AACC,KAgClB,cAhCkB,CAAA,CAAA,CAAA,GAgCE,CAhCF,UAAA,CAAA,GAAA,IAAA,EAAA,GAAA,EAAA,EAAA,GAgCgC,GAhChC,CAAA,KAAA,EAAA,CAAA,IAgC+C,CAhC/C,GAAA,KAAA;;AAAI,KAmCtB,eAnCsB,CAAA,CAAA,CAAA,GAAA,QAC9B,MAoCS,CApCT,GAoCa,CApCb,CAoCe,CApCf,CAAA,UAAA,CAAA,GAAA,IAAA,EAAA,GAAA,EAAA,EAAA,GAoC8C,GApC9C,CAAA,KAAA,EAAA,CAAA,IAoC6D,CApC7D,GAAA,KAAA,EAAC,CAAA,MAqCG,CArCF,CAAA;AAAC;AAYP;;;;;;;;;;;AAE0B;AAI1B;;;;;;;;;;;AAGoB;AAUR,iBAqCI,gBArCU,CAAA,sBAqC6B,gBArC7B,CAAA,CAAA,MAAA,EAsCjB,OAtCiB,GAsCP,mBAtCO,CAsCa,OAtCb,CAAA,CAAA,EAuCvB,sBAvCuB,CAuCA,OAvCA,CAAA;;;;;;;ADI1B;;AAAmD,iBEtDnC,mBAAA,CFsDmC,KAAA,EAAA,OAAA,CAAA,EAAA,MAAA"}

package/dist/json.d.ts

@@ -1,6 +1,6 @@
 import { Err, Result } from "./result-DKwq9BCr.js";
 import { InferError } from "./types-tXXk7K9Q.js";
-import "./index-B9PnZCTt.js";
+import "./index-BNWUFJ69.js";
 import "./tap-err-CFhHBPfH.js";
 import "./index-DnoV2ZDO.js";
 

package/dist/json.js

@@ -1,5 +1,5 @@
 import { trySync } from "./result-C5cJ1_WU.js";
-import { defineErrors, extractErrorMessage } from "./error-Dy9wXt5_.js";
+import { defineErrors, extractErrorMessage } from "./error-DLVm7dsh.js";
 import "./tap-err-CP-re1HT.js";
 import "./result-C9V2Knvt.js";
 

package/dist/logger/index.d.ts

@@ -123,6 +123,18 @@ type Logger = {
  * annotation form would widen an unnecessary Partial into the value type.
  *
  * No dispose handler — `console` is not a resource.
+ *
+ * ### CLI authors: stream routing
+ *
+ * `console[level]` routes by level, not uniformly to stdout:
+ * - `console.log` (not used here) is the only method that writes stdout.
+ * - `console.info`, `console.debug`, `console.warn`, `console.error`,
+ *   `console.trace` all write **stderr** in Node/Bun.
+ *
+ * For a CLI that emits structured program output on stdout and diagnostics
+ * on stderr, this default is correct — every logger event goes to stderr.
+ * Authors who expect `log.info` to print to stdout will be surprised; write
+ * a custom sink that routes to `process.stdout` if that's the requirement.
  */
 declare const consoleSink: (event: LogEvent) => void;
 //# sourceMappingURL=console-sink.d.ts.map
@@ -147,16 +159,38 @@ declare const consoleSink: (event: LogEvent) => void;
  *   plus the level string); spelling them out beats an `emitErr("warn")`
  *   riddle.
  *
+ * ### Source convention
+ *
+ * `source` is a free-form string, but downstream filtering and tail-log
+ * grep become much easier when call sites converge on a shape. Recommended:
+ *
+ *     '<package>/<module>'    e.g. 'workspace/sync-supervisor'
+ *     '<app>/<feature>'       e.g. 'fuji/daemon-route'
+ *     '<package>/<area>'      e.g. 'auth/oauth-app'
+ *
+ * Keep it lowercase-kebab. Avoid bare factory names like
+ * `'attachSqliteMaterializer'`: they don't carry package context.
+ *
+ * ### Module-scope vs injected
+ *
+ * `const log = createLogger('source')` at module scope is fine for
+ * process-singleton modules (CLI commands, app bootstrap, leaf utilities
+ * the host does not customize per instance). For anything that can be
+ * instantiated more than once per process with different routing needs
+ * (per-document attach primitives, per-account auth state, per-workspace
+ * services), accept `log?: Logger` at the factory boundary and default
+ * to `createLogger('source')` for development ergonomics.
+ *
  * @example Library code (caller wires the sink)
  * function attachThing(ydoc: Doc, opts: { log?: Logger }) {
- *   const log = opts.log ?? createLogger('thing');
+ *   const log = opts.log ?? createLogger('workspace/thing');
  *   // ...
  * }
  *
  * @example App wiring (share one sink, multiple loggers)
  * const sink = composeSinks(consoleSink, myCustomSink);
- * attachThing(ydoc, { log: createLogger('thing', sink) });
- * attachOther(ydoc, { log: createLogger('other', sink) });
+ * attachThing(ydoc, { log: createLogger('workspace/thing', sink) });
+ * attachOther(ydoc, { log: createLogger('workspace/other', sink) });
  */
 declare function createLogger(source: string, sink?: LogSink): Logger;
 //# sourceMappingURL=create-logger.d.ts.map

package/dist/logger/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/logger/types.ts","../../src/logger/console-sink.ts","../../src/logger/create-logger.ts","../../src/logger/memory-sink.ts","../../src/logger/compose-sinks.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAUA;AAoBA;AAgBA;;AAA+B,KApCnB,QAAA,GAoCmB,OAAA,GAAA,OAAA,GAAA,MAAA,GAAA,MAAA,GAAA,OAAA;;;AAA4B;AAuC3D;;;;;AAAgD;AAahD;;;;AAEwB;;;;AC/ExB;KDSY,QAAA;;SAEJ;EEMQ,MAAA,EAAA,MAAA;EAAY,OAAA,EAAA,MAAA;EAAA,IAErB,CAAA,EAAA,OAAA;CAAqB;AACnB;;;;ACjBT;;;;AAA+D,KHsBnD,OAAA,GGtBmD,CAAA,CAAA,KAAA,EHsBhC,QGtBgC,EAAA,GAAA,IAAA,CAAA,GHsBX,OGtBW,CHsBH,eGtBG,CAAA;;;;ACM/D;;;;AAA0D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KJuD9C,aAAA,GAAgB,iBAAiB,IAAI;;;;;;;;;;;;KAarC,MAAA;aACA;YACD;;;;;;;;;;;;;AA1FX;AAoBA;AAgBA;;;;;AAA2D;AAuC3D;;;;;AAAgD;AAapC,cC7EC,WD6EK,EAAA,CAAA,KAAA,ECtEE,QDsEF,EAAA,GAAA,IAAA;;;;;;;;;AAxFlB;AAoBA;AAgBA;;;;;AAA2D;AAuC3D;;;;;AAAgD;AAahD;;;;AAEwB;;;;AC/ExB;;;iBCiBgB,YAAA,wBAET,UACJ;AAHH;;;;;;;AF5BA;AAoBA;AAgBA;;;;;AAA2D;AAuC3D;;;;;AAAgD;AAahD;;;;AAEwB,iBG5ER,UAAA,CAAA,CH4EQ,EAAA;QG5Ec;UAAiB;;AFHvD;;;;;;;;ADXA;AAoBA;AAgBA;;;;;AAA2D;AAuC3D;;;;;AAAgD;AAahD;;;;AAEwB;;;;AC/ExB;;iBGSgB,YAAA,WAAuB,YAAY"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/logger/types.ts","../../src/logger/console-sink.ts","../../src/logger/create-logger.ts","../../src/logger/memory-sink.ts","../../src/logger/compose-sinks.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAUA;AAoBA;AAgBA;;AAA+B,KApCnB,QAAA,GAoCmB,OAAA,GAAA,OAAA,GAAA,MAAA,GAAA,MAAA,GAAA,OAAA;;;AAA4B;AAuC3D;;;;;AAAgD;AAahD;;;;AAEwB;;;;ACnExB;KDHY,QAAA;;SAEJ;EE4BQ,MAAA,EAAA,MAAA;EAAY,OAAA,EAAA,MAAA;EAAA,IAErB,CAAA,EAAA,OAAA;CAAqB;AACnB;;;;ACvCT;;;;AAA+D,KHsBnD,OAAA,GGtBmD,CAAA,CAAA,KAAA,EHsBhC,QGtBgC,EAAA,GAAA,IAAA,CAAA,GHsBX,OGtBW,CHsBH,eGtBG,CAAA;;;;ACM/D;;;;AAA0D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KJuD9C,aAAA,GAAgB,iBAAiB,IAAI;;;;;;;;;;;;KAarC,MAAA;aACA;YACD;;;;;;;;;;;;;AA1FX;AAoBA;AAgBA;;;;;AAA2D;AAuC3D;;;;;AAAgD;AAahD;;;;AAEwB;;;;ACnExB;;;;AC2BgB,cD3BH,WC2Be,EAAA,CAAA,KAAA,EDpBR,QCoBQ,EAAA,GAAA,IAAA;;;;;;;;;AFlD5B;AAoBA;AAgBA;;;;;AAA2D;AAuC3D;;;;;AAAgD;AAahD;;;;AAEwB;;;;ACnExB;;;;AC2BA;;;;AAGS;;;;ACvCT;;;;AAA+D;;;;ACM/D;;;;AAA0D;iBF8B1C,YAAA,wBAET,UACJ;;;;;;;;AFrDH;AAoBA;AAgBA;;;;;AAA2D;AAuC3D;;;;;AAAgD;AAahD;;;;AAEwB,iBG5ER,UAAA,CAAA,CH4EQ,EAAA;QG5Ec;UAAiB;;AFSvD;;;;;;;;ADvBA;AAoBA;AAgBA;;;;;AAA2D;AAuC3D;;;;;AAAgD;AAahD;;;;AAEwB;;;;ACnExB;;iBGHgB,YAAA,WAAuB,YAAY"}

package/dist/logger/index.js

@@ -20,6 +20,18 @@ import { tapErr } from "../tap-err-CP-re1HT.js";
 * annotation form would widen an unnecessary Partial into the value type.
 *
 * No dispose handler — `console` is not a resource.
+*
+* ### CLI authors: stream routing
+*
+* `console[level]` routes by level, not uniformly to stdout:
+* - `console.log` (not used here) is the only method that writes stdout.
+* - `console.info`, `console.debug`, `console.warn`, `console.error`,
+*   `console.trace` all write **stderr** in Node/Bun.
+*
+* For a CLI that emits structured program output on stdout and diagnostics
+* on stderr, this default is correct — every logger event goes to stderr.
+* Authors who expect `log.info` to print to stdout will be surprised; write
+* a custom sink that routes to `process.stdout` if that's the requirement.
 */
 const consoleSink = (event) => {
 	const prefix = `[${event.source}]`;
@@ -51,16 +63,38 @@ function unwrapLoggable(err) {
 *   plus the level string); spelling them out beats an `emitErr("warn")`
 *   riddle.
 *
+* ### Source convention
+*
+* `source` is a free-form string, but downstream filtering and tail-log
+* grep become much easier when call sites converge on a shape. Recommended:
+*
+*     '<package>/<module>'    e.g. 'workspace/sync-supervisor'
+*     '<app>/<feature>'       e.g. 'fuji/daemon-route'
+*     '<package>/<area>'      e.g. 'auth/oauth-app'
+*
+* Keep it lowercase-kebab. Avoid bare factory names like
+* `'attachSqliteMaterializer'`: they don't carry package context.
+*
+* ### Module-scope vs injected
+*
+* `const log = createLogger('source')` at module scope is fine for
+* process-singleton modules (CLI commands, app bootstrap, leaf utilities
+* the host does not customize per instance). For anything that can be
+* instantiated more than once per process with different routing needs
+* (per-document attach primitives, per-account auth state, per-workspace
+* services), accept `log?: Logger` at the factory boundary and default
+* to `createLogger('source')` for development ergonomics.
+*
 * @example Library code (caller wires the sink)
 * function attachThing(ydoc: Doc, opts: { log?: Logger }) {
-*   const log = opts.log ?? createLogger('thing');
+*   const log = opts.log ?? createLogger('workspace/thing');
 *   // ...
 * }
 *
 * @example App wiring (share one sink, multiple loggers)
 * const sink = composeSinks(consoleSink, myCustomSink);
-* attachThing(ydoc, { log: createLogger('thing', sink) });
-* attachOther(ydoc, { log: createLogger('other', sink) });
+* attachThing(ydoc, { log: createLogger('workspace/thing', sink) });
+* attachOther(ydoc, { log: createLogger('workspace/other', sink) });
 */
 function createLogger(source, sink = consoleSink) {
 	const emit = (level, message, data) => {

package/dist/logger/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["err: LoggableError","source: string","sink: LogSink","level: LogLevel","message: string","data?: unknown","events: LogEvent[]","event: LogEvent"],"sources":["../../src/logger/console-sink.ts","../../src/logger/create-logger.ts","../../src/logger/memory-sink.ts","../../src/logger/compose-sinks.ts"],"sourcesContent":["import type { LogSink } from \"./types.js\";\n\n/**\n * Default sink. Writes to `console.*` with a `[source]` prefix.\n *\n * Kept as a singleton value (not a factory) because it takes no config —\n * adding `createConsoleSink({ format })` would be ceremony for a pattern\n * the user can trivially replace by writing their own sink.\n *\n * `console[event.level]` routes directly without a detached lookup table.\n * `LogLevel` is a subset of the Console method keys, so TS errors at this\n * access if a future level drifts (e.g. adding `fatal`). Calling the method\n * through `console[...]` preserves the `this` binding — avoids \"Illegal\n * invocation\" in runtimes that require it.\n *\n * `satisfies LogSink` (not `: LogSink`) keeps the inferred callable type\n * precise — `LogSink` is an intersection with optional dispose, and the\n * annotation form would widen an unnecessary Partial into the value type.\n *\n * No dispose handler — `console` is not a resource.\n */\nexport const consoleSink = ((event) => {\n\tconst prefix = `[${event.source}]`;\n\tif (event.data === undefined) {\n\t\tconsole[event.level](prefix, event.message);\n\t} else {\n\t\tconsole[event.level](prefix, event.message, event.data);\n\t}\n}) satisfies LogSink;\n","import type { AnyTaggedError } from \"../error/types.js\";\nimport { consoleSink } from \"./console-sink.js\";\nimport type { LoggableError, LogLevel, Logger, LogSink } from \"./types.js\";\n\n/** Narrow `LoggableError` to the raw tagged object. See `LoggableError` in `types.ts` for the discriminator rationale. */\nfunction unwrapLoggable(err: LoggableError): AnyTaggedError {\n\treturn \"name\" in err ? err : err.error;\n}\n\n/**\n * Create a logger bound to a `source` namespace and a sink.\n *\n * Design choices:\n * - **Positional args, not a bag.** Two arguments, both with obvious meaning;\n *   a `{ source, sink }` object would be ceremony.\n * - **`sink` defaults to `consoleSink`.** Most callers during development\n *   want console output with zero setup. Production apps swap it out via DI\n *   at the attach/wire-up site.\n * - **No global default logger.** There is no `setDefaultLogger()` and no\n *   module-level registry. Every consumer takes a `log?: Logger` option\n *   and defaults to `createLogger('<source>')` if omitted. Globals make\n *   test isolation and sink composition painful.\n * - **Method shorthand in the return object** over higher-order factories.\n *   The five methods differ in two simple ways (error-unary vs free-form,\n *   plus the level string); spelling them out beats an `emitErr(\"warn\")`\n *   riddle.\n *\n * @example Library code (caller wires the sink)\n * function attachThing(ydoc: Doc, opts: { log?: Logger }) {\n *   const log = opts.log ?? createLogger('thing');\n *   // ...\n * }\n *\n * @example App wiring (share one sink, multiple loggers)\n * const sink = composeSinks(consoleSink, myCustomSink);\n * attachThing(ydoc, { log: createLogger('thing', sink) });\n * attachOther(ydoc, { log: createLogger('other', sink) });\n */\nexport function createLogger(\n\tsource: string,\n\tsink: LogSink = consoleSink,\n): Logger {\n\tconst emit = (level: LogLevel, message: string, data?: unknown): void => {\n\t\tsink({ ts: Date.now(), level, source, message, data });\n\t};\n\treturn {\n\t\terror(err) {\n\t\t\tconst tagged = unwrapLoggable(err);\n\t\t\temit(\"error\", tagged.message, tagged);\n\t\t},\n\t\twarn(err) {\n\t\t\tconst tagged = unwrapLoggable(err);\n\t\t\temit(\"warn\", tagged.message, tagged);\n\t\t},\n\t\tinfo(message, data) {\n\t\t\temit(\"info\", message, data);\n\t\t},\n\t\tdebug(message, data) {\n\t\t\temit(\"debug\", message, data);\n\t\t},\n\t\ttrace(message, data) {\n\t\t\temit(\"trace\", message, data);\n\t\t},\n\t};\n}\n","import type { LogEvent, LogSink } from \"./types.js\";\n\n/**\n * In-memory sink for tests. Returns `{ sink, events }` so callers can\n * both wire the sink and inspect captured events without a module-level\n * spy or `console.*` interception.\n *\n * A factory (not a singleton) so each test gets an isolated array; sharing\n * state across tests would leak events.\n *\n * Returning `{ sink, events }` (rather than an array with a method) keeps\n * the two roles separate — `sink` goes to `createLogger`, `events` goes to\n * assertions.\n *\n * Uses `satisfies LogSink` on the sink expression rather than `: LogSink =`\n * to preserve the precise inferred callable type.\n *\n * @example\n * const { sink, events } = memorySink();\n * const log = createLogger(\"test\", sink);\n * log.warn(MyError.Thing({ cause: new Error(\"boom\") }));\n * expect(events).toHaveLength(1);\n * expect(events[0]).toMatchObject({ level: \"warn\", source: \"test\" });\n */\nexport function memorySink(): { sink: LogSink; events: LogEvent[] } {\n\tconst events: LogEvent[] = [];\n\tconst sink = ((event) => {\n\t\tevents.push(event);\n\t}) satisfies LogSink;\n\treturn { sink, events };\n}\n","import type { LogEvent, LogSink } from \"./types.js\";\n\n/**\n * Fan one event out to every sink in order.\n *\n * Disposal: the returned sink has a `[Symbol.asyncDispose]` that forwards\n * to each member via optional chaining. Members without dispose (e.g.\n * `consoleSink`) are silent no-ops; members that own resources (file,\n * network) flush and close. Mix pure and stateful sinks freely — no\n * wrapping required.\n *\n * Fan-out is sequential and unguarded. If a member sink throws on emit,\n * later members do not receive the event — by design, since swallowing\n * sink errors hides real bugs. Wrap individual sinks yourself for\n * best-effort delivery.\n *\n * Dispose is sequential and awaits each member. If one throws, later\n * members don't get their chance; callers who want best-effort cleanup\n * should wrap the composed dispose themselves.\n *\n * Built with `Object.assign` + `satisfies LogSink` rather than mutating a\n * pre-typed `const` — avoids the widening that comes with `: LogSink =` and\n * keeps the inferred type precise (callable + definite dispose, not\n * callable + Partial dispose).\n *\n * @example\n * await using file = jsonlFileSink(\"/tmp/app.jsonl\");\n * const sink = composeSinks(consoleSink, file);\n * const log = createLogger(\"source\", sink);\n */\nexport function composeSinks(...sinks: LogSink[]): LogSink {\n\tconst emit = (event: LogEvent) => {\n\t\tfor (const sink of sinks) sink(event);\n\t};\n\tconst dispose = async (): Promise<void> => {\n\t\tfor (const sink of sinks) await sink[Symbol.asyncDispose]?.();\n\t};\n\treturn Object.assign(emit, {\n\t\t[Symbol.asyncDispose]: dispose,\n\t}) satisfies LogSink;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAqBA,MAAa,cAAe,CAAC,UAAU;CACtC,MAAM,SAAS,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC;AAClC,KAAI,MAAM,gBACT,SAAQ,MAAM,OAAO,QAAQ,MAAM,QAAQ;KAE3C,SAAQ,MAAM,OAAO,QAAQ,MAAM,SAAS,MAAM,KAAK;AAExD;;;;;ACvBD,SAAS,eAAeA,KAAoC;AAC3D,QAAO,UAAU,MAAM,MAAM,IAAI;AACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BD,SAAgB,aACfC,QACAC,OAAgB,aACP;CACT,MAAM,OAAO,CAACC,OAAiBC,SAAiBC,SAAyB;AACxE,OAAK;GAAE,IAAI,KAAK,KAAK;GAAE;GAAO;GAAQ;GAAS;EAAM,EAAC;CACtD;AACD,QAAO;EACN,MAAM,KAAK;GACV,MAAM,SAAS,eAAe,IAAI;AAClC,QAAK,SAAS,OAAO,SAAS,OAAO;EACrC;EACD,KAAK,KAAK;GACT,MAAM,SAAS,eAAe,IAAI;AAClC,QAAK,QAAQ,OAAO,SAAS,OAAO;EACpC;EACD,KAAK,SAAS,MAAM;AACnB,QAAK,QAAQ,SAAS,KAAK;EAC3B;EACD,MAAM,SAAS,MAAM;AACpB,QAAK,SAAS,SAAS,KAAK;EAC5B;EACD,MAAM,SAAS,MAAM;AACpB,QAAK,SAAS,SAAS,KAAK;EAC5B;CACD;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;ACxCD,SAAgB,aAAoD;CACnE,MAAMC,SAAqB,CAAE;CAC7B,MAAM,OAAQ,CAAC,UAAU;AACxB,SAAO,KAAK,MAAM;CAClB;AACD,QAAO;EAAE;EAAM;CAAQ;AACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACAD,SAAgB,aAAa,GAAG,OAA2B;CAC1D,MAAM,OAAO,CAACC,UAAoB;AACjC,OAAK,MAAM,QAAQ,MAAO,MAAK,MAAM;CACrC;CACD,MAAM,UAAU,YAA2B;AAC1C,OAAK,MAAM,QAAQ,MAAO,OAAM,KAAK,OAAO,iBAAiB;CAC7D;AACD,QAAO,OAAO,OAAO,MAAM,GACzB,OAAO,eAAe,QACvB,EAAC;AACF"}
+{"version":3,"file":"index.js","names":["err: LoggableError","source: string","sink: LogSink","level: LogLevel","message: string","data?: unknown","events: LogEvent[]","event: LogEvent"],"sources":["../../src/logger/console-sink.ts","../../src/logger/create-logger.ts","../../src/logger/memory-sink.ts","../../src/logger/compose-sinks.ts"],"sourcesContent":["import type { LogSink } from \"./types.js\";\n\n/**\n * Default sink. Writes to `console.*` with a `[source]` prefix.\n *\n * Kept as a singleton value (not a factory) because it takes no config —\n * adding `createConsoleSink({ format })` would be ceremony for a pattern\n * the user can trivially replace by writing their own sink.\n *\n * `console[event.level]` routes directly without a detached lookup table.\n * `LogLevel` is a subset of the Console method keys, so TS errors at this\n * access if a future level drifts (e.g. adding `fatal`). Calling the method\n * through `console[...]` preserves the `this` binding — avoids \"Illegal\n * invocation\" in runtimes that require it.\n *\n * `satisfies LogSink` (not `: LogSink`) keeps the inferred callable type\n * precise — `LogSink` is an intersection with optional dispose, and the\n * annotation form would widen an unnecessary Partial into the value type.\n *\n * No dispose handler — `console` is not a resource.\n *\n * ### CLI authors: stream routing\n *\n * `console[level]` routes by level, not uniformly to stdout:\n * - `console.log` (not used here) is the only method that writes stdout.\n * - `console.info`, `console.debug`, `console.warn`, `console.error`,\n *   `console.trace` all write **stderr** in Node/Bun.\n *\n * For a CLI that emits structured program output on stdout and diagnostics\n * on stderr, this default is correct — every logger event goes to stderr.\n * Authors who expect `log.info` to print to stdout will be surprised; write\n * a custom sink that routes to `process.stdout` if that's the requirement.\n */\nexport const consoleSink = ((event) => {\n\tconst prefix = `[${event.source}]`;\n\tif (event.data === undefined) {\n\t\tconsole[event.level](prefix, event.message);\n\t} else {\n\t\tconsole[event.level](prefix, event.message, event.data);\n\t}\n}) satisfies LogSink;\n","import type { AnyTaggedError } from \"../error/types.js\";\nimport { consoleSink } from \"./console-sink.js\";\nimport type { LoggableError, LogLevel, Logger, LogSink } from \"./types.js\";\n\n/** Narrow `LoggableError` to the raw tagged object. See `LoggableError` in `types.ts` for the discriminator rationale. */\nfunction unwrapLoggable(err: LoggableError): AnyTaggedError {\n\treturn \"name\" in err ? err : err.error;\n}\n\n/**\n * Create a logger bound to a `source` namespace and a sink.\n *\n * Design choices:\n * - **Positional args, not a bag.** Two arguments, both with obvious meaning;\n *   a `{ source, sink }` object would be ceremony.\n * - **`sink` defaults to `consoleSink`.** Most callers during development\n *   want console output with zero setup. Production apps swap it out via DI\n *   at the attach/wire-up site.\n * - **No global default logger.** There is no `setDefaultLogger()` and no\n *   module-level registry. Every consumer takes a `log?: Logger` option\n *   and defaults to `createLogger('<source>')` if omitted. Globals make\n *   test isolation and sink composition painful.\n * - **Method shorthand in the return object** over higher-order factories.\n *   The five methods differ in two simple ways (error-unary vs free-form,\n *   plus the level string); spelling them out beats an `emitErr(\"warn\")`\n *   riddle.\n *\n * ### Source convention\n *\n * `source` is a free-form string, but downstream filtering and tail-log\n * grep become much easier when call sites converge on a shape. Recommended:\n *\n *     '<package>/<module>'    e.g. 'workspace/sync-supervisor'\n *     '<app>/<feature>'       e.g. 'fuji/daemon-route'\n *     '<package>/<area>'      e.g. 'auth/oauth-app'\n *\n * Keep it lowercase-kebab. Avoid bare factory names like\n * `'attachSqliteMaterializer'`: they don't carry package context.\n *\n * ### Module-scope vs injected\n *\n * `const log = createLogger('source')` at module scope is fine for\n * process-singleton modules (CLI commands, app bootstrap, leaf utilities\n * the host does not customize per instance). For anything that can be\n * instantiated more than once per process with different routing needs\n * (per-document attach primitives, per-account auth state, per-workspace\n * services), accept `log?: Logger` at the factory boundary and default\n * to `createLogger('source')` for development ergonomics.\n *\n * @example Library code (caller wires the sink)\n * function attachThing(ydoc: Doc, opts: { log?: Logger }) {\n *   const log = opts.log ?? createLogger('workspace/thing');\n *   // ...\n * }\n *\n * @example App wiring (share one sink, multiple loggers)\n * const sink = composeSinks(consoleSink, myCustomSink);\n * attachThing(ydoc, { log: createLogger('workspace/thing', sink) });\n * attachOther(ydoc, { log: createLogger('workspace/other', sink) });\n */\nexport function createLogger(\n\tsource: string,\n\tsink: LogSink = consoleSink,\n): Logger {\n\tconst emit = (level: LogLevel, message: string, data?: unknown): void => {\n\t\tsink({ ts: Date.now(), level, source, message, data });\n\t};\n\treturn {\n\t\terror(err) {\n\t\t\tconst tagged = unwrapLoggable(err);\n\t\t\temit(\"error\", tagged.message, tagged);\n\t\t},\n\t\twarn(err) {\n\t\t\tconst tagged = unwrapLoggable(err);\n\t\t\temit(\"warn\", tagged.message, tagged);\n\t\t},\n\t\tinfo(message, data) {\n\t\t\temit(\"info\", message, data);\n\t\t},\n\t\tdebug(message, data) {\n\t\t\temit(\"debug\", message, data);\n\t\t},\n\t\ttrace(message, data) {\n\t\t\temit(\"trace\", message, data);\n\t\t},\n\t};\n}\n","import type { LogEvent, LogSink } from \"./types.js\";\n\n/**\n * In-memory sink for tests. Returns `{ sink, events }` so callers can\n * both wire the sink and inspect captured events without a module-level\n * spy or `console.*` interception.\n *\n * A factory (not a singleton) so each test gets an isolated array; sharing\n * state across tests would leak events.\n *\n * Returning `{ sink, events }` (rather than an array with a method) keeps\n * the two roles separate — `sink` goes to `createLogger`, `events` goes to\n * assertions.\n *\n * Uses `satisfies LogSink` on the sink expression rather than `: LogSink =`\n * to preserve the precise inferred callable type.\n *\n * @example\n * const { sink, events } = memorySink();\n * const log = createLogger(\"test\", sink);\n * log.warn(MyError.Thing({ cause: new Error(\"boom\") }));\n * expect(events).toHaveLength(1);\n * expect(events[0]).toMatchObject({ level: \"warn\", source: \"test\" });\n */\nexport function memorySink(): { sink: LogSink; events: LogEvent[] } {\n\tconst events: LogEvent[] = [];\n\tconst sink = ((event) => {\n\t\tevents.push(event);\n\t}) satisfies LogSink;\n\treturn { sink, events };\n}\n","import type { LogEvent, LogSink } from \"./types.js\";\n\n/**\n * Fan one event out to every sink in order.\n *\n * Disposal: the returned sink has a `[Symbol.asyncDispose]` that forwards\n * to each member via optional chaining. Members without dispose (e.g.\n * `consoleSink`) are silent no-ops; members that own resources (file,\n * network) flush and close. Mix pure and stateful sinks freely — no\n * wrapping required.\n *\n * Fan-out is sequential and unguarded. If a member sink throws on emit,\n * later members do not receive the event — by design, since swallowing\n * sink errors hides real bugs. Wrap individual sinks yourself for\n * best-effort delivery.\n *\n * Dispose is sequential and awaits each member. If one throws, later\n * members don't get their chance; callers who want best-effort cleanup\n * should wrap the composed dispose themselves.\n *\n * Built with `Object.assign` + `satisfies LogSink` rather than mutating a\n * pre-typed `const` — avoids the widening that comes with `: LogSink =` and\n * keeps the inferred type precise (callable + definite dispose, not\n * callable + Partial dispose).\n *\n * @example\n * await using file = jsonlFileSink(\"/tmp/app.jsonl\");\n * const sink = composeSinks(consoleSink, file);\n * const log = createLogger(\"source\", sink);\n */\nexport function composeSinks(...sinks: LogSink[]): LogSink {\n\tconst emit = (event: LogEvent) => {\n\t\tfor (const sink of sinks) sink(event);\n\t};\n\tconst dispose = async (): Promise<void> => {\n\t\tfor (const sink of sinks) await sink[Symbol.asyncDispose]?.();\n\t};\n\treturn Object.assign(emit, {\n\t\t[Symbol.asyncDispose]: dispose,\n\t}) satisfies LogSink;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,MAAa,cAAe,CAAC,UAAU;CACtC,MAAM,SAAS,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC;AAClC,KAAI,MAAM,gBACT,SAAQ,MAAM,OAAO,QAAQ,MAAM,QAAQ;KAE3C,SAAQ,MAAM,OAAO,QAAQ,MAAM,SAAS,MAAM,KAAK;AAExD;;;;;ACnCD,SAAS,eAAeA,KAAoC;AAC3D,QAAO,UAAU,MAAM,MAAM,IAAI;AACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDD,SAAgB,aACfC,QACAC,OAAgB,aACP;CACT,MAAM,OAAO,CAACC,OAAiBC,SAAiBC,SAAyB;AACxE,OAAK;GAAE,IAAI,KAAK,KAAK;GAAE;GAAO;GAAQ;GAAS;EAAM,EAAC;CACtD;AACD,QAAO;EACN,MAAM,KAAK;GACV,MAAM,SAAS,eAAe,IAAI;AAClC,QAAK,SAAS,OAAO,SAAS,OAAO;EACrC;EACD,KAAK,KAAK;GACT,MAAM,SAAS,eAAe,IAAI;AAClC,QAAK,QAAQ,OAAO,SAAS,OAAO;EACpC;EACD,KAAK,SAAS,MAAM;AACnB,QAAK,QAAQ,SAAS,KAAK;EAC3B;EACD,MAAM,SAAS,MAAM;AACpB,QAAK,SAAS,SAAS,KAAK;EAC5B;EACD,MAAM,SAAS,MAAM;AACpB,QAAK,SAAS,SAAS,KAAK;EAC5B;CACD;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;AC9DD,SAAgB,aAAoD;CACnE,MAAMC,SAAqB,CAAE;CAC7B,MAAM,OAAQ,CAAC,UAAU;AACxB,SAAO,KAAK,MAAM;CAClB;AACD,QAAO;EAAE;EAAM;CAAQ;AACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACAD,SAAgB,aAAa,GAAG,OAA2B;CAC1D,MAAM,OAAO,CAACC,UAAoB;AACjC,OAAK,MAAM,QAAQ,MAAO,MAAK,MAAM;CACrC;CACD,MAAM,UAAU,YAA2B;AAC1C,OAAK,MAAM,QAAQ,MAAO,OAAM,KAAK,OAAO,iBAAiB;CAC7D;AACD,QAAO,OAAO,OAAO,MAAM,GACzB,OAAO,eAAe,QACvB,EAAC;AACF"}

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { isErr, isOk } from "./result-C5cJ1_WU.js";
-import { extractErrorMessage } from "./error-Dy9wXt5_.js";
+import { extractErrorMessage } from "./error-DLVm7dsh.js";
 import "./tap-err-CP-re1HT.js";
 import "./result-C9V2Knvt.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wellcrafted",
-	"version": "0.36.0",
+	"version": "0.37.0",
 	"description": "Delightful TypeScript patterns for elegant, type-safe applications",
 	"type": "module",
 	"files": [

package/dist/error-Dy9wXt5_.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"error-Dy9wXt5_.js","names":["config: TConfig & ValidatedConfig<TConfig>","result: Record<string, unknown>","error: unknown"],"sources":["../src/error/defineErrors.ts","../src/error/extractErrorMessage.ts"],"sourcesContent":["import { Err } from \"../result/result.js\";\nimport type {\n\tDefineErrorsReturn,\n\tErrorsConfig,\n\tValidatedConfig,\n} from \"./types.js\";\n\n/**\n * Defines a set of typed error factories using Rust-style namespaced variants.\n *\n * Each key is a short variant name (the namespace provides context). Every\n * factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch\n * handlers. The variant name is stamped as `name` on the error object.\n *\n * @example\n * ```ts\n * const HttpError = defineErrors({\n *   Connection: ({ cause }: { cause: unknown }) => ({\n *     message: `Failed to connect: ${extractErrorMessage(cause)}`,\n *     cause,\n *   }),\n *   Response: ({ status }: { status: number; bodyMessage?: string }) => ({\n *     message: `HTTP ${status}`,\n *     status,\n *   }),\n *   Parse: ({ cause }: { cause: unknown }) => ({\n *     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,\n *     cause,\n *   }),\n * });\n *\n * type HttpError = InferErrors<typeof HttpError>;\n *\n * const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>\n * ```\n *\n * Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The\n * mapping is nearly 1:1:\n *\n * - `enum HttpError` → `const HttpError = defineErrors(...)`\n * - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`\n * - `#[error(\"Failed: {cause}\")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``\n * - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`\n * - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`\n *\n * The equivalent Rust `thiserror` enum:\n * ```rust\n * #[derive(Error, Debug)]\n * enum HttpError {\n *     #[error(\"Failed to connect: {cause}\")]\n *     Connection { cause: String },\n *\n *     #[error(\"HTTP {status}\")]\n *     Response { status: u16, body_message: Option<String> },\n *\n *     #[error(\"Failed to parse response body: {cause}\")]\n *     Parse { cause: String },\n * }\n * ```\n */\nexport function defineErrors<const TConfig extends ErrorsConfig>(\n\tconfig: TConfig & ValidatedConfig<TConfig>,\n): DefineErrorsReturn<TConfig> {\n\tconst result: Record<string, unknown> = {};\n\n\tfor (const [name, ctor] of Object.entries(config)) {\n\t\tresult[name] = (...args: unknown[]) => {\n\t\t\tconst body = (ctor as (...a: unknown[]) => Record<string, unknown>)(\n\t\t\t\t...args,\n\t\t\t);\n\t\t\treturn Err(Object.freeze({ ...body, name }));\n\t\t};\n\t}\n\n\treturn result as DefineErrorsReturn<TConfig>;\n}\n","/**\n * Extracts a readable error message from an unknown error value\n *\n * @param error - The unknown error to extract a message from\n * @returns A string representation of the error\n */\nexport function extractErrorMessage(error: unknown): string {\n\t// Handle Error instances\n\tif (error instanceof Error) {\n\t\treturn error.message;\n\t}\n\n\t// Handle primitives\n\tif (typeof error === \"string\") return error;\n\tif (\n\t\ttypeof error === \"number\" ||\n\t\ttypeof error === \"boolean\" ||\n\t\ttypeof error === \"bigint\"\n\t)\n\t\treturn String(error);\n\tif (typeof error === \"symbol\") return error.toString();\n\tif (error === null) return \"null\";\n\tif (error === undefined) return \"undefined\";\n\n\t// Handle arrays\n\tif (Array.isArray(error)) return JSON.stringify(error);\n\n\t// Handle plain objects\n\tif (typeof error === \"object\") {\n\t\tconst errorObj = error as Record<string, unknown>;\n\n\t\t// Check common error properties\n\t\tconst messageProps = [\n\t\t\t\"message\",\n\t\t\t\"error\",\n\t\t\t\"description\",\n\t\t\t\"title\",\n\t\t\t\"reason\",\n\t\t\t\"details\",\n\t\t] as const;\n\t\tfor (const prop of messageProps) {\n\t\t\tif (prop in errorObj && typeof errorObj[prop] === \"string\") {\n\t\t\t\treturn errorObj[prop];\n\t\t\t}\n\t\t}\n\n\t\t// Fallback to JSON stringification\n\t\ttry {\n\t\t\treturn JSON.stringify(error);\n\t\t} catch {\n\t\t\treturn String(error);\n\t\t}\n\t}\n\n\t// Final fallback\n\treturn String(error);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,SAAgB,aACfA,QAC8B;CAC9B,MAAMC,SAAkC,CAAE;AAE1C,MAAK,MAAM,CAAC,MAAM,KAAK,IAAI,OAAO,QAAQ,OAAO,CAChD,QAAO,QAAQ,CAAC,GAAG,SAAoB;EACtC,MAAM,OAAO,AAAC,KACb,GAAG,KACH;AACD,SAAO,IAAI,OAAO,OAAO;GAAE,GAAG;GAAM;EAAM,EAAC,CAAC;CAC5C;AAGF,QAAO;AACP;;;;;;;;;;ACrED,SAAgB,oBAAoBC,OAAwB;AAE3D,KAAI,iBAAiB,MACpB,QAAO,MAAM;AAId,YAAW,UAAU,SAAU,QAAO;AACtC,YACQ,UAAU,mBACV,UAAU,oBACV,UAAU,SAEjB,QAAO,OAAO,MAAM;AACrB,YAAW,UAAU,SAAU,QAAO,MAAM,UAAU;AACtD,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,iBAAqB,QAAO;AAGhC,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,KAAK,UAAU,MAAM;AAGtD,YAAW,UAAU,UAAU;EAC9B,MAAM,WAAW;EAGjB,MAAM,eAAe;GACpB;GACA;GACA;GACA;GACA;GACA;EACA;AACD,OAAK,MAAM,QAAQ,aAClB,KAAI,QAAQ,mBAAmB,SAAS,UAAU,SACjD,QAAO,SAAS;AAKlB,MAAI;AACH,UAAO,KAAK,UAAU,MAAM;EAC5B,QAAO;AACP,UAAO,OAAO,MAAM;EACpB;CACD;AAGD,QAAO,OAAO,MAAM;AACpB"}

package/dist/index-B9PnZCTt.d.ts

@@ -1,73 +0,0 @@
-import { DefineErrorsReturn, ErrorsConfig, ValidatedConfig } from "./types-tXXk7K9Q.js";
-
-//#region src/error/defineErrors.d.ts
-
-/**
- * Defines a set of typed error factories using Rust-style namespaced variants.
- *
- * Each key is a short variant name (the namespace provides context). Every
- * factory returns `Err<...>` directly — ready for `trySync`/`tryAsync` catch
- * handlers. The variant name is stamped as `name` on the error object.
- *
- * @example
- * ```ts
- * const HttpError = defineErrors({
- *   Connection: ({ cause }: { cause: unknown }) => ({
- *     message: `Failed to connect: ${extractErrorMessage(cause)}`,
- *     cause,
- *   }),
- *   Response: ({ status }: { status: number; bodyMessage?: string }) => ({
- *     message: `HTTP ${status}`,
- *     status,
- *   }),
- *   Parse: ({ cause }: { cause: unknown }) => ({
- *     message: `Failed to parse response body: ${extractErrorMessage(cause)}`,
- *     cause,
- *   }),
- * });
- *
- * type HttpError = InferErrors<typeof HttpError>;
- *
- * const result = HttpError.Connection({ cause: 'timeout' }); // Err<...>
- * ```
- *
- * Inspired by Rust's {@link https://docs.rs/thiserror | thiserror} crate. The
- * mapping is nearly 1:1:
- *
- * - `enum HttpError` → `const HttpError = defineErrors(...)`
- * - Variant `Connection { cause: String }` → key `Connection: ({ cause }: { cause: unknown }) => (...)`
- * - `#[error("Failed: {cause}")]` → `` message: `Failed: ${extractErrorMessage(cause)}` ``
- * - `HttpError::Connection { ... }` → `HttpError.Connection({ ... })`
- * - `match error { Connection { .. } => }` → `switch (error.name) { case 'Connection': }`
- *
- * The equivalent Rust `thiserror` enum:
- * ```rust
- * #[derive(Error, Debug)]
- * enum HttpError {
- *     #[error("Failed to connect: {cause}")]
- *     Connection { cause: String },
- *
- *     #[error("HTTP {status}")]
- *     Response { status: u16, body_message: Option<String> },
- *
- *     #[error("Failed to parse response body: {cause}")]
- *     Parse { cause: String },
- * }
- * ```
- */
-declare function defineErrors<const TConfig extends ErrorsConfig>(config: TConfig & ValidatedConfig<TConfig>): DefineErrorsReturn<TConfig>;
-//# sourceMappingURL=defineErrors.d.ts.map
-//#endregion
-//#region src/error/extractErrorMessage.d.ts
-/**
- * Extracts a readable error message from an unknown error value
- *
- * @param error - The unknown error to extract a message from
- * @returns A string representation of the error
- */
-declare function extractErrorMessage(error: unknown): string;
-//# sourceMappingURL=extractErrorMessage.d.ts.map
-
-//#endregion
-export { defineErrors, extractErrorMessage };
-//# sourceMappingURL=index-B9PnZCTt.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index-B9PnZCTt.d.ts","names":[],"sources":["../src/error/defineErrors.ts","../src/error/extractErrorMessage.ts"],"sourcesContent":[],"mappings":";;;;;;AA4DA;;;;;;;;AAEqB;;;;ACxDrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBDsDgB,mCAAmC,sBAC1C,UAAU,gBAAgB,WAChC,mBAAmB;;;;;;;AAFtB;;;AACS,iBCvDO,mBAAA,CDuDP,KAAA,EAAA,OAAA,CAAA,EAAA,MAAA"}