opshot 0.4.0 → 0.5.0

package/README.md

@@ -95,10 +95,10 @@ const Player = () => {
 	const player: PlayerState = useMutableState({
 		position: 0,
 
-		// ignore() on a value in the factory argument makes the edge at that path untracked.
+		// ignore() stores it as-is; opshot never looks inside.
 		element: ignore(new Audio()),
 
-		// unsafeTrack() on a value in the factory argument disables strict at and under that path.
+		// unsafeTrack() takes it anyway, tracking the plain data on it.
 		queue: unsafeTrack(new Playlist()),
 
 		seek(position: number) {
@@ -125,9 +125,9 @@ It can't track:
 - Own function properties on class instances
 - Non-writable properties that hold an object
 
-`strict: true` throws at a dangerous edge, at the cause.
+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` 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.
+`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
 
@@ -154,12 +154,8 @@ const Counter = () => {
 
 	useEffect(
 		() =>
-			subscribe(counter, (ops, meta) => {
-				// ops: [{
-				//   do:   { verb: "assign", path: ["count"], value: 1 },
-				//   undo: { verb: "assign", 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],
 	);
@@ -168,126 +164,63 @@ const Counter = () => {
 };
 ```
 
-## Ops
+## Operations
 
-An op is an invertible pair of halves. Every half uses one of three verbs:
+An operation is one key's change on one node:
 
 ```ts
-type OperationPath = ReadonlyArray<string | number>;
-
 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"];
+	readonly node: object;
+	readonly key: string;
+	readonly before?: unknown;
+	readonly after?: unknown;
+	readonly meta: unknown;
 }
 ```
 
-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 { applyOperations, subscribe, useMutableState, type Operation } from "opshot";
-
-const replay = {};
-
-const Counter = () => {
-	const counter = useMutableState({ count: 0 });
-	const history = useRef<Array<ReadonlyArray<Operation>>>([]);
-
-	useEffect(
-		() =>
-			subscribe(counter, (ops, meta) => {
-				// Skip our own replays, so undo doesn't record itself.
-				if (meta === replay) return;
-
-				history.current.push(ops);
-			}),
-		[counter],
-	);
-
-	const undo = () => {
-		const ops = history.current.pop();
-
-		if (!ops) return;
-
-		applyOperations(counter, ops, "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.
+`before` and `after` are absent properties when the key was absent.
 
-If your state is JSON serializable, **then ops are too**.
+## Emission
 
-## Groups
+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.
 
-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 `applyOperations` 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;
 
 				// ...
 			}),
@@ -295,9 +228,12 @@ const TitleBar = () => {
 	);
 
 	const rename = () => {
-		docChannel.transact(doc, () => {
-			doc.title = "Draft";
-		});
+		batch(
+			() => {
+				doc.title = "Draft";
+			},
+			{ source: "editor" },
+		);
 	};
 
 	// ...