monsqlize 2.0.5 → 3.0.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/expression.d.mts

@@ -0,0 +1,115 @@
+/**
+ * Unified expression operator type definitions.
+ * @module types/expression
+ * @since v1.0.9
+ */
+
+/**
+ * All 122 expression operators supported by the MonSQLize expression system
+ * (100% MongoDB coverage).
+ *
+ * @since v1.0.9
+ */
+export namespace UnifiedExpressionOperators {
+    /** Ternary conditional operator. */
+    export type TernaryOperator = '? :';
+
+    /** Nullish coalescing operator. */
+    export type NullishCoalescing = '??';
+
+    /** Comparison operators. */
+    export type ComparisonOperators = '>' | '>=' | '<' | '<=' | '===' | '!==';
+
+    /** Logical operators. */
+    export type LogicalOperators = '&&' | '||' | 'NOT';
+
+    /** Arithmetic operators. */
+    export type ArithmeticOperators = '+' | '-' | '*' | '/' | '%';
+
+    /** Math functions (8). */
+    export type MathFunctions = 'ABS' | 'CEIL' | 'FLOOR' | 'ROUND' | 'SQRT' | 'POW' | 'LOG' | 'LOG10';
+
+    /** Basic string functions (12). */
+    export type StringBasicFunctions =
+        | 'CONCAT' | 'UPPER' | 'LOWER' | 'TRIM' | 'SUBSTR' | 'LENGTH'
+        | 'SPLIT' | 'REPLACE' | 'INDEX_OF_STR' | 'LTRIM' | 'RTRIM' | 'SUBSTR_CP';
+
+    /** Extended string functions (3). @since v1.1.0 */
+    export type StringExtendedFunctions = 'STR_LEN_BYTES' | 'STR_LEN_CP' | 'SUBSTR_BYTES';
+
+    /** Basic array functions (10). */
+    export type ArrayBasicFunctions =
+        | 'SIZE' | 'ARRAY_ELEM_AT' | 'IN' | 'SLICE' | 'FIRST' | 'LAST'
+        | 'FILTER' | 'MAP' | 'INDEX_OF' | 'CONCAT_ARRAYS';
+
+    /** Extended array functions (4). @since v1.1.0 */
+    export type ArrayExtendedFunctions = 'REDUCE' | 'ZIP' | 'REVERSE_ARRAY' | 'RANGE';
+
+    /** Basic date functions (6). */
+    export type DateBasicFunctions = 'YEAR' | 'MONTH' | 'DAY_OF_MONTH' | 'HOUR' | 'MINUTE' | 'SECOND';
+
+    /** Advanced date functions (5). @since v1.1.0 */
+    export type DateAdvancedFunctions =
+        | 'DATE_ADD' | 'DATE_SUBTRACT' | 'DATE_DIFF' | 'DATE_TO_STRING' | 'DATE_FROM_STRING';
+
+    /** Extended date functions (8). @since v1.1.0 */
+    export type DateExtendedFunctions =
+        | 'DATE_FROM_PARTS' | 'DATE_TO_PARTS' | 'ISO_WEEK' | 'ISO_WEEK_YEAR'
+        | 'ISO_DAY_OF_WEEK' | 'DAY_OF_WEEK' | 'DAY_OF_YEAR' | 'WEEK';
+
+    /** Type inspection functions (5). */
+    export type TypeCheckFunctions = 'TYPE' | 'IS_NUMBER' | 'IS_ARRAY' | 'EXISTS' | 'NOT';
+
+    /** Basic type conversion functions. */
+    export type TypeConversionBasicFunctions = 'TO_INT' | 'TO_STRING' | 'OBJECT_TO_ARRAY' | 'ARRAY_TO_OBJECT';
+
+    /** Extended type conversion functions (7). @since v1.1.0 */
+    export type TypeConversionExtendedFunctions =
+        | 'TO_BOOL' | 'TO_DATE' | 'TO_DOUBLE' | 'TO_DECIMAL'
+        | 'TO_LONG' | 'TO_OBJECT_ID' | 'CONVERT';
+
+    /** Logical extended functions (2). @since v1.1.0 */
+    export type LogicalExtendedFunctions = 'ALL_ELEMENTS_TRUE' | 'ANY_ELEMENT_TRUE';
+
+    /** Conditional functions (3). */
+    export type ConditionalFunctions = 'SWITCH' | 'COND' | 'IF_NULL';
+
+    /** Object manipulation functions (5). */
+    export type ObjectOperationFunctions =
+        | 'MERGE_OBJECTS' | 'SET_FIELD' | 'UNSET_FIELD' | 'GET_FIELD' | 'OBJECT_TO_ARRAY';
+
+    /** Set operation functions (5). */
+    export type SetOperationFunctions =
+        | 'SET_UNION' | 'SET_DIFFERENCE' | 'SET_EQUALS' | 'SET_INTERSECTION' | 'SET_IS_SUBSET';
+
+    /** Advanced operation functions (5). @since v1.1.0 */
+    export type AdvancedOperationFunctions = 'LET' | 'LITERAL' | 'RAND' | 'SAMPLE_RATE' | 'REGEX';
+
+    /** Aggregate accumulator functions (7). */
+    export type AggregateFunctions = 'SUM' | 'AVG' | 'MAX' | 'MIN' | 'COUNT' | 'PUSH' | 'ADD_TO_SET';
+
+    /** Union of all supported operator strings. */
+    export type AllOperators =
+        | TernaryOperator
+        | NullishCoalescing
+        | ComparisonOperators
+        | LogicalOperators
+        | ArithmeticOperators
+        | MathFunctions
+        | StringBasicFunctions
+        | StringExtendedFunctions
+        | ArrayBasicFunctions
+        | ArrayExtendedFunctions
+        | DateBasicFunctions
+        | DateAdvancedFunctions
+        | DateExtendedFunctions
+        | TypeCheckFunctions
+        | TypeConversionBasicFunctions
+        | TypeConversionExtendedFunctions
+        | LogicalExtendedFunctions
+        | ConditionalFunctions
+        | ObjectOperationFunctions
+        | SetOperationFunctions
+        | AdvancedOperationFunctions
+        | AggregateFunctions;
+}

package/dist/types/index.d.mts

@@ -0,0 +1,24 @@
+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';
+export * from './mongodb.mjs';
+export * from './pool.mjs';
+export * from './runtime.mjs';
+export * from './saga.mjs';
+export * from './slow-query-log.mjs';
+export * from './sync.mjs';
+export * from './transaction.mjs';
+export * from './monsqlize.mjs';
+
+export { default, MonSQLize } from './monsqlize.mjs';
+export { Model, generateQueryHash, validateSyncConfig } from './runtime.mjs';
+
+export type { Lock as LockContract } from './lock.mjs';
+export type { ModelInstance as ModelAccessor, ModelInstance } from './model.mjs';
+export type { SyncTargetConfig as SyncTarget } from './sync.mjs';
+export type { Transaction as TransactionContract } from './transaction.mjs';
+export type { MonSQLizeOptions as BaseOptions } from './monsqlize.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

@@ -0,0 +1,77 @@
+/** Options for acquiring or configuring a distributed lock. */
+export interface LockOptions {
+    /** Lock TTL in milliseconds; the lock auto-releases after this duration. */
+    ttl?: number;
+    /** Number of retry attempts on acquire failure. */
+    retryTimes?: number;
+    /** Base delay between retries in milliseconds. */
+    retryDelay?: number;
+    /** Backoff multiplier applied to `retryDelay` on each successive retry. */
+    retryBackoff?: number;
+    /** When `true`, the callback is executed without a lock if acquisition fails (no-lock fallback). */
+    fallbackToNoLock?: boolean;
+}
+
+/** Aggregate statistics for a `LockManager` instance. */
+export interface LockStats {
+    locksAcquired: number;
+    locksReleased: number;
+    lockChecks: number;
+    errors: number;
+    lockKeyPrefix: string;
+    maxDuration: number;
+    activeLocks: number;
+}
+
+/** Thrown when a lock cannot be acquired after all retry attempts are exhausted. */
+export declare class LockAcquireError extends Error {
+    readonly code: 'LOCK_ACQUIRE_FAILED';
+}
+
+/** Thrown when a lock acquisition attempt times out. */
+export declare class LockTimeoutError extends Error {
+    readonly code: 'LOCK_TIMEOUT';
+}
+
+/** Represents an acquired distributed lock; call `release()` to free it. */
+export declare class Lock {
+    readonly key: string;
+    readonly lockId: string;
+    readonly ttl: number;
+    /** `true` after the lock has been released. v1 compat — exposed as readonly to prevent external mutation. */
+    readonly released: boolean;
+    /** Release the lock; returns `true` on success. */
+    release(): Promise<boolean>;
+    /** Extend the lock's TTL; returns `true` on success. */
+    renew(ttl?: number): Promise<boolean>;
+    /** Return `true` if the lock is still held (not yet released or expired). */
+    isHeld(): boolean;
+    /** Return the elapsed hold time in milliseconds since the lock was acquired. */
+    getHoldTime(): number;
+}
+
+/**
+ * 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; });
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
+    withLock<T>(key: string, callback: () => Promise<T>, options?: LockOptions): Promise<T>;
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
+    acquireLock(key: string, options?: LockOptions): Promise<Lock>;
+    /** @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;
+    /** Release the lock identified by `key` + `lockId`. */
+    releaseLock(key: string, lockId: string): Promise<boolean>;
+    /** Extend the TTL for the lock identified by `key` + `lockId`. */
+    renewLock(key: string, lockId: string, ttl: number): Promise<boolean>;
+    /** Return aggregate lock statistics. */
+    getStats(): LockStats;
+    /** Clear all active locks immediately. */
+    clear(): void;
+    /** Shut down the lock manager and release internal resources. */
+    close(): void;
+}

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;