@stackframe/stack-shared 2.8.36 → 2.8.40

package/dist/utils/numbers.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/numbers.tsx"],"sourcesContent":["const magnitudes = [\n  [1_000_000_000_000_000, \"trln\"],\n  [1_000_000_000_000, \"bln\"],\n  [1_000_000_000, \"bn\"],\n  [1_000_000, \"M\"],\n  [1_000, \"k\"],\n] as const;\n\nexport function prettyPrintWithMagnitudes(num: number): string {\n  if (typeof num !== \"number\") throw new Error(\"Expected a number\");\n  if (Number.isNaN(num)) return \"NaN\";\n  if (num < 0) return \"-\" + prettyPrintWithMagnitudes(-num);\n  if (!Number.isFinite(num)) return \"∞\";\n\n  for (const [magnitude, suffix] of magnitudes) {\n    if (num >= magnitude) {\n      return toFixedMax(num / magnitude, 1) + suffix;\n    }\n  }\n  return toFixedMax(num, 1); // Handle numbers less than 1,000 without suffix.\n}\nundefined?.test(\"prettyPrintWithMagnitudes\", ({ expect }) => {\n  // Test different magnitudes\n  expect(prettyPrintWithMagnitudes(999)).toBe(\"999\");\n  expect(prettyPrintWithMagnitudes(1000)).toBe(\"1k\");\n  expect(prettyPrintWithMagnitudes(1500)).toBe(\"1.5k\");\n  expect(prettyPrintWithMagnitudes(1000000)).toBe(\"1M\");\n  expect(prettyPrintWithMagnitudes(1500000)).toBe(\"1.5M\");\n  expect(prettyPrintWithMagnitudes(1000000000)).toBe(\"1bn\");\n  expect(prettyPrintWithMagnitudes(1500000000)).toBe(\"1.5bn\");\n  expect(prettyPrintWithMagnitudes(1000000000000)).toBe(\"1bln\");\n  expect(prettyPrintWithMagnitudes(1500000000000)).toBe(\"1.5bln\");\n  expect(prettyPrintWithMagnitudes(1000000000000000)).toBe(\"1trln\");\n  expect(prettyPrintWithMagnitudes(1500000000000000)).toBe(\"1.5trln\");\n  // Test small numbers\n  expect(prettyPrintWithMagnitudes(100)).toBe(\"100\");\n  expect(prettyPrintWithMagnitudes(0)).toBe(\"0\");\n  expect(prettyPrintWithMagnitudes(0.5)).toBe(\"0.5\");\n  // Test negative numbers\n  expect(prettyPrintWithMagnitudes(-1000)).toBe(\"-1k\");\n  expect(prettyPrintWithMagnitudes(-1500000)).toBe(\"-1.5M\");\n  // Test special cases\n  expect(prettyPrintWithMagnitudes(NaN)).toBe(\"NaN\");\n  expect(prettyPrintWithMagnitudes(Infinity)).toBe(\"∞\");\n  expect(prettyPrintWithMagnitudes(-Infinity)).toBe(\"-∞\");\n});\n\nexport function toFixedMax(num: number, maxDecimals: number): string {\n  return num.toFixed(maxDecimals).replace(/\\.?0+$/, \"\");\n}\nundefined?.test(\"toFixedMax\", ({ expect }) => {\n  expect(toFixedMax(1, 2)).toBe(\"1\");\n  expect(toFixedMax(1.2, 2)).toBe(\"1.2\");\n  expect(toFixedMax(1.23, 2)).toBe(\"1.23\");\n  expect(toFixedMax(1.234, 2)).toBe(\"1.23\");\n  expect(toFixedMax(1.0, 2)).toBe(\"1\");\n  expect(toFixedMax(1.20, 2)).toBe(\"1.2\");\n  expect(toFixedMax(0, 2)).toBe(\"0\");\n});\n\nexport function numberCompare(a: number, b: number): number {\n  return Math.sign(a - b);\n}\nundefined?.test(\"numberCompare\", ({ expect }) => {\n  expect(numberCompare(1, 2)).toBe(-1);\n  expect(numberCompare(2, 1)).toBe(1);\n  expect(numberCompare(1, 1)).toBe(0);\n  expect(numberCompare(0, 0)).toBe(0);\n  expect(numberCompare(-1, -2)).toBe(1);\n  expect(numberCompare(-2, -1)).toBe(-1);\n  expect(numberCompare(-1, 1)).toBe(-1);\n  expect(numberCompare(1, -1)).toBe(1);\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAM,aAAa;AAAA,EACjB,CAAC,MAAuB,MAAM;AAAA,EAC9B,CAAC,MAAmB,KAAK;AAAA,EACzB,CAAC,KAAe,IAAI;AAAA,EACpB,CAAC,KAAW,GAAG;AAAA,EACf,CAAC,KAAO,GAAG;AACb;AAEO,SAAS,0BAA0B,KAAqB;AAC7D,MAAI,OAAO,QAAQ,SAAU,OAAM,IAAI,MAAM,mBAAmB;AAChE,MAAI,OAAO,MAAM,GAAG,EAAG,QAAO;AAC9B,MAAI,MAAM,EAAG,QAAO,MAAM,0BAA0B,CAAC,GAAG;AACxD,MAAI,CAAC,OAAO,SAAS,GAAG,EAAG,QAAO;AAElC,aAAW,CAAC,WAAW,MAAM,KAAK,YAAY;AAC5C,QAAI,OAAO,WAAW;AACpB,aAAO,WAAW,MAAM,WAAW,CAAC,IAAI;AAAA,IAC1C;AAAA,EACF;AACA,SAAO,WAAW,KAAK,CAAC;AAC1B;AA2BO,SAAS,WAAW,KAAa,aAA6B;AACnE,SAAO,IAAI,QAAQ,WAAW,EAAE,QAAQ,UAAU,EAAE;AACtD;AAWO,SAAS,cAAc,GAAW,GAAmB;AAC1D,SAAO,KAAK,KAAK,IAAI,CAAC;AACxB;","names":[]}
+{"version":3,"sources":["../../src/utils/numbers.tsx"],"sourcesContent":["const magnitudes = [\n  [1_000, \"k\"],\n  [1_000, \"M\"],\n  [1_000, \"bn\"],\n  [1_000, \"bln\"],\n  [1_000, \"trln\"],\n] as const;\n\nexport function prettyPrintWithMagnitudes(num: number): string {\n  if (typeof num !== \"number\") throw new Error(\"Expected a number\");\n  if (Number.isNaN(num)) return \"NaN\";\n  if (num < 0) return \"-\" + prettyPrintWithMagnitudes(-num);\n  if (!Number.isFinite(num)) return \"∞\";\n\n  let current = toFixedMax(num, 1);\n  let lastSuffix = \"\";\n  for (const [difference, suffix] of magnitudes) {\n    if (+current >= difference) {\n      current = toFixedMax(+current / difference, 1);\n      lastSuffix = suffix;\n    } else {\n      break;\n    }\n  }\n  return current + lastSuffix;\n}\nundefined?.test(\"prettyPrintWithMagnitudes\", ({ expect }) => {\n  // Test different magnitudes\n  expect(prettyPrintWithMagnitudes(999)).toBe(\"999\");\n  expect(prettyPrintWithMagnitudes(1000)).toBe(\"1k\");\n  expect(prettyPrintWithMagnitudes(1500)).toBe(\"1.5k\");\n  expect(prettyPrintWithMagnitudes(999499)).toBe(\"999.5k\");\n  expect(prettyPrintWithMagnitudes(999500)).toBe(\"999.5k\");\n  expect(prettyPrintWithMagnitudes(999949)).toBe(\"999.9k\");\n  expect(prettyPrintWithMagnitudes(999950)).toBe(\"1M\");\n  expect(prettyPrintWithMagnitudes(1000000)).toBe(\"1M\");\n  expect(prettyPrintWithMagnitudes(1500000)).toBe(\"1.5M\");\n  expect(prettyPrintWithMagnitudes(1000000000)).toBe(\"1bn\");\n  expect(prettyPrintWithMagnitudes(1500000000)).toBe(\"1.5bn\");\n  expect(prettyPrintWithMagnitudes(1000000000000)).toBe(\"1bln\");\n  expect(prettyPrintWithMagnitudes(1500000000000)).toBe(\"1.5bln\");\n  expect(prettyPrintWithMagnitudes(1000000000000000)).toBe(\"1trln\");\n  expect(prettyPrintWithMagnitudes(1500000000000000)).toBe(\"1.5trln\");\n  // Test small numbers\n  expect(prettyPrintWithMagnitudes(100)).toBe(\"100\");\n  expect(prettyPrintWithMagnitudes(0)).toBe(\"0\");\n  expect(prettyPrintWithMagnitudes(0.5)).toBe(\"0.5\");\n  // Test negative numbers\n  expect(prettyPrintWithMagnitudes(-1000)).toBe(\"-1k\");\n  expect(prettyPrintWithMagnitudes(-1500000)).toBe(\"-1.5M\");\n  // Test special cases\n  expect(prettyPrintWithMagnitudes(NaN)).toBe(\"NaN\");\n  expect(prettyPrintWithMagnitudes(Infinity)).toBe(\"∞\");\n  expect(prettyPrintWithMagnitudes(-Infinity)).toBe(\"-∞\");\n});\n\nexport function toFixedMax(num: number, maxDecimals: number): string {\n  return num.toFixed(maxDecimals).replace(/\\.?0+$/, \"\");\n}\nundefined?.test(\"toFixedMax\", ({ expect }) => {\n  expect(toFixedMax(1, 2)).toBe(\"1\");\n  expect(toFixedMax(1.2, 2)).toBe(\"1.2\");\n  expect(toFixedMax(1.23, 2)).toBe(\"1.23\");\n  expect(toFixedMax(1.234, 2)).toBe(\"1.23\");\n  expect(toFixedMax(1.0, 2)).toBe(\"1\");\n  expect(toFixedMax(1.20, 2)).toBe(\"1.2\");\n  expect(toFixedMax(0, 2)).toBe(\"0\");\n});\n\nexport function numberCompare(a: number, b: number): number {\n  return Math.sign(a - b);\n}\nundefined?.test(\"numberCompare\", ({ expect }) => {\n  expect(numberCompare(1, 2)).toBe(-1);\n  expect(numberCompare(2, 1)).toBe(1);\n  expect(numberCompare(1, 1)).toBe(0);\n  expect(numberCompare(0, 0)).toBe(0);\n  expect(numberCompare(-1, -2)).toBe(1);\n  expect(numberCompare(-2, -1)).toBe(-1);\n  expect(numberCompare(-1, 1)).toBe(-1);\n  expect(numberCompare(1, -1)).toBe(1);\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAM,aAAa;AAAA,EACjB,CAAC,KAAO,GAAG;AAAA,EACX,CAAC,KAAO,GAAG;AAAA,EACX,CAAC,KAAO,IAAI;AAAA,EACZ,CAAC,KAAO,KAAK;AAAA,EACb,CAAC,KAAO,MAAM;AAChB;AAEO,SAAS,0BAA0B,KAAqB;AAC7D,MAAI,OAAO,QAAQ,SAAU,OAAM,IAAI,MAAM,mBAAmB;AAChE,MAAI,OAAO,MAAM,GAAG,EAAG,QAAO;AAC9B,MAAI,MAAM,EAAG,QAAO,MAAM,0BAA0B,CAAC,GAAG;AACxD,MAAI,CAAC,OAAO,SAAS,GAAG,EAAG,QAAO;AAElC,MAAI,UAAU,WAAW,KAAK,CAAC;AAC/B,MAAI,aAAa;AACjB,aAAW,CAAC,YAAY,MAAM,KAAK,YAAY;AAC7C,QAAI,CAAC,WAAW,YAAY;AAC1B,gBAAU,WAAW,CAAC,UAAU,YAAY,CAAC;AAC7C,mBAAa;AAAA,IACf,OAAO;AACL;AAAA,IACF;AAAA,EACF;AACA,SAAO,UAAU;AACnB;AA+BO,SAAS,WAAW,KAAa,aAA6B;AACnE,SAAO,IAAI,QAAQ,WAAW,EAAE,QAAQ,UAAU,EAAE;AACtD;AAWO,SAAS,cAAc,GAAW,GAAmB;AAC1D,SAAO,KAAK,KAAK,IAAI,CAAC;AACxB;","names":[]}

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

@@ -0,0 +1,176 @@
+type QueryOptions<Type extends 'next' | 'prev', Cursor, Filter, OrderBy> = {
+    filter: Filter;
+    orderBy: OrderBy;
+    limit: number;
+    /**
+     * Whether the limit should be treated as an exact value, or an approximate value.
+     *
+     * If set to 'exact', less items will only be returned if the list item is the first or last item.
+     *
+     * If set to 'at-least' or 'approximate', the implementation may decide to return more items than the limit requested if doing so comes at no (or negligible) extra cost.
+     *
+     * If set to 'at-most' or 'approximate', the implementation may decide to return less items than the limit requested if requesting more items would come at a non-negligible extra cost. In this case, if limit > 0, the implementation must still make progress towards the end of the list and the returned cursor must be different from the one passed in.
+     *
+     * Defaults to 'exact'.
+     */
+    limitPrecision: 'exact' | 'at-least' | 'at-most' | 'approximate';
+} & ([Type] extends [never] ? unknown : [Type] extends ['next'] ? {
+    after: Cursor;
+} : [Type] extends ['prev'] ? {
+    before: Cursor;
+} : {
+    cursor: Cursor;
+});
+type ImplQueryOptions<Type extends 'next' | 'prev', Cursor, Filter, OrderBy> = QueryOptions<Type, Cursor, Filter, OrderBy> & {
+    limitPrecision: 'approximate';
+};
+type QueryResult<Item, Cursor> = {
+    items: {
+        item: Item;
+        itemCursor: Cursor;
+    }[];
+    isFirst: boolean;
+    isLast: boolean;
+    cursor: Cursor;
+};
+type ImplQueryResult<Item, Cursor> = {
+    items: {
+        item: Item;
+        itemCursor: Cursor;
+    }[];
+    isFirst: boolean;
+    isLast: boolean;
+    cursor: Cursor;
+};
+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>>;
+    getFirstCursor(): Cursor;
+    getLastCursor(): Cursor;
+    compare(orderBy: OrderBy, a: Item, b: Item): number;
+    nextOrPrev(type: 'next' | 'prev', options: QueryOptions<'next' | 'prev', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    next({ after, ...rest }: QueryOptions<'next', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    prev({ before, ...rest }: QueryOptions<'prev', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    flatMap<Item2, Cursor2 extends string, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
+        itemMapper: (itemEntry: {
+            item: Item;
+            itemCursor: Cursor;
+        }, filter: Filter2, orderBy: OrderBy2) => {
+            item: Item2;
+            itemCursor: Cursor2;
+        }[];
+        compare: (orderBy: OrderBy2, a: Item2, b: Item2) => number;
+        newCursorFromOldCursor: (cursor: Cursor) => Cursor2;
+        oldCursorFromNewCursor: (cursor: Cursor2) => Cursor;
+        oldFilterFromNewFilter: (filter: Filter2) => Filter;
+        oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => OrderBy;
+        estimateItemsToFetch: (options: {
+            filter: Filter2;
+            orderBy: OrderBy2;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item2, Cursor2, Filter2, OrderBy2>;
+    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>;
+    filter<Filter2 extends unknown>(options: {
+        filter: (item: Item, filter: Filter2) => boolean;
+        oldFilterFromNewFilter: (filter: Filter2) => Filter;
+        estimateItemsToFetch: (options: {
+            filter: Filter2;
+            orderBy: OrderBy;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item, Cursor, Filter2, OrderBy>;
+    addFilter<AddedFilter extends unknown>(options: {
+        filter: (item: Item, filter: Filter & AddedFilter) => boolean;
+        estimateItemsToFetch: (options: {
+            filter: Filter & AddedFilter;
+            orderBy: OrderBy;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item, Cursor, Filter & AddedFilter, OrderBy>;
+    static merge<Item, Filter extends unknown, OrderBy extends unknown>(...lists: PaginatedList<Item, any, Filter, OrderBy>[]): PaginatedList<Item, string, Filter, OrderBy>;
+    static empty(): {
+        _getFirstCursor(): "first";
+        _getLastCursor(): "last";
+        _compare(orderBy: any, a: any, b: any): number;
+        _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', string, any, any>): Promise<{
+            items: never[];
+            isFirst: boolean;
+            isLast: boolean;
+            cursor: "first";
+        }>;
+        getFirstCursor(): "first" | "last";
+        getLastCursor(): "first" | "last";
+        compare(orderBy: any, a: never, b: never): number;
+        nextOrPrev(type: "next" | "prev", options: QueryOptions<"next" | "prev", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        next({ after, ...rest }: QueryOptions<"next", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        prev({ before, ...rest }: QueryOptions<"prev", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        flatMap<Item2, Cursor2 extends string, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
+            itemMapper: (itemEntry: {
+                item: never;
+                itemCursor: "first" | "last";
+            }, filter: Filter2, orderBy: OrderBy2) => {
+                item: Item2;
+                itemCursor: Cursor2;
+            }[];
+            compare: (orderBy: OrderBy2, a: Item2, b: Item2) => number;
+            newCursorFromOldCursor: (cursor: "first" | "last") => Cursor2;
+            oldCursorFromNewCursor: (cursor: Cursor2) => "first" | "last";
+            oldFilterFromNewFilter: (filter: Filter2) => any;
+            oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => any;
+            estimateItemsToFetch: (options: {
+                filter: Filter2;
+                orderBy: OrderBy2;
+                limit: number;
+            }) => number;
+        }): PaginatedList<Item2, Cursor2, Filter2, OrderBy2>;
+        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>;
+        filter<Filter2_2 extends unknown>(options: {
+            filter: (item: never, filter: Filter2_2) => boolean;
+            oldFilterFromNewFilter: (filter: Filter2_2) => any;
+            estimateItemsToFetch: (options: {
+                filter: Filter2_2;
+                orderBy: any;
+                limit: number;
+            }) => number;
+        }): PaginatedList<never, "first" | "last", Filter2_2, any>;
+        addFilter<AddedFilter extends unknown>(options: {
+            filter: (item: never, filter: any) => boolean;
+            estimateItemsToFetch: (options: {
+                filter: any;
+                orderBy: any;
+                limit: number;
+            }) => number;
+        }): PaginatedList<never, "first" | "last", any, any>;
+    };
+}
+declare class ArrayPaginatedList<Item> extends PaginatedList<Item, `${number}`, (item: Item) => boolean, (a: Item, b: Item) => number> {
+    private readonly array;
+    constructor(array: Item[]);
+    _getFirstCursor(): "0";
+    _getLastCursor(): `${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<{
+        items: {
+            item: Item;
+            itemCursor: `${number}`;
+        }[];
+        isFirst: boolean;
+        isLast: boolean;
+        cursor: `${number}`;
+    }>;
+}
+
+export { ArrayPaginatedList, PaginatedList };

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

@@ -0,0 +1,176 @@
+type QueryOptions<Type extends 'next' | 'prev', Cursor, Filter, OrderBy> = {
+    filter: Filter;
+    orderBy: OrderBy;
+    limit: number;
+    /**
+     * Whether the limit should be treated as an exact value, or an approximate value.
+     *
+     * If set to 'exact', less items will only be returned if the list item is the first or last item.
+     *
+     * If set to 'at-least' or 'approximate', the implementation may decide to return more items than the limit requested if doing so comes at no (or negligible) extra cost.
+     *
+     * If set to 'at-most' or 'approximate', the implementation may decide to return less items than the limit requested if requesting more items would come at a non-negligible extra cost. In this case, if limit > 0, the implementation must still make progress towards the end of the list and the returned cursor must be different from the one passed in.
+     *
+     * Defaults to 'exact'.
+     */
+    limitPrecision: 'exact' | 'at-least' | 'at-most' | 'approximate';
+} & ([Type] extends [never] ? unknown : [Type] extends ['next'] ? {
+    after: Cursor;
+} : [Type] extends ['prev'] ? {
+    before: Cursor;
+} : {
+    cursor: Cursor;
+});
+type ImplQueryOptions<Type extends 'next' | 'prev', Cursor, Filter, OrderBy> = QueryOptions<Type, Cursor, Filter, OrderBy> & {
+    limitPrecision: 'approximate';
+};
+type QueryResult<Item, Cursor> = {
+    items: {
+        item: Item;
+        itemCursor: Cursor;
+    }[];
+    isFirst: boolean;
+    isLast: boolean;
+    cursor: Cursor;
+};
+type ImplQueryResult<Item, Cursor> = {
+    items: {
+        item: Item;
+        itemCursor: Cursor;
+    }[];
+    isFirst: boolean;
+    isLast: boolean;
+    cursor: Cursor;
+};
+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>>;
+    getFirstCursor(): Cursor;
+    getLastCursor(): Cursor;
+    compare(orderBy: OrderBy, a: Item, b: Item): number;
+    nextOrPrev(type: 'next' | 'prev', options: QueryOptions<'next' | 'prev', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    next({ after, ...rest }: QueryOptions<'next', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    prev({ before, ...rest }: QueryOptions<'prev', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    flatMap<Item2, Cursor2 extends string, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
+        itemMapper: (itemEntry: {
+            item: Item;
+            itemCursor: Cursor;
+        }, filter: Filter2, orderBy: OrderBy2) => {
+            item: Item2;
+            itemCursor: Cursor2;
+        }[];
+        compare: (orderBy: OrderBy2, a: Item2, b: Item2) => number;
+        newCursorFromOldCursor: (cursor: Cursor) => Cursor2;
+        oldCursorFromNewCursor: (cursor: Cursor2) => Cursor;
+        oldFilterFromNewFilter: (filter: Filter2) => Filter;
+        oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => OrderBy;
+        estimateItemsToFetch: (options: {
+            filter: Filter2;
+            orderBy: OrderBy2;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item2, Cursor2, Filter2, OrderBy2>;
+    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>;
+    filter<Filter2 extends unknown>(options: {
+        filter: (item: Item, filter: Filter2) => boolean;
+        oldFilterFromNewFilter: (filter: Filter2) => Filter;
+        estimateItemsToFetch: (options: {
+            filter: Filter2;
+            orderBy: OrderBy;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item, Cursor, Filter2, OrderBy>;
+    addFilter<AddedFilter extends unknown>(options: {
+        filter: (item: Item, filter: Filter & AddedFilter) => boolean;
+        estimateItemsToFetch: (options: {
+            filter: Filter & AddedFilter;
+            orderBy: OrderBy;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item, Cursor, Filter & AddedFilter, OrderBy>;
+    static merge<Item, Filter extends unknown, OrderBy extends unknown>(...lists: PaginatedList<Item, any, Filter, OrderBy>[]): PaginatedList<Item, string, Filter, OrderBy>;
+    static empty(): {
+        _getFirstCursor(): "first";
+        _getLastCursor(): "last";
+        _compare(orderBy: any, a: any, b: any): number;
+        _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', string, any, any>): Promise<{
+            items: never[];
+            isFirst: boolean;
+            isLast: boolean;
+            cursor: "first";
+        }>;
+        getFirstCursor(): "first" | "last";
+        getLastCursor(): "first" | "last";
+        compare(orderBy: any, a: never, b: never): number;
+        nextOrPrev(type: "next" | "prev", options: QueryOptions<"next" | "prev", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        next({ after, ...rest }: QueryOptions<"next", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        prev({ before, ...rest }: QueryOptions<"prev", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        flatMap<Item2, Cursor2 extends string, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
+            itemMapper: (itemEntry: {
+                item: never;
+                itemCursor: "first" | "last";
+            }, filter: Filter2, orderBy: OrderBy2) => {
+                item: Item2;
+                itemCursor: Cursor2;
+            }[];
+            compare: (orderBy: OrderBy2, a: Item2, b: Item2) => number;
+            newCursorFromOldCursor: (cursor: "first" | "last") => Cursor2;
+            oldCursorFromNewCursor: (cursor: Cursor2) => "first" | "last";
+            oldFilterFromNewFilter: (filter: Filter2) => any;
+            oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => any;
+            estimateItemsToFetch: (options: {
+                filter: Filter2;
+                orderBy: OrderBy2;
+                limit: number;
+            }) => number;
+        }): PaginatedList<Item2, Cursor2, Filter2, OrderBy2>;
+        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>;
+        filter<Filter2_2 extends unknown>(options: {
+            filter: (item: never, filter: Filter2_2) => boolean;
+            oldFilterFromNewFilter: (filter: Filter2_2) => any;
+            estimateItemsToFetch: (options: {
+                filter: Filter2_2;
+                orderBy: any;
+                limit: number;
+            }) => number;
+        }): PaginatedList<never, "first" | "last", Filter2_2, any>;
+        addFilter<AddedFilter extends unknown>(options: {
+            filter: (item: never, filter: any) => boolean;
+            estimateItemsToFetch: (options: {
+                filter: any;
+                orderBy: any;
+                limit: number;
+            }) => number;
+        }): PaginatedList<never, "first" | "last", any, any>;
+    };
+}
+declare class ArrayPaginatedList<Item> extends PaginatedList<Item, `${number}`, (item: Item) => boolean, (a: Item, b: Item) => number> {
+    private readonly array;
+    constructor(array: Item[]);
+    _getFirstCursor(): "0";
+    _getLastCursor(): `${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<{
+        items: {
+            item: Item;
+            itemCursor: `${number}`;
+        }[];
+        isFirst: boolean;
+        isLast: boolean;
+        cursor: `${number}`;
+    }>;
+}
+
+export { ArrayPaginatedList, PaginatedList };

package/dist/utils/paginated-lists.js

@@ -0,0 +1,256 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/utils/paginated-lists.tsx
+var paginated_lists_exports = {};
+__export(paginated_lists_exports, {
+  ArrayPaginatedList: () => ArrayPaginatedList,
+  PaginatedList: () => PaginatedList
+});
+module.exports = __toCommonJS(paginated_lists_exports);
+var import_arrays = require("./arrays.js");
+var import_errors = require("./errors.js");
+var PaginatedList = class _PaginatedList {
+  // Implementations
+  getFirstCursor() {
+    return this._getFirstCursor();
+  }
+  getLastCursor() {
+    return this._getLastCursor();
+  }
+  compare(orderBy, a, b) {
+    return this._compare(orderBy, a, b);
+  }
+  async nextOrPrev(type, options) {
+    let result = [];
+    let includesFirst = false;
+    let includesLast = false;
+    let cursor = options.cursor;
+    let limitRemaining = options.limit;
+    while (limitRemaining > 0 || type === "next" && includesLast || type === "prev" && includesFirst) {
+      const iterationRes = await this._nextOrPrev(type, {
+        cursor,
+        limit: options.limit,
+        limitPrecision: "approximate",
+        filter: options.filter,
+        orderBy: options.orderBy
+      });
+      result[type === "next" ? "push" : "unshift"](...iterationRes.items);
+      limitRemaining -= iterationRes.items.length;
+      includesFirst ||= iterationRes.isFirst;
+      includesLast ||= iterationRes.isLast;
+      cursor = iterationRes.cursor;
+      if (["approximate", "at-most"].includes(options.limitPrecision)) break;
+    }
+    for (let i = 1; i < result.length; i++) {
+      if (this._compare(options.orderBy, result[i].item, result[i - 1].item) < 0) {
+        throw new import_errors.StackAssertionError("Paginated list result is not sorted; something is wrong with the implementation", {
+          i,
+          options,
+          result
+        });
+      }
+    }
+    if (["exact", "at-most"].includes(options.limitPrecision) && result.length > options.limit) {
+      if (type === "next") {
+        result = result.slice(0, options.limit);
+        includesLast = false;
+        if (options.limit > 0) cursor = result[result.length - 1].itemCursor;
+      } else {
+        result = result.slice(result.length - options.limit);
+        includesFirst = false;
+        if (options.limit > 0) cursor = result[0].itemCursor;
+      }
+    }
+    return { items: result, isFirst: includesFirst, isLast: includesLast, cursor };
+  }
+  async next({ after, ...rest }) {
+    return await this.nextOrPrev("next", {
+      ...rest,
+      cursor: after
+    });
+  }
+  async prev({ before, ...rest }) {
+    return await this.nextOrPrev("prev", {
+      ...rest,
+      cursor: before
+    });
+  }
+  // Utility methods below
+  flatMap(options) {
+    const that = this;
+    class FlatMapPaginatedList extends _PaginatedList {
+      _getFirstCursor() {
+        return options.newCursorFromOldCursor(that.getFirstCursor());
+      }
+      _getLastCursor() {
+        return options.newCursorFromOldCursor(that.getLastCursor());
+      }
+      _compare(orderBy, a, b) {
+        return options.compare(orderBy, a, b);
+      }
+      async _nextOrPrev(type, { limit, filter, orderBy, cursor }) {
+        const estimatedItems = options.estimateItemsToFetch({ limit, filter, orderBy });
+        const original = await that.nextOrPrev(type, {
+          limit: estimatedItems,
+          limitPrecision: "approximate",
+          cursor: options.oldCursorFromNewCursor(cursor),
+          filter: options.oldFilterFromNewFilter(filter),
+          orderBy: options.oldOrderByFromNewOrderBy(orderBy)
+        });
+        const mapped = original.items.flatMap((itemEntry) => options.itemMapper(
+          itemEntry,
+          filter,
+          orderBy
+        ));
+        return {
+          items: mapped,
+          isFirst: original.isFirst,
+          isLast: original.isLast,
+          cursor: options.newCursorFromOldCursor(original.cursor)
+        };
+      }
+    }
+    return new FlatMapPaginatedList();
+  }
+  map(options) {
+    return this.flatMap({
+      itemMapper: (itemEntry, filter, orderBy) => {
+        return [{ item: options.itemMapper(itemEntry.item), itemCursor: itemEntry.itemCursor }];
+      },
+      compare: (orderBy, a, b) => this.compare(options.oldOrderByFromNewOrderBy(orderBy), options.oldItemFromNewItem(a), options.oldItemFromNewItem(b)),
+      newCursorFromOldCursor: (cursor) => cursor,
+      oldCursorFromNewCursor: (cursor) => cursor,
+      oldFilterFromNewFilter: (filter) => options.oldFilterFromNewFilter(filter),
+      oldOrderByFromNewOrderBy: (orderBy) => options.oldOrderByFromNewOrderBy(orderBy),
+      estimateItemsToFetch: (options2) => options2.limit
+    });
+  }
+  filter(options) {
+    return this.flatMap({
+      itemMapper: (itemEntry, filter, orderBy) => options.filter(itemEntry.item, filter) ? [itemEntry] : [],
+      compare: (orderBy, a, b) => this.compare(orderBy, a, b),
+      newCursorFromOldCursor: (cursor) => cursor,
+      oldCursorFromNewCursor: (cursor) => cursor,
+      oldFilterFromNewFilter: (filter) => options.oldFilterFromNewFilter(filter),
+      oldOrderByFromNewOrderBy: (orderBy) => orderBy,
+      estimateItemsToFetch: (o) => options.estimateItemsToFetch(o)
+    });
+  }
+  addFilter(options) {
+    return this.filter({
+      filter: (item, filter) => options.filter(item, filter),
+      oldFilterFromNewFilter: (filter) => filter,
+      estimateItemsToFetch: (o) => options.estimateItemsToFetch(o)
+    });
+  }
+  static merge(...lists) {
+    class MergePaginatedList extends _PaginatedList {
+      _getFirstCursor() {
+        return JSON.stringify(lists.map((list) => list.getFirstCursor()));
+      }
+      _getLastCursor() {
+        return JSON.stringify(lists.map((list) => list.getLastCursor()));
+      }
+      _compare(orderBy, a, b) {
+        const listsResults = lists.map((list) => list.compare(orderBy, a, b));
+        if (!listsResults.every((result) => result === listsResults[0])) {
+          throw new import_errors.StackAssertionError("Lists have different compare results; make sure that they use the same compare function", { lists, listsResults });
+        }
+        return listsResults[0];
+      }
+      async _nextOrPrev(type, { limit, filter, orderBy, cursor }) {
+        const cursors = JSON.parse(cursor);
+        const fetchedLists = await Promise.all(lists.map(async (list, i) => {
+          return await list.nextOrPrev(type, {
+            limit,
+            filter,
+            orderBy,
+            cursor: cursors[i],
+            limitPrecision: "at-least"
+          });
+        }));
+        const combinedItems = fetchedLists.flatMap((list, i) => list.items.map((itemEntry) => ({ itemEntry, listIndex: i })));
+        const sortedItems = [...combinedItems].sort((a, b) => this._compare(orderBy, a.itemEntry.item, b.itemEntry.item));
+        const lastCursorForEachList = sortedItems.reduce((acc, item) => {
+          acc[item.listIndex] = item.itemEntry.itemCursor;
+          return acc;
+        }, (0, import_arrays.range)(lists.length).map((i) => cursors[i]));
+        return {
+          items: sortedItems.map((item) => item.itemEntry),
+          isFirst: sortedItems.every((item) => item.listIndex === 0),
+          isLast: sortedItems.every((item) => item.listIndex === lists.length - 1),
+          cursor: JSON.stringify(lastCursorForEachList)
+        };
+      }
+    }
+    return new MergePaginatedList();
+  }
+  static empty() {
+    class EmptyPaginatedList extends _PaginatedList {
+      _getFirstCursor() {
+        return "first";
+      }
+      _getLastCursor() {
+        return "last";
+      }
+      _compare(orderBy, a, b) {
+        return 0;
+      }
+      async _nextOrPrev(type, options) {
+        return { items: [], isFirst: true, isLast: true, cursor: "first" };
+      }
+    }
+    return new EmptyPaginatedList();
+  }
+};
+var ArrayPaginatedList = class extends PaginatedList {
+  constructor(array) {
+    super();
+    this.array = array;
+  }
+  _getFirstCursor() {
+    return "0";
+  }
+  _getLastCursor() {
+    return `${this.array.length - 1}`;
+  }
+  _compare(orderBy, a, b) {
+    return orderBy(a, b);
+  }
+  async _nextOrPrev(type, options) {
+    const filteredArray = this.array.filter(options.filter);
+    const sortedArray = [...filteredArray].sort((a, b) => this._compare(options.orderBy, a, b));
+    const itemEntriesArray = sortedArray.map((item, index) => ({ item, itemCursor: `${index}` }));
+    const oldCursor = Number(options.cursor);
+    const newCursor = Math.max(0, Math.min(this.array.length - 1, oldCursor + (type === "next" ? 1 : -1) * options.limit));
+    return {
+      items: itemEntriesArray.slice(Math.min(oldCursor, newCursor), Math.max(oldCursor, newCursor)),
+      isFirst: oldCursor === 0 || newCursor === 0,
+      isLast: oldCursor === this.array.length - 1 || newCursor === this.array.length - 1,
+      cursor: `${newCursor}`
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ArrayPaginatedList,
+  PaginatedList
+});
+//# sourceMappingURL=paginated-lists.js.map