opshot 0.3.4 → 0.4.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() 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) {
@@ -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.
+`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
 
@@ -161,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
 			}),
@@ -175,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(
 		() =>
@@ -219,11 +217,7 @@ const Counter = () => {
 
 		if (!ops) return;
 
-		applyOps(
-			counter,
-			[...ops].reverse().map((op) => op.undo),
-			replay,
-		);
+		applyOperations(counter, ops, "undo", replay);
 	};
 
 	return (
@@ -251,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(
 		() =>
@@ -270,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";