monsqlize 2.0.5 → 3.0.0

package/dist/types/collection.d.ts

@@ -1,4 +1,4 @@
-import type { ChangeStream, Document, FindOptions, Sort } from 'mongodb';
+import type { ChangeStream, Document, FindOptions as MongoFindOptions, Sort } from 'mongodb';
 
 /** Meta options for controlling timing/cache info in query results. */
 export interface MetaOptions {
@@ -8,6 +8,105 @@ export interface MetaOptions {
     includeCache?: boolean;
 }
 
+export type CacheInvalidationOperation =
+    | 'find'
+    | 'findOne'
+    | 'count'
+    | 'findPage'
+    | 'aggregate'
+    | 'distinct'
+    | 'findOneById'
+    | 'findByIds'
+    | 'all';
+
+export type CacheInvalidationEntry =
+    | string
+    | {
+        /** Exact cache key to delete. */
+        cacheKey?: string;
+        /** Exact cache keys to delete. */
+        cacheKeys?: string[];
+        /** Cache pattern to delete with delPattern(). */
+        pattern?: string;
+        /** Cache patterns to delete with delPattern(). */
+        patterns?: string[];
+        /** Read operation to invalidate. Add query/options for exact key invalidation. */
+        operation?: CacheInvalidationOperation | string;
+        /** Alias for operation. */
+        op?: CacheInvalidationOperation | string;
+        query?: unknown;
+        options?: unknown;
+        pipeline?: unknown[];
+        /** Field name for distinct invalidation descriptors. */
+        field?: string;
+        /** ID for findOneById invalidation descriptors. */
+        id?: unknown;
+        /** IDs for findByIds invalidation descriptors. */
+        ids?: unknown[];
+    };
+
+export type CacheInvalidationRequest = CacheInvalidationEntry | CacheInvalidationEntry[];
+
+export interface WriteCacheControlOptions {
+    cache?: {
+        /**
+         * Explicit invalidation for this write. `false` or `[]` means no invalidation for
+         * this write, even when instance-level cache.autoInvalidate is enabled.
+         */
+        invalidate?: false | true | CacheInvalidationRequest;
+        /** Per-write broad invalidation shortcut. Prefer invalidate for precise entries. */
+        autoInvalidate?: boolean;
+    };
+    /** Per-write broad invalidation shortcut kept for compatibility. */
+    autoInvalidate?: boolean;
+}
+
+/** v1-compatible find options exported from the root package. */
+export interface FindOptions {
+    projection?: Record<string, any> | string[];
+    /** Alias for `projection`; `projection` wins when both are provided. */
+    project?: Record<string, any> | string[];
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    skip?: number;
+    cache?: number;
+    maxTimeMS?: number;
+    hint?: any;
+    collation?: any;
+    comment?: string;
+    meta?: boolean | MetaOptions;
+}
+
+/** v1-compatible count options exported from the root package. */
+export interface CountOptions {
+    cache?: number;
+    maxTimeMS?: number;
+    hint?: any;
+    collation?: any;
+    comment?: string;
+    meta?: boolean | MetaOptions;
+}
+
+/** v1-compatible aggregate options exported from the root package. */
+export interface AggregateOptions {
+    cache?: number;
+    maxTimeMS?: number;
+    allowDiskUse?: boolean;
+    collation?: any;
+    hint?: string | object;
+    comment?: string;
+    meta?: boolean | MetaOptions;
+}
+
+/** v1-compatible distinct options exported from the root package. */
+export interface DistinctOptions {
+    cache?: number;
+    maxTimeMS?: number;
+    collation?: any;
+    hint?: string | object;
+    meta?: boolean | MetaOptions;
+}
+
 /** Query options that request the v1 `{ data, meta }` wrapper. */
 export interface QueryMetaOption extends Record<string, unknown> {
     /** Include operation timing metadata in the resolved query result. */
@@ -113,6 +212,8 @@ export interface TotalsOptions {
 /** Stream query options for collection.stream(). */
 export interface StreamOptions {
     projection?: Record<string, unknown> | string[];
+    /** Alias for `projection`; `projection` wins when both are provided. */
+    project?: Record<string, unknown> | string[];
     sort?: Record<string, 1 | -1>;
     limit?: number;
     skip?: number;
@@ -127,6 +228,8 @@ export interface StreamOptions {
 /** Explain/query plan options for collection.explain(). */
 export interface ExplainOptions {
     projection?: Record<string, unknown>;
+    /** Alias for `projection`; `projection` wins when both are provided. */
+    project?: Record<string, unknown>;
     sort?: Record<string, 1 | -1>;
     limit?: number;
     skip?: number;
@@ -169,9 +272,11 @@ export interface HealthView {
     status: 'up' | 'down';
     connected: boolean;
     /** @since v1 — driver connection state alias */
-    driver?: { connected: boolean };
+    driver?: { connected: boolean; error?: string };
     defaults?: Record<string, unknown>;
     cache?: Record<string, unknown>;
+    checks?: Record<string, Record<string, unknown> & { status: 'up' | 'down' | 'unknown' }>;
+    capabilities?: Record<string, unknown>;
 }
 
 export interface InsertOneResult {
@@ -198,6 +303,10 @@ export interface DeleteResult {
     deletedCount: number;
 }
 
+export type CursorValueType = 'date' | 'objectId' | 'string' | 'number' | 'boolean' | 'raw';
+
+export type CursorValueNormalizer = (field: string, value: unknown) => unknown;
+
 export interface FindPageOptions<TSchema = any> {
     query?: Document;
     page?: number;
@@ -205,7 +314,9 @@ export interface FindPageOptions<TSchema = any> {
     after?: string;
     before?: string;
     sort?: Sort;
-    projection?: Document;
+    projection?: Document | string[];
+    /** Alias for `projection`; `projection` wins when both are provided. */
+    project?: Document | string[];
     pipeline?: Document[];
     /** Totals/count configuration */
     totals?: TotalsOptions;
@@ -213,7 +324,11 @@ export interface FindPageOptions<TSchema = any> {
     explain?: boolean | string;
     /** Query comment for server-side profiling. v1 compat — top-level shortcut for `options.comment`. */
     comment?: string;
-    options?: FindOptions;
+    /** Cursor value type hints used when decoding after/before tokens. Keeps ISO-like string fields as strings when set to `string` or `raw`. */
+    cursorTypes?: Record<string, CursorValueType>;
+    /** Custom cursor value normalizer. Receives the sort field name and decoded cursor value. */
+    cursorValueNormalizer?: CursorValueNormalizer;
+    options?: MongoFindOptions;
     /** Cursor-walking bookmark jump configuration */
     jump?: JumpOptions;
     /** Offset-based fallback for small page ranges */
@@ -388,12 +503,16 @@ export interface UpdateBatchResult {
     totalCount: number | null;
     matchedCount: number;
     modifiedCount: number;
-    /** Number of documents upserted across all batches. */
+    /** Always 0; updateBatch rejects `upsert: true` before executing batch writes. */
     upsertedCount: number;
     batchCount: number;
     errors: BatchErrorRecord[];
     /** Per-batch retry records. */
     retries: BatchRetryRecord[];
+    /** Number of documents skipped by strict model version conflict handling. */
+    conflictCount?: number;
+    /** Document ids skipped by strict model version conflict handling. */
+    conflictedIds?: unknown[];
 }
 
 export interface DeleteBatchResult {
@@ -406,7 +525,7 @@ export interface DeleteBatchResult {
     retries: BatchRetryRecord[];
 }
 
-export interface BatchWriteOptions {
+export interface BatchWriteOptions extends WriteCacheControlOptions {
     batchSize?: number;
     ordered?: boolean;
     concurrency?: number;
@@ -418,7 +537,7 @@ export interface BatchWriteOptions {
 }
 
 /** Options for updateBatch operations. */
-export interface UpdateBatchOptions {
+export interface UpdateBatchOptions extends WriteCacheControlOptions {
     /** Number of documents per batch (default: 1000). */
     batchSize?: number;
     /** Estimate total for progress reporting. */
@@ -435,7 +554,11 @@ export interface UpdateBatchOptions {
     onRetry?: (retryInfo: RetryInfo) => void;
     /** MongoDB write concern. */
     writeConcern?: WriteConcern;
-    /** Upsert documents that do not match the filter. */
+    /**
+     * @deprecated `updateBatch` does not support `upsert: true`; use `upsertOne` for
+     * single-document upserts, or `updateMany(..., { upsert: true })` only when you
+     * want MongoDB's native single-insert-on-no-match semantics. Passing `true` throws.
+     */
     upsert?: boolean;
     /** Array filters for nested array updates. */
     arrayFilters?: unknown[];
@@ -445,7 +568,7 @@ export interface UpdateBatchOptions {
     sort?: Record<string, 1 | -1>;
 }
 
-export interface IncrementOneOptions extends Record<string, unknown> {
+export interface IncrementOneOptions extends WriteCacheControlOptions, Record<string, unknown> {
     returnDocument?: 'before' | 'after';
     projection?: Record<string, unknown>;
     $set?: Record<string, unknown>;
@@ -569,7 +692,7 @@ export interface AdminAccessor {
 
 export interface Collection<TSchema = any> {
     /** Returns the namespace descriptor (iid, db, collection) for this collection. */
-    getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; };
+    getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; pool?: string; };
     /** Returns the underlying native MongoDB Collection object. */
     raw(): unknown;
     /**
@@ -739,7 +862,7 @@ export interface Collection<TSchema = any> {
      * Updates matched documents in configurable batches, walking via a cursor.
      * @param filter - MongoDB filter query.
      * @param update - Update operators.
-     * @param options - UpdateBatchOptions (batchSize, upsert, onProgress, …).
+     * @param options - UpdateBatchOptions (batchSize, onProgress, retry settings; `upsert: true` is rejected).
      * @returns Aggregated update result across all batches.
      * @since v1.2.0
      */
@@ -947,12 +1070,12 @@ export type ClearBookmarksResult = BookmarkClearResult;
 // ---------------------------------------------------------------------------
 
 /** Simplified insertOne options (used for the shorthand call form). */
-export interface InsertOneSimplifiedOptions {
+export interface InsertOneSimplifiedOptions extends WriteCacheControlOptions {
     writeConcern?: WriteConcern;
     bypassDocumentValidation?: boolean;
     comment?: string;
     session?: unknown;
-    /** Invalidate query cache on success. @since v1.1.5 */
+    /** Broadly invalidate query cache on success. Prefer `cache.invalidate` for precise entries. */
     autoInvalidate?: boolean;
 }
 
@@ -965,13 +1088,13 @@ export interface InsertOneOptions {
 }
 
 /** Simplified insertMany options (used for the shorthand call form). */
-export interface InsertManySimplifiedOptions {
+export interface InsertManySimplifiedOptions extends WriteCacheControlOptions {
     ordered?: boolean;
     writeConcern?: WriteConcern;
     bypassDocumentValidation?: boolean;
     comment?: string;
     session?: unknown;
-    /** Invalidate query cache on success. @since v1.1.5 */
+    /** Broadly invalidate query cache on success. Prefer `cache.invalidate` for precise entries. */
     autoInvalidate?: boolean;
 }
 

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

@@ -0,0 +1,221 @@
+import type { MonSQLizeOptions } from './monsqlize.mjs';
+
+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;