@geekmidas/db 9.0.2 → 10.0.0-alpha.1

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

@@ -1,291 +0,0 @@
-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

@@ -1,98 +0,0 @@
-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

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

package/src/rls.ts

@@ -1,90 +0,0 @@
-import type { Transaction } from 'kysely';
-import { sql } from 'kysely';
-import {
-	type DatabaseConnection,
-	type TransactionSettings,
-	withTransaction,
-} from './kysely';
-
-/**
- * RLS context - key-value pairs to set as PostgreSQL session variables.
- * Keys become `prefix.key` (e.g., `app.user_id`).
- */
-export interface RlsContext {
-	[key: string]: string | number | boolean | null | undefined;
-}
-
-/**
- * Options for withRlsContext function.
- */
-export interface WithRlsContextOptions {
-	/** Prefix for PostgreSQL session variables (default: 'app') */
-	prefix?: string;
-	/** Transaction settings (isolation level) */
-	settings?: TransactionSettings;
-}
-
-/**
- * Execute a callback within a transaction with RLS context variables set.
- *
- * Sets PostgreSQL session variables using `SET LOCAL` which scopes them to the
- * current transaction. Variables are automatically cleared when the transaction
- * ends (commit or rollback).
- *
- * @example
- * ```ts
- * await withRlsContext(
- *   db,
- *   { user_id: session.userId, tenant_id: session.tenantId },
- *   async (trx) => {
- *     // RLS policies can now use current_setting('app.user_id')
- *     return trx.selectFrom('orders').selectAll().execute();
- *   }
- * );
- * ```
- *
- * @param db - Database connection (Kysely, Transaction, or ControlledTransaction)
- * @param context - Key-value pairs to set as session variables
- * @param callback - Function to execute within the RLS context
- * @param options - Optional prefix and transaction settings
- */
-export async function withRlsContext<DB, T>(
-	db: DatabaseConnection<DB>,
-	context: RlsContext,
-	callback: (trx: Transaction<DB>) => Promise<T>,
-	options?: WithRlsContextOptions,
-): Promise<T> {
-	const prefix = options?.prefix ?? 'app';
-
-	return withTransaction(
-		db,
-		async (trx) => {
-			// Set each context variable using SET LOCAL (scoped to transaction)
-			for (const [key, value] of Object.entries(context)) {
-				if (value === null || value === undefined) continue;
-
-				const settingName = `${prefix}.${key}`;
-				const settingValue = String(value);
-
-				// Use raw SQL for SET LOCAL with proper escaping
-				// The setting name is an identifier, value is a string literal
-				await sql`SELECT set_config(${settingName}, ${settingValue}, true)`.execute(
-					trx,
-				);
-			}
-
-			return callback(trx);
-		},
-		options?.settings,
-	);
-}
-
-/**
- * Bypass marker symbol for explicitly skipping RLS context.
- */
-export const RLS_BYPASS = Symbol.for('geekmidas.rls.bypass');
-
-/**
- * Type for RLS bypass marker.
- */
-export type RlsBypass = typeof RLS_BYPASS;

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "composite": true
-  },
-  "include": ["src/**/*"]
-}