@expo/entity-database-adapter-knex 0.55.0 → 0.57.0

package/build/src/SQLOperator.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Supported SQL value types that can be safely parameterized.
+ * This ensures type safety and prevents passing unsupported types to SQL queries.
+ */
+export type SupportedSQLValue = string | number | boolean | null | Date | Buffer | bigint | undefined | readonly SupportedSQLValue[] | Readonly<{
+    [key: string]: unknown;
+}>;
+/**
+ * Types of bindings that can be used in SQL queries.
+ */
+export type SQLBinding<TFields extends Record<string, any>> = {
+    type: 'value';
+    value: SupportedSQLValue;
+} | {
+    type: 'identifier';
+    name: string;
+} | {
+    type: 'entityField';
+    fieldName: keyof TFields;
+};
+/**
+ * SQL Fragment class that safely handles parameterized queries.
+ */
+export declare class SQLFragment<TFields extends Record<string, any>> {
+    readonly sql: string;
+    readonly bindings: readonly SQLBinding<TFields>[];
+    constructor(sql: string, bindings: readonly SQLBinding<TFields>[]);
+    /**
+     * Get bindings in the format expected by Knex.
+     * Knex expects a flat array where both identifiers and values are mixed in order.
+     *
+     * @param getColumnForField - function that resolves an entity field name to its database column name
+     */
+    getKnexBindings(getColumnForField: (fieldName: keyof TFields) => string): readonly (string | SupportedSQLValue)[];
+    /**
+     * Combine SQL fragments
+     */
+    append(other: SQLFragment<TFields>): SQLFragment<TFields>;
+    /**
+     * Join multiple SQL fragments with a comma separator.
+     * Useful for combining column lists, value lists, etc.
+     *
+     * @param fragments - Array of SQL fragments to join
+     * @returns - A new SQLFragment with the fragments joined by a comma and space
+     */
+    static joinWithCommaSeparator<TFields extends Record<string, any>>(...fragments: readonly SQLFragment<TFields>[]): SQLFragment<TFields>;
+    /**
+     * Concatenate multiple SQL fragments with space separator.
+     * Useful for combining SQL clauses like WHERE, ORDER BY, etc.
+     *
+     * @example
+     * ```ts
+     * const where = sql`WHERE age > ${18}`;
+     * const orderBy = sql`ORDER BY name`;
+     * const query = SQLFragment.concat(sql`SELECT * FROM users`, where, orderBy);
+     * // Generates: "SELECT * FROM users WHERE age > ? ORDER BY name"
+     * ```
+     */
+    static concat<TFields extends Record<string, any>>(...fragments: readonly SQLFragment<TFields>[]): SQLFragment<TFields>;
+    /**
+     * Get a debug representation of the query with values inline
+     * WARNING: This is for debugging only. Never execute the returned string directly.
+     */
+    getDebugString(): string;
+    /**
+     * Format a value for debug output based on its type.
+     * Handles all SupportedSQLValue types.
+     */
+    private static formatDebugValue;
+    private static isPlainObjectForDebug;
+}
+/**
+ * Helper for SQL identifiers (table/column names).
+ * Stores the raw identifier name to be escaped by Knex using ?? placeholder.
+ */
+export declare class SQLIdentifier {
+    readonly name: string;
+    constructor(name: string);
+}
+/**
+ * Helper for referencing entity fields that can be used in SQL queries. This allows for type-safe references to fields of an entity
+ * and does automatic translation to DB field names.
+ */
+export declare class SQLEntityField<TFields extends Record<string, any>> {
+    readonly fieldName: keyof TFields;
+    constructor(fieldName: keyof TFields);
+}
+/**
+ * Helper for raw SQL that should not be parameterized
+ * WARNING: Only use this with trusted input to avoid SQL injection
+ */
+export declare class SQLUnsafeRaw {
+    readonly rawSql: string;
+    constructor(rawSql: string);
+}
+/**
+ * Create a SQL identifier (table/column name) that will be escaped by Knex using ??.
+ *
+ * @example
+ * ```ts
+ * identifier('users') // Will be escaped as "users" in PostgreSQL
+ * identifier('my"table') // Will be escaped as "my""table" in PostgreSQL
+ * identifier('column"; DROP TABLE users; --') // Will be safely escaped
+ * ```
+ */
+export declare function identifier(name: string): SQLIdentifier;
+/**
+ * Create a reference to an entity field that can be used in SQL queries. This allows for type-safe references to fields of an entity
+ * and does automatic translation to DB field names and will be escaped by Knex using ??.
+ *
+ * @param fieldName - The entity field name to reference.
+ */
+export declare function entityField<TFields extends Record<string, any>>(fieldName: keyof TFields): SQLEntityField<TFields>;
+/**
+ * Insert raw SQL that will not be parameterized
+ * WARNING: This bypasses SQL injection protection. Only use with trusted input.
+ *
+ * @example
+ * ```ts
+ * // Dynamic column names
+ * const sortColumn = 'created_at';
+ * const query = sql`ORDER BY ${unsafeRaw(sortColumn)} DESC`;
+ *
+ * // Dynamic SQL expressions
+ * const query = sql`WHERE ${unsafeRaw('EXTRACT(year FROM created_at)')} = ${2024}`;
+ * ```
+ */
+export declare function unsafeRaw(sqlString: string): SQLUnsafeRaw;
+/**
+ * Tagged template literal function for SQL queries
+ *
+ * @example
+ * ```ts
+ * const age = 18;
+ * const query = sql`age >= ${age} AND status = ${'active'}`;
+ * ```
+ */
+export declare function sql<TFields extends Record<string, any>>(strings: TemplateStringsArray, ...values: readonly (SupportedSQLValue | SQLFragment<TFields> | SQLIdentifier | SQLUnsafeRaw | SQLEntityField<TFields>)[]): SQLFragment<TFields>;
+type PickSupportedSQLValueKeys<T> = {
+    [K in keyof T]: T[K] extends SupportedSQLValue ? K : never;
+}[keyof T];
+/**
+ * Common SQL helper functions for building queries
+ */
+export declare const SQLFragmentHelpers: {
+    /**
+     * IN clause helper
+     *
+     * @example
+     * ```ts
+     * const query = SQLFragmentHelpers.inArray<MyFields, 'id'>('status', ['active', 'pending']);
+     * // Generates: ?? IN (?, ?) with entityField binding for 'status' and value bindings
+     * ```
+     */
+    inArray<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, values: readonly TFields[N][]): SQLFragment<TFields>;
+    /**
+     * NOT IN clause helper
+     */
+    notInArray<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, values: readonly TFields[N][]): SQLFragment<TFields>;
+    /**
+     * BETWEEN helper
+     *
+     * @example
+     * ```ts
+     * const query = SQLFragmentHelpers.between<MyFields, 'id'>('age', 18, 65);
+     * // Generates: ?? BETWEEN ? AND ? with entityField binding for 'age' and value bindings
+     * ```
+     */
+    between<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, min: TFields[N], max: TFields[N]): SQLFragment<TFields>;
+    /**
+     * NOT BETWEEN helper
+     */
+    notBetween<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, min: TFields[N], max: TFields[N]): SQLFragment<TFields>;
+    /**
+     * LIKE helper with automatic escaping
+     *
+     * @example
+     * ```ts
+     * const query = SQLFragmentHelpers.like<MyFields, 'id'>('name', '%John%');
+     * // Generates: ?? LIKE ? with entityField binding for 'name' and value binding
+     * ```
+     */
+    like<TFields extends Record<string, any>>(fieldName: keyof TFields, pattern: string): SQLFragment<TFields>;
+    /**
+     * NOT LIKE helper
+     */
+    notLike<TFields extends Record<string, any>>(fieldName: keyof TFields, pattern: string): SQLFragment<TFields>;
+    /**
+     * ILIKE helper for case-insensitive matching
+     */
+    ilike<TFields extends Record<string, any>>(fieldName: keyof TFields, pattern: string): SQLFragment<TFields>;
+    /**
+     * NOT ILIKE helper for case-insensitive non-matching
+     */
+    notIlike<TFields extends Record<string, any>>(fieldName: keyof TFields, pattern: string): SQLFragment<TFields>;
+    /**
+     * NULL check helper
+     */
+    isNull<TFields extends Record<string, any>>(fieldName: keyof TFields): SQLFragment<TFields>;
+    /**
+     * NOT NULL check helper
+     */
+    isNotNull<TFields extends Record<string, any>>(fieldName: keyof TFields): SQLFragment<TFields>;
+    /**
+     * Single-equals-equality operator
+     */
+    eq<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    /**
+     * Single-equals-inequality operator
+     */
+    neq<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    /**
+     * Greater-than comparison operator
+     */
+    gt<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    /**
+     * Greater-than-or-equal-to comparison operator
+     */
+    gte<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    /**
+     * Less-than comparison operator
+     */
+    lt<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    /**
+     * Less-than-or-equal-to comparison operator
+     */
+    lte<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    /**
+     * JSON contains operator (\@\>)
+     */
+    jsonContains<TFields extends Record<string, any>>(fieldName: keyof TFields, value: unknown): SQLFragment<TFields>;
+    /**
+     * JSON contained by operator (\<\@\)
+     */
+    jsonContainedBy<TFields extends Record<string, any>>(fieldName: keyof TFields, value: unknown): SQLFragment<TFields>;
+    /**
+     * JSON path extraction helper (-\>)
+     */
+    jsonPath<TFields extends Record<string, any>>(fieldName: keyof TFields, path: string): SQLFragment<TFields>;
+    /**
+     * JSON path text extraction helper (-\>\>)
+     */
+    jsonPathText<TFields extends Record<string, any>>(fieldName: keyof TFields, path: string): SQLFragment<TFields>;
+    /**
+     * Logical AND of multiple fragments
+     */
+    and<TFields extends Record<string, any>>(...conditions: readonly SQLFragment<TFields>[]): SQLFragment<TFields>;
+    /**
+     * Logical OR of multiple fragments
+     */
+    or<TFields extends Record<string, any>>(...conditions: readonly SQLFragment<TFields>[]): SQLFragment<TFields>;
+    /**
+     * Logical NOT of a fragment
+     */
+    not<TFields extends Record<string, any>>(condition: SQLFragment<TFields>): SQLFragment<TFields>;
+    /**
+     * Parentheses helper for grouping conditions
+     */
+    group<TFields extends Record<string, any>>(condition: SQLFragment<TFields>): SQLFragment<TFields>;
+};
+export {};