@syidax/advanced 0.0.0-stage → 1.0.1

package/dist/types/components/grid/core/row-model/server-pivot-results.d.ts

@@ -0,0 +1,234 @@
+import { type ServerSidePivotResultColumn } from './server-side.ts';
+import type { GridRefInvalidationReason } from '../api/contracts';
+export type ServerPivotResultSource = 'columns' | 'fields' | 'none';
+export declare const SERVER_PIVOT_RESULT_SOURCES: readonly ServerPivotResultSource[];
+export type ServerPivotResultColumnKind = 'value' | 'group';
+export declare const SERVER_PIVOT_DERIVED_GROUP_PREFIX = "__spivot_g__";
+export interface ServerPivotResultColumn {
+    readonly colId: string;
+    readonly kind: ServerPivotResultColumnKind;
+    readonly headerName: string;
+    readonly field: string;
+    readonly groupPath: readonly string[];
+    readonly identityKey: string;
+    readonly hasParentGroup: boolean;
+    readonly parentGroupId: string;
+    readonly depth: number;
+    readonly leafIndex: number;
+    readonly meta: Readonly<Record<string, unknown>>;
+}
+export interface ServerPivotFieldsCoverage {
+    readonly checked: boolean;
+    readonly matchedCount: number;
+    readonly fieldsWithoutColumn: readonly string[];
+    readonly leavesWithoutField: readonly string[];
+}
+export interface ServerPivotResultColumnModel {
+    readonly source: ServerPivotResultSource;
+    readonly columns: readonly ServerPivotResultColumn[];
+    readonly leaves: readonly ServerPivotResultColumn[];
+    readonly groups: readonly ServerPivotResultColumn[];
+    readonly byColId: ReadonlyMap<string, ServerPivotResultColumn>;
+    readonly fieldsCoverage: ServerPivotFieldsCoverage;
+}
+export interface ServerPivotResultMetadata {
+    readonly pivotResultFields?: readonly string[];
+    readonly pivotResultColumns?: readonly ServerSidePivotResultColumn[];
+}
+export interface ServerPivotResultOptions {
+    readonly fieldSeparator?: string;
+}
+export type ServerPivotResultsIndex = {
+    readonly status: 'indexed';
+    readonly model: ServerPivotResultColumnModel;
+} | {
+    readonly status: 'refused-duplicate-ids';
+    readonly duplicateIds: readonly string[];
+    readonly detail: string;
+} | {
+    readonly status: 'refused-invalid-separator';
+    readonly detail: string;
+} | {
+    readonly status: 'refused-no-metadata';
+    readonly detail: string;
+};
+export declare const EMPTY_SERVER_PIVOT_MODEL: ServerPivotResultColumnModel;
+export declare function indexServerPivotResults(metadata: ServerPivotResultMetadata, options?: ServerPivotResultOptions): ServerPivotResultsIndex;
+export type ServerPivotResultsStatus = 'empty' | 'live' | 'stale';
+export type ServerPivotStaleCause = 'root-refresh' | 'datasource-replaced' | 'manual';
+export declare const SERVER_PIVOT_STALE_CAUSES: readonly ServerPivotStaleCause[];
+export type ServerPivotClearCause = 'pivot-disabled' | 'retopologise' | 'destroyed';
+export declare const SERVER_PIVOT_CLEAR_CAUSES: readonly ServerPivotClearCause[];
+export declare const SERVER_PIVOT_RESULT_POLICY: Readonly<{
+    readonly publishing: "root-store-only";
+    readonly refresh: "stale-but-answering";
+    readonly omittedMetadata: "retained";
+    readonly topologyChange: "cleared-new-era";
+    readonly identity: "survives-refresh";
+}>;
+export interface ServerPivotColumnEpoch {
+    readonly epoch: number;
+    readonly identityKey: string;
+}
+export interface ServerPivotResultsState {
+    readonly modelId: string;
+    readonly era: number;
+    readonly publishSeq: number;
+    readonly status: ServerPivotResultsStatus;
+    readonly staleCause: string;
+    readonly model: ServerPivotResultColumnModel;
+    readonly epochs: ReadonlyMap<string, ServerPivotColumnEpoch>;
+}
+export declare function createServerPivotResultsState(config: {
+    modelId: string;
+}): ServerPivotResultsState;
+export interface ServerPivotColumnMove {
+    readonly colId: string;
+    readonly from: number;
+    readonly to: number;
+}
+export type ServerPivotTransitionKind = 'initial' | 'unchanged' | 'relabelled' | 'reordered' | 'schema-changed';
+export declare const SERVER_PIVOT_TRANSITION_KINDS: readonly ServerPivotTransitionKind[];
+export interface ServerPivotSchemaTransition {
+    readonly kind: ServerPivotTransitionKind;
+    readonly publishSeq: number;
+    readonly schemaChanged: boolean;
+    readonly retained: readonly string[];
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+    readonly identityChanged: readonly string[];
+    readonly relabelled: readonly string[];
+    readonly moved: readonly ServerPivotColumnMove[];
+}
+export type ServerPivotPublishResult = {
+    readonly status: 'published';
+    readonly state: ServerPivotResultsState;
+    readonly transition: ServerPivotSchemaTransition;
+} | {
+    readonly status: 'refused-duplicate-ids';
+    readonly state: ServerPivotResultsState;
+    readonly duplicateIds: readonly string[];
+    readonly detail: string;
+} | {
+    readonly status: 'refused-invalid-separator';
+    readonly state: ServerPivotResultsState;
+    readonly detail: string;
+} | {
+    readonly status: 'refused-no-metadata';
+    readonly state: ServerPivotResultsState;
+    readonly detail: string;
+};
+export declare function publishServerPivotResults(state: ServerPivotResultsState, metadata: ServerPivotResultMetadata, options?: ServerPivotResultOptions): ServerPivotPublishResult;
+export declare function publishServerPivotResultsFromStore(state: ServerPivotResultsState, ssrm: {
+    readonly pivotResultFields: readonly string[];
+    readonly pivotResultColumns: readonly ServerSidePivotResultColumn[];
+}, options?: ServerPivotResultOptions): ServerPivotPublishResult;
+export declare function markServerPivotResultsStale(state: ServerPivotResultsState, cause: ServerPivotStaleCause): ServerPivotResultsState;
+export interface ServerPivotClearApplication {
+    readonly state: ServerPivotResultsState;
+    readonly invalidatedColIds: readonly string[];
+    readonly cause: ServerPivotClearCause;
+}
+export declare function clearServerPivotResults(state: ServerPivotResultsState, cause: ServerPivotClearCause): ServerPivotClearApplication;
+export interface ServerPivotColumnRef {
+    readonly modelId: string;
+    readonly era: number;
+    readonly colId: string;
+    readonly identityKey: string;
+    readonly epoch: number;
+}
+export type ServerPivotColumnRefMint = {
+    readonly status: 'ok';
+    readonly ref: ServerPivotColumnRef;
+} | {
+    readonly status: 'not-published';
+    readonly detail: string;
+} | {
+    readonly status: 'unknown-column';
+    readonly colId: string;
+    readonly detail: string;
+};
+export declare function serverPivotColumnRef(state: ServerPivotResultsState, colId: string): ServerPivotColumnRefMint;
+export type ServerPivotColumnDeadReason = 'foreign-model' | 'definitions-replaced' | 'removed' | 'recreated' | 'identity-changed';
+export declare const SERVER_PIVOT_DEAD_REASONS: readonly ServerPivotColumnDeadReason[];
+export type ServerPivotColumnResolution = {
+    readonly status: 'live';
+    readonly column: ServerPivotResultColumn;
+    readonly stale: boolean;
+} | {
+    readonly status: 'dead';
+    readonly reason: ServerPivotColumnDeadReason;
+    readonly colId: string;
+};
+export declare function resolveServerPivotColumnRef(state: ServerPivotResultsState, ref: ServerPivotColumnRef): ServerPivotColumnResolution;
+export declare function serverPivotGridInvalidationReason(reason: ServerPivotColumnDeadReason): GridRefInvalidationReason;
+export interface ServerPivotColumnUiEntry {
+    readonly colId: string;
+    readonly width?: number;
+    readonly pinned?: 'left' | 'right' | 'none';
+    readonly hidden?: boolean;
+}
+export interface ServerPivotColumnWidth {
+    readonly declared: boolean;
+    readonly px: number;
+}
+export interface ServerPivotColumnStateEntry {
+    readonly colId: string;
+    readonly identityKey: string;
+    readonly width: ServerPivotColumnWidth;
+    readonly pinned: 'left' | 'right' | 'none';
+    readonly hidden: boolean;
+}
+export interface ServerPivotColumnStateSnapshot {
+    readonly version: 1;
+    readonly modelId: string;
+    readonly era: number;
+    readonly publishSeq: number;
+    readonly entries: readonly ServerPivotColumnStateEntry[];
+}
+export type ServerPivotColumnStateCapture = {
+    readonly status: 'captured';
+    readonly snapshot: ServerPivotColumnStateSnapshot;
+    readonly unknownColIds: readonly string[];
+} | {
+    readonly status: 'not-published';
+    readonly detail: string;
+};
+export declare function captureServerPivotColumnState(state: ServerPivotResultsState, entries: readonly ServerPivotColumnUiEntry[]): ServerPivotColumnStateCapture;
+export type ServerPivotStateRestoreIssue = 'unknown-column' | 'identity-changed' | 'duplicate-entry';
+export declare const SERVER_PIVOT_STATE_RESTORE_ISSUES: readonly ServerPivotStateRestoreIssue[];
+export interface ServerPivotRestoredColumn {
+    readonly column: ServerPivotResultColumn;
+    readonly width: ServerPivotColumnWidth;
+    readonly pinned: 'left' | 'right' | 'none';
+    readonly hidden: boolean;
+}
+export type ServerPivotColumnStateRestore = {
+    readonly status: 'restored';
+    readonly applied: readonly ServerPivotRestoredColumn[];
+    readonly issues: readonly {
+        readonly colId: string;
+        readonly issue: ServerPivotStateRestoreIssue;
+    }[];
+    readonly restoredCount: number;
+    readonly untouchedColIds: readonly string[];
+} | {
+    readonly status: 'not-published';
+    readonly detail: string;
+} | {
+    readonly status: 'foreign-model';
+    readonly detail: string;
+};
+export declare function restoreServerPivotColumnState(state: ServerPivotResultsState, snapshot: ServerPivotColumnStateSnapshot): ServerPivotColumnStateRestore;
+export type ServerPivotUsageDisposition = 'live' | 'live-stale' | 'unknown-column';
+export interface ServerPivotUsageAudit {
+    readonly results: readonly {
+        readonly colId: string;
+        readonly disposition: ServerPivotUsageDisposition;
+    }[];
+    readonly liveCount: number;
+    readonly staleCount: number;
+    readonly unknownCount: number;
+    readonly clean: boolean;
+}
+export declare function auditServerPivotColumnUsage(state: ServerPivotResultsState, colIds: readonly string[]): ServerPivotUsageAudit;

package/dist/types/components/grid/core/row-model/server-refresh.d.ts

@@ -0,0 +1,63 @@
+import { type ServerStoreRegistry, type ServerStoreRoute } from './server-store-routes.ts';
+import type { ServerSideState } from './server-side.ts';
+export type ServerRefreshMode = 'soft' | 'purge';
+export interface ServerRefreshInput {
+    readonly route: readonly string[];
+    readonly mode?: ServerRefreshMode;
+}
+export type ServerRefreshPlanStatus = 'planned' | 'invalid-route' | 'store-not-open';
+export declare const SERVER_REFRESH_POLICY: Readonly<{
+    readonly selection: "untouched-by-refresh";
+    readonly expansion: "preserved-reexpand-on-load";
+}>;
+export interface ServerRefreshPlan {
+    readonly status: ServerRefreshPlanStatus;
+    readonly mode: ServerRefreshMode;
+    readonly route: ServerStoreRoute;
+    readonly storeId: string;
+    readonly reloadStoreIds: readonly string[];
+    readonly closeStoreIds: readonly string[];
+    readonly recreateStoreIds: readonly string[];
+    readonly abortStoreIds: readonly string[];
+    readonly untouchedStoreIds: readonly string[];
+    readonly policy: typeof SERVER_REFRESH_POLICY;
+    readonly issue: string;
+}
+export interface ServerRefreshApiResult {
+    readonly status: 'accepted' | 'invalid-route' | 'store-not-open';
+    readonly storeId: string;
+    readonly mode: ServerRefreshMode;
+    readonly reloadedStoreIds: readonly string[];
+    readonly closedStoreIds: readonly string[];
+    readonly recreatedStoreIds: readonly string[];
+    readonly abortedStoreIds: readonly string[];
+    readonly issue: string;
+}
+export declare function planServerSideRefresh(registry: ServerStoreRegistry, input: ServerRefreshInput, expandedPaths?: ReadonlySet<string>): ServerRefreshPlan;
+export interface ServerRefreshApplication<TRow> {
+    readonly registry: ServerStoreRegistry;
+    readonly ssrm: ServerSideState<TRow>;
+    readonly result: ServerRefreshApiResult;
+}
+export declare function applyServerSideRefresh<TRow>(registry: ServerStoreRegistry, ssrm: ServerSideState<TRow>, plan: ServerRefreshPlan): ServerRefreshApplication<TRow>;
+export type ServerRefreshCoalesceDisposition = {
+    readonly status: 'planned';
+    readonly planIndex: number;
+} | {
+    readonly status: 'absorbed';
+    readonly byInputIndex: number;
+} | {
+    readonly status: 'merged';
+    readonly intoInputIndex: number;
+} | {
+    readonly status: 'invalid-route';
+    readonly issue: string;
+} | {
+    readonly status: 'store-not-open';
+    readonly issue: string;
+};
+export interface ServerRefreshCoalesceResult {
+    readonly plans: readonly ServerRefreshPlan[];
+    readonly dispositions: readonly ServerRefreshCoalesceDisposition[];
+}
+export declare function coalesceServerSideRefreshes(registry: ServerStoreRegistry, inputs: readonly ServerRefreshInput[], expandedPaths?: ReadonlySet<string>): ServerRefreshCoalesceResult;

package/dist/types/components/grid/core/row-model/server-selection.d.ts

@@ -0,0 +1,76 @@
+import { type ServerStoreRegistry } from './server-store-routes.ts';
+import type { ServerSideState } from './server-side.ts';
+export declare const SERVER_SELECTION_POLICY: Readonly<{
+    readonly refresh: "untouched-by-refresh";
+    readonly filterChange: "kept-reconcile-owed";
+    readonly routeScope: "grid-wide-flat";
+    readonly staleToggles: "kept-until-proven-absent";
+}>;
+export interface ServerSelectionState {
+    readonly selectAll: boolean;
+    readonly toggled: ReadonlySet<string>;
+}
+export declare function createServerSelectionState(): ServerSelectionState;
+export declare function applyServerSelectAll(action: 'select' | 'clear'): ServerSelectionState;
+export declare function isServerRowSelected(state: ServerSelectionState, rowId: string): boolean;
+export interface ServerSelectionToggleResult {
+    readonly state: ServerSelectionState;
+    readonly changed: boolean;
+}
+export declare function toggleServerRowSelected(state: ServerSelectionState, rowId: string, selected: boolean): ServerSelectionToggleResult;
+export interface ServerSelectionSnapshot {
+    readonly selectAll: boolean;
+    readonly toggledRowIds: readonly string[];
+}
+export declare function getServerSelectionState(state: ServerSelectionState): ServerSelectionSnapshot;
+export type ServerSelectionSetRefusal = 'not-an-object' | 'select-all-not-boolean' | 'toggled-not-an-array';
+export type ServerSelectionSetResult = {
+    readonly status: 'applied';
+    readonly state: ServerSelectionState;
+    readonly droppedDuplicateIds: readonly string[];
+    readonly droppedInvalidCount: number;
+} | {
+    readonly status: 'refused';
+    readonly reason: ServerSelectionSetRefusal;
+    readonly detail: string;
+};
+export declare function setServerSelectionState(input: unknown): ServerSelectionSetResult;
+export interface ServerSelectionCount {
+    readonly known: boolean;
+    readonly selectedCount: number;
+    readonly toggledCount: number;
+}
+export declare function serverSelectionCount(state: ServerSelectionState, total: {
+    readonly known: boolean;
+    readonly rowCount: number;
+}): ServerSelectionCount;
+export interface ServerSelectionAttribution {
+    readonly presentRowIds: ReadonlySet<string>;
+    readonly complete: boolean;
+    readonly incompleteStoreIds: readonly string[];
+    readonly unopenedChildPaths: readonly string[];
+    readonly treeData: boolean;
+}
+export interface ServerSelectionAttributionConfig<TRow> {
+    readonly getRowId: (row: TRow) => string;
+    readonly getGroupKey: (row: TRow, level: number) => string;
+}
+export declare function serverSelectionAttribution<TRow>(registry: ServerStoreRegistry, ssrm: ServerSideState<TRow>, config: ServerSelectionAttributionConfig<TRow>): ServerSelectionAttribution;
+export interface ServerSelectionReconcilePlan {
+    readonly keptPresentIds: readonly string[];
+    readonly keptUnprovenIds: readonly string[];
+    readonly dropProvenAbsentIds: readonly string[];
+}
+export declare function planServerSelectionReconcile(state: ServerSelectionState, attribution: ServerSelectionAttribution): ServerSelectionReconcilePlan;
+export declare function applyServerSelectionReconcile(state: ServerSelectionState, plan: ServerSelectionReconcilePlan): ServerSelectionState;
+export declare function reconcileServerSelectionAfterTransaction<TRow>(state: ServerSelectionState, removedRows: readonly TRow[], getRowId: (row: TRow) => string): {
+    readonly state: ServerSelectionState;
+    readonly droppedToggledIds: readonly string[];
+};
+export interface ServerSelectionReport {
+    readonly selectAll: boolean;
+    readonly toggledCount: number;
+    readonly policy: typeof SERVER_SELECTION_POLICY;
+}
+export declare function serverSelectionReport(state: ServerSelectionState): ServerSelectionReport;
+export declare function serverSelectionHoldsRowData(value: unknown, depth?: number): boolean;

package/dist/types/components/grid/core/row-model/server-side-retry.d.ts

@@ -0,0 +1,37 @@
+import type { ServerSideDatasource, ServerSideGetRowsParams, ServerSideGetRowsResult } from './server-side.ts';
+export interface RetryScheduler {
+    setTimeout(cb: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface ServerSideRetryConfig {
+    maxRetries?: number;
+    timeoutMs?: number;
+    retryDelayMs?: number;
+    backoff?: 'fixed' | 'exponential';
+    scheduler?: RetryScheduler;
+}
+export declare function retryDelay(attempt: number, baseMs: number, backoff: 'fixed' | 'exponential'): number;
+export type ServerSideRetryFailureKind = 'failed' | 'timeout' | 'aborted';
+export interface ServerSideRetryFailure {
+    readonly kind: ServerSideRetryFailureKind;
+    readonly attempts: number;
+    readonly abortReason?: string;
+}
+export interface ServerSideRetryDiscard {
+    readonly kind: 'success' | 'failure';
+    readonly attempt: number;
+    readonly reason: 'attempt-superseded' | 'request-settled';
+}
+export interface RetriedGetRowsCallbacks<TRow> {
+    onSuccess: (result: ServerSideGetRowsResult<TRow>, meta: {
+        attempts: number;
+    }) => void;
+    onFail: (failure: ServerSideRetryFailure) => void;
+    onDiscarded?: (discard: ServerSideRetryDiscard) => void;
+}
+export interface RetriedRequestHandle {
+    abort(reason?: string): boolean;
+    settled(): boolean;
+}
+export declare function runRetriedGetRows<TRow>(inner: ServerSideDatasource<TRow>, params: ServerSideGetRowsParams, callbacks: RetriedGetRowsCallbacks<TRow>, config?: ServerSideRetryConfig): RetriedRequestHandle;
+export declare function withServerSideRetry<TRow>(inner: ServerSideDatasource<TRow>, config?: ServerSideRetryConfig): ServerSideDatasource<TRow>;

package/dist/types/components/grid/core/row-model/server-side.d.ts

@@ -0,0 +1,109 @@
+import { type InfiniteCacheState } from './block-cache.ts';
+export declare function serialiseGroupPath(groupKeys: readonly string[]): string;
+export interface ServerSideColumn {
+    readonly id?: string;
+    readonly colId?: string;
+    readonly field?: string;
+    readonly displayName?: string;
+    readonly aggFunc?: string;
+    readonly [key: string]: unknown;
+}
+export type ServerSideColumnRef = string | ServerSideColumn;
+export interface ServerSidePivotResultColumn {
+    readonly colId?: string;
+    readonly field?: string;
+    readonly headerName?: string;
+    readonly children?: readonly ServerSidePivotResultColumn[];
+    readonly [key: string]: unknown;
+}
+export interface ServerSideGetRowsParams {
+    groupKeys: readonly string[];
+    pivotMode?: boolean;
+    rowGroupCols: readonly ServerSideColumnRef[];
+    pivotCols?: readonly ServerSideColumnRef[];
+    startRow: number;
+    endRow: number;
+    sortModel?: ReadonlyArray<{
+        colId: string;
+        sort: 'asc' | 'desc';
+    }>;
+    filterModel?: Readonly<Record<string, unknown>>;
+    quickFilter?: string;
+    conditionModel?: unknown;
+    valueCols?: readonly ServerSideColumnRef[];
+}
+export interface NormalizedServerSideGetRowsParams {
+    readonly groupKeys: readonly string[];
+    readonly pivotMode: boolean;
+    readonly rowGroupCols: readonly ServerSideColumnRef[];
+    readonly pivotCols: readonly ServerSideColumnRef[];
+    readonly valueCols: readonly ServerSideColumnRef[];
+    readonly startRow: number;
+    readonly endRow: number;
+    readonly sortModel?: ReadonlyArray<{
+        readonly colId: string;
+        readonly sort: 'asc' | 'desc';
+    }>;
+    readonly filterModel?: Readonly<Record<string, unknown>>;
+    readonly quickFilter?: string;
+    readonly conditionModel?: unknown;
+}
+export declare function normalizeServerSideGetRowsParams(params: ServerSideGetRowsParams): NormalizedServerSideGetRowsParams;
+export interface ServerSideGetRowsResult<TRow> {
+    rows: TRow[];
+    rowCount?: number;
+    pivotResultFields?: readonly string[];
+    pivotResultColumns?: readonly ServerSidePivotResultColumn[];
+}
+export declare function normalizeServerSideGetRowsResult<TRow>(json: unknown): ServerSideGetRowsResult<TRow>;
+export interface ServerSideDatasource<TRow> {
+    getRows(params: ServerSideGetRowsParams, onSuccess: (result: ServerSideGetRowsResult<TRow>) => void, onFail: () => void): void;
+}
+export interface ServerSideState<TRow> {
+    readonly pivotMode: boolean;
+    readonly rowGroupCols: readonly ServerSideColumnRef[];
+    readonly pivotCols: readonly ServerSideColumnRef[];
+    readonly valueCols: readonly ServerSideColumnRef[];
+    readonly pivotResultFields: readonly string[];
+    readonly pivotResultColumns: readonly ServerSidePivotResultColumn[];
+    readonly blockSize: number;
+    readonly maxBlocks: number | null;
+    readonly nodes: Readonly<Record<string, InfiniteCacheState<TRow>>>;
+    readonly expanded: ReadonlySet<string>;
+}
+export interface ServerSideDisplayRow<TRow> {
+    kind: 'group' | 'leaf' | 'loading';
+    data: TRow | null;
+    groupKeys: string[];
+    level: number;
+    expanded: boolean;
+    status?: 'loading' | 'failed' | 'missing';
+    parentPath: string;
+    childIndex: number;
+}
+export interface ServerSideBlockRequest {
+    groupKeys: string[];
+    path: string;
+    blockNumber: number;
+    startRow: number;
+    endRow: number;
+}
+export declare function createServerSideState<TRow>(config: {
+    pivotMode?: boolean;
+    rowGroupCols?: readonly ServerSideColumnRef[];
+    pivotCols?: readonly ServerSideColumnRef[];
+    valueCols?: readonly ServerSideColumnRef[];
+    blockSize?: number;
+    maxBlocks?: number | null;
+}): ServerSideState<TRow>;
+export declare function isGroupLevel<TRow>(state: ServerSideState<TRow>, groupKeys: readonly string[]): boolean;
+export declare function nodeAt<TRow>(state: ServerSideState<TRow>, path: string): InfiniteCacheState<TRow> | null;
+export declare function toggleGroupExpanded<TRow>(state: ServerSideState<TRow>, groupKeys: readonly string[]): ServerSideState<TRow>;
+export declare function markServerBlockLoading<TRow>(state: ServerSideState<TRow>, path: string, blockNumber: number): ServerSideState<TRow>;
+export declare function applyServerBlockSuccess<TRow>(state: ServerSideState<TRow>, path: string, blockNumber: number, result: ServerSideGetRowsResult<TRow>): ServerSideState<TRow>;
+export declare function applyServerBlockSuccess<TRow>(state: ServerSideState<TRow>, path: string, blockNumber: number, rows: readonly TRow[], rowCount?: number, pivotResultFields?: readonly string[], pivotResultColumns?: readonly ServerSidePivotResultColumn[]): ServerSideState<TRow>;
+export declare function applyServerBlockFailure<TRow>(state: ServerSideState<TRow>, path: string, blockNumber: number): ServerSideState<TRow>;
+export declare function flattenServerSide<TRow>(state: ServerSideState<TRow>, getGroupKey: (row: TRow, level: number) => string, maxRows?: number): ServerSideDisplayRow<TRow>[];
+export declare function serverBlocksToLoad<TRow>(state: ServerSideState<TRow>, displayRows: ReadonlyArray<ServerSideDisplayRow<TRow>>, startDisplay: number, endDisplay: number, includeFailed?: boolean): ServerSideBlockRequest[];
+export declare function touchServerSideVisible<TRow>(state: ServerSideState<TRow>, displayRows: ReadonlyArray<ServerSideDisplayRow<TRow>>, startDisplay: number, endDisplay: number): ServerSideState<TRow>;
+export declare function purgeServerSide<TRow>(state: ServerSideState<TRow>): ServerSideState<TRow>;

package/dist/types/components/grid/core/row-model/server-store-events.d.ts

@@ -0,0 +1,160 @@
+import type { GridMutationId } from '../api/contracts.ts';
+import type { ServerRefreshApiResult, ServerRefreshMode } from './server-refresh.ts';
+import type { ServerDatasourceIssue, ServerDatasourceSettlement } from './server-datasource-lifecycle.ts';
+import type { ServerStoreRecord, ServerStoreRegistry, ServerStoreStatus } from './server-store-routes.ts';
+export type ServerRefreshOutcome = 'completed' | 'failed' | 'superseded' | 'store-closed' | 'destroyed';
+export declare const SERVER_REFRESH_OUTCOMES: readonly ServerRefreshOutcome[];
+export type ServerStoreUpdateKind = 'fetch-started' | 'block-loaded' | 'block-failed' | 'fetch-aborted' | 'stale-load-discarded' | 'rows-changed';
+export declare const SERVER_STORE_UPDATE_KINDS: readonly ServerStoreUpdateKind[];
+export interface ServerRefreshStartedDetail {
+    readonly mutationId: GridMutationId;
+    readonly storeId: string;
+    readonly storeSeq: number;
+    readonly mode: ServerRefreshMode;
+    readonly generation: number;
+    readonly previousStatus: ServerStoreStatus;
+    readonly status: ServerStoreStatus;
+}
+export interface ServerStoreUpdatedDetail {
+    readonly mutationId: GridMutationId;
+    readonly storeId: string;
+    readonly storeSeq: number;
+    readonly update: ServerStoreUpdateKind;
+    readonly generation: number;
+    readonly previousStatus: ServerStoreStatus;
+    readonly status: ServerStoreStatus;
+    readonly requestId?: number;
+    readonly blockNumber?: number;
+    readonly rowsLoaded?: number;
+    readonly rowsChanged?: {
+        readonly added: number;
+        readonly updated: number;
+        readonly removed: number;
+    };
+}
+export interface ServerRefreshFinishedDetail {
+    readonly mutationId: GridMutationId;
+    readonly storeId: string;
+    readonly storeSeq: number;
+    readonly mode: ServerRefreshMode;
+    readonly generation: number;
+    readonly outcome: ServerRefreshOutcome;
+    readonly status: ServerStoreStatus;
+}
+export type ServerStoreEvent = {
+    readonly type: 'refreshStarted';
+    readonly detail: ServerRefreshStartedDetail;
+} | {
+    readonly type: 'storeUpdated';
+    readonly detail: ServerStoreUpdatedDetail;
+} | {
+    readonly type: 'refreshFinished';
+    readonly detail: ServerRefreshFinishedDetail;
+};
+export type ServerStoreEventRecordResult = {
+    readonly status: 'tracked';
+} | {
+    readonly status: 'already-tracked';
+} | {
+    readonly status: 'retracked';
+    readonly previousStoreSeq: number;
+} | {
+    readonly status: 'bracketed';
+    readonly mutationId: GridMutationId;
+    readonly supersededMutationId: string;
+    readonly closedStoreIds: readonly string[];
+} | {
+    readonly status: 'fetch-tracked';
+    readonly mutationId: GridMutationId;
+    readonly viaRefresh: boolean;
+} | {
+    readonly status: 'deduped';
+} | {
+    readonly status: 'settled';
+    readonly update: ServerStoreUpdateKind;
+    readonly finishedRefresh: boolean;
+} | {
+    readonly status: 'rows-recorded';
+    readonly mutationId: GridMutationId;
+} | {
+    readonly status: 'closed';
+    readonly finishedRefreshes: number;
+    readonly abortedLoads: number;
+} | {
+    readonly status: 'not-accepted';
+} | {
+    readonly status: 'unknown-store';
+    readonly storeId: string;
+} | {
+    readonly status: 'stale-store-seq';
+    readonly storeId: string;
+} | {
+    readonly status: 'stale-issue';
+    readonly storeId: string;
+} | {
+    readonly status: 'refused-issue';
+} | {
+    readonly status: 'unmatched';
+    readonly requestId: number;
+} | {
+    readonly status: 'refused-destroyed';
+};
+export interface ServerStoreEventCounters {
+    readonly eventsEmitted: number;
+    readonly refreshesStarted: number;
+    readonly refreshesFinished: number;
+    readonly finishedCompleted: number;
+    readonly finishedFailed: number;
+    readonly finishedSuperseded: number;
+    readonly finishedStoreClosed: number;
+    readonly finishedDestroyed: number;
+    readonly fetchesStarted: number;
+    readonly blocksLoaded: number;
+    readonly blocksFailed: number;
+    readonly fetchesAborted: number;
+    readonly staleLoadsDiscarded: number;
+    readonly rowsChangedEvents: number;
+    readonly unmatchedSettlements: number;
+    readonly staleIssues: number;
+    readonly notAcceptedRefreshes: number;
+    readonly unknownStoreInputs: number;
+    readonly untrackedIssues: number;
+    readonly refusedAfterDestroy: number;
+}
+export interface ServerStoreEventView {
+    readonly storeId: string;
+    readonly storeSeq: number;
+    readonly generation: number;
+    readonly status: ServerStoreStatus;
+    readonly hasOpenRefresh: boolean;
+    readonly openRefreshMutationId: string;
+    readonly pendingLoadCount: number;
+}
+export interface ServerStoreEventHubConfig {
+    readonly mintMutationId: () => GridMutationId;
+    readonly onEvent: (event: ServerStoreEvent) => void;
+}
+export interface ServerStoreEventHub<TRow = unknown, TContext = unknown> {
+    trackStore(record: ServerStoreRecord): ServerStoreEventRecordResult;
+    recordRefreshApplied(result: ServerRefreshApiResult, registryAfter: ServerStoreRegistry): ServerStoreEventRecordResult;
+    recordIssue(issue: ServerDatasourceIssue<TContext>): ServerStoreEventRecordResult;
+    recordSettlement(settlement: ServerDatasourceSettlement<TRow, TContext>, info?: {
+        complete?: boolean;
+    }): ServerStoreEventRecordResult;
+    recordRowsChanged(input: {
+        storeId: string;
+        storeSeq: number;
+        added: number;
+        updated: number;
+        removed: number;
+        mutationId?: GridMutationId;
+    }): ServerStoreEventRecordResult;
+    recordStoreClosed(storeIds: readonly string[]): ServerStoreEventRecordResult;
+    destroy(): ServerStoreEventRecordResult;
+    status(): 'active' | 'destroyed';
+    openRefreshCount(): number;
+    pendingLoadCount(): number;
+    trackedStores(): readonly ServerStoreEventView[];
+    counters(): ServerStoreEventCounters;
+}
+export declare function createServerStoreEventHub<TRow = unknown, TContext = unknown>(config: ServerStoreEventHubConfig): ServerStoreEventHub<TRow, TContext>;