@hexclave/shared 1.0.0

package/dist/utils/objects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"objects.js","names":[],"sources":["../../src/utils/objects.tsx"],"sourcesContent":["import { HexclaveAssertionError } from \"./errors\";\nimport { identity } from \"./functions\";\nimport { stringCompare } from \"./strings\";\nimport { typeAssertIs } from \"./types\";\n\nexport function isNotNull<T>(value: T): value is NonNullable<T> {\n  return value !== null && value !== undefined;\n}\nimport.meta.vitest?.test(\"isNotNull\", ({ expect }) => {\n  expect(isNotNull(null)).toBe(false);\n  expect(isNotNull(undefined)).toBe(false);\n  expect(isNotNull(0)).toBe(true);\n  expect(isNotNull(\"\")).toBe(true);\n  expect(isNotNull(false)).toBe(true);\n  expect(isNotNull({})).toBe(true);\n  expect(isNotNull([])).toBe(true);\n});\n\nexport type DeepPartial<T> = T extends object ? (T extends any[] ? { [P in keyof T]: DeepPartial<T[P]> } : { [P in keyof T]?: DeepPartial<T[P]> }) : T;\nexport type DeepRequired<T> = T extends object ? { [P in keyof T]-?: DeepRequired<T[P]> } : T;\nexport type DeepRequiredOrUndefined<T> = T extends object ? { [P in keyof { [K in keyof T]-?: K}]: DeepRequiredOrUndefined<T[P]> } : T;\n\n\n/**\n * Assumes both objects are primitives, arrays, or non-function plain objects, and compares them deeply.\n *\n * Note that since they are assumed to be plain objects, this function does not compare prototypes.\n */\nexport function deepPlainEquals<T>(obj1: T, obj2: unknown, options: { ignoreUndefinedValues?: boolean } = {}): obj2 is T {\n  if (typeof obj1 !== typeof obj2) return false;\n  if (obj1 === obj2) return true;\n\n  switch (typeof obj1) {\n    case 'object': {\n      if (!obj1 || !obj2) return false;\n\n      if (Array.isArray(obj1) || Array.isArray(obj2)) {\n        if (!Array.isArray(obj1) || !Array.isArray(obj2)) return false;\n        if (obj1.length !== obj2.length) return false;\n        return obj1.every((v, i) => deepPlainEquals(v, obj2[i], options));\n      }\n\n      const entries1 = Object.entries(obj1).filter(([k, v]) => !options.ignoreUndefinedValues || v !== undefined);\n      const entries2 = Object.entries(obj2).filter(([k, v]) => !options.ignoreUndefinedValues || v !== undefined);\n      if (entries1.length !== entries2.length) return false;\n      return entries1.every(([k, v1]) => {\n        const e2 = entries2.find(([k2]) => k === k2);\n        if (!e2) return false;\n        return deepPlainEquals(v1, e2[1], options);\n      });\n    }\n    case 'undefined':\n    case 'string':\n    case 'number':\n    case 'boolean':\n    case 'bigint':\n    case 'symbol':\n    case 'function':{\n      return false;\n    }\n    default: {\n      throw new Error(\"Unexpected typeof \" + typeof obj1);\n    }\n  }\n}\nimport.meta.vitest?.test(\"deepPlainEquals\", ({ expect }) => {\n  // Simple values\n  expect(deepPlainEquals(1, 1)).toBe(true);\n  expect(deepPlainEquals(\"test\", \"test\")).toBe(true);\n  expect(deepPlainEquals(1, 2)).toBe(false);\n  expect(deepPlainEquals(\"test\", \"other\")).toBe(false);\n\n  // Arrays\n  expect(deepPlainEquals([1, 2, 3], [1, 2, 3])).toBe(true);\n  expect(deepPlainEquals([1, 2, 3], [1, 2, 4])).toBe(false);\n  expect(deepPlainEquals([1, 2, 3], [1, 2])).toBe(false);\n\n  // Objects\n  expect(deepPlainEquals({ a: 1, b: 2 }, { a: 1, b: 2 })).toBe(true);\n  expect(deepPlainEquals({ a: 1, b: 2 }, { a: 1, b: 3 })).toBe(false);\n  expect(deepPlainEquals({ a: 1, b: 2 }, { a: 1 })).toBe(false);\n\n  // Nested structures\n  expect(deepPlainEquals({ a: 1, b: [1, 2, { c: 3 }] }, { a: 1, b: [1, 2, { c: 3 }] })).toBe(true);\n  expect(deepPlainEquals({ a: 1, b: [1, 2, { c: 3 }] }, { a: 1, b: [1, 2, { c: 4 }] })).toBe(false);\n\n  // With options\n  expect(deepPlainEquals({ a: 1, b: undefined }, { a: 1 }, { ignoreUndefinedValues: true })).toBe(true);\n  expect(deepPlainEquals({ a: 1, b: undefined }, { a: 1 })).toBe(false);\n});\n\nexport function isCloneable<T>(obj: T): obj is Exclude<T, symbol | Function> {\n  return typeof obj !== 'symbol' && typeof obj !== 'function';\n}\n\nexport function shallowClone<T extends object>(obj: T): T {\n  if (!isCloneable(obj)) throw new HexclaveAssertionError(\"shallowClone does not support symbols or functions\", { obj });\n\n  if (Array.isArray(obj)) return obj.map(identity) as T;\n  return { ...obj };\n}\nimport.meta.vitest?.test(\"shallowClone\", ({ expect }) => {\n  expect(shallowClone({ a: 1, b: 2 })).toEqual({ a: 1, b: 2 });\n  expect(shallowClone([1, 2, 3])).toEqual([1, 2, 3]);\n  expect(() => shallowClone(() => {})).toThrow();\n});\n\nexport function deepPlainClone<T>(obj: T): T {\n  if (typeof obj === 'function') throw new HexclaveAssertionError(\"deepPlainClone does not support functions\");\n  if (typeof obj === 'symbol') throw new HexclaveAssertionError(\"deepPlainClone does not support symbols\");\n  if (typeof obj !== 'object' || !obj) return obj;\n  if (Array.isArray(obj)) return obj.map(deepPlainClone) as any;\n  return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, deepPlainClone(v)])) as any;\n}\nimport.meta.vitest?.test(\"deepPlainClone\", ({ expect }) => {\n  // Primitive values\n  expect(deepPlainClone(1)).toBe(1);\n  expect(deepPlainClone(\"test\")).toBe(\"test\");\n  expect(deepPlainClone(null)).toBe(null);\n  expect(deepPlainClone(undefined)).toBe(undefined);\n\n  // Arrays\n  const arr = [1, 2, 3];\n  const clonedArr = deepPlainClone(arr);\n  expect(clonedArr).toEqual(arr);\n  expect(clonedArr).not.toBe(arr); // Different reference\n\n  // Objects\n  const obj = { a: 1, b: 2 };\n  const clonedObj = deepPlainClone(obj);\n  expect(clonedObj).toEqual(obj);\n  expect(clonedObj).not.toBe(obj); // Different reference\n\n  // Nested structures\n  const nested = { a: 1, b: [1, 2, { c: 3 }] };\n  const clonedNested = deepPlainClone(nested);\n  expect(clonedNested).toEqual(nested);\n  expect(clonedNested).not.toBe(nested); // Different reference\n  expect(clonedNested.b).not.toBe(nested.b); // Different reference for nested array\n  expect(clonedNested.b[2]).not.toBe(nested.b[2]); // Different reference for nested object\n\n  // Error cases\n  expect(() => deepPlainClone(() => {})).toThrow();\n  expect(() => deepPlainClone(Symbol())).toThrow();\n});\n\nexport type DeepMerge<T, U> = U extends any ? DeepMergeNonDistributive<T, U> : never;  // distributive conditional type https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types\ntype DeepMergeNonDistributive<T, U> = Omit<T, keyof U> & Omit<U, keyof T> & DeepMergeInner<Pick<T, keyof U & keyof T>, Pick<U, keyof U & keyof T>>;\ntype DeepMergeInner<T, U> = {\n  [K in { [Ki in keyof U]-?: Ki }[keyof U]]:  // we use this weird construct instead of just `keyof U` because TypeScript automatically removes the `undefined` key when using `-?` as a modifier; this is a workaround to make TypeScript not recognize the -? and for us to get the `undefined` key back\n    undefined extends U[K]\n      ? K extends keyof T\n          ? T[K] extends object\n              ? Exclude<U[K], undefined> extends object\n                  ? DeepMerge<T[K], Exclude<U[K], undefined>>\n                  : T[K] | Exclude<U[K], undefined>\n              : T[K] | Exclude<U[K], undefined>\n          : Exclude<U[K], undefined>\n      : K extends keyof T\n          ? T[K] extends object\n              ? U[K] extends object\n                  ? DeepMerge<T[K], U[K]>\n                  : U[K]\n              : U[K]\n          : U[K];\n};\nexport function deepMerge<T extends {}, U extends {}>(baseObj: T, mergeObj: U): DeepMerge<T, U> {\n  if ([baseObj, mergeObj, ...Object.values(baseObj), ...Object.values(mergeObj)].some(o => !isCloneable(o))) throw new HexclaveAssertionError(\"deepMerge does not support functions or symbols\", { baseObj, mergeObj });\n\n  const res: any = shallowClone(baseObj);\n  for (const [key, mergeValue] of Object.entries(mergeObj)) {\n    if (has(res, key as any)) {\n      const baseValue = get(res, key as any);\n      if (isObjectLike(baseValue) && isObjectLike(mergeValue)) {\n        set(res, key, deepMerge(baseValue, mergeValue));\n        continue;\n      }\n    }\n    set(res, key, mergeValue);\n  }\n  return res as any;\n}\nimport.meta.vitest?.test(\"deepMerge\", ({ expect }) => {\n  // Test merging flat objects\n  expect(deepMerge({ a: 1 }, { b: 2 })).toEqual({ a: 1, b: 2 });\n  expect(deepMerge({ a: 1 }, { a: 2 })).toEqual({ a: 2 });\n  expect(deepMerge({ a: 1, b: 2 }, { b: 3, c: 4 })).toEqual({ a: 1, b: 3, c: 4 });\n\n  // Test with nested objects\n  expect(deepMerge(\n    { a: { x: 1, y: 2 }, b: 3 },\n    { a: { y: 3, z: 4 }, c: 5 }\n  )).toEqual({ a: { x: 1, y: 3, z: 4 }, b: 3, c: 5 });\n\n  // Test with arrays\n  expect(deepMerge(\n    { a: [1, 2], b: 3 },\n    { a: [3, 4], c: 5 }\n  )).toEqual({ a: [3, 4], b: 3, c: 5 });\n\n  // Test with null values\n  expect(deepMerge(\n    { a: { x: 1 }, b: null },\n    { a: { y: 2 }, b: { z: 3 } }\n  )).toEqual({ a: { x: 1, y: 2 }, b: { z: 3 } });\n\n  // Test with undefined values\n  expect(deepMerge(\n    { a: 1, b: undefined },\n    { b: 2, c: 3 }\n  )).toEqual({ a: 1, b: 2, c: 3 });\n\n  // Test deeply nested structures\n  expect(deepMerge(\n    {\n      a: {\n        x: { deep: 1 },\n        y: [1, 2]\n      },\n      b: 2\n    },\n    {\n      a: {\n        x: { deeper: 3 },\n        y: [3, 4]\n      },\n      c: 3\n    }\n  )).toEqual({\n    a: {\n      x: { deep: 1, deeper: 3 },\n      y: [3, 4]\n    },\n    b: 2,\n    c: 3\n  });\n\n  // Test with empty objects\n  expect(deepMerge({}, { a: 1 })).toEqual({ a: 1 });\n  expect(deepMerge({ a: 1 }, {})).toEqual({ a: 1 });\n  expect(deepMerge({}, {})).toEqual({});\n\n  // Test that original objects are not modified\n  const base = { a: { x: 1 }, b: 2 };\n  const merge = { a: { y: 2 }, c: 3 };\n  const baseClone = deepPlainClone(base);\n  const mergeClone = deepPlainClone(merge);\n\n  const result = deepMerge(base, merge);\n  expect(base).toEqual(baseClone);\n  expect(merge).toEqual(mergeClone);\n  expect(result).toEqual({ a: { x: 1, y: 2 }, b: 2, c: 3 });\n\n  // Test error cases\n  expect(() => deepMerge({ a: () => {} }, { b: 2 })).toThrow();\n  expect(() => deepMerge({ a: 1 }, { b: () => {} })).toThrow();\n  expect(() => deepMerge({ a: Symbol() }, { b: 2 })).toThrow();\n  expect(() => deepMerge({ a: 1 }, { b: Symbol() })).toThrow();\n});\n\nexport type DeepOmit<T, U> = T extends object ? { [K in keyof T]: K extends keyof U ? (T[K] extends U[K] ? undefined : T[K]) : T[K] } : (T extends U ? undefined : T);\n\nexport function typedEntries<T extends {}>(obj: T): [Exclude<keyof T, number>, T[keyof T]][] {\n  return Object.entries(obj) as any;\n}\nimport.meta.vitest?.test(\"typedEntries\", ({ expect }) => {\n  expect(typedEntries({})).toEqual([]);\n  expect(typedEntries({ a: 1, b: 2 })).toEqual([[\"a\", 1], [\"b\", 2]]);\n  expect(typedEntries({ a: \"hello\", b: true, c: null })).toEqual([[\"a\", \"hello\"], [\"b\", true], [\"c\", null]]);\n\n  // Test with object containing methods\n  const objWithMethod = { a: 1, b: () => \"test\" };\n  const entries = typedEntries(objWithMethod);\n  expect(entries.length).toBe(2);\n  expect(entries[0][0]).toBe(\"a\");\n  expect(entries[0][1]).toBe(1);\n  expect(entries[1][0]).toBe(\"b\");\n  expect(typeof entries[1][1]).toBe(\"function\");\n});\n\nexport function typedFromEntries<K extends PropertyKey, V>(entries: (readonly [K, V])[]): Record<K, V> {\n  return Object.fromEntries(entries) as any;\n}\nimport.meta.vitest?.test(\"typedFromEntries\", ({ expect }) => {\n  expect(typedFromEntries([])).toEqual({});\n  expect(typedFromEntries([[\"a\", 1], [\"b\", 2]])).toEqual({ a: 1, b: 2 });\n\n  // Test with mixed types (using type assertion)\n  const mixedEntries = [[\"a\", \"hello\"], [\"b\", true], [\"c\", null]] as [string, string | boolean | null][];\n  const mixedObj = typedFromEntries(mixedEntries);\n  expect(mixedObj).toEqual({ a: \"hello\", b: true, c: null });\n\n  // Test with function values\n  const fn = () => \"test\";\n  type MixedValue = number | (() => string);\n  const fnEntries: [string, MixedValue][] = [[\"a\", 1], [\"b\", fn]];\n  const obj = typedFromEntries(fnEntries);\n  expect(obj.a).toBe(1);\n  expect(typeof obj.b).toBe(\"function\");\n  // Type assertion needed for the function call\n  expect((obj.b as () => string)()).toBe(\"test\");\n});\n\nexport function typedKeys<T extends {}>(obj: T): (Exclude<keyof T, number>)[] {\n  return Object.keys(obj) as any;\n}\nimport.meta.vitest?.test(\"typedKeys\", ({ expect }) => {\n  expect(typedKeys({})).toEqual([]);\n  expect(typedKeys({ a: 1, b: 2 })).toEqual([\"a\", \"b\"]);\n  expect(typedKeys({ a: \"hello\", b: true, c: null })).toEqual([\"a\", \"b\", \"c\"]);\n\n  // Test with object containing methods\n  const objWithMethod = { a: 1, b: () => \"test\" };\n  expect(typedKeys(objWithMethod)).toEqual([\"a\", \"b\"]);\n});\n\nexport function typedValues<T extends {}>(obj: T): T[keyof T][] {\n  return Object.values(obj) as any;\n}\nimport.meta.vitest?.test(\"typedValues\", ({ expect }) => {\n  expect(typedValues({})).toEqual([]);\n  expect(typedValues({ a: 1, b: 2 })).toEqual([1, 2]);\n\n  // Test with mixed types\n  type MixedObj = { a: string, b: boolean, c: null };\n  const mixedObj: MixedObj = { a: \"hello\", b: true, c: null };\n  expect(typedValues(mixedObj)).toEqual([\"hello\", true, null]);\n\n  // Test with object containing methods\n  type ObjWithFn = { a: number, b: () => string };\n  const fn = () => \"test\";\n  const objWithMethod: ObjWithFn = { a: 1, b: fn };\n  const values = typedValues(objWithMethod);\n  expect(values.length).toBe(2);\n  expect(values[0]).toBe(1);\n  expect(typeof values[1]).toBe(\"function\");\n  // Need to cast to the correct type\n  const fnValue = values[1] as () => string;\n  expect(fnValue()).toBe(\"test\");\n});\n\nexport function typedAssign<T extends {}, U extends {}>(target: T, source: U): T & U {\n  return Object.assign(target, source);\n}\nimport.meta.vitest?.test(\"typedAssign\", ({ expect }) => {\n  // Test with empty objects\n  const emptyTarget = {};\n  const emptyResult = typedAssign(emptyTarget, { a: 1 });\n  expect(emptyResult).toEqual({ a: 1 });\n  expect(emptyResult).toBe(emptyTarget); // Same reference\n\n  // Test with non-empty target\n  const target = { a: 1, b: 2 };\n  const result = typedAssign(target, { c: 3, d: 4 });\n  expect(result).toEqual({ a: 1, b: 2, c: 3, d: 4 });\n  expect(result).toBe(target); // Same reference\n\n  // Test with overlapping properties\n  const targetWithOverlap = { a: 1, b: 2 };\n  const resultWithOverlap = typedAssign(targetWithOverlap, { b: 3, c: 4 });\n  expect(resultWithOverlap).toEqual({ a: 1, b: 3, c: 4 });\n  expect(resultWithOverlap).toBe(targetWithOverlap); // Same reference\n});\n\nexport type FilterUndefined<T> =\n  & { [k in keyof T as (undefined extends T[k] ? (T[k] extends undefined | void ? never : k) : never)]+?: T[k] & ({} | null) }\n  & { [k in keyof T as (undefined extends T[k] ? never : k)]: T[k] & ({} | null) }\n\n/**\n * Returns a new object with all undefined values removed. Useful when spreading optional parameters on an object, as\n * TypeScript's `Partial<XYZ>` type allows `undefined` values.\n */\nexport function filterUndefined<T extends object>(obj: T): FilterUndefined<T> {\n  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as any;\n}\nimport.meta.vitest?.test(\"filterUndefined\", ({ expect }) => {\n  expect(filterUndefined({})).toEqual({});\n  expect(filterUndefined({ a: 1, b: 2 })).toEqual({ a: 1, b: 2 });\n  expect(filterUndefined({ a: 1, b: undefined })).toEqual({ a: 1 });\n  expect(filterUndefined({ a: undefined, b: undefined })).toEqual({});\n  expect(filterUndefined({ a: null, b: undefined })).toEqual({ a: null });\n  expect(filterUndefined({ a: 0, b: \"\", c: false, d: undefined })).toEqual({ a: 0, b: \"\", c: false });\n});\n\nexport type FilterUndefinedOrNull<T> = FilterUndefined<{ [k in keyof T]: null extends T[k] ? NonNullable<T[k]> | undefined : T[k] }>;\n\n/**\n * Returns a new object with all undefined and null values removed. Useful when spreading optional parameters on an object, as\n * TypeScript's `Partial<XYZ>` type allows `undefined` values.\n */\nexport function filterUndefinedOrNull<T extends object>(obj: T): FilterUndefinedOrNull<T> {\n  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== null)) as any;\n}\nimport.meta.vitest?.test(\"filterUndefinedOrNull\", ({ expect }) => {\n  expect(filterUndefinedOrNull({})).toEqual({});\n  expect(filterUndefinedOrNull({ a: 1, b: 2 })).toEqual({ a: 1, b: 2 });\n});\n\nexport type DeepFilterUndefined<T> = T extends object ? FilterUndefined<{ [K in keyof T]: DeepFilterUndefined<T[K]> }> : T;\ntypeAssertIs<DeepFilterUndefined<{ a: { b: { c?: undefined, d?: 123 } } }>, { a: { b: { d?: 123 } } }>()();\n\nexport function deepFilterUndefined<T extends object>(obj: T): DeepFilterUndefined<T> {\n  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined).map(([k, v]) => [k, isObjectLike(v) ? deepFilterUndefined(v) : v])) as any;\n}\nimport.meta.vitest?.test(\"deepFilterUndefined\", ({ expect }) => {\n  expect(deepFilterUndefined({ a: 1, b: undefined })).toEqual({ a: 1 });\n});\n\nexport function pick<T extends {}, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {\n  return Object.fromEntries(Object.entries(obj).filter(([k]) => keys.includes(k as K))) as any;\n}\nimport.meta.vitest?.test(\"pick\", ({ expect }) => {\n  const obj = { a: 1, b: 2, c: 3, d: 4 };\n  expect(pick(obj, [\"a\", \"c\"])).toEqual({ a: 1, c: 3 });\n  expect(pick(obj, [])).toEqual({});\n  expect(pick(obj, [\"a\", \"e\" as keyof typeof obj])).toEqual({ a: 1 });\n  // Use type assertion for empty object to avoid TypeScript error\n  expect(pick({} as Record<string, unknown>, [\"a\"])).toEqual({});\n});\n\nexport function omit<T extends {}, K extends keyof T>(obj: T, keys: K[]): Omit<T, K> {\n  if (!Array.isArray(keys)) throw new HexclaveAssertionError(\"omit: keys must be an array\", { obj, keys });\n  return Object.fromEntries(Object.entries(obj).filter(([k]) => !keys.includes(k as K))) as any;\n}\nimport.meta.vitest?.test(\"omit\", ({ expect }) => {\n  const obj = { a: 1, b: 2, c: 3, d: 4 };\n  expect(omit(obj, [\"a\", \"c\"])).toEqual({ b: 2, d: 4 });\n  expect(omit(obj, [])).toEqual(obj);\n  expect(omit(obj, [\"a\", \"e\" as keyof typeof obj])).toEqual({ b: 2, c: 3, d: 4 });\n  // Use type assertion for empty object to avoid TypeScript error\n  expect(omit({} as Record<string, unknown>, [\"a\"])).toEqual({});\n});\n\nexport function split<T extends {}, K extends keyof T>(obj: T, keys: K[]): [Pick<T, K>, Omit<T, K>] {\n  return [pick(obj, keys), omit(obj, keys)];\n}\nimport.meta.vitest?.test(\"split\", ({ expect }) => {\n  const obj = { a: 1, b: 2, c: 3, d: 4 };\n  expect(split(obj, [\"a\", \"c\"])).toEqual([{ a: 1, c: 3 }, { b: 2, d: 4 }]);\n  expect(split(obj, [])).toEqual([{}, obj]);\n  expect(split(obj, [\"a\", \"e\" as keyof typeof obj])).toEqual([{ a: 1 }, { b: 2, c: 3, d: 4 }]);\n  // Use type assertion for empty object to avoid TypeScript error\n  expect(split({} as Record<string, unknown>, [\"a\"])).toEqual([{}, {}]);\n});\n\nexport function mapValues<T extends object, U>(obj: T, fn: (value: T extends (infer E)[] ? E : T[keyof T], key: keyof T) => U): Record<keyof T, U> {\n  if (Array.isArray(obj)) {\n    return obj.map((v, i) => fn(v, i as keyof T)) as any;\n  }\n  return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, fn(v, k as keyof T)])) as any;\n}\nimport.meta.vitest?.test(\"mapValues\", ({ expect }) => {\n  expect(mapValues({ a: 1, b: 2 }, v => v * 2)).toEqual({ a: 2, b: 4 });\n  expect(mapValues([1, 2, 3], v => v * 2)).toEqual([2, 4, 6]);\n});\n\nexport function sortKeys<T extends object>(obj: T): T {\n  if (Array.isArray(obj)) {\n    return [...obj] as any;\n  }\n  return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => stringCompare(a, b))) as any;\n}\nimport.meta.vitest?.test(\"sortKeys\", ({ expect }) => {\n  const obj = {\n    \"1\": 0,\n    \"10\": 1,\n    b: 2,\n    \"2\": 3,\n    a: 4,\n    \"-3.33\": 5,\n    \"-4\": 6,\n    \"-3\": 7,\n    abc: 8,\n    \"a-b\": 9,\n    ab: 10,\n    ac: 11,\n    aa: 12,\n    aab: 13,\n  };\n  expect(Object.entries(sortKeys(obj))).toEqual([\n    [\"1\", 0],\n    [\"2\", 3],\n    [\"10\", 1],\n    [\"-3\", 7],\n    [\"-3.33\", 5],\n    [\"-4\", 6],\n    [\"a\", 4],\n    [\"a-b\", 9],\n    [\"aa\", 12],\n    [\"aab\", 13],\n    [\"ab\", 10],\n    [\"abc\", 8],\n    [\"ac\", 11],\n    [\"b\", 2],\n  ]);\n});\n\nexport function deepSortKeys<T extends object>(obj: T): T {\n  return sortKeys(mapValues(obj, v => isObjectLike(v) ? deepSortKeys(v) : v)) as any;\n}\nimport.meta.vitest?.test(\"deepSortKeys\", ({ expect }) => {\n  const obj = {\n    h: { i: { k: 9, j: 8 }, l: 10 },\n    b: { d: 3, c: 2 },\n    a: 1,\n    e: [4, 5, { g: 7, f: 6 }],\n  };\n  const sorted = deepSortKeys(obj);\n  expect(Object.entries(sorted)).toEqual([\n    [\"a\", 1],\n    [\"b\", { c: 2, d: 3 }],\n    [\"e\", [4, 5, { f: 6, g: 7 }]],\n    [\"h\", { i: { j: 8, k: 9 }, l: 10 }],\n  ]);\n  expect(Object.entries(sorted.b)).toEqual([\n    [\"c\", 2],\n    [\"d\", 3],\n  ]);\n  expect(Object.entries(sorted.e[2])).toEqual([\n    [\"f\", 6],\n    [\"g\", 7],\n  ]);\n  expect(Object.entries(sorted.h)).toEqual([\n    [\"i\", { j: 8, k: 9 }],\n    [\"l\", 10],\n  ]);\n  expect(Object.entries(sorted.h.i)).toEqual([\n    [\"j\", 8],\n    [\"k\", 9],\n  ]);\n});\n\nexport function set<T extends object, K extends PropertyKey = keyof T>(obj: T, key: K, value: T[K & keyof T]) {\n  if (!isObjectLike(obj)) throw new HexclaveAssertionError(`set: obj is not an object (found: ${(obj as any) === null ? \"null\" : typeof obj})`, { obj, key, value });\n  Object.defineProperty(obj, key, { value, writable: true, configurable: true, enumerable: true });\n}\n\nexport function get<T extends object, K extends PropertyKey = keyof T>(obj: T, key: K): T[K & keyof T] {\n  if ((obj as any) == null) throw new HexclaveAssertionError(\"get: obj is null or undefined\", { obj, key });\n  const descriptor = Object.getOwnPropertyDescriptor(obj, key);\n  if (!descriptor) throw new HexclaveAssertionError(`get: key ${String(key)} does not exist`, { obj, key });\n  return descriptor.value;\n}\n\nexport function getOrUndefined<T extends object, K extends PropertyKey = keyof T>(obj: T, key: K): T[K & keyof T] | undefined {\n  if ((obj as any) == null) throw new HexclaveAssertionError(\"getOrUndefined: obj is null or undefined\", { obj, key });\n  return has(obj, key) ? get(obj, key) : undefined;\n}\n\nexport function has<T extends object, K extends PropertyKey = keyof T>(obj: T, key: K): obj is T & { [k in K & keyof T]: unknown } {\n  if ((obj as any) == null) throw new HexclaveAssertionError(\"has: obj is null or undefined\", { obj, key });\n  return Object.prototype.hasOwnProperty.call(obj, key);\n}\n\nimport.meta.vitest?.test(\"has\", ({ expect }) => {\n  const obj = { a: 1, b: undefined, c: null };\n  expect(has(obj, \"a\")).toBe(true);\n  expect(has(obj, \"b\")).toBe(true);\n  expect(has(obj, \"c\")).toBe(true);\n  expect(has(obj, \"d\" as keyof typeof obj)).toBe(false);\n});\n\n\nexport function hasAndNotUndefined<T extends object, K extends keyof T>(obj: T, key: K): obj is T & { [k in K]: Exclude<T[K], undefined> } {\n  return has(obj, key) && get(obj, key) !== undefined;\n}\n\nexport function deleteKey<T extends object, K extends keyof T>(obj: T, key: K) {\n  if (has(obj, key)) {\n    Reflect.deleteProperty(obj, key);\n  } else {\n    throw new HexclaveAssertionError(`deleteKey: key ${String(key)} does not exist`, { obj, key });\n  }\n}\n\n/**\n * Returns true iff the value is an object or a function, but not null.\n */\nexport function isObjectLike(value: unknown): value is object | Function {\n  return (typeof value === 'object' || typeof value === 'function') && value !== null;\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,442 @@
+//#region src/utils/paginated-lists.d.ts
+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;
+    prevCursor: Cursor;
+    nextCursor: Cursor;
+  }[];
+  isFirst: boolean;
+  isLast: boolean;
+  cursor: Cursor;
+};
+type ImplQueryResult<Item, Cursor> = {
+  items: {
+    item: Item;
+    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;
+      prevCursor: Cursor;
+      nextCursor: Cursor;
+    }, filter: Filter2, orderBy: OrderBy2) => {
+      item: Item2;
+      prevCursor: Cursor2;
+      nextCursor: 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>;
+  /**
+   * 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;
+    estimateItemsToFetch: (options: {
+      filter: Filter2;
+      orderBy: OrderBy;
+      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: {
+      filter: Filter & AddedFilter;
+      orderBy: OrderBy;
+      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";
+    _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";
+    }>; /** 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;
+        prevCursor: "first" | "last";
+        nextCursor: "first" | "last";
+      }, filter: Filter2, orderBy: OrderBy2) => {
+        item: Item2;
+        prevCursor: Cursor2;
+        nextCursor: 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>;
+    /**
+     * 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: never) => Item2;
+      oldItemFromNewItem: (item: Item2) => never;
+      oldFilterFromNewFilter: (filter: Filter2) => any;
+      oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => any;
+    }): PaginatedList<Item2, "first" | "last", 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: never, filter: Filter2) => boolean;
+      oldFilterFromNewFilter: (filter: Filter2) => any;
+      estimateItemsToFetch: (options: {
+        filter: Filter2;
+        orderBy: any;
+        limit: number;
+      }) => number;
+    }): PaginatedList<never, "first" | "last", Filter2, 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: {
+        filter: any;
+        orderBy: any;
+        limit: number;
+      }) => number;
+    }): PaginatedList<never, "first" | "last", any, any>;
+  };
+}
+/**
+ * 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(): "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', `before-${number}`, (item: Item) => boolean, (a: Item, b: Item) => number>): Promise<{
+    items: {
+      item: Item;
+      prevCursor: `before-${number}`;
+      nextCursor: `before-${number}`;
+    }[];
+    isFirst: boolean;
+    isLast: boolean;
+    cursor: `before-${number}`;
+  }>;
+}
+//#endregion
+export { ArrayPaginatedList, PaginatedList };
+//# sourceMappingURL=paginated-lists.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paginated-lists.d.ts","names":[],"sources":["../../src/utils/paginated-lists.tsx"],"mappings":"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"}