@gravito/ripple 3.1.0 → 4.0.1

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

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,79 @@
+/**
+ * @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 { defineConfig, fromEnv, loadConfig, loadConfigFile } from './config';
+export { Connection } from './connection/Connection';
+export { ConnectionManager } from './connection/ConnectionManager';
+export { ReplicaConnectionPool } from './connection/ReplicaConnectionPool';
+export { DB } from './DB';
+import { DB } from './DB';
+export declare const autoConfigure: typeof DB.autoConfigure;
+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, ModelRepository, 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 { MigrationGenerator } from './schema/MigrationGenerator';
+export type { ColumnDefinition as SchemaColumnDefinition, SchemaDiffResult, } from './schema/SchemaDiff';
+export { SchemaDiff } from './schema/SchemaDiff';
+export type { ModelTypeMap, TypeGeneratorOptions } from './schema/TypeGenerator';
+export { TypeGenerator } from './schema/TypeGenerator';
+export { TypeWriter } from './schema/TypeWriter';
+export type { FactoryDefinition, Seeder, SeederFile, SeederRunnerOptions } from './seed';
+export { Factory, factory, SeederRunner } from './seed';
+export { type ShardingConfig, ShardingManager } from './sharding/ShardingManager';
+export type { AtlasConnectionEntry, BooleanOperator, CompiledQuery, ConnectionConfig, ConnectionContract, CursorPaginateResult, DriverContract, DriverType, ExecuteResult, FieldInfo, GrammarContract, HavingClause, isReadWriteConfig, JoinClause, JoinType, MySQLConfig, Operator, OrderClause, OrderDirection, PaginateResult, PoolConfig, PostgresConfig, QueryBuilderContract, QueryResult, ReadWriteConnectionConfig, SQLiteConfig, SSLConfig, WhereClause, } from './types';
+export type { CursorPayload } from './utils/CursorEncoding';
+export { buildCursorWhereClause, decodeCursor, encodeCursor, } from './utils/CursorEncoding';