@geekmidas/db 0.1.0 → 0.2.0

package/dist/kysely/pagination.cjs

@@ -0,0 +1,83 @@
+
+//#region src/kysely/pagination.ts
+/**
+* Sort direction for cursor-based pagination.
+*/
+let Direction = /* @__PURE__ */ function(Direction$1) {
+	Direction$1["Asc"] = "asc";
+	Direction$1["Desc"] = "desc";
+	return Direction$1;
+}({});
+/**
+* Generic paginated search function that handles:
+* - Total count calculation
+* - Cursor-based pagination
+* - Fetching one extra row to determine hasMore
+* - Mapping rows to output format
+*
+* @example
+* ```typescript
+* const result = await paginatedSearch({
+*   query: db.selectFrom('users').selectAll(),
+*   cursor: previousCursor,
+*   limit: 20,
+*   mapRow: (row) => ({ id: row.id, name: row.name }),
+*   cursorField: 'id',
+*   cursorDirection: Direction.Asc,
+* });
+* ```
+*/
+async function paginatedSearch({ query, cursor, limit = 20, mapRow, cursorField = "id", cursorDirection = Direction.Asc }) {
+	const countResult = await query.clearSelect().clearOrderBy().select((eb) => eb.fn.countAll().as("count")).executeTakeFirstOrThrow();
+	const count = countResult.count;
+	let paginatedQuery = query;
+	if (cursor) {
+		const operator = cursorDirection === Direction.Asc ? ">" : "<";
+		paginatedQuery = paginatedQuery.where(cursorField, operator, cursor);
+	}
+	const data = await paginatedQuery.orderBy(cursorField, cursorDirection).limit(limit + 1).execute();
+	const hasMore = data.length > limit;
+	const rows = hasMore ? data.slice(0, limit) : data;
+	const lastRow = rows[rows.length - 1];
+	const nextCursor = hasMore && lastRow ? String(lastRow[cursorField]) : void 0;
+	const items = await Promise.all(rows.map(mapRow));
+	return {
+		items,
+		pagination: {
+			total: Number(count),
+			hasMore,
+			cursor: nextCursor
+		}
+	};
+}
+/**
+* Encode a cursor value for safe URL transmission.
+* Supports various types: string, number, Date, etc.
+*/
+function encodeCursor(value) {
+	const payload = {
+		v: value instanceof Date ? value.toISOString() : value,
+		t: value instanceof Date ? "date" : typeof value
+	};
+	return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+/**
+* Decode a cursor string back to its original value.
+*/
+function decodeCursor(cursor) {
+	try {
+		const json = Buffer.from(cursor, "base64url").toString("utf-8");
+		const payload = JSON.parse(json);
+		if (payload.t === "date") return new Date(payload.v);
+		return payload.v;
+	} catch {
+		throw new Error("Invalid cursor format");
+	}
+}
+
+//#endregion
+exports.Direction = Direction;
+exports.decodeCursor = decodeCursor;
+exports.encodeCursor = encodeCursor;
+exports.paginatedSearch = paginatedSearch;
+//# sourceMappingURL=pagination.cjs.map

package/dist/kysely/pagination.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.cjs","names":["value: unknown","cursor: string"],"sources":["../../src/kysely/pagination.ts"],"sourcesContent":["import type { SelectQueryBuilder } from 'kysely';\n\n/**\n * Sort direction for cursor-based pagination.\n */\nexport enum Direction {\n  Asc = 'asc',\n  Desc = 'desc',\n}\n\n/**\n * Result of a paginated query.\n */\nexport interface PaginationResult<TItem> {\n  items: TItem[];\n  pagination: {\n    total: number;\n    hasMore: boolean;\n    cursor?: string;\n  };\n}\n\n/**\n * Options for paginated search.\n */\nexport interface PaginatedSearchOptions<\n  TRow,\n  TMapRow extends (row: TRow) => unknown,\n> {\n  /** The base Kysely query to paginate */\n  query: SelectQueryBuilder<any, any, TRow>;\n  /** Cursor value for pagination (value of cursorField from previous page) */\n  cursor?: string;\n  /** Maximum number of items per page (default: 20) */\n  limit?: number;\n  /** Function to transform each row to the output format */\n  mapRow: TMapRow;\n  /** Field to use for cursor pagination (default: 'id') */\n  cursorField?: string;\n  /** Sort direction for cursor field (default: Direction.Asc) */\n  cursorDirection?: Direction;\n}\n\n/**\n * Generic paginated search function that handles:\n * - Total count calculation\n * - Cursor-based pagination\n * - Fetching one extra row to determine hasMore\n * - Mapping rows to output format\n *\n * @example\n * ```typescript\n * const result = await paginatedSearch({\n *   query: db.selectFrom('users').selectAll(),\n *   cursor: previousCursor,\n *   limit: 20,\n *   mapRow: (row) => ({ id: row.id, name: row.name }),\n *   cursorField: 'id',\n *   cursorDirection: Direction.Asc,\n * });\n * ```\n */\nexport async function paginatedSearch<\n  TRow extends Record<string, unknown>,\n  TMapRow extends (row: TRow) => unknown,\n>({\n  query,\n  cursor,\n  limit = 20,\n  mapRow,\n  cursorField = 'id',\n  cursorDirection = Direction.Asc,\n}: PaginatedSearchOptions<TRow, TMapRow>): Promise<\n  PaginationResult<Awaited<ReturnType<TMapRow>>>\n> {\n  // Get total count (without cursor)\n  const countResult = await query\n    .clearSelect()\n    .clearOrderBy()\n    .select((eb) => eb.fn.countAll().as('count'))\n    .executeTakeFirstOrThrow();\n\n  const count = countResult.count;\n\n  // Apply cursor if provided\n  let paginatedQuery = query;\n  if (cursor) {\n    const operator = cursorDirection === Direction.Asc ? '>' : '<';\n    paginatedQuery = paginatedQuery.where(\n      cursorField as any,\n      operator,\n      cursor,\n    ) as typeof query;\n  }\n\n  // Fetch one extra to determine if there are more results\n  const data = await paginatedQuery\n    .orderBy(cursorField as any, cursorDirection)\n    .limit(limit + 1)\n    .execute();\n\n  const hasMore = data.length > limit;\n  const rows = hasMore ? data.slice(0, limit) : data;\n  const lastRow = rows[rows.length - 1];\n  const nextCursor =\n    hasMore && lastRow ? String(lastRow[cursorField]) : undefined;\n\n  const items = (await Promise.all(rows.map(mapRow))) as Awaited<\n    ReturnType<TMapRow>\n  >[];\n\n  return {\n    items,\n    pagination: {\n      total: Number(count),\n      hasMore,\n      cursor: nextCursor,\n    },\n  };\n}\n\n/**\n * Encode a cursor value for safe URL transmission.\n * Supports various types: string, number, Date, etc.\n */\nexport function encodeCursor(value: unknown): string {\n  const payload = {\n    v: value instanceof Date ? value.toISOString() : value,\n    t: value instanceof Date ? 'date' : typeof value,\n  };\n  return Buffer.from(JSON.stringify(payload)).toString('base64url');\n}\n\n/**\n * Decode a cursor string back to its original value.\n */\nexport function decodeCursor(cursor: string): unknown {\n  try {\n    const json = Buffer.from(cursor, 'base64url').toString('utf-8');\n    const payload = JSON.parse(json);\n\n    if (payload.t === 'date') {\n      return new Date(payload.v);\n    }\n\n    return payload.v;\n  } catch {\n    throw new Error('Invalid cursor format');\n  }\n}\n"],"mappings":";;;;;AAKA,IAAY,kDAAL;AACL;AACA;;AACD;;;;;;;;;;;;;;;;;;;;AAsDD,eAAsB,gBAGpB,EACA,OACA,QACA,QAAQ,IACR,QACA,cAAc,MACd,kBAAkB,UAAU,KACU,EAEtC;CAEA,MAAM,cAAc,MAAM,MACvB,aAAa,CACb,cAAc,CACd,OAAO,CAAC,OAAO,GAAG,GAAG,UAAU,CAAC,GAAG,QAAQ,CAAC,CAC5C,yBAAyB;CAE5B,MAAM,QAAQ,YAAY;CAG1B,IAAI,iBAAiB;AACrB,KAAI,QAAQ;EACV,MAAM,WAAW,oBAAoB,UAAU,MAAM,MAAM;AAC3D,mBAAiB,eAAe,MAC9B,aACA,UACA,OACD;CACF;CAGD,MAAM,OAAO,MAAM,eAChB,QAAQ,aAAoB,gBAAgB,CAC5C,MAAM,QAAQ,EAAE,CAChB,SAAS;CAEZ,MAAM,UAAU,KAAK,SAAS;CAC9B,MAAM,OAAO,UAAU,KAAK,MAAM,GAAG,MAAM,GAAG;CAC9C,MAAM,UAAU,KAAK,KAAK,SAAS;CACnC,MAAM,aACJ,WAAW,UAAU,OAAO,QAAQ,aAAa;CAEnD,MAAM,QAAS,MAAM,QAAQ,IAAI,KAAK,IAAI,OAAO,CAAC;AAIlD,QAAO;EACL;EACA,YAAY;GACV,OAAO,OAAO,MAAM;GACpB;GACA,QAAQ;EACT;CACF;AACF;;;;;AAMD,SAAgB,aAAaA,OAAwB;CACnD,MAAM,UAAU;EACd,GAAG,iBAAiB,OAAO,MAAM,aAAa,GAAG;EACjD,GAAG,iBAAiB,OAAO,gBAAgB;CAC5C;AACD,QAAO,OAAO,KAAK,KAAK,UAAU,QAAQ,CAAC,CAAC,SAAS,YAAY;AAClE;;;;AAKD,SAAgB,aAAaC,QAAyB;AACpD,KAAI;EACF,MAAM,OAAO,OAAO,KAAK,QAAQ,YAAY,CAAC,SAAS,QAAQ;EAC/D,MAAM,UAAU,KAAK,MAAM,KAAK;AAEhC,MAAI,QAAQ,MAAM,OAChB,QAAO,IAAI,KAAK,QAAQ;AAG1B,SAAO,QAAQ;CAChB,QAAO;AACN,QAAM,IAAI,MAAM;CACjB;AACF"}

package/dist/kysely/pagination.d.cts

@@ -0,0 +1,78 @@
+import { SelectQueryBuilder } from "kysely";
+
+//#region src/kysely/pagination.d.ts
+
+/**
+ * Sort direction for cursor-based pagination.
+ */
+declare enum Direction {
+  Asc = "asc",
+  Desc = "desc",
+}
+/**
+ * Result of a paginated query.
+ */
+interface PaginationResult<TItem> {
+  items: TItem[];
+  pagination: {
+    total: number;
+    hasMore: boolean;
+    cursor?: string;
+  };
+}
+/**
+ * Options for paginated search.
+ */
+interface PaginatedSearchOptions<TRow, TMapRow extends (row: TRow) => unknown> {
+  /** The base Kysely query to paginate */
+  query: SelectQueryBuilder<any, any, TRow>;
+  /** Cursor value for pagination (value of cursorField from previous page) */
+  cursor?: string;
+  /** Maximum number of items per page (default: 20) */
+  limit?: number;
+  /** Function to transform each row to the output format */
+  mapRow: TMapRow;
+  /** Field to use for cursor pagination (default: 'id') */
+  cursorField?: string;
+  /** Sort direction for cursor field (default: Direction.Asc) */
+  cursorDirection?: Direction;
+}
+/**
+ * Generic paginated search function that handles:
+ * - Total count calculation
+ * - Cursor-based pagination
+ * - Fetching one extra row to determine hasMore
+ * - Mapping rows to output format
+ *
+ * @example
+ * ```typescript
+ * const result = await paginatedSearch({
+ *   query: db.selectFrom('users').selectAll(),
+ *   cursor: previousCursor,
+ *   limit: 20,
+ *   mapRow: (row) => ({ id: row.id, name: row.name }),
+ *   cursorField: 'id',
+ *   cursorDirection: Direction.Asc,
+ * });
+ * ```
+ */
+declare function paginatedSearch<TRow extends Record<string, unknown>, TMapRow extends (row: TRow) => unknown>({
+  query,
+  cursor,
+  limit,
+  mapRow,
+  cursorField,
+  cursorDirection
+}: PaginatedSearchOptions<TRow, TMapRow>): Promise<PaginationResult<Awaited<ReturnType<TMapRow>>>>;
+/**
+ * Encode a cursor value for safe URL transmission.
+ * Supports various types: string, number, Date, etc.
+ */
+declare function encodeCursor(value: unknown): string;
+/**
+ * Decode a cursor string back to its original value.
+ */
+declare function decodeCursor(cursor: string): unknown;
+//#endregion
+export { Direction, PaginatedSearchOptions, PaginationResult, decodeCursor, encodeCursor, paginatedSearch };
+//# sourceMappingURL=pagination.d.cts.map

package/dist/kysely/pagination.d.mts

@@ -0,0 +1,78 @@
+import { SelectQueryBuilder } from "kysely";
+
+//#region src/kysely/pagination.d.ts
+
+/**
+ * Sort direction for cursor-based pagination.
+ */
+declare enum Direction {
+  Asc = "asc",
+  Desc = "desc",
+}
+/**
+ * Result of a paginated query.
+ */
+interface PaginationResult<TItem> {
+  items: TItem[];
+  pagination: {
+    total: number;
+    hasMore: boolean;
+    cursor?: string;
+  };
+}
+/**
+ * Options for paginated search.
+ */
+interface PaginatedSearchOptions<TRow, TMapRow extends (row: TRow) => unknown> {
+  /** The base Kysely query to paginate */
+  query: SelectQueryBuilder<any, any, TRow>;
+  /** Cursor value for pagination (value of cursorField from previous page) */
+  cursor?: string;
+  /** Maximum number of items per page (default: 20) */
+  limit?: number;
+  /** Function to transform each row to the output format */
+  mapRow: TMapRow;
+  /** Field to use for cursor pagination (default: 'id') */
+  cursorField?: string;
+  /** Sort direction for cursor field (default: Direction.Asc) */
+  cursorDirection?: Direction;
+}
+/**
+ * Generic paginated search function that handles:
+ * - Total count calculation
+ * - Cursor-based pagination
+ * - Fetching one extra row to determine hasMore
+ * - Mapping rows to output format
+ *
+ * @example
+ * ```typescript
+ * const result = await paginatedSearch({
+ *   query: db.selectFrom('users').selectAll(),
+ *   cursor: previousCursor,
+ *   limit: 20,
+ *   mapRow: (row) => ({ id: row.id, name: row.name }),
+ *   cursorField: 'id',
+ *   cursorDirection: Direction.Asc,
+ * });
+ * ```
+ */
+declare function paginatedSearch<TRow extends Record<string, unknown>, TMapRow extends (row: TRow) => unknown>({
+  query,
+  cursor,
+  limit,
+  mapRow,
+  cursorField,
+  cursorDirection
+}: PaginatedSearchOptions<TRow, TMapRow>): Promise<PaginationResult<Awaited<ReturnType<TMapRow>>>>;
+/**
+ * Encode a cursor value for safe URL transmission.
+ * Supports various types: string, number, Date, etc.
+ */
+declare function encodeCursor(value: unknown): string;
+/**
+ * Decode a cursor string back to its original value.
+ */
+declare function decodeCursor(cursor: string): unknown;
+//#endregion
+export { Direction, PaginatedSearchOptions, PaginationResult, decodeCursor, encodeCursor, paginatedSearch };
+//# sourceMappingURL=pagination.d.mts.map

package/dist/kysely/pagination.mjs

@@ -0,0 +1,79 @@
+//#region src/kysely/pagination.ts
+/**
+* Sort direction for cursor-based pagination.
+*/
+let Direction = /* @__PURE__ */ function(Direction$1) {
+	Direction$1["Asc"] = "asc";
+	Direction$1["Desc"] = "desc";
+	return Direction$1;
+}({});
+/**
+* Generic paginated search function that handles:
+* - Total count calculation
+* - Cursor-based pagination
+* - Fetching one extra row to determine hasMore
+* - Mapping rows to output format
+*
+* @example
+* ```typescript
+* const result = await paginatedSearch({
+*   query: db.selectFrom('users').selectAll(),
+*   cursor: previousCursor,
+*   limit: 20,
+*   mapRow: (row) => ({ id: row.id, name: row.name }),
+*   cursorField: 'id',
+*   cursorDirection: Direction.Asc,
+* });
+* ```
+*/
+async function paginatedSearch({ query, cursor, limit = 20, mapRow, cursorField = "id", cursorDirection = Direction.Asc }) {
+	const countResult = await query.clearSelect().clearOrderBy().select((eb) => eb.fn.countAll().as("count")).executeTakeFirstOrThrow();
+	const count = countResult.count;
+	let paginatedQuery = query;
+	if (cursor) {
+		const operator = cursorDirection === Direction.Asc ? ">" : "<";
+		paginatedQuery = paginatedQuery.where(cursorField, operator, cursor);
+	}
+	const data = await paginatedQuery.orderBy(cursorField, cursorDirection).limit(limit + 1).execute();
+	const hasMore = data.length > limit;
+	const rows = hasMore ? data.slice(0, limit) : data;
+	const lastRow = rows[rows.length - 1];
+	const nextCursor = hasMore && lastRow ? String(lastRow[cursorField]) : void 0;
+	const items = await Promise.all(rows.map(mapRow));
+	return {
+		items,
+		pagination: {
+			total: Number(count),
+			hasMore,
+			cursor: nextCursor
+		}
+	};
+}
+/**
+* Encode a cursor value for safe URL transmission.
+* Supports various types: string, number, Date, etc.
+*/
+function encodeCursor(value) {
+	const payload = {
+		v: value instanceof Date ? value.toISOString() : value,
+		t: value instanceof Date ? "date" : typeof value
+	};
+	return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+/**
+* Decode a cursor string back to its original value.
+*/
+function decodeCursor(cursor) {
+	try {
+		const json = Buffer.from(cursor, "base64url").toString("utf-8");
+		const payload = JSON.parse(json);
+		if (payload.t === "date") return new Date(payload.v);
+		return payload.v;
+	} catch {
+		throw new Error("Invalid cursor format");
+	}
+}
+
+//#endregion
+export { Direction, decodeCursor, encodeCursor, paginatedSearch };
+//# sourceMappingURL=pagination.mjs.map

package/dist/kysely/pagination.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.mjs","names":["value: unknown","cursor: string"],"sources":["../../src/kysely/pagination.ts"],"sourcesContent":["import type { SelectQueryBuilder } from 'kysely';\n\n/**\n * Sort direction for cursor-based pagination.\n */\nexport enum Direction {\n  Asc = 'asc',\n  Desc = 'desc',\n}\n\n/**\n * Result of a paginated query.\n */\nexport interface PaginationResult<TItem> {\n  items: TItem[];\n  pagination: {\n    total: number;\n    hasMore: boolean;\n    cursor?: string;\n  };\n}\n\n/**\n * Options for paginated search.\n */\nexport interface PaginatedSearchOptions<\n  TRow,\n  TMapRow extends (row: TRow) => unknown,\n> {\n  /** The base Kysely query to paginate */\n  query: SelectQueryBuilder<any, any, TRow>;\n  /** Cursor value for pagination (value of cursorField from previous page) */\n  cursor?: string;\n  /** Maximum number of items per page (default: 20) */\n  limit?: number;\n  /** Function to transform each row to the output format */\n  mapRow: TMapRow;\n  /** Field to use for cursor pagination (default: 'id') */\n  cursorField?: string;\n  /** Sort direction for cursor field (default: Direction.Asc) */\n  cursorDirection?: Direction;\n}\n\n/**\n * Generic paginated search function that handles:\n * - Total count calculation\n * - Cursor-based pagination\n * - Fetching one extra row to determine hasMore\n * - Mapping rows to output format\n *\n * @example\n * ```typescript\n * const result = await paginatedSearch({\n *   query: db.selectFrom('users').selectAll(),\n *   cursor: previousCursor,\n *   limit: 20,\n *   mapRow: (row) => ({ id: row.id, name: row.name }),\n *   cursorField: 'id',\n *   cursorDirection: Direction.Asc,\n * });\n * ```\n */\nexport async function paginatedSearch<\n  TRow extends Record<string, unknown>,\n  TMapRow extends (row: TRow) => unknown,\n>({\n  query,\n  cursor,\n  limit = 20,\n  mapRow,\n  cursorField = 'id',\n  cursorDirection = Direction.Asc,\n}: PaginatedSearchOptions<TRow, TMapRow>): Promise<\n  PaginationResult<Awaited<ReturnType<TMapRow>>>\n> {\n  // Get total count (without cursor)\n  const countResult = await query\n    .clearSelect()\n    .clearOrderBy()\n    .select((eb) => eb.fn.countAll().as('count'))\n    .executeTakeFirstOrThrow();\n\n  const count = countResult.count;\n\n  // Apply cursor if provided\n  let paginatedQuery = query;\n  if (cursor) {\n    const operator = cursorDirection === Direction.Asc ? '>' : '<';\n    paginatedQuery = paginatedQuery.where(\n      cursorField as any,\n      operator,\n      cursor,\n    ) as typeof query;\n  }\n\n  // Fetch one extra to determine if there are more results\n  const data = await paginatedQuery\n    .orderBy(cursorField as any, cursorDirection)\n    .limit(limit + 1)\n    .execute();\n\n  const hasMore = data.length > limit;\n  const rows = hasMore ? data.slice(0, limit) : data;\n  const lastRow = rows[rows.length - 1];\n  const nextCursor =\n    hasMore && lastRow ? String(lastRow[cursorField]) : undefined;\n\n  const items = (await Promise.all(rows.map(mapRow))) as Awaited<\n    ReturnType<TMapRow>\n  >[];\n\n  return {\n    items,\n    pagination: {\n      total: Number(count),\n      hasMore,\n      cursor: nextCursor,\n    },\n  };\n}\n\n/**\n * Encode a cursor value for safe URL transmission.\n * Supports various types: string, number, Date, etc.\n */\nexport function encodeCursor(value: unknown): string {\n  const payload = {\n    v: value instanceof Date ? value.toISOString() : value,\n    t: value instanceof Date ? 'date' : typeof value,\n  };\n  return Buffer.from(JSON.stringify(payload)).toString('base64url');\n}\n\n/**\n * Decode a cursor string back to its original value.\n */\nexport function decodeCursor(cursor: string): unknown {\n  try {\n    const json = Buffer.from(cursor, 'base64url').toString('utf-8');\n    const payload = JSON.parse(json);\n\n    if (payload.t === 'date') {\n      return new Date(payload.v);\n    }\n\n    return payload.v;\n  } catch {\n    throw new Error('Invalid cursor format');\n  }\n}\n"],"mappings":";;;;AAKA,IAAY,kDAAL;AACL;AACA;;AACD;;;;;;;;;;;;;;;;;;;;AAsDD,eAAsB,gBAGpB,EACA,OACA,QACA,QAAQ,IACR,QACA,cAAc,MACd,kBAAkB,UAAU,KACU,EAEtC;CAEA,MAAM,cAAc,MAAM,MACvB,aAAa,CACb,cAAc,CACd,OAAO,CAAC,OAAO,GAAG,GAAG,UAAU,CAAC,GAAG,QAAQ,CAAC,CAC5C,yBAAyB;CAE5B,MAAM,QAAQ,YAAY;CAG1B,IAAI,iBAAiB;AACrB,KAAI,QAAQ;EACV,MAAM,WAAW,oBAAoB,UAAU,MAAM,MAAM;AAC3D,mBAAiB,eAAe,MAC9B,aACA,UACA,OACD;CACF;CAGD,MAAM,OAAO,MAAM,eAChB,QAAQ,aAAoB,gBAAgB,CAC5C,MAAM,QAAQ,EAAE,CAChB,SAAS;CAEZ,MAAM,UAAU,KAAK,SAAS;CAC9B,MAAM,OAAO,UAAU,KAAK,MAAM,GAAG,MAAM,GAAG;CAC9C,MAAM,UAAU,KAAK,KAAK,SAAS;CACnC,MAAM,aACJ,WAAW,UAAU,OAAO,QAAQ,aAAa;CAEnD,MAAM,QAAS,MAAM,QAAQ,IAAI,KAAK,IAAI,OAAO,CAAC;AAIlD,QAAO;EACL;EACA,YAAY;GACV,OAAO,OAAO,MAAM;GACpB;GACA,QAAQ;EACT;CACF;AACF;;;;;AAMD,SAAgB,aAAaA,OAAwB;CACnD,MAAM,UAAU;EACd,GAAG,iBAAiB,OAAO,MAAM,aAAa,GAAG;EACjD,GAAG,iBAAiB,OAAO,gBAAgB;CAC5C;AACD,QAAO,OAAO,KAAK,KAAK,UAAU,QAAQ,CAAC,CAAC,SAAS,YAAY;AAClE;;;;AAKD,SAAgB,aAAaC,QAAyB;AACpD,KAAI;EACF,MAAM,OAAO,OAAO,KAAK,QAAQ,YAAY,CAAC,SAAS,QAAQ;EAC/D,MAAM,UAAU,KAAK,MAAM,KAAK;AAEhC,MAAI,QAAQ,MAAM,OAChB,QAAO,IAAI,KAAK,QAAQ;AAG1B,SAAO,QAAQ;CAChB,QAAO;AACN,QAAM,IAAI,MAAM;CACjB;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/db",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -9,6 +9,11 @@
       "import": "./dist/kysely.mjs",
       "require": "./dist/kysely.cjs"
     },
+    "./kysely/pagination": {
+      "types": "./dist/kysely/pagination.d.ts",
+      "import": "./dist/kysely/pagination.mjs",
+      "require": "./dist/kysely/pagination.cjs"
+    },
     "./rls": {
       "types": "./dist/rls.d.ts",
       "import": "./dist/rls.mjs",

package/src/kysely/__tests__/pagination.integration.spec.ts

@@ -0,0 +1,341 @@
+import {
+  CamelCasePlugin,
+  type Generated,
+  Kysely,
+  PostgresDialect,
+  sql,
+} from 'kysely';
+import pg from 'pg';
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+} from 'vitest';
+import { TEST_DATABASE_CONFIG } from '../../../../testkit/test/globalSetup';
+import {
+  Direction,
+  decodeCursor,
+  encodeCursor,
+  paginatedSearch,
+} from '../pagination';
+
+interface TestDatabase {
+  paginationTestItems: {
+    id: Generated<number>;
+    name: string;
+    category: string;
+    price: number;
+    createdAt: Generated<Date>;
+  };
+}
+
+describe('Pagination Integration Tests', () => {
+  let db: Kysely<TestDatabase>;
+
+  beforeAll(async () => {
+    db = new Kysely<TestDatabase>({
+      dialect: new PostgresDialect({
+        pool: new pg.Pool({
+          ...TEST_DATABASE_CONFIG,
+          database: 'postgres',
+        }),
+      }),
+      plugins: [new CamelCasePlugin()],
+    });
+
+    // Create test table
+    await db.schema
+      .createTable('pagination_test_items')
+      .ifNotExists()
+      .addColumn('id', 'serial', (col) => col.primaryKey())
+      .addColumn('name', 'varchar(255)', (col) => col.notNull())
+      .addColumn('category', 'varchar(100)', (col) => col.notNull())
+      .addColumn('price', 'numeric(10, 2)', (col) => col.notNull())
+      .addColumn('created_at', 'timestamptz', (col) =>
+        col.defaultTo(sql`now()`).notNull(),
+      )
+      .execute();
+  });
+
+  beforeEach(async () => {
+    // Insert 25 test items
+    const items = [];
+    for (let i = 1; i <= 25; i++) {
+      items.push({
+        name: `Item ${String(i).padStart(2, '0')}`,
+        category:
+          i <= 10 ? 'category-a' : i <= 20 ? 'category-b' : 'category-c',
+        price: i * 10,
+      });
+    }
+    await db.insertInto('paginationTestItems').values(items).execute();
+  });
+
+  afterEach(async () => {
+    await db.deleteFrom('paginationTestItems').execute();
+  });
+
+  afterAll(async () => {
+    await db.schema.dropTable('pagination_test_items').ifExists().execute();
+    await db.destroy();
+  });
+
+  describe('paginatedSearch', () => {
+    it('should return first page of results with default settings', async () => {
+      const result = await paginatedSearch({
+        query: db.selectFrom('paginationTestItems').selectAll(),
+        limit: 10,
+        mapRow: (row) => ({ id: row.id, name: row.name }),
+      });
+
+      expect(result.items).toHaveLength(10);
+      expect(result.pagination.total).toBe(25);
+      expect(result.pagination.hasMore).toBe(true);
+      expect(result.pagination.cursor).toBeDefined();
+    });
+
+    it('should return second page using cursor', async () => {
+      // Get first page
+      const firstPage = await paginatedSearch({
+        query: db.selectFrom('paginationTestItems').selectAll(),
+        limit: 10,
+        mapRow: (row) => ({ id: row.id, name: row.name }),
+        cursorDirection: Direction.Asc,
+      });
+
+      expect(firstPage.pagination.cursor).toBeDefined();
+
+      // Get second page using cursor
+      const secondPage = await paginatedSearch({
+        query: db.selectFrom('paginationTestItems').selectAll(),
+        cursor: firstPage.pagination.cursor,
+        limit: 10,
+        mapRow: (row) => ({ id: row.id, name: row.name }),
+        cursorDirection: Direction.Asc,
+      });
+
+      expect(secondPage.items).toHaveLength(10);
+      expect(secondPage.pagination.total).toBe(25);
+      expect(secondPage.pagination.hasMore).toBe(true);
+
+      // Items should be different from first page
+      const firstIds = firstPage.items.map((i) => i.id);
+      const secondIds = secondPage.items.map((i) => i.id);
+      expect(firstIds.every((id) => !secondIds.includes(id))).toBe(true);
+    });
+
+    it('should return last page with hasMore false', async () => {
+      // Get all pages
+      let cursor: string | undefined;
+      let pages: { id: number; name: string }[][] = [];
+
+      do {
+        const page = await paginatedSearch({
+          query: db.selectFrom('paginationTestItems').selectAll(),
+          cursor,
+          limit: 10,
+          mapRow: (row) => ({ id: row.id, name: row.name }),
+          cursorDirection: Direction.Asc,
+        });
+
+        pages.push(page.items);
+        cursor = page.pagination.cursor;
+
+        if (!page.pagination.hasMore) break;
+      } while (cursor);
+
+      // Should have 3 pages
+      expect(pages).toHaveLength(3);
+      expect(pages[0]).toHaveLength(10);
+      expect(pages[1]).toHaveLength(10);
+      expect(pages[2]).toHaveLength(5);
+
+      // Total items should be 25
+      const allItems = pages.flat();
+      expect(allItems).toHaveLength(25);
+    });
+
+    it('should paginate in descending order', async () => {
+      const result = await paginatedSearch({
+        query: db.selectFrom('paginationTestItems').selectAll(),
+        limit: 5,
+        mapRow: (row) => ({ id: row.id, name: row.name }),
+        cursorDirection: Direction.Desc,
+      });
+
+      // First item should have highest ID
+      const ids = result.items.map((i) => i.id);
+      for (let i = 1; i < ids.length; i++) {
+        expect(ids[i]).toBeLessThan(ids[i - 1]);
+      }
+
+      // Get second page
+      const secondPage = await paginatedSearch({
+        query: db.selectFrom('paginationTestItems').selectAll(),
+        cursor: result.pagination.cursor,
+        limit: 5,
+        mapRow: (row) => ({ id: row.id, name: row.name }),
+        cursorDirection: Direction.Desc,
+      });
+
+      // All IDs in second page should be less than all in first page
+      const maxSecondPage = Math.max(...secondPage.items.map((i) => i.id));
+      const minFirstPage = Math.min(...ids);
+      expect(maxSecondPage).toBeLessThan(minFirstPage);
+    });
+
+    it('should work with custom cursor field', async () => {
+      const result = await paginatedSearch({
+        query: db.selectFrom('paginationTestItems').selectAll(),
+        limit: 5,
+        mapRow: (row) => ({ id: row.id, name: row.name, price: row.price }),
+        cursorField: 'price',
+        cursorDirection: Direction.Asc,
+      });
+
+      // Prices should be in ascending order
+      const prices = result.items.map((i) => Number(i.price));
+      for (let i = 1; i < prices.length; i++) {
+        expect(prices[i]).toBeGreaterThan(prices[i - 1]);
+      }
+
+      // Cursor should contain the last price value
+      expect(Number(result.pagination.cursor)).toBe(prices[prices.length - 1]);
+
+      // Get second page
+      const secondPage = await paginatedSearch({
+        query: db.selectFrom('paginationTestItems').selectAll(),
+        cursor: result.pagination.cursor,
+        limit: 5,
+        mapRow: (row) => ({ id: row.id, name: row.name, price: row.price }),
+        cursorField: 'price',
+        cursorDirection: Direction.Asc,
+      });
+
+      // All prices in second page should be greater than cursor
+      const minSecondPage = Math.min(
+        ...secondPage.items.map((i) => Number(i.price)),
+      );
+      expect(minSecondPage).toBeGreaterThan(prices[prices.length - 1]);
+    });
+
+    it('should use default limit of 20', async () => {
+      const result = await paginatedSearch({
+        query: db.selectFrom('paginationTestItems').selectAll(),
+        mapRow: (row) => ({ id: row.id }),
+      });
+
+      expect(result.items).toHaveLength(20);
+    });
+
+    it('should work with filtered queries', async () => {
+      const result = await paginatedSearch({
+        query: db
+          .selectFrom('paginationTestItems')
+          .selectAll()
+          .where('category', '=', 'category-a'),
+        limit: 5,
+        mapRow: (row) => ({
+          id: row.id,
+          name: row.name,
+          category: row.category,
+        }),
+      });
+
+      expect(result.pagination.total).toBe(10); // Only category-a items
+      expect(result.items).toHaveLength(5);
+      result.items.forEach((item) => {
+        expect(item.category).toBe('category-a');
+      });
+    });
+
+    it('should handle empty result set', async () => {
+      const result = await paginatedSearch({
+        query: db
+          .selectFrom('paginationTestItems')
+          .selectAll()
+          .where('category', '=', 'nonexistent'),
+        limit: 10,
+        mapRow: (row) => ({ id: row.id }),
+      });
+
+      expect(result.items).toHaveLength(0);
+      expect(result.pagination.total).toBe(0);
+      expect(result.pagination.hasMore).toBe(false);
+      expect(result.pagination.cursor).toBeUndefined();
+    });
+
+    it('should handle async mapRow function', async () => {
+      const result = await paginatedSearch({
+        query: db.selectFrom('paginationTestItems').selectAll(),
+        limit: 5,
+        mapRow: async (row) => {
+          // Simulate async transformation
+          await new Promise((resolve) => setTimeout(resolve, 1));
+          return {
+            id: row.id,
+            displayName: `Product: ${row.name}`,
+            priceFormatted: `$${Number(row.price).toFixed(2)}`,
+          };
+        },
+      });
+
+      expect(result.items).toHaveLength(5);
+      result.items.forEach((item) => {
+        expect(item.displayName).toMatch(/^Product: Item \d+$/);
+        expect(item.priceFormatted).toMatch(/^\$\d+\.\d{2}$/);
+      });
+    });
+  });
+
+  describe('encodeCursor / decodeCursor', () => {
+    it('should encode and decode string values', () => {
+      const original = 'some-cursor-value';
+      const encoded = encodeCursor(original);
+      const decoded = decodeCursor(encoded);
+
+      expect(decoded).toBe(original);
+    });
+
+    it('should encode and decode number values', () => {
+      const original = 12345;
+      const encoded = encodeCursor(original);
+      const decoded = decodeCursor(encoded);
+
+      expect(decoded).toBe(original);
+    });
+
+    it('should encode and decode Date values', () => {
+      const original = new Date('2024-01-15T10:30:00.000Z');
+      const encoded = encodeCursor(original);
+      const decoded = decodeCursor(encoded);
+
+      expect(decoded).toEqual(original);
+    });
+
+    it('should produce URL-safe base64 encoding', () => {
+      const encoded = encodeCursor('test/value+with=special');
+
+      // Base64url should not contain +, /, or =
+      expect(encoded).not.toMatch(/[+/=]/);
+    });
+
+    it('should throw error for invalid cursor format', () => {
+      expect(() => decodeCursor('invalid-cursor')).toThrow(
+        'Invalid cursor format',
+      );
+    });
+
+    it('should throw error for malformed JSON', () => {
+      // Create valid base64url but with invalid JSON content
+      const malformedCursor = Buffer.from('not-json').toString('base64url');
+      expect(() => decodeCursor(malformedCursor)).toThrow(
+        'Invalid cursor format',
+      );
+    });
+  });
+});

package/src/kysely/pagination.ts

@@ -0,0 +1,150 @@
+import type { SelectQueryBuilder } from 'kysely';
+
+/**
+ * Sort direction for cursor-based pagination.
+ */
+export enum Direction {
+  Asc = 'asc',
+  Desc = 'desc',
+}
+
+/**
+ * Result of a paginated query.
+ */
+export interface PaginationResult<TItem> {
+  items: TItem[];
+  pagination: {
+    total: number;
+    hasMore: boolean;
+    cursor?: string;
+  };
+}
+
+/**
+ * Options for paginated search.
+ */
+export interface PaginatedSearchOptions<
+  TRow,
+  TMapRow extends (row: TRow) => unknown,
+> {
+  /** The base Kysely query to paginate */
+  query: SelectQueryBuilder<any, any, TRow>;
+  /** Cursor value for pagination (value of cursorField from previous page) */
+  cursor?: string;
+  /** Maximum number of items per page (default: 20) */
+  limit?: number;
+  /** Function to transform each row to the output format */
+  mapRow: TMapRow;
+  /** Field to use for cursor pagination (default: 'id') */
+  cursorField?: string;
+  /** Sort direction for cursor field (default: Direction.Asc) */
+  cursorDirection?: Direction;
+}
+
+/**
+ * Generic paginated search function that handles:
+ * - Total count calculation
+ * - Cursor-based pagination
+ * - Fetching one extra row to determine hasMore
+ * - Mapping rows to output format
+ *
+ * @example
+ * ```typescript
+ * const result = await paginatedSearch({
+ *   query: db.selectFrom('users').selectAll(),
+ *   cursor: previousCursor,
+ *   limit: 20,
+ *   mapRow: (row) => ({ id: row.id, name: row.name }),
+ *   cursorField: 'id',
+ *   cursorDirection: Direction.Asc,
+ * });
+ * ```
+ */
+export async function paginatedSearch<
+  TRow extends Record<string, unknown>,
+  TMapRow extends (row: TRow) => unknown,
+>({
+  query,
+  cursor,
+  limit = 20,
+  mapRow,
+  cursorField = 'id',
+  cursorDirection = Direction.Asc,
+}: PaginatedSearchOptions<TRow, TMapRow>): Promise<
+  PaginationResult<Awaited<ReturnType<TMapRow>>>
+> {
+  // Get total count (without cursor)
+  const countResult = await query
+    .clearSelect()
+    .clearOrderBy()
+    .select((eb) => eb.fn.countAll().as('count'))
+    .executeTakeFirstOrThrow();
+
+  const count = countResult.count;
+
+  // Apply cursor if provided
+  let paginatedQuery = query;
+  if (cursor) {
+    const operator = cursorDirection === Direction.Asc ? '>' : '<';
+    paginatedQuery = paginatedQuery.where(
+      cursorField as any,
+      operator,
+      cursor,
+    ) as typeof query;
+  }
+
+  // Fetch one extra to determine if there are more results
+  const data = await paginatedQuery
+    .orderBy(cursorField as any, cursorDirection)
+    .limit(limit + 1)
+    .execute();
+
+  const hasMore = data.length > limit;
+  const rows = hasMore ? data.slice(0, limit) : data;
+  const lastRow = rows[rows.length - 1];
+  const nextCursor =
+    hasMore && lastRow ? String(lastRow[cursorField]) : undefined;
+
+  const items = (await Promise.all(rows.map(mapRow))) as Awaited<
+    ReturnType<TMapRow>
+  >[];
+
+  return {
+    items,
+    pagination: {
+      total: Number(count),
+      hasMore,
+      cursor: nextCursor,
+    },
+  };
+}
+
+/**
+ * Encode a cursor value for safe URL transmission.
+ * Supports various types: string, number, Date, etc.
+ */
+export function encodeCursor(value: unknown): string {
+  const payload = {
+    v: value instanceof Date ? value.toISOString() : value,
+    t: value instanceof Date ? 'date' : typeof value,
+  };
+  return Buffer.from(JSON.stringify(payload)).toString('base64url');
+}
+
+/**
+ * Decode a cursor string back to its original value.
+ */
+export function decodeCursor(cursor: string): unknown {
+  try {
+    const json = Buffer.from(cursor, 'base64url').toString('utf-8');
+    const payload = JSON.parse(json);
+
+    if (payload.t === 'date') {
+      return new Date(payload.v);
+    }
+
+    return payload.v;
+  } catch {
+    throw new Error('Invalid cursor format');
+  }
+}