wellcrafted 0.34.1 → 0.36.0

package/dist/logger/index.d.ts

@@ -0,0 +1,228 @@
+import { Err } from "../result-DKwq9BCr.js";
+import { AnyTaggedError } from "../types-tXXk7K9Q.js";
+import { tapErr } from "../tap-err-CFhHBPfH.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-C5cJ1_WU.js";
+import { tapErr } from "../tap-err-CP-re1HT.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-xH3TbSDF.js";
-import "../index-D_iQ3bBj.js";
+import { Result } from "../result-DKwq9BCr.js";
+import "../tap-err-CFhHBPfH.js";
+import "../index-DnoV2ZDO.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-BRfWC87j.js";
-import "../result-Cd0chHlN.js";
+import { Err, Ok, resolve } from "../result-C5cJ1_WU.js";
+import "../tap-err-CP-re1HT.js";
+import "../result-C9V2Knvt.js";
 
 //#region src/query/utils.ts
 /**

package/dist/query/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["queryClient: QueryClient","options: DefineQueryInput<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>","options: DefineMutationInput<TData, TError, TVariables, TContext>","variables: TVariables","options: MutationOptions<TData, TError, TVariables, TContext>"],"sources":["../../src/query/utils.ts"],"sourcesContent":["import type {\n\tDefaultError,\n\tMutationFunction,\n\tMutationKey,\n\tMutationOptions,\n\tQueryClient,\n\tQueryFunction,\n\tQueryKey,\n\tQueryObserverOptions,\n} from \"@tanstack/query-core\";\nimport { Err, Ok, type Result, resolve } from \"../result/index.js\";\n\n/**\n * Input options for defining a query.\n *\n * Extends TanStack Query's QueryObserverOptions but expects queryFn to return a Result type.\n * This type represents the configuration for creating a query definition with both\n * reactive and imperative interfaces for data fetching.\n *\n * @template TQueryFnData - The type of data returned by the query function\n * @template TError - The type of error that can be thrown\n * @template TData - The type of data returned by the query (after select transform)\n * @template TQueryKey - The type of the query key\n */\ntype DefineQueryInput<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = Omit<\n\tQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,\n\t\"queryFn\"\n> & {\n\tqueryKey: TQueryKey;\n\tqueryFn: QueryFunction<Result<TQueryFnData, TError>, TQueryKey>;\n};\n\n/**\n * Output of defineQuery function.\n *\n * The query definition is directly callable and defaults to `ensure()` behavior,\n * which is recommended for most imperative use cases like preloaders.\n *\n * Provides both reactive and imperative interfaces for data fetching:\n * - `()` (callable): Same as `ensure()` - returns cached data if available, fetches if not\n * - `options`: Returns config for use with useQuery() or createQuery()\n * - `fetch()`: Always attempts to fetch data (from cache if fresh, network if stale)\n * - `ensure()`: Guarantees data availability, preferring cached data (recommended for preloaders)\n *\n * @template TQueryFnData - The type of data returned by the query function\n * @template TError - The type of error that can be thrown\n * @template TData - The type of data returned by the query (after select transform)\n * @template TQueryKey - The type of the query key\n *\n * @example\n * ```typescript\n * const userQuery = defineQuery({...});\n *\n * // Directly callable (same as .ensure())\n * const { data, error } = await userQuery();\n *\n * // Or use explicit methods\n * const { data, error } = await userQuery.ensure();\n * const { data, error } = await userQuery.fetch();\n *\n * // For reactive usage (Svelte 5 requires accessor wrapper)\n * const query = createQuery(() => userQuery.options); // Svelte 5\n * const query = useQuery(userQuery.options); // React\n * ```\n */\ntype DefineQueryOutput<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = (() => Promise<Result<TQueryData, TError>>) & {\n\toptions: QueryObserverOptions<\n\t\tTQueryFnData,\n\t\tTError,\n\t\tTData,\n\t\tTQueryData,\n\t\tTQueryKey\n\t>;\n\tfetch: () => Promise<Result<TQueryData, TError>>;\n\tensure: () => Promise<Result<TQueryData, TError>>;\n};\n\n/**\n * Input options for defining a mutation.\n *\n * Extends TanStack Query's MutationOptions but expects mutationFn to return a Result type.\n * This type represents the configuration for creating a mutation definition with both\n * reactive and imperative interfaces for data mutations.\n *\n * @template TData - The type of data returned by the mutation\n * @template TError - The type of error that can be thrown\n * @template TVariables - The type of variables passed to the mutation\n * @template TContext - The type of context data for optimistic updates\n */\ntype DefineMutationInput<\n\tTData,\n\tTError,\n\tTVariables = void,\n\tTContext = unknown,\n> = Omit<MutationOptions<TData, TError, TVariables, TContext>, \"mutationFn\"> & {\n\tmutationKey: MutationKey;\n\tmutationFn: MutationFunction<Result<TData, TError>, TVariables>;\n};\n\n/**\n * Output of defineMutation function.\n *\n * The mutation definition is directly callable, which executes the mutation\n * and returns a Result. This is equivalent to calling `.execute()`.\n *\n * Provides both reactive and imperative interfaces for data mutations:\n * - `(variables)` (callable): Same as `execute()` - directly executes the mutation\n * - `options`: Returns config for use with useMutation() or createMutation()\n * - `execute(variables)`: Directly executes the mutation and returns a Result\n *\n * @template TData - The type of data returned by the mutation\n * @template TError - The type of error that can be thrown\n * @template TVariables - The type of variables passed to the mutation\n * @template TContext - The type of context data for optimistic updates\n *\n * @example\n * ```typescript\n * const createUser = defineMutation({...});\n *\n * // Directly callable (same as .execute())\n * const { data, error } = await createUser({ name: 'John' });\n *\n * // Or use explicit method\n * const { data, error } = await createUser.execute({ name: 'John' });\n *\n * // For reactive usage (Svelte 5 requires accessor wrapper)\n * const mutation = createMutation(() => createUser.options); // Svelte 5\n * const mutation = useMutation(createUser.options); // React\n * ```\n */\ntype DefineMutationOutput<\n\tTData,\n\tTError,\n\tTVariables = void,\n\tTContext = unknown,\n> = ((variables: TVariables) => Promise<Result<TData, TError>>) & {\n\toptions: MutationOptions<TData, TError, TVariables, TContext>;\n\texecute: (variables: TVariables) => Promise<Result<TData, TError>>;\n};\n\n/**\n * Creates factory functions for defining queries and mutations bound to a specific QueryClient.\n *\n * This factory pattern allows you to create isolated query/mutation definitions that are\n * bound to a specific QueryClient instance, enabling:\n * - Multiple query clients in the same application\n * - Testing with isolated query clients\n * - Framework-agnostic query definitions\n * - Proper separation of concerns between query logic and client instances\n *\n * The returned functions handle Result types automatically, unwrapping them for TanStack Query\n * while maintaining type safety throughout your application.\n *\n * @param queryClient - The QueryClient instance to bind the factories to\n * @returns An object containing defineQuery and defineMutation functions bound to the provided client\n *\n * @example\n * ```typescript\n * // Create your query client\n * const queryClient = new QueryClient({\n *   defaultOptions: {\n *     queries: { staleTime: 5 * 60 * 1000 }\n *   }\n * });\n *\n * // Create the factory functions\n * const { defineQuery, defineMutation } = createQueryFactories(queryClient);\n *\n * // Now use defineQuery and defineMutation as before\n * const userQuery = defineQuery({\n *   queryKey: ['user', userId],\n *   queryFn: () => services.getUser(userId)\n * });\n *\n * // Use in components (Svelte 5 requires accessor wrapper)\n * const query = createQuery(() => userQuery.options); // Svelte 5\n * const query = useQuery(userQuery.options); // React\n *\n * // Or imperatively\n * const { data, error } = await userQuery.fetch();\n * ```\n */\nexport function createQueryFactories(queryClient: QueryClient) {\n\t/**\n\t * Creates a query definition that bridges the gap between pure service functions and reactive UI components.\n\t *\n\t * This factory function is the cornerstone of our data fetching architecture. It wraps service calls\n\t * with TanStack Query superpowers while maintaining type safety through Result types.\n\t *\n\t * The returned query definition is **directly callable** and defaults to `ensure()` behavior,\n\t * which is recommended for most imperative use cases like preloaders.\n\t *\n\t * ## Why use defineQuery?\n\t *\n\t * 1. **Callable**: Call directly like `userQuery()` for imperative data fetching\n\t * 2. **Dual Interface**: Also provides reactive (`.options`) and explicit imperative (`.fetch()`, `.ensure()`) APIs\n\t * 3. **Automatic Error Handling**: Service functions return `Result<T, E>` types which are automatically\n\t *    unwrapped by TanStack Query, giving you proper error states in your components\n\t * 4. **Type Safety**: Full TypeScript support with proper inference for data and error types\n\t * 5. **Consistency**: Every query in the app follows the same pattern, making it easy to understand\n\t *\n\t * @template TQueryFnData - The type of data returned by the query function\n\t * @template TError - The type of error that can be thrown\n\t * @template TData - The type of data returned by the query (after select transform)\n\t * @template TQueryKey - The type of the query key\n\t *\n\t * @param options - Query configuration object\n\t * @param options.queryKey - Unique key for this query (used for caching and refetching)\n\t * @param options.queryFn - Function that fetches data and returns a Result type\n\t * @param options.* - Any other TanStack Query options (staleTime, refetchInterval, etc.)\n\t *\n\t * @returns Callable query definition with:\n\t *   - `()` (callable): Same as `ensure()` - returns cached data if available, fetches if not\n\t *   - `.options`: Config for use with useQuery() or createQuery()\n\t *   - `.fetch()`: Always attempts to fetch (from cache if fresh, network if stale)\n\t *   - `.ensure()`: Guarantees data availability, preferring cached data (recommended for preloaders)\n\t *\n\t * @example\n\t * ```typescript\n\t * // Step 1: Define your query in the query layer\n\t * const userQuery = defineQuery({\n\t *   queryKey: ['users', userId],\n\t *   queryFn: () => services.getUser(userId), // Returns Result<User, ApiError>\n\t *   staleTime: 5 * 60 * 1000, // Consider data fresh for 5 minutes\n\t * });\n\t *\n\t * // Step 2a: Use reactively in a Svelte 5 component (accessor wrapper required)\n\t * const query = createQuery(() => userQuery.options);\n\t * // query.data is User | undefined\n\t * // query.error is ApiError | null\n\t *\n\t * // Step 2b: Call directly in preloaders (recommended)\n\t * export const load = async () => {\n\t *   const { data, error } = await userQuery(); // Same as userQuery.ensure()\n\t *   if (error) throw error;\n\t *   return { user: data };\n\t * };\n\t *\n\t * // Step 2c: Use explicit methods when needed\n\t * async function refreshUser() {\n\t *   const { data, error } = await userQuery.fetch(); // Force fresh fetch\n\t *   if (error) {\n\t *     console.error('Failed to fetch user:', error);\n\t *   }\n\t * }\n\t * ```\n\t */\n\tconst defineQuery = <\n\t\tTQueryFnData = unknown,\n\t\tTError = DefaultError,\n\t\tTData = TQueryFnData,\n\t\tTQueryData = TQueryFnData,\n\t\tTQueryKey extends QueryKey = QueryKey,\n\t>(\n\t\toptions: DefineQueryInput<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>,\n\t): DefineQueryOutput<TQueryFnData, TError, TData, TQueryData, TQueryKey> => {\n\t\tconst newOptions = {\n\t\t\t...options,\n\t\t\tqueryFn: async (context) => {\n\t\t\t\tlet result = options.queryFn(context);\n\t\t\t\tif (result instanceof Promise) result = await result;\n\t\t\t\treturn resolve(result);\n\t\t\t},\n\t\t} satisfies QueryObserverOptions<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>;\n\n\t\t/**\n\t\t * Fetches data for this query using queryClient.fetchQuery().\n\t\t *\n\t\t * This method ALWAYS evaluates freshness and will refetch if data is stale.\n\t\t * It wraps TanStack Query's fetchQuery method, which returns cached data if fresh\n\t\t * or makes a network request if the data is stale or missing.\n\t\t *\n\t\t * **When to use fetch():**\n\t\t * - When you explicitly want to check data freshness\n\t\t * - For user-triggered refresh actions\n\t\t * - When you need the most up-to-date data\n\t\t *\n\t\t * **For preloaders, use ensure() instead** - it's more efficient for initial data loading.\n\t\t *\n\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t *\n\t\t * @example\n\t\t * // Good for user-triggered refresh\n\t\t * const { data, error } = await userQuery.fetch();\n\t\t * if (error) {\n\t\t *   console.error('Failed to load user:', error);\n\t\t * }\n\t\t */\n\t\tasync function fetch(): Promise<Result<TQueryData, TError>> {\n\t\t\ttry {\n\t\t\t\treturn Ok(\n\t\t\t\t\tawait queryClient.fetchQuery<\n\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\tTError,\n\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t>({\n\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\tqueryFn: newOptions.queryFn,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\t/**\n\t\t * Ensures data is available for this query using queryClient.ensureQueryData().\n\t\t *\n\t\t * This method PRIORITIZES cached data and only calls fetchQuery internally if no cached\n\t\t * data exists. It wraps TanStack Query's ensureQueryData method, which is perfect for\n\t\t * guaranteeing data availability with minimal network requests.\n\t\t *\n\t\t * **This is the RECOMMENDED method for preloaders** because:\n\t\t * - It returns cached data immediately if available\n\t\t * - It updates the query client cache properly\n\t\t * - It minimizes network requests during navigation\n\t\t * - It ensures components have data ready when they mount\n\t\t *\n\t\t * **When to use ensure():**\n\t\t * - Route preloaders and data loading functions\n\t\t * - Initial component data requirements\n\t\t * - When cached data is acceptable for immediate display\n\t\t *\n\t\t * This is also the default behavior when calling the query directly.\n\t\t *\n\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t *\n\t\t * @example\n\t\t * // Perfect for preloaders\n\t\t * export const load = async () => {\n\t\t *   const { data, error } = await userQuery.ensure();\n\t\t *   // Or simply: await userQuery();\n\t\t *   if (error) {\n\t\t *     throw error;\n\t\t *   }\n\t\t *   return { user: data };\n\t\t * };\n\t\t */\n\t\tasync function ensure(): Promise<Result<TQueryData, TError>> {\n\t\t\ttry {\n\t\t\t\treturn Ok(\n\t\t\t\t\tawait queryClient.ensureQueryData<\n\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\tTError,\n\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t>({\n\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\tqueryFn: newOptions.queryFn,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\t// Create a callable function that defaults to ensure() behavior\n\t\t// and attach options, fetch, and ensure as properties\n\t\treturn Object.assign(ensure, {\n\t\t\toptions: newOptions,\n\t\t\tfetch,\n\t\t\tensure,\n\t\t});\n\t};\n\n\t/**\n\t * Creates a mutation definition for operations that modify data (create, update, delete).\n\t *\n\t * This factory function is the mutation counterpart to defineQuery. It provides a clean way to\n\t * wrap service functions that perform side effects, while maintaining the same dual interface\n\t * pattern for maximum flexibility.\n\t *\n\t * The returned mutation definition is **directly callable**, which executes the mutation\n\t * and returns a Result. This is equivalent to calling `.execute()`.\n\t *\n\t * ## Why use defineMutation?\n\t *\n\t * 1. **Callable**: Call directly like `createUser({ name: 'John' })` for imperative execution\n\t * 2. **Dual Interface**: Also provides reactive (`.options`) and explicit imperative (`.execute()`) APIs\n\t * 3. **Consistent Error Handling**: Service functions return `Result<T, E>` types, ensuring\n\t *    errors are handled consistently throughout the app\n\t * 4. **Cache Management**: Mutations often update the cache after success (see examples)\n\t *\n\t * @template TData - The type of data returned by the mutation\n\t * @template TError - The type of error that can be thrown\n\t * @template TVariables - The type of variables passed to the mutation\n\t * @template TContext - The type of context data for optimistic updates\n\t *\n\t * @param options - Mutation configuration object\n\t * @param options.mutationKey - Unique key for this mutation (used for tracking in-flight state)\n\t * @param options.mutationFn - Function that performs the mutation and returns a Result type\n\t * @param options.* - Any other TanStack Mutation options (onSuccess, onError, etc.)\n\t *\n\t * @returns Callable mutation definition with:\n\t *   - `(variables)` (callable): Same as `execute()` - directly executes the mutation\n\t *   - `.options`: Config for use with useMutation() or createMutation()\n\t *   - `.execute(variables)`: Directly executes the mutation and returns a Result\n\t *\n\t * @example\n\t * ```typescript\n\t * // Step 1: Define your mutation with cache updates\n\t * const createRecording = defineMutation({\n\t *   mutationKey: ['recordings', 'create'],\n\t *   mutationFn: async (recording: Recording) => {\n\t *     // Call the service\n\t *     const result = await services.db.createRecording(recording);\n\t *     if (result.error) return Err(result.error);\n\t *\n\t *     // Update cache on success\n\t *     queryClient.setQueryData(['recordings'], (old) =>\n\t *       [...(old || []), recording]\n\t *     );\n\t *\n\t *     return Ok(result.data);\n\t *   }\n\t * });\n\t *\n\t * // Step 2a: Use reactively in a Svelte 5 component (accessor wrapper required)\n\t * const mutation = createMutation(() => createRecording.options);\n\t * // Call with: mutation.mutate(recordingData)\n\t *\n\t * // Step 2b: Call directly in an action (recommended)\n\t * async function saveRecording(data: Recording) {\n\t *   const { error } = await createRecording(data); // Same as createRecording.execute(data)\n\t *   if (error) {\n\t *     notify.error({ title: 'Failed to save', description: error.message });\n\t *   } else {\n\t *     notify.success({ title: 'Recording saved!' });\n\t *   }\n\t * }\n\t * ```\n\t *\n\t * @tip Calling directly is especially useful for:\n\t * - Event handlers that need to await the result\n\t * - Sequential operations that depend on each other\n\t * - Non-component code that needs to trigger mutations\n\t */\n\tconst defineMutation = <TData, TError, TVariables = void, TContext = unknown>(\n\t\toptions: DefineMutationInput<TData, TError, TVariables, TContext>,\n\t): DefineMutationOutput<TData, TError, TVariables, TContext> => {\n\t\tconst newOptions = {\n\t\t\t...options,\n\t\t\tmutationFn: async (variables: TVariables) => {\n\t\t\t\treturn resolve(await options.mutationFn(variables));\n\t\t\t},\n\t\t} satisfies MutationOptions<TData, TError, TVariables, TContext>;\n\n\t\t/**\n\t\t * Executes the mutation imperatively and returns a Result.\n\t\t *\n\t\t * This is the recommended way to trigger mutations from:\n\t\t * - Button click handlers\n\t\t * - Form submissions\n\t\t * - Keyboard shortcuts\n\t\t * - Any non-component code\n\t\t *\n\t\t * The method automatically wraps the result in a Result type, so you always\n\t\t * get back `{ data, error }` for consistent error handling.\n\t\t *\n\t\t * This is also the default behavior when calling the mutation directly.\n\t\t *\n\t\t * @param variables - The variables to pass to the mutation function\n\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t *\n\t\t * @example\n\t\t * // In an event handler\n\t\t * async function handleSubmit(formData: FormData) {\n\t\t *   const { data, error } = await createUser.execute(formData);\n\t\t *   // Or simply: await createUser(formData);\n\t\t *   if (error) {\n\t\t *     notify.error({ title: 'Failed to create user', description: error.message });\n\t\t *     return;\n\t\t *   }\n\t\t *   goto(`/users/${data.id}`);\n\t\t * }\n\t\t */\n\t\tasync function execute(variables: TVariables) {\n\t\t\ttry {\n\t\t\t\treturn Ok(await runMutation(queryClient, newOptions, variables));\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\t// Create a callable function that executes the mutation\n\t\t// and attach options and execute as properties\n\t\treturn Object.assign(execute, {\n\t\t\toptions: newOptions,\n\t\t\texecute,\n\t\t});\n\t};\n\n\treturn {\n\t\tdefineQuery,\n\t\tdefineMutation,\n\t};\n}\n\n/**\n * Internal helper that executes a mutation directly using the query client's mutation cache.\n *\n * This is what powers the callable behavior and `.execute()` method on mutations.\n * It bypasses the reactive mutation hooks and runs the mutation imperatively,\n * which is perfect for event handlers and other imperative code.\n *\n * @internal\n * @template TData - The type of data returned by the mutation\n * @template TError - The type of error that can be thrown\n * @template TVariables - The type of variables passed to the mutation\n * @template TContext - The type of context data\n * @param queryClient - The query client instance to use\n * @param options - The mutation options including mutationFn and mutationKey\n * @param variables - The variables to pass to the mutation function\n * @returns Promise that resolves with the mutation result\n */\nfunction runMutation<TData, TError, TVariables, TContext>(\n\tqueryClient: QueryClient,\n\toptions: MutationOptions<TData, TError, TVariables, TContext>,\n\tvariables: TVariables,\n) {\n\tconst mutation = queryClient.getMutationCache().build(queryClient, options);\n\treturn mutation.execute(variables);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkMA,SAAgB,qBAAqBA,aAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiE9D,MAAM,cAAc,CAOnBC,YAO2E;EAC3E,MAAM,aAAa;GAClB,GAAG;GACH,SAAS,OAAO,YAAY;IAC3B,IAAI,SAAS,QAAQ,QAAQ,QAAQ;AACrC,QAAI,kBAAkB,QAAS,UAAS,MAAM;AAC9C,WAAO,QAAQ,OAAO;GACtB;EACD;;;;;;;;;;;;;;;;;;;;;;;;EA+BD,eAAe,QAA6C;AAC3D,OAAI;AACH,WAAO,GACN,MAAM,YAAY,WAKhB;KACD,UAAU,WAAW;KACrB,SAAS,WAAW;IACpB,EAAC,CACF;GACD,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCD,eAAe,SAA8C;AAC5D,OAAI;AACH,WAAO,GACN,MAAM,YAAY,gBAKhB;KACD,UAAU,WAAW;KACrB,SAAS,WAAW;IACpB,EAAC,CACF;GACD,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;AAID,SAAO,OAAO,OAAO,QAAQ;GAC5B,SAAS;GACT;GACA;EACA,EAAC;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0ED,MAAM,iBAAiB,CACtBC,YAC+D;EAC/D,MAAM,aAAa;GAClB,GAAG;GACH,YAAY,OAAOC,cAA0B;AAC5C,WAAO,QAAQ,MAAM,QAAQ,WAAW,UAAU,CAAC;GACnD;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BD,eAAe,QAAQA,WAAuB;AAC7C,OAAI;AACH,WAAO,GAAG,MAAM,YAAY,aAAa,YAAY,UAAU,CAAC;GAChE,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;AAID,SAAO,OAAO,OAAO,SAAS;GAC7B,SAAS;GACT;EACA,EAAC;CACF;AAED,QAAO;EACN;EACA;CACA;AACD;;;;;;;;;;;;;;;;;;AAmBD,SAAS,YACRH,aACAI,SACAD,WACC;CACD,MAAM,WAAW,YAAY,kBAAkB,CAAC,MAAM,aAAa,QAAQ;AAC3E,QAAO,SAAS,QAAQ,UAAU;AAClC"}
+{"version":3,"file":"index.js","names":["queryClient: QueryClient","options: DefineQueryInput<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>","options: DefineMutationInput<TData, TError, TVariables, TContext>","variables: TVariables","options: MutationOptions<TData, TError, TVariables, TContext>"],"sources":["../../src/query/utils.ts"],"sourcesContent":["import type {\n\tDefaultError,\n\tMutationFunction,\n\tMutationKey,\n\tMutationOptions,\n\tQueryClient,\n\tQueryFunction,\n\tQueryKey,\n\tQueryObserverOptions,\n} from \"@tanstack/query-core\";\nimport { Err, Ok, type Result, resolve } from \"../result/index.js\";\n\n/**\n * Input options for defining a query.\n *\n * Extends TanStack Query's QueryObserverOptions but expects queryFn to return a Result type.\n * This type represents the configuration for creating a query definition with both\n * reactive and imperative interfaces for data fetching.\n *\n * @template TQueryFnData - The type of data returned by the query function\n * @template TError - The type of error that can be thrown\n * @template TData - The type of data returned by the query (after select transform)\n * @template TQueryKey - The type of the query key\n */\ntype DefineQueryInput<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = Omit<\n\tQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,\n\t\"queryFn\"\n> & {\n\tqueryKey: TQueryKey;\n\tqueryFn: QueryFunction<Result<TQueryFnData, TError>, TQueryKey>;\n};\n\n/**\n * Output of defineQuery function.\n *\n * The query definition is directly callable and defaults to `ensure()` behavior,\n * which is recommended for most imperative use cases like preloaders.\n *\n * Provides both reactive and imperative interfaces for data fetching:\n * - `()` (callable): Same as `ensure()` - returns cached data if available, fetches if not\n * - `options`: Returns config for use with useQuery() or createQuery()\n * - `fetch()`: Always attempts to fetch data (from cache if fresh, network if stale)\n * - `ensure()`: Guarantees data availability, preferring cached data (recommended for preloaders)\n *\n * @template TQueryFnData - The type of data returned by the query function\n * @template TError - The type of error that can be thrown\n * @template TData - The type of data returned by the query (after select transform)\n * @template TQueryKey - The type of the query key\n *\n * @example\n * ```typescript\n * const userQuery = defineQuery({...});\n *\n * // Directly callable (same as .ensure())\n * const { data, error } = await userQuery();\n *\n * // Or use explicit methods\n * const { data, error } = await userQuery.ensure();\n * const { data, error } = await userQuery.fetch();\n *\n * // For reactive usage (Svelte 5 requires accessor wrapper)\n * const query = createQuery(() => userQuery.options); // Svelte 5\n * const query = useQuery(userQuery.options); // React\n * ```\n */\ntype DefineQueryOutput<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = (() => Promise<Result<TQueryData, TError>>) & {\n\toptions: QueryObserverOptions<\n\t\tTQueryFnData,\n\t\tTError,\n\t\tTData,\n\t\tTQueryData,\n\t\tTQueryKey\n\t>;\n\tfetch: () => Promise<Result<TQueryData, TError>>;\n\tensure: () => Promise<Result<TQueryData, TError>>;\n};\n\n/**\n * Input options for defining a mutation.\n *\n * Extends TanStack Query's MutationOptions but expects mutationFn to return a Result type.\n * This type represents the configuration for creating a mutation definition with both\n * reactive and imperative interfaces for data mutations.\n *\n * @template TData - The type of data returned by the mutation\n * @template TError - The type of error that can be thrown\n * @template TVariables - The type of variables passed to the mutation\n * @template TContext - The type of context data for optimistic updates\n */\ntype DefineMutationInput<\n\tTData,\n\tTError,\n\tTVariables = void,\n\tTContext = unknown,\n> = Omit<MutationOptions<TData, TError, TVariables, TContext>, \"mutationFn\"> & {\n\tmutationKey: MutationKey;\n\tmutationFn: MutationFunction<Result<TData, TError>, TVariables>;\n};\n\n/**\n * Output of defineMutation function.\n *\n * The mutation definition is directly callable, which executes the mutation\n * and returns a Result. This is equivalent to calling `.execute()`.\n *\n * Provides both reactive and imperative interfaces for data mutations:\n * - `(variables)` (callable): Same as `execute()` - directly executes the mutation\n * - `options`: Returns config for use with useMutation() or createMutation()\n * - `execute(variables)`: Directly executes the mutation and returns a Result\n *\n * @template TData - The type of data returned by the mutation\n * @template TError - The type of error that can be thrown\n * @template TVariables - The type of variables passed to the mutation\n * @template TContext - The type of context data for optimistic updates\n *\n * @example\n * ```typescript\n * const createUser = defineMutation({...});\n *\n * // Directly callable (same as .execute())\n * const { data, error } = await createUser({ name: 'John' });\n *\n * // Or use explicit method\n * const { data, error } = await createUser.execute({ name: 'John' });\n *\n * // For reactive usage (Svelte 5 requires accessor wrapper)\n * const mutation = createMutation(() => createUser.options); // Svelte 5\n * const mutation = useMutation(createUser.options); // React\n * ```\n */\ntype DefineMutationOutput<\n\tTData,\n\tTError,\n\tTVariables = void,\n\tTContext = unknown,\n> = ((variables: TVariables) => Promise<Result<TData, TError>>) & {\n\toptions: MutationOptions<TData, TError, TVariables, TContext>;\n\texecute: (variables: TVariables) => Promise<Result<TData, TError>>;\n};\n\n/**\n * Creates factory functions for defining queries and mutations bound to a specific QueryClient.\n *\n * This factory pattern allows you to create isolated query/mutation definitions that are\n * bound to a specific QueryClient instance, enabling:\n * - Multiple query clients in the same application\n * - Testing with isolated query clients\n * - Framework-agnostic query definitions\n * - Proper separation of concerns between query logic and client instances\n *\n * The returned functions handle Result types automatically, unwrapping them for TanStack Query\n * while maintaining type safety throughout your application.\n *\n * @param queryClient - The QueryClient instance to bind the factories to\n * @returns An object containing defineQuery and defineMutation functions bound to the provided client\n *\n * @example\n * ```typescript\n * // Create your query client\n * const queryClient = new QueryClient({\n *   defaultOptions: {\n *     queries: { staleTime: 5 * 60 * 1000 }\n *   }\n * });\n *\n * // Create the factory functions\n * const { defineQuery, defineMutation } = createQueryFactories(queryClient);\n *\n * // Now use defineQuery and defineMutation as before\n * const userQuery = defineQuery({\n *   queryKey: ['user', userId],\n *   queryFn: () => services.getUser(userId)\n * });\n *\n * // Use in components (Svelte 5 requires accessor wrapper)\n * const query = createQuery(() => userQuery.options); // Svelte 5\n * const query = useQuery(userQuery.options); // React\n *\n * // Or imperatively\n * const { data, error } = await userQuery.fetch();\n * ```\n */\nexport function createQueryFactories(queryClient: QueryClient) {\n\t/**\n\t * Creates a query definition that bridges the gap between pure service functions and reactive UI components.\n\t *\n\t * This factory function is the cornerstone of our data fetching architecture. It wraps service calls\n\t * with TanStack Query superpowers while maintaining type safety through Result types.\n\t *\n\t * The returned query definition is **directly callable** and defaults to `ensure()` behavior,\n\t * which is recommended for most imperative use cases like preloaders.\n\t *\n\t * ## Why use defineQuery?\n\t *\n\t * 1. **Callable**: Call directly like `userQuery()` for imperative data fetching\n\t * 2. **Dual Interface**: Also provides reactive (`.options`) and explicit imperative (`.fetch()`, `.ensure()`) APIs\n\t * 3. **Automatic Error Handling**: Service functions return `Result<T, E>` types which are automatically\n\t *    unwrapped by TanStack Query, giving you proper error states in your components\n\t * 4. **Type Safety**: Full TypeScript support with proper inference for data and error types\n\t * 5. **Consistency**: Every query in the app follows the same pattern, making it easy to understand\n\t *\n\t * @template TQueryFnData - The type of data returned by the query function\n\t * @template TError - The type of error that can be thrown\n\t * @template TData - The type of data returned by the query (after select transform)\n\t * @template TQueryKey - The type of the query key\n\t *\n\t * @param options - Query configuration object\n\t * @param options.queryKey - Unique key for this query (used for caching and refetching)\n\t * @param options.queryFn - Function that fetches data and returns a Result type\n\t * @param options.* - Any other TanStack Query options (staleTime, refetchInterval, etc.)\n\t *\n\t * @returns Callable query definition with:\n\t *   - `()` (callable): Same as `ensure()` - returns cached data if available, fetches if not\n\t *   - `.options`: Config for use with useQuery() or createQuery()\n\t *   - `.fetch()`: Always attempts to fetch (from cache if fresh, network if stale)\n\t *   - `.ensure()`: Guarantees data availability, preferring cached data (recommended for preloaders)\n\t *\n\t * @example\n\t * ```typescript\n\t * // Step 1: Define your query in the query layer\n\t * const userQuery = defineQuery({\n\t *   queryKey: ['users', userId],\n\t *   queryFn: () => services.getUser(userId), // Returns Result<User, ApiError>\n\t *   staleTime: 5 * 60 * 1000, // Consider data fresh for 5 minutes\n\t * });\n\t *\n\t * // Step 2a: Use reactively in a Svelte 5 component (accessor wrapper required)\n\t * const query = createQuery(() => userQuery.options);\n\t * // query.data is User | undefined\n\t * // query.error is ApiError | null\n\t *\n\t * // Step 2b: Call directly in preloaders (recommended)\n\t * export const load = async () => {\n\t *   const { data, error } = await userQuery(); // Same as userQuery.ensure()\n\t *   if (error) throw error;\n\t *   return { user: data };\n\t * };\n\t *\n\t * // Step 2c: Use explicit methods when needed\n\t * async function refreshUser() {\n\t *   const { data, error } = await userQuery.fetch(); // Force fresh fetch\n\t *   if (error) {\n\t *     console.error('Failed to fetch user:', error);\n\t *   }\n\t * }\n\t * ```\n\t */\n\tconst defineQuery = <\n\t\tTQueryFnData = unknown,\n\t\tTError = DefaultError,\n\t\tTData = TQueryFnData,\n\t\tTQueryData = TQueryFnData,\n\t\tTQueryKey extends QueryKey = QueryKey,\n\t>(\n\t\toptions: DefineQueryInput<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>,\n\t): DefineQueryOutput<TQueryFnData, TError, TData, TQueryData, TQueryKey> => {\n\t\tconst newOptions = {\n\t\t\t...options,\n\t\t\tqueryFn: async (context) => {\n\t\t\t\tlet result = options.queryFn(context);\n\t\t\t\tif (result instanceof Promise) result = await result;\n\t\t\t\treturn resolve(result);\n\t\t\t},\n\t\t} satisfies QueryObserverOptions<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>;\n\n\t\t/**\n\t\t * Fetches data for this query using queryClient.fetchQuery().\n\t\t *\n\t\t * This method ALWAYS evaluates freshness and will refetch if data is stale.\n\t\t * It wraps TanStack Query's fetchQuery method, which returns cached data if fresh\n\t\t * or makes a network request if the data is stale or missing.\n\t\t *\n\t\t * **When to use fetch():**\n\t\t * - When you explicitly want to check data freshness\n\t\t * - For user-triggered refresh actions\n\t\t * - When you need the most up-to-date data\n\t\t *\n\t\t * **For preloaders, use ensure() instead** - it's more efficient for initial data loading.\n\t\t *\n\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t *\n\t\t * @example\n\t\t * // Good for user-triggered refresh\n\t\t * const { data, error } = await userQuery.fetch();\n\t\t * if (error) {\n\t\t *   console.error('Failed to load user:', error);\n\t\t * }\n\t\t */\n\t\tasync function fetch(): Promise<Result<TQueryData, TError>> {\n\t\t\ttry {\n\t\t\t\treturn Ok(\n\t\t\t\t\tawait queryClient.fetchQuery<\n\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\tTError,\n\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t>({\n\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\tqueryFn: newOptions.queryFn,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\t/**\n\t\t * Ensures data is available for this query using queryClient.ensureQueryData().\n\t\t *\n\t\t * This method PRIORITIZES cached data and only calls fetchQuery internally if no cached\n\t\t * data exists. It wraps TanStack Query's ensureQueryData method, which is perfect for\n\t\t * guaranteeing data availability with minimal network requests.\n\t\t *\n\t\t * **This is the RECOMMENDED method for preloaders** because:\n\t\t * - It returns cached data immediately if available\n\t\t * - It updates the query client cache properly\n\t\t * - It minimizes network requests during navigation\n\t\t * - It ensures components have data ready when they mount\n\t\t *\n\t\t * **When to use ensure():**\n\t\t * - Route preloaders and data loading functions\n\t\t * - Initial component data requirements\n\t\t * - When cached data is acceptable for immediate display\n\t\t *\n\t\t * This is also the default behavior when calling the query directly.\n\t\t *\n\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t *\n\t\t * @example\n\t\t * // Perfect for preloaders\n\t\t * export const load = async () => {\n\t\t *   const { data, error } = await userQuery.ensure();\n\t\t *   // Or simply: await userQuery();\n\t\t *   if (error) {\n\t\t *     throw error;\n\t\t *   }\n\t\t *   return { user: data };\n\t\t * };\n\t\t */\n\t\tasync function ensure(): Promise<Result<TQueryData, TError>> {\n\t\t\ttry {\n\t\t\t\treturn Ok(\n\t\t\t\t\tawait queryClient.ensureQueryData<\n\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\tTError,\n\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t>({\n\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\tqueryFn: newOptions.queryFn,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\t// Create a callable function that defaults to ensure() behavior\n\t\t// and attach options, fetch, and ensure as properties\n\t\treturn Object.assign(ensure, {\n\t\t\toptions: newOptions,\n\t\t\tfetch,\n\t\t\tensure,\n\t\t});\n\t};\n\n\t/**\n\t * Creates a mutation definition for operations that modify data (create, update, delete).\n\t *\n\t * This factory function is the mutation counterpart to defineQuery. It provides a clean way to\n\t * wrap service functions that perform side effects, while maintaining the same dual interface\n\t * pattern for maximum flexibility.\n\t *\n\t * The returned mutation definition is **directly callable**, which executes the mutation\n\t * and returns a Result. This is equivalent to calling `.execute()`.\n\t *\n\t * ## Why use defineMutation?\n\t *\n\t * 1. **Callable**: Call directly like `createUser({ name: 'John' })` for imperative execution\n\t * 2. **Dual Interface**: Also provides reactive (`.options`) and explicit imperative (`.execute()`) APIs\n\t * 3. **Consistent Error Handling**: Service functions return `Result<T, E>` types, ensuring\n\t *    errors are handled consistently throughout the app\n\t * 4. **Cache Management**: Mutations often update the cache after success (see examples)\n\t *\n\t * @template TData - The type of data returned by the mutation\n\t * @template TError - The type of error that can be thrown\n\t * @template TVariables - The type of variables passed to the mutation\n\t * @template TContext - The type of context data for optimistic updates\n\t *\n\t * @param options - Mutation configuration object\n\t * @param options.mutationKey - Unique key for this mutation (used for tracking in-flight state)\n\t * @param options.mutationFn - Function that performs the mutation and returns a Result type\n\t * @param options.* - Any other TanStack Mutation options (onSuccess, onError, etc.)\n\t *\n\t * @returns Callable mutation definition with:\n\t *   - `(variables)` (callable): Same as `execute()` - directly executes the mutation\n\t *   - `.options`: Config for use with useMutation() or createMutation()\n\t *   - `.execute(variables)`: Directly executes the mutation and returns a Result\n\t *\n\t * @example\n\t * ```typescript\n\t * // Step 1: Define your mutation with cache updates\n\t * const createRecording = defineMutation({\n\t *   mutationKey: ['recordings', 'create'],\n\t *   mutationFn: async (recording: Recording) => {\n\t *     // Call the service\n\t *     const result = await services.db.createRecording(recording);\n\t *     if (result.error) return Err(result.error);\n\t *\n\t *     // Update cache on success\n\t *     queryClient.setQueryData(['recordings'], (old) =>\n\t *       [...(old || []), recording]\n\t *     );\n\t *\n\t *     return Ok(result.data);\n\t *   }\n\t * });\n\t *\n\t * // Step 2a: Use reactively in a Svelte 5 component (accessor wrapper required)\n\t * const mutation = createMutation(() => createRecording.options);\n\t * // Call with: mutation.mutate(recordingData)\n\t *\n\t * // Step 2b: Call directly in an action (recommended)\n\t * async function saveRecording(data: Recording) {\n\t *   const { error } = await createRecording(data); // Same as createRecording.execute(data)\n\t *   if (error) {\n\t *     notify.error({ title: 'Failed to save', description: error.message });\n\t *   } else {\n\t *     notify.success({ title: 'Recording saved!' });\n\t *   }\n\t * }\n\t * ```\n\t *\n\t * @tip Calling directly is especially useful for:\n\t * - Event handlers that need to await the result\n\t * - Sequential operations that depend on each other\n\t * - Non-component code that needs to trigger mutations\n\t */\n\tconst defineMutation = <TData, TError, TVariables = void, TContext = unknown>(\n\t\toptions: DefineMutationInput<TData, TError, TVariables, TContext>,\n\t): DefineMutationOutput<TData, TError, TVariables, TContext> => {\n\t\tconst newOptions = {\n\t\t\t...options,\n\t\t\tmutationFn: async (variables: TVariables) => {\n\t\t\t\treturn resolve(await options.mutationFn(variables));\n\t\t\t},\n\t\t} satisfies MutationOptions<TData, TError, TVariables, TContext>;\n\n\t\t/**\n\t\t * Executes the mutation imperatively and returns a Result.\n\t\t *\n\t\t * This is the recommended way to trigger mutations from:\n\t\t * - Button click handlers\n\t\t * - Form submissions\n\t\t * - Keyboard shortcuts\n\t\t * - Any non-component code\n\t\t *\n\t\t * The method automatically wraps the result in a Result type, so you always\n\t\t * get back `{ data, error }` for consistent error handling.\n\t\t *\n\t\t * This is also the default behavior when calling the mutation directly.\n\t\t *\n\t\t * @param variables - The variables to pass to the mutation function\n\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t *\n\t\t * @example\n\t\t * // In an event handler\n\t\t * async function handleSubmit(formData: FormData) {\n\t\t *   const { data, error } = await createUser.execute(formData);\n\t\t *   // Or simply: await createUser(formData);\n\t\t *   if (error) {\n\t\t *     notify.error({ title: 'Failed to create user', description: error.message });\n\t\t *     return;\n\t\t *   }\n\t\t *   goto(`/users/${data.id}`);\n\t\t * }\n\t\t */\n\t\tasync function execute(variables: TVariables) {\n\t\t\ttry {\n\t\t\t\treturn Ok(await runMutation(queryClient, newOptions, variables));\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\t// Create a callable function that executes the mutation\n\t\t// and attach options and execute as properties\n\t\treturn Object.assign(execute, {\n\t\t\toptions: newOptions,\n\t\t\texecute,\n\t\t});\n\t};\n\n\treturn {\n\t\tdefineQuery,\n\t\tdefineMutation,\n\t};\n}\n\n/**\n * Internal helper that executes a mutation directly using the query client's mutation cache.\n *\n * This is what powers the callable behavior and `.execute()` method on mutations.\n * It bypasses the reactive mutation hooks and runs the mutation imperatively,\n * which is perfect for event handlers and other imperative code.\n *\n * @internal\n * @template TData - The type of data returned by the mutation\n * @template TError - The type of error that can be thrown\n * @template TVariables - The type of variables passed to the mutation\n * @template TContext - The type of context data\n * @param queryClient - The query client instance to use\n * @param options - The mutation options including mutationFn and mutationKey\n * @param variables - The variables to pass to the mutation function\n * @returns Promise that resolves with the mutation result\n */\nfunction runMutation<TData, TError, TVariables, TContext>(\n\tqueryClient: QueryClient,\n\toptions: MutationOptions<TData, TError, TVariables, TContext>,\n\tvariables: TVariables,\n) {\n\tconst mutation = queryClient.getMutationCache().build(queryClient, options);\n\treturn mutation.execute(variables);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkMA,SAAgB,qBAAqBA,aAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiE9D,MAAM,cAAc,CAOnBC,YAO2E;EAC3E,MAAM,aAAa;GAClB,GAAG;GACH,SAAS,OAAO,YAAY;IAC3B,IAAI,SAAS,QAAQ,QAAQ,QAAQ;AACrC,QAAI,kBAAkB,QAAS,UAAS,MAAM;AAC9C,WAAO,QAAQ,OAAO;GACtB;EACD;;;;;;;;;;;;;;;;;;;;;;;;EA+BD,eAAe,QAA6C;AAC3D,OAAI;AACH,WAAO,GACN,MAAM,YAAY,WAKhB;KACD,UAAU,WAAW;KACrB,SAAS,WAAW;IACpB,EAAC,CACF;GACD,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCD,eAAe,SAA8C;AAC5D,OAAI;AACH,WAAO,GACN,MAAM,YAAY,gBAKhB;KACD,UAAU,WAAW;KACrB,SAAS,WAAW;IACpB,EAAC,CACF;GACD,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;AAID,SAAO,OAAO,OAAO,QAAQ;GAC5B,SAAS;GACT;GACA;EACA,EAAC;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0ED,MAAM,iBAAiB,CACtBC,YAC+D;EAC/D,MAAM,aAAa;GAClB,GAAG;GACH,YAAY,OAAOC,cAA0B;AAC5C,WAAO,QAAQ,MAAM,QAAQ,WAAW,UAAU,CAAC;GACnD;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BD,eAAe,QAAQA,WAAuB;AAC7C,OAAI;AACH,WAAO,GAAG,MAAM,YAAY,aAAa,YAAY,UAAU,CAAC;GAChE,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;AAID,SAAO,OAAO,OAAO,SAAS;GAC7B,SAAS;GACT;EACA,EAAC;CACF;AAED,QAAO;EACN;EACA;CACA;AACD;;;;;;;;;;;;;;;;;;AAmBD,SAAS,YACRH,aACAI,SACAD,WACC;CACD,MAAM,WAAW,YAAY,kBAAkB,CAAC,MAAM,aAAa,QAAQ;AAC3E,QAAO,SAAS,QAAQ,UAAU;AAClC"}

package/dist/result/index.d.ts

@@ -1,3 +1,4 @@
-import { Err, Ok, Result, UnwrapErr, UnwrapOk, isErr, isOk, isResult, resolve, tryAsync, trySync, unwrap } from "../result-xH3TbSDF.js";
-import { partitionResults } from "../index-D_iQ3bBj.js";
-export { Err, Ok, Result, UnwrapErr, UnwrapOk, isErr, isOk, isResult, partitionResults, resolve, tryAsync, trySync, unwrap };
+import { Err, Ok, Result, UnwrapErr, UnwrapOk, isErr, isOk, isResult, resolve, tryAsync, trySync, unwrap } from "../result-DKwq9BCr.js";
+import { tapErr } from "../tap-err-CFhHBPfH.js";
+import { partitionResults } from "../index-DnoV2ZDO.js";
+export { Err, Ok, Result, UnwrapErr, UnwrapOk, isErr, isOk, isResult, partitionResults, resolve, tapErr, tryAsync, trySync, unwrap };

package/dist/result/index.js

@@ -1,4 +1,5 @@
-import { Err, Ok, isErr, isOk, isResult, resolve, tryAsync, trySync, unwrap } from "../result-BRfWC87j.js";
-import { partitionResults } from "../result-Cd0chHlN.js";
+import { Err, Ok, isErr, isOk, isResult, resolve, tryAsync, trySync, unwrap } from "../result-C5cJ1_WU.js";
+import { tapErr } from "../tap-err-CP-re1HT.js";
+import { partitionResults } from "../result-C9V2Knvt.js";
 
-export { Err, Ok, isErr, isOk, isResult, partitionResults, resolve, tryAsync, trySync, unwrap };
+export { Err, Ok, isErr, isOk, isResult, partitionResults, resolve, tapErr, tryAsync, trySync, unwrap };