@gravito/echo 3.0.0 → 3.1.0

package/dist/atlas/src/grammar/MySQLGrammar.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MySQL Grammar
+ * @description SQL grammar implementation for MySQL/MariaDB
+ */
+import type { CompiledQuery } from '../types';
+import { Grammar } from './Grammar';
+/**
+ * MySQL Grammar
+ * Implements MySQL/MariaDB-specific SQL syntax
+ */
+export declare class MySQLGrammar extends Grammar {
+    /**
+     * MySQL uses backticks for identifiers
+     */
+    protected wrapChar: string;
+    /**
+     * Get placeholder for MySQL (?)
+     */
+    getPlaceholder(_index: number): string;
+    /**
+     * Compile INSERT and return ID using LAST_INSERT_ID()
+     */
+    compileInsertGetId(query: CompiledQuery, values: Record<string, unknown>, _primaryKey: string): string;
+    /**
+     * Compile TRUNCATE for MySQL
+     */
+    compileTruncate(query: CompiledQuery): string;
+    /**
+     * MySQL-specific: Compile UPSERT using ON DUPLICATE KEY UPDATE
+     */
+    compileUpsert(query: CompiledQuery, values: Record<string, unknown>[], _uniqueBy: string[], update: string[]): string;
+    /**
+     * MySQL-specific: Compile locking clause
+     */
+    compileLock(mode: 'update' | 'share'): string;
+    /**
+     * Override offset placeholders - MySQL uses ? for all
+     */
+    protected offsetPlaceholders(sql: string, _offset: number): string;
+    /**
+     * Compile EXISTS with MySQL syntax
+     */
+    compileExists(query: CompiledQuery): string;
+    /**
+     * Override aggregate to use backticks
+     */
+    compileAggregate(query: CompiledQuery, aggregate: {
+        function: string;
+        column: string;
+    }): string;
+    compileJsonPath(column: string, _value: unknown): string;
+    compileJsonContains(column: string, _value: unknown): string;
+    compileUpdateJson(query: CompiledQuery, column: string, _value: unknown): string;
+}

package/dist/atlas/src/grammar/NullGrammar.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Null Grammar
+ * @description A fallback grammar for non-SQL drivers
+ */
+import type { CompiledQuery, GrammarContract } from '../types';
+/**
+ * Null Grammar
+ * Used for MongoDB, Redis, etc. where SQL compilation is not needed.
+ */
+export declare class NullGrammar implements GrammarContract {
+    compileSelect(_query: CompiledQuery): string;
+    compileInsert(_query: CompiledQuery, _values: Record<string, unknown>[]): string;
+    compileInsertGetId(_query: CompiledQuery, _values: Record<string, unknown>, _primaryKey: string): string;
+    compileUpdate(_query: CompiledQuery, _values: Record<string, unknown>): string;
+    compileDelete(_query: CompiledQuery): string;
+    compileTruncate(_query: CompiledQuery): string;
+    compileAggregate(_query: CompiledQuery, _aggregate: {
+        function: string;
+        column: string;
+    }): string;
+    compileExists(_query: CompiledQuery): string;
+    getPlaceholder(_index: number): string;
+    wrapColumn(column: string): string;
+    wrapTable(table: string): string;
+    quoteValue(value: unknown): string;
+    compileLateralEagerLoad(_table: string, _foreignKey: string, _parentKeys: unknown[], _query: CompiledQuery): {
+        sql: string;
+        bindings: unknown[];
+    };
+    getStructuralKey(_query: CompiledQuery): string;
+    compileJsonPath(column: string, _value: unknown): string;
+    compileJsonContains(column: string, _value: unknown): string;
+    compileUpdateJson(_query: CompiledQuery, column: string, _value: unknown): string;
+    compileUpsert(_query: CompiledQuery, _values: Record<string, unknown>[], _uniqueBy: string[], _update: string[]): string;
+}

package/dist/atlas/src/grammar/PostgresGrammar.d.ts

@@ -0,0 +1,62 @@
+/**
+ * PostgreSQL Grammar
+ * @description SQL grammar implementation for PostgreSQL
+ */
+import type { CompiledQuery } from '../types';
+import { Grammar } from './Grammar';
+/**
+ * PostgreSQL Grammar
+ * Implements PostgreSQL-specific SQL syntax
+ */
+export declare class PostgresGrammar extends Grammar {
+    /**
+     * PostgreSQL uses double quotes for identifiers
+     */
+    protected wrapChar: string;
+    /**
+     * Get placeholder for PostgreSQL ($1, $2, $3...)
+     */
+    getPlaceholder(index: number): string;
+    /**
+     * Compile INSERT and return ID using RETURNING clause
+     */
+    compileInsertGetId(query: CompiledQuery, values: Record<string, unknown>, primaryKey: string): string;
+    /**
+     * Compile INSERT with RETURNING clause for PostgreSQL
+     */
+    compileInsert(query: CompiledQuery, values: Record<string, unknown>[]): string;
+    /**
+     * Compile UPDATE with RETURNING clause for PostgreSQL
+     */
+    compileUpdate(query: CompiledQuery, values: Record<string, unknown>): string;
+    /**
+     * Compile TRUNCATE with CASCADE option for PostgreSQL
+     */
+    compileTruncate(query: CompiledQuery): string;
+    /**
+     * PostgreSQL-specific: Compile UPSERT using ON CONFLICT
+     */
+    compileUpsert(query: CompiledQuery, values: Record<string, unknown>[], uniqueBy: string[], update: string[]): string;
+    /**
+     * PostgreSQL-specific: Compile locking clause
+     */
+    compileLock(mode: 'update' | 'share'): string;
+    /**
+     * Override offset placeholders for PostgreSQL
+     */
+    protected offsetPlaceholders(sql: string, offset: number): string;
+    /**
+     * Compile a lateral eager load query for PostgreSQL
+     */
+    compileLateralEagerLoad(_table: string, foreignKey: string, parentKeys: unknown[], query: CompiledQuery): {
+        sql: string;
+        bindings: unknown[];
+    };
+    /**
+     * Guess the PostgreSQL type for an array of values
+     */
+    protected guessType(values: unknown[]): string;
+    compileJsonPath(column: string, path: string[]): string;
+    compileJsonContains(column: string, _value: unknown): string;
+    compileUpdateJson(query: CompiledQuery, column: string, _value: unknown): string;
+}

package/dist/atlas/src/grammar/SQLiteGrammar.d.ts

@@ -0,0 +1,32 @@
+/**
+ * SQLite Grammar
+ * @description SQL grammar implementation for SQLite
+ */
+import type { CompiledQuery } from '../types';
+import { Grammar } from './Grammar';
+/**
+ * SQLite Grammar
+ * Implements SQLite-specific SQL syntax
+ */
+export declare class SQLiteGrammar extends Grammar {
+    /**
+     * SQLite uses double quotes for identifiers
+     */
+    protected wrapChar: string;
+    /**
+     * Get placeholder for SQLite (?)
+     */
+    getPlaceholder(_index: number): string;
+    /**
+     * Compile INSERT statement with RETURNING *
+     */
+    compileInsert(query: CompiledQuery, values: Record<string, unknown>[]): string;
+    compileInsertGetId(query: CompiledQuery, values: Record<string, unknown>, primaryKey: string): string;
+    /**
+     * Compile TRUNCATE statement
+     * SQLite doesn't have TRUNCATE, use DELETE FROM
+     */
+    compileTruncate(query: CompiledQuery): string;
+    compileJsonPath(column: string, _value: unknown): string;
+    compileJsonContains(_column: string, _value: unknown): string;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * @gravito/atlas
+ * @description The Standard Database Orbit - Custom Query Builder & ORM for Gravito
+ *
+ * @example
+ * ```typescript
+ * import { DB } from '@gravito/atlas'
+ *
+ * // Configure
+ * DB.addConnection('default', {
+ *   driver: 'postgres',
+ *   host: 'localhost',
+ *   port: 5432,
+ *   database: 'myapp',
+ *   username: 'postgres',
+ *   password: 'secret'
+ * })
+ *
+ * // Query
+ * const users = await DB.table('users')
+ *   .where('status', 'active')
+ *   .orderBy('created_at', 'desc')
+ *   .limit(10)
+ *   .get()
+ *
+ * // Insert
+ * const newUser = await DB.table('users').insert({
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * })
+ *
+ * // Update
+ * await DB.table('users')
+ *   .where('id', 1)
+ *   .update({ name: 'Jane Doe' })
+ *
+ * // Transaction
+ * await DB.transaction(async (db) => {
+ *   await db.table('accounts').where('id', 1).decrement('balance', 100)
+ *   await db.table('accounts').where('id', 2).increment('balance', 100)
+ * })
+ * ```
+ */
+export type { AtlasConfig } from './config';
+export { autoConfigure, defineConfig, fromEnv, loadConfig, loadConfigFile } from './config';
+export { Connection } from './connection/Connection';
+export { ConnectionManager } from './connection/ConnectionManager';
+export { DB } from './DB';
+export { BunSQLDriver } from './drivers/BunSQLDriver';
+export { PostgresDriver } from './drivers/PostgresDriver';
+export { SQLiteDriver } from './drivers/SQLiteDriver';
+export { ConnectionError, ConstraintViolationError, DatabaseError, ForeignKeyConstraintError, NotNullConstraintError, TableNotFoundError, UniqueConstraintError, } from './errors';
+export { Grammar } from './grammar/Grammar';
+export { PostgresGrammar } from './grammar/PostgresGrammar';
+export type { Migration, MigrationFile, MigrationRecord, MigrationResult, MigratorOptions, } from './migration';
+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 { 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 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';

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;
+}