@wgtechlabs/nuvex 0.1.1

package/dist/types/interfaces/index.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Nuvex - Interface Definitions
+ * Next-gen Unified Vault Experience
+ *
+ * Core interfaces for the multi-layer storage SDK
+ *
+ * @author Waren Gonzaga, WG Technology Labs
+ * @since 2025
+ */
+import type { StorageOptions, BatchOperation, BatchResult, QueryOptions, QueryResult, NuvexConfig } from '../types/index.js';
+/**
+ * Logger interface for consistent logging across the storage system
+ *
+ * Defines the standard logging interface that can be implemented by any
+ * logging library (Winston, Bunyan, console, etc.). All log methods
+ * accept optional metadata for structured logging.
+ *
+ * @interface Logger
+ */
+export interface Logger {
+    /** Log debug information for development and troubleshooting */
+    debug(message: string, meta?: unknown): void;
+    /** Log general information about system operations */
+    info(message: string, meta?: unknown): void;
+    /** Log warnings about non-critical issues that should be addressed */
+    warn(message: string, meta?: unknown): void;
+    /** Log errors and exceptions that require immediate attention */
+    error(message: string, meta?: unknown): void;
+}
+/**
+ * Structured logging context
+ *
+ * Standard metadata structure for logging operations and performance data.
+ * Provides consistent context across all log entries.
+ *
+ * @interface LogContext
+ */
+export interface LogContext {
+    /** Name of the operation being performed */
+    operation?: string;
+    /** Key involved in the operation */
+    key?: string;
+    /** Storage layer where the operation occurred */
+    layer?: string;
+    /** Duration of the operation in milliseconds */
+    duration?: number;
+    /** Whether the operation completed successfully */
+    success?: boolean;
+    /** Error message if the operation failed */
+    error?: string;
+    /** Additional operation-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Core storage interface
+ *
+ * Defines the fundamental storage operations that must be implemented by
+ * any storage engine. This interface provides the low-level operations
+ * for the multi-layer storage architecture.
+ *
+ * @interface Storage
+ */
+export interface Storage {
+    /** Establish connections to all configured storage layers */
+    connect(): Promise<void>;
+    /** Close all connections and cleanup resources */
+    disconnect(): Promise<void>;
+    /** Check if the storage engine is connected and ready */
+    isConnected(): boolean;
+    /** Store a value with optional configuration */
+    set<T = unknown>(key: string, value: T, options?: StorageOptions): Promise<boolean>;
+    /** Retrieve a value from storage */
+    get<T = unknown>(key: string, options: StorageOptions): Promise<T | null>;
+    /** Delete a value from all storage layers */
+    delete(key: string, options: StorageOptions): Promise<boolean>;
+    /** Check if a key exists in any storage layer */
+    exists(key: string, options: StorageOptions): Promise<boolean>;
+    /** Set or update expiration time for a key */
+    expire(key: string, ttl: number): Promise<boolean>;
+    /** Atomically increment a numeric value */
+    increment(key: string, delta?: number, ttl?: number): Promise<number>;
+    /** Execute multiple storage operations in a batch */
+    setBatch(operations: BatchOperation[]): Promise<BatchResult[]>;
+    /** Retrieve multiple values in a batch */
+    getBatch(keys: string[], options: StorageOptions): Promise<BatchResult[]>;
+    /** Delete multiple values in a batch */
+    deleteBatch(keys: string[]): Promise<BatchResult[]>;
+    /** Execute advanced queries with filtering and pagination */
+    query<T = unknown>(options: QueryOptions): Promise<QueryResult<T>>;
+    /** Get all keys matching an optional pattern */
+    keys(pattern?: string): Promise<string[]>;
+    /** Clear all keys or keys matching a pattern */
+    clear(pattern?: string): Promise<number>;
+    /** Get current performance metrics for all layers or specific layer(s) */
+    getMetrics(layers?: 'memory' | 'redis' | 'postgres' | 'all' | Array<'memory' | 'redis' | 'postgres'>): Record<string, number>;
+    /** Reset all performance metrics to zero */
+    resetMetrics(): void;
+    /** Promote a key to a higher performance layer */
+    promote(key: string, targetLayer: string): Promise<boolean>;
+    /** Demote a key to a lower performance layer */
+    demote(key: string, targetLayer: string): Promise<boolean>;
+    /** Get information about which layer currently holds a key */
+    getLayerInfo(key: string): Promise<{
+        layer: string;
+        ttl?: number;
+    } | null>;
+}
+/**
+ * High-level store interface
+ *
+ * Extends the basic Storage interface with additional features for
+ * configuration management, health monitoring, and maintenance operations.
+ * This is typically the interface used by application developers.
+ *
+ * @interface Store
+ * @extends Storage
+ */
+export interface Store extends Storage {
+    /** Update configuration with new settings */
+    configure(config: Partial<NuvexConfig>): Promise<void>;
+    /** Get current configuration */
+    getConfig(): NuvexConfig;
+    /** Perform comprehensive health checks on all storage layers or specific layer(s) */
+    healthCheck(layers?: 'memory' | 'redis' | 'postgres' | Array<'memory' | 'redis' | 'postgres'>): Promise<Record<string, boolean>>;
+    /** Clean up expired entries and optimize storage */
+    cleanup(): Promise<{
+        cleaned: number;
+        errors: number;
+    }>;
+    /** Compact storage and optimize performance */
+    compact(): Promise<void>;
+    /** Create a backup of all stored data */
+    backup(destination?: string): Promise<string>;
+    /** Restore data from a backup */
+    restore(source: string): Promise<boolean>;
+}
+/**
+ * Storage Layer interface for modular storage implementations
+ *
+ * Defines the contract that all storage layer implementations must follow.
+ * Each layer (Memory, Redis, PostgreSQL) implements this interface to provide
+ * consistent operations across the storage hierarchy.
+ *
+ * This interface supports:
+ * - Basic CRUD operations (get, set, delete)
+ * - Existence checks
+ * - Optional clear operation for cache layers
+ * - Health check via ping() method
+ *
+ * @interface StorageLayerInterface
+ * @since 1.0.0
+ */
+export interface StorageLayerInterface {
+    /**
+     * Retrieve a value from this storage layer
+     * @param key - The key to retrieve
+     * @returns Promise resolving to the value or null if not found
+     */
+    get(key: string): Promise<unknown>;
+    /**
+     * Store a value in this storage layer
+     * @param key - The key to store
+     * @param value - The value to store
+     * @param ttlSeconds - Optional TTL in seconds
+     * @returns Promise resolving when the operation completes
+     */
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /**
+     * Delete a value from this storage layer
+     * @param key - The key to delete
+     * @returns Promise resolving when the operation completes
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a key exists in this storage layer
+     * @param key - The key to check
+     * @returns Promise resolving to true if the key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Clear all data from this storage layer (optional for some layers)
+     * @returns Promise resolving when the operation completes
+     */
+    clear?(): Promise<void>;
+    /**
+     * Get all keys matching an optional pattern from this storage layer
+     * @param pattern - Optional glob pattern for key matching (e.g., 'user:*')
+     * @returns Promise resolving to an array of matching keys
+     */
+    keys?(pattern?: string): Promise<string[]>;
+    /**
+     * Health check for this storage layer
+     * @returns Promise resolving to true if the layer is healthy and operational
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Atomically increment a numeric value
+     *
+     * This operation is thread-safe and prevents race conditions.
+     * If the key doesn't exist, it's initialized to 0 before incrementing.
+     *
+     * @param key - The key to increment
+     * @param delta - The amount to increment by (can be negative for decrement)
+     * @param ttlSeconds - Optional TTL in seconds for the key
+     * @returns Promise resolving to the new value after increment
+     */
+    increment?(key: string, delta: number, ttlSeconds?: number): Promise<number>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/interfaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/interfaces/index.ts"],"names":[],"mappings":"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"}

package/dist/types/layers/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Nuvex - Storage Layers
+ * Next-gen Unified Vault Experience
+ *
+ * Exports modular storage layer implementations for the 3-tier architecture.
+ * Each layer provides consistent interface but different performance and
+ * persistence characteristics.
+ *
+ * @author Waren Gonzaga, WG Technology Labs
+ * @version 1.0.0
+ * @since 2025
+ */
+export { MemoryStorage } from './memory.js';
+export { RedisStorage } from './redis.js';
+export { PostgresStorage } from './postgres.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/layers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/layers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/types/layers/memory.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Nuvex - Memory Storage Layer (L1)
+ * Next-gen Unified Vault Experience
+ *
+ * In-memory cache layer with LRU (Least Recently Used) eviction policy.
+ * Provides the fastest access tier in the multi-layer storage architecture.
+ *
+ * Features:
+ * - LRU eviction with configurable maxSize
+ * - TTL-based expiration
+ * - Sub-millisecond access times
+ * - Automatic cleanup of expired entries
+ *
+ * @author Waren Gonzaga, WG Technology Labs
+ * @since 2025
+ */
+import type { StorageLayerInterface, Logger } from '../interfaces/index.js';
+/**
+ * Memory Storage Layer - L1 Cache with LRU Eviction
+ *
+ * Implements an in-memory cache with Least Recently Used (LRU) eviction policy.
+ * This layer provides the fastest access times but has limited capacity defined
+ * by maxSize. When the cache is full, the least recently accessed item is evicted
+ * to make room for new entries.
+ *
+ * **LRU Implementation:**
+ * - Uses JavaScript Map which maintains insertion order
+ * - On get(), moves accessed entry to end (marks as recently used)
+ * - On set(), evicts first entry (oldest/least recently used) when full
+ * - Combines LRU with TTL-based expiration for optimal memory management
+ *
+ * **Performance Characteristics:**
+ * - Get: O(1) average, O(n) worst case due to delete+set for LRU
+ * - Set: O(1) with occasional O(1) eviction
+ * - Memory: O(maxSize)
+ *
+ * @implements {StorageLayerInterface}
+ *
+ * @example
+ * ```typescript
+ * // Create memory layer with 1000 entry limit
+ * const memory = new MemoryStorage(1000);
+ *
+ * // Store with 60 second TTL
+ * await memory.set('user:123', userData, 60);
+ *
+ * // Retrieve (marks as recently used)
+ * const data = await memory.get('user:123');
+ *
+ * // Check health
+ * const isHealthy = await memory.ping(); // Always true
+ * ```
+ *
+ * @class MemoryStorage
+ * @since 1.0.0
+ */
+export declare class MemoryStorage implements StorageLayerInterface {
+    /** In-memory cache using Map for LRU ordering */
+    private cache;
+    /** Maximum number of entries before LRU eviction kicks in */
+    private readonly maxSize;
+    /** Optional logger for debugging and monitoring */
+    private logger;
+    /**
+     * Creates a new MemoryStorage instance
+     *
+     * @param maxSize - Maximum number of entries to store (default: 10,000)
+     * @param logger - Optional logger for debugging
+     *
+     * @example
+     * ```typescript
+     * // Default configuration
+     * const memory = new MemoryStorage();
+     *
+     * // Custom size limit
+     * const memory = new MemoryStorage(5000);
+     *
+     * // With logging
+     * const memory = new MemoryStorage(10000, console);
+     * ```
+     */
+    constructor(maxSize?: number, logger?: Logger | null);
+    /**
+     * Retrieve a value from memory cache
+     *
+     * Implements LRU by moving accessed entries to the end of the Map,
+     * marking them as recently used. Automatically removes expired entries.
+     *
+     * @param key - The key to retrieve
+     * @returns Promise resolving to the value or null if not found/expired
+     *
+     * @example
+     * ```typescript
+     * const value = await memory.get('user:123');
+     * if (value !== null) {
+     *   console.log('Cache hit!');
+     * }
+     * ```
+     */
+    get(key: string): Promise<unknown>;
+    /**
+     * Store a value in memory cache
+     *
+     * Implements LRU eviction when cache is full. If the cache has reached
+     * maxSize and the key doesn't already exist, the oldest entry (first in Map)
+     * is evicted to make room for the new entry.
+     *
+     * @param key - The key to store
+     * @param value - The value to store
+     * @param ttlSeconds - Optional TTL in seconds
+     *
+     * @example
+     * ```typescript
+     * // Store without TTL
+     * await memory.set('config:app', configData);
+     *
+     * // Store with 5 minute TTL
+     * await memory.set('session:abc', sessionData, 300);
+     * ```
+     */
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /**
+     * Delete a value from memory cache
+     *
+     * @param key - The key to delete
+     *
+     * @example
+     * ```typescript
+     * await memory.delete('user:123');
+     * ```
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a key exists in memory cache
+     *
+     * Verifies existence and checks if the entry has expired.
+     * Automatically removes expired entries.
+     *
+     * @param key - The key to check
+     * @returns Promise resolving to true if the key exists and is not expired
+     *
+     * @example
+     * ```typescript
+     * if (await memory.exists('user:123')) {
+     *   console.log('Key exists in memory');
+     * }
+     * ```
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Clear all entries from memory cache
+     *
+     * Removes all stored entries, resetting the cache to empty state.
+     *
+     * @example
+     * ```typescript
+     * await memory.clear();
+     * console.log('All memory cache cleared');
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Get all keys matching an optional pattern
+     *
+     * Returns all non-expired keys from the memory cache, optionally filtered
+     * by a glob pattern. Supports '*' (match any characters) and '?' (match single character).
+     *
+     * @param pattern - Optional glob pattern (default: '*' returns all keys)
+     * @returns Promise resolving to array of matching keys
+     *
+     * @example
+     * ```typescript
+     * // Get all keys
+     * const allKeys = await memory.keys();
+     *
+     * // Get keys matching pattern
+     * const userKeys = await memory.keys('user:*');
+     * ```
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Health check for memory storage layer
+     *
+     * Memory storage is always available if the application is running,
+     * so this method always returns true unless there's a critical failure.
+     *
+     * @returns Promise resolving to true (memory is always available)
+     *
+     * @example
+     * ```typescript
+     * const isHealthy = await memory.ping();
+     * console.log('Memory layer healthy:', isHealthy);
+     * ```
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Get current cache size
+     *
+     * Returns the number of entries currently stored in the cache.
+     * Useful for monitoring and debugging.
+     *
+     * @returns Current number of entries in cache
+     *
+     * @example
+     * ```typescript
+     * console.log(`Cache usage: ${memory.size()}/${memory.getMaxSize()}`);
+     * ```
+     */
+    size(): number;
+    /**
+     * Get maximum cache size
+     *
+     * Returns the configured maximum number of entries.
+     *
+     * @returns Maximum cache size
+     */
+    getMaxSize(): number;
+    /**
+     * Clean up expired entries
+     *
+     * Iterates through all entries and removes expired ones.
+     * This is useful for manual cleanup or scheduled maintenance.
+     *
+     * @returns Number of entries removed
+     *
+     * @example
+     * ```typescript
+     * const cleaned = await memory.cleanup();
+     * console.log(`Removed ${cleaned} expired entries`);
+     * ```
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Atomically increment a numeric value
+     *
+     * This operation is thread-safe for single-instance deployments.
+     * If the key doesn't exist or is expired, it's initialized to 0 before incrementing.
+     *
+     * @param key - The key to increment
+     * @param delta - The amount to increment by (can be negative for decrement)
+     * @param ttlSeconds - Optional TTL in seconds
+     * @returns Promise resolving to the new value after increment
+     *
+     * @example
+     * ```typescript
+     * const newValue = await memory.increment('counter', 1, 60);
+     * console.log(`Counter is now: ${newValue}`);
+     * ```
+     */
+    increment(key: string, delta: number, ttlSeconds?: number): Promise<number>;
+    /**
+     * Log a message if logger is configured
+     *
+     * @private
+     * @param level - Log level
+     * @param message - Log message
+     * @param meta - Optional metadata
+     */
+    private log;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/types/layers/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/layers/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAa5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,aAAc,YAAW,qBAAqB;IACzD,iDAAiD;IACjD,OAAO,CAAC,KAAK,CAAgC;IAE7C,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,mDAAmD;IACnD,OAAO,CAAC,MAAM,CAAgB;IAE9B;;;;;;;;;;;;;;;;;OAiBG;gBACS,OAAO,SAAQ,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW;IAMzD;;;;;;;;;;;;;;;;OAgBG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqBxC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1E;;;;;;;;;OASG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;;;;;;;;;;;;;;OAeG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAe3C;;;;;;;;;;OAUG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;;;;;;;;;;;;;;;;OAiBG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgC/C;;;;;;;;;;;;;OAaG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAe9B;;;;;;;;;;;;OAYG;IACH,IAAI,IAAI,MAAM;IAId;;;;;;OAMG;IACH,UAAU,IAAI,MAAM;IAIpB;;;;;;;;;;;;;OAaG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBhC;;;;;;;;;;;;;;;;OAgBG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBjF;;;;;;;OAOG;IACH,OAAO,CAAC,GAAG;CAKZ"}