monsqlize 2.0.5 → 3.0.0

package/dist/types/model.d.ts

@@ -1,11 +1,16 @@
 import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, InsertOneResult, UpdateBatchResult, UpdateResult } from './collection';
+import type { SchemaDslRuntime } from 'schema-dsl/runtime';
+
+/**
+ * Runtime-scoped schema-dsl namespace passed to Model schema callbacks.
+ */
+export type ModelSchemaDsl = SchemaDslRuntime['s'];
 
 /**
  * Schema DSL transformer function.
- * Receives a raw DSL descriptor and returns a transformed schema object.
  * @since v1.0.0
  */
-export type SchemaDSL = (dsl: unknown) => unknown;
+export type SchemaDSL = (s: ModelSchemaDsl) => unknown;
 
 /**
  * Default value for a model field — either a static value or a factory function.
@@ -54,6 +59,8 @@ export interface PopulateConfig {
     sort?: Record<string, 1 | -1>;
     limit?: number;
     skip?: number;
+    /** Maximum nested populate depth for this branch. Defaults to 5. */
+    maxDepth?: number;
     populate?: string | PopulateConfig | Array<string | PopulateConfig>;
 }
 
@@ -65,10 +72,38 @@ export interface VirtualConfig {
 export type ModelAutoIndexOptions = boolean | {
     /** Enable automatic model index creation. Defaults to true for backward compatibility. */
     enabled?: boolean;
-    /** Emit `model-index-error` when automatic index creation fails. Defaults to true. */
+    /** Emit `model-index-error` when automatic index creation fails or conflicts are detected. Defaults to true. */
     emitEvents?: boolean;
 };
 
+export type ModelVersionUpdateManyMode = 'counter' | 'strict' | 'off';
+
+export interface ModelVersionOptions {
+    enabled?: boolean;
+    field?: string;
+    /**
+     * Version handling for updateMany on versioned models.
+     * - counter: native batch update plus version increment; not optimistic locking.
+     * - strict: pre-read IDs/versions and conditionally update each document.
+     * - off: skip version handling for this batch update.
+     */
+    updateMany?: ModelVersionUpdateManyMode;
+}
+
+export type ModelWriteOptions = Record<string, unknown> & {
+    expectedVersion?: number;
+    version?: number;
+};
+
+export type ModelUpdateManyOptions = ModelWriteOptions & {
+    versionMode?: ModelVersionUpdateManyMode;
+};
+
+export type ModelStrictUpdateManyResult = UpdateResult & {
+    conflictCount: number;
+    conflictedIds: unknown[];
+};
+
 export type ModelIndexSource = 'definition' | 'softDelete';
 
 export interface ModelDeclaredIndex {
@@ -200,10 +235,7 @@ export interface ModelDefinitionOptions {
         type?: string;
         ttl?: number | null;
     };
-    version?: boolean | {
-        enabled?: boolean;
-        field?: string;
-    };
+    version?: boolean | ModelVersionOptions;
 }
 
 export interface ModelDefinition<TDocument = Record<string, unknown>> {
@@ -212,7 +244,7 @@ export interface ModelDefinition<TDocument = Record<string, unknown>> {
     /** Compatibility collection name used by model auto-loading files; `collection` has higher priority. */
     name?: string;
     enums?: Record<string, string>;
-    schema?: ((dsl: unknown) => unknown) | Record<string, unknown>;
+    schema?: SchemaDSL | Record<string, unknown>;
     defaults?: Record<string, unknown | ((context?: unknown, doc?: TDocument) => unknown)>;
     hooks?:
     | {
@@ -284,7 +316,7 @@ export interface ModelInstance<TDocument = any> {
     readonly poolName?: string;
     readonly definition: ModelDefinition<TDocument>;
     /** Returns namespace metadata for the current model, including instance ID, type, database, and collection. */
-    getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; };
+    getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; pool?: string; };
     /** Returns the relation config map declared by the current model. */
     getRelations(): Record<string, RelationConfig>;
     /** Returns the enum value map declared by the current model. */
@@ -379,21 +411,21 @@ export interface ModelInstance<TDocument = any> {
      * @param update Update operator document, such as `$set` or `$inc`.
      * @param options Optional update options.
      */
-    updateOne(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
+    updateOne(filter?: unknown, update?: unknown, options?: ModelWriteOptions): Promise<UpdateResult>;
     /**
      * Updates all documents matching the filter.
      * @param filter Filter.
      * @param update Update operator document.
      * @param options Optional update options.
      */
-    updateMany(filter?: unknown, update?: unknown, options?: unknown): Promise<UpdateResult>;
+    updateMany(filter?: unknown, update?: unknown, options?: ModelUpdateManyOptions): Promise<UpdateResult>;
     /**
      * Replaces the first document matching the filter with a full replacement document.
      * @param filter Filter.
      * @param replacement Full replacement document.
      * @param options Optional replacement options.
      */
-    replaceOne(filter?: unknown, replacement?: unknown, options?: unknown): Promise<UpdateResult>;
+    replaceOne(filter?: unknown, replacement?: unknown, options?: ModelWriteOptions): Promise<UpdateResult>;
     /**
      * Atomically finds and updates one document.
      * @param filter Filter.
@@ -401,7 +433,7 @@ export interface ModelInstance<TDocument = any> {
      * @param options Optional options such as `returnDocument: 'after'`.
      * @returns Updated document, or `null` when none is found.
      */
-    findOneAndUpdate(filter?: unknown, update?: unknown, options?: unknown): Promise<TDocument | null>;
+    findOneAndUpdate(filter?: unknown, update?: unknown, options?: ModelWriteOptions): Promise<TDocument | null>;
     /**
      * Atomically finds and replaces one document.
      * @param filter Filter.
@@ -409,7 +441,7 @@ export interface ModelInstance<TDocument = any> {
      * @param options Optional options.
      * @returns Replaced document, or `null` when none is found.
      */
-    findOneAndReplace(filter?: unknown, replacement?: unknown, options?: unknown): Promise<TDocument | null>;
+    findOneAndReplace(filter?: unknown, replacement?: unknown, options?: ModelWriteOptions): Promise<TDocument | null>;
     /**
      * Atomically finds and deletes one document.
      * @param filter Filter.

package/dist/types/mongodb.d.mts

@@ -0,0 +1,56 @@
+import type { Db, MongoClient, MongoClientOptions } from 'mongodb';
+import type { SSHConfig } from './monsqlize.mjs';
+
+export interface MongoConnectConfig {
+    uri?: string;
+    options?: MongoClientOptions;
+    /** v1 compat: read preference shortcut merged into MongoClient options. */
+    readPreference?: MongoClientOptions['readPreference'];
+    /**
+     * v1 compat: when true, automatically starts mongodb-memory-server without requiring a uri.
+     * For testing only.
+     */
+    useMemoryServer?: boolean;
+    /** Instance/binary configuration options for mongodb-memory-server. */
+    memoryServerOptions?: {
+        instance?: {
+            port?: number;
+            dbName?: string;
+            storageEngine?: string;
+            replSet?: string;
+            dbPath?: string;
+            launchTimeout?: number;
+        };
+        binary?: { version?: string };
+        [key: string]: unknown;
+    };
+    /**
+     * SSH tunnel configuration. When provided, monSQLize establishes an SSH port-forward
+     * through the specified bastion host before connecting to MongoDB.
+     * The remote host/port are auto-parsed from `uri` unless overridden by `remoteHost`/`remotePort`.
+     * @since v1.3.0
+     */
+    ssh?: SSHConfig;
+    /**
+     * Explicit remote MongoDB host visible from the SSH server.
+     * Overrides the host auto-parsed from `uri` when `ssh` is set.
+     * @since v1.3.0
+     */
+    remoteHost?: string;
+    /**
+     * Explicit remote MongoDB port visible from the SSH server.
+     * Overrides the port auto-parsed from `uri` when `ssh` is set.
+     * @since v1.3.0
+     */
+    remotePort?: number;
+    /** @alias remoteHost — v1 SSH config field */
+    mongoHost?: string;
+    /** @alias remotePort — v1 SSH config field */
+    mongoPort?: number;
+}
+
+export interface MongoConnectionState {
+    client: MongoClient;
+    db: Db;
+}
+