@gravito/ripple 3.1.0 → 4.0.1

package/dist/atlas/src/migration/Migration.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Migration Interface
+ * @description Contract for database migration classes
+ */
+/**
+ * Migration Interface
+ *
+ * All database migration classes must implement this interface.
+ * The `up` method is used to apply changes (e.g., create tables),
+ * while the `down` method is used to reverse those changes.
+ *
+ * @example
+ * ```typescript
+ * import { Migration, Schema } from '@gravito/atlas'
+ *
+ * export default class CreateUsersTable implements Migration {
+ *   async up(): Promise<void> {
+ *     await Schema.create('users', (table) => {
+ *       table.id()
+ *       table.string('email').unique()
+ *       table.timestamps()
+ *     })
+ *   }
+ *
+ *   async down(): Promise<void> {
+ *     await Schema.dropIfExists('users')
+ *   }
+ * }
+ * ```
+ */
+export interface Migration {
+    /**
+     * Run the migration (create tables, add columns, etc.)
+     */
+    up(): Promise<void>;
+    /**
+     * Reverse the migration (drop tables, remove columns, etc.)
+     */
+    down(): Promise<void>;
+}
+/**
+ * Migration constructor type
+ */
+export type MigrationConstructor = new () => Migration;
+/**
+ * Migration record stored in the database
+ */
+export interface MigrationRecord {
+    /** Migration ID */
+    id: number;
+    /** Migration file name (without path) */
+    migration: string;
+    /** Batch number when the migration was run */
+    batch: number;
+}
+/**
+ * Migration file info
+ */
+export interface MigrationFile {
+    /** Migration file name (without path) */
+    name: string;
+    /** Full file path */
+    path: string;
+}

package/dist/atlas/src/migration/MigrationRepository.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Migration Repository
+ * @description Tracks migration execution state in the database
+ */
+import type { MigrationRecord } from './Migration';
+/**
+ * Migration Repository
+ *
+ * The MigrationRepository class manages the database table that tracks
+ * which migrations have been executed. It provides methods for logging
+ * migrations, retrieving the list of ran migrations, and managing batches.
+ */
+export declare class MigrationRepository {
+    private tableName;
+    private connectionName;
+    constructor(connectionName?: string);
+    /**
+     * Set the table name for migrations
+     */
+    setTable(table: string): this;
+    /**
+     * Create the migration repository table if it doesn't exist
+     */
+    createRepository(): Promise<void>;
+    /**
+     * Check if the migration repository exists
+     */
+    repositoryExists(): Promise<boolean>;
+    /**
+     * Delete the migration repository table
+     */
+    deleteRepository(): Promise<void>;
+    /**
+     * Get all ran migrations
+     */
+    getRan(): Promise<string[]>;
+    /**
+     * Get migrations for a specific batch
+     */
+    getMigrations(batch: number): Promise<MigrationRecord[]>;
+    /**
+     * Get the last batch number
+     */
+    getLastBatchNumber(): Promise<number>;
+    /**
+     * Get the next batch number
+     */
+    getNextBatchNumber(): Promise<number>;
+    /**
+     * Log that a migration was run
+     */
+    log(migration: string, batch: number): Promise<void>;
+    /**
+     * Remove a migration from the log
+     */
+    delete(migration: string): Promise<void>;
+    /**
+     * Get the last migrations (for rollback)
+     */
+    getLast(): Promise<MigrationRecord[]>;
+    /**
+     * Get the database connection
+     */
+    private getConnection;
+}

package/dist/atlas/src/migration/Migrator.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Migrator
+ * @description Migration runner with support for running and rolling back migrations
+ */
+/**
+ * Migrator Options
+ */
+export interface MigratorOptions {
+    /** Path to migrations directory */
+    path?: string;
+    /** Database connection name */
+    connection?: string;
+    /** Migration table name */
+    table?: string;
+}
+/**
+ * Migration Result
+ */
+export interface MigrationResult {
+    /** Migrations that were run */
+    migrations: string[];
+    /** Batch number */
+    batch?: number;
+}
+/**
+ * Migrator
+ *
+ * The Migrator class is responsible for managing the database migration lifecycle.
+ * It handles discovering migration files, tracking which migrations have been run
+ * in the database, and executing the `up` or `down` methods of migration classes.
+ *
+ * @example
+ * ```typescript
+ * const migrator = new Migrator({ path: './migrations' })
+ *
+ * // Run all pending migrations
+ * await migrator.run()
+ *
+ * // Rollback the last batch of migrations
+ * await migrator.rollback()
+ * ```
+ */
+export declare class Migrator {
+    private repository;
+    private migrationsPath;
+    private resolvedMigrations;
+    constructor(options?: MigratorOptions);
+    /**
+     * Set migrations path
+     */
+    setPath(path: string): this;
+    /**
+     * Set database connection
+     */
+    connection(name: string): this;
+    /**
+     * Run all pending migrations.
+     *
+     * This method will identify all migration files that have not yet been
+     * recorded in the migrations table and execute their `up` method.
+     *
+     * @returns A promise that resolves to the migration result.
+     */
+    run(): Promise<MigrationResult>;
+    /**
+     * Run a specific migration up
+     */
+    runUp(migrationName: string): Promise<void>;
+    /**
+     * Rollback the last batch of migrations.
+     *
+     * This method will identify the migrations that were part of the last
+     * execution batch and execute their `down` method.
+     *
+     * @param steps The number of batches to rollback (defaults to 1).
+     * @returns A promise that resolves to the migration result.
+     */
+    rollback(steps?: number): Promise<MigrationResult>;
+    /**
+     * Rollback all migrations
+     */
+    reset(): Promise<MigrationResult>;
+    /**
+     * Reset and re-run all migrations
+     */
+    fresh(): Promise<MigrationResult>;
+    /**
+     * Rollback and re-run the last batch
+     */
+    refresh(steps?: number): Promise<MigrationResult>;
+    /**
+     * Get migration status
+     */
+    status(): Promise<{
+        ran: string[];
+        pending: string[];
+    }>;
+    /**
+     * Get all migration files from the migrations directory
+     */
+    private getMigrationFiles;
+    /**
+     * Run a single migration
+     */
+    private runMigration;
+    /**
+     * Resolve migration class from file
+     */
+    private resolveMigration;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Migration Module Index
+ */
+export type { Migration, MigrationConstructor, MigrationFile, MigrationRecord } from './Migration';
+export { MigrationRepository } from './MigrationRepository';
+export { type MigrationResult, Migrator, type MigratorOptions } from './Migrator';

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

@@ -0,0 +1,33 @@
+import { type Counter, type Histogram } from '@opentelemetry/api';
+export interface AtlasMetricsConfig {
+    enabled: boolean;
+}
+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;
+}

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

@@ -0,0 +1,15 @@
+import { AtlasMetrics, type AtlasMetricsConfig } from './AtlasMetrics';
+import { AtlasTracer, type AtlasTracingConfig } from './AtlasTracer';
+export declare class AtlasObservability {
+    private static instance;
+    tracer?: AtlasTracer;
+    metrics?: AtlasMetrics;
+    private constructor();
+    static getInstance(): AtlasObservability;
+    initialize(config: {
+        tracing?: AtlasTracingConfig;
+        metrics?: AtlasMetricsConfig;
+    }): void;
+    static getTracer(): AtlasTracer | undefined;
+    static getMetrics(): AtlasMetrics | undefined;
+}

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

@@ -0,0 +1,12 @@
+import { type Context, type Span } from '@opentelemetry/api';
+export interface AtlasTracingConfig {
+    enabled: boolean;
+    serviceName?: string;
+}
+export declare class AtlasTracer {
+    private tracer;
+    private config;
+    constructor(config: AtlasTracingConfig);
+    startSpan(name: string, attributes?: Record<string, any>): Span | undefined;
+    getActiveContext(): Context;
+}

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

@@ -0,0 +1,9 @@
+export * from './AtlasMetrics';
+export * from './AtlasObservability';
+export * from './AtlasTracer';
+export interface AtlasObservabilityConfig {
+    enabled: boolean;
+    tracing?: boolean;
+    metrics?: boolean;
+    serviceName?: string;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * ORM Module Index
+ */
+export * from './model';
+export { ModelRepository } from './Repository';
+export * from './schema';

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

@@ -0,0 +1,121 @@
+/**
+ * Dirty Tracker for monitoring attribute modifications on model instances.
+ *
+ * Maintains a snapshot of original values and tracks which keys have been
+ * changed. Supports optimized structural comparison and deep change detection
+ * for complex objects.
+ *
+ * @template T - The shape of the model attributes.
+ */
+export declare class DirtyTracker<T extends Record<string, unknown>> {
+    /**
+     * Stores the initial values as retrieved from the database.
+     */
+    private original;
+    /**
+     * Tracks keys that differ from their original state.
+     */
+    private dirty;
+    /**
+     * When enabled, nested objects are compared recursively.
+     */
+    private useDeepComparison;
+    /**
+     * Configures the comparison strategy for nested structures.
+     *
+     * @param enabled - True to enable recursive comparison.
+     */
+    setDeepComparison(enabled: boolean): void;
+    /**
+     * Records initial state and clears the dirty set.
+     *
+     * Called typically during hydration or after a successful save.
+     *
+     * @param data - The baseline values.
+     */
+    setOriginal(data: Partial<T>): void;
+    /**
+     * Checks for changes and updates the dirty set accordingly.
+     *
+     * Compares the new value against the original. If they match, the key
+     * is removed from the dirty set (reversion).
+     *
+     * @param key - The attribute name.
+     * @param newValue - The proposed new value.
+     */
+    mark(key: keyof T, newValue: unknown): void;
+    /**
+     * Indicates if any attributes or a specific attribute has been modified.
+     *
+     * @param key - Optional specific attribute to check.
+     * @returns True if changes are detected.
+     */
+    isDirty(key?: keyof T): boolean;
+    /**
+     * Returns a list of all modified attribute names.
+     */
+    getDirty(): Array<keyof T>;
+    /**
+     * Extracts current values for all dirty attributes.
+     *
+     * @param current - The source object containing all current values.
+     * @returns An object with only the modified entries.
+     */
+    getDirtyValues(current: Partial<T>): Partial<T>;
+    /**
+     * Retrieves the original value of an attribute from the snapshot.
+     */
+    getOriginal(key: keyof T): unknown;
+    /**
+     * Retrieves the complete original snapshot.
+     */
+    getOriginals(): Partial<T>;
+    /**
+     * Synchronizes the snapshot with the current state.
+     *
+     * @param data - The new baseline data.
+     */
+    sync(data: Partial<T>): void;
+    /**
+     * Reverts the dirty flag for a specific attribute.
+     */
+    reset(key: keyof T): void;
+    /**
+     * Clears all tracking information.
+     */
+    resetAll(): void;
+    /**
+     * Compares two values for equality using optimized structural comparison.
+     *
+     * Performs shallow comparison by default. Avoids JSON.stringify overhead
+     * by using recursive structural comparison for arrays, maps, and sets.
+     *
+     * @param a - First value.
+     * @param b - Second value.
+     * @returns True if equal.
+     * @internal
+     */
+    private isEqual;
+    /**
+     * Performs deep equality comparison with cycle detection.
+     *
+     * @param a - First value.
+     * @param b - Second value.
+     * @param visited - Set tracking visited objects.
+     * @returns True if deeply equal.
+     * @internal
+     */
+    private deepEqual;
+    /**
+     * Clones a value to ensure the original snapshot remains immutable.
+     *
+     * @param value - Value to clone.
+     * @internal
+     */
+    private cloneValue;
+    /**
+     * Performs recursive deep cloning.
+     * @internal
+     */
+    private deepClone;
+}