@classytic/repo-core 0.3.0 → 0.4.0

package/dist/testing/index.d.mts

@@ -1,3 +1,3 @@
-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 };
+export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, runStandardRepoConformance };

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.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.",
   "type": "module",
   "sideEffects": false,
@@ -70,6 +70,22 @@
       "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"
+    },
     "./package.json": "./package.json"
   },
   "keywords": [
@@ -105,6 +121,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 +142,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 };