search-input-query-parser 0.1.0

package/dist/esm/validate-expression-fields.js

@@ -0,0 +1,240 @@
+// Helper to validate numeric values
+const validateNumber = (value, position, errors) => {
+    if (value === "")
+        return false;
+    if (isNaN(Number(value))) {
+        errors.push({
+            message: "Invalid numeric value",
+            position,
+            length: value.length,
+        });
+        return false;
+    }
+    return true;
+};
+// Helper to validate range values for numeric fields
+const validateNumericRange = (start, end, basePosition, errors) => {
+    let isValid = true;
+    const startPos = basePosition;
+    const endPos = basePosition + start.length + 2; // +2 for the '..'
+    if (start && !validateNumber(start, startPos, errors)) {
+        isValid = false;
+    }
+    if (end && !validateNumber(end, endPos, errors)) {
+        isValid = false;
+    }
+    if (isValid && start && end) {
+        const startNum = Number(start);
+        const endNum = Number(end);
+        if (startNum > endNum) {
+            errors.push({
+                message: "Range start must be less than or equal to range end",
+                position: basePosition,
+                length: start.length + 2 + end.length,
+            });
+            isValid = false;
+        }
+    }
+    return isValid;
+};
+// Helper to validate numeric comparison operators
+const validateNumericComparison = (operator, value, basePosition, errors) => {
+    const valuePosition = basePosition + operator.length;
+    return validateNumber(value, valuePosition, errors);
+};
+// Field validation helpers
+const validateFieldValue = (expr, allowedFields, errors, schemas) => {
+    switch (expr.type) {
+        case "IN": {
+            if (!allowedFields.has(expr.field.toLowerCase())) {
+                errors.push({
+                    message: `Invalid field: "${expr.field}"`,
+                    position: expr.position,
+                    length: expr.field.length,
+                });
+            }
+            // Get schema for type validation
+            const schema = schemas.get(expr.field.toLowerCase());
+            if (schema) {
+                expr.values.forEach((value, index) => {
+                    switch (schema.type) {
+                        case "number":
+                            if (isNaN(Number(value))) {
+                                errors.push({
+                                    message: "Invalid numeric value",
+                                    position: expr.position +
+                                        expr.field.length +
+                                        4 +
+                                        index * (value.length + 1),
+                                    length: value.length,
+                                });
+                            }
+                            break;
+                        case "date":
+                            if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+                                errors.push({
+                                    message: "Invalid date format",
+                                    position: expr.position +
+                                        expr.field.length +
+                                        3 +
+                                        index * (value.length + 1),
+                                    length: value.length,
+                                });
+                            }
+                            break;
+                    }
+                });
+            }
+            break;
+        }
+        case "WILDCARD": {
+            // For wildcard patterns, validate against field type constraints
+            const schema = schemas.get(expr.prefix.toLowerCase());
+            if ((schema === null || schema === void 0 ? void 0 : schema.type) === "number" || (schema === null || schema === void 0 ? void 0 : schema.type) === "date") {
+                errors.push({
+                    message: `Wildcards are not allowed for ${schema.type} fields`,
+                    position: expr.position,
+                    length: expr.length,
+                });
+            }
+            break;
+        }
+        case "STRING": {
+            const colonIndex = expr.value.indexOf(":");
+            if (colonIndex === -1)
+                return;
+            const fieldName = expr.value.substring(0, colonIndex).trim();
+            const value = expr.value.substring(colonIndex + 1).trim();
+            if (!allowedFields.has(fieldName.toLowerCase()) && colonIndex > 0) {
+                errors.push({
+                    message: `Invalid field: "${fieldName}"`,
+                    position: expr.position,
+                    length: colonIndex,
+                });
+            }
+            if (!value) {
+                errors.push({
+                    message: "Expected field value",
+                    position: expr.position,
+                    length: colonIndex + 1,
+                });
+                return;
+            }
+            if (value.startsWith(":")) {
+                errors.push({
+                    message: "Missing field name",
+                    position: expr.position,
+                    length: value.length + colonIndex + 1,
+                });
+                return;
+            }
+            const schema = schemas.get(fieldName.toLowerCase());
+            if (!schema)
+                return;
+            const valueStartPosition = expr.position + colonIndex + 1;
+            if (schema.type === "number") {
+                if (value.includes("..")) {
+                    if (value === ".." || value.includes("...")) {
+                        errors.push({
+                            message: "Invalid range format",
+                            position: valueStartPosition,
+                            length: value.length,
+                        });
+                        return;
+                    }
+                    const [start, end] = value.split("..");
+                    validateNumericRange(start, end, valueStartPosition, errors);
+                    return;
+                }
+                const comparisonMatch = value.match(/^(>=|>|<=|<)(.*)$/);
+                if (comparisonMatch) {
+                    const [, operator, compValue] = comparisonMatch;
+                    const invalidOp = /^[<>]{2,}|>=>/;
+                    if (invalidOp.test(value)) {
+                        errors.push({
+                            message: "Invalid range operator",
+                            position: valueStartPosition,
+                            length: 3,
+                        });
+                        return;
+                    }
+                    if (!compValue) {
+                        errors.push({
+                            message: "Expected range value",
+                            position: valueStartPosition + operator.length,
+                            length: 0,
+                        });
+                        return;
+                    }
+                    validateNumericComparison(operator, compValue, valueStartPosition, errors);
+                    return;
+                }
+                validateNumber(value, valueStartPosition, errors);
+                return;
+            }
+            if (schema.type === "date") {
+                const dateValidator = (dateStr) => {
+                    if (!dateStr)
+                        return true;
+                    if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
+                        return false;
+                    }
+                    const date = new Date(dateStr);
+                    return (!isNaN(date.getTime()) &&
+                        dateStr === date.toISOString().split("T")[0]);
+                };
+                if (value.includes("..")) {
+                    const [start, end] = value.split("..");
+                    if (!dateValidator(start) || !dateValidator(end)) {
+                        errors.push({
+                            message: "Invalid date format",
+                            position: valueStartPosition,
+                            length: value.length,
+                        });
+                        return;
+                    }
+                }
+                else {
+                    const comparisonMatch = value.match(/^(>=|>|<=|<)(.*)$/);
+                    if (comparisonMatch) {
+                        const [, , dateStr] = comparisonMatch;
+                        if (!dateValidator(dateStr)) {
+                            errors.push({
+                                message: "Invalid date format",
+                                position: valueStartPosition,
+                                length: value.length,
+                            });
+                            return;
+                        }
+                    }
+                    else if (!dateValidator(value)) {
+                        errors.push({
+                            message: "Invalid date format",
+                            position: valueStartPosition,
+                            length: value.length,
+                        });
+                        return;
+                    }
+                }
+            }
+            break;
+        }
+    }
+};
+export const validateExpressionFields = (expr, allowedFields, errors, schemas) => {
+    switch (expr.type) {
+        case "STRING":
+        case "WILDCARD":
+        case "IN":
+            validateFieldValue(expr, allowedFields, errors, schemas);
+            break;
+        case "AND":
+        case "OR":
+            validateExpressionFields(expr.left, allowedFields, errors, schemas);
+            validateExpressionFields(expr.right, allowedFields, errors, schemas);
+            break;
+        case "NOT":
+            validateExpressionFields(expr.expression, allowedFields, errors, schemas);
+            break;
+    }
+};

package/dist/esm/validate-in-expression.js

@@ -0,0 +1,29 @@
+import { reservedWords } from "./validator";
+export const validateInExpression = (expr, errors) => {
+    // Validate field name pattern
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(expr.field)) {
+        errors.push({
+            message: "Invalid characters in field name",
+            position: expr.position,
+            length: expr.field.length,
+        });
+    }
+    // Check for reserved words
+    if (reservedWords.has(expr.field.toUpperCase())) {
+        errors.push({
+            message: `${expr.field} is a reserved word`,
+            position: expr.position,
+            length: expr.field.length,
+        });
+    }
+    // Validate value format based on field type
+    expr.values.forEach((value, index) => {
+        if (value.includes(",")) {
+            errors.push({
+                message: "Invalid character in IN value",
+                position: expr.position + expr.field.length + 3 + index * (value.length + 1),
+                length: value.length,
+            });
+        }
+    });
+};

package/dist/esm/validate-string.js

@@ -0,0 +1,61 @@
+import { reservedWords } from "./validator";
+import { validateWildcard } from "./validate-wildcard";
+// Validate individual strings (field:value pairs or plain terms)
+export const validateString = (expr, errors) => {
+    // Validate wildcard usage
+    validateWildcard(expr, errors);
+    // For wildcard patterns, no additional validation needed
+    if (expr.type === "WILDCARD") {
+        return;
+    }
+    // Handle STRING type
+    // Check for empty field values
+    if (expr.value.endsWith(":")) {
+        errors.push({
+            message: "Expected field value",
+            position: expr.position,
+            length: expr.length,
+        });
+        return;
+    }
+    // Check for field values that start with colon
+    if (expr.value.startsWith(":")) {
+        errors.push({
+            message: "Missing field name",
+            position: expr.position,
+            length: expr.length,
+        });
+        return;
+    }
+    // For field:value patterns, validate the field name
+    if (expr.value.includes(":")) {
+        const [fieldName] = expr.value.split(":");
+        // Check for reserved words used as field names
+        if (reservedWords.has(fieldName.toUpperCase())) {
+            errors.push({
+                message: `${fieldName} is a reserved word`,
+                position: expr.position,
+                length: fieldName.length,
+            });
+            return;
+        }
+        // Check for invalid characters in field names
+        if (!/^[a-zA-Z0-9_-]+$/.test(fieldName)) {
+            errors.push({
+                message: "Invalid characters in field name",
+                position: expr.position,
+                length: fieldName.length,
+            });
+            return;
+        }
+    }
+    // Handle standalone reserved words (not in field:value pattern)
+    if (!expr.value.includes(":") &&
+        reservedWords.has(expr.value.toUpperCase())) {
+        errors.push({
+            message: `${expr.value} is a reserved word`,
+            position: expr.position,
+            length: expr.length,
+        });
+    }
+};

package/dist/esm/validate-wildcard.js

@@ -0,0 +1,36 @@
+// Validates wildcard patterns
+export const validateWildcard = (expr, errors) => {
+    const value = expr.type === "STRING" ? expr.value : expr.prefix + "*";
+    const starCount = (value.match(/\*/g) || []).length;
+    const isQuoted = expr.quoted;
+    // For unquoted strings
+    if (!isQuoted) {
+        const firstStar = value.indexOf("*");
+        if (starCount > 1) {
+            const secondStar = value.indexOf("*", firstStar + 1);
+            errors.push({
+                message: "Only one trailing wildcard (*) is allowed",
+                position: expr.position + secondStar,
+                length: 1,
+            });
+        }
+        if ((firstStar !== -1 && firstStar !== value.length - 1) && !value.endsWith("**")) {
+            errors.push({
+                message: "Wildcard (*) can only appear at the end of a term",
+                position: expr.position + firstStar,
+                length: 1,
+            });
+        }
+    }
+    // For quoted strings
+    else {
+        // Handle multiple wildcards or internal wildcards in quoted strings
+        if (value.endsWith("**")) {
+            errors.push({
+                message: "Only one trailing wildcard (*) is allowed",
+                position: expr.position + value.length - 1,
+                length: 1,
+            });
+        }
+    }
+};

package/dist/esm/validator.js

@@ -0,0 +1,30 @@
+import { validateInExpression } from "./validate-in-expression";
+import { validateString } from "./validate-string";
+export const reservedWords = new Set(["AND", "OR"]);
+const walkExpression = (expr, errors) => {
+    switch (expr.type) {
+        case "STRING":
+        case "WILDCARD":
+            validateString(expr, errors);
+            break;
+        case "AND":
+        case "OR":
+            walkExpression(expr.left, errors);
+            walkExpression(expr.right, errors);
+            break;
+        case "NOT":
+            walkExpression(expr.expression, errors);
+            break;
+        case "IN":
+            validateInExpression(expr, errors);
+            break;
+    }
+};
+export const validateSearchQuery = (expression) => {
+    const errors = [];
+    if (expression === null) {
+        return errors;
+    }
+    walkExpression(expression, errors);
+    return errors;
+};

package/dist/types/first-pass-parser.d.ts

@@ -0,0 +1,40 @@
+import { TokenStream } from "./lexer";
+export type PositionLength = {
+    position: number;
+    length: number;
+};
+export type StringLiteral = {
+    readonly type: "STRING";
+    readonly value: string;
+    readonly quoted: boolean;
+} & PositionLength;
+export type WildcardPattern = {
+    readonly type: "WILDCARD";
+    readonly prefix: string;
+    readonly quoted: boolean;
+} & PositionLength;
+export type AndExpression = {
+    readonly type: "AND";
+    readonly left: FirstPassExpression;
+    readonly right: FirstPassExpression;
+} & PositionLength;
+export type OrExpression = {
+    readonly type: "OR";
+    readonly left: FirstPassExpression;
+    readonly right: FirstPassExpression;
+} & PositionLength;
+export type NotExpression = {
+    readonly type: "NOT";
+    readonly expression: FirstPassExpression;
+} & PositionLength;
+export type InExpression = {
+    readonly type: "IN";
+    readonly field: string;
+    readonly values: string[];
+} & PositionLength;
+export type FirstPassExpression = StringLiteral | WildcardPattern | AndExpression | OrExpression | NotExpression | InExpression;
+export interface ParseResult<T> {
+    readonly result: T;
+    readonly stream: TokenStream;
+}
+export declare const parseExpression: (stream: TokenStream, minPrecedence?: number) => ParseResult<FirstPassExpression>;

package/dist/types/lexer.d.ts

@@ -0,0 +1,27 @@
+export declare enum TokenType {
+    STRING = "STRING",
+    QUOTED_STRING = "QUOTED_STRING",
+    LPAREN = "LPAREN",
+    RPAREN = "RPAREN",
+    AND = "AND",
+    OR = "OR",
+    NOT = "NOT",
+    EOF = "EOF",
+    IN = "IN",
+    COMMA = "COMMA",
+    NUMBER = "NUMBER"
+}
+export interface Token {
+    type: TokenType;
+    value: string;
+    position: number;
+    length: number;
+}
+export interface TokenStream {
+    readonly tokens: Token[];
+    readonly position: number;
+}
+export declare const createStream: (tokens: Token[]) => TokenStream;
+export declare const currentToken: (stream: TokenStream) => Token;
+export declare const advanceStream: (stream: TokenStream) => TokenStream;
+export declare const tokenize: (input: string) => Token[];

package/dist/types/parse-in-values.d.ts

@@ -0,0 +1,3 @@
+import { ParseResult } from "./first-pass-parser";
+import { TokenStream } from "./lexer";
+export declare const parseInValues: (stream: TokenStream, inValuePosition: number) => ParseResult<string[]>;

package/dist/types/parse-primary.d.ts

@@ -0,0 +1,6 @@
+import { ParseResult, FirstPassExpression } from "./first-pass-parser";
+import { TokenStream, TokenType } from "./lexer";
+export declare const expectToken: (stream: TokenStream, type: TokenType, message?: string) => TokenStream;
+export declare const isFieldValuePattern: (value: string) => boolean;
+export declare const extractFieldValue: (value: string) => [string, string];
+export declare const parsePrimary: (stream: TokenStream) => ParseResult<FirstPassExpression>;

package/dist/types/parse-range-expression.d.ts

@@ -0,0 +1,2 @@
+import { FieldSchema, RangeExpression, FieldValue } from "./parser";
+export declare const parseRangeExpression: (fieldName: string, value: string, schema: FieldSchema | undefined, position: number, colonIndex: number) => RangeExpression | FieldValue;

package/dist/types/parser.d.ts

@@ -0,0 +1,68 @@
+import { PositionLength } from "./first-pass-parser";
+import { ValidationError } from "./validator";
+interface FieldSchema {
+    name: string;
+    type: "string" | "number" | "date" | "boolean";
+}
+type SearchTerm = {
+    readonly type: "SEARCH_TERM";
+    readonly value: string;
+} & PositionLength;
+type WildcardPattern = {
+    readonly type: "WILDCARD";
+    readonly prefix: string;
+    readonly quoted: boolean;
+} & PositionLength;
+type Field = {
+    readonly type: "FIELD";
+    readonly value: string;
+} & PositionLength;
+type Value = {
+    readonly type: "VALUE";
+    readonly value: string;
+} & PositionLength;
+type RangeOperator = ">=" | ">" | "<=" | "<" | "BETWEEN";
+type RangeExpression = {
+    readonly type: "RANGE";
+    readonly field: Field;
+    readonly operator: RangeOperator;
+    readonly value: Value;
+    readonly value2?: Value;
+} & PositionLength;
+export type FieldValue = {
+    readonly type: "FIELD_VALUE";
+    readonly field: Field;
+    readonly value: Value;
+};
+type And = {
+    readonly type: "AND";
+    readonly left: Expression;
+    readonly right: Expression;
+} & PositionLength;
+type Or = {
+    readonly type: "OR";
+    readonly left: Expression;
+    readonly right: Expression;
+} & PositionLength;
+type Not = {
+    readonly type: "NOT";
+    readonly expression: Expression;
+} & PositionLength;
+type InExpression = {
+    readonly type: "IN";
+    readonly field: Field;
+    readonly values: Value[];
+} & PositionLength;
+type Expression = SearchTerm | WildcardPattern | FieldValue | RangeExpression | And | Or | Not | InExpression;
+type SearchQuery = {
+    readonly type: "SEARCH_QUERY";
+    readonly expression: Expression | null;
+};
+type SearchQueryError = {
+    readonly type: "SEARCH_QUERY_ERROR";
+    readonly expression: null;
+    readonly errors: ValidationError[];
+};
+declare const stringify: (expr: Expression) => string;
+export declare const parseSearchInputQuery: (input: string, fieldSchemas?: FieldSchema[]) => SearchQuery | SearchQueryError;
+export { type SearchQuery, type SearchQueryError, type Expression, type ValidationError, type FieldSchema, type RangeOperator, type RangeExpression, type WildcardPattern, type Value, stringify, };

package/dist/types/search-query-to-sql.d.ts

@@ -0,0 +1,18 @@
+import { SearchQuery, FieldSchema } from "./parser";
+export interface SqlQueryResult {
+    text: string;
+    values: any[];
+}
+export type SearchType = "ilike" | "tsvector" | "paradedb";
+export interface SearchQueryOptions {
+    searchType?: SearchType;
+    language?: string;
+}
+/**
+ * Convert a SearchQuery to a SQL WHERE clause with specified search type
+ */
+export declare const searchQueryToSql: (query: SearchQuery, searchableColumns: string[], schemas?: FieldSchema[], options?: SearchQueryOptions) => SqlQueryResult;
+/**
+ * Convert a search string directly to SQL
+ */
+export declare const searchStringToSql: (searchString: string, searchableColumns: string[], schemas?: FieldSchema[], options?: SearchQueryOptions) => SqlQueryResult;

package/dist/types/transform-to-expression.d.ts

@@ -0,0 +1,3 @@
+import { FirstPassExpression } from "./first-pass-parser";
+import { FieldSchema, Expression } from "./parser";
+export declare const transformToExpression: (expr: FirstPassExpression, schemas: Map<string, FieldSchema>) => Expression;

package/dist/types/validate-expression-fields.d.ts

@@ -0,0 +1,4 @@
+import { FieldSchema } from "./parser";
+import { FirstPassExpression } from "./first-pass-parser";
+import { ValidationError } from "./validator";
+export declare const validateExpressionFields: (expr: FirstPassExpression, allowedFields: Set<string>, errors: ValidationError[], schemas: Map<string, FieldSchema>) => void;

package/dist/types/validate-in-expression.d.ts

@@ -0,0 +1,3 @@
+import { InExpression } from "./first-pass-parser";
+import { ValidationError } from "./validator";
+export declare const validateInExpression: (expr: InExpression, errors: ValidationError[]) => void;

package/dist/types/validate-string.d.ts

@@ -0,0 +1,3 @@
+import { StringLiteral, WildcardPattern } from "./first-pass-parser";
+import { ValidationError } from "./validator";
+export declare const validateString: (expr: StringLiteral | WildcardPattern, errors: ValidationError[]) => void;

package/dist/types/validate-wildcard.d.ts

@@ -0,0 +1,3 @@
+import { StringLiteral, WildcardPattern } from "./first-pass-parser";
+import { ValidationError } from "./validator";
+export declare const validateWildcard: (expr: StringLiteral | WildcardPattern, errors: ValidationError[]) => void;

package/dist/types/validator.d.ts

@@ -0,0 +1,8 @@
+import { FirstPassExpression } from "./first-pass-parser";
+export type ValidationError = {
+    message: string;
+    position: number;
+    length: number;
+};
+export declare const reservedWords: Set<string>;
+export declare const validateSearchQuery: (expression: FirstPassExpression) => ValidationError[];

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "search-input-query-parser",
+  "version": "0.1.0",
+  "description": "A parser for advanced search query syntax with field:value support",
+  "keywords": [
+    "search",
+    "parser",
+    "query",
+    "typescript"
+  ],
+  "author": "William Cotton",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/williamcotton/search-input-query"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/parser.d.ts",
+      "import": "./dist/esm/parser.js",
+      "require": "./dist/cjs/parser.js"
+    }
+  },
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "type-check": "tsc --noEmit",
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "prepublishOnly": "npm run build"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/*.test.ts"
+    ]
+  },
+  "license": "ISC",
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.11.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.3.3"
+  }
+}