wellcrafted 0.34.0 → 0.35.0

package/dist/error/index.d.ts

@@ -1,47 +1,8 @@
-import { Err } from "../result-BgPMmUXd.js";
+import "../result-BongGO2O.js";
+import { AnyTaggedError, DefineErrorsReturn, ErrorBody, ErrorsConfig, InferError, InferErrors, ValidatedConfig } from "../types-cY80Bw6u.js";
 
-//#region src/error/types.d.ts
-
-/**
- * Base type for any tagged error, used as a minimum constraint.
- */
-type AnyTaggedError = {
-  name: string;
-  message: string;
-};
-/**
- * Constructor return must include `message: string`.
- * JSON serializability is a convention, not enforced at the type level
- * (optional fields produce `T | undefined` which breaks `JsonObject`).
- */
-type ErrorBody = {
-  message: string;
-};
-/**
- * Per-key validation: tells the user exactly what `name` will be stamped as.
- * If a user provides `name` in the return object, they see a descriptive error.
- */
-type ValidateErrorBody<K extends string> = {
-  message: string;
-  name?: `The 'name' key is reserved as '${K}'. Remove it.`;
-};
-/** The config: each key is a variant name, each value is a constructor function. */
-type ErrorsConfig = Record<string, (...args: any[]) => ErrorBody>;
-/** Validates each config entry, injecting the key-specific `name` reservation message. */
-type ValidatedConfig<T extends ErrorsConfig> = { [K in keyof T & string]: T[K] extends ((...args: infer A) => infer R) ? (...args: A) => R & ValidateErrorBody<K> : T[K] };
-/** Single factory: takes constructor args, returns Err-wrapped error. */
-type ErrorFactory<TName extends string, TFn extends (...args: any[]) => ErrorBody> = { [K in TName]: (...args: Parameters<TFn>) => Err<Readonly<{
-  name: TName;
-} & ReturnType<TFn>>> };
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
-/** Return type of `defineErrors`. Maps each config key to its factory. */
-type DefineErrorsReturn<TConfig extends ErrorsConfig> = UnionToIntersection<{ [K in keyof TConfig & string]: ErrorFactory<K, TConfig[K]> }[keyof TConfig & string]>;
-/** Extract the error type from a single factory. */
-type InferError<T> = T extends ((...args: any[]) => Err<infer R>) ? R : never;
-/** Extract union of ALL error types from a defineErrors return. */
-type InferErrors<T> = { [K in keyof T]: T[K] extends ((...args: any[]) => Err<infer R>) ? R : never }[keyof T];
-//#endregion
 //#region src/error/defineErrors.d.ts
+
 /**
  * Defines a set of typed error factories using Rust-style namespaced variants.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/error/types.ts","../../src/error/defineErrors.ts","../../src/error/extractErrorMessage.ts"],"sourcesContent":[],"mappings":";;;;;;AAKA;AAWY,KAXA,cAAA,GAWS;EAMhB,IAAA,EAAA,MAAA;EAOO,OAAA,EAAA,MAAY;CAAA;;;AAAS;AAGjC;;AAAsC,KAhB1B,SAAA,GAgB0B;EAAY,OAErC,EAAA,MAAA;CAAC;;;;;KAZT,iBAamB,CAAA,UAAA,MAAA,CAAA,GAAA;EAAiB,OACrC,EAAA,MAAA;EAAC,IAAC,CAAA,EAAA,kCAZoC,CAYpC,eAAA;AAAC,CAAA;AACL;AAGe,KAXL,YAAA,GAAe,MAWV,CAAA,MAAA,EAAA,CAAA,GAAA,IAAA,EAAA,GAAA,EAAA,EAAA,GAX6C,SAW7C,CAAA;;AAKV,KAbK,eAaL,CAAA,UAb+B,YAa/B,CAAA,GAAA,QACe,MAZT,CAYS,GAAA,MAAA,GAZI,CAYJ,CAZM,CAYN,CAAA,UAAA,CAAA,GAAA,IAAA,EAAA,KAAA,EAAA,EAAA,GAAA,KAAA,EAAA,IAAA,CAAA,GAAA,IAAA,EAXR,CAWQ,EAAA,GAXF,CAWE,GAXE,iBAWF,CAXoB,CAWpB,CAAA,GAVlB,CAUkB,CAVhB,CAUgB,CAAA,EAAG;;KANpB,YAO2C,CAAA,cAAA,MAAA,EAAA,YAAA,CAAA,GAAA,IAAA,EAAA,GAAA,EAAA,EAAA,GAJf,SAIe,CAAA,GAAA,QAFzC,KAE8B,GAAA,CAAA,GAAA,IAAA,EAD1B,UAC0B,CADf,GACe,CAAA,EAAA,GAA/B,GAA+B,CAA3B,QAA2B,CAAA;EAA3B,IAAA,EAAiB,KAAjB;AAAQ,CAAA,GAAmB,UAA/B,CAA0C,GAA1C,CAAA,CAAA,CAAA,EAAG;AAAA,KAIJ,mBAAA,CAAA,CAAmB,CAAA,GAAA,CAAO,CAAP,SAAA,GAAA,GAAA,CAAA,CAAA,EAA2B,CAA3B,EAAA,GAAA,IAAA,GAAA,KAAA,CAAA,UAAA,CAAA,CAAA,EAAA,KAAA,EAAA,EAAA,GAAA,IAAA,IAGrB,CAHqB,GAAA,KAAA;;AAAO,KAOnB,kBAPmB,CAAA,gBAOgB,YAPhB,CAAA,GAQ9B,mBAR8B,CAAA,QAAoB,MAUpC,OAVoC,GAAA,MAAA,GAUjB,YAViB,CAUJ,CAVI,EAUD,OAVC,CAUO,CAVP,CAAA,CAAA,EAAC,CAAA,MAW1C,OARP,GAAA,MAAA,CAAA,CAAA;AAAC;AAIQ,KAQA,UARA,CAAA,CAAA,CAAkB,GAU7B,CAV6B,UAAA,CAAA,GAAA,IAAA,EAAA,GAAA,EAAA,EAAA,GAUC,GAVD,CAAA,KAAA,EAAA,CAAA,IAUgB,CAVhB,GAAA,KAAA;;AAAiB,KAanC,WAbmC,CAAA,CAAA,CAAA,GAAA,QAGhC,MAYF,CAZE,GAYE,CAZF,CAYI,CAZJ,CAAA,UAAA,CAAA,GAAA,IAAA,EAAA,GAAA,EAAA,EAAA,GAYmC,GAZnC,CAAA,KAAA,EAAA,CAAA,IAYkD,CAZlD,GAAA,KAAA,EAAO,CAAA,MAad,CAbuC,CAAA;;;;;AAxD/C;AAWA;AAA4C;AAa5C;;;;AAAiC;AAGjC;;;;;;;;;;;;AAIO;AACL;;;;;;;;;;;AAUO;AAAA;;;;;AAOL;AAIJ;;;;;;;;;;AACoB;AAOpB;AAAsB,iBCNN,YDMM,CAAA,sBCN6B,YDM7B,CAAA,CAAA,MAAA,ECLb,ODKa,GCLH,eDKG,CCLa,ODKb,CAAA,CAAA,ECJnB,kBDImB,CCJA,ODIA,CAAA;;;;;;;AA7DtB;AAWA;AAA4C;AAahC,iBEvBI,mBAAA,CFuBQ,KAAA,EAAA,OAAA,CAAA,EAAA,MAAA"}
+{"version":3,"file":"index.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;;AAAmD,iBCtDnC,mBAAA,CDsDmC,KAAA,EAAA,OAAA,CAAA,EAAA,MAAA"}

package/dist/error/index.js

@@ -1,4 +1,4 @@
-import { Err } from "../result-DnOm5ds5.js";
+import { Err } from "../result-DzL3K2yA.js";
 
 //#region src/error/defineErrors.ts
 /**

package/dist/{index-8WW9UMob.d.ts → index-mb9iYu0a.d.ts}

@@ -1,4 +1,4 @@
-import { Err, Ok, Result } from "./result-BgPMmUXd.js";
+import { Err, Ok, Result } from "./result-BongGO2O.js";
 
 //#region src/result/utils.d.ts
 
@@ -25,4 +25,4 @@ declare function partitionResults<T, E>(results: Result<T, E>[]): {
 //# sourceMappingURL=utils.d.ts.map
 //#endregion
 export { partitionResults };
-//# sourceMappingURL=index-8WW9UMob.d.ts.map
+//# sourceMappingURL=index-mb9iYu0a.d.ts.map

package/dist/{index-8WW9UMob.d.ts.map → index-mb9iYu0a.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"index-8WW9UMob.d.ts","names":[],"sources":["../src/result/utils.ts"],"sourcesContent":[],"mappings":";;;;;;AAmBA;;;;;;;;;AAK+B;;;;;iBALf,gCAAgC,OAAO,GAAG;OAK7C,GAAG;QAAY,IAAI"}
+{"version":3,"file":"index-mb9iYu0a.d.ts","names":[],"sources":["../src/result/utils.ts"],"sourcesContent":[],"mappings":";;;;;;AAmBA;;;;;;;;;AAK+B;;;;;iBALf,gCAAgC,OAAO,GAAG;OAK7C,GAAG;QAAY,IAAI"}

package/dist/logger/index.d.ts

@@ -0,0 +1,228 @@
+import { Err } from "../result-BongGO2O.js";
+import { AnyTaggedError } from "../types-cY80Bw6u.js";
+import { tapErr } from "../tap-err-Bqs9aQpZ.js";
+
+//#region src/logger/types.d.ts
+
+/**
+ * Five levels, no `fatal`. Matches Rust's `tracing` exactly.
+ *
+ * Process termination is the application's call, not the library's — so
+ * there is no `fatal`. Apps that want to exit on a specific error do so
+ * explicitly (`process.exit`, `Bun.exit`) at the call site.
+ */
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/**
+ * The normalized event every sink receives.
+ *
+ * - `ts` is epoch millis (not a `Date`) — cheap to create, easy to serialize,
+ *   trivially monotonic for ordering. Sinks that want ISO-8601 on the wire
+ *   convert at serialization time.
+ * - `source` is the logger's namespace, stamped once at `createLogger` and
+ *   carried on every event. Analogous to `tracing`'s `target`.
+ * - `message` is human text. For `warn`/`error` it's copied from the
+ *   typed error's `message` field (so `event.message === event.data.message`
+ *   on those levels — intentional duplication so sinks have one uniform
+ *   rendering path regardless of event origin; they never need to know
+ *   whether `data` is a tagged error or free-form payload). The variant
+ *   template owns the phrasing; sinks just render.
+ * - `data` carries the structured payload. For `warn`/`error` it's the
+ *   typed error object itself (including `name` + captured fields). For
+ *   `info`/`debug`/`trace` it's free-form, caller-supplied.
+ */
+type LogEvent = {
+  ts: number;
+  level: LogLevel;
+  source: string;
+  message: string;
+  data?: unknown;
+};
+/**
+ * A sink is a callable that accepts events, with optional resource cleanup.
+ *
+ * The intersection with `Partial<AsyncDisposable>` lets the same type cover
+ * both pure functions (no-op dispose) and stateful sinks (file writers,
+ * network sockets). Callers who need guaranteed cleanup narrow to a
+ * `LogSink & AsyncDisposable` return type or bind with `await using`.
+ */
+type LogSink = ((event: LogEvent) => void) & Partial<AsyncDisposable>;
+/**
+ * Accepted by `log.warn` / `log.error`. Union of two shapes:
+ *
+ * - `AnyTaggedError` — the raw tagged error `{ name, message, ...fields }`.
+ *   Arrives via `result.error` after narrowing a Result.
+ * - `Err<AnyTaggedError>` — the `{ error: tagged, data: null }` wrapper
+ *   that `defineErrors` factories return directly.
+ *
+ * The logger unwraps via `"name" in err` inside `unwrapLoggable` — a
+ * purely structural discriminator:
+ *
+ * - `AnyTaggedError` always has `name` at the top level (stamped by
+ *   `defineErrors` from the factory key — a hard invariant of every
+ *   tagged error).
+ * - `Err<AnyTaggedError>` has exactly `{ error, data }` at the top level.
+ *   The tagged error's `name` lives on `err.error.name`, not `err.name`.
+ *
+ * Intentionally **not** checking `err.data === null`: that's also true for
+ * `Ok(T)` when `T = null` (see wellcrafted's `Ok(null)`/`Err(null)`
+ * structural collision edge — discussed in
+ * `docs/articles/ok-null-is-fine-err-null-is-a-lie.md`). Always discriminate
+ * by an invariant non-null property (`name` here), never by null-presence.
+ *
+ * Native `Error` instances also satisfy `AnyTaggedError` structurally
+ * (`name` and `message` are both present), so `log.warn(new Error("x"))`
+ * works out of the box — useful when migrating from `console.warn(err)`
+ * call sites that caught a plain `Error`.
+ *
+ * @example Err-wrapped (direct mint)
+ * log.warn(MyError.Thing({ cause }));
+ *
+ * @example Raw tagged (from result.error, after narrowing)
+ * if (isErr(result)) log.warn(result.error);
+ *
+ * @example Plain Error (migration from console.warn)
+ * try { risky(); } catch (e) { log.warn(e as Error); }
+ */
+type LoggableError = AnyTaggedError | Err<AnyTaggedError>;
+/**
+ * The logger surface.
+ *
+ * Shape split is intentional:
+ * - `warn`/`error` take a typed error **unary** — message and structured
+ *   data both live on the variant, level is chosen at the call site.
+ * - `trace`/`debug`/`info` are free-form — diagnostic events don't need
+ *   enumeration and often don't have a useful "name" to dedupe on.
+ *
+ * Mirrors Rust's `tracing::warn!(?err)` vs `tracing::info!("msg", ...)`.
+ */
+type Logger = {
+  error(err: LoggableError): void;
+  warn(err: LoggableError): void;
+  info(message: string, data?: unknown): void;
+  debug(message: string, data?: unknown): void;
+  trace(message: string, data?: unknown): void;
+};
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/logger/console-sink.d.ts
+/**
+ * Default sink. Writes to `console.*` with a `[source]` prefix.
+ *
+ * Kept as a singleton value (not a factory) because it takes no config —
+ * adding `createConsoleSink({ format })` would be ceremony for a pattern
+ * the user can trivially replace by writing their own sink.
+ *
+ * `console[event.level]` routes directly without a detached lookup table.
+ * `LogLevel` is a subset of the Console method keys, so TS errors at this
+ * access if a future level drifts (e.g. adding `fatal`). Calling the method
+ * through `console[...]` preserves the `this` binding — avoids "Illegal
+ * invocation" in runtimes that require it.
+ *
+ * `satisfies LogSink` (not `: LogSink`) keeps the inferred callable type
+ * precise — `LogSink` is an intersection with optional dispose, and the
+ * annotation form would widen an unnecessary Partial into the value type.
+ *
+ * No dispose handler — `console` is not a resource.
+ */
+declare const consoleSink: (event: LogEvent) => void;
+//# sourceMappingURL=console-sink.d.ts.map
+
+//#endregion
+//#region src/logger/create-logger.d.ts
+/**
+ * Create a logger bound to a `source` namespace and a sink.
+ *
+ * Design choices:
+ * - **Positional args, not a bag.** Two arguments, both with obvious meaning;
+ *   a `{ source, sink }` object would be ceremony.
+ * - **`sink` defaults to `consoleSink`.** Most callers during development
+ *   want console output with zero setup. Production apps swap it out via DI
+ *   at the attach/wire-up site.
+ * - **No global default logger.** There is no `setDefaultLogger()` and no
+ *   module-level registry. Every consumer takes a `log?: Logger` option
+ *   and defaults to `createLogger('<source>')` if omitted. Globals make
+ *   test isolation and sink composition painful.
+ * - **Method shorthand in the return object** over higher-order factories.
+ *   The five methods differ in two simple ways (error-unary vs free-form,
+ *   plus the level string); spelling them out beats an `emitErr("warn")`
+ *   riddle.
+ *
+ * @example Library code (caller wires the sink)
+ * function attachThing(ydoc: Doc, opts: { log?: Logger }) {
+ *   const log = opts.log ?? createLogger('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) });
+ */
+declare function createLogger(source: string, sink?: LogSink): Logger;
+//# sourceMappingURL=create-logger.d.ts.map
+//#endregion
+//#region src/logger/memory-sink.d.ts
+/**
+ * In-memory sink for tests. Returns `{ sink, events }` so callers can
+ * both wire the sink and inspect captured events without a module-level
+ * spy or `console.*` interception.
+ *
+ * A factory (not a singleton) so each test gets an isolated array; sharing
+ * state across tests would leak events.
+ *
+ * Returning `{ sink, events }` (rather than an array with a method) keeps
+ * the two roles separate — `sink` goes to `createLogger`, `events` goes to
+ * assertions.
+ *
+ * Uses `satisfies LogSink` on the sink expression rather than `: LogSink =`
+ * to preserve the precise inferred callable type.
+ *
+ * @example
+ * const { sink, events } = memorySink();
+ * const log = createLogger("test", sink);
+ * log.warn(MyError.Thing({ cause: new Error("boom") }));
+ * expect(events).toHaveLength(1);
+ * expect(events[0]).toMatchObject({ level: "warn", source: "test" });
+ */
+declare function memorySink(): {
+  sink: LogSink;
+  events: LogEvent[];
+};
+//# sourceMappingURL=memory-sink.d.ts.map
+
+//#endregion
+//#region src/logger/compose-sinks.d.ts
+/**
+ * Fan one event out to every sink in order.
+ *
+ * Disposal: the returned sink has a `[Symbol.asyncDispose]` that forwards
+ * to each member via optional chaining. Members without dispose (e.g.
+ * `consoleSink`) are silent no-ops; members that own resources (file,
+ * network) flush and close. Mix pure and stateful sinks freely — no
+ * wrapping required.
+ *
+ * Fan-out is sequential and unguarded. If a member sink throws on emit,
+ * later members do not receive the event — by design, since swallowing
+ * sink errors hides real bugs. Wrap individual sinks yourself for
+ * best-effort delivery.
+ *
+ * Dispose is sequential and awaits each member. If one throws, later
+ * members don't get their chance; callers who want best-effort cleanup
+ * should wrap the composed dispose themselves.
+ *
+ * Built with `Object.assign` + `satisfies LogSink` rather than mutating a
+ * pre-typed `const` — avoids the widening that comes with `: LogSink =` and
+ * keeps the inferred type precise (callable + definite dispose, not
+ * callable + Partial dispose).
+ *
+ * @example
+ * await using file = jsonlFileSink("/tmp/app.jsonl");
+ * const sink = composeSinks(consoleSink, file);
+ * const log = createLogger("source", sink);
+ */
+declare function composeSinks(...sinks: LogSink[]): LogSink;
+//# sourceMappingURL=compose-sinks.d.ts.map
+
+//#endregion
+export { LogEvent, LogLevel, LogSink, LoggableError, Logger, composeSinks, consoleSink, createLogger, memorySink, tapErr };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/logger/index.js

@@ -0,0 +1,173 @@
+import "../result-DzL3K2yA.js";
+import { tapErr } from "../tap-err-Bf6rQ4Cw.js";
+
+//#region src/logger/console-sink.ts
+/**
+* Default sink. Writes to `console.*` with a `[source]` prefix.
+*
+* Kept as a singleton value (not a factory) because it takes no config —
+* adding `createConsoleSink({ format })` would be ceremony for a pattern
+* the user can trivially replace by writing their own sink.
+*
+* `console[event.level]` routes directly without a detached lookup table.
+* `LogLevel` is a subset of the Console method keys, so TS errors at this
+* access if a future level drifts (e.g. adding `fatal`). Calling the method
+* through `console[...]` preserves the `this` binding — avoids "Illegal
+* invocation" in runtimes that require it.
+*
+* `satisfies LogSink` (not `: LogSink`) keeps the inferred callable type
+* precise — `LogSink` is an intersection with optional dispose, and the
+* annotation form would widen an unnecessary Partial into the value type.
+*
+* No dispose handler — `console` is not a resource.
+*/
+const consoleSink = (event) => {
+	const prefix = `[${event.source}]`;
+	if (event.data === void 0) console[event.level](prefix, event.message);
+	else console[event.level](prefix, event.message, event.data);
+};
+
+//#endregion
+//#region src/logger/create-logger.ts
+/** Narrow `LoggableError` to the raw tagged object. See `LoggableError` in `types.ts` for the discriminator rationale. */
+function unwrapLoggable(err) {
+	return "name" in err ? err : err.error;
+}
+/**
+* Create a logger bound to a `source` namespace and a sink.
+*
+* Design choices:
+* - **Positional args, not a bag.** Two arguments, both with obvious meaning;
+*   a `{ source, sink }` object would be ceremony.
+* - **`sink` defaults to `consoleSink`.** Most callers during development
+*   want console output with zero setup. Production apps swap it out via DI
+*   at the attach/wire-up site.
+* - **No global default logger.** There is no `setDefaultLogger()` and no
+*   module-level registry. Every consumer takes a `log?: Logger` option
+*   and defaults to `createLogger('<source>')` if omitted. Globals make
+*   test isolation and sink composition painful.
+* - **Method shorthand in the return object** over higher-order factories.
+*   The five methods differ in two simple ways (error-unary vs free-form,
+*   plus the level string); spelling them out beats an `emitErr("warn")`
+*   riddle.
+*
+* @example Library code (caller wires the sink)
+* function attachThing(ydoc: Doc, opts: { log?: Logger }) {
+*   const log = opts.log ?? createLogger('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) });
+*/
+function createLogger(source, sink = consoleSink) {
+	const emit = (level, message, data) => {
+		sink({
+			ts: Date.now(),
+			level,
+			source,
+			message,
+			data
+		});
+	};
+	return {
+		error(err) {
+			const tagged = unwrapLoggable(err);
+			emit("error", tagged.message, tagged);
+		},
+		warn(err) {
+			const tagged = unwrapLoggable(err);
+			emit("warn", tagged.message, tagged);
+		},
+		info(message, data) {
+			emit("info", message, data);
+		},
+		debug(message, data) {
+			emit("debug", message, data);
+		},
+		trace(message, data) {
+			emit("trace", message, data);
+		}
+	};
+}
+
+//#endregion
+//#region src/logger/memory-sink.ts
+/**
+* In-memory sink for tests. Returns `{ sink, events }` so callers can
+* both wire the sink and inspect captured events without a module-level
+* spy or `console.*` interception.
+*
+* A factory (not a singleton) so each test gets an isolated array; sharing
+* state across tests would leak events.
+*
+* Returning `{ sink, events }` (rather than an array with a method) keeps
+* the two roles separate — `sink` goes to `createLogger`, `events` goes to
+* assertions.
+*
+* Uses `satisfies LogSink` on the sink expression rather than `: LogSink =`
+* to preserve the precise inferred callable type.
+*
+* @example
+* const { sink, events } = memorySink();
+* const log = createLogger("test", sink);
+* log.warn(MyError.Thing({ cause: new Error("boom") }));
+* expect(events).toHaveLength(1);
+* expect(events[0]).toMatchObject({ level: "warn", source: "test" });
+*/
+function memorySink() {
+	const events = [];
+	const sink = (event) => {
+		events.push(event);
+	};
+	return {
+		sink,
+		events
+	};
+}
+
+//#endregion
+//#region src/logger/compose-sinks.ts
+/**
+* Fan one event out to every sink in order.
+*
+* Disposal: the returned sink has a `[Symbol.asyncDispose]` that forwards
+* to each member via optional chaining. Members without dispose (e.g.
+* `consoleSink`) are silent no-ops; members that own resources (file,
+* network) flush and close. Mix pure and stateful sinks freely — no
+* wrapping required.
+*
+* Fan-out is sequential and unguarded. If a member sink throws on emit,
+* later members do not receive the event — by design, since swallowing
+* sink errors hides real bugs. Wrap individual sinks yourself for
+* best-effort delivery.
+*
+* Dispose is sequential and awaits each member. If one throws, later
+* members don't get their chance; callers who want best-effort cleanup
+* should wrap the composed dispose themselves.
+*
+* Built with `Object.assign` + `satisfies LogSink` rather than mutating a
+* pre-typed `const` — avoids the widening that comes with `: LogSink =` and
+* keeps the inferred type precise (callable + definite dispose, not
+* callable + Partial dispose).
+*
+* @example
+* await using file = jsonlFileSink("/tmp/app.jsonl");
+* const sink = composeSinks(consoleSink, file);
+* const log = createLogger("source", sink);
+*/
+function composeSinks(...sinks) {
+	const emit = (event) => {
+		for (const sink of sinks) sink(event);
+	};
+	const dispose = async () => {
+		for (const sink of sinks) await sink[Symbol.asyncDispose]?.();
+	};
+	return Object.assign(emit, { [Symbol.asyncDispose]: dispose });
+}
+
+//#endregion
+export { composeSinks, consoleSink, createLogger, memorySink, tapErr };
+//# sourceMappingURL=index.js.map

package/dist/logger/index.js.map

@@ -0,0 +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"}

package/dist/query/index.d.ts

@@ -1,5 +1,6 @@
-import { Result } from "../result-BgPMmUXd.js";
-import "../index-8WW9UMob.js";
+import { Result } from "../result-BongGO2O.js";
+import "../tap-err-Bqs9aQpZ.js";
+import "../index-mb9iYu0a.js";
 import { DefaultError, MutationFunction, MutationKey, MutationOptions, QueryClient, QueryFunction, QueryKey, QueryObserverOptions } from "@tanstack/query-core";
 
 //#region src/query/utils.d.ts

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/query/utils.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAUmE;;;;;;;;;KAc9D,gBAOuC,CAAA,eAAA,OAAA,EAAA,SALlC,YAKkC,EAAA,QAJnC,YAImC,EAAA,aAH9B,YAG8B,EAAA,kBAFzB,QAEyB,GAFd,QAEc,CAAA,GADxC,IACwC,CAA3C,oBAA2C,CAAtB,YAAsB,EAAR,MAAQ,EAAA,KAAA,EAAO,UAAP,EAAmB,SAAnB,CAAA,EAAA,SAAA,CAAA,GAAA;EAAK,QAAE,EAGxC,SAHwC;EAAU,OAAE,EAIrD,aAJqD,CAIvC,MAJuC,CAIhC,YAJgC,EAIlB,MAJkB,CAAA,EAIT,SAJS,CAAA;CAAS;;;;;;;;AAIjD;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAmDD,KAfjB,iBAeiB,CAAA,eAAA,OAAA,EAAA,SAbZ,YAaY,EAAA,QAZb,YAYa,EAAA,aAXR,YAWQ,EAAA,kBAVH,QAUG,GAVQ,QAUR,CAAA,GAAA,CAAA,GAAA,GATX,OASW,CATH,MASG,CATI,UASJ,EATgB,MAShB,CAAA,CAAA,CAAA,GAAA;EAejB,OAAA,EAvBK,oBAuBc,CAtBtB,YAsBsB,EArBtB,MAqBsB,EApBtB,KAoBsB,EAnBtB,UAmBsB,EAlBtB,SAkBsB,CAAA;EAAA,KAAA,EAAA,GAAA,GAhBV,OAgBU,CAhBF,MAgBE,CAhBK,UAgBL,EAhBiB,MAgBjB,CAAA,CAAA;EAAA,MAKC,EAAA,GAAA,GApBV,OAoBU,CApBF,MAoBE,CApBK,UAoBL,EApBiB,MAoBjB,CAAA,CAAA;CAAK;;;;;;;;;;;AAED;AAAA;KAPxB,mBAyCoB,CAAA,KAAA,EAAA,MAAA,EAAA,aAAA,IAAA,EAAA,WAAA,OAAA,CAAA,GApCrB,IAoCqB,CApChB,eAoCgB,CApCA,KAoCA,EApCO,MAoCP,EApCe,UAoCf,EApC2B,QAoC3B,CAAA,EAAA,YAAA,CAAA,GAAA;EAAA,WAKR,EAxCH,WAwCG;EAAU,UAAoB,EAvClC,gBAuCkC,CAvCjB,MAuCiB,CAvCV,KAuCU,EAvCH,MAuCG,CAAA,EAvCM,UAuCN,CAAA;CAAK;;;;;;;;;;;;;AAER;AA6C5C;;;;;;;;;;;;;;;;;;KApDK,oBAmID,CAAA,KAAA,EAAA,MAAA,EAAA,aAAA,IAAA,EAAA,WAAA,OAAA,CAAA,GAAA,CAAA,CAAA,SAAA,EA9Ha,UA8Hb,EAAA,GA9H4B,OA8H5B,CA9HoC,MA8HpC,CA9H2C,KA8H3C,EA9HkD,MA8HlD,CAAA,CAAA,CAAA,GAAA;EAAiB,OA8LU,EA3TrB,eA2TqB,CA3TL,KA2TK,EA3TE,MA2TF,EA3TU,UA2TV,EA3TsB,QA2TtB,CAAA;EAAK,OAAE,EAAA,CAAA,SAAA,EA1ThB,UA0TgB,EAAA,GA1TD,OA0TC,CA1TO,MA0TP,CA1Tc,KA0Td,EA1TqB,MA0TrB,CAAA,CAAA;CAAM;;;;;;;;AACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA9QR,oBAAA,cAAkC;iDAmE1C,eACD,2BACK,gCACQ,wCAET,iBACR,cACA,QACA,OACA,YACA,eAEC,kBAAkB,cAAc,QAAQ,OAAO,YAAY;kFA8LpD,oBAAoB,OAAO,QAAQ,YAAY,cACtD,qBAAqB,OAAO,QAAQ,YAAY"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/query/utils.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAUmE;;;;;;;;KAc9D,gBAO+B,CAAA,eAAA,OAAA,EAAA,SAL1B,YAK0B,EAAA,QAJ3B,YAI2B,EAAA,aAHtB,YAGsB,EAAA,kBAFjB,QAEiB,GAFN,QAEM,CAAA,GADhC,IACgC,CAAnC,oBAAmC,CAAd,YAAc,EAAA,MAAA,EAAQ,KAAR,EAAe,UAAf,EAA2B,SAA3B,CAAA,EAAA,SAAA,CAAA,GAAA;EAAM,QAAE,EAGjC,SAHiC;EAAK,OAAE,EAIzC,aAJyC,CAI3B,MAJ2B,CAIpB,YAJoB,EAIN,MAJM,CAAA,EAIG,SAJH,CAAA;CAAU;;;;;;;;;AAItC;AAAA;;;;;;;;;;;;;;;;;;;;;;;;KAoClB,iBAeU,CAAA,eAAA,OAAA,EAAA,SAbL,YAaK,EAAA,QAZN,YAYM,EAAA,aAXD,YAWC,EAAA,kBAVI,QAUJ,GAVe,QAUf,CAAA,GAAA,CAAA,GAAA,GATJ,OASI,CATI,MASJ,CATW,UASX,EATuB,MASvB,CAAA,CAAA,CAAA,GAAA;EAAO,OAAA,EARZ,oBAQY,CAPpB,YAOoB,EANpB,MAMoB,EALpB,KAKoB,EAJpB,UAIoB,EAHpB,SAGoB,CAAA;EAejB,KAAA,EAAA,GAAA,GAhBS,OAgBT,CAhBiB,MAgBE,CAhBK,UAgBL,EAhBiB,MAgBjB,CAAA,CAAA;EAAA,MAAA,EAAA,GAAA,GAfT,OAeS,CAfD,MAeC,CAfM,UAeN,EAfkB,MAelB,CAAA,CAAA;CAAA;;;;;;;;;;;;AAOK;AAAA,KAPxB,mBAyCA,CAAA,KAAoB,EAAA,MAAA,EAAA,aAAA,IAAA,EAAA,WAAA,OAAA,CAAA,GApCrB,IAoCqB,CApChB,eAoCgB,CApCA,KAoCA,EApCO,MAoCP,EApCe,UAoCf,EApC2B,QAoC3B,CAAA,EAAA,YAAA,CAAA,GAAA;EAAA,WAAA,EAnCX,WAmCW;EAAA,UAKR,EAvCJ,gBAuCI,CAvCa,MAuCb,CAvCoB,KAuCpB,EAvC2B,MAuC3B,CAAA,EAvCoC,UAuCpC,CAAA;CAAU;;;;;;;;;;;;;;AAEiB;AA6C5C;;;;;;;;;;;;;;;;;KApDK,oBAmI0D,CAAA,KAAA,EAAA,MAAA,EAAA,aAAA,IAAA,EAAA,WAAA,OAAA,CAAA,GAAA,CAAA,CAAA,SAAA,EA9H9C,UA8H8C,EAAA,GA9H/B,OA8H+B,CA9HvB,MA8HuB,CA9HhB,KA8HgB,EA9HT,MA8HS,CAAA,CAAA,CAAA,GAAA;EAAS,OAApE,EA7HM,eA6HN,CA7HsB,KA6HtB,EA7H6B,MA6H7B,EA7HqC,UA6HrC,EA7HiD,QA6HjD,CAAA;EAAiB,OA8LU,EAAA,CAAA,SAAA,EA1TT,UA0TS,EAAA,GA1TM,OA0TN,CA1Tc,MA0Td,CA1TqB,KA0TrB,EA1T4B,MA0T5B,CAAA,CAAA;CAAK;;;;;;;;;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA9QR,oBAAA,cAAkC;iDAmE1C,eACD,2BACK,gCACQ,wCAET,iBACR,cACA,QACA,OACA,YACA,eAEC,kBAAkB,cAAc,QAAQ,OAAO,YAAY;kFA8LpD,oBAAoB,OAAO,QAAQ,YAAY,cACtD,qBAAqB,OAAO,QAAQ,YAAY"}

package/dist/query/index.js

@@ -1,5 +1,6 @@
-import { Err, Ok, resolve } from "../result-DnOm5ds5.js";
-import "../result-0QjbC3Hw.js";
+import { Err, Ok, resolve } from "../result-DzL3K2yA.js";
+import "../tap-err-Bf6rQ4Cw.js";
+import "../result-corfYKOe.js";
 
 //#region src/query/utils.ts
 /**