@wgtechlabs/nuvex 0.1.1

package/dist/types/core/client.d.ts

@@ -0,0 +1,561 @@
+/**
+ * Nuvex - Client Implementation
+ * Next-gen Unified Vault Experience
+ *
+ * High-level client operations for any Node.js application using the StorageEngine
+ * multi-layer architecture. Provides application-centric methods for storing and
+ * retrieving data with built-in health checks, metrics, and maintenance operations.
+ *
+ * Core Features:
+ * - Generic key-value operations with intelligent caching
+ * - Health monitoring and diagnostics
+ * - Automatic cleanup and maintenance
+ * - Configuration management
+ * - Backup and restore capabilities
+ *
+ * @author Waren Gonzaga, WG Technology Labs
+ * @since 2025
+ */
+import { StorageEngine } from './engine.js';
+import type { NuvexConfig, StorageOptions, BatchOperation, BatchResult, QueryOptions, QueryResult } from '../types/index.js';
+import type { Store as IStore } from '../interfaces/index.js';
+/**
+ * Nuvex Client - High-level storage operations
+ *
+ * Provides a high-level interface for interacting with the multi-layer storage
+ * architecture. Implements the Store interface with additional convenience methods,
+ * health monitoring, backup/restore capabilities, and singleton pattern support.
+ *
+ * @example
+ * ```typescript
+ * // Initialize as singleton
+ * const client = await NuvexClient.initialize({
+ *   postgres: { host: 'localhost', port: 5432, database: 'myapp' },
+ *   redis: { url: 'redis://localhost:6379' },
+ *   memory: { ttl: 3600000, maxSize: 10000 }
+ * });
+ *
+ * // Store and retrieve data
+ * await client.set('user:123', { name: 'John', email: 'john@example.com' });
+ * const user = await client.get('user:123');
+ *
+ * // Use namespacing
+ * await client.setNamespaced('users', '123', userData);
+ * const userData = await client.getNamespaced('users', '123');
+ *
+ * // Perform health checks
+ * const health = await client.healthCheck();
+ * console.log('Storage layers healthy:', health.overall);
+ * ```
+ *
+ * @class NuvexClient
+ * @implements {IStore}
+ * @author Waren Gonzaga, WG Technology Labs
+ * @since 2025
+ */
+export declare class NuvexClient implements IStore {
+    private static instance;
+    private storage;
+    private config;
+    private logger;
+    constructor(config: NuvexConfig);
+    private log;
+    /**
+     * Initialize the Store singleton instance
+     *
+     * Creates a new NuvexClient instance if one doesn't exist and connects to all
+     * configured storage layers. This method ensures only one instance exists
+     * throughout the application lifecycle.
+     *
+     * @param config - Configuration object for all storage layers
+     * @returns Promise that resolves to the initialized NuvexClient instance
+     *
+     * @example
+     * ```typescript
+     * const client = await NuvexClient.initialize({
+     *   postgres: { host: 'localhost', port: 5432, database: 'myapp' },
+     *   redis: { url: 'redis://localhost:6379' },
+     *   memory: { ttl: 3600000, maxSize: 10000 }
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    static initialize(config: NuvexConfig): Promise<NuvexClient>;
+    /**
+     * Get the singleton instance
+     *
+     * Returns the existing NuvexClient instance. Must be called after initialize().
+     *
+     * @returns The singleton NuvexClient instance
+     * @throws {Error} If the store has not been initialized
+     *
+     * @example
+     * ```typescript
+     * // After initialization
+     * const client = NuvexClient.getInstance();
+     * await client.set('key', 'value');
+     * ```
+     *
+     * @since 1.0.0
+     */
+    static getInstance(): NuvexClient;
+    /**
+     * Create a new Store instance (non-singleton)
+     *
+     * Creates a new NuvexClient instance without affecting the singleton.
+     * Useful for testing or when multiple isolated instances are needed.
+     *
+     * @param config - Configuration object for all storage layers
+     * @returns Promise that resolves to a new NuvexClient instance
+     *
+     * @example
+     * ```typescript
+     * const testClient = await NuvexClient.create({
+     *   postgres: testDbConfig,
+     *   memory: { ttl: 1000 }
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    static create(config: NuvexConfig): Promise<NuvexClient>;
+    /**
+     * Connect to all configured storage layers
+     *
+     * Establishes connections to PostgreSQL, Redis (if configured), and initializes
+     * the memory cache. This method is automatically called by initialize() and create().
+     *
+     * @returns Promise that resolves when all connections are established
+     * @throws {Error} If any required storage layer fails to connect
+     *
+     * @since 1.0.0
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from all storage layers
+     *
+     * Cleanly closes all connections and clears the memory cache.
+     * Should be called during application shutdown.
+     *
+     * @returns Promise that resolves when all connections are closed
+     *
+     * @since 1.0.0
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if the client is connected to storage layers
+     *
+     * @returns True if connected to at least the primary storage layer
+     *
+     * @since 1.0.0
+     */
+    isConnected(): boolean;
+    /**
+     * Store a value in the multi-layer storage system
+     *
+     * Stores the value across all available storage layers (Memory → Redis → PostgreSQL)
+     * with intelligent TTL management and layer-specific optimizations.
+     *
+     * @template T - The type of the value being stored
+     * @param key - Unique identifier for the stored value
+     * @param value - The value to store (will be JSON serialized)
+     * @param options - Optional storage configuration
+     * @returns Promise that resolves to true if stored successfully
+     *
+     * @example
+     * ```typescript
+     * // Store with default TTL
+     * await client.set('user:123', { name: 'John', email: 'john@example.com' });
+     *
+     * // Store with custom TTL (60 seconds)
+     * await client.set('session:abc', sessionData, { ttl: 60 });
+     *
+     * // Store only in memory layer
+     * await client.set('cache:temp', data, { layer: StorageLayer.MEMORY });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    set<T = unknown>(key: string, value: T, options?: StorageOptions): Promise<boolean>;
+    /**
+     * Retrieve a value from the multi-layer storage system
+     *
+     * Searches for the value across storage layers in order (Memory → Redis → PostgreSQL)
+     * and automatically promotes the value to higher layers for faster future access.
+     *
+     * @template T - The expected type of the retrieved value
+     * @param key - Unique identifier of the value to retrieve
+     * @param options - Optional retrieval configuration
+     * @returns Promise that resolves to the value or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Get from any layer
+     * const user = await client.get<UserType>('user:123');
+     *
+     * // Get only from PostgreSQL, skip cache
+     * const freshData = await client.get('data:key', { skipCache: true });
+     *
+     * // Get only from memory layer
+     * const cachedData = await client.get('cache:key', { layer: StorageLayer.MEMORY });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    get<T = unknown>(key: string, options?: StorageOptions): Promise<T | null>;
+    /**
+     * Delete a value from all storage layers
+     *
+     * Removes the value from all storage layers to ensure consistency.
+     *
+     * @param key - Unique identifier of the value to delete
+     * @param options - Optional deletion configuration
+     * @returns Promise that resolves to true if deleted successfully
+     *
+     * @example
+     * ```typescript
+     * // Delete from all layers
+     * await client.delete('user:123');
+     *
+     * // Delete only from memory layer
+     * await client.delete('cache:temp', { layer: StorageLayer.MEMORY });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    delete(key: string, options?: StorageOptions): Promise<boolean>;
+    /**
+     * Check if a key exists in any storage layer
+     *
+     * @param key - Unique identifier to check for existence
+     * @param options - Optional configuration to check specific layer
+     * @returns Promise that resolves to true if the key exists
+     *
+     * @example
+     * ```typescript
+     * if (await client.exists('user:123')) {
+     *   console.log('User exists');
+     * }
+     * ```
+     *
+     * @since 1.0.0
+     */
+    exists(key: string, options?: StorageOptions): Promise<boolean>;
+    /**
+     * Set or update the expiration time for a key
+     *
+     * @param key - Unique identifier of the value
+     * @param ttl - Time to live in seconds
+     * @returns Promise that resolves to true if expiration was set successfully
+     *
+     * @example
+     * ```typescript
+     * // Expire in 1 hour
+     * await client.expire('session:abc', 3600);
+     * ```
+     *
+     * @since 1.0.0
+     */
+    expire(key: string, ttl: number): Promise<boolean>;
+    /**
+     * Execute multiple set operations in a batch
+     *
+     * Efficiently executes multiple storage operations with automatic error handling
+     * and transaction-like behavior where possible.
+     *
+     * @param operations - Array of batch operations to execute
+     * @returns Promise that resolves to an array of results for each operation
+     *
+     * @example
+     * ```typescript
+     * const results = await client.setBatch([
+     *   { operation: 'set', key: 'user:1', value: userData1 },
+     *   { operation: 'set', key: 'user:2', value: userData2, options: { ttl: 3600 } }
+     * ]);
+     *
+     * results.forEach((result, index) => {
+     *   console.log(`Operation ${index}: ${result.success ? 'Success' : 'Failed'}`);
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    setBatch(operations: BatchOperation[]): Promise<BatchResult[]>;
+    /**
+     * Retrieve multiple values in a batch
+     *
+     * Efficiently retrieves multiple values with layer optimization and
+     * automatic cache promotion.
+     *
+     * @param keys - Array of keys to retrieve
+     * @param options - Optional configuration applied to all operations
+     * @returns Promise that resolves to an array of results for each key
+     *
+     * @example
+     * ```typescript
+     * const results = await client.getBatch(['user:1', 'user:2', 'user:3']);
+     * const users = results
+     *   .filter(result => result.success && result.value)
+     *   .map(result => result.value);
+     * ```
+     *
+     * @since 1.0.0
+     */
+    getBatch(keys: string[], options?: StorageOptions): Promise<BatchResult[]>;
+    /**
+     * Delete multiple values in a batch
+     *
+     * Efficiently deletes multiple values from all storage layers.
+     *
+     * @param keys - Array of keys to delete
+     * @returns Promise that resolves to an array of results for each key
+     *
+     * @example
+     * ```typescript
+     * const results = await client.deleteBatch(['temp:1', 'temp:2', 'temp:3']);
+     * const deletedCount = results.filter(r => r.success).length;
+     * ```
+     *
+     * @since 1.0.0
+     */
+    deleteBatch(keys: string[]): Promise<BatchResult[]>;
+    query<T = unknown>(options: QueryOptions): Promise<QueryResult<T>>;
+    keys(pattern?: string): Promise<string[]>;
+    clear(pattern?: string): Promise<number>;
+    /**
+     * Get performance metrics for all layers or specific layer(s)
+     *
+     * Returns metrics about storage operations and performance. Can be filtered
+     * to return metrics for specific layers only.
+     *
+     * @param layers - Optional layer(s) to get metrics for. If not provided, returns all metrics.
+     *                 Can be a single layer string, 'all', or array of layer strings.
+     * @returns Object containing requested metrics
+     *
+     * @example
+     * ```typescript
+     * // Get all metrics
+     * const metrics = client.getMetrics();
+     *
+     * // Get specific layer metrics
+     * const memoryMetrics = client.getMetrics('memory');
+     * // { memoryHits, memoryMisses, memorySize, memoryMaxSize }
+     *
+     * // Get multiple layer metrics
+     * const cacheMetrics = client.getMetrics(['memory', 'redis']);
+     * // { memoryHits, memoryMisses, memorySize, memoryMaxSize, redisHits, redisMisses, totalOperations, averageResponseTime, cacheHitRatio }
+     * ```
+     *
+     * @since 1.0.0
+     */
+    getMetrics(layers?: 'memory' | 'redis' | 'postgres' | 'all' | Array<'memory' | 'redis' | 'postgres'>): Record<string, number>;
+    resetMetrics(): void;
+    promote(key: string, targetLayer: string): Promise<boolean>;
+    demote(key: string, targetLayer: string): Promise<boolean>;
+    getLayerInfo(key: string): Promise<{
+        layer: string;
+        ttl?: number;
+    } | null>;
+    /**
+     * Configure the store with new settings
+     */
+    configure(config: Partial<NuvexConfig>): Promise<void>;
+    /**
+     * Get the underlying storage engine
+     *
+     * @internal This method is intended for internal and testing use only.
+     * It provides direct access to the StorageEngine instance.
+     *
+     * @returns The StorageEngine instance used by this client
+     */
+    getEngine(): StorageEngine;
+    /**
+     * Get current configuration
+     */
+    getConfig(): NuvexConfig;
+    /**
+     * Health check for all storage layers or specific layer(s)
+     *
+     * Performs comprehensive health checks on configured storage layers
+     * using the underlying engine's ping() methods for each layer.
+     *
+     * @param layers - Optional layer(s) to check. If not provided, checks all layers.
+     *                 Can be a single layer string or array of layer strings.
+     * @returns Promise that resolves to health status for requested layer(s)
+     *
+     * @example
+     * ```typescript
+     * // Check all layers
+     * const health = await client.healthCheck();
+     * // { memory: true, redis: true, postgres: true }
+     *
+     * // Check specific layer
+     * const redisHealth = await client.healthCheck('redis');
+     * // { redis: true }
+     *
+     * // Check multiple layers
+     * const cacheHealth = await client.healthCheck(['memory', 'redis']);
+     * // { memory: true, redis: true }
+     *
+     * if (!health.redis) {
+     *   console.error('Redis layer is down');
+     * }
+     * ```
+     *
+     * @since 1.0.0
+     */
+    healthCheck(layers?: 'memory' | 'redis' | 'postgres' | Array<'memory' | 'redis' | 'postgres'>): Promise<Record<string, boolean>>;
+    /**
+     * Cleanup expired entries and optimize storage
+     */
+    cleanup(): Promise<{
+        cleaned: number;
+        errors: number;
+    }>;
+    /**
+     * Compact storage and optimize performance
+     */
+    compact(): Promise<void>;
+    /**
+     * Backup storage data to external location with incremental support
+     */
+    backup(destination?: string, options?: {
+        incremental?: boolean;
+        compression?: boolean;
+    }): Promise<string>;
+    /**
+     * Restore storage data from external backup location
+     */
+    restore(source: string, options?: {
+        clearExisting?: boolean;
+        dryRun?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Namespace-aware set operation
+     */
+    setNamespaced(namespace: string, key: string, value: unknown, options?: StorageOptions): Promise<boolean>;
+    /**
+     * Namespace-aware get operation
+     */
+    getNamespaced<T = unknown>(namespace: string, key: string, options?: StorageOptions): Promise<T | null>;
+    /**
+     * Get all keys in a namespace
+     */
+    getNamespaceKeys(namespace: string): Promise<string[]>;
+    /**
+     * Clear entire namespace
+     */
+    clearNamespace(namespace: string): Promise<number>;
+    /**
+     * Atomically increment a numeric value
+     *
+     * This method provides true atomic increments that are safe for concurrent access
+     * across all storage layers. Uses native atomic operations from Redis (INCRBY) and
+     * PostgreSQL (UPDATE with row locks) when available.
+     *
+     * **Thread-Safety:**
+     * - ✅ Safe for concurrent increments to the same key
+     * - ✅ No lost updates in high-concurrency scenarios
+     * - ✅ Works correctly across multiple instances
+     *
+     * **Important:** The key must contain a numeric value (or not exist).
+     * Incrementing a non-numeric value will throw an error.
+     *
+     * **How It Works:**
+     * 1. Uses atomic increment at the authoritative layer (PostgreSQL or Redis)
+     * 2. Propagates the new value to cache layers for consistency
+     * 3. Returns the exact new value after increment
+     *
+     * **Example Usage:**
+     * ```typescript
+     * // ✅ SAFE: Concurrent increments work correctly
+     * await Promise.all([
+     *   client.increment('counter'),  // atomic: 5 → 6
+     *   client.increment('counter')   // atomic: 6 → 7
+     * ]);
+     * // Result: 7 (all increments counted correctly)
+     *
+     * // Custom delta
+     * await client.increment('page_views', 5);
+     *
+     * // With TTL (in milliseconds)
+     * await client.increment('rate_limit', 1, 3600000);
+     * ```
+     *
+     * **Use Cases:**
+     * - ✅ High-concurrency counters (page views, API calls)
+     * - ✅ Critical operations (user credits, inventory)
+     * - ✅ Financial operations requiring exactness
+     * - ✅ Distributed systems with multiple instances
+     *
+     * @param key - The key to increment (must contain numeric value or not exist)
+     * @param delta - The amount to increment by (default: 1)
+     * @param ttl - Optional TTL in milliseconds
+     * @returns Promise resolving to the new value after increment
+     * @throws {Error} If the key contains a non-numeric value
+     */
+    increment(key: string, delta?: number, ttl?: number): Promise<number>;
+    /**
+     * Atomically decrement a numeric value
+     *
+     * This is a convenience method that uses atomic increment with a negative delta.
+     * Provides the same thread-safety guarantees as increment().
+     *
+     * @param key - The key to decrement
+     * @param delta - The amount to decrement by (default: 1)
+     * @param ttl - Optional TTL in milliseconds
+     * @returns Promise resolving to the new value after decrement
+     *
+     * @example
+     * ```typescript
+     * // Decrement by 1
+     * await client.decrement('inventory');
+     *
+     * // Decrement by custom amount
+     * await client.decrement('stock', 5);
+     * ```
+     */
+    decrement(key: string, delta?: number, ttl?: number): Promise<number>;
+    /**
+     * Set if not exists
+     *
+     * Stores a value only if the key does not already exist. Useful for
+     * initializing values that should not be overwritten.
+     *
+     * @note This implementation uses a check-then-set pattern which has a
+     * TOCTOU (Time-of-Check to Time-of-Use) race condition. Between the
+     * `exists()` and `set()` calls, another client could write to the same key.
+     * For critical use cases requiring true atomic set-if-not-exists semantics,
+     * use Redis `SET key value NX` or PostgreSQL `INSERT ... ON CONFLICT DO NOTHING`
+     * directly via the storage layer.
+     *
+     * @template T - The type of the value being stored
+     * @param key - Unique identifier for the stored value
+     * @param value - The value to store if key doesn't exist
+     * @param options - Optional storage configuration
+     * @returns Promise resolving to true if value was set, false if key already existed
+     *
+     * @example
+     * ```typescript
+     * // Initialize a counter only if it doesn't exist
+     * await client.setIfNotExists('counter', 0);
+     * ```
+     */
+    setIfNotExists<T = unknown>(key: string, value: T, options?: StorageOptions): Promise<boolean>;
+    /**
+     * Get multiple keys with a common prefix
+     */
+    getByPrefix<T = unknown>(prefix: string, options?: StorageOptions): Promise<Record<string, T>>;
+    static set<T = unknown>(key: string, value: T, options?: StorageOptions): Promise<boolean>;
+    static get<T = unknown>(key: string, options?: StorageOptions): Promise<T | null>;
+    static delete(key: string, options?: StorageOptions): Promise<boolean>;
+    static exists(key: string, options?: StorageOptions): Promise<boolean>;
+    static healthCheck(layers?: 'memory' | 'redis' | 'postgres' | Array<'memory' | 'redis' | 'postgres'>): Promise<Record<string, boolean>>;
+    static getMetrics(layers?: 'memory' | 'redis' | 'postgres' | 'all' | Array<'memory' | 'redis' | 'postgres'>): Record<string, number>;
+    /**
+     * Shutdown the store and cleanup resources
+     */
+    static shutdown(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/types/core/client.d.ts.map

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

package/dist/types/core/database.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Nuvex - Database Utilities
+ * Next-gen Unified Vault Experience
+ *
+ * Database schema setup and migration utilities for PostgreSQL storage layer.
+ *
+ * @author Waren Gonzaga, WG Technology Labs
+ * @since 2025
+ */
+import type { Pool as PoolType } from 'pg';
+import type { PostgresSchemaConfig } from '../types/index.js';
+import type { Logger } from '../interfaces/index.js';
+/**
+ * Validate SQL identifier to prevent SQL injection
+ * Ensures the identifier contains only alphanumeric characters and underscores
+ *
+ * @param identifier - SQL identifier to validate
+ * @param name - Name of the identifier for error messages
+ * @throws {Error} If identifier contains invalid characters
+ *
+ * @example
+ * ```typescript
+ * validateSQLIdentifier('my_table_123', 'table name'); // OK
+ * validateSQLIdentifier('users; DROP TABLE', 'table name'); // throws Error
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare function validateSQLIdentifier(identifier: string, name: string): void;
+/**
+ * Generate SQL schema for Nuvex storage with configurable table and column names
+ *
+ * @param schema - Optional schema configuration for custom table/column names
+ * @returns SQL string for creating the schema
+ * @throws {Error} If table or column names contain invalid characters
+ */
+export declare function generateNuvexSchemaSQL(schema?: PostgresSchemaConfig): string;
+export declare const NUVEX_SCHEMA_SQL: string;
+export interface SchemaSetupOptions {
+    /** Enable trigram extension for advanced pattern matching (requires pg_trgm) */
+    enableTrigram?: boolean;
+    /** Set up periodic cleanup job using pg_cron extension */
+    enableCleanupJob?: boolean;
+    /** Schema configuration for custom table/column names */
+    schema?: PostgresSchemaConfig;
+}
+/**
+ * Setup Nuvex database schema
+ *
+ * Creates the necessary PostgreSQL tables, indexes, functions, and triggers
+ * required for the Nuvex storage system. This function is idempotent and
+ * can be safely called multiple times.
+ *
+ * Features created:
+ * - `nuvex_storage` table with JSON support and TTL
+ * - Indexes for performance optimization
+ * - Automatic `updated_at` trigger
+ * - Cleanup function for expired entries
+ * - Optional trigram support for pattern matching
+ * - Optional automated cleanup job scheduling
+ *
+ * @param db - PostgreSQL connection pool
+ * @param options - Optional configuration for schema setup
+ * @returns Promise that resolves when schema is created
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from 'pg';
+ * import { setupNuvexSchema } from './database';
+ *
+ * const db = new Pool({ connectionString: 'postgresql://...' });
+ *
+ * // Basic setup
+ * await setupNuvexSchema(db);
+ *
+ * // Advanced setup with all features
+ * await setupNuvexSchema(db, {
+ *   enableTrigram: true,    // Enable pattern matching
+ *   enableCleanupJob: true  // Auto-cleanup expired entries
+ * });
+ * ```
+ *
+ * @throws {Error} If database connection fails or schema creation fails
+ *
+ * @since 1.0.0
+ */
+export declare function setupNuvexSchema(db: PoolType, options?: SchemaSetupOptions, logger?: Logger): Promise<void>;
+/**
+ * Manually clean up expired entries
+ *
+ * Executes the cleanup function to remove all expired entries from the
+ * nuvex_storage table. This can be called manually or as part of a maintenance routine.
+ *
+ * @param db - PostgreSQL connection pool
+ * @returns Promise that resolves to the number of deleted entries
+ *
+ * @example
+ * ```typescript
+ * const deletedCount = await cleanupExpiredEntries(db);
+ * console.log(`Cleaned up ${deletedCount} expired entries`);
+ * ```
+ *
+ * @throws {Error} If the cleanup operation fails
+ *
+ * @since 1.0.0
+ */
+export declare function cleanupExpiredEntries(db: PoolType, schema?: PostgresSchemaConfig, logger?: Logger): Promise<number>;
+/**
+ * Drop Nuvex schema (for cleanup/testing)
+ *
+ * Completely removes all Nuvex-related database objects including tables,
+ * functions, triggers, and indexes. This operation is irreversible and will
+ * result in permanent data loss.
+ *
+ * @param db - PostgreSQL connection pool
+ * @returns Promise that resolves when schema is dropped
+ *
+ * @example
+ * ```typescript
+ * // Use with extreme caution - this will delete all data!
+ * await dropNuvexSchema(testDb); // Only use in tests
+ * ```
+ *
+ * @throws {Error} If the drop operation fails
+ *
+ * @warning This operation is irreversible and will cause permanent data loss
+ * @since 1.0.0
+ */
+export declare function dropNuvexSchema(db: PoolType, schema?: PostgresSchemaConfig, logger?: Logger): Promise<void>;
+//# sourceMappingURL=database.d.ts.map