opshot 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -1,57 +1,21 @@
 import { ComponentType, FC } from 'react';
 
-declare const ignoreMarker: unique symbol;
 /**
- * A factory-argument marker wrapping `T`.
+ * Sets when a state's window flushes. Call `flush` once.
  *
- * @typeParam T - Value type.
- */
-interface Ignored<T> {
-    readonly [ignoreMarker]: T;
-}
-/**
- * Marks a factory-argument value so the edge at that path is untracked in that state.
- *
- * @typeParam T - Value type.
- * @param value - Value to ignore.
- * @returns A marker consumed at create.
- */
-declare function ignore<T>(value: T): Ignored<T>;
-
-declare const unsafeMarker: unique symbol;
-/**
- * A factory-argument marker wrapping `T`.
- *
- * @typeParam T - Value type.
- */
-interface UnsafeTracked<T> {
-    readonly [unsafeMarker]: T;
-}
-/**
- * Marks a factory-argument value so strict is disabled at and under that path.
- *
- * @typeParam T - Value type.
- * @param value - Value to track without strict.
- * @returns A marker consumed at create.
- */
-declare function unsafeTrack<T>(value: T): UnsafeTracked<T>;
-
-/**
- * Schedules when bare writes notify listeners. Call `flush` once.
- *
- * @param flush - Delivers pending ops.
+ * @param flush - Delivers pending operations.
  * @returns Nothing.
  */
 type EmissionScheduler = (flush: () => void) => void;
 /**
- * State creation options.
+ * Options for `createMutableState`.
  *
  * @example
- * createMutableState({ x: 0 }, { emitOn: (flush) => requestAnimationFrame(flush), strict: false })
+ * createMutableState({ count: 0 }, { emitOn, strict: false })
  */
-interface MutableNodeOptions {
+interface MutableStateOptions {
     /**
-     * When bare writes notify listeners. Defaults to a microtask.
+     * When the window flushes for all writes. Defaults to a microtask.
      */
     readonly emitOn?: EmissionScheduler;
     /**
@@ -59,366 +23,90 @@ interface MutableNodeOptions {
      */
     readonly strict?: boolean;
 }
-
-/**
- * Options for `createMutableState`.
- *
- * @example
- * createMutableState({ count: 0 }, { group, emitOn, strict: false })
- */
-interface MutableStateOptions extends MutableNodeOptions {
-    /**
-     * Group that receives this state's changes.
-     */
-    readonly group?: Group;
-}
-/**
- * The live state shape after factory-argument markers are collapsed.
- *
- * @typeParam T - Factory argument type.
- */
-type Unmarked<T> = T extends Ignored<infer Inner> ? Unmarked<Inner> : T extends UnsafeTracked<infer Inner> ? Unmarked<Inner> : T extends (...args: never) => unknown ? T : T extends ReadonlyArray<infer Element> ? Array<Unmarked<Element>> : T extends object ? {
-    [Key in keyof T]: Unmarked<T[Key]>;
-} : T;
 /**
  * Creates a mutable state object.
  *
- * `ignore()` on a value in the factory argument makes the edge at that path untracked in that state.
- * `unsafeTrack()` on a value in the factory argument disables strict at and under that path.
+ * `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, with factory-argument markers collapsed.
- */
-declare function createMutableState<T extends object>(properties: T, options?: MutableStateOptions): Unmarked<T>;
-
-/**
- * Path segments to a value in state.
- *
- * @example
- * ["document", "items", 0, "title"]
+ * @returns The state.
  */
-type OperationPath = ReadonlyArray<string | number>;
-
-interface DeclarationTrie {
-    readonly ignored: boolean;
-    readonly unsafe: boolean;
-    readonly children: ReadonlyMap<string, DeclarationTrie>;
-}
-
-interface InEdge {
-    readonly parent: object;
-    readonly key: string | number;
-}
-interface NodeRecord {
-    edges: Array<InEdge>;
-    id: number | undefined;
-}
-
-interface CaptureTables {
-    mints: Array<{
-        readonly node: object;
-        readonly id: number;
-    }>;
-    binds: Array<{
-        readonly node: object;
-        readonly id: number;
-    }>;
-    bindIdByNode: Map<object, number>;
-    bindNodeById: Map<number, object>;
-    mintIdByNode: Map<object, number>;
-    mintNodeById: Map<number, object>;
-    nextStagedId: number;
-}
-
-interface DirtyIndex {
-    readonly edges: WeakMap<object, Set<string | symbol>>;
-    readonly nodes: WeakSet<object>;
-}
-interface Handle {
-    proxy: {
-        readonly root: object;
-    };
-    lastSnapshot: object;
-    hasPendingWrites: boolean;
-    isFlushScheduled: boolean;
-    isFlushHeld: boolean;
-    flushGeneration: number;
-    subscribers: StateListeners;
-    groups?: ReadonlyArray<GroupListeners>;
-    disarmWatch?: () => void;
-    emitOn?: EmissionScheduler;
-    strict: boolean;
-    declarations: DeclarationTrie | undefined;
-    nodes: WeakMap<object, NodeRecord>;
-    byId: Map<number, object>;
-    nextInternId: number;
-    lastDirty?: DirtyIndex;
-    stamp: object;
-    version: number;
-    replaying: boolean;
-    transactionCapture?: CaptureTables;
-}
+declare function createMutableState<T extends object>(properties: T, options?: MutableStateOptions): T;
 
 /**
- * Assigns a value at a path.
- *
- * @example
- * { verb: "assign", path: ["count"], value: 1 }
- */
-interface AssignMutation {
-    /**
-     * `"assign"`.
-     */
-    readonly verb: "assign";
-    /**
-     * Path to assign.
-     */
-    readonly path: OperationPath;
-    /**
-     * Value to assign.
-     */
-    readonly value: unknown;
-    /**
-     * Walk-ordered intern ids that override deterministic vending when this half re-admits departed material.
-     */
-    readonly ids?: ReadonlyArray<number>;
-}
-/**
- * Deletes the value at a path.
- *
- * @example
- * { verb: "delete", path: ["temp"] }
- */
-interface DeleteMutation {
-    /**
-     * `"delete"`.
-     */
-    readonly verb: "delete";
-    /**
-     * Path to delete.
-     */
-    readonly path: OperationPath;
-}
-/**
- * Links the interned node `ref` into `path`.
- *
- * @example
- * { verb: "link", path: ["alias"], ref: 0 }
- */
-interface LinkMutation {
-    /**
-     * `"link"`.
-     */
-    readonly verb: "link";
-    /**
-     * Path to place the linked node.
-     */
-    readonly path: OperationPath;
-    /**
-     * Intern id of the node to link.
-     */
-    readonly ref: number;
-}
-/**
- * An assign, a delete, or a link.
+ * Returns a stable identity key for a value.
  *
- * @example
- * { verb: "assign", path: ["profile"], value: { name: "Ada" } }
+ * @param value - Value to identify.
+ * @returns Identity key.
  */
-type Mutation = AssignMutation | DeleteMutation | LinkMutation;
+declare function identify(value: object): object;
 /**
- * A change with do and undo halves.
+ * Returns whether two values share the same identity.
  *
- * @example
- * { do: { verb: "assign", path: ["count"], value: 1 }, undo: { verb: "assign", path: ["count"], value: 0 } }
+ * @param first - First value.
+ * @param second - Second value.
+ * @returns True if they match.
  */
-interface Operation {
-    /**
-     * Forward operation.
-     */
-    readonly do: Mutation;
-    /**
-     * Reverse operation.
-     */
-    readonly undo: Mutation;
-}
+declare function isSameIdentity(first: object, second: object): boolean;
 
 /**
- * Listener for one state's changes.
- *
- * @param ops - Ops for the change.
- * @param meta - Writer meta, if any.
- * @returns Nothing.
- */
-type StateListener = (ops: ReadonlyArray<Operation>, meta: unknown) => void;
-/**
- * Listener for a group's changes.
+ * Returns whether a value is an opshot state.
  *
- * @param state - State that changed.
- * @param ops - Ops for the change.
- * @param meta - Writer meta, if any.
- * @returns Nothing.
+ * @param value - Value to test.
+ * @returns True if it is a state.
  */
-type GroupListener = (state: object, ops: ReadonlyArray<Operation>, meta: unknown) => void;
-type StateDeliver = (ops: ReadonlyArray<Operation>, meta: unknown, channelId: object | undefined) => void;
-type GroupDeliver = (state: object, ops: ReadonlyArray<Operation>, meta: unknown, channelId: object | undefined) => void;
-type StateListeners = Map<Function, Map<object | undefined, StateDeliver>>;
-type GroupListeners = Map<Function, Map<object | undefined, GroupDeliver>>;
+declare function isState(value: unknown): value is object;
 
 /**
- * Creates states and receives their changes on one stream.
+ * A change to one key of a node.
  *
  * @example
- * const group = createGroup()
- * const doc = group.createMutableState({ title: "" })
- * subscribe(group, (state, ops, meta) => {})
+ * { node, key: "count", before: 0, after: 1, meta: undefined }
  */
-interface Group {
+interface Operation {
     /**
-     * Creates a state in this group.
-     *
-     * @typeParam T - State shape.
-     * @param properties - Initial fields.
-     * @param options - Creation options.
-     * @returns The state.
+     * Node that changed.
      */
-    createMutableState<T extends object>(properties: T, options?: MutableNodeOptions): Unmarked<T>;
-}
-/**
- * Creates a group.
- *
- * @param parent - Optional parent group whose listeners hear this group's states.
- * @returns A new group.
- */
-declare function createGroup(parent?: Group): Group;
-
-/**
- * Listener context from a channel subscription.
- *
- * @typeParam M - Meta type for this channel.
- */
-type EmissionContext<M> = {
-    readonly isTransaction: true;
-    readonly meta: M;
-} | {
-    readonly isTransaction: false;
-    readonly meta: unknown;
-};
-/**
- * Listens for changes from a group's states.
- *
- * @param group - Group to listen to.
- * @param listener - Called on each change.
- * @returns Unsubscribe function.
- */
-declare function subscribe(group: Group, listener: GroupListener): () => void;
-/**
- * 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;
-
-type ApplyDirection = "do" | "undo";
-
-/**
- * Channel-bound `transact`, `subscribe`, and `applyOperations`.
- *
- * @typeParam M - Meta type for this channel.
- */
-interface Channel<M extends object> {
+    readonly node: object;
     /**
-     * Runs a transaction with this channel's meta.
-     *
-     * @param state - State to change.
-     * @param mutate - Function that writes the state.
-     * @param meta - Meta for this write.
-     * @returns Nothing.
+     * Key that changed.
      */
-    transact(state: object, mutate: () => void, meta?: Partial<M>): void;
+    readonly key: string;
     /**
-     * Listens for changes from a group's states.
-     *
-     * @param group - Group to listen to.
-     * @param listener - Called on each change.
-     * @returns Unsubscribe function.
+     * Value before, absent when the key was absent.
      */
-    subscribe(group: Group, listener: (state: object, ops: ReadonlyArray<Operation>, context: EmissionContext<M>) => void): () => void;
+    readonly before?: unknown;
     /**
-     * Listens for changes to a state.
-     *
-     * @param state - State to listen to.
-     * @param listener - Called on each change.
-     * @returns Unsubscribe function.
+     * Value after, absent when the key is absent.
      */
-    subscribe(state: object, listener: (ops: ReadonlyArray<Operation>, context: EmissionContext<M>) => void): () => void;
+    readonly after?: unknown;
     /**
-     * Applies operations with this channel's meta.
-     *
-     * @param state - State to change.
-     * @param operations - Operations to apply.
-     * @param direction - `"do"` or `"undo"`.
-     * @param meta - Meta for this write.
-     * @returns Nothing.
+     * Meta of the batch the write was made in.
      */
-    applyOperations(state: object, operations: ReadonlyArray<Operation>, direction: ApplyDirection, meta?: Partial<M>): void;
+    readonly meta: unknown;
 }
-/**
- * Creates a channel with a typed meta convention.
- *
- * @typeParam M - Meta type for this channel.
- * @param defaults - Default meta for this channel's writes.
- * @returns The channel.
- */
-declare function createChannel<M extends object>(defaults?: M): Channel<M>;
 
 /**
- * Returns a stable identity key for a value.
+ * Marks an object so every edge to it is untracked in every state.
  *
- * @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;
-
-/**
- * Applies operations to a state.
- *
- * @param state - State to change.
- * @param operations - Operations to apply.
- * @param direction - `"do"` or `"undo"`.
- * @param meta - Passed to listeners.
- * @returns Nothing.
+ * @typeParam T - Value type.
+ * @param value - Value to mark or unmark.
+ * @param on - Whether the mark is set.
+ * @returns `value`.
  */
-declare function applyOperations(state: object, operations: ReadonlyArray<Operation>, direction: ApplyDirection, meta?: unknown): void;
+declare function ignore<T>(value: T, on?: boolean): T;
 
 /**
- * Diffs two plain objects into ops.
+ * Marks an object so a node entering a state while marked, or entering beneath an exempt node, is exempt from strict.
  *
- * @param before - Earlier value.
- * @param after - Later value.
- * @returns Ops from before to after.
+ * @typeParam T - Value type.
+ * @param value - Value to mark or unmark.
+ * @param on - Whether the mark is set.
+ * @returns `value`.
  */
-declare function diffObjects(before: object, after: object, handle?: Handle, dirty?: DirtyIndex, capture?: CaptureTables): Array<Operation>;
+declare function unsafeTrack<T>(value: T, on?: boolean): T;
 
 type DateConstructorArgs = [] | [value: number | string] | [
     year: number,
@@ -539,14 +227,35 @@ declare class TrackedSet<T> {
 }
 
 /**
- * Runs changes in one batch and notifies listeners with optional `meta`.
+ * Listener for one state's changes.
  *
- * @param state - State to change.
- * @param mutate - Function that writes the state.
- * @param meta - Passed to listeners.
- * @returns Nothing.
+ * @param operations - Operations for the change.
+ */
+type StateListener = (operations: ReadonlyArray<Operation>) => void;
+
+/**
+ * Listens for changes to a state.
+ *
+ * @param state - State to listen to.
+ * @param listener - Called on each change.
+ * @returns Unsubscribe function.
  */
-declare function transact(state: object, mutate: () => void, meta?: unknown): void;
+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;
+
+/**
+ * Ends the state's window now, delivering the operations gathered so far.
+ *
+ * @param state - State to flush.
+ */
+declare function flush(state: object): void;
 
 /**
  * Wraps a component so it re-renders only when fields it read change.
@@ -557,14 +266,6 @@ declare function transact(state: object, mutate: () => void, meta?: unknown): vo
  */
 declare function scope<P extends object>(Component: ComponentType<P>): FC<P>;
 
-/**
- * Creates a group for a component.
- *
- * @param parent - Optional parent group whose listeners hear this group's states.
- * @returns The group.
- */
-declare function useGroup(parent?: Group): Group;
-
 /**
  * Creates mutable state for a component.
  *
@@ -573,6 +274,6 @@ declare function useGroup(parent?: Group): Group;
  * @param options - Creation options.
  * @returns The state.
  */
-declare function useMutableState<T extends object>(properties: (() => T) | T, options?: MutableStateOptions): Unmarked<T>;
+declare function useMutableState<T extends object>(properties: (() => T) | T, options?: MutableStateOptions): T;
 
-export { type Channel, type EmissionContext, type EmissionScheduler, type Group, type GroupListener, type Ignored, type MutableNodeOptions, type MutableStateOptions, type Operation, type OperationPath, type StateListener, TrackedDate, TrackedMap, TrackedSet, type UnsafeTracked, applyOperations, createChannel, createGroup, createMutableState, diffObjects, identify, ignore, isSameIdentity, isState, scope, subscribe, transact, unsafeTrack, useGroup, useMutableState };
+export { type EmissionScheduler, type MutableStateOptions, type Operation, type StateListener, TrackedDate, TrackedMap, TrackedSet, batch, createMutableState, flush, identify, ignore, isSameIdentity, isState, scope, subscribe, unsafeTrack, useMutableState };