vastgrid 0.1.0 → 0.2.0

package/dist/core/store.d.ts

@@ -0,0 +1,233 @@
+import { type Column, type GridCommand, type GridDocument, type GridSession, type JsonValue, type Measure, type RowKey } from "vastgrid-spec";
+import { type Transport } from "./client.js";
+import { type Viewport } from "./rows.js";
+import { type CommandOutcome, GridError, type GridSnapshot, type InitialView, type OpenOptions } from "./types.js";
+/** Bytes of rows that a store keeps for the view on screen, by default. */
+export declare const CACHE_BYTES: number;
+export interface GridStoreOptions {
+    /** Where the engine is. */
+    transport: Transport;
+    /** The `ref` of the table to open (§8.2). */
+    table: string;
+    /** The `read` options of `open`. */
+    open?: OpenOptions;
+    /** The document to start with (§5.1); the empty document by default. */
+    document?: GridDocument;
+    /** The session to start with (§5.2). */
+    session?: GridSession;
+    /** Rows read on a server, shown before the first read (§7 of react.md). */
+    initial?: InitialView;
+    /** Bytes of rows to keep (`CACHE_BYTES` by default). */
+    cacheBytes?: number;
+}
+export interface DispatchOptions {
+    /** What `edit.paste` pastes. */
+    clipboard?: {
+        text?: string;
+        html?: string;
+    };
+}
+type Part = "document" | "session";
+interface Events {
+    document: GridDocument;
+    session: GridSession;
+    error: GridError;
+}
+/**
+ * The grid without a screen (§4 of react.md): the state of the specification as immutable snapshots, the
+ * commands that change it, and the rows of the view on screen, read through a transport. Making a store has
+ * no side effects; `connect` opens the table and starts reading.
+ */
+export declare class GridStore {
+    private readonly options;
+    private snapshot;
+    private readonly listeners;
+    private readonly rowListeners;
+    private readonly events;
+    private readonly controlled;
+    /** What a command made of a controlled part, until the host passes it back (§5.2 of react.md). */
+    private readonly proposed;
+    private client;
+    /** Counts connections, so that answers to an earlier one are dropped. */
+    private connection;
+    /** Whether the table is open for the current connection. */
+    private opened;
+    private current;
+    private next;
+    private readonly reader;
+    /**
+     * Values of writes (§7.2) that the rows read do not hold yet, by the key text of their row and by column, with
+     * the write that gave them: the grid shows them at once, and drops them when the write fails or once the view
+     * of its edits version is on screen.
+     */
+    private readonly written;
+    private writes;
+    /** The edits version that each write that succeeded made. */
+    private readonly writeVersions;
+    /** Settles once the writes sent so far are answered and their steps are in the history. */
+    private writing;
+    private readonly totals;
+    private rowsVersion;
+    constructor(options: GridStoreOptions);
+    getSnapshot: () => GridSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    /** Follows changes of the document or the session (reported also when they are controlled), and errors. */
+    on<K extends keyof Events>(event: K, listener: (value: Events[K]) => void): () => void;
+    private emit;
+    private publish;
+    /** Reads the one row of a plan that aggregates without keys: its values and their types, by column name. */
+    private measure;
+    /**
+     * Measures (§4.5) over the rows of the document's plan, for the column statistics: an `aggregate` without keys
+     * (`measuresPlan`). Fails for a plan that groups rows.
+     */
+    aggregate(measures: Measure[], signal?: AbortSignal): Promise<{
+        values: Record<string, JsonValue>;
+        columns: Record<string, Column>;
+    }>;
+    private displayedOf;
+    /** The state that commands apply to: what was proposed for controlled parts, or what is shown. */
+    private base;
+    /** The value of a cell of the view on screen; undefined while it is not read. */
+    cell(row: number, column: string): JsonValue | undefined;
+    /** Whether the engine cut a cell's value to the text limit (§8.4). */
+    isCut(row: number, column: string): boolean;
+    /** The key of a row of the view on screen (§5.3); undefined while it is not read. */
+    rowKey(row: number): RowKey | undefined;
+    /** The row ID of a row of the view on screen. */
+    rowId(row: number): number | undefined;
+    /** Changes whenever rows of the view on screen arrive or leave. */
+    getRowsVersion: () => number;
+    /** Follows the arrival of rows (the snapshot does not change when rows arrive). */
+    subscribeRows: (listener: () => void) => (() => void);
+    private emitRows;
+    /** Tells the store what the canvas shows, so that it reads those rows and a page around them. */
+    setViewport(viewport: Viewport): void;
+    /** Reads rows `[start, end)` of `columns` of the view on screen if they are not read, for cells React renders. */
+    ensure(start: number, end: number, columns: readonly string[]): void;
+    /**
+     * Opens the table, follows its events and reads the view of the document's plan. Gives the function that
+     * undoes all of it; connecting again afterwards works (Strict Mode does it, §4.3 of react.md).
+     */
+    connect(): () => void;
+    /** The table is open: repairs the document for it and reads the view (§5.5). */
+    private opening;
+    private onEvent;
+    private fail;
+    /** A read failed: unless it was cancelled, the failure belongs to no command (§4.2 of react.md). */
+    private readFailed;
+    /** Shows rows read on a server before the table is open. */
+    private seed;
+    /**
+     * Reads the view of a plan while the view on screen stays, and shows it when its first rows arrive, with the
+     * session moved by `view.update` (§5.4; §4.2 of react.md).
+     */
+    private showPlan;
+    private live;
+    private prepare;
+    private contextFor;
+    /** A row as commands read it, with the values of writes that its rows do not hold yet. */
+    private withWritten;
+    /** Shows the values of a write until it is answered (§7.2). */
+    private markWritten;
+    /** Forgets the values of writes: one that failed, or those that the rows on screen now hold. */
+    private dropWritten;
+    /** Makes a part controlled: commands report what they make of it, and only `setDocument`/`setSession` show it. */
+    control(part: Part, controlled: boolean): void;
+    /** Shows a document given by the host (a controlled prop, a saved view, an agent). */
+    setDocument(document: GridDocument): void;
+    /** Shows a session given by the host. */
+    setSession(session: GridSession): void;
+    /**
+     * Applies a new state from a command: shows what is not controlled, with `extra` members of the snapshot in the
+     * same step, and reports both parts that changed.
+     */
+    private change;
+    /** Applies a command now, or tells why it cannot be applied (rows to read first included). */
+    private applyNow;
+    /**
+     * Applies a command (§4.2 of react.md). The state changes at once when the command has what it needs;
+     * a command that needs rows that are not read reads them first. Resolves once the command's requests are
+     * answered, and never rejects. The same function for the life of the store.
+     */
+    readonly dispatch: (command: GridCommand, options?: DispatchOptions) => Promise<CommandOutcome>;
+    /**
+     * Applies a command synchronously, as a `copy` event needs (its clipboard is written before the handler
+     * returns). A command that needs rows that are not read fails with `not_loaded`; its requests are sent.
+     */
+    dispatchSync(command: GridCommand, options?: DispatchOptions): CommandOutcome;
+    /**
+     * Sends the failed write again (§6.6 of react.md): the same updates, or after an `edit_conflict` without their
+     * `previous`, so that they write over what the cells hold now. It succeeds as its command would have: the history
+     * gets its step, or an undo or a redo whose step is still the last moves it. Resolves as `dispatch` does.
+     */
+    readonly retryWrite: () => Promise<CommandOutcome>;
+    /** Forgets the failed write: its cells show what the engine holds. */
+    discardWrite(): void;
+    /** Keeps a write that failed, for `retryWrite` and `discardWrite`. */
+    private failWrite;
+    /** Whether a failed undo or redo has its step still last in its list, where its write then moves it from. */
+    private stillLast;
+    /** Where the file of an `export` without a target can be downloaded (`Transport.exportUrl`), or null. */
+    exportUrl(target: string): string | null;
+    /** A name for the file of an export that an engine answers as data: the table's name with the format's extension. */
+    exportName(format: string): string;
+    /**
+     * Reads the table's file as it is now (`reload`, §7.6), without the cells written into the table as it was read:
+     * for a file that changed on disk while the table had written cells (`fileChanged` of the table).
+     */
+    reload(): Promise<void>;
+    /** Another revision of the table (§5.4): the document is repaired for its columns (§5.5), and the view read. */
+    private adopt;
+    /** Counts and sums the cells of ranges of the view on screen (`summarize`, §8.2). */
+    summarize(ranges: [number, number][], columns: string[], signal?: AbortSignal): Promise<{
+        count: number;
+        numericCount: number;
+        sum: unknown;
+        min: unknown;
+        max: unknown;
+        average: unknown;
+    }>;
+    /**
+     * The values of a column with how many rows have each, the most common first, for the column menu's list: the
+     * rows of the document's plan without the column's own conditions, and those whose text contains `search`
+     * (`valuesPlan`). At most `limit` of them; `truncated` when there are more.
+     */
+    values(column: string, { search, limit }?: {
+        search?: string;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<{
+        values: {
+            value: JsonValue;
+            count: number;
+        }[];
+        truncated: boolean;
+    }>;
+    /**
+     * Finds the next cell of the view on screen after `from` (before it with `direction` −1) whose text contains
+     * `text` (`find`, §8.2), among the displayed columns in display order, wrapping around; null when none does.
+     */
+    find(text: string, { from, direction, caseSensitive, }: {
+        from: {
+            row: number;
+            column: string;
+        };
+        direction?: 1 | -1;
+        caseSensitive?: boolean;
+    }, signal?: AbortSignal): Promise<{
+        row: number;
+        column: string;
+    } | null>;
+    /** The whole value of a cell of the view on screen, also when the engine cut its text (§8.4), and its type. */
+    fullValue(row: number, column: string, signal?: AbortSignal): Promise<{
+        value: JsonValue;
+        column: Column;
+    }>;
+    /** Sends the requests of a command and applies the commands of §6.7 that their answers call for. */
+    private send;
+    private sendNow;
+}
+/** Makes a store (§4 of react.md). */
+export declare function createGridStore(options: GridStoreOptions): GridStore;
+export {};
+//# sourceMappingURL=store.d.ts.map

package/dist/core/store.d.ts.map

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