@stackframe/stack-shared 2.8.56 → 2.8.59

package/dist/utils/paginated-lists.d.mts

@@ -27,7 +27,8 @@ type ImplQueryOptions<Type extends 'next' | 'prev', Cursor, Filter, OrderBy> = Q
 type QueryResult<Item, Cursor> = {
     items: {
         item: Item;
-        itemCursor: Cursor;
+        prevCursor: Cursor;
+        nextCursor: Cursor;
     }[];
     isFirst: boolean;
     isLast: boolean;
@@ -36,30 +37,99 @@ type QueryResult<Item, Cursor> = {
 type ImplQueryResult<Item, Cursor> = {
     items: {
         item: Item;
-        itemCursor: Cursor;
+        prevCursor: Cursor;
+        nextCursor: Cursor;
     }[];
     isFirst: boolean;
     isLast: boolean;
     cursor: Cursor;
 };
+/**
+ * Abstract base class for cursor-based pagination over any ordered data source.
+ *
+ * Subclasses implement `_nextOrPrev` to fetch items in one direction. This class handles
+ * limit enforcement, sorting validation, and provides `map`, `filter`, `flatMap`, and `merge` utilities.
+ *
+ * @template Item - The type of items in the list
+ * @template Cursor - A string-based cursor type for position tracking. Cursors are always between two items in the list. Note that cursors may not be stable if the filter or orderBy changes.
+ * @template Filter - Query filter type
+ * @template OrderBy - Sort order specification type
+ *
+ * @example
+ * ```ts
+ * // Basic usage: paginate through users
+ * const users = new MyUserList();
+ * const first10 = await users.next({ after: users.getFirstCursor(), limit: 10, filter: {}, orderBy: 'name', limitPrecision: 'exact' });
+ * // first10 = { items: [...], isFirst: true, isLast: false, cursor: "cursor-after-item-10" }
+ *
+ * const next10 = await users.next({ after: first10.cursor, limit: 10, filter: {}, orderBy: 'name', limitPrecision: 'exact' });
+ * // Continues from where we left off
+ * ```
+ */
 declare abstract class PaginatedList<Item, Cursor extends string, Filter extends unknown, OrderBy extends unknown> {
     protected abstract _getFirstCursor(): Cursor;
     protected abstract _getLastCursor(): Cursor;
     protected abstract _compare(orderBy: OrderBy, a: Item, b: Item): number;
     protected abstract _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', Cursor, Filter, OrderBy>): Promise<ImplQueryResult<Item, Cursor>>;
+    /** Returns the cursor pointing to the start of the list (before any items). */
     getFirstCursor(): Cursor;
+    /** Returns the cursor pointing to the end of the list (after all items). */
     getLastCursor(): Cursor;
+    /** Compares two items according to the given orderBy. Returns negative if a < b, 0 if equal, positive if a > b. */
     compare(orderBy: OrderBy, a: Item, b: Item): number;
+    /**
+     * Fetches items moving forward ('next') or backward ('prev') from the given cursor.
+     *
+     * Respects `limitPrecision`: 'exact' guarantees the exact limit, 'at-least'/'at-most'/'approximate'
+     * allow flexibility for performance. Returns items, boundary flags, and a new cursor.
+     *
+     * @example
+     * ```ts
+     * // Get 5 items after the start
+     * const result = await list.nextOrPrev('next', { cursor: list.getFirstCursor(), limit: 5, filter: {}, orderBy: 'asc', limitPrecision: 'exact' });
+     * // result.items.length === 5 (or less if list has fewer items)
+     * // result.isFirst === true (started at first cursor)
+     * // result.isLast === true if we got all remaining items
+     *
+     * // Continue from where we left off
+     * const more = await list.nextOrPrev('next', { cursor: result.cursor, limit: 5, ... });
+     * ```
+     */
     nextOrPrev(type: 'next' | 'prev', options: QueryOptions<'next' | 'prev', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    /** Fetches items after the given cursor (forward pagination). */
     next({ after, ...rest }: QueryOptions<'next', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    /** Fetches items before the given cursor (backward pagination). */
     prev({ before, ...rest }: QueryOptions<'prev', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    /**
+     * Transforms this list by mapping each item to zero or more new items.
+     *
+     * Note that the sort order must be preserved after the operation; the flat-mapped list will not be sorted automatically.
+     *
+     * @param itemMapper - Maps each item (with its cursor) to an array of new items
+     * @param compare - Comparison function for the new item type
+     * @param newCursorFromOldCursor/oldCursorFromNewCursor - Cursor conversion functions
+     * @param estimateItemsToFetch - Estimates how many source items to fetch for a given limit
+     *
+     * @example
+     * ```ts
+     * // Expand orders into line items (1 order -> N line items)
+     * const lineItems = ordersList.flatMap({
+     *   itemMapper: ({ item: order }) => order.lineItems.map((li, i) => ({ item: li, prevCursor: `${order.id}-${i}`, nextCursor: `${order.id}-${i + 1}` })),
+     *   compare: (_, a, b) => a.createdAt - b.createdAt,
+     *   estimateItemsToFetch: ({ limit }) => Math.ceil(limit / 3), // avg 3 items per order
+     *   // ... cursor converters
+     * });
+     * ```
+     */
     flatMap<Item2, Cursor2 extends string, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
         itemMapper: (itemEntry: {
             item: Item;
-            itemCursor: Cursor;
+            prevCursor: Cursor;
+            nextCursor: Cursor;
         }, filter: Filter2, orderBy: OrderBy2) => {
             item: Item2;
-            itemCursor: Cursor2;
+            prevCursor: Cursor2;
+            nextCursor: Cursor2;
         }[];
         compare: (orderBy: OrderBy2, a: Item2, b: Item2) => number;
         newCursorFromOldCursor: (cursor: Cursor) => Cursor2;
@@ -72,12 +142,45 @@ declare abstract class PaginatedList<Item, Cursor extends string, Filter extends
             limit: number;
         }) => number;
     }): PaginatedList<Item2, Cursor2, Filter2, OrderBy2>;
+    /**
+     * Transforms each item in the list. Requires a reverse mapper for comparison delegation.
+     *
+     * @param itemMapper - Transforms each item
+     * @param oldItemFromNewItem - Reverse-maps new items back to old items (for comparison)
+     *
+     * @example
+     * ```ts
+     * // Convert User objects to UserDTO
+     * const userDtos = usersList.map({
+     *   itemMapper: (user) => ({ id: user.id, displayName: user.name }),
+     *   oldItemFromNewItem: (dto) => fullUsers.get(dto.id)!, // for comparison
+     *   oldFilterFromNewFilter: (f) => f,
+     *   oldOrderByFromNewOrderBy: (o) => o,
+     * });
+     * ```
+     */
     map<Item2, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
         itemMapper: (item: Item) => Item2;
         oldItemFromNewItem: (item: Item2) => Item;
         oldFilterFromNewFilter: (filter: Filter2) => Filter;
         oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => OrderBy;
     }): PaginatedList<Item2, Cursor, Filter2, OrderBy2>;
+    /**
+     * Filters items in the list. Requires an estimate function since filtering may reduce output.
+     *
+     * @param filter - Predicate to include/exclude items
+     * @param estimateItemsToFetch - Estimates how many source items to fetch (accounts for filter selectivity)
+     *
+     * @example
+     * ```ts
+     * // Filter to only active users
+     * const activeUsers = usersList.filter({
+     *   filter: (user, filterOpts) => user.isActive && user.role === filterOpts.role,
+     *   oldFilterFromNewFilter: (f) => ({}), // original list has no filter
+     *   estimateItemsToFetch: ({ limit }) => limit * 2, // expect ~50% active
+     * });
+     * ```
+     */
     filter<Filter2 extends unknown>(options: {
         filter: (item: Item, filter: Filter2) => boolean;
         oldFilterFromNewFilter: (filter: Filter2) => Filter;
@@ -87,6 +190,20 @@ declare abstract class PaginatedList<Item, Cursor extends string, Filter extends
             limit: number;
         }) => number;
     }): PaginatedList<Item, Cursor, Filter2, OrderBy>;
+    /**
+     * Adds an additional filter constraint while preserving the original filter type.
+     * Shorthand for `filter()` that intersects Filter with AddedFilter.
+     *
+     * @example
+     * ```ts
+     * // Add a "verified" filter on top of existing filters
+     * const verifiedUsers = usersList.addFilter({
+     *   filter: (user, f) => user.emailVerified,
+     *   estimateItemsToFetch: ({ limit }) => limit * 2, // ~50% are verified
+     * });
+     * // verifiedUsers filter type is Filter
+     * ```
+     */
     addFilter<AddedFilter extends unknown>(options: {
         filter: (item: Item, filter: Filter & AddedFilter) => boolean;
         estimateItemsToFetch: (options: {
@@ -95,7 +212,31 @@ declare abstract class PaginatedList<Item, Cursor extends string, Filter extends
             limit: number;
         }) => number;
     }): PaginatedList<Item, Cursor, Filter & AddedFilter, OrderBy>;
+    /**
+     * Merges multiple paginated lists into one, interleaving items by sort order.
+     * All lists must use the same compare function.
+     *
+     * The merged cursor is a JSON-encoded array of individual list cursors.
+     *
+     * @example
+     * ```ts
+     * // Merge users from multiple sources into a unified feed
+     * const allUsers = PaginatedList.merge(internalUsers, externalUsers, partnerUsers);
+     * const page = await allUsers.next({ after: allUsers.getFirstCursor(), limit: 20, ... });
+     * // page.items contains interleaved items from all sources, sorted by orderBy
+     * ```
+     */
     static merge<Item, Filter extends unknown, OrderBy extends unknown>(...lists: PaginatedList<Item, any, Filter, OrderBy>[]): PaginatedList<Item, string, Filter, OrderBy>;
+    /**
+     * Returns an empty paginated list that always returns no items.
+     *
+     * @example
+     * ```ts
+     * const empty = PaginatedList.empty();
+     * const result = await empty.next({ after: empty.getFirstCursor(), limit: 10, ... });
+     * // result = { items: [], isFirst: true, isLast: true, cursor: "first" }
+     * ```
+     */
     static empty(): {
         _getFirstCursor(): "first";
         _getLastCursor(): "last";
@@ -106,19 +247,65 @@ declare abstract class PaginatedList<Item, Cursor extends string, Filter extends
             isLast: boolean;
             cursor: "first";
         }>;
+        /** Returns the cursor pointing to the start of the list (before any items). */
         getFirstCursor(): "first" | "last";
+        /** Returns the cursor pointing to the end of the list (after all items). */
         getLastCursor(): "first" | "last";
+        /** Compares two items according to the given orderBy. Returns negative if a < b, 0 if equal, positive if a > b. */
         compare(orderBy: any, a: never, b: never): number;
+        /**
+         * Fetches items moving forward ('next') or backward ('prev') from the given cursor.
+         *
+         * Respects `limitPrecision`: 'exact' guarantees the exact limit, 'at-least'/'at-most'/'approximate'
+         * allow flexibility for performance. Returns items, boundary flags, and a new cursor.
+         *
+         * @example
+         * ```ts
+         * // Get 5 items after the start
+         * const result = await list.nextOrPrev('next', { cursor: list.getFirstCursor(), limit: 5, filter: {}, orderBy: 'asc', limitPrecision: 'exact' });
+         * // result.items.length === 5 (or less if list has fewer items)
+         * // result.isFirst === true (started at first cursor)
+         * // result.isLast === true if we got all remaining items
+         *
+         * // Continue from where we left off
+         * const more = await list.nextOrPrev('next', { cursor: result.cursor, limit: 5, ... });
+         * ```
+         */
         nextOrPrev(type: "next" | "prev", options: QueryOptions<"next" | "prev", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        /** Fetches items after the given cursor (forward pagination). */
         next({ after, ...rest }: QueryOptions<"next", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        /** Fetches items before the given cursor (backward pagination). */
         prev({ before, ...rest }: QueryOptions<"prev", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        /**
+         * Transforms this list by mapping each item to zero or more new items.
+         *
+         * Note that the sort order must be preserved after the operation; the flat-mapped list will not be sorted automatically.
+         *
+         * @param itemMapper - Maps each item (with its cursor) to an array of new items
+         * @param compare - Comparison function for the new item type
+         * @param newCursorFromOldCursor/oldCursorFromNewCursor - Cursor conversion functions
+         * @param estimateItemsToFetch - Estimates how many source items to fetch for a given limit
+         *
+         * @example
+         * ```ts
+         * // Expand orders into line items (1 order -> N line items)
+         * const lineItems = ordersList.flatMap({
+         *   itemMapper: ({ item: order }) => order.lineItems.map((li, i) => ({ item: li, prevCursor: `${order.id}-${i}`, nextCursor: `${order.id}-${i + 1}` })),
+         *   compare: (_, a, b) => a.createdAt - b.createdAt,
+         *   estimateItemsToFetch: ({ limit }) => Math.ceil(limit / 3), // avg 3 items per order
+         *   // ... cursor converters
+         * });
+         * ```
+         */
         flatMap<Item2, Cursor2 extends string, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
             itemMapper: (itemEntry: {
                 item: never;
-                itemCursor: "first" | "last";
+                prevCursor: "first" | "last";
+                nextCursor: "first" | "last";
             }, filter: Filter2, orderBy: OrderBy2) => {
                 item: Item2;
-                itemCursor: Cursor2;
+                prevCursor: Cursor2;
+                nextCursor: Cursor2;
             }[];
             compare: (orderBy: OrderBy2, a: Item2, b: Item2) => number;
             newCursorFromOldCursor: (cursor: "first" | "last") => Cursor2;
@@ -131,12 +318,45 @@ declare abstract class PaginatedList<Item, Cursor extends string, Filter extends
                 limit: number;
             }) => number;
         }): PaginatedList<Item2, Cursor2, Filter2, OrderBy2>;
+        /**
+         * Transforms each item in the list. Requires a reverse mapper for comparison delegation.
+         *
+         * @param itemMapper - Transforms each item
+         * @param oldItemFromNewItem - Reverse-maps new items back to old items (for comparison)
+         *
+         * @example
+         * ```ts
+         * // Convert User objects to UserDTO
+         * const userDtos = usersList.map({
+         *   itemMapper: (user) => ({ id: user.id, displayName: user.name }),
+         *   oldItemFromNewItem: (dto) => fullUsers.get(dto.id)!, // for comparison
+         *   oldFilterFromNewFilter: (f) => f,
+         *   oldOrderByFromNewOrderBy: (o) => o,
+         * });
+         * ```
+         */
         map<Item2_1, Filter2_1 extends unknown, OrderBy2_1 extends unknown>(options: {
             itemMapper: (item: never) => Item2_1;
             oldItemFromNewItem: (item: Item2_1) => never;
             oldFilterFromNewFilter: (filter: Filter2_1) => any;
             oldOrderByFromNewOrderBy: (orderBy: OrderBy2_1) => any;
         }): PaginatedList<Item2_1, "first" | "last", Filter2_1, OrderBy2_1>;
+        /**
+         * Filters items in the list. Requires an estimate function since filtering may reduce output.
+         *
+         * @param filter - Predicate to include/exclude items
+         * @param estimateItemsToFetch - Estimates how many source items to fetch (accounts for filter selectivity)
+         *
+         * @example
+         * ```ts
+         * // Filter to only active users
+         * const activeUsers = usersList.filter({
+         *   filter: (user, filterOpts) => user.isActive && user.role === filterOpts.role,
+         *   oldFilterFromNewFilter: (f) => ({}), // original list has no filter
+         *   estimateItemsToFetch: ({ limit }) => limit * 2, // expect ~50% active
+         * });
+         * ```
+         */
         filter<Filter2_2 extends unknown>(options: {
             filter: (item: never, filter: Filter2_2) => boolean;
             oldFilterFromNewFilter: (filter: Filter2_2) => any;
@@ -146,6 +366,20 @@ declare abstract class PaginatedList<Item, Cursor extends string, Filter extends
                 limit: number;
             }) => number;
         }): PaginatedList<never, "first" | "last", Filter2_2, any>;
+        /**
+         * Adds an additional filter constraint while preserving the original filter type.
+         * Shorthand for `filter()` that intersects Filter with AddedFilter.
+         *
+         * @example
+         * ```ts
+         * // Add a "verified" filter on top of existing filters
+         * const verifiedUsers = usersList.addFilter({
+         *   filter: (user, f) => user.emailVerified,
+         *   estimateItemsToFetch: ({ limit }) => limit * 2, // ~50% are verified
+         * });
+         * // verifiedUsers filter type is Filter
+         * ```
+         */
         addFilter<AddedFilter extends unknown>(options: {
             filter: (item: never, filter: any) => boolean;
             estimateItemsToFetch: (options: {
@@ -156,20 +390,43 @@ declare abstract class PaginatedList<Item, Cursor extends string, Filter extends
         }): PaginatedList<never, "first" | "last", any, any>;
     };
 }
-declare class ArrayPaginatedList<Item> extends PaginatedList<Item, `${number}`, (item: Item) => boolean, (a: Item, b: Item) => number> {
+/**
+ * A simple in-memory paginated list backed by an array.
+ *
+ * Filter is a predicate function, OrderBy is a comparator function.
+ * Cursors are in the format "before-{index}" representing the position before that index.
+ *
+ * Note: This implementation re-filters and re-sorts the entire array on each query,
+ * so it's only suitable for small datasets.
+ *
+ * @example
+ * ```ts
+ * const numbers = new ArrayPaginatedList([5, 2, 8, 1, 9, 3]);
+ * const page = await numbers.next({
+ *   after: "before-0",
+ *   limit: 3,
+ *   filter: (n) => n > 2,
+ *   orderBy: (a, b) => a - b,
+ *   limitPrecision: 'exact',
+ * });
+ * // page.items = [{ item: 3, prevCursor: "before-0", nextCursor: "before-1" }, { item: 5, prevCursor: "before-1", nextCursor: "before-2" }, ...]
+ * ```
+ */
+declare class ArrayPaginatedList<Item> extends PaginatedList<Item, `before-${number}`, (item: Item) => boolean, (a: Item, b: Item) => number> {
     private readonly array;
     constructor(array: Item[]);
-    _getFirstCursor(): "0";
-    _getLastCursor(): `${number}`;
+    _getFirstCursor(): "before-0";
+    _getLastCursor(): `before-${number}`;
     _compare(orderBy: (a: Item, b: Item) => number, a: Item, b: Item): number;
-    _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', `${number}`, (item: Item) => boolean, (a: Item, b: Item) => number>): Promise<{
+    _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', `before-${number}`, (item: Item) => boolean, (a: Item, b: Item) => number>): Promise<{
         items: {
             item: Item;
-            itemCursor: `${number}`;
+            prevCursor: `before-${number}`;
+            nextCursor: `before-${number}`;
         }[];
         isFirst: boolean;
         isLast: boolean;
-        cursor: `${number}`;
+        cursor: `before-${number}`;
     }>;
 }