effect-atom-svelte 0.1.2 → 0.3.0

package/dist/HydrationBoundary.svelte

@@ -1,13 +1,22 @@
 <!--
   @component
   Hydrates dehydrated atom state, for example from `Hydration.dehydrate` returned by a remote
-  function. Atoms new to the registry are hydrated before children render; in the browser, atoms
-  that already exist are updated after render, so current UI does not jump to the incoming data
-  mid-render. On the server, where nothing renders again, they are updated at once.
+  function. Atoms new to the registry, or holding only an initial value nobody has read yet, are
+  hydrated before children render; in the browser, atoms that already exist are updated after
+  render, so current UI does not jump to the incoming data mid-render. On the server, where nothing
+  renders again, and in the browser while it hydrates the server's markup, they are updated at once.
+  That needs Svelte's `experimental.async`: without it, the browser can't tell that it is hydrating,
+  and atoms that already exist, as one read above the boundary, are updated after the first render.
+
+  With `experimental.async` on, custom server rendering must `await render(...)`, as SvelteKit does,
+  so the boundary's `hydratable` entry is written into the page. Otherwise a production build of
+  Svelte logs `hydratable_missing_but_expected` once per boundary as the page hydrates.
 
   A value for an atom nobody reads waits in the registry until something does. When the boundary
   is destroyed, as at the end of a server render, the values it brought that are still unread are
-  dropped, so a registry that outlives the boundary doesn't hand them to a later reader.
+  dropped, as is a promise-encoded value that lands afterwards, so a registry that outlives the
+  boundary doesn't hand them to a later reader. In the browser, a reader that already held the atom
+  when the boundary ended and still holds it, as a layout's reader above it, gets the late value.
 
   **Example** (Hydrating the state a load function dehydrated)
 
@@ -28,10 +37,15 @@
 -->
 <script lang="ts">
   import { Hydration } from "effect/reactivity";
+  import type { AtomRegistry } from "effect/reactivity";
   import { BROWSER } from "esm-env";
-  import { onDestroy } from "svelte";
+  import { hydratable } from "svelte";
   import type { Snippet } from "svelte";
 
+  import { queuedBy } from "./internal/boundaries.js";
+  import { holdsInitialValue } from "./internal/nodeInternals.js";
+  import { onRenderEnd } from "./internal/renderEnd.js";
+  import { onTeardownAfterChildren } from "./internal/teardown.svelte.js";
   import { getRegistry } from "./RegistryContext.js";
 
   interface Props {
@@ -49,14 +63,93 @@
   };
   // The values this boundary queued, by key, so it can drop the ones nobody took.
   const queued = new Map<string, unknown>();
+  // Whether the boundary has ended, as at the end of the server render or once the browser destroys
+  // it, after which a late promise-encoded value is dropped.
+  let ended = false;
+
+  const counts =
+    queuedBy.get(registry) ?? new Map<string, Map<unknown, number>>();
+  queuedBy.set(registry, counts);
+  /** Adds one to or takes one from the boundaries queueing a value, and returns the new count. */
+  const count = (key: string, value: unknown, delta: 1 | -1): number => {
+    const byValue = counts.get(key) ?? new Map<unknown, number>();
+    counts.set(key, byValue);
+    const next = (byValue.get(value) ?? 0) + delta;
+    if (next > 0) {
+      byValue.set(value, next);
+    } else {
+      byValue.delete(value);
+      if (byValue.size === 0) {
+        counts.delete(key);
+      }
+    }
+    return next;
+  };
+
+  // SAFETY: Hydration.hydrate ignores a promise-encoded value that resolves to this marker, which
+  // Hydration.ts registers with Symbol.for (Effect 4.0.1) but doesn't export.
+  const skipped = Symbol.for("effect/reactivity/Hydration/Skipped");
+  // The keys of the promise-encoded values the boundary is waiting for.
+  const waiting = new Set<string>();
+  // In the browser, the node that held each of those keys when the boundary ended. That node, as a
+  // layout's reader above the boundary that took its waiting value, still needs the result, or it
+  // waits forever. A node a later reader creates doesn't get it, nor does one that replaced a node
+  // swept since, as a reader inside the boundary's is just after it ends.
+  const nodesAtEnd = new Map<string, AtomRegistry.Node<unknown>>();
+  /** A promise-encoded value as the boundary waits for it; one landing after the boundary ends is skipped. */
+  const lateDropped = async (
+    key: string,
+    late: Promise<unknown>
+  ): Promise<unknown> => {
+    waiting.add(key);
+    const value = await late;
+    if (!ended) {
+      return value;
+    }
+    const held = BROWSER ? nodesAtEnd.get(key) : undefined;
+    return held !== undefined && registry.getNodes().get(key) === held
+      ? value
+      : skipped;
+  };
 
   const queue = (atoms: readonly Hydration.DehydratedAtomValue[]): void => {
-    Hydration.hydrate(registry, atoms);
+    // A promise-encoded value landing after the boundary has ended, after the server render or once
+    // the browser has navigated away, would stay queued in a registry that outlives it for a later
+    // reader, however late: it is ignored once the boundary ends, unless, in the browser, the node
+    // that held its key then still does.
+    Hydration.hydrate(
+      registry,
+      atoms.map((atom) =>
+        atom.resultPromise === undefined
+          ? atom
+          : {
+              ...atom,
+              resultPromise: lateDropped(atom.key, atom.resultPromise),
+            }
+      )
+    );
     for (const { key, value } of atoms) {
+      if (queued.has(key)) {
+        if (queued.get(key) === value) {
+          continue;
+        }
+        count(key, queued.get(key), -1);
+      }
       queued.set(key, value);
+      count(key, value, 1);
     }
   };
 
+  /**
+   * Whether a node's value may be on the page already. A node holding only an initial value nobody
+   * has read, as RegistryProvider's initialValues leave it, shows nowhere yet: it takes the incoming
+   * value before children render, as on the server, so the browser's first render matches the
+   * server's markup.
+   */
+  const shown = (node: AtomRegistry.Node<unknown> | undefined): boolean =>
+    node !== undefined &&
+    !(holdsInitialValue(node) && node.currentState() === "stale");
+
   const hydrateNew = (
     incoming: Iterable<Hydration.DehydratedAtom> | undefined
   ): Hydration.DehydratedAtomValue[] => {
@@ -64,7 +157,7 @@
     const fresh: Hydration.DehydratedAtomValue[] = [];
     const existing: Hydration.DehydratedAtomValue[] = [];
     for (const atom of Hydration.toValues([...(incoming ?? [])])) {
-      (nodes.has(atom.key) ? existing : fresh).push(atom);
+      (shown(nodes.get(atom.key)) ? existing : fresh).push(atom);
     }
     queue(fresh);
     return existing;
@@ -91,8 +184,18 @@
   // svelte-ignore state_referenced_locally
   let deferred = hydrateNew(state);
   // Effects don't run on the server, and nothing there renders again, so the atoms that already
-  // exist are updated now, before the children read them.
-  if (!BROWSER) {
+  // exist are updated now, before the children read them. The browser does the same while it
+  // hydrates the server's markup, so its first render matches the server's. The server writes true;
+  // the browser reads it only while hydrating, and false otherwise. hydratable throws in development
+  // for a key the server didn't write, as for a boundary the server didn't render: that is false too.
+  const hydratingServerMarkup = (() => {
+    try {
+      return hydratable("effect-atom-svelte/HydrationBoundary", () => !BROWSER);
+    } catch {
+      return false;
+    }
+  })();
+  if (!BROWSER || hydratingServerMarkup) {
     hydrateExisting(deferred);
     deferred = [];
   }
@@ -111,13 +214,28 @@
 
   // A queued value stays in the registry until its key is looked up. With a registry that outlives
   // the boundary, such as one the caller passes to the server's provider, it would reach a later
-  // request. Drop the ones still waiting, unless something queued another value since.
-  onDestroy(() => {
+  // request. Drop the ones still waiting, unless something queued another value since or another
+  // live boundary queued the same one. On the server they're dropped when the render ends, even if
+  // a failed boundary discarded this one; in the browser, also when it is destroyed while pending.
+  (BROWSER ? onTeardownAfterChildren : onRenderEnd)(() => {
+    if (ended) {
+      return;
+    }
+    ended = true;
+    if (BROWSER) {
+      const nodes = registry.getNodes();
+      for (const key of waiting) {
+        const node = nodes.get(key);
+        if (node) {
+          nodesAtEnd.set(key, node);
+        }
+      }
+    }
     if (!preloaded) {
       return;
     }
     for (const [key, value] of queued) {
-      if (preloaded.get(key) === value) {
+      if (count(key, value, -1) <= 0 && preloaded.get(key) === value) {
         preloaded.delete(key);
       }
     }

package/dist/HydrationBoundary.svelte.d.ts

@@ -6,13 +6,22 @@ interface Props {
 }
 /**
  * Hydrates dehydrated atom state, for example from `Hydration.dehydrate` returned by a remote
- * function. Atoms new to the registry are hydrated before children render; in the browser, atoms
- * that already exist are updated after render, so current UI does not jump to the incoming data
- * mid-render. On the server, where nothing renders again, they are updated at once.
+ * function. Atoms new to the registry, or holding only an initial value nobody has read yet, are
+ * hydrated before children render; in the browser, atoms that already exist are updated after
+ * render, so current UI does not jump to the incoming data mid-render. On the server, where nothing
+ * renders again, and in the browser while it hydrates the server's markup, they are updated at once.
+ * That needs Svelte's `experimental.async`: without it, the browser can't tell that it is hydrating,
+ * and atoms that already exist, as one read above the boundary, are updated after the first render.
+ *
+ * With `experimental.async` on, custom server rendering must `await render(...)`, as SvelteKit does,
+ * so the boundary's `hydratable` entry is written into the page. Otherwise a production build of
+ * Svelte logs `hydratable_missing_but_expected` once per boundary as the page hydrates.
  *
  * A value for an atom nobody reads waits in the registry until something does. When the boundary
  * is destroyed, as at the end of a server render, the values it brought that are still unread are
- * dropped, so a registry that outlives the boundary doesn't hand them to a later reader.
+ * dropped, as is a promise-encoded value that lands afterwards, so a registry that outlives the
+ * boundary doesn't hand them to a later reader. In the browser, a reader that already held the atom
+ * when the boundary ended and still holds it, as a layout's reader above it, gets the late value.
  *
  * **Example** (Hydrating the state a load function dehydrated)
  *

package/dist/Inspector.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Watches what an atom registry does, for developer tools: every node added and removed, every
+ * computation and why it ran, every value, reader, interruption and finalizer.
+ *
+ * Nothing is watched until `inspect` is called. In development, the registries an app provides
+ * (and the default browser registry) are listed by `registries`, so a tool can find them without
+ * being handed one.
+ *
+ * @since 0.2.0
+ */
+import { Atom } from "effect/reactivity";
+import type { AtomRegistry } from "effect/reactivity";
+import type { ReadKind } from "./internal/scope.svelte.ts";
+/**
+ * Why a node computed its value.
+ *
+ * - `FirstRead`: its first computation.
+ * - `ParentChanged`: atoms it read changed since its last computation; `parents` are those nodes.
+ * - `Refreshed`: `registry.refresh` (or `useAtomRefresh`) asked for it, or for an atom it wraps.
+ *   A signal that refreshes the atom (`refreshOnWindowFocus`, `makeRefreshOnSignal`, `swr`) calls
+ *   `registry.refresh` too, so it is reported the same way.
+ * - `Invalidated`: something else made it stale, such as the atom refreshing itself (`refreshSelf`)
+ *   or a reactivity key.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export type BuildCause = {
+    readonly _tag: "FirstRead";
+} | {
+    readonly _tag: "ParentChanged";
+    readonly parents: readonly AtomRegistry.Node<unknown>[];
+} | {
+    readonly _tag: "Refreshed";
+} | {
+    readonly _tag: "Invalidated";
+};
+/**
+ * Where a node's new value came from.
+ *
+ * - `build`: its computation returned it.
+ * - `write`: `registry.set`, `update` or `modify` (which the write hooks use), on it or on a
+ *   writable atom that wrote it, and another atom's `get.set`, which goes through `registry.set`.
+ * - `async`: anything else, such as an effect settling or a stream emitting after the computation
+ *   returned.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export type UpdateSource = "build" | "write" | "async";
+/**
+ * Something a registry did to one of its nodes. `time` is from `performance.now()`.
+ *
+ * - `NodeAdded`: an atom was read, mounted or written for the first time, or again after it was
+ *   removed, and the registry made a node for it.
+ * - `Built`: the node is about to compute its value, for the `cause` given.
+ * - `Updated`: its value changed. `first` marks its first value, which has no `previous`.
+ * - `ReadersChanged`: a listener was added or removed; `readers` is how many it has now. Hooks,
+ *   `registry.subscribe` and `mount`, and atoms that subscribe to others all count.
+ * - `Interrupted`: its effect hadn't finished when what its computation started was torn down, so
+ *   the fiber was interrupted. Followed by `Finalized`. Not reported for an `Atom.runtime` atom,
+ *   whose layer build isn't interrupted. An effect atom made with `{ uninterruptible: true }` is
+ *   reported all the same, though its fiber keeps running: the inspector can't tell it apart.
+ * - `Finalized`: what its last computation started was torn down, before it computes again or as
+ *   it is removed; `finalizers` ran.
+ * - `NodeRemoved`: the registry disposed of the node, as nothing read it any more.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export type Event = {
+    readonly node: AtomRegistry.Node<unknown>;
+    readonly time: number;
+} & ({
+    readonly _tag: "NodeAdded";
+} | {
+    readonly _tag: "Built";
+    readonly cause: BuildCause;
+} | {
+    readonly _tag: "Updated";
+    readonly first: boolean;
+    readonly previous: unknown;
+    readonly value: unknown;
+    readonly source: UpdateSource;
+} | {
+    readonly _tag: "ReadersChanged";
+    readonly readers: number;
+} | {
+    readonly _tag: "Interrupted";
+} | {
+    readonly _tag: "Finalized";
+    readonly finalizers: number;
+} | {
+    readonly _tag: "NodeRemoved";
+});
+/**
+ * What `inspect` returns for a registry.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export interface Inspector {
+    readonly registry: AtomRegistry.AtomRegistry;
+    /**
+     * Calls `listener` with each event as it happens; returns the function that stops it. Events
+     * arrive in the middle of the registry's work, so a listener must not read or write atoms, nor
+     * write Svelte state: queue the event and handle it later, for example on the next animation
+     * frame.
+     */
+    readonly subscribe: (listener: (event: Event) => void) => () => void;
+    /**
+     * How long an atom nobody reads is kept before it is removed, in milliseconds: its own idle TTL,
+     * or the registry's default. `undefined` for an atom kept alive, and for one removed as soon as
+     * its last reader goes.
+     */
+    readonly idleTTL: (atom: Atom.Atom<unknown>) => number | undefined;
+    /**
+     * `false` when the registry's nodes aren't the implementation the inspector was written against
+     * (a later Effect, say). Then only `NodeAdded` and `NodeRemoved` are reported.
+     */
+    readonly complete: boolean;
+}
+/**
+ * Starts watching a registry, and returns its inspector: the same one each time it is called for
+ * the same registry.
+ *
+ * Until then a registry runs as it always does. From then on, in a registry made by Effect 4.0,
+ * each node reports what happens to it, which costs a little on every read and write, so call it
+ * from developer tools rather than from the app.
+ *
+ * Nodes the registry already holds are watched from now on; what happened to them before isn't
+ * known. Read them with `registry.getNodes()`.
+ *
+ * **Example** (Logging every computation)
+ *
+ * ```ts
+ * import { getRegistry } from "effect-atom-svelte";
+ * import { inspect } from "effect-atom-svelte/inspector";
+ *
+ * const events = [];
+ * inspect(getRegistry()).subscribe((event) => events.push(event));
+ * setInterval(() => {
+ *   for (const event of events.splice(0)) {
+ *     if (event._tag === "Built") {
+ *       console.log(event.node.atom.label?.[0], event.cause._tag);
+ *     }
+ *   }
+ * }, 1000);
+ * ```
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category inspecting
+ */
+export declare const inspect: (registry: AtomRegistry.AtomRegistry) => Inspector;
+/**
+ * The registries the app has in the browser during development: each one a `RegistryProvider` or
+ * `provideRegistry` gives its children, while it is mounted, and the default browser registry once
+ * something has used it. Empty on the server and in production builds.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category inspecting
+ */
+export declare const registries: () => readonly AtomRegistry.AtomRegistry[];
+/**
+ * Calls `f` with `registries()` now and whenever it changes, as providers mount and unmount;
+ * returns the function that stops it.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category inspecting
+ */
+export declare const watchRegistries: (f: (registries: readonly AtomRegistry.AtomRegistry[]) => void) => (() => void);
+/**
+ * How a component uses an atom it reports to a scope: `read` (`useAtomValue`, `useAtom`,
+ * `useAtomResult`, `useAtomSuspense`), `mount` (`useAtomMount`), `subscribe`
+ * (`useAtomSubscribe`) or `write` (`useAtomSet`, which holds the atom mounted to write it).
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export type ReaderKind = ReadKind;
+/**
+ * A hook in the scope's part of the component tree that uses an atom. `component` and `file` name
+ * the component it is in, when the atomLabels plugin of effect-atom-svelte-devtools (or
+ * `nameComponent`) names components; `instance` tells two instances of one component apart.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export interface ScopeReader {
+    readonly id: number;
+    readonly kind: ReaderKind;
+    /** The `id` of the atom's node in the snapshot. */
+    readonly atom: number;
+    readonly component: string | undefined;
+    readonly file: string | undefined;
+    readonly instance: number | undefined;
+}
+/**
+ * An atom in a scope's snapshot.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export interface ScopeNode {
+    /** Stable for the atom while the scope lives. */
+    readonly id: number;
+    readonly atom: Atom.Atom<unknown>;
+    readonly node: AtomRegistry.Node<unknown>;
+    /** The atom's label (its variable's name, with the atomLabels plugin), if it has one. */
+    readonly label: string | undefined;
+    /** Used by a hook in the scope, rather than only upstream of one. */
+    readonly read: boolean;
+    /** Has no label while other atoms in the scope do: made by a runtime, mutation or store. */
+    readonly plumbing: boolean;
+    /** Every listener the node has: the scope's hooks, and anything else that subscribes. */
+    readonly listeners: number;
+    /** The tag of its value when that is an `AsyncResult`, otherwise `Value`. */
+    readonly state: "Value" | "Initial" | "Success" | "Failure";
+    readonly waiting: boolean;
+}
+/**
+ * An edge from an atom to one that reads it. With plumbing left out, an atom that reads plumbing is
+ * linked to the nearest atoms upstream of it that are shown.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export interface ScopeEdge {
+    readonly from: number;
+    readonly to: number;
+}
+/**
+ * What a scope's part of the component tree reads, at one moment: the atoms its hooks use, the
+ * atoms upstream of them, the edges between, and the hooks.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export interface ScopeSnapshot {
+    readonly nodes: readonly ScopeNode[];
+    readonly edges: readonly ScopeEdge[];
+    readonly readers: readonly ScopeReader[];
+}
+/**
+ * An event a scope passes on: the inspector's `Event` for a node in the scope, with the node's
+ * `id`, or `ScopeChanged` once its atoms, edges or hooks have changed, after the registry's work,
+ * to take a new `snapshot()`. A node's `NodeAdded` arrives before the node is linked into the
+ * scope, so it isn't passed on; the `ScopeChanged` that follows is.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export type ScopeEvent = (Event & {
+    readonly id: number;
+}) | {
+    readonly _tag: "ScopeChanged";
+};
+/**
+ * A part of the component tree, as `provideInspectorScope` returns it.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category models
+ */
+export interface InspectorScope {
+    /** The atoms the scope reads now. `plumbing: true` includes those otherwise left out. */
+    readonly snapshot: (options?: {
+        readonly plumbing?: boolean;
+    }) => ScopeSnapshot;
+    /**
+     * Calls `listener` with each event for the scope's atoms; returns the function that stops it. The
+     * first listener starts the inspector on the registries the scope reads from. As with
+     * `Inspector.subscribe`, a listener must not read or write atoms or write Svelte state.
+     */
+    readonly subscribe: (listener: (event: ScopeEvent) => void) => () => void;
+}
+/**
+ * Makes the component being set up, and everything below it, an inspector scope, and returns it.
+ * The library's hooks below report the atoms they use to the nearest scope, which shows those
+ * atoms, everything upstream of them, and the hooks that use them. Call it while the component
+ * sets up, as context requires.
+ *
+ * Only in the browser, in development and production alike (the effect-atom-svelte docs draw each
+ * example's atoms from one); on the server it returns a scope that is always empty. Until the
+ * scope has a listener it only keeps a list of its hooks: the registry's inspector starts with the
+ * first listener.
+ *
+ * **Example** (A graph of what an example reads)
+ *
+ * ```ts
+ * import { provideInspectorScope } from "effect-atom-svelte/inspector";
+ *
+ * // In the component that frames the example, around its content
+ * const scope = provideInspectorScope();
+ * $effect(() =>
+ *   scope.subscribe((event) => {
+ *     if (event._tag === "ScopeChanged") {
+ *       draw(scope.snapshot());
+ *     } else if (event._tag === "Updated") {
+ *       pulse(event.id);
+ *     }
+ *   })
+ * );
+ * ```
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category inspecting
+ */
+export declare const provideInspectorScope: () => InspectorScope;
+/**
+ * Names the component being set up, for the scopes its hooks report to. The atomLabels plugin of
+ * effect-atom-svelte-devtools calls it at the top of each component's script; without the plugin,
+ * call it yourself. Only in the browser.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ * @category inspecting
+ */
+export declare const nameComponent: (name: string, file?: string) => void;