@classytic/repo-core 0.2.0 → 0.4.0

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

@@ -0,0 +1,43 @@
+//#region src/query-parser/reserved.d.ts
+/**
+ * URL parameter keys reserved by the framework — never parsed as
+ * filter predicates. Two categories:
+ *
+ * 1. **Pagination / list-control params** — `page`, `limit`, `after`,
+ *    `sort`, `select`, `populate`, `search`. Universal across kits;
+ *    every backend agrees on their meaning.
+ *
+ * 2. **Resource-dispatch verbs** — `_count`, `_distinct`, `_exists`.
+ *    Arc-style frameworks pick the repo method from these URL keys
+ *    (list vs count vs distinct vs exists).
+ *
+ * **Why an explicit allowlist, not a `_*` namespace.** MongoDB's `_id`
+ * (and every kit's analog) is a legitimate filter field; user-defined
+ * `_internal`, `_meta`, `_v` fields are common in real schemas. A
+ * blanket `key.startsWith('_')` rule silently drops filters on these.
+ * Adding a new dispatch verb here is a deliberate ecosystem-wide
+ * change — small, audited, and only needed every few major versions.
+ */
+/**
+ * Reserved top-level URL keys handled outside the filter pipeline.
+ * Pagination + sort + select + populate + search + resource-dispatch
+ * verbs (`_count`, `_distinct`, `_exists`).
+ */
+declare const STANDARD_RESERVED_PARAMS: ReadonlySet<string>;
+/**
+ * True when `key` is a framework-reserved URL parameter and should be
+ * skipped during filter parsing.
+ *
+ * Use in any URL-parser implementation that decides "is this a filter
+ * predicate or a control flag?":
+ *
+ * ```ts
+ * for (const [key, value] of params.entries()) {
+ *   if (isControlParam(key)) continue;  // skip page, limit, _count, ...
+ *   // … parse as filter predicate
+ * }
+ * ```
+ */
+declare function isControlParam(key: string): boolean;
+//#endregion
+export { STANDARD_RESERVED_PARAMS, isControlParam };

package/dist/query-parser/reserved.mjs

@@ -0,0 +1,56 @@
+//#region src/query-parser/reserved.ts
+/**
+* URL parameter keys reserved by the framework — never parsed as
+* filter predicates. Two categories:
+*
+* 1. **Pagination / list-control params** — `page`, `limit`, `after`,
+*    `sort`, `select`, `populate`, `search`. Universal across kits;
+*    every backend agrees on their meaning.
+*
+* 2. **Resource-dispatch verbs** — `_count`, `_distinct`, `_exists`.
+*    Arc-style frameworks pick the repo method from these URL keys
+*    (list vs count vs distinct vs exists).
+*
+* **Why an explicit allowlist, not a `_*` namespace.** MongoDB's `_id`
+* (and every kit's analog) is a legitimate filter field; user-defined
+* `_internal`, `_meta`, `_v` fields are common in real schemas. A
+* blanket `key.startsWith('_')` rule silently drops filters on these.
+* Adding a new dispatch verb here is a deliberate ecosystem-wide
+* change — small, audited, and only needed every few major versions.
+*/
+/**
+* Reserved top-level URL keys handled outside the filter pipeline.
+* Pagination + sort + select + populate + search + resource-dispatch
+* verbs (`_count`, `_distinct`, `_exists`).
+*/
+const STANDARD_RESERVED_PARAMS = new Set([
+	"page",
+	"limit",
+	"after",
+	"sort",
+	"select",
+	"populate",
+	"search",
+	"_count",
+	"_distinct",
+	"_exists"
+]);
+/**
+* True when `key` is a framework-reserved URL parameter and should be
+* skipped during filter parsing.
+*
+* Use in any URL-parser implementation that decides "is this a filter
+* predicate or a control flag?":
+*
+* ```ts
+* for (const [key, value] of params.entries()) {
+*   if (isControlParam(key)) continue;  // skip page, limit, _count, ...
+*   // … parse as filter predicate
+* }
+* ```
+*/
+function isControlParam(key) {
+	return STANDARD_RESERVED_PARAMS.has(key);
+}
+//#endregion
+export { STANDARD_RESERVED_PARAMS, isControlParam };

package/dist/repository/agg-output.d.mts

@@ -0,0 +1,63 @@
+//#region src/repository/agg-output.d.ts
+/**
+ * Cross-kit AggResult row-shape normalization.
+ *
+ * When an `AggRequest` includes `lookups` and `groupBy` references a
+ * joined-alias path (e.g. `'department.code'`), the row that lands in
+ * `AggResult.rows` carries the joined data as a NESTED object:
+ *
+ *   ```ts
+ *   { status: 'pending', department: { code: 'ENG' }, count: 3 }
+ *   ```
+ *
+ * Same convention `lookupPopulate` uses. Mongokit's `$project` with
+ * dotted-key output naturally nests; sqlitekit gets flat-dotted keys
+ * from Drizzle's SELECT alias map and runs results through
+ * `nestDottedKeys` before returning.
+ *
+ * **Why nested over flat-dotted?**
+ *   - Matches `lookupPopulate` precedent (single convention across
+ *     all read primitives).
+ *   - JSON-clean: `{ department: { code: 'ENG' } }` round-trips
+ *     identically through `JSON.stringify` / `parse`.
+ *   - Cleaner consumer code: `row.department.code` vs
+ *     `row['department.code']`.
+ *   - BSON allows nested but disallows literal `.` in field names —
+ *     the only shape that works in mongo without BSON workarounds.
+ *
+ * **Out of scope**:
+ *   - Multi-level dotted paths (`'a.b.c'`) — kits don't emit these
+ *     today (single-level joins only). The helper handles them
+ *     correctly by recursive descent so future depth is supported.
+ *   - Conflicting flat + nested keys on the same row (e.g. both
+ *     `department` and `department.code`). The flat-dotted side wins;
+ *     a top-level `department` value gets overwritten when a
+ *     `department.<x>` partner key is processed. In practice this
+ *     never happens — kits emit one or the other per groupBy key.
+ */
+/**
+ * Walk a row's top-level keys, splitting any that contain `.` into
+ * nested objects. Keys without `.` pass through unchanged. Mutates a
+ * fresh output object — the input is not modified.
+ *
+ * @example
+ * ```ts
+ * nestDottedKeys({ status: 'pending', 'department.code': 'ENG', count: 3 })
+ * // → { status: 'pending', department: { code: 'ENG' }, count: 3 }
+ * ```
+ *
+ * Multi-level paths (`a.b.c`) recurse:
+ *
+ * ```ts
+ * nestDottedKeys({ 'a.b.c': 1 })
+ * // → { a: { b: { c: 1 } } }
+ * ```
+ */
+declare function nestDottedKeys<T extends Record<string, unknown>>(row: T): Record<string, unknown>;
+/**
+ * Convenience wrapper for an array of rows. Returns a new array of
+ * normalized rows; the input is not modified.
+ */
+declare function nestDottedKeysAll<T extends Record<string, unknown>>(rows: readonly T[]): Record<string, unknown>[];
+//#endregion
+export { nestDottedKeys, nestDottedKeysAll };

package/dist/repository/agg-output.mjs

@@ -0,0 +1,89 @@
+//#region src/repository/agg-output.ts
+/**
+* Cross-kit AggResult row-shape normalization.
+*
+* When an `AggRequest` includes `lookups` and `groupBy` references a
+* joined-alias path (e.g. `'department.code'`), the row that lands in
+* `AggResult.rows` carries the joined data as a NESTED object:
+*
+*   ```ts
+*   { status: 'pending', department: { code: 'ENG' }, count: 3 }
+*   ```
+*
+* Same convention `lookupPopulate` uses. Mongokit's `$project` with
+* dotted-key output naturally nests; sqlitekit gets flat-dotted keys
+* from Drizzle's SELECT alias map and runs results through
+* `nestDottedKeys` before returning.
+*
+* **Why nested over flat-dotted?**
+*   - Matches `lookupPopulate` precedent (single convention across
+*     all read primitives).
+*   - JSON-clean: `{ department: { code: 'ENG' } }` round-trips
+*     identically through `JSON.stringify` / `parse`.
+*   - Cleaner consumer code: `row.department.code` vs
+*     `row['department.code']`.
+*   - BSON allows nested but disallows literal `.` in field names —
+*     the only shape that works in mongo without BSON workarounds.
+*
+* **Out of scope**:
+*   - Multi-level dotted paths (`'a.b.c'`) — kits don't emit these
+*     today (single-level joins only). The helper handles them
+*     correctly by recursive descent so future depth is supported.
+*   - Conflicting flat + nested keys on the same row (e.g. both
+*     `department` and `department.code`). The flat-dotted side wins;
+*     a top-level `department` value gets overwritten when a
+*     `department.<x>` partner key is processed. In practice this
+*     never happens — kits emit one or the other per groupBy key.
+*/
+/**
+* Walk a row's top-level keys, splitting any that contain `.` into
+* nested objects. Keys without `.` pass through unchanged. Mutates a
+* fresh output object — the input is not modified.
+*
+* @example
+* ```ts
+* nestDottedKeys({ status: 'pending', 'department.code': 'ENG', count: 3 })
+* // → { status: 'pending', department: { code: 'ENG' }, count: 3 }
+* ```
+*
+* Multi-level paths (`a.b.c`) recurse:
+*
+* ```ts
+* nestDottedKeys({ 'a.b.c': 1 })
+* // → { a: { b: { c: 1 } } }
+* ```
+*/
+function nestDottedKeys(row) {
+	const out = {};
+	for (const [key, value] of Object.entries(row)) {
+		if (key.indexOf(".") < 0) {
+			out[key] = value;
+			continue;
+		}
+		setDeep(out, key.split("."), value);
+	}
+	return out;
+}
+/**
+* Convenience wrapper for an array of rows. Returns a new array of
+* normalized rows; the input is not modified.
+*/
+function nestDottedKeysAll(rows) {
+	return rows.map((r) => nestDottedKeys(r));
+}
+function setDeep(target, path, value) {
+	let cursor = target;
+	for (let i = 0; i < path.length - 1; i++) {
+		const segment = path[i];
+		const existing = cursor[segment];
+		if (existing && typeof existing === "object" && !Array.isArray(existing)) cursor = existing;
+		else {
+			const next = {};
+			cursor[segment] = next;
+			cursor = next;
+		}
+	}
+	cursor[path[path.length - 1]] = value;
+}
+//#endregion
+export { nestDottedKeys, nestDottedKeysAll };

package/dist/repository/base.mjs

@@ -15,11 +15,13 @@ var RepositoryBase = class {
 		this.modelName = options.name;
 		this.hooks = new HookEngine(options.hooks ?? "async");
 		const plugins = options.plugins ?? [];
+		for (let i = 0; i < plugins.length; i++) assertValidPlugin(plugins[i], this.modelName, i);
 		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) {
+		assertValidPlugin(plugin, this.modelName);
 		if (typeof plugin === "function") plugin(this);
 		else plugin.apply(this);
 		return this;
@@ -107,5 +109,24 @@ var RepositoryBase = class {
 		return context["_cachedResult"];
 	}
 };
+/**
+* Reject malformed plugin entries before they reach `use()`.
+*
+* Caught the field-reported `new Repository(Model, ['organizationId'], ...)`
+* crash where a tenant-field string array landed in the plugins slot and
+* blew up with `TypeError: plugin.apply is not a function` deep inside the
+* constructor. Validating shape up front turns that into a single, action-
+* able error pointing at the offending index.
+*/
+function assertValidPlugin(plugin, repoName, index) {
+	const where = typeof index === "number" ? `plugin at index ${index}` : "plugin";
+	if (plugin === null || plugin === void 0) throw new TypeError(`[repo-core] Repository "${repoName}": ${where} is ${plugin === null ? "null" : "undefined"}. Expected a function \`(repo) => void\` or an object \`{ name, apply(repo) }\`.`);
+	if (typeof plugin === "function") return;
+	if (typeof plugin !== "object") {
+		const detail = typeof plugin === "string" ? `'${plugin}'` : "";
+		throw new TypeError(`[repo-core] Repository "${repoName}": ${where} has wrong type. Expected a function or { name, apply(repo) } object — got ${typeof plugin} ${detail}. Common cause: \`new Repository(Model, [tenantField], opts)\` — second argument must be a plugins array.`);
+	}
+	if (typeof plugin.apply !== "function") throw new TypeError(`[repo-core] Repository "${repoName}": ${where} is an object but missing \`apply(repo)\`. Expected \`{ name: string, apply: (repo) => void }\`.`);
+}
 //#endregion
 export { RepositoryBase };

package/dist/repository/index.d.mts

@@ -1,6 +1,8 @@
 import { LookupPopulateOptions, LookupPopulateResult, LookupRow, LookupSpec } from "../lookup/types.mjs";
 import { UpdateInput } from "../update/types.mjs";
+import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.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, FilterInput, 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 FilterInput, 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 UpdateInput, type UpdateManyResult, type WriteOptions, validatePluginOrder };
+import { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey } from "./options.mjs";
+import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions } from "./types.mjs";
+export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ClaimTransition, type ClaimVersionTransition, type DeleteManyResult, type DeleteOptions, type DeleteResult, type FilterInput, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, 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, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type UpdateInput, type UpdateManyResult, type WriteOptions, nestDottedKeys, nestDottedKeysAll, validatePluginOrder };

package/dist/repository/index.mjs

@@ -1,3 +1,5 @@
+import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase } from "./base.mjs";
-export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, validatePluginOrder };
+import { STANDARD_REPO_OPTION_KEYS } from "./options.mjs";
+export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, STANDARD_REPO_OPTION_KEYS, nestDottedKeys, nestDottedKeysAll, validatePluginOrder };

package/dist/repository/options.d.mts

@@ -0,0 +1,62 @@
+//#region src/repository/options.d.ts
+/**
+ * Canonical option keys forwarded into every `MinimalRepo` /
+ * `StandardRepo` method call.
+ *
+ * The options bag is the cross-cutting plumbing every kit's plugin
+ * layer reads from: multi-tenant scope, audit attribution, transaction
+ * threading, observability correlation. Hosts (and arc-style
+ * frameworks) extract these from the request context once and forward
+ * them into every repo call so plugins don't need request-context
+ * access of their own.
+ *
+ * Without a single agreed-on set, drift is inevitable: one host
+ * forwards `userId`, another forwards `actorId`, a third forgets
+ * `requestId` entirely — and audit logs lose attribution silently.
+ * `STANDARD_REPO_OPTION_KEYS` is the contract every kit and every
+ * arc-style framework agrees on. Adding a key here is a deliberate
+ * ecosystem-wide commitment.
+ *
+ * Kits implementing custom plugins (commission, supplier-performance,
+ * pos, ...) can declare their own canonical sets via mongokit's
+ * `createOptionsExtractor<TCtx>` — that pattern stays domain-local and
+ * doesn't pollute the cross-kit contract.
+ */
+/**
+ * The canonical keys every kit's plugin layer reads from the options
+ * bag, and every framework auto-threads from request context.
+ *
+ * - `organizationId` — multi-tenant scope. Tenant plugins
+ *   (mongokit's `multiTenantPlugin`, sqlitekit's tenant filter) read
+ *   it to stamp on write + filter on read. Cast handling (e.g.
+ *   `ObjectId` coercion) is plugin-local — pass the raw scope id.
+ * - `userId` — actor id for audit attribution. Audit-log / audit-
+ *   trail plugins read it for the `who` column.
+ * - `user` — denormalized actor object, when the audit log wants
+ *   richer payload than a bare id (display name, role snapshot, ...).
+ * - `session` — driver-specific transaction handle. Mongoose
+ *   `ClientSession`, better-sqlite3 transaction fn, Prisma
+ *   transaction client. Opaque to repo-core — kits narrow at the
+ *   boundary.
+ * - `requestId` — request correlation id for trace stitching across
+ *   logs, events, and downstream service calls.
+ *
+ * Frameworks should treat this set as the canonical forward list:
+ * peel matching keys off the request context, drop them into the
+ * options bag, and let kit plugins read what they implement. Unknown
+ * ctx keys do NOT forward — the bag stays narrow.
+ */
+declare const STANDARD_REPO_OPTION_KEYS: readonly ["organizationId", "userId", "user", "session", "requestId"];
+/**
+ * Type-level union of canonical option keys. Use to constrain
+ * framework helpers that thread request context into repo options:
+ *
+ * ```ts
+ * function pickStandardOptions(ctx: Record<string, unknown>): Partial<
+ *   Record<StandardRepoOptionKey, unknown>
+ * > { ... }
+ * ```
+ */
+type StandardRepoOptionKey = (typeof STANDARD_REPO_OPTION_KEYS)[number];
+//#endregion
+export { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey };

package/dist/repository/options.mjs

@@ -0,0 +1,57 @@
+//#region src/repository/options.ts
+/**
+* Canonical option keys forwarded into every `MinimalRepo` /
+* `StandardRepo` method call.
+*
+* The options bag is the cross-cutting plumbing every kit's plugin
+* layer reads from: multi-tenant scope, audit attribution, transaction
+* threading, observability correlation. Hosts (and arc-style
+* frameworks) extract these from the request context once and forward
+* them into every repo call so plugins don't need request-context
+* access of their own.
+*
+* Without a single agreed-on set, drift is inevitable: one host
+* forwards `userId`, another forwards `actorId`, a third forgets
+* `requestId` entirely — and audit logs lose attribution silently.
+* `STANDARD_REPO_OPTION_KEYS` is the contract every kit and every
+* arc-style framework agrees on. Adding a key here is a deliberate
+* ecosystem-wide commitment.
+*
+* Kits implementing custom plugins (commission, supplier-performance,
+* pos, ...) can declare their own canonical sets via mongokit's
+* `createOptionsExtractor<TCtx>` — that pattern stays domain-local and
+* doesn't pollute the cross-kit contract.
+*/
+/**
+* The canonical keys every kit's plugin layer reads from the options
+* bag, and every framework auto-threads from request context.
+*
+* - `organizationId` — multi-tenant scope. Tenant plugins
+*   (mongokit's `multiTenantPlugin`, sqlitekit's tenant filter) read
+*   it to stamp on write + filter on read. Cast handling (e.g.
+*   `ObjectId` coercion) is plugin-local — pass the raw scope id.
+* - `userId` — actor id for audit attribution. Audit-log / audit-
+*   trail plugins read it for the `who` column.
+* - `user` — denormalized actor object, when the audit log wants
+*   richer payload than a bare id (display name, role snapshot, ...).
+* - `session` — driver-specific transaction handle. Mongoose
+*   `ClientSession`, better-sqlite3 transaction fn, Prisma
+*   transaction client. Opaque to repo-core — kits narrow at the
+*   boundary.
+* - `requestId` — request correlation id for trace stitching across
+*   logs, events, and downstream service calls.
+*
+* Frameworks should treat this set as the canonical forward list:
+* peel matching keys off the request context, drop them into the
+* options bag, and let kit plugins read what they implement. Unknown
+* ctx keys do NOT forward — the bag stays narrow.
+*/
+const STANDARD_REPO_OPTION_KEYS = [
+	"organizationId",
+	"userId",
+	"user",
+	"session",
+	"requestId"
+];
+//#endregion
+export { STANDARD_REPO_OPTION_KEYS };