@classytic/repo-core 0.1.0

package/dist/query-parser/types.d.mts

@@ -0,0 +1,104 @@
+import { Filter } from "../filter/types.mjs";
+
+//#region src/query-parser/types.d.ts
+/** Sort direction on a single field. */
+type ParsedSortDirection = 1 | -1;
+/** Sort spec after parsing — array so field order is preserved. */
+type ParsedSort = Record<string, ParsedSortDirection>;
+/** Projection — field inclusion/exclusion map (`1` include, `0` exclude). */
+type ParsedSelect = Record<string, 0 | 1>;
+/**
+ * Populate / include spec for relation fetching. Kits interpret per backend:
+ *
+ * - mongokit compiles to Mongoose `populate()`
+ * - sqlitekit uses it as a hint for JOIN generation (future)
+ * - prismakit compiles to `include: {...}`
+ *
+ * Frontends pass it through from URL `populate[field][select]=...`
+ * params; the shape matches mongoose's `PopulateOptions`.
+ */
+interface ParsedPopulate {
+  path: string;
+  select?: string;
+  match?: Record<string, unknown>;
+  options?: {
+    limit?: number;
+    sort?: ParsedSort;
+    skip?: number;
+  };
+  populate?: ParsedPopulate;
+}
+/**
+ * Canonical parsed-query envelope. Every kit receives this shape, every
+ * frontend emits URLs that produce it, arc's BaseController threads it
+ * into repo calls. **Do not add kit-specific fields here** — kits extend
+ * their own options types for native-only features.
+ */
+interface ParsedQuery {
+  /** Filter IR tree. Always present (TRUE when no filter params). */
+  filter: Filter;
+  /** Optional sort spec. When absent, kits apply their default sort. */
+  sort?: ParsedSort;
+  /** Field projection. */
+  select?: ParsedSelect;
+  /** Relation population (when the kit supports it). */
+  populate?: ParsedPopulate[];
+  /** 1-indexed page. Present only when the URL used offset-pagination params. */
+  page?: number;
+  /** Opaque cursor from a prior `next`. Present only on keyset requests. */
+  after?: string;
+  /** Per-page item count. */
+  limit: number;
+  /** Free-text search term (kits interpret per backend — $text, FTS, etc.). */
+  search?: string;
+}
+/**
+ * Configuration knobs for the parser. All optional — sane defaults cover
+ * typical arc use cases.
+ */
+interface QueryParserOptions {
+  /** Default per-page count when the URL omits `limit`. Default: 20. */
+  defaultLimit?: number;
+  /** Hard cap on `limit` to prevent resource exhaustion. Default: 200. */
+  maxLimit?: number;
+  /** Allowlist of filter field names. When set, unknown fields are dropped. */
+  allowedFilterFields?: readonly string[];
+  /** Allowlist of sort field names. When set, unknown fields are dropped. */
+  allowedSortFields?: readonly string[];
+  /** Allowlist of operator names accepted in bracket syntax. */
+  allowedOperators?: readonly BracketOperator[];
+  /** Max filter nesting depth (defends against filter-bomb URLs). Default: 10. */
+  maxFilterDepth?: number;
+  /** Regex pattern length cap (ReDoS defense). Default: 500. */
+  maxRegexLength?: number;
+  /** Search query length cap. Default: 200. */
+  maxSearchLength?: number;
+  /**
+   * Field-type hints for value coercion. When a filter field is in this
+   * map, the URL string value is coerced to the declared type:
+   *   - `'number'`  → `Number(value)`
+   *   - `'boolean'` → `'true'`/`'1'` → true, else false
+   *   - `'date'`    → `new Date(value)` (validated)
+   *   - `'string'`  → left as-is (default for unlisted fields)
+   *
+   * Use this to avoid the heuristic coercion's footguns (e.g. `?sku=12345`
+   * against a string SKU column — without a hint, heuristics turn it into
+   * a number and the SQL comparison fails).
+   */
+  fieldTypes?: Record<string, 'string' | 'number' | 'boolean' | 'date'>;
+}
+/**
+ * Bracket operators accepted in URL syntax. When you see `field[op]=value`
+ * in a URL, `op` is one of these. Kept as a closed set — new operators
+ * require a new version.
+ */
+type BracketOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'contains' | 'startsWith' | 'endsWith' | 'ieq' | 'regex' | 'between' | 'exists';
+/**
+ * Input shape for `parseUrl`. URL search params can be sourced from
+ * `URLSearchParams.entries()`, Fastify's `request.query`, or
+ * Express's `req.query` — all of these produce a `Record<string, string | string[]>`
+ * or a compatible iterable. The parser normalizes.
+ */
+type QueryParserInput = URLSearchParams | Record<string, string | string[] | undefined> | Iterable<[string, string]>;
+//#endregion
+export { BracketOperator, ParsedPopulate, ParsedQuery, ParsedSelect, ParsedSort, ParsedSortDirection, QueryParserInput, QueryParserOptions };

package/dist/repository/base.d.mts

@@ -0,0 +1,90 @@
+import { RepositoryContext } from "../context/types.mjs";
+import { HookListener, HookMode } from "../hooks/types.mjs";
+import { HookEngine } from "../hooks/engine.mjs";
+import { PluginType } from "./plugin-types.mjs";
+
+//#region src/repository/base.d.ts
+/** Construction options common to every kit. */
+interface RepositoryBaseOptions {
+  /** Stable identifier (model/table name) — surfaces in hook contexts and ordering errors. */
+  name: string;
+  /** Plugins to install at construction. Order matters — see `PLUGIN_ORDER_CONSTRAINTS`. */
+  plugins?: readonly PluginType[];
+  /** Emit mode for the hook engine. Default: `'async'`. */
+  hooks?: HookMode;
+  /** Plugin-order validation mode. Default: `'warn'`. */
+  pluginOrderChecks?: 'warn' | 'throw' | 'off';
+  /** Optional callback for plugin-order warnings (defaults to `console.warn`). */
+  onPluginOrderWarning?: (message: string) => void;
+}
+/**
+ * Base class every driver kit extends. Exposes the hook surface
+ * (`on` / `off` / `emit` / `emitAsync`), plugin installation (`use`), and
+ * context building (`_buildContext`). Kits layer their CRUD on top.
+ */
+declare abstract class RepositoryBase {
+  /** Model/table identifier — set once at construction, read on every hook context. */
+  readonly modelName: string;
+  /** Public hook engine so plugins + kits dispatch directly without a method wrapper. */
+  readonly hooks: HookEngine;
+  /**
+   * Open-ended property bag so plugins can install methods on the repo
+   * (e.g. `softDeletePlugin` adds `repo.restore(id)`). The `unknown` escape
+   * hatch keeps the class assignable to the richer `StandardRepo` contract
+   * without casts.
+   */
+  [key: string]: unknown;
+  constructor(options: RepositoryBaseOptions);
+  /** Install a plugin (object with `apply(repo)` or a plain function). */
+  use(plugin: PluginType): this;
+  /**
+   * Register a hook listener. Lower priority numbers run first.
+   * Generic over listener data type so plugins can annotate their handler
+   * parameter (e.g. `(ctx: RepositoryContext) => void`) without casting.
+   */
+  on<TData = unknown>(event: string, listener: HookListener<TData>, options?: {
+    priority?: number;
+  }): this;
+  /** Remove a specific listener. */
+  off<TData = unknown>(event: string, listener: HookListener<TData>): this;
+  /** Remove all listeners for an event (or all events when omitted). */
+  removeAllListeners(event?: string): this;
+  /** Emit fire-and-forget (async errors routed to `error:hook`). */
+  emit(event: string, data: unknown): void;
+  /** Emit and await every listener in priority order. */
+  emitAsync(event: string, data: unknown): Promise<void>;
+  /**
+   * Build a context + run before-hooks. Kits call this at the top of every
+   * op, mutate as needed (e.g. compile the filter after plugins have injected
+   * scope), perform the native operation, then call `_emitAfter`.
+   *
+   * **Always awaits before-hooks** regardless of the engine's `hooks` mode.
+   * The before-phase is where policy plugins (multi-tenant, soft-delete,
+   * validation) inject scope and reject requests — fire-and-forget here
+   * would let the driver call run before the filter is augmented. `hooks:
+   * 'sync'` only affects `_emitAfter` / `_emitError`, where fire-and-forget
+   * is acceptable for observability/metrics listeners.
+   */
+  _buildContext<TOptions extends Record<string, unknown>>(operation: string, inputs: TOptions): Promise<RepositoryContext>;
+  /** Emit after-hook. Kits invoke this after the native op succeeds. */
+  _emitAfter(operation: string, context: RepositoryContext, result: unknown): Promise<void>;
+  /**
+   * Emit error-hook. Swallows any throw from within the hook itself so the
+   * original operation's error remains authoritative.
+   */
+  _emitError(operation: string, context: RepositoryContext, error: Error): Promise<void>;
+  /**
+   * Cache-plugin escape hatch. When the cache plugin's `before:*` hook
+   * finds a hit, it stamps `_cacheHit = true` + `_cachedResult` onto the
+   * context. Kits call this helper at the top of every read op right after
+   * `_buildContext`. Returns the cached value, or `undefined` when there
+   * was no hit (kit proceeds with the native driver call).
+   *
+   * Returns `undefined` also covers "hit, but the cached value was undefined" —
+   * callers typically treat that as a miss since repo methods return null,
+   * not undefined, for "not found".
+   */
+  _cachedValue<T>(context: RepositoryContext): T | undefined;
+}
+//#endregion
+export { RepositoryBase, RepositoryBaseOptions };

package/dist/repository/base.mjs

@@ -0,0 +1,111 @@
+import { HookEngine } from "../hooks/engine.mjs";
+import { validatePluginOrder } from "./plugin-types.mjs";
+//#region src/repository/base.ts
+/**
+* Base class every driver kit extends. Exposes the hook surface
+* (`on` / `off` / `emit` / `emitAsync`), plugin installation (`use`), and
+* context building (`_buildContext`). Kits layer their CRUD on top.
+*/
+var RepositoryBase = class {
+	/** Model/table identifier — set once at construction, read on every hook context. */
+	modelName;
+	/** Public hook engine so plugins + kits dispatch directly without a method wrapper. */
+	hooks;
+	constructor(options) {
+		this.modelName = options.name;
+		this.hooks = new HookEngine(options.hooks ?? "async");
+		const plugins = options.plugins ?? [];
+		validatePluginOrder(plugins, this.modelName, options.pluginOrderChecks ?? "warn", options.onPluginOrderWarning);
+		for (const plugin of plugins) this.use(plugin);
+	}
+	/** Install a plugin (object with `apply(repo)` or a plain function). */
+	use(plugin) {
+		if (typeof plugin === "function") plugin(this);
+		else plugin.apply(this);
+		return this;
+	}
+	/**
+	* Register a hook listener. Lower priority numbers run first.
+	* Generic over listener data type so plugins can annotate their handler
+	* parameter (e.g. `(ctx: RepositoryContext) => void`) without casting.
+	*/
+	on(event, listener, options) {
+		this.hooks.on(event, listener, options);
+		return this;
+	}
+	/** Remove a specific listener. */
+	off(event, listener) {
+		this.hooks.off(event, listener);
+		return this;
+	}
+	/** Remove all listeners for an event (or all events when omitted). */
+	removeAllListeners(event) {
+		this.hooks.removeAllListeners(event);
+		return this;
+	}
+	/** Emit fire-and-forget (async errors routed to `error:hook`). */
+	emit(event, data) {
+		this.hooks.emit(event, data);
+	}
+	/** Emit and await every listener in priority order. */
+	async emitAsync(event, data) {
+		await this.hooks.emitAsync(event, data);
+	}
+	/**
+	* Build a context + run before-hooks. Kits call this at the top of every
+	* op, mutate as needed (e.g. compile the filter after plugins have injected
+	* scope), perform the native operation, then call `_emitAfter`.
+	*
+	* **Always awaits before-hooks** regardless of the engine's `hooks` mode.
+	* The before-phase is where policy plugins (multi-tenant, soft-delete,
+	* validation) inject scope and reject requests — fire-and-forget here
+	* would let the driver call run before the filter is augmented. `hooks:
+	* 'sync'` only affects `_emitAfter` / `_emitError`, where fire-and-forget
+	* is acceptable for observability/metrics listeners.
+	*/
+	async _buildContext(operation, inputs) {
+		const context = {
+			operation,
+			model: this.modelName,
+			...inputs
+		};
+		await this.hooks.emitAsync(`before:${operation}`, context);
+		return context;
+	}
+	/** Emit after-hook. Kits invoke this after the native op succeeds. */
+	async _emitAfter(operation, context, result) {
+		await this.hooks.emitAccordingToMode(`after:${operation}`, {
+			context,
+			result
+		});
+	}
+	/**
+	* Emit error-hook. Swallows any throw from within the hook itself so the
+	* original operation's error remains authoritative.
+	*/
+	async _emitError(operation, context, error) {
+		try {
+			await this.hooks.emitAccordingToMode(`error:${operation}`, {
+				context,
+				error
+			});
+		} catch {}
+	}
+	/**
+	* Cache-plugin escape hatch. When the cache plugin's `before:*` hook
+	* finds a hit, it stamps `_cacheHit = true` + `_cachedResult` onto the
+	* context. Kits call this helper at the top of every read op right after
+	* `_buildContext`. Returns the cached value, or `undefined` when there
+	* was no hit (kit proceeds with the native driver call).
+	*
+	* Returns `undefined` also covers "hit, but the cached value was undefined" —
+	* callers typically treat that as a miss since repo methods return null,
+	* not undefined, for "not found".
+	*/
+	_cachedValue(context) {
+		if (context["_cacheHit"] !== true) return void 0;
+		return context["_cachedResult"];
+	}
+};
+//#endregion
+export { RepositoryBase };

package/dist/repository/index.d.mts

@@ -0,0 +1,5 @@
+import { LookupPopulateOptions, LookupPopulateResult, LookupRow, LookupSpec } from "../lookup/types.mjs";
+import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder } from "./plugin-types.mjs";
+import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
+import { AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, BulkWriteOperation, BulkWriteResult, DeleteManyResult, DeleteOptions, DeleteResult, FindOneAndUpdateOptions, InferDoc, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions } from "./types.mjs";
+export { type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type BulkWriteOperation, type BulkWriteResult, type DeleteManyResult, type DeleteOptions, type DeleteResult, type FindOneAndUpdateOptions, type InferDoc, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type QueryOptions, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type StandardRepo, type UpdateManyResult, type WriteOptions, validatePluginOrder };

package/dist/repository/index.mjs

@@ -0,0 +1,3 @@
+import { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder } from "./plugin-types.mjs";
+import { RepositoryBase } from "./base.mjs";
+export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, validatePluginOrder };

package/dist/repository/plugin-types.d.mts

@@ -0,0 +1,27 @@
+import { RepositoryBase } from "./base.mjs";
+
+//#region src/repository/plugin-types.d.ts
+/** Object-style plugin — preferred form. Carries a stable `name` for ordering checks. */
+interface Plugin<TRepo extends RepositoryBase = RepositoryBase> {
+  /** Stable identifier used by plugin-order validators. */
+  readonly name: string;
+  apply(repo: TRepo): void;
+}
+/** Function-style plugin for quick-and-dirty one-off extensions. No ordering guarantees. */
+type PluginFunction<TRepo extends RepositoryBase = RepositoryBase> = (repo: TRepo) => void;
+/** Either flavor is accepted by `repo.use(...)`. */
+type PluginType<TRepo extends RepositoryBase = RepositoryBase> = Plugin<TRepo> | PluginFunction<TRepo>;
+/**
+ * Ordered pairs that produce wrong behavior when installed out of order.
+ * Each entry: `[mustComeFirst, mustComeAfter, reason]`.
+ *
+ * Surfaced by `validatePluginOrder` at repository construction time.
+ */
+declare const PLUGIN_ORDER_CONSTRAINTS: readonly (readonly [string, string, string])[];
+/**
+ * Assert plugin-install order. Emits a `warn` (default) or throws based on
+ * mode. Plain-function plugins (no `name`) are skipped — no false positives.
+ */
+declare function validatePluginOrder(plugins: readonly PluginType[], repoName: string, mode?: 'warn' | 'throw' | 'off', onWarn?: (message: string) => void): void;
+//#endregion
+export { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder };

package/dist/repository/plugin-types.mjs

@@ -0,0 +1,45 @@
+//#region src/repository/plugin-types.ts
+/**
+* Ordered pairs that produce wrong behavior when installed out of order.
+* Each entry: `[mustComeFirst, mustComeAfter, reason]`.
+*
+* Surfaced by `validatePluginOrder` at repository construction time.
+*/
+const PLUGIN_ORDER_CONSTRAINTS = [
+	[
+		"soft-delete",
+		"batch-operations",
+		"soft-delete must precede batch-operations so bulk deletes/updates see the soft-delete filter"
+	],
+	[
+		"multi-tenant",
+		"cache",
+		"multi-tenant must precede cache so tenant scoping is baked into cache keys (prevents cross-tenant cache poisoning)"
+	],
+	[
+		"multi-tenant",
+		"soft-delete",
+		"multi-tenant should precede soft-delete so tenant scope is applied before deletion-state filter"
+	]
+];
+/**
+* Assert plugin-install order. Emits a `warn` (default) or throws based on
+* mode. Plain-function plugins (no `name`) are skipped — no false positives.
+*/
+function validatePluginOrder(plugins, repoName, mode = "warn", onWarn = (m) => {
+	console.warn(m);
+}) {
+	if (mode === "off") return;
+	const names = plugins.map((p) => typeof p === "function" ? void 0 : p.name);
+	for (const [first, after, reason] of PLUGIN_ORDER_CONSTRAINTS) {
+		const firstIdx = names.indexOf(first);
+		const afterIdx = names.indexOf(after);
+		if (firstIdx === -1 || afterIdx === -1) continue;
+		if (firstIdx < afterIdx) continue;
+		const message = `[repo-core] Repository "${repoName}": plugin order issue — ${reason}. Got: [..., '${after}' at index ${String(afterIdx)}, '${first}' at index ${String(firstIdx)}]. Swap them, or pass { pluginOrderChecks: 'off' } to silence.`;
+		if (mode === "throw") throw new Error(message);
+		onWarn(message);
+	}
+}
+//#endregion
+export { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder };