@thomasfosterau/effect-svelte 0.1.0 → 0.3.0

package/dist/await.svelte.d.ts

@@ -0,0 +1,53 @@
+import { RuntimeLike } from "./internal/run.js";
+import { Effect } from "effect";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+
+//#region src/await.svelte.d.ts
+interface UseQueryPromiseOptions<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 UseQueryPromiseReturn<A, E> {
+  /** The underlying query result state (same as {@link useQuery}). */
+  readonly current: AsyncResult.AsyncResult<A, E>;
+  /**
+   * A `Promise` reflecting `current`, for use with Svelte's `{#await}` (or
+   * `<svelte:boundary>`). Its identity is stable until the result transitions:
+   * pending while loading, resolved with the (possibly stale) value, rejected
+   * on failure.
+   */
+  readonly promise: Promise<A>;
+  /** Re-run the effect. A new `promise` is produced as the result transitions. */
+  readonly refetch: () => void;
+}
+/**
+ * Run an effect and bridge its result to Svelte 5's native async, so you can
+ * render it with an `{#await}` block instead of `AsyncResult.match`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useQueryPromise } from '@thomasfosterau/effect-svelte';
+ *   import { Effect } from 'effect';
+ *
+ *   const user = useQueryPromise(fetchUser(1));
+ * </script>
+ *
+ * {#await user.promise}
+ *   <p>Loading…</p>
+ * {:then value}
+ *   <p>{value.name}</p>
+ * {:catch error}
+ *   <p>Failed: {error.message}</p>
+ * {/await}
+ *
+ * <button onclick={user.refetch}>Reload</button>
+ * ```
+ */
+declare function useQueryPromise<A, E, R>(effect: Effect.Effect<A, E, R>, options?: UseQueryPromiseOptions<R>): UseQueryPromiseReturn<A, E>;
+//#endregion
+export { UseQueryPromiseOptions, UseQueryPromiseReturn, useQueryPromise };
+//# sourceMappingURL=await.svelte.d.ts.map

package/dist/await.svelte.js

@@ -0,0 +1,44 @@
+import { resultToPromise } from "./internal/await.js";
+import { useQuery } from "./query.svelte.js";
+//#region src/await.svelte.ts
+/**
+* Run an effect and bridge its result to Svelte 5's native async, so you can
+* render it with an `{#await}` block instead of `AsyncResult.match`.
+*
+* @example
+* ```svelte
+* <script lang="ts">
+*   import { useQueryPromise } from '@thomasfosterau/effect-svelte';
+*   import { Effect } from 'effect';
+*
+*   const user = useQueryPromise(fetchUser(1));
+* <\/script>
+*
+* {#await user.promise}
+*   <p>Loading…</p>
+* {:then value}
+*   <p>{value.name}</p>
+* {:catch error}
+*   <p>Failed: {error.message}</p>
+* {/await}
+*
+* <button onclick={user.refetch}>Reload</button>
+* ```
+*/
+function useQueryPromise(effect, options = {}) {
+	const query = useQuery(effect, options);
+	const promise = $derived(resultToPromise(query.current));
+	return {
+		get current() {
+			return query.current;
+		},
+		get promise() {
+			return promise;
+		},
+		refetch: query.refetch
+	};
+}
+//#endregion
+export { useQueryPromise };
+
+//# sourceMappingURL=await.svelte.js.map

package/dist/await.svelte.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"await.svelte.js","names":[],"sources":["../src/await.svelte.ts"],"sourcesContent":["import type { Effect } from \"effect\";\nimport type * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\nimport { resultToPromise } from \"./internal/await.js\";\nimport type { RuntimeLike } from \"./internal/run.js\";\nimport { useQuery } from \"./query.svelte.js\";\n\nexport interface UseQueryPromiseOptions<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 UseQueryPromiseReturn<A, E> {\n  /** The underlying query result state (same as {@link useQuery}). */\n  readonly current: AsyncResult.AsyncResult<A, E>;\n\n  /**\n   * A `Promise` reflecting `current`, for use with Svelte's `{#await}` (or\n   * `<svelte:boundary>`). Its identity is stable until the result transitions:\n   * pending while loading, resolved with the (possibly stale) value, rejected\n   * on failure.\n   */\n  readonly promise: Promise<A>;\n\n  /** Re-run the effect. A new `promise` is produced as the result transitions. */\n  readonly refetch: () => void;\n}\n\n/**\n * Run an effect and bridge its result to Svelte 5's native async, so you can\n * render it with an `{#await}` block instead of `AsyncResult.match`.\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { useQueryPromise } from '@thomasfosterau/effect-svelte';\n *   import { Effect } from 'effect';\n *\n *   const user = useQueryPromise(fetchUser(1));\n * </script>\n *\n * {#await user.promise}\n *   <p>Loading…</p>\n * {:then value}\n *   <p>{value.name}</p>\n * {:catch error}\n *   <p>Failed: {error.message}</p>\n * {/await}\n *\n * <button onclick={user.refetch}>Reload</button>\n * ```\n */\nexport function useQueryPromise<A, E, R>(\n  effect: Effect.Effect<A, E, R>,\n  options: UseQueryPromiseOptions<R> = {},\n): UseQueryPromiseReturn<A, E> {\n  const query = useQuery(effect, options);\n\n  // Recompute (and only then hand `{#await}` a new promise) when the underlying\n  // result transitions — not on every unrelated re-render.\n  const promise = $derived(resultToPromise(query.current));\n\n  return {\n    get current() {\n      return query.current;\n    },\n    get promise() {\n      return promise;\n    },\n    refetch: query.refetch,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,SAAgB,gBACd,QACA,UAAqC,CAAC,GACT;CAC7B,MAAM,QAAQ,SAAS,QAAQ,OAAO;CAItC,MAAM,UAAU,SAAS,gBAAgB,MAAM,OAAO,CAAC;CAEvD,OAAO;EACL,IAAI,UAAU;GACZ,OAAO,MAAM;EACf;EACA,IAAI,UAAU;GACZ,OAAO;EACT;EACA,SAAS,MAAM;CACjB;AACF"}

package/dist/context.svelte.d.ts

@@ -32,6 +32,56 @@ declare function getRuntimeContext(): RuntimeLike<never>;
  * ```
  */
 declare function provideRuntime<R = never>(runtime?: RuntimeLike<R>): void;
+/**
+ * A dedicated, type-safe runtime context.
+ *
+ * Unlike the shared default context ({@link provideRuntime} / {@link getRuntime},
+ * which is untyped — `RuntimeLike<never>`), each call to `createRuntimeContext`
+ * mints its *own* context instance carrying a fully-typed `RuntimeLike<R>`. A
+ * library whose whole point is a service-typed runtime (e.g.
+ * `ManagedRuntime<ClientView, never>`) can therefore expose its own context
+ * without colliding with the default context or with other libraries, and
+ * `get()` returns the precise `RuntimeLike<R>` rather than `RuntimeLike<never>`.
+ */
+interface RuntimeContext<R> {
+  /**
+   * Provide the runtime to the component subtree. Like `setContext`, this must
+   * be called during component initialisation.
+   */
+  readonly provide: (runtime: RuntimeLike<R>) => void;
+  /**
+   * Retrieve the runtime. Must be called during component initialisation.
+   * Throws an actionable error when no ancestor called `provide`.
+   */
+  readonly get: () => RuntimeLike<R>;
+}
+/**
+ * Create a typed runtime context, built on Svelte's
+ * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) (one
+ * context instance per call).
+ *
+ * @param name - an optional label used in the "runtime not provided" error, to
+ *   help downstream users find the missing `provide` call.
+ *
+ * @example
+ * ```ts
+ * // library.ts — a library exposing a service-typed runtime
+ * import { createRuntimeContext } from '@thomasfosterau/effect-svelte';
+ * import type { ManagedRuntime } from 'effect';
+ * import type { ClientView } from './client.js';
+ *
+ * export const ClientContext =
+ *   createRuntimeContext<ClientView>('@legation/svelte client');
+ * ```
+ * ```svelte
+ * <script lang="ts">
+ *   // Root.svelte
+ *   import { ClientContext } from './library.js';
+ *   ClientContext.provide(myClientRuntime);
+ * </script>
+ * ```
+ */
+declare function createRuntimeContext<R>(name?: string): RuntimeContext<R>;
 //#endregion
-export { getRuntimeContext, provideRuntime };
+export { type RuntimeContext, createRuntimeContext, getRuntimeContext, provideRuntime };
 //# sourceMappingURL=context.svelte.d.ts.map

package/dist/context.svelte.js

@@ -47,7 +47,49 @@ function getRuntimeContext() {
 function provideRuntime(runtime = defaultSvelteRuntime) {
 	provideRuntimeInternal(runtime);
 }
+/**
+* Create a typed runtime context, built on Svelte's
+* [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) (one
+* context instance per call).
+*
+* @param name - an optional label used in the "runtime not provided" error, to
+*   help downstream users find the missing `provide` call.
+*
+* @example
+* ```ts
+* // library.ts — a library exposing a service-typed runtime
+* import { createRuntimeContext } from '@thomasfosterau/effect-svelte';
+* import type { ManagedRuntime } from 'effect';
+* import type { ClientView } from './client.js';
+*
+* export const ClientContext =
+*   createRuntimeContext<ClientView>('@legation/svelte client');
+* ```
+* ```svelte
+* <script lang="ts">
+*   // Root.svelte
+*   import { ClientContext } from './library.js';
+*   ClientContext.provide(myClientRuntime);
+* <\/script>
+* ```
+*/
+function createRuntimeContext(name) {
+	const [get, set] = createContext();
+	const label = name === void 0 ? "this runtime context" : `the "${name}" runtime context`;
+	return {
+		provide(runtime) {
+			set(runtime);
+		},
+		get() {
+			try {
+				return get();
+			} catch {
+				throw new Error(`effect-svelte: No Effect runtime found for ${label}. Call its \`provide(runtime)\` in a parent component during initialisation.`);
+			}
+		}
+	};
+}
 //#endregion
-export { getRuntimeContext, provideRuntime };
+export { createRuntimeContext, getRuntimeContext, provideRuntime };
 
 //# sourceMappingURL=context.svelte.js.map

package/dist/context.svelte.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.svelte.js","names":[],"sources":["../src/context.svelte.ts"],"sourcesContent":["import { createContext } from \"svelte\";\nimport { defaultSvelteRuntime } from \"./runtime.js\";\nimport type { RuntimeLike } from \"./internal/run.js\";\n\n/**\n * Type-safe context for Effect runtime management.\n * Uses Svelte 5's createContext API for better type safety and developer experience.\n *\n * The context accepts either a plain services `Context.Context` (e.g. `Context.empty()`)\n * or a `ManagedRuntime` (e.g. `SvelteRuntime.defaultRuntime` / `SvelteRuntime.extend(...)`).\n * Users must ensure their runtime provides all required services for the effects they run.\n */\nconst [getRuntime, provideRuntimeInternal] = createContext<RuntimeLike<never>>();\n\n/**\n * Retrieves the Effect runtime from Svelte context.\n *\n * @returns The runtime provided via provideRuntime\n * @throws Will throw if called outside of a component with a provided runtime\n */\nfunction getRuntimeContext(): RuntimeLike<never> {\n  const runtime = getRuntime();\n  if (runtime === undefined) {\n    throw new Error(\n      \"effect-svelte: No Effect runtime found in context. \" +\n        \"Make sure you have called provideRuntime() in a parent component.\",\n    );\n  }\n  return runtime;\n}\n\n/**\n * Provides an Effect runtime to the Svelte context tree.\n * This should be called at the root of your component tree, typically in your root layout.\n *\n * The default runtime (SvelteRuntime.defaultRuntime) is recommended for most applications.\n * For applications requiring custom services, extend the runtime using SvelteRuntime.extend().\n *\n * @param runtime - The Effect runtime to provide. Defaults to SvelteRuntime.defaultRuntime\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { provideRuntime, SvelteRuntime } from '@thomasfosterau/effect-svelte';\n *\n *   // Use default runtime\n *   provideRuntime();\n *\n *   // Or provide a custom runtime\n *   const customRuntime = SvelteRuntime.extend(myCustomLayer);\n *   provideRuntime(customRuntime);\n * </script>\n * ```\n */\nfunction provideRuntime<R = never>(\n  runtime: RuntimeLike<R> = defaultSvelteRuntime as RuntimeLike<R>,\n): void {\n  provideRuntimeInternal(runtime as RuntimeLike<never>);\n}\n\nexport { getRuntimeContext as getRuntime, provideRuntime };\nexport type { RuntimeLike };\n"],"mappings":";;;;;;;;;;;AAYA,MAAM,CAAC,YAAY,0BAA0B,cAAkC;;;;;;;AAQ/E,SAAS,oBAAwC;CAC/C,MAAM,UAAU,WAAW;CAC3B,IAAI,YAAY,KAAA,GACd,MAAM,IAAI,MACR,sHAEF;CAEF,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAS,eACP,UAA0B,sBACpB;CACN,uBAAuB,OAA6B;AACtD"}
+{"version":3,"file":"context.svelte.js","names":[],"sources":["../src/context.svelte.ts"],"sourcesContent":["import { createContext } from \"svelte\";\nimport { defaultSvelteRuntime } from \"./runtime.js\";\nimport type { RuntimeLike } from \"./internal/run.js\";\n\n/**\n * Type-safe context for Effect runtime management.\n * Uses Svelte 5's createContext API for better type safety and developer experience.\n *\n * The context accepts either a plain services `Context.Context` (e.g. `Context.empty()`)\n * or a `ManagedRuntime` (e.g. `SvelteRuntime.defaultRuntime` / `SvelteRuntime.extend(...)`).\n * Users must ensure their runtime provides all required services for the effects they run.\n */\nconst [getRuntime, provideRuntimeInternal] = createContext<RuntimeLike<never>>();\n\n/**\n * Retrieves the Effect runtime from Svelte context.\n *\n * @returns The runtime provided via provideRuntime\n * @throws Will throw if called outside of a component with a provided runtime\n */\nfunction getRuntimeContext(): RuntimeLike<never> {\n  const runtime = getRuntime();\n  if (runtime === undefined) {\n    throw new Error(\n      \"effect-svelte: No Effect runtime found in context. \" +\n        \"Make sure you have called provideRuntime() in a parent component.\",\n    );\n  }\n  return runtime;\n}\n\n/**\n * Provides an Effect runtime to the Svelte context tree.\n * This should be called at the root of your component tree, typically in your root layout.\n *\n * The default runtime (SvelteRuntime.defaultRuntime) is recommended for most applications.\n * For applications requiring custom services, extend the runtime using SvelteRuntime.extend().\n *\n * @param runtime - The Effect runtime to provide. Defaults to SvelteRuntime.defaultRuntime\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { provideRuntime, SvelteRuntime } from '@thomasfosterau/effect-svelte';\n *\n *   // Use default runtime\n *   provideRuntime();\n *\n *   // Or provide a custom runtime\n *   const customRuntime = SvelteRuntime.extend(myCustomLayer);\n *   provideRuntime(customRuntime);\n * </script>\n * ```\n */\nfunction provideRuntime<R = never>(\n  runtime: RuntimeLike<R> = defaultSvelteRuntime as RuntimeLike<R>,\n): void {\n  provideRuntimeInternal(runtime as RuntimeLike<never>);\n}\n\n/**\n * A dedicated, type-safe runtime context.\n *\n * Unlike the shared default context ({@link provideRuntime} / {@link getRuntime},\n * which is untyped — `RuntimeLike<never>`), each call to `createRuntimeContext`\n * mints its *own* context instance carrying a fully-typed `RuntimeLike<R>`. A\n * library whose whole point is a service-typed runtime (e.g.\n * `ManagedRuntime<ClientView, never>`) can therefore expose its own context\n * without colliding with the default context or with other libraries, and\n * `get()` returns the precise `RuntimeLike<R>` rather than `RuntimeLike<never>`.\n */\ninterface RuntimeContext<R> {\n  /**\n   * Provide the runtime to the component subtree. Like `setContext`, this must\n   * be called during component initialisation.\n   */\n  readonly provide: (runtime: RuntimeLike<R>) => void;\n\n  /**\n   * Retrieve the runtime. Must be called during component initialisation.\n   * Throws an actionable error when no ancestor called `provide`.\n   */\n  readonly get: () => RuntimeLike<R>;\n}\n\n/**\n * Create a typed runtime context, built on Svelte's\n * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) (one\n * context instance per call).\n *\n * @param name - an optional label used in the \"runtime not provided\" error, to\n *   help downstream users find the missing `provide` call.\n *\n * @example\n * ```ts\n * // library.ts — a library exposing a service-typed runtime\n * import { createRuntimeContext } from '@thomasfosterau/effect-svelte';\n * import type { ManagedRuntime } from 'effect';\n * import type { ClientView } from './client.js';\n *\n * export const ClientContext =\n *   createRuntimeContext<ClientView>('@legation/svelte client');\n * ```\n * ```svelte\n * <script lang=\"ts\">\n *   // Root.svelte\n *   import { ClientContext } from './library.js';\n *   ClientContext.provide(myClientRuntime);\n * </script>\n * ```\n */\nfunction createRuntimeContext<R>(name?: string): RuntimeContext<R> {\n  const [get, set] = createContext<RuntimeLike<R>>();\n  const label = name === undefined ? \"this runtime context\" : `the \"${name}\" runtime context`;\n\n  return {\n    provide(runtime) {\n      set(runtime);\n    },\n    get() {\n      try {\n        return get();\n      } catch {\n        throw new Error(\n          `effect-svelte: No Effect runtime found for ${label}. ` +\n            \"Call its `provide(runtime)` in a parent component during initialisation.\",\n        );\n      }\n    },\n  };\n}\n\nexport { createRuntimeContext, getRuntimeContext as getRuntime, provideRuntime };\nexport type { RuntimeContext, RuntimeLike };\n"],"mappings":";;;;;;;;;;;AAYA,MAAM,CAAC,YAAY,0BAA0B,cAAkC;;;;;;;AAQ/E,SAAS,oBAAwC;CAC/C,MAAM,UAAU,WAAW;CAC3B,IAAI,YAAY,KAAA,GACd,MAAM,IAAI,MACR,sHAEF;CAEF,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAS,eACP,UAA0B,sBACpB;CACN,uBAAuB,OAA6B;AACtD;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAS,qBAAwB,MAAkC;CACjE,MAAM,CAAC,KAAK,OAAO,cAA8B;CACjD,MAAM,QAAQ,SAAS,KAAA,IAAY,yBAAyB,QAAQ,KAAK;CAEzE,OAAO;EACL,QAAQ,SAAS;GACf,IAAI,OAAO;EACb;EACA,MAAM;GACJ,IAAI;IACF,OAAO,IAAI;GACb,QAAQ;IACN,MAAM,IAAI,MACR,8CAA8C,MAAM,6EAEtD;GACF;EACF;CACF;AACF"}

package/dist/derived.svelte.d.ts

@@ -1,7 +1,25 @@
-import { Effect } from "effect";
+import { RuntimeLike } from "./internal/run.js";
+import { Duration, Effect } from "effect";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 
 //#region src/derived.svelte.d.ts
+interface UseDerivedOptions<R = never> {
+  /**
+   * Debounce re-runs by this duration: when a dependency changes, wait this
+   * long before running, and if another change arrives within the window,
+   * restart the wait. The previous value stays visible during the window (the
+   * result only flips to `waiting` once the run actually starts).
+   *
+   * Accepts any Effect `Duration.Input` (e.g. `"300 millis"`, `500`,
+   * `Duration.seconds(1)`).
+   */
+  readonly debounce?: Duration.Input;
+  /**
+   * 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 DerivedReturn<A, E> {
   /**
    * The current result. While re-running after a dependency change, the
@@ -14,30 +32,32 @@ interface DerivedReturn<A, E> {
  * The function parameter is called inside $effect, so it automatically tracks dependencies.
  * When dependencies change, the previous fiber is interrupted and a new one starts.
  *
+ * Pass `{ debounce }` to coalesce rapid dependency changes (e.g. a search box):
+ * interrupting the previous fiber cancels its pending debounce sleep, so only
+ * the last change in a burst actually runs.
+ *
  * @example
  * ```svelte
  * <script lang="ts">
  *   import { useDerived, AsyncResult } from '@thomasfosterau/effect-svelte';
  *   import { Effect } from 'effect';
  *
- *   let userId = $state(1);
+ *   let query = $state('');
  *
- *   const user = useDerived(() =>
- *     Effect.gen(function* () {
- *       const response = yield* fetchUser(userId);
- *       return response;
- *     })
+ *   const results = useDerived(
+ *     () => search(query),
+ *     { debounce: '300 millis' },
  *   );
  * </script>
  *
- * <button onclick={() => userId++}>Next User</button>
+ * <input bind:value={query} />
  *
- * {#if AsyncResult.isSuccess(user.current)}
- *   <p>User: {user.current.value.name}</p>
+ * {#if AsyncResult.isSuccess(results.current)}
+ *   <ul>{#each results.current.value as r}<li>{r}</li>{/each}</ul>
  * {/if}
  * ```
  */
-declare function useDerived<A, E, R>(fn: () => Effect.Effect<A, E, R>): DerivedReturn<A, E>;
+declare function useDerived<A, E, R>(fn: () => Effect.Effect<A, E, R>, options?: UseDerivedOptions<R>): DerivedReturn<A, E>;
 //#endregion
-export { DerivedReturn, useDerived };
+export { DerivedReturn, UseDerivedOptions, useDerived };
 //# sourceMappingURL=derived.svelte.d.ts.map

package/dist/derived.svelte.js

@@ -8,38 +8,48 @@ import { Effect, Fiber } from "effect";
 * The function parameter is called inside $effect, so it automatically tracks dependencies.
 * When dependencies change, the previous fiber is interrupted and a new one starts.
 *
+* Pass `{ debounce }` to coalesce rapid dependency changes (e.g. a search box):
+* interrupting the previous fiber cancels its pending debounce sleep, so only
+* the last change in a burst actually runs.
+*
 * @example
 * ```svelte
 * <script lang="ts">
 *   import { useDerived, AsyncResult } from '@thomasfosterau/effect-svelte';
 *   import { Effect } from 'effect';
 *
-*   let userId = $state(1);
+*   let query = $state('');
 *
-*   const user = useDerived(() =>
-*     Effect.gen(function* () {
-*       const response = yield* fetchUser(userId);
-*       return response;
-*     })
+*   const results = useDerived(
+*     () => search(query),
+*     { debounce: '300 millis' },
 *   );
 * <\/script>
 *
-* <button onclick={() => userId++}>Next User</button>
+* <input bind:value={query} />
 *
-* {#if AsyncResult.isSuccess(user.current)}
-*   <p>User: {user.current.value.name}</p>
+* {#if AsyncResult.isSuccess(results.current)}
+*   <ul>{#each results.current.value as r}<li>{r}</li>{/each}</ul>
 * {/if}
 * ```
 */
-function useDerived(fn) {
-	const runtime = getRuntimeContext();
+function useDerived(fn, options = {}) {
+	const { debounce } = options;
+	const runtime = options.runtime ?? getRuntimeContext();
 	const state = makeResult();
 	let currentFiber = null;
 	$effect(() => {
 		if (currentFiber !== null) interruptFiber(currentFiber);
 		const effect = fn();
-		state.startWaiting();
-		const runningFiber = runFork(runtime)(effect);
+		let runningFiber;
+		if (debounce === void 0) {
+			state.startWaiting();
+			runningFiber = runFork(runtime)(effect);
+		} else runningFiber = runFork(runtime)(Effect.gen(function* () {
+			yield* Effect.sleep(debounce);
+			yield* Effect.sync(() => state.startWaiting());
+			return yield* effect;
+		}));
 		currentFiber = runningFiber;
 		runFork(runtime)(Effect.gen(function* () {
 			const exit = yield* Fiber.await(runningFiber);

package/dist/derived.svelte.js.map

@@ -1 +1 @@
-{"version":3,"file":"derived.svelte.js","names":["getRuntime"],"sources":["../src/derived.svelte.ts"],"sourcesContent":["import { Effect, Fiber } from \"effect\";\nimport type * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\nimport { getRuntime } from \"./context.svelte.js\";\nimport { interruptFiber, runFork, type RuntimeLike } from \"./internal/run.js\";\nimport { makeResult } from \"./internal/result.svelte.js\";\n\nexport interface DerivedReturn<A, E> {\n  /**\n   * The current result. While re-running after a dependency change, the\n   * previous value is kept as a waiting `Success` (stale-while-revalidate).\n   */\n  readonly current: AsyncResult.AsyncResult<A, E>;\n}\n\n/**\n * Re-run an effect whenever reactive dependencies change.\n * The function parameter is called inside $effect, so it automatically tracks dependencies.\n * When dependencies change, the previous fiber is interrupted and a new one starts.\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { useDerived, AsyncResult } from '@thomasfosterau/effect-svelte';\n *   import { Effect } from 'effect';\n *\n *   let userId = $state(1);\n *\n *   const user = useDerived(() =>\n *     Effect.gen(function* () {\n *       const response = yield* fetchUser(userId);\n *       return response;\n *     })\n *   );\n * </script>\n *\n * <button onclick={() => userId++}>Next User</button>\n *\n * {#if AsyncResult.isSuccess(user.current)}\n *   <p>User: {user.current.value.name}</p>\n * {/if}\n * ```\n */\nexport function useDerived<A, E, R>(fn: () => Effect.Effect<A, E, R>): DerivedReturn<A, E> {\n  const runtime = getRuntime() as RuntimeLike<R>;\n\n  const state = makeResult<A, E>();\n  let currentFiber: Fiber.Fiber<A, E> | null = null;\n\n  $effect(() => {\n    // Interrupt previous fiber if it exists\n    if (currentFiber !== null) {\n      interruptFiber(currentFiber);\n    }\n\n    // Get the effect (this tracks reactive dependencies)\n    const effect = fn();\n\n    // Mark as waiting, preserving the previous value if there is one.\n    state.startWaiting();\n\n    // Run the effect and capture the fiber reference\n    const runningFiber = runFork(runtime)(effect);\n    currentFiber = runningFiber;\n\n    // Settle the result when the fiber completes, unless deps changed first.\n    runFork(runtime)(\n      Effect.gen(function* () {\n        const exit = yield* Fiber.await(runningFiber);\n        if (currentFiber === runningFiber) {\n          state.settle(exit);\n          currentFiber = null;\n        }\n      }),\n    );\n\n    // Cleanup: interrupt the fiber when dependencies change or component unmounts\n    return () => {\n      if (currentFiber !== null) {\n        interruptFiber(currentFiber);\n        currentFiber = null;\n      }\n    };\n  });\n\n  return {\n    get current() {\n      return state.current;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,WAAoB,IAAuD;CACzF,MAAM,UAAUA,kBAAW;CAE3B,MAAM,QAAQ,WAAiB;CAC/B,IAAI,eAAyC;CAE7C,cAAc;EAEZ,IAAI,iBAAiB,MACnB,eAAe,YAAY;EAI7B,MAAM,SAAS,GAAG;EAGlB,MAAM,aAAa;EAGnB,MAAM,eAAe,QAAQ,OAAO,EAAE,MAAM;EAC5C,eAAe;EAGf,QAAQ,OAAO,EACb,OAAO,IAAI,aAAa;GACtB,MAAM,OAAO,OAAO,MAAM,MAAM,YAAY;GAC5C,IAAI,iBAAiB,cAAc;IACjC,MAAM,OAAO,IAAI;IACjB,eAAe;GACjB;EACF,CAAC,CACH;EAGA,aAAa;GACX,IAAI,iBAAiB,MAAM;IACzB,eAAe,YAAY;IAC3B,eAAe;GACjB;EACF;CACF,CAAC;CAED,OAAO,EACL,IAAI,UAAU;EACZ,OAAO,MAAM;CACf,EACF;AACF"}
+{"version":3,"file":"derived.svelte.js","names":["getRuntime"],"sources":["../src/derived.svelte.ts"],"sourcesContent":["import { Duration, Effect, Fiber } from \"effect\";\nimport type * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\nimport { getRuntime } from \"./context.svelte.js\";\nimport { interruptFiber, runFork, type RuntimeLike } from \"./internal/run.js\";\nimport { makeResult } from \"./internal/result.svelte.js\";\n\nexport interface UseDerivedOptions<R = never> {\n  /**\n   * Debounce re-runs by this duration: when a dependency changes, wait this\n   * long before running, and if another change arrives within the window,\n   * restart the wait. The previous value stays visible during the window (the\n   * result only flips to `waiting` once the run actually starts).\n   *\n   * Accepts any Effect `Duration.Input` (e.g. `\"300 millis\"`, `500`,\n   * `Duration.seconds(1)`).\n   */\n  readonly debounce?: Duration.Input;\n\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 DerivedReturn<A, E> {\n  /**\n   * The current result. While re-running after a dependency change, the\n   * previous value is kept as a waiting `Success` (stale-while-revalidate).\n   */\n  readonly current: AsyncResult.AsyncResult<A, E>;\n}\n\n/**\n * Re-run an effect whenever reactive dependencies change.\n * The function parameter is called inside $effect, so it automatically tracks dependencies.\n * When dependencies change, the previous fiber is interrupted and a new one starts.\n *\n * Pass `{ debounce }` to coalesce rapid dependency changes (e.g. a search box):\n * interrupting the previous fiber cancels its pending debounce sleep, so only\n * the last change in a burst actually runs.\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { useDerived, AsyncResult } from '@thomasfosterau/effect-svelte';\n *   import { Effect } from 'effect';\n *\n *   let query = $state('');\n *\n *   const results = useDerived(\n *     () => search(query),\n *     { debounce: '300 millis' },\n *   );\n * </script>\n *\n * <input bind:value={query} />\n *\n * {#if AsyncResult.isSuccess(results.current)}\n *   <ul>{#each results.current.value as r}<li>{r}</li>{/each}</ul>\n * {/if}\n * ```\n */\nexport function useDerived<A, E, R>(\n  fn: () => Effect.Effect<A, E, R>,\n  options: UseDerivedOptions<R> = {},\n): DerivedReturn<A, E> {\n  const { debounce } = options;\n  const runtime = options.runtime ?? (getRuntime() as RuntimeLike<R>);\n\n  const state = makeResult<A, E>();\n  let currentFiber: Fiber.Fiber<A, E> | null = null;\n\n  $effect(() => {\n    // Interrupt previous fiber if it exists (this also cancels a pending\n    // debounce sleep, which is what makes debouncing work).\n    if (currentFiber !== null) {\n      interruptFiber(currentFiber);\n    }\n\n    // Get the effect (this tracks reactive dependencies).\n    const effect = fn();\n\n    let runningFiber: Fiber.Fiber<A, E>;\n    if (debounce === undefined) {\n      // Mark as waiting, preserving the previous value if there is one.\n      state.startWaiting();\n      runningFiber = runFork(runtime)(effect);\n    } else {\n      // Wait out the debounce window first; only then flip to waiting and run,\n      // so the previous value stays visible until the run actually begins.\n      runningFiber = runFork(runtime)(\n        Effect.gen(function* () {\n          yield* Effect.sleep(debounce);\n          yield* Effect.sync(() => state.startWaiting());\n          return yield* effect;\n        }),\n      );\n    }\n    currentFiber = runningFiber;\n\n    // Settle the result when the fiber completes, unless deps changed first.\n    runFork(runtime)(\n      Effect.gen(function* () {\n        const exit = yield* Fiber.await(runningFiber);\n        if (currentFiber === runningFiber) {\n          state.settle(exit);\n          currentFiber = null;\n        }\n      }),\n    );\n\n    // Cleanup: interrupt the fiber when dependencies change or component unmounts\n    return () => {\n      if (currentFiber !== null) {\n        interruptFiber(currentFiber);\n        currentFiber = null;\n      }\n    };\n  });\n\n  return {\n    get current() {\n      return state.current;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+DA,SAAgB,WACd,IACA,UAAgC,CAAC,GACZ;CACrB,MAAM,EAAE,aAAa;CACrB,MAAM,UAAU,QAAQ,WAAYA,kBAAW;CAE/C,MAAM,QAAQ,WAAiB;CAC/B,IAAI,eAAyC;CAE7C,cAAc;EAGZ,IAAI,iBAAiB,MACnB,eAAe,YAAY;EAI7B,MAAM,SAAS,GAAG;EAElB,IAAI;EACJ,IAAI,aAAa,KAAA,GAAW;GAE1B,MAAM,aAAa;GACnB,eAAe,QAAQ,OAAO,EAAE,MAAM;EACxC,OAGE,eAAe,QAAQ,OAAO,EAC5B,OAAO,IAAI,aAAa;GACtB,OAAO,OAAO,MAAM,QAAQ;GAC5B,OAAO,OAAO,WAAW,MAAM,aAAa,CAAC;GAC7C,OAAO,OAAO;EAChB,CAAC,CACH;EAEF,eAAe;EAGf,QAAQ,OAAO,EACb,OAAO,IAAI,aAAa;GACtB,MAAM,OAAO,OAAO,MAAM,MAAM,YAAY;GAC5C,IAAI,iBAAiB,cAAc;IACjC,MAAM,OAAO,IAAI;IACjB,eAAe;GACjB;EACF,CAAC,CACH;EAGA,aAAa;GACX,IAAI,iBAAiB,MAAM;IACzB,eAAe,YAAY;IAC3B,eAAe;GACjB;EACF;CACF,CAAC;CAED,OAAO,EACL,IAAI,UAAU;EACZ,OAAO,MAAM;CACf,EACF;AACF"}

package/dist/effect.svelte.d.ts

@@ -1,14 +1,20 @@
+import { RuntimeLike } from "./internal/run.js";
 import { Effect } from "effect";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 
 //#region src/effect.svelte.d.ts
-interface UseEffectOptions {
+interface UseEffectOptions<R = never> {
   /**
    * If true, the effect will run immediately on mount.
    * If false, the effect will only run when manually triggered via run().
    * @default false
    */
   immediate?: boolean;
+  /**
+   * Run against this runtime instead of the ambient context. When provided, the
+   * effect's `R` is constrained to what the runtime provides.
+   */
+  runtime?: RuntimeLike<R>;
 }
 interface UseEffectReturn<A, E> {
   /**
@@ -24,6 +30,19 @@ interface UseEffectReturn<A, E> {
    * Interrupt the currently running effect
    */
   interrupt: () => void;
+  /**
+   * Optimistically overwrite the current value with a non-waiting `Success`,
+   * without running the effect. Accepts a value or an updater function that
+   * receives the current value (`undefined` if there is none yet). Useful for
+   * local cache writes after a mutation, reconciled by the next `run`.
+   */
+  setData: (updater: A | ((previous: A | undefined) => A)) => void;
+  /**
+   * `true` while a previous value is being shown but a re-run is in flight
+   * (stale-while-revalidate) — i.e. the result is `waiting` and still holds a
+   * value.
+   */
+  readonly isStale: boolean;
 }
 /**
  * Run a single Effect and track its result state.
@@ -45,7 +64,7 @@ interface UseEffectReturn<A, E> {
  * {/if}
  * ```
  */
-declare function useEffect<A, E, R>(effect: Effect.Effect<A, E, R>, options?: UseEffectOptions): UseEffectReturn<A, E>;
+declare function useEffect<A, E, R>(effect: Effect.Effect<A, E, R>, options?: UseEffectOptions<R>): UseEffectReturn<A, E>;
 //#endregion
 export { UseEffectOptions, UseEffectReturn, useEffect };
 //# sourceMappingURL=effect.svelte.d.ts.map

package/dist/effect.svelte.js

@@ -1,7 +1,8 @@
 import { getRuntimeContext } from "./context.svelte.js";
 import { interruptFiber, runFork } from "./internal/run.js";
 import { makeResult } from "./internal/result.svelte.js";
-import { Effect, Fiber } from "effect";
+import { Effect, Fiber, Option } from "effect";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 //#region src/effect.svelte.ts
 /**
 * Run a single Effect and track its result state.
@@ -25,7 +26,7 @@ import { Effect, Fiber } from "effect";
 */
 function useEffect(effect, options = {}) {
 	const { immediate = false } = options;
-	const runtime = getRuntimeContext();
+	const runtime = options.runtime ?? getRuntimeContext();
 	const state = makeResult();
 	let currentFiber = null;
 	const run = () => {
@@ -54,12 +55,21 @@ function useEffect(effect, options = {}) {
 			interrupt();
 		};
 	});
+	const setData = (updater) => {
+		const previous = Option.getOrUndefined(AsyncResult.value(state.current));
+		const next = typeof updater === "function" ? updater(previous) : updater;
+		state.succeed(next);
+	};
 	return {
 		get current() {
 			return state.current;
 		},
 		run,
-		interrupt
+		interrupt,
+		setData,
+		get isStale() {
+			return AsyncResult.isWaiting(state.current) && Option.isSome(AsyncResult.value(state.current));
+		}
 	};
 }
 //#endregion

package/dist/effect.svelte.js.map

@@ -1 +1 @@
-{"version":3,"file":"effect.svelte.js","names":["getRuntime"],"sources":["../src/effect.svelte.ts"],"sourcesContent":["import { Effect, Fiber } from \"effect\";\nimport type * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\nimport { getRuntime } from \"./context.svelte.js\";\nimport { interruptFiber, runFork, type RuntimeLike } from \"./internal/run.js\";\nimport { makeResult } from \"./internal/result.svelte.js\";\n\nexport interface UseEffectOptions {\n  /**\n   * If true, the effect will run immediately on mount.\n   * If false, the effect will only run when manually triggered via run().\n   * @default false\n   */\n  immediate?: boolean;\n}\n\nexport interface UseEffectReturn<A, E> {\n  /**\n   * The current result state of the effect. Re-running preserves the previous\n   * value as a waiting `Success` (stale-while-revalidate).\n   */\n  readonly current: AsyncResult.AsyncResult<A, E>;\n\n  /**\n   * Manually trigger execution of the effect\n   */\n  run: () => void;\n\n  /**\n   * Interrupt the currently running effect\n   */\n  interrupt: () => void;\n}\n\n/**\n * Run a single Effect and track its result state.\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { useEffect, AsyncResult } from '@thomasfosterau/effect-svelte';\n *   import { Effect } from 'effect';\n *\n *   const fetchData = useEffect(\n *     Effect.delay(Effect.succeed(42), '1 second'),\n *     { immediate: true }\n *   );\n * </script>\n *\n * {#if AsyncResult.isSuccess(fetchData.current)}\n *   <p>Result: {fetchData.current.value}</p>\n * {/if}\n * ```\n */\nexport function useEffect<A, E, R>(\n  effect: Effect.Effect<A, E, R>,\n  options: UseEffectOptions = {},\n): UseEffectReturn<A, E> {\n  const { immediate = false } = options;\n  const runtime = getRuntime() as RuntimeLike<R>;\n\n  const state = makeResult<A, E>();\n  let currentFiber: Fiber.Fiber<A, E> | null = null;\n\n  const run = () => {\n    // Interrupt any existing fiber\n    if (currentFiber !== null) {\n      interruptFiber(currentFiber);\n    }\n\n    // Mark as waiting, preserving the previous value if there is one.\n    state.startWaiting();\n\n    // Run the effect and capture the fiber reference\n    const runningFiber = runFork(runtime)(effect);\n    currentFiber = runningFiber;\n\n    // Settle the result when the fiber completes, unless a newer run replaced it.\n    runFork(runtime)(\n      Effect.gen(function* () {\n        const exit = yield* Fiber.await(runningFiber);\n        if (currentFiber === runningFiber) {\n          state.settle(exit);\n          currentFiber = null;\n        }\n      }),\n    );\n  };\n\n  const interrupt = () => {\n    if (currentFiber !== null) {\n      interruptFiber(currentFiber);\n      currentFiber = null;\n      // Return to the initial state so the effect can be run again cleanly.\n      state.reset();\n    }\n  };\n\n  // Set up effect lifecycle\n  $effect(() => {\n    if (immediate) {\n      run();\n    }\n\n    // Cleanup: interrupt any running fiber on unmount\n    return () => {\n      interrupt();\n    };\n  });\n\n  return {\n    get current() {\n      return state.current;\n    },\n    run,\n    interrupt,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAgB,UACd,QACA,UAA4B,CAAC,GACN;CACvB,MAAM,EAAE,YAAY,UAAU;CAC9B,MAAM,UAAUA,kBAAW;CAE3B,MAAM,QAAQ,WAAiB;CAC/B,IAAI,eAAyC;CAE7C,MAAM,YAAY;EAEhB,IAAI,iBAAiB,MACnB,eAAe,YAAY;EAI7B,MAAM,aAAa;EAGnB,MAAM,eAAe,QAAQ,OAAO,EAAE,MAAM;EAC5C,eAAe;EAGf,QAAQ,OAAO,EACb,OAAO,IAAI,aAAa;GACtB,MAAM,OAAO,OAAO,MAAM,MAAM,YAAY;GAC5C,IAAI,iBAAiB,cAAc;IACjC,MAAM,OAAO,IAAI;IACjB,eAAe;GACjB;EACF,CAAC,CACH;CACF;CAEA,MAAM,kBAAkB;EACtB,IAAI,iBAAiB,MAAM;GACzB,eAAe,YAAY;GAC3B,eAAe;GAEf,MAAM,MAAM;EACd;CACF;CAGA,cAAc;EACZ,IAAI,WACF,IAAI;EAIN,aAAa;GACX,UAAU;EACZ;CACF,CAAC;CAED,OAAO;EACL,IAAI,UAAU;GACZ,OAAO,MAAM;EACf;EACA;EACA;CACF;AACF"}
+{"version":3,"file":"effect.svelte.js","names":["getRuntime"],"sources":["../src/effect.svelte.ts"],"sourcesContent":["import { Effect, Fiber, Option } from \"effect\";\nimport * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\nimport { getRuntime } from \"./context.svelte.js\";\nimport { interruptFiber, runFork, type RuntimeLike } from \"./internal/run.js\";\nimport { makeResult } from \"./internal/result.svelte.js\";\n\nexport interface UseEffectOptions<R = never> {\n  /**\n   * If true, the effect will run immediately on mount.\n   * If false, the effect will only run when manually triggered via run().\n   * @default false\n   */\n  immediate?: boolean;\n\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  runtime?: RuntimeLike<R>;\n}\n\nexport interface UseEffectReturn<A, E> {\n  /**\n   * The current result state of the effect. Re-running preserves the previous\n   * value as a waiting `Success` (stale-while-revalidate).\n   */\n  readonly current: AsyncResult.AsyncResult<A, E>;\n\n  /**\n   * Manually trigger execution of the effect\n   */\n  run: () => void;\n\n  /**\n   * Interrupt the currently running effect\n   */\n  interrupt: () => void;\n\n  /**\n   * Optimistically overwrite the current value with a non-waiting `Success`,\n   * without running the effect. Accepts a value or an updater function that\n   * receives the current value (`undefined` if there is none yet). Useful for\n   * local cache writes after a mutation, reconciled by the next `run`.\n   */\n  setData: (updater: A | ((previous: A | undefined) => A)) => void;\n\n  /**\n   * `true` while a previous value is being shown but a re-run is in flight\n   * (stale-while-revalidate) — i.e. the result is `waiting` and still holds a\n   * value.\n   */\n  readonly isStale: boolean;\n}\n\n/**\n * Run a single Effect and track its result state.\n *\n * @example\n * ```svelte\n * <script lang=\"ts\">\n *   import { useEffect, AsyncResult } from '@thomasfosterau/effect-svelte';\n *   import { Effect } from 'effect';\n *\n *   const fetchData = useEffect(\n *     Effect.delay(Effect.succeed(42), '1 second'),\n *     { immediate: true }\n *   );\n * </script>\n *\n * {#if AsyncResult.isSuccess(fetchData.current)}\n *   <p>Result: {fetchData.current.value}</p>\n * {/if}\n * ```\n */\nexport function useEffect<A, E, R>(\n  effect: Effect.Effect<A, E, R>,\n  options: UseEffectOptions<R> = {},\n): UseEffectReturn<A, E> {\n  const { immediate = false } = options;\n  const runtime = options.runtime ?? (getRuntime() as RuntimeLike<R>);\n\n  const state = makeResult<A, E>();\n  let currentFiber: Fiber.Fiber<A, E> | null = null;\n\n  const run = () => {\n    // Interrupt any existing fiber\n    if (currentFiber !== null) {\n      interruptFiber(currentFiber);\n    }\n\n    // Mark as waiting, preserving the previous value if there is one.\n    state.startWaiting();\n\n    // Run the effect and capture the fiber reference\n    const runningFiber = runFork(runtime)(effect);\n    currentFiber = runningFiber;\n\n    // Settle the result when the fiber completes, unless a newer run replaced it.\n    runFork(runtime)(\n      Effect.gen(function* () {\n        const exit = yield* Fiber.await(runningFiber);\n        if (currentFiber === runningFiber) {\n          state.settle(exit);\n          currentFiber = null;\n        }\n      }),\n    );\n  };\n\n  const interrupt = () => {\n    if (currentFiber !== null) {\n      interruptFiber(currentFiber);\n      currentFiber = null;\n      // Return to the initial state so the effect can be run again cleanly.\n      state.reset();\n    }\n  };\n\n  // Set up effect lifecycle\n  $effect(() => {\n    if (immediate) {\n      run();\n    }\n\n    // Cleanup: interrupt any running fiber on unmount\n    return () => {\n      interrupt();\n    };\n  });\n\n  const setData = (updater: A | ((previous: A | undefined) => A)): void => {\n    const previous = Option.getOrUndefined(AsyncResult.value(state.current));\n    const next =\n      typeof updater === \"function\"\n        ? (updater as (previous: A | undefined) => A)(previous)\n        : updater;\n    state.succeed(next);\n  };\n\n  return {\n    get current() {\n      return state.current;\n    },\n    run,\n    interrupt,\n    setData,\n    get isStale() {\n      return (\n        AsyncResult.isWaiting(state.current) && Option.isSome(AsyncResult.value(state.current))\n      );\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,UACd,QACA,UAA+B,CAAC,GACT;CACvB,MAAM,EAAE,YAAY,UAAU;CAC9B,MAAM,UAAU,QAAQ,WAAYA,kBAAW;CAE/C,MAAM,QAAQ,WAAiB;CAC/B,IAAI,eAAyC;CAE7C,MAAM,YAAY;EAEhB,IAAI,iBAAiB,MACnB,eAAe,YAAY;EAI7B,MAAM,aAAa;EAGnB,MAAM,eAAe,QAAQ,OAAO,EAAE,MAAM;EAC5C,eAAe;EAGf,QAAQ,OAAO,EACb,OAAO,IAAI,aAAa;GACtB,MAAM,OAAO,OAAO,MAAM,MAAM,YAAY;GAC5C,IAAI,iBAAiB,cAAc;IACjC,MAAM,OAAO,IAAI;IACjB,eAAe;GACjB;EACF,CAAC,CACH;CACF;CAEA,MAAM,kBAAkB;EACtB,IAAI,iBAAiB,MAAM;GACzB,eAAe,YAAY;GAC3B,eAAe;GAEf,MAAM,MAAM;EACd;CACF;CAGA,cAAc;EACZ,IAAI,WACF,IAAI;EAIN,aAAa;GACX,UAAU;EACZ;CACF,CAAC;CAED,MAAM,WAAW,YAAwD;EACvE,MAAM,WAAW,OAAO,eAAe,YAAY,MAAM,MAAM,OAAO,CAAC;EACvE,MAAM,OACJ,OAAO,YAAY,aACd,QAA2C,QAAQ,IACpD;EACN,MAAM,QAAQ,IAAI;CACpB;CAEA,OAAO;EACL,IAAI,UAAU;GACZ,OAAO,MAAM;EACf;EACA;EACA;EACA;EACA,IAAI,UAAU;GACZ,OACE,YAAY,UAAU,MAAM,OAAO,KAAK,OAAO,OAAO,YAAY,MAAM,MAAM,OAAO,CAAC;EAE1F;CACF;AACF"}

package/dist/index.d.ts

@@ -1,14 +1,19 @@
 import { RuntimeLike } from "./internal/run.js";
-import { getRuntimeContext, provideRuntime } from "./context.svelte.js";
+import { RuntimeContext, createRuntimeContext, getRuntimeContext, provideRuntime } from "./context.svelte.js";
 import { SvelteRuntime, defaultSvelteRuntime } from "./runtime.js";
 import { useScope, useScopeCallback } from "./scope.svelte.js";
 import { UseEffectOptions, UseEffectReturn, useEffect } from "./effect.svelte.js";
-import { UseStreamReturn, useStream } from "./stream.svelte.js";
-import { DerivedReturn, useDerived } from "./derived.svelte.js";
-import { UseQueryReturn, useQuery } from "./query.svelte.js";
-import { UsePubSubReturn, UseSubscriptionRefReturn, usePubSub, useSubscriptionRef } from "./subscription.svelte.js";
-import { ReactiveMutationReturn, ReactiveQueryReturn, ReactiveStreamReturn, reactiveMutation, reactiveQuery, reactiveStream, useInvalidateKeys } from "./reactivity.svelte.js";
+import { UseStreamOptions, UseStreamReturn, useStream } from "./stream.svelte.js";
+import { UseLiveStreamOptions, UseLiveStreamReturn, useLiveStream } from "./live-stream.svelte.js";
+import { DerivedReturn, UseDerivedOptions, useDerived } from "./derived.svelte.js";
+import { UseQueryOptions, UseQueryReturn, useQuery } from "./query.svelte.js";
+import { MutationCallbacks } from "./internal/mutation.js";
+import { UseMutationOptions, UseMutationReturn, useMutation } from "./mutation.svelte.js";
+import { UseQueryPromiseOptions, UseQueryPromiseReturn, useQueryPromise } from "./await.svelte.js";
+import { UsePubSubOptions, UsePubSubReturn, UseSubscriptionRefOptions, UseSubscriptionRefReturn, usePubSub, useSubscriptionRef } from "./subscription.svelte.js";
+import { UseWritableRefOptions, UseWritableRefReturn, useWritableRef } from "./writable-ref.svelte.js";
+import { ReactiveMutationReturn, ReactiveOptions, ReactiveQueryReturn, ReactiveStreamReturn, reactiveMutation, reactiveQuery, reactiveStream, useInvalidateKeys } from "./reactivity.svelte.js";
 import { SignalEmitter } from "./emitter.js";
 import { Store_d_exports } from "./Store.js";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
-export { AsyncResult, type DerivedReturn, type ReactiveMutationReturn, type ReactiveQueryReturn, type ReactiveStreamReturn, type RuntimeLike, SignalEmitter, Store_d_exports as Store, SvelteRuntime, type UseEffectOptions, type UseEffectReturn, type UsePubSubReturn, type UseQueryReturn, type UseStreamReturn, type UseSubscriptionRefReturn, defaultSvelteRuntime, getRuntimeContext as getRuntime, provideRuntime, reactiveMutation, reactiveQuery, reactiveStream, useDerived, useEffect, useInvalidateKeys, usePubSub, useQuery, useScope, useScopeCallback, useStream, useSubscriptionRef };
+export { AsyncResult, type DerivedReturn, type MutationCallbacks, type ReactiveMutationReturn, type ReactiveOptions, type ReactiveQueryReturn, type ReactiveStreamReturn, type RuntimeContext, type RuntimeLike, SignalEmitter, Store_d_exports as Store, SvelteRuntime, type UseDerivedOptions, type UseEffectOptions, type UseEffectReturn, type UseLiveStreamOptions, type UseLiveStreamReturn, type UseMutationOptions, type UseMutationReturn, type UsePubSubOptions, type UsePubSubReturn, type UseQueryOptions, type UseQueryPromiseOptions, type UseQueryPromiseReturn, type UseQueryReturn, type UseStreamOptions, type UseStreamReturn, type UseSubscriptionRefOptions, type UseSubscriptionRefReturn, type UseWritableRefOptions, type UseWritableRefReturn, createRuntimeContext, defaultSvelteRuntime, getRuntimeContext as getRuntime, provideRuntime, reactiveMutation, reactiveQuery, reactiveStream, useDerived, useEffect, useInvalidateKeys, useLiveStream, useMutation, usePubSub, useQuery, useQueryPromise, useScope, useScopeCallback, useStream, useSubscriptionRef, useWritableRef };

package/dist/index.js

@@ -1,13 +1,17 @@
 import { SvelteRuntime, defaultSvelteRuntime } from "./runtime.js";
-import { getRuntimeContext, provideRuntime } from "./context.svelte.js";
+import { createRuntimeContext, getRuntimeContext, provideRuntime } from "./context.svelte.js";
 import { useScope, useScopeCallback } from "./scope.svelte.js";
 import { useEffect } from "./effect.svelte.js";
 import { useStream } from "./stream.svelte.js";
+import { useLiveStream } from "./live-stream.svelte.js";
 import { useDerived } from "./derived.svelte.js";
 import { useQuery } from "./query.svelte.js";
+import { useMutation } from "./mutation.svelte.js";
+import { useQueryPromise } from "./await.svelte.js";
 import { usePubSub, useSubscriptionRef } from "./subscription.svelte.js";
+import { useWritableRef } from "./writable-ref.svelte.js";
 import { reactiveMutation, reactiveQuery, reactiveStream, useInvalidateKeys } from "./reactivity.svelte.js";
 import { SignalEmitter } from "./emitter.js";
 import { Store_exports } from "./Store.js";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
-export { AsyncResult, SignalEmitter, Store_exports as Store, SvelteRuntime, defaultSvelteRuntime, getRuntimeContext as getRuntime, provideRuntime, reactiveMutation, reactiveQuery, reactiveStream, useDerived, useEffect, useInvalidateKeys, usePubSub, useQuery, useScope, useScopeCallback, useStream, useSubscriptionRef };
+export { AsyncResult, SignalEmitter, Store_exports as Store, SvelteRuntime, createRuntimeContext, defaultSvelteRuntime, getRuntimeContext as getRuntime, provideRuntime, reactiveMutation, reactiveQuery, reactiveStream, useDerived, useEffect, useInvalidateKeys, useLiveStream, useMutation, usePubSub, useQuery, useQueryPromise, useScope, useScopeCallback, useStream, useSubscriptionRef, useWritableRef };

package/dist/internal/await.js

@@ -0,0 +1,52 @@
+import { Cause, Option } from "effect";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+//#region src/internal/await.ts
+/**
+* Convert an {@link AsyncResult.AsyncResult} into a `Promise`, so Effect-backed
+* state can drive Svelte 5's native async (`{#await}` blocks and
+* `<svelte:boundary>` suspense), which both consume a real thenable.
+*
+* Mapping:
+* - **Failure** → a rejected promise (with the typed error `E` when present,
+*   otherwise the squashed cause). Checked first, so a failure that carries a
+*   previous success still surfaces the error in the `{:catch}` block.
+* - **Holds a value** (a `Success`, including a waiting one during
+*   stale-while-revalidate) → a resolved promise, so the UI keeps showing data
+*   while a refresh is in flight.
+* - **Initial / waiting with no value** → a perpetually-pending promise, so the
+*   `{#await}` loading branch (or the boundary's `pending` snippet) shows.
+*
+* Callers should memoise the result (e.g. via `$derived`) so a fresh pending
+* promise is not produced on unrelated re-renders — a new promise identity is
+* only wanted when the underlying result transitions.
+*/
+function resultToPromise(result) {
+	if (AsyncResult.isFailure(result)) {
+		const cause = AsyncResult.cause(result);
+		return rejected(Option.isSome(cause) ? Option.match(Cause.findErrorOption(cause.value), {
+			onNone: () => Cause.squash(cause.value),
+			onSome: (error) => error
+		}) : /* @__PURE__ */ new Error("AsyncResult failure with no cause"));
+	}
+	const value = AsyncResult.value(result);
+	if (Option.isSome(value)) return Promise.resolve(value.value);
+	return new Promise(() => {});
+}
+/**
+* A rejected promise whose rejection is pre-observed with a no-op handler.
+*
+* Failures are surfaced as rejected promises from a `$derived`; a reactive
+* re-render can produce (and then discard) such a promise before anything
+* `await`s it. The no-op `catch` keeps that discarded value from tripping
+* Node's `unhandledRejection` warning, while the returned promise still rejects
+* for every real consumer (the `catch` runs on a separate branch).
+*/
+function rejected(reason) {
+	const promise = Promise.reject(reason);
+	promise.catch(() => {});
+	return promise;
+}
+//#endregion
+export { resultToPromise };
+
+//# sourceMappingURL=await.js.map

package/dist/internal/await.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"await.js","names":[],"sources":["../../src/internal/await.ts"],"sourcesContent":["import { Cause, Option } from \"effect\";\nimport * as AsyncResult from \"effect/unstable/reactivity/AsyncResult\";\n\n/**\n * Convert an {@link AsyncResult.AsyncResult} into a `Promise`, so Effect-backed\n * state can drive Svelte 5's native async (`{#await}` blocks and\n * `<svelte:boundary>` suspense), which both consume a real thenable.\n *\n * Mapping:\n * - **Failure** → a rejected promise (with the typed error `E` when present,\n *   otherwise the squashed cause). Checked first, so a failure that carries a\n *   previous success still surfaces the error in the `{:catch}` block.\n * - **Holds a value** (a `Success`, including a waiting one during\n *   stale-while-revalidate) → a resolved promise, so the UI keeps showing data\n *   while a refresh is in flight.\n * - **Initial / waiting with no value** → a perpetually-pending promise, so the\n *   `{#await}` loading branch (or the boundary's `pending` snippet) shows.\n *\n * Callers should memoise the result (e.g. via `$derived`) so a fresh pending\n * promise is not produced on unrelated re-renders — a new promise identity is\n * only wanted when the underlying result transitions.\n */\nexport function resultToPromise<A, E>(result: AsyncResult.AsyncResult<A, E>): Promise<A> {\n  if (AsyncResult.isFailure(result)) {\n    const cause = AsyncResult.cause(result);\n    const reason = Option.isSome(cause)\n      ? Option.match(Cause.findErrorOption(cause.value), {\n          onNone: () => Cause.squash(cause.value),\n          onSome: (error) => error,\n        })\n      : new Error(\"AsyncResult failure with no cause\");\n    return rejected(reason);\n  }\n\n  const value = AsyncResult.value(result);\n  if (Option.isSome(value)) return Promise.resolve(value.value);\n\n  // Initial / waiting with no value yet: stay pending.\n  return new Promise<A>(() => {});\n}\n\n/**\n * A rejected promise whose rejection is pre-observed with a no-op handler.\n *\n * Failures are surfaced as rejected promises from a `$derived`; a reactive\n * re-render can produce (and then discard) such a promise before anything\n * `await`s it. The no-op `catch` keeps that discarded value from tripping\n * Node's `unhandledRejection` warning, while the returned promise still rejects\n * for every real consumer (the `catch` runs on a separate branch).\n */\nfunction rejected<A>(reason: unknown): Promise<A> {\n  const promise = Promise.reject<A>(reason);\n  promise.catch(() => {});\n  return promise;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,gBAAsB,QAAmD;CACvF,IAAI,YAAY,UAAU,MAAM,GAAG;EACjC,MAAM,QAAQ,YAAY,MAAM,MAAM;EAOtC,OAAO,SANQ,OAAO,OAAO,KAAK,IAC9B,OAAO,MAAM,MAAM,gBAAgB,MAAM,KAAK,GAAG;GAC/C,cAAc,MAAM,OAAO,MAAM,KAAK;GACtC,SAAS,UAAU;EACrB,CAAC,oBACD,IAAI,MAAM,mCAAmC,CAC3B;CACxB;CAEA,MAAM,QAAQ,YAAY,MAAM,MAAM;CACtC,IAAI,OAAO,OAAO,KAAK,GAAG,OAAO,QAAQ,QAAQ,MAAM,KAAK;CAG5D,OAAO,IAAI,cAAiB,CAAC,CAAC;AAChC;;;;;;;;;;AAWA,SAAS,SAAY,QAA6B;CAChD,MAAM,UAAU,QAAQ,OAAU,MAAM;CACxC,QAAQ,YAAY,CAAC,CAAC;CACtB,OAAO;AACT"}