@classytic/repo-core 0.5.0 → 0.6.1

package/dist/schema/standard-schema.mjs

@@ -0,0 +1,59 @@
+import { ERROR_CODES } from "../errors/types.mjs";
+//#region src/schema/standard-schema.ts
+/**
+* Standard Schema integration — the validator-agnostic validation slot.
+*
+* [Standard Schema](https://standardschema.dev) is the shared interface
+* implemented by Zod 3.24+, Valibot 1.0+, ArkType 2.0+, Effect Schema and
+* others. Vendoring the interface (officially encouraged — it's a
+* types-only spec designed to be copied) keeps repo-core's zero-dependency
+* guarantee while letting hosts plug ANY conforming validator into a
+* repository:
+*
+* ```ts
+* import { z } from 'zod';
+*
+* const repo = createRepository(UserModel, {
+*   schema: z.object({ name: z.string(), email: z.string().email() }),
+* });
+* await repo.create({ name: 1 }); // throws HttpError 400 with validationErrors
+* ```
+*
+* `RepositoryBase` wires `schema` / `updateSchema` into `before:create` /
+* `before:createMany` / `before:update` hooks at `HOOK_PRIORITY.VALIDATION`
+* — after policy plugins (so tenant-stamped fields are present) and before
+* cache/observability.
+*/
+/** Dot-path string from a Standard Schema issue path. */
+function issuePath(issue) {
+	if (!issue.path || issue.path.length === 0) return "";
+	return issue.path.map((seg) => String(typeof seg === "object" && seg !== null && "key" in seg ? seg.key : seg)).join(".");
+}
+/**
+* Validate `data` against a Standard Schema. Returns the schema's typed
+* output (validators may coerce/transform) or throws an `HttpError` 400
+* carrying `validationErrors` + structured `meta.issues` — the same wire
+* shape every kit's own validation errors serialize to.
+*/
+async function validateStandardSchema(schema, data) {
+	let result = schema["~standard"].validate(data);
+	if (result instanceof Promise) result = await result;
+	if (result.issues) {
+		const validationErrors = result.issues.map((issue) => ({
+			validator: schema["~standard"].vendor,
+			error: issuePath(issue) ? `${issuePath(issue)}: ${issue.message}` : issue.message
+		}));
+		throw Object.assign(/* @__PURE__ */ new Error("Validation failed"), {
+			status: 400,
+			code: ERROR_CODES.VALIDATION,
+			validationErrors,
+			meta: { issues: result.issues.map((issue) => ({
+				path: issuePath(issue) || void 0,
+				message: issue.message
+			})) }
+		});
+	}
+	return result.value;
+}
+//#endregion
+export { validateStandardSchema };

package/dist/tenant/resolve.d.mts

@@ -10,18 +10,8 @@ import { ResolvedTenantConfig, TenantConfig } from "./types.mjs";
  * runtime default — `Pick<TenantConfig, 'fieldType'>` extension preserves
  * type-level alignment without forcing a runtime default change.
  */
-declare const DEFAULT_TENANT_CONFIG: Required<Pick<TenantConfig, 'strategy' | 'enabled' | 'tenantField' | 'fieldType' | 'ref' | 'contextKey' | 'required'>>;
-/**
- * Resolve a possibly-partial {@link TenantConfig} against the defaults.
- *
- * - `false` → `enabled: false`, `strategy: 'none'`, `required: false`.
- * - `true` / `undefined` → default field strategy.
- * - Object with `strategy: 'custom'` → `resolve` is required; throws
- *   otherwise so the misconfiguration surfaces at boot, not runtime.
- * - Object with `strategy: 'none'` → `enabled: false` (preserves
- *   user-supplied `tenantField` / `fieldType` / `ref` so the doc field
- *   stays correctly typed even with scoping off).
- */
+type TenantDefaults = { [K in 'strategy' | 'enabled' | 'tenantField' | 'fieldType' | 'ref' | 'contextKey' | 'required']-?: Exclude<TenantConfig[K], undefined> };
+declare const DEFAULT_TENANT_CONFIG: TenantDefaults;
 declare function resolveTenantConfig(config?: TenantConfig | boolean): ResolvedTenantConfig;
 //#endregion
 export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };

package/dist/tenant/resolve.mjs

@@ -1,13 +1,4 @@
 //#region src/tenant/resolve.ts
-/**
-* Sensible defaults for a freshly-built package (field strategy).
-*
-* `fieldType: 'objectId'` is the recommended default for new Mongo-shaped
-* kits because it enables `$lookup` / `.populate()`. Existing kits that
-* historically defaulted to `'string'` (mongokit pre-3.x) keep their own
-* runtime default — `Pick<TenantConfig, 'fieldType'>` extension preserves
-* type-level alignment without forcing a runtime default change.
-*/
 const DEFAULT_TENANT_CONFIG = {
 	strategy: "field",
 	enabled: true,
@@ -17,17 +8,11 @@ const DEFAULT_TENANT_CONFIG = {
 	contextKey: "organizationId",
 	required: true
 };
-/**
-* Resolve a possibly-partial {@link TenantConfig} against the defaults.
-*
-* - `false` → `enabled: false`, `strategy: 'none'`, `required: false`.
-* - `true` / `undefined` → default field strategy.
-* - Object with `strategy: 'custom'` → `resolve` is required; throws
-*   otherwise so the misconfiguration surfaces at boot, not runtime.
-* - Object with `strategy: 'none'` → `enabled: false` (preserves
-*   user-supplied `tenantField` / `fieldType` / `ref` so the doc field
-*   stays correctly typed even with scoping off).
-*/
+function stripUndefined(obj) {
+	const out = {};
+	for (const [k, v] of Object.entries(obj)) if (v !== void 0) out[k] = v;
+	return out;
+}
 function resolveTenantConfig(config) {
 	if (config === false) return {
 		...DEFAULT_TENANT_CONFIG,
@@ -36,33 +21,34 @@ function resolveTenantConfig(config) {
 		required: false
 	};
 	if (config === true || config === void 0) return { ...DEFAULT_TENANT_CONFIG };
-	const strategy = config.strategy ?? (config.enabled === false ? "none" : "field");
-	const contextKey = config.contextKey ?? config.tenantField ?? DEFAULT_TENANT_CONFIG.contextKey;
+	const cleaned = stripUndefined(config);
+	const strategy = cleaned.strategy ?? (cleaned.enabled === false ? "none" : "field");
+	const contextKey = cleaned.contextKey ?? cleaned.tenantField ?? DEFAULT_TENANT_CONFIG.contextKey;
 	if (strategy === "none") return {
 		...DEFAULT_TENANT_CONFIG,
-		...config,
+		...cleaned,
 		contextKey,
 		strategy: "none",
 		enabled: false,
 		required: false
 	};
 	if (strategy === "custom") {
-		if (typeof config.resolve !== "function") throw new Error("[repo-core] TenantConfig.strategy 'custom' requires a 'resolve' function");
+		if (typeof cleaned.resolve !== "function") throw new Error("[repo-core] TenantConfig.strategy 'custom' requires a 'resolve' function");
 		return {
 			...DEFAULT_TENANT_CONFIG,
-			...config,
+			...cleaned,
 			contextKey,
 			strategy: "custom",
-			enabled: config.enabled ?? true,
-			resolve: config.resolve
+			enabled: cleaned.enabled ?? true,
+			resolve: cleaned.resolve
 		};
 	}
 	return {
 		...DEFAULT_TENANT_CONFIG,
-		...config,
+		...cleaned,
 		contextKey,
 		strategy: "field",
-		enabled: config.enabled ?? true
+		enabled: cleaned.enabled ?? true
 	};
 }
 //#endregion

package/dist/tenant/types.d.mts

@@ -50,7 +50,7 @@ interface TenantConfig {
    *
    * @default 'field'
    */
-  strategy?: TenantStrategy;
+  strategy?: TenantStrategy | undefined;
   /**
    * Whether tenant scoping is active. When `false`, the package runs in
    * single-tenant mode — no filter injection, no tenant field on documents.
@@ -58,27 +58,27 @@ interface TenantConfig {
    *
    * @default true
    */
-  enabled?: boolean;
+  enabled?: boolean | undefined;
   /**
    * Document / column field name that stores the tenant id. Used when
    * `strategy === 'field'`.
    *
    * @default 'organizationId'
    */
-  tenantField?: string;
+  tenantField?: string | undefined;
   /**
    * How to store / cast the tenant id.
    *
    * @default 'objectId'
    */
-  fieldType?: TenantFieldType;
+  fieldType?: TenantFieldType | undefined;
   /**
    * Mongoose ref for `'objectId'` types. Ignored by SQL kits and when
    * `fieldType === 'string'`.
    *
    * @default 'organization'
    */
-  ref?: string;
+  ref?: string | undefined;
   /**
    * Which key on the repository context to read the tenant id from.
    *
@@ -92,14 +92,14 @@ interface TenantConfig {
    *
    * @default tenantField ?? 'organizationId'
    */
-  contextKey?: string;
+  contextKey?: string | undefined;
   /**
    * Whether the field is required. When `false`, the package permits
    * unscoped / cross-tenant reads (typically only for admin paths).
    *
    * @default true
    */
-  required?: boolean;
+  required?: boolean | undefined;
   /**
    * Custom resolver — called when `strategy === 'custom'` to produce the
    * filter object injected into queries. Packages pass the request /
@@ -121,7 +121,7 @@ interface TenantConfig {
    * }
    * ```
    */
-  resolve?: (ctx: Record<string, unknown>) => Record<string, unknown>;
+  resolve?: (ctx: Record<string, unknown>) => Record<string, unknown> | undefined;
 }
 /**
  * Resolved shape returned by `resolveTenantConfig`. Always includes the
@@ -136,7 +136,7 @@ type ResolvedTenantConfig = {
   ref: string;
   contextKey: string;
   required: boolean;
-  resolve?: TenantConfig['resolve'];
+  resolve?: TenantConfig['resolve'] | undefined;
 };
 //#endregion
 export { ResolvedTenantConfig, TenantConfig, TenantFieldType, TenantStrategy };

package/dist/testing/index.d.mts

@@ -1,4 +1,5 @@
-import { AggregateOpsSupport, ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
+import { AggregateOpsSupport } from "../repository/capabilities.mjs";
+import { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
 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/types.d.mts

@@ -1,3 +1,4 @@
+import { AggregateOpsSupport, RepoCapabilities } from "../repository/capabilities.mjs";
 import { MinimalRepo, StandardRepo } from "../repository/types.mjs";
 
 //#region src/testing/types.d.ts
@@ -27,119 +28,18 @@ interface ConformanceDoc {
   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.
+ * Per-backend feature flags — an alias of the runtime
+ * {@link RepoCapabilities} descriptor (one shape, no drift). Scenarios
+ * that exercise a non-universal capability (transactions in D1, upsert
+ * in narrow stores) check the flag and `it.skip` on the off branch — so
+ * the suite runs on every environment without "optional test failed"
+ * noise.
  *
- * **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
- * flag and `it.skip` on the off branch — so the suite runs on every
- * environment without "optional test failed" noise.
+ * **Single source of truth.** Kits declare `repo.capabilities` at
+ * runtime and pass the SAME object as the harness's `features` — what a
+ * kit claims to support is exactly what the conformance suite verifies.
  */
-interface ConformanceFeatures {
-  /** `withTransaction(fn)` — D1 throws, standalone Mongo throws 263. */
-  transactions: boolean;
-  /**
-   * True if calling `withTransaction` inside another `withTransaction`
-   * callback is expected to work. Mongo's driver supports it via the
-   * same session; SQL drivers typically reject it. Either behavior is
-   * valid — the scenario asserts whichever the harness declares.
-   */
-  nestedTransactions: boolean;
-  /** `findOneAndUpdate` with upsert: true. */
-  upsert: boolean;
-  /** `isDuplicateKeyError(err)` classifier. */
-  duplicateKeyError: boolean;
-  /** `distinct(field)`. */
-  distinct: boolean;
-  /**
-   * 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)`. */
-  countAndExists: boolean;
-  /**
-   * `purgeByField(field, value, strategy, options)` — compliance-grade
-   * tenant cleanup primitive. Both mongokit and sqlitekit ship this as
-   * of repo-core 0.x. Future kits without it leave the flag absent
-   * (defaults to false) and skip the cleanup scenarios.
-   */
-  purgeByField?: boolean;
-}
+type ConformanceFeatures = RepoCapabilities;
 /**
  * One-shot context produced by `harness.setup()`. Scenarios receive a
  * fresh context per test — the harness is responsible for isolation
@@ -214,4 +114,4 @@ interface ConformanceHarness<TDoc extends ConformanceDoc = ConformanceDoc> {
   makeDoc(overrides?: Partial<ConformanceDoc>): Partial<TDoc>;
 }
 //#endregion
-export { AggregateOpsSupport, ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness };
+export { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness };

package/package.json

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