effect-atom-svelte 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jarred Norris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# effect-atom-svelte
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Svelte 5 bindings for Effect Atom (`effect/reactivity`): hooks with a reactive `current`, async atoms you can `await` in markup, and server rendering with hydration. The API follows `@effect/atom-react`.
+
+This is a community project by Jarred Norris. It is not part of Effect, and the Effect team neither makes nor endorses it. Most of its code and docs were written with the help of AI (Claude Opus 5.5); its behavior is covered by tests in Chromium, Firefox and WebKit.
+
+**Documentation: [atom.jarrednorris.dev](https://atom.jarrednorris.dev)** · [API reference](https://atom.jarrednorris.dev/reference) · [GitHub](https://github.com/jarrednorrisdev/effect-atom-svelte)
+
+## Requirements
+
+- `effect` 4.0.x. The peer range is `~4.0.0`, not `^4.0.0`: the bindings use parts of the atom registry that aren't public API, which a minor release of `effect` can change.
+- Svelte 5.57.2 or later. `experimental.async` is needed for `useAtomSuspense`, `useAtomResult` and server rendering.
+- SvelteKit is optional. The docs site and its tests run on SvelteKit 3. On SvelteKit 2, the error hooks in `effect-atom-svelte/sveltekit` work with less detail.
+
+## Installation
+
+```sh
+npm install effect-atom-svelte "effect@~4.0.0"
+```
+
+Turn on Svelte's async mode. In SvelteKit 3, pass it to `sveltekit()` in `vite.config.ts`:
+
+```ts
+// vite.config.ts
+sveltekit({
+  compilerOptions: { experimental: { async: true } },
+});
+```
+
+Then put a registry around your app, in the root layout:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script lang="ts">
+  import { RegistryProvider } from "effect-atom-svelte";
+
+  const { children } = $props();
+</script>
+
+<RegistryProvider>{@render children()}</RegistryProvider>
+```
+
+On the server, the provider creates a registry for each request, so visitors never see each other's state. Without one, the server throws `No AtomRegistry in context`. [Installation](https://atom.jarrednorris.dev/installation) covers the registry options and apps without SvelteKit.
+
+## Example
+
+```svelte
+<script module lang="ts">
+  import { Effect } from "effect";
+  import { Atom } from "effect/reactivity";
+
+  const countAtom = Atom.make(0);
+  const doubledAtom = Atom.make((get) => get(countAtom) * 2);
+  const greetingAtom = Atom.make(
+    Effect.succeed("Hello from an Effect").pipe(Effect.delay("1 second"))
+  );
+</script>
+
+<script lang="ts">
+  import { useAtom, useAtomSuspense, useAtomValue } from "effect-atom-svelte";
+
+  const count = useAtom(countAtom);
+  const doubled = useAtomValue(doubledAtom);
+  const greeting = useAtomSuspense(greetingAtom);
+</script>
+
+<button onclick={() => (count.current += 1)}>{count.current} × 2 = {doubled.current}</button>
+
+<svelte:boundary>
+  <p>{await greeting.current}</p>
+  {#snippet pending()}<p>Loading…</p>{/snippet}
+  {#snippet failed()}<p>Something went wrong</p>{/snippet}
+</svelte:boundary>
+```
+
+Hooks return an object whose `current` you read, assign or `bind:` to. Don't destructure `current`: `const { current } = useAtomValue(atom)` reads once and never updates. Coming from `@effect/atom-react`? See [Migrating from atom-react](https://atom.jarrednorris.dev/migrating-from-react).
+
+## Learn more
+
+- [Your first atom](https://atom.jarrednorris.dev/first-atom), [Reading and writing](https://atom.jarrednorris.dev/reading-and-writing) and [Async atoms](https://atom.jarrednorris.dev/async-atoms)
+- [Server rendering](https://atom.jarrednorris.dev/server-rendering) and [Hydration](https://atom.jarrednorris.dev/hydration)
+- [Effect RPC](https://atom.jarrednorris.dev/rpc) and [HttpApi](https://atom.jarrednorris.dev/http)
+- [API reference](https://atom.jarrednorris.dev/reference) and [Troubleshooting](https://atom.jarrednorris.dev/troubleshooting)
+- [Every export at a glance, and more recipes](https://github.com/jarrednorrisdev/effect-atom-svelte#api-at-a-glance), in the repository's README
+
+## Versioning
+
+The package is at 0.x, so a minor release can change the API. Every change is listed in the [changelog](https://github.com/jarrednorrisdev/effect-atom-svelte/blob/main/packages/effect-atom-svelte/CHANGELOG.md).
+
+## License
+
+[MIT](https://github.com/jarrednorrisdev/effect-atom-svelte/blob/main/LICENSE)

package/dist/Hooks.svelte.d.ts

@@ -0,0 +1,396 @@
+/**
+ * Hooks that read, write and await atoms from Svelte 5 components.
+ *
+ * @since 0.1.0
+ */
+import { Exit } from "effect";
+import { AsyncResult, Atom } from "effect/reactivity";
+import type { AtomRef } from "effect/reactivity";
+/**
+ * An atom, or a getter so the hook follows the atom when reactive state picks a different one.
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category models
+ */
+export type AtomInput<A> = A | (() => A);
+/**
+ * A reactive read-only value. Read `.current` in markup, `$derived` or `$effect` to track it.
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category models
+ */
+export interface AtomValue<A> {
+    readonly current: A;
+}
+/**
+ * A reactive value that can also be assigned, so `bind:value={state.current}` works.
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category models
+ */
+export interface AtomState<R, W = R> {
+    get current(): R;
+    set current(value: W);
+}
+/**
+ * How a setter from `useAtomSet` reports back: not at all, with the result, or with the `Exit`.
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category models
+ */
+export type WriteMode = "value" | "promise" | "promiseExit";
+/**
+ * Options for a promise-mode setter call.
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category models
+ */
+export interface WriteOptions {
+    readonly signal?: AbortSignal | undefined;
+}
+/**
+ * Reads an atom, optionally through a transform. The atom stays mounted while something reactive
+ * reads `.current`, and unmounted when nothing does. The transform runs again only when the atom,
+ * or state the transform reads, changes, so a transform that builds an object returns the same
+ * object until then. A read outside a reactive context, such as in an event handler, runs it again.
+ *
+ * **Example** (Reading an atom through a transform)
+ *
+ * ```ts
+ * import { useAtomValue } from "effect-atom-svelte";
+ * import { countAtom } from "./atoms.ts";
+ *
+ * const doubled = useAtomValue(countAtom, (count) => count * 2);
+ * // In the markup: {doubled.current}
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category hooks
+ */
+export declare function useAtomValue<A>(input: AtomInput<Atom.Atom<A>>): AtomValue<A>;
+export declare function useAtomValue<A, B>(input: AtomInput<Atom.Atom<A>>, f: (value: A) => B): AtomValue<B>;
+/**
+ * Reads and writes a writable atom through `.current`, so `bind:value={state.current}` works.
+ *
+ * **Example** (Binding an input to an atom)
+ *
+ * ```ts
+ * import { useAtom } from "effect-atom-svelte";
+ * import { nameAtom } from "./atoms.ts";
+ *
+ * const name = useAtom(nameAtom);
+ * // In the markup: <input bind:value={name.current} />
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category hooks
+ */
+export declare const useAtom: <R, W>(input: AtomInput<Atom.Writable<R, W>>) => AtomState<R, W>;
+/**
+ * Keeps an atom alive for as long as this component is mounted, even when no component reads
+ * it. Use it in a component that outlives the readers, such as a layout, so the atom keeps its
+ * value while they come and go. Mounting an atom that hasn't been computed also computes it.
+ *
+ * **Example** (Keeping a connection open while a component is mounted)
+ *
+ * ```ts
+ * import { useAtomMount } from "effect-atom-svelte";
+ * import { socketAtom } from "./atoms.ts";
+ *
+ * // Not disposed while this component lives, even though nothing reads it.
+ * useAtomMount(socketAtom);
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category hooks
+ */
+export declare const useAtomMount: (input: AtomInput<Atom.Atom<unknown>>) => void;
+/**
+ * Returns a setter. The atom is mounted for the component's lifetime, so an `Atom.fn` keeps its
+ * state between calls and is not disposed between set and read.
+ *
+ * In `value` mode a function passed to the setter is an updater, called with the current value. To
+ * store a function in an atom, wrap it: `set(() => handler)`.
+ *
+ * In `promise` and `promiseExit` modes the setter waits for the atom's next settled result. The
+ * wait holds the atom, so a call still in flight keeps it running after the component is
+ * destroyed, until it settles. The call's `signal` cancels only the wait: an `Atom.fn` already
+ * running keeps going (send `Atom.Interrupt` to stop it). A signal that is already aborted settles
+ * the call as interrupted without writing, as `fetch` does. Calls on one `Atom.fn` share its single
+ * result, so a new call supersedes one in flight and every pending call resolves with the latest
+ * call's result. `Atom.Reset` has no result to wait for, so these modes leave it out of their
+ * types and reject it; reset with a `value` mode setter.
+ *
+ * **Example** (Updating an atom from its current value)
+ *
+ * ```ts
+ * import { useAtomSet } from "effect-atom-svelte";
+ * import { countAtom } from "./atoms.ts";
+ *
+ * const setCount = useAtomSet(countAtom);
+ * // In the markup: <button onclick={() => setCount((n) => n + 1)}>+</button>
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category hooks
+ */
+export declare function useAtomSet<R, W>(input: AtomInput<Atom.Writable<R, W>>, options?: {
+    readonly mode?: "value" | undefined;
+}): (value: W | ((current: R) => W)) => void;
+export declare function useAtomSet<A, E, W>(input: AtomInput<Atom.Writable<AsyncResult.AsyncResult<A, E>, W>>, options: {
+    readonly mode: "promise";
+}): (value: Exclude<W, Atom.Reset>, options?: WriteOptions) => Promise<A>;
+export declare function useAtomSet<A, E, W>(input: AtomInput<Atom.Writable<AsyncResult.AsyncResult<A, E>, W>>, options: {
+    readonly mode: "promiseExit";
+}): (value: Exclude<W, Atom.Reset>, options?: WriteOptions) => Promise<Exit.Exit<A, E>>;
+export declare function useAtomSet<A, E, W>(input: AtomInput<Atom.Writable<AsyncResult.AsyncResult<A, E>, W>>, options?: {
+    readonly mode?: WriteMode | undefined;
+}): (value: W, options?: WriteOptions) => undefined | Promise<A> | Promise<Exit.Exit<A, E>>;
+/**
+ * Returns a function that runs the atom again. The atom is mounted so the refresh is not lost.
+ *
+ * **Example** (Running an atom again on click)
+ *
+ * ```ts
+ * import { useAtomRefresh } from "effect-atom-svelte";
+ * import { dieAtom } from "./atoms.ts";
+ *
+ * const roll = useAtomRefresh(dieAtom);
+ * // In the markup: <button onclick={roll}>Roll</button>
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category hooks
+ */
+export declare const useAtomRefresh: (input: AtomInput<Atom.Atom<unknown>>) => (() => void);
+/**
+ * Calls `f` on every change while the component lives, and with the current value first when
+ * `immediate` is set. The atom is computed once the component mounts, and never on the server, so a
+ * derived or effect atom that nothing else reads still runs and reports its changes. A change raised while another component
+ * is reading an atom reaches `f` on a microtask, so `f` can write `$state` (Svelte forbids that
+ * during a read). Changes after it wait their turn, so `f` sees every change in order; any other
+ * change reaches it synchronously. Nothing reaches `f` once the component is destroyed, not even a
+ * change still waiting for its microtask.
+ *
+ * **Example** (Saving every change)
+ *
+ * ```ts
+ * import { useAtomSubscribe } from "effect-atom-svelte";
+ * import { draftAtom } from "./atoms.ts";
+ *
+ * useAtomSubscribe(draftAtom, (draft) => localStorage.setItem("draft", draft));
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category hooks
+ */
+export declare const useAtomSubscribe: <A>(input: AtomInput<Atom.Atom<A>>, f: (value: A) => void, options?: {
+    readonly immediate?: boolean | undefined;
+}) => void;
+/**
+ * Sets starting values as `AtomRegistry.make({ initialValues })` would: on the atom that receives it
+ * (a wrapper such as `withRefresh` passes it to its source), kept as the value of the atom's first
+ * build, which still reads and follows the atom's sources. The atoms are not computed here: each
+ * keeps its value, uncomputed, while this component lives, and the first component to read it
+ * computes it from there, so a value set in a layout is still there when a page reads it later, and
+ * an atom that can only compute in the browser can start from a value on the server.
+ *
+ * A value applies once while the atom is held, so a component mounted later, or a second
+ * component with its own value, does not overwrite a value the atom has moved on from. Once nothing
+ * holds the atom and the registry disposes it, the next component to start it applies its value
+ * again. On the server a value lasts one render, so each request against a shared registry applies
+ * its own; requests rendering at the same time share the registry's atoms, and with them the value
+ * the first one applied.
+ *
+ * **Example** (Starting an atom from a prop)
+ *
+ * ```ts
+ * import { untrack } from "svelte";
+ * import { useAtomInitialValues, useAtomValue } from "effect-atom-svelte";
+ * import { countAtom } from "./atoms.ts";
+ *
+ * const { start } = $props();
+ * // Only the first value counts, so untrack says a later change to the prop is not followed.
+ * useAtomInitialValues([[countAtom, untrack(() => start)]]);
+ * const count = useAtomValue(countAtom);
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category hooks
+ */
+export declare const useAtomInitialValues: (initialValues: Iterable<readonly [Atom.Atom<unknown>, unknown]>) => void;
+/**
+ * Reads an `AtomRef`, following it when the getter returns a different ref. For one property of a
+ * ref, use `useAtomRefPropValue`.
+ *
+ * A ref has no registry. On the server, one created at module level is shared by every request,
+ * so don't write a visitor's data to it there: see
+ * https://atom.jarrednorris.dev/server-rendering#module-state-is-shared-between-visitors
+ *
+ * **Example** (Reading a ref)
+ *
+ * ```ts
+ * import { useAtomRef } from "effect-atom-svelte";
+ * import { profile } from "./refs.ts";
+ *
+ * const current = useAtomRef(profile);
+ * // In the markup: {current.current.name}
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category hooks
+ */
+export declare const useAtomRef: <A>(input: AtomInput<AtomRef.ReadonlyRef<A>>) => AtomValue<A>;
+/**
+ * Returns `ref.prop(prop)`, the `AtomRef` for one property of an `AtomRef`. It takes the ref
+ * itself, not a getter, and does not follow later changes to `ref` or `prop`; to read a property
+ * of a ref picked by a getter, use `useAtomRefPropValue`.
+ *
+ * **Example** (Writing one property of a ref)
+ *
+ * ```ts
+ * import { useAtomRefProp } from "effect-atom-svelte";
+ * import { profile } from "./refs.ts";
+ *
+ * const name = useAtomRefProp(profile, "name");
+ * const rename = (next: string) => name.set(next); // profile.value.name changes too
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category hooks
+ */
+export declare const useAtomRefProp: <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K) => AtomRef.AtomRef<A[K]>;
+/**
+ * Reads one property of an `AtomRef`, following the getter to a different ref. `prop` is taken
+ * once, when the component starts, and is not followed.
+ *
+ * **Example** (Reading one property of a ref)
+ *
+ * ```ts
+ * import { useAtomRefPropValue } from "effect-atom-svelte";
+ * import { profile } from "./refs.ts";
+ *
+ * const name = useAtomRefPropValue(profile, "name");
+ * // In the markup: {name.current}
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category hooks
+ */
+export declare const useAtomRefPropValue: <A, K extends keyof A>(input: AtomInput<AtomRef.AtomRef<A>>, prop: K) => AtomValue<A[K]>;
+/**
+ * Options for `useAtomResult`.
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category models
+ */
+export interface ResultOptions {
+    /** Treat a refreshing result as pending, so the first await also waits for the refresh. */
+    readonly suspendOnWaiting?: boolean | undefined;
+    /**
+     * Run a server-rendered atom again once the page has hydrated. Overrides `RegistryProvider`'s
+     * `revalidateOnHydrate`, which defaults to `false`.
+     */
+    readonly revalidateOnHydrate?: boolean | undefined;
+}
+/**
+ * Awaits an async atom's first result, then returns a live handle to its `AsyncResult`. Use it as
+ * a top-level `await` in a component script; server rendering waits for it, and with a
+ * serialization key the browser starts from the server's result instead of running the atom
+ * again. With a getter, only the first atom is awaited: when the getter picks another atom the
+ * handle follows it, starting from that atom's current result (often `Initial`), and the
+ * component's await does not run again. On the server, an atom with a `withServerValue` override
+ * reads as that value and is never computed. An atom that has not started, whose result is
+ * `Initial` with nothing running, as an `Atom.fn` nothing has called, keeps the await pending in the
+ * browser until something writes it; on the server, where nothing will during the render, the
+ * await rejects.
+ *
+ * **Example** (Awaiting an atom picked by a prop)
+ *
+ * ```ts
+ * import { useAtomResult } from "effect-atom-svelte";
+ * import { todoAtom } from "./atoms.ts";
+ *
+ * const { id } = $props();
+ * const todo = await useAtomResult(() => todoAtom(id));
+ * // todo.current is the AsyncResult, a Success or a Failure by now
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category async
+ */
+export declare const useAtomResult: <A, E>(input: AtomInput<Atom.Atom<AsyncResult.AsyncResult<A, E>>>, options?: ResultOptions) => Promise<AtomValue<AsyncResult.AsyncResult<A, E>>>;
+/**
+ * Options for `useAtomSuspense`.
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category models
+ */
+export interface SuspenseOptions {
+    /**
+     * Treat a refreshing result as pending, so `await` waits for the refreshed value instead of
+     * resolving with the current one. The boundary keeps showing its content meanwhile; use
+     * `$effect.pending()` to show progress.
+     */
+    readonly suspendOnWaiting?: boolean | undefined;
+    /** Resolve with the Success or Failure result instead of the value, rather than rejecting. */
+    readonly includeFailure?: boolean | undefined;
+    /**
+     * Run a server-rendered atom again once the page has hydrated. Overrides `RegistryProvider`'s
+     * `revalidateOnHydrate`, which defaults to `false`.
+     */
+    readonly revalidateOnHydrate?: boolean | undefined;
+}
+/**
+ * Exposes an async atom as a promise for `await` in markup or `$derived(await ...)`. The promise is
+ * stable while the result is unchanged, and a new one is issued when the result changes, so Svelte
+ * re-runs dependents only on real updates. Unchanged means the same atom and the same result
+ * object: a refresh issues a new promise even if its value is equal, and so does a read after
+ * every reader of a pending promise went away, as that wait was interrupted. Failures reject with the squashed cause, or resolve with
+ * the `Failure` when `includeFailure` is set. On the server, an atom with a `withServerValue`
+ * override resolves from that value and is never computed; if the value is `Initial`, the promise
+ * rejects, so read it inside a `<svelte:boundary>` with a `pending` snippet. An atom that has not
+ * started, whose result is `Initial` with nothing running, as an `Atom.fn` nothing has called,
+ * stays pending in the browser until something writes it, and rejects on the server.
+ *
+ * **Example** (Awaiting an atom in the markup)
+ *
+ * ```ts
+ * import { useAtomSuspense } from "effect-atom-svelte";
+ * import { todosAtom } from "./atoms.ts";
+ *
+ * const todos = useAtomSuspense(todosAtom);
+ * // In the markup, inside a <svelte:boundary>: {#each await todos.current as todo}
+ * ```
+ *
+ * @stability unstable
+ * @since 0.1.0
+ * @category async
+ */
+export declare function useAtomSuspense<A, E>(input: AtomInput<Atom.Atom<AsyncResult.AsyncResult<A, E>>>, options?: SuspenseOptions & {
+    readonly includeFailure?: false | undefined;
+}): AtomValue<Promise<A>>;
+export declare function useAtomSuspense<A, E>(input: AtomInput<Atom.Atom<AsyncResult.AsyncResult<A, E>>>, options: SuspenseOptions & {
+    readonly includeFailure: true;
+}): AtomValue<Promise<AsyncResult.Success<A, E> | AsyncResult.Failure<A, E>>>;
+export declare function useAtomSuspense<A, E>(input: AtomInput<Atom.Atom<AsyncResult.AsyncResult<A, E>>>, options?: SuspenseOptions & {
+    readonly includeFailure?: boolean | undefined;
+}): AtomValue<Promise<A | AsyncResult.Success<A, E> | AsyncResult.Failure<A, E>>>;