@gravito/ripple 4.0.0 → 4.0.1

package/dist/atlas/src/pool/PoolWarmer.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @gravito/atlas - Connection Pool Warmer
+ * @description Preheats connection pools during initialization
+ */
+import type { ConnectionManager } from '../connection/ConnectionManager';
+export interface PoolWarmerConfig {
+    /**
+     * Target number of connections to warm for each pool
+     * @default 2
+     */
+    targetConnections?: number;
+    /**
+     * Number of concurrent warmup queries
+     * @default 2
+     */
+    concurrency?: number;
+    /**
+     * Timeout (ms) for each warmup query
+     * @default 5000
+     */
+    timeout?: number;
+    /**
+     * Callback when warmup completes
+     */
+    onComplete?: (result: WarmupResult) => void;
+    /**
+     * Callback for individual connection warmup
+     */
+    onConnectionWarmed?: (connection: string, duration: number) => void;
+}
+export interface ConnectionWarmupResult {
+    /**
+     * Whether warmup succeeded
+     */
+    success: boolean;
+    /**
+     * Connection name
+     */
+    connection: string;
+    /**
+     * Time spent warming up (ms)
+     */
+    duration: number;
+    /**
+     * Error message (if failed)
+     */
+    error?: string;
+}
+export interface WarmupResult {
+    /**
+     * Total connections processed
+     */
+    total: number;
+    /**
+     * Number of successful warmups
+     */
+    successful: number;
+    /**
+     * Number of failed warmups
+     */
+    failed: number;
+    /**
+     * Results for each connection
+     */
+    results: Record<string, ConnectionWarmupResult>;
+    /**
+     * Total duration (ms)
+     */
+    duration: number;
+}
+export declare const DEFAULT_WARMER_CONFIG: PoolWarmerConfig;
+/**
+ * Connection pool warmer
+ * Preheats pools by establishing connections
+ */
+export declare class PoolWarmer {
+    private connectionManager;
+    private config;
+    constructor(connectionManager: ConnectionManager, config: PoolWarmerConfig);
+    /**
+     * Warm all connection pools
+     */
+    warmAll(): Promise<WarmupResult>;
+    /**
+     * Warm a specific connection pool
+     */
+    warmConnection(name: string): Promise<ConnectionWarmupResult>;
+    /**
+     * Execute a warmup query with timeout
+     */
+    private executeWarmupQuery;
+}

package/dist/atlas/src/query/QueryBuilder.d.ts

@@ -1,7 +1,8 @@
 import type { Model, ModelConstructor } from '../orm/model/Model';
-import type { BooleanOperator, CompiledQuery, ConnectionContract, GrammarContract, JoinType, Operator, OrderDirection, PaginateResult, QueryBuilderContract } from '../types';
+import type { BooleanOperator, CompiledQuery, ConnectionContract, CursorPaginateResult, GrammarContract, JoinType, Operator, OrderDirection, PaginateResult, QueryBuilderContract } from '../types';
 import { GroupByClause, HavingClause, JoinManager, LimitClause, OrderByClause, SelectClause, WhereClause } from './clauses';
 import { Expression } from './Expression';
+import type { RelationshipResolver } from './RelationshipResolver';
 export declare class QueryBuilderError extends Error {
     constructor(message: string);
 }
@@ -30,6 +31,11 @@ export declare class RecordNotFoundError extends Error {
 export declare class QueryBuilder<T = Record<string, unknown>> implements QueryBuilderContract<T> {
     protected readonly connection: ConnectionContract;
     protected readonly grammar: GrammarContract;
+    /**
+     * Global relationship resolver to avoid circular dependencies and require() calls.
+     * Injected by the Model layer.
+     */
+    static relationshipResolver?: RelationshipResolver;
     /**
      * Name of the target database table.
      */
@@ -49,6 +55,12 @@ export declare class QueryBuilder<T = Record<string, unknown>> implements QueryB
      * Read-only flag to bypass hydration for performance.
      */
     protected isReadOnly: boolean;
+    /**
+     * When true, this query will always use the write (primary) connection,
+     * even if read replicas are configured. Use after a write to avoid
+     * replication lag issues.
+     */
+    protected _forceWrite: boolean;
     /**
      * Map of relationships to load alongside query results.
      */
@@ -246,6 +258,29 @@ export declare class QueryBuilder<T = Record<string, unknown>> implements QueryB
      * OR version of {@link whereJsonContains}.
      */
     orWhereJsonContains(column: string, value: unknown): this;
+    /**
+     * Spatial distance filter: matches records within a given radius.
+     *
+     * Generates dialect-appropriate SQL:
+     * - **PostgreSQL**: `ST_DWithin(column::geography, ST_MakePoint(lng, lat)::geography, distance)`
+     * - **MySQL**: `ST_Distance_Sphere(column, POINT(lng, lat)) <= distance`
+     *
+     * Requires a spatial/geometry column and a GIS extension.
+     *
+     * @param column - The geometry/geography column name
+     * @param point - GPS point `{ lat, lng }` in decimal degrees
+     * @param distanceMeters - Search radius in meters
+     *
+     * @example
+     * ```typescript
+     * // Find all stores within 5km of a location
+     * await Store.query().whereDistanceWithin('location', { lat: 25.04, lng: 121.52 }, 5000).get()
+     * ```
+     */
+    whereDistanceWithin(column: string, point: {
+        lat: number;
+        lng: number;
+    }, distanceMeters: number): this;
     /**
      * Groups constraints in parentheses.
      *
@@ -491,6 +526,41 @@ export declare class QueryBuilder<T = Record<string, unknown>> implements QueryB
      * Alias for {@link paginate}.
      */
     simplePaginate(perPage?: number, page?: number, primaryKey?: string): Promise<PaginateResult<T>>;
+    /**
+     * Forces this query to use the primary (write) connection.
+     *
+     * Essential after writes to avoid reading stale data from replicas.
+     * Example: after saving a model, use `.useWriteConnection()` to read back.
+     *
+     * @example
+     * ```typescript
+     * await User.create({ name: 'Alice' })
+     * const alice = await User.query().useWriteConnection().where('name', 'Alice').first()
+     * ```
+     */
+    useWriteConnection(): this;
+    /**
+     * Cursor-based pagination for large datasets.
+     *
+     * Achieves O(1) performance by using tuple comparison SQL instead of OFFSET.
+     * Ideal for infinite scroll, API cursors, and feeds with millions of records.
+     *
+     * @param limit - Number of records to fetch per page
+     * @param cursor - Opaque cursor from a previous page's `nextCursor` (undefined for first page)
+     * @param sortColumn - Column to sort by (defaults to primary key 'id')
+     * @param direction - Sort direction (defaults to 'asc')
+     * @returns CursorPaginateResult with data and cursor metadata
+     *
+     * @example
+     * ```typescript
+     * // First page
+     * const page1 = await User.query().orderBy('created_at').cursorPaginate(20)
+     *
+     * // Next page using cursor from previous result
+     * const page2 = await User.query().orderBy('created_at').cursorPaginate(20, page1.nextCursor)
+     * ```
+     */
+    cursorPaginate(limit?: number, cursor?: string, sortColumn?: string, direction?: 'asc' | 'desc'): Promise<CursorPaginateResult<T>>;
     /**
      * Processes the entire dataset in memory-efficient chunks.
      *

package/dist/atlas/src/query/RelationshipResolver.d.ts

@@ -0,0 +1,23 @@
+import type { QueryBuilderContract } from '../types';
+/**
+ * Relationship Metadata interface for QueryBuilder
+ */
+export interface RelationshipMeta {
+    type: string;
+    related: () => any;
+    foreignKey?: string;
+    localKey?: string;
+    pivotTable?: string;
+    relatedKey?: string;
+    pivotColumns?: string[];
+    morphName?: string;
+    morphTypeField?: string;
+    morphIdField?: string;
+}
+/**
+ * Relationship Resolver interface to decouple QueryBuilder from Model relationships
+ */
+export interface RelationshipResolver {
+    getRelationships(model: any): Map<string, RelationshipMeta>;
+    eagerLoadMany(parents: any[], relations: string[] | Record<string, any> | Map<string, (query: QueryBuilderContract<any>) => void>): Promise<void>;
+}

package/dist/atlas/src/schema/MigrationGenerator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @gravito/atlas - Migration Generator
+ * @description Converts a SchemaDiffResult into SQL ALTER TABLE statements
+ * for both PostgreSQL and MySQL dialects.
+ *
+ * Powers the `migrate:generate` and `db:push` CLI commands.
+ */
+import type { DriverType } from '../types';
+import type { SchemaDiffResult } from './SchemaDiff';
+export interface MigrationGeneratorOptions {
+    /** Target database dialect */
+    dialect: DriverType;
+}
+/**
+ * MigrationGenerator
+ *
+ * Takes a `SchemaDiffResult` and generates the corresponding SQL statements
+ * required to bring the database schema in sync with Model definitions.
+ *
+ * @example
+ * ```typescript
+ * const gen = new MigrationGenerator({ dialect: 'postgres' })
+ * const sql = gen.generate(diff)
+ * // Returns: ALTER TABLE users ADD COLUMN bio TEXT NULL; ...
+ * ```
+ */
+export declare class MigrationGenerator {
+    private readonly dialect;
+    constructor(options: MigrationGeneratorOptions);
+    /**
+     * Generate SQL statements for the given diff.
+     *
+     * @param diff - Schema diff result from SchemaDiff.compare()
+     * @returns Array of SQL statements to execute
+     */
+    generate(diff: SchemaDiffResult): string[];
+    /**
+     * Generate a timestamped migration script content string.
+     *
+     * @param diff - Schema diff result
+     * @param migrationName - Optional migration name
+     */
+    generateMigrationScript(diff: SchemaDiffResult, migrationName?: string): string;
+    private quoteIdentifier;
+}

package/dist/atlas/src/schema/SchemaDiff.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @gravito/atlas - Schema Differ
+ * @description Compares Atlas Model decorator metadata against the live database
+ * schema (information_schema) and produces a structured diff.
+ *
+ * This powers the `db:push` and `migrate:generate` CLI commands.
+ */
+import type { ConnectionContract } from '../types';
+/**
+ * A single column definition from information_schema or decorator meta.
+ */
+export interface ColumnDefinition {
+    name: string;
+    type: string;
+    nullable: boolean;
+    defaultValue: string | null;
+    isPrimary: boolean;
+    isUnique: boolean;
+}
+/**
+ * The result of comparing two schema states.
+ */
+export interface SchemaDiffResult {
+    /** Table name */
+    table: string;
+    /** Columns that exist in models but not in the DB */
+    added: ColumnDefinition[];
+    /** Columns that exist in the DB but not in models */
+    removed: ColumnDefinition[];
+    /** Columns where the type or nullability has changed */
+    modified: Array<{
+        name: string;
+        from: ColumnDefinition;
+        to: ColumnDefinition;
+    }>;
+    /** Whether any changes were detected */
+    hasChanges: boolean;
+}
+export interface SchemaDiffOptions {
+    /** Database connection to compare against */
+    connection: ConnectionContract;
+    /** Table name */
+    table: string;
+    /** Desired column definitions (from Model decorators) */
+    desired: ColumnDefinition[];
+}
+/**
+ * SchemaDiff
+ *
+ * Compares the desired schema (from Model @Column decorators) against the
+ * current live database schema and produces a structured diff result.
+ *
+ * @example
+ * ```typescript
+ * const differ = new SchemaDiff({ connection, table: 'users', desired: userColumns })
+ * const diff = await differ.compare()
+ * if (diff.hasChanges) console.log('Schema is out of sync!')
+ * ```
+ */
+export declare class SchemaDiff {
+    private readonly connection;
+    private readonly table;
+    private readonly desired;
+    constructor(options: SchemaDiffOptions);
+    /**
+     * Perform the schema comparison and return the diff result.
+     */
+    compare(): Promise<SchemaDiffResult>;
+    /**
+     * Normalize DB type strings for comparison (e.g. 'character varying' → 'varchar').
+     */
+    private normalizeType;
+}

package/dist/atlas/src/schema/TypeGenerator.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @gravito/atlas - Schema Type Generator
+ * @description Reads @Column decorator metadata from Model classes and builds a
+ * type map for generating TypeScript declaration files.
+ *
+ * Eliminates "Type Drift" by deriving types 100% from decorator metadata.
+ */
+export declare const COLUMN_METADATA_KEY = "atlas:columns";
+/**
+ * Column metadata stored by @Column decorator
+ */
+export interface ColumnMeta {
+    name: string;
+    type: string;
+    nullable?: boolean;
+    primary?: boolean;
+    unique?: boolean;
+    default?: unknown;
+}
+/**
+ * Generated type map for a single Model class
+ */
+export interface ModelTypeMap {
+    /** Model class name (e.g. 'User') */
+    modelName: string;
+    /** Table name the model maps to */
+    tableName: string;
+    /** Column-to-TypeScript type mapping */
+    columns: Record<string, string>;
+}
+export interface TypeGeneratorOptions {
+    /** Root directory to scan for Model files */
+    modelsDir: string;
+    /** Whether to log progress */
+    verbose?: boolean;
+}
+/**
+ * TypeGenerator
+ *
+ * Scans a directory for Atlas Model files and extracts @Column decorator
+ * metadata to produce a complete type map.
+ *
+ * @example
+ * ```typescript
+ * const gen = new TypeGenerator({ modelsDir: './src/models' })
+ * const result = await gen.generate()
+ * ```
+ */
+export declare class TypeGenerator {
+    private readonly modelsDir;
+    private readonly verbose;
+    constructor(options: TypeGeneratorOptions);
+    /**
+     * Scan models directory and extract type maps from all Model files.
+     */
+    generate(): Promise<ModelTypeMap[]>;
+}

package/dist/atlas/src/schema/TypeWriter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @gravito/atlas - Type Writer
+ * @description Writes TypeScript declaration files from generated Model type maps.
+ *
+ * Outputs interface declarations that can be merged into Model classes via
+ * Declaration Merging for zero type-drift DX.
+ */
+import type { ModelTypeMap } from './TypeGenerator';
+export interface TypeWriterOptions {
+    /** Output file path (e.g., '.orbit/generated.d.ts') */
+    outputPath: string;
+    /** Optional banner comment */
+    banner?: string;
+}
+/**
+ * TypeWriter
+ *
+ * Converts a list of ModelTypeMap objects into a `.d.ts` declaration file.
+ *
+ * @example
+ * ```typescript
+ * const writer = new TypeWriter({ outputPath: '.orbit/generated.d.ts' })
+ * await writer.write(typeMaps)
+ * // Emits:
+ * //   export interface GeneratedUser { id: number; name: string; ... }
+ * ```
+ */
+export declare class TypeWriter {
+    private readonly outputPath;
+    private readonly banner;
+    constructor(options: TypeWriterOptions);
+    /**
+     * Write the declaration file to disk.
+     *
+     * @param typeMaps - Array of model type maps from TypeGenerator
+     */
+    write(typeMaps: ModelTypeMap[]): Promise<void>;
+    /**
+     * Build the .d.ts file content string.
+     */
+    buildContent(typeMaps: ModelTypeMap[]): string;
+}

package/dist/atlas/src/sharding/ShardingManager.d.ts

@@ -0,0 +1,59 @@
+import type { ConnectionConfig, ConnectionContract } from '../types';
+/**
+ * Sharding Configuration
+ */
+export interface ShardingConfig {
+    /**
+     * Number of shards
+     */
+    shardCount: number;
+    /**
+     * List of shard connection configurations
+     */
+    shards: (ConnectionConfig & {
+        id: number;
+    })[];
+    /**
+     * Sharding algorithm (default: 'consistent-hashing')
+     */
+    algorithm?: 'consistent-hashing' | 'modulo' | 'range';
+}
+/**
+ * Sharding Manager
+ *
+ * Manages database sharding, connection routing, and distributed queries.
+ * Supports horizontal scaling by partitioning data across multiple database instances.
+ */
+export declare class ShardingManager {
+    private connections;
+    private shardCount;
+    private algorithm;
+    constructor(config: ShardingConfig);
+    /**
+     * Initialize all shard connections
+     */
+    private initializeShards;
+    /**
+     * Get a shard connection by distribution key (e.g., userId, tenantId)
+     *
+     * @param key - The distribution key
+     * @returns The connection instance for the calculated shard
+     */
+    getShard(key: string | number): ConnectionContract;
+    /**
+     * Calculate Shard ID based on the key and selected algorithm
+     */
+    private calculateShardId;
+    /**
+     * Execute a query across all shards and aggregate the results.
+     * Useful for reports, analytics, or global searches.
+     *
+     * @param callback - The operation to perform on each shard
+     * @returns Aggregated results from all shards
+     */
+    mapReduce<T>(callback: (connection: ConnectionContract, shardId: number) => Promise<T[]>): Promise<T[]>;
+    /**
+     * Get all active shard connections
+     */
+    getAllShards(): Map<number, ConnectionContract>;
+}

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

@@ -74,6 +74,28 @@ export interface BaseConnectionConfig {
  * Union type for all connection configurations
  */
 export type ConnectionConfig = PostgresConfig | MySQLConfig | SQLiteConfig | MongoDBConfig | RedisConfig | BaseConnectionConfig;
+/**
+ * Read/Write Replica configuration
+ * Defines a primary (write) node and one or more read replicas.
+ */
+export interface ReadWriteConnectionConfig {
+    /**
+     * Primary write node configuration
+     */
+    write: ConnectionConfig;
+    /**
+     * Read replica configurations (Round-robin selected)
+     */
+    read: ConnectionConfig[];
+}
+/**
+ * Union type for Atlas connection entry (standard or replica)
+ */
+export type AtlasConnectionEntry = ConnectionConfig | ReadWriteConnectionConfig;
+/**
+ * Type guard to check if a connection config is a read/write replica config
+ */
+export declare function isReadWriteConfig(config: AtlasConnectionEntry): config is ReadWriteConnectionConfig;
 export interface AtlasObservabilityConfig {
     enabled: boolean;
     tracing?: boolean;
@@ -82,7 +104,7 @@ export interface AtlasObservabilityConfig {
 }
 export interface AtlasConfig {
     default: string;
-    connections: Record<string, ConnectionConfig>;
+    connections: Record<string, AtlasConnectionEntry>;
     observability?: AtlasObservabilityConfig;
 }
 /**
@@ -459,6 +481,33 @@ export interface PaginateResult<T> {
         hasPrev: boolean;
     };
 }
+/**
+ * Cursor-based pagination result
+ * Provides O(1) performance regardless of dataset size.
+ * Ideal for infinite scroll and large datasets.
+ */
+export interface CursorPaginateResult<T> {
+    /**
+     * Current page data
+     */
+    data: T[];
+    /**
+     * Opaque cursor pointing to the next page (null if no more data)
+     */
+    nextCursor: string | null;
+    /**
+     * Opaque cursor pointing to the previous page (null if first page)
+     */
+    prevCursor: string | null;
+    /**
+     * Whether more records exist beyond the current page
+     */
+    hasMore: boolean;
+    /**
+     * Number of records returned
+     */
+    count: number;
+}
 /**
  * Connection pool statistics
  */
@@ -484,6 +533,27 @@ export interface PoolStats {
      */
     max: number;
 }
+/**
+ * Connection pool health status
+ */
+export interface PoolHealth {
+    /**
+     * Health status: 'healthy' | 'warning' | 'critical' | 'disconnected'
+     */
+    status: 'healthy' | 'warning' | 'critical' | 'disconnected';
+    /**
+     * Human-readable health message
+     */
+    message: string;
+    /**
+     * Pool statistics (when available)
+     */
+    stats?: PoolStats;
+    /**
+     * Last health check timestamp
+     */
+    lastCheck?: Date;
+}
 /**
  * Model base class (forward declaration)
  * Actual implementation in src/orm/model/Model.ts
@@ -571,6 +641,18 @@ export interface DriverContract {
      * @returns Pool statistics or null if not supported
      */
     getPoolStats?(): PoolStats | null;
+    /**
+     * Get connection pool health status
+     * @optional Only implemented by drivers that support connection pooling
+     * @returns Pool health information
+     */
+    getPoolHealth?(): PoolHealth;
+    /**
+     * Adjust the connection pool size dynamically
+     * @optional Only implemented by drivers that support pool resizing
+     * @param targetSize - Target number of connections
+     */
+    adjustPoolSize?(targetSize: number): Promise<void>;
 }
 /**
  * Connection Contract

package/dist/atlas/src/utils/CursorEncoding.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @gravito/atlas - Cursor Encoding Utility
+ * @description Base64 encode/decode for cursor-based pagination cursors.
+ *
+ * Cursor format: base64(JSON({ id, sortValue, sortColumn, direction }))
+ * This enables O(1) pagination using tuple comparison SQL:
+ *   WHERE (sort_col, id) > (val, id_val)
+ */
+export interface CursorPayload {
+    /**
+     * Primary key value of the last/first record in the current page
+     */
+    id: unknown;
+    /**
+     * Value of the sort column at the cursor boundary
+     */
+    sortValue: unknown;
+    /**
+     * Column name used for sorting
+     */
+    sortColumn: string;
+    /**
+     * Sort direction
+     */
+    direction: 'asc' | 'desc';
+}
+/**
+ * Encode a cursor payload to an opaque base64 string.
+ *
+ * @param payload - Cursor data to encode
+ * @returns Base64-encoded cursor string
+ *
+ * @example
+ * const cursor = encodeCursor({ id: 42, sortValue: '2026-01-01', sortColumn: 'created_at', direction: 'asc' })
+ */
+export declare function encodeCursor(payload: CursorPayload): string;
+/**
+ * Decode a cursor string back to its payload.
+ *
+ * @param cursor - Base64 cursor string
+ * @returns Decoded cursor payload
+ * @throws {Error} If the cursor is malformed or tampered with
+ *
+ * @example
+ * const payload = decodeCursor(cursor)
+ * // payload.id, payload.sortValue, etc.
+ */
+export declare function decodeCursor(cursor: string): CursorPayload;
+/**
+ * Build the WHERE clause raw SQL and bindings for cursor pagination.
+ *
+ * For ascending sort: WHERE (sort_col, id) > (sort_val, id_val)
+ * For descending sort: WHERE (sort_col, id) < (sort_val, id_val)
+ *
+ * Uses tuple comparison which is O(1) on indexed columns in Postgres & MySQL.
+ *
+ * @param payload - Decoded cursor payload
+ * @returns { sql, bindings } ready for whereRaw()
+ */
+export declare function buildCursorWhereClause(payload: CursorPayload, idColumn?: string): {
+    sql: string;
+    bindings: unknown[];
+};