@utiliread/primitives 1.0.0-143 → 1.0.0-144

package/src/cursor-navigation-state.ts

@@ -0,0 +1,168 @@
+interface CursorPage {
+    items: unknown[];
+    nextCursor: string | null;
+    hasMore: boolean;
+    totalCount?: number;
+}
+
+/**
+ * Tracks client-side navigation state for cursor-based paging.
+ *
+ * The first page is represented by the empty-string cursor.
+ * `futureCursor` is the server-provided cursor for the page after the current
+ * one, while `cursors` keeps the visited cursor chain so the UI can move
+ * backward without recomputing anything.
+ */
+export class CursorNavigationState {
+    /** Number of items requested per page. */
+    readonly limit: number;
+
+    /** Cursor for the currently displayed page. */
+    currentCursor: string = "";
+
+    /**
+     * Cursor for the next page as reported by the server.
+     *
+     * `undefined` means the current page has not been loaded yet.
+     * `null` means that all pages are exhausted.
+     */
+    futureCursor: string | null | undefined = undefined;
+
+    /** Visited page cursor chain in navigation order. */
+    private cursors: string[] = [];
+    private pageItemCounts = new Map<string, number>();
+
+    /** Total item count when the API provides it or when the last page is reached. */
+    totalCount: number | null = null;
+
+    /** One-based page number inferred from the visited cursor chain. */
+    get pageNumber() {
+        return this.cursors.indexOf(this.currentCursor) + 1;
+    }
+
+    /** Total number of pages computed from the total item count and page limit. */
+    get pageCount() {
+        return this.totalCount != null
+            ? Math.ceil(this.totalCount / this.limit)
+            : 0;
+    }
+
+    /** One-based index of the first item on the current page. */
+    get firstItemNumber() {
+        const index = this.cursors.indexOf(this.currentCursor);
+        const currentPageItemCount =
+            this.pageItemCounts.get(this.currentCursor) ?? 0;
+        return index >= 0 && currentPageItemCount > 0
+            ? this.cursors
+                  .slice(0, index)
+                  .reduce(
+                      (itemCount, cursor) =>
+                          itemCount + (this.pageItemCounts.get(cursor) ?? 0),
+                      0,
+                  ) + 1
+            : 0;
+    }
+
+    /** One-based index of the last item on the current page. */
+    get lastItemNumber() {
+        const currentPageItemCount =
+            this.pageItemCounts.get(this.currentCursor) ?? 0;
+        return currentPageItemCount > 0
+            ? this.firstItemNumber + currentPageItemCount - 1
+            : 0;
+    }
+
+    /**
+     * Cursor for the next page, or the current page cursor if the current page is the last page.
+     */
+    get nextCursor() {
+        const currentIndex = this.cursors.indexOf(this.currentCursor);
+        return currentIndex >= 0 && currentIndex < this.cursors.length - 1
+            ? this.cursors[currentIndex + 1]
+            : (this.futureCursor ?? this.currentCursor);
+    }
+
+    /** Cursor for the previous page, or the first-page sentinel. */
+    get previousCursor() {
+        const currentIndex = this.cursors.indexOf(this.currentCursor);
+        const previousCursor = this.cursors[currentIndex - 1] ?? "";
+        return previousCursor;
+    }
+
+    /** Whether the current page is the first page. */
+    get currentIsFirst() {
+        return this.currentCursor === "";
+    }
+
+    /** Whether the current page is the last page. */
+    get currentIsLast() {
+        return (
+            this.futureCursor === null &&
+            (this.cursors.length === 0 ||
+                this.cursors[this.cursors.length - 1] === this.currentCursor)
+        );
+    }
+
+    constructor(options?: { limit?: number }) {
+        this.limit = options?.limit ?? 20;
+    }
+
+    /**
+     * Applies a fetched page to the navigation state.
+     *
+     * `cursor` is the request cursor that produced `page`.
+     */
+    visitPage(cursor: string, page: CursorPage) {
+        // Determine if this page is the first in the navigation flow, and that it is the first time it it visited.
+        const isInitialFirstPage = this.cursors.length === 0 && cursor === "";
+        const isExpectedFuturePage =
+            this.cursors.length > 0 && cursor === this.futureCursor;
+
+        this.currentCursor = cursor;
+
+        // Add the visited cursor to the chain only if it's the first or expected future page.
+        if (isInitialFirstPage || isExpectedFuturePage) {
+            this.cursors.push(cursor);
+        }
+
+        // Set or update the item count for the visited page.
+        if (this.cursors.includes(cursor)) {
+            this.pageItemCounts.set(cursor, page.items.length);
+        }
+
+        // Set or advance the future cursor if monotonically advancing.
+        // Note that `futureCursor` is advanced even when `cursors.length === 0`.
+        // This allows us to "start" with some intermediate cursor if the first page is not the initial page;
+        // in that case we still track the `futureCursor` so that we can navigate forward - backward in this case is however not possible.
+        if (
+            this.futureCursor === undefined ||
+            isInitialFirstPage ||
+            cursor === this.futureCursor
+        ) {
+            this.futureCursor = page.nextCursor;
+        }
+
+        // Assign total count if provided
+        if (page.totalCount != null) {
+            this.totalCount = page.totalCount;
+        } else if (
+            (isInitialFirstPage || isExpectedFuturePage) &&
+            !page.hasMore
+        ) {
+            this.totalCount = this.cursors.reduce(
+                (itemCount, cursor) =>
+                    itemCount + (this.pageItemCounts.get(cursor) ?? 0),
+                0,
+            );
+        }
+    }
+
+    toString() {
+        const hasItemNumbers = this.cursors.indexOf(this.currentCursor) >= 0;
+        const range = hasItemNumbers
+            ? `${this.firstItemNumber}-${this.lastItemNumber}`
+            : "...";
+        const total = this.totalCount ?? "?";
+        return `${range} / ${total}`;
+    }
+}

package/src/index.ts

@@ -40,6 +40,7 @@ export { RegisterLibrary } from "./register-library";
 export { Repository } from "./repository";
 export { TimeOrRule } from "./time-or-rule";
 export type { UnitId } from "./unit-id";
+export { CursorNavigationState } from "./cursor-navigation-state";
 
 export const registers: Record<RegisterId, RegisterDefinition> = Registers;