@gravito/echo 3.0.0 → 3.1.0

package/dist/atlas/src/orm/schema/SchemaRegistry.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Schema Registry
+ * @description Central registry for table schemas with JIT sniffing and AOT locking
+ */
+import type { ColumnSchema, TableSchema } from './types';
+/**
+ * Schema Registry Mode
+ */
+export type SchemaMode = 'jit' | 'aot';
+/**
+ * Schema Registry Options
+ */
+export interface SchemaRegistryOptions {
+    /** Mode: jit (dev) or aot (prod) */
+    mode?: SchemaMode;
+    /** Path to schema lock file */
+    lockPath?: string;
+    /** Database connection name */
+    connection?: string;
+    /** Cache TTL in milliseconds (JIT mode) */
+    cacheTtl?: number;
+}
+/**
+ * Schema Registry
+ * Central registry for table schemas
+ *
+ * @example
+ * ```typescript
+ * // Dev mode: JIT sniffing
+ * const registry = SchemaRegistry.getInstance({ mode: 'jit' })
+ * const schema = await registry.get('users')
+ *
+ * // Prod mode: AOT from lock file
+ * SchemaRegistry.init({ mode: 'aot', lockPath: '.schema-lock.json' })
+ * const schema = await registry.get('users')
+ * ```
+ */
+export declare class SchemaRegistry {
+    private static instance;
+    private cache;
+    private sniffer;
+    private mode;
+    private lockPath;
+    private cacheTtl;
+    private _initialized;
+    private constructor();
+    /**
+     * Check if registry is initialized
+     */
+    get isInitialized(): boolean;
+    /**
+     * Initialize the registry (call once at startup)
+     */
+    static init(options?: SchemaRegistryOptions): SchemaRegistry;
+    /**
+     * Get the registry instance
+     */
+    static getInstance(): SchemaRegistry;
+    /**
+     * Reset the registry (for testing)
+     */
+    static reset(): void;
+    /**
+     * Get schema for a table
+     */
+    get(table: string, connection?: string): Promise<TableSchema>;
+    /**
+     * Check if table schema exists
+     */
+    has(table: string): boolean;
+    /**
+     * Get column schema
+     */
+    getColumn(table: string, column: string): Promise<ColumnSchema | undefined>;
+    /**
+     * Check if column exists
+     */
+    hasColumn(table: string, column: string): Promise<boolean>;
+    /**
+     * Get all cached tables
+     */
+    getTables(): string[];
+    /**
+     * Invalidate cache for a specific table
+     * Forces re-sniff on next access
+     */
+    invalidate(table: string): void;
+    /**
+     * Invalidate all cached schemas
+     */
+    invalidateAll(): void;
+    /**
+     * Force refresh schema for a table
+     * Re-sniffs even if cached (JIT mode only)
+     */
+    refresh(table: string): Promise<TableSchema>;
+    /**
+     * Wrap a database operation with self-healing
+     * Automatically re-sniffs schema on column-related errors and retries
+     *
+     * @example
+     * ```typescript
+     * const result = await registry.withSelfHealing('users', async () => {
+     *   return await connection.table('users').where('new_column', value).get()
+     * })
+     * ```
+     */
+    withSelfHealing<T>(table: string, operation: () => Promise<T>): Promise<T>;
+    /**
+     * Check if an error is schema-related
+     */
+    private isSchemaError;
+    /**
+     * Load schemas from lock file (AOT mode)
+     */
+    loadFromLock(path?: string): void;
+    /**
+     * Save schemas to lock file
+     */
+    saveToLock(tables: string[], path?: string): Promise<void>;
+    private serializeTableSchema;
+    private deserializeTableSchema;
+}

package/dist/atlas/src/orm/schema/SchemaSniffer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Schema Sniffer
+ * @description Introspects database schema at runtime (JIT mode)
+ */
+import type { TableSchema } from './types';
+/**
+ * Schema Sniffer
+ * Retrieves table schema from database at runtime
+ */
+export declare class SchemaSniffer {
+    private connectionName;
+    constructor(connectionName?: string);
+    /**
+     * Sniff table schema from database
+     */
+    sniff(table: string): Promise<TableSchema>;
+    /**
+     * Sniff SQLite table schema
+     */
+    private sniffSQLite;
+    /**
+     * Sniff PostgreSQL table schema
+     */
+    private sniffPostgres;
+    /**
+     * Sniff MySQL table schema
+     */
+    private sniffMySQL;
+    /**
+     * Map PostgreSQL type to ColumnType
+     */
+    private mapPostgresType;
+    /**
+     * Map MySQL type to ColumnType
+     */
+    private mapMySQLType;
+    private mapSQLiteType;
+    /**
+     * Parse default value
+     */
+    private parseDefault;
+    /**
+     * Extract length from MySQL type
+     */
+    private extractMySQLLength;
+    /**
+     * Extract enum values from MySQL type
+     */
+    private extractMySQLEnumValues;
+    /**
+     * Get driver name
+     */
+    private getDriverName;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Schema Module Index
+ */
+export { type SchemaMode, SchemaRegistry, type SchemaRegistryOptions } from './SchemaRegistry';
+export { SchemaSniffer } from './SchemaSniffer';
+export type { ColumnSchema, ColumnType, SchemaLock, SerializedColumnSchema, SerializedTableSchema, TableSchema, } from './types';

package/dist/atlas/src/orm/schema/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Schema Types
+ * @description Type definitions for schema introspection
+ */
+/**
+ * Column data types
+ */
+export type ColumnType = 'string' | 'text' | 'integer' | 'bigint' | 'smallint' | 'decimal' | 'float' | 'boolean' | 'date' | 'time' | 'datetime' | 'timestamp' | 'json' | 'jsonb' | 'uuid' | 'binary' | 'enum' | 'unknown';
+/**
+ * Column schema definition
+ */
+export interface ColumnSchema {
+    /** Column name */
+    name: string;
+    /** Column type */
+    type: ColumnType;
+    /** Is nullable */
+    nullable: boolean;
+    /** Default value */
+    default?: unknown;
+    /** Is primary key */
+    primary: boolean;
+    /** Is unique */
+    unique: boolean;
+    /** Is auto-increment */
+    autoIncrement: boolean;
+    /** Enum values (if type is enum) */
+    enumValues?: string[] | undefined;
+    /** Max length (for string types) */
+    maxLength?: number | undefined;
+    /** Numeric precision */
+    precision?: number | undefined;
+    /** Numeric scale */
+    scale?: number | undefined;
+}
+/**
+ * Table schema definition
+ */
+export interface TableSchema {
+    /** Table name */
+    table: string;
+    /** Column definitions */
+    columns: Map<string, ColumnSchema>;
+    /** Primary key column(s) */
+    primaryKey: string[];
+    /** Timestamp of schema capture */
+    capturedAt: number;
+}
+/**
+ * Schema lock file format
+ */
+export interface SchemaLock {
+    /** Version for compatibility */
+    version: string;
+    /** Driver used to generate */
+    driver: string;
+    /** Generation timestamp */
+    generatedAt: string;
+    /** Table schemas */
+    tables: Record<string, SerializedTableSchema>;
+}
+/**
+ * Serialized table schema (for JSON storage)
+ */
+export interface SerializedTableSchema {
+    table: string;
+    columns: SerializedColumnSchema[];
+    primaryKey: string[];
+}
+/**
+ * Serialized column schema (for JSON storage)
+ */
+export interface SerializedColumnSchema {
+    name: string;
+    type: ColumnType;
+    nullable: boolean;
+    default?: unknown;
+    primary: boolean;
+    unique: boolean;
+    autoIncrement: boolean;
+    enumValues?: string[] | undefined;
+    maxLength?: number | undefined;
+    precision?: number | undefined;
+    scale?: number | undefined;
+}

package/dist/atlas/src/query/Expression.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Raw SQL Expression
+ * @description Represents a raw SQL expression that should not be escaped by the query builder.
+ * Use this for complex SQL fragments, function calls, or database-specific syntax.
+ */
+export declare class Expression {
+    private readonly sql;
+    private readonly bindings;
+    /**
+     * Create a new Expression instance
+     *
+     * @param sql - The raw SQL string
+     * @param bindings - Optional array of bindings for the expression
+     */
+    constructor(sql: string, bindings?: unknown[]);
+    /**
+     * Get the raw SQL string
+     *
+     * @returns The SQL string
+     */
+    getValue(): string;
+    /**
+     * Get the bindings associated with this expression
+     *
+     * @returns Array of bindings
+     */
+    getBindings(): unknown[];
+    /**
+     * Convert the expression to its SQL string representation
+     *
+     * @returns The SQL string
+     */
+    toString(): string;
+}
+/**
+ * Create a raw SQL expression
+ *
+ * @param sql - The raw SQL string
+ * @param bindings - Optional array of bindings
+ * @returns A new Expression instance
+ * @example
+ * ```typescript
+ * DB.table('users').select(raw('COUNT(*) as total')).get()
+ * ```
+ */
+export declare function raw(sql: string, bindings?: unknown[]): Expression;
+/**
+ * Tagged template literal for safe raw SQL construction
+ *
+ * @param strings - Template strings
+ * @param values - Values to be used as bindings
+ * @returns A new Expression instance with auto-generated placeholders
+ * @example
+ * ```typescript
+ * const userId = 1;
+ * const query = sql`SELECT * FROM users WHERE id = ${userId}`;
+ * // Result: Expression { sql: "SELECT * FROM users WHERE id = ?", bindings: [1] }
+ * ```
+ */
+export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): Expression;

package/dist/atlas/src/query/NPlusOneDetector.d.ts

@@ -0,0 +1,10 @@
+export declare class NPlusOneDetector {
+    private static queryCounts;
+    private static timeframe;
+    private static threshold;
+    private static enabled;
+    static track(tableName: string, sql: string, structureKey: string): void;
+    static reset(): void;
+    static setEnabled(enabled: boolean): void;
+    private static warn;
+}