@classytic/mongokit 3.12.0 → 3.13.1

package/README.md

@@ -9,7 +9,7 @@ Production-grade MongoDB repository pattern for Node.js. Zero runtime deps — M
 npm install @classytic/mongokit @classytic/repo-core mongoose
 ```
 
-Requires Mongoose `>=9.4.1`, `@classytic/repo-core` `>=0.3.0`, Node.js `>=22`.
+Requires Mongoose `>=9.4.1`, `@classytic/repo-core` `>=0.4.0`, Node.js `>=22`.
 
 > **Swap-able with sqlitekit.** Mongokit implements the `StandardRepo<TDoc>` contract from `@classytic/repo-core/repository`. Controller code written against the contract runs unchanged on [@classytic/sqlitekit](https://www.npmjs.com/package/@classytic/sqlitekit) — both kits share an identical conformance suite.
 
@@ -17,7 +17,7 @@ Requires Mongoose `>=9.4.1`, `@classytic/repo-core` `>=0.3.0`, Node.js `>=22`.
 
 - `getById(id)` → returns `null` on miss (not thrown). Invalid-shape ids (e.g. `'not-a-valid-id'` on an ObjectId `_id`) short-circuit to `null` rather than raising mongoose `CastError`.
 - `update(id, data)` → returns `null` on miss.
-- `delete(id)` → returns `{ success: false, message: 'Document not found' }` on miss.
+- `delete(id)` → returns `null` on miss. On hit, returns a `DeleteResult` (e.g. `{ message: 'Soft deleted successfully', id, soft: true }` when `softDeletePlugin` is wired; the driver's hard-delete result otherwise).
 - Pass `{ throwOnNotFound: true }` to opt back into the legacy 404-throw behavior for any of the three.
 
 ---
@@ -96,6 +96,42 @@ repo.on('after:create',  ({ context, result }) => { /* audit, notify */ });
 
 The `before:*` hook receives the context directly; `after:*` and `error:*` receive `{ context, result | error }`.
 
+### Middleware
+
+`useMiddleware()` composes around every op (including cache-hit branches), wrap-style. Inputs and outputs both pass through; registration order = composition order (first registered runs outermost).
+
+```ts
+repo.useMiddleware(async ({ operation, next }) => {
+  const start = performance.now();
+  try { return await next(); }
+  finally { metrics.record(operation, performance.now() - start); }
+});
+
+// Short-circuit by returning without calling next()
+repo.useMiddleware(async ({ operation, context, next }) => {
+  if (operation === 'getById' && readOnlyMaintenance) return cachedReadOnlyResponse(context.id);
+  return next();
+});
+```
+
+**Middleware is for ergonomics, NOT security.** This is the load-bearing distinction. The execution order on every call is:
+
+```text
+_buildContext + before:<op>     ← repo.on('before:*') hooks
+  [outer middleware pre]        ← repo.useMiddleware() registrations
+    [...inner middleware pre]
+      fn (driver call)
+      after:<op> | error:<op>   ← repo.on('after:*' / 'error:*')
+    [...inner middleware post]
+  [outer middleware post]
+```
+
+Build/`before:*` hooks fire BEFORE the middleware chain dispatches. A throw from a `before:*` policy hook (tenant scope, soft-delete, access-control) unwinds before middleware ever fires — middleware **cannot wrap, observe, or short-circuit a policy failure**.
+
+That's by design. Middleware as a security boundary would be impossible to audit because registration order would determine whether tenant scope wins. Use `before:*` hooks for security policy (tenant scope, soft-delete filtering, audit, cache invalidation) and `useMiddleware()` for ergonomics (timing, metrics, input/output mutation in a single closure).
+
+If you want middleware to observe a policy rejection, listen on `error:<op>` — that fires from inside the middleware chain and is reachable.
+
 ---
 
 ## Pagination
@@ -105,12 +141,12 @@ The `before:*` hook receives the context directly; `after:*` and `error:*` recei
 ```ts
 // Offset — dashboards, admin panels
 await repo.getAll({ mode: 'offset', page: 1, limit: 20, sort: { createdAt: -1 } });
-// → { method: 'offset', docs, total, pages, hasNext, hasPrev }
+// → { method: 'offset', data, total, pages, hasNext, hasPrev, page, limit }
 
 // Keyset — feeds, infinite scroll
 const p1 = await repo.getAll({ mode: 'keyset', sort: { createdAt: -1 }, limit: 20 });
 const p2 = await repo.getAll({ mode: 'keyset', sort: { createdAt: -1 }, after: p1.next });
-// → { method: 'keyset', docs, hasMore, next }
+// → { method: 'keyset', data, hasMore, next, limit }
 ```
 
 Keyset pagination with `filters + sort` warns once if no matching schema-declared compound index exists. Silent in `NODE_ENV=test`. Route warnings via `configureLogger({ warn })`.
@@ -248,6 +284,58 @@ Each plugin is tree-shakeable. Import only what you use.
 
 ---
 
+## Composing with mongoose-level plugins
+
+mongokit deliberately doesn't reabsorb mongoose plugins that already work via `schema.plugin(...)`. They compose cleanly: the mongoose plugin attaches to the schema before the model lands at mongokit, both layers fire on every write.
+
+Canonical examples — install + wire as documented by the upstream package, then hand the model to mongokit:
+
+```ts
+import mongoose from 'mongoose';
+import { Repository, multiTenantPlugin } from '@classytic/mongokit';
+import timelineAuditPlugin from 'mongoose-timeline-audit';
+import slugPlugin from 'mongoose-slug-plugin';
+
+const orderSchema = new mongoose.Schema({
+  customerId: { type: mongoose.Schema.Types.ObjectId, ref: 'Customer' },
+  status: String,
+  title: String,
+});
+
+// 1. Wire mongoose-level plugins on the schema
+orderSchema.plugin(timelineAuditPlugin, {
+  ownerField: 'customerId',
+  eventLimits: { 'order.updated': 20 },
+});
+orderSchema.plugin(slugPlugin, { tmpl: '<%=title%>' });
+
+// 2. Build the model
+const Order = mongoose.model('Order', orderSchema);
+
+// 3. Hand the model to mongokit — kit plugins layer on top
+const orderRepo = new Repository(Order, [
+  multiTenantPlugin({ tenantField: 'organizationId' }),
+]);
+
+// Now every write fires BOTH layers:
+//   - mongoose pre('save') / post('save') (timeline-audit, slug)
+//   - mongokit before:create / after:create (multi-tenant, audit, cache)
+await orderRepo.create({ customerId, status: 'pending', title: 'New order' });
+```
+
+**Why this composition over absorbing into mongokit:** mongoose plugins hook `schema.add()` + `pre('save')`; mongokit plugins hook `before:create` / `after:update`. Different event models, different concerns. Wrapping a mongoose plugin as a mongokit plugin would be a fork, not a wrapper — and the mongoose plugin already works without mongokit being involved at all. Keeping the layers separate also lets each package version independently.
+
+**When to use which audit surface:**
+
+| Need | Reach for |
+|---|---|
+| Per-doc UX timeline visible to end users (`order.timeline = [{event, actor, at}, ...]`) | `mongoose-timeline-audit` (mongoose plugin) — embedded array on the doc |
+| Compliance audit ledger across models, immutable, queryable | `auditTrailPlugin` (mongokit, ships in this package) — separate collection |
+
+The two are complementary, not alternatives. A typical app wires both — timeline for the customer-facing order page, auditTrail for the compliance officer's quarterly export.
+
+---
+
 ## QueryParser (URL → filter)
 
 Turn Express / Fastify query strings into sanitized Mongo filters + sort + pagination.
@@ -313,6 +401,40 @@ import { coerceFieldValue } from '@classytic/mongokit/query/primitives/coercion'
 
 ---
 
+## Better Auth bridge — `@classytic/mongokit/better-auth`
+
+When [Better Auth](https://better-auth.com) writes to your Mongo collections via `@better-auth/mongo-adapter`, mongokit ships a kit-owned bridge so you can expose those collections as full repositories — pagination, query parser, OpenAPI, audit, all of it.
+
+**Two helpers**:
+
+```ts
+import {
+  registerBetterAuthStubs,    // bulk stubs for `populate('user')` etc.
+  createBetterAuthOverlay,    // per-collection DataAdapter for arc/your host
+} from '@classytic/mongokit/better-auth';
+
+// 1. Bulk-register stubs so populate() works app-wide.
+registerBetterAuthStubs(mongoose, { plugins: ['organization'] });
+
+// 2. Per-resource overlay — async because we read BA's resolved schema.
+//    Resolves once at boot, picks up additionalFields + modelName overrides
+//    + plugin schema additions automatically.
+const orgAdapter = await createBetterAuthOverlay({
+  auth,                                // your betterAuth() instance
+  mongoose,
+  collection: 'organization',
+});
+
+// Plug the adapter into any host that consumes `DataAdapter<TDoc>`:
+defineResource({ name: 'organization', adapter: orgAdapter });
+```
+
+Need custom validators / Repository methods / `toJSON` transforms (e.g., strip `password`)? Drop the factory and hand-roll the schema + Repository — that's the recommended path when you outgrow the defaults. The factory and the hand-roll produce structurally identical adapters; you can switch back and forth without touching consumer code.
+
+`better-auth` is an **optional peer dependency** — only required when you import this subpath. Mongokit users who don't touch BA don't get an install warning.
+
+---
+
 ## Testing
 
 Uses `mongodb-memory-server` by default; override via `MONGODB_URI` for a real replica set when running transaction tests locally.

package/dist/{PaginationEngine-BDaAsyPn.mjs → PaginationEngine-CfQRM1yz.mjs}

@@ -1,4 +1,4 @@
-import { r as warn } from "./logger-8-VS1za6.mjs";
+import { n as warn } from "./logger-DprijP5h.mjs";
 import { t as createError } from "./error-B00pI7dV.mjs";
 import { n as encodeCursor, r as resolveCursorFilter } from "./cursor-J84rR6wG.mjs";
 import { r as validateKeysetSort, t as getPrimaryField } from "./sort-CrZjTK25.mjs";
@@ -224,7 +224,7 @@ var PaginationEngine = class {
 	*   page: 1,
 	*   limit: 20
 	* });
-	* console.log(result.docs, result.total, result.hasNext);
+	* console.log(result.data, result.total, result.hasNext);
 	*/
 	async paginate(options = {}) {
 		const { filters = {}, sort, countFilters, page = 1, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, maxTimeMS, countStrategy = "exact", readPreference, collation } = options;
@@ -255,17 +255,17 @@ var PaginationEngine = class {
 			if (readPreference) countQuery.read(readPreference);
 			countPromise = countQuery.exec();
 		}
-		const [docs, total] = await Promise.all([query.exec(), countPromise]);
+		const [data, total] = await Promise.all([query.exec(), countPromise]);
 		const totalPages = countStrategy === "none" ? 0 : calculateTotalPages(total, sanitizedLimit);
 		let hasNext;
 		if (countStrategy === "none") {
-			hasNext = docs.length > sanitizedLimit;
-			if (hasNext) docs.pop();
+			hasNext = data.length > sanitizedLimit;
+			if (hasNext) data.pop();
 		} else hasNext = sanitizedPage < totalPages;
 		const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination (page ${sanitizedPage}). Consider getAll({ after, sort, limit }) for better performance.` : void 0;
 		return {
 			method: "offset",
-			docs,
+			data,
 			page: sanitizedPage,
 			limit: sanitizedLimit,
 			total,
@@ -321,16 +321,16 @@ var PaginationEngine = class {
 		if (hint) mongoQuery = mongoQuery.hint(hint);
 		if (maxTimeMS) mongoQuery = mongoQuery.maxTimeMS(maxTimeMS);
 		if (readPreference) mongoQuery = mongoQuery.read(readPreference);
-		const docs = await mongoQuery.exec();
-		const hasMore = docs.length > sanitizedLimit;
-		if (hasMore) docs.pop();
+		const data = await mongoQuery.exec();
+		const hasMore = data.length > sanitizedLimit;
+		if (hasMore) data.pop();
 		const primaryField = getPrimaryField(normalizedSort);
 		return {
 			method: "keyset",
-			docs,
+			data,
 			limit: sanitizedLimit,
 			hasMore,
-			next: hasMore && docs.length > 0 ? encodeCursor(docs[docs.length - 1], primaryField, normalizedSort, this.config.cursorVersion) : null
+			next: hasMore && data.length > 0 ? encodeCursor(data[data.length - 1], primaryField, normalizedSort, this.config.cursorVersion) : null
 		};
 	}
 	/**
@@ -358,7 +358,7 @@ var PaginationEngine = class {
 		const sanitizedLimit = validateLimit(limit, this.config);
 		const skip = calculateSkip(sanitizedPage, sanitizedLimit);
 		const fetchLimit = countStrategy === "none" ? sanitizedLimit + 1 : sanitizedLimit;
-		const facetStages = { docs: [{ $skip: skip }, { $limit: fetchLimit }] };
+		const facetStages = { data: [{ $skip: skip }, { $limit: fetchLimit }] };
 		if (countStrategy !== "none") facetStages.total = [{ $count: "count" }];
 		const facetPipeline = [...pipeline, { $facet: facetStages }];
 		const aggregation = this.Model.aggregate(facetPipeline);
@@ -367,18 +367,18 @@ var PaginationEngine = class {
 		if (maxTimeMS) aggregation.option({ maxTimeMS });
 		if (readPreference) aggregation.read(readPreference);
 		const [result] = await aggregation.exec();
-		const docs = result.docs;
+		const data = result.data;
 		const total = result.total?.[0]?.count || 0;
 		const totalPages = countStrategy === "none" ? 0 : calculateTotalPages(total, sanitizedLimit);
 		let hasNext;
 		if (countStrategy === "none") {
-			hasNext = docs.length > sanitizedLimit;
-			if (hasNext) docs.pop();
+			hasNext = data.length > sanitizedLimit;
+			if (hasNext) data.pop();
 		} else hasNext = sanitizedPage < totalPages;
 		const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination in aggregate (page ${sanitizedPage}). Uses $skip internally.` : void 0;
 		return {
 			method: "aggregate",
-			docs,
+			data,
 			page: sanitizedPage,
 			limit: sanitizedLimit,
 			total,