monsqlize 1.3.1 → 2.0.0

package/dist/types/expression.d.ts

@@ -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.ts

@@ -0,0 +1,23 @@
+export * from './base';
+export * from './collection';
+export * from './expression';
+export * from './lock';
+export * from './model';
+export * from './mongodb';
+export * from './pool';
+export * from './runtime';
+export * from './saga';
+export * from './slow-query-log';
+export * from './sync';
+export * from './transaction';
+export * from './monsqlize';
+
+export { default, MonSQLize } from './monsqlize';
+export { Model, generateQueryHash, validateSyncConfig } from './runtime';
+
+export type { Lock as LockContract } from './lock';
+export type { ModelInstance as ModelAccessor, ModelInstance } from './model';
+export type { SyncTargetConfig as SyncTarget } from './sync';
+export type { Transaction as TransactionContract } from './transaction';
+export type { MonSQLizeOptions as BaseOptions } from './monsqlize';
+

package/dist/types/lock.d.ts

@@ -0,0 +1,74 @@
+/** 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 distributed locks backed by the in-memory cache or a Redis store. */
+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. */
+    withLock<T>(key: string, callback: () => Promise<T>, options?: LockOptions): Promise<T>;
+    /** Acquire the lock for `key`, blocking until available or timeout/retries are exhausted. */
+    acquireLock(key: string, options?: LockOptions): Promise<Lock>;
+    /** Try to acquire the lock for `key` without blocking; returns `null` if already held. */
+    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;
+}