@qualithm/arrow-flight-sql-js 0.0.1 → 0.1.0

package/dist/query-builder.d.ts

@@ -1 +1,363 @@
+/**
+ * Fluent SQL query builder for constructing type-safe queries.
+ *
+ * This module provides a query builder API that generates SQL strings
+ * compatible with the FlightSqlClient.query() and executeUpdate() methods.
+ *
+ * @example
+ * ```typescript
+ * import { QueryBuilder } from "@qualithm/arrow-flight-sql-js"
+ *
+ * const query = new QueryBuilder()
+ *   .select("id", "name", "email")
+ *   .from("users")
+ *   .where("status", "=", "active")
+ *   .orderBy("created_at", "DESC")
+ *   .limit(10)
+ *   .build()
+ *
+ * const result = await client.query(query)
+ * ```
+ *
+ * @packageDocumentation
+ */
+/** SQL comparison operators */
+export type ComparisonOperator = "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=" | "LIKE" | "NOT LIKE" | "ILIKE" | "IN" | "NOT IN" | "IS" | "IS NOT" | "BETWEEN";
+/** Sort direction */
+export type SortDirection = "ASC" | "DESC";
+/** Join types */
+export type JoinType = "INNER" | "LEFT" | "RIGHT" | "FULL" | "CROSS";
+/** Logical operators for combining conditions */
+export type LogicalOperator = "AND" | "OR";
+/** A single WHERE condition */
+export type WhereCondition = {
+    column: string;
+    operator: ComparisonOperator;
+    value: SqlValue;
+    logical: LogicalOperator;
+};
+/** A raw SQL expression */
+export type RawExpression = {
+    __raw: true;
+    sql: string;
+};
+/** SQL value types */
+export type SqlValue = string | number | boolean | bigint | null | Date | RawExpression | SqlValue[];
+/** Column with optional alias */
+export type ColumnSpec = string | {
+    column: string;
+    alias: string;
+};
+/** Order by specification */
+export type OrderSpec = {
+    column: string;
+    direction: SortDirection;
+    nulls?: "FIRST" | "LAST";
+};
+/** Join specification */
+export type JoinSpec = {
+    type: JoinType;
+    table: string;
+    alias?: string;
+    on: string;
+};
+/** Result of building a query */
+export type BuiltQuery = {
+    /** The SQL query string */
+    sql: string;
+    /** Parameter values for prepared statements (if using parameterized mode) */
+    params: SqlValue[];
+};
+/**
+ * Creates a raw SQL expression that won't be escaped.
+ *
+ * WARNING: Only use with trusted input. Raw expressions bypass escaping
+ * and can lead to SQL injection if used with untrusted data.
+ *
+ * @example
+ * ```typescript
+ * const query = new QueryBuilder()
+ *   .select("*")
+ *   .from("events")
+ *   .where("created_at", ">", raw("NOW() - INTERVAL '1 day'"))
+ *   .build()
+ * ```
+ */
+export declare function raw(sql: string): RawExpression;
+/**
+ * Escape a SQL identifier (table name, column name).
+ * Uses double quotes for standard SQL compliance.
+ */
+export declare function escapeIdentifier(identifier: string): string;
+/**
+ * Escape a SQL string value.
+ * Uses single quotes with proper escaping.
+ */
+export declare function escapeString(value: string): string;
+/**
+ * Format a SQL value for inclusion in a query.
+ */
+export declare function formatValue(value: SqlValue): string;
+/**
+ * Fluent SQL query builder.
+ *
+ * Supports SELECT, INSERT, UPDATE, and DELETE operations with a chainable API.
+ *
+ * @example SELECT query
+ * ```typescript
+ * const sql = new QueryBuilder()
+ *   .select("id", "name")
+ *   .from("users")
+ *   .where("active", "=", true)
+ *   .limit(10)
+ *   .build()
+ * ```
+ *
+ * @example INSERT query
+ * ```typescript
+ * const sql = new QueryBuilder()
+ *   .insertInto("users")
+ *   .columns("name", "email")
+ *   .values("Alice", "alice@example.com")
+ *   .build()
+ * ```
+ *
+ * @example UPDATE query
+ * ```typescript
+ * const sql = new QueryBuilder()
+ *   .update("users")
+ *   .set("status", "inactive")
+ *   .where("last_login", "<", new Date("2024-01-01"))
+ *   .build()
+ * ```
+ *
+ * @example DELETE query
+ * ```typescript
+ * const sql = new QueryBuilder()
+ *   .deleteFrom("users")
+ *   .where("status", "=", "deleted")
+ *   .build()
+ * ```
+ */
+export declare class QueryBuilder {
+    private _operation;
+    private _distinct;
+    private _columns;
+    private _table;
+    private _tableAlias?;
+    private _joins;
+    private _conditions;
+    private _groupBy;
+    private _having;
+    private _orderBy;
+    private _limit?;
+    private _offset?;
+    private _parameterized;
+    private _params;
+    private _insertColumns;
+    private _insertValues;
+    private _setValues;
+    /**
+     * Specify columns to select.
+     *
+     * @param columns - Column names or column specs with aliases
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * .select("id", "name")
+     * .select({ column: "email", alias: "user_email" })
+     * .select("*")
+     * ```
+     */
+    select(...columns: ColumnSpec[]): this;
+    /**
+     * Select distinct rows only.
+     */
+    distinct(): this;
+    /**
+     * Specify the table to query from.
+     *
+     * @param table - Table name
+     * @param alias - Optional table alias
+     */
+    from(table: string, alias?: string): this;
+    /**
+     * Add a JOIN clause.
+     *
+     * @param type - Join type (INNER, LEFT, RIGHT, FULL, CROSS)
+     * @param table - Table to join
+     * @param on - Join condition
+     * @param alias - Optional table alias
+     */
+    join(type: JoinType, table: string, on: string, alias?: string): this;
+    /**
+     * Add an INNER JOIN clause.
+     */
+    innerJoin(table: string, on: string, alias?: string): this;
+    /**
+     * Add a LEFT JOIN clause.
+     */
+    leftJoin(table: string, on: string, alias?: string): this;
+    /**
+     * Add a RIGHT JOIN clause.
+     */
+    rightJoin(table: string, on: string, alias?: string): this;
+    /**
+     * Add a WHERE condition.
+     *
+     * @param column - Column name
+     * @param operator - Comparison operator
+     * @param value - Value to compare against
+     *
+     * @example
+     * ```typescript
+     * .where("status", "=", "active")
+     * .where("age", ">=", 18)
+     * .where("role", "IN", ["admin", "moderator"])
+     * .where("deleted_at", "IS", null)
+     * ```
+     */
+    where(column: string, operator: ComparisonOperator, value: SqlValue): this;
+    /**
+     * Add an OR WHERE condition.
+     */
+    orWhere(column: string, operator: ComparisonOperator, value: SqlValue): this;
+    /**
+     * Add a WHERE BETWEEN condition.
+     */
+    whereBetween(column: string, min: SqlValue, max: SqlValue): this;
+    /**
+     * Add a WHERE IN condition.
+     */
+    whereIn(column: string, values: SqlValue[]): this;
+    /**
+     * Add a WHERE IS NULL condition.
+     */
+    whereNull(column: string): this;
+    /**
+     * Add a WHERE IS NOT NULL condition.
+     */
+    whereNotNull(column: string): this;
+    /**
+     * Add GROUP BY columns.
+     */
+    groupBy(...columns: string[]): this;
+    /**
+     * Add a HAVING condition.
+     */
+    having(column: string, operator: ComparisonOperator, value: SqlValue): this;
+    /**
+     * Add ORDER BY clause.
+     *
+     * @param column - Column to order by
+     * @param direction - Sort direction (ASC or DESC)
+     * @param nulls - NULLS FIRST or NULLS LAST
+     */
+    orderBy(column: string, direction?: SortDirection, nulls?: "FIRST" | "LAST"): this;
+    /**
+     * Set the maximum number of rows to return.
+     */
+    limit(count: number): this;
+    /**
+     * Set the number of rows to skip.
+     */
+    offset(count: number): this;
+    /**
+     * Start an INSERT statement.
+     *
+     * @param table - Table to insert into
+     */
+    insertInto(table: string): this;
+    /**
+     * Specify columns for INSERT.
+     */
+    columns(...columns: string[]): this;
+    /**
+     * Add values to INSERT.
+     * Can be called multiple times for multi-row inserts.
+     *
+     * @param values - Values corresponding to columns
+     */
+    values(...values: SqlValue[]): this;
+    /**
+     * Start an UPDATE statement.
+     *
+     * @param table - Table to update
+     */
+    update(table: string): this;
+    /**
+     * Set a column value for UPDATE.
+     *
+     * @param column - Column to update
+     * @param value - New value
+     */
+    set(column: string, value: SqlValue): this;
+    /**
+     * Set multiple column values for UPDATE.
+     *
+     * @param values - Object mapping column names to values
+     */
+    setMany(values: Record<string, SqlValue>): this;
+    /**
+     * Start a DELETE statement.
+     *
+     * @param table - Table to delete from
+     */
+    deleteFrom(table: string): this;
+    /**
+     * Build the SQL query string.
+     *
+     * @returns The complete SQL query string
+     */
+    build(): string;
+    /**
+     * Build query with parameter placeholders for prepared statements.
+     *
+     * @returns Object containing SQL with placeholders and parameter values
+     */
+    buildParameterized(): BuiltQuery;
+    /**
+     * Create a copy of this query builder.
+     */
+    clone(): QueryBuilder;
+    /**
+     * Reset the builder to initial state.
+     */
+    reset(): this;
+    private buildSelect;
+    private buildInsert;
+    private buildUpdate;
+    private buildDelete;
+    private buildConditions;
+    private formatOrParam;
+}
+/**
+ * Create a new QueryBuilder for a SELECT query.
+ *
+ * @param columns - Columns to select
+ * @returns A new QueryBuilder with SELECT initialized
+ */
+export declare function select(...columns: ColumnSpec[]): QueryBuilder;
+/**
+ * Create a new QueryBuilder for an INSERT query.
+ *
+ * @param table - Table to insert into
+ * @returns A new QueryBuilder with INSERT initialized
+ */
+export declare function insertInto(table: string): QueryBuilder;
+/**
+ * Create a new QueryBuilder for an UPDATE query.
+ *
+ * @param table - Table to update
+ * @returns A new QueryBuilder with UPDATE initialized
+ */
+export declare function update(table: string): QueryBuilder;
+/**
+ * Create a new QueryBuilder for a DELETE query.
+ *
+ * @param table - Table to delete from
+ * @returns A new QueryBuilder with DELETE initialized
+ */
+export declare function deleteFrom(table: string): QueryBuilder;
 //# sourceMappingURL=query-builder.d.ts.map

package/dist/query-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../src/query-builder.ts"],"names":[],"mappings":""}
+{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../src/query-builder.ts"],"names":[],"mappings":"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"}