@devbro/neko-sql 0.1.37 → 0.1.39

package/dist/cjs/index.d.ts

@@ -0,0 +1,615 @@
+import { EventEmittor } from '@devbro/neko-helper';
+import pg, { PoolClient, PoolConfig } from 'pg';
+import pg_cursor from 'pg-cursor';
+import Database from 'better-sqlite3';
+import mysql from 'mysql2/promise';
+
+declare class Expression {
+    private sql;
+    private bindings;
+    constructor(sql?: string, bindings?: never[]);
+    toCompiledSql(): CompiledSql;
+}
+
+declare abstract class QueryGrammar {
+    sqlParts: string[];
+    toSql(query: Query): CompiledSql;
+    toSqlParts(query: Query): CompiledSql;
+    compileCount(query: Query): CompiledSql;
+    compileSelect(selects: selectType[]): CompiledSql;
+    joinArray(arr: (string | number)[]): string;
+    compileTable(tableName: string): CompiledSql;
+    compileJoin(joins: joinType[]): CompiledSql;
+    compileWhere(wheres: whereType[]): CompiledSql;
+    compileWhereNested(w: whereNested): CompiledSql;
+    compileWhereOperation(w: whereOp): CompiledSql;
+    compileWhereOperationColumn(w: whereOpColumn): CompiledSql;
+    compileWhereRaw(w: whereRaw): CompiledSql;
+    compileOrderBy(orderBy: string[]): CompiledSql;
+    compileLimit(limit: number | null): CompiledSql;
+    compileOffset(offset: number | null): CompiledSql;
+    compileWhereNull(w: whereNull): CompiledSql;
+    compileInsert(query: Query, data: Record<string, Parameter> | Record<string, Parameter>[]): CompiledSql;
+    abstract compileInsertGetId(query: Query, data: Record<string, Parameter> | Record<string, Parameter>[], options: {
+        primaryKey: string[];
+    }): CompiledSql;
+    compileUpdate(query: Query, data: Record<string, Parameter>): CompiledSql;
+    compileDelete(query: Query): CompiledSql;
+    compileUpsert(query: Query, data: Record<string, Parameter>, conflictFields: string[], updateFields: string[]): CompiledSql;
+    compileGroupBy(groupBy: string[]): CompiledSql;
+    compileHaving(having: havingType[]): CompiledSql;
+    compileHavingOperation(w: whereOp): CompiledSql;
+    compileHavingRaw(w: whereRaw): CompiledSql;
+    /**
+     * post process result from database
+     * @param result result from database
+     * @returns post processed result
+     */
+    postProcessGetInsertId(result: any): any;
+}
+
+type QueryParts = {
+    select: selectType[];
+    table: string;
+    join: joinType[];
+    where: whereType[];
+    groupBy: string[];
+    having: havingType[];
+    orderBy: string[];
+    limit: number | null;
+    offset: number | null;
+    alias: string | null;
+};
+declare class Query {
+    readonly connection: Connection | null;
+    readonly grammar: QueryGrammar;
+    allowedOperations: string[];
+    parts: QueryParts;
+    constructor(connection: Connection | null, grammar: QueryGrammar);
+    table(tableName: string): this;
+    whereNested(func: (q: Query) => void, joinCondition?: JoinCondition, negateCondition?: boolean): this;
+    whereOp(column: string, operation: (typeof this.allowedOperations)[number], value: Parameter, joinCondition?: JoinCondition, negateCondition?: boolean): this;
+    whereRaw(sql: string, bindings: Parameter[], joinCondition?: JoinCondition, negateCondition?: boolean): this;
+    whereColumn(column1: string, operation: (typeof this.allowedOperations)[number], column2: string, joinCondition?: JoinCondition, negateCondition?: boolean): this;
+    whereNull(column: string, joinCondition?: JoinCondition, negateCondition?: boolean): this;
+    clearWhere(): this;
+    select(selects: selectType[]): this;
+    groupBy(columns: string[]): this;
+    havingOp(column: string, operation: (typeof this.allowedOperations)[number], value: Parameter, joinCondition?: JoinCondition, negateCondition?: boolean): this;
+    havingRaw(sql: string, bindings: Parameter[], joinCondition?: JoinCondition, negateCondition?: boolean): this;
+    orderBy(column: string, direction?: 'asc' | 'desc'): this;
+    limit(limit: number): this;
+    offset(offset: number): this;
+    toSql(): CompiledSql;
+    get(): Promise<any>;
+    first(): Promise<any>;
+    count(): Promise<number>;
+    getCursor(): Promise<any>;
+    getConnection(): Connection | null;
+    insert(data: Record<string, Parameter> | Record<string, Parameter>[]): Promise<any>;
+    insertGetId(data: Record<string, Parameter> | Record<string, Parameter>[], options?: {
+        primaryKey: string[];
+    }): Promise<any>;
+    update(data: Record<string, Parameter>): Promise<any>;
+    upsert(data: Record<string, Parameter>, uniqueColumns: string[], updateColumns: string[]): Promise<any>;
+    delete(): Promise<any>;
+    join(table: string | Query, type: joinType['type'], conditions: (whereType | {
+        column1: string;
+        column2: string;
+    })[]): this;
+    innerJoin(table: Parameters<typeof this.join>[0], conditions: (whereType | {
+        column1: string;
+        column2: string;
+    })[]): this;
+    leftJoin(table: Parameters<typeof this.join>[0], conditions: (whereType | {
+        column1: string;
+        column2: string;
+    })[]): this;
+    rightJoin(table: Parameters<typeof this.join>[0], conditions: (whereType | {
+        column1: string;
+        column2: string;
+    })[]): this;
+    fullJoin(table: Parameters<typeof this.join>[0], conditions: (whereType | {
+        column1: string;
+        column2: string;
+    })[]): this;
+    crossJoin(table: Parameters<typeof this.join>[0], conditions: (whereType | {
+        column1: string;
+        column2: string;
+    })[]): this;
+    alias(alias: string): this;
+}
+
+type selectType = string;
+type whereBasic = {
+    joinCondition: JoinCondition;
+    negateCondition: boolean;
+};
+type whereOp = {
+    type: 'operation';
+    column: string;
+    operation: string;
+    value: Parameter;
+};
+type whereOpColumn = {
+    type: 'operationColumn';
+    column1: string;
+    operation: string;
+    column2: string;
+};
+type whereNested = {
+    type: 'nested';
+    query: Query;
+};
+type whereRaw = {
+    type: 'raw';
+    sql: string;
+    bindings: Parameter[];
+};
+type whereNull = {
+    type: 'null';
+    column: string;
+};
+type whereType = whereBasic & (whereOp | whereOpColumn | whereNested | whereNull | whereRaw);
+type Parameter = string | number | Date | boolean | null | Expression | undefined | number[] | string[];
+type JoinCondition = 'and' | 'or';
+type CompiledSql = {
+    sql: string;
+    parts: (string | number)[];
+    bindings: Parameter[];
+};
+type havingType = whereBasic & (whereOp | whereRaw);
+type joinType = {
+    type: 'inner' | 'left' | 'right' | 'full' | 'cross';
+    table: string | Query;
+    conditions: whereType[];
+};
+
+type ColumnPropertiesType = {
+    type: 'string' | 'integer' | 'float' | 'double' | 'boolean' | 'char' | 'text' | 'date' | 'timestamp' | 'timestampz' | 'serial' | 'json' | 'jsonb' | 'raw';
+    length: number;
+    nullable: boolean;
+    unique: boolean;
+    default: Parameter;
+};
+declare class Column {
+    columnName: string;
+    properties: ColumnPropertiesType;
+    constructor(columnName: string, type: ColumnPropertiesType['type']);
+    length(length: number): this;
+    nullable(nullable?: boolean): this;
+    unique(unique?: boolean): this;
+    default(value: ColumnPropertiesType['default']): this;
+}
+declare class IndexConstraint {
+    columns: string[];
+    indexName: string | undefined;
+    unique: boolean;
+    _type: 'gin' | 'btree' | 'hash' | 'gist' | 'spgist' | 'brin' | undefined;
+    constructor(columns: string | string[]);
+    name(indexName: string): this;
+    setUnique(unique?: boolean): this;
+    type(type: typeof this._type): this;
+}
+declare class ForeignKeyConstraint {
+    column: string;
+    reference_table: {
+        table: string;
+        column: string;
+    };
+    onUpdateAction: 'cascade' | 'set null' | 'restrict' | 'no action';
+    onDeleteAction: 'cascade' | 'set null' | 'restrict' | 'no action';
+    constructor(column: string);
+    on(table: string): this;
+    references(column: string): this;
+    onDelete(action: typeof this.onDeleteAction): this;
+    onUpdate(action: typeof this.onUpdateAction): this;
+}
+declare class Blueprint {
+    tableName: string;
+    columns: Column[];
+    drop_coumns: string[];
+    foreignKeys: ForeignKeyConstraint[];
+    indexes: IndexConstraint[];
+    existingTable: boolean;
+    primaryKeys: string[];
+    constructor();
+    setTableName(tableName: string, existingTable?: boolean): void;
+    boolean(columnName: string): Column;
+    char(columnName: string): Column;
+    string(columnName: string, length?: number): Column;
+    raw(sql: string): Column;
+    text(columnName: string): Column;
+    json(columnName: string): Column;
+    jsonb(columnName: string): Column;
+    integer(columnName: string): Column;
+    float(columnName: string): Column;
+    double(columnName: string): Column;
+    id(): Column;
+    timestamps(): void;
+    date(columnName: string): Column;
+    timestamp(columnName: string): Column;
+    timestampTz(columnName: string): Column;
+    datetime(columnName: string): Column;
+    datetimeTz(columnName: string): Column;
+    primary(keys: string[]): void;
+    foreign(columnName: string): ForeignKeyConstraint;
+    dropColumn(columnName: string): void;
+    index(columns: string | string[], indexName?: string): IndexConstraint;
+    unique(columns: string | string[], indexName?: string): IndexConstraint;
+}
+
+declare class SchemaGrammar {
+    toSql(blueprint: Blueprint): string;
+    compileCreateTable(blueprint: Blueprint): CompiledSql;
+    compileAlterTable(blueprint: Blueprint): CompiledSql;
+    compileColumn(column: Column): string;
+    escape(value: Parameter): string;
+    compilePrimaryKeys(primaryKeys: string[]): string;
+    compileTables(schema?: string | string[] | undefined): CompiledSql;
+    compileTableExists(tableName: string, schema?: string): CompiledSql;
+    compileDropTable(tableName: string): CompiledSql;
+    compileDropTableIfExists(tableName: string): CompiledSql;
+    protected compileSchemaWhereClause(schema: string | string[] | undefined, column: string): string;
+    protected quoteString(value: string | string[]): string;
+    protected doubleQuoteString(value: string | string[]): string;
+    protected compileForeignKey(foreignKey: ForeignKeyConstraint): string;
+    protected compileIndex(tableName: string, index: IndexConstraint): CompiledSql;
+}
+
+/**
+ * Schema builder for creating and managing database tables.
+ * Provides methods for table creation, alteration, and inspection.
+ */
+declare class Schema {
+    private readonly connection;
+    private readonly grammar;
+    /**
+     * Creates a new Schema instance.
+     *
+     * @param connection - The database connection to use for schema operations
+     * @param grammar - The schema grammar for generating SQL statements
+     */
+    constructor(connection: Connection | null, grammar: SchemaGrammar);
+    /**
+     * Creates a new table in the database.
+     *
+     * @param tableName - The name of the table to create
+     * @param structMethod - A callback function that receives a Blueprint to define table structure
+     *
+     * @example
+     * await schema.createTable('users', (table) => {
+     *   table.increments('id');
+     *   table.string('name');
+     *   table.string('email').unique();
+     *   table.timestamps();
+     * });
+     */
+    createTable(tableName: string, structMethod: (blueprint: Blueprint) => void): Promise<void>;
+    /**
+     * Modifies an existing table structure.
+     *
+     * @param tableName - The name of the table to alter
+     * @param structMethod - A callback function that receives a Blueprint to define modifications
+     *
+     * @example
+     * await schema.alterTable('users', (table) => {
+     *   table.string('phone').nullable();
+     *   table.dropColumn('old_field');
+     * });
+     */
+    alterTable(tableName: string, structMethod: (blueprint: Blueprint) => void): Promise<void>;
+    /**
+     * Drops (deletes) a table from the database.
+     *
+     * @param tableName - The name of the table to drop
+     *
+     * @example
+     * await schema.dropTable('old_users');
+     */
+    dropTable(tableName: string): Promise<void>;
+    /**
+     * Drops a table from the database if it exists.
+     * Safe to call even if the table doesn't exist.
+     *
+     * @param tableName - The name of the table to drop
+     *
+     * @example
+     * await schema.dropTableIfExists('temp_table');
+     */
+    dropTableIfExists(tableName: string): Promise<void>;
+    /**
+     * Retrieves a list of all tables in the database.
+     *
+     * @returns A promise that resolves to an array of table information
+     *
+     * @example
+     * const allTables = await schema.tables();
+     * console.log(allTables);
+     */
+    tables(): Promise<any>;
+    /**
+     * Checks if a table exists in the database.
+     *
+     * @param table_name - The name of the table to check
+     * @returns A promise that resolves to true if the table exists, false otherwise
+     *
+     * @example
+     * if (await schema.tableExists('users')) {
+     *   console.log('Users table exists');
+     * }
+     */
+    tableExists(table_name: string): Promise<boolean>;
+}
+
+type connection_events = 'connect' | 'disconnect' | 'query' | 'error';
+declare abstract class Connection implements EventEmittor<connection_events[]> {
+    abstract on(event: connection_events, listener: (...args: any[]) => void): this;
+    abstract off(event: connection_events, listener: (...args: any[]) => void): this;
+    abstract emit(event: connection_events, ...args: any[]): Promise<boolean>;
+    abstract isConnected(): boolean;
+    abstract connect(): Promise<boolean>;
+    abstract runQuery(sql: CompiledSql | string): Promise<any>;
+    abstract runCursor(sql: CompiledSql): Promise<any>;
+    abstract disconnect(): Promise<boolean>;
+    abstract getQuery(): Query;
+    abstract getSchema(): Schema;
+    abstract beginTransaction(): Promise<void>;
+    abstract commit(): Promise<void>;
+    abstract rollback(): Promise<void>;
+    abstract getQueryGrammar(): QueryGrammar;
+    abstract getSchemaGrammar(): SchemaGrammar;
+    abstract createDatabase(name: string): Promise<void>;
+    abstract dropDatabase(name: string): Promise<void>;
+    abstract listDatabases(): Promise<string[]>;
+    abstract existsDatabase(name: string): Promise<boolean>;
+}
+
+declare class PostgresqlQueryGrammar extends QueryGrammar {
+    constructor();
+    toSql(query: Query): CompiledSql;
+    compileInsert(query: Query, data: Record<string, any> | Record<string, any>[]): CompiledSql;
+    compileInsertGetId(query: Query, data: Record<string, any> | Record<string, any>[], options?: {
+        primaryKey: string[];
+    }): CompiledSql;
+    compileUpdate(query: Query, data: Record<string, any>): CompiledSql;
+    compileDelete(query: Query): CompiledSql;
+    compileUpsert(query: Query, data: Record<string, Parameter>, conflictFields: string[], updateFields: string[]): CompiledSql;
+    compileCount(query: Query): CompiledSql;
+}
+
+declare class PostgresqlSchemaGrammar extends SchemaGrammar {
+}
+
+declare class PostgresqlConnection extends Connection {
+    private eventManager;
+    on(event: connection_events, listener: (...args: any[]) => void): this;
+    off(event: connection_events, listener: (...args: any[]) => void): this;
+    emit(event: connection_events, ...args: any[]): Promise<boolean>;
+    static pg: typeof pg;
+    static pg_cursor: typeof pg_cursor;
+    connection: PoolClient | undefined;
+    static pool: pg.Pool;
+    static defaults: PoolConfig;
+    constructor(params: PoolConfig);
+    connect(): Promise<boolean>;
+    runQuery(sql: CompiledSql | string): Promise<any>;
+    runCursor(sql: CompiledSql): Promise<any>;
+    disconnect(): Promise<boolean>;
+    getQuery(): Query;
+    getSchema(): Schema;
+    getQueryGrammar(): PostgresqlQueryGrammar;
+    getSchemaGrammar(): PostgresqlSchemaGrammar;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    static destroy(): Promise<void>;
+    isConnected(): boolean;
+    /**
+     * Validates and escapes a PostgreSQL identifier (database name, table name, etc.)
+     * Uses a whitelist approach to ensure only safe characters are allowed
+     */
+    private validateAndEscapeIdentifier;
+    createDatabase(name: string): Promise<void>;
+    dropDatabase(name: string): Promise<void>;
+    listDatabases(): Promise<string[]>;
+    existsDatabase(name: string): Promise<boolean>;
+}
+
+declare class SqliteQueryGrammar extends QueryGrammar {
+    constructor();
+    toSql(query: Query): CompiledSql;
+    compileInsert(query: Query, data: Record<string, any> | Record<string, any>[]): CompiledSql;
+    compileInsertGetId(query: Query, data: Record<string, any> | Record<string, any>[], options?: {
+        primaryKey: string[];
+    }): CompiledSql;
+    compileUpdate(query: Query, data: Record<string, any>): CompiledSql;
+    compileDelete(query: Query): CompiledSql;
+    compileUpsert(query: Query, data: Record<string, Parameter>, conflictFields: string[], updateFields: string[]): CompiledSql;
+    compileCount(query: Query): CompiledSql;
+}
+
+declare class SqliteSchemaGrammar extends SchemaGrammar {
+    compileColumn(column: Column): string;
+}
+
+/**
+ * Configuration options for SQLite database connection
+ */
+interface SqliteConfig {
+    /** Path to the SQLite database file */
+    filename: string;
+    /** Open the database in read-only mode (default: false) */
+    readonly?: boolean;
+    /** Throw an error if the database file doesn't exist (default: false) */
+    fileMustExist?: boolean;
+    /** Timeout in milliseconds for database operations (default: 5000) */
+    timeout?: number;
+    /** Optional verbose logging function for debugging SQL statements */
+    verbose?: (message?: unknown, ...additionalArgs: unknown[]) => void;
+}
+/**
+ * SQLite database connection implementation
+ *
+ * Provides a connection to SQLite databases using better-sqlite3.
+ * Supports transactions, queries, schema operations, and database management.
+ */
+declare class SqliteConnection extends Connection {
+    private eventManager;
+    on(event: connection_events, listener: (...args: any[]) => void): this;
+    off(event: connection_events, listener: (...args: any[]) => void): this;
+    emit(event: connection_events, ...args: any[]): Promise<boolean>;
+    connection: Database.Database | undefined;
+    private config;
+    /** Default configuration values for SQLite connections */
+    static defaults: Partial<SqliteConfig>;
+    constructor(params: SqliteConfig);
+    static sqlite: typeof Database;
+    /**
+     * Establishes a connection to the SQLite database
+     * Creates or opens the database file specified in the configuration
+     */
+    connect(): Promise<boolean>;
+    /**
+     * Executes a SQL query against the database
+     * Automatically detects SELECT queries and queries with RETURNING clauses
+     *
+     * @param sql - Compiled SQL or raw SQL string to execute
+     * @returns Query results (rows for SELECT, run info for INSERT/UPDATE/DELETE)
+     */
+    runQuery(sql: CompiledSql | string): Promise<any>;
+    /**
+     * Executes a query and returns an iterator for streaming results
+     * Useful for large result sets to avoid loading all rows into memory
+     *
+     * @param sql - Compiled SQL to execute
+     * @returns Iterator over query results
+     */
+    runCursor(sql: CompiledSql): Promise<any>;
+    /**
+     * Closes the database connection
+     */
+    disconnect(): Promise<boolean>;
+    /**
+     * Creates a new query builder instance for this connection
+     */
+    getQuery(): Query;
+    /**
+     * Creates a new schema builder instance for this connection
+     */
+    getSchema(): Schema;
+    /**
+     * Gets the query grammar for building SQL statements
+     */
+    getQueryGrammar(): SqliteQueryGrammar;
+    /**
+     * Gets the schema grammar for building DDL statements
+     */
+    getSchemaGrammar(): SqliteSchemaGrammar;
+    /**
+     * Starts a new database transaction
+     */
+    beginTransaction(): Promise<void>;
+    /**
+     * Commits the current transaction
+     */
+    commit(): Promise<void>;
+    /**
+     * Rolls back the current transaction
+     */
+    rollback(): Promise<void>;
+    /**
+     * Checks if the database connection is active
+     */
+    isConnected(): boolean;
+    /**
+     * Validates and escapes a SQLite identifier (database name, table name, etc.)
+     * Uses a whitelist approach to ensure only safe characters are allowed
+     *
+     * @param name - The identifier to validate and escape
+     * @returns The escaped identifier, quoted if it's a reserved keyword
+     * @throws Error if the identifier contains invalid characters
+     */
+    private validateAndEscapeIdentifier;
+    /**
+     * Creates a new SQLite database file
+     *
+     * @param name - Name or path of the database file to create
+     */
+    createDatabase(name: string): Promise<void>;
+    /**
+     * Deletes a SQLite database file
+     *
+     * @param name - Name or path of the database file to delete
+     */
+    dropDatabase(name: string): Promise<void>;
+    /**
+     * Lists available databases
+     * For SQLite, this returns the current database filename
+     *
+     * @returns Array containing the current database filename
+     */
+    listDatabases(): Promise<string[]>;
+    /**
+     * Checks if a database file exists
+     *
+     * @param name - Name or path of the database file to check
+     * @returns True if the database file exists, false otherwise
+     */
+    existsDatabase(name: string): Promise<boolean>;
+}
+
+declare class MysqlQueryGrammar extends QueryGrammar {
+    compileInsertGetId(query: Query, data: Record<string, any> | Record<string, any>[], options?: {
+        primaryKey: string[];
+    }): CompiledSql;
+    postProcessGetInsertId(result: any): {
+        id: any;
+    }[];
+}
+
+declare class MysqlSchemaGrammar extends SchemaGrammar {
+    compileColumn(column: Column): string;
+}
+
+declare class MysqlConnection extends Connection {
+    private eventManager;
+    on(event: connection_events, listener: (...args: any[]) => void): this;
+    off(event: connection_events, listener: (...args: any[]) => void): this;
+    emit(event: connection_events, ...args: any[]): Promise<boolean>;
+    connection: mysql.PoolConnection | undefined;
+    static pool: mysql.Pool;
+    static poolConfig: mysql.PoolOptions;
+    static mysql: typeof mysql;
+    static defaults: mysql.PoolOptions;
+    constructor(params: mysql.PoolOptions);
+    connect(): Promise<boolean>;
+    runQuery(sql: CompiledSql | string): Promise<any>;
+    runCursor(sql: CompiledSql): Promise<any>;
+    disconnect(): Promise<boolean>;
+    getQuery(): Query;
+    getSchema(): Schema;
+    getQueryGrammar(): MysqlQueryGrammar;
+    getSchemaGrammar(): MysqlSchemaGrammar;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    static destroy(): Promise<void>;
+    isConnected(): boolean;
+    /**
+     * Validates and escapes a MySQL identifier (database name, table name, etc.)
+     * Uses a whitelist approach to ensure only safe characters are allowed
+     */
+    private validateAndEscapeIdentifier;
+    createDatabase(name: string): Promise<void>;
+    dropDatabase(name: string): Promise<void>;
+    listDatabases(): Promise<string[]>;
+    existsDatabase(name: string): Promise<boolean>;
+}
+
+declare abstract class Migration {
+    abstract up(schema: Schema): Promise<void>;
+    abstract down(schema: Schema): Promise<void>;
+}
+
+export { Blueprint, Column, type ColumnPropertiesType, type CompiledSql, Connection, ForeignKeyConstraint, IndexConstraint, type JoinCondition, Migration, MysqlConnection, MysqlQueryGrammar, MysqlSchemaGrammar, type Parameter, PostgresqlConnection, PostgresqlQueryGrammar, PostgresqlSchemaGrammar, Query, QueryGrammar, type QueryParts, Schema, SchemaGrammar, type SqliteConfig, SqliteConnection, SqliteQueryGrammar, SqliteSchemaGrammar, type connection_events, type havingType, type joinType, type selectType, type whereBasic, type whereNested, type whereNull, type whereOp, type whereOpColumn, type whereRaw, type whereType };