Viewport Snapshot · Reducer

comins-table@0.2.2React

외부 store 등에서 상태를 직접 관리할 때 사용하는 순수 함수입니다. 각 응답을 함수형 상태 갱신으로 반영하여 동시에 도착한 블록을 보존합니다.

createCominsViewportData

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

빈 blocks·requests·changes, 빈 retainRange와 version/clock 0으로 시작합니다. rowCount가 음수·소수·안전한 정수 범위 밖이면 RangeError를 던집니다. 기본 blockSize는 100, cacheSize는 12입니다.

reduceCominsViewportData

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

입력 snapshot을 변경하지 않고 다음 snapshot을 반환합니다. request → success/error/cancel을 같은 requestId로 연결하십시오. Promise 완료만으로 요청 상태가 갱신되지는 않습니다. 범위는 blockSize 배수에서 시작하여 min(rowCount, startIndex + blockSize)에서 끝나야 합니다. revision이나 현재 requestId가 다른 응답은 무시합니다.

CominsViewportDataOptions

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

속성	동작·기본값
`revision`	필수 dataset 식별자. reset 시 새 값으로 교체합니다.
`rowCount`	필수 전체 건수. 0 이상의 안전한 정수입니다.
`blockSize`	블록 행 수. 기본 100, 양의 안전한 정수만 허용합니다.
`cacheSize`	비보호 블록을 포함한 캐시 목표 개수. 기본 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>[];
};

속성	동작·기본값
`revision`	현재 dataset revision.
`rowCount`	전체 건수. blocks에 로딩된 행 수와 다릅니다.
`blockSize`	정규화된 블록 행 수.
`cacheSize`	정규화된 블록 캐시 목표 개수.
`blocks`	로딩된 블록. 전체 건수 길이의 배열을 만들지 않습니다.
`requests`	활성 loading 및 보관된 error 상태. 성공·취소 후 해당 항목은 제거됩니다.
`retainRange`	현재 보존할 반개구간. 겹치는 블록은 캐시 정리에서 보호됩니다.
`version`	편집 patch가 반영될 때 증가하며, 이전 조회가 새 편집을 덮는 것을 방지합니다.
`clock`	블록 조회 성공·retain 변경 시 증가하는 사용 순서입니다.
`changes`	마지막으로 승인된 편집 patch 목록. 요청/보존/응답 전환에서 비워집니다.

CominsViewportBlock

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

속성	동작·기본값
`startIndex`	블록 첫 행의 절대 인덱스.
`rows`	블록 내 행 배열. 마지막 블록은 짧을 수 있습니다.
`version`	로드/편집 시점의 데이터 version. 오래된 응답 차단에 사용합니다.
`touched`	최근 사용 clock. 비보호 블록 퇴출 우선순위에 사용합니다.

CominsViewportRequestState

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

CominsViewportRange의 startIndex/endIndex에 requestId, loading/error 상태, 요청 시작 시점 version을 더합니다. 오류 메시지 객체는 저장하지 않습니다. 사용자 오류 표시가 필요하면 앱에서 별도로 보관합니다.

CominsViewportPatch

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

속성	동작·기본값
`index`	로딩된 행의 절대 인덱스. 미수신 인덱스 patch는 반영하지 않습니다.
`row`	부분 객체가 아닌 새 행 전체. 동일 인덱스의 마지막 patch가 우선합니다.

CominsViewportDataEvent

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

BrowserViewportDataEvent는 배포 선언 내부의 별칭 이름입니다. 애플리케이션은 루트 comins-table에서 공개 타입 CominsViewportDataEvent와 CominsViewportRequest를 가져옵니다. 내부 파일을 직접 import하지 않습니다. 별칭을 펼친 이벤트 계약은 다음과 같습니다.

`type`	추가 필드
`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`

요청을 포함한 네 variant의 CominsViewportRequest에는 signal: AbortSignal과 requestId, revision, startIndex, endIndex, retainRange가 포함됩니다. retain, patch, reset은 signal을 요구하지 않습니다. 공개 API 카탈로그의 도달 계약 탭에서 별칭의 원본 선언도 확인할 수 있습니다.

request는 현재 블록 요청을 등록합니다. success는 정확한 길이의 rows를 캐시하며, null/undefined 또는 길이 불일치는 error 상태가 됩니다. error는 실패를 기록하고 cancel은 해당 요청을 제거합니다.

retain은 범위를 0…rowCount로 정규화하고 비보호 블록을 정리합니다. patch는 캐시에 있는 행만 갱신하며 실제 변경이 있으면 version을 증가시킵니다. 요청 이후 편집된 같은 블록은 늦은 success로 덮어쓰지 않습니다. reset은 새 options로 완전히 초기화합니다.

CominsViewportRevision

export type CominsViewportRevision = string | number;

문자열 또는 숫자입니다. 동일 revision 안에서는 인덱스와 행의 대응을 안정적으로 유지하십시오.