@gravito/echo 3.0.0 → 3.1.0

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

@@ -0,0 +1,108 @@
+/**
+ * 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;
+    /**
+     * 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,111 @@
+/**
+ * Connection Manager
+ * @description Manages multiple database connections
+ */
+import type { ConnectionConfig, ConnectionContract } 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 readonly MAX_IDLE_TIME;
+    private readonly CLEANUP_INTERVAL;
+    constructor(configs?: Record<string, ConnectionConfig>);
+    /**
+     * 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;
+    /**
+     * Add a connection configuration.
+     *
+     * @param name - Unique name for the connection.
+     * @param config - Connection configuration settings.
+     */
+    addConnection(name: string, config: ConnectionConfig): 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): ConnectionConfig | 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;
+    /**
+     * Shutdown the connection manager.
+     * Stops the idle cleanup interval and disconnects all connections.
+     *
+     * @returns A promise that resolves when shutdown is complete.
+     */
+    shutdown(): Promise<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,66 @@
+/**
+ * MySQL/MariaDB Driver
+ * @description Database driver for MySQL and MariaDB using mysql2 package
+ */
+import type { ConnectionConfig, DriverContract, DriverType, ExecuteResult, QueryResult } from '../types';
+export declare class MySQLDriver implements DriverContract {
+    private readonly config;
+    private readonly driverType;
+    private pool;
+    private transactionConnection;
+    private connected;
+    private mysql;
+    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 a connection from the pool
+     */
+    private getConnection;
+    /**
+     * Normalize MySQL/MariaDB errors
+     */
+    private normalizeError;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * PostgreSQL Driver
+ * @description Database driver implementation for PostgreSQL using node-pg
+ */
+import type { DriverContract, DriverType, ExecuteResult, PostgresConfig, QueryResult } from '../types';
+/**
+ * PostgreSQL Driver
+ * Connects and executes queries against PostgreSQL databases
+ */
+export declare class PostgresDriver implements DriverContract {
+    private readonly config;
+    private pool;
+    private connected;
+    private transactionActive;
+    private transactionClient;
+    private preparedStatements;
+    private statementCounter;
+    constructor(config: PostgresConfig);
+    /**
+     * Get driver name
+     */
+    getDriverName(): DriverType;
+    /**
+     * Connect to the database
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the database
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Execute a query and return results
+     */
+    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>;
+    /**
+     * Prepare a statement for repeated execution
+     */
+    prepare(sql: string): Promise<string>;
+    /**
+     * Execute a prepared statement
+     */
+    executePrepared<T>(name: string, bindings?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Clear all prepared statements
+     */
+    clearPreparedStatements(): Promise<void>;
+    /**
+     * Begin a transaction
+     */
+    beginTransaction(): Promise<void>;
+    /**
+     * Commit the current transaction
+     */
+    commit(): Promise<void>;
+    /**
+     * Rollback the current transaction
+     */
+    rollback(): Promise<void>;
+    /**
+     * Check if currently in a transaction
+     */
+    inTransaction(): boolean;
+    /**
+     * Get a client for executing queries
+     */
+    private getClient;
+    /**
+     * Normalize PostgreSQL errors
+     */
+    private normalizeError;
+    /**
+     * Dynamically load the pg module
+     */
+    private loadPgModule;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Redis Driver
+ * @description Driver implementation for Redis using ioredis
+ */
+import type { ConnectionConfig, DriverContract, DriverType, ExecuteResult, QueryResult } from '../types';
+/**
+ * Redis Driver
+ * Provides a key-value interface via DB.connection('redis')
+ */
+import type { RedisClient } from './types';
+export declare class RedisDriver implements DriverContract {
+    private config;
+    private client;
+    private RedisCtor?;
+    constructor(config: ConnectionConfig, deps?: {
+        Redis?: new (config: Record<string, unknown>) => RedisClient;
+    });
+    getDriverName(): DriverType;
+    connect(): Promise<void>;
+    /**
+     * Dynamically load ioredis module
+     */
+    private loadRedisModule;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /**
+     * Raw Redis command execution via pseudo-SQL or direct mapping
+     */
+    query<T = any>(_sql: string, _bindings?: unknown[]): Promise<QueryResult<T>>;
+    execute(_sql: string, _bindings?: unknown[]): Promise<ExecuteResult>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string | number): Promise<'OK'>;
+    setex(key: string, seconds: number, value: string | number): Promise<'OK'>;
+    del(key: string): Promise<number>;
+    /**
+     * Get the raw ioredis client for advanced operations
+     */
+    getRawClient(): RedisClient | null;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    inTransaction(): boolean;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * SQLite Driver
+ * @description Database driver implementation for SQLite using better-sqlite3
+ */
+import type { ConnectionConfig, DriverContract, DriverType, ExecuteResult, QueryResult } from '../types';
+/**
+
+ * SQLite Driver
+
+ */
+/**
+ * SQLite driver implementation for Atlas ORM.
+ *
+ * Automatically detects and uses `bun:sqlite` if running in Bun,
+ * otherwise falls back to `better-sqlite3`.
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare class SQLiteDriver implements DriverContract {
+    private config;
+    private client;
+    private inTransactionState;
+    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>;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    inTransaction(): boolean;
+    /**
+  
+  
+  
+       * Normalize SQLite errors
+  
+  
+  
+       */
+    private normalizeError;
+}