@gravito/ripple 4.0.0 → 4.0.1

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

@@ -1,5 +1,6 @@
 import { type AtlasMetrics, type AtlasTracer } from './observability';
-import type { AtlasConfig, CacheInterface, ConnectionConfig, ConnectionContract, QueryBuilderContract, QueryResult } from './types';
+import type { ShardingManager } from './sharding/ShardingManager';
+import type { AtlasConfig, AtlasConnectionEntry, CacheInterface, ConnectionContract, QueryBuilderContract, QueryResult } from './types';
 /**
  * DB Facade - Static entry point for database operations.
  *
@@ -24,12 +25,27 @@ import type { AtlasConfig, CacheInterface, ConnectionConfig, ConnectionContract,
  */
 export declare class DB {
     private static manager;
+    private static shardingManagers;
     private static initialized;
     private static cache;
     private static _debug;
     private static _queryLog;
     private static readonly MAX_LOG_SIZE;
     private static queryListener?;
+    /**
+     * Registers a ShardingManager for distributed database architectures.
+     *
+     * @param name - Unique identifier for the sharding cluster
+     * @param manager - The initialized ShardingManager instance
+     */
+    static addShardingManager(name: string, manager: ShardingManager): void;
+    /**
+     * Retrieves a registered ShardingManager.
+     *
+     * @param name - Name of the sharding cluster (defaults to 'default')
+     * @throws Error if the manager is not found
+     */
+    static getShardingManager(name?: string): ShardingManager;
     /**
      * Sets the global cache provider for query results.
      *
@@ -165,9 +181,9 @@ export declare class DB {
      * Manually adds a connection to the manager.
      *
      * @param name - Unique connection name.
-     * @param config - Connection settings.
+     * @param config - Connection settings (standard or read/write replica).
      */
-    static addConnection(name: string, config: ConnectionConfig): void;
+    static addConnection(name: string, config: AtlasConnectionEntry): void;
     /**
      * Adds a connection configured via prefixed environment variables.
      *
@@ -193,6 +209,23 @@ export declare class DB {
      * @throws {Error} If DB is not configured or connection name is unknown.
      */
     static connection(name?: string): ConnectionContract;
+    /**
+     * Retrieves the read replica connection for the given connection name.
+     *
+     * Uses round-robin selection across configured read replicas.
+     * Falls back to the primary connection if no replicas are configured.
+     *
+     * @param name - Connection name (defaults to global default)
+     */
+    static readConnection(name?: string): ConnectionContract;
+    /**
+     * Retrieves the write (primary) connection for the given connection name.
+     *
+     * Use this to force a query to run on the primary even inside a read context.
+     *
+     * @param name - Connection name (defaults to global default)
+     */
+    static writeConnection(name?: string): ConnectionContract;
     /**
      * Checks if a specific connection has been configured.
      */
@@ -204,7 +237,7 @@ export declare class DB {
     /**
      * Retrieves the raw configuration for a connection.
      */
-    static getConnectionConfig(name?: string): ConnectionConfig | undefined;
+    static getConnectionConfig(name?: string): AtlasConnectionEntry | undefined;
     /**
      * Initializes a fluent query builder for a specific table.
      *
@@ -243,6 +276,20 @@ export declare class DB {
      * @returns The callback's return value.
      */
     static transaction<T>(callback: (connection: ConnectionContract) => Promise<T>, connectionName?: string): Promise<T>;
+    /**
+     * Executes logic within a managed database transaction with automatic retry on serialization/stale data failures.
+     *
+     * Particularly useful for high-concurrency environments utilizing optimistic locking,
+     * where `StaleModelError` is thrown due to concurrent writes.
+     *
+     * @template T - Logic result type.
+     * @param callback - The transactional logic.
+     * @param connectionName - Optional specific connection.
+     * @param maxRetries - Maximum number of retries (default: 5).
+     * @returns The callback's return value.
+     * @throws Rethrows the error if max retries are exceeded.
+     */
+    static transactionWithRetry<T>(callback: (connection: ConnectionContract, attempt: number) => Promise<T>, connectionName?: string, maxRetries?: number): Promise<T>;
     /**
      * Manually starts a database transaction.
      *

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

@@ -4,4 +4,4 @@
  */
 export type { AtlasConfig, ConnectionConfig } from '../types';
 export { defineConfig, fromEnv } from './defineConfig';
-export { autoConfigure, loadConfig, loadConfigFile } from './loadConfig';
+export { loadConfig, loadConfigFile } from './loadConfig';

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

@@ -39,10 +39,3 @@ export declare function loadConfig(options?: {
     useEnv?: boolean;
     envPrefix?: string;
 }): Promise<AtlasConfig>;
-/**
- * Auto-configure database from config file or environment
- * This is a convenience function that tries config file first, then environment
- *
- * @param configPath - Optional path to config file
- */
-export declare function autoConfigure(configPath?: string): Promise<void>;

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

@@ -52,6 +52,10 @@ export declare class Connection implements ConnectionContract {
      * Get the tracer
      */
     getTracer(): AtlasTracer | undefined;
+    /**
+     * Get the metrics
+     */
+    getMetrics(): AtlasMetrics | undefined;
     /**
      * Create a new query builder for a table
      */

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

@@ -2,7 +2,10 @@
  * Connection Manager
  * @description Manages multiple database connections
  */
-import type { ConnectionConfig, ConnectionContract } from '../types';
+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
  *
@@ -19,9 +22,14 @@ export declare class ConnectionManager {
     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, ConnectionConfig>);
+    constructor(configs?: Record<string, AtlasConnectionEntry>);
     /**
      * Get a connection instance by name.
      * If the connection is not already initialized, it will be created.
@@ -31,13 +39,41 @@ export declare class ConnectionManager {
      * @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.
+     * @param config - Connection configuration settings (standard or read/write replica).
      */
-    addConnection(name: string, config: ConnectionConfig): void;
+    addConnection(name: string, config: AtlasConnectionEntry): void;
     /**
      * Set the default connection name.
      *
@@ -69,7 +105,7 @@ export declare class ConnectionManager {
      * @param name - The connection name.
      * @returns The connection configuration or undefined if not found.
      */
-    getConfig(name: string): ConnectionConfig | undefined;
+    getConfig(name: string): AtlasConnectionEntry | undefined;
     /**
      * Disconnect all active connections.
      *
@@ -101,9 +137,42 @@ export declare class ConnectionManager {
     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 and disconnects all connections.
+     * Stops the idle cleanup interval, health checking, adaptive management, and disconnects all connections.
      *
      * @returns A promise that resolves when shutdown is complete.
      */

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/MySQLDriver.d.ts

@@ -2,14 +2,14 @@
  * MySQL/MariaDB Driver
  * @description Database driver for MySQL and MariaDB using mysql2 package
  */
-import type { ConnectionConfig, DriverContract, DriverType, ExecuteResult, QueryResult } from '../types';
+import type { ConnectionConfig, DriverContract, DriverType, ExecuteResult, PoolHealth, PoolStats, QueryResult } from '../types';
 export declare class MySQLDriver implements DriverContract {
-    private readonly config;
-    private readonly driverType;
     private pool;
     private transactionConnection;
     private connected;
     private mysql;
+    private poolConfig;
+    private readonly driverType;
     constructor(config: ConnectionConfig, driverType?: 'mysql' | 'mariadb');
     /**
      * Get the driver name
@@ -55,6 +55,19 @@ export declare class MySQLDriver implements DriverContract {
      * 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
      */

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

@@ -2,19 +2,19 @@
  * PostgreSQL Driver
  * @description Database driver implementation for PostgreSQL using node-pg
  */
-import type { DriverContract, DriverType, ExecuteResult, PostgresConfig, QueryResult } from '../types';
+import type { DriverContract, DriverType, ExecuteResult, PoolHealth, PoolStats, 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;
+    private poolConfig;
     constructor(config: PostgresConfig);
     /**
      * Get driver name
@@ -68,6 +68,19 @@ export declare class PostgresDriver implements DriverContract {
      * Check if currently in a transaction
      */
     inTransaction(): boolean;
+    /**
+     * Get connection pool statistics
+     */
+    getPoolStats(): PoolStats | null;
+    /**
+     * Get connection pool health status
+     */
+    getPoolHealth(): PoolHealth;
+    /**
+     * Adjust the connection pool size
+     * Note: pg Pool doesn't support dynamic resizing, so we reconnect with new size
+     */
+    adjustPoolSize(targetSize: number): Promise<void>;
     /**
      * Get a client for executing queries
      */

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

@@ -42,10 +42,13 @@
  * ```
  */
 export type { AtlasConfig } from './config';
-export { autoConfigure, defineConfig, fromEnv, loadConfig, loadConfigFile } from './config';
+export { defineConfig, fromEnv, loadConfig, loadConfigFile } from './config';
 export { Connection } from './connection/Connection';
 export { ConnectionManager } from './connection/ConnectionManager';
+export { ReplicaConnectionPool } from './connection/ReplicaConnectionPool';
 export { DB } from './DB';
+import { DB } from './DB';
+export declare const autoConfigure: typeof DB.autoConfigure;
 export { BunSQLDriver } from './drivers/BunSQLDriver';
 export { PostgresDriver } from './drivers/PostgresDriver';
 export { SQLiteDriver } from './drivers/SQLiteDriver';
@@ -56,12 +59,21 @@ export type { Migration, MigrationFile, MigrationRecord, MigrationResult, Migrat
 export { MigrationRepository, Migrator } from './migration';
 export { OrbitAtlas } from './OrbitAtlas';
 export type { ColumnSchema as OrmColumnSchema, ModelAttributes, ModelConstructor, ModelStatic, RelationshipMeta, RelationType, SchemaLock, SchemaMode, SchemaRegistryOptions, TableSchema, } from './orm';
-export { BelongsTo, BelongsToMany, ColumnNotFoundError, column, DirtyTracker, eagerLoad, eagerLoadMany, getRelationships, HasMany, HasOne, Model, ModelNotFoundError, ModelRegistry, MorphMany, MorphOne, MorphTo, NullableConstraintError, SchemaRegistry, SchemaSniffer, SoftDeletes, TypeMismatchError, version, } from './orm';
+export { BelongsTo, BelongsToMany, ColumnNotFoundError, column, DirtyTracker, eagerLoad, eagerLoadMany, getRelationships, HasMany, HasOne, Model, ModelNotFoundError, ModelRegistry, ModelRepository, MorphMany, MorphOne, MorphTo, NullableConstraintError, SchemaRegistry, SchemaSniffer, SoftDeletes, TypeMismatchError, version, } from './orm';
 export { Expression, raw } from './query/Expression';
 export { QueryBuilder, QueryBuilderError, RecordNotFoundError } from './query/QueryBuilder';
 export type { ColumnType, ForeignKeyAction, ForeignKeyDefinition, IndexDefinition } from './schema';
 export { Blueprint, ColumnDefinition, Schema } from './schema';
 export { MySQLSchemaGrammar, PostgresSchemaGrammar, SchemaGrammar, SQLiteSchemaGrammar, } from './schema/grammars';
+export { MigrationGenerator } from './schema/MigrationGenerator';
+export type { ColumnDefinition as SchemaColumnDefinition, SchemaDiffResult, } from './schema/SchemaDiff';
+export { SchemaDiff } from './schema/SchemaDiff';
+export type { ModelTypeMap, TypeGeneratorOptions } from './schema/TypeGenerator';
+export { TypeGenerator } from './schema/TypeGenerator';
+export { TypeWriter } from './schema/TypeWriter';
 export type { FactoryDefinition, Seeder, SeederFile, SeederRunnerOptions } from './seed';
 export { Factory, factory, SeederRunner } from './seed';
-export type { BooleanOperator, CompiledQuery, ConnectionConfig, ConnectionContract, DriverContract, DriverType, ExecuteResult, FieldInfo, GrammarContract, HavingClause, JoinClause, JoinType, MySQLConfig, Operator, OrderClause, OrderDirection, PaginateResult, PoolConfig, PostgresConfig, QueryBuilderContract, QueryResult, SQLiteConfig, SSLConfig, WhereClause, } from './types';
+export { type ShardingConfig, ShardingManager } from './sharding/ShardingManager';
+export type { AtlasConnectionEntry, BooleanOperator, CompiledQuery, ConnectionConfig, ConnectionContract, CursorPaginateResult, DriverContract, DriverType, ExecuteResult, FieldInfo, GrammarContract, HavingClause, isReadWriteConfig, JoinClause, JoinType, MySQLConfig, Operator, OrderClause, OrderDirection, PaginateResult, PoolConfig, PostgresConfig, QueryBuilderContract, QueryResult, ReadWriteConnectionConfig, SQLiteConfig, SSLConfig, WhereClause, } from './types';
+export type { CursorPayload } from './utils/CursorEncoding';
+export { buildCursorWhereClause, decodeCursor, encodeCursor, } from './utils/CursorEncoding';

package/dist/atlas/src/observability/AtlasMetrics.d.ts

@@ -5,7 +5,29 @@ export interface AtlasMetricsConfig {
 export declare class AtlasMetrics {
     private meter;
     private config;
+    private poolCallbacks;
     readonly operationDuration?: Histogram;
     readonly operationErrors?: Counter;
+    readonly poolSize?: any;
+    readonly poolUtilization?: any;
+    readonly poolWaitTime?: Histogram;
+    readonly poolAcquisitionErrors?: Counter;
     constructor(config: AtlasMetricsConfig);
+    /**
+     * Register pool statistics callback for ObservableGauge
+     */
+    registerPoolStatsCallback(connectionName: string, getStats: () => {
+        idle: number;
+        active: number;
+        pending: number;
+        max: number;
+    } | null): void;
+    /**
+     * Record connection wait time
+     */
+    recordConnectionWaitTime(connectionName: string, duration: number): void;
+    /**
+     * Record connection acquisition error
+     */
+    recordConnectionAcquisitionError(connectionName: string, error: string): void;
 }