@mark1russell7/render-node 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+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,40 @@
 # @mark1russell7/render-node
 
-This version is a placeholder. The release workflow of https://github.com/mark1russell7/render publishes the real versions. Use a later version.
+[![npm](https://img.shields.io/npm/v/@mark1russell7/render-node?color=2346c4)](https://www.npmjs.com/package/@mark1russell7/render-node) [![CI](https://github.com/mark1russell7/render/actions/workflows/ci.yml/badge.svg)](https://github.com/mark1russell7/render/actions/workflows/ci.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-2346c4)](https://github.com/mark1russell7/render/blob/main/LICENSE)
+
+The reactive store of render. Each value is a node with an expression. One write starts one epoch. The store evaluates each reader of the node in topological order, and it stops at each value that does not change.
+
+```sh
+npm i @mark1russell7/render-node @mark1russell7/render-dsl @mark1russell7/render-splay
+```
+
+```ts
+import { app, lit, ref } from "@mark1russell7/render-dsl";
+import { addNode, batch, nodeStore, readValue, setValue } from "@mark1russell7/render-node";
+import { standardOps } from "@mark1russell7/render-splay";
+
+const store = nodeStore({ ops: standardOps });
+addNode(store, lit(2), "w");
+addNode(store, lit(4), "h");
+addNode(store, app("*", ref("w"), ref("h")), "area");
+
+setValue(store, "w", 3);
+readValue(store, "area"); // { tag: "some", value: 12 }
+store.epochStats; // the nodes that the write evaluated and changed
+
+// A batch makes many writes one epoch
+batch(store, () => {
+  setValue(store, "w", 5);
+  setValue(store, "h", 5);
+});
+```
+
+A node can be a container of named slots, and a reference reads through the slots. The `NodeOps` of a store (`splash`, `flow`, `deref` and `targets`) are its extension points.
+
+## More
+
+- [The site](https://mark1russell7.github.io/render/): the guide, live demos and the viewer.
+- [The API reference](https://mark1russell7.github.io/render/reference/api/): the exports of each package.
+- [The repository](https://github.com/mark1russell7/render): the source, the tests and the review of each known defect.
+
+Each package of render is ESM, has TypeScript declarations, and works in Node.js 22.12 or later and in browsers. The license is MIT.

package/build/index.d.ts

@@ -0,0 +1,238 @@
+import { Optional } from "@mark1russell7/render-optional";
+import { DepPath, Expr, Ops, Resolver } from "@mark1russell7/render-dsl";
+//#region src/types.d.ts
+/** The identity of a node in its store. */
+type NodeId = string;
+/**
+ * A node is the reactive primitive. It is a reactive variable (an expression and its value),
+ * a seat (it knows its readers) and a container of named slots.
+ *
+ * Only the engine changes a node. The `splash` op writes `value` through its target (`SplashTarget`).
+ */
+type Node = {
+  readonly id: NodeId;
+  /**
+   * The expression is the source of truth. The value is a cache of its evaluation.
+   * A write changes the expression, thus a later evaluation cannot revert the write.
+   */
+  readonly expr: Expr;
+  /** The value of the expression after the last epoch. `none` is a value: the expression has no result. */
+  readonly value: Optional<unknown>;
+  /** The free reference paths of `expr`. */
+  readonly reads: readonly DepPath[];
+  /** The value readers: the nodes whose read path ends on this node. */
+  readonly seats: ReadonlySet<NodeId>;
+  /** The structural readers: the nodes whose read path goes through a slot of this node. */
+  readonly seatsStructural: ReadonlySet<NodeId>;
+  /** The nodes that have this node as a reader. Unwiring uses this index. */
+  readonly seatedOn: ReadonlySet<NodeId>;
+  /** The container that owns this node as a slot. The removal of the owner also removes this node. */
+  readonly parent: NodeId | undefined;
+  /** The containers that have a slot to this node: the owner and each container that shares the node. */
+  readonly heldBy: ReadonlySet<NodeId>;
+  /**
+   * The named slots of a container. A node with slots is a container: its expression is a `record`
+   * form over its slots, thus its value is the record of their values.
+   */
+  readonly slots: ReadonlyMap<string, NodeId>;
+};
+/**
+ * The reactive semantics of a store. The engine uses these three ops for each write, each epoch and
+ * each reference. Biblo layers class methods on top of them (`classNodeOps`).
+ */
+type NodeOps = {
+  /** This op writes a result to a node. It gives `true` when the value changed. */
+  readonly splash: SplashFn;
+  /** This op gives the nodes that a change of the target makes dirty. */
+  readonly flow: FlowFn;
+  /** This op resolves a path from a root node. It goes through slots first, then through the fields of the value. */
+  readonly deref: DerefFn;
+  /**
+   * This op gives the nodes that a path from a root node depends on. The engine seats the reader on them.
+   * A custom `deref` gives a matching `targets`, thus the wiring always agrees with the resolution.
+   */
+  readonly targets: TargetsFn;
+};
+/** The target of the write op: a node whose `value` the op can write. */
+type SplashTarget = Omit<Node, "value"> & {
+  value: Optional<unknown>;
+};
+/** The write op. It gives `true` when the value of the target changed. */
+type SplashFn = (value: Optional<unknown>, target: SplashTarget, store: NodeStore) => boolean;
+/** The propagation op. It gives the nodes that a change of the target makes dirty. */
+type FlowFn = (target: Node, store: NodeStore) => ReadonlySet<NodeId>;
+/** The resolution op. It gives the value at a path from a root node. */
+type DerefFn = (root: Node, path: readonly string[], store: NodeStore) => Optional<unknown>;
+/**
+ * The nodes that a read path depends on. A change of the value of `terminal` makes the reader dirty.
+ * A change of the slots of a node in `through` makes the reader resolve its path again.
+ * A path with no terminal reads no value, for example a missing slot of a container.
+ */
+type ReadTargets = {
+  readonly through: readonly Node[];
+  readonly terminal: Node | undefined;
+};
+/** The dependency op: the nodes that a path from a root node depends on. It agrees with `deref`. */
+type TargetsFn = (root: Node, path: readonly string[], store: NodeStore) => ReadTargets;
+/** The record of one epoch. */
+type EpochStats = {
+  /** The nodes that the epoch evaluated. */
+  readonly evaluated: ReadonlySet<NodeId>;
+  /** The nodes whose value changed in the epoch. */
+  readonly changed: ReadonlySet<NodeId>;
+  /** The nodes on a dependency cycle. A cycle evaluates again until its values are stable, up to `MAX_CYCLE_ROUNDS` rounds. */
+  readonly cyclic: ReadonlySet<NodeId>;
+  /** The number of nodes in the store after the epoch. */
+  readonly total: number;
+};
+/** A store of nodes, with the semantics of its reactivity and the op registry of its expressions. */
+type NodeStore = {
+  readonly nodes: ReadonlyMap<NodeId, Node>;
+  readonly nodeOps: NodeOps;
+  readonly ops: Ops;
+  /** The record of the last epoch, or `null` before the first epoch. */
+  readonly epochStats: EpochStats | null;
+};
+/** The options of `nodeStore`. */
+type StoreOptions = {
+  /** The reactive semantics. The default is `defaultOps`. */
+  readonly nodeOps?: NodeOps | undefined;
+  /** The op registry of the expressions. The default is an empty registry. */
+  readonly ops?: Ops | undefined;
+};
+//#endregion
+//#region src/ops.d.ts
+/**
+ * The default write. It keeps the old value when the new result is structurally equal, thus an equal
+ * object keeps its old reference. A change from a value to `none`, or from `none` to a value, is a change.
+ */
+export declare const defaultSplash: SplashFn;
+/** The default propagation. A change of a node makes its value readers dirty. */
+export declare const defaultFlow: FlowFn;
+/**
+ * The default resolution. It goes through slots as far as they exist, then through the own fields of the value.
+ * A path that ends on a node gives the value of that node. For a container, this value is the record of its slots.
+ * A path that stops at a container before its end reads a missing slot, thus it gives `none`.
+ */
+export declare const defaultDeref: DerefFn;
+/**
+ * The default dependencies of a path, which agree with `defaultDeref`. The nodes that the path goes through are
+ * structural targets, and the node where it ends is the terminal. A path that stops at a container before its end
+ * reads a missing slot: it has no terminal, and the container is a structural target.
+ */
+export declare const defaultTargets: TargetsFn;
+/** The default semantics of a store. */
+export declare const defaultOps: NodeOps;
+//#endregion
+//#region src/writes.d.ts
+/** This function makes an empty store. The options give its reactive semantics and its op registry. */
+export declare const nodeStore: (options?: StoreOptions) => NodeStore;
+/**
+ * This function gives an independent copy of a store: the same nodes, values, slots and seats, and the same
+ * counters. A write to one store does not change the other. The expressions and the values are immutable,
+ * thus the copy shares them. The options replace the semantics or the op registry of the copy, for example the
+ * class semantics of a copied biblo. The function throws inside a batch, because a batch has pending work.
+ */
+export declare const forkStore: (store: NodeStore, options?: StoreOptions) => NodeStore;
+/** This function gives a node of the store, or `undefined`. */
+export declare const getNode: (store: NodeStore, id: NodeId) => Node | undefined;
+/** This function gives the value of a node, or `none` when the store has no such node. */
+export declare const readValue: (store: NodeStore, id: NodeId) => Optional<unknown>;
+/**
+ * This function makes `fn` one transaction. The writes in `fn` change the structure at once, and one epoch
+ * at the end evaluates all their effects. A batch inside a batch joins the outer batch.
+ */
+export declare const batch: <T>(store: NodeStore, fn: () => T) => T;
+/**
+ * This function adds a node with an expression and evaluates it. It gives the ID of the node.
+ * The ID is the hint when no node has it, otherwise a fresh ID. A reader that waited for this ID gets rewired.
+ */
+export declare const addNode: (store: NodeStore, expr: Expr, idHint?: string) => NodeId;
+/**
+ * This function sets the expression of a node. This is the fundamental write.
+ * The engine rewires the reads of the node, evaluates it and propagates the change.
+ * A write to a container collapses it first: its own slots are removed, and the expression replaces the record.
+ */
+export declare const setExpr: (store: NodeStore, id: NodeId, expr: Expr) => void;
+/**
+ * This function writes a literal value: it is `setExpr` with `lit(value)`.
+ * A write to a derived node makes it an input node, like a value that a person types over a formula.
+ */
+export declare const setValue: (store: NodeStore, id: NodeId, value: unknown) => void;
+/** This function writes many literal values in one batch, thus in one epoch. */
+export declare const fillMany: (store: NodeStore, writes: Iterable<readonly [NodeId, unknown]>) => void;
+/** The options of `setSlot`. */
+type SlotOptions = {
+  /**
+   * With `own`, the container becomes the owner of the child when the child has no owner. The removal of the
+   * owner removes the child, and so does a slot change that drops the child. Without `own`, the child is shared.
+   */
+  readonly own?: boolean;
+};
+/**
+ * This function points a slot of a container at a node, or removes the slot when `childId` is `undefined`.
+ * This is the structural write: the container gets a new record expression, and each reader whose path goes
+ * through the container resolves its path again. A node that the container owns and drops is removed.
+ * The function does nothing when a node is missing or when the child is the container itself.
+ */
+export declare const setSlot: (store: NodeStore, parentId: NodeId, name: string, childId: NodeId | undefined, options?: SlotOptions) => void;
+/**
+ * This function expands a node whose value is a plain object. Each field becomes a slot, and
+ * a field that is a plain object becomes a container in turn. The node becomes a container, and its slots
+ * are from then on the source of truth of its fields. A reader of a field gets a seat on the field node,
+ * thus an edit of one field makes only its own readers dirty. An expansion of a derived node keeps the current fields.
+ *
+ * Inside a batch, the expansion waits for the epoch of the batch, thus it uses the settled value.
+ * The function does nothing for a container or for a value that is not a plain object.
+ */
+export declare const expandNode: (store: NodeStore, id: NodeId) => void;
+/**
+ * This function removes a node and the slots that it owns. The containers that hold it lose the slot.
+ * Its readers resolve their paths again: a path to a removed node gives `none`. If a node with the same ID
+ * comes back later, the readers find it.
+ */
+export declare const removeNode: (store: NodeStore, id: NodeId) => void;
+/**
+ * This function evaluates the full store again. It rewires each node, makes each record expression again,
+ * and starts one epoch in which each node evaluates one time in topological order. The operations keep the
+ * store consistent, thus this function is a repair tool. It does not revert a write.
+ */
+export declare const resolveAll: (store: NodeStore) => void;
+//#endregion
+//#region src/engine.d.ts
+/**
+ * This function gives the chain of nodes that a read path goes through. The chain starts at the root
+ * (`path[0]`, a node ID) and follows slots as far as they exist. The last node is the terminal: the path
+ * reads its value. The function gives an empty chain when the root is not in the store.
+ */
+export declare const readTargets: (nodes: ReadonlyMap<NodeId, Node>, path: DepPath) => Node[];
+/** This function makes the resolver that the expressions of a store use: `path[0]` is a node ID. */
+declare const resolverOf: (store: NodeStore) => Resolver;
+/**
+ * The limit of the rounds of a cycle in one epoch. Like the iterative calculation of a spreadsheet, the members
+ * of a cycle evaluate again until their values are stable, or until this limit.
+ */
+export declare const MAX_CYCLE_ROUNDS = 100;
+//#endregion
+//#region src/toposort.d.ts
+/**
+ * This function sorts the nodes of a store by their static dependencies (Kahn's algorithm).
+ *
+ * The edges come from the `targets` op of the store, like the seat wiring.
+ * A reader depends on the terminal of each path and on each node that the path goes through.
+ * A path to a node that is not in the store adds no edge.
+ *
+ * The result has the dependencies before their readers. A node on a cycle of two or more nodes is not in the
+ * result. A reference of a node to itself adds no edge. The epochs of the engine use the edges of `flow`
+ * instead, thus this function is a tool for analysis.
+ */
+export declare const toposort: (store: NodeStore) => NodeId[];
+//#endregion
+//#region src/equality.d.ts
+/** This function tells if a value is a plain object: its prototype is `Object.prototype` or `null`. */
+export declare const isPlainObject: (v: unknown) => v is Record<string, unknown>;
+/** This function compares two node values structurally. The module comment gives the rules. */
+export declare const valueEquals: (a: unknown, b: unknown) => boolean;
+//#endregion
+export { type DerefFn, type EpochStats, type FlowFn, type Node, type NodeId, type NodeOps, type NodeStore, type ReadTargets, type SlotOptions, type SplashFn, type SplashTarget, type StoreOptions, type TargetsFn, resolverOf as storeResolver };
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/ops.ts","../src/writes.ts","../src/engine.ts","../src/toposort.ts","../src/equality.ts"],"mappings":";;;;KAIY;;;;;;;KAQA;WACD,IAAI;;;;;WAKJ,MAAM;;WAEN,OAAO;;WAEP,gBAAgB;;WAEhB,OAAO,YAAY;;WAEnB,iBAAiB,YAAY;;WAE7B,UAAU,YAAY;;WAEtB,QAAQ;;WAER,QAAQ,YAAY;;;;;WAKpB,OAAO,oBAAoB;;;;;;KAO1B;;WAED,QAAQ;;WAER,MAAM;;WAEN,OAAO;;;;;WAKP,SAAS;;;KAIR,eAAe,KAAK;EAAmB,OAAO;;;KAG9C,YAAY,OAAO,mBAAmB,QAAQ,cAAc,OAAO;;KAGnE,UAAU,QAAQ,MAAM,OAAO,cAAc,YAAY;;KAGzD,WAAW,MAAM,MAAM,yBAAyB,OAAO,cAAc;;;;;;KAOrE;WAAyB,kBAAkB;WAAiB,UAAU;;;KAGtE,aAAa,MAAM,MAAM,yBAAyB,OAAO,cAAc;;KAGvE;;WAED,WAAW,YAAY;;WAEvB,SAAS,YAAY;;WAErB,QAAQ,YAAY;;WAEpB;;;KAIC;WACD,OAAO,YAAY,QAAQ;WAC3B,SAAS;WACT,KAAK;;WAEL,YAAY;;;KAIX;;WAED,UAAU;;WAEV,MAAM;;;;;;;;qBChGJ,eAAe;;qBAQf,aAAa;;;;;;qBAOb,cAAc;;;;;;qBA2Bd,gBAAgB;;qBAgBhB,YAAY;;;;qBClDZ,YAAa,UAAS,iBAAoB;;;;;;;qBAS1C,YAAa,OAAO,WAAW,UAAS,iBAAoB;;qBAoC5D,UAAW,OAAO,WAAW,IAAI,WAAS;;qBAG1C,YAAa,OAAO,WAAW,IAAI,WAAS;;;;;qBAM5C,QAAS,GAAG,OAAO,WAAW,UAAU,MAAI;;;;;qBAM5C,UAAW,OAAO,WAAW,MAAM,MAAM,oBAAkB;;;;;;qBAa3D,UAAW,OAAO,WAAW,IAAI,QAAQ,MAAM;;;;;qBAe/C,WAAY,OAAO,WAAW,IAAI,QAAQ;;qBAK1C,WAAY,OAAO,WAAW,QAAQ,mBAAmB;;KAO1D;;;;;WAKD;;;;;;;;qBASE,UACX,OAAO,WACP,UAAU,QACV,cACA,SAAS,oBACT,UAAS;;;;;;;;;;qBA6BE,aAAc,OAAO,WAAW,IAAI;;;;;;qBAYpC,aAAc,OAAO,WAAW,IAAI;;;;;;qBAYpC,aAAc,OAAO;;;;;;;;qBC/BrB,cAAe,OAAO,YAAY,QAAQ,OAAO,MAAM,YAAU;;cAwQjE,aAAc,OAAO,cAAY;;;;;qBAUjC;;;;;;;;;;;;;;qBCnaA,WAAY,OAAO,cAAY;;;;qBCG/B,gBAAiB,eAAa,KAAK;;qBA6BnC,cAAe,YAAY"}