@usequark/quark-core 2.5.4

package/src/pagination.js

@@ -0,0 +1,139 @@
+/**
+ * @techstream/quark-core - Pagination Utilities
+ *
+ * Provides offset-based pagination helpers that integrate with Prisma's
+ * skip/take API and the project's ValidationError convention.
+ *
+ * Usage in a route handler:
+ *
+ *   import { parsePaginationQuery } from "@techstream/quark-core";
+ *
+ *   export async function GET(request) {
+ *     const { searchParams } = new URL(request.url);
+ *     const { skip, take, meta } = parsePaginationQuery(searchParams);
+ *     const [records, total] = await Promise.all([
+ *       prisma.post.findMany({ skip, take }),
+ *       prisma.post.count(),
+ *     ]);
+ *     return NextResponse.json({ data: records, pagination: meta(total) });
+ *   }
+ */
+
+import { z } from "zod";
+import { ValidationError } from "./errors.js";
+
+/** Default maximum page size. Can be overridden per-call via options. */
+const DEFAULT_MAX_LIMIT = 100;
+
+/** Default page size when ?limit is not provided. */
+const DEFAULT_LIMIT = 20;
+
+/**
+ * Build a Zod schema for pagination query params.
+ * @param {number} maxLimit
+ * @returns {import("zod").ZodObject<any>}
+ */
+function buildSchema(maxLimit) {
+	return z.object({
+		page: z.coerce.number().int().min(1).default(1),
+		limit: z.coerce.number().int().min(1).max(maxLimit).default(DEFAULT_LIMIT),
+	});
+}
+
+/**
+ * Parse and validate raw pagination params from a URL search params object,
+ * a plain key/value object, or any iterable of [key, value] pairs.
+ *
+ * Throws ValidationError on invalid input so the existing `handleError`
+ * in route handlers catches it and returns a 422 automatically.
+ *
+ * @param {URLSearchParams | Record<string, string | undefined> | Iterable<[string, string]>} params
+ * @param {{ maxLimit?: number }} [options]
+ * @returns {{ page: number, limit: number }}
+ */
+export function parsePagination(params, options = {}) {
+	const maxLimit = options.maxLimit ?? DEFAULT_MAX_LIMIT;
+	const schema = buildSchema(maxLimit);
+
+	// Normalise to a plain object regardless of input type
+	let raw;
+	if (params instanceof URLSearchParams) {
+		raw = { page: params.get("page"), limit: params.get("limit") };
+	} else if (
+		typeof params === "object" &&
+		params !== null &&
+		typeof params[Symbol.iterator] === "function"
+	) {
+		raw = Object.fromEntries(params);
+	} else {
+		raw = params ?? {};
+	}
+
+	// Strip null/undefined keys so Zod defaults kick in
+	const cleaned = Object.fromEntries(
+		Object.entries(raw).filter(([, v]) => v != null),
+	);
+
+	const result = schema.safeParse(cleaned);
+	if (!result.success) {
+		throw new ValidationError(result.error.flatten());
+	}
+	return result.data;
+}
+
+/**
+ * Convert page + limit into Prisma's skip/take arguments.
+ *
+ * @param {{ page: number, limit: number }} pagination
+ * @returns {{ skip: number, take: number }}
+ */
+export function paginationToSkip({ page, limit }) {
+	return {
+		skip: (page - 1) * limit,
+		take: limit,
+	};
+}
+
+/**
+ * Build the pagination metadata envelope returned in API responses.
+ *
+ * @param {{ page: number, limit: number, total: number }} params
+ * @returns {{ total: number, page: number, limit: number, totalPages: number, hasNext: boolean, hasPrev: boolean }}
+ */
+export function paginationMeta({ page, limit, total }) {
+	const totalPages = Math.ceil(total / limit);
+	return {
+		total,
+		page,
+		limit,
+		totalPages,
+		hasNext: page < totalPages,
+		hasPrev: page > 1,
+	};
+}
+
+/**
+ * Convenience helper that parses pagination params and returns everything
+ * needed to call Prisma + build the response envelope in one shot.
+ *
+ * @param {URLSearchParams | Record<string, string | undefined>} params
+ * @param {{ maxLimit?: number }} [options]
+ * @returns {{
+ *   page: number,
+ *   limit: number,
+ *   skip: number,
+ *   take: number,
+ *   meta: (total: number) => ReturnType<typeof paginationMeta>
+ * }}
+ */
+export function parsePaginationQuery(params, options = {}) {
+	const { page, limit } = parsePagination(params, options);
+	const { skip, take } = paginationToSkip({ page, limit });
+	return {
+		page,
+		limit,
+		skip,
+		take,
+		meta: (total) => paginationMeta({ page, limit, total }),
+	};
+}

package/src/pagination.test.js

@@ -0,0 +1,210 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { ValidationError } from "./errors.js";
+import {
+	paginationMeta,
+	paginationToSkip,
+	parsePagination,
+	parsePaginationQuery,
+} from "./pagination.js";
+
+// ─── parsePagination ──────────────────────────────────────────────────────────
+
+describe("parsePagination", () => {
+	describe("from URLSearchParams", () => {
+		it("returns defaults when no params are given", () => {
+			const result = parsePagination(new URLSearchParams());
+			assert.deepEqual(result, { page: 1, limit: 20 });
+		});
+
+		it("parses page and limit", () => {
+			const result = parsePagination(new URLSearchParams("page=3&limit=50"));
+			assert.deepEqual(result, { page: 3, limit: 50 });
+		});
+
+		it("coerces string numbers", () => {
+			const result = parsePagination(new URLSearchParams("page=2&limit=10"));
+			assert.equal(typeof result.page, "number");
+			assert.equal(typeof result.limit, "number");
+		});
+	});
+
+	describe("from plain object", () => {
+		it("accepts a plain object", () => {
+			const result = parsePagination({ page: "2", limit: "10" });
+			assert.deepEqual(result, { page: 2, limit: 10 });
+		});
+
+		it("uses defaults for undefined values", () => {
+			const result = parsePagination({});
+			assert.deepEqual(result, { page: 1, limit: 20 });
+		});
+
+		it("ignores null values and uses defaults", () => {
+			const result = parsePagination({ page: null, limit: null });
+			assert.deepEqual(result, { page: 1, limit: 20 });
+		});
+	});
+
+	describe("validation", () => {
+		it("throws ValidationError for page < 1", () => {
+			assert.throws(
+				() => parsePagination({ page: "0" }),
+				(err) => err instanceof ValidationError,
+			);
+		});
+
+		it("throws ValidationError for non-integer page", () => {
+			assert.throws(
+				() => parsePagination({ page: "1.5" }),
+				(err) => err instanceof ValidationError,
+			);
+		});
+
+		it("throws ValidationError for limit > maxLimit (default 100)", () => {
+			assert.throws(
+				() => parsePagination({ limit: "101" }),
+				(err) => err instanceof ValidationError,
+			);
+		});
+
+		it("respects custom maxLimit option", () => {
+			const result = parsePagination({ limit: "200" }, { maxLimit: 500 });
+			assert.equal(result.limit, 200);
+		});
+
+		it("throws when limit exceeds custom maxLimit", () => {
+			assert.throws(
+				() => parsePagination({ limit: "51" }, { maxLimit: 50 }),
+				(err) => err instanceof ValidationError,
+			);
+		});
+	});
+});
+
+// ─── paginationToSkip ─────────────────────────────────────────────────────────
+
+describe("paginationToSkip", () => {
+	it("page 1 → skip 0", () => {
+		assert.deepEqual(paginationToSkip({ page: 1, limit: 20 }), {
+			skip: 0,
+			take: 20,
+		});
+	});
+
+	it("page 2 limit 20 → skip 20", () => {
+		assert.deepEqual(paginationToSkip({ page: 2, limit: 20 }), {
+			skip: 20,
+			take: 20,
+		});
+	});
+
+	it("page 3 limit 10 → skip 20", () => {
+		assert.deepEqual(paginationToSkip({ page: 3, limit: 10 }), {
+			skip: 20,
+			take: 10,
+		});
+	});
+
+	it("page 5 limit 100 → skip 400", () => {
+		assert.deepEqual(paginationToSkip({ page: 5, limit: 100 }), {
+			skip: 400,
+			take: 100,
+		});
+	});
+});
+
+// ─── paginationMeta ───────────────────────────────────────────────────────────
+
+describe("paginationMeta", () => {
+	it("calculates totalPages correctly", () => {
+		const meta = paginationMeta({ page: 1, limit: 20, total: 100 });
+		assert.equal(meta.totalPages, 5);
+	});
+
+	it("rounds totalPages up for non-divisible totals", () => {
+		const meta = paginationMeta({ page: 1, limit: 20, total: 101 });
+		assert.equal(meta.totalPages, 6);
+	});
+
+	it("hasNext is true when not on last page", () => {
+		const meta = paginationMeta({ page: 2, limit: 10, total: 50 });
+		assert.equal(meta.hasNext, true);
+	});
+
+	it("hasNext is false on last page", () => {
+		const meta = paginationMeta({ page: 5, limit: 10, total: 50 });
+		assert.equal(meta.hasNext, false);
+	});
+
+	it("hasPrev is true when not on first page", () => {
+		const meta = paginationMeta({ page: 3, limit: 10, total: 50 });
+		assert.equal(meta.hasPrev, true);
+	});
+
+	it("hasPrev is false on first page", () => {
+		const meta = paginationMeta({ page: 1, limit: 10, total: 50 });
+		assert.equal(meta.hasPrev, false);
+	});
+
+	it("returns total, page, limit in metadata", () => {
+		const meta = paginationMeta({ page: 2, limit: 10, total: 45 });
+		assert.equal(meta.total, 45);
+		assert.equal(meta.page, 2);
+		assert.equal(meta.limit, 10);
+	});
+
+	it("handles total of 0", () => {
+		const meta = paginationMeta({ page: 1, limit: 20, total: 0 });
+		assert.equal(meta.totalPages, 0);
+		assert.equal(meta.hasNext, false);
+		assert.equal(meta.hasPrev, false);
+	});
+
+	it("handles single page result", () => {
+		const meta = paginationMeta({ page: 1, limit: 20, total: 5 });
+		assert.equal(meta.totalPages, 1);
+		assert.equal(meta.hasNext, false);
+		assert.equal(meta.hasPrev, false);
+	});
+});
+
+// ─── parsePaginationQuery ─────────────────────────────────────────────────────
+
+describe("parsePaginationQuery", () => {
+	it("returns page, limit, skip, take, and meta function", () => {
+		const sp = new URLSearchParams("page=2&limit=15");
+		const result = parsePaginationQuery(sp);
+		assert.equal(result.page, 2);
+		assert.equal(result.limit, 15);
+		assert.equal(result.skip, 15);
+		assert.equal(result.take, 15);
+		assert.equal(typeof result.meta, "function");
+	});
+
+	it("meta(total) returns correct pagination envelope", () => {
+		const result = parsePaginationQuery(new URLSearchParams("page=2&limit=10"));
+		const meta = result.meta(45);
+		assert.deepEqual(meta, {
+			total: 45,
+			page: 2,
+			limit: 10,
+			totalPages: 5,
+			hasNext: true,
+			hasPrev: true,
+		});
+	});
+
+	it("uses defaults when no params are provided", () => {
+		const result = parsePaginationQuery(new URLSearchParams());
+		assert.equal(result.skip, 0);
+		assert.equal(result.take, 20);
+	});
+
+	it("propagates ValidationError on invalid input", () => {
+		assert.throws(
+			() => parsePaginationQuery(new URLSearchParams("page=0")),
+			(err) => err instanceof ValidationError,
+		);
+	});
+});

package/src/query-builder.js

@@ -0,0 +1,183 @@
+/**
+ * @techstream/quark-core - Query Builder
+ * Builds Prisma where/orderBy clauses from query parameters
+ * with validation and sanitization.
+ */
+
+/**
+ * @typedef {Object} QueryBuilderOptions
+ * @property {string[]} [searchFields] - Fields to search across
+ * @property {string[]} [sortableFields] - Fields that can be sorted
+ * @property {string[]} [filterableFields] - Fields that can be filtered
+ */
+
+/**
+ * Supported filter operators
+ */
+const OPERATORS = {
+	eq: "equals",
+	ne: "not",
+	gt: "gt",
+	gte: "gte",
+	lt: "lt",
+	lte: "lte",
+	contains: "contains",
+	startsWith: "startsWith",
+	endsWith: "endsWith",
+	in: "in",
+};
+
+/**
+ * Query builder for constructing Prisma where/orderBy clauses.
+ */
+export class QueryBuilder {
+	/**
+	 * @param {QueryBuilderOptions} options
+	 */
+	constructor(options = {}) {
+		this.searchFields = options.searchFields || [];
+		this.sortableFields = options.sortableFields || [];
+		this.filterableFields = options.filterableFields || [];
+		this.filters = [];
+		this.searchTerm = null;
+		this.sortField = null;
+		this.sortDirection = "asc";
+	}
+
+	/**
+	 * Add a filter condition.
+	 * @param {string} field - Field name
+	 * @param {string} operator - Operator (eq, ne, gt, gte, lt, lte, contains, startsWith, endsWith, in)
+	 * @param {any} value - Filter value
+	 * @returns {QueryBuilder}
+	 */
+	filter(field, operator, value) {
+		if (!this.filterableFields.includes(field)) {
+			throw new Error(
+				`Field "${field}" is not filterable. Allowed: ${this.filterableFields.join(", ")}`,
+			);
+		}
+
+		if (!OPERATORS[operator]) {
+			throw new Error(
+				`Operator "${operator}" is not supported. Allowed: ${Object.keys(OPERATORS).join(", ")}`,
+			);
+		}
+
+		this.filters.push({ field, operator, value });
+		return this;
+	}
+
+	/**
+	 * Add a full-text search across multiple fields.
+	 * @param {string} term - Search term
+	 * @returns {QueryBuilder}
+	 */
+	search(term) {
+		if (!term || typeof term !== "string") {
+			return this;
+		}
+
+		if (this.searchFields.length === 0) {
+			throw new Error("No search fields configured for this query");
+		}
+
+		this.searchTerm = term.trim();
+		return this;
+	}
+
+	/**
+	 * Set sort field and direction.
+	 * @param {string} field - Field name
+	 * @param {"asc" | "desc"} [direction="asc"] - Sort direction
+	 * @returns {QueryBuilder}
+	 */
+	sort(field, direction = "asc") {
+		if (!this.sortableFields.includes(field)) {
+			throw new Error(
+				`Field "${field}" is not sortable. Allowed: ${this.sortableFields.join(", ")}`,
+			);
+		}
+
+		if (direction !== "asc" && direction !== "desc") {
+			throw new Error('Sort direction must be "asc" or "desc"');
+		}
+
+		this.sortField = field;
+		this.sortDirection = direction;
+		return this;
+	}
+
+	/**
+	 * Build Prisma where clause.
+	 * @returns {Object} Prisma where object
+	 */
+	toWhere() {
+		const conditions = [];
+
+		// Add filter conditions
+		for (const { field, operator, value } of this.filters) {
+			const prismaOp = OPERATORS[operator];
+
+			if (operator === "in") {
+				// Special handling for "in" operator - value should be an array
+				const values = Array.isArray(value) ? value : [value];
+				conditions.push({ [field]: { in: values } });
+			} else if (operator === "ne") {
+				// "not" operator wraps the value
+				conditions.push({ [field]: { not: value } });
+			} else {
+				conditions.push({ [field]: { [prismaOp]: value } });
+			}
+		}
+
+		// Add search condition
+		if (this.searchTerm) {
+			const searchConditions = this.searchFields.map((field) => ({
+				[field]: { contains: this.searchTerm, mode: "insensitive" },
+			}));
+			conditions.push({ OR: searchConditions });
+		}
+
+		// Return combined conditions
+		if (conditions.length === 0) {
+			return {};
+		}
+		if (conditions.length === 1) {
+			return conditions[0];
+		}
+		return { AND: conditions };
+	}
+
+	/**
+	 * Build Prisma orderBy clause.
+	 * @returns {Object | undefined} Prisma orderBy object
+	 */
+	toOrderBy() {
+		if (!this.sortField) {
+			return undefined;
+		}
+		return { [this.sortField]: this.sortDirection };
+	}
+
+	/**
+	 * Reset all filters, search, and sort.
+	 * @returns {QueryBuilder}
+	 */
+	reset() {
+		this.filters = [];
+		this.searchTerm = null;
+		this.sortField = null;
+		this.sortDirection = "asc";
+		return this;
+	}
+}
+
+/**
+ * Factory function to create a new QueryBuilder.
+ * @param {QueryBuilderOptions} options
+ * @returns {QueryBuilder}
+ */
+export function createQueryBuilder(options) {
+	return new QueryBuilder(options);
+}