opshot 0.3.3 → 0.4.0

package/README.md

@@ -82,23 +82,23 @@ This is how you optimize re-rendering across your component tree: place `scope`
 ## Creating State
 
 ```tsx
-import { ignore, unsafeTrack, useMutableState, type Ignored, type UnsafeTracked } from "opshot";
+import { ignore, unsafeTrack, useMutableState } from "opshot";
 
 interface PlayerState {
 	position: number;
-	element: Ignored<HTMLAudioElement>;
-	queue: UnsafeTracked<Playlist>;
+	element: HTMLAudioElement;
+	queue: Playlist;
 	seek: (position: number) => void;
 }
 
 const Player = () => {
-	const player = useMutableState<PlayerState>({
+	const player: PlayerState = useMutableState({
 		position: 0,
 
-		// ignore() keeps a value out of reactivity and ops.
+		// ignore() on a value in the factory argument makes the edge at that path untracked.
 		element: ignore(new Audio()),
 
-		// unsafeTrack() tracks all the values it can, even if there is weird behaviour
+		// unsafeTrack() on a value in the factory argument disables strict at and under that path.
 		queue: unsafeTrack(new Playlist()),
 
 		seek(position: number) {
@@ -120,13 +120,14 @@ opshot tracks plain data.
 
 It can't track:
 
-- Internal slots (language level features like in Map)
-- #private fields (hidden at the language level)
-- Array subclasses (the prototype is lost when copied)
+- Hidden stores (language-level features like in Map)
+- #private fields
+- Own function properties on class instances
+- Non-writable properties that hold an object
 
-And `this` for arrow methods on classes refers to the original and **not** the tracked state.
+`strict: true` throws at a dangerous edge, at the cause.
 
-Use `ignore` or `unsafeTrack` when dealing with these.
+Use `ignore` on a value in the factory argument to make the edge at that path untracked. Use `unsafeTrack` on a value in the factory argument to disable strict at and under that path.
 
 ## Tracked collections
 
@@ -155,8 +156,8 @@ const Counter = () => {
 		() =>
 			subscribe(counter, (ops, meta) => {
 				// ops: [{
-				//   do:   { op: "replace", path: ["count"], value: 1 },
-				//   undo: { op: "replace", path: ["count"], value: 0 },
+				//   do:   { verb: "assign", path: ["count"], value: 1 },
+				//   undo: { verb: "assign", path: ["count"], value: 0 },
 				// }]
 				// meta: whatever the writer passed, or undefined for bare writes
 			}),
@@ -169,33 +170,36 @@ const Counter = () => {
 
 ## Ops
 
-An op is an invertible pair of `Operation` halves. Every half uses one of three verbs:
+An op is an invertible pair of halves. Every half uses one of three verbs:
 
 ```ts
 type OperationPath = ReadonlyArray<string | number>;
 
-type Operation =
-	| { readonly op: "add"; readonly path: OperationPath; readonly value: unknown }
-	| { readonly op: "replace"; readonly path: OperationPath; readonly value: unknown }
-	| { readonly op: "remove"; readonly path: OperationPath };
-
-interface Op {
-	readonly do: Operation;
-	readonly undo: Operation;
+interface Operation {
+	readonly do:
+		| {
+				readonly verb: "assign";
+				readonly path: OperationPath;
+				readonly value: unknown;
+				readonly ids?: ReadonlyArray<number>;
+		  }
+		| { readonly verb: "delete"; readonly path: OperationPath }
+		| { readonly verb: "link"; readonly path: OperationPath; readonly ref: number };
+	readonly undo: Operation["do"];
 }
 ```
 
-`applyOps` puts them back on a state, so a history is a list of ops and an undo is their `undo` halves in reverse.
+Ids vend in admission-walk order over the emitted artifact; a departure's undo assign may carry `ids` to rebind that walk, the one naming fact construction cannot re-derive. `applyOperations` puts them back on a state, so a history is a list of ops and an undo is `applyOperations` with `"undo"`.
 
 ```tsx
 import { useEffect, useRef } from "react";
-import { applyOps, subscribe, useMutableState, type Op } from "opshot";
+import { applyOperations, subscribe, useMutableState, type Operation } from "opshot";
 
 const replay = {};
 
 const Counter = () => {
 	const counter = useMutableState({ count: 0 });
-	const history = useRef<Array<ReadonlyArray<Op>>>([]);
+	const history = useRef<Array<ReadonlyArray<Operation>>>([]);
 
 	useEffect(
 		() =>
@@ -213,11 +217,7 @@ const Counter = () => {
 
 		if (!ops) return;
 
-		applyOps(
-			counter,
-			[...ops].reverse().map((op) => op.undo),
-			replay,
-		);
+		applyOperations(counter, ops, "undo", replay);
 	};
 
 	return (
@@ -245,8 +245,8 @@ const Editor = () => {
 	const group = useGroup();
 
 	// Created through the group, so their ops reach the group's subscribers.
-	const doc = useMutableState({ items: new Array<string>() }, group);
-	const selection = useMutableState({ index: 0 }, group);
+	const doc = useMutableState({ items: new Array<string>() }, { group });
+	const selection = useMutableState({ index: 0 }, { group });
 
 	useEffect(
 		() =>
@@ -264,7 +264,7 @@ const Editor = () => {
 
 ## Channels
 
-A channel binds `transact`, `subscribe`, and `applyOps` to a typed meta convention, so a listener can tell its own writes from everyone else's.
+A channel binds `transact`, `subscribe`, and `applyOperations` to a typed meta convention, so a listener can tell its own writes from everyone else's.
 
 ```tsx
 import { useEffect } from "react";

package/dist/index.d.ts

@@ -1,75 +1,424 @@
 import { ComponentType, FC } from 'react';
 
+declare const ignoreMarker: unique symbol;
+/**
+ * A factory-argument marker wrapping `T`.
+ *
+ * @typeParam T - Value type.
+ */
+interface Ignored<T> {
+    readonly [ignoreMarker]: T;
+}
+/**
+ * Marks a factory-argument value so the edge at that path is untracked in that state.
+ *
+ * @typeParam T - Value type.
+ * @param value - Value to ignore.
+ * @returns A marker consumed at create.
+ */
+declare function ignore<T>(value: T): Ignored<T>;
+
+declare const unsafeMarker: unique symbol;
+/**
+ * A factory-argument marker wrapping `T`.
+ *
+ * @typeParam T - Value type.
+ */
+interface UnsafeTracked<T> {
+    readonly [unsafeMarker]: T;
+}
+/**
+ * Marks a factory-argument value so strict is disabled at and under that path.
+ *
+ * @typeParam T - Value type.
+ * @param value - Value to track without strict.
+ * @returns A marker consumed at create.
+ */
+declare function unsafeTrack<T>(value: T): UnsafeTracked<T>;
+
+/**
+ * Schedules when bare writes notify listeners. Call `flush` once.
+ *
+ * @param flush - Delivers pending ops.
+ * @returns Nothing.
+ */
+type EmissionScheduler = (flush: () => void) => void;
+/**
+ * State creation options.
+ *
+ * @example
+ * createMutableState({ x: 0 }, { emitOn: (flush) => requestAnimationFrame(flush), strict: false })
+ */
+interface MutableNodeOptions {
+    /**
+     * When bare writes notify listeners. Defaults to a microtask.
+     */
+    readonly emitOn?: EmissionScheduler;
+    /**
+     * When true, throws at a dangerous edge, at the cause. Defaults to true.
+     */
+    readonly strict?: boolean;
+}
+
+/**
+ * Options for `createMutableState`.
+ *
+ * @example
+ * createMutableState({ count: 0 }, { group, emitOn, strict: false })
+ */
+interface MutableStateOptions extends MutableNodeOptions {
+    /**
+     * Group that receives this state's changes.
+     */
+    readonly group?: Group;
+}
+/**
+ * The live state shape after factory-argument markers are collapsed.
+ *
+ * @typeParam T - Factory argument type.
+ */
+type Unmarked<T> = T extends Ignored<infer Inner> ? Unmarked<Inner> : T extends UnsafeTracked<infer Inner> ? Unmarked<Inner> : T extends (...args: never) => unknown ? T : T extends ReadonlyArray<infer Element> ? Array<Unmarked<Element>> : T extends object ? {
+    [Key in keyof T]: Unmarked<T[Key]>;
+} : T;
+/**
+ * Creates a mutable state object.
+ *
+ * `ignore()` on a value in the factory argument makes the edge at that path untracked in that state.
+ * `unsafeTrack()` on a value in the factory argument disables strict at and under that path.
+ *
+ * @typeParam T - State shape.
+ * @param properties - Initial fields.
+ * @param options - Creation options.
+ * @returns The state, with factory-argument markers collapsed.
+ */
+declare function createMutableState<T extends object>(properties: T, options?: MutableStateOptions): Unmarked<T>;
+
+/**
+ * Path segments to a value in state.
+ *
+ * @example
+ * ["document", "items", 0, "title"]
+ */
 type OperationPath = ReadonlyArray<string | number>;
 
-interface AddOperation {
-    readonly op: "add";
+interface DeclarationTrie {
+    readonly ignored: boolean;
+    readonly unsafe: boolean;
+    readonly children: ReadonlyMap<string, DeclarationTrie>;
+}
+
+interface InEdge {
+    readonly parent: object;
+    readonly key: string | number;
+}
+interface NodeRecord {
+    edges: Array<InEdge>;
+    id: number | undefined;
+}
+
+interface CaptureTables {
+    mints: Array<{
+        readonly node: object;
+        readonly id: number;
+    }>;
+    binds: Array<{
+        readonly node: object;
+        readonly id: number;
+    }>;
+    bindIdByNode: Map<object, number>;
+    bindNodeById: Map<number, object>;
+    mintIdByNode: Map<object, number>;
+    mintNodeById: Map<number, object>;
+    nextStagedId: number;
+}
+
+interface DirtyIndex {
+    readonly edges: WeakMap<object, Set<string | symbol>>;
+    readonly nodes: WeakSet<object>;
+}
+interface Handle {
+    proxy: {
+        readonly root: object;
+    };
+    lastSnapshot: object;
+    hasPendingWrites: boolean;
+    isFlushScheduled: boolean;
+    isFlushHeld: boolean;
+    flushGeneration: number;
+    subscribers: StateListeners;
+    groups?: ReadonlyArray<GroupListeners>;
+    disarmWatch?: () => void;
+    emitOn?: EmissionScheduler;
+    strict: boolean;
+    declarations: DeclarationTrie | undefined;
+    nodes: WeakMap<object, NodeRecord>;
+    byId: Map<number, object>;
+    nextInternId: number;
+    lastDirty?: DirtyIndex;
+    stamp: object;
+    version: number;
+    replaying: boolean;
+    transactionCapture?: CaptureTables;
+}
+
+/**
+ * Assigns a value at a path.
+ *
+ * @example
+ * { verb: "assign", path: ["count"], value: 1 }
+ */
+interface AssignMutation {
+    /**
+     * `"assign"`.
+     */
+    readonly verb: "assign";
+    /**
+     * Path to assign.
+     */
     readonly path: OperationPath;
+    /**
+     * Value to assign.
+     */
     readonly value: unknown;
+    /**
+     * Walk-ordered intern ids that override deterministic vending when this half re-admits departed material.
+     */
+    readonly ids?: ReadonlyArray<number>;
 }
-interface ReplaceOperation {
-    readonly op: "replace";
+/**
+ * Deletes the value at a path.
+ *
+ * @example
+ * { verb: "delete", path: ["temp"] }
+ */
+interface DeleteMutation {
+    /**
+     * `"delete"`.
+     */
+    readonly verb: "delete";
+    /**
+     * Path to delete.
+     */
     readonly path: OperationPath;
-    readonly value: unknown;
 }
-interface RemoveOperation {
-    readonly op: "remove";
+/**
+ * Links the interned node `ref` into `path`.
+ *
+ * @example
+ * { verb: "link", path: ["alias"], ref: 0 }
+ */
+interface LinkMutation {
+    /**
+     * `"link"`.
+     */
+    readonly verb: "link";
+    /**
+     * Path to place the linked node.
+     */
     readonly path: OperationPath;
+    /**
+     * Intern id of the node to link.
+     */
+    readonly ref: number;
 }
-type Operation = AddOperation | ReplaceOperation | RemoveOperation;
-interface Op {
-    readonly do: Operation;
-    readonly undo: Operation;
+/**
+ * An assign, a delete, or a link.
+ *
+ * @example
+ * { verb: "assign", path: ["profile"], value: { name: "Ada" } }
+ */
+type Mutation = AssignMutation | DeleteMutation | LinkMutation;
+/**
+ * A change with do and undo halves.
+ *
+ * @example
+ * { do: { verb: "assign", path: ["count"], value: 1 }, undo: { verb: "assign", path: ["count"], value: 0 } }
+ */
+interface Operation {
+    /**
+     * Forward operation.
+     */
+    readonly do: Mutation;
+    /**
+     * Reverse operation.
+     */
+    readonly undo: Mutation;
 }
 
-type StateListener = (ops: ReadonlyArray<Op>, meta: unknown) => void;
-type GroupListener = (state: object, ops: ReadonlyArray<Op>, meta: unknown) => void;
+/**
+ * Listener for one state's changes.
+ *
+ * @param ops - Ops for the change.
+ * @param meta - Writer meta, if any.
+ * @returns Nothing.
+ */
+type StateListener = (ops: ReadonlyArray<Operation>, meta: unknown) => void;
+/**
+ * Listener for a group's changes.
+ *
+ * @param state - State that changed.
+ * @param ops - Ops for the change.
+ * @param meta - Writer meta, if any.
+ * @returns Nothing.
+ */
+type GroupListener = (state: object, ops: ReadonlyArray<Operation>, meta: unknown) => void;
+type StateDeliver = (ops: ReadonlyArray<Operation>, meta: unknown, channelId: object | undefined) => void;
+type GroupDeliver = (state: object, ops: ReadonlyArray<Operation>, meta: unknown, channelId: object | undefined) => void;
+type StateListeners = Map<Function, Map<object | undefined, StateDeliver>>;
+type GroupListeners = Map<Function, Map<object | undefined, GroupDeliver>>;
 
+/**
+ * Creates states and receives their changes on one stream.
+ *
+ * @example
+ * const group = createGroup()
+ * const doc = group.createMutableState({ title: "" })
+ * subscribe(group, (state, ops, meta) => {})
+ */
 interface Group {
-    createMutableState<T extends object>(properties: T): T;
+    /**
+     * Creates a state in this group.
+     *
+     * @typeParam T - State shape.
+     * @param properties - Initial fields.
+     * @param options - Creation options.
+     * @returns The state.
+     */
+    createMutableState<T extends object>(properties: T, options?: MutableNodeOptions): Unmarked<T>;
 }
-declare function createGroup(): Group;
+/**
+ * Creates a group.
+ *
+ * @param parent - Optional parent group whose listeners hear this group's states.
+ * @returns A new group.
+ */
+declare function createGroup(parent?: Group): Group;
 
-type Context<M> = {
+/**
+ * Listener context from a channel subscription.
+ *
+ * @typeParam M - Meta type for this channel.
+ */
+type EmissionContext<M> = {
     readonly isTransaction: true;
     readonly meta: M;
 } | {
     readonly isTransaction: false;
     readonly meta: unknown;
 };
+/**
+ * Listens for changes from a group's states.
+ *
+ * @param group - Group to listen to.
+ * @param listener - Called on each change.
+ * @returns Unsubscribe function.
+ */
 declare function subscribe(group: Group, listener: GroupListener): () => void;
+/**
+ * Listens for changes to a state.
+ *
+ * @param state - State to listen to.
+ * @param listener - Called on each change.
+ * @returns Unsubscribe function.
+ */
 declare function subscribe(state: object, listener: StateListener): () => void;
 
+type ApplyDirection = "do" | "undo";
+
+/**
+ * Channel-bound `transact`, `subscribe`, and `applyOperations`.
+ *
+ * @typeParam M - Meta type for this channel.
+ */
 interface Channel<M extends object> {
+    /**
+     * Runs a transaction with this channel's meta.
+     *
+     * @param state - State to change.
+     * @param mutate - Function that writes the state.
+     * @param meta - Meta for this write.
+     * @returns Nothing.
+     */
     transact(state: object, mutate: () => void, meta?: Partial<M>): void;
-    subscribe(group: Group, listener: (state: object, ops: ReadonlyArray<Op>, context: Context<M>) => void): () => void;
-    subscribe(state: object, listener: (ops: ReadonlyArray<Op>, context: Context<M>) => void): () => void;
-    applyOps(state: object, operations: ReadonlyArray<Operation>, meta?: Partial<M>): void;
+    /**
+     * Listens for changes from a group's states.
+     *
+     * @param group - Group to listen to.
+     * @param listener - Called on each change.
+     * @returns Unsubscribe function.
+     */
+    subscribe(group: Group, listener: (state: object, ops: ReadonlyArray<Operation>, context: EmissionContext<M>) => void): () => void;
+    /**
+     * Listens for changes to a state.
+     *
+     * @param state - State to listen to.
+     * @param listener - Called on each change.
+     * @returns Unsubscribe function.
+     */
+    subscribe(state: object, listener: (ops: ReadonlyArray<Operation>, context: EmissionContext<M>) => void): () => void;
+    /**
+     * Applies operations with this channel's meta.
+     *
+     * @param state - State to change.
+     * @param operations - Operations to apply.
+     * @param direction - `"do"` or `"undo"`.
+     * @param meta - Meta for this write.
+     * @returns Nothing.
+     */
+    applyOperations(state: object, operations: ReadonlyArray<Operation>, direction: ApplyDirection, meta?: Partial<M>): void;
 }
+/**
+ * Creates a channel with a typed meta convention.
+ *
+ * @typeParam M - Meta type for this channel.
+ * @param defaults - Default meta for this channel's writes.
+ * @returns The channel.
+ */
 declare function createChannel<M extends object>(defaults?: M): Channel<M>;
 
-declare function createMutableState<T extends object>(properties: T, group?: Group): T;
-
+/**
+ * Returns a stable identity key for a value.
+ *
+ * @param value - Value to identify.
+ * @returns Identity key.
+ */
 declare function identify(value: object): object;
+/**
+ * Returns whether two values share the same identity.
+ *
+ * @param first - First value.
+ * @param second - Second value.
+ * @returns True if they match.
+ */
 declare function isSameIdentity(first: object, second: object): boolean;
 
+/**
+ * Returns whether a value is an opshot state.
+ *
+ * @param value - Value to test.
+ * @returns True if it is a state.
+ */
 declare function isState(value: unknown): value is object;
 
-declare function applyOps(state: object, operations: ReadonlyArray<Operation>, meta?: unknown): void;
-
-declare function diffSnapshots(before: object, after: object): Array<Op>;
-
-declare const ignoredMarker: unique symbol;
-type Ignored<T extends object> = T & {
-    readonly [ignoredMarker]: true;
-};
-declare const ignore: <T extends object>(value: T) => Ignored<T>;
+/**
+ * Applies operations to a state.
+ *
+ * @param state - State to change.
+ * @param operations - Operations to apply.
+ * @param direction - `"do"` or `"undo"`.
+ * @param meta - Passed to listeners.
+ * @returns Nothing.
+ */
+declare function applyOperations(state: object, operations: ReadonlyArray<Operation>, direction: ApplyDirection, meta?: unknown): void;
 
-declare const unsafeTrackedBrand: unique symbol;
-type UnsafeTracked<T extends object> = T & {
-    readonly [unsafeTrackedBrand]: true;
-};
-declare function unsafeTrack<T extends object>(value: T): UnsafeTracked<T>;
+/**
+ * Diffs two plain objects into ops.
+ *
+ * @param before - Earlier value.
+ * @param after - Later value.
+ * @returns Ops from before to after.
+ */
+declare function diffObjects(before: object, after: object, handle?: Handle, dirty?: DirtyIndex, capture?: CaptureTables): Array<Operation>;
 
 type DateConstructorArgs = [] | [value: number | string] | [
     year: number,
@@ -80,10 +429,17 @@ type DateConstructorArgs = [] | [value: number | string] | [
     seconds?: number,
     milliseconds?: number
 ];
+/**
+ * Tracked `Date` for use in state.
+ *
+ * @example
+ * createMutableState({ when: new TrackedDate() })
+ */
 declare class TrackedDate {
     private epochMs;
     constructor(...args: DateConstructorArgs);
     private readDate;
+    private readEpochMs;
     private write;
     toString(): string;
     toDateString(): string;
@@ -134,6 +490,12 @@ declare class TrackedDate {
     readonly [Symbol.toStringTag]: "TrackedDate";
 }
 
+/**
+ * Tracked `Map` for use in state.
+ *
+ * @typeParam K - Key type.
+ * @typeParam V - Value type.
+ */
 declare class TrackedMap<K, V> {
     private slots;
     private index;
@@ -153,6 +515,11 @@ declare class TrackedMap<K, V> {
     readonly [Symbol.toStringTag]: "TrackedMap";
 }
 
+/**
+ * Tracked `Set` for use in state.
+ *
+ * @typeParam T - Member type.
+ */
 declare class TrackedSet<T> {
     private slots;
     private index;
@@ -171,15 +538,41 @@ declare class TrackedSet<T> {
     readonly [Symbol.toStringTag]: "TrackedSet";
 }
 
+/**
+ * Runs changes in one batch and notifies listeners with optional `meta`.
+ *
+ * @param state - State to change.
+ * @param mutate - Function that writes the state.
+ * @param meta - Passed to listeners.
+ * @returns Nothing.
+ */
 declare function transact(state: object, mutate: () => void, meta?: unknown): void;
 
-interface ScopeOptions {
-    readonly maxDepth?: number;
-}
-declare function scope<P extends object>(Component: ComponentType<P>, options?: ScopeOptions): FC<P>;
+/**
+ * Wraps a component so it re-renders only when fields it read change.
+ *
+ * @typeParam P - Props type.
+ * @param Component - Component to wrap.
+ * @returns The wrapped component.
+ */
+declare function scope<P extends object>(Component: ComponentType<P>): FC<P>;
 
-declare function useGroup(): Group;
+/**
+ * Creates a group for a component.
+ *
+ * @param parent - Optional parent group whose listeners hear this group's states.
+ * @returns The group.
+ */
+declare function useGroup(parent?: Group): Group;
 
-declare function useMutableState<T extends object>(properties: T, group?: Group): T;
+/**
+ * Creates mutable state for a component.
+ *
+ * @typeParam T - State shape.
+ * @param properties - Initial fields, or a function that returns them.
+ * @param options - Creation options.
+ * @returns The state.
+ */
+declare function useMutableState<T extends object>(properties: (() => T) | T, options?: MutableStateOptions): Unmarked<T>;
 
-export { type AddOperation, type Channel, type Context, type Group, type GroupListener, type Ignored, type Op, type Operation, type OperationPath, type RemoveOperation, type ReplaceOperation, type ScopeOptions, type StateListener, TrackedDate, TrackedMap, TrackedSet, type UnsafeTracked, applyOps, createChannel, createGroup, createMutableState, diffSnapshots, identify, ignore, isSameIdentity, isState, scope, subscribe, transact, unsafeTrack, useGroup, useMutableState };
+export { type Channel, type EmissionContext, type EmissionScheduler, type Group, type GroupListener, type Ignored, type MutableNodeOptions, type MutableStateOptions, type Operation, type OperationPath, type StateListener, TrackedDate, TrackedMap, TrackedSet, type UnsafeTracked, applyOperations, createChannel, createGroup, createMutableState, diffObjects, identify, ignore, isSameIdentity, isState, scope, subscribe, transact, unsafeTrack, useGroup, useMutableState };