effect-atom-svelte 0.2.0 → 0.3.0

package/dist/SvelteKit.js

@@ -4,7 +4,9 @@
  *
  * The module does not import SvelteKit: the hooks take the fields of SvelteKit's input they read
  * and return the fields they set, so they type-check against `HandleClientError` and
- * `HandleServerError` once `App.Error` declares `tag?: string`.
+ * `HandleServerError` once `App.Error` declares `tag?: string`. In SvelteKit 2, whose `App.Error`
+ * requires a message, they are typed to return one when there is no `kind`, as they then always
+ * set one.
  *
  * @since 0.1.0
  */
@@ -31,52 +33,17 @@ const body = (message, tag) => {
     }
     return { ...(message ? { message } : {}), ...(tag ? { tag } : {}) };
 };
-/**
- * A client `handleError` hook (`src/hooks.client.ts`) that keeps the message and `_tag` of errors
- * thrown by your code, so a boundary's `failed` snippet shows them instead of
- * `{ status: 500, message: "Internal Error" }`. It logs those errors like SvelteKit's default
- * hook, and leaves `error(...)` and SvelteKit's own errors as they are. Made for SvelteKit 3:
- * SvelteKit 2 doesn't say which errors are its own, so there every error is kept and logged.
- *
- * **Example** (Using it as the client hook)
- *
- * ```ts
- * // src/hooks.client.ts
- * export { handleClientError as handleError } from "effect-atom-svelte/sveltekit";
- * ```
- *
- * @stability unstable
- * @since 0.1.0
- * @category hooks
- */
-export const handleClientError = (input) => {
+export function handleClientError(input) {
     // Destructured here, not in the parameter list, so the API reference shows a named parameter.
     const { error, kind = "unknown" } = input;
     if (kind !== "unknown") {
         return undefined;
     }
     console.error(error);
-    return body(messageOf(error) ?? fallbackMessage(input), tagOf(error));
-};
-/**
- * A server `handleError` hook (`src/hooks.server.ts`) that keeps the `_tag` of errors thrown by
- * your code but not their message, which could expose details of the server to users: the
- * message stays SvelteKit's `"Internal Error"`. It logs errors with `console.error`.
- * Server errors reach a boundary's `failed` snippet when it renders on the server. Made for
- * SvelteKit 3: SvelteKit 2 doesn't say which errors are its own, so there every error is logged.
- *
- * **Example** (Using it as the server hook)
- *
- * ```ts
- * // src/hooks.server.ts
- * export { handleServerError as handleError } from "effect-atom-svelte/sveltekit";
- * ```
- *
- * @stability unstable
- * @since 0.1.0
- * @category hooks
- */
-export const handleServerError = (input) => {
+    // `||`, not `??`: an error with an empty message gets SvelteKit 2's instead.
+    return body(messageOf(error) || fallbackMessage(input), tagOf(error));
+}
+export function handleServerError(input) {
     const { error, issues, kind = "unknown" } = input;
     if (kind === "validation") {
         console.error("Remote function schema validation failed:", issues);
@@ -87,4 +54,4 @@ export const handleServerError = (input) => {
     }
     console.error(error);
     return body(fallbackMessage(input), tagOf(error));
-};
+}

package/dist/index.d.ts

@@ -47,4 +47,4 @@ export * as ScopedAtom from "./ScopedAtom.ts";
  * @since 0.1.0
  * @category re-exports
  */
-export { AsyncResult, Atom, AtomHttpApi, AtomRef, AtomRegistry, AtomRpc, Hydration, } from "effect/reactivity";
+export { AsyncResult, Atom, AtomHttpApi, AtomRef, AtomRegistry, AtomRpc, Hydration, Reactivity, } from "effect/reactivity";

package/dist/index.js

@@ -47,4 +47,4 @@ export * as ScopedAtom from "./ScopedAtom.js";
  * @since 0.1.0
  * @category re-exports
  */
-export { AsyncResult, Atom, AtomHttpApi, AtomRef, AtomRegistry, AtomRpc, Hydration, } from "effect/reactivity";
+export { AsyncResult, Atom, AtomHttpApi, AtomRef, AtomRegistry, AtomRpc, Hydration, Reactivity, } from "effect/reactivity";

package/dist/internal/boundaries.d.ts

@@ -0,0 +1,9 @@
+import type { AtomRegistry } from "effect/reactivity";
+/**
+ * Per registry, key and queued value, how many live boundaries queued it. Boundaries given the
+ * same state, as a layout and its page might be, queue the same values, and one destroyed first
+ * must leave them for the other's children.
+ */
+export declare const queuedBy: WeakMap<AtomRegistry.AtomRegistry, Map<string, Map<unknown, number>>>;
+/** Whether a live boundary brought a value for the key: it sends that value to the browser itself. */
+export declare const queuedByBoundary: (registry: AtomRegistry.AtomRegistry, key: string) => boolean;

package/dist/internal/boundaries.js

@@ -0,0 +1,8 @@
+/**
+ * Per registry, key and queued value, how many live boundaries queued it. Boundaries given the
+ * same state, as a layout and its page might be, queue the same values, and one destroyed first
+ * must leave them for the other's children.
+ */
+export const queuedBy = new WeakMap();
+/** Whether a live boundary brought a value for the key: it sends that value to the browser itself. */
+export const queuedByBoundary = (registry, key) => queuedBy.get(registry)?.has(key) === true;

package/dist/internal/disposal.d.ts

@@ -0,0 +1,13 @@
+import type { AtomRegistry } from "effect/reactivity";
+/** Calls `f` once if `registry` is disposed of through `disposeRegistry`; returns the canceler. */
+export declare const onDispose: (registry: AtomRegistry.AtomRegistry, f: () => void) => (() => void);
+/**
+ * Disposes of `registry`, then runs what waited on it, even when a finalizer the disposal runs
+ * throws.
+ *
+ * In the browser that error is rethrown on a microtask, so it is still reported as uncaught but
+ * stays out of Svelte's teardown: thrown from the `onDestroy` of a component being destroyed, it
+ * escapes Svelte's flush and leaves every `$derived` on the page running again on every read. On
+ * the server it is thrown here.
+ */
+export declare const disposeRegistry: (registry: AtomRegistry.AtomRegistry) => void;

package/dist/internal/disposal.js

@@ -0,0 +1,43 @@
+import { BROWSER } from "esm-env";
+const callbacks = new WeakMap();
+/** Calls `f` once if `registry` is disposed of through `disposeRegistry`; returns the canceler. */
+export const onDispose = (registry, f) => {
+    let set = callbacks.get(registry);
+    if (set === undefined) {
+        set = new Set();
+        callbacks.set(registry, set);
+    }
+    set.add(f);
+    return () => {
+        set.delete(f);
+    };
+};
+/**
+ * Disposes of `registry`, then runs what waited on it, even when a finalizer the disposal runs
+ * throws.
+ *
+ * In the browser that error is rethrown on a microtask, so it is still reported as uncaught but
+ * stays out of Svelte's teardown: thrown from the `onDestroy` of a component being destroyed, it
+ * escapes Svelte's flush and leaves every `$derived` on the page running again on every read. On
+ * the server it is thrown here.
+ */
+export const disposeRegistry = (registry) => {
+    try {
+        registry.dispose();
+    }
+    catch (error) {
+        if (!BROWSER) {
+            throw error;
+        }
+        queueMicrotask(() => {
+            throw error;
+        });
+    }
+    finally {
+        const set = callbacks.get(registry);
+        callbacks.delete(registry);
+        for (const f of set ?? []) {
+            f();
+        }
+    }
+};

package/dist/internal/hydration.d.ts

@@ -6,6 +6,11 @@ export declare const setRevalidateOnHydrate: (value: boolean) => void;
  * provider's, else no (JND-19). Call during component init.
  */
 export declare const revalidatesOnHydrate: (option: boolean | undefined) => boolean;
+/**
+ * What the server sends for a result it doesn't pass on, so the browser computes the atom itself.
+ * An encoded `AsyncResult` is an object, never `null`.
+ */
+export declare const noSeed: null;
 /**
  * Encodes the server's result for the page, or returns the no-seed marker for a result that must
  * not or cannot travel:
@@ -17,8 +22,12 @@ export declare const revalidatesOnHydrate: (option: boolean | undefined) => bool
  *   failing the whole render. Development builds warn.
  */
 export declare const encodeSeed: (key: string, encode: (value: AsyncResult.AsyncResult<unknown, unknown>) => unknown, result: AsyncResult.AsyncResult<unknown, unknown>) => unknown;
-/** The server's result, decoded, or undefined when the server sent none. */
-export declare const decodeSeed: (value: unknown, decode: (value: unknown) => unknown) => unknown;
+/**
+ * The server's result, decoded, or undefined when the server sent none or it doesn't decode with
+ * the browser's schema: the browser then computes the atom itself, as for a result the server
+ * couldn't encode. Development builds warn.
+ */
+export declare const decodeSeed: (key: string, value: unknown, decode: (value: unknown) => unknown) => unknown;
 /**
  * Whether a seed is still waiting, as a stream's result is between its values. The browser runs
  * the atom again from it, as the server's run ended with the render.

package/dist/internal/hydration.js

@@ -19,7 +19,7 @@ export const revalidatesOnHydrate = (option) => option ?? (hasDefault() ? getDef
  * What the server sends for a result it doesn't pass on, so the browser computes the atom itself.
  * An encoded `AsyncResult` is an object, never `null`.
  */
-const noSeed = null;
+export const noSeed = null;
 /**
  * Encodes the server's result for the page, or returns the no-seed marker for a result that must
  * not or cannot travel:
@@ -48,8 +48,28 @@ export const encodeSeed = (key, encode, result) => {
         return noSeed;
     }
 };
-/** The server's result, decoded, or undefined when the server sent none. */
-export const decodeSeed = (value, decode) => (value === noSeed ? undefined : decode(value));
+/**
+ * The server's result, decoded, or undefined when the server sent none or it doesn't decode with
+ * the browser's schema: the browser then computes the atom itself, as for a result the server
+ * couldn't encode. Development builds warn.
+ */
+export const decodeSeed = (key, value, decode) => {
+    if (value === noSeed) {
+        return undefined;
+    }
+    try {
+        return decode(value);
+    }
+    catch (error) {
+        if (!Schema.isSchemaError(error)) {
+            throw error;
+        }
+        if (DEV) {
+            console.warn(`effect-atom-svelte: the server's result for the serializable atom "${key}" doesn't decode with its schema, so the browser computes the atom again.`, error);
+        }
+        return undefined;
+    }
+};
 /**
  * Whether a seed is still waiting, as a stream's result is between its values. The browser runs
  * the atom again from it, as the server's run ended with the render.

package/dist/internal/nodeInternals.d.ts

@@ -14,6 +14,8 @@ export interface NodeHooks {
     readonly dispose: (finalizers: number, value: unknown) => void;
     /** A listener was added or removed; the node's `listeners` hold the new set. */
     readonly readers: () => void;
+    /** The node's remove() has returned. */
+    readonly removed: () => void;
 }
 /** Reports what happens to a node, or returns false if it isn't the implementation this expects. */
 export declare const instrumentNode: (node: AtomRegistry.Node<unknown>, hooks: NodeHooks) => boolean;
@@ -22,3 +24,7 @@ export declare const instrumentNode: (node: AtomRegistry.Node<unknown>, hooks: N
  * which the implementation keeps but the interface doesn't show.
  */
 export declare const defaultIdleTTL: (registry: AtomRegistry.AtomRegistry) => number | undefined;
+/** Whether the node holds an initial value it hasn't computed (setInitialValue on a new node). */
+export declare const holdsInitialValue: (node: AtomRegistry.Node<unknown>) => boolean;
+/** Whether the node is building and its running build has not read `parent` yet. */
+export declare const buildWillRead: (node: AtomRegistry.Node<unknown>, parent: AtomRegistry.Node<unknown>) => boolean;

package/dist/internal/nodeInternals.js

@@ -20,6 +20,13 @@ class Listeners extends Set {
         }
         return this;
     }
+    clear() {
+        const had = this.size > 0;
+        super.clear();
+        if (had) {
+            this.#changed();
+        }
+    }
     delete(listener) {
         const deleted = super.delete(listener);
         if (deleted) {
@@ -33,7 +40,15 @@ export const instrumentNode = (node, hooks) => {
     if (!isNodeImpl(node)) {
         return false;
     }
-    const { build: compute } = node;
+    const { build: compute, remove: removeNode } = node;
+    node.remove = function remove() {
+        try {
+            removeNode.call(this);
+        }
+        finally {
+            hooks.removed();
+        }
+    };
     let value = node._value;
     let { lifetime } = node;
     node.build = function build() {
@@ -81,3 +96,12 @@ export const defaultIdleTTL = (registry) => {
         .defaultIdleTTL;
     return typeof ttl === "number" ? ttl : undefined;
 };
+/** Whether the node holds an initial value it hasn't computed (setInitialValue on a new node). */
+export const holdsInitialValue = (node) => node
+    .preserveInitialValueOnBuild === true;
+/** Whether the node is building and its running build has not read `parent` yet. */
+export const buildWillRead = (node, parent) => {
+    const reads = node.lifetime
+        ?.reads;
+    return reads !== undefined && !reads.has(parent);
+};

package/dist/internal/renderEnd.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Runs `f` once when the server render ends: in `onDestroy`, and failing that when the render's
+ * abort signal fires. A `<svelte:boundary>` with a `failed` snippet discards the content of children
+ * that throw while setting up, and their `onDestroy` callbacks with it, so a component set up before
+ * the throw would otherwise keep its mounts and holds on a caller-owned registry, and the next
+ * request would render this one's initial values (JND-17). On the server `getAbortSignal` returns the
+ * render's signal, which Svelte aborts once every `onDestroy` has run. A dropped component whose
+ * script awaits before calling this resumes after the render has ended and the signal has aborted,
+ * where a listener would never fire, so `f` then runs in a microtask: callers take what `f` releases
+ * synchronously after calling this. Call it during component init. Svelte bug workaround, to be
+ * removed with the fix (https://github.com/jarrednorrisdev/effect-atom-svelte/issues/35).
+ */
+export declare const onRenderEnd: (f: () => void) => void;

package/dist/internal/renderEnd.js

@@ -0,0 +1,34 @@
+// When a server render ends, for the hooks that release what they hold in a registry the caller may
+// keep across requests. Internal: not exported from the package.
+import { getAbortSignal, onDestroy } from "svelte";
+/**
+ * Runs `f` once when the server render ends: in `onDestroy`, and failing that when the render's
+ * abort signal fires. A `<svelte:boundary>` with a `failed` snippet discards the content of children
+ * that throw while setting up, and their `onDestroy` callbacks with it, so a component set up before
+ * the throw would otherwise keep its mounts and holds on a caller-owned registry, and the next
+ * request would render this one's initial values (JND-17). On the server `getAbortSignal` returns the
+ * render's signal, which Svelte aborts once every `onDestroy` has run. A dropped component whose
+ * script awaits before calling this resumes after the render has ended and the signal has aborted,
+ * where a listener would never fire, so `f` then runs in a microtask: callers take what `f` releases
+ * synchronously after calling this. Call it during component init. Svelte bug workaround, to be
+ * removed with the fix (https://github.com/jarrednorrisdev/effect-atom-svelte/issues/35).
+ */
+export const onRenderEnd = (f) => {
+    let done = false;
+    const once = () => {
+        if (!done) {
+            done = true;
+            f();
+        }
+    };
+    onDestroy(once);
+    const signal = getAbortSignal();
+    if (signal.aborted) {
+        // The render already ended, as for a component a failed boundary dropped whose script resumed
+        // after an await. Deferred, as callers register before taking what `f` releases.
+        queueMicrotask(once);
+    }
+    else {
+        signal.addEventListener("abort", once, { once: true });
+    }
+};

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

@@ -0,0 +1,17 @@
+/**
+ * Runs `f` when the component is destroyed, even while its script is still awaiting. In the browser
+ * `onDestroy` only takes effect once the component mounts, so a component removed while pending
+ * would never call it. A pre effect runs during init and is torn down with the component (JND-16).
+ * On the server, `f` runs when the render ends, even for a component a failed boundary dropped.
+ */
+export declare const onTeardown: (f: () => void) => void;
+/**
+ * As `onTeardown`, but for a mounted component `f` runs after its children are destroyed, as with
+ * `onDestroy`: a pre effect is torn down before the children, whose own teardown may still use what
+ * `f` ends, such as a provider's registry. The pre effect only covers a component destroyed before
+ * it mounted. On the server `f` runs through `onRenderEnd`, so `provideRegistry` disposes its
+ * registry even when a failed boundary dropped the provider. A successful render keeps the
+ * children-first order through `onDestroy`; when the render ends without it, `f` may run before
+ * the children's releases, which are then no-ops on the disposed registry.
+ */
+export declare const onTeardownAfterChildren: (f: () => void) => void;

package/dist/internal/teardown.svelte.js

@@ -0,0 +1,44 @@
+// When a component is destroyed, for the hooks and providers. Internal: not exported from the
+// package.
+import { BROWSER } from "esm-env";
+import { onDestroy, onMount } from "svelte";
+import { onRenderEnd } from "./renderEnd.js";
+/**
+ * Runs `f` when the component is destroyed, even while its script is still awaiting. In the browser
+ * `onDestroy` only takes effect once the component mounts, so a component removed while pending
+ * would never call it. A pre effect runs during init and is torn down with the component (JND-16).
+ * On the server, `f` runs when the render ends, even for a component a failed boundary dropped.
+ */
+export const onTeardown = (f) => {
+    if (BROWSER) {
+        $effect.pre(() => f);
+    }
+    else {
+        onRenderEnd(f);
+    }
+};
+/**
+ * As `onTeardown`, but for a mounted component `f` runs after its children are destroyed, as with
+ * `onDestroy`: a pre effect is torn down before the children, whose own teardown may still use what
+ * `f` ends, such as a provider's registry. The pre effect only covers a component destroyed before
+ * it mounted. On the server `f` runs through `onRenderEnd`, so `provideRegistry` disposes its
+ * registry even when a failed boundary dropped the provider. A successful render keeps the
+ * children-first order through `onDestroy`; when the render ends without it, `f` may run before
+ * the children's releases, which are then no-ops on the disposed registry.
+ */
+export const onTeardownAfterChildren = (f) => {
+    if (!BROWSER) {
+        onRenderEnd(f);
+        return;
+    }
+    let mounted = false;
+    $effect.pre(() => () => {
+        if (!mounted) {
+            f();
+        }
+    });
+    onMount(() => {
+        mounted = true;
+    });
+    onDestroy(f);
+};

package/dist/internal/troubleshooting.d.ts

@@ -0,0 +1,2 @@
+/** The sentence that ends an error message: a link to its entry on the troubleshooting page. */
+export declare const troubleshooting: (entry: string) => string;

package/dist/internal/troubleshooting.js

@@ -0,0 +1,3 @@
+// Where error messages point for more. Internal: not exported from the package.
+/** The sentence that ends an error message: a link to its entry on the troubleshooting page. */
+export const troubleshooting = (entry) => `See https://atom.jarrednorris.dev/troubleshooting#${entry}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-atom-svelte",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Community-built Svelte 5 bindings for Effect Atom (not affiliated with the Effect team)",
   "keywords": [
     "effect",