opshot 0.2.1 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Cavender
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 # opshot
 
-Mutable state for React, with re-render for only the components that read what changed. (It's [valtio](https://github.com/pmndrs/valtio), but not a footgun.)
+Mutable state for React, with re-render for only the components that read what changed. (It's like [valtio](https://github.com/pmndrs/valtio), but not a footgun.)
 
 ## Install
 
@@ -20,12 +20,12 @@ const [user, setUser] = useState({ name: "Ada", age: 36 });
 setUser((prev) => ({ ...prev, age: 37 }));
 ```
 
-opshot state is mutable: you assign the field.
+**opshot** state is a live mutable object: you assign the field.
 
 ```tsx
-const user = useTrackedState({ name: "Ada", age: 36 });
+const user = useMutableState({ name: "Ada", age: 36 });
 
-user.mutate((mutable) => (mutable.age = 37));
+user.age = 37;
 ```
 
 ## Bounded re-renders
@@ -55,13 +55,15 @@ const Parent = () => {
 const Child = ({ user }: { user: User }) => <p>{user.age}</p>;
 ```
 
-opshot re-renders only what read the change. Wrap a child in `retrack` and it subscribes to the fields it reads. **Where the mutation happens doesn't matter** — here Parent writes, and only Child re-renders, because renders follow reads, not writes.
+**opshot** re-renders only what read the change. Wrap a child in `scope` and it subscribes to the fields it reads. **Where the mutation happens doesn't matter** — here Parent writes, and only Child re-renders, because renders follow reads, not writes.
 
 ```tsx
 const Parent = () => {
-	const user = useTrackedState<User>({ name: "Ada", age: 36 });
+	const user = useMutableState<User>({ name: "Ada", age: 36 });
 
-	const birthday = () => user.mutate((mutable) => mutable.age++);
+	const birthday = () => {
+		user.age++;
+	};
 
 	// A click re-renders only Child.
 	return (
@@ -72,145 +74,235 @@ const Parent = () => {
 	);
 };
 
-const Child = retrack<{ user: State<User> }>(({ user }) => <p>{user.age}</p>);
+const Child = scope<{ user: User }>(({ user }) => <p>{user.age}</p>);
 ```
 
-This is how you optimize re-rendering across your component tree: place `retrack` boundaries where you want re-renders contained, and each boundary re-renders only when a field it read changes. `useTrackedState` is a boundary itself.
+This is how you optimize re-rendering across your component tree: place `scope` boundaries where you want re-renders contained, and each boundary re-renders only when a field it read changes. `useMutableState` is a boundary itself.
 
 ## Creating State
 
 ```tsx
-import { ref } from "opshot";
-import { useTrackedState } from "opshot/react";
+import { ignore, unsafeTrack, useMutableState, type Ignored, type UnsafeTracked } from "opshot";
+
+interface PlayerState {
+	position: number;
+	element: Ignored<HTMLAudioElement>;
+	queue: UnsafeTracked<Playlist>;
+	seek: (position: number) => void;
+}
 
 const Player = () => {
-	const player = useTrackedState((mutate, get) => ({
+	const player = useMutableState<PlayerState>({
 		position: 0,
 
-		// ref() keeps a value out of reactivity and ops.
-		element: ref(new Audio()),
+		// ignore() keeps a value out of reactivity and ops.
+		element: ignore(new Audio()),
+
+		// unsafeTrack() tracks all the values it can, even if there is weird behaviour
+		queue: unsafeTrack(new Playlist()),
 
-		// get() reads the current values.
-		seek: (position: number) => {
-			get().element.currentTime = position;
+		seek(position: number) {
+			this.element.currentTime = position;
 
-			mutate((mutable) => (mutable.position = position));
+			if (this.position === position) return;
+
+			this.position = position;
 		},
-	}));
+	});
 
 	// ...
 };
 ```
 
-## Tracked State
+## Constraints
+
+opshot tracks plain data.
+
+It can't track:
+
+- Internal slots (language level features like in Map)
+- #private fields (hidden at the language level)
+- Arrow methods on classes (they write to the original object, not the tracked one)
+- Array subclasses (the prototype is lost when copied)
+
+Use `ignore` or `unsafeTrack` when dealing with these.
+
+## Tracked collections
 
-Everything opshot attaches lives under two reserved keys, `mutate` and `op`.
+`TrackedMap`, `TrackedSet`, and `TrackedDate` stand in for the built-ins opshot rejects. They have the exact same API as their counterparts.
 
 ```ts
-// The write path. An optional second argument is passed to every subscriber.
-counter.mutate((mutable) => mutable.count++, { transactionKey: "drag" });
+import { TrackedMap, useMutableState } from "opshot";
 
-// Hears every op this state emits; returns an unsubscribe.
-const unsubscribe = counter.op.subscribe((state, ops, meta) => {
-	// ...
-});
+const state = useMutableState({ index: new TrackedMap<string, number>() });
+
+state.index.set("a", 1);
+```
+
+## Subscribe
 
-// State references are not reliable for equality: every mutation produces a new one. Use this instead.
-counter.op.isSameState(other);
+`subscribe` hears every change to a state.
 
-// True while a mutate callback is running.
-counter.op.isMutating;
+```tsx
+import { useEffect } from "react";
+import { subscribe, useMutableState } from "opshot";
 
-// The current values as your plain object, op stripped: for serializing and reads outside render.
-counter.op.unwrap();
+const Counter = () => {
+	const counter = useMutableState({ count: 0 });
+
+	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
+			}),
+		[counter],
+	);
 
-// The underlying valtio proxy, typed object: an escape hatch.
-counter.op.unsafeMutable;
+	// ...
+};
 ```
 
 ## Ops
 
+An op is an invertible pair of `Operation` halves. Every half uses one of three verbs:
+
 ```ts
-const unsubscribe = counter.op.subscribe((state, ops, meta) => {
-	// state: the snapshot these ops produced
-	// ops: [{
-	//   do:   { op: "replace", path: "/count", value: 1 },
-	//   undo: { op: "replace", path: "/count", value: 0 },
-	// }]
-});
+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;
+}
 ```
 
-An op is a pair of [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) patch operations, each half carrying its own value, so any JSON Patch tool applies and inverts them.
+`applyOps` puts them back on a state, so a history is a list of ops and an undo is their `undo` halves in reverse.
 
-A subscriber must not write to the state it subscribes to; writing to a different state is fine.
+```tsx
+import { useEffect, useRef } from "react";
+import { applyOps, subscribe, useMutableState, type Op } from "opshot";
 
-Ops cost nothing until someone listens: a state with no subscribers, on itself or its group, skips computing them entirely.
+const replay = {};
 
-## Meta
+const Counter = () => {
+	const counter = useMutableState({ count: 0 });
+	const history = useRef<Array<ReadonlyArray<Op>>>([]);
 
-`mutate`'s optional second argument is delivered to every subscriber alongside the ops.
+	useEffect(
+		() =>
+			subscribe(counter, (ops, meta) => {
+				// Skip our own replays, so undo doesn't record itself.
+				if (meta === replay) return;
 
-To type it, declare a meta token once and pass it in.
+				history.current.push(ops);
+			}),
+		[counter],
+	);
 
-```tsx
-import { useEffect } from "react";
-import { createMeta } from "opshot";
-import { useTrackedState } from "opshot/react";
+	const undo = () => {
+		const ops = history.current.pop();
 
-interface DocumentMeta {
-	replay?: boolean;
-}
+		if (!ops) return;
+
+		applyOps(
+			counter,
+			[...ops].reverse().map((op) => op.undo),
+			replay,
+		);
+	};
 
-// Declared once, at module scope.
-const documentMeta = createMeta<DocumentMeta>();
+	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.
+
+```tsx
+import { useEffect } from "react";
+import { subscribe, useGroup, useMutableState } from "opshot";
 
 const Editor = () => {
-	const doc = useTrackedState({ title: "Untitled" }, documentMeta);
+	const group = useGroup();
 
-	// A history replaying an undone op marks the write, so recorders can tell it apart.
-	// The meta argument is typed DocumentMeta.
-	const undo = () => doc.mutate((mutable) => (mutable.title = "Untitled"), { replay: true });
+	// 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);
 
 	useEffect(
 		() =>
-			// The subscriber's meta parameter is typed DocumentMeta.
-			doc.op.subscribe((state, ops, meta) => {
-				// A recorder skips its own replays.
-				if (meta.replay) return;
-
+			// Fires for doc, selection, and every other state the group created.
+			// state is whichever one changed.
+			subscribe(group, (state, ops, meta) => {
 				// ...
 			}),
-		[doc.op],
+		[group],
 	);
 
 	// ...
 };
 ```
 
-## Groups
+## Channels
 
-A group creates states and hears every op from the states it created: one stream for history, sync, and persistence.
+A channel binds `transact`, `subscribe`, and `applyOps` to a typed meta convention, so a listener can tell its own writes from everyone else's.
 
 ```tsx
 import { useEffect } from "react";
-import { useGroup, useTrackedState } from "opshot/react";
+import { createChannel, useMutableState } from "opshot";
 
-const Editor = () => {
-	// A lifetime-stable group.
-	const group = useGroup();
+interface DocumentMeta {
+	replay?: boolean;
+	source?: string;
+}
+
+const docChannel = createChannel<DocumentMeta>({ source: "editor" }); // set defaults
 
-	// Created through the group, so its ops reach the group's subscribers.
-	const doc = useTrackedState({ items: new Array<string>() }, group);
+const TitleBar = () => {
+	const doc = useMutableState({ title: "Untitled" });
 
 	useEffect(
 		() =>
-			// Fires for doc and every other state the group created.
-			group.subscribe((state, ops, meta) => {
+			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;
+
 				// ...
 			}),
-		[group],
+		[doc],
 	);
 
+	const rename = () => {
+		docChannel.transact(doc, () => {
+			doc.title = "Draft";
+		});
+	};
+
 	// ...
 };
 ```
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -1,56 +1,185 @@
-import { Snapshot } from 'valtio/vanilla';
-export { Snapshot, ref } from 'valtio/vanilla';
+import { ComponentType, FC } from 'react';
 
-type PatchOperation = {
+type OperationPath = ReadonlyArray<string | number>;
+
+interface AddOperation {
     readonly op: "add";
-    readonly path: string;
+    readonly path: OperationPath;
     readonly value: unknown;
-} | {
+}
+interface ReplaceOperation {
     readonly op: "replace";
-    readonly path: string;
+    readonly path: OperationPath;
     readonly value: unknown;
-} | {
+}
+interface RemoveOperation {
     readonly op: "remove";
-    readonly path: string;
-};
+    readonly path: OperationPath;
+}
+type Operation = AddOperation | ReplaceOperation | RemoveOperation;
 interface Op {
-    readonly do: PatchOperation;
-    readonly undo: PatchOperation;
-}
-declare function diffSnapshots(before: unknown, after: unknown): Array<Op>;
-
-type MetaRecord = Record<string, unknown>;
-declare const metaIn: unique symbol;
-interface Meta<In extends object = MetaRecord, Out extends object = MetaRecord> {
-    readonly defaults?: Out;
-    readonly [metaIn]?: (value: In) => void;
-}
-type Mutate<T extends object, In extends object = MetaRecord> = (callback: (mutable: T) => void, ...meta: {} extends In ? [meta?: In] : [meta: In]) => void;
-type StateListener<T extends object, In extends object = MetaRecord, Out extends object = MetaRecord> = (state: State<T, In, Out>, ops: Array<Op>, meta: Out) => void;
-interface OpshotHandle<T extends object, In extends object = MetaRecord, Out extends object = MetaRecord> {
-    readonly unsafeMutable: object;
-    readonly isMutating: boolean;
-    readonly subscribe: (listener: StateListener<T, In, Out>) => () => void;
-    readonly isSameState: (other: unknown) => boolean;
-    readonly unwrap: () => Snapshot<T>;
-}
-type State<T extends object, In extends object = MetaRecord, Out extends object = MetaRecord> = Snapshot<T> & {
-    readonly mutate: Mutate<T, In>;
-    readonly op: OpshotHandle<T, In, Out>;
-};
-type DefineCallback<T extends object, In extends object = MetaRecord, Out extends object = MetaRecord> = (mutate: Mutate<T, In>, get: () => State<T, In, Out>) => T;
-type Define<T extends object, In extends object = MetaRecord, Out extends object = MetaRecord> = DefineCallback<T, In, Out> | T;
-declare function createMeta<M extends object>(): Meta<M, M>;
-declare function createMeta<M extends object>(defaults: M): Meta<Partial<M>, M>;
-declare function createState<T extends object>(define: Define<T>): State<T>;
-declare function createState<T extends object, In extends object, Out extends object>(define: Define<T, In, Out>, meta: Meta<In, Out>): State<T, In, Out>;
-declare function isState(value: unknown): value is State<object>;
-
-interface Group<In extends object = MetaRecord, Out extends object = MetaRecord> {
-    createState<T extends object>(define: Define<T, In, Out>): State<T, In, Out>;
-    subscribe(listener: StateListener<object, In, Out>): () => void;
+    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;
 }
 declare function createGroup(): Group;
-declare function createGroup<In extends object, Out extends object>(meta: Meta<In, Out>): Group<In, Out>;
 
-export { type Define, type DefineCallback, type Group, type Meta, type MetaRecord, type Mutate, type Op, type OpshotHandle, type PatchOperation, type State, type StateListener, createGroup, createMeta, createState, diffSnapshots, isState };
+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;
+
+declare function identify(value: object): object;
+declare function isSameIdentity(first: object, second: object): boolean;
+
+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>;
+
+declare const unsafeTrackedBrand: unique symbol;
+type UnsafeTracked<T extends object> = T & {
+    readonly [unsafeTrackedBrand]: true;
+};
+declare function unsafeTrack<T extends object>(value: T): UnsafeTracked<T>;
+
+type DateConstructorArgs = [] | [value: number | string] | [
+    year: number,
+    monthIndex: number,
+    date?: number,
+    hours?: number,
+    minutes?: number,
+    seconds?: number,
+    milliseconds?: number
+];
+declare class TrackedDate {
+    private epochMs;
+    constructor(...args: DateConstructorArgs);
+    private readDate;
+    private write;
+    toString(): string;
+    toDateString(): string;
+    toTimeString(): string;
+    toLocaleString(locales?: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions): string;
+    toLocaleDateString(locales?: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions): string;
+    toLocaleTimeString(locales?: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions): string;
+    valueOf(): number;
+    getTime(): number;
+    getFullYear(): number;
+    getYear(): number;
+    getUTCFullYear(): number;
+    getMonth(): number;
+    getUTCMonth(): number;
+    getDate(): number;
+    getUTCDate(): number;
+    getDay(): number;
+    getUTCDay(): number;
+    getHours(): number;
+    getUTCHours(): number;
+    getMinutes(): number;
+    getUTCMinutes(): number;
+    getSeconds(): number;
+    getUTCSeconds(): number;
+    getMilliseconds(): number;
+    getUTCMilliseconds(): number;
+    getTimezoneOffset(): number;
+    setYear(year: number): number;
+    setTime(...args: [time: number]): number;
+    setMilliseconds(...args: [milliseconds: number]): number;
+    setUTCMilliseconds(...args: [milliseconds: number]): number;
+    setSeconds(...args: [seconds: number, milliseconds?: number]): number;
+    setUTCSeconds(...args: [seconds: number, milliseconds?: number]): number;
+    setMinutes(...args: [minutes: number, seconds?: number, milliseconds?: number]): number;
+    setUTCMinutes(...args: [minutes: number, seconds?: number, milliseconds?: number]): number;
+    setHours(...args: [hours: number, minutes?: number, seconds?: number, milliseconds?: number]): number;
+    setUTCHours(...args: [hours: number, minutes?: number, seconds?: number, milliseconds?: number]): number;
+    setDate(...args: [dateValue: number]): number;
+    setUTCDate(...args: [dateValue: number]): number;
+    setMonth(...args: [month: number, dateValue?: number]): number;
+    setUTCMonth(...args: [month: number, dateValue?: number]): number;
+    setFullYear(...args: [year: number, month?: number, dateValue?: number]): number;
+    setUTCFullYear(...args: [year: number, month?: number, dateValue?: number]): number;
+    toUTCString(): string;
+    toGMTString(): string;
+    toISOString(): string;
+    [Symbol.toPrimitive](hint: "default" | "string" | "number"): string | number;
+    readonly [Symbol.toStringTag]: "TrackedDate";
+}
+
+declare class TrackedMap<K, V> {
+    private slots;
+    private index;
+    private count;
+    constructor(entries?: Iterable<readonly [K, V]>);
+    get size(): number;
+    has(key: K): boolean;
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    clear(): void;
+    entries(): IterableIterator<[K, V]>;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    forEach(callback: (value: V, key: K, map: TrackedMap<K, V>) => void): void;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    readonly [Symbol.toStringTag]: "TrackedMap";
+}
+
+declare class TrackedSet<T> {
+    private slots;
+    private index;
+    private count;
+    constructor(values?: Iterable<T>);
+    get size(): number;
+    has(value: T): boolean;
+    add(value: T): this;
+    delete(value: T): boolean;
+    clear(): void;
+    entries(): IterableIterator<[T, T]>;
+    keys(): IterableIterator<T>;
+    values(): IterableIterator<T>;
+    forEach(callback: (value: T, key: T, set: TrackedSet<T>) => void): void;
+    [Symbol.iterator](): IterableIterator<T>;
+    readonly [Symbol.toStringTag]: "TrackedSet";
+}
+
+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>;
+
+declare function useGroup(): Group;
+
+declare function useMutableState<T extends object>(properties: T, group?: Group): 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 };