stream-chat 9.50.3 → 10.0.0-rc.2

package/dist/types/pagination/paginators/BasePaginator.d.ts

@@ -0,0 +1,848 @@
+import type { ItemLocation } from '../sortCompiler';
+import { StateStore, type ValueOrPatch } from '../../store';
+import { type DebouncedFunc } from '../../utils';
+import type { FieldToDataResolver } from '../types.normalization';
+import type { ItemIndexApi } from '../ItemIndex';
+export declare const LOGICAL_HEAD_INTERVAL_ID = "__logical_head__";
+export declare const LOGICAL_TAIL_INTERVAL_ID = "__logical_tail__";
+type IntervalSortBounds<T> = {
+    start: T;
+    end: T;
+};
+type IntervalPaginationEdges<T> = {
+    head: T;
+    tail: T;
+};
+export type LogicalInterval = {
+    itemIds: string[];
+    id: typeof LOGICAL_HEAD_INTERVAL_ID | typeof LOGICAL_TAIL_INTERVAL_ID;
+};
+export type Interval = {
+    hasMoreHead: boolean;
+    hasMoreTail: boolean;
+    itemIds: string[];
+    id: string;
+    /**
+     * True if this interval represents the global head of the dataset
+     * under the current sortComparator.
+     *
+     * Cursor pagination:
+     *   headward === null
+     *
+     * Offset pagination:
+     *   offset === 0
+     */
+    isHead: boolean;
+    /**
+     * True if this interval represents the global tail of the dataset
+     * under the current sortComparator.
+     *
+     * Cursor pagination:
+     *   tailward === null
+     *
+     * Offset pagination:
+     *   returnedItems.length < pageSize
+     */
+    isTail: boolean;
+};
+export type AnyInterval = Interval | LogicalInterval;
+export type IntervalMergePolicy = 'auto' | 'strict-overlap-only';
+type ItemIntervalCoordinates = ItemLocation & {
+    interval: Interval | LogicalInterval;
+};
+export type ItemCoordinates = {
+    /** Location inside state.items (visible list) */
+    state?: ItemLocation;
+    /** Location inside an interval (anchored or logical) */
+    interval?: ItemIntervalCoordinates;
+};
+export declare const isLiveHeadInterval: (interval: AnyInterval) => interval is LogicalInterval;
+export declare const isLiveTailInterval: (interval: AnyInterval) => interval is LogicalInterval;
+export declare const isLogicalInterval: (interval: AnyInterval) => interval is LogicalInterval;
+export type MakeIntervalParams<T> = {
+    page: T[];
+    isHead?: boolean;
+    isTail?: boolean;
+};
+export type SetPaginatorItemsParams<T> = {
+    valueOrFactory: ValueOrPatch<T[]>;
+    cursor?: PaginatorCursor;
+    /**
+     * Relevant only is using item interval storage in the paginator.
+     * Indicates that the page would be the head of pagination intervals array.
+     * Items falling outside this intervals head bound will be merged into this interval.
+     */
+    isFirstPage?: boolean;
+    /**
+     * Relevant only is using item interval storage in the paginator.
+     * Indicates that the page would be the tail of pagination intervals array
+     * Items falling outside this intervals tail bound will be merged into this interval.
+     */
+    isLastPage?: boolean;
+};
+type MergeIntervalsResult = {
+    logicalHead: LogicalInterval | null;
+    merged: Interval | null;
+    logicalTail: LogicalInterval | null;
+};
+/**
+ * headward - going from page  X -> X-Y -> 0
+ * tailward - goring from page 0 -> X -> X + Y ...
+ *
+ * Head is the place where new items are added - same as git.
+ * Tail is the place where retrieved pages are appended.
+ */
+export type PaginationDirection = 'headward' | 'tailward';
+export type CursorDeriveContext<T, Q> = {
+    /**
+     * Current cursor to be merged with the newly derived cursor.
+     * Allows to preserve the direction we have not paginated with the given request.
+     */
+    cursor: PaginatorCursor | undefined;
+    /**
+     * Direction we just paginated in.
+     *
+     * May be undefined for non-directional queries (e.g. jump-to / *_around).
+     */
+    direction: PaginationDirection | undefined;
+    hasMoreTail: boolean;
+    hasMoreHead: boolean;
+    /** The parent interval the page was ingested into (if any) */
+    interval: Interval;
+    /** The page we just received after filtering */
+    page: T[];
+    /** Last query shape (sometimes useful for bespoke logic) */
+    queryShape: Q | undefined;
+    /** Number we asked for */
+    requestedPageSize: number;
+};
+export type PaginationFlags = {
+    hasMoreHead: boolean;
+    hasMoreTail: boolean;
+};
+export type CursorDeriveResult = PaginationFlags & {
+    cursor: PaginatorCursor | undefined;
+};
+export type CursorDerivator<T, Q> = (ctx: CursorDeriveContext<T, Q>) => CursorDeriveResult;
+/**
+ * string - there is a next page in the given direction
+ * null - pagination in the given direction has been exhausted
+ * undefined - no page has been requested in the given pagination direction
+ */
+export type PaginatorCursor = {
+    tailward: string | null | undefined;
+    headward: string | null | undefined;
+};
+export declare const ZERO_PAGE_CURSOR: PaginatorCursor;
+type StateResetPolicy = 'auto' | 'yes' | 'no' | (string & {});
+export type PaginationQueryShapeChangeIdentifier<S> = (toHeadQueryShape?: S, toTailQueryShape?: S) => boolean;
+export type PaginationQueryParams<Q> = {
+    direction?: PaginationDirection;
+    /**
+     * Keep the currently loaded items (and cursor/flags) visible while a first-page query runs
+     * instead of blanking to the empty initial state. The freshly fetched page is merged into the
+     * active interval by `postQueryReconcile` (upserting changed items, appending new ones), so the
+     * list is refreshed in place with no loading-screen flash. Used by the non-destructive refresh.
+     */
+    keepPreviousItems?: boolean;
+    /** Data that define the query (filters, sort, ...) */
+    queryShape?: Q;
+    /** Per-call override of the reset behavior. */
+    reset?: StateResetPolicy;
+    /**
+     * How many times to **retry** a failed request, i.e. `retryCount + 1` attempts in total. Per-call
+     * override of `PaginatorOptions.retryCount`, which defaults to 0 (no retry).
+     */
+    retryCount?: number;
+    /**
+     * Suppress `isLoading` transitions for this query (a silent, background refresh). When falsy
+     * (default) the usual loading state is surfaced so the UI can show a spinner.
+     */
+    silent?: boolean;
+    /** Determines, whether the page loaded with the query will be committed to the paginator state. Default: true. */
+    updateState?: boolean;
+};
+export type PostQueryReconcileParams<T, Q> = Pick<PaginationQueryParams<Q>, 'direction' | 'queryShape' | 'updateState' | 'keepPreviousItems'> & {
+    isFirstPage: boolean;
+    requestedPageSize: number;
+    results: PaginationQueryReturnValue<T> | null;
+};
+export type ExecuteQueryReturnValue<T> = {
+    /**
+     * State object resulting from the post query processing.
+     * The object is committed to the state if PaginationQueryParams<Q>['updateState'] === true.
+     */
+    stateCandidate: Partial<PaginatorState<T>>;
+    /** In case the items are kept in intervals, the interval into which the page has been merged, will be returned. */
+    targetInterval: AnyInterval | null;
+};
+export type PaginationQueryReturnValue<T> = {
+    items: T[];
+} & {
+    headward?: string;
+    tailward?: string;
+    /**
+     * @deprecated Use `tailward` instead.
+     */
+    next?: string;
+    /**
+     * @deprecated Use `headward` instead.
+     */
+    prev?: string;
+};
+export type PaginatorDebounceOptions = {
+    debounceMs: number;
+};
+type DebouncedExecQueryFunction<Q> = DebouncedFunc<(params: PaginationQueryParams<Q>) => Promise<void>>;
+export type PaginatorState<T> = {
+    hasMoreHead: boolean;
+    hasMoreTail: boolean;
+    isLoading: boolean;
+    items: T[] | undefined;
+    lastQueryError?: Error;
+    cursor?: PaginatorCursor;
+    offset?: number;
+};
+/**
+ * Reactive projections of specific (fixed-identity) intervals, published independently of the
+ * paginated `state` (which tracks only the *active* interval). See {@link BasePaginator.intervalViews}.
+ * A field is rewritten only when its own interval changes, so a `useStateStore`/`subscribeWithSelector`
+ * consumer selecting one field only wakes when *that* interval changes. (The head-most window that can
+ * be either a logical or an anchored interval is a derived *role*, not a fixed interval, so it is not
+ * published here — read it one-shot via {@link BasePaginator.headItems} / {@link BasePaginator.headmostItem}.)
+ */
+export type PaginatorIntervalViews<T> = {
+    /** Live logical-head interval — out-of-order items above the loaded window. */
+    logicalHead: T[];
+    /** Live logical-tail interval — out-of-order items below the loaded window. */
+    logicalTail: T[];
+    /**
+     * Anchored head interval — the loaded page bounded at the dataset head (`isHead`), i.e. the newest
+     * loaded page; empty when the head is not loaded. Its content updates when that page ingests/removes
+     * an item, and its identity updates when a page's `isHead` flag flips during query reconciliation.
+     */
+    anchoredHead: T[];
+};
+export type PaginatorItemsChangeProcessor<T> = (params: {
+    nextItems: T[] | undefined;
+    previousItems: T[] | undefined;
+}) => T[] | undefined;
+export interface PaginatorPlugin<T> {
+    /**
+     * Optional plugin hook invoked immediately before the paginator emits a new
+     * `items` value to subscribers, but only when the `items` array has actually
+     * changed by reference.
+     *
+     * This hook allows plugins to post-process the visible items—such as
+     * deduplicating, normalizing, sorting, enriching, or otherwise transforming
+     * the array—at the final stage of state emission. The processed value becomes
+     * the `items` value delivered to subscribers.
+     *
+     * Return a new array to replace `nextState.items`, or return `undefined`
+     * to leave the items unchanged.
+     *
+     * Executed in the order plugins are registered.
+     */
+    onBeforeItemsEmitted?: PaginatorItemsChangeProcessor<T>;
+}
+/**
+ * Optional list of plugins that can hook into paginator lifecycle events.
+ *
+ * Plugins allow you to encapsulate cross-cutting behavior (such as items
+ * post-processing, analytics, offline caching, etc.) without modifying
+ * the core paginator logic. Each plugin can register handlers like
+ * `onItemsChange` that are invoked when relevant events occur.
+ *
+ * All registered plugins are executed in the order they appear in this array.
+ */
+export type PaginatorOptions<T, Q> = {
+    /** The number of milliseconds to debounce the search query. The default interval is 300ms. */
+    debounceMs?: number;
+    /**
+     * When set (and not disabled for tests — see `stateThrottling.ts`), coalesces the paginator's own
+     * live `state.items` publishes to at most once per `stateThrottleMs` (leading + trailing edge): a
+     * burst of live mutations (WS `message.new`, reactions, reads) re-projects the active window and
+     * publishes it ~2×/sec instead of once per event. Only the paginator's OWN writes to `state.items`
+     * are batched — `state.getLatestValue()` is untouched (no `StateStore` change), pagination / jump /
+     * query publishes stay immediate, and an immediate flush past it is available via
+     * {@link flushPendingPublishes}. Unset ⇒ no throttle (default). Enabled at
+     * 500ms for the message list — see {@link MessagePaginator}.
+     */
+    stateThrottleMs?: number;
+    /**
+     * Function containing custom logic that decides, whether the next pagination query to be executed should be considered the first page query.
+     * It makes sense to consider the next query as the first page query if filters, sort, options etc. (query params) excluding the page size have changed.
+     */
+    hasPaginationQueryShapeChanged?: PaginationQueryShapeChangeIdentifier<any>;
+    /**
+     * Optional hook to fully control cursor + hasMore logic in 'derived' mode.
+     * If not provided, BasePaginator uses its own default implementation.
+     */
+    deriveCursor?: CursorDerivator<T, Q>;
+    /** Custom function to retrieve items pages and optionally return a cursor in case of cursor pagination. */
+    doRequest?: (queryParams: Q) => Promise<{
+        items: T[];
+        cursor?: PaginatorCursor;
+    }>;
+    /** In case of cursor pagination, specify the initial cursor value. */
+    initialCursor?: PaginatorCursor;
+    /** In case of offset pagination, specify the initial offset value. */
+    initialOffset?: number;
+    /** If item index is provided, this index ensures updates in a single place and all consumers have access to a single source of data. */
+    itemIndex?: ItemIndexApi<T>;
+    /**
+     * Factory for the item index, invoked with the fully-constructed paginator as `owner`.
+     * Lets a subclass back the paginator with an adapter that needs a reference to the
+     * owner (e.g. a shared, client-global store) without the `this`-before-`super` problem.
+     * Ignored when an explicit `itemIndex` is supplied.
+     */
+    createItemIndex?: (owner: BasePaginator<T, Q>) => ItemIndexApi<T>;
+    /**
+     * Comparator defining in-memory item ordering for interval math and visible list rendering.
+     * Defaults to `sortComparator` to preserve existing paginator behavior.
+     */
+    itemOrderComparator?: (a: T, b: T) => number;
+    /**
+     * Will prevent changing the index of existing items in state.
+     * If true, an item that is already visible keeps its relative position in the current items array when updated.
+     * It does not guarantee global stability across interval changes or page jumps.
+     */
+    lockItemOrder?: boolean;
+    /** The item page size to be requested from the server. */
+    pageSize?: number;
+    /**
+     * How many times to **retry** a failed request before giving up, i.e. `retryCount + 1` attempts in
+     * total, with `DEFAULT_QUERY_CHANNELS_MS_BETWEEN_RETRIES` between them. Defaults to 0 (no retry);
+     * `PaginationQueryParams.retryCount` overrides it per call.
+     */
+    retryCount?: number;
+    /** Prevent silencing the errors thrown during the pagination execution. Default is false. */
+    throwErrors?: boolean;
+};
+type OptionalPaginatorConfigFields = 'stateThrottleMs' | 'deriveCursor' | 'doRequest' | 'initialCursor' | 'initialOffset' | 'itemIndex' | 'createItemIndex' | 'itemOrderComparator' | 'throwErrors';
+export type BasePaginatorConfig<T, Q> = Pick<PaginatorOptions<T, Q>, OptionalPaginatorConfigFields> & Required<Omit<PaginatorOptions<T, Q>, OptionalPaginatorConfigFields>>;
+export declare const DEFAULT_PAGINATION_OPTIONS: BasePaginatorConfig<any, any>;
+export declare abstract class BasePaginator<T, Q> {
+    state: StateStore<PaginatorState<T>>;
+    /**
+     * Reactive projections of specific intervals — see {@link PaginatorIntervalViews}. Unlike `state`
+     * (which only re-emits when the *active* interval is impacted), a field here is rewritten whenever
+     * its own interval changes, regardless of which interval is active — so consumers can reactively
+     * render off-window "sideloaded" content (`logicalHead`/`logicalTail`) and the newest loaded page
+     * (`anchoredHead`). Kept separate from `state` so the paginated-list contract stays focused on the
+     * active window + pagination status.
+     */
+    intervalViews: StateStore<PaginatorIntervalViews<T>>;
+    config: BasePaginatorConfig<T, Q>;
+    /**
+     * Throttle for the active-window `state.items` publish (message list). Created only when
+     * `config.stateThrottleMs` is set; drives {@link scheduleWindowPublish} / {@link flushPendingPublishes}. See
+     * `stateThrottleMs` in {@link PaginatorOptions}.
+     */
+    private _windowPublishThrottle?;
+    /**
+     * Throttle for the interval-view publishes (`anchoredHead` / `logicalHead` / `logicalTail`) driven
+     * by sibling store updates. Independent of {@link _windowPublishThrottle} so a view refresh lands on
+     * its own trailing edge even when `state.items` stays quiet. Created alongside it (only when
+     * `config.stateThrottleMs` is set); buffers changed ids in {@link _pendingViewChangedIds}.
+     */
+    private _viewPublishThrottle?;
+    /** Changed ids buffered since the last {@link flushIntervalViewPublish} (throttled paginators only). */
+    private _pendingViewChangedIds;
+    /**
+     * Intervals keep items in disconnected ranges.
+     * That is a scenario of jumping to non-sequential pages.
+     * Intervals are populated only if itemIndex is provided.
+     */
+    protected _itemIntervals: Map<string, AnyInterval>;
+    protected _activeIntervalId: string | undefined;
+    /**
+     * ItemIndex is a canonical, ID-addressable storage layer for domain items.
+     * It serves as a single source of truth for all those that need to access the items
+     * outside the paginator.
+     */
+    protected _itemIndex: ItemIndexApi<T>;
+    protected _executeQueryDebounced: DebouncedExecQueryFunction<Q>;
+    /** Last effective query shape produced by subclass for the most recent request. */
+    protected _lastQueryShape?: Q;
+    protected _nextQueryShape?: Q;
+    /**
+     * Stable, performs purely item data-driven (age, last_message_at, etc.) comparison.
+     * Used under the hood
+     * 1. as a fallback by effectiveComparator / boostComparator if boost comparison is not conclusive
+     * 2. interval comparator
+     *
+     * Intervals cannot be sorted using boostComparator, because boosting the interval boundary (top item)
+     * would lead to the boosting of the entire interval when sorting the intervals.
+     *
+     * Sorting within a single interval should be done using effectiveComparator, which by default uses boostComparator.
+     */
+    sortComparator: (a: T, b: T) => number;
+    protected _filterFieldToDataResolvers: FieldToDataResolver<T>[];
+    protected boosts: Map<string, {
+        until: number;
+        seq: number;
+    }>;
+    protected _maxBoostSeq: number;
+    /**
+     * Describes how `interval.itemIds` are oriented relative to pagination semantics.
+     *
+     * - `true`  => `itemIds[0]` is the pagination head edge (default)
+     * - `false` => `itemIds[itemIds.length - 1]` is the pagination head edge
+     *
+     * NOTE: This does not affect the *sorting* of `itemIds` (they are always kept
+     * in `sortComparator` order). It only affects which side is considered
+     * "head" for interval ordering and live ingestion decisions.
+     */
+    protected get intervalItemIdsAreHeadFirst(): boolean;
+    /**
+     * Determines the ordering of intervals in the internal interval list.
+     *
+     * This controls only the ordering of intervals relative to each other (by comparing
+     * their head edges using `sortComparator`). It is intentionally decoupled from:
+     * - the ordering of itemIds inside an interval
+     * - the meaning of the head edge (controlled by `intervalItemIdsAreHeadFirst`)
+     */
+    protected get intervalSortDirection(): 'asc' | 'desc';
+    protected constructor({ initialCursor, initialOffset, itemIndex, createItemIndex, ...options }?: PaginatorOptions<T, Q>);
+    get lastQueryError(): Error | undefined;
+    get hasMoreTail(): boolean;
+    get hasMoreHead(): boolean;
+    /**
+     * @deprecated Use `hasMoreTail` instead.
+     */
+    get hasNext(): boolean;
+    /**
+     * @deprecated Use `hasMoreHead` instead.
+     */
+    get hasPrev(): boolean;
+    get hasResults(): boolean;
+    get isLoading(): boolean;
+    /** Signals that the paginator has not performed any query so far */
+    get isInitialized(): boolean;
+    get isOfflineSupportEnabled(): boolean;
+    get isCursorPagination(): boolean;
+    get initialState(): PaginatorState<T>;
+    get items(): T[] | undefined;
+    /**
+     * The newest loaded window of items, independent of which window is currently *active*
+     * (`items` follows the active interval, which may point at a jumped-to / searched window). This is
+     * the head-most loaded interval under the paginator's ordering (anchored or the live-head logical
+     * interval).
+     *
+     * NOTE: this deliberately uses the head-*most loaded* interval rather than requiring the
+     * `isHead` flag — the query/hydration seed does not reliably mark a freshly loaded latest page
+     * as `isHead`, so an isHead-only check would miss channel-list channels entirely. The trade-off
+     * is that after jumping to an older window with the latest window not loaded, this reports that
+     * older window as "latest" (best effort). Use for "latest"-derived reads: last message, unread
+     * counting, delivery candidates, channel-list previews.
+     */
+    get headItems(): T[];
+    /**
+     * The item on the head edge of the head pagination interval (of {@link BasePaginator.headItems}).
+     * `undefined` when nothing is loaded.
+     */
+    get headmostItem(): T | undefined;
+    get cursor(): PaginatorCursor | undefined;
+    get offset(): number | undefined;
+    get pageSize(): number;
+    set pageSize(size: number);
+    set initialCursor(cursor: PaginatorCursor);
+    set initialOffset(offset: number);
+    /** Single point of truth: always use the effective comparator */
+    get effectiveComparator(): (a: T, b: T) => number;
+    protected get itemOrderComparator(): (a: T, b: T) => number;
+    get intervalComparator(): (a: AnyInterval, b: AnyInterval) => number;
+    get maxBoostSeq(): number;
+    protected get itemIntervals(): AnyInterval[];
+    protected get liveHeadLogical(): LogicalInterval | undefined;
+    protected get liveTailLogical(): LogicalInterval | undefined;
+    /**
+     * The current contents of the live logical-head interval (items ingested out of pagination order).
+     * Reads the same value published to {@link BasePaginator.intervalViews}.`logicalHead`.
+     */
+    get logicalHeadItems(): T[];
+    /**
+     * The current contents of the live logical-tail interval (out-of-order items below the loaded
+     * window). Reads the same value published to {@link BasePaginator.intervalViews}.`logicalTail`.
+     */
+    get logicalTailItems(): T[];
+    /**
+     * The current contents of the anchored head interval (the loaded page bounded at the dataset head,
+     * `isHead`). Reads the same value published to {@link BasePaginator.intervalViews}.`anchoredHead`.
+     */
+    get anchoredHeadItems(): T[];
+    /**
+     * Commit an interval into storage. Single choke point for adding/updating an interval, so it also
+     * republishes the matching {@link intervalViews} field when the committed interval is a tracked one
+     * (logical head / logical tail / anchored head). Use this instead of writing `_itemIntervals`
+     * directly — bulk re-sorting (which does not change any interval's membership) goes through
+     * {@link setIntervals}.
+     */
+    protected commitInterval(interval: AnyInterval): void;
+    /** Drop an interval from storage, republishing the matching {@link intervalViews} field if tracked. */
+    protected dropInterval(id: string): void;
+    /**
+     * Republish the {@link intervalViews} field backed by the given interval — called from
+     * {@link commitInterval} / {@link dropInterval} (i.e. when that interval ingests or removes an item).
+     * A write to an untracked interval touches nothing here. (The anchored head is also published
+     * directly via {@link publishAsAnchoredHead} from the reconciliation points that flip `isHead` —
+     * see {@link postQueryReconcile}.)
+     */
+    private publishIntervalViewFor;
+    /**
+     * Publish `interval` as the anchored head — the loaded page bounded at the dataset head (`isHead`),
+     * or `undefined` to clear it (the head page was removed or a page stopped being the head). Callers
+     * pass the interval they already have, so this does not re-scan storage for the head. Its content
+     * changes via ingest/remove (routed through {@link commitInterval}/{@link dropInterval}) and its
+     * identity changes when a page's `isHead` flag flips during query reconciliation — both call here.
+     */
+    protected publishAsAnchoredHead(interval: AnyInterval | undefined): void;
+    /**
+     * Keep `anchoredHead` in sync after a page's `isHead` flag was (re)computed during query
+     * reconciliation, given its value `wasHead` beforehand. Acts only on an actual transition:
+     * - became the head page → publish it as the anchored head;
+     * - stopped being the head page → clear the anchored head;
+     * - unchanged → nothing (a content change, if any, was already published when the interval was
+     *   committed — see {@link commitInterval}).
+     */
+    protected syncAnchoredHeadAfterHeadFlip(interval: Interval, wasHead: boolean): void;
+    private intervalItemsOrEmpty;
+    /**
+     * Empty every {@link intervalViews} field. Used by reset paths that clear intervals in bulk (via
+     * {@link setIntervals}), which bypasses the per-interval {@link commitInterval}/{@link dropInterval}
+     * publishing. No-ops when the views are already empty so a reset does not emit needlessly.
+     */
+    protected clearIntervalViews(): void;
+    abstract query(params: PaginationQueryParams<Q>): Promise<PaginationQueryReturnValue<T>>;
+    abstract filterQueryResults(items: T[]): T[];
+    /**
+     * Subclasses must return the query shape.
+     */
+    protected getNextQueryShape(_params?: Pick<PaginationQueryParams<Q>, 'direction'>): Q;
+    /**
+     * Filters an item is matched against locally (`matchesFilter`) — NOT the filters sent to the server.
+     * A paginator whose backend query is filtered has to build the request filters separately (see
+     * `ChannelPaginator.buildQueryFilters`), because the two can differ: the backend may resolve a
+     * server-side stored filter of its own, and some paginators filter locally without sending anything.
+     */
+    protected buildMatchFilters(): object | null;
+    matchesFilter(item: T): boolean;
+    setFilterResolvers(resolvers: FieldToDataResolver<T>[]): void;
+    addFilterResolvers(resolvers: FieldToDataResolver<T>[]): void;
+    getItemId(item: T): string;
+    getItem(id: string | undefined): T | undefined;
+    /**
+     * Whether this paginator's live `state.items` publishes are currently throttled — `stateThrottleMs`
+     * is set, throttling is not globally disabled (tests), and item order is not locked (a locked-order
+     * list must emit the caller-computed, order-preserved array, not a re-projection). When false, every
+     * live mutation publishes immediately, exactly as before this feature.
+     */
+    protected get isStateThrottled(): boolean;
+    /** Re-project the active window from its (live, source-of-truth) interval. `undefined` when inactive. */
+    private projectActiveWindow;
+    /**
+     * Publish the active window to `state`, re-projecting it fresh from the active interval at call time
+     * (the throttle boundary / flush). Because the intervals are mutated synchronously by every live op,
+     * this always reflects the latest settled state, so intermediate values within a window coalesce
+     * away. Clears the visible window when the active interval is gone (e.g. the last item was removed).
+     */
+    private flushWindowPublish;
+    /**
+     * Schedule a throttled active-window publish (leading + trailing). Called from live mutations
+     * (ingest / content-change / remove) INSTEAD of an inline `state.partialNext({ items })` when
+     * {@link isStateThrottled}. Safe to call many times within one op — they coalesce to a single emit.
+     */
+    protected scheduleWindowPublish(): void;
+    /**
+     * Flush any pending throttled window + interval-view publishes immediately. No-op when nothing
+     * is pending or throttling is off.
+     */
+    protected flushPendingPublishes(): void;
+    /**
+     * {@link _viewPublishThrottle} boundary: apply every interval-view change buffered since the last
+     * flush, then clear the buffer. Independent of the `state.items` window publish, so a view update
+     * lands within one throttle interval even when the active window stays quiet (e.g. a reaction on a
+     * head message while a non-head window is active). No-op when nothing was buffered.
+     */
+    private flushIntervalViewPublish;
+    /**
+     * Refresh any tracked {@link intervalViews} field (logical head, logical tail, anchored head) that
+     * holds one of `changedIds`. A sibling holder writing new content through the shared item store
+     * swaps the item object those views reference, but only this paginator's own ingest/remove
+     * ({@link commitInterval}/{@link dropInterval}) republish them — so a reaction/edit made elsewhere
+     * would otherwise leave stale references in `anchoredHead`/`logicalHead`/`logicalTail` even though
+     * the active window (`state.items`, see {@link reconcileChangedIds}) was refreshed.
+     *
+     * Called immediately for un-throttled paginators, or from {@link flushIntervalViewPublish} at the
+     * view-publish throttle boundary when throttled — see {@link reconcileChangedIds}. Handled
+     * independently of `state.items`. When the anchored head is also the active interval its content is
+     * projected here as well as into `state.items`; deduping that double projection is a separate,
+     * deferred perf follow-up.
+     */
+    private refreshIntervalViewsForChangedIds;
+    private intervalHoldsAnyChangedId;
+    /**
+     * Reconcile the projected window + interval views against a set of changed ids: another holder
+     * swapped the shared item object those views reference. Refreshes any tracked interval view that
+     * holds a changed id and re-projects (or slot-swaps) the active window — coalesced through the
+     * publish throttles when throttling is on.
+     */
+    protected reconcileChangedIds(changedIds: ReadonlySet<string>): void;
+    protected clearExpiredBoosts(now?: number): void;
+    /**
+     * Applied by the effectiveComparator to take into consideration item boosts when sorting items.
+     *
+     * @param a - The first item to compare.
+     * @param b - The second item to compare.
+     */
+    protected boostComparator: (a: T, b: T) => number;
+    /**
+     * Increases the item's importance when sorting.
+     * Boost affects position inside an item interval (if used), but should not redefine interval boundaries.
+     *
+     * @param itemId - Id of the item to boost.
+     * @param opts - Boost options: `ttlMs` / `until` control expiry and `seq` orders concurrent boosts.
+     */
+    boost(itemId: string, opts?: {
+        ttlMs?: number;
+        until?: number;
+        seq?: number;
+    }): void;
+    getBoost(id: string): {
+        until: number;
+        seq: number;
+    } | undefined;
+    removeBoost(id: string): void;
+    isBoosted(id: string): boolean;
+    generateIntervalId(_page: (T | string)[]): string;
+    intervalToItems(interval: Interval | LogicalInterval): T[];
+    makeInterval({ page, isHead, isTail }: MakeIntervalParams<T>): Interval;
+    protected getCursorFromInterval(interval: Interval): PaginatorCursor;
+    isActiveInterval(interval: AnyInterval): boolean;
+    /**
+     * Whether the currently active (viewed) interval is the anchored head. Used to decide if it is
+     * safe to re-seed an already-loaded paginator with a fresh newest page: only when at the head
+     * (the newest page overlaps it, so the re-seed reconciles + re-derives cursors in place). When the
+     * caller has jumped to an older window (active interval is NOT the head), a first-page re-seed
+     * would force-merge the newest page into that window across the gap - so the re-seed is skipped.
+     */
+    get isActiveIntervalAtHead(): boolean;
+    setActiveInterval(interval: AnyInterval | undefined, opts?: {
+        updateState?: boolean;
+    }): void;
+    protected getIntervalSortBounds(interval: Interval | LogicalInterval): IntervalSortBounds<T> | null;
+    /**
+     * Returns pagination head/tail edges of an interval.
+     *
+     * IMPORTANT:
+     * - Edges are derived from the *sort bounds* of the interval (min/max under `sortComparator`).
+     * - Which bound is treated as the pagination "head" is controlled by `intervalItemIdsAreHeadFirst`.
+     * - This is a semantic notion of head/tail (where new items are expected to appear),
+     *   not necessarily "min/max under sortComparator".
+     * New items are always expected to appear at the head of the interval.
+     */
+    protected getIntervalPaginationEdges(interval: Interval | LogicalInterval): IntervalPaginationEdges<T> | null;
+    protected compareIntervalHeadEdges(a: T, b: T): number;
+    protected aIsMoreHeadwardThanB(a: T, b: T): boolean;
+    protected aIsMoreTailwardThanB(a: T, b: T): boolean;
+    protected getHeadIntervalFromSortedIntervals(intervals: AnyInterval[]): AnyInterval | undefined;
+    protected getTailIntervalFromSortedIntervals(intervals: AnyInterval[]): AnyInterval | undefined;
+    protected sortIntervals<I extends AnyInterval>(intervals: I[]): I[];
+    protected setIntervals(intervals: AnyInterval[]): void;
+    protected intervalsStrictlyOverlap(a: AnyInterval, b: AnyInterval): boolean;
+    /**
+     * Returns true if intervals A and B should be merged.
+     *
+     * 1) Strict overlap (range overlap in `sortComparator` order):
+     *    A.min ≤ B.max  AND  B.min ≤ A.max
+     *
+     * 2) Forced merge (policy: 'auto' only):
+     *    If one interval is marked as `isHead`/`isTail`, treat the other as mergeable
+     *    when it extends beyond that interval's pagination head/tail edge
+     *    (computed via `getIntervalPaginationEdges` + headward/tailward helpers).
+     *
+     * In 'strict-overlap-only' policy, only (1) applies.
+     */
+    protected intervalsOverlap(a: AnyInterval, b: AnyInterval, policy?: IntervalMergePolicy): boolean;
+    /**
+     * Whether an item belongs to an anchored interval.
+     */
+    protected belongsToInterval(item: T, interval: AnyInterval): boolean;
+    protected mergeTwoAnchoredIntervals(preceding: Interval, following: Interval): Interval;
+    /**
+     * Merges anchored intervals. Returns null if there are no intervals to merge.
+     */
+    protected mergeAnchoredIntervals(intervals: Interval[], baseInterval?: Interval): Interval | null;
+    protected locateIntervalIndex(interval: Interval): number;
+    /**
+     * Locate item inside a specific interval using the same logic as locateByItem,
+     * but scoped to interval items.
+     */
+    protected locateByItemInInterval({ item, interval, }: {
+        item: T;
+        interval: Interval | LogicalInterval;
+    }): ItemLocation | null;
+    protected locateIntervalForItem(item: T): AnyInterval | undefined;
+    /**
+     * The interval whose `itemIds` lists this id, regardless of where the item now sorts.
+     */
+    protected findIntervalHoldingItem(item: T): AnyInterval | undefined;
+    protected locateByItemInIntervals(item: T): ItemCoordinates['interval'] | undefined;
+    /**
+     * Locates the current position of the item and the index at which the item should be inserted
+     * according to effectiveComparator.
+     *
+     * @param item - The item to locate within the current state.
+     */
+    protected locateItemInState(item: T): ItemLocation | null;
+    locateByItem: (item: T) => ItemCoordinates;
+    protected removeItemIdFromInterval({ interval, ...itemLocation }: ItemIntervalCoordinates): ItemIntervalCoordinates;
+    /**
+     * Inserts an item ID into the interval in the correct sorted position.
+     * Returns unchanged interval if the correct insertion position could not be determined.
+     */
+    protected insertItemIdIntoInterval<I extends Interval | LogicalInterval>(interval: I, item: T): I;
+    /**
+     * Re-evaluates what the logical (live head / tail) intervals still hold against a freshly ingested
+     * page, returning the resulting anchored interval. Live updates park items there before any page
+     * exists — a channel archived while the archived list is untouched lands in the live head — and
+     * once a page covers such an item, leaving it gives the same id two homes, which is what renders
+     * as a duplicated row. The merge in `ingestPage` only folds logical intervals in when its
+     * `isHead`/overlap heuristics fire; this pass is unconditional and idempotent.
+     */
+    protected reconcileLogicalIntervalsAgainst(anchored: Interval): Interval;
+    /**
+     * Moves items the loaded window proves are parked on the wrong side: an item sitting in the live
+     * head that actually sorts past the tail edge of everything loaded belongs to the live tail (the
+     * unloaded region on that side), and vice versa. Leaving it claims the wrong end of the list —
+     * the archived channel would render above a page it sorts below.
+     *
+     * Compared against the outermost anchored interval, not the page just ingested: an item that
+     * lands between two loaded pages is not "beyond" either side, it is a gap item, and those stay
+     * where they are (`ingestPage` turns them into their own island once the merge reaches the edge).
+     */
+    protected moveMisfiledItemsToOppositeSide(logical: LogicalInterval, ingested: Interval): void;
+    /**
+     * Splits a logical interval by checking each item individually.
+     * Items overlapping anchoredInterval are merged into it.
+     * Others stay in a retained logical interval.
+     */
+    protected mergeItemsFromLogicalInterval(logical: LogicalInterval, anchored: Interval): {
+        mergedAnchored: Interval;
+        remainingLogical: LogicalInterval | null;
+    };
+    /**
+     * Merges all intervals (anchored + logical head/tail).
+     * Returns:
+     *   - merged anchored interval (or null if none merged)
+     *   - possibly reduced logical head / tail intervals
+     */
+    protected mergeIntervals(intervals: AnyInterval[], baseInterval?: Interval): MergeIntervalsResult;
+    /**
+     * Ingests the whole page into intervals and returns the resulting anchored interval.
+     */
+    ingestPage({ page, policy, isHead, isTail, targetIntervalId, setActive, }: {
+        page: T[];
+        /**
+         * Describes the policy for merging intervals.
+         * - 'auto' (default): Merge intervals if they overlap.
+         * - 'strict-overlap-only': Merge intervals only if they strictly overlap. Useful for jumping to a specific message.
+         *   - This is useful for jumping to a specific message.
+         */
+        policy?: IntervalMergePolicy;
+        isHead?: boolean;
+        isTail?: boolean;
+        targetIntervalId?: string;
+        setActive?: boolean;
+    }): Interval | null;
+    /**
+     * Ingests a single item on live update:
+     *  - update the ItemIndex
+     *  - find an anchored interval whose sort bounds contain the item
+     *  - insert the item into that interval using locate+plateau logic
+     *  - if this is the active interval, re-emit state.items from interval
+     */
+    ingestItem(ingestedItem: T): boolean;
+    protected removeItemAtCoordinates(coords: ItemCoordinates): ItemCoordinates;
+    /**
+     * Meaning of location values
+     * - currentIndex === -1 could not be found
+     * - insertionIndex === -1 insertion index was no intended to be determined
+     *
+     * If we are removing the last item from the currently active interval, we do not search for a new active interval.
+     * If the number of items approach 0 in an active interval, we expect from the UI to load new pages to populate
+     * the active interval.
+     */
+    removeItem({ id, item: inputItem }: {
+        id?: string;
+        item?: T;
+    }): ItemCoordinates;
+    /** Sets the items in the state, ingesting them so the active interval is updated. */
+    setItems({ valueOrFactory, cursor, isFirstPage, isLastPage, }: SetPaginatorItemsParams<T>): void;
+    setDebounceOptions: ({ debounceMs }: PaginatorDebounceOptions) => void;
+    protected shouldResetStateBeforeQuery(prevQueryShape: unknown | undefined, nextQueryShape: unknown | undefined): boolean;
+    protected canExecuteQuery: ({ direction, reset, }: {
+        direction?: PaginationDirection;
+    } & Pick<PaginationQueryParams<Q>, "reset">) => boolean;
+    isFirstPageQuery: (params: {
+        queryShape?: unknown;
+    } & Pick<PaginationQueryParams<Q>, "reset">) => boolean;
+    protected getStateBeforeFirstQuery(): PaginatorState<T>;
+    isJumpQueryShape(_queryShape: Q): boolean;
+    protected getStateAfterQuery(stateUpdate: Partial<PaginatorState<T>>, _isFirstPage: boolean): PaginatorState<T>;
+    preloadFirstPageFromOfflineDb: (_params: PaginationQueryParams<Q>) => Promise<T[] | undefined> | T[] | undefined;
+    populateOfflineDbAfterQuery: (_params: {
+        items: T[] | undefined;
+        queryShape: Q | undefined;
+    }) => Promise<T[] | undefined> | T[] | undefined;
+    protected runQueryRetryable(params?: PaginationQueryParams<Q>): Promise<PaginationQueryReturnValue<T> | null>;
+    /**
+     * Falsy return value means query was not successful.
+     *
+     * @param params - Query parameters.
+     * @param params.direction - Direction to paginate in (headward or tailward).
+     * @param params.keepPreviousItems - Keep already-loaded items instead of clearing them on a first-page query.
+     * @param params.queryShape - Explicit query shape overriding the one derived from current state.
+     * @param params.reset - Whether to reset the loaded state before querying.
+     * @param params.retryCount - Number of remaining retry attempts on failure.
+     * @param params.silent - Suppress loading/state updates for this query.
+     * @param params.updateState - Whether to write the query results back to state.
+     */
+    executeQuery({ direction, keepPreviousItems, queryShape: forcedQueryShape, reset, retryCount, silent, updateState, }?: PaginationQueryParams<Q>): Promise<ExecuteQueryReturnValue<T> | void>;
+    postQueryReconcile({ direction, isFirstPage, keepPreviousItems, queryShape, requestedPageSize, results, updateState, }: PostQueryReconcileParams<T, Q>): ExecuteQueryReturnValue<T>;
+    cancelScheduledQuery(): void;
+    resetState(): void;
+    /**
+     * Releases this paginator's hold on its item content. With a shared, refcounted item index this
+     * unlinks every member id from the backing store, so the store no longer strong-references this
+     * paginator through its subscriber registry — otherwise a discarded owner stays pinned, keeps
+     * receiving change notifications, and its items never garbage-collect. Call on teardown of the
+     * owner: a discard, not a reset (the owner is not reused; a re-appearing id gets a fresh instance;
+     * leftover interval/state caches die with the paginator when it is dropped). Also cancels any
+     * pending throttled window/view publish, so nothing emits after teardown.
+     */
+    dispose(): void;
+    toTail: (params?: Omit<PaginationQueryParams<Q>, "direction" | "queryShape">) => Promise<void | ExecuteQueryReturnValue<T>>;
+    toHead: (params?: Omit<PaginationQueryParams<Q>, "direction" | "queryShape">) => Promise<void | ExecuteQueryReturnValue<T>>;
+    /**
+     * @deprecated Use `toTail` instead.
+     */
+    next: (params?: Omit<PaginationQueryParams<Q>, "direction" | "queryShape">) => Promise<void | ExecuteQueryReturnValue<T>>;
+    /**
+     * @deprecated Use `toHead` instead.
+     */
+    prev: (params?: Omit<PaginationQueryParams<Q>, "direction" | "queryShape">) => Promise<void | ExecuteQueryReturnValue<T>>;
+    toTailDebounced: (params?: Omit<PaginationQueryParams<Q>, "direction" | "queryShape">) => void;
+    toHeadDebounced: (params?: Omit<PaginationQueryParams<Q>, "direction" | "queryShape">) => void;
+    /**
+     * @deprecated Use `toTailDebounced` instead.
+     */
+    nextDebounced: (params?: Omit<PaginationQueryParams<Q>, "direction" | "queryShape">) => void;
+    /**
+     * @deprecated Use `toHeadDebounced` instead.
+     */
+    prevDebounced: (params?: Omit<PaginationQueryParams<Q>, "direction" | "queryShape">) => void;
+    reload: () => Promise<void>;
+}
+export {};