@classytic/repo-core 0.3.0 → 0.4.1

package/dist/testing/index.d.mts

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

package/dist/testing/index.mjs

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

package/dist/testing/lock-conformance.d.mts

@@ -0,0 +1,25 @@
+import { LockAdapter } from "../lock/index.mjs";
+
+//#region src/testing/lock-conformance.d.ts
+interface LockConformanceHarness {
+  /**
+   * Construct a fresh adapter for each describe block. May be async
+   * (e.g. SQL adapters that need to run a CREATE TABLE migration).
+   * The same adapter instance is shared by every test in the suite —
+   * `beforeEach` is responsible for clearing residual lock state.
+   */
+  createAdapter(): LockAdapter | Promise<LockAdapter>;
+  /**
+   * Wipe every lock between tests. Mongo: drop the collection.
+   * SQLite: `DELETE FROM kit_locks`. Memory: noop (factory returns
+   * a fresh `Map`).
+   *
+   * Required because tests share an adapter and acquire under
+   * conflicting names. A leaked lock from one test breaks the
+   * "first acquire wins" invariant in the next.
+   */
+  beforeEach?(adapter: LockAdapter): void | Promise<void>;
+}
+declare function runLockAdapterConformance(harness: LockConformanceHarness): void;
+//#endregion
+export { LockConformanceHarness, runLockAdapterConformance };

package/dist/testing/lock-conformance.mjs

@@ -0,0 +1,167 @@
+import { beforeEach, describe, expect, it } from "vitest";
+//#region src/testing/lock-conformance.ts
+/**
+* `runLockAdapterConformance` — cross-kit lock-adapter contract suite.
+*
+* Wires a kit-specific `LockConformanceHarness` to a canonical set of
+* scenarios that every `LockAdapter` implementation should pass. The
+* goal is parity: "swap mongokit/lock for sqlitekit/lock" must be a
+* provable claim, and behavior drift between backends shows up here
+* before it ships.
+*
+* Mirrors `runStandardRepoConformance` in shape — vitest is imported
+* at top of file (this subpath is test-only) and the harness gives
+* the kit one chance to construct the adapter, then handles cleanup
+* between scenarios.
+*
+* ## Usage from a kit
+*
+*     import { runLockAdapterConformance } from '@classytic/repo-core/testing';
+*     import { createMongoLockAdapter } from '../../src/lock/index.js';
+*
+*     describe('mongokit/lock conformance', () => {
+*       runLockAdapterConformance({
+*         createAdapter: () => createMongoLockAdapter({ collectionName: 'lock_conformance' }),
+*         async beforeEach() { await clearLocks(); },
+*       });
+*     });
+*/
+const A = "replica-A";
+const B = "replica-B";
+function runLockAdapterConformance(harness) {
+	describe("LockAdapter contract", () => {
+		let adapter;
+		beforeEach(async () => {
+			adapter = await harness.createAdapter();
+			await harness.beforeEach?.(adapter);
+		});
+		describe("tryAcquire", () => {
+			it("first acquire wins on a free lock", async () => {
+				expect(await adapter.tryAcquire("cron.outbox", A, 5e3)).toBe(true);
+			});
+			it("second acquire by a different holder fails while the first is live", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				expect(await adapter.tryAcquire("cron.outbox", B, 5e3)).toBe(false);
+			});
+			it("same holder may extend (idempotent re-acquire)", async () => {
+				expect(await adapter.tryAcquire("cron.outbox", A, 5e3)).toBe(true);
+				expect(await adapter.tryAcquire("cron.outbox", A, 5e3)).toBe(true);
+			});
+			it("expired lease is reclaimable by another holder", async () => {
+				expect(await adapter.tryAcquire("cron.outbox", A, 1)).toBe(true);
+				await sleep(10);
+				expect(await adapter.tryAcquire("cron.outbox", B, 5e3)).toBe(true);
+				expect(await adapter.tryAcquire("cron.outbox", A, 5e3)).toBe(false);
+			});
+			it("different lock names are independent", async () => {
+				expect(await adapter.tryAcquire("lock.one", A, 5e3)).toBe(true);
+				expect(await adapter.tryAcquire("lock.two", A, 5e3)).toBe(true);
+				expect(await adapter.tryAcquire("lock.one", B, 5e3)).toBe(false);
+			});
+			it("parallel acquires resolve to exactly one winner", async () => {
+				expect((await Promise.all([adapter.tryAcquire("shared.name", A, 5e3), adapter.tryAcquire("shared.name", B, 5e3)])).filter((r) => r === true)).toHaveLength(1);
+			});
+		});
+		describe("release", () => {
+			it("the holder can release their own lock", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				expect(await adapter.release("cron.outbox", A)).toBe(true);
+			});
+			it("a non-holder cannot release", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				expect(await adapter.release("cron.outbox", B)).toBe(false);
+			});
+			it("release on an unheld lock returns false (idempotent)", async () => {
+				expect(await adapter.release("never.acquired", A)).toBe(false);
+			});
+			it("after release, another holder can acquire", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				await adapter.release("cron.outbox", A);
+				expect(await adapter.tryAcquire("cron.outbox", B, 5e3)).toBe(true);
+			});
+			it("repeated release by the same holder returns false on the second call", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				expect(await adapter.release("cron.outbox", A)).toBe(true);
+				expect(await adapter.release("cron.outbox", A)).toBe(false);
+			});
+		});
+		describe("inspect", () => {
+			it("reports the current holder for a live lock", async () => {
+				if (!adapter.inspect) return;
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				const state = await adapter.inspect("cron.outbox");
+				expect(state).toBeTruthy();
+				expect(state?.name).toBe("cron.outbox");
+				expect(state?.holder).toBe(A);
+				expect(state?.expiresAt).toBeInstanceOf(Date);
+				expect(state?.acquiredAt).toBeInstanceOf(Date);
+			});
+			it("returns null for a never-acquired lock", async () => {
+				if (!adapter.inspect) return;
+				expect(await adapter.inspect("never.acquired")).toBeNull();
+			});
+			it("returns null for an expired lock (treats expired as absent)", async () => {
+				if (!adapter.inspect) return;
+				await adapter.tryAcquire("cron.outbox", A, 1);
+				await sleep(10);
+				expect(await adapter.inspect("cron.outbox")).toBeNull();
+			});
+			it("preserves acquiredAt across same-holder extensions", async () => {
+				if (!adapter.inspect) return;
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				const original = (await adapter.inspect("cron.outbox"))?.acquiredAt;
+				await sleep(5);
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				const extended = (await adapter.inspect("cron.outbox"))?.acquiredAt;
+				expect(extended?.getTime()).toBe(original?.getTime());
+			});
+		});
+		describe("post-steal semantics", () => {
+			it("the original holder cannot release after a steal", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 1);
+				await sleep(10);
+				await adapter.tryAcquire("cron.outbox", B, 5e3);
+				expect(await adapter.release("cron.outbox", A)).toBe(false);
+				if (adapter.inspect) expect((await adapter.inspect("cron.outbox"))?.holder).toBe(B);
+			});
+		});
+		describe("stress", () => {
+			it("50 concurrent holders against one name → exactly one winner", async () => {
+				const holders = Array.from({ length: 50 }, (_, i) => `replica-${i}`);
+				expect((await Promise.all(holders.map((h) => adapter.tryAcquire("contended", h, 5e3)))).filter((r) => r === true)).toHaveLength(1);
+			});
+			it("100 sequential acquire/release cycles leave no residue", async () => {
+				for (let i = 0; i < 100; i++) {
+					expect(await adapter.tryAcquire("cycled", A, 5e3)).toBe(true);
+					expect(await adapter.release("cycled", A)).toBe(true);
+				}
+				expect(await adapter.tryAcquire("cycled", B, 5e3)).toBe(true);
+			});
+			it("100 same-holder extensions preserve the original acquiredAt", async () => {
+				if (!adapter.inspect) return;
+				await adapter.tryAcquire("extended", A, 5e3);
+				const original = (await adapter.inspect("extended"))?.acquiredAt;
+				expect(original).toBeTruthy();
+				for (let i = 0; i < 100; i++) await adapter.tryAcquire("extended", A, 5e3);
+				const final = (await adapter.inspect("extended"))?.acquiredAt;
+				expect(final?.getTime()).toBe(original?.getTime());
+			});
+			it("ownership churn: A → B → C → A handovers each succeed atomically", async () => {
+				for (const holder of [
+					A,
+					B,
+					"replica-C",
+					A
+				]) {
+					expect(await adapter.tryAcquire("churn", holder, 5e3)).toBe(true);
+					expect(await adapter.release("churn", holder)).toBe(true);
+				}
+			});
+		});
+	});
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+//#endregion
+export { runLockAdapterConformance };

package/dist/testing/types.d.mts

@@ -26,6 +26,70 @@ interface ConformanceDoc {
   notes: string | null;
   createdAt: string;
 }
+/**
+ * Per-aggregate-op support matrix. Some aggregate ops aren't
+ * portable across every backend — `percentile` requires Mongo 7+'s
+ * `$percentile` accumulator or SQL's `PERCENTILE_CONT`, neither of
+ * which sqlitekit ships. Scenarios that exercise a non-universal
+ * op gate on the matching flag and `it.skip` on the off branch so
+ * the suite runs cleanly across every environment.
+ *
+ * **Stability contract.** Adding a flag here is additive — kits
+ * that don't declare the new key default to `false`, which is the
+ * conservative choice. Renaming or removing a flag is a breaking
+ * change.
+ *
+ * **Naming convention.** Flag names match the IR field they gate
+ * (`percentile` → `AggMeasure.op === 'percentile'`). When in doubt,
+ * grep the IR types and use the same identifier.
+ */
+interface AggregateOpsSupport {
+  /**
+   * `{ op: 'percentile', field, p }` measure. Mongokit (Mongo 7+)
+   * supports it; sqlitekit throws by design (no native function).
+   * Hosts targeting percentile dashboards pin to a kit that supports it.
+   */
+  percentile?: boolean;
+  /**
+   * `{ op: 'stddev', field }` / `{ op: 'stddevPop', field }` measures.
+   * Mongokit supports both via native `$stdDevSamp` / `$stdDevPop`
+   * (Welford). Sqlitekit throws — SQLite has no native STDDEV and
+   * the computational formula is numerically unstable. Hosts pin
+   * to mongokit / future pgkit when stddev is load-bearing.
+   */
+  stddev?: boolean;
+  /**
+   * `topN: { partitionBy, sortBy, limit, ties }` filter. Both
+   * mongokit and sqlitekit support it as of repo-core 0.4.x; the
+   * flag exists for future kits that may not ship window-function
+   * equivalents.
+   */
+  topN?: boolean;
+  /**
+   * `dateBuckets: { ..., interval: { every, unit } }` custom-bin
+   * form. Kits that only support named-bucket form can leave this
+   * `false`; tests for `'minute'` / `'hour'` named intervals are
+   * gated separately via `dateBucketSubMinute`.
+   */
+  customDateBuckets?: boolean;
+  /**
+   * Sub-day-granularity named buckets (`'minute'` / `'hour'`).
+   * Older kits may only support day+ named intervals; flag exists
+   * to gate those scenarios cleanly.
+   */
+  dateBucketSubMinute?: boolean;
+  /**
+   * Per-request `cache?: AggCacheOptions` slot — TTL / tags / SWR /
+   * bypass / `repo.invalidateAggregateCache(tags)`. Both mongokit
+   * and sqlitekit support it as of repo-core 0.4.x. Future kits
+   * without the wiring can leave this false to skip cache scenarios.
+   *
+   * Independent of which CACHE BACKEND the harness wires — test
+   * scenarios construct their own `createMemoryCacheAdapter()` so
+   * this flag is purely "does the kit honour the request slot".
+   */
+  cache?: boolean;
+}
 /**
  * Per-backend feature flags. Scenarios that exercise a non-universal
  * capability (transactions in D1, upsert in narrow stores) check the
@@ -48,8 +112,22 @@ interface ConformanceFeatures {
   duplicateKeyError: boolean;
   /** `distinct(field)`. */
   distinct: boolean;
-  /** Portable `aggregate({ measures, groupBy, having })`. */
+  /**
+   * Portable `aggregate({ measures, groupBy, having })`. Coarse
+   * top-level flag — gates the entire `describe('aggregate')` block.
+   * Per-op flags live on `aggregateOps` for asymmetric capabilities
+   * (percentile, custom date bins, etc.) that some kits skip while
+   * still supporting the core aggregate surface.
+   */
   aggregate: boolean;
+  /**
+   * Per-op feature matrix for the aggregate surface. Optional —
+   * absent matrix or absent key both mean "not supported", so kits
+   * opt INTO scenarios for ops they implement. This avoids the
+   * trap where a future kit silently fails percentile tests because
+   * it forgot to set the flag.
+   */
+  aggregateOps?: AggregateOpsSupport;
   /** `getOrCreate(filter, data)`. */
   getOrCreate: boolean;
   /** `count(filter)` and `exists(filter)`. */
@@ -69,6 +147,25 @@ interface ConformanceContext<TDoc extends ConformanceDoc = ConformanceDoc> {
    * be omitted; scenarios that need it will skip if missing.
    */
   secondaryRepo?: StandardRepo<TDoc> & MinimalRepo<TDoc>;
+  /**
+   * Optional repo-with-cache for cache-suite scenarios. Required iff
+   * the harness declares `features.aggregateOps.cache === true`.
+   *
+   * **Why a separate repo** rather than reconfiguring the primary
+   * one: cache state survives across calls within a test, and the
+   * primary repo is shared by every other suite. A dedicated cached
+   * repo keeps the cache scenarios hermetic.
+   *
+   * The bound type widens to include `invalidateAggregateCache` —
+   * cast at the use site since the contract type
+   * (`StandardRepo<TDoc>`) doesn't currently surface it. This
+   * intentionally leaves the contract narrower than the
+   * implementation; consumers pin to a specific kit when they need
+   * the invalidate method on their `RepositoryLike` slot.
+   */
+  cachedRepo?: StandardRepo<TDoc> & MinimalRepo<TDoc> & {
+    invalidateAggregateCache(tags?: readonly string[]): Promise<number>;
+  };
   /** Release resources (close db, drop collection). Must be idempotent. */
   cleanup(): Promise<void>;
 }
@@ -110,4 +207,4 @@ interface ConformanceHarness<TDoc extends ConformanceDoc = ConformanceDoc> {
   makeDoc(overrides?: Partial<ConformanceDoc>): Partial<TDoc>;
 }
 //#endregion
-export { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness };
+export { AggregateOpsSupport, ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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.",
   "type": "module",
   "sideEffects": false,
@@ -70,6 +70,26 @@
       "types": "./dist/lookup/index.d.mts",
       "default": "./dist/lookup/index.mjs"
     },
+    "./adapter": {
+      "types": "./dist/adapter/index.d.mts",
+      "default": "./dist/adapter/index.mjs"
+    },
+    "./better-auth": {
+      "types": "./dist/better-auth/index.d.mts",
+      "default": "./dist/better-auth/index.mjs"
+    },
+    "./aggregate": {
+      "types": "./dist/aggregate/index.d.mts",
+      "default": "./dist/aggregate/index.mjs"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.mts",
+      "default": "./dist/plugins/index.mjs"
+    },
+    "./lock": {
+      "types": "./dist/lock/index.d.mts",
+      "default": "./dist/lock/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "keywords": [
@@ -105,6 +125,7 @@
     "test:e2e": "vitest run --project e2e",
     "test:all": "vitest run",
     "test:watch": "vitest --project unit --project integration",
+    "bench": "vitest bench --run --project bench",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
     "lint": "biome check src tests",
@@ -125,6 +146,7 @@
     "@classytic/dev-tools": "^0.2.0",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.4",
+    "fast-check": "^4.7.0",
     "knip": "^6.3.0",
     "publint": "^0.3.18",
     "tsdown": "^0.21.8",

package/dist/cache/stable-stringify.d.mts

@@ -1,15 +0,0 @@
-//#region src/cache/stable-stringify.d.ts
-/**
- * Deterministic JSON stringify — equivalent values produce identical output.
- *
- * Used by kits that build cache keys from hook contexts so
- * `{ b: 1, a: 2 }` and `{ a: 2, b: 1 }` hash to the same bucket. Arrays
- * preserve order (order is part of array identity).
- *
- * Extracted from the mongokit / sqlitekit cache plugins into repo-core so
- * every kit's cachePlugin uses the same keying rule — cross-kit caches
- * remain bucket-compatible.
- */
-declare function stableStringify(value: unknown): string;
-//#endregion
-export { stableStringify };