@gravito/ripple 3.1.0 → 4.0.1

package/dist/atlas/src/OrbitAtlas.d.ts

@@ -0,0 +1,9 @@
+import type { GravitoOrbit, PlanetCore } from '@gravito/core';
+/**
+ * Atlas Orbit - Database & ORM Integration
+ * Integrates the Atlas ORM engine into the Gravito Core ecosystem.
+ * @public
+ */
+export declare class OrbitAtlas implements GravitoOrbit {
+    install(core: PlanetCore): Promise<void>;
+}

package/dist/atlas/src/config/defineConfig.d.ts

@@ -0,0 +1,14 @@
+import type { AtlasConfig, AtlasObservabilityConfig, ConnectionConfig, PostgresConfig } from '../types';
+export type { AtlasConfig, AtlasObservabilityConfig, ConnectionConfig, PostgresConfig };
+/**
+ * Define configuration with type checking
+ */
+export declare function defineConfig(config: AtlasConfig): AtlasConfig;
+/**
+ * Load configuration from environment variables with optional prefix
+ * Supports both DATABASE_URL and individual DB_* variables
+ *
+ * @param connectionName - Name for the connection
+ * @param prefix - Optional prefix for environment variables (e.g., 'READ' for DB_READ_*)
+ */
+export declare function fromEnv(connectionName?: string, prefix?: string): AtlasConfig;

package/dist/atlas/src/config/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Configuration Module
+ * @description Database configuration utilities
+ */
+export type { AtlasConfig, ConnectionConfig } from '../types';
+export { defineConfig, fromEnv } from './defineConfig';
+export { loadConfig, loadConfigFile } from './loadConfig';

package/dist/atlas/src/config/loadConfig.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Configuration Loader
+ * @description Load database configuration from various sources
+ */
+import type { AtlasConfig } from '../types';
+/**
+ * Load configuration from a TypeScript/JavaScript config file
+ *
+ * @param configPath - Path to the config file (default: 'config/database.ts' or 'config/database.js')
+ * @returns Atlas configuration
+ *
+ * @example
+ * ```typescript
+ * // config/database.ts
+ * import { defineConfig } from '@gravito/atlas'
+ *
+ * export default defineConfig({
+ *   default: 'default',
+ *   connections: {
+ *     default: {
+ *       driver: 'postgres',
+ *       host: 'localhost',
+ *       database: 'myapp'
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function loadConfigFile(configPath?: string): Promise<AtlasConfig>;
+/**
+ * Load configuration from multiple sources with priority
+ * Priority: 1. Config file, 2. Environment variables, 3. Default
+ *
+ * @param options - Loading options
+ * @returns Atlas configuration
+ */
+export declare function loadConfig(options?: {
+    configPath?: string;
+    useEnv?: boolean;
+    envPrefix?: string;
+}): Promise<AtlasConfig>;

package/dist/atlas/src/connection/Connection.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Connection
+ * @description Represents a database connection
+ */
+import type { AtlasMetrics, AtlasTracer } from '../observability';
+import type { ConnectionConfig, ConnectionContract, DriverContract, ExecuteResult, GrammarContract, PoolStats, QueryBuilderContract, QueryResult } from '../types';
+/**
+ * Database Connection
+ * Wraps a driver and grammar for query building and execution
+ */
+export declare class Connection implements ConnectionContract {
+    protected readonly name: string;
+    protected readonly config: ConnectionConfig;
+    protected driver: DriverContract;
+    protected grammar: GrammarContract;
+    protected connected: boolean;
+    protected proxy?: ConnectionContract;
+    protected tracer: AtlasTracer | undefined;
+    protected metrics: AtlasMetrics | undefined;
+    /**
+     * Static query listeners for global observation (e.g. debugging)
+     */
+    static queryListeners: Array<(query: {
+        connection: string;
+        sql: string;
+        bindings: unknown[];
+        duration: number;
+        timestamp: number;
+    }) => void>;
+    constructor(name: string, config: ConnectionConfig);
+    /**
+     * Set the proxy instance for this connection
+     */
+    setProxy(proxy: ConnectionContract): void;
+    /**
+     * Get connection name
+     */
+    getName(): string;
+    /**
+     * Get the underlying driver
+     */
+    getDriver(): DriverContract;
+    /**
+     * Get connection configuration
+     */
+    getConfig(): ConnectionConfig;
+    /**
+     * Get the grammar
+     */
+    getGrammar(): GrammarContract;
+    /**
+     * Get the tracer
+     */
+    getTracer(): AtlasTracer | undefined;
+    /**
+     * Get the metrics
+     */
+    getMetrics(): AtlasMetrics | undefined;
+    /**
+     * Create a new query builder for a table
+     */
+    table<T = Record<string, unknown>>(tableName: string): QueryBuilderContract<T>;
+    /**
+     * Alias for table() for NoSQL connections
+     */
+    collection<T = Record<string, unknown>>(name: string): QueryBuilderContract<T>;
+    /**
+     * Execute raw SQL
+     */
+    raw<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Execute raw SQL statement (INSERT/UPDATE/DELETE)
+     */
+    execute(sql: string, bindings?: unknown[]): Promise<ExecuteResult>;
+    /**
+     * Run a callback within a transaction
+     */
+    transaction<T>(callback: (connection: ConnectionContract) => Promise<T>): Promise<T>;
+    /**
+     * Stream query results for processing large datasets
+     * @param sql - SQL query
+     * @param bindings - Query parameters
+     * @returns Async iterable of result rows
+     */
+    stream<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): AsyncIterable<T>;
+    /**
+     * Get connection pool statistics (if supported by driver)
+     * @returns Pool statistics or null if not supported
+     */
+    getPoolStats(): PoolStats | null;
+    /**
+     * Disconnect from the database
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Connect to the database
+     */
+    connect(): Promise<void>;
+    /**
+     * Ensure connection is established
+     */
+    protected ensureConnected(): Promise<void>;
+    /**
+     * Create the driver instance based on config
+     * Automatically prefers Bun.sql native driver when available (unless explicitly disabled)
+     */
+    protected createDriver(): DriverContract;
+    /**
+     * Create the grammar instance based on config
+     */
+    protected createGrammar(): GrammarContract;
+}

package/dist/atlas/src/connection/ConnectionManager.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Connection Manager
+ * @description Manages multiple database connections
+ */
+import { type AdaptivePoolConfig, AdaptivePoolManager } from '../pool/AdaptivePoolManager';
+import { type PoolHealthCheckConfig } from '../pool/PoolHealthChecker';
+import { type PoolWarmerConfig } from '../pool/PoolWarmer';
+import type { AtlasConnectionEntry, ConnectionContract, PoolHealth } from '../types';
+/**
+ * Connection Manager
+ *
+ * Responsible for managing the lifecycle of database connections.
+ * It handles connection pooling (via drivers), lazy initialization,
+ * and automatic cleanup of idle connections.
+ *
+ * Connections are stored in a Map and retrieved by name. If a connection
+ * hasn't been initialized, the manager creates it using the provided configuration.
+ */
+export declare class ConnectionManager {
+    private readonly configs;
+    private connections;
+    private defaultConnectionName;
+    private lastUsed;
+    private cleanupInterval?;
+    private healthChecker?;
+    private warmer?;
+    private adaptiveManager?;
+    /** Replica pools keyed by connection name */
+    private replicaPools;
+    private readonly MAX_IDLE_TIME;
+    private readonly CLEANUP_INTERVAL;
+    constructor(configs?: Record<string, AtlasConnectionEntry>);
+    /**
+     * Get a connection instance by name.
+     * If the connection is not already initialized, it will be created.
+     *
+     * @param name - Optional connection name (defaults to 'default').
+     * @returns The connection instance.
+     * @throws Error if the connection is not configured.
+     */
+    connection(name?: string): ConnectionContract;
+    /**
+     * Get the read replica connection for a named connection.
+     * Returns the round-robin selected read replica, or the write connection
+     * if no replicas are configured.
+     *
+     * @param name - Connection name (defaults to default)
+     */
+    readConnection(name?: string): ConnectionContract;
+    /**
+     * Get the write (primary) connection for a named connection.
+     *
+     * @param name - Connection name (defaults to default)
+     */
+    writeConnection(name?: string): ConnectionContract;
+    /**
+     * Check whether a given connection has read replicas.
+     */
+    hasReplicas(name?: string): boolean;
+    /**
+     * Build and register a Connection instance, wrapping it in a Proxy.
+     * @internal
+     */
+    private _buildAndRegisterConnection;
+    /**
+     * Build a proxy-wrapped Connection from config without registering.
+     * @internal
+     */
+    private _buildConnection;
+    /**
+     * Add a connection configuration.
+     *
+     * @param name - Unique name for the connection.
+     * @param config - Connection configuration settings (standard or read/write replica).
+     */
+    addConnection(name: string, config: AtlasConnectionEntry): void;
+    /**
+     * Set the default connection name.
+     *
+     * @param name - The name of the default connection.
+     */
+    setDefaultConnection(name: string): void;
+    /**
+     * Get the default connection name.
+     *
+     * @returns The default connection name.
+     */
+    getDefaultConnection(): string;
+    /**
+     * Check if a connection configuration exists.
+     *
+     * @param name - The connection name to check.
+     * @returns True if the connection is configured.
+     */
+    hasConnection(name: string): boolean;
+    /**
+     * Get all configured connection names.
+     *
+     * @returns Array of connection names.
+     */
+    getConnectionNames(): string[];
+    /**
+     * Get the configuration for a specific connection.
+     *
+     * @param name - The connection name.
+     * @returns The connection configuration or undefined if not found.
+     */
+    getConfig(name: string): AtlasConnectionEntry | undefined;
+    /**
+     * Disconnect all active connections.
+     *
+     * @returns A promise that resolves when all connections are closed.
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * Disconnect a specific connection by name.
+     *
+     * @param name - Optional connection name (defaults to default).
+     * @returns A promise that resolves when the connection is closed.
+     */
+    disconnect(name?: string): Promise<void>;
+    /**
+     * Purge a connection from the manager's cache.
+     * This will NOT disconnect the connection if it's already active.
+     *
+     * @param name - Optional connection name.
+     */
+    purge(name?: string): void;
+    /**
+     * Reconnect to a connection.
+     * This will disconnect the existing connection and create a new one.
+     *
+     * @param name - Optional connection name.
+     * @returns The new connection instance.
+     */
+    reconnect(name?: string): Promise<ConnectionContract>;
+    private cleanupIdleConnections;
+    private startCleanup;
+    stopCleanup(): void;
+    /**
+     * Enable connection pool health checking
+     */
+    enableHealthCheck(config?: Partial<PoolHealthCheckConfig>): void;
+    /**
+     * Disable connection pool health checking
+     */
+    disableHealthCheck(): void;
+    /**
+     * Get connection pool health status
+     */
+    getHealthStatus(connectionName?: string): PoolHealth | Map<string, PoolHealth>;
+    /**
+     * Enable connection pool warming
+     */
+    enableWarmup(config?: Partial<PoolWarmerConfig>): void;
+    /**
+     * Warm up all connection pools
+     */
+    warmup(): Promise<any>;
+    /**
+     * Enable adaptive connection pool management
+     * Automatically adjusts pool sizes based on load patterns
+     */
+    enableAdaptive(config?: Partial<AdaptivePoolConfig>): void;
+    /**
+     * Disable adaptive connection pool management
+     */
+    disableAdaptive(): void;
+    /**
+     * Get adaptive pool manager instance (if enabled)
+     */
+    getAdaptiveManager(): AdaptivePoolManager | undefined;
+    /**
+     * Shutdown the connection manager.
+     * Stops the idle cleanup interval, health checking, adaptive management, and disconnects all connections.
+     *
+     * @returns A promise that resolves when shutdown is complete.
+     */
+    shutdown(): Promise<void>;
+}

package/dist/atlas/src/connection/ReplicaConnectionPool.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @gravito/atlas - Replica Connection Pool
+ * @description Manages read/write replica connections with Round-robin load balancing.
+ *
+ * Wraps a write (primary) connection and a pool of read (replica) connections.
+ * Transparently routes SELECT queries to read replicas and mutations to the primary.
+ */
+import type { ConnectionContract } from '../types';
+/**
+ * ReplicaConnectionPool
+ *
+ * Holds one authoritative write connection and N read replica connections.
+ * Applies Round-robin selection across replicas to balance read load.
+ *
+ * Usage:
+ * ```typescript
+ * const pool = new ReplicaConnectionPool(writeConn, [replica1, replica2])
+ * const readConn = pool.getReadConnection()    // Round-robin
+ * const writeConn = pool.getWriteConnection()  // Always primary
+ * ```
+ */
+export declare class ReplicaConnectionPool {
+    private readonly writeConnection;
+    private readonly readConnections;
+    private roundRobinIndex;
+    constructor(writeConnection: ConnectionContract, readConnections?: ConnectionContract[]);
+    /**
+     * Get the primary write connection (always the same node).
+     */
+    getWriteConnection(): ConnectionContract;
+    /**
+     * Get a read replica connection using Round-robin selection.
+     *
+     * Falls back to the write connection if no replicas are configured.
+     */
+    getReadConnection(): ConnectionContract;
+    /**
+     * Whether this pool has any read replicas configured.
+     */
+    hasReplicas(): boolean;
+    /**
+     * Total number of replica connections in the pool.
+     */
+    replicaCount(): number;
+    /**
+     * Disconnect all connections (write + all replicas).
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * Reset round-robin index (useful for testing).
+     * @internal
+     */
+    _resetIndex(): void;
+}

package/dist/atlas/src/drivers/BunSQLDriver.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bun Native SQL Driver
+ */
+import type { ConnectionConfig, DriverContract, DriverType, ExecuteResult, PoolStats, QueryResult } from '../types';
+export declare class BunSQLDriver implements DriverContract {
+    private readonly config;
+    private client;
+    private sqliteClient;
+    private connected;
+    private transactionActive;
+    private preparedManager?;
+    constructor(config: ConnectionConfig);
+    getDriverName(): DriverType;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    query<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<QueryResult<T>>;
+    execute(sql: string, bindings?: unknown[]): Promise<ExecuteResult>;
+    private normalizeBindings;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    inTransaction(): boolean;
+    private ensureConnection;
+    private getConnectionUrl;
+    prepare(sql: string): Promise<string>;
+    executePrepared<T = Record<string, unknown>>(name: string, bindings?: unknown[]): Promise<QueryResult<T>>;
+    clearPreparedStatements(): Promise<void>;
+    stream<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): AsyncIterable<T>;
+    getPoolStats(): PoolStats | null;
+    private normalizeError;
+}

package/dist/atlas/src/drivers/BunSQLPreparedStatement.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Bun SQL Prepared Statement Manager
+ * @description Manages prepared statement caching, lifecycle, and optimization
+ */
+import type { BunSQLClient } from './types';
+/**
+ * Configuration options for prepared statement manager
+ */
+export interface PreparedStatementManagerConfig {
+    /**
+     * Maximum number of prepared statements to cache
+     * @default 100
+     */
+    maxStatements?: number;
+    /**
+     * Idle timeout in milliseconds before a statement is removed
+     * @default 60000 (1 minute)
+     */
+    idleTimeout?: number;
+}
+/**
+ * Prepared Statement Manager for BunSQL
+ *
+ * Manages statement caching and lifecycle to optimize query performance.
+ * Features:
+ * - LRU (Least Recently Used) cache eviction
+ * - Idle timeout cleanup
+ * - Usage statistics tracking
+ *
+ * @example
+ * ```typescript
+ * const manager = new BunSQLPreparedStatementManager(client)
+ *
+ * // Prepare a statement
+ * const stmtId = await manager.prepare('SELECT * FROM users WHERE id = ?')
+ *
+ * // Execute multiple times
+ * const users1 = await manager.execute(stmtId, [1])
+ * const users2 = await manager.execute(stmtId, [2])
+ *
+ * // Clean up
+ * await manager.clear()
+ * ```
+ */
+export declare class BunSQLPreparedStatementManager {
+    private readonly client;
+    private statements;
+    private sqlToName;
+    private readonly config;
+    private cleanupTimer?;
+    constructor(client: BunSQLClient, config?: PreparedStatementManagerConfig);
+    /**
+     * Prepare a SQL statement for repeated execution
+     *
+     * @param sql - SQL query to prepare
+     * @returns Prepared statement identifier
+     */
+    prepare(sql: string): Promise<string>;
+    /**
+     * Execute a prepared statement
+     *
+     * @param name - Prepared statement identifier
+     * @param bindings - Query parameters
+     * @returns Query result rows
+     */
+    execute<T = Record<string, unknown>>(name: string, bindings?: unknown[]): Promise<T[]>;
+    /**
+     * Clear all prepared statements
+     */
+    clear(): Promise<void>;
+    /**
+     * Clean up idle statements
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get statement usage statistics
+     *
+     * @param name - Prepared statement identifier
+     * @returns Usage statistics or null if not found
+     */
+    getStats(name: string): {
+        useCount: number;
+        lastUsed: number;
+    } | null;
+    /**
+     * Get the number of cached statements
+     */
+    getSize(): number;
+    /**
+     * Destroy the manager and clean up resources
+     */
+    destroy(): Promise<void>;
+    /**
+     * Evict the least recently used statement
+     * @private
+     */
+    private evictLeastRecentlyUsed;
+    /**
+     * Generate a unique statement name
+     * @private
+     */
+    private generateStatementName;
+    /**
+     * Simple hash function for SQL strings
+     * @private
+     */
+    private simpleHash;
+    /**
+     * Start periodic cleanup timer
+     * @private
+     */
+    private startCleanupTimer;
+    /**
+     * Stop cleanup timer
+     * @private
+     */
+    private stopCleanupTimer;
+}

package/dist/atlas/src/drivers/MongoDBDriver.d.ts

@@ -0,0 +1,36 @@
+import type { ConnectionConfig, DriverContract, DriverType, ExecuteResult, QueryResult } from '../types';
+/**
+ * MongoDB Driver
+ * Provides a document interface via DB.connection('mongodb')
+ */
+import type { MongoClient } from './types';
+export declare class MongoDBDriver implements DriverContract {
+    private config;
+    private client;
+    private db;
+    private MongoClientCtor?;
+    constructor(config: ConnectionConfig, deps?: {
+        MongoClient?: new (url: string, options?: Record<string, unknown>) => MongoClient;
+    });
+    getDriverName(): DriverType;
+    connect(): Promise<void>;
+    /**
+     * Dynamically load mongodb module
+     */
+    private loadMongoModule;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /**
+     * Execute a query (Protocol: JSON String)
+     */
+    query<T = Record<string, unknown>>(protocolJson: string, _bindings?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Execute a write operation (Protocol: JSON String)
+     */
+    execute(protocolJson: string, _bindings?: unknown[]): Promise<ExecuteResult>;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    inTransaction(): boolean;
+    private mapDocument;
+}

package/dist/atlas/src/drivers/MySQLDriver.d.ts

@@ -0,0 +1,79 @@
+/**
+ * MySQL/MariaDB Driver
+ * @description Database driver for MySQL and MariaDB using mysql2 package
+ */
+import type { ConnectionConfig, DriverContract, DriverType, ExecuteResult, PoolHealth, PoolStats, QueryResult } from '../types';
+export declare class MySQLDriver implements DriverContract {
+    private pool;
+    private transactionConnection;
+    private connected;
+    private mysql;
+    private poolConfig;
+    private readonly driverType;
+    constructor(config: ConnectionConfig, driverType?: 'mysql' | 'mariadb');
+    /**
+     * Get the driver name
+     */
+    getDriverName(): DriverType;
+    /**
+     * Connect to MySQL/MariaDB
+     */
+    connect(): Promise<void>;
+    /**
+     * Dynamically load mysql2 module
+     */
+    private loadMySQLModule;
+    /**
+     * Disconnect from MySQL
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Execute a query
+     */
+    query<T = Record<string, unknown>>(sql: string, bindings?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Execute a statement (INSERT/UPDATE/DELETE)
+     */
+    execute(sql: string, bindings?: unknown[]): Promise<ExecuteResult>;
+    /**
+     * Begin a transaction
+     */
+    beginTransaction(): Promise<void>;
+    /**
+     * Commit the current transaction
+     */
+    commit(): Promise<void>;
+    /**
+     * Rollback the current transaction
+     */
+    rollback(): Promise<void>;
+    /**
+     * Check if in transaction
+     */
+    inTransaction(): boolean;
+    /**
+     * Get connection pool statistics
+     */
+    getPoolStats(): PoolStats | null;
+    /**
+     * Get connection pool health status
+     */
+    getPoolHealth(): PoolHealth;
+    /**
+     * Adjust the connection pool size
+     * Note: mysql2 Pool doesn't support dynamic resizing, so we reconnect with new size
+     */
+    adjustPoolSize(targetSize: number): Promise<void>;
+    /**
+     * Get a connection from the pool
+     */
+    private getConnection;
+    /**
+     * Normalize MySQL/MariaDB errors
+     */
+    private normalizeError;
+}