flongo 1.0.2 → 1.2.0

package/dist/cache/cacheConfig.d.ts

@@ -0,0 +1,62 @@
+import { InvalidationStrategy } from './cacheStrategies';
+import { ICollectionQuery, Pagination } from '../types';
+export interface WarmupQuery {
+    collection: string;
+    operation: string;
+    query?: ICollectionQuery;
+    pagination?: Pagination;
+}
+export interface CacheProviderConfig {
+    type: 'memory' | 'redis' | 'memcached' | 'custom';
+    connectionString?: string;
+    options?: Record<string, unknown>;
+}
+export interface CacheConfig {
+    enabled: boolean;
+    provider: CacheProviderConfig;
+    maxEntries: number;
+    maxMemoryMB: number;
+    defaultTTL: number;
+    checkInterval: number;
+    enableStats: boolean;
+    invalidationStrategy: InvalidationStrategy;
+    customTTLs?: Record<string, number>;
+    warmupQueries?: WarmupQuery[];
+    debug?: boolean;
+}
+export declare class CacheConfiguration {
+    private static defaultConfig;
+    private config;
+    constructor(config?: Partial<CacheConfig>);
+    private mergeConfig;
+    get enabled(): boolean;
+    get providerType(): string;
+    get providerOptions(): Record<string, unknown> | undefined;
+    get connectionString(): string | undefined;
+    get maxEntries(): number;
+    get maxMemoryMB(): number;
+    get defaultTTL(): number;
+    get checkInterval(): number;
+    get enableStats(): boolean;
+    get invalidationStrategy(): InvalidationStrategy;
+    get customTTLs(): Record<string, number> | undefined;
+    get warmupQueries(): WarmupQuery[] | undefined;
+    get debug(): boolean;
+    setEnabled(enabled: boolean): void;
+    setProvider(provider: CacheProviderConfig): void;
+    setMaxEntries(max: number): void;
+    setMaxMemoryMB(max: number): void;
+    setDefaultTTL(ttl: number): void;
+    setCheckInterval(interval: number): void;
+    setInvalidationStrategy(strategy: InvalidationStrategy): void;
+    setCustomTTL(pattern: string, ttl: number): void;
+    addWarmupQuery(query: WarmupQuery): void;
+    setDebug(debug: boolean): void;
+    toJSON(): CacheConfig;
+    static fromEnvironment(): CacheConfiguration;
+    validate(): string[];
+}
+export declare function createDefaultConfig(): CacheConfig;
+export declare function createProductionConfig(): CacheConfig;
+export declare function createDevelopmentConfig(): CacheConfig;
+//# sourceMappingURL=cacheConfig.d.ts.map

package/dist/cache/cacheConfig.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheConfiguration = void 0;
+exports.createDefaultConfig = createDefaultConfig;
+exports.createProductionConfig = createProductionConfig;
+exports.createDevelopmentConfig = createDevelopmentConfig;
+const cacheStrategies_1 = require("./cacheStrategies");
+class CacheConfiguration {
+    constructor(config) {
+        this.config = this.mergeConfig(config);
+    }
+    mergeConfig(userConfig) {
+        if (!userConfig) {
+            return { ...CacheConfiguration.defaultConfig };
+        }
+        const merged = {
+            ...CacheConfiguration.defaultConfig,
+            ...userConfig
+        };
+        if (userConfig.provider) {
+            merged.provider = {
+                ...CacheConfiguration.defaultConfig.provider,
+                ...userConfig.provider
+            };
+        }
+        if (userConfig.customTTLs) {
+            merged.customTTLs = { ...userConfig.customTTLs };
+        }
+        if (userConfig.warmupQueries) {
+            merged.warmupQueries = [...userConfig.warmupQueries];
+        }
+        return merged;
+    }
+    get enabled() {
+        return this.config.enabled;
+    }
+    get providerType() {
+        return this.config.provider.type;
+    }
+    get providerOptions() {
+        return this.config.provider.options;
+    }
+    get connectionString() {
+        return this.config.provider.connectionString;
+    }
+    get maxEntries() {
+        return this.config.maxEntries;
+    }
+    get maxMemoryMB() {
+        return this.config.maxMemoryMB;
+    }
+    get defaultTTL() {
+        return this.config.defaultTTL;
+    }
+    get checkInterval() {
+        return this.config.checkInterval;
+    }
+    get enableStats() {
+        return this.config.enableStats;
+    }
+    get invalidationStrategy() {
+        return this.config.invalidationStrategy;
+    }
+    get customTTLs() {
+        return this.config.customTTLs;
+    }
+    get warmupQueries() {
+        return this.config.warmupQueries;
+    }
+    get debug() {
+        return this.config.debug || false;
+    }
+    setEnabled(enabled) {
+        this.config.enabled = enabled;
+    }
+    setProvider(provider) {
+        this.config.provider = provider;
+    }
+    setMaxEntries(max) {
+        if (max <= 0) {
+            throw new Error('maxEntries must be greater than 0');
+        }
+        this.config.maxEntries = max;
+    }
+    setMaxMemoryMB(max) {
+        if (max <= 0) {
+            throw new Error('maxMemoryMB must be greater than 0');
+        }
+        this.config.maxMemoryMB = max;
+    }
+    setDefaultTTL(ttl) {
+        if (ttl < 0) {
+            throw new Error('defaultTTL must be non-negative');
+        }
+        this.config.defaultTTL = ttl;
+    }
+    setCheckInterval(interval) {
+        if (interval < 0) {
+            throw new Error('checkInterval must be non-negative');
+        }
+        this.config.checkInterval = interval;
+    }
+    setInvalidationStrategy(strategy) {
+        this.config.invalidationStrategy = strategy;
+    }
+    setCustomTTL(pattern, ttl) {
+        if (!this.config.customTTLs) {
+            this.config.customTTLs = {};
+        }
+        this.config.customTTLs[pattern] = ttl;
+    }
+    addWarmupQuery(query) {
+        if (!this.config.warmupQueries) {
+            this.config.warmupQueries = [];
+        }
+        this.config.warmupQueries.push(query);
+    }
+    setDebug(debug) {
+        this.config.debug = debug;
+    }
+    toJSON() {
+        return { ...this.config };
+    }
+    static fromEnvironment() {
+        const config = {};
+        if (process.env.FLONGO_CACHE_ENABLED) {
+            config.enabled = process.env.FLONGO_CACHE_ENABLED === 'true';
+        }
+        if (process.env.FLONGO_CACHE_PROVIDER) {
+            config.provider = {
+                type: process.env.FLONGO_CACHE_PROVIDER
+            };
+        }
+        if (process.env.FLONGO_CACHE_CONNECTION) {
+            if (!config.provider) {
+                config.provider = { type: 'redis' };
+            }
+            config.provider.connectionString = process.env.FLONGO_CACHE_CONNECTION;
+        }
+        if (process.env.FLONGO_CACHE_MAX_ENTRIES) {
+            config.maxEntries = parseInt(process.env.FLONGO_CACHE_MAX_ENTRIES, 10);
+        }
+        if (process.env.FLONGO_CACHE_MAX_MEMORY_MB) {
+            config.maxMemoryMB = parseInt(process.env.FLONGO_CACHE_MAX_MEMORY_MB, 10);
+        }
+        if (process.env.FLONGO_CACHE_DEFAULT_TTL) {
+            config.defaultTTL = parseInt(process.env.FLONGO_CACHE_DEFAULT_TTL, 10);
+        }
+        if (process.env.FLONGO_CACHE_CHECK_INTERVAL) {
+            config.checkInterval = parseInt(process.env.FLONGO_CACHE_CHECK_INTERVAL, 10);
+        }
+        if (process.env.FLONGO_CACHE_ENABLE_STATS) {
+            config.enableStats = process.env.FLONGO_CACHE_ENABLE_STATS === 'true';
+        }
+        if (process.env.FLONGO_CACHE_INVALIDATION_STRATEGY) {
+            config.invalidationStrategy = process.env.FLONGO_CACHE_INVALIDATION_STRATEGY;
+        }
+        if (process.env.FLONGO_CACHE_DEBUG) {
+            config.debug = process.env.FLONGO_CACHE_DEBUG === 'true';
+        }
+        return new CacheConfiguration(config);
+    }
+    validate() {
+        const errors = [];
+        if (this.config.maxEntries <= 0) {
+            errors.push('maxEntries must be greater than 0');
+        }
+        if (this.config.maxMemoryMB <= 0) {
+            errors.push('maxMemoryMB must be greater than 0');
+        }
+        if (this.config.defaultTTL < 0) {
+            errors.push('defaultTTL must be non-negative');
+        }
+        if (this.config.checkInterval < 0) {
+            errors.push('checkInterval must be non-negative');
+        }
+        const validProviders = ['memory', 'redis', 'memcached', 'custom'];
+        if (!validProviders.includes(this.config.provider.type)) {
+            errors.push(`Invalid provider type: ${this.config.provider.type}`);
+        }
+        if (this.config.provider.type === 'redis' || this.config.provider.type === 'memcached') {
+            if (!this.config.provider.connectionString) {
+                errors.push(`Connection string required for ${this.config.provider.type} provider`);
+            }
+        }
+        const validStrategies = Object.values(cacheStrategies_1.InvalidationStrategy);
+        if (!validStrategies.includes(this.config.invalidationStrategy)) {
+            errors.push(`Invalid invalidation strategy: ${this.config.invalidationStrategy}`);
+        }
+        return errors;
+    }
+}
+exports.CacheConfiguration = CacheConfiguration;
+CacheConfiguration.defaultConfig = {
+    enabled: false,
+    provider: {
+        type: 'memory'
+    },
+    maxEntries: 10000,
+    maxMemoryMB: 100,
+    defaultTTL: 300,
+    checkInterval: 60,
+    enableStats: true,
+    invalidationStrategy: cacheStrategies_1.InvalidationStrategy.Smart,
+    debug: false
+};
+function createDefaultConfig() {
+    return new CacheConfiguration().toJSON();
+}
+function createProductionConfig() {
+    return new CacheConfiguration({
+        enabled: true,
+        provider: {
+            type: 'memory'
+        },
+        maxEntries: 50000,
+        maxMemoryMB: 500,
+        defaultTTL: 600,
+        checkInterval: 120,
+        enableStats: true,
+        invalidationStrategy: cacheStrategies_1.InvalidationStrategy.Smart
+    }).toJSON();
+}
+function createDevelopmentConfig() {
+    return new CacheConfiguration({
+        enabled: true,
+        provider: {
+            type: 'memory'
+        },
+        maxEntries: 1000,
+        maxMemoryMB: 50,
+        defaultTTL: 60,
+        checkInterval: 30,
+        enableStats: true,
+        invalidationStrategy: cacheStrategies_1.InvalidationStrategy.Smart,
+        debug: true
+    }).toJSON();
+}
+//# sourceMappingURL=cacheConfig.js.map

package/dist/cache/cacheKeyGenerator.d.ts

@@ -0,0 +1,30 @@
+import { ICollectionQuery, Pagination } from '../types';
+export interface CacheKeyOptions {
+    collection: string;
+    operation: string;
+    query?: ICollectionQuery;
+    id?: string;
+    pagination?: Pagination;
+    additionalParams?: Record<string, unknown>;
+}
+export declare class CacheKeyGenerator {
+    private static readonly SEPARATOR;
+    private static readonly NULL_VALUE;
+    private static readonly UNDEFINED_VALUE;
+    static generate(options: CacheKeyOptions): string;
+    static generatePattern(collection: string, operation?: string): string;
+    private static hashQuery;
+    private static normalizeQuery;
+    private static normalizeValue;
+    private static hashObject;
+    private static hash;
+    static parseKey(key: string): {
+        collection?: string;
+        operation?: string;
+        identifier?: string;
+    };
+    static isFlongoKey(key: string): boolean;
+    static getCollectionFromKey(key: string): string | undefined;
+    static getOperationFromKey(key: string): string | undefined;
+}
+//# sourceMappingURL=cacheKeyGenerator.d.ts.map

package/dist/cache/cacheKeyGenerator.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheKeyGenerator = void 0;
+const crypto_1 = require("crypto");
+const types_1 = require("../types");
+class CacheKeyGenerator {
+    static generate(options) {
+        const parts = [
+            'flongo',
+            options.collection,
+            options.operation
+        ];
+        if (options.id) {
+            parts.push(options.id);
+            return parts.join(this.SEPARATOR);
+        }
+        if (options.query) {
+            const queryHash = this.hashQuery(options.query);
+            parts.push(queryHash);
+        }
+        if (options.pagination) {
+            parts.push(`p${options.pagination.offset}-${options.pagination.count}`);
+        }
+        if (options.additionalParams) {
+            const paramsHash = this.hashObject(options.additionalParams);
+            parts.push(paramsHash);
+        }
+        return parts.join(this.SEPARATOR);
+    }
+    static generatePattern(collection, operation) {
+        const parts = ['flongo', collection];
+        if (operation) {
+            parts.push(operation);
+        }
+        return parts.join(this.SEPARATOR) + '*';
+    }
+    static hashQuery(query) {
+        const normalized = this.normalizeQuery(query);
+        return this.hash(JSON.stringify(normalized));
+    }
+    static normalizeQuery(query) {
+        const normalized = {};
+        if (query.expressions && query.expressions.length > 0) {
+            normalized.expressions = query.expressions
+                .map(exp => ({
+                op: exp.op || '==',
+                key: exp.key,
+                val: this.normalizeValue(exp.val)
+            }))
+                .sort((a, b) => {
+                const keyCompare = a.key.localeCompare(b.key);
+                if (keyCompare !== 0)
+                    return keyCompare;
+                const opCompare = a.op.localeCompare(b.op);
+                if (opCompare !== 0)
+                    return opCompare;
+                return String(a.val).localeCompare(String(b.val));
+            });
+        }
+        if (query.ranges && query.ranges.length > 0) {
+            normalized.ranges = query.ranges
+                .map(range => ({
+                key: range.key,
+                start: this.normalizeValue(range.start),
+                end: this.normalizeValue(range.end)
+            }))
+                .sort((a, b) => a.key.localeCompare(b.key));
+        }
+        if (query.orderField) {
+            normalized.order = {
+                field: query.orderField,
+                direction: query.orderDirection || types_1.SortDirection.Ascending
+            };
+        }
+        if (query.orQueries && query.orQueries.length > 0) {
+            normalized.or = query.orQueries
+                .map(q => this.normalizeQuery(q))
+                .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+        }
+        if (query.andQueries && query.andQueries.length > 0) {
+            normalized.and = query.andQueries
+                .map(q => this.normalizeQuery(q))
+                .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+        }
+        return normalized;
+    }
+    static normalizeValue(value) {
+        if (value === null) {
+            return this.NULL_VALUE;
+        }
+        if (value === undefined) {
+            return this.UNDEFINED_VALUE;
+        }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (typeof value === 'object' && value !== null) {
+            if (Array.isArray(value)) {
+                return value.map(v => this.normalizeValue(v)).sort();
+            }
+            const normalized = {};
+            const keys = Object.keys(value).sort();
+            for (const key of keys) {
+                normalized[key] = this.normalizeValue(value[key]);
+            }
+            return normalized;
+        }
+        return value;
+    }
+    static hashObject(obj) {
+        const normalized = this.normalizeValue(obj);
+        return this.hash(JSON.stringify(normalized));
+    }
+    static hash(input) {
+        return (0, crypto_1.createHash)('sha256')
+            .update(input)
+            .digest('hex')
+            .substring(0, 16);
+    }
+    static parseKey(key) {
+        const parts = key.split(this.SEPARATOR);
+        if (parts[0] !== 'flongo') {
+            return {};
+        }
+        return {
+            collection: parts[1],
+            operation: parts[2],
+            identifier: parts.slice(3).join(this.SEPARATOR)
+        };
+    }
+    static isFlongoKey(key) {
+        return key.startsWith('flongo' + this.SEPARATOR);
+    }
+    static getCollectionFromKey(key) {
+        const parsed = this.parseKey(key);
+        return parsed.collection;
+    }
+    static getOperationFromKey(key) {
+        const parsed = this.parseKey(key);
+        return parsed.operation;
+    }
+}
+exports.CacheKeyGenerator = CacheKeyGenerator;
+CacheKeyGenerator.SEPARATOR = ':';
+CacheKeyGenerator.NULL_VALUE = '__null__';
+CacheKeyGenerator.UNDEFINED_VALUE = '__undefined__';
+//# sourceMappingURL=cacheKeyGenerator.js.map

package/dist/cache/cacheStats.d.ts

@@ -0,0 +1,69 @@
+import { CacheStats } from './cacheStore';
+export interface DetailedCacheStats extends CacheStats {
+    hitRate: number;
+    missRate: number;
+    evictionRate: number;
+    averageAccessTime?: number;
+    totalRequests: number;
+    uptime: number;
+    lastReset: number;
+}
+export interface CacheMetrics {
+    operationCounts: Map<string, number>;
+    operationLatencies: Map<string, number[]>;
+    collectionStats: Map<string, CacheStats>;
+    keyAccessCounts: Map<string, number>;
+    memoryUsageOverTime: Array<{
+        timestamp: number;
+        usage: number;
+    }>;
+}
+export declare class CacheStatsCollector {
+    private startTime;
+    private lastResetTime;
+    private metrics;
+    private maxHistorySize;
+    constructor(maxHistorySize?: number);
+    recordOperation(operation: string, latencyMs: number): void;
+    recordKeyAccess(key: string): void;
+    recordMemoryUsage(usageBytes: number): void;
+    updateCollectionStats(collection: string, stats: Partial<CacheStats>): void;
+    getDetailedStats(baseStats: CacheStats): DetailedCacheStats;
+    getOperationStats(): Map<string, {
+        count: number;
+        averageLatency: number;
+        p50: number;
+        p95: number;
+        p99: number;
+    }>;
+    getTopKeys(limit?: number): Array<{
+        key: string;
+        count: number;
+    }>;
+    getMemoryTrend(): Array<{
+        timestamp: number;
+        usage: number;
+    }>;
+    getCollectionStats(): Map<string, CacheStats>;
+    reset(): void;
+    private calculateAverage;
+    private calculatePercentile;
+    private calculateAverageLatency;
+    toJSON(): object;
+}
+export declare class CacheMonitor {
+    private collectors;
+    private globalCollector;
+    private intervalId?;
+    constructor();
+    getCollector(name: string): CacheStatsCollector;
+    getGlobalCollector(): CacheStatsCollector;
+    startMonitoring(intervalMs?: number, callback?: (stats: any) => void): void;
+    stopMonitoring(): void;
+    getSnapshot(): object;
+    reset(): void;
+    destroy(): void;
+}
+export declare function getGlobalCacheMonitor(): CacheMonitor;
+export declare function resetGlobalCacheMonitor(): void;
+//# sourceMappingURL=cacheStats.d.ts.map