@updog/data-editor 0.1.59 → 0.1.61

package/index.d.ts

@@ -376,6 +376,7 @@ declare var export_default = {
       redo: "Redo",
     },
     validation: {
+      alreadyExists: "Already exists in your database",
       endDateBeforeStart: "End date must be after start date",
       invalidDate: "Invalid date",
       invalidEmail: "Invalid email address",
@@ -650,6 +651,38 @@ type BuiltInValidator = {
 } | {
     type: "numeric";
     message?: string;
+} | {
+    type: "unique";
+    message?: string;
+    fn?: UniqueRemoteFn;
+};
+/** One cell in an asyncFunction batch. Row is passed by reference. */
+type AsyncValidatorCell = {
+    /** Value of the validated column for this cell. */
+    value: unknown;
+    /** The full row — for row-dependent checks. */
+    row: DataEditorRow;
+};
+/**
+ * Remote existence check for `{ type: "unique" }`. Called once per sweep
+ * with all distinct candidate values; report the subset that already exists —
+ * return it and/or stream it via onChunk (results are unioned). `signal`
+ * fires only when results can no longer be used. Client-mode only.
+ */
+type UniqueRemoteFn = (values: unknown[], onChunk: (existing: unknown[]) => void, signal: AbortSignal) => Promise<unknown[] | void>;
+type AsyncFunctionValidator = {
+    type: "asyncFunction";
+    /**
+     * Called once per column per operation with every affected cell. Report
+     * failures by `index` into `cells`: return an array aligned with the input
+     * (null = valid) and/or stream sparse failures via onChunk (unioned, any
+     * order). `signal` fires only when results can no longer be used.
+     * Client-mode only. For uniqueness use `unique.fn`, not this.
+     */
+    fn: (cells: AsyncValidatorCell[], onChunk: (failures: {
+        index: number;
+        error: ValidationError;
+    }[]) => void, signal: AbortSignal) => Promise<(ValidationError | null)[] | void>;
 };
 /**
  * Server-mode-only escape hatch: an expression evaluated by the Go binary
@@ -676,7 +709,13 @@ type FunctionValidator = {
  * Named `ValidatorRule` (not `Validator`) so it doesn't clash with the
  * runtime `Validator` class in `core/Validator.ts`.
  */
-type ValidatorRule = BuiltInValidator | ExpressionValidator | FunctionValidator;
+type ValidatorRule = BuiltInValidator | ExpressionValidator | FunctionValidator | AsyncFunctionValidator;
+/**
+ * Async-check state of a cell, orthogonal to errors/misplaced: "pending"
+ * while a verdict is awaited, "unverified" when the check failed or timed
+ * out. Idle cells carry no entry.
+ */
+type CellAsyncState = "pending" | "unverified";
 
 /**
  * Severity level for a validation message.
@@ -808,7 +847,7 @@ type ColumnLockMode = "all" | "default";
  * ```ts
  * const columns: DataEditorColumn[] = [
  *   { id: "name", title: "Full Name", size: 200, validators: [{ type: "required", message: "Name is required" }] },
- *   { id: "email", title: "Email", size: 250, validators: [{ type: "required", message: "Email is required" }, { type: "email", message: "Invalid email" }], unique: true },
+ *   { id: "email", title: "Email", size: 250, validators: [{ type: "required", message: "Email is required" }, { type: "email", message: "Invalid email" }, { type: "unique" }] },
  *   { id: "role", title: "Role", editor: { type: "select", options: ["Admin", "Editor", "Viewer"] } },
  *   { id: "salary", title: "Salary", validators: [{ type: "numeric", message: "Must be a number" }], formatter: (v) => v ? `$${v}` : "" },
  * ];
@@ -821,19 +860,13 @@ type DataEditorColumn = {
     title: string;
     /**
      * One or more validators run on every edit. Accepts:
-     * - Built-in object literals: `{ type: "required" | "email" | "regex" | "range" | "oneOf" | "date" | "numeric", ... }`.
+     * - Built-in object literals: `{ type: "required" | "email" | "regex" | "range" | "oneOf" | "date" | "numeric" | "unique", ... }`.
      * - `{ type: "expression", expr }` — server-mode only. Warned in client mode.
      * - `{ type: "function", fn }` — client-mode only. Dropped+warned in server mode.
      *
      * See `_specs/VALIDATIONS.md` §4.5 for the per-mode support matrix.
      */
     validators?: ValidatorRule[];
-    /**
-     * When `true`, the editor flags duplicate values in this column as errors.
-     * The error message is localized via the `translations` prop
-     * (`dataEditor.validation.valueMustBeUnique`).
-     */
-    unique?: boolean;
     /**
      * Column IDs to revalidate when this column changes. Use for cross-field
      * rules like "end date must be after start date".
@@ -1470,6 +1503,21 @@ declare class ErrorHandler {
     handleError(error: UpdogError): void;
 }
 
+type UniqueConfig = {
+    message?: string;
+    fn?: UniqueRemoteFn;
+};
+/**
+ * Core-internal column shape produced by normalizeUniqueColumns. Uniqueness
+ * lives in `uniqueConfig` and asyncFunction rules in `asyncConfig` — the
+ * single internal sources of truth — never as entries in `validators`.
+ * Never exported from the package entry.
+ */
+type NormalizedColumn = DataEditorColumn & {
+    uniqueConfig?: UniqueConfig;
+    asyncConfig?: AsyncFunctionValidator[];
+};
+
 type FormulaCellContext = {
     value: unknown;
     field: string;
@@ -2023,6 +2071,7 @@ interface SnapshotStateReader {
     hasColumnScoping(): boolean;
     getSortState(): SortState;
     getShowOnlyDeletedRows(): boolean;
+    getPendingValidationCount(): number;
     /** Server-provided aggregate counts. Present only in server mode. */
     getServerEditedCount?(): number;
     getServerNewCount?(): number;
@@ -2095,10 +2144,15 @@ type ValidationDelta = {
     errorDelta: number;
     rowErrorChanged: boolean;
     rowMisplacedChanged: boolean;
+    pendingDelta: number;
 };
 type IValidationStore = {
     setCellValidation(rowId: TRowId, field: string, result: ValidationResult): ValidationDelta;
     getCellValidation(rowId: TRowId, field: string): ValidationResult;
+    setCellAsyncState(rowId: TRowId, field: string, state: CellAsyncState | null): ValidationDelta;
+    getCellAsyncState(rowId: TRowId, field: string): CellAsyncState | null;
+    getPendingCount(): number;
+    getRowsWithPending(): ReadonlySet<TRowId>;
     clearRowValidations(rowId: TRowId): void;
     hasRowErrors(rowId: TRowId): boolean;
     getRowsWithErrors(): ReadonlySet<TRowId>;
@@ -2114,6 +2168,40 @@ type IValidationStore = {
     clear(): void;
 };
 
+/**
+ * AsyncValidationScheduler — facade over the async annotation channel.
+ *
+ * Owns: per-cell version stamps (the ONLY staleness arbiter), pending /
+ * unverified transitions, edit debounce (SweepQueue), inactivity timeout,
+ * once-per-sweep error reporting, and throttled notify. Checks
+ * (UniqueRemoteCheck / FunctionCheck) own only the client protocol.
+ *
+ * No cancellation — last write wins. Sweeps are never aborted by other
+ * sweeps; every dispatched sweep runs to completion. Each enqueue stamps its
+ * cells with a fresh token; a sweep may touch a cell (state transitions,
+ * asyncFunction error writes) only while its recorded token is current.
+ * Unique error writes go through the live index instead (same last-state-
+ * wins property). The AbortSignal handed to the client fn fires only on
+ * sweep timeout and destroy — a courtesy, never a correctness mechanism.
+ */
+
+type AsyncCellRequest = {
+    rowId: TRowId;
+    field: string;
+    value: unknown;
+};
+type EnqueueOptions = {
+    bulk?: boolean;
+};
+/** What Validator sees — one method, never the class (ValidatorDataAccess idiom). */
+type AsyncValidationPort = {
+    enqueue(requests: AsyncCellRequest[], opts?: EnqueueOptions): void;
+};
+type IAsyncValidationScheduler = AsyncValidationPort & {
+    flush(): void;
+    destroy(): void;
+};
+
 type IValidator<TRow extends DataEditorRow = DataEditorRow> = {
     validateRow(rowId: TRowId): void;
     validateRows(rows: TRow[], rowIds: TRowId[]): void;
@@ -2123,6 +2211,7 @@ type IValidator<TRow extends DataEditorRow = DataEditorRow> = {
     validateColumn(field: string, oldValues: ReadonlyMap<TRowId, unknown>): void;
     revalidateColumnChunked(field: string, oldValues: ReadonlyMap<TRowId, unknown>, newValues: ReadonlyMap<TRowId, unknown>, processor: ChunkedProcessor<TRowId>, onComplete: () => void): void;
     removeRow(rowId: TRowId): void;
+    setAsyncPort(port: AsyncValidationPort): void;
     destroy(): void;
 };
 
@@ -2271,6 +2360,7 @@ declare class DataStore<TRow extends DataEditorRow = DataEditorRow> {
     private dirtyTracker;
     private filterEngine;
     private validationStore;
+    private asyncScheduler;
     private snapshotManager;
     private history;
     private validator;
@@ -2343,8 +2433,8 @@ declare class DataStore<TRow extends DataEditorRow = DataEditorRow> {
     private withAddedOptions;
     private rebuildEffectiveColumns;
     setSchemaColumns(columns: DataEditorColumn[]): void;
-    getDynamicColumns(): DataEditorColumn[];
-    getEffectiveColumns: () => DataEditorColumn[];
+    getDynamicColumns(): NormalizedColumn[];
+    getEffectiveColumns: () => NormalizedColumn[];
     setDynamicColumns(fn: (prev: DataEditorColumn[]) => DataEditorColumn[]): void;
     addDynamicColumns(columns: DataEditorColumn[]): void;
     addColumnOptions(columnId: string, values: string[]): void;
@@ -2511,6 +2601,9 @@ declare class DataStore<TRow extends DataEditorRow = DataEditorRow> {
     syncWorkerFlags(): void;
     setCellValidation(rowId: TRowId, field: string, result: ValidationResult): void;
     getCellValidation(rowId: TRowId, field: string): ValidationResult;
+    setAsyncScheduler(scheduler: IAsyncValidationScheduler): void;
+    setCellAsyncState(rowId: TRowId, field: string, state: CellAsyncState | null): void;
+    getCellAsyncState(rowId: TRowId, field: string): CellAsyncState | null;
     /** Strips "misplaced" from one cell, keeping any error-level entries. */
     private clearCellMisplaced;
     /**
@@ -2547,6 +2640,8 @@ declare class DataStore<TRow extends DataEditorRow = DataEditorRow> {
     getOriginalCellValue(rowId: TRowId, field: string): unknown | undefined;
     isCellDirty(rowId: TRowId, field: string): boolean;
     hasRowErrors(rowId: TRowId): boolean;
+    /** O(1) row gate for the grid's pending-stripe pass. */
+    hasRowPending(rowId: TRowId): boolean;
     hasEmptyCells(rowId: TRowId): boolean;
     hasRowMisplaced(rowId: TRowId): boolean;
     getRowsWithMisplaced(): ReadonlySet<TRowId>;
@@ -2836,6 +2931,10 @@ type DataStoreSnapshot = {
     filteredEmptyRowCount: number;
     /** Visible non-deleted rows with a cell flagged as misplaced after ragged-row realignment. */
     misplacedRowCount: number;
+    /** Cells currently awaiting an async validation verdict. */
+    pendingValidationCount: number;
+    /** True while any async check is queued or in flight — drives submit gating. */
+    isAsyncValidating: boolean;
     isLoading: boolean;
     isFiltering: boolean;
     /** Unified phase state machine. Controls what actions are allowed. */
@@ -2843,6 +2942,7 @@ type DataStoreSnapshot = {
     /** Details about the in-progress operation. Null when phase is "idle". */
     processing: ProcessingInfo | null;
     sources: DataSourceState[];
+    hasBaselineData: boolean;
     canUndo: boolean;
     canRedo: boolean;
     /** Increments on undo/redo to force canvas grid re-render */