@fragno-dev/db 0.2.2 → 0.4.1

package/dist/query/condition-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"condition-builder.js","names":["builder: ConditionBuilder<Columns>"],"sources":["../../src/query/condition-builder.ts"],"sourcesContent":["import type { AnyColumn, FragnoId, IdColumn } from \"../schema/create\";\n\nexport type ConditionType = \"compare\" | \"and\" | \"or\" | \"not\";\n\nexport type Condition =\n  | {\n      type: \"compare\";\n      a: AnyColumn;\n      operator: Operator;\n      b: AnyColumn | unknown | null;\n    }\n  | {\n      type: \"or\" | \"and\";\n      items: Condition[];\n    }\n  | {\n      type: \"not\";\n      item: Condition;\n    };\n\n// TODO: we temporarily dropped support for comparing against another column, because Prisma ORM still have problems with it.\n\n/**\n * Helper type that allows FragnoId for ID columns and reference columns (bigint).\n * Used in ConditionBuilder to accept FragnoId values in where conditions.\n */\ntype AcceptsFragnoId<T extends AnyColumn> = T extends IdColumn\n  ? T[\"$in\"] | FragnoId\n  : T[\"$in\"] extends bigint\n    ? T[\"$in\"] | FragnoId\n    : T[\"$in\"];\n\nexport type ConditionBuilder<Columns extends Record<string, AnyColumn>> = {\n  <ColName extends keyof Columns>(\n    a: ColName,\n    operator: (typeof valueOperators)[number] | (typeof stringOperators)[number],\n    b: AcceptsFragnoId<Columns[ColName]> | null,\n  ): Condition;\n\n  <ColName extends keyof Columns>(\n    a: ColName,\n    operator: (typeof arrayOperators)[number],\n    b: AcceptsFragnoId<Columns[ColName]>[],\n  ): Condition;\n\n  /**\n   * Boolean values\n   */\n  <ColName extends keyof Columns>(a: ColName): Condition;\n\n  and: (...v: (Condition | boolean)[]) => Condition | boolean;\n  or: (...v: (Condition | boolean)[]) => Condition | boolean;\n  not: (v: Condition | boolean) => Condition | boolean;\n\n  isNull: (a: keyof Columns) => Condition;\n  isNotNull: (a: keyof Columns) => Condition;\n};\n\n// replacement for `like` (Prisma doesn't support `like`)\nconst stringOperators = [\n  \"contains\",\n  \"starts with\",\n  \"ends with\",\n\n  \"not contains\",\n  \"not starts with\",\n  \"not ends with\",\n  // excluded `regexp` since MSSQL doesn't support it, may re-consider\n] as const;\n\nconst arrayOperators = [\"in\", \"not in\"] as const;\n\nconst valueOperators = [\"=\", \"!=\", \">\", \">=\", \"<\", \"<=\", \"is\", \"is not\"] as const;\n\n// JSON specific operators are not included, some databases don't support them\n// `match` requires additional extensions & configurations on SQLite and PostgreSQL\n// MySQL & SQLite requires workarounds to support `ilike`\nexport const operators = [...valueOperators, ...arrayOperators, ...stringOperators] as const;\n\nexport type Operator = (typeof operators)[number];\n\nexport function createBuilder<Columns extends Record<string, AnyColumn>>(\n  columns: Columns,\n): ConditionBuilder<Columns> {\n  function col(name: keyof Columns) {\n    const out = columns[name];\n    if (!out) {\n      throw new Error(`Invalid column name ${String(name)}`);\n    }\n\n    return out;\n  }\n\n  const builder: ConditionBuilder<Columns> = (...args: [string, Operator, unknown] | [string]) => {\n    if (args.length === 3) {\n      const [a, operator, b] = args;\n\n      if (!operators.includes(operator)) {\n        throw new Error(`Unsupported operator: ${operator}`);\n      }\n\n      return {\n        type: \"compare\",\n        a: col(a),\n        b,\n        operator,\n      };\n    }\n\n    return {\n      type: \"compare\",\n      a: col(args[0]),\n      operator: \"=\",\n      b: true,\n    };\n  };\n\n  builder.isNull = (a) => builder(a, \"is\", null);\n  builder.isNotNull = (a) => builder(a, \"is not\", null);\n  builder.not = (condition) => {\n    if (typeof condition === \"boolean\") {\n      return !condition;\n    }\n\n    return {\n      type: \"not\",\n      item: condition,\n    };\n  };\n\n  builder.or = (...conditions) => {\n    const out = {\n      type: \"or\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        return true;\n      }\n      if (item === false) {\n        continue;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return false;\n    }\n    return out;\n  };\n\n  builder.and = (...conditions) => {\n    const out = {\n      type: \"and\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        continue;\n      }\n      if (item === false) {\n        return false;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return true;\n    }\n    return out;\n  };\n\n  return builder;\n}\n\nexport function buildCondition<T, Columns extends Record<string, AnyColumn>>(\n  columns: Columns,\n  input: (builder: ConditionBuilder<Columns>) => T,\n): T {\n  return input(createBuilder(columns));\n}\n\n/**\n * Create a ConditionBuilder that only allows comparisons on indexed columns.\n * Used in Unit of Work to ensure queries can leverage indexes for optimal performance.\n *\n * @param columns - The full set of columns from the table\n * @param indexedColumnNames - Set of column names that are part of indexes\n * @returns A ConditionBuilder restricted to indexed columns only\n *\n * @example\n * ```ts\n * const builder = createIndexedBuilder(\n *   table.columns,\n *   new Set([\"id\", \"userId\", \"createdAt\"])\n * );\n * const condition = builder(\"userId\", \"=\", \"123\");\n * ```\n */\nexport function createIndexedBuilder<Columns extends Record<string, AnyColumn>>(\n  columns: Columns,\n  indexedColumnNames: Set<string>,\n): ConditionBuilder<Columns> {\n  function col(name: keyof Columns) {\n    const columnName = String(name);\n\n    if (!indexedColumnNames.has(columnName)) {\n      throw new Error(\n        `Column \"${columnName}\" is not indexed. Only indexed columns can be used in Unit of Work queries. ` +\n          `Available indexed columns: ${Array.from(indexedColumnNames).join(\", \")}`,\n      );\n    }\n\n    const out = columns[name];\n    if (!out) {\n      throw new Error(`Invalid column name ${columnName}`);\n    }\n\n    return out;\n  }\n\n  const builder: ConditionBuilder<Columns> = (...args: [string, Operator, unknown] | [string]) => {\n    if (args.length === 3) {\n      const [a, operator, b] = args;\n\n      if (!operators.includes(operator)) {\n        throw new Error(`Unsupported operator: ${operator}`);\n      }\n\n      return {\n        type: \"compare\",\n        a: col(a),\n        b,\n        operator,\n      };\n    }\n\n    return {\n      type: \"compare\",\n      a: col(args[0]),\n      operator: \"=\",\n      b: true,\n    };\n  };\n\n  builder.isNull = (a) => builder(a, \"is\", null);\n  builder.isNotNull = (a) => builder(a, \"is not\", null);\n  builder.not = (condition) => {\n    if (typeof condition === \"boolean\") {\n      return !condition;\n    }\n\n    return {\n      type: \"not\",\n      item: condition,\n    };\n  };\n\n  builder.or = (...conditions) => {\n    const out = {\n      type: \"or\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        return true;\n      }\n      if (item === false) {\n        continue;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return false;\n    }\n    return out;\n  };\n\n  builder.and = (...conditions) => {\n    const out = {\n      type: \"and\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        continue;\n      }\n      if (item === false) {\n        return false;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return true;\n    }\n    return out;\n  };\n\n  return builder;\n}\n"],"mappings":";AA2DA,MAAM,kBAAkB;CACtB;CACA;CACA;CAEA;CACA;CACA;CAED;AAED,MAAM,iBAAiB,CAAC,MAAM,SAAS;AAEvC,MAAM,iBAAiB;CAAC;CAAK;CAAM;CAAK;CAAM;CAAK;CAAM;CAAM;CAAS;AAKxE,MAAa,YAAY;CAAC,GAAG;CAAgB,GAAG;CAAgB,GAAG;CAAgB;AAInF,SAAgB,cACd,SAC2B;CAC3B,SAAS,IAAI,MAAqB;EAChC,MAAM,MAAM,QAAQ;AACpB,MAAI,CAAC,IACH,OAAM,IAAI,MAAM,uBAAuB,OAAO,KAAK,GAAG;AAGxD,SAAO;;CAGT,MAAMA,WAAsC,GAAG,SAAiD;AAC9F,MAAI,KAAK,WAAW,GAAG;GACrB,MAAM,CAAC,GAAG,UAAU,KAAK;AAEzB,OAAI,CAAC,UAAU,SAAS,SAAS,CAC/B,OAAM,IAAI,MAAM,yBAAyB,WAAW;AAGtD,UAAO;IACL,MAAM;IACN,GAAG,IAAI,EAAE;IACT;IACA;IACD;;AAGH,SAAO;GACL,MAAM;GACN,GAAG,IAAI,KAAK,GAAG;GACf,UAAU;GACV,GAAG;GACJ;;AAGH,SAAQ,UAAU,MAAM,QAAQ,GAAG,MAAM,KAAK;AAC9C,SAAQ,aAAa,MAAM,QAAQ,GAAG,UAAU,KAAK;AACrD,SAAQ,OAAO,cAAc;AAC3B,MAAI,OAAO,cAAc,UACvB,QAAO,CAAC;AAGV,SAAO;GACL,MAAM;GACN,MAAM;GACP;;AAGH,SAAQ,MAAM,GAAG,eAAe;EAC9B,MAAM,MAAM;GACV,MAAM;GACN,OAAO,EAAE;GACV;AAED,OAAK,MAAM,QAAQ,YAAY;AAC7B,OAAI,SAAS,KACX,QAAO;AAET,OAAI,SAAS,MACX;AAGF,OAAI,MAAM,KAAK,KAAK;;AAGtB,MAAI,IAAI,MAAM,WAAW,EACvB,QAAO;AAET,SAAO;;AAGT,SAAQ,OAAO,GAAG,eAAe;EAC/B,MAAM,MAAM;GACV,MAAM;GACN,OAAO,EAAE;GACV;AAED,OAAK,MAAM,QAAQ,YAAY;AAC7B,OAAI,SAAS,KACX;AAEF,OAAI,SAAS,MACX,QAAO;AAGT,OAAI,MAAM,KAAK,KAAK;;AAGtB,MAAI,IAAI,MAAM,WAAW,EACvB,QAAO;AAET,SAAO;;AAGT,QAAO;;AAGT,SAAgB,eACd,SACA,OACG;AACH,QAAO,MAAM,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"condition-builder.js","names":["builder: ConditionBuilder<Columns>"],"sources":["../../src/query/condition-builder.ts"],"sourcesContent":["import type { AnyColumn, FragnoId, IdColumn } from \"../schema/create\";\nimport { dbInterval, dbNow, type DbInterval, type DbIntervalInput, type DbNow } from \"./db-now\";\n\nexport type ConditionType = \"compare\" | \"and\" | \"or\" | \"not\";\n\nexport type Condition =\n  | {\n      type: \"compare\";\n      a: AnyColumn;\n      operator: Operator;\n      b: AnyColumn | unknown | null;\n    }\n  | {\n      type: \"or\" | \"and\";\n      items: Condition[];\n    }\n  | {\n      type: \"not\";\n      item: Condition;\n    };\n\n// TODO: we temporarily dropped support for comparing against another column, because Prisma ORM still have problems with it.\n\n/**\n * Helper type that allows FragnoId for ID columns and reference columns (bigint).\n * Used in ConditionBuilder to accept FragnoId values in where conditions.\n */\ntype AcceptsFragnoId<T extends AnyColumn> = T extends IdColumn\n  ? T[\"$in\"] | FragnoId\n  : T[\"$in\"] extends bigint\n    ? T[\"$in\"] | FragnoId\n    : T[\"$in\"];\n\nexport type ConditionBuilder<Columns extends Record<string, AnyColumn>> = {\n  <ColName extends keyof Columns>(\n    a: ColName,\n    operator: (typeof valueOperators)[number] | (typeof stringOperators)[number],\n    b: AcceptsFragnoId<Columns[ColName]> | null,\n  ): Condition;\n\n  <ColName extends keyof Columns>(\n    a: ColName,\n    operator: (typeof arrayOperators)[number],\n    b: AcceptsFragnoId<Columns[ColName]>[],\n  ): Condition;\n\n  /**\n   * Boolean values\n   */\n  <ColName extends keyof Columns>(a: ColName): Condition;\n\n  and: (...v: (Condition | boolean)[]) => Condition | boolean;\n  or: (...v: (Condition | boolean)[]) => Condition | boolean;\n  not: (v: Condition | boolean) => Condition | boolean;\n\n  isNull: (a: keyof Columns) => Condition;\n  isNotNull: (a: keyof Columns) => Condition;\n  now: () => DbNow;\n  interval: (input: DbIntervalInput) => DbInterval;\n};\n\n// replacement for `like` (Prisma doesn't support `like`)\nconst stringOperators = [\n  \"contains\",\n  \"starts with\",\n  \"ends with\",\n\n  \"not contains\",\n  \"not starts with\",\n  \"not ends with\",\n  // excluded `regexp` since MSSQL doesn't support it, may re-consider\n] as const;\n\nconst arrayOperators = [\"in\", \"not in\"] as const;\n\nconst valueOperators = [\"=\", \"!=\", \">\", \">=\", \"<\", \"<=\", \"is\", \"is not\"] as const;\n\n// JSON specific operators are not included, some databases don't support them\n// `match` requires additional extensions & configurations on SQLite and PostgreSQL\n// MySQL & SQLite requires workarounds to support `ilike`\nexport const operators = [...valueOperators, ...arrayOperators, ...stringOperators] as const;\n\nexport type Operator = (typeof operators)[number];\n\nexport function createBuilder<Columns extends Record<string, AnyColumn>>(\n  columns: Columns,\n): ConditionBuilder<Columns> {\n  function col(name: keyof Columns) {\n    const out = columns[name];\n    if (!out) {\n      throw new Error(`Invalid column name ${String(name)}`);\n    }\n\n    return out;\n  }\n\n  const builder: ConditionBuilder<Columns> = (...args: [string, Operator, unknown] | [string]) => {\n    if (args.length === 3) {\n      const [a, operator, b] = args;\n\n      if (!operators.includes(operator)) {\n        throw new Error(`Unsupported operator: ${operator}`);\n      }\n\n      return {\n        type: \"compare\",\n        a: col(a),\n        b,\n        operator,\n      };\n    }\n\n    return {\n      type: \"compare\",\n      a: col(args[0]),\n      operator: \"=\",\n      b: true,\n    };\n  };\n\n  builder.isNull = (a) => builder(a, \"is\", null);\n  builder.isNotNull = (a) => builder(a, \"is not\", null);\n  builder.now = () => dbNow();\n  builder.interval = (input) => dbInterval(input);\n  builder.not = (condition) => {\n    if (typeof condition === \"boolean\") {\n      return !condition;\n    }\n\n    return {\n      type: \"not\",\n      item: condition,\n    };\n  };\n\n  builder.or = (...conditions) => {\n    const out = {\n      type: \"or\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        return true;\n      }\n      if (item === false) {\n        continue;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return false;\n    }\n    return out;\n  };\n\n  builder.and = (...conditions) => {\n    const out = {\n      type: \"and\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        continue;\n      }\n      if (item === false) {\n        return false;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return true;\n    }\n    return out;\n  };\n\n  return builder;\n}\n\nexport function buildCondition<T, Columns extends Record<string, AnyColumn>>(\n  columns: Columns,\n  input: (builder: ConditionBuilder<Columns>) => T,\n): T {\n  return input(createBuilder(columns));\n}\n\n/**\n * Create a ConditionBuilder that only allows comparisons on indexed columns.\n * Used in Unit of Work to ensure queries can leverage indexes for optimal performance.\n *\n * @param columns - The full set of columns from the table\n * @param indexedColumnNames - Set of column names that are part of indexes\n * @returns A ConditionBuilder restricted to indexed columns only\n *\n * @example\n * ```ts\n * const builder = createIndexedBuilder(\n *   table.columns,\n *   new Set([\"id\", \"userId\", \"createdAt\"])\n * );\n * const condition = builder(\"userId\", \"=\", \"123\");\n * ```\n */\nexport function createIndexedBuilder<Columns extends Record<string, AnyColumn>>(\n  columns: Columns,\n  indexedColumnNames: Set<string>,\n): ConditionBuilder<Columns> {\n  function col(name: keyof Columns) {\n    const columnName = String(name);\n\n    if (!indexedColumnNames.has(columnName)) {\n      throw new Error(\n        `Column \"${columnName}\" is not indexed. Only indexed columns can be used in Unit of Work queries. ` +\n          `Available indexed columns: ${Array.from(indexedColumnNames).join(\", \")}`,\n      );\n    }\n\n    const out = columns[name];\n    if (!out) {\n      throw new Error(`Invalid column name ${columnName}`);\n    }\n\n    return out;\n  }\n\n  const builder: ConditionBuilder<Columns> = (...args: [string, Operator, unknown] | [string]) => {\n    if (args.length === 3) {\n      const [a, operator, b] = args;\n\n      if (!operators.includes(operator)) {\n        throw new Error(`Unsupported operator: ${operator}`);\n      }\n\n      return {\n        type: \"compare\",\n        a: col(a),\n        b,\n        operator,\n      };\n    }\n\n    return {\n      type: \"compare\",\n      a: col(args[0]),\n      operator: \"=\",\n      b: true,\n    };\n  };\n\n  builder.isNull = (a) => builder(a, \"is\", null);\n  builder.isNotNull = (a) => builder(a, \"is not\", null);\n  builder.now = () => dbNow();\n  builder.interval = (input) => dbInterval(input);\n  builder.not = (condition) => {\n    if (typeof condition === \"boolean\") {\n      return !condition;\n    }\n\n    return {\n      type: \"not\",\n      item: condition,\n    };\n  };\n\n  builder.or = (...conditions) => {\n    const out = {\n      type: \"or\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        return true;\n      }\n      if (item === false) {\n        continue;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return false;\n    }\n    return out;\n  };\n\n  builder.and = (...conditions) => {\n    const out = {\n      type: \"and\",\n      items: [] as Condition[],\n    } as const;\n\n    for (const item of conditions) {\n      if (item === true) {\n        continue;\n      }\n      if (item === false) {\n        return false;\n      }\n\n      out.items.push(item);\n    }\n\n    if (out.items.length === 0) {\n      return true;\n    }\n    return out;\n  };\n\n  return builder;\n}\n"],"mappings":";;;AA8DA,MAAM,kBAAkB;CACtB;CACA;CACA;CAEA;CACA;CACA;CAED;AAED,MAAM,iBAAiB,CAAC,MAAM,SAAS;AAEvC,MAAM,iBAAiB;CAAC;CAAK;CAAM;CAAK;CAAM;CAAK;CAAM;CAAM;CAAS;AAKxE,MAAa,YAAY;CAAC,GAAG;CAAgB,GAAG;CAAgB,GAAG;CAAgB;AAInF,SAAgB,cACd,SAC2B;CAC3B,SAAS,IAAI,MAAqB;EAChC,MAAM,MAAM,QAAQ;AACpB,MAAI,CAAC,IACH,OAAM,IAAI,MAAM,uBAAuB,OAAO,KAAK,GAAG;AAGxD,SAAO;;CAGT,MAAMA,WAAsC,GAAG,SAAiD;AAC9F,MAAI,KAAK,WAAW,GAAG;GACrB,MAAM,CAAC,GAAG,UAAU,KAAK;AAEzB,OAAI,CAAC,UAAU,SAAS,SAAS,CAC/B,OAAM,IAAI,MAAM,yBAAyB,WAAW;AAGtD,UAAO;IACL,MAAM;IACN,GAAG,IAAI,EAAE;IACT;IACA;IACD;;AAGH,SAAO;GACL,MAAM;GACN,GAAG,IAAI,KAAK,GAAG;GACf,UAAU;GACV,GAAG;GACJ;;AAGH,SAAQ,UAAU,MAAM,QAAQ,GAAG,MAAM,KAAK;AAC9C,SAAQ,aAAa,MAAM,QAAQ,GAAG,UAAU,KAAK;AACrD,SAAQ,YAAY,OAAO;AAC3B,SAAQ,YAAY,UAAU,WAAW,MAAM;AAC/C,SAAQ,OAAO,cAAc;AAC3B,MAAI,OAAO,cAAc,UACvB,QAAO,CAAC;AAGV,SAAO;GACL,MAAM;GACN,MAAM;GACP;;AAGH,SAAQ,MAAM,GAAG,eAAe;EAC9B,MAAM,MAAM;GACV,MAAM;GACN,OAAO,EAAE;GACV;AAED,OAAK,MAAM,QAAQ,YAAY;AAC7B,OAAI,SAAS,KACX,QAAO;AAET,OAAI,SAAS,MACX;AAGF,OAAI,MAAM,KAAK,KAAK;;AAGtB,MAAI,IAAI,MAAM,WAAW,EACvB,QAAO;AAET,SAAO;;AAGT,SAAQ,OAAO,GAAG,eAAe;EAC/B,MAAM,MAAM;GACV,MAAM;GACN,OAAO,EAAE;GACV;AAED,OAAK,MAAM,QAAQ,YAAY;AAC7B,OAAI,SAAS,KACX;AAEF,OAAI,SAAS,MACX,QAAO;AAGT,OAAI,MAAM,KAAK,KAAK;;AAGtB,MAAI,IAAI,MAAM,WAAW,EACvB,QAAO;AAET,SAAO;;AAGT,QAAO;;AAGT,SAAgB,eACd,SACA,OACG;AACH,QAAO,MAAM,cAAc,QAAQ,CAAC"}

package/dist/query/cursor-client.d.ts

@@ -0,0 +1,105 @@
+import { AnyColumn } from "../schema/create.js";
+
+//#region src/query/cursor-client.d.ts
+
+/**
+ * Cursor object containing all information needed for pagination
+ */
+declare class Cursor {
+  #private;
+  constructor(data: {
+    indexName: string;
+    orderDirection: "asc" | "desc";
+    pageSize: number;
+    indexValues: Record<string, unknown>;
+  });
+  /**
+   * Get the index name being used for pagination
+   */
+  get indexName(): string;
+  /**
+   * Get the ordering direction
+   */
+  get orderDirection(): "asc" | "desc";
+  /**
+   * Get the page size
+   */
+  get pageSize(): number;
+  /**
+   * Get the cursor position values
+   */
+  get indexValues(): Record<string, unknown>;
+  /**
+   * Encode cursor to an opaque base64 string (safe to send to client)
+   */
+  encode(): string;
+}
+/**
+ * Result of a cursor-based query containing items and pagination cursor
+ */
+interface CursorResult<T> {
+  /**
+   * The query results
+   */
+  items: T[];
+  /**
+   * Cursor to fetch the next page (undefined if no more results)
+   */
+  cursor?: Cursor;
+  /**
+   * Whether there are more results available after this page
+   */
+  hasNextPage: boolean;
+}
+/**
+ * Cursor data structure for serialization
+ */
+interface CursorData {
+  v: number;
+  indexName: string;
+  orderDirection: "asc" | "desc";
+  pageSize: number;
+  indexValues: Record<string, unknown>;
+}
+/**
+ * Decode a base64 cursor string back to a Cursor object
+ *
+ * @param cursor - The base64-encoded cursor string
+ * @returns Decoded Cursor object
+ * @throws Error if cursor is invalid or malformed
+ *
+ * @example
+ * ```ts
+ * const cursor = decodeCursor("eyJpbmRleFZhbHVlcyI6e30sImRpcmVjdGlvbiI6ImZvcndhcmQifQ==");
+ * ```
+ */
+declare function decodeCursor(cursor: string): Cursor;
+/**
+ * Create a cursor from a record and pagination metadata
+ *
+ * @param record - The database record
+ * @param indexColumns - The columns that make up the index
+ * @param metadata - Pagination metadata (index name, order direction, page size)
+ * @returns Cursor object
+ *
+ * @example
+ * ```ts
+ * const cursor = createCursorFromRecord(
+ *   { id: "abc", name: "Alice", createdAt: 123 },
+ *   [table.columns.createdAt, table.columns.id],
+ *   {
+ *     indexName: "idx_created",
+ *     orderDirection: "asc",
+ *     pageSize: 10
+ *   }
+ * );
+ * ```
+ */
+declare function createCursorFromRecord(record: Record<string, unknown>, indexColumns: AnyColumn[], metadata: {
+  indexName: string;
+  orderDirection: "asc" | "desc";
+  pageSize: number;
+}): Cursor;
+//#endregion
+export { Cursor, CursorData, CursorResult, createCursorFromRecord, decodeCursor };
+//# sourceMappingURL=cursor-client.d.ts.map

package/dist/query/cursor-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-client.d.ts","names":[],"sources":["../../src/query/cursor-client.ts"],"sourcesContent":[],"mappings":";;;;;;AAKA;AAiEiB,cAjEJ,MAAA,CAiEgB;EAkBZ,CAAA,OAAA;EAkED,WAAA,CAAA,IAAY,EAAA;IA+DZ,SAAA,EAAA,MAAA;IACN,cAAA,EAAA,KAAA,GAAA,MAAA;IACM,QAAA,EAAA,MAAA;IAMb,WAAA,EAlNc,MAkNd,CAAA,MAAA,EAAA,OAAA,CAAA;EAAM,CAAA;;;;;;;;;;;;;;;;qBAlLY;;;;;;;;;UAuBJ;;;;SAIR;;;;WAIE;;;;;;;;;UAUM,UAAA;;;;;eAKF;;;;;;;;;;;;;;iBA6DC,YAAA,kBAA8B;;;;;;;;;;;;;;;;;;;;;;iBA+D9B,sBAAA,SACN,uCACM;;;;IAMb"}

package/dist/query/cursor-client.js

@@ -0,0 +1,165 @@
+//#region src/query/cursor-client.ts
+/**
+* Cursor object containing all information needed for pagination
+*/
+var Cursor = class {
+	#indexName;
+	#orderDirection;
+	#pageSize;
+	#indexValues;
+	constructor(data) {
+		this.#indexName = data.indexName;
+		this.#orderDirection = data.orderDirection;
+		this.#pageSize = data.pageSize;
+		this.#indexValues = data.indexValues;
+	}
+	/**
+	* Get the index name being used for pagination
+	*/
+	get indexName() {
+		return this.#indexName;
+	}
+	/**
+	* Get the ordering direction
+	*/
+	get orderDirection() {
+		return this.#orderDirection;
+	}
+	/**
+	* Get the page size
+	*/
+	get pageSize() {
+		return this.#pageSize;
+	}
+	/**
+	* Get the cursor position values
+	*/
+	get indexValues() {
+		return this.#indexValues;
+	}
+	/**
+	* Encode cursor to an opaque base64 string (safe to send to client)
+	*/
+	encode() {
+		assertSerializableIndexValues(this.#indexValues);
+		return encodeCursorData({
+			v: 1,
+			indexName: this.#indexName,
+			orderDirection: this.#orderDirection,
+			pageSize: this.#pageSize,
+			indexValues: this.#indexValues
+		});
+	}
+};
+const getBase64Helpers = () => {
+	const { btoa, atob, TextEncoder, TextDecoder } = globalThis;
+	if (!btoa || !atob) throw new Error("Base64 helpers (btoa/atob) are not available in this environment.");
+	if (!TextEncoder || !TextDecoder) throw new Error("TextEncoder/TextDecoder are required for cursor encoding.");
+	const encodeBase64 = (input) => {
+		const bytes = new TextEncoder().encode(input);
+		let binary = "";
+		for (const byte of bytes) binary += String.fromCharCode(byte);
+		return btoa(binary);
+	};
+	const decodeBase64 = (input) => {
+		const binary = atob(input);
+		const bytes = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+		return new TextDecoder().decode(bytes);
+	};
+	return {
+		encodeBase64,
+		decodeBase64
+	};
+};
+/**
+* Encode cursor data to a base64 string (internal)
+*/
+function encodeCursorData(data) {
+	let json;
+	try {
+		json = JSON.stringify(data);
+	} catch (error) {
+		throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : "malformed data"}`);
+	}
+	return getBase64Helpers().encodeBase64(json);
+}
+/**
+* Decode a base64 cursor string back to a Cursor object
+*
+* @param cursor - The base64-encoded cursor string
+* @returns Decoded Cursor object
+* @throws Error if cursor is invalid or malformed
+*
+* @example
+* ```ts
+* const cursor = decodeCursor("eyJpbmRleFZhbHVlcyI6e30sImRpcmVjdGlvbiI6ImZvcndhcmQifQ==");
+* ```
+*/
+function decodeCursor(cursor) {
+	try {
+		const json = getBase64Helpers().decodeBase64(cursor);
+		const data = JSON.parse(json);
+		const record = data;
+		if (!isPlainObject(data) || !isPlainObject(record["indexValues"]) || typeof record["indexName"] !== "string" || record["indexName"].length === 0 || typeof record["orderDirection"] !== "string" || record["orderDirection"] !== "asc" && record["orderDirection"] !== "desc" || typeof record["pageSize"] !== "number" || !Number.isFinite(record["pageSize"]) || !Number.isInteger(record["pageSize"]) || record["pageSize"] <= 0) throw new Error("Invalid cursor structure");
+		if (typeof record["v"] !== "number") throw new Error("Unsupported cursor version: missing. Only v1 is supported.");
+		const version = record["v"];
+		if (version !== 1) throw new Error(`Unsupported cursor version: ${version}. Only v1 is supported.`);
+		return new Cursor({
+			indexName: record["indexName"],
+			orderDirection: record["orderDirection"],
+			pageSize: record["pageSize"],
+			indexValues: record["indexValues"]
+		});
+	} catch (error) {
+		throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : "malformed data"}`);
+	}
+}
+/**
+* Create a cursor from a record and pagination metadata
+*
+* @param record - The database record
+* @param indexColumns - The columns that make up the index
+* @param metadata - Pagination metadata (index name, order direction, page size)
+* @returns Cursor object
+*
+* @example
+* ```ts
+* const cursor = createCursorFromRecord(
+*   { id: "abc", name: "Alice", createdAt: 123 },
+*   [table.columns.createdAt, table.columns.id],
+*   {
+*     indexName: "idx_created",
+*     orderDirection: "asc",
+*     pageSize: 10
+*   }
+* );
+* ```
+*/
+function createCursorFromRecord(record, indexColumns, metadata) {
+	const indexValues = {};
+	for (const col of indexColumns) {
+		const value = record[col.name];
+		if (value === void 0) throw new Error(`Record is missing value for index column "${col.name}".`);
+		indexValues[col.name] = value;
+	}
+	return new Cursor({
+		indexName: metadata.indexName,
+		orderDirection: metadata.orderDirection,
+		pageSize: metadata.pageSize,
+		indexValues
+	});
+}
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const assertSerializableIndexValues = (values) => {
+	for (const [key, value] of Object.entries(values)) {
+		if (value === void 0) throw new Error(`Cursor index value "${key}" is undefined.`);
+		if (typeof value === "number" && !Number.isFinite(value)) throw new Error(`Cursor index value "${key}" must be a finite number.`);
+		if (typeof value === "bigint") throw new Error(`Cursor index value "${key}" must not be a BigInt.`);
+		if (typeof value === "function" || typeof value === "symbol") throw new Error(`Cursor index value "${key}" is not JSON-serializable.`);
+	}
+};
+
+//#endregion
+export { Cursor, createCursorFromRecord, decodeCursor };
+//# sourceMappingURL=cursor-client.js.map

package/dist/query/cursor-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-client.js","names":["#indexName","#orderDirection","#pageSize","#indexValues","json: string","indexValues: Record<string, unknown>"],"sources":["../../src/query/cursor-client.ts"],"sourcesContent":["import type { AnyColumn } from \"../schema/create\";\n\n/**\n * Cursor object containing all information needed for pagination\n */\nexport class Cursor {\n  readonly #indexName: string;\n  readonly #orderDirection: \"asc\" | \"desc\";\n  readonly #pageSize: number;\n  readonly #indexValues: Record<string, unknown>;\n\n  constructor(data: {\n    indexName: string;\n    orderDirection: \"asc\" | \"desc\";\n    pageSize: number;\n    indexValues: Record<string, unknown>;\n  }) {\n    this.#indexName = data.indexName;\n    this.#orderDirection = data.orderDirection;\n    this.#pageSize = data.pageSize;\n    this.#indexValues = data.indexValues;\n  }\n\n  /**\n   * Get the index name being used for pagination\n   */\n  get indexName(): string {\n    return this.#indexName;\n  }\n\n  /**\n   * Get the ordering direction\n   */\n  get orderDirection(): \"asc\" | \"desc\" {\n    return this.#orderDirection;\n  }\n\n  /**\n   * Get the page size\n   */\n  get pageSize(): number {\n    return this.#pageSize;\n  }\n\n  /**\n   * Get the cursor position values\n   */\n  get indexValues(): Record<string, unknown> {\n    return this.#indexValues;\n  }\n\n  /**\n   * Encode cursor to an opaque base64 string (safe to send to client)\n   */\n  encode(): string {\n    assertSerializableIndexValues(this.#indexValues);\n    const data: CursorData = {\n      v: 1,\n      indexName: this.#indexName,\n      orderDirection: this.#orderDirection,\n      pageSize: this.#pageSize,\n      indexValues: this.#indexValues,\n    };\n    return encodeCursorData(data);\n  }\n}\n\n/**\n * Result of a cursor-based query containing items and pagination cursor\n */\nexport interface CursorResult<T> {\n  /**\n   * The query results\n   */\n  items: T[];\n  /**\n   * Cursor to fetch the next page (undefined if no more results)\n   */\n  cursor?: Cursor;\n  /**\n   * Whether there are more results available after this page\n   */\n  hasNextPage: boolean;\n}\n\n/**\n * Cursor data structure for serialization\n */\nexport interface CursorData {\n  v: number; // version\n  indexName: string;\n  orderDirection: \"asc\" | \"desc\";\n  pageSize: number;\n  indexValues: Record<string, unknown>;\n}\n\nconst getBase64Helpers = () => {\n  const { btoa, atob, TextEncoder, TextDecoder } = globalThis;\n\n  if (!btoa || !atob) {\n    throw new Error(\"Base64 helpers (btoa/atob) are not available in this environment.\");\n  }\n\n  if (!TextEncoder || !TextDecoder) {\n    throw new Error(\"TextEncoder/TextDecoder are required for cursor encoding.\");\n  }\n\n  const encodeBase64 = (input: string): string => {\n    const bytes = new TextEncoder().encode(input);\n    let binary = \"\";\n    for (const byte of bytes) {\n      binary += String.fromCharCode(byte);\n    }\n    return btoa(binary);\n  };\n\n  const decodeBase64 = (input: string): string => {\n    const binary = atob(input);\n    const bytes = new Uint8Array(binary.length);\n    for (let i = 0; i < binary.length; i += 1) {\n      bytes[i] = binary.charCodeAt(i);\n    }\n    return new TextDecoder().decode(bytes);\n  };\n\n  return { encodeBase64, decodeBase64 };\n};\n\n/**\n * Encode cursor data to a base64 string (internal)\n */\nfunction encodeCursorData(data: CursorData): string {\n  let json: string;\n  try {\n    json = JSON.stringify(data);\n  } catch (error) {\n    throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : \"malformed data\"}`);\n  }\n\n  return getBase64Helpers().encodeBase64(json);\n}\n\n/**\n * Decode a base64 cursor string back to a Cursor object\n *\n * @param cursor - The base64-encoded cursor string\n * @returns Decoded Cursor object\n * @throws Error if cursor is invalid or malformed\n *\n * @example\n * ```ts\n * const cursor = decodeCursor(\"eyJpbmRleFZhbHVlcyI6e30sImRpcmVjdGlvbiI6ImZvcndhcmQifQ==\");\n * ```\n */\nexport function decodeCursor(cursor: string): Cursor {\n  try {\n    const json = getBase64Helpers().decodeBase64(cursor);\n    const data = JSON.parse(json);\n    const record = data as Record<string, unknown>;\n\n    // Validate structure\n    if (\n      !isPlainObject(data) ||\n      !isPlainObject(record[\"indexValues\"]) ||\n      typeof record[\"indexName\"] !== \"string\" ||\n      record[\"indexName\"].length === 0 ||\n      typeof record[\"orderDirection\"] !== \"string\" ||\n      (record[\"orderDirection\"] !== \"asc\" && record[\"orderDirection\"] !== \"desc\") ||\n      typeof record[\"pageSize\"] !== \"number\" ||\n      !Number.isFinite(record[\"pageSize\"]) ||\n      !Number.isInteger(record[\"pageSize\"]) ||\n      record[\"pageSize\"] <= 0\n    ) {\n      throw new Error(\"Invalid cursor structure\");\n    }\n\n    // Only support v1\n    if (typeof record[\"v\"] !== \"number\") {\n      throw new Error(\"Unsupported cursor version: missing. Only v1 is supported.\");\n    }\n    const version = record[\"v\"];\n    if (version !== 1) {\n      throw new Error(`Unsupported cursor version: ${version}. Only v1 is supported.`);\n    }\n\n    return new Cursor({\n      indexName: record[\"indexName\"],\n      orderDirection: record[\"orderDirection\"],\n      pageSize: record[\"pageSize\"],\n      indexValues: record[\"indexValues\"],\n    });\n  } catch (error) {\n    throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : \"malformed data\"}`);\n  }\n}\n\n/**\n * Create a cursor from a record and pagination metadata\n *\n * @param record - The database record\n * @param indexColumns - The columns that make up the index\n * @param metadata - Pagination metadata (index name, order direction, page size)\n * @returns Cursor object\n *\n * @example\n * ```ts\n * const cursor = createCursorFromRecord(\n *   { id: \"abc\", name: \"Alice\", createdAt: 123 },\n *   [table.columns.createdAt, table.columns.id],\n *   {\n *     indexName: \"idx_created\",\n *     orderDirection: \"asc\",\n *     pageSize: 10\n *   }\n * );\n * ```\n */\nexport function createCursorFromRecord(\n  record: Record<string, unknown>,\n  indexColumns: AnyColumn[],\n  metadata: {\n    indexName: string;\n    orderDirection: \"asc\" | \"desc\";\n    pageSize: number;\n  },\n): Cursor {\n  const indexValues: Record<string, unknown> = {};\n\n  for (const col of indexColumns) {\n    const value = record[col.name];\n    if (value === undefined) {\n      throw new Error(`Record is missing value for index column \"${col.name}\".`);\n    }\n    indexValues[col.name] = value;\n  }\n\n  return new Cursor({\n    indexName: metadata.indexName,\n    orderDirection: metadata.orderDirection,\n    pageSize: metadata.pageSize,\n    indexValues,\n  });\n}\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\nconst assertSerializableIndexValues = (values: Record<string, unknown>): void => {\n  for (const [key, value] of Object.entries(values)) {\n    if (value === undefined) {\n      throw new Error(`Cursor index value \"${key}\" is undefined.`);\n    }\n    if (typeof value === \"number\" && !Number.isFinite(value)) {\n      throw new Error(`Cursor index value \"${key}\" must be a finite number.`);\n    }\n    if (typeof value === \"bigint\") {\n      throw new Error(`Cursor index value \"${key}\" must not be a BigInt.`);\n    }\n    if (typeof value === \"function\" || typeof value === \"symbol\") {\n      throw new Error(`Cursor index value \"${key}\" is not JSON-serializable.`);\n    }\n  }\n};\n"],"mappings":"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"}

package/dist/query/cursor.d.ts

@@ -1,5 +1,6 @@
 import { AnyColumn } from "../schema/create.js";
 import { DriverConfig } from "../adapters/generic-sql/driver-config.js";
+import { SQLiteStorageMode } from "../adapters/generic-sql/sqlite-storage.js";
 
 //#region src/query/cursor.d.ts
 
@@ -114,6 +115,7 @@ declare function createCursorFromRecord(record: Record<string, unknown>, indexCo
  * @param cursor - The cursor object
  * @param indexColumns - The columns that make up the index
  * @param driverConfig - The driver configuration
+ * @param sqliteStorageMode - Optional SQLite storage mode override
  * @returns Serialized values ready for database queries
  *
  * @example
@@ -125,7 +127,7 @@ declare function createCursorFromRecord(record: Record<string, unknown>, indexCo
  * );
  * ```
  */
-declare function serializeCursorValues(cursor: Cursor, indexColumns: AnyColumn[], driverConfig: DriverConfig): Record<string, unknown>;
+declare function serializeCursorValues(cursor: Cursor, indexColumns: AnyColumn[], driverConfig: DriverConfig, sqliteStorageMode?: SQLiteStorageMode): Record<string, unknown>;
 //#endregion
 export { Cursor, CursorData, CursorResult, createCursorFromRecord, decodeCursor, serializeCursorValues };
 //# sourceMappingURL=cursor.d.ts.map

package/dist/query/cursor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor.d.ts","names":[],"sources":["../../src/query/cursor.ts"],"sourcesContent":[],"mappings":";;;;;;;AAQA;AAgEiB,cAhEJ,MAAA,CAgEgB;EAkBZ,CAAA,OAAA;EAgCD,WAAA,CAAA,IAAY,EAAA;IA8DZ,SAAA,EAAA,MAAA;IACN,cAAA,EAAA,KAAA,GAAA,MAAA;IACM,QAAA,EAAA,MAAA;IAMb,WAAA,EA9Kc,MA8Kd,CAAA,MAAA,EAAA,OAAA,CAAA;EAAM,CAAA;EAuCO;;;EAGA,IAAA,SAAA,CAAA,CAAA,EAAA,MAAA;EACb;;;;;;;;;;;qBAzLkB;;;;;;;;;UAsBJ;;;;SAIR;;;;WAIE;;;;;;;;;UAUM,UAAA;;;;;eAKF;;;;;;;;;;;;;;iBA2BC,YAAA,kBAA8B;;;;;;;;;;;;;;;;;;;;;;iBA8D9B,sBAAA,SACN,uCACM;;;;IAMb;;;;;;;;;;;;;;;;;;;;;;;;;iBAuCa,qBAAA,SACN,sBACM,2BACA,eACb"}
+{"version":3,"file":"cursor.d.ts","names":[],"sources":["../../src/query/cursor.ts"],"sourcesContent":[],"mappings":";;;;;;;;AASA;AAiEiB,cAjEJ,MAAA,CAiEgB;EAkBZ,CAAA,OAAA;EAqCD,WAAA,CAAA,IAAY,EAAA;IAoEZ,SAAA,EAAA,MAAA;IACN,cAAA,EAAA,KAAA,GAAA,MAAA;IACM,QAAA,EAAA,MAAA;IAMb,WAAA,EA1Lc,MA0Ld,CAAA,MAAA,EAAA,OAAA,CAAA;EAAM,CAAA;EA+CO;;;EAGA,IAAA,SAAA,CAAA,CAAA,EAAA,MAAA;EACM;;;;;;;;;;;qBA7MD;;;;;;;;;UAuBJ;;;;SAIR;;;;WAIE;;;;;;;;;UAUM,UAAA;;;;;eAKF;;;;;;;;;;;;;;iBAgCC,YAAA,kBAA8B;;;;;;;;;;;;;;;;;;;;;;iBAoE9B,sBAAA,SACN,uCACM;;;;IAMb;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+Ca,qBAAA,SACN,sBACM,2BACA,kCACM,oBACnB"}

package/dist/query/cursor.js

@@ -44,6 +44,7 @@ var Cursor = class {
 	* Encode cursor to an opaque base64 string (safe to send to client)
 	*/
 	encode() {
+		assertSerializableIndexValues(this.#indexValues);
 		return encodeCursorData({
 			v: 1,
 			indexName: this.#indexName,
@@ -57,7 +58,12 @@ var Cursor = class {
 * Encode cursor data to a base64 string (internal)
 */
 function encodeCursorData(data) {
-	const json = JSON.stringify(data);
+	let json;
+	try {
+		json = JSON.stringify(data);
+	} catch (error) {
+		throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : "malformed data"}`);
+	}
 	if (typeof Buffer !== "undefined") return Buffer.from(json, "utf-8").toString("base64");
 	return btoa(json);
 }
@@ -79,14 +85,16 @@ function decodeCursor(cursor) {
 		if (typeof Buffer !== "undefined") json = Buffer.from(cursor, "base64").toString("utf-8");
 		else json = atob(cursor);
 		const data = JSON.parse(json);
-		if (!data || typeof data !== "object" || !data.indexValues || typeof data.indexValues !== "object" || typeof data.pageSize !== "number" || !data.indexName || !data.orderDirection || data.orderDirection !== "asc" && data.orderDirection !== "desc") throw new Error("Invalid cursor structure");
-		const version = typeof data.v === "number" ? data.v : 0;
+		const record = data;
+		if (!isPlainObject(data) || !isPlainObject(record["indexValues"]) || typeof record["indexName"] !== "string" || record["indexName"].length === 0 || typeof record["orderDirection"] !== "string" || record["orderDirection"] !== "asc" && record["orderDirection"] !== "desc" || typeof record["pageSize"] !== "number" || !Number.isFinite(record["pageSize"]) || !Number.isInteger(record["pageSize"]) || record["pageSize"] <= 0) throw new Error("Invalid cursor structure");
+		if (typeof record["v"] !== "number") throw new Error("Unsupported cursor version: missing. Only v1 is supported.");
+		const version = record["v"];
 		if (version !== 1) throw new Error(`Unsupported cursor version: ${version}. Only v1 is supported.`);
 		return new Cursor({
-			indexName: data.indexName,
-			orderDirection: data.orderDirection,
-			pageSize: data.pageSize,
-			indexValues: data.indexValues
+			indexName: record["indexName"],
+			orderDirection: record["orderDirection"],
+			pageSize: record["pageSize"],
+			indexValues: record["indexValues"]
 		});
 	} catch (error) {
 		throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : "malformed data"}`);
@@ -115,7 +123,12 @@ function decodeCursor(cursor) {
 */
 function createCursorFromRecord(record, indexColumns, metadata) {
 	const indexValues = {};
-	for (const col of indexColumns) indexValues[col.ormName] = record[col.ormName];
+	for (const col of indexColumns) {
+		const value = record[col.name];
+		if (value === void 0) throw new Error(`Record is missing value for index column "${col.name}".`);
+		const resolved = resolveFragnoIdValue(value, col);
+		indexValues[col.name] = typeof resolved === "bigint" ? resolved.toString() : resolved;
+	}
 	return new Cursor({
 		indexName: metadata.indexName,
 		orderDirection: metadata.orderDirection,
@@ -136,6 +149,7 @@ function createCursorFromRecord(record, indexColumns, metadata) {
 * @param cursor - The cursor object
 * @param indexColumns - The columns that make up the index
 * @param driverConfig - The driver configuration
+* @param sqliteStorageMode - Optional SQLite storage mode override
 * @returns Serialized values ready for database queries
 *
 * @example
@@ -147,18 +161,41 @@ function createCursorFromRecord(record, indexColumns, metadata) {
 * );
 * ```
 */
-function serializeCursorValues(cursor, indexColumns, driverConfig) {
-	const serializer = createSQLSerializer(driverConfig);
+function serializeCursorValues(cursor, indexColumns, driverConfig, sqliteStorageMode) {
+	const serializer = createSQLSerializer(driverConfig, sqliteStorageMode);
 	const serialized = {};
+	const missingColumns = [];
 	for (const col of indexColumns) {
-		const value = cursor.indexValues[col.ormName];
-		if (value !== void 0) {
-			const resolved = resolveFragnoIdValue(serializer.deserialize(value, col), col);
-			serialized[col.ormName] = serializer.serialize(resolved, col);
+		const value = cursor.indexValues[col.name];
+		if (value === void 0) {
+			missingColumns.push(col.name);
+			continue;
+		}
+		const resolvedDirect = resolveFragnoIdValue(value, col);
+		if (resolvedDirect !== value) {
+			serialized[col.name] = serializer.serialize(resolvedDirect, col);
+			continue;
 		}
+		const resolved = resolveFragnoIdValue(serializer.deserialize(value, col), col);
+		serialized[col.name] = serializer.serialize(resolved, col);
+	}
+	if (missingColumns.length > 0) {
+		const suffix = cursor.indexName ? ` for index "${cursor.indexName}"` : "";
+		const columns = missingColumns.map((name) => `"${name}"`).join(", ");
+		const plural = missingColumns.length === 1 ? "" : "s";
+		throw new Error(`Cursor is missing values for index column${plural} ${columns}${suffix}.`);
 	}
 	return serialized;
 }
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const assertSerializableIndexValues = (values) => {
+	for (const [key, value] of Object.entries(values)) {
+		if (value === void 0) throw new Error(`Cursor index value "${key}" is undefined.`);
+		if (typeof value === "number" && !Number.isFinite(value)) throw new Error(`Cursor index value "${key}" must be a finite number.`);
+		if (typeof value === "bigint") throw new Error(`Cursor index value "${key}" must not be a BigInt.`);
+		if (typeof value === "function" || typeof value === "symbol") throw new Error(`Cursor index value "${key}" is not JSON-serializable.`);
+	}
+};
 
 //#endregion
 export { Cursor, createCursorFromRecord, decodeCursor, serializeCursorValues };

package/dist/query/cursor.js.map

@@ -1 +1 @@
-{"version":3,"file":"cursor.js","names":["#indexName","#orderDirection","#pageSize","#indexValues","json: string","indexValues: Record<string, unknown>","serialized: Record<string, unknown>"],"sources":["../../src/query/cursor.ts"],"sourcesContent":["import type { AnyColumn } from \"../schema/create\";\nimport { createSQLSerializer } from \"./serialize/create-sql-serializer\";\nimport { resolveFragnoIdValue } from \"./value-encoding\";\nimport type { DriverConfig } from \"../adapters/generic-sql/driver-config\";\n\n/**\n * Cursor object containing all information needed for pagination\n */\nexport class Cursor {\n  readonly #indexName: string;\n  readonly #orderDirection: \"asc\" | \"desc\";\n  readonly #pageSize: number;\n  readonly #indexValues: Record<string, unknown>;\n\n  constructor(data: {\n    indexName: string;\n    orderDirection: \"asc\" | \"desc\";\n    pageSize: number;\n    indexValues: Record<string, unknown>;\n  }) {\n    this.#indexName = data.indexName;\n    this.#orderDirection = data.orderDirection;\n    this.#pageSize = data.pageSize;\n    this.#indexValues = data.indexValues;\n  }\n\n  /**\n   * Get the index name being used for pagination\n   */\n  get indexName(): string {\n    return this.#indexName;\n  }\n\n  /**\n   * Get the ordering direction\n   */\n  get orderDirection(): \"asc\" | \"desc\" {\n    return this.#orderDirection;\n  }\n\n  /**\n   * Get the page size\n   */\n  get pageSize(): number {\n    return this.#pageSize;\n  }\n\n  /**\n   * Get the cursor position values\n   */\n  get indexValues(): Record<string, unknown> {\n    return this.#indexValues;\n  }\n\n  /**\n   * Encode cursor to an opaque base64 string (safe to send to client)\n   */\n  encode(): string {\n    const data: CursorData = {\n      v: 1,\n      indexName: this.#indexName,\n      orderDirection: this.#orderDirection,\n      pageSize: this.#pageSize,\n      indexValues: this.#indexValues,\n    };\n    return encodeCursorData(data);\n  }\n}\n\n/**\n * Result of a cursor-based query containing items and pagination cursor\n */\nexport interface CursorResult<T> {\n  /**\n   * The query results\n   */\n  items: T[];\n  /**\n   * Cursor to fetch the next page (undefined if no more results)\n   */\n  cursor?: Cursor;\n  /**\n   * Whether there are more results available after this page\n   */\n  hasNextPage: boolean;\n}\n\n/**\n * Cursor data structure for serialization\n */\nexport interface CursorData {\n  v: number; // version\n  indexName: string;\n  orderDirection: \"asc\" | \"desc\";\n  pageSize: number;\n  indexValues: Record<string, unknown>;\n}\n\n/**\n * Encode cursor data to a base64 string (internal)\n */\nfunction encodeCursorData(data: CursorData): string {\n  const json = JSON.stringify(data);\n  // Use Buffer in Node.js or btoa in browsers\n  if (typeof Buffer !== \"undefined\") {\n    return Buffer.from(json, \"utf-8\").toString(\"base64\");\n  }\n  return btoa(json);\n}\n\n/**\n * Decode a base64 cursor string back to a Cursor object\n *\n * @param cursor - The base64-encoded cursor string\n * @returns Decoded Cursor object\n * @throws Error if cursor is invalid or malformed\n *\n * @example\n * ```ts\n * const cursor = decodeCursor(\"eyJpbmRleFZhbHVlcyI6e30sImRpcmVjdGlvbiI6ImZvcndhcmQifQ==\");\n * ```\n */\nexport function decodeCursor(cursor: string): Cursor {\n  try {\n    let json: string;\n    if (typeof Buffer !== \"undefined\") {\n      json = Buffer.from(cursor, \"base64\").toString(\"utf-8\");\n    } else {\n      json = atob(cursor);\n    }\n    const data = JSON.parse(json);\n\n    // Validate structure\n    if (\n      !data ||\n      typeof data !== \"object\" ||\n      !data.indexValues ||\n      typeof data.indexValues !== \"object\" ||\n      typeof data.pageSize !== \"number\" ||\n      !data.indexName ||\n      !data.orderDirection ||\n      (data.orderDirection !== \"asc\" && data.orderDirection !== \"desc\")\n    ) {\n      throw new Error(\"Invalid cursor structure\");\n    }\n\n    // Only support v1\n    const version = typeof data.v === \"number\" ? data.v : 0;\n    if (version !== 1) {\n      throw new Error(`Unsupported cursor version: ${version}. Only v1 is supported.`);\n    }\n\n    return new Cursor({\n      indexName: data.indexName,\n      orderDirection: data.orderDirection,\n      pageSize: data.pageSize,\n      indexValues: data.indexValues,\n    });\n  } catch (error) {\n    throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : \"malformed data\"}`);\n  }\n}\n\n/**\n * Create a cursor from a record and pagination metadata\n *\n * @param record - The database record\n * @param indexColumns - The columns that make up the index\n * @param metadata - Pagination metadata (index name, order direction, page size)\n * @returns Cursor object\n *\n * @example\n * ```ts\n * const cursor = createCursorFromRecord(\n *   { id: \"abc\", name: \"Alice\", createdAt: 123 },\n *   [table.columns.createdAt, table.columns.id],\n *   {\n *     indexName: \"idx_created\",\n *     orderDirection: \"asc\",\n *     pageSize: 10\n *   }\n * );\n * ```\n */\nexport function createCursorFromRecord(\n  record: Record<string, unknown>,\n  indexColumns: AnyColumn[],\n  metadata: {\n    indexName: string;\n    orderDirection: \"asc\" | \"desc\";\n    pageSize: number;\n  },\n): Cursor {\n  const indexValues: Record<string, unknown> = {};\n\n  for (const col of indexColumns) {\n    indexValues[col.ormName] = record[col.ormName];\n  }\n\n  return new Cursor({\n    indexName: metadata.indexName,\n    orderDirection: metadata.orderDirection,\n    pageSize: metadata.pageSize,\n    indexValues,\n  });\n}\n\n/**\n * Serialize cursor values for database queries\n *\n * Converts cursor values (which are in JSON-compatible format after decode)\n * to database format using the column serialization rules.\n *\n * This function performs a two-step process:\n * 1. Deserialize from JSON format to application format (e.g., ISO string → Date)\n * 2. Serialize from application format to database format (e.g., Date → driver format)\n *\n * @param cursor - The cursor object\n * @param indexColumns - The columns that make up the index\n * @param driverConfig - The driver configuration\n * @returns Serialized values ready for database queries\n *\n * @example\n * ```ts\n * const serialized = serializeCursorValues(\n *   cursor,\n *   [table.columns.createdAt],\n *   driverConfig\n * );\n * ```\n */\nexport function serializeCursorValues(\n  cursor: Cursor,\n  indexColumns: AnyColumn[],\n  driverConfig: DriverConfig,\n): Record<string, unknown> {\n  const serializer = createSQLSerializer(driverConfig);\n  const serialized: Record<string, unknown> = {};\n\n  for (const col of indexColumns) {\n    const value = cursor.indexValues[col.ormName];\n    if (value !== undefined) {\n      // First deserialize from JSON format to application format\n      // (e.g., \"2025-11-07T09:36:57.959Z\" string → Date object)\n      const deserialized = serializer.deserialize(value, col);\n      // Resolve FragnoId/FragnoReference to primitive values (if present)\n      const resolved = resolveFragnoIdValue(deserialized, col);\n      // Then serialize to database format\n      // (e.g., Date → database driver format)\n      serialized[col.ormName] = serializer.serialize(resolved, col);\n    }\n  }\n\n  return serialized;\n}\n"],"mappings":";;;;;;;AAQA,IAAa,SAAb,MAAoB;CAClB,CAASA;CACT,CAASC;CACT,CAASC;CACT,CAASC;CAET,YAAY,MAKT;AACD,QAAKH,YAAa,KAAK;AACvB,QAAKC,iBAAkB,KAAK;AAC5B,QAAKC,WAAY,KAAK;AACtB,QAAKC,cAAe,KAAK;;;;;CAM3B,IAAI,YAAoB;AACtB,SAAO,MAAKH;;;;;CAMd,IAAI,iBAAiC;AACnC,SAAO,MAAKC;;;;;CAMd,IAAI,WAAmB;AACrB,SAAO,MAAKC;;;;;CAMd,IAAI,cAAuC;AACzC,SAAO,MAAKC;;;;;CAMd,SAAiB;AAQf,SAAO,iBAPkB;GACvB,GAAG;GACH,WAAW,MAAKH;GAChB,gBAAgB,MAAKC;GACrB,UAAU,MAAKC;GACf,aAAa,MAAKC;GACnB,CAC4B;;;;;;AAoCjC,SAAS,iBAAiB,MAA0B;CAClD,MAAM,OAAO,KAAK,UAAU,KAAK;AAEjC,KAAI,OAAO,WAAW,YACpB,QAAO,OAAO,KAAK,MAAM,QAAQ,CAAC,SAAS,SAAS;AAEtD,QAAO,KAAK,KAAK;;;;;;;;;;;;;;AAenB,SAAgB,aAAa,QAAwB;AACnD,KAAI;EACF,IAAIC;AACJ,MAAI,OAAO,WAAW,YACpB,QAAO,OAAO,KAAK,QAAQ,SAAS,CAAC,SAAS,QAAQ;MAEtD,QAAO,KAAK,OAAO;EAErB,MAAM,OAAO,KAAK,MAAM,KAAK;AAG7B,MACE,CAAC,QACD,OAAO,SAAS,YAChB,CAAC,KAAK,eACN,OAAO,KAAK,gBAAgB,YAC5B,OAAO,KAAK,aAAa,YACzB,CAAC,KAAK,aACN,CAAC,KAAK,kBACL,KAAK,mBAAmB,SAAS,KAAK,mBAAmB,OAE1D,OAAM,IAAI,MAAM,2BAA2B;EAI7C,MAAM,UAAU,OAAO,KAAK,MAAM,WAAW,KAAK,IAAI;AACtD,MAAI,YAAY,EACd,OAAM,IAAI,MAAM,+BAA+B,QAAQ,yBAAyB;AAGlF,SAAO,IAAI,OAAO;GAChB,WAAW,KAAK;GAChB,gBAAgB,KAAK;GACrB,UAAU,KAAK;GACf,aAAa,KAAK;GACnB,CAAC;UACK,OAAO;AACd,QAAM,IAAI,MAAM,mBAAmB,iBAAiB,QAAQ,MAAM,UAAU,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;AAyBnG,SAAgB,uBACd,QACA,cACA,UAKQ;CACR,MAAMC,cAAuC,EAAE;AAE/C,MAAK,MAAM,OAAO,aAChB,aAAY,IAAI,WAAW,OAAO,IAAI;AAGxC,QAAO,IAAI,OAAO;EAChB,WAAW,SAAS;EACpB,gBAAgB,SAAS;EACzB,UAAU,SAAS;EACnB;EACD,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BJ,SAAgB,sBACd,QACA,cACA,cACyB;CACzB,MAAM,aAAa,oBAAoB,aAAa;CACpD,MAAMC,aAAsC,EAAE;AAE9C,MAAK,MAAM,OAAO,cAAc;EAC9B,MAAM,QAAQ,OAAO,YAAY,IAAI;AACrC,MAAI,UAAU,QAAW;GAKvB,MAAM,WAAW,qBAFI,WAAW,YAAY,OAAO,IAAI,EAEH,IAAI;AAGxD,cAAW,IAAI,WAAW,WAAW,UAAU,UAAU,IAAI;;;AAIjE,QAAO"}
+{"version":3,"file":"cursor.js","names":["#indexName","#orderDirection","#pageSize","#indexValues","json: string","indexValues: Record<string, unknown>","serialized: Record<string, unknown>","missingColumns: string[]"],"sources":["../../src/query/cursor.ts"],"sourcesContent":["import type { DriverConfig } from \"../adapters/generic-sql/driver-config\";\nimport type { SQLiteStorageMode } from \"../adapters/generic-sql/sqlite-storage\";\nimport type { AnyColumn } from \"../schema/create\";\nimport { createSQLSerializer } from \"./serialize/create-sql-serializer\";\nimport { resolveFragnoIdValue } from \"./value-encoding\";\n\n/**\n * Cursor object containing all information needed for pagination\n */\nexport class Cursor {\n  readonly #indexName: string;\n  readonly #orderDirection: \"asc\" | \"desc\";\n  readonly #pageSize: number;\n  readonly #indexValues: Record<string, unknown>;\n\n  constructor(data: {\n    indexName: string;\n    orderDirection: \"asc\" | \"desc\";\n    pageSize: number;\n    indexValues: Record<string, unknown>;\n  }) {\n    this.#indexName = data.indexName;\n    this.#orderDirection = data.orderDirection;\n    this.#pageSize = data.pageSize;\n    this.#indexValues = data.indexValues;\n  }\n\n  /**\n   * Get the index name being used for pagination\n   */\n  get indexName(): string {\n    return this.#indexName;\n  }\n\n  /**\n   * Get the ordering direction\n   */\n  get orderDirection(): \"asc\" | \"desc\" {\n    return this.#orderDirection;\n  }\n\n  /**\n   * Get the page size\n   */\n  get pageSize(): number {\n    return this.#pageSize;\n  }\n\n  /**\n   * Get the cursor position values\n   */\n  get indexValues(): Record<string, unknown> {\n    return this.#indexValues;\n  }\n\n  /**\n   * Encode cursor to an opaque base64 string (safe to send to client)\n   */\n  encode(): string {\n    assertSerializableIndexValues(this.#indexValues);\n    const data: CursorData = {\n      v: 1,\n      indexName: this.#indexName,\n      orderDirection: this.#orderDirection,\n      pageSize: this.#pageSize,\n      indexValues: this.#indexValues,\n    };\n    return encodeCursorData(data);\n  }\n}\n\n/**\n * Result of a cursor-based query containing items and pagination cursor\n */\nexport interface CursorResult<T> {\n  /**\n   * The query results\n   */\n  items: T[];\n  /**\n   * Cursor to fetch the next page (undefined if no more results)\n   */\n  cursor?: Cursor;\n  /**\n   * Whether there are more results available after this page\n   */\n  hasNextPage: boolean;\n}\n\n/**\n * Cursor data structure for serialization\n */\nexport interface CursorData {\n  v: number; // version\n  indexName: string;\n  orderDirection: \"asc\" | \"desc\";\n  pageSize: number;\n  indexValues: Record<string, unknown>;\n}\n\n/**\n * Encode cursor data to a base64 string (internal)\n */\nfunction encodeCursorData(data: CursorData): string {\n  let json: string;\n  try {\n    json = JSON.stringify(data);\n  } catch (error) {\n    throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : \"malformed data\"}`);\n  }\n  // Use Buffer in Node.js or btoa in browsers\n  if (typeof Buffer !== \"undefined\") {\n    return Buffer.from(json, \"utf-8\").toString(\"base64\");\n  }\n  return btoa(json);\n}\n\n/**\n * Decode a base64 cursor string back to a Cursor object\n *\n * @param cursor - The base64-encoded cursor string\n * @returns Decoded Cursor object\n * @throws Error if cursor is invalid or malformed\n *\n * @example\n * ```ts\n * const cursor = decodeCursor(\"eyJpbmRleFZhbHVlcyI6e30sImRpcmVjdGlvbiI6ImZvcndhcmQifQ==\");\n * ```\n */\nexport function decodeCursor(cursor: string): Cursor {\n  try {\n    let json: string;\n    if (typeof Buffer !== \"undefined\") {\n      json = Buffer.from(cursor, \"base64\").toString(\"utf-8\");\n    } else {\n      json = atob(cursor);\n    }\n    const data = JSON.parse(json);\n    const record = data as Record<string, unknown>;\n\n    // Validate structure\n    if (\n      !isPlainObject(data) ||\n      !isPlainObject(record[\"indexValues\"]) ||\n      typeof record[\"indexName\"] !== \"string\" ||\n      record[\"indexName\"].length === 0 ||\n      typeof record[\"orderDirection\"] !== \"string\" ||\n      (record[\"orderDirection\"] !== \"asc\" && record[\"orderDirection\"] !== \"desc\") ||\n      typeof record[\"pageSize\"] !== \"number\" ||\n      !Number.isFinite(record[\"pageSize\"]) ||\n      !Number.isInteger(record[\"pageSize\"]) ||\n      record[\"pageSize\"] <= 0\n    ) {\n      throw new Error(\"Invalid cursor structure\");\n    }\n\n    // Only support v1\n    if (typeof record[\"v\"] !== \"number\") {\n      throw new Error(\"Unsupported cursor version: missing. Only v1 is supported.\");\n    }\n    const version = record[\"v\"];\n    if (version !== 1) {\n      throw new Error(`Unsupported cursor version: ${version}. Only v1 is supported.`);\n    }\n\n    return new Cursor({\n      indexName: record[\"indexName\"],\n      orderDirection: record[\"orderDirection\"],\n      pageSize: record[\"pageSize\"],\n      indexValues: record[\"indexValues\"],\n    });\n  } catch (error) {\n    throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : \"malformed data\"}`);\n  }\n}\n\n/**\n * Create a cursor from a record and pagination metadata\n *\n * @param record - The database record\n * @param indexColumns - The columns that make up the index\n * @param metadata - Pagination metadata (index name, order direction, page size)\n * @returns Cursor object\n *\n * @example\n * ```ts\n * const cursor = createCursorFromRecord(\n *   { id: \"abc\", name: \"Alice\", createdAt: 123 },\n *   [table.columns.createdAt, table.columns.id],\n *   {\n *     indexName: \"idx_created\",\n *     orderDirection: \"asc\",\n *     pageSize: 10\n *   }\n * );\n * ```\n */\nexport function createCursorFromRecord(\n  record: Record<string, unknown>,\n  indexColumns: AnyColumn[],\n  metadata: {\n    indexName: string;\n    orderDirection: \"asc\" | \"desc\";\n    pageSize: number;\n  },\n): Cursor {\n  const indexValues: Record<string, unknown> = {};\n\n  for (const col of indexColumns) {\n    const value = record[col.name];\n    if (value === undefined) {\n      throw new Error(`Record is missing value for index column \"${col.name}\".`);\n    }\n    // Resolve FragnoId/FragnoReference to primitive values for cursor serialization.\n    const resolved = resolveFragnoIdValue(value, col);\n    // BigInt values are not JSON-serializable, so store them as strings.\n    indexValues[col.name] = typeof resolved === \"bigint\" ? resolved.toString() : resolved;\n  }\n\n  return new Cursor({\n    indexName: metadata.indexName,\n    orderDirection: metadata.orderDirection,\n    pageSize: metadata.pageSize,\n    indexValues,\n  });\n}\n\n/**\n * Serialize cursor values for database queries\n *\n * Converts cursor values (which are in JSON-compatible format after decode)\n * to database format using the column serialization rules.\n *\n * This function performs a two-step process:\n * 1. Deserialize from JSON format to application format (e.g., ISO string → Date)\n * 2. Serialize from application format to database format (e.g., Date → driver format)\n *\n * @param cursor - The cursor object\n * @param indexColumns - The columns that make up the index\n * @param driverConfig - The driver configuration\n * @param sqliteStorageMode - Optional SQLite storage mode override\n * @returns Serialized values ready for database queries\n *\n * @example\n * ```ts\n * const serialized = serializeCursorValues(\n *   cursor,\n *   [table.columns.createdAt],\n *   driverConfig\n * );\n * ```\n */\nexport function serializeCursorValues(\n  cursor: Cursor,\n  indexColumns: AnyColumn[],\n  driverConfig: DriverConfig,\n  sqliteStorageMode?: SQLiteStorageMode,\n): Record<string, unknown> {\n  const serializer = createSQLSerializer(driverConfig, sqliteStorageMode);\n  const serialized: Record<string, unknown> = {};\n  const missingColumns: string[] = [];\n\n  for (const col of indexColumns) {\n    const value = cursor.indexValues[col.name];\n    if (value === undefined) {\n      missingColumns.push(col.name);\n      continue;\n    }\n\n    // If the cursor value is already a FragnoId/FragnoReference, resolve it directly\n    // to avoid deserializing non-JSON objects.\n    const resolvedDirect = resolveFragnoIdValue(value, col);\n    if (resolvedDirect !== value) {\n      serialized[col.name] = serializer.serialize(resolvedDirect, col);\n      continue;\n    }\n\n    // First deserialize from JSON format to application format\n    // (e.g., \"2025-11-07T09:36:57.959Z\" string → Date object)\n    const deserialized = serializer.deserialize(value, col);\n    // Resolve FragnoId/FragnoReference to primitive values (if present)\n    const resolved = resolveFragnoIdValue(deserialized, col);\n    // Then serialize to database format\n    // (e.g., Date → database driver format)\n    serialized[col.name] = serializer.serialize(resolved, col);\n  }\n\n  if (missingColumns.length > 0) {\n    const suffix = cursor.indexName ? ` for index \"${cursor.indexName}\"` : \"\";\n    const columns = missingColumns.map((name) => `\"${name}\"`).join(\", \");\n    const plural = missingColumns.length === 1 ? \"\" : \"s\";\n    throw new Error(`Cursor is missing values for index column${plural} ${columns}${suffix}.`);\n  }\n\n  return serialized;\n}\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\nconst assertSerializableIndexValues = (values: Record<string, unknown>): void => {\n  for (const [key, value] of Object.entries(values)) {\n    if (value === undefined) {\n      throw new Error(`Cursor index value \"${key}\" is undefined.`);\n    }\n    if (typeof value === \"number\" && !Number.isFinite(value)) {\n      throw new Error(`Cursor index value \"${key}\" must be a finite number.`);\n    }\n    if (typeof value === \"bigint\") {\n      throw new Error(`Cursor index value \"${key}\" must not be a BigInt.`);\n    }\n    if (typeof value === \"function\" || typeof value === \"symbol\") {\n      throw new Error(`Cursor index value \"${key}\" is not JSON-serializable.`);\n    }\n  }\n};\n"],"mappings":"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"}

package/dist/query/db-now.d.ts

@@ -0,0 +1,22 @@
+//#region src/query/db-now.d.ts
+type DbInterval = {
+  tag: "db-interval";
+  ms: number;
+};
+type DbIntervalInput = number | {
+  ms?: number;
+  seconds?: number;
+  minutes?: number;
+  hours?: number;
+  days?: number;
+};
+type DbNow = {
+  tag: "db-now";
+  offsetMs?: number;
+  plus: (interval: DbInterval | DbIntervalInput) => DbNow;
+};
+declare const dbNow: () => DbNow;
+declare const dbInterval: (input: DbIntervalInput) => DbInterval;
+//#endregion
+export { DbInterval, DbIntervalInput, DbNow, dbInterval, dbNow };
+//# sourceMappingURL=db-now.d.ts.map

package/dist/query/db-now.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-now.d.ts","names":[],"sources":["../../src/query/db-now.ts"],"sourcesContent":[],"mappings":";KAAY,UAAA;EAAA,GAAA,EAAA,aAAU;EAEV,EAAA,EAAA,MAAA;AAUZ,CAAA;AAGmB,KAbP,eAAA,GAaO,MAAA,GAAA;EAAa,EAAA,CAAA,EAAA,MAAA;EAAoB,OAAA,CAAA,EAAA,MAAA;EAAK,OAAA,CAAA,EAAA,MAAA;EA2C5C,KAAA,CAAA,EAAmC,MAAA;EAQnC,IAAA,CAAA,EAAA,MAGX;;KAzDU,KAAA;;;mBAGO,aAAa,oBAAoB;;cA2CvC,aAAY;cAQZ,oBAAqB,oBAAkB"}

package/dist/query/db-now.js

@@ -0,0 +1,35 @@
+//#region src/query/db-now.ts
+const toIntervalMs = (input) => {
+	if (typeof input === "number") {
+		if (!Number.isFinite(input)) throw new Error("DB_INTERVAL_INVALID");
+		return input;
+	}
+	if (typeof input === "object" && input !== null && "tag" in input) {
+		const tagged = input;
+		if (tagged.tag === "db-interval") {
+			if (!Number.isFinite(tagged.ms)) throw new Error("DB_INTERVAL_INVALID");
+			return tagged.ms;
+		}
+		throw new Error("DB_INTERVAL_INVALID");
+	}
+	const interval = input;
+	const totalMs = (interval.ms ?? 0) + (interval.seconds ?? 0) * 1e3 + (interval.minutes ?? 0) * 6e4 + (interval.hours ?? 0) * 36e5 + (interval.days ?? 0) * 864e5;
+	if (!Number.isFinite(totalMs)) throw new Error("DB_INTERVAL_INVALID");
+	return totalMs;
+};
+const createDbNow = (offsetMs = 0) => ({
+	tag: "db-now",
+	offsetMs,
+	plus: (interval) => createDbNow(offsetMs + toIntervalMs(interval))
+});
+const dbNow = () => createDbNow(0);
+const isDbNow = (value) => typeof value === "object" && value !== null && value.tag === "db-now";
+const getDbNowOffsetMs = (value) => typeof value.offsetMs === "number" ? value.offsetMs : 0;
+const dbInterval = (input) => ({
+	tag: "db-interval",
+	ms: toIntervalMs(input)
+});
+
+//#endregion
+export { dbInterval, dbNow, getDbNowOffsetMs, isDbNow };
+//# sourceMappingURL=db-now.js.map

package/dist/query/db-now.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-now.js","names":[],"sources":["../../src/query/db-now.ts"],"sourcesContent":["export type DbInterval = { tag: \"db-interval\"; ms: number };\n\nexport type DbIntervalInput =\n  | number\n  | {\n      ms?: number;\n      seconds?: number;\n      minutes?: number;\n      hours?: number;\n      days?: number;\n    };\n\nexport type DbNow = {\n  tag: \"db-now\";\n  offsetMs?: number;\n  plus: (interval: DbInterval | DbIntervalInput) => DbNow;\n};\n\nconst toIntervalMs = (input: DbInterval | DbIntervalInput): number => {\n  if (typeof input === \"number\") {\n    if (!Number.isFinite(input)) {\n      throw new Error(\"DB_INTERVAL_INVALID\");\n    }\n    return input;\n  }\n\n  if (typeof input === \"object\" && input !== null && \"tag\" in input) {\n    const tagged = input as DbInterval;\n    if (tagged.tag === \"db-interval\") {\n      if (!Number.isFinite(tagged.ms)) {\n        throw new Error(\"DB_INTERVAL_INVALID\");\n      }\n      return tagged.ms;\n    }\n    throw new Error(\"DB_INTERVAL_INVALID\");\n  }\n\n  const interval = input as Exclude<DbIntervalInput, number>;\n  const totalMs =\n    (interval.ms ?? 0) +\n    (interval.seconds ?? 0) * 1000 +\n    (interval.minutes ?? 0) * 60_000 +\n    (interval.hours ?? 0) * 3_600_000 +\n    (interval.days ?? 0) * 86_400_000;\n\n  if (!Number.isFinite(totalMs)) {\n    throw new Error(\"DB_INTERVAL_INVALID\");\n  }\n\n  return totalMs;\n};\n\nconst createDbNow = (offsetMs = 0): DbNow => ({\n  tag: \"db-now\",\n  offsetMs,\n  plus: (interval) => createDbNow(offsetMs + toIntervalMs(interval)),\n});\n\nexport const dbNow = (): DbNow => createDbNow(0);\n\nexport const isDbNow = (value: unknown): value is DbNow =>\n  typeof value === \"object\" && value !== null && (value as { tag?: string }).tag === \"db-now\";\n\nexport const getDbNowOffsetMs = (value: DbNow): number =>\n  typeof value.offsetMs === \"number\" ? value.offsetMs : 0;\n\nexport const dbInterval = (input: DbIntervalInput): DbInterval => ({\n  tag: \"db-interval\",\n  ms: toIntervalMs(input),\n});\n\nexport const isDbInterval = (value: unknown): value is DbInterval =>\n  typeof value === \"object\" && value !== null && (value as { tag?: string }).tag === \"db-interval\";\n"],"mappings":";AAkBA,MAAM,gBAAgB,UAAgD;AACpE,KAAI,OAAO,UAAU,UAAU;AAC7B,MAAI,CAAC,OAAO,SAAS,MAAM,CACzB,OAAM,IAAI,MAAM,sBAAsB;AAExC,SAAO;;AAGT,KAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,SAAS,OAAO;EACjE,MAAM,SAAS;AACf,MAAI,OAAO,QAAQ,eAAe;AAChC,OAAI,CAAC,OAAO,SAAS,OAAO,GAAG,CAC7B,OAAM,IAAI,MAAM,sBAAsB;AAExC,UAAO,OAAO;;AAEhB,QAAM,IAAI,MAAM,sBAAsB;;CAGxC,MAAM,WAAW;CACjB,MAAM,WACH,SAAS,MAAM,MACf,SAAS,WAAW,KAAK,OACzB,SAAS,WAAW,KAAK,OACzB,SAAS,SAAS,KAAK,QACvB,SAAS,QAAQ,KAAK;AAEzB,KAAI,CAAC,OAAO,SAAS,QAAQ,CAC3B,OAAM,IAAI,MAAM,sBAAsB;AAGxC,QAAO;;AAGT,MAAM,eAAe,WAAW,OAAc;CAC5C,KAAK;CACL;CACA,OAAO,aAAa,YAAY,WAAW,aAAa,SAAS,CAAC;CACnE;AAED,MAAa,cAAqB,YAAY,EAAE;AAEhD,MAAa,WAAW,UACtB,OAAO,UAAU,YAAY,UAAU,QAAS,MAA2B,QAAQ;AAErF,MAAa,oBAAoB,UAC/B,OAAO,MAAM,aAAa,WAAW,MAAM,WAAW;AAExD,MAAa,cAAc,WAAwC;CACjE,KAAK;CACL,IAAI,aAAa,MAAM;CACxB"}