flongo 1.0.2 → 1.2.0

package/dist/cache/memoryCache.d.ts

@@ -0,0 +1,39 @@
+import { BaseCacheStore, CacheStoreOptions } from './cacheStore';
+export interface MemoryCacheOptions extends CacheStoreOptions {
+    checkInterval?: number;
+    maxMemoryMB?: number;
+}
+export declare class MemoryCache<T> extends BaseCacheStore<T> {
+    private cache;
+    private lruOrder;
+    private cleanupInterval?;
+    private readonly memoryOptions;
+    private readonly locks;
+    private capacityLock;
+    constructor(options?: MemoryCacheOptions);
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    size(): Promise<number>;
+    keys(): Promise<string[]>;
+    getMemoryUsage(): Promise<number>;
+    destroy(): void;
+    private isExpired;
+    private updateLRU;
+    private removeLRU;
+    private ensureCapacity;
+    private checkMemoryLimit;
+    private estimateSize;
+    private startCleanupInterval;
+    private cleanupExpired;
+    private acquireLock;
+    private createLockPromise;
+    private releaseLock;
+    private waitForLock;
+    private acquireCapacityLock;
+    private releaseCapacityLock;
+    private waitForCapacityLock;
+}
+//# sourceMappingURL=memoryCache.d.ts.map

package/dist/cache/memoryCache.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCache = void 0;
+const cacheStore_1 = require("./cacheStore");
+class MemoryCache extends cacheStore_1.BaseCacheStore {
+    constructor(options = {}) {
+        super(options);
+        this.capacityLock = null;
+        this.cache = new Map();
+        this.lruOrder = [];
+        this.locks = new Map();
+        this.memoryOptions = {
+            ...this.options,
+            checkInterval: options.checkInterval ?? 60000,
+            maxMemoryMB: options.maxMemoryMB ?? 100
+        };
+        if (this.memoryOptions.checkInterval > 0) {
+            this.startCleanupInterval();
+        }
+    }
+    async get(key) {
+        await this.waitForLock(key);
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.incrementStat('misses');
+            return undefined;
+        }
+        if (this.isExpired(entry)) {
+            await this.delete(key);
+            this.incrementStat('misses');
+            return undefined;
+        }
+        this.updateLRU(key);
+        entry.lastAccessedAt = Date.now();
+        entry.accessCount++;
+        this.incrementStat('hits');
+        return entry.value;
+    }
+    async set(key, value, ttlSeconds) {
+        // Acquire capacity lock for eviction check
+        await this.waitForCapacityLock();
+        const capacityLock = this.acquireCapacityLock();
+        try {
+            await capacityLock;
+            // Check and ensure capacity with global lock
+            await this.checkMemoryLimit();
+            await this.ensureCapacity();
+        }
+        finally {
+            this.releaseCapacityLock();
+        }
+        // Now acquire key-specific lock for the actual set
+        const lock = this.acquireLock(key);
+        try {
+            await lock;
+            const ttl = ttlSeconds ?? this.options.defaultTTL;
+            const now = Date.now();
+            const entry = {
+                value,
+                ttl: ttl > 0 ? ttl * 1000 : undefined,
+                createdAt: now,
+                lastAccessedAt: now,
+                accessCount: 0
+            };
+            this.cache.set(key, entry);
+            this.updateLRU(key);
+            this.incrementStat('sets');
+        }
+        finally {
+            this.releaseLock(key);
+        }
+    }
+    async delete(key) {
+        const lock = this.acquireLock(key);
+        try {
+            await lock;
+            const existed = this.cache.has(key);
+            if (existed) {
+                const entry = this.cache.get(key);
+                this.cache.delete(key);
+                this.removeLRU(key);
+                this.incrementStat('deletes');
+                if (entry && this.options.onEviction) {
+                    this.options.onEviction(key, entry.value);
+                }
+            }
+            return existed;
+        }
+        finally {
+            this.releaseLock(key);
+        }
+    }
+    async clear() {
+        const keys = Array.from(this.cache.keys());
+        for (const key of keys) {
+            await this.waitForLock(key);
+        }
+        this.cache.clear();
+        this.lruOrder = [];
+        this.incrementStat('clears');
+    }
+    async has(key) {
+        await this.waitForLock(key);
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        if (this.isExpired(entry)) {
+            await this.delete(key);
+            return false;
+        }
+        return true;
+    }
+    async size() {
+        return this.cache.size;
+    }
+    async keys() {
+        const validKeys = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (!this.isExpired(entry)) {
+                validKeys.push(key);
+            }
+        }
+        return validKeys;
+    }
+    async getMemoryUsage() {
+        let totalSize = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            totalSize += this.estimateSize(key, entry);
+        }
+        return totalSize;
+    }
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = undefined;
+        }
+        this.cache.clear();
+        this.lruOrder = [];
+        this.locks.clear();
+    }
+    isExpired(entry) {
+        if (!entry.ttl) {
+            return false;
+        }
+        return Date.now() - entry.createdAt > entry.ttl;
+    }
+    updateLRU(key) {
+        const index = this.lruOrder.indexOf(key);
+        if (index > -1) {
+            this.lruOrder.splice(index, 1);
+        }
+        this.lruOrder.push(key);
+    }
+    removeLRU(key) {
+        const index = this.lruOrder.indexOf(key);
+        if (index > -1) {
+            this.lruOrder.splice(index, 1);
+        }
+    }
+    async ensureCapacity() {
+        // Need to ensure we have room for one more entry
+        if (this.cache.size >= this.options.maxEntries && this.lruOrder.length > 0) {
+            // Batch evict to make room
+            const entriesToEvict = Math.max(1, this.cache.size - this.options.maxEntries + 1);
+            const keysToEvict = this.lruOrder.slice(0, Math.min(entriesToEvict, this.lruOrder.length));
+            // Batch delete without recursion
+            for (const key of keysToEvict) {
+                const entry = this.cache.get(key);
+                if (entry) {
+                    this.cache.delete(key);
+                    this.removeLRU(key);
+                    this.incrementStat('evictions');
+                    this.incrementStat('deletes');
+                    if (this.options.onEviction) {
+                        this.options.onEviction(key, entry.value);
+                    }
+                }
+            }
+        }
+    }
+    async checkMemoryLimit() {
+        const memoryUsageMB = (await this.getMemoryUsage()) / (1024 * 1024);
+        if (memoryUsageMB > this.memoryOptions.maxMemoryMB && this.lruOrder.length > 0) {
+            // Calculate how many entries to evict (at least 10% of cache or 1 entry)
+            const entriesToEvict = Math.max(1, Math.ceil(this.cache.size * 0.1));
+            const keysToEvict = this.lruOrder.slice(0, Math.min(entriesToEvict, this.lruOrder.length));
+            for (const key of keysToEvict) {
+                await this.delete(key);
+                this.incrementStat('evictions');
+            }
+        }
+    }
+    estimateSize(key, entry) {
+        let size = key.length * 2;
+        size += 8 * 4;
+        const value = entry.value;
+        if (value === null || value === undefined) {
+            return size;
+        }
+        if (typeof value === 'string') {
+            size += value.length * 2;
+        }
+        else if (typeof value === 'number') {
+            size += 8;
+        }
+        else if (typeof value === 'boolean') {
+            size += 4;
+        }
+        else if (typeof value === 'object') {
+            try {
+                size += JSON.stringify(value).length * 2;
+            }
+            catch (error) {
+                // Handle circular references or other JSON errors
+                // Estimate size based on object key count
+                if (error instanceof Error && error.message.includes('circular')) {
+                    const keys = Object.keys(value).length;
+                    size += keys * 50; // Rough estimate: 50 bytes per key
+                }
+                else {
+                    size += 1024; // Default fallback
+                }
+            }
+        }
+        return size;
+    }
+    startCleanupInterval() {
+        this.cleanupInterval = setInterval(async () => {
+            await this.cleanupExpired();
+        }, this.memoryOptions.checkInterval);
+        if (this.cleanupInterval.unref) {
+            this.cleanupInterval.unref();
+        }
+    }
+    async cleanupExpired() {
+        const keysToDelete = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (this.isExpired(entry)) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            await this.delete(key);
+        }
+    }
+    acquireLock(key) {
+        const existingLock = this.locks.get(key);
+        if (existingLock) {
+            const newLock = existingLock.then(() => this.createLockPromise());
+            this.locks.set(key, newLock);
+            return newLock;
+        }
+        const lock = this.createLockPromise();
+        this.locks.set(key, lock);
+        return lock;
+    }
+    // Simple async lock for Node.js single-threaded environment
+    // Note: Node.js JavaScript execution is single-threaded
+    createLockPromise() {
+        return new Promise(resolve => {
+            // Use nextTick for immediate execution in next iteration
+            process.nextTick(resolve);
+        });
+    }
+    releaseLock(key) {
+        this.locks.delete(key);
+    }
+    async waitForLock(key) {
+        const lock = this.locks.get(key);
+        if (lock) {
+            await lock;
+        }
+    }
+    acquireCapacityLock() {
+        if (this.capacityLock) {
+            const newLock = this.capacityLock.then(() => this.createLockPromise());
+            this.capacityLock = newLock;
+            return newLock;
+        }
+        const lock = this.createLockPromise();
+        this.capacityLock = lock;
+        return lock;
+    }
+    releaseCapacityLock() {
+        this.capacityLock = null;
+    }
+    async waitForCapacityLock() {
+        if (this.capacityLock) {
+            await this.capacityLock;
+        }
+    }
+}
+exports.MemoryCache = MemoryCache;
+//# sourceMappingURL=memoryCache.js.map

package/dist/flongoQuery.d.ts

@@ -123,6 +123,34 @@ export declare class FlongoQuery implements ICollectionQuery {
      * @returns This query instance for chaining
      */
     arrContainsAny(val?: any[]): FlongoQuery;
+    /**
+     * Matches array elements that satisfy all specified conditions.
+     * Use this to query objects within arrays by their properties.
+     *
+     * @example
+     * // Find users with a contextRole where orgId is 'org1'
+     * query.where('contextRoles').elemMatch({ orgId: 'org1' })
+     *
+     * @example
+     * // Find users with a contextRole where orgId is 'org1' AND role is 'admin'
+     * query.where('contextRoles').elemMatch({ orgId: 'org1', role: 'admin' })
+     *
+     * @example
+     * // Using fluent API for conditions (supports all FlongoQuery operators)
+     * query.where('contextRoles').elemMatch(
+     *   new FlongoQuery().where('orgId').eq('org1').and('role').eq('admin')
+     * )
+     *
+     * @example
+     * // Using comparison operators
+     * query.where('scores').elemMatch(
+     *   new FlongoQuery().where('value').gtEq(80).and('subject').eq('math')
+     * )
+     *
+     * @param conditions - Object with field/value pairs or a FlongoQuery instance
+     * @returns This query instance for chaining
+     */
+    elemMatch(conditions?: Record<string, any> | FlongoQuery): FlongoQuery;
     /**
      * Adds case-insensitive string starts-with constraint
      * @param val - String prefix to match

package/dist/flongoQuery.js

@@ -175,6 +175,36 @@ class FlongoQuery {
     arrContainsAny(val) {
         return val?.length ? this.set("$in", val) : this.handleEmptyValue();
     }
+    /**
+     * Matches array elements that satisfy all specified conditions.
+     * Use this to query objects within arrays by their properties.
+     *
+     * @example
+     * // Find users with a contextRole where orgId is 'org1'
+     * query.where('contextRoles').elemMatch({ orgId: 'org1' })
+     *
+     * @example
+     * // Find users with a contextRole where orgId is 'org1' AND role is 'admin'
+     * query.where('contextRoles').elemMatch({ orgId: 'org1', role: 'admin' })
+     *
+     * @example
+     * // Using fluent API for conditions (supports all FlongoQuery operators)
+     * query.where('contextRoles').elemMatch(
+     *   new FlongoQuery().where('orgId').eq('org1').and('role').eq('admin')
+     * )
+     *
+     * @example
+     * // Using comparison operators
+     * query.where('scores').elemMatch(
+     *   new FlongoQuery().where('value').gtEq(80).and('subject').eq('math')
+     * )
+     *
+     * @param conditions - Object with field/value pairs or a FlongoQuery instance
+     * @returns This query instance for chaining
+     */
+    elemMatch(conditions) {
+        return this.set("$elemMatch", conditions);
+    }
     // ===========================================
     // STRING OPERATORS
     // ===========================================
@@ -366,11 +396,25 @@ class FlongoQuery {
                         break; // _id queries are typically exclusive
                     }
                     // Build query object for non-_id fields
-                    const fieldValue = expression.op
-                        ? expression.op === "$regex"
-                            ? { [expression.op]: expression.val, ["$options"]: "i" } // Case-insensitive regex
-                            : { [expression.op]: expression.val }
-                        : expression.val; // Direct value assignment for simple equality
+                    let fieldValue;
+                    if (!expression.op) {
+                        // Direct value assignment for simple equality (arrContains)
+                        fieldValue = expression.val;
+                    }
+                    else if (expression.op === "$regex") {
+                        // Case-insensitive regex
+                        fieldValue = { [expression.op]: expression.val, ["$options"]: "i" };
+                    }
+                    else if (expression.op === "$elemMatch") {
+                        // Handle FlongoQuery or raw object for $elemMatch
+                        fieldValue = {
+                            [expression.op]: expression.val instanceof FlongoQuery ? expression.val.build() : expression.val
+                        };
+                    }
+                    else {
+                        // Standard operator
+                        fieldValue = { [expression.op]: expression.val };
+                    }
                     // Merge operators for the same field (e.g., range queries)
                     if (mongodbQuery[expression.key] &&
                         typeof mongodbQuery[expression.key] === "object" &&

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export { FlongoCollection, FlongoCollectionOptions } from "./flongoCollection";
 export { FlongoQuery, FlongoQueryBuilder } from "./flongoQuery";
 export { initializeFlongo, FlongoConfig, flongoClient, flongoDb } from "./flongo";
 export { Error404, Error400 } from "./errors";
-export { Entity, DbRecord, Pagination, Coordinates, Bounds, Event, EventName, EventRecord, Logic, SortDirection, ColRange, ColExpression, ICollectionQuery, ICollection, Repository } from "./types";
+export { Entity, DbRecord, Pagination, Coordinates, Bounds, Event, EventName, EventRecord, Logic, SortDirection, ColRange, ColExpression, ICollectionQuery, ICollection, Repository, CacheOptions, CachedCollectionOptions } from "./types";
+export { CacheStore, CacheEntry, CacheStats, CacheStoreOptions, BaseCacheStore, MemoryCache, MemoryCacheOptions, CacheKeyGenerator, CacheKeyOptions, InvalidationStrategy, InvalidationRule, InvalidationOptions, CacheInvalidator, TTLStrategy, LRUStrategy, CacheConfig, CacheProviderConfig, CacheConfiguration, createDefaultConfig, createProductionConfig, createDevelopmentConfig, DetailedCacheStats, CacheMetrics, CacheStatsCollector, CacheMonitor, getGlobalCacheMonitor, resetGlobalCacheMonitor } from "./cache";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,7 +1,7 @@
 "use strict";
 // Main exports for flongo package
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ColExpression = exports.ColRange = exports.SortDirection = exports.Logic = exports.EventName = exports.Error400 = exports.Error404 = exports.flongoDb = exports.flongoClient = exports.initializeFlongo = exports.FlongoQueryBuilder = exports.FlongoQuery = exports.FlongoCollection = void 0;
+exports.resetGlobalCacheMonitor = exports.getGlobalCacheMonitor = exports.CacheMonitor = exports.CacheStatsCollector = exports.createDevelopmentConfig = exports.createProductionConfig = exports.createDefaultConfig = exports.CacheConfiguration = exports.LRUStrategy = exports.TTLStrategy = exports.CacheInvalidator = exports.InvalidationStrategy = exports.CacheKeyGenerator = exports.MemoryCache = exports.BaseCacheStore = exports.ColExpression = exports.ColRange = exports.SortDirection = exports.Logic = exports.EventName = exports.Error400 = exports.Error404 = exports.flongoDb = exports.flongoClient = exports.initializeFlongo = exports.FlongoQueryBuilder = exports.FlongoQuery = exports.FlongoCollection = void 0;
 var flongoCollection_1 = require("./flongoCollection");
 Object.defineProperty(exports, "FlongoCollection", { enumerable: true, get: function () { return flongoCollection_1.FlongoCollection; } });
 var flongoQuery_1 = require("./flongoQuery");
@@ -20,4 +20,21 @@ Object.defineProperty(exports, "Logic", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "SortDirection", { enumerable: true, get: function () { return types_1.SortDirection; } });
 Object.defineProperty(exports, "ColRange", { enumerable: true, get: function () { return types_1.ColRange; } });
 Object.defineProperty(exports, "ColExpression", { enumerable: true, get: function () { return types_1.ColExpression; } });
+// Cache exports
+var cache_1 = require("./cache");
+Object.defineProperty(exports, "BaseCacheStore", { enumerable: true, get: function () { return cache_1.BaseCacheStore; } });
+Object.defineProperty(exports, "MemoryCache", { enumerable: true, get: function () { return cache_1.MemoryCache; } });
+Object.defineProperty(exports, "CacheKeyGenerator", { enumerable: true, get: function () { return cache_1.CacheKeyGenerator; } });
+Object.defineProperty(exports, "InvalidationStrategy", { enumerable: true, get: function () { return cache_1.InvalidationStrategy; } });
+Object.defineProperty(exports, "CacheInvalidator", { enumerable: true, get: function () { return cache_1.CacheInvalidator; } });
+Object.defineProperty(exports, "TTLStrategy", { enumerable: true, get: function () { return cache_1.TTLStrategy; } });
+Object.defineProperty(exports, "LRUStrategy", { enumerable: true, get: function () { return cache_1.LRUStrategy; } });
+Object.defineProperty(exports, "CacheConfiguration", { enumerable: true, get: function () { return cache_1.CacheConfiguration; } });
+Object.defineProperty(exports, "createDefaultConfig", { enumerable: true, get: function () { return cache_1.createDefaultConfig; } });
+Object.defineProperty(exports, "createProductionConfig", { enumerable: true, get: function () { return cache_1.createProductionConfig; } });
+Object.defineProperty(exports, "createDevelopmentConfig", { enumerable: true, get: function () { return cache_1.createDevelopmentConfig; } });
+Object.defineProperty(exports, "CacheStatsCollector", { enumerable: true, get: function () { return cache_1.CacheStatsCollector; } });
+Object.defineProperty(exports, "CacheMonitor", { enumerable: true, get: function () { return cache_1.CacheMonitor; } });
+Object.defineProperty(exports, "getGlobalCacheMonitor", { enumerable: true, get: function () { return cache_1.getGlobalCacheMonitor; } });
+Object.defineProperty(exports, "resetGlobalCacheMonitor", { enumerable: true, get: function () { return cache_1.resetGlobalCacheMonitor; } });
 //# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -86,4 +86,21 @@ export type ICollection<T> = {
     updateFirst: (attributes: any, filters?: any, clientId?: string) => Promise<Entity & T>;
 };
 export type Repository = string;
+export interface CacheOptions {
+    enabled?: boolean;
+    ttlSeconds?: number;
+    maxEntries?: number;
+    maxMemoryMB?: number;
+    invalidateOnWrite?: boolean;
+    customKey?: string;
+}
+export interface CachedCollectionOptions {
+    enableCaching?: boolean;
+    cacheConfig?: {
+        maxEntries?: number;
+        ttlSeconds?: number;
+        provider?: 'memory' | 'redis' | 'memcached' | 'custom';
+        enableStats?: boolean;
+    };
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flongo",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Firestore-like fluent query API for MongoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",