monsqlize 2.0.6 → 3.1.0

package/dist/types/data-tasks.d.ts

@@ -0,0 +1,221 @@
+import type { MonSQLizeOptions } from './monsqlize';
+
+export type DataTaskEnvironment = 'development' | 'test' | 'staging' | 'production' | 'prod' | 'live';
+
+export interface DataTaskIndexDefinition {
+    key: Record<string, unknown>;
+    options?: Record<string, unknown>;
+    name?: string;
+}
+
+export type DataTaskJobErrorCode =
+    | 'INVALID_JOB'
+    | 'IDENTITY_CONFLICT'
+    | 'INDEX_CONFLICT'
+    | 'APPROVAL_STALE'
+    | 'BACKUP_FAILED'
+    | 'LOCK_NOT_ACQUIRED'
+    | 'LOCK_LOST'
+    | 'APPLY_PARTIAL'
+    | 'RESTORE_DRIFT'
+    | 'RESTORE_FAILED';
+
+export declare class DataTaskJobError extends Error {
+    readonly code: DataTaskJobErrorCode;
+    readonly phase: string;
+    readonly collection?: string;
+    constructor(code: DataTaskJobErrorCode, message: string, phase?: string, collection?: string);
+}
+
+export interface DataTaskConnectionRuntime {
+    readonly options?: MonSQLizeOptions;
+    collection(name: string): unknown;
+    connect?(): Promise<unknown>;
+    close?(): Promise<void>;
+}
+
+export type DataTaskConnection = DataTaskConnectionRuntime | MonSQLizeOptions;
+
+export type DataTaskIdentity =
+    | { mode: 'fields'; fields: string[] }
+    | { mode: 'source-id'; conflictBy?: string[] };
+
+export interface DataTaskDataRule {
+    filter?: Record<string, unknown>;
+    all?: boolean;
+    identity: DataTaskIdentity;
+    strategy?: 'upsert' | 'insert';
+    projection?: Record<string, unknown>;
+    /** Rename only the listed source fields before synchronizing them. */
+    rename?: Record<string, string>;
+    /** Set only the listed literal values before synchronizing the document. */
+    set?: Record<string, unknown>;
+    /** Remove only the listed field paths from the synchronized target document. */
+    unset?: string[];
+    /** Maximum source documents this collection may plan. Defaults to 10000. */
+    maxDocuments?: number;
+    /** Write-ahead checkpoint batch size. Writes remain ordered within each batch. */
+    batchSize?: number;
+}
+
+export interface DataTaskVerifyRule {
+    mode?: 'sample' | 'full';
+    fields?: string[];
+    sampleSize?: number;
+}
+
+export interface DataTaskCollectionJob {
+    name: string;
+    targetName?: string;
+    indexes?: DataTaskIndexDefinition[];
+    data?: DataTaskDataRule;
+    verify?: DataTaskVerifyRule;
+}
+
+export interface DataTaskBackupOptions {
+    dir?: string;
+    format?: 'extended-jsonl';
+    compression?: 'gzip' | 'none';
+    retentionDays?: number;
+    /** Maximum uncompressed affected-scope backup size in bytes. Defaults to 256 MiB. */
+    maxBytes?: number;
+}
+
+export interface DataTaskLeaseLockOptions {
+    ttlMs?: number;
+    waitTimeoutMs?: number;
+}
+
+export interface DataTaskJob {
+    name: string;
+    description?: string;
+    source: DataTaskConnection;
+    target: DataTaskConnection;
+    targetEnvironment: DataTaskEnvironment;
+    collections: DataTaskCollectionJob[];
+    backup?: DataTaskBackupOptions;
+    lock?: boolean | DataTaskLeaseLockOptions;
+}
+
+export interface DataTaskApproval {
+    kind: 'apply' | 'restore';
+    token: string;
+    jobHash: string;
+    sourceHash: string;
+    targetHash: string;
+    indexHash: string;
+    issuedAt: string;
+    expiresAt: string;
+}
+
+export interface DataTaskIndexPlan {
+    name?: string;
+    key: Record<string, unknown>;
+    options: Record<string, unknown>;
+    status: 'existing' | 'missing' | 'conflict';
+    reason?: string;
+}
+
+export interface DataTaskChangeSample {
+    identity: Record<string, unknown>;
+    operation: 'insert' | 'update';
+    before: Record<string, unknown> | null;
+    after: Record<string, unknown>;
+}
+
+export interface DataTaskCollectionPreview {
+    source: string;
+    target: string;
+    data: {
+        source: number;
+        insert: number;
+        update: number;
+        unchanged: number;
+        conflict: number;
+    };
+    indexes: DataTaskIndexPlan[];
+    samples: DataTaskChangeSample[];
+    backupDocuments: number;
+    backupBytes: number;
+}
+
+export interface DataTaskPreviewResult {
+    mode: 'preview';
+    jobName: string;
+    passed: boolean;
+    collections: DataTaskCollectionPreview[];
+    warnings: string[];
+    errors: string[];
+    approval?: DataTaskApproval;
+}
+
+export interface DataTaskPreviewOptions {
+    approvalTtlMs?: number;
+    sampleSize?: number;
+}
+
+export interface DataTaskBackupRef {
+    runId: string;
+    manifestPath: string;
+    checksum: string;
+}
+
+export interface DataTaskApplyOptions {
+    approval: DataTaskApproval;
+}
+
+export interface DataTaskApplyResult {
+    mode: 'apply';
+    runId: string;
+    jobName: string;
+    passed: boolean;
+    status: 'passed' | 'partial' | 'failed';
+    collections: DataTaskCollectionPreview[];
+    backup: DataTaskBackupRef;
+    warnings: string[];
+    errors: string[];
+}
+
+export interface DataTaskRestoreTargetOptions {
+    target?: DataTaskConnection;
+}
+
+export interface DataTaskRestorePreviewResult {
+    mode: 'preview-restore';
+    runId: string;
+    passed: boolean;
+    restoreDocuments: number;
+    deleteDocuments: number;
+    dropIndexes: number;
+    createIndexes: number;
+    warnings: string[];
+    errors: string[];
+    approval?: DataTaskApproval;
+}
+
+export interface DataTaskRestoreOptions extends DataTaskRestoreTargetOptions {
+    approval: DataTaskApproval;
+}
+
+export interface DataTaskRestoreResult {
+    mode: 'restore';
+    runId: string;
+    passed: boolean;
+    status: 'passed' | 'partial' | 'failed';
+    safetyBackup: DataTaskBackupRef;
+    restoredDocuments: number;
+    deletedDocuments: number;
+    droppedIndexes: number;
+    createdIndexes: number;
+    warnings: string[];
+    errors: string[];
+}
+
+export interface DataTaskService {
+    preview(job: DataTaskJob, options?: DataTaskPreviewOptions): Promise<DataTaskPreviewResult>;
+    apply(job: DataTaskJob, options: DataTaskApplyOptions): Promise<DataTaskApplyResult>;
+    previewRestore(backup: DataTaskBackupRef, options?: DataTaskRestoreTargetOptions): Promise<DataTaskRestorePreviewResult>;
+    restore(backup: DataTaskBackupRef, options: DataTaskRestoreOptions): Promise<DataTaskRestoreResult>;
+}
+
+export declare const dataTasks: DataTaskService;

package/dist/types/index.d.mts

@@ -1,5 +1,6 @@
 export * from './base.mjs';
 export * from './collection.mjs';
+export * from './data-tasks.mjs';
 export * from './expression.mjs';
 export * from './lock.mjs';
 export * from './model.mjs';

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from './base';
 export * from './collection';
+export * from './data-tasks';
 export * from './expression';
 export * from './lock';
 export * from './model';

package/dist/types/lock.d.mts

@@ -50,14 +50,17 @@ export declare class Lock {
     getHoldTime(): number;
 }
 
-/** Manages distributed locks backed by the in-memory cache or a Redis store. */
+/**
+ * Manages legacy monSQLize locks backed by the in-memory cache or a Redis store.
+ * @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking.
+ */
 export declare class LockManager {
     constructor(options?: { logger?: unknown; lockKeyPrefix?: string; maxDuration?: number; });
-    /** Execute `callback` while holding the lock for `key`; the lock is released automatically on completion. */
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     withLock<T>(key: string, callback: () => Promise<T>, options?: LockOptions): Promise<T>;
-    /** Acquire the lock for `key`, blocking until available or timeout/retries are exhausted. */
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     acquireLock(key: string, options?: LockOptions): Promise<Lock>;
-    /** Try to acquire the lock for `key` without blocking; returns `null` if already held. */
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     tryAcquireLock(key: string, options?: Omit<LockOptions, 'retryTimes'>): Promise<Lock | null>;
     /** Return `true` if `key` is currently locked. */
     isLocked(key: string): boolean;

package/dist/types/lock.d.ts

@@ -50,14 +50,17 @@ export declare class Lock {
     getHoldTime(): number;
 }
 
-/** Manages distributed locks backed by the in-memory cache or a Redis store. */
+/**
+ * Manages legacy monSQLize locks backed by the in-memory cache or a Redis store.
+ * @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking.
+ */
 export declare class LockManager {
     constructor(options?: { logger?: unknown; lockKeyPrefix?: string; maxDuration?: number; });
-    /** Execute `callback` while holding the lock for `key`; the lock is released automatically on completion. */
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     withLock<T>(key: string, callback: () => Promise<T>, options?: LockOptions): Promise<T>;
-    /** Acquire the lock for `key`, blocking until available or timeout/retries are exhausted. */
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     acquireLock(key: string, options?: LockOptions): Promise<Lock>;
-    /** Try to acquire the lock for `key` without blocking; returns `null` if already held. */
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     tryAcquireLock(key: string, options?: Omit<LockOptions, 'retryTimes'>): Promise<Lock | null>;
     /** Return `true` if `key` is currently locked. */
     isLocked(key: string): boolean;

package/dist/types/model.d.mts

@@ -1,11 +1,16 @@
 import type { BookmarkClearResult, BookmarkListResult, BookmarkPrewarmResult, DeleteBatchResult, DeleteResult, IncrementOneResult, IndexCreateResult, InsertBatchResult, InsertManyResult, InsertOneResult, UpdateBatchResult, UpdateResult } from './collection.mjs';
+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/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.