@thomasfosterau/effect-svelte 0.1.0 → 0.3.0

package/dist/internal/live-stream.js

@@ -0,0 +1,43 @@
+import { interruptFiber, runFork } from "./run.js";
+import { Cause, Effect, Exit, Stream } from "effect";
+//#region src/internal/live-stream.ts
+/**
+* Orchestrates a live `Stream` subscription against a {@link LiveResultState}.
+*
+* A single {@link makeLiveStream} instance is reused across re-subscriptions
+* (driven by the hook's `$effect`): every call to `subscribe` interrupts the
+* previous run and starts a fresh one, keeping the previous value visible as a
+* waiting `Success` in between (stale-while-revalidate).
+*
+* Interruption caused by the hook's own teardown / re-subscribe must never
+* surface as a `Failure` — only genuine failures (`Cause.hasFails`) and defects
+* (`Cause.hasDies`) settle the result to `Failure`.
+*/
+function makeLiveStream(runtime, state) {
+	let active = null;
+	const subscribe = (stream) => {
+		const token = Symbol();
+		active = token;
+		state.startWaiting();
+		const consume = Stream.runForEach(stream, (value) => Effect.sync(() => {
+			if (active !== token) return;
+			state.emit(value);
+		}));
+		const program = Effect.flatMap(Effect.yieldNow, () => consume).pipe(Effect.onExit((exit) => Effect.sync(() => {
+			if (active !== token) return;
+			if (Exit.isSuccess(exit)) return;
+			const cause = exit.cause;
+			if (Cause.hasFails(cause) || Cause.hasDies(cause)) state.failCause(cause);
+		})));
+		const fiber = runFork(runtime)(program);
+		return () => {
+			if (active === token) active = null;
+			interruptFiber(fiber);
+		};
+	};
+	return { subscribe };
+}
+//#endregion
+export { makeLiveStream };
+
+//# sourceMappingURL=live-stream.js.map

package/dist/internal/live-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-stream.js","names":[],"sources":["../../src/internal/live-stream.ts"],"sourcesContent":["import { Cause, Effect, Exit, Stream } from \"effect\";\nimport type * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\nimport { interruptFiber, runFork, type RuntimeLike } from \"./run.js\";\n\n/**\n * The reactive holder driven by {@link makeLiveStream}. The rune-backed\n * implementation lives in `live-stream.svelte.ts` (a `$state.raw` cell); this\n * interface keeps the orchestrator below rune-free so it can be unit-tested\n * with a plain fake (the same split as `makeResult` / `makeMutation`).\n *\n * The transitions follow the same stale-while-revalidate semantics as the rest\n * of the package: marking a result waiting preserves whatever value it already\n * holds, so the previous emission stays visible while a new subscription spins\n * up.\n */\nexport interface LiveResultState<A, E> {\n  /** The current result. Read inside an effect or template to track it. */\n  readonly current: AsyncResult.AsyncResult<A, E>;\n\n  /**\n   * Mark the current result as waiting, preserving any value it already holds\n   * (a seeded `Success` becomes a waiting `Success`, an `Initial` a waiting\n   * `Initial`).\n   */\n  startWaiting(): void;\n\n  /**\n   * Replace the result with a non-waiting `Success`. Each emission replaces the\n   * previous one — live queries emit whole result sets, never appended deltas.\n   */\n  emit(value: A): void;\n\n  /** Replace the result with a `Failure`, carrying the previous success forward. */\n  failCause(cause: Cause.Cause<E>): void;\n}\n\n/**\n * Orchestrates a live `Stream` subscription against a {@link LiveResultState}.\n *\n * A single {@link makeLiveStream} instance is reused across re-subscriptions\n * (driven by the hook's `$effect`): every call to `subscribe` interrupts the\n * previous run and starts a fresh one, keeping the previous value visible as a\n * waiting `Success` in between (stale-while-revalidate).\n *\n * Interruption caused by the hook's own teardown / re-subscribe must never\n * surface as a `Failure` — only genuine failures (`Cause.hasFails`) and defects\n * (`Cause.hasDies`) settle the result to `Failure`.\n */\nexport function makeLiveStream<A, E, R>(\n  runtime: RuntimeLike<R>,\n  state: LiveResultState<A, E>,\n): {\n  /** Start a new subscription, returning a teardown that interrupts it. */\n  readonly subscribe: (stream: Stream.Stream<A, E, R>) => () => void;\n} {\n  // Identifies the live subscription. A superseded run's late emission (or\n  // exit) is dropped by comparing against this token, so a fiber that is being\n  // interrupted cannot clobber the value the newer subscription just set.\n  let active: symbol | null = null;\n\n  const subscribe = (stream: Stream.Stream<A, E, R>): (() => void) => {\n    const token = Symbol();\n    active = token;\n\n    // Keep the previous value visible as a waiting `Success` while the new\n    // subscription starts (stale-while-revalidate). On the very first run this\n    // marks a seeded `Success` / bare `Initial` as waiting.\n    state.startWaiting();\n\n    const consume = Stream.runForEach(stream, (value) =>\n      Effect.sync(() => {\n        if (active !== token) return;\n        // Each emission replaces the current value — never appends.\n        state.emit(value);\n      }),\n    );\n\n    // Yield once before consuming, so a synchronously-resolving stream cannot\n    // write state *during* the `$effect` flush that started it (Svelte flags a\n    // write-during-flush that the awaited `promise` reads back as an update\n    // cycle). The subscription still starts on the very next microtask.\n    const program = Effect.flatMap(Effect.yieldNow, () => consume).pipe(\n      Effect.onExit((exit) =>\n        Effect.sync(() => {\n          if (active !== token) return;\n          // A completed stream leaves the last emission in place.\n          if (Exit.isSuccess(exit)) return;\n          const cause = exit.cause;\n          // Teardown / re-subscribe interruption is normal lifecycle churn and\n          // must not surface as a `Failure`; only real failures and defects do.\n          if (Cause.hasFails(cause) || Cause.hasDies(cause)) {\n            state.failCause(cause);\n          }\n        }),\n      ),\n    );\n\n    const fiber = runFork(runtime)(program);\n\n    return () => {\n      if (active === token) active = null;\n      interruptFiber(fiber);\n    };\n  };\n\n  return { subscribe };\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgDA,SAAgB,eACd,SACA,OAIA;CAIA,IAAI,SAAwB;CAE5B,MAAM,aAAa,WAAiD;EAClE,MAAM,QAAQ,OAAO;EACrB,SAAS;EAKT,MAAM,aAAa;EAEnB,MAAM,UAAU,OAAO,WAAW,SAAS,UACzC,OAAO,WAAW;GAChB,IAAI,WAAW,OAAO;GAEtB,MAAM,KAAK,KAAK;EAClB,CAAC,CACH;EAMA,MAAM,UAAU,OAAO,QAAQ,OAAO,gBAAgB,OAAO,EAAE,KAC7D,OAAO,QAAQ,SACb,OAAO,WAAW;GAChB,IAAI,WAAW,OAAO;GAEtB,IAAI,KAAK,UAAU,IAAI,GAAG;GAC1B,MAAM,QAAQ,KAAK;GAGnB,IAAI,MAAM,SAAS,KAAK,KAAK,MAAM,QAAQ,KAAK,GAC9C,MAAM,UAAU,KAAK;EAEzB,CAAC,CACH,CACF;EAEA,MAAM,QAAQ,QAAQ,OAAO,EAAE,OAAO;EAEtC,aAAa;GACX,IAAI,WAAW,OAAO,SAAS;GAC/B,eAAe,KAAK;EACtB;CACF;CAEA,OAAO,EAAE,UAAU;AACrB"}

package/dist/internal/mutation.d.ts

@@ -0,0 +1,38 @@
+import { Effect } from "effect";
+
+//#region src/internal/mutation.d.ts
+/**
+ * Lifecycle callbacks for a mutation, following TanStack Query conventions.
+ *
+ * `onMutate` runs synchronously before the effect starts and its return value
+ * is threaded through `onSuccess` / `onError` / `onSettled` as `context` — the
+ * idiomatic place to apply an optimistic update and capture a snapshot for
+ * rollback.
+ */
+interface MutationCallbacks<A, E, I, C> {
+  /**
+   * Runs before the mutation effect. Apply an optimistic update here and return
+   * any value (e.g. a snapshot) to receive it back as `context` in the other
+   * callbacks — use it to roll back in `onError`.
+   */
+  readonly onMutate?: (input: I) => C;
+  /** Runs after the mutation succeeds, before invalidation. */
+  readonly onSuccess?: (value: A, input: I, context: C | undefined) => void;
+  /**
+   * Runs after the mutation fails with a typed error. Pure defects (dies)
+   * still settle `current` as a failure but do not invoke this callback, since
+   * there is no `E` value to hand back — inspect `current` for those.
+   */
+  readonly onError?: (error: E, input: I, context: C | undefined) => void;
+  /** Runs after `onSuccess` / `onError`, regardless of outcome. */
+  readonly onSettled?: (input: I, context: C | undefined) => void;
+  /**
+   * Reactivity keys to invalidate after a successful mutation (a static array
+   * or a function of the input). Requires the runtime to include
+   * `Reactivity.layer` from `effect/unstable/reactivity`.
+   */
+  readonly invalidates?: ReadonlyArray<unknown> | ((input: I) => ReadonlyArray<unknown>);
+}
+//#endregion
+export { MutationCallbacks };
+//# sourceMappingURL=mutation.d.ts.map

package/dist/internal/mutation.js

@@ -0,0 +1,61 @@
+import { interruptFiber, runFork } from "./run.js";
+import { Cause, Effect, Exit, Fiber, Option } from "effect";
+import { Reactivity } from "effect/unstable/reactivity";
+//#region src/internal/mutation.ts
+/**
+* The orchestration half of {@link useMutation}, factored out of the rune
+* wrapper so it can be unit-tested with a plain (non-rune) {@link ResultState}
+* and a real runtime.
+*
+* Drives `state` through the stale-while-revalidate transitions and dispatches
+* the {@link MutationCallbacks} from the settled `Exit`. Interrupted runs (a
+* newer `mutate` replacing an older one, or teardown) are ignored so a
+* superseded run never clobbers the latest result.
+*/
+function makeMutation(runtime, state, fn, callbacks = {}) {
+	let currentFiber = null;
+	const mutate = (input) => {
+		if (currentFiber !== null) interruptFiber(currentFiber);
+		const context = callbacks.onMutate?.(input);
+		state.startWaiting();
+		const running = runFork(runtime)(fn(input));
+		currentFiber = running;
+		runFork(runtime)(Effect.gen(function* () {
+			const exit = yield* Fiber.await(running);
+			if (currentFiber !== running) return;
+			currentFiber = null;
+			if (Exit.isSuccess(exit)) {
+				state.settle(exit);
+				callbacks.onSuccess?.(exit.value, input, context);
+				const keys = typeof callbacks.invalidates === "function" ? callbacks.invalidates(input) : callbacks.invalidates;
+				if (keys !== void 0) runFork(runtime)(Reactivity.invalidate(keys));
+				callbacks.onSettled?.(input, context);
+				return;
+			}
+			if (Cause.hasInterrupts(exit.cause)) return;
+			state.settle(exit);
+			const error = Cause.findErrorOption(exit.cause);
+			if (Option.isSome(error)) callbacks.onError?.(error.value, input, context);
+			callbacks.onSettled?.(input, context);
+		}));
+	};
+	const interrupt = () => {
+		if (currentFiber !== null) {
+			interruptFiber(currentFiber);
+			currentFiber = null;
+		}
+	};
+	const reset = () => {
+		interrupt();
+		state.reset();
+	};
+	return {
+		mutate,
+		reset,
+		interrupt
+	};
+}
+//#endregion
+export { makeMutation };
+
+//# sourceMappingURL=mutation.js.map

package/dist/internal/mutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation.js","names":[],"sources":["../../src/internal/mutation.ts"],"sourcesContent":["import { Cause, Effect, Exit, Fiber, Option } from \"effect\";\nimport { Reactivity } from \"effect/unstable/reactivity\";\nimport { interruptFiber, runFork, type RuntimeLike } from \"./run.js\";\nimport type { ResultState } from \"./result.svelte.js\";\n\n/**\n * Lifecycle callbacks for a mutation, following TanStack Query conventions.\n *\n * `onMutate` runs synchronously before the effect starts and its return value\n * is threaded through `onSuccess` / `onError` / `onSettled` as `context` — the\n * idiomatic place to apply an optimistic update and capture a snapshot for\n * rollback.\n */\nexport interface MutationCallbacks<A, E, I, C> {\n  /**\n   * Runs before the mutation effect. Apply an optimistic update here and return\n   * any value (e.g. a snapshot) to receive it back as `context` in the other\n   * callbacks — use it to roll back in `onError`.\n   */\n  readonly onMutate?: (input: I) => C;\n  /** Runs after the mutation succeeds, before invalidation. */\n  readonly onSuccess?: (value: A, input: I, context: C | undefined) => void;\n  /**\n   * Runs after the mutation fails with a typed error. Pure defects (dies)\n   * still settle `current` as a failure but do not invoke this callback, since\n   * there is no `E` value to hand back — inspect `current` for those.\n   */\n  readonly onError?: (error: E, input: I, context: C | undefined) => void;\n  /** Runs after `onSuccess` / `onError`, regardless of outcome. */\n  readonly onSettled?: (input: I, context: C | undefined) => void;\n  /**\n   * Reactivity keys to invalidate after a successful mutation (a static array\n   * or a function of the input). Requires the runtime to include\n   * `Reactivity.layer` from `effect/unstable/reactivity`.\n   */\n  readonly invalidates?: ReadonlyArray<unknown> | ((input: I) => ReadonlyArray<unknown>);\n}\n\n/** The imperative surface of a mutation, independent of any rune state. */\nexport interface MutationCore<I> {\n  /** Run the mutation for `input`, interrupting any in-flight run. */\n  readonly mutate: (input: I) => void;\n  /** Interrupt the in-flight run and reset the result to `Initial`. */\n  readonly reset: () => void;\n  /** Interrupt the in-flight run without resetting the result. */\n  readonly interrupt: () => void;\n}\n\n/**\n * The orchestration half of {@link useMutation}, factored out of the rune\n * wrapper so it can be unit-tested with a plain (non-rune) {@link ResultState}\n * and a real runtime.\n *\n * Drives `state` through the stale-while-revalidate transitions and dispatches\n * the {@link MutationCallbacks} from the settled `Exit`. Interrupted runs (a\n * newer `mutate` replacing an older one, or teardown) are ignored so a\n * superseded run never clobbers the latest result.\n */\nexport function makeMutation<A, E, I, C, R>(\n  runtime: RuntimeLike<R>,\n  state: ResultState<A, E>,\n  fn: (input: I) => Effect.Effect<A, E, R>,\n  callbacks: MutationCallbacks<A, E, I, C> = {},\n): MutationCore<I> {\n  let currentFiber: Fiber.Fiber<A, E> | null = null;\n\n  const mutate = (input: I): void => {\n    if (currentFiber !== null) interruptFiber(currentFiber);\n\n    const context = callbacks.onMutate?.(input);\n    state.startWaiting();\n\n    const running = runFork(runtime)(fn(input));\n    currentFiber = running;\n\n    runFork(runtime)(\n      Effect.gen(function* () {\n        const exit = yield* Fiber.await(running);\n        // A newer mutate (or teardown) has superseded this run.\n        if (currentFiber !== running) return;\n        currentFiber = null;\n\n        if (Exit.isSuccess(exit)) {\n          state.settle(exit);\n          callbacks.onSuccess?.(exit.value, input, context);\n          const keys =\n            typeof callbacks.invalidates === \"function\"\n              ? callbacks.invalidates(input)\n              : callbacks.invalidates;\n          if (keys !== undefined) {\n            // Requires the runtime to provide Reactivity (documented contract).\n            runFork(runtime as RuntimeLike<Reactivity.Reactivity>)(Reactivity.invalidate(keys));\n          }\n          callbacks.onSettled?.(input, context);\n          return;\n        }\n\n        // Interruption is normal teardown; keep the prior state.\n        if (Cause.hasInterrupts(exit.cause)) return;\n\n        state.settle(exit);\n        const error = Cause.findErrorOption(exit.cause);\n        if (Option.isSome(error)) callbacks.onError?.(error.value, input, context);\n        callbacks.onSettled?.(input, context);\n      }),\n    );\n  };\n\n  const interrupt = (): void => {\n    if (currentFiber !== null) {\n      interruptFiber(currentFiber);\n      currentFiber = null;\n    }\n  };\n\n  const reset = (): void => {\n    interrupt();\n    state.reset();\n  };\n\n  return { mutate, reset, interrupt };\n}\n"],"mappings":";;;;;;;;;;;;;;AA0DA,SAAgB,aACd,SACA,OACA,IACA,YAA2C,CAAC,GAC3B;CACjB,IAAI,eAAyC;CAE7C,MAAM,UAAU,UAAmB;EACjC,IAAI,iBAAiB,MAAM,eAAe,YAAY;EAEtD,MAAM,UAAU,UAAU,WAAW,KAAK;EAC1C,MAAM,aAAa;EAEnB,MAAM,UAAU,QAAQ,OAAO,EAAE,GAAG,KAAK,CAAC;EAC1C,eAAe;EAEf,QAAQ,OAAO,EACb,OAAO,IAAI,aAAa;GACtB,MAAM,OAAO,OAAO,MAAM,MAAM,OAAO;GAEvC,IAAI,iBAAiB,SAAS;GAC9B,eAAe;GAEf,IAAI,KAAK,UAAU,IAAI,GAAG;IACxB,MAAM,OAAO,IAAI;IACjB,UAAU,YAAY,KAAK,OAAO,OAAO,OAAO;IAChD,MAAM,OACJ,OAAO,UAAU,gBAAgB,aAC7B,UAAU,YAAY,KAAK,IAC3B,UAAU;IAChB,IAAI,SAAS,KAAA,GAEX,QAAQ,OAA6C,EAAE,WAAW,WAAW,IAAI,CAAC;IAEpF,UAAU,YAAY,OAAO,OAAO;IACpC;GACF;GAGA,IAAI,MAAM,cAAc,KAAK,KAAK,GAAG;GAErC,MAAM,OAAO,IAAI;GACjB,MAAM,QAAQ,MAAM,gBAAgB,KAAK,KAAK;GAC9C,IAAI,OAAO,OAAO,KAAK,GAAG,UAAU,UAAU,MAAM,OAAO,OAAO,OAAO;GACzE,UAAU,YAAY,OAAO,OAAO;EACtC,CAAC,CACH;CACF;CAEA,MAAM,kBAAwB;EAC5B,IAAI,iBAAiB,MAAM;GACzB,eAAe,YAAY;GAC3B,eAAe;EACjB;CACF;CAEA,MAAM,cAAoB;EACxB,UAAU;EACV,MAAM,MAAM;CACd;CAEA,OAAO;EAAE;EAAQ;EAAO;CAAU;AACpC"}

package/dist/internal/result.svelte.d.ts

@@ -0,0 +1 @@
+import { Cause, Exit } from "effect";

package/dist/internal/writable.js

@@ -0,0 +1,21 @@
+import { runFork } from "./run.js";
+import { SubscriptionRef } from "effect";
+//#region src/internal/writable.ts
+/**
+* Build a {@link RefWriter} for a `SubscriptionRef`, running writes on the
+* given runtime.
+*/
+function refWriter(runtime, ref) {
+	return {
+		set: (value) => {
+			runFork(runtime)(SubscriptionRef.set(ref, value));
+		},
+		update: (f) => {
+			runFork(runtime)(SubscriptionRef.update(ref, f));
+		}
+	};
+}
+//#endregion
+export { refWriter };
+
+//# sourceMappingURL=writable.js.map

package/dist/internal/writable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writable.js","names":[],"sources":["../../src/internal/writable.ts"],"sourcesContent":["import { SubscriptionRef } from \"effect\";\nimport { runFork, type RuntimeLike } from \"./run.js\";\n\n/**\n * The imperative write half of a two-way `SubscriptionRef` binding, factored\n * out of the rune wrapper so the write semantics can be unit-tested without a\n * Svelte component context.\n *\n * Both `set` and `update` fork the write onto the runtime and return\n * immediately — the value the caller sees update is driven by the ref's\n * `changes` stream (or, in the rune wrapper, an optimistic local assignment).\n */\nexport interface RefWriter<A> {\n  /** Replace the ref's value. */\n  readonly set: (value: A) => void;\n  /** Apply a function to the ref's current value. */\n  readonly update: (f: (current: A) => A) => void;\n}\n\n/**\n * Build a {@link RefWriter} for a `SubscriptionRef`, running writes on the\n * given runtime.\n */\nexport function refWriter<A, R = never>(\n  runtime: RuntimeLike<R>,\n  ref: SubscriptionRef.SubscriptionRef<A>,\n): RefWriter<A> {\n  return {\n    set: (value) => {\n      runFork(runtime)(SubscriptionRef.set(ref, value));\n    },\n    update: (f) => {\n      runFork(runtime)(SubscriptionRef.update(ref, f));\n    },\n  };\n}\n"],"mappings":";;;;;;;AAuBA,SAAgB,UACd,SACA,KACc;CACd,OAAO;EACL,MAAM,UAAU;GACd,QAAQ,OAAO,EAAE,gBAAgB,IAAI,KAAK,KAAK,CAAC;EAClD;EACA,SAAS,MAAM;GACb,QAAQ,OAAO,EAAE,gBAAgB,OAAO,KAAK,CAAC,CAAC;EACjD;CACF;AACF"}

package/dist/live-stream.svelte.d.ts

@@ -0,0 +1,72 @@
+import { RuntimeLike } from "./internal/run.js";
+import { Stream } from "effect";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+
+//#region src/live-stream.svelte.d.ts
+interface UseLiveStreamOptions<A, R> {
+  /**
+   * Run against this runtime instead of the ambient context. When provided, the
+   * stream's `R` is constrained to what the runtime provides (a service-typed
+   * `ManagedRuntime` gives a fully-checked `R`).
+   */
+  readonly runtime?: RuntimeLike<R>;
+  /**
+   * A synchronous seed value. When provided, `current` starts as a non-waiting
+   * `Success(initial)` (and `promise` starts already-resolved) instead of
+   * `Initial`, so server renders and the first client render show the data the
+   * server already had — the first real emission then replaces it. This is the
+   * SSR seam: without a synchronous seed, SSR output and the first client render
+   * would show empty state and hydration would mismatch.
+   */
+  readonly initial?: A;
+}
+interface UseLiveStreamReturn<A, E> {
+  /**
+   * The latest emission as an {@link AsyncResult.AsyncResult}. Each emission
+   * replaces the previous value (never appends). While re-subscribing after a
+   * reactive-input change the previous value stays visible as a waiting
+   * `Success` (stale-while-revalidate). Held in `$state.raw`, so a large array's
+   * reference identity is preserved for downstream dedup.
+   */
+  readonly current: AsyncResult.AsyncResult<A, E>;
+  /**
+   * A reactive `Promise` reflecting `current`, for `{#await}`-free async
+   * templates (`experimental.async` + `<svelte:boundary>`). Pending until the
+   * first emission, then replaced with an already-resolved promise on every
+   * subsequent emission (no pending flash after first load); failures reject it.
+   * With `initial` it starts already-resolved, so seeded pages never suspend
+   * during SSR.
+   */
+  readonly promise: Promise<A>;
+}
+/**
+ * Subscribe to a live `Stream` and track its latest emission, re-subscribing
+ * whenever the reactive inputs it reads change.
+ *
+ * The `stream` thunk is called inside `$effect`, so any reactive state it reads
+ * (e.g. a pagination cursor in `$state`) is dependency-tracked; when it changes,
+ * the previous subscription is interrupted and a new one starts, keeping the
+ * previous value visible as a waiting `Success` (stale-while-revalidate). This
+ * is distinct from {@link useStream} (accumulates a static stream) and
+ * `reactiveStream` (re-runs an *Effect* on Reactivity-key invalidation).
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useLiveStream } from '@thomasfosterau/effect-svelte';
+ *
+ *   let cursor = $state(0);
+ *
+ *   // Re-subscribes whenever `cursor` changes.
+ *   const todos = useLiveStream(() => liveTodos(cursor), { initial: seededTodos });
+ * </script>
+ *
+ * <svelte:boundary>
+ *   <ul>{#each await todos.promise as todo}<li>{todo.title}</li>{/each}</ul>
+ * </svelte:boundary>
+ * ```
+ */
+declare function useLiveStream<A, E, R>(stream: () => Stream.Stream<A, E, R>, options?: UseLiveStreamOptions<A, R>): UseLiveStreamReturn<A, E>;
+//#endregion
+export { UseLiveStreamOptions, UseLiveStreamReturn, useLiveStream };
+//# sourceMappingURL=live-stream.svelte.d.ts.map

package/dist/live-stream.svelte.js

@@ -0,0 +1,77 @@
+import { getRuntimeContext } from "./context.svelte.js";
+import { resultToPromise } from "./internal/await.js";
+import { makeLiveStream } from "./internal/live-stream.js";
+import { Option } from "effect";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+//#region src/live-stream.svelte.ts
+/**
+* A rune-backed {@link LiveResultState}. Holds the result in `$state.raw`:
+* emissions can be large arrays whose reference equality is meaningful
+* downstream, so deep proxying would break dedup and waste work.
+*/
+function makeLiveResult(seed) {
+	let current = $state.raw(Option.isSome(seed) ? AsyncResult.success(seed.value) : AsyncResult.initial());
+	return {
+		get current() {
+			return current;
+		},
+		startWaiting() {
+			current = AsyncResult.waiting(current);
+		},
+		emit(value) {
+			current = AsyncResult.success(value);
+		},
+		failCause(cause) {
+			current = AsyncResult.failureWithPrevious(cause, { previous: Option.some(current) });
+		}
+	};
+}
+/**
+* Subscribe to a live `Stream` and track its latest emission, re-subscribing
+* whenever the reactive inputs it reads change.
+*
+* The `stream` thunk is called inside `$effect`, so any reactive state it reads
+* (e.g. a pagination cursor in `$state`) is dependency-tracked; when it changes,
+* the previous subscription is interrupted and a new one starts, keeping the
+* previous value visible as a waiting `Success` (stale-while-revalidate). This
+* is distinct from {@link useStream} (accumulates a static stream) and
+* `reactiveStream` (re-runs an *Effect* on Reactivity-key invalidation).
+*
+* @example
+* ```svelte
+* <script lang="ts">
+*   import { useLiveStream } from '@thomasfosterau/effect-svelte';
+*
+*   let cursor = $state(0);
+*
+*   // Re-subscribes whenever `cursor` changes.
+*   const todos = useLiveStream(() => liveTodos(cursor), { initial: seededTodos });
+* <\/script>
+*
+* <svelte:boundary>
+*   <ul>{#each await todos.promise as todo}<li>{todo.title}</li>{/each}</ul>
+* </svelte:boundary>
+* ```
+*/
+function useLiveStream(stream, options = {}) {
+	const runtime = options.runtime ?? getRuntimeContext();
+	const state = makeLiveResult("initial" in options ? Option.some(options.initial) : Option.none());
+	const core = makeLiveStream(runtime, state);
+	$effect(() => {
+		const current = stream();
+		return core.subscribe(current);
+	});
+	const promise = $derived(resultToPromise(state.current));
+	return {
+		get current() {
+			return state.current;
+		},
+		get promise() {
+			return promise;
+		}
+	};
+}
+//#endregion
+export { useLiveStream };
+
+//# sourceMappingURL=live-stream.svelte.js.map

package/dist/live-stream.svelte.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-stream.svelte.js","names":["getRuntime"],"sources":["../src/live-stream.svelte.ts"],"sourcesContent":["import { Option, type Stream } from \"effect\";\nimport * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\nimport { getRuntime } from \"./context.svelte.js\";\nimport { resultToPromise } from \"./internal/await.js\";\nimport { makeLiveStream, type LiveResultState } from \"./internal/live-stream.js\";\nimport type { RuntimeLike } from \"./internal/run.js\";\n\nexport interface UseLiveStreamOptions<A, R> {\n  /**\n   * Run against this runtime instead of the ambient context. When provided, the\n   * stream's `R` is constrained to what the runtime provides (a service-typed\n   * `ManagedRuntime` gives a fully-checked `R`).\n   */\n  readonly runtime?: RuntimeLike<R>;\n\n  /**\n   * A synchronous seed value. When provided, `current` starts as a non-waiting\n   * `Success(initial)` (and `promise` starts already-resolved) instead of\n   * `Initial`, so server renders and the first client render show the data the\n   * server already had — the first real emission then replaces it. This is the\n   * SSR seam: without a synchronous seed, SSR output and the first client render\n   * would show empty state and hydration would mismatch.\n   */\n  readonly initial?: A;\n}\n\nexport interface UseLiveStreamReturn<A, E> {\n  /**\n   * The latest emission as an {@link AsyncResult.AsyncResult}. Each emission\n   * replaces the previous value (never appends). While re-subscribing after a\n   * reactive-input change the previous value stays visible as a waiting\n   * `Success` (stale-while-revalidate). Held in `$state.raw`, so a large array's\n   * reference identity is preserved for downstream dedup.\n   */\n  readonly current: AsyncResult.AsyncResult<A, E>;\n\n  /**\n   * A reactive `Promise` reflecting `current`, for `{#await}`-free async\n   * templates (`experimental.async` + `<svelte:boundary>`). Pending until the\n   * first emission, then replaced with an already-resolved promise on every\n   * subsequent emission (no pending flash after first load); failures reject it.\n   * With `initial` it starts already-resolved, so seeded pages never suspend\n   * during SSR.\n   */\n  readonly promise: Promise<A>;\n}\n\n/**\n * A rune-backed {@link LiveResultState}. Holds the result in `$state.raw`:\n * emissions can be large arrays whose reference equality is meaningful\n * downstream, so deep proxying would break dedup and waste work.\n */\nfunction makeLiveResult<A, E>(seed: Option.Option<A>): LiveResultState<A, E> {\n  let current = $state.raw<AsyncResult.AsyncResult<A, E>>(\n    Option.isSome(seed) ? AsyncResult.success<A, E>(seed.value) : AsyncResult.initial<A, E>(),\n  );\n\n  return {\n    get current() {\n      return current;\n    },\n    startWaiting() {\n      current = AsyncResult.waiting(current);\n    },\n    emit(value) {\n      current = AsyncResult.success<A, E>(value);\n    },\n    failCause(cause) {\n      current = AsyncResult.failureWithPrevious<A, E>(cause, { previous: Option.some(current) });\n    },\n  };\n}\n\n/**\n * Subscribe to a live `Stream` and track its latest emission, re-subscribing\n * whenever the reactive inputs it reads change.\n *\n * The `stream` thunk is called inside `$effect`, so any reactive state it reads\n * (e.g. a pagination cursor in `$state`) is dependency-tracked; when it changes,\n * the previous subscription is interrupted and a new one starts, keeping the\n * previous value visible as a waiting `Success` (stale-while-revalidate). This\n * is distinct from {@link useStream} (accumulates a static stream) and\n * `reactiveStream` (re-runs an *Effect* on Reactivity-key invalidation).\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { useLiveStream } from '@thomasfosterau/effect-svelte';\n *\n *   let cursor = $state(0);\n *\n *   // Re-subscribes whenever `cursor` changes.\n *   const todos = useLiveStream(() => liveTodos(cursor), { initial: seededTodos });\n * </script>\n *\n * <svelte:boundary>\n *   <ul>{#each await todos.promise as todo}<li>{todo.title}</li>{/each}</ul>\n * </svelte:boundary>\n * ```\n */\nexport function useLiveStream<A, E, R>(\n  stream: () => Stream.Stream<A, E, R>,\n  options: UseLiveStreamOptions<A, R> = {},\n): UseLiveStreamReturn<A, E> {\n  const runtime = options.runtime ?? (getRuntime() as RuntimeLike<R>);\n  const seed: Option.Option<A> =\n    \"initial\" in options ? Option.some(options.initial as A) : Option.none();\n\n  const state = makeLiveResult<A, E>(seed);\n  const core = makeLiveStream(runtime, state);\n\n  $effect(() => {\n    // Calling the thunk inside `$effect` tracks the reactive inputs it reads;\n    // when they change, the effect re-runs — tearing down the old subscription\n    // (interrupt, no Failure) and starting a fresh one.\n    const current = stream();\n    return core.subscribe(current);\n  });\n\n  // A new promise identity is produced only when the underlying result\n  // transitions, so awaited template expressions re-run with fresh data instead\n  // of on every unrelated re-render.\n  const promise = $derived(resultToPromise(state.current));\n\n  return {\n    get current() {\n      return state.current;\n    },\n    get promise() {\n      return promise;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;AAoDA,SAAS,eAAqB,MAA+C;CAC3E,IAAI,UAAU,OAAO,IACnB,OAAO,OAAO,IAAI,IAAI,YAAY,QAAc,KAAK,KAAK,IAAI,YAAY,QAAc,CAC1F;CAEA,OAAO;EACL,IAAI,UAAU;GACZ,OAAO;EACT;EACA,eAAe;GACb,UAAU,YAAY,QAAQ,OAAO;EACvC;EACA,KAAK,OAAO;GACV,UAAU,YAAY,QAAc,KAAK;EAC3C;EACA,UAAU,OAAO;GACf,UAAU,YAAY,oBAA0B,OAAO,EAAE,UAAU,OAAO,KAAK,OAAO,EAAE,CAAC;EAC3F;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,cACd,QACA,UAAsC,CAAC,GACZ;CAC3B,MAAM,UAAU,QAAQ,WAAYA,kBAAW;CAI/C,MAAM,QAAQ,eAFZ,aAAa,UAAU,OAAO,KAAK,QAAQ,OAAY,IAAI,OAAO,KAAK,CAElC;CACvC,MAAM,OAAO,eAAe,SAAS,KAAK;CAE1C,cAAc;EAIZ,MAAM,UAAU,OAAO;EACvB,OAAO,KAAK,UAAU,OAAO;CAC/B,CAAC;CAKD,MAAM,UAAU,SAAS,gBAAgB,MAAM,OAAO,CAAC;CAEvD,OAAO;EACL,IAAI,UAAU;GACZ,OAAO,MAAM;EACf;EACA,IAAI,UAAU;GACZ,OAAO;EACT;CACF;AACF"}

package/dist/mutation.svelte.d.ts

@@ -0,0 +1,65 @@
+import { RuntimeLike } from "./internal/run.js";
+import { MutationCallbacks } from "./internal/mutation.js";
+import { Effect } from "effect";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+
+//#region src/mutation.svelte.d.ts
+/**
+ * Options for {@link useMutation}: the lifecycle {@link MutationCallbacks} plus
+ * an optional explicit `runtime`.
+ */
+type UseMutationOptions<A, E, I, R, C> = MutationCallbacks<A, E, I, C> & {
+  /**
+   * Run against this runtime instead of the ambient context. When provided, the
+   * mutation's `R` is constrained to what the runtime provides.
+   */
+  readonly runtime?: RuntimeLike<R>;
+};
+interface UseMutationReturn<A, E, I> {
+  /**
+   * The current result state of the mutation. Starts `Initial`; each `mutate`
+   * marks it waiting (preserving the previous value) and settles to
+   * `Success` / `Failure`.
+   */
+  readonly current: AsyncResult.AsyncResult<A, E>;
+  /** Run the mutation with `input`. A new call interrupts any in-flight run. */
+  readonly mutate: (input: I) => void;
+  /** Interrupt any in-flight run and reset `current` back to `Initial`. */
+  readonly reset: () => void;
+}
+/**
+ * A TanStack-Query-shaped mutation hook: run an effectful `fn(input)` on
+ * demand, track its {@link AsyncResult.AsyncResult}, and fire lifecycle
+ * callbacks.
+ *
+ * Optimistic updates follow the TanStack model — apply the change in `onMutate`
+ * and return a snapshot as `context`, then roll back in `onError`. `invalidates`
+ * re-runs any reactive queries depending on the given keys after success (this
+ * requires the runtime to include `Reactivity.layer`).
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMutation, AsyncResult } from '@thomasfosterau/effect-svelte';
+ *   import { Effect } from 'effect';
+ *
+ *   const addTodo = useMutation(
+ *     (title: string) => saveTodo(title),
+ *     {
+ *       invalidates: ['todos'],
+ *       onSuccess: (todo) => console.log('added', todo.id),
+ *     },
+ *   );
+ * </script>
+ *
+ * <button onclick={() => addTodo.mutate('Buy milk')}>Add</button>
+ *
+ * {#if AsyncResult.isWaiting(addTodo.current)}
+ *   <p>Saving…</p>
+ * {/if}
+ * ```
+ */
+declare function useMutation<A, E, I, R, C = unknown>(fn: (input: I) => Effect.Effect<A, E, R>, options?: UseMutationOptions<A, E, I, R, C>): UseMutationReturn<A, E, I>;
+//#endregion
+export { UseMutationOptions, UseMutationReturn, useMutation };
+//# sourceMappingURL=mutation.svelte.d.ts.map

package/dist/mutation.svelte.js

@@ -0,0 +1,53 @@
+import { getRuntimeContext } from "./context.svelte.js";
+import { makeResult } from "./internal/result.svelte.js";
+import { makeMutation } from "./internal/mutation.js";
+//#region src/mutation.svelte.ts
+/**
+* A TanStack-Query-shaped mutation hook: run an effectful `fn(input)` on
+* demand, track its {@link AsyncResult.AsyncResult}, and fire lifecycle
+* callbacks.
+*
+* Optimistic updates follow the TanStack model — apply the change in `onMutate`
+* and return a snapshot as `context`, then roll back in `onError`. `invalidates`
+* re-runs any reactive queries depending on the given keys after success (this
+* requires the runtime to include `Reactivity.layer`).
+*
+* @example
+* ```svelte
+* <script lang="ts">
+*   import { useMutation, AsyncResult } from '@thomasfosterau/effect-svelte';
+*   import { Effect } from 'effect';
+*
+*   const addTodo = useMutation(
+*     (title: string) => saveTodo(title),
+*     {
+*       invalidates: ['todos'],
+*       onSuccess: (todo) => console.log('added', todo.id),
+*     },
+*   );
+* <\/script>
+*
+* <button onclick={() => addTodo.mutate('Buy milk')}>Add</button>
+*
+* {#if AsyncResult.isWaiting(addTodo.current)}
+*   <p>Saving…</p>
+* {/if}
+* ```
+*/
+function useMutation(fn, options = {}) {
+	const runtime = options.runtime ?? getRuntimeContext();
+	const state = makeResult();
+	const core = makeMutation(runtime, state, fn, options);
+	$effect(() => () => core.interrupt());
+	return {
+		get current() {
+			return state.current;
+		},
+		mutate: core.mutate,
+		reset: core.reset
+	};
+}
+//#endregion
+export { useMutation };
+
+//# sourceMappingURL=mutation.svelte.js.map

package/dist/mutation.svelte.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation.svelte.js","names":["getRuntime"],"sources":["../src/mutation.svelte.ts"],"sourcesContent":["import type { Effect } from \"effect\";\nimport type * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\nimport { getRuntime } from \"./context.svelte.js\";\nimport { makeMutation, type MutationCallbacks } from \"./internal/mutation.js\";\nimport type { RuntimeLike } from \"./internal/run.js\";\nimport { makeResult } from \"./internal/result.svelte.js\";\n\nexport type { MutationCallbacks } from \"./internal/mutation.js\";\n\n/**\n * Options for {@link useMutation}: the lifecycle {@link MutationCallbacks} plus\n * an optional explicit `runtime`.\n */\nexport type UseMutationOptions<A, E, I, R, C> = MutationCallbacks<A, E, I, C> & {\n  /**\n   * Run against this runtime instead of the ambient context. When provided, the\n   * mutation's `R` is constrained to what the runtime provides.\n   */\n  readonly runtime?: RuntimeLike<R>;\n};\n\nexport interface UseMutationReturn<A, E, I> {\n  /**\n   * The current result state of the mutation. Starts `Initial`; each `mutate`\n   * marks it waiting (preserving the previous value) and settles to\n   * `Success` / `Failure`.\n   */\n  readonly current: AsyncResult.AsyncResult<A, E>;\n\n  /** Run the mutation with `input`. A new call interrupts any in-flight run. */\n  readonly mutate: (input: I) => void;\n\n  /** Interrupt any in-flight run and reset `current` back to `Initial`. */\n  readonly reset: () => void;\n}\n\n/**\n * A TanStack-Query-shaped mutation hook: run an effectful `fn(input)` on\n * demand, track its {@link AsyncResult.AsyncResult}, and fire lifecycle\n * callbacks.\n *\n * Optimistic updates follow the TanStack model — apply the change in `onMutate`\n * and return a snapshot as `context`, then roll back in `onError`. `invalidates`\n * re-runs any reactive queries depending on the given keys after success (this\n * requires the runtime to include `Reactivity.layer`).\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { useMutation, AsyncResult } from '@thomasfosterau/effect-svelte';\n *   import { Effect } from 'effect';\n *\n *   const addTodo = useMutation(\n *     (title: string) => saveTodo(title),\n *     {\n *       invalidates: ['todos'],\n *       onSuccess: (todo) => console.log('added', todo.id),\n *     },\n *   );\n * </script>\n *\n * <button onclick={() => addTodo.mutate('Buy milk')}>Add</button>\n *\n * {#if AsyncResult.isWaiting(addTodo.current)}\n *   <p>Saving…</p>\n * {/if}\n * ```\n */\nexport function useMutation<A, E, I, R, C = unknown>(\n  fn: (input: I) => Effect.Effect<A, E, R>,\n  options: UseMutationOptions<A, E, I, R, C> = {},\n): UseMutationReturn<A, E, I> {\n  const runtime = options.runtime ?? (getRuntime() as RuntimeLike<R>);\n  const state = makeResult<A, E>();\n  const core = makeMutation(runtime, state, fn, options);\n\n  // Interrupt any in-flight mutation when the component unmounts.\n  $effect(() => () => core.interrupt());\n\n  return {\n    get current() {\n      return state.current;\n    },\n    mutate: core.mutate,\n    reset: core.reset,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEA,SAAgB,YACd,IACA,UAA6C,CAAC,GAClB;CAC5B,MAAM,UAAU,QAAQ,WAAYA,kBAAW;CAC/C,MAAM,QAAQ,WAAiB;CAC/B,MAAM,OAAO,aAAa,SAAS,OAAO,IAAI,OAAO;CAGrD,oBAAoB,KAAK,UAAU,CAAC;CAEpC,OAAO;EACL,IAAI,UAAU;GACZ,OAAO,MAAM;EACf;EACA,QAAQ,KAAK;EACb,OAAO,KAAK;CACd;AACF"}

package/dist/query.svelte.d.ts

@@ -1,7 +1,15 @@
+import { RuntimeLike } from "./internal/run.js";
 import { Effect } from "effect";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 
 //#region src/query.svelte.d.ts
+interface UseQueryOptions<R> {
+  /**
+   * Run against this runtime instead of the ambient context. When provided, the
+   * effect's `R` is constrained to what the runtime provides.
+   */
+  readonly runtime?: RuntimeLike<R>;
+}
 interface UseQueryReturn<A, E> {
   /**
    * The current result state of the query. Refetching preserves the previous
@@ -12,6 +20,17 @@ interface UseQueryReturn<A, E> {
    * Re-fetch the data by re-running the effect
    */
   refetch: () => void;
+  /**
+   * Optimistically overwrite the query's data locally without refetching.
+   * Accepts a value or an updater over the current value (`undefined` if none
+   * yet). The next `refetch` reconciles it with the server.
+   */
+  setData: (updater: A | ((previous: A | undefined) => A)) => void;
+  /**
+   * `true` while showing a previous value during a refetch
+   * (stale-while-revalidate).
+   */
+  readonly isStale: boolean;
 }
 /**
  * Query pattern with refetch capability.
@@ -39,7 +58,7 @@ interface UseQueryReturn<A, E> {
  * {/if}
  * ```
  */
-declare function useQuery<A, E, R>(effect: Effect.Effect<A, E, R>): UseQueryReturn<A, E>;
+declare function useQuery<A, E, R>(effect: Effect.Effect<A, E, R>, options?: UseQueryOptions<R>): UseQueryReturn<A, E>;
 //#endregion
-export { UseQueryReturn, useQuery };
+export { UseQueryOptions, UseQueryReturn, useQuery };
 //# sourceMappingURL=query.svelte.d.ts.map

package/dist/query.svelte.js

@@ -26,13 +26,20 @@ import { useEffect } from "./effect.svelte.js";
 * {/if}
 * ```
 */
-function useQuery(effect) {
-	const effectHook = useEffect(effect, { immediate: true });
+function useQuery(effect, options = {}) {
+	const effectHook = useEffect(effect, {
+		immediate: true,
+		...options
+	});
 	return {
 		get current() {
 			return effectHook.current;
 		},
-		refetch: effectHook.run
+		refetch: effectHook.run,
+		setData: effectHook.setData,
+		get isStale() {
+			return effectHook.isStale;
+		}
 	};
 }
 //#endregion

package/dist/query.svelte.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.svelte.js","names":[],"sources":["../src/query.svelte.ts"],"sourcesContent":["import type { Effect } from \"effect\";\nimport type * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\nimport { useEffect } from \"./effect.svelte.js\";\n\nexport interface UseQueryReturn<A, E> {\n  /**\n   * The current result state of the query. Refetching preserves the previous\n   * value as a waiting `Success` (stale-while-revalidate).\n   */\n  readonly current: AsyncResult.AsyncResult<A, E>;\n\n  /**\n   * Re-fetch the data by re-running the effect\n   */\n  refetch: () => void;\n}\n\n/**\n * Query pattern with refetch capability.\n * Runs the effect immediately on mount and provides a refetch function.\n * Built on top of useEffect with immediate: true.\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { useQuery, AsyncResult } from '@thomasfosterau/effect-svelte';\n *   import { Effect } from 'effect';\n *\n *   const query = useQuery(\n *     Effect.gen(function* () {\n *       const data = yield* fetchData();\n *       return data;\n *     })\n *   );\n * </script>\n *\n * <button onclick={query.refetch}>Refresh</button>\n *\n * {#if AsyncResult.isSuccess(query.current)}\n *   <p>Data: {JSON.stringify(query.current.value)}</p>\n * {/if}\n * ```\n */\nexport function useQuery<A, E, R>(effect: Effect.Effect<A, E, R>): UseQueryReturn<A, E> {\n  const effectHook = useEffect(effect, { immediate: true });\n\n  return {\n    get current() {\n      return effectHook.current;\n    },\n    refetch: effectHook.run,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,SAAgB,SAAkB,QAAsD;CACtF,MAAM,aAAa,UAAU,QAAQ,EAAE,WAAW,KAAK,CAAC;CAExD,OAAO;EACL,IAAI,UAAU;GACZ,OAAO,WAAW;EACpB;EACA,SAAS,WAAW;CACtB;AACF"}
+{"version":3,"file":"query.svelte.js","names":[],"sources":["../src/query.svelte.ts"],"sourcesContent":["import type { Effect } from \"effect\";\nimport type * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\nimport { useEffect } from \"./effect.svelte.js\";\nimport type { RuntimeLike } from \"./internal/run.js\";\n\nexport interface UseQueryOptions<R> {\n  /**\n   * Run against this runtime instead of the ambient context. When provided, the\n   * effect's `R` is constrained to what the runtime provides.\n   */\n  readonly runtime?: RuntimeLike<R>;\n}\n\nexport interface UseQueryReturn<A, E> {\n  /**\n   * The current result state of the query. Refetching preserves the previous\n   * value as a waiting `Success` (stale-while-revalidate).\n   */\n  readonly current: AsyncResult.AsyncResult<A, E>;\n\n  /**\n   * Re-fetch the data by re-running the effect\n   */\n  refetch: () => void;\n\n  /**\n   * Optimistically overwrite the query's data locally without refetching.\n   * Accepts a value or an updater over the current value (`undefined` if none\n   * yet). The next `refetch` reconciles it with the server.\n   */\n  setData: (updater: A | ((previous: A | undefined) => A)) => void;\n\n  /**\n   * `true` while showing a previous value during a refetch\n   * (stale-while-revalidate).\n   */\n  readonly isStale: boolean;\n}\n\n/**\n * Query pattern with refetch capability.\n * Runs the effect immediately on mount and provides a refetch function.\n * Built on top of useEffect with immediate: true.\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { useQuery, AsyncResult } from '@thomasfosterau/effect-svelte';\n *   import { Effect } from 'effect';\n *\n *   const query = useQuery(\n *     Effect.gen(function* () {\n *       const data = yield* fetchData();\n *       return data;\n *     })\n *   );\n * </script>\n *\n * <button onclick={query.refetch}>Refresh</button>\n *\n * {#if AsyncResult.isSuccess(query.current)}\n *   <p>Data: {JSON.stringify(query.current.value)}</p>\n * {/if}\n * ```\n */\nexport function useQuery<A, E, R>(\n  effect: Effect.Effect<A, E, R>,\n  options: UseQueryOptions<R> = {},\n): UseQueryReturn<A, E> {\n  const effectHook = useEffect(effect, { immediate: true, ...options });\n\n  return {\n    get current() {\n      return effectHook.current;\n    },\n    refetch: effectHook.run,\n    setData: effectHook.setData,\n    get isStale() {\n      return effectHook.isStale;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,SAAgB,SACd,QACA,UAA8B,CAAC,GACT;CACtB,MAAM,aAAa,UAAU,QAAQ;EAAE,WAAW;EAAM,GAAG;CAAQ,CAAC;CAEpE,OAAO;EACL,IAAI,UAAU;GACZ,OAAO,WAAW;EACpB;EACA,SAAS,WAAW;EACpB,SAAS,WAAW;EACpB,IAAI,UAAU;GACZ,OAAO,WAAW;EACpB;CACF;AACF"}

package/dist/reactivity.svelte.d.ts

@@ -1,11 +1,21 @@
+import { RuntimeLike } from "./internal/run.js";
 import { Effect } from "effect";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+import { Reactivity } from "effect/unstable/reactivity";
 
 //#region src/reactivity.svelte.d.ts
 interface ReactiveQueryReturn<A, E> {
   /** The current result, re-derived whenever the keys are invalidated. */
   readonly current: AsyncResult.AsyncResult<A, E>;
 }
+interface ReactiveOptions<R> {
+  /**
+   * Run against this runtime instead of the ambient context. Must still provide
+   * `Reactivity.Reactivity`; when provided, the effect's `R` is otherwise
+   * constrained to what the runtime provides.
+   */
+  readonly runtime?: RuntimeLike<R | Reactivity.Reactivity>;
+}
 /**
  * Creates a reactive query that automatically re-runs when the specified keys are invalidated.
  *
@@ -37,7 +47,7 @@ interface ReactiveQueryReturn<A, E> {
  * {/if}
  * ```
  */
-declare function reactiveQuery<A, E, R>(keys: () => ReadonlyArray<unknown>, effectFn: () => Effect.Effect<A, E, R>): ReactiveQueryReturn<A, E>;
+declare function reactiveQuery<A, E, R>(keys: () => ReadonlyArray<unknown>, effectFn: () => Effect.Effect<A, E, R>, options?: ReactiveOptions<R>): ReactiveQueryReturn<A, E>;
 interface ReactiveStreamReturn<A, E> {
   readonly current: AsyncResult.AsyncResult<ReadonlyArray<A>, E>;
   readonly values: ReadonlyArray<A>;
@@ -72,7 +82,7 @@ interface ReactiveStreamReturn<A, E> {
  * </ul>
  * ```
  */
-declare function reactiveStream<A, E, R>(keys: ReadonlyArray<unknown> | (() => ReadonlyArray<unknown>), effect: Effect.Effect<A, E, R> | (() => Effect.Effect<A, E, R>)): ReactiveStreamReturn<A, E>;
+declare function reactiveStream<A, E, R>(keys: ReadonlyArray<unknown> | (() => ReadonlyArray<unknown>), effect: Effect.Effect<A, E, R> | (() => Effect.Effect<A, E, R>), options?: ReactiveOptions<R>): ReactiveStreamReturn<A, E>;
 interface ReactiveMutationReturn<A, E> {
   readonly current: AsyncResult.AsyncResult<A, E>;
   run: () => void;
@@ -101,7 +111,7 @@ interface ReactiveMutationReturn<A, E> {
  * <button onclick={() => updateUser.run()}>Update</button>
  * ```
  */
-declare function reactiveMutation<A, E, R>(keys: ReadonlyArray<unknown> | (() => ReadonlyArray<unknown>), effect: Effect.Effect<A, E, R> | (() => Effect.Effect<A, E, R>)): ReactiveMutationReturn<A, E>;
+declare function reactiveMutation<A, E, R>(keys: ReadonlyArray<unknown> | (() => ReadonlyArray<unknown>), effect: Effect.Effect<A, E, R> | (() => Effect.Effect<A, E, R>), options?: ReactiveOptions<R>): ReactiveMutationReturn<A, E>;
 /**
  * Returns a function that manually invalidates reactivity keys, causing any
  * reactive queries depending on those keys to re-run.
@@ -117,7 +127,7 @@ declare function reactiveMutation<A, E, R>(keys: ReadonlyArray<unknown> | (() =>
  * <button onclick={() => invalidate(['users'])}>Refresh Users</button>
  * ```
  */
-declare function useInvalidateKeys(): (keys: ReadonlyArray<unknown>) => void;
+declare function useInvalidateKeys(options?: ReactiveOptions<never>): (keys: ReadonlyArray<unknown>) => void;
 //#endregion
-export { ReactiveMutationReturn, ReactiveQueryReturn, ReactiveStreamReturn, reactiveMutation, reactiveQuery, reactiveStream, useInvalidateKeys };
+export { ReactiveMutationReturn, ReactiveOptions, ReactiveQueryReturn, ReactiveStreamReturn, reactiveMutation, reactiveQuery, reactiveStream, useInvalidateKeys };
 //# sourceMappingURL=reactivity.svelte.d.ts.map