@gravito/ripple 3.0.1 → 4.0.0

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,11 @@
+import { type Counter, type Histogram } from '@opentelemetry/api';
+export interface AtlasMetricsConfig {
+    enabled: boolean;
+}
+export declare class AtlasMetrics {
+    private meter;
+    private config;
+    readonly operationDuration?: Histogram;
+    readonly operationErrors?: Counter;
+    constructor(config: AtlasMetricsConfig);
+}

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

@@ -0,0 +1,5 @@
+/**
+ * ORM Module Index
+ */
+export * from './model';
+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;
+}