@classytic/repo-core 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.20.0] - 2026-08-04
+
+### Added
+
+- **`ResolveBetterAuthCollectionsOptions.exclude`** — canonical collection names
+  to omit from `resolveBetterAuthCollections()` output. Applied before
+  `modelOverrides` / `usePlural` so a caller names the canonical collection
+  (`'user'`) and never has to predict the final model name. Solves the collision
+  when a host registers stub models for BA collections it merely references and a
+  full `createBetterAuthOverlay` for the one it exposes CRUD on — both for the
+  same collection would cause mongoose to lock the schema on first `model()`,
+  silently dropping `additionalFields` and causing the overlay to refuse.
+
 ## [0.19.0] - 2026-07-29
 
 ### Added — `coerceFilterDates` + ISO date helpers (`./filter`)

package/dist/better-auth/index.d.mts

@@ -71,6 +71,18 @@ interface ResolveBetterAuthCollectionsOptions {
    * @default []
    */
   plugins?: BetterAuthPluginKey[];
+  /**
+   * CANONICAL collection names to omit from the result.
+   *
+   * The reason this exists: a host commonly needs stub models for the BA collections it merely
+   * REFERENCES and a full `createBetterAuthOverlay` for the one it exposes CRUD on. Registering both
+   * for the same collection collides — mongoose locks a schema on first `model()`, so the overlay's
+   * `additionalFields` would be silently dropped, and the overlay therefore refuses.
+   *
+   * Applied BEFORE `modelOverrides` / `usePlural`, so a caller names the canonical collection and
+   * never has to predict the final model name.
+   */
+  exclude?: string[];
   /**
    * Additional collection names beyond the built-in plugin set.
    *

package/dist/better-auth/index.mjs

@@ -52,7 +52,8 @@ function pluralizeBetterAuthCollection(name) {
 * collection names. `core` is always included.
 */
 function resolveBetterAuthCollections(options = {}) {
-	const { plugins = [], extraCollections = [], usePlural = false, modelOverrides = {} } = options;
+	const { plugins = [], extraCollections = [], usePlural = false, modelOverrides = {}, exclude = [] } = options;
+	const excluded = new Set(exclude);
 	const pluginSet = /* @__PURE__ */ new Set(["core", ...plugins]);
 	const collected = [];
 	for (const key of pluginSet) for (const name of BA_COLLECTIONS_BY_PLUGIN[key]) collected.push(name);
@@ -62,6 +63,12 @@ function resolveBetterAuthCollections(options = {}) {
 	for (const canonical of collected) {
 		if (seen.has(canonical)) continue;
 		seen.add(canonical);
+		/**
+		* Excluded HERE, while the CANONICAL name is still in hand — before `modelOverrides` /
+		* `usePlural` produce the final name. A caller excluding `'user'` should not have to predict
+		* whether that becomes `users` or something a `modelName` override renamed it to.
+		*/
+		if (excluded.has(canonical)) continue;
 		const finalName = modelOverrides[canonical] ?? (usePlural ? pluralizeBetterAuthCollection(canonical) : canonical);
 		unique.push(finalName);
 	}

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

@@ -0,0 +1,15 @@
+//#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 };

package/dist/filter/coerce-dates.d.mts

@@ -60,6 +60,28 @@ declare function tryCoerceIsoDate(value: unknown): unknown;
  * // → { $and: [{ createdAt: { $gte: Date(2026-04-01) } }] }
  * ```
  */
-declare function coerceFilterDates(filter: Record<string, unknown>): Record<string, unknown>;
+interface CoerceFilterDatesOptions {
+  /**
+   * Schema oracle: given a field path, is it actually date-typed?
+   *
+   * WITHOUT this the coercion is a guess based only on how the VALUE looks, and the guess
+   * is wrong for any string column whose contents happen to be ISO-shaped — a civil date
+   * (`'2026-08-02'`), a version, a period key. Coercing there produces the exact failure
+   * this function exists to prevent, in reverse: the bound becomes a Date, BSON will not
+   * compare Date to String, and the range silently matches NOTHING.
+   *
+   * That cost real time. A sales-fact reconciler filtered `civilDate` — a `String` field
+   * holding `'YYYY-MM-DD'` — with `$gte`/`$lte`. The bounds were coerced to Dates, the
+   * aggregate returned zero rows for every window, and the report therefore accused the
+   * PROJECTOR of having written nothing, for every cell, forever. The projection was
+   * correct the whole time; the reconciler was comparing a Date to a String.
+   *
+   * Return `false` to leave the operand exactly as given. Omit the option entirely to keep
+   * the old value-shape-only behaviour (correct for callers with no schema to consult,
+   * such as a URL query parser).
+   */
+  isDateField?: (field: string) => boolean;
+}
+declare function coerceFilterDates(filter: Record<string, unknown>, options?: CoerceFilterDatesOptions): Record<string, unknown>;
 //#endregion
-export { ISO_DATE_PATTERN, coerceFilterDates, tryCoerceIsoDate };
+export { CoerceFilterDatesOptions, ISO_DATE_PATTERN, coerceFilterDates, tryCoerceIsoDate };

package/dist/filter/coerce-dates.mjs

@@ -83,33 +83,22 @@ const LOGICAL_OBJECT_OPS = /* @__PURE__ */ new Set(["$not", "not"]);
 function isPlainObject(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
 }
-/**
-* Walk a record-shape filter and coerce ISO-date strings on range operators
-* to `Date`, recursing through logical wrappers. Returns a new object;
-* the input is never mutated. Non-range operators, real nested documents,
-* and already-typed values pass through unchanged.
-*
-* @example
-* ```ts
-* coerceFilterDates({ $and: [{ createdAt: { $gte: '2026-04-01' } }] })
-* // → { $and: [{ createdAt: { $gte: Date(2026-04-01) } }] }
-* ```
-*/
-function coerceFilterDates(filter) {
+function coerceFilterDates(filter, options) {
 	const out = {};
 	for (const [key, value] of Object.entries(filter)) {
 		if (LOGICAL_ARRAY_OPS.has(key) && Array.isArray(value)) {
-			out[key] = value.map((entry) => isPlainObject(entry) ? coerceFilterDates(entry) : entry);
+			out[key] = value.map((entry) => isPlainObject(entry) ? coerceFilterDates(entry, options) : entry);
 			continue;
 		}
 		if (LOGICAL_OBJECT_OPS.has(key) && isPlainObject(value)) {
-			out[key] = coerceFilterDates(value);
+			out[key] = coerceFilterDates(value, options);
 			continue;
 		}
 		if (isPlainObject(value)) {
 			let changed = false;
 			const coerced = {};
-			for (const [op, operand] of Object.entries(value)) if (RANGE_OPS.has(op)) {
+			const coercible = options?.isDateField === void 0 || options.isDateField(key);
+			for (const [op, operand] of Object.entries(value)) if (coercible && RANGE_OPS.has(op)) {
 				const next = tryCoerceIsoDate(operand);
 				coerced[op] = next;
 				if (next !== operand) changed = true;

package/dist/hash/index.d.mts

@@ -0,0 +1,14 @@
+import { stableStringify } from "../cache/stable-stringify.mjs";
+//#region src/hash/index.d.ts
+/**
+ * SHA-256 hex digest of a value's canonical (key-order-independent) JSON form.
+ * Equivalent inputs → identical digest. `algorithm` may be any hash Node's
+ * `crypto` supports (default `'sha256'`); `encoding` the digest format
+ * (default `'hex'`).
+ */
+declare function contentHash(value: unknown, options?: {
+  algorithm?: string;
+  encoding?: 'hex' | 'base64' | 'base64url';
+}): string;
+//#endregion
+export { contentHash, stableStringify };

package/dist/hash/index.mjs

@@ -0,0 +1,31 @@
+import { stableStringify } from "../cache/stable-stringify.mjs";
+import { createHash } from "node:crypto";
+//#region src/hash/index.ts
+/**
+* Content-addressing — a stable cryptographic hash of any JSON-serializable value.
+*
+* `contentHash(value)` produces the SAME hex digest for structurally-equal values
+* regardless of object key order, so it's suitable for content-addressing:
+* reproducibility snapshots, idempotency keys, ETags, and dedupe. It builds on
+* {@link stableStringify} (canonical JSON) and SHA-256.
+*
+* This is DISTINCT from the cache module's `fnv1a64`: that is a fast,
+* collision-tolerant NON-cryptographic hash for cache-key bucketing. Use
+* `contentHash` when a collision would be a correctness or integrity problem
+* (e.g. "does this recomputation match the stored result?").
+*
+* `Date` values serialize via their ISO string (JSON.stringify default), so a
+* value carrying dates hashes stably across a JSON round-trip.
+*/
+/**
+* SHA-256 hex digest of a value's canonical (key-order-independent) JSON form.
+* Equivalent inputs → identical digest. `algorithm` may be any hash Node's
+* `crypto` supports (default `'sha256'`); `encoding` the digest format
+* (default `'hex'`).
+*/
+function contentHash(value, options = {}) {
+	const { algorithm = "sha256", encoding = "hex" } = options;
+	return createHash(algorithm).update(stableStringify(value)).digest(encoding);
+}
+//#endregion
+export { contentHash, stableStringify };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@classytic/repo-core",
-	"version": "0.19.0",
+	"version": "0.20.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,
@@ -54,6 +54,10 @@
 			"types": "./dist/cache/index.d.mts",
 			"default": "./dist/cache/index.mjs"
 		},
+		"./hash": {
+			"types": "./dist/hash/index.d.mts",
+			"default": "./dist/hash/index.mjs"
+		},
 		"./events": {
 			"types": "./dist/events/index.d.mts",
 			"default": "./dist/events/index.mjs"