@classytic/mongokit 3.18.0 → 3.19.0

package/README.md

@@ -351,6 +351,72 @@ npm run build
 
 The test suite uses `mongodb-memory-server` by default. Set `MONGODB_URI` to run against an external MongoDB deployment.
 
+## Test Harness — `@classytic/mongokit/testkit`
+
+A batteries-included harness for testing your own repositories. Spins an ephemeral MongoDB (standalone, or a single-node replica set for transactions), opens an **isolated** connection, and gives you a live mongokit `Repository` in one call.
+
+`mongodb-memory-server` is an **optional peer** — install it where you use the testkit; it is never a production dependency and is dynamically imported, so it never enters your app bundle:
+
+```bash
+npm i -D mongodb-memory-server
+```
+
+```ts
+import { createTestRepository } from '@classytic/mongokit/testkit';
+
+const t = await createTestRepository({
+  name: 'Order',
+  schema: orderSchema,
+  config: { softDelete: true, timestamps: true }, // full CreateRepositoryConfig
+});
+
+await t.repository.create({ total: 10 });
+await t.clear();   // empty the collection between tests
+await t.close();   // close connection + stop server (idempotent)
+```
+
+### Run against your own local or cloud DB
+
+Pass a `uri` (or set `MONGODB_URI`) and **no in-memory server starts** — the testkit connects to your real database and `close()`/`stop()` become no-ops, so it never drops it:
+
+```ts
+const t = await createTestRepository({
+  name: 'Order', schema: orderSchema,
+  uri: process.env.ATLAS_TEST_URI ?? 'mongodb://localhost:27017/myapp-test',
+});
+```
+
+```bash
+# or for the whole suite, no code change:
+MONGODB_URI="mongodb+srv://…/myapp-test" vitest run
+```
+
+> ⚠️ `clear()` empties **every collection** on the connection. Against a real database, always point at a **dedicated test DB** — never production.
+
+### Testing indexes
+
+`createTestRepository` runs `model.init()`, so declared indexes are really built — unique-constraint enforcement (`E11000`), TTL, compound, text, and geo indexes all behave for real on the in-memory server. Use the exposed `model` for runtime index work:
+
+```ts
+await t.model.syncIndexes();
+await t.model.collection.indexes();          // inspect
+await t.model.collection.dropIndex('tag_1'); // drop
+```
+
+Atlas **`$search` / `$vectorSearch`** indexes are Atlas-only and don't exist on any non-Atlas server — test those by pointing `uri` at a real Atlas test cluster.
+
+### Helpers
+
+| Helper | Use |
+| --- | --- |
+| `createTestRepository` | server + connection + live `Repository` in one call |
+| `createTestConnection` | isolated connection + `clear()` / `close()` |
+| `withMongoMemory(fn)` | scoped setup → run → teardown (`finally`) |
+| `createMongoMemory` | raw server lifecycle (`uri` + `stop`) |
+| `mongoMemoryBackend()` | a `TestBackend` seam for `@classytic/arc-testkit` |
+
+All accept `{ replset?, dbName?, uri? }`.
+
 ## License
 
 MIT

package/dist/PaginationEngine-4SjzfBQE.d.mts

@@ -0,0 +1,103 @@
+import { A as KeysetPaginationOptions, U as PaginationConfig, V as OffsetPaginationOptions, i as AnyDocument, n as AggregatePaginationOptions } from "./types-BA8oXjFe.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
+export { PaginationEngine as t };

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-fi91ycQc.mjs";
+import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-BgSBwlWu.mjs";
 export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };

package/dist/adapter/index.mjs

@@ -1,2 +1,2 @@
-import { n as createMongooseAdapter, r as isMongooseModel, t as MongooseAdapter } from "../adapter-DYEMkLwK.mjs";
+import { n as createMongooseAdapter, r as isMongooseModel, t as MongooseAdapter } from "../adapter-BSxhT0Ip.mjs";
 export { MongooseAdapter, createMongooseAdapter, isMongooseModel };

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { G as Plugin } from "../types-CU3SEDbD.mjs";
+import { G as Plugin } from "../types-BA8oXjFe.mjs";
 import { PipelineStage } from "mongoose";
 
 //#region src/ai/types.d.ts

package/dist/better-auth/index.mjs

@@ -1,5 +1,5 @@
 import { n as Repository } from "../Repository-B01VW_fU.mjs";
-import { n as createMongooseAdapter } from "../adapter-DYEMkLwK.mjs";
+import { n as createMongooseAdapter } from "../adapter-BSxhT0Ip.mjs";
 import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@classytic/repo-core/better-auth";
 //#region src/better-auth/index.ts
 /**

package/dist/create-repository-D5YX0wGs.mjs

@@ -0,0 +1,29 @@
+import { n as Repository } from "./Repository-B01VW_fU.mjs";
+import { a as methodRegistryPlugin, d as cachePlugin, f as batchOperationsPlugin, h as auditLogPlugin, i as multiTenantPlugin, m as auditTrailPlugin, n as softDeletePlugin, o as customIdPlugin, t as timestampPlugin } from "./timestamp.plugin-B1A9U-P7.mjs";
+//#region src/create-repository.ts
+function isLoggerAudit(value) {
+	const v = value;
+	return typeof v.info === "function" || typeof v.warn === "function" || typeof v.error === "function" || typeof v.debug === "function";
+}
+/**
+* Build a `Repository` from a declarative config. See module JSDoc for
+* ordering guarantees and an example.
+*/
+function createRepository(model, config = {}) {
+	const { tenant, softDelete, timestamps, batch, cache, audit, customId, plugins = [], pagination = {}, ...repositoryOptions } = config;
+	const stack = [methodRegistryPlugin()];
+	if (tenant) stack.push(multiTenantPlugin(tenant));
+	if (softDelete) stack.push(softDeletePlugin(softDelete === true ? {} : softDelete));
+	if (timestamps) stack.push(timestampPlugin());
+	if (customId) stack.push(customIdPlugin(customId));
+	if (cache) stack.push(cachePlugin(cache));
+	if (audit) stack.push(isLoggerAudit(audit) ? auditLogPlugin(audit) : auditTrailPlugin(audit));
+	if (batch) stack.push(batchOperationsPlugin());
+	stack.push(...plugins);
+	return new Repository(model, stack, pagination, {
+		pluginOrderChecks: repositoryOptions.pluginOrderChecks ?? "throw",
+		...repositoryOptions
+	});
+}
+//#endregion
+export { createRepository as t };