@classytic/repo-core 0.1.0

package/dist/filter/walk.mjs

@@ -0,0 +1,77 @@
+//#region src/filter/walk.ts
+/**
+* Depth-first visit of every node. Visitor returns `false` to stop descent
+* into the current subtree (e.g. optimization prunes). Otherwise visits
+* children.
+*/
+function walkFilter(filter, visit) {
+	if (visit(filter) === false) return;
+	switch (filter.op) {
+		case "and":
+		case "or":
+			for (const child of filter.children) walkFilter(child, visit);
+			return;
+		case "not":
+			walkFilter(filter.child, visit);
+			return;
+		default: return;
+	}
+}
+/**
+* Post-order transform. `transform` sees every node after its children have
+* been rewritten, so leaf rewrites cascade up. Return the same node
+* reference to opt-out of a rewrite at that level.
+*
+* Guarantees:
+* - Immutable — never mutates input.
+* - Identity-preserving — when no child changes, the parent node is
+*   returned unchanged (useful for structural sharing in caches).
+*/
+function mapFilter(filter, transform) {
+	switch (filter.op) {
+		case "and": {
+			let changed = false;
+			const next = [];
+			for (const child of filter.children) {
+				const mapped = mapFilter(child, transform);
+				if (mapped !== child) changed = true;
+				next.push(mapped);
+			}
+			return transform(changed ? Object.freeze({
+				op: "and",
+				children: Object.freeze(next)
+			}) : filter);
+		}
+		case "or": {
+			let changed = false;
+			const next = [];
+			for (const child of filter.children) {
+				const mapped = mapFilter(child, transform);
+				if (mapped !== child) changed = true;
+				next.push(mapped);
+			}
+			return transform(changed ? Object.freeze({
+				op: "or",
+				children: Object.freeze(next)
+			}) : filter);
+		}
+		case "not": {
+			const mapped = mapFilter(filter.child, transform);
+			return transform(mapped === filter.child ? filter : Object.freeze({
+				op: "not",
+				child: mapped
+			}));
+		}
+		default: return transform(filter);
+	}
+}
+/** Collect every field name referenced in the tree. Useful for index hints, policy checks. */
+function collectFields(filter) {
+	const seen = /* @__PURE__ */ new Set();
+	walkFilter(filter, (node) => {
+		if ("field" in node && typeof node.field === "string") seen.add(node.field);
+	});
+	return [...seen];
+}
+//#endregion
+export { collectFields, mapFilter, walkFilter };

package/dist/hooks/engine.d.mts

@@ -0,0 +1,48 @@
+import { HookListener, HookMode, PrioritizedHook } from "./types.mjs";
+
+//#region src/hooks/engine.d.ts
+/** The default priority assigned when a user omits one on `on(...)`. */
+declare const DEFAULT_LISTENER_PRIORITY = 500;
+declare class HookEngine {
+  readonly mode: HookMode;
+  private readonly hooks;
+  constructor(mode?: HookMode);
+  /**
+   * Register a listener. Lower priority numbers run first. Equal priorities
+   * preserve registration order.
+   */
+  on(event: string, listener: HookListener, options?: {
+    priority?: number;
+  }): void;
+  /** Remove a specific listener. No-op if not registered. */
+  off(event: string, listener: HookListener): void;
+  /**
+   * Remove every listener for a specific event, or every listener entirely.
+   * Prefer `off(event, listener)` in plugins — blanket removal invalidates
+   * other plugins' hooks (the mongokit footgun the StandardRepo docs warn about).
+   */
+  removeAllListeners(event?: string): void;
+  /**
+   * Emit event synchronously — fires every listener but does NOT await.
+   * Async listeners that reject route their errors to `error:hook` so the
+   * failure isn't swallowed.
+   */
+  emit(event: string, data: unknown): void;
+  /** Emit event and await every listener in priority order. */
+  emitAsync(event: string, data: unknown): Promise<void>;
+  /** Emit honoring the engine's configured mode. */
+  emitAccordingToMode(event: string, data: unknown): Promise<void>;
+  /** Count listeners for an event — useful for tests. */
+  count(event: string): number;
+  /**
+   * Read-only snapshot of the listener registry.
+   *
+   * Returns a fresh Map whose buckets are frozen arrays, so callers can
+   * inspect priorities/ordering without mutating engine state. Useful for
+   * observability (kits often expose this as `repo._hooks` for BC with
+   * mongokit ≤3.9 test surface) and for debugging.
+   */
+  listeners(): Map<string, readonly PrioritizedHook[]>;
+}
+//#endregion
+export { DEFAULT_LISTENER_PRIORITY, HookEngine };

package/dist/hooks/engine.mjs

@@ -0,0 +1,101 @@
+//#region src/hooks/engine.ts
+/** The default priority assigned when a user omits one on `on(...)`. */
+const DEFAULT_LISTENER_PRIORITY = 500;
+var HookEngine = class {
+	mode;
+	hooks;
+	constructor(mode = "async") {
+		this.mode = mode;
+		this.hooks = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Register a listener. Lower priority numbers run first. Equal priorities
+	* preserve registration order.
+	*/
+	on(event, listener, options = {}) {
+		const priority = options.priority ?? 500;
+		const bucket = this.hooks.get(event) ?? [];
+		bucket.push({
+			listener,
+			priority
+		});
+		bucket.sort((a, b) => a.priority - b.priority);
+		this.hooks.set(event, bucket);
+	}
+	/** Remove a specific listener. No-op if not registered. */
+	off(event, listener) {
+		const bucket = this.hooks.get(event);
+		if (!bucket) return;
+		const idx = bucket.findIndex((h) => h.listener === listener);
+		if (idx !== -1) bucket.splice(idx, 1);
+	}
+	/**
+	* Remove every listener for a specific event, or every listener entirely.
+	* Prefer `off(event, listener)` in plugins — blanket removal invalidates
+	* other plugins' hooks (the mongokit footgun the StandardRepo docs warn about).
+	*/
+	removeAllListeners(event) {
+		if (event === void 0) this.hooks.clear();
+		else this.hooks.delete(event);
+	}
+	/**
+	* Emit event synchronously — fires every listener but does NOT await.
+	* Async listeners that reject route their errors to `error:hook` so the
+	* failure isn't swallowed.
+	*/
+	emit(event, data) {
+		const bucket = this.hooks.get(event);
+		if (!bucket) return;
+		for (const { listener } of bucket) try {
+			const result = listener(data);
+			if (result && typeof result.then === "function") result.catch((err) => {
+				if (event === "error:hook") return;
+				const error = err instanceof Error ? err : new Error(String(err));
+				this.emit("error:hook", {
+					event,
+					error
+				});
+			});
+		} catch (err) {
+			if (event === "error:hook") continue;
+			const error = err instanceof Error ? err : new Error(String(err));
+			this.emit("error:hook", {
+				event,
+				error
+			});
+		}
+	}
+	/** Emit event and await every listener in priority order. */
+	async emitAsync(event, data) {
+		const bucket = this.hooks.get(event);
+		if (!bucket) return;
+		for (const { listener } of bucket) await listener(data);
+	}
+	/** Emit honoring the engine's configured mode. */
+	async emitAccordingToMode(event, data) {
+		if (this.mode === "async") {
+			await this.emitAsync(event, data);
+			return;
+		}
+		this.emit(event, data);
+	}
+	/** Count listeners for an event — useful for tests. */
+	count(event) {
+		return this.hooks.get(event)?.length ?? 0;
+	}
+	/**
+	* Read-only snapshot of the listener registry.
+	*
+	* Returns a fresh Map whose buckets are frozen arrays, so callers can
+	* inspect priorities/ordering without mutating engine state. Useful for
+	* observability (kits often expose this as `repo._hooks` for BC with
+	* mongokit ≤3.9 test surface) and for debugging.
+	*/
+	listeners() {
+		const snapshot = /* @__PURE__ */ new Map();
+		for (const [event, bucket] of this.hooks) snapshot.set(event, Object.freeze([...bucket]));
+		return snapshot;
+	}
+};
+//#endregion
+export { DEFAULT_LISTENER_PRIORITY, HookEngine };

package/dist/hooks/events.d.mts

@@ -0,0 +1,95 @@
+//#region src/hooks/events.d.ts
+/**
+ * Canonical repository-operation event names.
+ *
+ * Every kit's repository emits these `before:* / after:* / error:*` events
+ * via the hook engine. Plugin authors subscribe through `HOOK_EVENTS` so
+ * typos become compile errors and a plugin written against these constants
+ * works identically on mongokit, sqlitekit, pgkit, prismakit.
+ *
+ * ## Scope — the `MinimalRepo + StandardRepo` op set
+ *
+ * This constant covers **every op in repo-core's standard vocabulary.**
+ * Kits with additional native operations (mongokit's `aggregate` / `bulkWrite`,
+ * future pgkit's `copyFrom`, etc.) extend their own typed subset:
+ *
+ * ```ts
+ * export const MONGOKIT_HOOK_EVENTS = {
+ *   ...HOOK_EVENTS,
+ *   BEFORE_AGGREGATE: 'before:aggregate',
+ *   AFTER_AGGREGATE: 'after:aggregate',
+ *   ERROR_AGGREGATE: 'error:aggregate',
+ * } as const;
+ * ```
+ *
+ * Subscribing to an event that a given kit doesn't emit is a no-op, not an
+ * error — that's how the hook engine already behaves — so cross-kit plugins
+ * can safely wire listeners for the full standard set and only fire on kits
+ * that actually emit them.
+ *
+ * @example
+ * ```ts
+ * import { HOOK_EVENTS, HOOK_PRIORITY } from '@classytic/repo-core/hooks';
+ *
+ * repo.on(HOOK_EVENTS.BEFORE_CREATE, (ctx) => {
+ *   if (!ctx.data?.organizationId) ctx.data = { ...ctx.data, organizationId: 'org_123' };
+ * }, { priority: HOOK_PRIORITY.POLICY });
+ * ```
+ */
+declare const HOOK_EVENTS: {
+  readonly BEFORE_CREATE: "before:create";
+  readonly AFTER_CREATE: "after:create";
+  readonly ERROR_CREATE: "error:create";
+  readonly BEFORE_UPDATE: "before:update";
+  readonly AFTER_UPDATE: "after:update";
+  readonly ERROR_UPDATE: "error:update";
+  readonly BEFORE_DELETE: "before:delete";
+  readonly AFTER_DELETE: "after:delete";
+  readonly ERROR_DELETE: "error:delete";
+  readonly BEFORE_GET_BY_ID: "before:getById";
+  readonly AFTER_GET_BY_ID: "after:getById";
+  readonly ERROR_GET_BY_ID: "error:getById";
+  readonly BEFORE_GET_ALL: "before:getAll";
+  readonly AFTER_GET_ALL: "after:getAll";
+  readonly ERROR_GET_ALL: "error:getAll";
+  readonly BEFORE_CREATE_MANY: "before:createMany";
+  readonly AFTER_CREATE_MANY: "after:createMany";
+  readonly ERROR_CREATE_MANY: "error:createMany";
+  readonly BEFORE_UPDATE_MANY: "before:updateMany";
+  readonly AFTER_UPDATE_MANY: "after:updateMany";
+  readonly ERROR_UPDATE_MANY: "error:updateMany";
+  readonly BEFORE_DELETE_MANY: "before:deleteMany";
+  readonly AFTER_DELETE_MANY: "after:deleteMany";
+  readonly ERROR_DELETE_MANY: "error:deleteMany";
+  readonly BEFORE_FIND_ONE_AND_UPDATE: "before:findOneAndUpdate";
+  readonly AFTER_FIND_ONE_AND_UPDATE: "after:findOneAndUpdate";
+  readonly ERROR_FIND_ONE_AND_UPDATE: "error:findOneAndUpdate";
+  readonly BEFORE_RESTORE: "before:restore";
+  readonly AFTER_RESTORE: "after:restore";
+  readonly ERROR_RESTORE: "error:restore";
+  readonly BEFORE_GET_BY_QUERY: "before:getByQuery";
+  readonly AFTER_GET_BY_QUERY: "after:getByQuery";
+  readonly ERROR_GET_BY_QUERY: "error:getByQuery";
+  readonly BEFORE_GET_ONE: "before:getOne";
+  readonly AFTER_GET_ONE: "after:getOne";
+  readonly ERROR_GET_ONE: "error:getOne";
+  readonly BEFORE_FIND_ALL: "before:findAll";
+  readonly AFTER_FIND_ALL: "after:findAll";
+  readonly ERROR_FIND_ALL: "error:findAll";
+  readonly BEFORE_GET_OR_CREATE: "before:getOrCreate";
+  readonly AFTER_GET_OR_CREATE: "after:getOrCreate";
+  readonly ERROR_GET_OR_CREATE: "error:getOrCreate";
+  readonly BEFORE_COUNT: "before:count";
+  readonly AFTER_COUNT: "after:count";
+  readonly ERROR_COUNT: "error:count";
+  readonly BEFORE_EXISTS: "before:exists";
+  readonly AFTER_EXISTS: "after:exists";
+  readonly ERROR_EXISTS: "error:exists";
+  readonly BEFORE_DISTINCT: "before:distinct";
+  readonly AFTER_DISTINCT: "after:distinct";
+  readonly ERROR_DISTINCT: "error:distinct";
+};
+/** String-literal union of every canonical hook event name. */
+type HookEventName = (typeof HOOK_EVENTS)[keyof typeof HOOK_EVENTS];
+//#endregion
+export { HOOK_EVENTS, HookEventName };

package/dist/hooks/events.mjs

@@ -0,0 +1,93 @@
+//#region src/hooks/events.ts
+/**
+* Canonical repository-operation event names.
+*
+* Every kit's repository emits these `before:* / after:* / error:*` events
+* via the hook engine. Plugin authors subscribe through `HOOK_EVENTS` so
+* typos become compile errors and a plugin written against these constants
+* works identically on mongokit, sqlitekit, pgkit, prismakit.
+*
+* ## Scope — the `MinimalRepo + StandardRepo` op set
+*
+* This constant covers **every op in repo-core's standard vocabulary.**
+* Kits with additional native operations (mongokit's `aggregate` / `bulkWrite`,
+* future pgkit's `copyFrom`, etc.) extend their own typed subset:
+*
+* ```ts
+* export const MONGOKIT_HOOK_EVENTS = {
+*   ...HOOK_EVENTS,
+*   BEFORE_AGGREGATE: 'before:aggregate',
+*   AFTER_AGGREGATE: 'after:aggregate',
+*   ERROR_AGGREGATE: 'error:aggregate',
+* } as const;
+* ```
+*
+* Subscribing to an event that a given kit doesn't emit is a no-op, not an
+* error — that's how the hook engine already behaves — so cross-kit plugins
+* can safely wire listeners for the full standard set and only fire on kits
+* that actually emit them.
+*
+* @example
+* ```ts
+* import { HOOK_EVENTS, HOOK_PRIORITY } from '@classytic/repo-core/hooks';
+*
+* repo.on(HOOK_EVENTS.BEFORE_CREATE, (ctx) => {
+*   if (!ctx.data?.organizationId) ctx.data = { ...ctx.data, organizationId: 'org_123' };
+* }, { priority: HOOK_PRIORITY.POLICY });
+* ```
+*/
+const HOOK_EVENTS = {
+	BEFORE_CREATE: "before:create",
+	AFTER_CREATE: "after:create",
+	ERROR_CREATE: "error:create",
+	BEFORE_UPDATE: "before:update",
+	AFTER_UPDATE: "after:update",
+	ERROR_UPDATE: "error:update",
+	BEFORE_DELETE: "before:delete",
+	AFTER_DELETE: "after:delete",
+	ERROR_DELETE: "error:delete",
+	BEFORE_GET_BY_ID: "before:getById",
+	AFTER_GET_BY_ID: "after:getById",
+	ERROR_GET_BY_ID: "error:getById",
+	BEFORE_GET_ALL: "before:getAll",
+	AFTER_GET_ALL: "after:getAll",
+	ERROR_GET_ALL: "error:getAll",
+	BEFORE_CREATE_MANY: "before:createMany",
+	AFTER_CREATE_MANY: "after:createMany",
+	ERROR_CREATE_MANY: "error:createMany",
+	BEFORE_UPDATE_MANY: "before:updateMany",
+	AFTER_UPDATE_MANY: "after:updateMany",
+	ERROR_UPDATE_MANY: "error:updateMany",
+	BEFORE_DELETE_MANY: "before:deleteMany",
+	AFTER_DELETE_MANY: "after:deleteMany",
+	ERROR_DELETE_MANY: "error:deleteMany",
+	BEFORE_FIND_ONE_AND_UPDATE: "before:findOneAndUpdate",
+	AFTER_FIND_ONE_AND_UPDATE: "after:findOneAndUpdate",
+	ERROR_FIND_ONE_AND_UPDATE: "error:findOneAndUpdate",
+	BEFORE_RESTORE: "before:restore",
+	AFTER_RESTORE: "after:restore",
+	ERROR_RESTORE: "error:restore",
+	BEFORE_GET_BY_QUERY: "before:getByQuery",
+	AFTER_GET_BY_QUERY: "after:getByQuery",
+	ERROR_GET_BY_QUERY: "error:getByQuery",
+	BEFORE_GET_ONE: "before:getOne",
+	AFTER_GET_ONE: "after:getOne",
+	ERROR_GET_ONE: "error:getOne",
+	BEFORE_FIND_ALL: "before:findAll",
+	AFTER_FIND_ALL: "after:findAll",
+	ERROR_FIND_ALL: "error:findAll",
+	BEFORE_GET_OR_CREATE: "before:getOrCreate",
+	AFTER_GET_OR_CREATE: "after:getOrCreate",
+	ERROR_GET_OR_CREATE: "error:getOrCreate",
+	BEFORE_COUNT: "before:count",
+	AFTER_COUNT: "after:count",
+	ERROR_COUNT: "error:count",
+	BEFORE_EXISTS: "before:exists",
+	AFTER_EXISTS: "after:exists",
+	ERROR_EXISTS: "error:exists",
+	BEFORE_DISTINCT: "before:distinct",
+	AFTER_DISTINCT: "after:distinct",
+	ERROR_DISTINCT: "error:distinct"
+};
+//#endregion
+export { HOOK_EVENTS };

package/dist/hooks/index.d.mts

@@ -0,0 +1,5 @@
+import { EventPhase, HookListener, HookMode, PrioritizedHook } from "./types.mjs";
+import { DEFAULT_LISTENER_PRIORITY, HookEngine } from "./engine.mjs";
+import { HOOK_EVENTS, HookEventName } from "./events.mjs";
+import { HOOK_PRIORITY, HookPriority } from "./priority.mjs";
+export { DEFAULT_LISTENER_PRIORITY, type EventPhase, HOOK_EVENTS, HOOK_PRIORITY, HookEngine, type HookEventName, type HookListener, type HookMode, type HookPriority, type PrioritizedHook };

package/dist/hooks/index.mjs

@@ -0,0 +1,4 @@
+import { DEFAULT_LISTENER_PRIORITY, HookEngine } from "./engine.mjs";
+import { HOOK_EVENTS } from "./events.mjs";
+import { HOOK_PRIORITY } from "./priority.mjs";
+export { DEFAULT_LISTENER_PRIORITY, HOOK_EVENTS, HOOK_PRIORITY, HookEngine };

package/dist/hooks/priority.d.mts

@@ -0,0 +1,23 @@
+//#region src/hooks/priority.d.ts
+/**
+ * Hook priority constants for the repository lifecycle.
+ *
+ * Lower numbers run first. Policy hooks (multi-tenant scope, soft-delete
+ * filtering, validation) must run before cache lookup so that tenant and
+ * deletion filters are part of the cache key — otherwise one tenant can
+ * read another tenant's cached row.
+ *
+ * Driver-agnostic: both `@classytic/mongokit` and future kits
+ * (`pgkit`, `prismakit`) use these same priorities so cross-kit plugins
+ * compose identically.
+ */
+declare const HOOK_PRIORITY: {
+  /** Policy enforcement — tenant isolation, soft-delete filtering, validation. */readonly POLICY: 100; /** Cache lookup / store — must run after policy so filters are in the key. */
+  readonly CACHE: 200; /** Observability — audit logging, metrics, telemetry. Must not mutate context. */
+  readonly OBSERVABILITY: 300; /** Default priority for user-registered hooks with no explicit priority. */
+  readonly DEFAULT: 500;
+};
+/** The numeric type of any `HOOK_PRIORITY` value. */
+type HookPriority = (typeof HOOK_PRIORITY)[keyof typeof HOOK_PRIORITY];
+//#endregion
+export { HOOK_PRIORITY, HookPriority };

package/dist/hooks/priority.mjs

@@ -0,0 +1,21 @@
+//#region src/hooks/priority.ts
+/**
+* Hook priority constants for the repository lifecycle.
+*
+* Lower numbers run first. Policy hooks (multi-tenant scope, soft-delete
+* filtering, validation) must run before cache lookup so that tenant and
+* deletion filters are part of the cache key — otherwise one tenant can
+* read another tenant's cached row.
+*
+* Driver-agnostic: both `@classytic/mongokit` and future kits
+* (`pgkit`, `prismakit`) use these same priorities so cross-kit plugins
+* compose identically.
+*/
+const HOOK_PRIORITY = {
+	POLICY: 100,
+	CACHE: 200,
+	OBSERVABILITY: 300,
+	DEFAULT: 500
+};
+//#endregion
+export { HOOK_PRIORITY };

package/dist/hooks/types.d.mts

@@ -0,0 +1,37 @@
+//#region src/hooks/types.d.ts
+/**
+ * Hook system types.
+ *
+ * The hook engine sits on every `RepositoryBase` instance. Plugins register
+ * `before:op` / `after:op` / `error:op` listeners with a priority; the
+ * engine runs them in sorted order. Priorities are the coordination
+ * mechanism that lets multi-tenant scope inject before cache lookup (so
+ * tenant ID makes it into the cache key) — see `HOOK_PRIORITY`.
+ */
+/**
+ * Hook listener signature. The data argument's shape depends on the event
+ * phase:
+ *   - `before:*` → `RepositoryContext` (mutate to inject filters, data, etc.)
+ *   - `after:*`  → `{ context, result }`
+ *   - `error:*`  → `{ context, error }`
+ *
+ * Listeners may be sync or async. The engine awaits async listeners in
+ * priority order.
+ */
+type HookListener<TData = unknown> = (data: TData) => void | Promise<void>;
+/**
+ * Execution mode for event emission. `async` awaits every listener before
+ * returning (default — plugins rely on this to mutate context synchronously
+ * from the caller's perspective). `sync` runs listeners but doesn't await;
+ * fire-and-forget telemetry can use it.
+ */
+type HookMode = 'async' | 'sync';
+/** A hook entry in the priority-sorted registry. */
+interface PrioritizedHook {
+  readonly listener: HookListener;
+  readonly priority: number;
+}
+/** Event phase discriminator for hook names. */
+type EventPhase = 'before' | 'after' | 'error';
+//#endregion
+export { EventPhase, HookListener, HookMode, PrioritizedHook };

package/dist/lookup/index.d.mts

@@ -0,0 +1,2 @@
+import { LookupPopulateOptions, LookupPopulateResult, LookupRow, LookupSpec } from "./types.mjs";
+export { type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec };