@gravito/echo 3.0.0 → 3.1.0

package/dist/atlas/src/query/clauses/JoinClause.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Join Clause
+ *
+ * Handles JOIN operations
+ */
+import type { JoinClause, JoinType } from '../../types';
+/**
+ * Join Manager
+ * @description Handles the construction of JOIN clauses for SQL queries
+ */
+export declare class JoinManager {
+    /** Internal storage for join conditions */
+    private joins;
+    /**
+     * Add a JOIN condition to the query
+     *
+     * @param type - Join type (INNER, LEFT, RIGHT, FULL, CROSS)
+     * @param table - Table to join
+     * @param first - First column for the ON condition
+     * @param operator - Join operator (=, !=, >, <, etc.)
+     * @param second - Second column for the ON condition
+     * @example
+     * ```typescript
+     * manager.add('inner', 'posts', 'users.id', '=', 'posts.user_id')
+     * ```
+     */
+    add(type: JoinType, table: string, first: string, operator: string, second: string): void;
+    /**
+     * Add a LEFT JOIN condition
+     *
+     * @param table - Table to join
+     * @param first - First column for the ON condition
+     * @param operator - Join operator
+     * @param second - Second column for the ON condition
+     * @example
+     * ```typescript
+     * manager.left('posts', 'users.id', '=', 'posts.user_id')
+     * ```
+     */
+    left(table: string, first: string, operator: string, second: string): void;
+    /**
+     * Add a RIGHT JOIN condition
+     *
+     * @param table - Table to join
+     * @param first - First column for the ON condition
+     * @param operator - Join operator
+     * @param second - Second column for the ON condition
+     */
+    right(table: string, first: string, operator: string, second: string): void;
+    /**
+     * Add a CROSS JOIN condition
+     *
+     * @param table - Table to join
+     * @param first - First column for the ON condition
+     * @param operator - Join operator
+     * @param second - Second column for the ON condition
+     */
+    cross(table: string, first: string, operator: string, second: string): void;
+    /**
+     * Get all joins
+     *
+     * @returns Array of joins
+     */
+    getJoins(): JoinClause[];
+    /**
+     * Compile the JOIN clause to SQL
+     *
+     * @returns JOIN clause SQL string
+     */
+    toSQL(): string;
+    /**
+     * Reset the clause state
+     */
+    reset(): void;
+    /**
+     * Check if the clause has any joins
+     *
+     * @returns True if joins exist
+     */
+    hasJoins(): boolean;
+    /**
+     * Clone the clause
+     *
+     * @returns A deep copy of the clause
+     */
+    clone(): JoinManager;
+}

package/dist/atlas/src/query/clauses/LimitClause.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Limit Clause
+ * @description Handles the construction of LIMIT and OFFSET clauses for SQL queries
+ */
+export declare class LimitClause {
+    /** The maximum number of records to return */
+    private limitValue?;
+    /** The number of records to skip before starting to return results */
+    private offsetValue?;
+    /**
+     * Set the LIMIT value
+     *
+     * @param value - Maximum number of records
+     * @example
+     * ```typescript
+     * clause.setLimit(10)
+     * ```
+     */
+    setLimit(value: number): void;
+    /**
+     * Set the OFFSET value
+     *
+     * @param value - Number of records to skip
+     * @example
+     * ```typescript
+     * clause.setOffset(20)
+     * ```
+     */
+    setOffset(value: number): void;
+    /**
+     * Get the current LIMIT value
+     *
+     * @returns The limit value or undefined if not set
+     */
+    getLimit(): number | undefined;
+    /**
+     * Get the current OFFSET value
+     *
+     * @returns The offset value or undefined if not set
+     */
+    getOffset(): number | undefined;
+    /**
+     * Compile the LIMIT/OFFSET clause to SQL
+     *
+     * @returns SQL string for the clause
+     */
+    toSQL(): string;
+    /**
+     * Reset the clause state
+     */
+    reset(): void;
+    /**
+     * Check if the clause has a LIMIT value set
+     *
+     * @returns True if limit is set
+     */
+    hasLimit(): boolean;
+    /**
+     * Check if the clause has an OFFSET value set
+     *
+     * @returns True if offset is set
+     */
+    hasOffset(): boolean;
+    /**
+     * Set the number of records to take (alias for limit)
+     *
+     * @param value - Number of records
+     */
+    take(value: number): void;
+    /**
+     * Set the number of records to skip (alias for offset)
+     *
+     * @param value - Number of records
+     */
+    skip(value: number): void;
+    /**
+     * Clone the clause
+     *
+     * @returns A deep copy of the clause
+     */
+    clone(): LimitClause;
+}

package/dist/atlas/src/query/clauses/OrderByClause.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Order By Clause
+ *
+ * Handles ORDER BY operations
+ */
+import type { OrderClause as OrderClauseType, OrderDirection } from '../../types';
+import { Expression } from '../Expression';
+/**
+ * Order By Clause
+ * @description Handles the construction of ORDER BY clauses for SQL queries
+ */
+export declare class OrderByClause {
+    /** Internal storage for order by clauses */
+    private orders;
+    /** Bindings for raw order clauses */
+    private bindings;
+    /**
+     * Add an ORDER BY clause to the query
+     *
+     * @param column - Column name
+     * @param direction - Sort direction ('asc' or 'desc')
+     * @example
+     * ```typescript
+     * clause.orderBy('created_at', 'desc')
+     * ```
+     */
+    orderBy(column: string, direction?: OrderDirection): void;
+    /**
+     * Add a raw ORDER BY clause to the query
+     *
+     * @param sql - Raw SQL string or Expression instance
+     * @param bindings - Optional array of bindings
+     */
+    orderByRaw(sql: string | Expression, bindings?: unknown[]): void;
+    /**
+     * Get all order clauses
+     *
+     * @returns Array of order clauses
+     */
+    getOrders(): OrderClauseType[];
+    /**
+     * Get the bindings associated with this clause
+     *
+     * @returns Array of bindings
+     */
+    getBindings(): unknown[];
+    /**
+     * Compile the ORDER BY clause to SQL
+     *
+     * @returns ORDER BY clause SQL string
+     */
+    toSQL(): string;
+    /**
+     * Reset the clause state
+     */
+    reset(): void;
+    /**
+     * Check if the clause has any order conditions
+     *
+     * @returns True if order conditions exist
+     */
+    hasOrders(): boolean;
+    /**
+     * Clone the clause
+     *
+     * @returns A deep copy of the clause
+     */
+    clone(): OrderByClause;
+}

package/dist/atlas/src/query/clauses/SelectClause.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Select Clause
+ * @description Handles the construction of SELECT and DISTINCT clauses for SQL queries
+ */
+export declare class SelectClause {
+    /** Array of columns to select, defaults to all columns ('*') */
+    private columns;
+    /** Whether to apply the DISTINCT keyword to the query */
+    private distinct;
+    /** Bindings for raw expressions */
+    private bindings;
+    /**
+     * Set the columns to be selected
+     *
+     * @param columns - List of column names
+     * @example
+     * ```typescript
+     * clause.setColumns('id', 'name', 'email')
+     * ```
+     */
+    setColumns(...columns: string[]): void;
+    /**
+     * Add a raw SQL expression to the SELECT clause
+     *
+     * @param expression - Raw SQL string
+     * @param bindings - Bindings for the expression
+     * @example
+     * ```typescript
+     * clause.addRaw('COUNT(*) as total')
+     * ```
+     */
+    addRaw(expression: string, bindings?: unknown[]): void;
+    /**
+     * Enable the DISTINCT keyword for the query
+     */
+    setDistinct(): void;
+    /**
+     * Get the list of selected columns
+     *
+     * @returns Array of column names or expressions
+     */
+    getColumns(): string[];
+    /**
+     * Check if the DISTINCT keyword is enabled
+     *
+     * @returns True if distinct is set
+     */
+    isDistinct(): boolean;
+    /**
+     * Compile the SELECT clause to SQL
+     *
+     * @returns SQL string for the clause
+     */
+    toSQL(): string;
+    /**
+     * Reset the clause state to its default values
+     */
+    reset(): void;
+    /**
+     * Get the bindings associated with this clause
+     *
+     * @returns Array of bindings
+     */
+    getBindings(): unknown[];
+    /**
+     * Clone the clause
+     *
+     * @returns A deep copy of the clause
+     */
+    clone(): SelectClause;
+}

package/dist/atlas/src/query/clauses/WhereClause.d.ts

@@ -0,0 +1,167 @@
+import type { Operator } from '../../types';
+/**
+ * Where Condition Interface
+ * @description Represents a single WHERE condition or a group of nested conditions
+ */
+export interface WhereCondition {
+    /** Type of the condition */
+    type: 'basic' | 'nested' | 'in' | 'null' | 'between' | 'raw' | 'exists' | 'column';
+    /** Column name for the condition */
+    column?: string;
+    /** Comparison operator (e.g., '=', '!=', 'LIKE') */
+    operator?: Operator;
+    /** Value to compare against (for basic conditions) */
+    value?: unknown;
+    /** Logical connector to the previous condition ('and' or 'or') */
+    boolean: 'and' | 'or';
+    /** Array of nested conditions (for 'nested' type) */
+    conditions?: WhereCondition[];
+    /** Array of values (for 'in' type) */
+    values?: unknown[];
+    /** Whether to negate the condition (e.g., NOT IN, IS NOT NULL) */
+    not?: boolean;
+    /** Raw SQL for raw clauses */
+    sql?: string;
+    /** Bindings for raw clauses */
+    bindings?: unknown[];
+}
+/**
+ * Where Clause
+ * @description Handles the construction of WHERE clauses with support for complex nested conditions
+ */
+export declare class WhereClause {
+    /** Internal storage for WHERE conditions */
+    private wheres;
+    /**
+     * Add a basic WHERE condition
+     *
+     * @param column - Column name
+     * @param operator - Comparison operator
+     * @param value - Value to compare
+     * @param boolean - Logical connector ('and' or 'or')
+     * @example
+     * ```typescript
+     * clause.add('status', '=', 'active')
+     * ```
+     */
+    add(column: string, operator: Operator, value: unknown, boolean?: 'and' | 'or'): void;
+    /**
+     * Add a group of nested WHERE conditions
+     *
+     * @param conditions - Array of nested conditions
+     * @param boolean - Logical connector for the group
+     * @example
+     * ```typescript
+     * clause.addNested([
+     *   { type: 'basic', column: 'age', operator: '>', value: 18 },
+     *   { type: 'basic', column: 'status', operator: '=', value: 'active', boolean: 'or' }
+     * ])
+     * ```
+     */
+    addNested(conditions: WhereCondition[], boolean?: 'and' | 'or'): void;
+    /**
+     * Add a WHERE IN condition
+     *
+     * @param column - Column name
+     * @param values - Array of values to check against
+     * @param boolean - Logical connector
+     * @param not - Whether to use NOT IN
+     * @example
+     * ```typescript
+     * clause.addIn('id', [1, 2, 3])
+     * ```
+     */
+    addIn(column: string, values: unknown[], boolean?: 'and' | 'or', not?: boolean): void;
+    /**
+     * Add a WHERE NULL condition
+     *
+     * @param column - Column name
+     * @param boolean - Logical connector
+     * @param not - Whether to use IS NOT NULL
+     * @example
+     * ```typescript
+     * clause.addNull('deleted_at')
+     * ```
+     */
+    addNull(column: string, boolean?: 'and' | 'or', not?: boolean): void;
+    /**
+     * Add a WHERE NOT NULL condition
+     *
+     * @param column - Column name
+     * @param boolean - Logical connector
+     */
+    addNotNull(column: string, boolean?: 'and' | 'or'): void;
+    /**
+     * Add a WHERE BETWEEN condition
+     *
+     * @param column - Column name
+     * @param values - [min, max] values
+     * @param boolean - Logical connector
+     * @param not - Negate condition
+     */
+    addBetween(column: string, values: [unknown, unknown], boolean?: 'and' | 'or', not?: boolean): void;
+    /**
+     * Add a raw WHERE condition
+     *
+     * @param sql - SQL string
+     * @param bindings - Bindings array
+     * @param boolean - Logical connector
+     */
+    addRaw(sql: string, bindings: unknown[], boolean?: 'and' | 'or'): void;
+    /**
+     * Add a column comparison condition
+     *
+     * @param first - First column
+     * @param operator - Operator
+     * @param second - Second column
+     * @param boolean - Logical connector
+     */
+    addColumn(first: string, operator: Operator, second: string, boolean?: 'and' | 'or'): void;
+    /**
+     * Get all registered WHERE conditions
+     *
+     * @returns Array of conditions
+     */
+    getWheres(): WhereCondition[];
+    /**
+     * Helper to perform deep copy of conditions
+     */
+    private deepCopyConditions;
+    /**
+     * Extract all values from the conditions for use as query bindings
+     *
+     * @returns Array of binding values
+     */
+    getValues(): unknown[];
+    private getNestedValues;
+    /**
+     * Compile the WHERE clause to SQL
+     *
+     * @returns SQL string for the clause
+     */
+    toSQL(): string;
+    /**
+     * Recursively compile nested conditions to SQL
+     *
+     * @param conditions - Array of nested conditions
+     * @returns Compiled SQL string for the nested group
+     * @internal
+     */
+    private compileNested;
+    /**
+     * Reset the clause state
+     */
+    reset(): void;
+    /**
+     * Check if the clause has any conditions registered
+     *
+     * @returns True if conditions exist
+     */
+    hasConditions(): boolean;
+    /**
+     * Clone the clause
+     *
+     * @returns A deep copy of the clause
+     */
+    clone(): WhereClause;
+}

package/dist/atlas/src/query/clauses/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Query Clauses Index
+ * @description Re-exports all query clause modules for easier access
+ */
+export { GroupByClause } from './GroupByClause';
+export { HavingClause } from './HavingClause';
+export { JoinManager } from './JoinClause';
+export { LimitClause } from './LimitClause';
+export { OrderByClause } from './OrderByClause';
+export { SelectClause } from './SelectClause';
+export { WhereClause, type WhereCondition } from './WhereClause';