@gravito/ripple 4.0.0 → 4.0.1

package/dist/atlas/src/orm/Repository.d.ts

@@ -0,0 +1,247 @@
+import type { QueryBuilderContract } from '../types';
+import type { Model, ModelStatic } from './model/Model';
+/**
+ * ModelRepository - Base Repository for Active Record Models
+ *
+ * Provides a collection-like interface for accessing and persisting domain models.
+ * Extends the Active Record pattern with common repository operations.
+ *
+ * @template T - The type of Model managed by this repository
+ *
+ * @example
+ * ```typescript
+ * class UserRepository extends ModelRepository<User> {
+ *   protected modelClass = User
+ *
+ *   async findByEmail(email: string): Promise<User | null> {
+ *     return this.findWhere('email', email)
+ *   }
+ *
+ *   async findActive(): Promise<User[]> {
+ *     return this.query().where('is_active', true).get()
+ *   }
+ * }
+ *
+ * // Usage
+ * const userRepo = new UserRepository()
+ * const user = await userRepo.find(1)
+ * const active = await userRepo.findActive()
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare abstract class ModelRepository<T extends Model> {
+    /**
+     * The model class this repository manages.
+     * Must be set by subclasses.
+     *
+     * @example
+     * ```typescript
+     * class UserRepository extends ModelRepository<User> {
+     *   protected modelClass = User
+     * }
+     * ```
+     */
+    protected abstract modelClass: ModelStatic<T>;
+    /**
+     * Get a query builder for this model.
+     *
+     * @returns A new query builder instance
+     */
+    protected query(): QueryBuilderContract<T>;
+    /**
+     * Retrieve all records from the database.
+     *
+     * @returns Promise resolving to array of all model instances
+     *
+     * @example
+     * ```typescript
+     * const users = await userRepository.all()
+     * ```
+     */
+    all(): Promise<T[]>;
+    /**
+     * Find a single record by its primary key.
+     *
+     * @param id - The primary key value
+     * @returns Promise resolving to the model instance or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.find(1)
+     * ```
+     */
+    find(id: unknown): Promise<T | null>;
+    /**
+     * Find a single record by its primary key or throw an error.
+     *
+     * @param id - The primary key value
+     * @returns Promise resolving to the model instance
+     * @throws ModelNotFoundError if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.findOrFail(1)
+     * ```
+     */
+    findOrFail(id: unknown): Promise<T>;
+    /**
+     * Find a single record matching a where clause.
+     *
+     * @param column - The column name
+     * @param value - The value to match
+     * @returns Promise resolving to the model instance or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.findWhere('email', 'john@example.com')
+     * ```
+     */
+    findWhere(column: string, value: unknown): Promise<T | null>;
+    /**
+     * Find multiple records matching a where clause.
+     *
+     * @param column - The column name
+     * @param value - The value to match
+     * @returns Promise resolving to array of model instances
+     *
+     * @example
+     * ```typescript
+     * const admins = await userRepository.findManyWhere('role', 'admin')
+     * ```
+     */
+    findManyWhere(column: string, value: unknown): Promise<T[]>;
+    /**
+     * Find records using a callback for complex queries.
+     *
+     * @param callback - Function that receives the query builder
+     * @returns Promise resolving to array of model instances
+     *
+     * @example
+     * ```typescript
+     * const result = await userRepository.findWhere(q =>
+     *   q.where('role', 'admin').where('is_active', true)
+     * )
+     * ```
+     */
+    findByQuery(callback: (query: QueryBuilderContract<T>) => QueryBuilderContract<T>): Promise<T[]>;
+    /**
+     * Find a single record using a callback for complex queries.
+     *
+     * @param callback - Function that receives the query builder
+     * @returns Promise resolving to the model instance or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.findOneByQuery(q =>
+     *   q.where('email', email).where('is_active', true)
+     * )
+     * ```
+     */
+    findOneByQuery(callback: (query: QueryBuilderContract<T>) => QueryBuilderContract<T>): Promise<T | null>;
+    /**
+     * Create a new record in the database.
+     *
+     * @param attributes - Object containing model attributes
+     * @returns Promise resolving to the created model instance
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.create({
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * })
+     * ```
+     */
+    create(attributes: Partial<T>): Promise<T>;
+    /**
+     * Update an existing record by its primary key.
+     *
+     * @param id - The primary key value
+     * @param attributes - Object containing attributes to update
+     * @returns Promise resolving to the updated model instance
+     * @throws ModelNotFoundError if record not found
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.update(1, { name: 'Jane Doe' })
+     * ```
+     */
+    update(id: unknown, attributes: Partial<T>): Promise<T>;
+    /**
+     * Delete a record by its primary key.
+     *
+     * @param id - The primary key value
+     * @returns Promise that resolves when deletion is complete
+     *
+     * @example
+     * ```typescript
+     * await userRepository.delete(1)
+     * ```
+     */
+    delete(id: unknown): Promise<void>;
+    /**
+     * Check if a record exists by its primary key.
+     *
+     * @param id - The primary key value
+     * @returns Promise resolving to true if exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const exists = await userRepository.exists(1)
+     * ```
+     */
+    exists(id: unknown): Promise<boolean>;
+    /**
+     * Count the total number of records.
+     *
+     * @returns Promise resolving to the count
+     *
+     * @example
+     * ```typescript
+     * const total = await userRepository.count()
+     * ```
+     */
+    count(): Promise<number>;
+    /**
+     * Paginate records.
+     *
+     * @param page - The page number (1-indexed)
+     * @param perPage - The number of records per page
+     * @returns Promise resolving to pagination result
+     *
+     * @example
+     * ```typescript
+     * const result = await userRepository.paginate(1, 20)
+     * // result.data: T[]
+     * // result.total: number
+     * // result.per_page: number
+     * ```
+     */
+    paginate(page?: number, perPage?: number): Promise<import("..").PaginateResult<T>>;
+    /**
+     * Restore soft-deleted records (requires SoftDeletes mixin on model).
+     *
+     * @param id - The primary key value
+     * @returns Promise that resolves when restoration is complete
+     *
+     * @example
+     * ```typescript
+     * await userRepository.restore(1)
+     * ```
+     */
+    restore(id: unknown): Promise<void>;
+    /**
+     * Permanently delete a soft-deleted record (requires SoftDeletes mixin on model).
+     *
+     * @param id - The primary key value
+     * @returns Promise that resolves when permanent deletion is complete
+     *
+     * @example
+     * ```typescript
+     * await userRepository.forceDelete(1)
+     * ```
+     */
+    forceDelete(id: unknown): Promise<void>;
+}

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

@@ -2,4 +2,5 @@
  * ORM Module Index
  */
 export * from './model';
+export { ModelRepository } from './Repository';
 export * from './schema';

package/dist/atlas/src/orm/model/Model.d.ts

@@ -26,7 +26,8 @@ export interface ModelStatic<T extends Model> {
     findOrFail(key: unknown): Promise<T>;
     all(): Promise<T[]>;
     create(attributes?: Partial<ModelAttributes>): Promise<T>;
-    query(): QueryBuilderContract<T>;
+    query(connection?: import('../../types').ConnectionContract): QueryBuilderContract<T>;
+    shard(key: string | number): QueryBuilderContract<T>;
     where(column: string | Record<string, unknown>, operatorOrValue?: Operator | unknown, value?: unknown): QueryBuilderContract<T>;
 }
 /**
@@ -370,11 +371,19 @@ export declare abstract class Model {
      * @yields Chunks of model instances.
      */
     static cursor<T extends Model>(this: ModelConstructor<T> & typeof Model, chunkSize?: number): AsyncGenerator<T[], void, unknown>;
+    /**
+     * Initializes a fluent query builder for the model on a specific sharded connection.
+     *
+     * @param key - The shard distribution key
+     * @returns A proxied query builder instance connected to the right shard.
+     */
+    static shard<T extends Model>(this: ModelConstructor<T> & typeof Model, key: string | number): import('../../types').QueryBuilderContract<T>;
     /**
      * Initializes a fluent query builder for the model.
      *
      * Automatically handles model hydration, soft delete filtering, and scope application.
      *
+     * @param connectionContract - Optional specific database connection
      * @returns A proxied query builder instance.
      *
      * @example
@@ -382,7 +391,7 @@ export declare abstract class Model {
      * const users = await User.query().where('active', true).get();
      * ```
      */
-    static query<T extends Model>(this: ModelConstructor<T> & typeof Model): QueryBuilderContract<T>;
+    static query<T extends Model>(this: ModelConstructor<T> & typeof Model, connectionContract?: import('../../types').ConnectionContract): QueryBuilderContract<T>;
     /**
      * Starts a query with a standard WHERE clause.
      *

package/dist/atlas/src/orm/model/concerns/HasAttributes.d.ts

@@ -6,6 +6,20 @@ export type ModelAttributes = Record<string, unknown>;
  * @description Provides attribute management functionality including getting/setting, casting, and dirty tracking.
  */
 export declare class HasAttributes {
+    /**
+     * Static schema registry for JIT validation.
+     * @internal
+     */
+    static schemaRegistry?: any;
+    /**
+     * Static error classes for validation.
+     * @internal
+     */
+    static validationErrors?: {
+        ColumnNotFoundError: any;
+        NullableConstraintError: any;
+        TypeMismatchError: any;
+    };
     /**
      * Model attributes storage
      * @internal

package/dist/atlas/src/orm/model/concerns/HasPersistence.d.ts

@@ -14,6 +14,11 @@ export declare class HasPersistence {
      * @returns True if the model has been persisted
      */
     get exists(): boolean;
+    /**
+     * Internal helper to retrieve the correct connection depending on sharding configuration
+     * @internal
+     */
+    protected _getConnection(): import('../../../types').ConnectionContract;
     /**
      * Save the model instance to the database (insert or update).
      *

package/dist/atlas/src/orm/model/decorators.d.ts

@@ -26,6 +26,35 @@ export declare const COLUMN_KEY: unique symbol;
  * @internal
  */
 export declare const VERSION_KEY: unique symbol;
+/**
+ * Metadata key for Sharded configuration.
+ * @internal
+ */
+export declare const SHARDED_KEY: unique symbol;
+/**
+ * Options for the Sharded decorator.
+ */
+export interface ShardedOptions {
+    /**
+     * The name of the ShardingManager to use.
+     * @default 'default'
+     */
+    manager?: string;
+    /**
+     * The property name of the shard key (e.g. 'tenantId').
+     */
+    key: string;
+}
+/**
+ * Sharded Decorator
+ *
+ * Marks a model as being horizontally sharded across multiple databases.
+ * Active Record operations will automatically route to the correct connection
+ * based on the shard key provided.
+ *
+ * @param options - Configuration for sharding containing the distribution key
+ */
+export declare function sharded(options: ShardedOptions): ClassDecorator;
 /**
  * Soft Deletes Decorator
  *

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

@@ -3,7 +3,7 @@
  */
 export { applyMixins, HasAttributes, HasEvents, HasPersistence, HasRelationships, HasSerialization, } from './concerns';
 export { DirtyTracker } from './DirtyTracker';
-export { column, SoftDeletes, version } from './decorators';
+export { column, SoftDeletes, sharded, version } from './decorators';
 export { ColumnNotFoundError, ModelNotFoundError, NullableConstraintError, TypeMismatchError, } from './errors';
 export { Model, type ModelAttributes, type ModelConstructor, type ModelStatic } from './Model';
 export { ModelRegistry } from './ModelRegistry';

package/dist/atlas/src/orm/schema/SchemaRegistry.d.ts

@@ -38,6 +38,7 @@ export interface SchemaRegistryOptions {
 export declare class SchemaRegistry {
     private static instance;
     private cache;
+    private pendingSniffs;
     private sniffer;
     private mode;
     private lockPath;

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

@@ -0,0 +1,98 @@
+/**
+ * @gravito/atlas - Adaptive Pool Manager
+ * @description Manages adaptive pool sizing based on strategies
+ */
+import type { ConnectionManager } from '../connection/ConnectionManager';
+import type { PoolStats } from '../types';
+import type { PoolStrategy } from './PoolStrategy';
+export interface PoolStatsHistory {
+    stats: PoolStats;
+    timestamp: number;
+}
+export interface PoolAdjustmentEvent {
+    connection: string;
+    action: 'increase' | 'decrease' | 'maintain';
+    from: number;
+    to: number;
+    reason: string;
+}
+export interface AdaptivePoolConfig {
+    /**
+     * Evaluation interval (ms)
+     * @default 60000
+     */
+    evaluationInterval: number;
+    /**
+     * Minimum cooldown period (ms) before next adjustment
+     * @default 30000
+     */
+    cooldownPeriod: number;
+    /**
+     * Maximum history size
+     * @default 10
+     */
+    maxHistorySize: number;
+    /**
+     * Callback when adjustment is made
+     */
+    onAdjustment?: (event: PoolAdjustmentEvent) => void;
+}
+export declare const DEFAULT_ADAPTIVE_CONFIG: AdaptivePoolConfig;
+/**
+ * Adaptive pool manager
+ * Periodically evaluates pool statistics and adjusts size based on strategy
+ */
+export declare class AdaptivePoolManager {
+    private connectionManager;
+    private strategy;
+    private config;
+    private intervalHandle?;
+    private statsHistory;
+    private adjustmentCooldown;
+    private lastAdjustment;
+    constructor(connectionManager: ConnectionManager, strategy: PoolStrategy, config: AdaptivePoolConfig);
+    /**
+     * Start adaptive management
+     */
+    start(): void;
+    /**
+     * Stop adaptive management
+     */
+    stop(): void;
+    /**
+     * Get last adjustment for a connection
+     */
+    getLastAdjustment(connectionName: string): PoolAdjustmentEvent | undefined;
+    /**
+     * Get history for a connection
+     */
+    getHistory(connectionName: string): PoolStatsHistory[];
+    /**
+     * Evaluate all connection pools
+     */
+    private evaluateAllPools;
+    /**
+     * Evaluate a specific pool
+     */
+    private evaluatePool;
+    /**
+     * Build strategy context from current state
+     */
+    private buildContext;
+    /**
+     * Update historical statistics
+     */
+    private updateHistory;
+    /**
+     * Check if in cooldown period
+     */
+    private isInCooldown;
+    /**
+     * Set cooldown period
+     */
+    private setCooldown;
+    /**
+     * Apply adjustment to pool
+     */
+    private applyAdjustment;
+}

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

@@ -0,0 +1,91 @@
+/**
+ * @gravito/atlas - Connection Pool Health Checker
+ * @description Monitors connection pool health and triggers callbacks on state changes
+ */
+import type { ConnectionManager } from '../connection/ConnectionManager';
+import type { PoolHealth } from '../types';
+export interface PoolHealthCheckConfig {
+    /**
+     * Interval (ms) to check pool health
+     * @default 30000 (30 seconds)
+     */
+    checkInterval: number;
+    /**
+     * Health status thresholds
+     */
+    thresholds: {
+        /**
+         * Utilization ratio (0-1) to trigger warning
+         * @default 0.7
+         */
+        warningUtilization: number;
+        /**
+         * Utilization ratio (0-1) to trigger critical
+         * @default 0.9
+         */
+        criticalUtilization: number;
+        /**
+         * Pending ratio (0-1) to trigger warning
+         * @default 0.5
+         */
+        maxPendingRatio: number;
+    };
+    /**
+     * Whether to test connection availability during health check
+     * @default true
+     */
+    enableConnectionTest: boolean;
+    /**
+     * Timeout (ms) for connection test
+     * @default 5000
+     */
+    connectionTestTimeout: number;
+    /**
+     * Callback when health status changes
+     */
+    onHealthChange?: (connectionName: string, health: PoolHealth) => void;
+    /**
+     * Callback when pool health becomes critical
+     */
+    onCritical?: (connectionName: string, health: PoolHealth) => void;
+}
+export declare const DEFAULT_HEALTH_CHECK_CONFIG: PoolHealthCheckConfig;
+/**
+ * Connection pool health checker
+ * Periodically monitors pool health and triggers callbacks
+ */
+export declare class PoolHealthChecker {
+    private connectionManager;
+    private config;
+    private intervalHandle?;
+    private lastHealthStatus;
+    constructor(connectionManager: ConnectionManager, config: PoolHealthCheckConfig);
+    /**
+     * Start health checking
+     */
+    start(): void;
+    /**
+     * Stop health checking
+     */
+    stop(): void;
+    /**
+     * Get current health status for a specific connection
+     */
+    getHealthStatus(connectionName?: string): PoolHealth | Map<string, PoolHealth>;
+    /**
+     * Check health of all connections
+     */
+    private checkAllConnections;
+    /**
+     * Check health of a specific connection
+     */
+    private checkConnection;
+    /**
+     * Evaluate pool health based on statistics
+     */
+    private evaluateHealth;
+    /**
+     * Test connection availability
+     */
+    private testConnectionAvailability;
+}

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

@@ -0,0 +1,129 @@
+/**
+ * @gravito/atlas - Pool Strategy Engine
+ * @description Strategies for adaptive connection pool management
+ */
+import type { PoolStats } from '../types';
+/**
+ * Pool strategy decision result
+ */
+export interface PoolAdjustmentDecision {
+    /**
+     * Action to take: 'increase' | 'decrease' | 'maintain'
+     */
+    action: 'increase' | 'decrease' | 'maintain';
+    /**
+     * Target pool size
+     */
+    targetSize: number;
+    /**
+     * Reason for the decision
+     */
+    reason: string;
+    /**
+     * Confidence level (0-1)
+     */
+    confidence: number;
+}
+/**
+ * Strategy context for decision making
+ */
+export interface PoolStrategyContext {
+    /**
+     * Current pool statistics
+     */
+    stats: PoolStats;
+    /**
+     * Historical statistics (if available)
+     */
+    history?: PoolStats[];
+    /**
+     * Pool configuration
+     */
+    config: {
+        min?: number;
+        max?: number;
+    };
+    /**
+     * Connection name
+     */
+    connectionName: string;
+}
+/**
+ * Abstract base class for pool adjustment strategies
+ */
+export declare abstract class PoolStrategy {
+    /**
+     * Strategy name
+     */
+    abstract readonly name: string;
+    /**
+     * Make an adjustment decision based on pool context
+     */
+    abstract decide(context: PoolStrategyContext): PoolAdjustmentDecision;
+    /**
+     * Validate if an adjustment decision is acceptable
+     */
+    validateAdjustment(decision: PoolAdjustmentDecision, context: PoolStrategyContext): boolean;
+    /**
+     * Protected helper: calculate utilization ratio
+     */
+    protected calculateUtilization(stats: PoolStats): number;
+    /**
+     * Protected helper: calculate pending ratio
+     */
+    protected calculatePendingRatio(stats: PoolStats): number;
+    /**
+     * Protected helper: clamp value to bounds
+     */
+    protected clampToSize(value: number, context: PoolStrategyContext): number;
+}
+/**
+ * Load-aware strategy: adjusts based on current utilization
+ */
+export declare class LoadAwareStrategy extends PoolStrategy {
+    readonly name = "load-aware";
+    private readonly warningUtilization;
+    private readonly criticalUtilization;
+    private readonly recoveryUtilization;
+    constructor(config?: {
+        warningUtilization?: number;
+        criticalUtilization?: number;
+        recoveryUtilization?: number;
+    });
+    decide(context: PoolStrategyContext): PoolAdjustmentDecision;
+}
+/**
+ * Predictive strategy: adjusts based on historical trends
+ */
+export declare class PredictiveStrategy extends PoolStrategy {
+    readonly name = "predictive";
+    private readonly minHistorySize;
+    constructor(config?: {
+        minHistorySize?: number;
+    });
+    decide(context: PoolStrategyContext): PoolAdjustmentDecision;
+    /**
+     * Calculate linear trend from data points
+     */
+    private calculateTrend;
+}
+/**
+ * Hybrid strategy: combines multiple strategies
+ */
+export declare class HybridStrategy extends PoolStrategy {
+    private loadAware;
+    private predictive;
+    private loadWeight;
+    private predictiveWeight;
+    readonly name = "hybrid";
+    constructor(loadAware: LoadAwareStrategy, predictive: PredictiveStrategy, loadWeight?: number, predictiveWeight?: number);
+    decide(context: PoolStrategyContext): PoolAdjustmentDecision;
+}
+/**
+ * Create default strategies for pool management
+ */
+export declare function createDefaultStrategies(): {
+    loadAware: LoadAwareStrategy;
+    predictive: PredictiveStrategy;
+    hybrid: HybridStrategy;
+};