monsqlize 2.0.5 → 2.0.6

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,50 @@ export interface MetaOptions {
     includeCache?: boolean;
 }
 
+/** v1-compatible find options exported from the root package. */
+export interface FindOptions {
+    projection?: 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. */
@@ -213,7 +257,7 @@ 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;
+    options?: MongoFindOptions;
     /** Cursor-walking bookmark jump configuration */
     jump?: JumpOptions;
     /** Offset-based fallback for small page ranges */

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,23 @@
+export * from './base.mjs';
+export * from './collection.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/lock.d.mts

@@ -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;
+}