@classytic/mongokit 3.18.0 → 3.20.0

package/dist/pagination/PaginationEngine.d.mts

@@ -1,103 +1,2 @@
-import { A as KeysetPaginationOptions, U as PaginationConfig, V as OffsetPaginationOptions, i as AnyDocument, n as AggregatePaginationOptions } from "../types-CU3SEDbD.mjs";
-import { Model } from "mongoose";
-import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
-
-//#region src/pagination/PaginationEngine.d.ts
-/**
- * Internal pagination config with required values
- */
-interface ResolvedPaginationConfig {
-  defaultLimit: number;
-  maxLimit: number;
-  maxPage: number;
-  deepPageThreshold: number;
-  cursorVersion: number;
-  minCursorVersion: number;
-  strictKeysetSortFields: string[] | undefined;
-  useEstimatedCount: boolean;
-}
-/**
- * Production-grade pagination engine for MongoDB
- * Supports offset, keyset (cursor), and aggregate pagination
- */
-declare class PaginationEngine<TDoc = AnyDocument> {
-  readonly Model: Model<TDoc>;
-  readonly config: ResolvedPaginationConfig;
-  /**
-   * Lazily-cached schema index snapshot used by stream() to decide whether
-   * to emit the "missing compound index" warning. Computed on first use.
-   */
-  private _cachedSchemaIndexes;
-  /**
-   * Create a new pagination engine
-   *
-   * @param Model - Mongoose model to paginate
-   * @param config - Pagination configuration
-   */
-  constructor(Model: Model<TDoc, any, any, any>, config?: PaginationConfig);
-  /** Memoized schema index lookup — avoids re-walking schema on every stream(). */
-  private _getSchemaIndexes;
-  /**
-   * Offset-based pagination using skip/limit
-   * Best for small datasets and when users need random page access
-   * O(n) performance - slower for deep pages
-   *
-   * @param options - Pagination options
-   * @returns Pagination result with total count
-   *
-   * @example
-   * const result = await engine.paginate({
-   *   filters: { status: 'active' },
-   *   sort: { createdAt: -1 },
-   *   page: 1,
-   *   limit: 20
-   * });
-   * console.log(result.data, result.total, result.hasNext);
-   */
-  paginate(options?: OffsetPaginationOptions): Promise<OffsetPaginationResult<TDoc>>;
-  /**
-   * Keyset (cursor-based) pagination for high-performance streaming
-   * Best for large datasets, infinite scroll, real-time feeds
-   * O(1) performance - consistent speed regardless of position
-   *
-   * @param options - Pagination options (sort is required)
-   * @returns Pagination result with next cursor
-   *
-   * @example
-   * // First page
-   * const page1 = await engine.stream({
-   *   sort: { createdAt: -1 },
-   *   limit: 20
-   * });
-   *
-   * // Next page using cursor
-   * const page2 = await engine.stream({
-   *   sort: { createdAt: -1 },
-   *   after: page1.next,
-   *   limit: 20
-   * });
-   */
-  stream(options: KeysetPaginationOptions): Promise<KeysetPaginationResult<TDoc>>;
-  /**
-   * Aggregate pipeline with pagination
-   * Best for complex queries requiring aggregation stages
-   * Uses $facet to combine results and count in single query
-   *
-   * @param options - Aggregation options
-   * @returns Pagination result with total count
-   *
-   * @example
-   * const result = await engine.aggregatePaginate({
-   *   pipeline: [
-   *     { $match: { status: 'active' } },
-   *     { $group: { _id: '$category', count: { $sum: 1 } } },
-   *     { $sort: { count: -1 } }
-   *   ],
-   *   page: 1,
-   *   limit: 20
-   * });
-   */
-  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
-}
-//#endregion
+import { t as PaginationEngine } from "../PaginationEngine-DYpOD2wY.mjs";
 export { PaginationEngine };

package/dist/pagination/PaginationEngine.mjs

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-BcvaXBQ-.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-BT1ywu9k.mjs";
 export { PaginationEngine };

package/dist/plugins/index.d.mts

@@ -1,7 +1,7 @@
-import { G as Plugin } from "../types-CU3SEDbD.mjs";
-import { $ as AuditEntry, B as IdGenerator, C as LeasePluginOptions, D as elasticSearchPlugin, E as ElasticSearchOptions, F as MultiTenantOptions, G as getNextSequence, H as SequentialIdOptions, J as CacheAdapter, K as prefixedId, L as multiTenantPlugin, M as auditLogPlugin, N as AggregateHelpersMethods, O as cascadePlugin, P as aggregateHelpersPlugin, Q as cachePlugin, R as CustomIdOptions, S as LeaseMethods, T as fieldFilterPlugin, U as customIdPlugin, V as PrefixedIdOptions, W as dateSequentialId, X as RepositoryCacheHandle, Y as CacheOptions, Z as RepositoryCachePluginOptions, _ as observabilityPlugin, a as uniqueField, at as AuditTrailQuery, b as MethodRegistryRepository, c as TenantContext, d as SubdocumentMethods, et as AuditOperation, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, it as AuditTrailOptions, j as batchOperationsPlugin, k as BatchOperationsMethods, l as TenantStore, m as softDeletePlugin, n as blockIf, nt as AuditQueryResult, o as validationChainPlugin, ot as auditTrailPlugin, p as SoftDeleteMethods, q as sequentialId, r as immutableField, rt as AuditTrailMethods, s as timestampPlugin, t as autoInject, tt as AuditQueryOptions, u as createTenantContext, v as MongoOperationsMethods, w as leasePlugin, x as methodRegistryPlugin, y as mongoOperationsPlugin, z as DateSequentialIdOptions } from "../validation-chain.plugin-BpMfy18N.mjs";
+import { G as Plugin } from "../types-DNFMofHy.mjs";
+import { C as AuditTrailMethods, E as auditTrailPlugin, S as AuditQueryResult, T as AuditTrailQuery, _ as RepositoryCachePluginOptions, a as DateSequentialIdOptions, b as AuditOperation, c as SequentialIdOptions, d as getNextSequence, f as prefixedId, g as RepositoryCacheHandle, h as CacheOptions, i as CustomIdOptions, l as customIdPlugin, m as CacheAdapter, o as IdGenerator, p as sequentialId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as cachePlugin, w as AuditTrailOptions, x as AuditQueryOptions, y as AuditEntry } from "../multi-tenant.plugin-CTsWz0XK.mjs";
+import { C as LeasePluginOptions, D as elasticSearchPlugin, E as ElasticSearchOptions, M as auditLogPlugin, N as AggregateHelpersMethods, O as cascadePlugin, P as aggregateHelpersPlugin, S as LeaseMethods, T as fieldFilterPlugin, _ as observabilityPlugin, a as uniqueField, b as MethodRegistryRepository, c as TenantContext, d as SubdocumentMethods, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, j as batchOperationsPlugin, k as BatchOperationsMethods, l as TenantStore, m as softDeletePlugin, n as blockIf, o as validationChainPlugin, p as SoftDeleteMethods, r as immutableField, s as timestampPlugin, t as autoInject, u as createTenantContext, v as MongoOperationsMethods, w as leasePlugin, x as methodRegistryPlugin, y as mongoOperationsPlugin } from "../validation-chain.plugin-buy3uvyk.mjs";
 import { ChangeLogStore } from "@classytic/repo-core/sync";
-
 //#region src/plugins/change-log.plugin.d.ts
 interface ChangeLogPluginOptions {
   /** Durable feed implementing the repo-core/sync contract. */

package/dist/plugins/index.mjs

@@ -1,4 +1,5 @@
-import { A as auditLogPlugin, C as getNextSequence, D as batchOperationsPlugin, E as cachePlugin, O as AuditTrailQuery, S as dateSequentialId, T as sequentialId, _ as softDeletePlugin, a as uniqueField, b as methodRegistryPlugin, c as subdocumentPlugin, d as leasePlugin, f as fieldFilterPlugin, g as timestampPlugin, h as aggregateHelpersPlugin, i as requireField, k as auditTrailPlugin, l as observabilityPlugin, m as cascadePlugin, n as blockIf, o as validationChainPlugin, p as elasticSearchPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as mongoOperationsPlugin, w as prefixedId, x as customIdPlugin, y as multiTenantPlugin } from "../validation-chain.plugin-DJtC0KJ-.mjs";
+import { a as methodRegistryPlugin, c as getNextSequence, d as cachePlugin, f as batchOperationsPlugin, h as auditLogPlugin, i as multiTenantPlugin, l as prefixedId, m as auditTrailPlugin, n as softDeletePlugin, o as customIdPlugin, p as AuditTrailQuery, s as dateSequentialId, t as timestampPlugin, u as sequentialId } from "../timestamp.plugin-nG9Z1JEk.mjs";
+import { a as uniqueField, c as subdocumentPlugin, d as leasePlugin, f as fieldFilterPlugin, h as aggregateHelpersPlugin, i as requireField, l as observabilityPlugin, m as cascadePlugin, n as blockIf, o as validationChainPlugin, p as elasticSearchPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as mongoOperationsPlugin } from "../validation-chain.plugin-Dn_wZYLA.mjs";
 //#region src/plugins/change-log.plugin.ts
 const PLUGIN_NAME = "changeLog";
 function isSkipped(context) {

package/dist/query/primitives/coercion.d.mts

@@ -1,2 +1,2 @@
-import { a as coerceHeuristic, i as coerceFieldValue, n as SchemaPathsLike, o as coerceToType, r as buildFieldTypeMap, s as normalizeMongooseType, t as FieldType } from "../../coercion-TRMmR49h.mjs";
+import { a as coerceHeuristic, i as coerceFieldValue, n as SchemaPathsLike, o as coerceToType, r as buildFieldTypeMap, s as normalizeMongooseType, t as FieldType } from "../../coercion-BjdPX3YF.mjs";
 export { FieldType, SchemaPathsLike, buildFieldTypeMap, coerceFieldValue, coerceHeuristic, coerceToType, normalizeMongooseType };

package/dist/query/primitives/coercion.mjs

@@ -1,4 +1,4 @@
-import { r as isObjectIdInstance } from "../../id-resolution-CnN0YA8t.mjs";
+import { r as isObjectIdInstance } from "../../id-resolution-P2OzcyRl.mjs";
 import mongoose from "mongoose";
 //#region src/query/primitives/coercion.ts
 /**

package/dist/query/primitives/geo.d.mts

@@ -14,7 +14,7 @@
  * `[nearSphere]`, or `[geoWithin]` operator on a field.
  */
 /** Geo operators recognized by the parser */
-declare const GEO_OPERATORS: readonly ["near", "nearSphere", "geoWithin", "withinRadius"];
+declare const GEO_OPERATORS: readonly ['near', 'nearSphere', 'geoWithin', 'withinRadius'];
 type GeoOperator = (typeof GEO_OPERATORS)[number];
 /**
  * True iff `operator` is one of the geo operators we handle.

package/dist/query/primitives/indexes.d.mts

@@ -1,2 +1,2 @@
-import { n as SchemaIndexes, r as extractSchemaIndexes, t as IndexableSchema } from "../../indexes-CgOF7Wjd.mjs";
+import { n as SchemaIndexes, r as extractSchemaIndexes, t as IndexableSchema } from "../../indexes-DIjMpYES.mjs";
 export { IndexableSchema, SchemaIndexes, extractSchemaIndexes };

package/dist/testkit/index.d.mts

@@ -0,0 +1,128 @@
+import { a as Repository, n as CreateRepositoryConfig } from "../create-repository-0TkQhcv-.mjs";
+import { Connection, Model, Schema } from "mongoose";
+import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
+//#region src/testkit/index.d.ts
+interface MongoMemoryOptions {
+  /**
+   * Boot a single-node replica set instead of a standalone mongod. Required for
+   * any code that opens a `session.startTransaction()` — a standalone server
+   * rejects it with error 263. Slightly slower to start (~2-3s). Default false.
+   */
+  replset?: boolean;
+  /** Database name baked into the generated URI. Default `"mongokit-test"`. */
+  dbName?: string;
+  /**
+   * Use this URI instead of spinning an in-memory server (real MongoDB, CI
+   * replica set). Falls back to `process.env.MONGODB_URI`. When either is set,
+   * `stop()` is a no-op — the caller owns the server's lifecycle.
+   */
+  uri?: string;
+}
+interface MongoMemoryHandle {
+  /** Connection string for the running (or external) server. */
+  uri: string;
+  /** The in-memory server; `undefined` when an external `uri` is used. */
+  server?: MongoMemoryServer | MongoMemoryReplSet;
+  /** Stop the in-memory server. No-op for an external URI. Idempotent. */
+  stop(): Promise<void>;
+}
+/**
+ * Start an ephemeral MongoDB (or resolve an external one) and return its URI +
+ * a `stop()` teardown. Prefer `createTestConnection` / `createTestRepository`
+ * unless you need the server without a mongoose connection.
+ */
+declare function createMongoMemory(options?: MongoMemoryOptions): Promise<MongoMemoryHandle>;
+interface TestConnection {
+  /** An isolated mongoose connection (never the global `mongoose.connection`). */
+  connection: Connection;
+  uri: string;
+  /** Empty every collection on this connection — call in `beforeEach`. */
+  clear(): Promise<void>;
+  /** Close the connection and stop the server. Idempotent. */
+  close(): Promise<void>;
+}
+/** Drop every document in every collection on a connection (models preserved). */
+declare function clearCollections(connection: Connection): Promise<void>;
+/**
+ * Start (or resolve) a server AND open an isolated mongoose connection over it.
+ * Each call gets its own connection — model registries are per-connection, so
+ * repeated boots in one process never collide.
+ */
+declare function createTestConnection(options?: MongoMemoryOptions): Promise<TestConnection>;
+/**
+ * Scoped harness: start a connection, run `fn`, and tear down in a `finally`
+ * even if `fn` throws.
+ *
+ * ```ts
+ * await withMongoMemory(async ({ connection }) => {
+ *   const repo = createRepository(connection.model("User", userSchema));
+ *   // ... assertions ...
+ * });
+ * ```
+ */
+declare function withMongoMemory<T>(fn: (ctx: TestConnection) => Promise<T> | T, options?: MongoMemoryOptions): Promise<T>;
+interface CreateTestRepositoryOptions<TDoc> extends MongoMemoryOptions {
+  /** Model / collection name (unique per test to avoid cross-file collisions). */
+  name: string;
+  /** Mongoose schema for the model. */
+  schema: Schema<TDoc>;
+  /** mongokit `createRepository` config — tenant, softDelete, plugins, cache… */
+  config?: CreateRepositoryConfig;
+}
+interface TestRepository<TDoc> {
+  /** A live mongokit repository over an in-memory collection. */
+  repository: Repository<TDoc>;
+  /** The underlying mongoose model (bound to the isolated connection). */
+  model: Model<TDoc>;
+  connection: Connection;
+  uri: string;
+  /** Empty this repository's collection. */
+  clear(): Promise<void>;
+  /** Close the connection and stop the server. Idempotent. */
+  close(): Promise<void>;
+}
+/**
+ * The fast path for testing a mongokit repository: spins an in-memory server,
+ * opens an isolated connection, registers the model on it, builds indexes, and
+ * returns a ready `Repository` (plus `clear()` / `close()`).
+ *
+ * ```ts
+ * const t = await createTestRepository({ name: "Order", schema: orderSchema,
+ *   config: { softDelete: true } });
+ * await t.repository.create({ total: 10 });
+ * await t.close();
+ * ```
+ */
+declare function createTestRepository<TDoc>(options: CreateTestRepositoryOptions<TDoc>): Promise<TestRepository<TDoc>>;
+/** The context a module receives from the Mongo backend (live connection + URI). */
+interface MongoTestContext {
+  connection: Connection;
+  uri: string;
+}
+/**
+ * A backend usable by `@classytic/arc-testkit`'s `bootModuleApp`. Structurally
+ * a `TestBackend<MongoTestContext>` — no import of arc-testkit, so mongokit
+ * never depends on it (one-way: arc-testkit consumes this by shape).
+ */
+interface MongoMemoryBackend {
+  setup(): Promise<{
+    ctx: MongoTestContext;
+    teardown: () => Promise<void>;
+  }>;
+}
+/**
+ * A real in-memory Mongo backend for arc-testkit:
+ *
+ * ```ts
+ * import { bootModuleApp } from "@classytic/arc-testkit";
+ * import { mongoMemoryBackend } from "@classytic/mongokit/testkit";
+ *
+ * const t = await bootModuleApp(
+ *   ({ connection }) => [createAccountingModule({ connection, permissions })],
+ *   { backend: mongoMemoryBackend() },
+ * );
+ * ```
+ */
+declare function mongoMemoryBackend(options?: MongoMemoryOptions): MongoMemoryBackend;
+//#endregion
+export { CreateTestRepositoryOptions, MongoMemoryBackend, MongoMemoryHandle, MongoMemoryOptions, MongoTestContext, TestConnection, TestRepository, clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, withMongoMemory };

package/dist/testkit/index.mjs

@@ -0,0 +1,139 @@
+import { t as createRepository } from "../create-repository-CJATiAKX.mjs";
+import { createConnection } from "mongoose";
+//#region src/testkit/index.ts
+function idempotentStop(server) {
+	let stopped = false;
+	return async () => {
+		if (stopped) return;
+		stopped = true;
+		await server.stop().catch(() => void 0);
+	};
+}
+/**
+* Start an ephemeral MongoDB (or resolve an external one) and return its URI +
+* a `stop()` teardown. Prefer `createTestConnection` / `createTestRepository`
+* unless you need the server without a mongoose connection.
+*/
+async function createMongoMemory(options = {}) {
+	const externalUri = options.uri ?? process.env.MONGODB_URI;
+	if (externalUri) return {
+		uri: externalUri,
+		stop: async () => void 0
+	};
+	const { MongoMemoryServer, MongoMemoryReplSet } = await import("mongodb-memory-server");
+	const dbName = options.dbName ?? "mongokit-test";
+	if (options.replset) {
+		const rs = await MongoMemoryReplSet.create({ replSet: { count: 1 } });
+		return {
+			uri: rs.getUri(dbName),
+			server: rs,
+			stop: idempotentStop(rs)
+		};
+	}
+	const server = await MongoMemoryServer.create();
+	return {
+		uri: server.getUri(dbName),
+		server,
+		stop: idempotentStop(server)
+	};
+}
+/** Drop every document in every collection on a connection (models preserved). */
+async function clearCollections(connection) {
+	const collections = await connection.db?.collections();
+	if (!collections) return;
+	await Promise.all(collections.map((c) => c.deleteMany({})));
+}
+/**
+* Start (or resolve) a server AND open an isolated mongoose connection over it.
+* Each call gets its own connection — model registries are per-connection, so
+* repeated boots in one process never collide.
+*/
+async function createTestConnection(options = {}) {
+	const handle = await createMongoMemory(options);
+	const connection = await createConnection(handle.uri).asPromise();
+	let closed = false;
+	return {
+		connection,
+		uri: handle.uri,
+		clear: () => clearCollections(connection),
+		close: async () => {
+			if (closed) return;
+			closed = true;
+			await connection.close().catch(() => void 0);
+			await handle.stop();
+		}
+	};
+}
+/**
+* Scoped harness: start a connection, run `fn`, and tear down in a `finally`
+* even if `fn` throws.
+*
+* ```ts
+* await withMongoMemory(async ({ connection }) => {
+*   const repo = createRepository(connection.model("User", userSchema));
+*   // ... assertions ...
+* });
+* ```
+*/
+async function withMongoMemory(fn, options = {}) {
+	const ctx = await createTestConnection(options);
+	try {
+		return await fn(ctx);
+	} finally {
+		await ctx.close();
+	}
+}
+/**
+* The fast path for testing a mongokit repository: spins an in-memory server,
+* opens an isolated connection, registers the model on it, builds indexes, and
+* returns a ready `Repository` (plus `clear()` / `close()`).
+*
+* ```ts
+* const t = await createTestRepository({ name: "Order", schema: orderSchema,
+*   config: { softDelete: true } });
+* await t.repository.create({ total: 10 });
+* await t.close();
+* ```
+*/
+async function createTestRepository(options) {
+	const tc = await createTestConnection(options);
+	const model = tc.connection.model(options.name, options.schema);
+	await model.init();
+	return {
+		repository: createRepository(model, options.config),
+		model,
+		connection: tc.connection,
+		uri: tc.uri,
+		clear: async () => {
+			await model.deleteMany({});
+		},
+		close: tc.close
+	};
+}
+/**
+* A real in-memory Mongo backend for arc-testkit:
+*
+* ```ts
+* import { bootModuleApp } from "@classytic/arc-testkit";
+* import { mongoMemoryBackend } from "@classytic/mongokit/testkit";
+*
+* const t = await bootModuleApp(
+*   ({ connection }) => [createAccountingModule({ connection, permissions })],
+*   { backend: mongoMemoryBackend() },
+* );
+* ```
+*/
+function mongoMemoryBackend(options = {}) {
+	return { async setup() {
+		const tc = await createTestConnection(options);
+		return {
+			ctx: {
+				connection: tc.connection,
+				uri: tc.uri
+			},
+			teardown: tc.close
+		};
+	} };
+}
+//#endregion
+export { clearCollections, createMongoMemory, createTestConnection, createTestRepository, mongoMemoryBackend, withMongoMemory };