@wgtechlabs/nuvex 0.1.1

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

@@ -0,0 +1,313 @@
+/**
+ * Nuvex - PostgreSQL Storage Layer (L3)
+ * Next-gen Unified Vault Experience
+ *
+ * PostgreSQL persistent storage layer serving as the source of truth for all data.
+ * Provides ACID-compliant, durable storage with full data integrity guarantees.
+ *
+ * Features:
+ * - ACID-compliant persistent storage
+ * - Source of truth for all data
+ * - JSON support for flexible data structures
+ * - Automatic TTL-based expiration
+ * - Connection pooling for optimal performance
+ * - Health monitoring with SELECT 1 queries
+ *
+ * @author Waren Gonzaga, WG Technology Labs
+ * @since 2025
+ */
+import type { Pool as PoolType } from 'pg';
+import type { StorageLayerInterface, Logger } from '../interfaces/index.js';
+import type { PostgresConfig } from '../types/index.js';
+/**
+ * PostgreSQL Storage Layer - L3 Persistent Storage
+ *
+ * Implements persistent storage using PostgreSQL. This is the authoritative
+ * source of truth for all data in the system. All writes must succeed here
+ * for the operation to be considered successful.
+ *
+ * **Key Features:**
+ * - ACID compliance for data integrity
+ * - Durable storage that survives restarts
+ * - JSON/JSONB support for complex objects
+ * - TTL-based automatic expiration
+ * - Connection pooling for performance
+ * - Transaction support for complex operations
+ *
+ * **Storage Schema:**
+ * - Table: nuvex_storage
+ * - Columns: id, key (unique), value (JSONB), expires_at, created_at, updated_at
+ * - Indexes: key, expires_at, key pattern (trigram)
+ *
+ * **Performance Characteristics:**
+ * - Get: O(log n) with index lookup
+ * - Set: O(log n) with index update
+ * - Latency: 5-50ms typical (storage + network)
+ *
+ * **Error Handling:**
+ * - Returns null on read errors (graceful degradation)
+ * - Logs errors for monitoring
+ * - Throws on critical connection failures
+ *
+ * @implements {StorageLayerInterface}
+ *
+ * @example
+ * ```typescript
+ * // Create PostgreSQL layer
+ * const postgres = new PostgresStorage({
+ *   host: 'localhost',
+ *   port: 5432,
+ *   database: 'myapp',
+ *   user: 'postgres',
+ *   password: 'password'
+ * });
+ *
+ * // Connect (creates pool)
+ * await postgres.connect();
+ *
+ * // Store data (source of truth)
+ * await postgres.set('user:123', userData, 86400);
+ *
+ * // Retrieve data
+ * const data = await postgres.get('user:123');
+ *
+ * // Check health
+ * const isHealthy = await postgres.ping();
+ * ```
+ *
+ * @class PostgresStorage
+ * @since 1.0.0
+ */
+export declare class PostgresStorage implements StorageLayerInterface {
+    /** PostgreSQL connection pool */
+    private pool;
+    /** Database configuration or existing pool */
+    private readonly config;
+    /** Whether the pool is connected */
+    private connected;
+    /** Optional logger for debugging and monitoring */
+    private logger;
+    /** Whether we created the pool (vs. received existing one) */
+    private readonly ownsPool;
+    /** Table name for storage */
+    private readonly tableName;
+    /** Key column name */
+    private readonly keyColumn;
+    /** Value/data column name */
+    private readonly valueColumn;
+    /**
+     * Creates a new PostgresStorage instance
+     *
+     * Accepts either a PostgreSQL configuration object or an existing Pool instance.
+     * If a Pool is provided, the caller is responsible for managing its lifecycle.
+     *
+     * Schema configuration is extracted from the config object when creating a new pool.
+     * When using an existing pool, schema defaults to standard Nuvex naming.
+     *
+     * @param config - PostgreSQL configuration or existing Pool instance
+     * @param logger - Optional logger for debugging
+     *
+     * @example
+     * ```typescript
+     * // With configuration (supports schema customization)
+     * const postgres = new PostgresStorage({
+     *   host: 'localhost',
+     *   database: 'myapp',
+     *   user: 'postgres',
+     *   password: 'password',
+     *   schema: {
+     *     tableName: 'storage_cache',
+     *     columns: { key: 'key', value: 'value' }
+     *   }
+     * });
+     *
+     * // With existing pool (uses default schema)
+     * const existingPool = new Pool({ ... });
+     * const postgres = new PostgresStorage(existingPool);
+     * ```
+     */
+    constructor(config: PostgresConfig | PoolType, logger?: Logger | null);
+    /**
+     * Establish connection to PostgreSQL
+     *
+     * Creates a connection pool (if not already provided) and tests the connection.
+     * Should be called before any storage operations.
+     *
+     * @throws {Error} If connection test fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await postgres.connect();
+     *   console.log('PostgreSQL connected');
+     * } catch (error) {
+     *   console.error('PostgreSQL connection failed:', error);
+     * }
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Close PostgreSQL connection pool
+     *
+     * Only closes the pool if we created it. If an existing pool was provided,
+     * the caller is responsible for closing it.
+     *
+     * @example
+     * ```typescript
+     * await postgres.disconnect();
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Retrieve a value from PostgreSQL
+     *
+     * Queries the nuvex_storage table and automatically filters out expired entries.
+     * Deserializes the JSON-stored value.
+     *
+     * @param key - The key to retrieve
+     * @returns Promise resolving to the value or null if not found/expired
+     *
+     * @example
+     * ```typescript
+     * const userData = await postgres.get('user:123');
+     * if (userData !== null) {
+     *   console.log('Found in PostgreSQL');
+     * }
+     * ```
+     */
+    get(key: string): Promise<unknown>;
+    /**
+     * Store a value in PostgreSQL
+     *
+     * Inserts or updates the value in the nuvex_storage table. Uses UPSERT
+     * (INSERT ... ON CONFLICT) to handle existing keys efficiently.
+     *
+     * **Note:** This is the authoritative write. If this fails, the entire
+     * write operation should be considered failed.
+     *
+     * @param key - The key to store
+     * @param value - The value to store (will be JSON serialized)
+     * @param ttlSeconds - Optional TTL in seconds
+     *
+     * @example
+     * ```typescript
+     * // Store with 24 hour TTL
+     * await postgres.set('user:123', userData, 86400);
+     *
+     * // Store without TTL (persists until deleted)
+     * await postgres.set('config:app', configData);
+     * ```
+     */
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /**
+     * Delete a value from PostgreSQL
+     *
+     * Permanently removes the key from the nuvex_storage table.
+     *
+     * @param key - The key to delete
+     *
+     * @example
+     * ```typescript
+     * await postgres.delete('user:123');
+     * ```
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a key exists in PostgreSQL
+     *
+     * Queries for the key and verifies it hasn't expired.
+     *
+     * @param key - The key to check
+     * @returns Promise resolving to true if the key exists and is not expired
+     *
+     * @example
+     * ```typescript
+     * if (await postgres.exists('user:123')) {
+     *   console.log('Key exists in PostgreSQL');
+     * }
+     * ```
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Clear all keys from PostgreSQL
+     *
+     * **WARNING:** This operation deletes all data from nuvex_storage table.
+     * Use with extreme caution in production environments.
+     *
+     * @example
+     * ```typescript
+     * await postgres.clear(); // Deletes all data
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Health check for PostgreSQL connection
+     *
+     * Executes a simple SELECT 1 query to verify connectivity and database
+     * responsiveness. This is a lightweight operation that tests the full
+     * connection path including pool, connection, and database.
+     *
+     * @returns Promise resolving to true if PostgreSQL is healthy and responsive
+     *
+     * @example
+     * ```typescript
+     * const isHealthy = await postgres.ping();
+     * if (!isHealthy) {
+     *   console.error('PostgreSQL connection is down');
+     * }
+     * ```
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Check if PostgreSQL is connected
+     *
+     * @returns True if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get the PostgreSQL connection pool
+     *
+     * Useful for executing custom queries or transactions.
+     *
+     * @returns The connection pool or null if not connected
+     *
+     * @example
+     * ```typescript
+     * const pool = postgres.getPool();
+     * if (pool) {
+     *   const result = await pool.query('SELECT * FROM custom_table');
+     * }
+     * ```
+     */
+    getPool(): PoolType | null;
+    /**
+     * Atomically increment a numeric value
+     *
+     * Uses PostgreSQL UPDATE with row-level locking for true atomic increments.
+     * If the key doesn't exist, it's created with the delta value.
+     *
+     * This operation is safe for concurrent access across multiple instances.
+     *
+     * @param key - The key to increment
+     * @param delta - The amount to increment by
+     * @param ttlSeconds - Optional TTL in seconds
+     * @returns Promise resolving to the new value after increment
+     *
+     * @example
+     * ```typescript
+     * // Atomic increment - safe for concurrent access
+     * const newValue = await postgres.increment('counter', 1, 86400);
+     * ```
+     */
+    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=postgres.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../../src/layers/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;AAC3C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,qBAAa,eAAgB,YAAW,qBAAqB;IAC3D,iCAAiC;IACjC,OAAO,CAAC,IAAI,CAAkB;IAE9B,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD,oCAAoC;IACpC,OAAO,CAAC,SAAS,CAAU;IAE3B,mDAAmD;IACnD,OAAO,CAAC,MAAM,CAAgB;IAE9B,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IAEnC,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,sBAAsB;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;gBACS,MAAM,EAAE,cAAc,GAAG,QAAQ,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW;IAsB3E;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB9B;;;;;;;;;;OAUG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC;;;;;;;;;;;;;;;;OAgBG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BxC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB1E;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB3C;;;;;;;;;;OAUG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;;;;;;;;;;;;;;OAgBG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAuB9B;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;;;;;;;;OAcG;IACH,OAAO,IAAI,QAAQ,GAAG,IAAI;IAI1B;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0CjF;;;;;;;OAOG;IACH,OAAO,CAAC,GAAG;CAKZ"}

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

@@ -0,0 +1,248 @@
+/**
+ * Nuvex - Redis Storage Layer (L2)
+ * Next-gen Unified Vault Experience
+ *
+ * Redis distributed cache layer providing fast, persistent caching across
+ * multiple application instances. Acts as the middle tier in the storage hierarchy.
+ *
+ * Features:
+ * - Distributed caching for multi-instance deployments
+ * - Fast access times (1-5ms typical)
+ * - Automatic TTL-based expiration
+ * - Connection health monitoring
+ * - Graceful degradation on failures
+ *
+ * @author Waren Gonzaga, WG Technology Labs
+ * @since 2025
+ */
+import type { StorageLayerInterface, Logger } from '../interfaces/index.js';
+/**
+ * Redis Storage Layer - L2 Distributed Cache
+ *
+ * Implements distributed caching using Redis. This layer provides fast access
+ * to frequently used data while supporting multiple application instances.
+ * Redis data persists across application restarts (depending on Redis configuration).
+ *
+ * **Key Features:**
+ * - Distributed cache shared across instances
+ * - Configurable TTL for automatic expiration
+ * - JSON serialization for complex objects
+ * - Graceful error handling with logging
+ * - Connection health monitoring via PING
+ *
+ * **Performance Characteristics:**
+ * - Get: O(1) network + Redis lookup
+ * - Set: O(1) network + Redis write
+ * - Latency: 1-5ms typical (network dependent)
+ *
+ * **Error Handling:**
+ * - Returns null on connection failures
+ * - Logs errors for monitoring
+ * - Doesn't throw to allow graceful degradation
+ *
+ * @implements {StorageLayerInterface}
+ *
+ * @example
+ * ```typescript
+ * // Create Redis layer
+ * const redis = new RedisStorage('redis://localhost:6379');
+ *
+ * // Connect to Redis
+ * await redis.connect();
+ *
+ * // Store with 5 minute TTL
+ * await redis.set('session:abc', sessionData, 300);
+ *
+ * // Retrieve data
+ * const data = await redis.get('session:abc');
+ *
+ * // Check health
+ * const isHealthy = await redis.ping();
+ * ```
+ *
+ * @class RedisStorage
+ * @since 1.0.0
+ */
+export declare class RedisStorage implements StorageLayerInterface {
+    /** Redis client instance */
+    private client;
+    /** Redis connection URL */
+    private readonly url;
+    /** Whether the client is connected */
+    private connected;
+    /** Optional logger for debugging and monitoring */
+    private logger;
+    /**
+     * Creates a new RedisStorage instance
+     *
+     * Note: The instance is created but not connected. Call connect() to establish
+     * the Redis connection.
+     *
+     * @param url - Redis connection URL (e.g., redis://localhost:6379)
+     * @param logger - Optional logger for debugging
+     *
+     * @example
+     * ```typescript
+     * const redis = new RedisStorage('redis://localhost:6379', console);
+     * await redis.connect();
+     * ```
+     */
+    constructor(url: string, logger?: Logger | null);
+    /**
+     * Establish connection to Redis
+     *
+     * Creates and connects the Redis client. Should be called before any
+     * storage operations.
+     *
+     * @throws {Error} If connection fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await redis.connect();
+     *   console.log('Redis connected');
+     * } catch (error) {
+     *   console.error('Redis connection failed:', error);
+     * }
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Close Redis connection
+     *
+     * Gracefully closes the Redis connection. Should be called during
+     * application shutdown.
+     *
+     * @example
+     * ```typescript
+     * await redis.disconnect();
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Retrieve a value from Redis cache
+     *
+     * Deserializes the JSON-stored value. Returns null if the key doesn't exist
+     * or if there's a connection/parsing error.
+     *
+     * @param key - The key to retrieve
+     * @returns Promise resolving to the value or null if not found
+     *
+     * @example
+     * ```typescript
+     * const userData = await redis.get('user:123');
+     * if (userData !== null) {
+     *   console.log('Found in Redis');
+     * }
+     * ```
+     */
+    get(key: string): Promise<unknown>;
+    /**
+     * Store a value in Redis cache
+     *
+     * Serializes the value as JSON and stores it with optional TTL.
+     * If TTL is not provided, the key will persist indefinitely (until manually deleted).
+     *
+     * @param key - The key to store
+     * @param value - The value to store (will be JSON serialized)
+     * @param ttlSeconds - Optional TTL in seconds
+     *
+     * @example
+     * ```typescript
+     * // Store with 1 hour TTL
+     * await redis.set('session:abc', sessionData, 3600);
+     *
+     * // Store without TTL (persists until deleted)
+     * await redis.set('config:app', configData);
+     * ```
+     */
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /**
+     * Delete a value from Redis cache
+     *
+     * @param key - The key to delete
+     *
+     * @example
+     * ```typescript
+     * await redis.delete('session:expired');
+     * ```
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a key exists in Redis cache
+     *
+     * @param key - The key to check
+     * @returns Promise resolving to true if the key exists
+     *
+     * @example
+     * ```typescript
+     * if (await redis.exists('user:123')) {
+     *   console.log('Key exists in Redis');
+     * }
+     * ```
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Clear all keys from Redis database
+     *
+     * **WARNING:** This operation flushes the entire Redis database.
+     * Use with caution in production environments.
+     *
+     * @example
+     * ```typescript
+     * await redis.clear(); // Flushes entire Redis DB
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Health check for Redis connection
+     *
+     * Uses Redis PING command to verify connectivity and responsiveness.
+     * Returns false if not connected or if PING fails.
+     *
+     * @returns Promise resolving to true if Redis is healthy and responsive
+     *
+     * @example
+     * ```typescript
+     * const isHealthy = await redis.ping();
+     * if (!isHealthy) {
+     *   console.error('Redis connection is down');
+     * }
+     * ```
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Check if Redis is connected
+     *
+     * @returns True if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Atomically increment a numeric value
+     *
+     * Uses Redis INCRBY command for true atomic increments that are safe
+     * across multiple instances and concurrent requests.
+     *
+     * @param key - The key to increment
+     * @param delta - The amount to increment by
+     * @param ttlSeconds - Optional TTL in seconds
+     * @returns Promise resolving to the new value after increment
+     *
+     * @example
+     * ```typescript
+     * // Atomic increment - safe for concurrent access
+     * const newValue = await redis.increment('counter', 1, 3600);
+     * ```
+     */
+    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=redis.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../../src/layers/redis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,YAAa,YAAW,qBAAqB;IACxD,4BAA4B;IAC5B,OAAO,CAAC,MAAM,CAAyB;IAEvC,2BAA2B;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,sCAAsC;IACtC,OAAO,CAAC,SAAS,CAAU;IAE3B,mDAAmD;IACnD,OAAO,CAAC,MAAM,CAAgB;IAE9B;;;;;;;;;;;;;;OAcG;gBACS,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW;IAOrD;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB9B;;;;;;;;;;OAUG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC;;;;;;;;;;;;;;;;OAgBG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBxC;;;;;;;;;;;;;;;;;;OAkBG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB1E;;;;;;;;;OASG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgB3C;;;;;;;;;;OAUG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;;;;;;;;;;;;;OAeG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAgB9B;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;;;;;;;;;;OAgBG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBjF;;;;;;;OAOG;IACH,OAAO,CAAC,GAAG;CAKZ"}