mango-orm 1.0.0

package/dist/src/mango.d.ts

@@ -0,0 +1,276 @@
+import * as sql from "mysql";
+/**
+ * MangoType - Schema builder for defining table column types
+ * Provides chainable methods to build SQL column definitions
+ *
+ * @example
+ * const type = new MangoType();
+ * type.varchar(255).notNull().unique();
+ */
+declare class MangoType {
+    private query;
+    constructor();
+    /** Define an INT column */
+    int(): this;
+    /** Define a BIGINT column */
+    bigInt(): this;
+    /** Define a FLOAT column */
+    float(): this;
+    /**
+     * Define a CHAR column with fixed length
+     * @param length - The fixed character length
+     */
+    char(length: number): this;
+    /** Define a TEXT column for large text data */
+    text(): this;
+    /** Define a DATE column (YYYY-MM-DD) */
+    date(): this;
+    /** Define a DATETIME column (YYYY-MM-DD HH:MM:SS) */
+    dateTime(): this;
+    /** Define a TIMESTAMP column (auto-updated on changes) */
+    timeStamp(): this;
+    /** Define a BOOLEAN column (stored as TINYINT(1)) */
+    boolean(): this;
+    /**
+     * Define a TINYINT column
+     * @param length - Display width (e.g., TINYINT(1))
+     */
+    tinyInt(length: number): this;
+    /** Make column auto-incrementing (use with INT/BIGINT) */
+    autoIncrement(): this;
+    /** Mark column as primary key */
+    primaryKey(): this;
+    /**
+     * Define a VARCHAR column with variable length
+     * @param length - Maximum character length (e.g., 255)
+     */
+    varchar(length: number): this;
+    /** Make column NOT NULL (required field) */
+    notNull(): this;
+    /** Add UNIQUE constraint (no duplicate values) */
+    unique(): this;
+    /** Get the built SQL column definition */
+    getQuery(): string;
+}
+/**
+ * MangoQuery - Internal query executor
+ * Handles SQL query execution and prepared statements
+ * Automatically resets state after execution to prevent query contamination
+ */
+declare class MangoQuery {
+    private db;
+    query: string;
+    supplies: any;
+    /**
+     * Configure the database connection pool
+     * @param db - MySQL connection pool instance
+     */
+    config(db: sql.Pool): void;
+    /**
+     * Execute the built query with prepared statements
+     * Automatically resets query and supplies after execution
+     * @returns Promise resolving to query results
+     */
+    execute<T>(): Promise<T>;
+    /**
+     * Execute a custom SQL query with parameters
+     * Use for complex queries not covered by the query builder
+     * @param query - Raw SQL query string
+     * @param supplies - Array of parameter values
+     * @returns Promise resolving to query results
+     */
+    customQuery<T>(query: string, supplies: any[]): Promise<T>;
+}
+/**
+ * MangoTable<T> - Main query builder class for table operations
+ * Provides chainable methods for building SQL queries
+ * Generic type T represents the shape of table rows
+ *
+ * @example
+ * const users = new MangoTable(db, 'users', ['id', 'name', 'email']);
+ * const result = await users.selectAll().where('id', '=', 1).execute();
+ */
+declare class MangoTable<T> {
+    private db;
+    private tableName;
+    private tableFields;
+    private query;
+    /**
+     * Create a new table instance
+     * @param db - MySQL connection pool
+     * @param name - Table name (no spaces allowed)
+     * @param fields - Array of column names in the table
+     */
+    constructor(db: sql.Pool, name: string, fields?: string[]);
+    /**
+     * Add new columns to an existing table
+     * Updates internal field list for validation
+     * @param fields - Object mapping column names to MangoType definitions
+     * @returns this for method chaining
+     *
+     * @example
+     * table.addColumns({
+     *   age: mango.types().int().notNull(),
+     *   status: mango.types().varchar(50)
+     * }).execute();
+     */
+    addColumns(fields: Record<string, MangoType>): this;
+    /**
+     * Remove columns from the table
+     * Validates columns exist before removal
+     * @param fields - Array of column names to remove
+     * @returns this for method chaining
+     *
+     * @example
+     * table.removeColumns(['old_field', 'deprecated_col']).execute();
+     */
+    removeColumns(fields: string[]): this;
+    /**
+     * Select all columns from the table
+     * @returns this for method chaining
+     *
+     * @example
+     * await table.selectAll().where('active', '=', true).execute();
+     */
+    selectAll(): this;
+    /**
+     * Select specific columns from the table
+     * Validates all columns exist before building query
+     * @param columns - Array of column names to select
+     * @returns this for method chaining
+     *
+     * @example
+     * await table.selectColumns(['id', 'name', 'email']).execute();
+     */
+    selectColumns(columns: string[]): this;
+    selectDistinctColumns(columns: string[]): this;
+    orderBy(columnName: string): this;
+    sort(sort?: number): this;
+    limit(length: number): this;
+    offset(length: number): this;
+    insertOne(data: Record<string, any>): this;
+    insertMany(fields: string[], data?: any[][]): this;
+    getFields(): string[];
+    getName(): string;
+    truncate(): this;
+    /**
+     * Add WHERE clause to filter query results
+     * Use with comparison operators to filter rows
+     * Supports falsy values (0, false, empty string)
+     * @param field - Column name to filter on
+     * @param operator - SQL comparison operator (=, !=, <, >, LIKE, etc.)
+     * @param value - Value to compare against (any type)
+     * @returns this for method chaining
+     *
+     * @example
+     * table.selectAll().where('age', '>=', 18).execute();
+     * table.selectAll().where('active', '=', false).execute(); // Works with false!
+     * table.selectAll().where('count', '=', 0).execute(); // Works with 0!
+     */
+    where(field: string, operator: string, value: any): this;
+    /**
+     * Add AND condition to existing WHERE clause
+     * Chain multiple conditions together
+     * @param field - Column name
+     * @param operator - SQL comparison operator
+     * @param value - Value to compare (any type including 0, false)
+     * @returns this for method chaining
+     *
+     * @example
+     * table.selectAll()
+     *   .where('age', '>=', 18)
+     *   .and('active', '=', true)
+     *   .execute();
+     */
+    and(field: string, operator: string, value: any): this;
+    /**
+     * Add OR condition to existing WHERE clause
+     * Combine alternative conditions
+     * @param field - Column name
+     * @param operator - SQL comparison operator
+     * @param value - Value to compare (any type including 0, false)
+     * @returns this for method chaining
+     *
+     * @example
+     * table.selectAll()
+     *   .where('role', '=', 'admin')
+     *   .or('role', '=', 'moderator')
+     *   .execute();
+     */
+    or(field: string, operator: string, value: any): this;
+    update(data: Record<string, any>): this;
+    join(type: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL', table: string, condition: {
+        left: string;
+        operator: string;
+        right: string;
+    }): this;
+    delete(): this;
+    whereIn(field: string, values: any[]): this;
+    whereNotIn(field: string, values: any[]): this;
+    getQuery(): MangoQuery;
+    execute(): Promise<T[]>;
+    customQuery<Type>(query: string, supplies: any[]): Promise<Type[]>;
+}
+/**
+ * Mango - Main ORM class for MySQL database operations
+ * Manages connection pool and provides table instances
+ * Auto-discovers existing tables on connection
+ *
+ * @example
+ * const mango = new Mango();
+ * await mango.connect({
+ *   host: 'localhost',
+ *   user: 'root',
+ *   password: 'pass',
+ *   database: 'mydb'
+ * });
+ *
+ * const users = mango.selectTable('users');
+ * const results = await users.selectAll().execute();
+ */
+declare class Mango {
+    private db;
+    private tables;
+    private query;
+    connect({ host, user, password, database, connectionLimit, waitForConnection, queueLimit, connectTimeout, charset, }: {
+        host: any;
+        user: any;
+        password: any;
+        database: any;
+        connectionLimit?: number;
+        waitForConnection?: boolean;
+        queueLimit?: number;
+        connectTimeout?: number;
+        charset?: string;
+    }): Promise<this>;
+    disconnect(): Promise<void>;
+    /**
+     * Get a new MangoType instance for schema building
+     * Use when creating or modifying table columns
+     * @returns New MangoType instance for chaining
+     *
+     * @example
+     * const idField = mango.types().int().autoIncrement().primaryKey();
+     */
+    types(): MangoType;
+    /**
+     * Get a table instance by name
+     * Returns strongly-typed table if generic provided
+     * @param name - Name of the table
+     * @returns MangoTable instance for building queries
+     *
+     * @example
+     * interface User { id: number; name: string; email: string }
+     * const users = mango.selectTable<User>('users');
+     */
+    selectTable<T = any>(name: string): MangoTable<T>;
+    /**
+     * Get all discovered table instances
+     * @returns Array of all MangoTable instances
+     */
+    getTables(): MangoTable<any>[];
+    createTable<T>(name: string, fields: Record<string, MangoType>): Promise<MangoTable<T>>;
+    dropTable(name: string): Promise<void>;
+    customQuery<Type>(query: string, supplies: any[]): Promise<Type>;
+}
+export { Mango, MangoType, MangoTable };