@react-querybuilder/core 8.20.2 → 8.21.0

package/dist/parseSQL.d.mts

@@ -1,36 +1,284 @@
-import { E as DefaultRuleGroupType, j as Except, x as DefaultRuleGroupTypeIC } from "./index-DlVg-QXo.mjs";
-import { t as ParserCommonOptions } from "./import-ShTj5IdB.mjs";
-
+import { A as DefaultOperatorName, L as Except, P as ExpressionNode, T as DefaultRuleGroupTypeIC, j as DefaultRuleGroupType, k as DefaultCombinatorNameExtended } from "./index-BSwFvkeI.mjs";
+import { t as ParserCommonOptions } from "./import-BVdxeIBO.mjs";
+//#region src/utils/parseSQL/types.d.ts
+type AnyCase<T extends string> = string extends T ? string : T extends `${infer F1}${infer F2}${infer R}` ? `${Uppercase<F1> | Lowercase<F1>}${Uppercase<F2> | Lowercase<F2>}${AnyCase<R>}` : T extends `${infer F}${infer R}` ? `${Uppercase<F> | Lowercase<F>}${AnyCase<R>}` : "";
+type TokenType = "AndExpression" | "BetweenPredicate" | "BitExpression" | "Boolean" | "BooleanExtra" | "CaseWhen" | "ComparisonBooleanPrimary" | "ComparisonSubQueryBooleanPrimary" | "ContainsExpr" | "EndsWithExpr" | "ExpressionList" | "ForceIndexHint" | "ForOptIndexHint" | "FunctionCall" | "FunctionCallParam" | "GroupBy" | "GroupByOrderByItem" | "Identifier" | "IdentifierExpr" | "IdentifierList" | "IgnoreIndexHint" | "IndexHintList" | "InExpressionListPredicate" | "InnerCrossJoinTable" | "InSubQueryPredicate" | "IsExpression" | "IsNullBooleanPrimary" | "LeftRightJoinTable" | "LikePredicate" | "Limit" | "Main" | "NaturalJoinTable" | "NotExpression" | "Null" | "Number" | "OnJoinCondition" | "OrderBy" | "OrExpression" | "Partitions" | "PlaceHolder" | "Prefix" | "RegexpPredicate" | "Select" | "SelectExpr" | "SelectParenthesized" | "SimpleExprParentheses" | "SoundsLikePredicate" | "StartsWithExpr" | "StraightJoinTable" | "String" | "SubQuery" | "TableFactor" | "TableReference" | "TableReferences" | "Union" | "UseIndexHint" | "UsingJoinCondition" | "WhenThenList" | "XorExpression";
+type ComparisonOperator = "=" | ">=" | ">" | "<=" | "<" | "<>" | "!=";
+type NotOpt = AnyCase<"NOT"> | null;
+type AndOperator = AnyCase<"AND">;
+type OrOperator = AnyCase<"OR">;
+type XorOperator = AnyCase<"XOR">;
+interface SQLWhereObject {
+  type: TokenType;
+}
+interface SQLIdentifier extends SQLWhereObject {
+  type: "Identifier";
+  value: string;
+}
+interface SQLWhereObjectAny extends SQLWhereObject {
+  [k: string]: any;
+}
+interface SQLStringValue extends SQLWhereObject {
+  type: "String";
+  value: string;
+}
+interface SQLNumberValue extends SQLWhereObject {
+  type: "Number";
+  value: string;
+}
+interface SQLSignedNumberValue extends SQLWhereObject {
+  type: "Prefix";
+  prefix: "+" | "-";
+  value: SQLNumberValue;
+}
+interface SQLBooleanValue extends SQLWhereObject {
+  type: "Boolean";
+  value: AnyCase<"TRUE"> | AnyCase<"FALSE">;
+}
+interface SQLBooleanExtra extends SQLWhereObject {
+  type: "BooleanExtra";
+  value: AnyCase<"UNKNOWN">;
+}
+interface SQLSimpleExprParentheses extends SQLWhereObject {
+  type: "SimpleExprParentheses";
+  value: SQLExpressionList;
+}
+interface SQLExpressionList extends SQLWhereObject {
+  type: "ExpressionList";
+  value: SQLExpression[];
+}
+interface SQLInExpressionListPredicate extends SQLWhereObject {
+  type: "InExpressionListPredicate";
+  hasNot: NotOpt;
+  left: SQLSimpleExpression;
+  right: SQLExpressionList;
+}
+interface SQLBetweenPredicate extends SQLWhereObject {
+  type: "BetweenPredicate";
+  hasNot: NotOpt;
+  left: SQLSimpleExpression;
+  right: {
+    left: SQLSimpleExpression;
+    right: SQLPredicate;
+  };
+}
+interface SQLLikePredicate extends SQLWhereObject {
+  type: "LikePredicate";
+  hasNot: NotOpt;
+  left: SQLSimpleExpression;
+  right: SQLSimpleExpression | SQLStartsWithExpr | SQLEndsWithExpr | SQLContainsExpr;
+  escape: SQLStringValue | null;
+}
+interface SQLStartsWithExpr extends SQLWhereObject {
+  type: "StartsWithExpr";
+  value: SQLStringValue | SQLIdentifier;
+}
+interface SQLEndsWithExpr extends SQLWhereObject {
+  type: "EndsWithExpr";
+  value: SQLStringValue | SQLIdentifier;
+}
+interface SQLContainsExpr extends SQLWhereObject {
+  type: "ContainsExpr";
+  value: SQLStringValue | SQLIdentifier;
+}
+interface SQLIsNullBooleanPrimary extends SQLWhereObject {
+  type: "IsNullBooleanPrimary";
+  hasNot: NotOpt;
+  value: SQLBooleanPrimary;
+}
+interface SQLComparisonBooleanPrimary extends SQLWhereObject {
+  type: "ComparisonBooleanPrimary";
+  left: SQLBooleanPrimary;
+  operator: ComparisonOperator;
+  right: SQLPredicate;
+}
+interface SQLIsExpression extends SQLWhereObject {
+  type: "IsExpression";
+  hasNot: NotOpt;
+  left: SQLBooleanPrimary;
+  right: SQLBooleanExtra;
+}
+interface SQLNotExpression extends SQLWhereObject {
+  type: "NotExpression";
+  value: SQLExpression;
+}
+interface SQLAndExpression extends SQLWhereObject {
+  type: "AndExpression";
+  operator: AndOperator;
+  left: SQLExpression;
+  right: SQLExpression;
+}
+interface SQLOrExpression extends SQLWhereObject {
+  type: "OrExpression";
+  operator: OrOperator;
+  left: SQLExpression;
+  right: SQLExpression;
+}
+interface SQLXorExpression extends SQLWhereObject {
+  type: "XorExpression";
+  operator: XorOperator;
+  left: SQLExpression;
+  right: SQLExpression;
+}
+interface SQLPlaceHolder extends SQLWhereObject {
+  type: "PlaceHolder";
+  /** Raw token, e.g. `${p1}`. */
+  value: string;
+  /** Prefix-free placeholder name, e.g. `p1`. */
+  param: string;
+}
+interface SQLFunctionCall extends SQLWhereObjectAny {
+  type: "FunctionCall";
+  name: string;
+  params: SQLExpressionOperand[];
+}
+interface SQLCaseWhen extends SQLWhereObjectAny {
+  type: "CaseWhen";
+}
+interface SQLPrefix extends SQLWhereObjectAny {
+  type: "Prefix";
+}
+interface SQLSubQuery extends SQLWhereObjectAny {
+  type: "SubQuery";
+}
+interface SQLIdentifierExpr extends SQLWhereObjectAny {
+  type: "IdentifierExpr";
+}
+interface SQLBitExpression extends SQLWhereObjectAny {
+  type: "BitExpression";
+  operator: string;
+  left: SQLExpressionOperand;
+  right: SQLExpressionOperand;
+}
+interface SQLInSubQueryPredicate extends SQLWhereObjectAny {
+  type: "InSubQueryPredicate";
+}
+interface SQLSoundsLikePredicate extends SQLWhereObjectAny {
+  type: "SoundsLikePredicate";
+}
+interface SQLRegexpPredicate extends SQLWhereObjectAny {
+  type: "RegexpPredicate";
+}
+interface SQLComparisonSubQueryBooleanPrimary extends SQLWhereObjectAny {
+  type: "ComparisonSubQueryBooleanPrimary";
+}
+type SQLLiteralValue = SQLStringValue | SQLNumberValue | SQLBooleanValue;
+type SQLSimpleExpression = SQLLiteralValue | SQLIdentifier | SQLFunctionCall | SQLCaseWhen | SQLPrefix | SQLSubQuery | SQLIdentifierExpr | SQLBitExpression | SQLPlaceHolder | SQLSimpleExprParentheses;
+type SQLPredicate = SQLSimpleExpression | SQLInExpressionListPredicate | SQLBetweenPredicate | SQLLikePredicate | SQLInSubQueryPredicate | SQLSoundsLikePredicate | SQLRegexpPredicate;
+type SQLBooleanPrimary = SQLPredicate | SQLIsNullBooleanPrimary | SQLComparisonBooleanPrimary | SQLComparisonSubQueryBooleanPrimary;
+type SQLExpression = SQLBooleanPrimary | SQLIsExpression | SQLNotExpression | SQLAndExpression | SQLOrExpression | SQLXorExpression;
+interface ParsedSQL {
+  nodeType: "Main";
+  value: {
+    type: "Select";
+    distinctOpt: string | null;
+    highPriorityOpt: unknown;
+    maxStateMentTimeOpt: unknown;
+    straightJoinOpt: unknown;
+    sqlSmallResultOpt: unknown;
+    sqlBigResultOpt: unknown;
+    sqlBufferResultOpt: unknown;
+    sqlCacheOpt: unknown;
+    sqlCalcFoundRowsOpt: unknown;
+    selectItems: SQLWhereObjectAny;
+    from: SQLWhereObjectAny;
+    partition: unknown;
+    where: SQLExpression;
+    groupBy: SQLWhereObjectAny | null;
+    having: SQLWhereObjectAny | null;
+    orderBy: SQLWhereObjectAny | null;
+    limit: SQLWhereObjectAny | null;
+    procedure: SQLWhereObjectAny | null;
+    updateLockMode: unknown;
+  };
+  hasSemicolon: boolean;
+}
+type MixedAndXorOrList = {
+  combinator: DefaultCombinatorNameExtended;
+  expressions: (MixedAndXorOrList | SQLExpression)[];
+};
+/**
+ * A SQL operand subtree that a {@link ParseSQLOptions.getExpression} handler may receive: a
+ * bare identifier, a (signed) literal, a placeholder, an arithmetic {@link SQLBitExpression},
+ * a {@link SQLFunctionCall}, or a parenthesized wrapper (unwrapped by the handler).
+ */
+type SQLExpressionOperand = SQLIdentifier | SQLLiteralValue | SQLSignedNumberValue | SQLPlaceHolder | SQLBitExpression | SQLFunctionCall | SQLSimpleExprParentheses;
+/**
+ * Context passed to a {@link ParseSQLOptions.getExpression} handler alongside the operand
+ * node. Carries the same number-parsing option as the rest of `parseSQL` plus a predicate
+ * for validating that `field` leaves inside an expression exist in the configured fields.
+ */
+interface ParseSQLExpressionContext {
+  bigIntOnOverflow?: boolean;
+  /** `true` when the field exists in the configured fields (or no fields were configured). */
+  fieldExists: (fieldName: string) => boolean;
+}
+//#endregion
 //#region src/utils/parseSQL/parseSQL.d.ts
 /**
-* Options object for {@link parseSQL}.
-*/
+ * Options object for {@link parseSQL}.
+ */
 interface ParseSQLOptions extends ParserCommonOptions {
   paramPrefix?: string;
   params?: any[] | Record<string, any>;
+  /**
+   * Handler that converts a non-identifier/non-literal SQL operand subtree (arithmetic
+   * {@link SQLExpressionOperand BitExpression} / FunctionCall / parenthesized) into an
+   * {@link ExpressionNode}. Return `null` to reject (the rule is dropped). Supplied by
+   * `@react-querybuilder/expr` (`expressionParserSQL`). When omitted, expression operands
+   * are ignored (current behavior — rule dropped).
+   */
+  getExpression?: (node: SQLExpressionOperand, ctx: ParseSQLExpressionContext) => ExpressionNode | null;
+  /**
+   * When set, parameter placeholders are retained as `valueSource: 'parameter'` rules
+   * (value = placeholder name) instead of being dropped. Placeholders whose name is
+   * supplied via {@link ParseSQLOptions.params} are still substituted to literals first.
+   *
+   * - `true` — accept the default named prefix `':'` and positional `'?'`.
+   * - `{ prefix }` — one or more named prefixes to accept (e.g. `':'`, `'@'`, `'$'`).
+   * - `{ positional }` — enable/disable positional `?` (default enabled).
+   */
+  parseParameters?: boolean | {
+    prefix?: string | string[];
+    positional?: boolean;
+  };
 }
 /**
-* Converts a SQL `SELECT` statement into a query suitable for the
-* {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
-* ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
-*/
+ * Converts a SQL `SELECT` statement into a query suitable for the
+ * {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
+ * ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
+ */
 declare function parseSQL(sql: string): DefaultRuleGroupType;
 /**
-* Converts a SQL `SELECT` statement into a query suitable for the
-* {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
-* ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
-*/
+ * Converts a SQL `SELECT` statement into a query suitable for the
+ * {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
+ * ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
+ */
 declare function parseSQL(sql: string, options: Except<ParseSQLOptions, "independentCombinators"> & {
   independentCombinators?: false;
 }): DefaultRuleGroupType;
 /**
-* Converts a SQL `SELECT` statement into a query suitable for the
-* {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
-* ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
-*/
+ * Converts a SQL `SELECT` statement into a query suitable for the
+ * {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
+ * ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
+ */
 declare function parseSQL(sql: string, options: Except<ParseSQLOptions, "independentCombinators"> & {
   independentCombinators: true;
 }): DefaultRuleGroupTypeIC;
 //#endregion
-export { ParseSQLOptions, parseSQL };
+//#region src/utils/parseSQL/utils.d.ts
+declare const isSQLLiteralValue: (v?: SQLWhereObjectAny) => v is SQLLiteralValue;
+declare const isSQLSignedNumber: (v?: SQLWhereObjectAny) => v is SQLSignedNumberValue;
+declare const isSQLLiteralOrSignedNumberValue: (v?: SQLWhereObjectAny) => v is SQLLiteralValue | SQLSignedNumberValue;
+declare const isSQLIdentifier: (v?: SQLWhereObjectAny) => v is SQLIdentifier;
+declare const isSQLBitExpression: (v?: SQLWhereObjectAny) => v is SQLBitExpression;
+declare const isSQLFunctionCall: (v?: SQLWhereObjectAny) => v is SQLFunctionCall;
+declare const isSQLPlaceHolder: (v?: SQLWhereObjectAny) => v is SQLPlaceHolder;
+/** An operand that is neither a bare identifier nor a (signed) literal nor a placeholder. */
+declare const isSQLExpressionOperand: (v?: SQLWhereObjectAny) => boolean;
+declare const getFieldName: (f: string | SQLIdentifier) => string;
+declare const normalizeOperator: (op: ComparisonOperator, flip?: boolean) => DefaultOperatorName;
+declare const evalSQLLiteralValue: (valueObj: SQLLiteralValue | SQLSignedNumberValue, { bigIntOnOverflow }?: ParseSQLOptions) => any;
+//#endregion
+export { AndOperator, ComparisonOperator, MixedAndXorOrList, NotOpt, OrOperator, ParseSQLExpressionContext, ParseSQLOptions, ParsedSQL, SQLAndExpression, SQLBetweenPredicate, SQLBitExpression, SQLBooleanExtra, SQLBooleanPrimary, SQLBooleanValue, SQLCaseWhen, SQLComparisonBooleanPrimary, SQLComparisonSubQueryBooleanPrimary, SQLContainsExpr, SQLEndsWithExpr, SQLExpression, SQLExpressionList, SQLExpressionOperand, SQLFunctionCall, SQLIdentifier, SQLIdentifierExpr, SQLInExpressionListPredicate, SQLInSubQueryPredicate, SQLIsExpression, SQLIsNullBooleanPrimary, SQLLikePredicate, SQLLiteralValue, SQLNotExpression, SQLNumberValue, SQLOrExpression, SQLPlaceHolder, SQLPredicate, SQLPrefix, SQLRegexpPredicate, SQLSignedNumberValue, SQLSimpleExprParentheses, SQLSimpleExpression, SQLSoundsLikePredicate, SQLStartsWithExpr, SQLStringValue, SQLSubQuery, SQLWhereObject, SQLWhereObjectAny, SQLXorExpression, XorOperator, evalSQLLiteralValue, getFieldName, isSQLBitExpression, isSQLExpressionOperand, isSQLFunctionCall, isSQLIdentifier, isSQLLiteralOrSignedNumberValue, isSQLLiteralValue, isSQLPlaceHolder, isSQLSignedNumber, normalizeOperator, parseSQL };
 //# sourceMappingURL=parseSQL.d.mts.map

package/dist/parseSQL.d.ts

@@ -1,36 +1,284 @@
-import { E as DefaultRuleGroupType, j as Except, x as DefaultRuleGroupTypeIC } from "./index-DlVg-QXo.js";
-import { t as ParserCommonOptions } from "./import-Qs1-kgv5.js";
-
+import { A as DefaultOperatorName, L as Except, P as ExpressionNode, T as DefaultRuleGroupTypeIC, j as DefaultRuleGroupType, k as DefaultCombinatorNameExtended } from "./index-BSwFvkeI.js";
+import { t as ParserCommonOptions } from "./import-Ddc3d_8q.js";
+//#region src/utils/parseSQL/types.d.ts
+type AnyCase<T extends string> = string extends T ? string : T extends `${infer F1}${infer F2}${infer R}` ? `${Uppercase<F1> | Lowercase<F1>}${Uppercase<F2> | Lowercase<F2>}${AnyCase<R>}` : T extends `${infer F}${infer R}` ? `${Uppercase<F> | Lowercase<F>}${AnyCase<R>}` : "";
+type TokenType = "AndExpression" | "BetweenPredicate" | "BitExpression" | "Boolean" | "BooleanExtra" | "CaseWhen" | "ComparisonBooleanPrimary" | "ComparisonSubQueryBooleanPrimary" | "ContainsExpr" | "EndsWithExpr" | "ExpressionList" | "ForceIndexHint" | "ForOptIndexHint" | "FunctionCall" | "FunctionCallParam" | "GroupBy" | "GroupByOrderByItem" | "Identifier" | "IdentifierExpr" | "IdentifierList" | "IgnoreIndexHint" | "IndexHintList" | "InExpressionListPredicate" | "InnerCrossJoinTable" | "InSubQueryPredicate" | "IsExpression" | "IsNullBooleanPrimary" | "LeftRightJoinTable" | "LikePredicate" | "Limit" | "Main" | "NaturalJoinTable" | "NotExpression" | "Null" | "Number" | "OnJoinCondition" | "OrderBy" | "OrExpression" | "Partitions" | "PlaceHolder" | "Prefix" | "RegexpPredicate" | "Select" | "SelectExpr" | "SelectParenthesized" | "SimpleExprParentheses" | "SoundsLikePredicate" | "StartsWithExpr" | "StraightJoinTable" | "String" | "SubQuery" | "TableFactor" | "TableReference" | "TableReferences" | "Union" | "UseIndexHint" | "UsingJoinCondition" | "WhenThenList" | "XorExpression";
+type ComparisonOperator = "=" | ">=" | ">" | "<=" | "<" | "<>" | "!=";
+type NotOpt = AnyCase<"NOT"> | null;
+type AndOperator = AnyCase<"AND">;
+type OrOperator = AnyCase<"OR">;
+type XorOperator = AnyCase<"XOR">;
+interface SQLWhereObject {
+  type: TokenType;
+}
+interface SQLIdentifier extends SQLWhereObject {
+  type: "Identifier";
+  value: string;
+}
+interface SQLWhereObjectAny extends SQLWhereObject {
+  [k: string]: any;
+}
+interface SQLStringValue extends SQLWhereObject {
+  type: "String";
+  value: string;
+}
+interface SQLNumberValue extends SQLWhereObject {
+  type: "Number";
+  value: string;
+}
+interface SQLSignedNumberValue extends SQLWhereObject {
+  type: "Prefix";
+  prefix: "+" | "-";
+  value: SQLNumberValue;
+}
+interface SQLBooleanValue extends SQLWhereObject {
+  type: "Boolean";
+  value: AnyCase<"TRUE"> | AnyCase<"FALSE">;
+}
+interface SQLBooleanExtra extends SQLWhereObject {
+  type: "BooleanExtra";
+  value: AnyCase<"UNKNOWN">;
+}
+interface SQLSimpleExprParentheses extends SQLWhereObject {
+  type: "SimpleExprParentheses";
+  value: SQLExpressionList;
+}
+interface SQLExpressionList extends SQLWhereObject {
+  type: "ExpressionList";
+  value: SQLExpression[];
+}
+interface SQLInExpressionListPredicate extends SQLWhereObject {
+  type: "InExpressionListPredicate";
+  hasNot: NotOpt;
+  left: SQLSimpleExpression;
+  right: SQLExpressionList;
+}
+interface SQLBetweenPredicate extends SQLWhereObject {
+  type: "BetweenPredicate";
+  hasNot: NotOpt;
+  left: SQLSimpleExpression;
+  right: {
+    left: SQLSimpleExpression;
+    right: SQLPredicate;
+  };
+}
+interface SQLLikePredicate extends SQLWhereObject {
+  type: "LikePredicate";
+  hasNot: NotOpt;
+  left: SQLSimpleExpression;
+  right: SQLSimpleExpression | SQLStartsWithExpr | SQLEndsWithExpr | SQLContainsExpr;
+  escape: SQLStringValue | null;
+}
+interface SQLStartsWithExpr extends SQLWhereObject {
+  type: "StartsWithExpr";
+  value: SQLStringValue | SQLIdentifier;
+}
+interface SQLEndsWithExpr extends SQLWhereObject {
+  type: "EndsWithExpr";
+  value: SQLStringValue | SQLIdentifier;
+}
+interface SQLContainsExpr extends SQLWhereObject {
+  type: "ContainsExpr";
+  value: SQLStringValue | SQLIdentifier;
+}
+interface SQLIsNullBooleanPrimary extends SQLWhereObject {
+  type: "IsNullBooleanPrimary";
+  hasNot: NotOpt;
+  value: SQLBooleanPrimary;
+}
+interface SQLComparisonBooleanPrimary extends SQLWhereObject {
+  type: "ComparisonBooleanPrimary";
+  left: SQLBooleanPrimary;
+  operator: ComparisonOperator;
+  right: SQLPredicate;
+}
+interface SQLIsExpression extends SQLWhereObject {
+  type: "IsExpression";
+  hasNot: NotOpt;
+  left: SQLBooleanPrimary;
+  right: SQLBooleanExtra;
+}
+interface SQLNotExpression extends SQLWhereObject {
+  type: "NotExpression";
+  value: SQLExpression;
+}
+interface SQLAndExpression extends SQLWhereObject {
+  type: "AndExpression";
+  operator: AndOperator;
+  left: SQLExpression;
+  right: SQLExpression;
+}
+interface SQLOrExpression extends SQLWhereObject {
+  type: "OrExpression";
+  operator: OrOperator;
+  left: SQLExpression;
+  right: SQLExpression;
+}
+interface SQLXorExpression extends SQLWhereObject {
+  type: "XorExpression";
+  operator: XorOperator;
+  left: SQLExpression;
+  right: SQLExpression;
+}
+interface SQLPlaceHolder extends SQLWhereObject {
+  type: "PlaceHolder";
+  /** Raw token, e.g. `${p1}`. */
+  value: string;
+  /** Prefix-free placeholder name, e.g. `p1`. */
+  param: string;
+}
+interface SQLFunctionCall extends SQLWhereObjectAny {
+  type: "FunctionCall";
+  name: string;
+  params: SQLExpressionOperand[];
+}
+interface SQLCaseWhen extends SQLWhereObjectAny {
+  type: "CaseWhen";
+}
+interface SQLPrefix extends SQLWhereObjectAny {
+  type: "Prefix";
+}
+interface SQLSubQuery extends SQLWhereObjectAny {
+  type: "SubQuery";
+}
+interface SQLIdentifierExpr extends SQLWhereObjectAny {
+  type: "IdentifierExpr";
+}
+interface SQLBitExpression extends SQLWhereObjectAny {
+  type: "BitExpression";
+  operator: string;
+  left: SQLExpressionOperand;
+  right: SQLExpressionOperand;
+}
+interface SQLInSubQueryPredicate extends SQLWhereObjectAny {
+  type: "InSubQueryPredicate";
+}
+interface SQLSoundsLikePredicate extends SQLWhereObjectAny {
+  type: "SoundsLikePredicate";
+}
+interface SQLRegexpPredicate extends SQLWhereObjectAny {
+  type: "RegexpPredicate";
+}
+interface SQLComparisonSubQueryBooleanPrimary extends SQLWhereObjectAny {
+  type: "ComparisonSubQueryBooleanPrimary";
+}
+type SQLLiteralValue = SQLStringValue | SQLNumberValue | SQLBooleanValue;
+type SQLSimpleExpression = SQLLiteralValue | SQLIdentifier | SQLFunctionCall | SQLCaseWhen | SQLPrefix | SQLSubQuery | SQLIdentifierExpr | SQLBitExpression | SQLPlaceHolder | SQLSimpleExprParentheses;
+type SQLPredicate = SQLSimpleExpression | SQLInExpressionListPredicate | SQLBetweenPredicate | SQLLikePredicate | SQLInSubQueryPredicate | SQLSoundsLikePredicate | SQLRegexpPredicate;
+type SQLBooleanPrimary = SQLPredicate | SQLIsNullBooleanPrimary | SQLComparisonBooleanPrimary | SQLComparisonSubQueryBooleanPrimary;
+type SQLExpression = SQLBooleanPrimary | SQLIsExpression | SQLNotExpression | SQLAndExpression | SQLOrExpression | SQLXorExpression;
+interface ParsedSQL {
+  nodeType: "Main";
+  value: {
+    type: "Select";
+    distinctOpt: string | null;
+    highPriorityOpt: unknown;
+    maxStateMentTimeOpt: unknown;
+    straightJoinOpt: unknown;
+    sqlSmallResultOpt: unknown;
+    sqlBigResultOpt: unknown;
+    sqlBufferResultOpt: unknown;
+    sqlCacheOpt: unknown;
+    sqlCalcFoundRowsOpt: unknown;
+    selectItems: SQLWhereObjectAny;
+    from: SQLWhereObjectAny;
+    partition: unknown;
+    where: SQLExpression;
+    groupBy: SQLWhereObjectAny | null;
+    having: SQLWhereObjectAny | null;
+    orderBy: SQLWhereObjectAny | null;
+    limit: SQLWhereObjectAny | null;
+    procedure: SQLWhereObjectAny | null;
+    updateLockMode: unknown;
+  };
+  hasSemicolon: boolean;
+}
+type MixedAndXorOrList = {
+  combinator: DefaultCombinatorNameExtended;
+  expressions: (MixedAndXorOrList | SQLExpression)[];
+};
+/**
+ * A SQL operand subtree that a {@link ParseSQLOptions.getExpression} handler may receive: a
+ * bare identifier, a (signed) literal, a placeholder, an arithmetic {@link SQLBitExpression},
+ * a {@link SQLFunctionCall}, or a parenthesized wrapper (unwrapped by the handler).
+ */
+type SQLExpressionOperand = SQLIdentifier | SQLLiteralValue | SQLSignedNumberValue | SQLPlaceHolder | SQLBitExpression | SQLFunctionCall | SQLSimpleExprParentheses;
+/**
+ * Context passed to a {@link ParseSQLOptions.getExpression} handler alongside the operand
+ * node. Carries the same number-parsing option as the rest of `parseSQL` plus a predicate
+ * for validating that `field` leaves inside an expression exist in the configured fields.
+ */
+interface ParseSQLExpressionContext {
+  bigIntOnOverflow?: boolean;
+  /** `true` when the field exists in the configured fields (or no fields were configured). */
+  fieldExists: (fieldName: string) => boolean;
+}
+//#endregion
 //#region src/utils/parseSQL/parseSQL.d.ts
 /**
-* Options object for {@link parseSQL}.
-*/
+ * Options object for {@link parseSQL}.
+ */
 interface ParseSQLOptions extends ParserCommonOptions {
   paramPrefix?: string;
   params?: any[] | Record<string, any>;
+  /**
+   * Handler that converts a non-identifier/non-literal SQL operand subtree (arithmetic
+   * {@link SQLExpressionOperand BitExpression} / FunctionCall / parenthesized) into an
+   * {@link ExpressionNode}. Return `null` to reject (the rule is dropped). Supplied by
+   * `@react-querybuilder/expr` (`expressionParserSQL`). When omitted, expression operands
+   * are ignored (current behavior — rule dropped).
+   */
+  getExpression?: (node: SQLExpressionOperand, ctx: ParseSQLExpressionContext) => ExpressionNode | null;
+  /**
+   * When set, parameter placeholders are retained as `valueSource: 'parameter'` rules
+   * (value = placeholder name) instead of being dropped. Placeholders whose name is
+   * supplied via {@link ParseSQLOptions.params} are still substituted to literals first.
+   *
+   * - `true` — accept the default named prefix `':'` and positional `'?'`.
+   * - `{ prefix }` — one or more named prefixes to accept (e.g. `':'`, `'@'`, `'$'`).
+   * - `{ positional }` — enable/disable positional `?` (default enabled).
+   */
+  parseParameters?: boolean | {
+    prefix?: string | string[];
+    positional?: boolean;
+  };
 }
 /**
-* Converts a SQL `SELECT` statement into a query suitable for the
-* {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
-* ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
-*/
+ * Converts a SQL `SELECT` statement into a query suitable for the
+ * {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
+ * ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
+ */
 declare function parseSQL(sql: string): DefaultRuleGroupType;
 /**
-* Converts a SQL `SELECT` statement into a query suitable for the
-* {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
-* ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
-*/
+ * Converts a SQL `SELECT` statement into a query suitable for the
+ * {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
+ * ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
+ */
 declare function parseSQL(sql: string, options: Except<ParseSQLOptions, "independentCombinators"> & {
   independentCombinators?: false;
 }): DefaultRuleGroupType;
 /**
-* Converts a SQL `SELECT` statement into a query suitable for the
-* {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
-* ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
-*/
+ * Converts a SQL `SELECT` statement into a query suitable for the
+ * {@link index!QueryBuilder QueryBuilder} component's `query` or `defaultQuery` props
+ * ({@link index!DefaultRuleGroupType DefaultRuleGroupType}).
+ */
 declare function parseSQL(sql: string, options: Except<ParseSQLOptions, "independentCombinators"> & {
   independentCombinators: true;
 }): DefaultRuleGroupTypeIC;
 //#endregion
-export { ParseSQLOptions, parseSQL };
+//#region src/utils/parseSQL/utils.d.ts
+declare const isSQLLiteralValue: (v?: SQLWhereObjectAny) => v is SQLLiteralValue;
+declare const isSQLSignedNumber: (v?: SQLWhereObjectAny) => v is SQLSignedNumberValue;
+declare const isSQLLiteralOrSignedNumberValue: (v?: SQLWhereObjectAny) => v is SQLLiteralValue | SQLSignedNumberValue;
+declare const isSQLIdentifier: (v?: SQLWhereObjectAny) => v is SQLIdentifier;
+declare const isSQLBitExpression: (v?: SQLWhereObjectAny) => v is SQLBitExpression;
+declare const isSQLFunctionCall: (v?: SQLWhereObjectAny) => v is SQLFunctionCall;
+declare const isSQLPlaceHolder: (v?: SQLWhereObjectAny) => v is SQLPlaceHolder;
+/** An operand that is neither a bare identifier nor a (signed) literal nor a placeholder. */
+declare const isSQLExpressionOperand: (v?: SQLWhereObjectAny) => boolean;
+declare const getFieldName: (f: string | SQLIdentifier) => string;
+declare const normalizeOperator: (op: ComparisonOperator, flip?: boolean) => DefaultOperatorName;
+declare const evalSQLLiteralValue: (valueObj: SQLLiteralValue | SQLSignedNumberValue, { bigIntOnOverflow }?: ParseSQLOptions) => any;
+//#endregion
+export { AndOperator, ComparisonOperator, MixedAndXorOrList, NotOpt, OrOperator, ParseSQLExpressionContext, ParseSQLOptions, ParsedSQL, SQLAndExpression, SQLBetweenPredicate, SQLBitExpression, SQLBooleanExtra, SQLBooleanPrimary, SQLBooleanValue, SQLCaseWhen, SQLComparisonBooleanPrimary, SQLComparisonSubQueryBooleanPrimary, SQLContainsExpr, SQLEndsWithExpr, SQLExpression, SQLExpressionList, SQLExpressionOperand, SQLFunctionCall, SQLIdentifier, SQLIdentifierExpr, SQLInExpressionListPredicate, SQLInSubQueryPredicate, SQLIsExpression, SQLIsNullBooleanPrimary, SQLLikePredicate, SQLLiteralValue, SQLNotExpression, SQLNumberValue, SQLOrExpression, SQLPlaceHolder, SQLPredicate, SQLPrefix, SQLRegexpPredicate, SQLSignedNumberValue, SQLSimpleExprParentheses, SQLSimpleExpression, SQLSoundsLikePredicate, SQLStartsWithExpr, SQLStringValue, SQLSubQuery, SQLWhereObject, SQLWhereObjectAny, SQLXorExpression, XorOperator, evalSQLLiteralValue, getFieldName, isSQLBitExpression, isSQLExpressionOperand, isSQLFunctionCall, isSQLIdentifier, isSQLLiteralOrSignedNumberValue, isSQLLiteralValue, isSQLPlaceHolder, isSQLSignedNumber, normalizeOperator, parseSQL };
 //# sourceMappingURL=parseSQL.d.ts.map