Viewport snapshot & reducer

comins-table@0.2.2React

Pure functions for integrations that own state in an external store. Use functional updates for each response so concurrent blocks are preserved.

createCominsViewportData

export declare function createCominsViewportData<T>(options: CominsViewportDataOptions): CominsViewportData<T>;

Starts with empty blocks, requests, changes and retainRange, with version/clock at 0. A negative, fractional or unsafe rowCount throws RangeError. blockSize defaults to 100 and cacheSize to 12.

reduceCominsViewportData

export declare function reduceCominsViewportData<T>(data: CominsViewportData<T>, event: CominsViewportDataEvent<T>): CominsViewportData<T>;

Returns the next snapshot without mutating the input. Pair request with success/error/cancel using the same requestId. Resolving a Promise alone does not update the snapshot. A range starts at a blockSize multiple and ends at min(rowCount, startIndex + blockSize). Mismatched revisions or current request IDs are ignored.

CominsViewportDataOptions

export type CominsViewportDataOptions = {
    revision: CominsViewportRevision;
    rowCount: number;
    blockSize?: number;
    cacheSize?: number;
};

Property	Behavior / default
`revision`	Required dataset identifier; replace it on reset.
`rowCount`	Required total count, a non-negative safe integer.
`blockSize`	Rows per block; defaults to 100 for invalid positive-safe-integer input.
`cacheSize`	Target block count, including unprotected blocks; defaults to 12.

CominsViewportData

export type CominsViewportData<T> = {
    revision: CominsViewportRevision;
    rowCount: number;
    blockSize: number;
    cacheSize: number;
    blocks: readonly CominsViewportBlock<T>[];
    requests: readonly CominsViewportRequestState[];
    retainRange: CominsViewportRange;
    version: number;
    clock: number;
    changes: readonly CominsViewportPatch<T>[];
};

Property	Behavior / default
`revision`	Current dataset revision.
`rowCount`	Total count, independent of the loaded rows in blocks.
`blockSize`	Normalized block size in rows.
`cacheSize`	Normalized target block count.
`blocks`	Loaded blocks; no full-length dataset array is allocated.
`requests`	Active loading and retained error records; success/cancel removes the matching entry.
`retainRange`	Half-open range to retain; intersecting blocks are protected during trimming.
`version`	Increments on accepted patches and prevents an older fetch from overwriting newer edits.
`clock`	Usage counter incremented on successful loads and retain changes.
`changes`	Last accepted edit patches; cleared by request/retain/response transitions.

CominsViewportBlock

export type CominsViewportBlock<T> = {
    startIndex: number;
    rows: readonly T[];
    version: number;
    touched: number;
};

Property	Behavior / default
`startIndex`	Absolute index of the first row.
`rows`	Block rows; the final block can be shorter.
`version`	Data version at load/edit time, used to reject stale overwrites.
`touched`	Last-used clock for evicting unprotected blocks.

CominsViewportRequestState

export type CominsViewportRequestState = CominsViewportRange & {
    requestId: string;
    status: "loading" | "error";
    version: number;
};

Adds requestId, loading/error status and the request-start version to CominsViewportRange.startIndex/endIndex. It does not store an error message object; keep custom error details in the app.

CominsViewportPatch

export type CominsViewportPatch<T> = {
    index: number;
    row: T;
};

Property	Behavior / default
`index`	Absolute index of a loaded row; patches for unloaded rows are ignored.
`row`	Complete replacement row, not a partial object. The last patch for a repeated index wins.

CominsViewportDataEvent

export type CominsViewportDataEvent<T> = BrowserViewportDataEvent<T>;

BrowserViewportDataEvent is an alias inside the published declaration. Applications import the public CominsViewportDataEvent and CominsViewportRequest types from the root comins-table entry; do not import internal files. The expanded event contract is:

`type`	Additional fields
`request`	`request: CominsViewportRequest`
`cancel`	`request: CominsViewportRequest`
`error`	`request: CominsViewportRequest`
`success`	`request: CominsViewportRequest`, `rows: readonly T[]`
`retain`	`range: CominsViewportRange`
`patch`	`changes: readonly CominsViewportPatch<T>[]`
`reset`	`options: CominsViewportDataOptions`

For the four request-bearing variants, CominsViewportRequest includes signal: AbortSignal, requestId, revision, startIndex, endIndex, and retainRange. The retain, patch, and reset variants do not require a signal. The reachable-contracts tab in the public API catalog also contains the underlying alias declarations.

request registers the current request for a block. success caches rows of the exact requested length; null/undefined rows or a length mismatch produce an error record. error records failure and cancel removes the matching request.

retain normalizes its range to 0…rowCount and trims unprotected blocks. patch updates cached rows only and increments version when a row actually changes. A late success cannot overwrite a block edited since its request began. reset recreates the snapshot using new options.

CominsViewportRevision

export type CominsViewportRevision = string | number;

A string or number. Keep the index-to-row mapping stable within a revision.