@classytic/repo-core 0.28.0 → 0.29.0

package/dist/testing/query-grammar-conformance.mjs

@@ -0,0 +1,380 @@
+import { describe, expect, it } from "vitest";
+//#region src/testing/query-grammar-conformance.ts
+/**
+* `runQueryGrammarConformance` — every list-query parser reads a URL the same way.
+*
+* Cases are SEMANTIC: each parser's output is evaluated against one fixture set and must select
+* the same rows (or refuse the same input with a 400). A parser passes by agreeing on RESULTS,
+* so its emitted shape (Filter IR, Mongo record, a custom dialect) is free.
+*/
+const at = (iso) => new Date(iso);
+/** The fixture every case runs against: nulls, missing fields, codes, dates, and text metacharacters. */
+const QUERY_GRAMMAR_DOCS = [
+	{
+		_id: "a",
+		status: "active",
+		qty: 5,
+		code: "007",
+		name: "Blue Hoodie",
+		price: 10,
+		tags: ["x"],
+		createdAt: at("2026-09-01T00:00:00Z"),
+		note: "50% off",
+		deletedAt: null
+	},
+	{
+		_id: "b",
+		status: "draft",
+		qty: 12,
+		code: "7",
+		name: "blue cap",
+		price: 100,
+		createdAt: at("2026-09-15T00:00:00Z"),
+		note: "a.b"
+	},
+	{
+		_id: "c",
+		status: "archived",
+		qty: 0,
+		code: "0123",
+		name: "Red Hoodie",
+		price: 55.5,
+		tags: [],
+		createdAt: at("2026-10-02T00:00:00Z"),
+		deletedAt: at("2026-10-03T00:00:00Z")
+	},
+	{
+		_id: "d",
+		name: "Green",
+		price: 7
+	},
+	{
+		_id: "e",
+		status: null,
+		name: "HOODIE",
+		price: 0,
+		note: "axb"
+	}
+];
+const DEFAULT_OPTIONS = {
+	maxLimit: 100,
+	defaultLimit: 20
+};
+const QUERY_GRAMMAR_FILTER_CASES = [
+	{
+		query: "status=active",
+		ids: ["a"]
+	},
+	{
+		query: "status=active&status=draft",
+		ids: ["a", "b"]
+	},
+	{
+		query: "status[in]=active,draft",
+		ids: ["a", "b"]
+	},
+	{
+		query: "status[in]=active&status[in]=draft",
+		ids: ["a", "b"]
+	},
+	{
+		query: "status=active&status[in]=draft,archived",
+		ids: [
+			"a",
+			"b",
+			"c"
+		]
+	},
+	{
+		query: "status[nin]=active&status[ne]=draft",
+		ids: ["c"]
+	},
+	{
+		query: "status[nin]=active,draft",
+		ids: ["c"]
+	},
+	{
+		query: "status[in]=null,active",
+		ids: [
+			"a",
+			"d",
+			"e"
+		]
+	},
+	{
+		query: "status[nin]=null,active",
+		ids: ["b", "c"]
+	},
+	{
+		query: "status[ne]=active",
+		ids: ["b", "c"]
+	},
+	{
+		query: "status[exists]=true",
+		ids: [
+			"a",
+			"b",
+			"c"
+		]
+	},
+	{
+		query: "status[exists]=false",
+		ids: ["d", "e"]
+	},
+	{
+		query: "filter[status]=active",
+		ids: ["a"]
+	},
+	{
+		query: "status=",
+		ids: [
+			"a",
+			"b",
+			"c",
+			"d",
+			"e"
+		]
+	},
+	{
+		query: "qty=5",
+		ids: ["a"]
+	},
+	{
+		query: "qty[in]=5,12",
+		ids: ["a", "b"]
+	},
+	{
+		query: "qty[gte]=5",
+		ids: ["a", "b"]
+	},
+	{
+		query: "qty[lt]=5",
+		ids: ["c"]
+	},
+	{
+		query: "code=007",
+		ids: ["a"]
+	},
+	{
+		query: "code=0123",
+		ids: ["c"]
+	},
+	{
+		query: "price[gte]=10&price[lte]=100",
+		ids: [
+			"a",
+			"b",
+			"c"
+		]
+	},
+	{
+		query: "price[between]=10,60",
+		ids: ["a", "c"]
+	},
+	{
+		query: "price[between]=,9",
+		ids: ["d", "e"]
+	},
+	{
+		query: "price=10&price[gte]=1",
+		ids: ["a"]
+	},
+	{
+		query: "createdAt[gte]=2026-09-10",
+		ids: ["b", "c"]
+	},
+	{
+		query: "createdAt[between]=2026-09-01,2026-09-30",
+		ids: ["a", "b"]
+	},
+	{
+		query: "name[contains]=hoodie",
+		ids: [
+			"a",
+			"c",
+			"e"
+		]
+	},
+	{
+		query: "name[like]=hoodie",
+		ids: [
+			"a",
+			"c",
+			"e"
+		]
+	},
+	{
+		query: "name[startsWith]=blue",
+		ids: ["a", "b"]
+	},
+	{
+		query: "name[endsWith]=hoodie",
+		ids: [
+			"a",
+			"c",
+			"e"
+		]
+	},
+	{
+		query: "name[ieq]=hoodie",
+		ids: ["e"]
+	},
+	{
+		query: "note[contains]=a.b",
+		ids: ["b"]
+	},
+	{
+		query: "note[contains]=50%25",
+		ids: ["a"]
+	},
+	{
+		query: "name[regex]=^Blue",
+		ids: ["a"]
+	},
+	{
+		query: "name[regex]=^blue&name[options]=i",
+		ids: ["a", "b"]
+	},
+	{
+		query: "deletedAt=null",
+		ids: [
+			"a",
+			"b",
+			"d",
+			"e"
+		]
+	},
+	{
+		query: "tags[exists]=false",
+		ids: [
+			"b",
+			"d",
+			"e"
+		]
+	},
+	{
+		query: "status=active",
+		ids: ["a"],
+		options: { allowedFilterFields: ["status"] }
+	}
+];
+const QUERY_GRAMMAR_REFUSED = [
+	{ query: "x[foo]=1" },
+	{ query: "meta[color]=red" },
+	{ query: "meta[color][shade]=red" },
+	{ query: "status[$ne]=x" },
+	{ query: "$where=1" },
+	{ query: "name[regex]=(a%2B)%2B" },
+	{ query: "status[exists]=maybe" },
+	{ query: "price[between]=1" },
+	{ query: "price[between]=1,2,3" },
+	{ query: "qty[gte]=null" },
+	{ query: "name[options]=i" },
+	{ query: "name[regex]=a&name[options]=g" },
+	{
+		query: "price=1",
+		options: { allowedFilterFields: ["status"] }
+	},
+	{ query: "limit=0" },
+	{ query: "limit=-1" },
+	{ query: "limit=abc" },
+	{ query: "limit=1.5" },
+	{ query: "page=0" },
+	{ query: "page=abc" },
+	{ query: "sort=name;DROP" },
+	{ query: "sort=$x" },
+	{
+		query: "sort=price",
+		options: { allowedSortFields: ["name"] }
+	}
+];
+const QUERY_GRAMMAR_PAGING_CASES = [
+	{
+		query: "",
+		expect: { limit: 20 }
+	},
+	{
+		query: "limit=5",
+		expect: { limit: 5 }
+	},
+	{
+		query: "limit=500",
+		expect: { limit: 100 }
+	},
+	{
+		query: "page=2",
+		expect: {
+			limit: 20,
+			page: 2
+		}
+	},
+	{
+		query: "after=abc",
+		expect: {
+			limit: 20,
+			after: "abc"
+		}
+	},
+	{
+		query: "sort=-createdAt,name",
+		expect: {
+			limit: 20,
+			sort: {
+				createdAt: -1,
+				name: 1
+			}
+		}
+	}
+];
+function statusOf(error) {
+	const e = error;
+	const status = e?.status ?? e?.statusCode;
+	return typeof status === "number" ? status : void 0;
+}
+const refusedWith400 = (attempt, query) => {
+	let caught;
+	try {
+		attempt();
+	} catch (error) {
+		caught = error;
+	}
+	expect(caught, `?${query} was accepted`).toBeDefined();
+	expect(statusOf(caught)).toBe(400);
+};
+function runQueryGrammarConformance(name, harness, conformance = {}) {
+	const parse = (query, options) => harness.parse(query, {
+		...DEFAULT_OPTIONS,
+		...options
+	});
+	const unsupported = conformance.unsupportedOperators ?? [];
+	const usesUnsupported = (query) => unsupported.some((op) => query.includes(`[${op}]`));
+	describe(`query grammar conformance — ${name}`, () => {
+		describe("filters select the same rows", () => {
+			for (const { query, ids, options } of QUERY_GRAMMAR_FILTER_CASES) it(`?${query}${options ? ` ${JSON.stringify(options)}` : ""}`, () => {
+				if (usesUnsupported(query)) {
+					refusedWith400(() => parse(query, options), query);
+					return;
+				}
+				const parsed = parse(query, options);
+				const matched = QUERY_GRAMMAR_DOCS.filter((doc) => parsed.matches(doc)).map((doc) => doc["_id"]);
+				expect(matched).toEqual([...ids]);
+			});
+		});
+		describe("invalid input is refused with a 400, never dropped", () => {
+			for (const { query, options } of QUERY_GRAMMAR_REFUSED) it(`?${query}${options ? ` ${JSON.stringify(options)}` : ""}`, () => {
+				refusedWith400(() => parse(query, options), query);
+			});
+		});
+		describe("paging and sort", () => {
+			for (const { query, expect: want } of QUERY_GRAMMAR_PAGING_CASES) it(`?${query}`, () => {
+				const parsed = parse(query);
+				expect(parsed.limit).toBe(want.limit);
+				if (want.page !== void 0) expect(parsed.page).toBe(want.page);
+				if (want.after !== void 0) expect(parsed.after).toBe(want.after);
+				if (want.sort !== void 0) expect(parsed.sort).toEqual(want.sort);
+			});
+		});
+	});
+}
+//#endregion
+export { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, runQueryGrammarConformance };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.28.0",
-  "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
+  "version": "0.29.0",
+  "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design \u2014 no plugins ship here; each kit owns its own.",
   "type": "module",
   "sideEffects": false,
   "files": [
@@ -98,6 +98,10 @@
       "types": "./dist/lock/index.d.mts",
       "default": "./dist/lock/index.mjs"
     },
+    "./idempotency": {
+      "types": "./dist/idempotency/index.d.mts",
+      "default": "./dist/idempotency/index.mjs"
+    },
     "./loader": {
       "types": "./dist/loader/index.d.mts",
       "default": "./dist/loader/index.mjs"

package/dist/errors/types.mjs

@@ -1,29 +0,0 @@
-//#region src/errors/types.ts
-/**
-* Cross-cutting error codes used across the org. Every canonical code is
-* lowercase + snake_case to match RFC 7807, Stripe, and Shopify
-* conventions. Domain packages add their own hierarchical codes
-* (`'order.validation.*'`, `'payment.gateway.*'`); these cover the
-* universal cases every HTTP-emitting layer needs.
-*
-* **Arc compatibility note.** Arc's `ArcError` hierarchy historically
-* uses UPPER_SNAKE codes (`'NOT_FOUND'`, `'VALIDATION_ERROR'`) for
-* back-compat with hosts that switch on those values. New code should
-* prefer the canonical lowercase codes; arc keeps emitting its UPPER_SNAKE
-* codes on the wire so existing client switches keep working.
-*/
-const ERROR_CODES = {
-	VALIDATION: "validation_error",
-	NOT_FOUND: "not_found",
-	CONFLICT: "conflict",
-	UNAUTHORIZED: "unauthorized",
-	FORBIDDEN: "forbidden",
-	RATE_LIMITED: "rate_limited",
-	IDEMPOTENCY_CONFLICT: "idempotency_conflict",
-	PRECONDITION_FAILED: "precondition_failed",
-	INTERNAL: "internal_error",
-	UNAVAILABLE: "service_unavailable",
-	TIMEOUT: "timeout"
-};
-//#endregion
-export { ERROR_CODES };