effect-atom-svelte 0.3.0 → 0.4.0

package/dist/internal/form/paths.js

@@ -0,0 +1,175 @@
+// Paths into a form's values, and the item keys that let state follow an array item when it moves.
+// Internal: not exported from the package.
+//
+// Two kinds of path: an index path (["items", 0, "qty"]) addresses the values as they are now, and
+// a key path (["items", 7, "qty"]) names array items by their key instead of their index. Touched
+// state and errors are stored by key path, so they move with their item. Both are arrays of
+// strings (object keys) and numbers (an index, or an item key).
+import { Array as Arr, Equal, Predicate } from "effect";
+/** A string for a key path, to use as a map key. */
+export const pathId = (path) => JSON.stringify(path);
+/** Parses a `pathId` back into its path. */
+export const fromPathId = (id) => {
+    const path = JSON.parse(id);
+    // SAFETY: every id comes from `pathId`, which stringifies a KeyPath.
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- JSON.parse can't say what it parsed, and the id is only ever pathId's
+    return path;
+};
+const isRecord = Predicate.isObject;
+/** The value at `path`, or `undefined` when a step is missing. */
+export const getIn = (root, path) => {
+    let current = root;
+    for (const segment of path) {
+        if (Array.isArray(current) && typeof segment === "number") {
+            current = current[segment];
+        }
+        else if (isRecord(current) && typeof segment === "string") {
+            current = current[segment];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+};
+/** A copy of `root` with `value` at `path`, sharing everything off the path. */
+export const setIn = (root, path, value) => {
+    if (path.length === 0) {
+        return value;
+    }
+    const [head, ...rest] = path;
+    if (typeof head === "number") {
+        const array = Arr.isArray(root) ? [...root] : [];
+        array[head] = setIn(array[head], rest, value);
+        return array;
+    }
+    if (head === undefined) {
+        return value;
+    }
+    const record = isRecord(root) ? root : {};
+    return {
+        ...record,
+        [head]: setIn(record[head], rest, value),
+    };
+};
+/** Whether `path` starts with `prefix`. */
+export const startsWith = (path, prefix) => prefix.length <= path.length &&
+    prefix.every((segment, index) => path[index] === segment);
+/**
+ * The key path for an index path, or `undefined` when an index has no item. A number segment is an
+ * index only where the value so far is an array; a record's numeric-looking keys are strings.
+ */
+export const toKeyPath = (keys, path) => {
+    const out = [];
+    for (const segment of path) {
+        if (typeof segment === "number") {
+            const key = keys.get(pathId(out))?.[segment];
+            if (key === undefined) {
+                return undefined;
+            }
+            out.push(key);
+        }
+        else {
+            out.push(segment);
+        }
+    }
+    return out;
+};
+/** The index path for a key path, or `undefined` when one of its items is gone. */
+export const toIndexPath = (keys, path) => {
+    const out = [];
+    for (const [position, segment] of path.entries()) {
+        if (typeof segment === "number") {
+            const arrayKeys = keys.get(pathId(path.slice(0, position)));
+            const index = arrayKeys?.indexOf(segment) ?? -1;
+            if (index < 0) {
+                return undefined;
+            }
+            out.push(index);
+        }
+        else {
+            out.push(segment);
+        }
+    }
+    return out;
+};
+/**
+ * Item keys for every array in `values`. Arrays that already have keys keep them, by position, and
+ * new positions take fresh keys from `next`; keys for arrays that are gone are dropped.
+ */
+export const reconcileKeys = (values, previous, next) => {
+    const out = new Map();
+    const walk = (value, path) => {
+        if (Array.isArray(value)) {
+            const id = pathId(path);
+            const old = previous.get(id) ?? [];
+            const keys = old.length === value.length
+                ? old
+                : Array.from({ length: value.length }, (_, index) => old[index] ?? next());
+            out.set(id, keys);
+            for (const [index, item] of value.entries()) {
+                const key = keys[index];
+                if (key !== undefined) {
+                    walk(item, [...path, key]);
+                }
+            }
+        }
+        else if (isRecord(value)) {
+            for (const [key, item] of Object.entries(value)) {
+                walk(item, [...path, key]);
+            }
+        }
+    };
+    walk(values, []);
+    return out;
+};
+/** Whether every item key in `path` still belongs to its array. */
+export const isLive = (keys, path) => toIndexPath(keys, path) !== undefined;
+// An object literal, or one made with `Object.create(null)`: not a class instance.
+const isPlain = (value) => {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+/**
+ * Equality for form values. Arrays and plain objects compare by content, with a key set to
+ * `undefined` the same as a missing one; dates by time; values that implement Effect's `Equal`
+ * (`Option`, `HashMap`) by `Equal.equals`. Any other class instance compares by identity: a
+ * `File`, a `Map`, and also a `Data.Class` or `Schema.Class` value, which in Effect 4 doesn't
+ * implement `Equal`. So a fresh instance with the same content counts as a change.
+ */
+export const equals = (a, b) => {
+    if (Object.is(a, b)) {
+        return true;
+    }
+    if (a instanceof Date && b instanceof Date) {
+        return a.getTime() === b.getTime();
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return (a.length === b.length && a.every((item, index) => equals(item, b[index])));
+    }
+    if (Equal.isEqual(a) && Equal.isEqual(b)) {
+        return Equal.equals(a, b);
+    }
+    if (isRecord(a) && isRecord(b) && isPlain(a) && isPlain(b)) {
+        const keysA = Object.keys(a).filter((key) => a[key] !== undefined);
+        const keysB = Object.keys(b).filter((key) => b[key] !== undefined);
+        return (keysA.length === keysB.length &&
+            keysA.every((key) => equals(a[key], b[key])));
+    }
+    return false;
+};
+// One character of a key that isn't a letter or a digit, as `_` and its code in hex: `-` is `_2d`.
+const escapeChar = (char) => `_${(char.codePointAt(0) ?? 0).toString(16)}_`;
+/**
+ * A string for a key path that is safe in an element id and different for every path:
+ * `items-_7-qty`. Segments are joined with `-`, an item key is `_` and the number, and any other
+ * character of a key than a letter or a digit is escaped (`a-b` is `a_2d_b`), so a key can't
+ * produce a `-` or an item key's form.
+ */
+export const idSuffix = (path) => path
+    .map((segment) => typeof segment === "number"
+    ? `_${segment}`
+    : segment.replaceAll(/[^A-Za-z0-9]/gu, escapeChar))
+    .join("-");
+/** The `name` attribute for an index path: `items.0.qty`. */
+export const nameOf = (path) => path.join(".");

package/dist/internal/form/types.d.ts

@@ -0,0 +1,80 @@
+import type { Cause, Option, Schema } from "effect";
+import type { AsyncResult, Atom, AtomRegistry } from "effect/reactivity";
+import type { CheckHook, LeafHook } from "./issues.ts";
+import type { IndexPath, Keys } from "./paths.ts";
+/**
+ * When a field's error shows: as the user types, when they leave it, or only on submit. The Schema
+ * checks every change whatever the timing.
+ */
+export type Timing = "submit" | "blur" | "input";
+/** Where an error came from, which decides when it clears. */
+export type ErrorSource = "schema" | "submit" | "manual";
+/** Errors to put on a form: per top-level field, per path, and form-level. */
+export interface ErrorsInput {
+    readonly fields?: Readonly<Record<string, string | undefined>> | undefined;
+    readonly paths?: readonly (readonly [IndexPath | string, string])[] | undefined;
+    readonly form?: string | undefined;
+}
+/** A definition's settings, shared by every instance. */
+export interface Definition {
+    readonly schema: Schema.Top;
+    /**
+     * The form's name, for its atoms' labels (`SignUp.values`). Writable: the devtools' Vite plugin
+     * fills it in from the variable a definition is declared as, when `Form.make` was given none.
+     */
+    name: string | undefined;
+    /** An `Atom.AtomRuntime`, kept untyped: only its `fn` is used. */
+    readonly runtime?: unknown;
+    readonly validateOn: Timing;
+    readonly revalidateOn: Timing;
+    readonly debounce: number;
+    readonly leafHook?: LeafHook | undefined;
+    readonly checkHook?: CheckHook | undefined;
+}
+/** One instance's settings. */
+export interface EngineOptions {
+    readonly registry: AtomRegistry.AtomRegistry;
+    readonly id: string;
+    readonly initialValues: unknown;
+    readonly values?: Atom.Writable<unknown> | undefined;
+    readonly submit?: {
+        readonly atom: () => Atom.Writable<AsyncResult.AsyncResult<unknown, unknown>, unknown>;
+        readonly payload?: ((decoded: unknown, args: unknown) => unknown) | undefined;
+    } | undefined;
+    readonly mapError?: ((error: unknown) => ErrorsInput | undefined) | undefined;
+    readonly autoSubmit?: boolean | undefined;
+    readonly resetOnSuccess?: boolean | undefined;
+    /** Whether validation runs at all: not while rendering on the server. */
+    readonly validates: boolean;
+}
+export interface ExternalError {
+    readonly message: string;
+    readonly source: "submit" | "manual";
+}
+/** An instance's state, in one atom. Error maps are keyed by `pathId` of a key path. */
+export interface State {
+    readonly initial: unknown;
+    readonly keys: Keys;
+    readonly touched: ReadonlySet<string>;
+    /** Schema errors on show, by path. A path drops out once its check passes. */
+    readonly revealed: ReadonlySet<string>;
+    /** Paths that have shown an error since the last reset: they follow `revalidateOn`. */
+    readonly shown: ReadonlySet<string>;
+    /** The latest validation run's messages, in the Schema's order. */
+    readonly issues: ReadonlyMap<string, string>;
+    /** The values that run decoded, to tell whether its result is current. */
+    readonly checked: unknown;
+    readonly decoded: Option.Option<unknown>;
+    /** Why the latest run couldn't decode at all (a defect, a runtime that failed), if it couldn't. */
+    readonly failure: Cause.Cause<unknown> | undefined;
+    readonly validating: boolean;
+    readonly external: ReadonlyMap<string, ExternalError>;
+    readonly submitCount: number;
+    readonly validationCount: number;
+    readonly submitting: boolean;
+    readonly submitResult: AsyncResult.AsyncResult<unknown, unknown>;
+    readonly lastSubmitted: Option.Option<{
+        readonly encoded: unknown;
+        readonly decoded: unknown;
+    }>;
+}

package/dist/internal/form/types.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/form/validationError.d.ts

@@ -0,0 +1,13 @@
+import type { IndexPath } from "./paths.ts";
+declare const FormValidationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "FormValidationError";
+} & Readonly<A>;
+/** A form's validation failure, as `submit` reports it. */
+export declare class FormValidationError extends FormValidationError_base<{
+    readonly errors: readonly {
+        readonly path: IndexPath;
+        readonly message: string;
+    }[];
+}> {
+}
+export {};

package/dist/internal/form/validationError.js

@@ -0,0 +1,6 @@
+// The failure a form's submit reports when its values don't decode. Internal: `Form.ts` exports it.
+import { Data } from "effect";
+/** A form's validation failure, as `submit` reports it. */
+// oxlint-disable-next-line effecttsgo/prefer-schema-tagged-error -- a local error that never crosses the network; a Schema class would change Form.ValidationError's public type and check its fields on every construction
+export class FormValidationError extends Data.TaggedError("FormValidationError") {
+}

package/dist/internal/hydration.js

@@ -14,7 +14,9 @@ export const setRevalidateOnHydrate = (value) => {
  * Whether a hook runs its atom again once the page has hydrated: its own option, else the nearest
  * provider's, else no (JND-19). Call during component init.
  */
-export const revalidatesOnHydrate = (option) => option ?? (hasDefault() ? getDefault() : false);
+export const revalidatesOnHydrate = (
+// oxlint-disable-next-line sonarjs/bool-param-default -- undefined is "the hook gave no option", which a default would erase
+option) => option ?? (hasDefault() ? getDefault() : false);
 /**
  * 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`.

package/dist/internal/nodeInternals.js

@@ -1,7 +1,38 @@
-const isNodeImpl = (node) => Object.hasOwn(node, "_value") &&
-    Object.hasOwn(node, "lifetime") &&
-    typeof node.build === "function" &&
-    node.listeners instanceof Set;
+// The one place the inspector (../Inspector.ts) relies on how Effect implements AtomRegistry rather
+// than on its public API. Written against effect 4.0.1 (effect/src/reactivity/AtomRegistry.ts); the
+// peer range is ~4.0.0 because of code like this.
+//
+// The public `AtomRegistry` announces nodes added and removed (`onNodeAdded`, `onNodeRemoved`), and
+// a `Node` shows its parents, children and listeners. It says nothing when a node's value changes,
+// when it computes, when what a computation started is torn down or when its listeners change.
+// Each of those goes through a member of the implementation's node (`NodeImpl`), which is replaced
+// on that one node:
+//
+// - `build()`: computes the node's value, running the atom's `read`. Wrapped, for when a
+//   computation starts and ends.
+// - `_value`: the node's value. Written by `setValue` (a computation's result, `setSelf`, a write)
+//   and `setInitialValue`, and only when the value is not equal to the last. Made an accessor.
+// - `lifetime`: what the current computation holds. `disposeLifetime` clears it, then runs its
+//   `finalizers`, which interrupt the fiber of an effect atom that hasn't finished. That happens
+//   before every recomputation and when the node is removed. Made an accessor.
+// - `listeners`: public, but only as a set to read. Everything that reads an atom reactively
+//   (`AtomRegistry.subscribe` and `mount`, an atom's `get.subscribe`, the hooks' `holdNode`) adds
+//   to it and deletes from it through the node's field, so a set put in its place hears each one,
+//   including the deletes of subscriptions made before.
+//
+// A node that lacks any of them is left alone (`instrumentNode` returns false), so a change in
+// Effect stops the inspector from reporting rather than breaking the registry.
+//
+// docs/proposals/atom-registry-inspector.md proposes an API in Effect that would replace this file.
+import { Predicate } from "effect";
+const isNodeImpl = (node) => {
+    if (!(Object.hasOwn(node, "_value") && Object.hasOwn(node, "lifetime"))) {
+        return false;
+    }
+    return ("build" in node &&
+        typeof node.build === "function" &&
+        node.listeners instanceof Set);
+};
 /** A node's listeners that report each one added or removed. */
 class Listeners extends Set {
     #changed;
@@ -92,16 +123,18 @@ export const instrumentNode = (node, hooks) => {
  * which the implementation keeps but the interface doesn't show.
  */
 export const defaultIdleTTL = (registry) => {
-    const ttl = registry
-        .defaultIdleTTL;
+    const ttl = "defaultIdleTTL" in registry ? registry.defaultIdleTTL : undefined;
     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;
+export const holdsInitialValue = (node) => "preserveInitialValueOnBuild" in 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);
+    // The lifetime is the build's `get`, a function.
+    const lifetime = "lifetime" in node ? node.lifetime : undefined;
+    const reads = Predicate.hasProperty(lifetime, "reads")
+        ? lifetime.reads
+        : undefined;
+    return reads instanceof Set && !reads.has(parent);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-atom-svelte",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Community-built Svelte 5 bindings for Effect Atom (not affiliated with the Effect team)",
   "keywords": [
     "effect",
@@ -45,7 +45,7 @@
   },
   "scripts": {
     "build": "svelte-package -i src -o dist",
-    "check": "svelte-check --tsconfig ./tsconfig.json && bun scripts/check-docs.ts",
+    "check": "svelte-check --tsconfig ./tsconfig.json && tsc -p scripts && bun scripts/check-docs.ts",
     "test": "vitest run"
   },
   "dependencies": {
@@ -53,16 +53,18 @@
   },
   "devDependencies": {
     "@demo/domain": "workspace:*",
-    "@sveltejs/package": "^3.0.0",
-    "@sveltejs/vite-plugin-svelte": "^7.2.0",
-    "@vitest/browser": "^5.0.3",
-    "@vitest/browser-playwright": "^5.0.3",
-    "effect": "4.0.1",
+    "@sveltejs/package": "^3.0.1",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "@types/bun": "^1.4.2",
+    "@vitest/browser": "^5.0.5",
+    "@vitest/browser-playwright": "^5.0.5",
+    "effect": "4.0.5",
     "playwright": "^1.57.0",
     "svelte": "^5.57.2",
-    "svelte-check": "^4.6.0",
-    "vite": "^8.3.0",
-    "vitest": "^5.0.3",
+    "svelte-check": "^4.7.6",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.5",
     "vitest-browser-svelte": "^3.1.0"
   },
   "peerDependencies": {