sqlparser-devexpress 2.1.4 → 2.2.0

package/README.md

@@ -1,29 +1,142 @@
 # SQLParser
 
-SQLParser is a JavaScript library that converts SQL-like filter strings into DevExpress format filters. It provides utilities for parsing, sanitizing, and converting SQL-like expressions into a format that can be used with DevExpress components.
+SQLParser is a JavaScript library that converts SQL `WHERE` clauses into a structured **Abstract Syntax Tree (AST)** and transforms them into DevExpress filter format. It removes inline parameters while preserving them as dynamic variables for flexible query processing.
 
-## Usage
+## Features
 
-### Convert SQL to AST
+- **AST-Based Query Processing**: Parses `WHERE` clauses and generates a structured AST.
+- **Supports Dynamic Parameters**: Identifies and extracts placeholders (`{param}`) for dynamic resolution.
+- **Parameter Cleanup**: Removes inline parameters while maintaining their structure.
+- **DevExpress-Compatible Output**: Converts parsed SQL conditions into the DevExpress filter format.
+- **Short-Circuit Optimization**: By default, eliminates `value = value` expressions for DevExpress compatibility (can be disabled for performance optimization).
+- **Separation of Concerns**: Generate AST once, then use it for multiple state updates.
 
-To convert a SQL-like filter string to an Abstract Syntax Tree (AST):
+## Example Workflow
+
+### **Step 1: Input SQL**
+
+```sql
+WHERE OrderID = {CustomerOrders.OrderID} AND Status IN (1, 3)
+```
+
+### **Step 2: Generate AST**
 
 ```javascript
-const filterString= "(ID <> {Item.ID}) AND (ItemGroupType IN ({Item.AllowedItemGroupType}))";
-const parsedResult = convertSQLToAst(filterString);
+import { convertSQLToAst } from "sqlparser-devexpress";
+
+const sqlQuery = "OrderID = {CustomerOrders.OrderID} AND Status IN (1, 3)";
+const { ast, variables } = convertSQLToAst(sqlQuery, true); // Enable logs
+```
+
+#### **AST Output**
+
+```json
+{
+  "type": "logical",
+  "operator": "AND",
+  "left": {
+    "type": "comparison",
+    "field": "OrderID",
+    "operator": "=",
+    "value": {
+      "type": "placeholder",
+      "value": "CustomerOrders.OrderID"
+    }
+  },
+  "right": {
+    "type": "comparison",
+    "field": "Status",
+    "operator": "in",
+    "value": {
+      "type": "value",
+      "value": [1, 3]
+    }
+  }
+}
 ```
 
-### Convert AST to DevExpress Format
+#### Extracted Variables  
 
-To convert an AST to DevExpress format:
+The parser identifies placeholders within the SQL query and extracts them for dynamic value resolution.  
+
+#### **Example Output:**  
+```json
+[
+  "CustomerOrders.OrderID"
+]
+```  
+
+These extracted variables can be used to fetch the corresponding state values in the application. You can store them in a `Record<string, any>`, where the key is the placeholder name, and the value is the resolved data from the application's state.
+
+
+
+### **Step 3: Convert AST to DevExpress Format**
 
 ```javascript
-const ast = { /* your AST here */ };
-const variables = [/* your variables here */];
-const state = { /* your state here */ };
+import { convertAstToDevextreme } from "sqlparser-devexpress";
+
+const sampleState = {
+    "CustomerOrders.OrderID": 76548
+};
+
+const devexpressFilter = convertAstToDevextreme(ast, sampleState, true); // Short-circuit enabled (default)
 
-const devExpressFilter = convertAstToDevextreme(ast, variables, state);
+console.log("DevExpress Filter:", JSON.stringify(devexpressFilter, null, 2));
+```
+
+#### **DevExpress Filter Output**
+
+```json
+[
+  ["OrderID", "=", 76548],
+  "and",
+  [
+    ["Status", "=", 1],
+    "or",
+    ["Status", "=", 3]
+  ]
+]
+```
 
-console.log(devExpressFilter);
+## Installation
+
+```sh
+npm install sqlparser-devexpress
 ```
 
+## API Reference
+
+### `convertSQLToAst(filterString, enableConsoleLogs = false)`
+
+- **Input:** SQL `WHERE` clause as a string.
+- **Output:** An object `{ ast }` where:
+  - `ast`: The parsed Abstract Syntax Tree.
+- **Example:**
+  ```javascript
+  const { ast } = convertSQLToAst("OrderID = {CustomerOrders.OrderID} AND Status IN (1, 3)");
+  ```
+
+### `convertAstToDevextreme(ast, state, shortCircuit = true)`
+
+- **Input:**
+  - `ast`: The AST generated from `convertSQLToAst()`.
+  - `state`: An object containing values for placeholders.
+  - `shortCircuit`: (Optional, default `true`) Enables short-circuiting of `value = value` expressions for DevExpress compatibility.
+- **Output:** DevExpress filter array.
+- **Example:**
+  ```javascript
+  const devexpressFilter = convertAstToDevextreme(ast, sampleState, false); // Disables short-circuiting
+  ```
+
+## Roadmap
+
+- Support for additional SQL operators and functions.
+- Improved error handling and validation.
+
+## Contributing
+
+Contributions are welcome! Feel free to open issues or submit pull requests.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlparser-devexpress",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "main": "src/index.js",
   "type": "module",
   "scripts": {

package/src/constants.js

@@ -9,3 +9,5 @@ export const OPERATOR_PRECEDENCE = {
 
 // Regular expression to check for unsupported SQL patterns (like SELECT-FROM or JOIN statements)
 export const UNSUPPORTED_PATTERN = /\bSELECT\b.*\bFROM\b|\bINNER\s+JOIN\b/i;
+
+export const LOGICAL_OPERATORS = ['and', 'or'];

package/src/core/converter.js

@@ -1,31 +1,25 @@
-const logicalOperators = ['and', 'or'];
+import { LOGICAL_OPERATORS } from "../constants.js";
 
 /**
  * Main conversion function that sets up the global context
- * @param {Object} ast - The abstract syntax tree
- * @param {Array} vars - Array of variable names
- * @param {Object} results - Optional object for placeholder resolution
  * @returns {Array|null} DevExpress format filter
  */
 function DevExpressConverter() {
     // Global variables accessible throughout the converter
     let resultObject = null;
-    let primaryEntity = null;
-    let primaryKey = null;
-    let variables = [];
     const EnableShortCircuit = true;
 
     /**
    * Main conversion function that sets up the global context
    * @param {Object} ast - The abstract syntax tree
-   * @param {Array} vars - Array of variable names
    * @param {Object} ResultObject - Optional object for placeholder resolution
+   * @param {boolean} enableShortCircuit - Optional enabling and disabling the shortcircuit ie evaluating value = value scenario 
    * @returns {Array|null} DevExpress format filter
    */
-    function convert(ast, vars, ResultObject = null) {
+    function convert(ast, ResultObject = null, enableShortCircuit = true) {
         // Set up global context
-        variables = vars;
         resultObject = ResultObject;
+        EnableShortCircuit = enableShortCircuit;
 
         // Process the AST
         let result = processAstNode(ast);
@@ -111,8 +105,8 @@ function DevExpressConverter() {
 
         // Detect and flatten nested logical expressions
         if (parentOperator === null) {
-            if (left.length === 3 && logicalOperators.includes(left[1])) parentOperator = left[1];
-            if (right.length === 3 && logicalOperators.includes(right[1])) parentOperator = right[1];
+            if (left.length === 3 && LOGICAL_OPERATORS.includes(left[1])) parentOperator = left[1];
+            if (right.length === 3 && LOGICAL_OPERATORS.includes(right[1])) parentOperator = right[1];
         }
 
         // Flatten nested logical expressions if applicable
@@ -377,12 +371,10 @@ const devExpressConverter = DevExpressConverter();
 /**
  * Converts an abstract syntax tree to DevExpress format
  * @param {Object} ast - The abstract syntax tree
- * @param {Array} variables - Array of variable names
  * @param {Object} resultObject - Optional object for placeholder resolution
- * @param {string} primaryEntity - Optional primary entity name
- * @param {string} primaryKey - Optional primary key value
+ * @param {string} enableShortCircuit - Optional enabling and disabling the shortcircuit ie evaluating value = value scenario 
  * @returns {Array|null} DevExpress format filter
  */
-export function convertToDevExpressFormat({ ast, variables, resultObject = null }) {
-    return devExpressConverter.init(ast, variables, resultObject);
+export function convertToDevExpressFormat({ ast, resultObject = null, enableShortCircuit = true }) {
+    return devExpressConverter.init(ast, resultObject,enableShortCircuit);
 }

package/src/core/tokenizer.js

@@ -1,4 +1,4 @@
-import { LITERALS } from "../constants";
+import { LITERALS } from "../constants.js";
 
 // Define regex patterns for different token types
 const tokenPatterns = {
@@ -9,7 +9,7 @@ const tokenPatterns = {
   placeholder: "'?\\{[^}]+\\}'?", // Matches placeholders like {variable} or '{variable}'
   string: "\\('\\w+\\'\\)|'(?:''|[^'])*'", // Matches strings, allowing for escaped single quotes ('')
   operator: "=>|<=|!=|>=|=|<>|>|<|\\bAND\\b|\\bOR\\b|\\bBETWEEN\\b|\\bIN\\b|\\bNOT IN\\b|\\bLIKE\\b|\\bIS NOT\\b|\\bNOT LIKE\\b|\\bIS\\b", // Matches SQL operators and logical keywords
-  identifier: "[\\w.]+", // Matches identifiers, including table.column format
+  identifier: "[\\w.]+|\"[^\"]+\"|\\[[^\\]]+\\]", // Matches regular identifiers, quoted identifiers ("identifier"), and bracketed identifiers [identifier]
   paren: "[()]", // Matches standalone parentheses
   comma: "," // Matches commas
 };
@@ -59,8 +59,15 @@ class Tokenizer {
         }
       }
 
-      if (LITERALS.includes(type)) value = value.replace(/^[(]|[)]$/g, "")
+      if (LITERALS.includes(type)){
+        value = value.replace(/^[(]|[)]$/g, "");
+      }
 
+      if (type === "identifier") {
+        value = value.replace(/^["\[]|["\]]$/g, "");
+      }
+      
+      
       return { type, value };
     }
 

package/src/debug.js

@@ -6,17 +6,15 @@
 // import { convertToDevExpressFormat } from "./core/converter.js";
 // import { parse } from "./core/parser.js";
 // import { sanitizeQuery } from "./core/sanitizer.js";
-// import { convertAstToDevextreme, convertSQLToAst } from "./index.js";
 
 // const sampleData = {
 //     'LeadStatementGlobalRpt.StateID': null,
 //     'LeadStatementGlobalRpt.RegionID': null,
-//     'ServiceOrderDocument.SourceID': 2
+//     'ServiceOrderDocument.SourceID': 2,
+//     'CustomerOrders.OrderID': 76548
 // }
 
 // export function parseFilterString(filterString, sampleData = null) {
-//     if (filterString.toUpperCase().startsWith("SELECT")) return null; // Skip full SQL queries
-
 //     let { sanitizedSQL, extractedVariables } = sanitizeQuery(filterString);
 //     console.log("Sanitized SQL:", sanitizedSQL, "\n");
 
@@ -30,9 +28,9 @@
 //     return convertToDevExpressFormat({ ast: astTree, variables: extractedVariables, resultObject: sampleData });
 // }
 
-// // const devexpress = parseFilterString("(RS2ID in ({LeadStatementGlobalRpt.StateID}) Or ({LeadStatementGlobalRpt.StateID} =0)) And (RS3ID  in (0,{LeadStatementGlobalRpt.RegionID}) Or {LeadStatementGlobalRpt.RegionID} =0 )", sampleData);
-// const devexpress = parseFilterString("{LeadStatementGlobalRpt.RegionID} =0", sampleData);
+// const devexpress = parseFilterString("OrderID = {CustomerOrders.OrderID} AND Status IN (1, 3)", sampleData);
 // console.log("DevExpress Filter:", JSON.stringify(devexpress, null, 2));
+// // const devexpress = parseFilterString("(RS2ID in ({LeadStatementGlobalRpt.StateID}) Or ({LeadStatementGlobalRpt.StateID} =0)) And (RS3ID  in (0,{LeadStatementGlobalRpt.RegionID}) Or {LeadStatementGlobalRpt.RegionID} =0 )", sampleData);
 
 // // const devExpressFilter = convertSQLToAst("(RS2ID in ({LeadStatementGlobalRpt.StateID}) Or ({LeadStatementGlobalRpt.StateID} =0)) And (RS3ID  in (0,{LeadStatementGlobalRpt.RegionID}) Or {LeadStatementGlobalRpt.RegionID} =0 ) ");
 // // const devExpressFilterresult = convertAstToDevextreme(devExpressFilter.ast, devExpressFilter.variables, sampleData);