search-input-query-parser 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,137 @@
+# Search Input Query
+
+## Parser
+
+### Installation
+
+```typescript
+npm install search-input-query-parser
+```
+
+### Basic Usage
+
+```typescript
+import {
+  parseSearchInputQuery,
+  type FieldSchema
+} from 'search-input-query-parser';
+
+// Define your field schemas
+const schemas: FieldSchema[] = [
+  { name: 'title', type: 'string' },
+  { name: 'price', type: 'number' },
+  { name: 'date', type: 'date' }
+];
+
+// Parse a search query
+const query = 'title:"winter boots" AND price:>100';
+const result = parseSearchInputQuery(query, schemas);
+
+if (result.type === 'SEARCH_QUERY') {
+  // Handle successful parse where the expression is in AST format
+  console.log(result.expression);
+} else {
+  // Handle validation errors
+  console.log(result.errors);
+}
+```
+## SQL Conversion
+
+The parser can convert search queries into SQL WHERE clauses using three different search strategies:
+
+1. ILIKE - Case-insensitive pattern matching
+2. tsvector - PostgreSQL full-text search
+3. ParadeDB - BM25-based full-text search
+
+### Basic Usage
+
+```typescript
+import {
+  searchStringToIlikeSql,
+  searchStringToTsVectorSql,
+  searchStringToParadeDBSql,
+  type FieldSchema
+} from 'search-input-query-parser';
+
+// Define searchable columns and schemas
+const searchableColumns = ['title', 'description'];
+const schemas: FieldSchema[] = [
+  { name: 'title', type: 'string' },
+  { name: 'price', type: 'number' },
+  { name: 'date', type: 'date' }
+];
+
+// Convert a search query to SQL
+const query = 'winter boots AND price:>100';
+
+// Using ILIKE (case-insensitive pattern matching)
+const ilikeResult = searchStringToIlikeSql(query, searchableColumns, schemas);
+// Result:
+// {
+//   text: "((lower(title) LIKE lower($1) OR lower(description) LIKE lower($1)) AND price > $2)",
+//   values: ["%winter boots%", 100]
+// }
+
+// Using tsvector (PostgreSQL full-text search)
+const tsvectorResult = searchStringToTsVectorSql(query, searchableColumns, schemas);
+// Result:
+// {
+//   text: "((to_tsvector('english', title) || to_tsvector('english', description)) @@ plainto_tsquery('english', $1) AND price > $2)",
+//   values: ["winter boots", 100]
+// }
+
+// Using ParadeDB (BM25 search)
+const paradedbResult = searchStringToParadeDBSql(query, searchableColumns, schemas);
+// Result:
+// {
+//   text: "((title @@@ $1 OR description @@@ $1) AND price @@@ '>' || $2)",
+//   values: ['"winter boots"', 100]
+// }
+```
+
+### Search Types Comparison
+
+| Feature | ILIKE | tsvector | ParadeDB |
+|---------|-------|----------|----------|
+| Case Sensitivity | Case-insensitive | Case-insensitive | Case-sensitive |
+| Pattern Matching | Simple wildcards | Language-aware tokens | BM25 ranking |
+| Performance | Slower on large datasets | Fast with proper indexes | Fast with proper indexes |
+| Setup Required | None | PostgreSQL extension | ParadeDB extension |
+| Best For | Simple searches, small datasets | Advanced text search | Relevance-based search |
+
+### Configuration Options
+
+```typescript
+// Common options for all search types
+interface SearchQueryOptions {
+  language?: string;  // Language for text analysis (default: 'english')
+}
+
+// Example with options
+const result = searchStringToTsVectorSql(
+  query,
+  searchableColumns,
+  schemas,
+  {
+    language: 'spanish'
+  }
+);
+```
+
+### Using with Raw SQL
+
+The converters return objects with `text` (the WHERE clause) and `values` (the parameter values):
+
+```typescript
+import { searchStringToIlikeSql } from 'search-input-query-parser';
+
+const base = 'SELECT * FROM products';
+const { text, values } = searchStringToIlikeSql(query, searchableColumns, schemas);
+const fullQuery = `${base} WHERE ${text}`;
+
+// Using with node-postgres
+const result = await client.query(fullQuery, values);
+
+// Using with Prisma
+const result = await prisma.$queryRaw`${Prisma.raw(base)} WHERE ${Prisma.raw(text)}`;
+```

package/dist/cjs/search-query-to-ilike-sql.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchStringToIlikeSql = exports.searchQueryToIlikeSql = void 0;
+const parser_1 = require("./parser");
+// Constants
+const SPECIAL_CHARS = ["%", "_"];
+const ESCAPE_CHAR = "\\";
+// Helper Functions
+const escapeRegExp = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const escapeSpecialChars = (value) => SPECIAL_CHARS.reduce((escaped, char) => escaped.replace(new RegExp(escapeRegExp(char), "g"), ESCAPE_CHAR + char), value);
+const stripQuotes = (value) => {
+    if (value.startsWith('"') && value.endsWith('"')) {
+        return value.slice(1, -1);
+    }
+    return value;
+};
+const cleanQuotedString = (value, stripOuterQuotes = true) => {
+    // First strip the outer quotes if requested
+    let cleaned = stripOuterQuotes ? stripQuotes(value) : value;
+    // Replace escaped quotes with regular quotes
+    cleaned = cleaned.replace(/\\"/g, '"');
+    // Clean up any remaining escape characters
+    cleaned = cleaned.replace(/\\\\/g, "\\");
+    return cleaned;
+};
+// Create a new parameter placeholder and update state
+const nextParam = (state) => {
+    const paramName = `$${state.paramCounter}`;
+    const newState = {
+        ...state,
+        paramCounter: state.paramCounter + 1,
+    };
+    return [paramName, newState];
+};
+// Add a value to the state and return updated state
+const addValue = (state, value) => ({
+    ...state,
+    values: [...state.values, value],
+});
+/**
+ * Convert a wildcard pattern to SQL
+ */
+const wildcardPatternToSql = (expr, state) => {
+    if (expr.prefix === "") {
+        return ["1=1", state];
+    }
+    const [paramName, newState] = nextParam(state);
+    const cleanedPrefix = cleanQuotedString(expr.prefix);
+    const escapedPrefix = escapeSpecialChars(cleanedPrefix);
+    const conditions = state.searchableColumns.map((column) => `lower(${column}) LIKE lower(${paramName})`);
+    const sql = conditions.length === 1
+        ? conditions[0]
+        : `(${conditions.join(" OR ")})`;
+    return [sql, addValue(newState, `${escapedPrefix}%`)];
+};
+/**
+ * Convert a search term to SQL conditions based on search type
+ */
+const searchTermToSql = (value, state) => {
+    const [paramName, newState] = nextParam(state);
+    const hasWildcard = value.endsWith("*");
+    const cleanedValue = cleanQuotedString(value);
+    const baseValue = hasWildcard ? cleanedValue.slice(0, -1) : cleanedValue;
+    // Use lower() for case-insensitive search in SQLite
+    const escapedTerm = escapeSpecialChars(baseValue);
+    const conditions = state.searchableColumns.map((column) => `lower(${column}) LIKE lower(${paramName})`);
+    const sql = conditions.length === 1
+        ? conditions[0]
+        : `(${conditions.join(" OR ")})`;
+    if (hasWildcard) {
+        return [sql, addValue(newState, `${escapedTerm}%`)];
+    }
+    else {
+        return [sql, addValue(newState, `%${escapedTerm}%`)];
+    }
+};
+/**
+ * Convert a field:value pair to SQL based on search type
+ */
+const fieldValueToSql = (field, value, state) => {
+    const [paramName, newState] = nextParam(state);
+    const schema = state.schemas.get(field.toLowerCase());
+    const hasWildcard = value.endsWith("*");
+    const cleanedValue = cleanQuotedString(value);
+    const baseValue = hasWildcard ? cleanedValue.slice(0, -1) : cleanedValue;
+    // Rest of the function remains the same...
+    switch (schema === null || schema === void 0 ? void 0 : schema.type) {
+        case "date":
+            return [
+                `${field} = ${paramName}`,
+                addValue(newState, cleanedValue),
+            ];
+        case "number":
+            return [
+                `${field} = ${paramName}`,
+                addValue(newState, Number(cleanedValue)),
+            ];
+        default:
+            const escapedValue = escapeSpecialChars(baseValue);
+            return [
+                `lower(${field}) LIKE lower(${paramName})`,
+                addValue(newState, hasWildcard ? `${escapedValue}%` : `%${escapedValue}%`),
+            ];
+    }
+};
+/**
+ * Convert a range expression to SQL
+ */
+const rangeToSql = (field, operator, value, value2, state) => {
+    const schema = state.schemas.get(field.toLowerCase());
+    const isDateField = (schema === null || schema === void 0 ? void 0 : schema.type) === "date";
+    if (operator === "BETWEEN" && value2) {
+        const [param1, state1] = nextParam(state);
+        const [param2, state2] = nextParam(state1);
+        let val1 = isDateField ? value : Number(value);
+        let val2 = isDateField ? value2 : Number(value2);
+        return [
+            `${field} BETWEEN ${param1} AND ${param2}`,
+            addValue(addValue(state2, val1), val2),
+        ];
+    }
+    const [paramName, newState] = nextParam(state);
+    const val = isDateField ? value : Number(value);
+    return [
+        `${field} ${operator} ${paramName}`,
+        addValue(newState, val),
+    ];
+};
+const inExpressionToSql = (field, values, state) => {
+    let currentState = state;
+    const cleanedValues = values.map((v) => cleanQuotedString(v));
+    const paramNames = [];
+    const schema = state.schemas.get(field.toLowerCase());
+    for (const value of cleanedValues) {
+        const [paramName, newState] = nextParam(currentState);
+        paramNames.push(paramName);
+        currentState = addValue(newState, (schema === null || schema === void 0 ? void 0 : schema.type) === "number" ? Number(value) : value);
+    }
+    return [
+        `${field} IN (${paramNames
+            .map((p) => p)
+            .join(", ")})`,
+        currentState,
+    ];
+};
+/**
+ * Convert a binary operation (AND/OR) to SQL
+ */
+const binaryOpToSql = (operator, left, right, state) => {
+    const [leftText, leftState] = expressionToSql(left, state);
+    const [rightText, rightState] = expressionToSql(right, leftState);
+    return [`(${leftText} ${operator} ${rightText})`, rightState];
+};
+/**
+ * Convert a single expression to SQL
+ */
+const expressionToSql = (expr, state) => {
+    var _a;
+    switch (expr.type) {
+        case "SEARCH_TERM":
+            return searchTermToSql(expr.value, state);
+        case "WILDCARD":
+            return wildcardPatternToSql(expr, state);
+        case "IN":
+            return inExpressionToSql(expr.field.value, expr.values.map((v) => v.value), state);
+        case "FIELD_VALUE":
+            return fieldValueToSql(expr.field.value, expr.value.value, state);
+        case "RANGE":
+            return rangeToSql(expr.field.value, expr.operator, expr.value.value, (_a = expr.value2) === null || _a === void 0 ? void 0 : _a.value, state);
+        case "AND":
+            return binaryOpToSql("AND", expr.left, expr.right, state);
+        case "OR":
+            return binaryOpToSql("OR", expr.left, expr.right, state);
+        case "NOT": {
+            const [sqlText, newState] = expressionToSql(expr.expression, state);
+            return [`NOT ${sqlText}`, newState];
+        }
+    }
+};
+/**
+ * Convert a SearchQuery to a SQL WHERE clause with specified search type
+ */
+const searchQueryToIlikeSql = (query, searchableColumns, schemas = [], options = {}) => {
+    const initialState = {
+        paramCounter: 1,
+        values: [],
+        searchableColumns,
+        schemas: new Map(schemas.map((s) => [s.name.toLowerCase(), s])),
+        language: options.language,
+    };
+    if (!query.expression) {
+        return { text: "1=1", values: [] };
+    }
+    const [text, finalState] = expressionToSql(query.expression, initialState);
+    return { text, values: finalState.values };
+};
+exports.searchQueryToIlikeSql = searchQueryToIlikeSql;
+/**
+ * Convert a search string directly to SQL
+ */
+const searchStringToIlikeSql = (searchString, searchableColumns, schemas = [], options = {}) => {
+    const query = (0, parser_1.parseSearchInputQuery)(searchString, schemas);
+    if (query.type === "SEARCH_QUERY_ERROR") {
+        throw new Error(`Parse error: ${query.errors[0].message}`);
+    }
+    return (0, exports.searchQueryToIlikeSql)(query, searchableColumns, schemas, options);
+};
+exports.searchStringToIlikeSql = searchStringToIlikeSql;

package/dist/cjs/search-query-to-paradedb-sql.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchStringToParadeDbSql = exports.searchQueryToParadeDbSql = void 0;
+const parser_1 = require("./parser");
+// Helper Functions
+const escapeRegExp = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// Helper to escape special characters for ParadeDB query syntax
+const escapeParadeDBChars = (value) => {
+    const specialChars = [
+        "+",
+        "^",
+        "`",
+        ":",
+        "{",
+        "}",
+        '"',
+        "[",
+        "]",
+        "(",
+        ")",
+        "<",
+        ">",
+        "~",
+        "!",
+        "\\",
+        "*",
+    ];
+    return specialChars.reduce((escaped, char) => escaped.replace(new RegExp(escapeRegExp(char), "g"), `\\${char}`), value);
+};
+const stripQuotes = (value) => {
+    if (value.startsWith('"') && value.endsWith('"')) {
+        return value.slice(1, -1);
+    }
+    return value;
+};
+const cleanQuotedString = (value, stripOuterQuotes = true) => {
+    // First strip the outer quotes if requested
+    let cleaned = stripOuterQuotes ? stripQuotes(value) : value;
+    // Replace escaped quotes with regular quotes
+    cleaned = cleaned.replace(/\\"/g, '"');
+    // Clean up any remaining escape characters
+    cleaned = cleaned.replace(/\\\\/g, "\\");
+    return cleaned;
+};
+const prepareParadeDBString = (value, includeWildcard = false) => {
+    // First clean up the string
+    const cleaned = cleanQuotedString(value);
+    // For ParadeDB, we need to:
+    // 1. Escape special characters (except wildcards)
+    // 2. Wrap in quotes
+    // 3. Add wildcard if needed
+    const escaped = escapeParadeDBChars(cleaned);
+    const result = `"${escaped}"`;
+    return includeWildcard ? `${result}*` : result;
+};
+// Create a new parameter placeholder and update state
+const nextParam = (state) => {
+    const paramName = `$${state.paramCounter}`;
+    const newState = {
+        ...state,
+        paramCounter: state.paramCounter + 1,
+    };
+    return [paramName, newState];
+};
+// Add a value to the state and return updated state
+const addValue = (state, value) => ({
+    ...state,
+    values: [...state.values, value],
+});
+/**
+ * Convert a wildcard pattern to SQL
+ */
+const wildcardPatternToSql = (expr, state) => {
+    if (expr.prefix === "") {
+        return ["1=1", state];
+    }
+    const [paramName, newState] = nextParam(state);
+    const cleanedPrefix = cleanQuotedString(expr.prefix);
+    const queryValue = prepareParadeDBString(cleanedPrefix, true);
+    const conditions = state.searchableColumns.map((column) => `${column} @@@ ${paramName}`);
+    const sql = conditions.length === 1
+        ? conditions[0]
+        : `(${conditions.join(" OR ")})`;
+    return [sql, addValue(newState, queryValue)];
+};
+/**
+ * Convert a search term to SQL conditions based on search type
+ */
+const searchTermToSql = (value, state) => {
+    const [paramName, newState] = nextParam(state);
+    const hasWildcard = value.endsWith("*");
+    const cleanedValue = cleanQuotedString(value);
+    const baseValue = hasWildcard ? cleanedValue.slice(0, -1) : cleanedValue;
+    const queryValue = prepareParadeDBString(baseValue, hasWildcard);
+    const conditions = state.searchableColumns.map((column) => `${column} @@@ ${paramName}`);
+    const sql = conditions.length === 1
+        ? conditions[0]
+        : `(${conditions.join(" OR ")})`;
+    return [sql, addValue(newState, queryValue)];
+};
+/**
+ * Convert a field:value pair to SQL based on search type
+ */
+const fieldValueToSql = (field, value, state) => {
+    const [paramName, newState] = nextParam(state);
+    const schema = state.schemas.get(field.toLowerCase());
+    const hasWildcard = value.endsWith("*");
+    const cleanedValue = cleanQuotedString(value);
+    const baseValue = hasWildcard ? cleanedValue.slice(0, -1) : cleanedValue;
+    switch (schema === null || schema === void 0 ? void 0 : schema.type) {
+        case "date": {
+            // Use parameter binding for dates
+            const [dateParam, dateState] = nextParam(state);
+            return [
+                `${field} @@@ '"' || ${dateParam} || '"'`,
+                addValue(dateState, baseValue),
+            ];
+        }
+        case "number":
+            return [`${field} @@@ '${baseValue}'`, newState];
+        default: {
+            const queryValue = prepareParadeDBString(baseValue, hasWildcard);
+            return [`${field} @@@ ${paramName}`, addValue(newState, queryValue)];
+        }
+    }
+};
+/**
+ * Convert a range expression to SQL
+ */
+const rangeToSql = (field, operator, value, value2, state) => {
+    const schema = state.schemas.get(field.toLowerCase());
+    const isDateField = (schema === null || schema === void 0 ? void 0 : schema.type) === "date";
+    if (operator === "BETWEEN" && value2) {
+        const [param1, state1] = nextParam(state);
+        const [param2, state2] = nextParam(state1);
+        let val1 = isDateField ? value : Number(value);
+        let val2 = isDateField ? value2 : Number(value2);
+        return [
+            `${field} @@@ '[' || ${param1} || ' TO ' || ${param2} || ']'`,
+            addValue(addValue(state2, val1), val2),
+        ];
+    }
+    else {
+        const [paramName, newState] = nextParam(state);
+        const rangeOp = operator.replace(">=", ">=").replace("<=", "<=");
+        const val = isDateField ? value : Number(value);
+        return [
+            `${field} @@@ '${rangeOp}' || ${paramName}`,
+            addValue(newState, val),
+        ];
+    }
+};
+const inExpressionToSql = (field, values, state) => {
+    let currentState = state;
+    const cleanedValues = values.map((v) => cleanQuotedString(v));
+    const paramNames = [];
+    for (const value of cleanedValues) {
+        const [paramName, newState] = nextParam(currentState);
+        paramNames.push(paramName);
+        currentState = addValue(newState, value);
+    }
+    const concatExpr = paramNames.join(" || ' ' || ");
+    return [`${field} @@@ 'IN[' || ${concatExpr} || ']'`, currentState];
+};
+/**
+ * Convert a binary operation (AND/OR) to SQL
+ */
+const binaryOpToSql = (operator, left, right, state) => {
+    const [leftText, leftState] = expressionToSql(left, state);
+    const [rightText, rightState] = expressionToSql(right, leftState);
+    return [`(${leftText} ${operator} ${rightText})`, rightState];
+};
+/**
+ * Convert a single expression to SQL
+ */
+const expressionToSql = (expr, state) => {
+    var _a;
+    switch (expr.type) {
+        case "SEARCH_TERM":
+            return searchTermToSql(expr.value, state);
+        case "WILDCARD":
+            return wildcardPatternToSql(expr, state);
+        case "IN":
+            return inExpressionToSql(expr.field.value, expr.values.map((v) => v.value), state);
+        case "FIELD_VALUE":
+            return fieldValueToSql(expr.field.value, expr.value.value, state);
+        case "RANGE":
+            return rangeToSql(expr.field.value, expr.operator, expr.value.value, (_a = expr.value2) === null || _a === void 0 ? void 0 : _a.value, state);
+        case "AND":
+            return binaryOpToSql("AND", expr.left, expr.right, state);
+        case "OR":
+            return binaryOpToSql("OR", expr.left, expr.right, state);
+        case "NOT": {
+            const [sqlText, newState] = expressionToSql(expr.expression, state);
+            return [`NOT ${sqlText}`, newState];
+        }
+    }
+};
+/**
+ * Convert a SearchQuery to a SQL WHERE clause with specified search type
+ */
+const searchQueryToParadeDbSql = (query, searchableColumns, schemas = [], options = {}) => {
+    const initialState = {
+        paramCounter: 1,
+        values: [],
+        searchableColumns,
+        schemas: new Map(schemas.map((s) => [s.name.toLowerCase(), s])),
+        language: options.language,
+    };
+    if (!query.expression) {
+        return { text: "1=1", values: [] };
+    }
+    const [text, finalState] = expressionToSql(query.expression, initialState);
+    return { text, values: finalState.values };
+};
+exports.searchQueryToParadeDbSql = searchQueryToParadeDbSql;
+/**
+ * Convert a search string directly to SQL
+ */
+const searchStringToParadeDbSql = (searchString, searchableColumns, schemas = [], options = {}) => {
+    const query = (0, parser_1.parseSearchInputQuery)(searchString, schemas);
+    if (query.type === "SEARCH_QUERY_ERROR") {
+        throw new Error(`Parse error: ${query.errors[0].message}`);
+    }
+    return (0, exports.searchQueryToParadeDbSql)(query, searchableColumns, schemas, options);
+};
+exports.searchStringToParadeDbSql = searchStringToParadeDbSql;

package/dist/cjs/search-query-to-sql.js

@@ -1,7 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.searchStringToSql = exports.searchQueryToSql = void 0;
+exports.searchStringToSql = exports.searchQueryToSql = exports.searchStringToParadeDbSql = exports.searchQueryToParadeDbSql = exports.searchStringToTsVectorSql = exports.searchQueryToTsVectorSql = exports.searchQueryToIlikeSql = exports.searchStringToIlikeSql = void 0;
 const parser_1 = require("./parser");
+var search_query_to_ilike_sql_1 = require("./search-query-to-ilike-sql");
+Object.defineProperty(exports, "searchStringToIlikeSql", { enumerable: true, get: function () { return search_query_to_ilike_sql_1.searchStringToIlikeSql; } });
+Object.defineProperty(exports, "searchQueryToIlikeSql", { enumerable: true, get: function () { return search_query_to_ilike_sql_1.searchQueryToIlikeSql; } });
+var search_query_to_tsvector_sql_1 = require("./search-query-to-tsvector-sql");
+Object.defineProperty(exports, "searchQueryToTsVectorSql", { enumerable: true, get: function () { return search_query_to_tsvector_sql_1.searchQueryToTsVectorSql; } });
+Object.defineProperty(exports, "searchStringToTsVectorSql", { enumerable: true, get: function () { return search_query_to_tsvector_sql_1.searchStringToTsVectorSql; } });
+var search_query_to_paradedb_sql_1 = require("./search-query-to-paradedb-sql");
+Object.defineProperty(exports, "searchQueryToParadeDbSql", { enumerable: true, get: function () { return search_query_to_paradedb_sql_1.searchQueryToParadeDbSql; } });
+Object.defineProperty(exports, "searchStringToParadeDbSql", { enumerable: true, get: function () { return search_query_to_paradedb_sql_1.searchStringToParadeDbSql; } });
 // Constants
 const SPECIAL_CHARS = ["%", "_"];
 const ESCAPE_CHAR = "\\";