@synnaxlabs/client 0.56.1 → 0.57.0

package/dist/src/actions/controller.d.ts

@@ -0,0 +1,194 @@
+import { destructor, record, TimeSpan, TimeStamp } from '@synnaxlabs/x';
+import { default as z } from 'zod';
+import { query } from '../query';
+import { Table } from '../query/table';
+export interface StackEntry<Action> {
+    forward: Action[];
+    inverse: Action[];
+    kind: string;
+    /** Wall-clock push time, used only for coalescing. */
+    ts: TimeStamp;
+    /** Tick of the earliest push, used to order the entry against remote touches. */
+    tick: number;
+    targets: readonly string[];
+}
+export interface Reducer<State extends query.Data, Action> {
+    (state: State, actions: Action[]): {
+        next: State;
+        inverse: Action[];
+        targets: readonly string[];
+    };
+}
+/** Result of replaying a set of actions locally. The caller commits the
+ *  matching server send and runs `rollback` on failure. */
+export interface ReplayResult<Action> {
+    processed: Action[];
+    inverse: Action[];
+    targets: readonly string[];
+    changed: boolean;
+    rollback: destructor.Destructor;
+}
+/** Result of preparing to undo or redo. The caller applies `actions` and runs
+ *  `commit` on success (which itself returns a destructor for failure-rollback). */
+export interface Reversal<Action> {
+    actions: Action[];
+    commit: () => destructor.Destructor;
+}
+/**
+ * A staged set of dispatches committed atomically as one undoable. Commit
+ * resolves false when there is nothing to send; a send failure rolls back the
+ * staged state and rethrows.
+ */
+export interface Transaction<Action> {
+    add: (actions: Action | Action[]) => void;
+    commit: () => Promise<boolean>;
+    abort: () => void;
+}
+/** Sends an already-processed action list to the server. Supplied by the
+ *  caller so the controller stays free of network concerns. */
+export type Send<Action> = (actions: Action[]) => Promise<void>;
+/**
+ * Network send used by the dispatch/undo/redo loops. Receives the
+ * controller-generated dispatch key that was registered as outstanding before
+ * the call, so the broadcast echo is recognized as own.
+ */
+export type SendDispatch<Action> = (actions: Action[], dispatchKey: string) => Promise<void>;
+/** Rewrites an action batch against the current document before replay. */
+export type Preprocess<State, Action> = (state: State, actions: Action[]) => Action[];
+/** Options accepted by domain-client dispatch methods. */
+export interface Options<State, Action> {
+    /**
+     * Per-call action rewrite requiring caller context the domain client lacks
+     * (e.g. diagram geometry). Runs against the cached doc before replay.
+     */
+    preprocess?: Preprocess<State, Action>;
+}
+/** The action-dispatch surface a document domain client exposes. */
+export interface Domain<Key extends record.Key, State extends query.Data, Action> {
+    dispatch(key: Key, actions: Action | Action[], opts?: Options<State, Action>): Promise<boolean>;
+    undo(key: Key): Promise<boolean>;
+    redo(key: Key): Promise<boolean>;
+    hasUndo(key: Key): boolean;
+    hasRedo(key: Key): boolean;
+    onUndoStateChange(callback: () => void, key?: Key): destructor.Destructor;
+    beginTransaction(key: Key, kind?: string): Transaction<Action>;
+}
+/**
+ * The canonical wire shape for a broadcast action frame. The consumer's `schema` must
+ * produce this shape (use a zod transform if the server emits differently-named
+ * fields). `seq` is a per-key monotonic sequence stamped by the originating server node
+ * and is used to skip echoes that are stale relative to the high-water mark — see
+ * `applyRemote`. `dispatchKey` is the client-generated batch identifier the originator
+ * registered as outstanding before sending; it is used to recognize own echoes
+ * race-safely so a redundant reduce can be skipped when no foreign action interleaved.
+ */
+export interface Frame<Key, Action> {
+    key: Key;
+    dispatchKey: string;
+    seq: number;
+    actions: Action[];
+}
+export interface ControllerParams<Key extends record.Key, State extends query.Data, Action> {
+    /** The table holding the documents this controller dispatches over. */
+    store: Table<Key, State>;
+    /** Reports listener errors that have no caller to throw to. */
+    onError: (error: Error) => void;
+    reduce: Reducer<State, Action>;
+    preprocess?: (state: State, actions: Action[]) => Action[];
+    isUndoable?: (action: Action) => boolean;
+    kindOf?: (actions: Action[]) => string;
+    /**
+     * Returns the document carried by a create action, undefined otherwise.
+     * Lets remote frames for never-cached documents ingest instead of drop.
+     */
+    createOf?: (action: Action) => State | undefined;
+    coalesceWindow?: TimeSpan;
+    stackCap?: number;
+    /** Clock stamping entries for the coalesce window. Defaults to TimeStamp.now. */
+    now?: () => TimeStamp;
+}
+/**
+ * Owns the action-dispatch loop for one document table: local replay with
+ * rollback, per-doc undo/redo stacks, echo recognition, and remote-frame
+ * application. Operates on a plain cache table; all dispatch bookkeeping is
+ * session-local and dropped when a document's row is deleted (tombstoned).
+ */
+export declare class Controller<Key extends record.Key, State extends query.Data, Action> {
+    private readonly docs;
+    private readonly undos;
+    private readonly params;
+    private readonly lastAppliedSeq;
+    private readonly outstandingDispatches;
+    private tick;
+    constructor(opts: ControllerParams<Key, State, Action>);
+    private drop;
+    private updateUndo;
+    /**
+     * Run preprocess + reduce against the cached doc and write the result.
+     * Returns the reducer output and a rollback that restores the prior doc
+     * state. Returns null if the doc isn't cached.
+     */
+    replay(key: Key, actions: Action[], opts?: {
+        skipPreprocess?: boolean;
+    }): ReplayResult<Action> | null;
+    /**
+     * Append an undoable entry to the stack. Filters non-undoable actions,
+     * derives the kind, and coalesces with the prior entry if it falls within
+     * the configured window with matching kind/targets. Clears redo.
+     */
+    recordEntry(key: Key, forward: Action[], inverse: Action[], targets: readonly string[], kindOverride?: string): destructor.Destructor;
+    private prepareReversal;
+    private applySend;
+    /**
+     * Apply an action batch to the cached doc and send it to the server,
+     * recording an undoable entry. Returns false without side effects when the
+     * doc isn't cached. Rolls back the local apply and rethrows on send failure.
+     */
+    dispatch(key: Key, actions: Action[], send: SendDispatch<Action>, opts?: Options<State, Action>): Promise<boolean>;
+    /**
+     * Apply and send the top live undo entry, moving it to the redo stack. Returns false
+     * when nothing is undoable. Rolls back and rethrows on send failure.
+     */
+    undo(key: Key, send: SendDispatch<Action>): Promise<boolean>;
+    /** Mirror of {@link undo} for the redo stack. */
+    redo(key: Key, send: SendDispatch<Action>): Promise<boolean>;
+    /**
+     * Stage actions committed atomically as one undoable entry, registering the batch as
+     * outstanding before the send so the broadcast echo is recognized as own.
+     */
+    transaction(key: Key, send: SendDispatch<Action>, kind?: string): Transaction<Action>;
+    prepareUndo(key: Key): Reversal<Action> | null;
+    prepareRedo(key: Key): Reversal<Action> | null;
+    beginTransaction(key: Key, send: Send<Action>, kind?: string): Transaction<Action>;
+    markRemoteTouched(key: Key, targets: readonly string[]): destructor.Destructor;
+    /** Whether any locally replayed dispatch for the key still awaits its echo. */
+    hasOutstanding(key: Key): boolean;
+    /**
+     * Register a dispatch as outstanding so when its broadcast echo arrives it
+     * can be recognized as own and a redundant reduce skipped. Called by the
+     * dispatcher *before* the network send so the registration always wins the
+     * race against a fast echo. A registration whose echo has already been
+     * applied (seq advanced past it) is silently dropped; that's the safe
+     * fallback when the echo arrives before the dispatch promise resolves.
+     */
+    registerOutstandingDispatch(key: Key, dispatchKey: string): void;
+    /**
+     * Apply a remote frame. The frame is dropped if its seq does not exceed the
+     * high-water mark previously applied for this key. If `dispatchKey` matches an entry
+     * the originator registered as outstanding, these actions were already applied via
+     * replay: if no foreign action interleaved during the outstanding window, skip the
+     * reduce; otherwise re-run it to recover from the foreign overwrite. A foreign frame
+     * (one whose dispatchKey is unknown) always reduces and marks every outstanding own
+     * dispatch with a greater seq as needing recovery.
+     */
+    applyRemote(key: Key, seq: number, dispatchKey: string, actions: Action[]): void;
+    hasUndo(key: Key): boolean;
+    hasRedo(key: Key): boolean;
+    onUndoStateChange(callback: () => void, key?: Key): destructor.Destructor;
+    /**
+     * Builds a channel listener that applies broadcast action frames from the
+     * given channel to this controller. Registered via {@link query.Cache.listen}.
+     */
+    listener(channel: string, schema: z.ZodType<Frame<Key, Action>>): query.Listener<z.ZodType<Frame<Key, Action>>>;
+}
+//# sourceMappingURL=controller.d.ts.map

package/dist/src/actions/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/actions/controller.ts"],"names":[],"mappings":"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"}

package/dist/src/actions/external.d.ts

@@ -1,2 +1,3 @@
 export * from './actions';
+export { Controller, type ControllerParams, type Domain, type Options, type Preprocess, type Reducer, type SendDispatch, type StackEntry, type Transaction, } from './controller';
 //# sourceMappingURL=external.d.ts.map

package/dist/src/actions/external.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../../../src/actions/external.ts"],"names":[],"mappings":"AASA,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../../../src/actions/external.ts"],"names":[],"mappings":"AASA,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,UAAU,EACV,KAAK,gBAAgB,EACrB,KAAK,MAAM,EACX,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,sBAAsB,CAAC"}