effect-atom-svelte 0.1.2 → 0.3.0

package/dist/Inspector.js

@@ -0,0 +1,558 @@
+/**
+ * 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 { AsyncResult, Atom } from "effect/reactivity";
+import { BROWSER } from "esm-env";
+import { buildWillRead, defaultIdleTTL, holdsInitialValue, instrumentNode, } from "./internal/nodeInternals.js";
+import { list, watch } from "./internal/registries.js";
+import { nameComponent as setComponentName, setReporter, } from "./internal/scope.svelte.js";
+const nodeKey = (atom) => Atom.isSerializable(atom) ? atom[Atom.SerializableTypeId].key : atom;
+/**
+ * An `Atom.runtime` atom, by the `layer` and `factory` it carries. It builds its layer with
+ * `uninterruptible: true`, so a build torn down midway keeps running.
+ */
+const isRuntime = (atom) => "layer" in atom &&
+    Atom.isAtom(atom.layer) &&
+    "factory" in atom &&
+    typeof atom.factory === "function";
+const install = (registry) => {
+    const listeners = new Set();
+    const records = new WeakMap();
+    // The node that held each result first: the one whose computation or effect made it.
+    const origins = new WeakMap();
+    let writing = 0;
+    let complete = true;
+    const emit = (event) => {
+        for (const listener of listeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                // A tool's mistake mustn't break the app's registry.
+                console.error("effect-atom-svelte: an inspector listener threw", error);
+            }
+        }
+    };
+    const record = (node) => {
+        let found = records.get(node);
+        if (found === undefined) {
+            found = {
+                building: 0,
+                builds: 0,
+                changed: new Set(),
+                refreshed: false,
+                removing: false,
+                values: 0,
+            };
+            records.set(node, found);
+        }
+        return found;
+    };
+    const instrument = (node) => {
+        const instrumented = instrumentNode(node, {
+            build: () => {
+                const self = record(node);
+                let cause = { _tag: "Invalidated" };
+                if (self.builds === 0) {
+                    cause = { _tag: "FirstRead" };
+                }
+                else if (self.refreshed) {
+                    cause = { _tag: "Refreshed" };
+                }
+                else if (self.changed.size > 0) {
+                    cause = { _tag: "ParentChanged", parents: [...self.changed] };
+                }
+                self.builds += 1;
+                self.refreshed = false;
+                self.changed = new Set();
+                self.building += 1;
+                emit({ _tag: "Built", cause, node, time: performance.now() });
+            },
+            built: () => {
+                record(node).building -= 1;
+            },
+            dispose: (finalizers, value) => {
+                if (finalizers === 0) {
+                    return;
+                }
+                // An effect atom's computation leaves a waiting result until its fiber is done, and a
+                // finalizer that interrupts the fiber.
+                // A wrapper that passes on another atom's result (debounce, makeRefreshOnSignal) holds a
+                // value that atom made, and has no fiber of its own. A runtime's fiber isn't interrupted.
+                if (AsyncResult.isAsyncResult(value) &&
+                    value.waiting &&
+                    (origins.get(value) ?? node) === node &&
+                    !isRuntime(node.atom)) {
+                    emit({ _tag: "Interrupted", node, time: performance.now() });
+                }
+                emit({ _tag: "Finalized", finalizers, node, time: performance.now() });
+            },
+            readers: () => {
+                emit({
+                    _tag: "ReadersChanged",
+                    node,
+                    readers: node.listeners.size,
+                    time: performance.now(),
+                });
+            },
+            removed: () => {
+                const self = record(node);
+                if (self.removing) {
+                    self.removing = false;
+                    emit({ _tag: "NodeRemoved", node, time: performance.now() });
+                }
+            },
+            value: (previous, value) => {
+                const self = record(node);
+                if (AsyncResult.isAsyncResult(value) && !origins.has(value)) {
+                    origins.set(value, node);
+                }
+                const first = self.values === 0;
+                self.values += 1;
+                if (!first) {
+                    for (const child of node.children) {
+                        // A running build that hasn't read this node yet reads the new value: not a cause of
+                        // its next computation.
+                        if (!buildWillRead(child, node)) {
+                            record(child).changed.add(node);
+                        }
+                    }
+                }
+                let source = "async";
+                if (self.building > 0) {
+                    source = "build";
+                }
+                else if (writing > 0) {
+                    source = "write";
+                }
+                emit({
+                    _tag: "Updated",
+                    first,
+                    node,
+                    previous,
+                    source,
+                    time: performance.now(),
+                    value,
+                });
+            },
+        });
+        complete &&= instrumented;
+    };
+    const patchable = registry;
+    const { modify, onNodeAdded, onNodeRemoved, refresh, set, update } = patchable;
+    const writes = (f) => {
+        writing += 1;
+        try {
+            return f();
+        }
+        finally {
+            writing -= 1;
+        }
+    };
+    patchable.set = (atom, value) => writes(() => set.call(registry, atom, value));
+    patchable.update = (atom, f) => writes(() => update.call(registry, atom, f));
+    patchable.modify = (atom, f) => writes(() => modify.call(registry, atom, f));
+    // An atom with its own refresh (a wrapper such as withRefresh) calls the registry's refresh for
+    // the atoms it wraps, through this replacement, so each of those is marked too.
+    patchable.refresh = (atom) => {
+        const node = registry.getNodes().get(nodeKey(atom));
+        if (node !== undefined) {
+            record(node).refreshed = true;
+        }
+        try {
+            refresh.call(registry, atom);
+        }
+        finally {
+            // Still valid: the refresh didn't reach it (what it wraps computed an equal value), or it
+            // computed already. Either way the mark isn't the cause of a later computation.
+            if (node?.currentState() === "valid") {
+                record(node).refreshed = false;
+            }
+        }
+    };
+    patchable.onNodeAdded = (node) => {
+        onNodeAdded?.(node);
+        instrument(node);
+        emit({ _tag: "NodeAdded", node, time: performance.now() });
+    };
+    patchable.onNodeRemoved = (node) => {
+        onNodeRemoved?.(node);
+        // An idle node is announced before it is removed; its teardown is reported first.
+        if (node.currentState() !== "removed" && records.has(node)) {
+            record(node).removing = true;
+            return;
+        }
+        emit({ _tag: "NodeRemoved", node, time: performance.now() });
+    };
+    for (const node of registry.getNodes().values()) {
+        instrument(node);
+        // A node that has computed before isn't on its first read or value any more.
+        if (node.currentState() !== "uninitialized") {
+            const self = record(node);
+            self.builds = holdsInitialValue(node) ? 0 : 1;
+            self.values = 1;
+        }
+    }
+    return {
+        get complete() {
+            return complete;
+        },
+        idleTTL: (atom) => {
+            // An idle TTL of 0 is none: the registry removes the atom as soon as nothing reads it.
+            if (atom.keepAlive || atom.idleTTL === 0) {
+                return undefined;
+            }
+            return atom.idleTTL ?? defaultIdleTTL(registry);
+        },
+        registry,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+};
+const inspectors = new WeakMap();
+/**
+ * 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 const inspect = (registry) => {
+    let inspector = inspectors.get(registry);
+    if (inspector === undefined) {
+        inspector = install(registry);
+        inspectors.set(registry, inspector);
+    }
+    return 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 const registries = () => list();
+/**
+ * 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 const watchRegistries = (f) => watch(f);
+const emptySnapshot = { edges: [], nodes: [], readers: [] };
+/** The scope on the server: always empty. */
+const inertScope = {
+    snapshot: () => emptySnapshot,
+    subscribe: () => () => undefined,
+};
+const stateOf = (node) => {
+    // A valid node's value is read without computing anything.
+    const value = node.currentState() === "valid" ? node.value() : undefined;
+    return AsyncResult.isAsyncResult(value)
+        ? { state: value._tag, waiting: value.waiting }
+        : { state: "Value", waiting: false };
+};
+class Scope {
+    #reads = new Map();
+    #ids = new WeakMap();
+    #keyIds = new Map();
+    #listeners = new Set();
+    // The inspectors the scope follows while it has listeners, by registry.
+    #following = new Map();
+    #nextId = 0;
+    #nextRead = 0;
+    // The nodes in the scope, worked out again only after something that can change them.
+    #members;
+    // The last nodes worked out, so a node removed from the scope still has its removal passed on.
+    #previous = new Set();
+    #signature = "";
+    #checking = false;
+    reporter = {
+        report: ({ atom, component, kind, registry }) => {
+            this.#nextRead += 1;
+            const id = this.#nextRead;
+            this.#reads.set(id, { atom, component, id, kind, registry });
+            this.#follow(registry);
+            this.#changed();
+            return () => {
+                this.#reads.delete(id);
+                this.#changed();
+            };
+        },
+    };
+    #id(atom) {
+        const key = nodeKey(atom);
+        let id = typeof key === "string" ? this.#keyIds.get(key) : this.#ids.get(atom);
+        if (id === undefined) {
+            this.#nextId += 1;
+            id = this.#nextId;
+            if (typeof key === "string") {
+                this.#keyIds.set(key, id);
+            }
+            else {
+                this.#ids.set(atom, id);
+            }
+        }
+        return id;
+    }
+    /** Every node the scope's hooks use, and every node upstream of them. */
+    #nodes() {
+        // Without a listener the scope follows no inspector, so nothing would say the graph changed.
+        if (this.#listeners.size === 0) {
+            return this.#walk();
+        }
+        if (this.#members === undefined) {
+            this.#members = this.#walk();
+        }
+        return this.#members;
+    }
+    /** Works out the scope's nodes from the graph as it is now, without keeping them. */
+    #walk() {
+        const members = new Set();
+        const add = (node) => {
+            if (!members.has(node)) {
+                members.add(node);
+                for (const parent of node.parents) {
+                    add(parent);
+                }
+            }
+        };
+        for (const read of this.#reads.values()) {
+            const node = read.registry.getNodes().get(nodeKey(read.atom));
+            if (node !== undefined) {
+                add(node);
+            }
+        }
+        return members;
+    }
+    /** The nearest shown atoms upstream of `node`, looking through those not shown. */
+    #shownParents(node, shown) {
+        const found = new Set();
+        const seen = new Set();
+        const walk = (parents) => {
+            for (const parent of parents) {
+                const id = this.#id(parent.atom);
+                if (shown.has(id)) {
+                    found.add(id);
+                }
+                else if (!seen.has(parent)) {
+                    seen.add(parent);
+                    walk(parent.parents);
+                }
+            }
+        };
+        walk(node.parents);
+        found.delete(this.#id(node.atom));
+        return found;
+    }
+    snapshot(options) {
+        const members = [...this.#nodes()];
+        const read = new Set([...this.#reads.values()].map((entry) => this.#id(entry.atom)));
+        const labelled = members.some((node) => node.atom.label !== undefined);
+        const nodes = members.map((node) => {
+            const id = this.#id(node.atom);
+            return {
+                atom: node.atom,
+                id,
+                label: node.atom.label?.[0],
+                listeners: node.listeners.size,
+                node,
+                plumbing: labelled && node.atom.label === undefined,
+                read: read.has(id),
+                ...stateOf(node),
+            };
+        });
+        // An atom a hook uses is shown even without a label: it is what the component uses.
+        const shown = nodes.filter((node) => options?.plumbing === true || !node.plumbing || node.read);
+        const shownIds = new Set(shown.map((node) => node.id));
+        const edges = shown.flatMap((node) => [...this.#shownParents(node.node, shownIds)].map((from) => ({
+            from,
+            to: node.id,
+        })));
+        const readers = [...this.#reads.values()].map((entry) => ({
+            atom: this.#id(entry.atom),
+            component: entry.component?.name,
+            file: entry.component?.file,
+            id: entry.id,
+            instance: entry.component?.instance,
+            kind: entry.kind,
+        }));
+        return { edges, nodes: shown, readers };
+    }
+    subscribe(listener) {
+        if (this.#listeners.size === 0) {
+            // Kept from before the scope last stopped following, and the graph may have changed since.
+            this.#members = undefined;
+            this.#previous = new Set();
+        }
+        this.#listeners.add(listener);
+        for (const read of this.#reads.values()) {
+            this.#follow(read.registry);
+        }
+        this.#signature = this.#sign();
+        return () => {
+            this.#listeners.delete(listener);
+            if (this.#listeners.size === 0) {
+                for (const stop of this.#following.values()) {
+                    stop();
+                }
+                this.#following.clear();
+            }
+        };
+    }
+    #follow(registry) {
+        if (this.#listeners.size === 0 || this.#following.has(registry)) {
+            return;
+        }
+        this.#following.set(registry, inspect(registry).subscribe((event) => this.#receive(event)));
+    }
+    #receive(event) {
+        // Events arrive in the middle of the registry's work, while a computation is still changing
+        // the edges it reads through: what is worked out now isn't kept for the snapshot.
+        const inScope = this.#previous.has(event.node) ||
+            (this.#members ?? this.#walk()).has(event.node);
+        if (event._tag === "NodeAdded" ||
+            event._tag === "NodeRemoved" ||
+            event._tag === "Built") {
+            this.#changed();
+        }
+        if (inScope) {
+            this.#emit({ ...event, id: this.#id(event.node.atom) });
+        }
+    }
+    #emit(event) {
+        for (const listener of this.#listeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.error("effect-atom-svelte: an inspector scope listener threw", error);
+            }
+        }
+    }
+    /** What the snapshot shows, in short, to tell whether it changed. */
+    #sign() {
+        const { edges, nodes, readers } = this.snapshot();
+        return [
+            nodes.map((node) => node.id).join(","),
+            edges.map((edge) => `${edge.from}>${edge.to}`).join(","),
+            readers.map((reader) => `${reader.id}:${reader.atom}`).join(","),
+        ].join("|");
+    }
+    /** The scope may have changed: work it out again once the registry's work is done. */
+    #changed() {
+        if (this.#members !== undefined) {
+            this.#previous = this.#members;
+        }
+        this.#members = undefined;
+        if (this.#checking || this.#listeners.size === 0) {
+            return;
+        }
+        this.#checking = true;
+        queueMicrotask(() => {
+            this.#checking = false;
+            const signature = this.#sign();
+            this.#previous = this.#nodes();
+            if (signature !== this.#signature) {
+                this.#signature = signature;
+                this.#emit({ _tag: "ScopeChanged" });
+            }
+        });
+    }
+}
+/**
+ * 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 const provideInspectorScope = () => {
+    if (!BROWSER) {
+        return inertScope;
+    }
+    const scope = new Scope();
+    setReporter(scope.reporter);
+    return scope;
+};
+/**
+ * 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 const nameComponent = (name, file) => {
+    if (BROWSER) {
+        setComponentName(name, file);
+    }
+};

package/dist/RegistryContext.d.ts

@@ -99,6 +99,8 @@ export type ProvideRegistryOptions = ProvideExistingRegistry | ProvideNewRegistr
  *
  * A registry created here is owned by the component and disposed of with it, which on the server
  * means at the end of the request. A registry passed in is left for the caller to dispose of.
+ * In the browser, a finalizer that throws while the provider disposes of its registry is reported
+ * as an uncaught error after teardown, rather than thrown into Svelte's teardown.
  *
  * **Example** (Giving the app a registry from the root layout)
  *

package/dist/RegistryContext.js

@@ -4,9 +4,13 @@
  * @since 0.1.0
  */
 import { AtomRegistry } from "effect/reactivity";
-import { BROWSER } from "esm-env";
-import { createContext, onDestroy } from "svelte";
+import { BROWSER, DEV } from "esm-env";
+import { createContext } from "svelte";
+import { disposeRegistry } from "./internal/disposal.js";
 import { setRevalidateOnHydrate } from "./internal/hydration.js";
+import { track } from "./internal/registries.js";
+import { onTeardownAfterChildren } from "./internal/teardown.svelte.js";
+import { troubleshooting } from "./internal/troubleshooting.js";
 const [getContextRegistry, setContextRegistry, hasContextRegistry] = createContext();
 let browserRegistry;
 /**
@@ -34,9 +38,14 @@ export const getRegistry = () => {
         return getContextRegistry();
     }
     if (!BROWSER) {
-        throw new Error("No AtomRegistry in context. Wrap the app in <RegistryProvider> so each server request gets its own registry.");
+        throw new Error(`No AtomRegistry in context. Wrap the app in <RegistryProvider> so each server request gets its own registry. ${troubleshooting("no-atomregistry-in-context")}`);
+    }
+    if (browserRegistry === undefined) {
+        browserRegistry = AtomRegistry.make();
+        if (DEV) {
+            track(browserRegistry);
+        }
     }
-    browserRegistry ??= AtomRegistry.make();
     return browserRegistry;
 };
 /**
@@ -44,6 +53,8 @@ export const getRegistry = () => {
  *
  * A registry created here is owned by the component and disposed of with it, which on the server
  * means at the end of the request. A registry passed in is left for the caller to dispose of.
+ * In the browser, a finalizer that throws while the provider disposes of its registry is reported
+ * as an uncaught error after teardown, rather than thrown into Svelte's teardown.
  *
  * **Example** (Giving the app a registry from the root layout)
  *
@@ -71,15 +82,20 @@ export const provideRegistry = (options = {}) => {
     if (provided &&
         Object.values(registryOptions).some((value) => value !== undefined)) {
         // The types rule this out; a caller without them would otherwise lose the options silently.
-        throw new Error("provideRegistry takes an existing registry or options for a new one, not both. Apply initialValues to the existing registry yourself.");
+        throw new Error(`provideRegistry takes an existing registry or options for a new one, not both. Apply initialValues to the existing registry yourself. ${troubleshooting("provideregistry-takes-an-existing-registry-or-options-for-a-new-one-not-both")}`);
     }
     const registry = provided ?? AtomRegistry.make(registryOptions);
     setContextRegistry(registry);
     if (revalidateOnHydrate !== undefined) {
         setRevalidateOnHydrate(revalidateOnHydrate);
     }
+    // Not onDestroy: in the browser it never runs for a component destroyed while its script awaits.
     if (!provided) {
-        onDestroy(() => registry.dispose());
+        onTeardownAfterChildren(() => disposeRegistry(registry));
+    }
+    if (DEV && BROWSER) {
+        // For developer tools to find (effect-atom-svelte/inspector).
+        onTeardownAfterChildren(track(registry));
     }
     return registry;
 };

package/dist/ScopedAtom.d.ts

@@ -49,10 +49,11 @@ export interface MakeOptions {
 /**
  * Creates a scoped atom from a factory, which runs once per providing component.
  *
- * Each provider gets its own atom, so a factory that adds `Atom.serializable` with a fixed key
- * gives every copy the same key: once two providers are on a page, reading them with
- * `useAtomResult` or `useAtomSuspense` throws, as two different atoms share the serialization
- * key. Put the input in the key, or leave scoped atoms unserialized.
+ * Each provider gets its own atom, so a factory that makes a serializable atom gives every copy of
+ * one input the same key, and two such providers on a server-rendered page make the render throw:
+ * two different atoms share the serialization key. For a value from the server, return a family's
+ * atom instead, `ScopedAtom.make((id: string) => userAtom(id))`, so every provider of one input
+ * holds the same atom.
  *
  * **Example** (A counter per subtree, started from an input)
  *

package/dist/ScopedAtom.js

@@ -13,10 +13,11 @@ export const TypeId = "~effect-atom-svelte/ScopedAtom";
 /**
  * Creates a scoped atom from a factory, which runs once per providing component.
  *
- * Each provider gets its own atom, so a factory that adds `Atom.serializable` with a fixed key
- * gives every copy the same key: once two providers are on a page, reading them with
- * `useAtomResult` or `useAtomSuspense` throws, as two different atoms share the serialization
- * key. Put the input in the key, or leave scoped atoms unserialized.
+ * Each provider gets its own atom, so a factory that makes a serializable atom gives every copy of
+ * one input the same key, and two such providers on a server-rendered page make the render throw:
+ * two different atoms share the serialization key. For a value from the server, return a family's
+ * atom instead, `ScopedAtom.make((id: string) => userAtom(id))`, so every provider of one input
+ * holds the same atom.
  *
  * **Example** (A counter per subtree, started from an input)
  *