@geekmidas/db 1.0.0 → 1.0.2

package/src/kysely/pagination.ts

@@ -1,31 +1,19 @@
 import type { SelectQueryBuilder } from 'kysely';
+import {
+	Direction,
+	decodeCursor,
+	encodeCursor,
+	type PaginationResult,
+} from '../pagination';
 
-/**
- * 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;
-	};
-}
+export { Direction, decodeCursor, encodeCursor, type PaginationResult };
 
 /**
  * Options for paginated search.
  */
 export interface PaginatedSearchOptions<
 	TRow,
-	TMapRow extends (row: TRow) => unknown,
+	TMapRow extends (row: TRow) => unknown = (row: TRow) => TRow,
 > {
 	/** The base Kysely query to paginate */
 	query: SelectQueryBuilder<any, any, TRow>;
@@ -33,8 +21,8 @@ export interface PaginatedSearchOptions<
 	cursor?: string;
 	/** Maximum number of items per page (default: 20) */
 	limit?: number;
-	/** Function to transform each row to the output format */
-	mapRow: TMapRow;
+	/** Function to transform each row to the output format (default: identity) */
+	mapRow?: TMapRow;
 	/** Field to use for cursor pagination (default: 'id') */
 	cursorField?: string;
 	/** Sort direction for cursor field (default: Direction.Asc) */
@@ -50,19 +38,23 @@ export interface PaginatedSearchOptions<
  *
  * @example
  * ```typescript
+ * // With mapRow
  * 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,
+ * });
+ *
+ * // Without mapRow — items are the raw row type
+ * const result = await paginatedSearch({
+ *   query: db.selectFrom('users').selectAll(),
+ *   limit: 20,
  * });
  * ```
  */
 export async function paginatedSearch<
 	TRow extends Record<string, unknown>,
-	TMapRow extends (row: TRow) => unknown,
+	TMapRow extends (row: TRow) => unknown = (row: TRow) => TRow,
 >({
 	query,
 	cursor,
@@ -105,7 +97,8 @@ export async function paginatedSearch<
 	const nextCursor =
 		hasMore && lastRow ? String(lastRow[cursorField]) : undefined;
 
-	const items = (await Promise.all(rows.map(mapRow))) as Awaited<
+	const mapper = mapRow ?? ((row: TRow) => row);
+	const items = (await Promise.all(rows.map(mapper))) as Awaited<
 		ReturnType<TMapRow>
 	>[];
 
@@ -118,33 +111,3 @@ export async function paginatedSearch<
 		},
 	};
 }
-
-/**
- * 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');
-	}
-}

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

@@ -0,0 +1,291 @@
+import knex, { type Knex } from 'knex';
+import { Model } from 'objection';
+import {
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	it,
+} from 'vitest';
+import { TEST_DATABASE_CONFIG } from '../../../../testkit/test/globalSetup';
+import { Direction, paginatedSearch } from '../pagination';
+
+class PaginationTestItem extends Model {
+	static tableName = 'objection_pagination_test_items';
+
+	id!: number;
+	name!: string;
+	category!: string;
+	price!: number;
+	createdAt!: Date;
+}
+
+describe('Objection Pagination Integration Tests', () => {
+	let db: Knex;
+
+	beforeAll(async () => {
+		db = knex({
+			client: 'pg',
+			connection: {
+				...TEST_DATABASE_CONFIG,
+				database: 'postgres',
+			},
+		});
+
+		Model.knex(db);
+
+		await db.schema.createTableIfNotExists(
+			'objection_pagination_test_items',
+			(table) => {
+				table.increments('id').primary();
+				table.string('name', 255).notNullable();
+				table.string('category', 100).notNullable();
+				table.decimal('price', 10, 2).notNullable();
+				table.timestamp('created_at').defaultTo(db.fn.now()).notNullable();
+			},
+		);
+	});
+
+	beforeEach(async () => {
+		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 PaginationTestItem.query().insert(items);
+	});
+
+	afterEach(async () => {
+		await PaginationTestItem.query().delete();
+	});
+
+	afterAll(async () => {
+		await db.schema.dropTableIfExists('objection_pagination_test_items');
+		await db.destroy();
+	});
+
+	describe('paginatedSearch', () => {
+		it('should return first page of results with default settings', async () => {
+			const result = await paginatedSearch({
+				query: PaginationTestItem.query(),
+				limit: 10,
+			});
+
+			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 model instances when no mapRow is provided', async () => {
+			const result = await paginatedSearch({
+				query: PaginationTestItem.query(),
+				limit: 5,
+			});
+
+			expect(result.items[0]).toBeInstanceOf(PaginationTestItem);
+			expect(result.items[0].name).toBeDefined();
+		});
+
+		it('should return second page using cursor', async () => {
+			const firstPage = await paginatedSearch({
+				query: PaginationTestItem.query(),
+				limit: 10,
+				cursorDirection: Direction.Asc,
+			});
+
+			expect(firstPage.pagination.cursor).toBeDefined();
+
+			const secondPage = await paginatedSearch({
+				query: PaginationTestItem.query(),
+				cursor: firstPage.pagination.cursor,
+				limit: 10,
+				cursorDirection: Direction.Asc,
+			});
+
+			expect(secondPage.items).toHaveLength(10);
+			expect(secondPage.pagination.total).toBe(25);
+			expect(secondPage.pagination.hasMore).toBe(true);
+
+			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 () => {
+			let cursor: string | undefined;
+			const pages: PaginationTestItem[][] = [];
+
+			do {
+				const page = await paginatedSearch({
+					query: PaginationTestItem.query(),
+					cursor,
+					limit: 10,
+					cursorDirection: Direction.Asc,
+				});
+
+				pages.push(page.items);
+				cursor = page.pagination.cursor;
+
+				if (!page.pagination.hasMore) break;
+			} while (cursor);
+
+			expect(pages).toHaveLength(3);
+			expect(pages[0]).toHaveLength(10);
+			expect(pages[1]).toHaveLength(10);
+			expect(pages[2]).toHaveLength(5);
+
+			const allItems = pages.flat();
+			expect(allItems).toHaveLength(25);
+		});
+
+		it('should paginate in descending order', async () => {
+			const result = await paginatedSearch({
+				query: PaginationTestItem.query(),
+				limit: 5,
+				cursorDirection: Direction.Desc,
+			});
+
+			const ids = result.items.map((i) => i.id);
+			for (let i = 1; i < ids.length; i++) {
+				expect(ids[i]).toBeLessThan(ids[i - 1]);
+			}
+
+			const secondPage = await paginatedSearch({
+				query: PaginationTestItem.query(),
+				cursor: result.pagination.cursor,
+				limit: 5,
+				cursorDirection: Direction.Desc,
+			});
+
+			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: PaginationTestItem.query(),
+				limit: 5,
+				mapRow: (row) => ({ id: row.id, name: row.name, price: row.price }),
+				cursorField: 'price',
+				cursorDirection: Direction.Asc,
+			});
+
+			const prices = result.items.map((i) => Number(i.price));
+			for (let i = 1; i < prices.length; i++) {
+				expect(prices[i]).toBeGreaterThan(prices[i - 1]);
+			}
+
+			expect(Number(result.pagination.cursor)).toBe(prices[prices.length - 1]);
+
+			const secondPage = await paginatedSearch({
+				query: PaginationTestItem.query(),
+				cursor: result.pagination.cursor,
+				limit: 5,
+				mapRow: (row) => ({ id: row.id, name: row.name, price: row.price }),
+				cursorField: 'price',
+				cursorDirection: Direction.Asc,
+			});
+
+			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: PaginationTestItem.query(),
+			});
+
+			expect(result.items).toHaveLength(20);
+		});
+
+		it('should work with filtered queries', async () => {
+			const result = await paginatedSearch({
+				query: PaginationTestItem.query().where('category', 'category-a'),
+				limit: 5,
+				mapRow: (row) => ({
+					id: row.id,
+					name: row.name,
+					category: row.category,
+				}),
+			});
+
+			expect(result.pagination.total).toBe(10);
+			expect(result.items).toHaveLength(5);
+			for (const item of result.items) {
+				expect(item.category).toBe('category-a');
+			}
+		});
+
+		it('should handle empty result set', async () => {
+			const result = await paginatedSearch({
+				query: PaginationTestItem.query().where('category', 'nonexistent'),
+				limit: 10,
+			});
+
+			expect(result.items).toHaveLength(0);
+			expect(result.pagination.total).toBe(0);
+			expect(result.pagination.hasMore).toBe(false);
+			expect(result.pagination.cursor).toBeUndefined();
+		});
+
+		it('should work with mapRow transformation', async () => {
+			const result = await paginatedSearch({
+				query: PaginationTestItem.query(),
+				limit: 5,
+				mapRow: (row) => ({
+					id: row.id,
+					displayName: `Product: ${row.name}`,
+					priceFormatted: `$${Number(row.price).toFixed(2)}`,
+				}),
+			});
+
+			expect(result.items).toHaveLength(5);
+			for (const item of result.items) {
+				expect(item.displayName).toMatch(/^Product: Item \d+$/);
+				expect(item.priceFormatted).toMatch(/^\$\d+\.\d{2}$/);
+			}
+		});
+
+		it('should work with eager loading', async () => {
+			// withGraphFetched doesn't error even without relations defined;
+			// this validates the query builder composition works end-to-end
+			const result = await paginatedSearch({
+				query: PaginationTestItem.query().select('id', 'name'),
+				limit: 5,
+			});
+
+			expect(result.items).toHaveLength(5);
+			expect(result.items[0].id).toBeDefined();
+			expect(result.items[0].name).toBeDefined();
+		});
+
+		it('should work with async mapRow function', async () => {
+			const result = await paginatedSearch({
+				query: PaginationTestItem.query(),
+				limit: 5,
+				mapRow: async (row) => {
+					await new Promise((resolve) => setTimeout(resolve, 1));
+					return {
+						id: row.id,
+						displayName: `Product: ${row.name}`,
+					};
+				},
+			});
+
+			expect(result.items).toHaveLength(5);
+			for (const item of result.items) {
+				expect(item.displayName).toMatch(/^Product: Item \d+$/);
+			}
+		});
+	});
+});

package/src/objection/pagination.ts

@@ -0,0 +1,98 @@
+import type { Model, QueryBuilder } from 'objection';
+import {
+	Direction,
+	decodeCursor,
+	encodeCursor,
+	type PaginationResult,
+} from '../pagination';
+
+export { Direction, decodeCursor, encodeCursor, type PaginationResult };
+
+/**
+ * Options for paginated search with Objection.js models.
+ */
+export interface ObjectionPaginatedSearchOptions<
+	TModel extends Model,
+	TMapRow extends (row: TModel) => unknown = (row: TModel) => TModel,
+> {
+	/** The Objection QueryBuilder to paginate (e.g. User.query(trx).where(...)) */
+	query: QueryBuilder<TModel>;
+	/** 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 (default: identity) */
+	mapRow?: TMapRow;
+	/** Field to use for cursor pagination (default: 'id') */
+	cursorField?: string;
+	/** Sort direction for cursor field (default: Direction.Asc) */
+	cursorDirection?: Direction;
+}
+
+/**
+ * Cursor-based paginated search for Objection.js models.
+ *
+ * Accepts a pre-built QueryBuilder so callers can apply filters,
+ * eager loading, and scopes before pagination is layered on top.
+ *
+ * @example
+ * ```typescript
+ * const result = await paginatedSearch({
+ *   query: User.query(trx).where('orgId', orgId).withGraphFetched('roles'),
+ *   cursor: previousCursor,
+ *   limit: 20,
+ *   cursorField: 'createdAt',
+ *   cursorDirection: Direction.Desc,
+ * });
+ * ```
+ */
+export async function paginatedSearch<
+	TModel extends Model,
+	TMapRow extends (row: TModel) => unknown = (row: TModel) => TModel,
+>({
+	query,
+	cursor,
+	limit = 20,
+	mapRow,
+	cursorField = 'id',
+	cursorDirection = Direction.Asc,
+}: ObjectionPaginatedSearchOptions<TModel, TMapRow>): Promise<
+	PaginationResult<Awaited<ReturnType<TMapRow>>>
+> {
+	// Get total count (without cursor filtering)
+	const total = await query.resultSize();
+
+	// Apply cursor if provided
+	let paginatedQuery = query.clone();
+	if (cursor) {
+		const operator = cursorDirection === Direction.Asc ? '>' : '<';
+		paginatedQuery = paginatedQuery.where(cursorField, operator, cursor);
+	}
+
+	// Fetch one extra to determine if there are more results
+	const data = await paginatedQuery
+		.orderBy(cursorField, cursorDirection)
+		.limit(limit + 1);
+
+	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 as Record<string, unknown>)[cursorField])
+			: undefined;
+
+	const mapper = mapRow ?? ((row: TModel) => row);
+	const items = (await Promise.all(rows.map(mapper))) as Awaited<
+		ReturnType<TMapRow>
+	>[];
+
+	return {
+		items,
+		pagination: {
+			total,
+			hasMore,
+			cursor: nextCursor,
+		},
+	};
+}

package/src/pagination.ts

@@ -0,0 +1,49 @@
+/**
+ * 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;
+	};
+}
+
+/**
+ * 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');
+	}
+}