@classytic/repo-core 0.1.0

package/dist/schema/types.d.mts

@@ -0,0 +1,138 @@
+//#region src/schema/types.d.ts
+/**
+ * Schema contract types — shared across every kit that emits JSON Schemas
+ * from its native schema (Mongoose models, Drizzle tables, Prisma schemas,
+ * zod schemas, etc.).
+ *
+ * Driver-free by design: every field on every type describes the *output*
+ * shape, not how it's produced. A kit's introspection code (mongooseToJsonSchema,
+ * drizzleToJsonSchema, ...) fills in the shape; repo-core just locks the
+ * contract so switching kits is a package swap, not an API rewrite.
+ */
+/**
+ * Per-field rule — declarative constraints that shape how a field appears
+ * in the create / update / query body schemas.
+ *
+ * These are pure policy: they touch neither the DB schema nor the Filter IR.
+ * A kit's schema builder reads them and omits / optionalizes fields in the
+ * generated JSON Schema accordingly.
+ */
+interface FieldRule {
+  /** Field cannot be updated — omitted from the update body schema. */
+  immutable?: boolean;
+  /** Alias for `immutable`. Kept for docstring clarity at call sites. */
+  immutableAfterCreate?: boolean;
+  /** System-only field — omitted from both create AND update body schemas. */
+  systemManaged?: boolean;
+  /** Remove from `required[]` in the generated schema. DB-level constraints unaffected. */
+  optional?: boolean;
+}
+/** Map of field name → FieldRule. */
+interface FieldRules {
+  [fieldName: string]: FieldRule;
+}
+/**
+ * JSON Schema (draft-07 subset) — intentionally loose so kits can emit
+ * vendor extensions (`x-ref`, `x-foreign-key`, etc.) without type pressure.
+ */
+interface JsonSchema {
+  type: string | string[];
+  properties?: Record<string, unknown>;
+  required?: string[];
+  additionalProperties?: boolean | unknown;
+  items?: unknown;
+  enum?: unknown[];
+  format?: string;
+  pattern?: string;
+  minProperties?: number;
+  maxProperties?: number;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  default?: unknown;
+  description?: string;
+  title?: string;
+  [key: `x-${string}`]: unknown;
+}
+/**
+ * CRUD schema bundle — the four JSON Schemas every HTTP endpoint needs:
+ * body validation on POST / PATCH, route-param validation on id routes, and
+ * query-string validation on list endpoints.
+ */
+interface CrudSchemas {
+  /** JSON Schema for create request body (POST). */
+  createBody: JsonSchema;
+  /** JSON Schema for update request body (PATCH / PUT). */
+  updateBody: JsonSchema;
+  /** JSON Schema for route params (id validation). */
+  params: JsonSchema;
+  /** JSON Schema for list/query parameters. */
+  listQuery: JsonSchema;
+}
+/**
+ * Options consumed by every kit's schema builder. Fields are additive:
+ * kit-specific extensions live on a separate extending interface so the
+ * portable subset stays identical across kits.
+ */
+interface SchemaBuilderOptions {
+  /** Field rules for create/update schemas. */
+  fieldRules?: FieldRules;
+  /**
+   * When `true`, emit `"additionalProperties": false` on create/update/query
+   * schemas. Default `false` so generators stay permissive by default;
+   * Fastify/AJV consumers typically flip this on for stricter validation.
+   */
+  strictAdditionalProperties?: boolean;
+  /** Date rendering: `'datetime'` → `format: date-time`; `'date'` → `format: date`. */
+  dateAs?: 'date' | 'datetime';
+  /** Create-schema overrides. */
+  create?: {
+    /** Fields to omit from the create body. */omitFields?: string[]; /** Force field to required (merged with auto-detected required). */
+    requiredOverrides?: Record<string, boolean>; /** Force field to optional (even if DB-level required). */
+    optionalOverrides?: Record<string, boolean>; /** Replace the generated schema for a specific field. */
+    schemaOverrides?: Record<string, unknown>;
+  };
+  /**
+   * Field names to mark as soft-required: they remain in the generated body
+   * schema's `properties` (still validated when present) but are excluded
+   * from the `required[]` array so the client may omit them.
+   *
+   * DB-level `required: true` invariants are unaffected — the driver still
+   * rejects null on save. This flag only affects HTTP body validation.
+   */
+  softRequiredFields?: string[];
+  /** Update-schema overrides. */
+  update?: {
+    /** Fields to omit from the update body. */omitFields?: string[]; /** When `true`, reject empty update bodies (`minProperties: 1`). */
+    requireAtLeastOne?: boolean;
+  };
+  /** List-query schema overrides. */
+  query?: {
+    /** Extra filterable fields exposed on the list-query schema. */filterableFields?: Record<string, {
+      type: string;
+    } | unknown>;
+  };
+  /**
+   * Emit OpenAPI vendor extensions (`x-*` keywords like `x-ref` for populated
+   * foreign-key fields).
+   *
+   * Default `false` because Ajv strict mode throws on unknown `x-*` keywords.
+   * Turn ON when feeding the schema into a docgen tool (Swagger, Redocly).
+   */
+  openApiExtensions?: boolean;
+}
+/**
+ * Result of `validateUpdateBody` — caller-friendly shape with structured
+ * violations for each disallowed field.
+ */
+interface ValidationResult {
+  valid: boolean;
+  violations?: Array<{
+    field: string;
+    reason: string;
+  }>;
+  message?: string;
+}
+//#endregion
+export { CrudSchemas, FieldRule, FieldRules, JsonSchema, SchemaBuilderOptions, ValidationResult };

package/dist/testing/conformance.d.mts

@@ -0,0 +1,6 @@
+import { ConformanceDoc, ConformanceHarness } from "./types.mjs";
+
+//#region src/testing/conformance.d.ts
+declare function runStandardRepoConformance<TDoc extends ConformanceDoc = ConformanceDoc>(harness: ConformanceHarness<TDoc>): void;
+//#endregion
+export { runStandardRepoConformance };

package/dist/testing/conformance.mjs

@@ -0,0 +1,481 @@
+import { and, eq, gt, in_, isNull, like, ne, or } from "../filter/builders.mjs";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+//#region src/testing/conformance.ts
+/**
+* `runStandardRepoConformance` — the cross-kit contract suite.
+*
+* Wires a kit-specific `ConformanceHarness` to a canonical set of
+* scenarios that every `StandardRepo<TDoc>` implementation should pass.
+* Each describe block probes one behavior of the contract; scenarios
+* the backend doesn't support (D1 transactions, Mongo standalone
+* transactions, optional methods) are `it.skip`ped via feature flags.
+*
+* The goal is to make "swap mongokit for sqlitekit" a provable claim:
+* when both kits' conformance suites stay green, controller code can
+* move between backends without behavior drift.
+*/
+/** Read the primary key from a doc regardless of backend convention. */
+function idOf(doc, idField) {
+	if (!doc) return void 0;
+	const value = doc[idField];
+	return value == null ? void 0 : String(value);
+}
+/** ISO timestamp N seconds offset from now — deterministic ordering fixture. */
+function isoAt(offsetSeconds) {
+	return new Date(Date.UTC(2026, 3, 1) + offsetSeconds * 1e3).toISOString();
+}
+function runStandardRepoConformance(harness) {
+	describe(`[conformance] ${harness.name}`, () => {
+		let ctx;
+		beforeEach(async () => {
+			ctx = await harness.setup();
+		});
+		afterEach(async () => {
+			await ctx.cleanup();
+		});
+		describe("CRUD basics", () => {
+			it("create → getById round-trips all scalar fields", async () => {
+				const input = harness.makeDoc({
+					name: "Alice",
+					email: "alice@example.com",
+					category: "admin",
+					count: 42,
+					active: true,
+					notes: "seed note",
+					createdAt: isoAt(0)
+				});
+				const id = idOf(await ctx.repo.create(input), harness.idField);
+				expect(id).toBeDefined();
+				const fetched = await ctx.repo.getById(id);
+				expect(fetched).not.toBeNull();
+				expect(fetched?.name).toBe("Alice");
+				expect(fetched?.email).toBe("alice@example.com");
+				expect(fetched?.category).toBe("admin");
+				expect(fetched?.count).toBe(42);
+				expect(fetched?.active).toBe(true);
+				expect(fetched?.notes).toBe("seed note");
+				expect(fetched?.createdAt).toBe(isoAt(0));
+			});
+			it("getById miss returns null", async () => {
+				expect(await ctx.repo.getById("does-not-exist-xyz")).toBeNull();
+			});
+			it("update by id returns updated doc; miss returns null", async () => {
+				const id = idOf(await ctx.repo.create(harness.makeDoc({
+					name: "Bob",
+					count: 1
+				})), harness.idField);
+				expect((await ctx.repo.update(id, { count: 99 }))?.count).toBe(99);
+				expect(await ctx.repo.update("no-such-id", { count: 1 })).toBeNull();
+			});
+			it("delete by id succeeds; second delete returns success:false", async () => {
+				const id = idOf(await ctx.repo.create(harness.makeDoc({ name: "Carol" })), harness.idField);
+				expect((await ctx.repo.delete(id)).success).toBe(true);
+				expect((await ctx.repo.delete(id)).success).toBe(false);
+			});
+		});
+		describe("findOneAndUpdate", () => {
+			beforeEach(async () => {
+				await ctx.repo.createMany([
+					harness.makeDoc({
+						name: "u1",
+						email: "u1@x.com",
+						category: "reader",
+						createdAt: isoAt(1)
+					}),
+					harness.makeDoc({
+						name: "u2",
+						email: "u2@x.com",
+						category: "reader",
+						createdAt: isoAt(2)
+					}),
+					harness.makeDoc({
+						name: "u3",
+						email: "u3@x.com",
+						category: "reader",
+						createdAt: isoAt(3)
+					})
+				]);
+			});
+			it("sort claims oldest row first (FIFO)", async () => {
+				if (!ctx.repo.findOneAndUpdate) return;
+				const claimed = await ctx.repo.findOneAndUpdate({ category: "reader" }, { category: "claimed" }, { sort: { createdAt: 1 } });
+				expect(claimed?.name).toBe("u1");
+				expect(claimed?.category).toBe("claimed");
+			});
+			it("returnDocument: \"before\" returns pre-update state", async () => {
+				if (!ctx.repo.findOneAndUpdate) return;
+				expect((await ctx.repo.findOneAndUpdate({ name: "u2" }, { category: "archived" }, { returnDocument: "before" }))?.category).toBe("reader");
+			});
+			it("no match, no upsert → returns null", async () => {
+				if (!ctx.repo.findOneAndUpdate) return;
+				expect(await ctx.repo.findOneAndUpdate({ name: "does-not-exist" }, { category: "x" })).toBeNull();
+			});
+			it.skipIf(!harness.features.upsert)("upsert inserts when no row matches", async () => {
+				if (!ctx.repo.findOneAndUpdate) return;
+				const inserted = await ctx.repo.findOneAndUpdate({ email: "brand-new@x.com" }, harness.makeDoc({
+					name: "Zed",
+					email: "brand-new@x.com",
+					category: "reader",
+					createdAt: isoAt(100)
+				}), { upsert: true });
+				expect(inserted?.name).toBe("Zed");
+				expect(inserted?.email).toBe("brand-new@x.com");
+			});
+		});
+		describe("updateMany / deleteMany", () => {
+			beforeEach(async () => {
+				await ctx.repo.createMany([
+					harness.makeDoc({
+						name: "a",
+						category: "reader",
+						count: 1
+					}),
+					harness.makeDoc({
+						name: "b",
+						category: "reader",
+						count: 2
+					}),
+					harness.makeDoc({
+						name: "c",
+						category: "admin",
+						count: 3
+					})
+				]);
+			});
+			it("updateMany affects only matching rows", async () => {
+				if (!ctx.repo.updateMany) return;
+				const result = await ctx.repo.updateMany({ category: "reader" }, { category: "former-reader" });
+				expect(result.matchedCount).toBe(2);
+				expect(result.modifiedCount).toBe(2);
+				expect(await ctx.repo.findAll({ category: "admin" })).toHaveLength(1);
+			});
+			it("updateMany with no match returns matchedCount 0", async () => {
+				if (!ctx.repo.updateMany) return;
+				const result = await ctx.repo.updateMany({ category: "nonexistent" }, { category: "x" });
+				expect(result.matchedCount).toBe(0);
+				expect(result.modifiedCount).toBe(0);
+			});
+			it("deleteMany removes matching rows and reports count", async () => {
+				if (!ctx.repo.deleteMany) return;
+				expect((await ctx.repo.deleteMany({ category: "reader" }, { mode: "hard" })).deletedCount).toBe(2);
+				expect(await ctx.repo.findAll()).toHaveLength(1);
+			});
+			it("deleteMany with empty match returns deletedCount 0", async () => {
+				if (!ctx.repo.deleteMany) return;
+				expect((await ctx.repo.deleteMany({ category: "nope" }, { mode: "hard" })).deletedCount).toBe(0);
+			});
+		});
+		describe("projections", () => {
+			beforeEach(async () => {
+				await ctx.repo.createMany([
+					harness.makeDoc({
+						name: "a",
+						category: "reader"
+					}),
+					harness.makeDoc({
+						name: "b",
+						category: "reader"
+					}),
+					harness.makeDoc({
+						name: "c",
+						category: "admin"
+					}),
+					harness.makeDoc({
+						name: "d",
+						category: null
+					}),
+					harness.makeDoc({
+						name: "e",
+						category: null
+					})
+				]);
+			});
+			it.skipIf(!harness.features.distinct)("distinct returns each unique value exactly once", async () => {
+				if (!ctx.repo.distinct) return;
+				const categories = await ctx.repo.distinct("category");
+				const set = new Set(categories);
+				expect(set.has("reader")).toBe(true);
+				expect(set.has("admin")).toBe(true);
+				const nullCount = categories.filter((v) => v === null).length;
+				expect(nullCount).toBeLessThanOrEqual(1);
+			});
+			it.skipIf(!harness.features.countAndExists)("count with filter matches expected rows", async () => {
+				if (!ctx.repo.count) return;
+				expect(await ctx.repo.count({ category: "reader" })).toBe(2);
+				expect(await ctx.repo.count({ category: "no-such" })).toBe(0);
+			});
+			it.skipIf(!harness.features.countAndExists)("exists is truthy when filter matches, falsy when it does not", async () => {
+				if (!ctx.repo.exists) return;
+				const hit = await ctx.repo.exists({ category: "reader" });
+				const miss = await ctx.repo.exists({ category: "no-such" });
+				expect(Boolean(hit)).toBe(true);
+				expect(Boolean(miss)).toBe(false);
+			});
+		});
+		describe("aggregate", () => {
+			beforeEach(async () => {
+				await ctx.repo.createMany([
+					harness.makeDoc({
+						name: "a",
+						category: "reader",
+						count: 10,
+						active: true
+					}),
+					harness.makeDoc({
+						name: "b",
+						category: "reader",
+						count: 20,
+						active: true
+					}),
+					harness.makeDoc({
+						name: "c",
+						category: "admin",
+						count: 30,
+						active: false
+					}),
+					harness.makeDoc({
+						name: "d",
+						category: "admin",
+						count: 40,
+						active: true
+					})
+				]);
+			});
+			it.skipIf(!harness.features.aggregate)("empty result set returns { rows: [] } (no throw)", async () => {
+				if (!ctx.repo.aggregate) return;
+				expect((await ctx.repo.aggregate({
+					filter: { category: "does-not-exist" },
+					groupBy: "category",
+					measures: { total: {
+						op: "sum",
+						field: "count"
+					} }
+				})).rows).toEqual([]);
+			});
+			it.skipIf(!harness.features.aggregate)("groupBy + sum produces one row per group with correct totals", async () => {
+				if (!ctx.repo.aggregate) return;
+				const result = await ctx.repo.aggregate({
+					groupBy: "category",
+					measures: { total: {
+						op: "sum",
+						field: "count"
+					} },
+					sort: { category: 1 }
+				});
+				expect(result.rows).toHaveLength(2);
+				const byCategory = {};
+				for (const row of result.rows) byCategory[row.category] = Number(row.total);
+				expect(byCategory["admin"]).toBe(70);
+				expect(byCategory["reader"]).toBe(30);
+			});
+			it.skipIf(!harness.features.aggregate)("scalar aggregate (no groupBy) returns single row", async () => {
+				if (!ctx.repo.aggregate) return;
+				const result = await ctx.repo.aggregate({ measures: {
+					total: {
+						op: "sum",
+						field: "count"
+					},
+					n: { op: "count" }
+				} });
+				expect(result.rows).toHaveLength(1);
+				expect(Number(result.rows[0]?.total)).toBe(100);
+				expect(Number(result.rows[0]?.n)).toBe(4);
+			});
+			it.skipIf(!harness.features.aggregate)("having filters aggregated rows by measure alias", async () => {
+				if (!ctx.repo.aggregate) return;
+				const result = await ctx.repo.aggregate({
+					groupBy: "category",
+					measures: { total: {
+						op: "sum",
+						field: "count"
+					} },
+					having: gt("total", 50)
+				});
+				expect(result.rows).toHaveLength(1);
+				expect(result.rows[0].category).toBe("admin");
+			});
+		});
+		describe("pagination edges", () => {
+			beforeEach(async () => {
+				for (let i = 0; i < 5; i++) await ctx.repo.create(harness.makeDoc({
+					name: `p${i}`,
+					count: i,
+					createdAt: isoAt(i)
+				}));
+			});
+			it("page beyond last returns empty docs array, total reflects real count", async () => {
+				const out = await ctx.repo.getAll({
+					page: 99,
+					limit: 10,
+					sort: "createdAt"
+				});
+				expect(Array.isArray(out.docs)).toBe(true);
+				expect(out.docs).toHaveLength(0);
+				expect(out.total).toBe(5);
+			});
+			it("limit larger than dataset returns all rows, no error", async () => {
+				const out = await ctx.repo.getAll({
+					page: 1,
+					limit: 1e3,
+					sort: "createdAt"
+				});
+				expect(out.docs).toHaveLength(5);
+				expect(out.total).toBe(5);
+			});
+			it("explicit filter in pagination narrows results consistently", async () => {
+				const out = await ctx.repo.getAll({
+					filters: { count: 3 },
+					page: 1,
+					limit: 10
+				});
+				expect(out.docs).toHaveLength(1);
+				expect(out.total).toBe(1);
+			});
+		});
+		describe("Filter IR compilation parity", () => {
+			beforeEach(async () => {
+				await ctx.repo.createMany([
+					harness.makeDoc({
+						name: "plain",
+						category: "a",
+						count: 1,
+						notes: "hello world"
+					}),
+					harness.makeDoc({
+						name: "pct",
+						category: "a",
+						count: 2,
+						notes: "50% off"
+					}),
+					harness.makeDoc({
+						name: "under",
+						category: "b",
+						count: 3,
+						notes: "file_name.txt"
+					}),
+					harness.makeDoc({
+						name: "back",
+						category: "b",
+						count: 4,
+						notes: "back\\slash"
+					}),
+					harness.makeDoc({
+						name: "nullnote",
+						category: null,
+						count: 5,
+						notes: null
+					})
+				]);
+			});
+			it("in_([]) matches nothing (not everything)", async () => {
+				expect(await ctx.repo.findAll(in_("category", []))).toHaveLength(0);
+			});
+			it("in_ with non-empty list matches those values", async () => {
+				expect(await ctx.repo.findAll(in_("category", ["a"]))).toHaveLength(2);
+			});
+			it("eq null matches rows where the field is null", async () => {
+				const rows = await ctx.repo.findAll(isNull("category"));
+				expect(rows).toHaveLength(1);
+				expect(rows[0]?.name).toBe("nullnote");
+			});
+			it("ne does not include null-valued rows (SQL 3VL / Mongo parity)", async () => {
+				expect((await ctx.repo.findAll(ne("category", "a"))).map((r) => r.name).sort()).toEqual(["back", "under"]);
+			});
+			it("like with % metacharacter in the value matches literally", async () => {
+				expect((await ctx.repo.findAll(like("notes", "50\\% off"))).map((r) => r.name)).toEqual(["pct"]);
+			});
+			it("like with _ metacharacter in the value matches literally", async () => {
+				expect((await ctx.repo.findAll(like("notes", "file\\_name.txt"))).map((r) => r.name)).toEqual(["under"]);
+			});
+			it("nested and/or composes correctly", async () => {
+				expect((await ctx.repo.findAll(or(and(eq("category", "a"), gt("count", 1)), eq("name", "back")))).map((r) => r.name).sort()).toEqual(["back", "pct"]);
+			});
+		});
+		describe.skipIf(!harness.features.duplicateKeyError)("isDuplicateKeyError", () => {
+			it("returns true for a unique-constraint / E11000 violation", async () => {
+				await ctx.repo.create(harness.makeDoc({
+					name: "dup",
+					email: "dup@x.com"
+				}));
+				let caught;
+				try {
+					await ctx.repo.create(harness.makeDoc({
+						name: "dup2",
+						email: "dup@x.com"
+					}));
+				} catch (err) {
+					caught = err;
+				}
+				expect(caught).toBeDefined();
+				expect(ctx.repo.isDuplicateKeyError?.(caught)).toBe(true);
+			});
+			it("returns false for unrelated errors", async () => {
+				const notDup = /* @__PURE__ */ new Error("something else");
+				expect(ctx.repo.isDuplicateKeyError?.(notDup)).toBe(false);
+				expect(ctx.repo.isDuplicateKeyError?.(null)).toBe(false);
+				expect(ctx.repo.isDuplicateKeyError?.("plain string")).toBe(false);
+			});
+		});
+		describe.skipIf(!harness.features.getOrCreate)("getOrCreate", () => {
+			it("inserts when no row matches filter", async () => {
+				if (!ctx.repo.getOrCreate) return;
+				expect((await ctx.repo.getOrCreate({ email: "fresh@x.com" }, harness.makeDoc({
+					name: "Fresh",
+					email: "fresh@x.com"
+				})))?.name).toBe("Fresh");
+				expect(await ctx.repo.findAll()).toHaveLength(1);
+			});
+			it("returns existing row when filter matches (no insert)", async () => {
+				if (!ctx.repo.getOrCreate) return;
+				await ctx.repo.create(harness.makeDoc({
+					name: "Existing",
+					email: "existing@x.com"
+				}));
+				expect((await ctx.repo.getOrCreate({ email: "existing@x.com" }, harness.makeDoc({
+					name: "WouldOverwrite",
+					email: "existing@x.com"
+				})))?.name).toBe("Existing");
+				expect(await ctx.repo.findAll()).toHaveLength(1);
+			});
+		});
+		describe.skipIf(!harness.features.transactions)("withTransaction", () => {
+			it("commits when callback resolves", async () => {
+				await ctx.repo.withTransaction(async (txRepo) => {
+					await txRepo.create(harness.makeDoc({
+						name: "tx-committed",
+						email: "c@x.com"
+					}));
+				});
+				expect(await ctx.repo.findAll({ name: "tx-committed" })).toHaveLength(1);
+			});
+			it("rolls back on thrown error — no row persists", async () => {
+				const err = /* @__PURE__ */ new Error("boom");
+				let caught;
+				try {
+					await ctx.repo.withTransaction(async (txRepo) => {
+						await txRepo.create(harness.makeDoc({
+							name: "tx-rollback",
+							email: "r@x.com"
+						}));
+						throw err;
+					});
+				} catch (e) {
+					caught = e;
+				}
+				expect(caught).toBe(err);
+				expect(await ctx.repo.findAll({ name: "tx-rollback" })).toHaveLength(0);
+			});
+			it("reads inside the txRepo see writes inside the same callback", async () => {
+				await ctx.repo.withTransaction(async (txRepo) => {
+					const id = idOf(await txRepo.create(harness.makeDoc({
+						name: "tx-read",
+						email: "rr@x.com"
+					})), harness.idField);
+					expect((await txRepo.getById(id))?.name).toBe("tx-read");
+				});
+			});
+		});
+	});
+}
+//#endregion
+export { runStandardRepoConformance };

package/dist/testing/index.d.mts

@@ -0,0 +1,3 @@
+import { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
+import { runStandardRepoConformance } from "./conformance.mjs";
+export { type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, runStandardRepoConformance };

package/dist/testing/index.mjs

@@ -0,0 +1,2 @@
+import { runStandardRepoConformance } from "./conformance.mjs";
+export { runStandardRepoConformance };