@classytic/repo-core 0.29.0 → 0.31.0

package/dist/testing/pagination-property-conformance.mjs

@@ -0,0 +1,160 @@
+import { describe, expect, it } from "vitest";
+import fc from "fast-check";
+//#region src/testing/pagination-property-conformance.ts
+/**
+* Pagination properties (fast-check), gated by `RepoCapabilities.paginationProperties`.
+*
+* - a full keyset walk equals an in-memory sort of the same rows (nulls first ascending, last
+*   descending; ties broken by id), for a numeric-nullable and a string key;
+* - under inserts, deletes and sort-key updates between pages, every row untouched during the
+*   walk is returned exactly once (no duplicate, no gap). A row whose key MOVED may be met
+*   twice or not at all; no keyset scheme can promise more for a row that changed position;
+* - an offset page never repeats a row.
+* Requires `fast-check` in the consumer's devDependencies (like `vitest`). An undeclared
+* capability is reported as a skipped group naming it; a declared one without a fixture fails.
+*/
+const rowArb = fc.record({
+	k: fc.option(fc.integer({
+		min: -5,
+		max: 5
+	}), { nil: null }),
+	s: fc.constantFrom("a", "b", "c", "aa", "ab")
+});
+function compare(a, b, field, dir) {
+	const av = a[field];
+	const bv = b[field];
+	return (av === bv ? 0 : av === null ? -1 : bv === null ? 1 : av < bv ? -1 : 1) * dir;
+}
+async function walkKeyset(f, sort, limit, between) {
+	const out = [];
+	let after;
+	for (let step = 0; step < 500; step++) {
+		const page = await f.keysetPage({
+			sort,
+			limit,
+			...after ? { after } : {}
+		});
+		out.push(...page.data);
+		if (!page.next) return out;
+		after = page.next;
+		if (between) await between(step);
+	}
+	throw new Error("keyset walk did not terminate in 500 pages");
+}
+function runPaginationPropertyConformance(harness) {
+	const title = `[pagination properties] ${harness.name}`;
+	if (harness.features.paginationProperties !== true) {
+		describe.skip(`${title} [skipped: capability 'paginationProperties' not declared]`, () => {
+			it("skipped", () => void 0);
+		});
+		return;
+	}
+	const numRuns = harness.numRuns ?? 15;
+	describe(title, () => {
+		if (!harness.fixture) {
+			it("declares 'paginationProperties' and supplies its fixture", () => {
+				throw new Error(`${harness.name} declares 'paginationProperties' but supplies no fixture`);
+			});
+			return;
+		}
+		const make = harness.fixture;
+		it("a full keyset walk equals an in-memory sort (nulls, ties)", async () => {
+			const f = await make();
+			try {
+				await fc.assert(fc.asyncProperty(fc.array(rowArb, {
+					minLength: 0,
+					maxLength: 25
+				}), fc.constantFrom("k", "s"), fc.constantFrom(1, -1), fc.integer({
+					min: 1,
+					max: 6
+				}), async (rows, field, dir, limit) => {
+					await f.reset();
+					await f.insert(rows);
+					const walked = await walkKeyset(f, { [field]: dir }, limit);
+					expect(new Set(walked.map((r) => r.id)).size).toBe(rows.length);
+					const keys = walked.map((r) => r[field]);
+					const sorted = [...walked].sort((a, b) => compare(a, b, field, dir)).map((r) => r[field]);
+					expect(keys).toEqual(sorted);
+				}), { numRuns });
+			} finally {
+				await f.cleanup();
+			}
+		});
+		it("a keyset walk under concurrent writes returns every untouched row exactly once", async () => {
+			const f = await make();
+			try {
+				await fc.assert(fc.asyncProperty(fc.array(rowArb, {
+					minLength: 5,
+					maxLength: 25
+				}), fc.array(fc.oneof(fc.record({
+					op: fc.constant("insert"),
+					row: rowArb
+				}), fc.record({
+					op: fc.constant("delete"),
+					at: fc.nat()
+				}), fc.record({
+					op: fc.constant("move"),
+					at: fc.nat(),
+					k: fc.option(fc.integer({
+						min: -5,
+						max: 5
+					}), { nil: null })
+				})), { maxLength: 12 }), fc.constantFrom(1, -1), async (rows, ops, dir) => {
+					await f.reset();
+					const ids = await f.insert(rows);
+					const touched = /* @__PURE__ */ new Set();
+					const live = [...ids];
+					const seen = (await walkKeyset(f, { k: dir }, 3, async (step) => {
+						const op = ops[step];
+						if (!op) return;
+						if (op.op === "insert") {
+							const [id] = await f.insert([op.row]);
+							if (id) touched.add(id);
+						} else if (live.length > 0) {
+							const id = live[op.at % live.length];
+							touched.add(id);
+							if (op.op === "delete") {
+								live.splice(live.indexOf(id), 1);
+								await f.remove(id);
+							} else await f.update(id, op.k);
+						}
+					})).map((r) => r.id);
+					for (const id of ids) {
+						if (touched.has(id)) continue;
+						expect(seen.filter((x) => x === id), `untouched row ${id}`).toHaveLength(1);
+					}
+				}), { numRuns });
+			} finally {
+				await f.cleanup();
+			}
+		});
+		it("an offset page never repeats a row", async () => {
+			const f = await make();
+			try {
+				await fc.assert(fc.asyncProperty(fc.array(rowArb, {
+					minLength: 1,
+					maxLength: 25
+				}), fc.integer({
+					min: 1,
+					max: 6
+				}), fc.integer({
+					min: 1,
+					max: 5
+				}), async (rows, limit, page) => {
+					await f.reset();
+					await f.insert(rows);
+					const { data } = await f.offsetPage({
+						sort: { s: 1 },
+						page,
+						limit
+					});
+					expect(new Set(data.map((r) => r.id)).size).toBe(data.length);
+				}), { numRuns });
+			} finally {
+				await f.cleanup();
+			}
+		});
+	});
+}
+//#endregion
+export { runPaginationPropertyConformance };

package/dist/testing/read-model-property-conformance.d.mts

@@ -0,0 +1,13 @@
+import { RepoCapabilities } from "../repository/capabilities.mjs";
+import { ReadModelFixture } from "./data-access-conformance.mjs";
+//#region src/testing/read-model-property-conformance.d.ts
+interface ReadModelPropertyHarness {
+  name: string;
+  features: RepoCapabilities;
+  fixture?: () => Promise<ReadModelFixture>;
+  /** fast-check runs. Default 15. */
+  numRuns?: number;
+}
+declare function runReadModelPropertyConformance(harness: ReadModelPropertyHarness): void;
+//#endregion
+export { ReadModelPropertyHarness, runReadModelPropertyConformance };

package/dist/testing/read-model-property-conformance.mjs

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import fc from "fast-check";
+//#region src/testing/read-model-property-conformance.ts
+/**
+* Read-model properties (fast-check), gated by `RepoCapabilities.readModel`.
+*
+* For random increments with random replays: the incremental model equals the source (no drift,
+* a replay never double-counts); a rebuild from the source keeps zero drift; and corrupting one
+* grain yields EXACTLY one drift row, naming that grain. An undeclared capability is a skipped
+* group naming it; a declared one without a fixture fails.
+*/
+const eventArb = fc.record({
+	period: fc.constantFrom("2026-01", "2026-02", "2026-03"),
+	rate: fc.constantFrom(0, 5, 15),
+	tax: fc.integer({
+		min: 1,
+		max: 1e3
+	})
+});
+function runReadModelPropertyConformance(harness) {
+	const title = `[read-model properties] ${harness.name}`;
+	if (harness.features.readModel !== true) {
+		describe.skip(`${title} [skipped: capability 'readModel' not declared]`, () => {
+			it("skipped", () => void 0);
+		});
+		return;
+	}
+	describe(title, () => {
+		if (!harness.fixture) {
+			it("declares 'readModel' and supplies its fixture", () => {
+				throw new Error(`${harness.name} declares 'readModel' but supplies no fixture`);
+			});
+			return;
+		}
+		const make = harness.fixture;
+		it("increments with replays equal the source; rebuild keeps zero drift; one corruption is one drift row", async () => {
+			await fc.assert(fc.asyncProperty(fc.array(eventArb, {
+				minLength: 1,
+				maxLength: 20
+			}), fc.array(fc.nat(), { maxLength: 10 }), fc.nat(), async (events, replayPicks, corruptPick) => {
+				const f = await make();
+				try {
+					const tenant = "t-prop";
+					const keyed = events.map((e, i) => ({
+						...e,
+						dedupeKey: `e${i}`
+					}));
+					await f.seedSource(tenant, events);
+					const replays = replayPicks.map((p) => keyed[p % keyed.length]).filter((x) => x !== void 0);
+					const half = Math.ceil(keyed.length / 2);
+					await f.applyIncrements(tenant, keyed.slice(0, half));
+					await f.applyIncrements(tenant, [...replays, ...keyed.slice(half)]);
+					expect(await f.reconcile(tenant)).toEqual([]);
+					await f.rebuild(tenant);
+					expect(await f.reconcile(tenant)).toEqual([]);
+					const grains = await f.readTotals(tenant);
+					const target = grains[corruptPick % grains.length];
+					if (!target) throw new Error("no grain to corrupt");
+					await f.tamper(tenant, target.period, target.rate);
+					const drift = await f.reconcile(tenant);
+					expect(drift).toHaveLength(1);
+					expect(drift[0]?.key).toMatchObject({
+						period: target.period,
+						rate: target.rate
+					});
+				} finally {
+					await f.cleanup();
+				}
+			}), { numRuns: harness.numRuns ?? 15 });
+		});
+	});
+}
+//#endregion
+export { runReadModelPropertyConformance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.29.0",
+  "version": "0.31.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,