opshot 0.5.3 → 0.6.1

package/README.md

@@ -82,7 +82,8 @@ This is how you optimize re-rendering across your component tree: place `scope`
 ## Creating State
 
 ```tsx
-import { ignore, unsafeTrack, useMutableState } from "opshot";
+import { ignore, unsafeTrack } from "opshot";
+import { useMutableState } from "opshot/react";
 
 interface PlayerState {
 	position: number;
@@ -114,6 +115,10 @@ const Player = () => {
 };
 ```
 
+`createMutableState(properties, options)` creates the same state outside a component, for a store or a process with no React.
+
+`ignore(value, false)` and `unsafeTrack(value, false)` undo these effects on the value.
+
 ## Constraints
 
 opshot tracks plain data.
@@ -125,16 +130,15 @@ It can't track:
 - Own function properties on class instances
 - Non-writable properties that hold an object
 
-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.
-
-`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.
+`strict: true` throws when opshot meets one of these, naming the value that caused it; `strict: false` stores the value untracked. It defaults to true in development and false in production.
 
 ## Tracked collections
 
 `TrackedMap`, `TrackedSet`, and `TrackedDate` stand in for the built-ins opshot rejects. They have the exact same API as their counterparts.
 
 ```ts
-import { TrackedMap, useMutableState } from "opshot";
+import { TrackedMap } from "opshot";
+import { useMutableState } from "opshot/react";
 
 const state = useMutableState({ index: new TrackedMap<string, number>() });
 
@@ -147,15 +151,20 @@ state.index.set("a", 1);
 
 ```tsx
 import { useEffect } from "react";
-import { subscribe, useMutableState } from "opshot";
+import { subscribe } from "opshot";
+import { useMutableState } from "opshot/react";
+
+interface Meta {
+	source: string;
+}
 
 const Counter = () => {
 	const counter = useMutableState({ count: 0 });
 
 	useEffect(
 		() =>
-			subscribe(counter, (operations) => {
-				// operations: [{ node, key: "count", before: 0, after: 1, meta: undefined }]
+			subscribe<Meta | undefined>(counter, (operations) => {
+				// operations: [{ kind: "change", node, key: "count", before: 0, after: 1, meta: undefined }]
 			}),
 		[counter],
 	);
@@ -169,26 +178,58 @@ const Counter = () => {
 An operation is one key's change on one node:
 
 ```ts
-interface Operation {
-	readonly node: object;
+interface AddOperation<Meta = unknown> {
+	readonly kind: "add";
+	readonly node: Record<string, unknown>; // The live state being applied to
+	readonly key: string;
+	readonly after: unknown;
+	readonly meta: Meta;
+}
+
+interface ChangeOperation<Meta = unknown> {
+	readonly kind: "change";
+	readonly node: Record<string, unknown>;
+	readonly key: string;
+	readonly before: unknown;
+	readonly after: unknown;
+	readonly meta: Meta;
+}
+
+interface DeleteOperation<Meta = unknown> {
+	readonly kind: "delete";
+	readonly node: Record<string, unknown>;
 	readonly key: string;
-	readonly before?: unknown;
-	readonly after?: unknown;
-	readonly meta: unknown;
+	readonly before: unknown;
+	readonly meta: Meta;
 }
+
+type Operation<Meta = unknown> = AddOperation<Meta> | ChangeOperation<Meta> | DeleteOperation<Meta>;
+```
+
+```ts
+const revert = (operation: Operation) => {
+	if (operation.kind === "add") delete operation.node[operation.key];
+	else operation.node[operation.key] = operation.before;
+};
+
+const apply = (operation: Operation) => {
+	if (operation.kind === "delete") delete operation.node[operation.key];
+	else operation.node[operation.key] = operation.after;
+};
 ```
 
-`before` and `after` are absent properties when the key was absent.
+Undo and redo are a switch on `kind`. Revert an emission in reverse and apply it forward.
 
 ## Emission
 
-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 state gathers its writes and delivers them together, in order. 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.
 
 `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, useMutableState } from "opshot";
+import { subscribe } from "opshot";
+import { useMutableState } from "opshot/react";
 
 const Chart = () => {
 	// One emission per frame, however many writes land in between.
@@ -206,7 +247,7 @@ const Chart = () => {
 };
 ```
 
-Separate from that callback, the `flush(state)` export ends the window from outside.
+Separate from that callback, the `flush(state, ...states)` export ends each state's window from outside.
 
 ## Batches
 
@@ -214,7 +255,8 @@ Separate from that callback, the `flush(state)` export ends the window from outs
 
 ```tsx
 import { useEffect } from "react";
-import { batch, subscribe, useMutableState } from "opshot";
+import { batch, subscribe } from "opshot";
+import { useMutableState } from "opshot/react";
 
 const TitleBar = () => {
 	const doc = useMutableState({ title: "Untitled" });
@@ -222,7 +264,7 @@ const TitleBar = () => {
 	useEffect(
 		() =>
 			subscribe(doc, (operations) => {
-				if (operations[0]?.meta === "replay") return;
+				const edits = operations.filter((operation) => operation.meta !== "replay");
 
 				// ...
 			}),
@@ -230,18 +272,35 @@ const TitleBar = () => {
 	);
 
 	const rename = () => {
-		batch(
-			() => {
-				doc.title = "Draft";
-			},
-			{ source: "editor" },
-		);
+		batch(() => {
+			doc.title = "Draft";
+		}, "editor");
 	};
 
 	// ...
 };
 ```
 
+## Identity
+
+```tsx
+const object = { name: "Ada", age: 36 };
+const state = useMutableState(object);
+
+object === state; // false
+isSameIdentity(object, state); // true
+
+isState(object); // false
+isState(state); // true
+```
+
+```tsx
+// The state's identity changes when the state or anything nested inside it changes.
+useEffect(() => {
+	// ...
+}, [state]);
+```
+
 ## License
 
 [MIT](LICENSE)