opshot 0.3.4 → 0.5.0

package/README.md

@@ -28,12 +28,6 @@ const user = useMutableState({ name: "Ada", age: 36 });
 user.age = 37;
 ```
 
-The state is created once, on the first render. Pass a function to build the properties once as well, exactly as `useState` does:
-
-```tsx
-const navigation = useMutableState(createNavigation);
-```
-
 ## Bounded re-renders
 
 React re-renders a component and its children when its state changes.
@@ -88,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() stores it as-is; opshot never looks inside.
 		element: ignore(new Audio()),
 
-		// unsafeTrack() tracks all the values it can, even if there is weird behaviour
+		// unsafeTrack() takes it anyway, tracking the plain data on it.
 		queue: unsafeTrack(new Playlist()),
 
 		seek(position: number) {
@@ -126,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.
+By default opshot throws when it meets one of these, naming the value that caused it. Passing `strict: false` turns off those errors but may cause unpredictable behaviour.
 
-Use `ignore` or `unsafeTrack` when dealing with these.
+`ignore(value)` stores a value without state inside it being tracked, and `ignore(value, false)` undoes that. `unsafeTrack(value)` does the reverse: it takes a value strict mode would reject, tracking the plain data on it and quietly missing the rest. Either mark only affects states the value enters afterwards.
 
 ## Tracked collections
 
@@ -159,12 +154,8 @@ const Counter = () => {
 
 	useEffect(
 		() =>
-			subscribe(counter, (ops, meta) => {
-				// ops: [{
-				//   do:   { op: "replace", path: ["count"], value: 1 },
-				//   undo: { op: "replace", path: ["count"], value: 0 },
-				// }]
-				// meta: whatever the writer passed, or undefined for bare writes
+			subscribe(counter, (operations) => {
+				// operations: [{ node, key: "count", before: 0, after: 1, meta: undefined }]
 			}),
 		[counter],
 	);
@@ -173,127 +164,63 @@ const Counter = () => {
 };
 ```
 
-## Ops
+## Operations
 
-An op is an invertible pair of `Operation` halves. Every half uses one of three verbs:
+An operation is one key's change on one node:
 
 ```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 node: object;
+	readonly key: string;
+	readonly before?: unknown;
+	readonly after?: unknown;
+	readonly meta: unknown;
 }
 ```
 
-`applyOps` puts them back on a state, so a history is a list of ops and an undo is their `undo` halves in reverse.
-
-```tsx
-import { useEffect, useRef } from "react";
-import { applyOps, subscribe, useMutableState, type Op } from "opshot";
-
-const replay = {};
-
-const Counter = () => {
-	const counter = useMutableState({ count: 0 });
-	const history = useRef<Array<ReadonlyArray<Op>>>([]);
-
-	useEffect(
-		() =>
-			subscribe(counter, (ops, meta) => {
-				// Skip our own replays, so undo doesn't record itself.
-				if (meta === replay) return;
+`before` and `after` are absent properties when the key was absent.
 
-				history.current.push(ops);
-			}),
-		[counter],
-	);
+## Emission
 
-	const undo = () => {
-		const ops = history.current.pop();
+A state gathers its writes and delivers them together. The window is a microtask by default, so everything you change in one go arrives as one emission carrying the net change — a listener hears where a field ended up, not every step it took there.
 
-		if (!ops) return;
-
-		applyOps(
-			counter,
-			[...ops].reverse().map((op) => op.undo),
-			replay,
-		);
-	};
-
-	return (
-		<>
-			<button onClick={() => counter.count++}>+</button>
-			<button onClick={undo}>Undo</button>
-		</>
-	);
-};
-```
-
-Replay is exact for anything opshot can see: plain data. State behind a constraint is the exception.
-
-If your state is JSON serializable, **then ops are too**.
-
-## Groups
-
-A group creates states and hears every op from the states it created: one stream for history, sync, persistence, etc.
+`emitOn` sets the window instead. opshot hands you a `flush`, and the state waits until you call it.
 
 ```tsx
 import { useEffect } from "react";
-import { subscribe, useGroup, useMutableState } from "opshot";
-
-const Editor = () => {
-	const group = useGroup();
+import { subscribe, useMutableState } from "opshot";
 
-	// 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 Chart = () => {
+	// One emission per frame, however many writes land in between.
+	const cursor = useMutableState({ x: 0, y: 0 }, { emitOn: (flush) => requestAnimationFrame(flush) });
 
 	useEffect(
 		() =>
-			// Fires for doc, selection, and every other state the group created.
-			// state is whichever one changed.
-			subscribe(group, (state, ops, meta) => {
+			subscribe(cursor, (operations) => {
 				// ...
 			}),
-		[group],
+		[cursor],
 	);
 
 	// ...
 };
 ```
 
-## Channels
+## Batches
 
-A channel binds `transact`, `subscribe`, and `applyOps` to a typed meta convention, so a listener can tell its own writes from everyone else's.
+`batch` runs a callback and tags every write inside it with your `meta`, so a listener can tell its own writes from everyone else's.
 
 ```tsx
 import { useEffect } from "react";
-import { createChannel, useMutableState } from "opshot";
-
-interface DocumentMeta {
-	replay?: boolean;
-	source?: string;
-}
-
-const docChannel = createChannel<DocumentMeta>({ source: "editor" }); // set defaults
+import { batch, subscribe, useMutableState } from "opshot";
 
 const TitleBar = () => {
 	const doc = useMutableState({ title: "Untitled" });
 
 	useEffect(
 		() =>
-			docChannel.subscribe(doc, (ops, context) => {
-				// A bare write, or a transact from another channel: meta is unknown.
-				if (!context.isTransaction) return;
-
-				// Own-channel transaction: meta is typed, with defaults merged.
-				if (context.meta.replay) return;
+			subscribe(doc, (operations) => {
+				if (operations[0]?.meta === "replay") return;
 
 				// ...
 			}),
@@ -301,9 +228,12 @@ const TitleBar = () => {
 	);
 
 	const rename = () => {
-		docChannel.transact(doc, () => {
-			doc.title = "Draft";
-		});
+		batch(
+			() => {
+				doc.title = "Draft";
+			},
+			{ source: "editor" },
+		);
 	};
 
 	// ...

package/dist/index.d.ts

@@ -1,75 +1,112 @@
 import { ComponentType, FC } from 'react';
 
-type OperationPath = ReadonlyArray<string | number>;
-
-interface AddOperation {
-    readonly op: "add";
-    readonly path: OperationPath;
-    readonly value: unknown;
-}
-interface ReplaceOperation {
-    readonly op: "replace";
-    readonly path: OperationPath;
-    readonly value: unknown;
-}
-interface RemoveOperation {
-    readonly op: "remove";
-    readonly path: OperationPath;
-}
-type Operation = AddOperation | ReplaceOperation | RemoveOperation;
-interface Op {
-    readonly do: Operation;
-    readonly undo: Operation;
-}
-
-type StateListener = (ops: ReadonlyArray<Op>, meta: unknown) => void;
-type GroupListener = (state: object, ops: ReadonlyArray<Op>, meta: unknown) => void;
-
-interface Group {
-    createMutableState<T extends object>(properties: T): T;
+/**
+ * Sets when a state's window flushes. Call `flush` once.
+ *
+ * @param flush - Delivers pending operations.
+ * @returns Nothing.
+ */
+type EmissionScheduler = (flush: () => void) => void;
+/**
+ * Options for `createMutableState`.
+ *
+ * @example
+ * createMutableState({ count: 0 }, { emitOn, strict: false })
+ */
+interface MutableStateOptions {
+    /**
+     * When the window flushes for all writes. Defaults to a microtask.
+     */
+    readonly emitOn?: EmissionScheduler;
+    /**
+     * When true, throws at a dangerous edge, at the cause. Defaults to true.
+     */
+    readonly strict?: boolean;
 }
-declare function createGroup(): Group;
-
-type Context<M> = {
-    readonly isTransaction: true;
-    readonly meta: M;
-} | {
-    readonly isTransaction: false;
-    readonly meta: unknown;
-};
-declare function subscribe(group: Group, listener: GroupListener): () => void;
-declare function subscribe(state: object, listener: StateListener): () => void;
-
-interface Channel<M extends object> {
-    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;
-}
-declare function createChannel<M extends object>(defaults?: M): Channel<M>;
-
-declare function createMutableState<T extends object>(properties: T, group?: Group): T;
+/**
+ * Creates a mutable state object.
+ *
+ * `ignore()` marks an object so every edge to it is untracked. `unsafeTrack()` marks an object so a node entering while marked, or entering beneath an exempt node, is exempt from strict.
+ *
+ * @typeParam T - State shape.
+ * @param properties - Initial fields.
+ * @param options - Creation options.
+ * @returns The state.
+ */
+declare function createMutableState<T extends object>(properties: T, options?: MutableStateOptions): 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>;
+/**
+ * A change to one key of a node.
+ *
+ * @example
+ * { node, key: "count", before: 0, after: 1, meta: undefined }
+ */
+interface Operation {
+    /**
+     * Node that changed.
+     */
+    readonly node: object;
+    /**
+     * Key that changed.
+     */
+    readonly key: string;
+    /**
+     * Value before, absent when the key was absent.
+     */
+    readonly before?: unknown;
+    /**
+     * Value after, absent when the key is absent.
+     */
+    readonly after?: unknown;
+    /**
+     * Meta of the batch the write was made in.
+     */
+    readonly meta: unknown;
+}
 
-declare const ignoredMarker: unique symbol;
-type Ignored<T extends object> = T & {
-    readonly [ignoredMarker]: true;
-};
-declare const ignore: <T extends object>(value: T) => Ignored<T>;
+/**
+ * Marks an object so every edge to it is untracked in every state.
+ *
+ * @typeParam T - Value type.
+ * @param value - Value to mark or unmark.
+ * @param on - Whether the mark is set.
+ * @returns `value`.
+ */
+declare function ignore<T>(value: T, on?: boolean): T;
 
-declare const unsafeTrackedBrand: unique symbol;
-type UnsafeTracked<T extends object> = T & {
-    readonly [unsafeTrackedBrand]: true;
-};
-declare function unsafeTrack<T extends object>(value: T): UnsafeTracked<T>;
+/**
+ * Marks an object so a node entering a state while marked, or entering beneath an exempt node, is exempt from strict.
+ *
+ * @typeParam T - Value type.
+ * @param value - Value to mark or unmark.
+ * @param on - Whether the mark is set.
+ * @returns `value`.
+ */
+declare function unsafeTrack<T>(value: T, on?: boolean): T;
 
 type DateConstructorArgs = [] | [value: number | string] | [
     year: number,
@@ -80,10 +117,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 +178,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 +203,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 +226,47 @@ declare class TrackedSet<T> {
     readonly [Symbol.toStringTag]: "TrackedSet";
 }
 
-declare function transact(state: object, mutate: () => void, meta?: unknown): void;
+/**
+ * Listener for one state's changes.
+ *
+ * @param operations - Operations for the change.
+ */
+type StateListener = (operations: ReadonlyArray<Operation>) => void;
 
-interface ScopeOptions {
-    readonly maxDepth?: number;
-}
-declare function scope<P extends object>(Component: ComponentType<P>, options?: ScopeOptions): FC<P>;
+/**
+ * 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;
+
+/**
+ * Runs writes carrying `meta`.
+ *
+ * @param callback - Function that writes any states.
+ * @param meta - Carried by each write's operation.
+ */
+declare function batch(callback: () => void, meta?: unknown): void;
 
-declare function useGroup(): Group;
+/**
+ * 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 useMutableState<T extends object>(properties: (() => T) | 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): 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 EmissionScheduler, type MutableStateOptions, type Operation, type StateListener, TrackedDate, TrackedMap, TrackedSet, batch, createMutableState, identify, ignore, isSameIdentity, isState, scope, subscribe, unsafeTrack, useMutableState };