@classytic/repo-core 0.3.0 → 0.4.0

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/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 };