@gravito/echo 3.0.0 → 3.1.0

package/dist/atlas/src/schema/Blueprint.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Blueprint
+ * @description Fluent interface for defining table schema
+ */
+import { ColumnDefinition, type ForeignKeyAction } from './ColumnDefinition';
+import type { ForeignKeyDefinition, IndexDefinition } from './ForeignKeyDefinition';
+/**
+ * Blueprint
+ *
+ * The Blueprint class provides a fluent interface for defining table schema.
+ * It is used within the `Schema.create` and `Schema.table` callbacks to
+ * define columns, indexes, and foreign keys.
+ *
+ * @example
+ * ```typescript
+ * Schema.create('users', (table) => {
+ *   table.id()
+ *   table.string('email').unique()
+ *   table.string('password')
+ *   table.timestamps()
+ * })
+ * ```
+ */
+export declare class Blueprint {
+    /** Table name */
+    readonly table: string;
+    /** Column definitions */
+    private _columns;
+    /** Index definitions */
+    private _indexes;
+    /** Foreign key definitions (standalone) */
+    private _foreignKeys;
+    /** Columns to drop */
+    private _dropColumns;
+    /** Indexes to drop */
+    private _dropIndexes;
+    /** Foreign keys to drop */
+    private _dropForeignKeys;
+    constructor(table: string);
+    /**
+     * Create a new auto-incrementing BIGINT primary key column.
+     *
+     * @param name The name of the column (defaults to 'id').
+     * @returns The ColumnDefinition instance for further modification.
+     */
+    id(name?: string): ColumnDefinition;
+    /**
+     * Create a new UUID primary key column.
+     *
+     * @param name The name of the column (defaults to 'id').
+     * @returns The ColumnDefinition instance for further modification.
+     */
+    uuid(name?: string): ColumnDefinition;
+    /**
+     * Create a new integer column.
+     *
+     * @param name The name of the column.
+     * @returns The ColumnDefinition instance for further modification.
+     */
+    integer(name: string): ColumnDefinition;
+    /**
+     * SMALLINT column
+     */
+    smallInteger(name: string): ColumnDefinition;
+    /**
+     * BIGINT column
+     */
+    bigInteger(name: string): ColumnDefinition;
+    /**
+     * DECIMAL column
+     */
+    decimal(name: string, precision?: number, scale?: number): ColumnDefinition;
+    /**
+     * FLOAT column
+     */
+    float(name: string): ColumnDefinition;
+    /**
+     * BOOLEAN column
+     */
+    boolean(name: string): ColumnDefinition;
+    /**
+     * Create a new string (VARCHAR) column.
+     *
+     * @param name The name of the column.
+     * @param length The maximum length of the string (defaults to 255).
+     * @returns The ColumnDefinition instance for further modification.
+     */
+    string(name: string, length?: number): ColumnDefinition;
+    /**
+     * TEXT column
+     */
+    text(name: string): ColumnDefinition;
+    /**
+     * ENUM column
+     */
+    enum(name: string, values: string[]): ColumnDefinition;
+    /**
+     * SET column (MySQL)
+     */
+    set(name: string, values: string[]): ColumnDefinition;
+    /**
+     * DATE column
+     */
+    date(name: string): ColumnDefinition;
+    /**
+     * TIME column
+     */
+    time(name: string): ColumnDefinition;
+    /**
+     * TIME WITH TIME ZONE column
+     */
+    timeTz(name: string): ColumnDefinition;
+    /**
+     * DATETIME column
+     */
+    dateTime(name: string): ColumnDefinition;
+    /**
+     * DATETIME WITH TIME ZONE column
+     */
+    dateTimeTz(name: string): ColumnDefinition;
+    /**
+     * TIMESTAMP column
+     */
+    timestamp(name: string): ColumnDefinition;
+    /**
+     * TIMESTAMP WITH TIME ZONE column
+     */
+    timestampTz(name: string): ColumnDefinition;
+    /**
+     * Add `created_at` and `updated_at` TIMESTAMP columns to the table.
+     */
+    timestamps(): void;
+    /**
+     * created_at and updated_at TIMESTAMP WITH TZ columns
+     */
+    timestampsTz(): void;
+    /**
+     * deleted_at TIMESTAMP column for soft deletes
+     */
+    softDeletes(name?: string): ColumnDefinition;
+    /**
+     * deleted_at TIMESTAMP WITH TZ column for soft deletes
+     */
+    softDeletesTz(name?: string): ColumnDefinition;
+    /**
+     * BINARY/BLOB column
+     */
+    binary(name: string): ColumnDefinition;
+    /**
+     * JSON column
+     */
+    json(name: string): ColumnDefinition;
+    /**
+     * JSONB column (PostgreSQL)
+     */
+    jsonb(name: string): ColumnDefinition;
+    /**
+     * MAC address column
+     */
+    macAddress(name: string): ColumnDefinition;
+    /**
+     * IP address column
+     */
+    ipAddress(name: string): ColumnDefinition;
+    /**
+     * VECTOR column (PostgreSQL pgvector)
+     */
+    vector(name: string, dimensions?: number): ColumnDefinition;
+    /**
+     * remember_token VARCHAR(100) column
+     */
+    rememberToken(): ColumnDefinition;
+    /**
+     * Create a new BIGINT UNSIGNED column for a foreign key.
+     *
+     * @param name The name of the column.
+     * @returns The ColumnDefinition instance for further modification.
+     *
+     * @example
+     * ```typescript
+     * table.foreignId('user_id').constrained().onDelete('cascade')
+     * ```
+     */
+    foreignId(name: string): ColumnDefinition;
+    /**
+     * Add a standalone foreign key constraint to the table.
+     *
+     * @param column The name of the local column.
+     * @returns A ForeignKeyBuilder instance to define the reference.
+     *
+     * @example
+     * ```typescript
+     * table.foreign('user_id').references('id').on('users')
+     * ```
+     */
+    foreign(column: string): ForeignKeyBuilder;
+    /**
+     * Add PRIMARY KEY constraint
+     */
+    primary(columns: string | string[], name?: string): this;
+    /**
+     * Add a UNIQUE index to the table.
+     *
+     * @param columns The column(s) to include in the index.
+     * @param name The name of the index (optional).
+     * @returns The Blueprint instance for chaining.
+     */
+    unique(columns: string | string[], name?: string): this;
+    /**
+     * Add a basic index to the table.
+     *
+     * @param columns The column(s) to include in the index.
+     * @param name The name of the index (optional).
+     * @returns The Blueprint instance for chaining.
+     */
+    index(columns: string | string[], name?: string): this;
+    /**
+     * Add FULLTEXT index
+     */
+    fullText(columns: string | string[], language?: string, name?: string): this;
+    /**
+     * Add SPATIAL index (not supported in SQLite)
+     */
+    spatialIndex(columns: string | string[], name?: string): this;
+    /**
+     * Drop a column
+     */
+    dropColumn(column: string | string[]): this;
+    /**
+     * Drop an index
+     */
+    dropIndex(name: string | string[]): this;
+    /**
+     * Drop a foreign key
+     */
+    dropForeign(columns: string | string[]): this;
+    getColumns(): ColumnDefinition[];
+    getIndexes(): IndexDefinition[];
+    getForeignKeys(): ForeignKeyDefinition[];
+    getDropColumns(): string[];
+    getDropIndexes(): string[];
+    getDropForeignKeys(): string[];
+    private addColumn;
+    addForeignKey(fk: ForeignKeyDefinition): void;
+}
+/**
+ * Foreign Key Builder (for standalone FK definitions)
+ */
+declare class ForeignKeyBuilder {
+    private readonly blueprint;
+    private column;
+    private referencedColumn;
+    private referencedTable;
+    private onDeleteAction;
+    private onUpdateAction;
+    constructor(blueprint: Blueprint, column: string);
+    /**
+     * Set the referenced column
+     */
+    references(column: string): this;
+    /**
+     * Set the referenced table
+     */
+    on(table: string): this;
+    /**
+     * Set ON DELETE action
+     */
+    onDelete(action: ForeignKeyAction): this;
+    /**
+     * Set ON UPDATE action
+     */
+    onUpdate(action: ForeignKeyAction): this;
+    private finalize;
+    private updateForeignKey;
+}
+export {};

package/dist/atlas/src/schema/ColumnDefinition.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Column Definition
+ * @description Represents a column in a table schema with fluent modifiers
+ */
+import type { ForeignKeyDefinition } from './ForeignKeyDefinition';
+/**
+ * Column data type
+ */
+export type ColumnType = 'bigInteger' | 'binary' | 'boolean' | 'date' | 'dateTime' | 'dateTimeTz' | 'decimal' | 'enum' | 'float' | 'integer' | 'ipAddress' | 'json' | 'jsonb' | 'macAddress' | 'set' | 'smallInteger' | 'string' | 'text' | 'time' | 'timeTz' | 'timestamp' | 'timestampTz' | 'uuid' | 'vector';
+/**
+ * Foreign key action
+ */
+export type ForeignKeyAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+/**
+ * Column Definition
+ *
+ * The ColumnDefinition class represents a column in a database table.
+ * It provides a fluent interface for defining column properties such as
+ * nullability, default values, indexes, and foreign key constraints.
+ */
+export declare class ColumnDefinition {
+    /** Column name */
+    readonly name: string;
+    /** Column type */
+    readonly type: ColumnType;
+    /** Type-specific parameters */
+    readonly parameters: Record<string, unknown>;
+    /** Modifiers */
+    private _nullable;
+    private _default;
+    private _hasDefault;
+    private _unique;
+    private _index;
+    private _primary;
+    private _unsigned;
+    private _autoIncrement;
+    private _comment;
+    private _after;
+    private _first;
+    private _change;
+    /** Foreign key reference */
+    private _foreignKey;
+    constructor(name: string, type: ColumnType, parameters?: Record<string, unknown>);
+    /**
+     * Allow NULL values to be stored in the column.
+     *
+     * @param value Whether the column should be nullable (defaults to true).
+     * @returns The ColumnDefinition instance for chaining.
+     */
+    nullable(value?: boolean): this;
+    /**
+     * Set the default value for the column.
+     *
+     * @param value The default value.
+     * @returns The ColumnDefinition instance for chaining.
+     */
+    default(value: unknown): this;
+    /**
+     * Add a UNIQUE constraint to the column.
+     *
+     * @returns The ColumnDefinition instance for chaining.
+     */
+    unique(): this;
+    /**
+     * Add INDEX
+     */
+    index(): this;
+    /**
+     * Set the column as a PRIMARY KEY.
+     *
+     * @returns The ColumnDefinition instance for chaining.
+     */
+    primary(): this;
+    /**
+     * Make UNSIGNED (MySQL)
+     */
+    unsigned(): this;
+    /**
+     * Set AUTO_INCREMENT
+     */
+    autoIncrement(): this;
+    /**
+     * Add column comment
+     */
+    comment(text: string): this;
+    /**
+     * Place column after another column (MySQL)
+     */
+    after(column: string): this;
+    /**
+     * Place column first (MySQL)
+     */
+    first(): this;
+    /**
+     * Mark column for modification
+     */
+    change(): this;
+    /**
+     * Define a foreign key constraint for the column.
+     *
+     * @param table The name of the referenced table (inferred from column name if not provided).
+     * @returns The ColumnDefinition instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * table.foreignId('user_id').constrained('users')
+     * ```
+     */
+    constrained(table?: string): this;
+    /**
+     * Set the ON DELETE action for the foreign key constraint.
+     *
+     * @param action The action to perform (e.g., 'cascade', 'set null').
+     * @returns The ColumnDefinition instance for chaining.
+     */
+    onDelete(action: ForeignKeyAction): this;
+    /**
+     * Set ON UPDATE action
+     */
+    onUpdate(action: ForeignKeyAction): this;
+    /**
+     * Set the referenced column (for manual FK definition)
+     */
+    references(column: string): ForeignKeyBuilder;
+    isNullable(): boolean;
+    hasDefaultValue(): boolean;
+    getDefault(): unknown;
+    isUnique(): boolean;
+    hasIndex(): boolean;
+    isPrimary(): boolean;
+    isUnsigned(): boolean;
+    isAutoIncrement(): boolean;
+    getComment(): string | undefined;
+    getAfter(): string | undefined;
+    isFirst(): boolean;
+    isChange(): boolean;
+    getForeignKey(): ForeignKeyDefinition | undefined;
+    setForeignKey(fk: ForeignKeyDefinition): void;
+    private inferTableName;
+}
+/**
+ * Foreign Key Builder
+ * For manual foreign key definition: column.references('id').on('users')
+ */
+declare class ForeignKeyBuilder {
+    private readonly column;
+    private referencedColumn;
+    constructor(column: ColumnDefinition, referencedColumn: string);
+    /**
+     * Set the referenced table
+     */
+    on(table: string): ColumnDefinition;
+}
+export {};

package/dist/atlas/src/schema/ForeignKeyDefinition.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Foreign Key Definition
+ * @description Represents a foreign key constraint
+ */
+import type { ForeignKeyAction } from './ColumnDefinition';
+/**
+ * Foreign Key Definition
+ *
+ * Represents a foreign key constraint between two tables.
+ */
+export interface ForeignKeyDefinition {
+    /** Local column name */
+    column: string;
+    /** Referenced table name */
+    referencedTable: string;
+    /** Referenced column name */
+    referencedColumn: string;
+    /** ON DELETE action */
+    onDelete: ForeignKeyAction | undefined;
+    /** ON UPDATE action */
+    onUpdate: ForeignKeyAction | undefined;
+}
+/**
+ * Index Definition
+ *
+ * Represents a database index (Primary, Unique, Index, Fulltext, or Spatial).
+ */
+export interface IndexDefinition {
+    /** Index name */
+    name: string;
+    /** Index type */
+    type: 'index' | 'unique' | 'primary' | 'fulltext' | 'spatial';
+    /** Columns in the index */
+    columns: string[];
+    /** Language for fulltext index */
+    language?: string | undefined;
+}

package/dist/atlas/src/schema/Schema.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Schema Facade
+ * @description Entry point for database schema operations
+ */
+import { Blueprint } from './Blueprint';
+/**
+ * Schema Facade
+ *
+ * The Schema class provides a database agnostic way of manipulating tables.
+ * It works with all supported databases and provides a unified API for
+ * creating, modifying, and dropping tables.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from '@gravito/atlas'
+ *
+ * // Create a new table
+ * await Schema.create('users', (table) => {
+ *   table.id()
+ *   table.string('email').unique()
+ *   table.timestamps()
+ * })
+ *
+ * // Modify an existing table
+ * await Schema.table('users', (table) => {
+ *   table.string('phone').nullable()
+ * })
+ * ```
+ */
+export declare class Schema {
+    private static grammar;
+    private static connectionName;
+    /**
+     * Set the connection to use for schema operations.
+     *
+     * @param name The name of the connection defined in your database configuration.
+     * @returns The Schema class for chaining.
+     */
+    static connection(name: string): typeof Schema;
+    /**
+     * Reset the schema facade state (primarily for testing).
+     * @internal
+     */
+    static reset(): void;
+    /**
+     * Get the grammar instance for the current connection
+     */
+    private static getGrammar;
+    /**
+     * Check if grammar instance matches driver
+     */
+    private static isGrammarMatch;
+    private static getDriverName;
+    private static createGrammar;
+    /**
+     * Create a new table on the schema.
+     *
+     * @param table The name of the table to create.
+     * @param callback A callback that receives a Blueprint instance to define columns.
+     *
+     * @example
+     * ```typescript
+     * await Schema.create('posts', (table) => {
+     *   table.id()
+     *   table.foreignId('user_id').constrained().onDelete('cascade')
+     *   table.string('title')
+     *   table.text('content')
+     *   table.timestamps()
+     * })
+     * ```
+     */
+    static create(table: string, callback: (blueprint: Blueprint) => void): Promise<void>;
+    /**
+     * Modify an existing table on the schema.
+     *
+     * @param table The name of the table to modify.
+     * @param callback A callback that receives a Blueprint instance to modify columns or indexes.
+     *
+     * @example
+     * ```typescript
+     * await Schema.table('users', (table) => {
+     *   table.string('avatar_url').nullable()
+     *   table.index(['email', 'avatar_url'])
+     * })
+     * ```
+     */
+    static table(table: string, callback: (blueprint: Blueprint) => void): Promise<void>;
+    /**
+     * Drop a table from the schema.
+     *
+     * @param table - The name of the table to drop.
+     * @throws Error if the table does not exist.
+     */
+    static drop(table: string): Promise<void>;
+    /**
+     * Drop a table from the schema only if it exists.
+     *
+     * @param table - The name of the table to drop.
+     */
+    static dropIfExists(table: string): Promise<void>;
+    /**
+     * Rename an existing table on the schema.
+     *
+     * @param from - The current name of the table.
+     * @param to - The new name for the table.
+     */
+    static rename(from: string, to: string): Promise<void>;
+    /**
+     * Determine if the given table exists in the database.
+     *
+     * @param table - The name of the table to check.
+     * @returns Promise resolving to true if the table exists.
+     */
+    static hasTable(table: string): Promise<boolean>;
+    /**
+     * Determine if the given table has a specific column.
+     *
+     * @param table - The name of the table.
+     * @param column - The name of the column.
+     * @returns Promise resolving to true if the column exists.
+     */
+    static hasColumn(table: string, column: string): Promise<boolean>;
+    /**
+     * Get a list of all table names for the current database connection.
+     *
+     * @returns Promise resolving to an array of table names.
+     */
+    static getTables(): Promise<string[]>;
+    private static executeStatement;
+    private static executeQuery;
+}

package/dist/atlas/src/schema/grammars/MySQLSchemaGrammar.d.ts

@@ -0,0 +1,23 @@
+/**
+ * MySQL Schema Grammar
+ * @description DDL generation for MySQL/MariaDB
+ */
+import type { ColumnDefinition } from '../ColumnDefinition';
+import type { IndexDefinition } from '../ForeignKeyDefinition';
+import { SchemaGrammar } from './SchemaGrammar';
+/**
+ * MySQL Schema Grammar
+ */
+export declare class MySQLSchemaGrammar extends SchemaGrammar {
+    protected compileType(column: ColumnDefinition): string;
+    protected compileAutoIncrement(): string;
+    protected supportsUnsigned(): boolean;
+    protected compileFullTextIndex(table: string, index: IndexDefinition): string;
+    protected compileSpatialIndex(table: string, index: IndexDefinition): string;
+    compileDropIndex(table: string, name: string): string;
+    wrapTable(table: string): string;
+    wrapColumn(column: string): string;
+    compileTableExists(table: string): string;
+    compileColumnExists(table: string, column: string): string;
+    compileListTables(): string;
+}

package/dist/atlas/src/schema/grammars/PostgresSchemaGrammar.d.ts

@@ -0,0 +1,26 @@
+/**
+ * PostgreSQL Schema Grammar
+ * @description DDL generation for PostgreSQL
+ */
+import type { Blueprint } from '../Blueprint';
+import type { ColumnDefinition } from '../ColumnDefinition';
+import type { IndexDefinition } from '../ForeignKeyDefinition';
+import { SchemaGrammar } from './SchemaGrammar';
+/**
+ * PostgreSQL Schema Grammar
+ */
+export declare class PostgresSchemaGrammar extends SchemaGrammar {
+    protected wrapChar: string;
+    protected compileType(column: ColumnDefinition): string;
+    protected compileAutoIncrement(): string;
+    protected compileColumn(column: ColumnDefinition, blueprint: Blueprint): string;
+    protected supportsUnsigned(): boolean;
+    protected compileFullTextIndex(table: string, index: IndexDefinition): string;
+    protected compileSpatialIndex(table: string, index: IndexDefinition): string;
+    compileDropIndex(_table: string, name: string): string;
+    wrapTable(table: string): string;
+    wrapColumn(column: string): string;
+    compileTableExists(table: string): string;
+    compileColumnExists(table: string, column: string): string;
+    compileListTables(): string;
+}

package/dist/atlas/src/schema/grammars/SQLiteSchemaGrammar.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SQLite Schema Grammar
+ * @description DDL generation for SQLite
+ */
+import type { Blueprint } from '../Blueprint';
+import type { ColumnDefinition } from '../ColumnDefinition';
+import type { IndexDefinition } from '../ForeignKeyDefinition';
+import { SchemaGrammar } from './SchemaGrammar';
+/**
+ * SQLite Schema Grammar
+ * Generates SQL DDL statements specifically for SQLite databases.
+ * @internal
+ */
+export declare class SQLiteSchemaGrammar extends SchemaGrammar {
+    protected wrapChar: string;
+    compileCreate(blueprint: Blueprint): string;
+    wrapTable(table: string): string;
+    wrapColumn(column: string): string;
+    compileTableExists(table: string): string;
+    compileColumnExists(table: string, column: string): string;
+    compileListTables(): string;
+    protected compileType(column: ColumnDefinition): string;
+    protected compileAutoIncrement(): string;
+    protected supportsUnsigned(): boolean;
+    protected compileFullTextIndex(_table: string, _index: IndexDefinition): string;
+    protected compileSpatialIndex(_table: string, _index: IndexDefinition): string;
+    compileDropIndex(_table: string, name: string): string;
+}