@gravito/echo 3.0.0 → 3.1.0

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

@@ -0,0 +1,260 @@
+/**
+ * Driver Type Definitions
+ * @description Type definitions for third-party database driver libraries
+ */
+/**
+ * MySQL/MariaDB Pool Connection
+ */
+export interface MySQLPool {
+    query(sql: string, values?: unknown[]): Promise<unknown>;
+    execute(sql: string, values?: unknown[]): Promise<unknown>;
+    getConnection(): Promise<MySQLConnection>;
+    end(): Promise<void>;
+}
+/**
+ * MySQL/MariaDB Connection
+ */
+export interface MySQLConnection {
+    query(sql: string, values?: unknown[]): Promise<unknown>;
+    execute(sql: string, values?: unknown[]): Promise<unknown>;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    release(): void;
+}
+/**
+ * MySQL/MariaDB Module
+ */
+export interface MySQLModule {
+    createPool(config: Record<string, unknown>): MySQLPool;
+    createConnection(config: Record<string, unknown>): Promise<MySQLConnection>;
+}
+/**
+ * PostgreSQL Pool Client
+ */
+export interface PostgresPoolClient {
+    query(sql: string, values?: unknown[]): Promise<{
+        rows: unknown[];
+        rowCount: number;
+    }>;
+    release(): void;
+}
+/**
+ * PostgreSQL Pool
+ */
+export interface PostgresPool {
+    connect(): Promise<PostgresPoolClient>;
+    query(sql: string, values?: unknown[]): Promise<{
+        rows: unknown[];
+        rowCount: number;
+    }>;
+    end(): Promise<void>;
+}
+/**
+ * SQLite Database Client (Bun)
+ */
+export interface SQLiteClient {
+    prepare(sql: string): SQLiteStatement;
+    query(sql: string, ...params: unknown[]): unknown[];
+    run(sql: string, ...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number;
+    };
+    exec?(sql: string): void;
+    pragma?(name: string, value?: unknown): unknown;
+    open?: boolean;
+    inTransaction?: boolean;
+    close(): void;
+}
+/**
+ * SQLite Statement
+ */
+export interface SQLiteStatement {
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number;
+    };
+    all(...params: unknown[]): unknown[];
+    get(...params: unknown[]): unknown;
+}
+/**
+ * Redis Client
+ */
+export interface RedisClient {
+    connect(): Promise<void>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string | number): Promise<'OK'>;
+    setex(key: string, seconds: number, value: string | number): Promise<'OK'>;
+    del(key: string): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    exists(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    quit(): Promise<void>;
+    status?: string;
+}
+/**
+ * MongoDB Client
+ */
+export interface MongoClient {
+    connect(): Promise<void>;
+    db(name?: string): MongoDatabase;
+    close(): Promise<void>;
+}
+/**
+ * MongoDB Database
+ */
+export interface MongoDatabase {
+    collection(name: string): MongoCollection;
+}
+/**
+ * MongoDB Collection
+ */
+export interface MongoCollection {
+    find(filter?: Record<string, unknown>, options?: Record<string, unknown>): MongoCursor;
+    findOne(filter?: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    insertOne(doc: Record<string, unknown>): Promise<{
+        insertedId: unknown;
+    }>;
+    insertMany(docs: Record<string, unknown>[]): Promise<{
+        insertedIds: unknown[];
+        insertedCount: number;
+    }>;
+    countDocuments(filter?: Record<string, unknown>): Promise<number>;
+    updateOne(filter: Record<string, unknown>, update: Record<string, unknown>): Promise<{
+        modifiedCount: number;
+    }>;
+    updateMany(filter: Record<string, unknown>, update: Record<string, unknown>): Promise<{
+        modifiedCount: number;
+    }>;
+    deleteOne(filter: Record<string, unknown>): Promise<{
+        deletedCount: number;
+    }>;
+    deleteMany(filter: Record<string, unknown>): Promise<{
+        deletedCount: number;
+    }>;
+}
+/**
+ * MongoDB Cursor
+ */
+export interface MongoCursor {
+    toArray(): Promise<Record<string, unknown>[]>;
+    limit(n: number): MongoCursor;
+    skip(n: number): MongoCursor;
+    sort(sort: Record<string, 1 | -1>): MongoCursor;
+}
+/**
+ * Bun SQL Client (Enhanced for Bun 1.3+)
+ * @description Comprehensive type definitions for Bun.sql native driver
+ */
+export interface BunSQLClient {
+    (strings: TemplateStringsArray, ...values: unknown[]): Promise<BunSQLResult>;
+    unsafe?(sql: string, bindings?: unknown[]): Promise<BunSQLResult>;
+    query?(sql: string, bindings?: unknown[]): Promise<BunSQLResult>;
+    all?(sql: string, bindings?: unknown[]): Promise<unknown[]>;
+    run?(sql: string, bindings?: unknown[]): Promise<BunSQLResult>;
+    simple?(strings: TemplateStringsArray, ...values: unknown[]): Promise<BunSQLResult>;
+    prepare?(sql: string): BunSQLPreparedStatement;
+    transaction?<T>(callback: (sql: BunSQLClient) => Promise<T>): Promise<T>;
+    begin?(): Promise<BunSQLTransaction>;
+    close?(): Promise<void>;
+    end?(): Promise<void>;
+    readonly connections?: {
+        idle: number;
+        pending: number;
+        active: number;
+        total: number;
+    };
+}
+/**
+ * Bun SQL Query Result
+ * @description Result structure returned by Bun.sql queries
+ */
+export interface BunSQLResult {
+    /**
+     * Result rows (iterable)
+     */
+    rows?: unknown[];
+    /**
+     * Number of rows affected/returned
+     */
+    rowCount?: number;
+    count?: number;
+    /**
+     * Last inserted ID (for INSERT operations)
+     */
+    lastInsertRowid?: number | bigint;
+    /**
+     * Number of changed rows (for UPDATE operations)
+     */
+    changes?: number;
+    /**
+     * Iterator support for streaming
+     */
+    [Symbol.iterator](): Iterator<unknown>;
+}
+/**
+ * Bun SQL Prepared Statement
+ * @description Prepared statement interface for query optimization
+ */
+export interface BunSQLPreparedStatement {
+    /**
+     * Execute prepared statement and return result
+     */
+    run(...params: unknown[]): Promise<BunSQLResult>;
+    /**
+     * Execute and return all rows
+     */
+    all(...params: unknown[]): Promise<unknown[]>;
+    /**
+     * Execute and return first row
+     */
+    get(...params: unknown[]): Promise<unknown | undefined>;
+    /**
+     * Finalize and release the prepared statement
+     */
+    finalize(): void;
+}
+/**
+ * Bun SQL Transaction
+ * @description Transaction handle for advanced transaction control
+ */
+export interface BunSQLTransaction {
+    /**
+     * Commit the transaction
+     */
+    commit(): Promise<void>;
+    /**
+     * Rollback the transaction
+     */
+    rollback(): Promise<void>;
+    /**
+     * Create a savepoint
+     */
+    savepoint?(name: string): Promise<void>;
+    /**
+     * Rollback to a savepoint
+     */
+    rollbackTo?(name: string): Promise<void>;
+    /**
+     * Release a savepoint
+     */
+    release?(name: string): Promise<void>;
+}
+/**
+ * Bun SQL Pool Configuration
+ * @description Configuration options for connection pool
+ */
+export interface BunSQLPoolConfig {
+    /**
+     * Maximum number of connections in the pool
+     */
+    max?: number;
+    /**
+     * Maximum time (ms) a connection can be idle before being released
+     */
+    idleTimeout?: number;
+    /**
+     * Maximum time (ms) to wait for a connection from the pool
+     */
+    connectionTimeout?: number;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Base Database Error
+ */
+export declare class DatabaseError extends Error {
+    readonly originalError: unknown;
+    readonly query?: string;
+    readonly bindings?: unknown[];
+    constructor(message: string, originalError?: unknown, query?: string, bindings?: unknown[]);
+}
+/**
+ * Constraint Violation Error (Base)
+ */
+export declare class ConstraintViolationError extends DatabaseError {
+    constructor(message: string, originalError?: unknown, query?: string, bindings?: unknown[]);
+}
+/**
+ * Unique Constraint Violation
+ */
+export declare class UniqueConstraintError extends ConstraintViolationError {
+    constructor(message: string, originalError?: unknown, query?: string, bindings?: unknown[]);
+}
+/**
+ * Foreign Key Constraint Violation
+ */
+export declare class ForeignKeyConstraintError extends ConstraintViolationError {
+    constructor(message: string, originalError?: unknown, query?: string, bindings?: unknown[]);
+}
+/**
+ * Not Null Constraint Violation
+ */
+export declare class NotNullConstraintError extends ConstraintViolationError {
+    constructor(message: string, originalError?: unknown, query?: string, bindings?: unknown[]);
+}
+/**
+ * Table Not Found Error
+ */
+export declare class TableNotFoundError extends DatabaseError {
+    constructor(message: string, originalError?: unknown, query?: string, bindings?: unknown[]);
+}
+/**
+ * Connection Error
+ */
+export declare class ConnectionError extends DatabaseError {
+    constructor(message: string, originalError?: unknown);
+}

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

@@ -0,0 +1,342 @@
+/**
+ * Abstract SQL Grammar providing base logic for SQL generation.
+ *
+ * Handles the structural assembly of SELECT, INSERT, UPDATE, and DELETE
+ * statements. Includes a sophisticated compilation cache to minimize
+ * string manipulation overhead for repetitive query structures.
+ */
+import { LRUCache } from 'lru-cache';
+import type { CompiledQuery, GrammarContract, HavingClause, JoinClause, OrderClause, WhereClause } from '../types';
+export declare abstract class Grammar implements GrammarContract {
+    /**
+     * Optional prefix for all table names.
+     */
+    protected tablePrefix: string;
+    /**
+     * Database-specific character for wrapping identifiers (e.g., " or `).
+     */
+    protected abstract wrapChar: string;
+    /**
+     * Internal cache for compiled SQL templates.
+     * Keyed by structural hash to allow reuse across different parameter values.
+     */
+    private static compilationCache;
+    /**
+     * Metrics for cache performance monitoring.
+     */
+    private static cacheStats;
+    /**
+     * Global toggle for SQL compilation caching.
+     */
+    static useCache: boolean;
+    /**
+     * Determines if the cache is shared globally or isolated per grammar instance.
+     */
+    static cacheScope: 'global' | 'instance';
+    private _instanceCache?;
+    private _instanceCacheStats;
+    /**
+     * Retrieves performance metrics for the compilation cache.
+     *
+     * @returns Stats including hit rate and utilization.
+     */
+    static getCacheStats(): {
+        size: number;
+        maxSize: number;
+        hits: number;
+        misses: number;
+        sets: number;
+        hitRate: number;
+        missRate: number;
+        totalRequests: number;
+        utilization: number;
+    };
+    /**
+     * Retrieves metrics for the instance-level cache.
+     *
+     * @returns Stats object or null if instance caching is disabled.
+     */
+    getInstanceCacheStats(): {
+        size: number;
+        maxSize: number;
+        hits: number;
+        misses: number;
+        sets: number;
+        hitRate: number;
+        missRate: number;
+        totalRequests: number;
+        utilization: number;
+    } | null;
+    /**
+     * Flushes all performance counters.
+     */
+    static resetCacheStats(): void;
+    /**
+     * Wipes the compilation cache.
+     */
+    static clearCache(): void;
+    /**
+     * Resizes the global compilation cache.
+     *
+     * @param max - Maximum number of templates to store.
+     */
+    static setCacheSize(max: number): void;
+    /**
+     * Resolves the active cache instance based on scope configuration.
+     * @internal
+     */
+    protected getCompilationCache(): LRUCache<string, string>;
+    /**
+     * Returns the database-specific placeholder (e.g., ?, $1, :name).
+     *
+     * @param index - The zero-based binding index.
+     */
+    abstract getPlaceholder(index: number): string;
+    /**
+     * Compiles an INSERT statement that returns the primary key.
+     */
+    abstract compileInsertGetId(query: CompiledQuery, values: Record<string, unknown>, primaryKey: string): string;
+    /**
+     * Transforms a query structure into a SELECT SQL string.
+     *
+     * Leverages caching by generating a structural key that ignores binding values.
+     *
+     * @param query - The structural definition of the query.
+     * @returns The compiled SQL string.
+     */
+    compileSelect(query: CompiledQuery): string;
+    /**
+     * Generates a unique hash representing the SQL structure.
+     *
+     * Ignores specific binding values to allow cache hits for similar queries.
+     * Uses efficient array joining for performance.
+     *
+     * @param query - The query structure.
+     * @returns A deterministic string key.
+     */
+    getStructuralKey(query: CompiledQuery): string;
+    /**
+     * Compiles the SELECT list.
+     * @internal
+     */
+    protected compileColumns(query: CompiledQuery): string;
+    /**
+     * Compiles the FROM clause.
+     * @internal
+     */
+    protected compileFrom(query: CompiledQuery): string;
+    /**
+     * Compiles all WHERE constraints.
+     *
+     * @param query - The query definition.
+     * @param bindingOffset - Initial parameter index.
+     * @returns Compiled SQL snippet.
+     * @internal
+     */
+    protected compileWheres(query: CompiledQuery, bindingOffset?: number): string;
+    /**
+     * @deprecated Use compileWhereWithOffset.
+     */
+    protected compileWhere(where: WhereClause, _query: CompiledQuery): string;
+    /**
+     * Compiles a single WHERE clause with offset awareness.
+     * @internal
+     */
+    protected compileWhereWithOffset(where: WhereClause, offset: number): {
+        sql: string;
+        bindingsUsed: number;
+    };
+    /**
+     * Compiles a standard equality or comparison clause.
+     * @internal
+     */
+    protected compileWhereBasicWithOffset(where: WhereClause, offset: number): string;
+    /**
+     * Compiles an IN clause.
+     * @internal
+     */
+    protected compileWhereInWithOffset(where: WhereClause, offset: number): string;
+    /**
+     * Wraps nested SQL in parentheses.
+     * @internal
+     */
+    protected compileWhereNested(where: WhereClause): string;
+    /**
+     * Compiles IS NULL constraints.
+     * @internal
+     */
+    protected compileWhereNull(where: WhereClause): string;
+    /**
+     * Compiles BETWEEN constraints.
+     * @internal
+     */
+    protected compileWhereBetweenWithOffset(where: WhereClause, offset: number): string;
+    /**
+     * Compiles column-to-column comparisons.
+     * @internal
+     */
+    protected compileWhereColumn(where: WhereClause): string;
+    /**
+     * Compiles all JOIN clauses.
+     * @internal
+     */
+    protected compileJoins(query: CompiledQuery): string;
+    /**
+     * Compiles a single JOIN relationship.
+     * @internal
+     */
+    protected compileJoin(join: JoinClause): string;
+    /**
+     * Compiles the GROUP BY clause.
+     * @internal
+     */
+    protected compileGroups(query: CompiledQuery): string;
+    /**
+     * Compiles all HAVING constraints.
+     * @internal
+     */
+    protected compileHavings(query: CompiledQuery, bindingOffset?: number): string;
+    /**
+     * Sums bindings across all WHERE clauses.
+     * @internal
+     */
+    protected countAllWhereBindings(wheres: WhereClause[]): number;
+    /**
+     * Counts bindings for a specific WHERE type.
+     * @internal
+     */
+    protected countWhereBindings(where: WhereClause): number;
+    /**
+     * Compiles a single HAVING clause.
+     * @internal
+     */
+    protected compileHavingWithOffset(having: HavingClause, offset: number): {
+        sql: string;
+        bindingsUsed: number;
+    };
+    /**
+     * @deprecated
+     */
+    protected compileHaving(having: HavingClause, _query: CompiledQuery): string;
+    /**
+     * Compiles the full ORDER BY clause.
+     * @internal
+     */
+    protected compileOrders(query: CompiledQuery): string;
+    /**
+     * Compiles a single sorting rule.
+     * @internal
+     */
+    protected compileOrder(order: OrderClause): string;
+    /**
+     * Compiles the LIMIT clause.
+     * @internal
+     */
+    protected compileLimit(query: CompiledQuery): string;
+    /**
+     * Compiles the OFFSET clause.
+     * @internal
+     */
+    protected compileOffset(query: CompiledQuery): string;
+    /**
+     * Compiles a multi-row INSERT statement.
+     *
+     * @param query - The query definition.
+     * @param values - Records to insert.
+     * @returns The SQL string.
+     */
+    compileInsert(query: CompiledQuery, values: Record<string, unknown>[]): string;
+    /**
+     * Compiles an UPDATE statement with WHERE constraints.
+     *
+     * @param query - The query definition.
+     * @param values - Fields and values to update.
+     * @returns The SQL string.
+     */
+    compileUpdate(query: CompiledQuery, values: Record<string, unknown>): string;
+    /**
+     * Adjusts placeholders in a pre-compiled snippet.
+     * @internal
+     */
+    protected offsetPlaceholders(sql: string, _offset: number): string;
+    /**
+     * Compiles a DELETE statement.
+     */
+    compileDelete(query: CompiledQuery): string;
+    /**
+     * Compiles a TRUNCATE statement to wipe a table.
+     */
+    compileTruncate(query: CompiledQuery): string;
+    /**
+     * Compiles an aggregate function selection (COUNT, MAX, etc.).
+     */
+    compileAggregate(query: CompiledQuery, aggregate: {
+        function: string;
+        column: string;
+    }): string;
+    /**
+     * Compiles an EXISTS check.
+     */
+    compileExists(query: CompiledQuery): string;
+    /**
+     * Escapes a column name for SQL safety.
+     *
+     * Handles table aliases, raw expressions, and wildcards.
+     *
+     * @param column - The column identifier.
+     */
+    wrapColumn(column: string): string;
+    /**
+     * Escapes a table name.
+     */
+    wrapTable(table: string): string;
+    /**
+     * Internal string escaping.
+     * @internal
+     */
+    protected wrapValue(value: string): string;
+    /**
+     * Manually quotes a value for literal injection.
+     *
+     * Warning: Prefer bindings over manual quoting for security.
+     *
+     * @param value - The value to quote.
+     */
+    quoteValue(value: unknown): string;
+    /**
+     * Configures a prefix for all table references.
+     */
+    setTablePrefix(prefix: string): void;
+    /**
+     * Retrieves the current table prefix.
+     */
+    getTablePrefix(): string;
+    /**
+     * Compiles a query for relationship lateral loading.
+     * @throws {Error} If unsupported by driver.
+     */
+    compileLateralEagerLoad(_table: string, _foreignKey: string, _parentKeys: unknown[], _query: CompiledQuery): {
+        sql: string;
+        bindings: unknown[];
+    };
+    /**
+     * Compiles a JSON path selector.
+     * @throws {Error} If unsupported.
+     */
+    compileJsonPath(_column: string, _value: unknown): string;
+    /**
+     * Compiles a JSON containment check.
+     * @throws {Error} If unsupported.
+     */
+    compileJsonContains(_column: string, _value: unknown): string;
+    /**
+     * Compiles a partial JSON update.
+     * @throws {Error} If unsupported.
+     */
+    compileUpdateJson(_query: CompiledQuery, _column: string, _value: unknown): string;
+    /**
+     * Compiles an UPSERT statement.
+     * @throws {Error} If unsupported.
+     */
+    compileUpsert(_query: CompiledQuery, _values: Record<string, unknown>[], _uniqueBy: string[], _update: string[]): string;
+}

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

@@ -0,0 +1,47 @@
+/**
+ * MongoDB Grammar
+ * @description Translates generic CompiledQuery into a MongoDB Query Protocol (JSON)
+ */
+import type { CompiledQuery } from '../types';
+import { Grammar } from './Grammar';
+/**
+ * MongoDB Query Protocol
+ * Represents the structure passed from Grammar to Driver
+ */
+export interface MongoQueryProtocol {
+    collection: string;
+    operation: 'find' | 'insert' | 'update' | 'delete' | 'aggregate' | 'count';
+    filter?: Record<string, unknown>;
+    options?: Record<string, unknown>;
+    document?: Record<string, unknown> | Record<string, unknown>[];
+    update?: Record<string, unknown>;
+    pipeline?: Record<string, unknown>[];
+}
+/**
+ * Mongo Grammar
+ * Transforms QueryBuilder state into MongoDB commands
+ */
+export declare class MongoGrammar extends Grammar {
+    protected wrapChar: string;
+    getPlaceholder(_index: number): string;
+    compileInsertGetId(query: CompiledQuery, values: Record<string, unknown>, _primaryKey: string): string;
+    compileSelect(query: CompiledQuery): string;
+    compileInsert(query: CompiledQuery, values: Record<string, unknown>[]): string;
+    compileUpdate(query: CompiledQuery, values: Record<string, unknown>): string;
+    compileDelete(query: CompiledQuery): string;
+    compileAggregate(query: CompiledQuery, aggregate: {
+        function: string;
+        column: string;
+    }): string;
+    compileTruncate(query: CompiledQuery): string;
+    /**
+     * Translate generic WhereClause[] to MongoDB Filter
+     */
+    private compileMongoWheres;
+    private normalizeValue;
+    private compileBasicWhere;
+    private compileInWhere;
+    private compileNullWhere;
+    private normalizeColumn;
+    compileJsonPath(column: string, value: unknown): string;
+}