@gblikas/querykit 0.1.0 → 0.3.0

package/dist/parser/input-parser.js

@@ -0,0 +1,493 @@
+"use strict";
+/**
+ * Input Parser for QueryKit
+ *
+ * This module provides utilities for parsing partial/in-progress query input
+ * from search bars, enabling features like:
+ * - Key-value highlighting
+ * - Autocomplete suggestions
+ * - Real-time validation feedback
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseQueryInput = parseQueryInput;
+exports.getTermAtPosition = getTermAtPosition;
+exports.isInputComplete = isInputComplete;
+exports.extractKeyValue = extractKeyValue;
+exports.parseQueryTokens = parseQueryTokens;
+/**
+ * Regular expression patterns for parsing
+ */
+const PATTERNS = {
+    // Matches logical operators (AND, OR, NOT) with word boundaries
+    LOGICAL_OPERATOR: /\b(AND|OR|NOT)\b/gi,
+    // Matches comparison operators: :, :>, :>=, :<, :<=, :!=, :=
+    COMPARISON_OPERATOR: /^(:>=|:<=|:!=|:>|:<|:=|:)/,
+    // Matches a quoted string (single or double quotes)
+    QUOTED_STRING: /^(["'])(?:\\.|[^\\])*?\1/,
+    // Matches word characters and some special chars (for keys/values)
+    WORD_CHARS: /^[a-zA-Z0-9_.-]+/,
+    // Matches whitespace
+    WHITESPACE: /^\s+/,
+    // Matches parentheses
+    PAREN_OPEN: /^\(/,
+    PAREN_CLOSE: /^\)/,
+    // Matches negation prefix
+    NEGATION: /^-/
+};
+/**
+ * Parse a single term (key:value, key:>value, or just value)
+ */
+function parseTerm(input, startPosition) {
+    if (!input || input.length === 0) {
+        return null;
+    }
+    let key = null;
+    let operator = null;
+    let value = null;
+    let remaining = input;
+    let currentPos = 0;
+    // Handle negation prefix (e.g., -status:active)
+    let hasNegation = false;
+    const negationMatch = remaining.match(PATTERNS.NEGATION);
+    if (negationMatch) {
+        hasNegation = true;
+        remaining = remaining.substring(1);
+        currentPos += 1;
+    }
+    // Try to match a key (word before operator)
+    const keyMatch = remaining.match(PATTERNS.WORD_CHARS);
+    if (keyMatch) {
+        const potentialKey = keyMatch[0];
+        const afterKey = remaining.substring(potentialKey.length);
+        // Check if followed by an operator
+        const operatorMatch = afterKey.match(PATTERNS.COMPARISON_OPERATOR);
+        if (operatorMatch) {
+            // This is a key:value pattern
+            key = (hasNegation ? '-' : '') + potentialKey;
+            operator = operatorMatch[0];
+            currentPos += potentialKey.length + operator.length;
+            remaining = afterKey.substring(operator.length);
+            // Try to match the value
+            // First check for quoted string
+            const quotedMatch = remaining.match(PATTERNS.QUOTED_STRING);
+            if (quotedMatch) {
+                value = quotedMatch[0];
+                currentPos += value.length;
+            }
+            else {
+                // Match unquoted value (until whitespace or logical operator)
+                const valueMatch = remaining.match(/^[^\s()]+/);
+                if (valueMatch) {
+                    value = valueMatch[0];
+                    currentPos += value.length;
+                }
+                else {
+                    // Operator present but no value yet
+                    value = null;
+                }
+            }
+        }
+        else {
+            // No operator - this is a bare value (or incomplete key)
+            // Treat the whole thing as a potential key that could become key:value
+            // or as a bare value for full-text search
+            key = null;
+            operator = null;
+            value = (hasNegation ? '-' : '') + potentialKey;
+            currentPos += potentialKey.length;
+        }
+    }
+    else {
+        // Check for quoted string as bare value
+        const quotedMatch = remaining.match(PATTERNS.QUOTED_STRING);
+        if (quotedMatch) {
+            key = null;
+            operator = null;
+            value = (hasNegation ? '-' : '') + quotedMatch[0];
+            currentPos += quotedMatch[0].length;
+        }
+        else {
+            // No recognizable token
+            return null;
+        }
+    }
+    return {
+        key,
+        operator,
+        value,
+        startPosition,
+        endPosition: startPosition + currentPos,
+        raw: input.substring(0, currentPos)
+    };
+}
+/**
+ * Tokenize the input string into terms and logical operators
+ */
+function tokenize(input) {
+    const terms = [];
+    const logicalOperators = [];
+    let remaining = input;
+    let position = 0;
+    while (remaining.length > 0) {
+        // Skip whitespace
+        const wsMatch = remaining.match(PATTERNS.WHITESPACE);
+        if (wsMatch) {
+            position += wsMatch[0].length;
+            remaining = remaining.substring(wsMatch[0].length);
+            continue;
+        }
+        // Skip parentheses (they're structural, not terms)
+        if (remaining.match(PATTERNS.PAREN_OPEN)) {
+            position += 1;
+            remaining = remaining.substring(1);
+            continue;
+        }
+        if (remaining.match(PATTERNS.PAREN_CLOSE)) {
+            position += 1;
+            remaining = remaining.substring(1);
+            continue;
+        }
+        // Check for logical operators
+        const logicalMatch = remaining.match(/^(AND|OR|NOT)\b/i);
+        if (logicalMatch) {
+            logicalOperators.push({
+                operator: logicalMatch[0].toUpperCase(),
+                position
+            });
+            position += logicalMatch[0].length;
+            remaining = remaining.substring(logicalMatch[0].length);
+            continue;
+        }
+        // Try to parse a term
+        const term = parseTerm(remaining, position);
+        if (term) {
+            terms.push(term);
+            position = term.endPosition;
+            remaining = input.substring(position);
+        }
+        else {
+            // Skip unknown character
+            position += 1;
+            remaining = remaining.substring(1);
+        }
+    }
+    return { terms, logicalOperators };
+}
+/**
+ * Determine the cursor context based on position within a term
+ */
+function determineCursorContext(term, cursorPosition) {
+    const relativePos = cursorPosition - term.startPosition;
+    if (term.key !== null && term.operator !== null) {
+        // Key and operator are present
+        const keyLength = term.key.length;
+        const operatorLength = term.operator.length;
+        const keyPlusOperatorLength = keyLength + operatorLength;
+        if (relativePos < keyLength) {
+            return 'key';
+        }
+        else if (relativePos < keyPlusOperatorLength) {
+            return 'operator';
+        }
+        else {
+            // Cursor is at or after the operator - this is the value position
+            // Even if value is null (user hasn't typed anything yet),
+            // they're positioned to type a value
+            return 'value';
+        }
+    }
+    else if (term.key !== null) {
+        // Only key present (incomplete term)
+        return 'key';
+    }
+    else if (term.value !== null) {
+        // Only value present (bare value)
+        return 'value';
+    }
+    return 'empty';
+}
+/**
+ * Find the term that contains the cursor position
+ */
+function findActiveTermAndContext(terms, cursorPosition, inputLength) {
+    if (cursorPosition === null) {
+        // If no cursor position provided, use the last term
+        if (terms.length > 0) {
+            const lastTerm = terms[terms.length - 1];
+            return {
+                activeTerm: lastTerm,
+                cursorContext: determineCursorContext(lastTerm, lastTerm.endPosition)
+            };
+        }
+        return { activeTerm: null, cursorContext: 'empty' };
+    }
+    // Find term containing cursor
+    for (const term of terms) {
+        if (cursorPosition >= term.startPosition &&
+            cursorPosition <= term.endPosition) {
+            return {
+                activeTerm: term,
+                cursorContext: determineCursorContext(term, cursorPosition)
+            };
+        }
+    }
+    // Cursor is between terms or at the end
+    if (cursorPosition >= inputLength && terms.length > 0) {
+        // Cursor at the end - check if right after a term
+        const lastTerm = terms[terms.length - 1];
+        if (cursorPosition === lastTerm.endPosition) {
+            return {
+                activeTerm: lastTerm,
+                cursorContext: determineCursorContext(lastTerm, cursorPosition)
+            };
+        }
+    }
+    return { activeTerm: null, cursorContext: 'between' };
+}
+/**
+ * Parse query input to extract structured information about the current search state.
+ *
+ * This function is designed for real-time parsing of user input in a search bar,
+ * allowing developers to:
+ * - Highlight keys and values differently
+ * - Provide autocomplete suggestions based on context
+ * - Validate input as the user types
+ *
+ * @param input The current search input string
+ * @param cursorPosition Optional cursor position to determine the active term
+ * @param options Optional parsing options
+ * @returns Structured information about the query input
+ *
+ * @example
+ * ```typescript
+ * // User is typing "status:d" (intending to type "status:done")
+ * const result = parseQueryInput('status:d');
+ * // result.terms[0] = { key: 'status', operator: ':', value: 'd', ... }
+ * // result.activeTerm = { key: 'status', operator: ':', value: 'd', ... }
+ * // result.cursorContext = 'value'
+ *
+ * // User is typing "priority:>2 status:"
+ * const result = parseQueryInput('priority:>2 status:', 19);
+ * // result.terms[0] = { key: 'priority', operator: ':>', value: '2', ... }
+ * // result.terms[1] = { key: 'status', operator: ':', value: null, ... }
+ * // result.activeTerm = result.terms[1] (cursor is at position 19)
+ * // result.cursorContext = 'value' (waiting for value input)
+ * ```
+ */
+function parseQueryInput(input, cursorPosition, options) {
+    // Handle empty input
+    if (!input || input.trim().length === 0) {
+        return {
+            terms: [],
+            activeTerm: null,
+            cursorContext: 'empty',
+            input,
+            cursorPosition: cursorPosition ?? null,
+            logicalOperators: []
+        };
+    }
+    // Tokenize the input
+    const { terms, logicalOperators } = tokenize(input);
+    // Apply case-insensitivity to keys if requested
+    if (options?.caseInsensitiveKeys) {
+        for (const term of terms) {
+            if (term.key !== null) {
+                term.key = term.key.toLowerCase();
+            }
+        }
+    }
+    // Find active term and cursor context
+    const { activeTerm, cursorContext } = findActiveTermAndContext(terms, cursorPosition ?? null, input.length);
+    return {
+        terms,
+        activeTerm,
+        cursorContext,
+        input,
+        cursorPosition: cursorPosition ?? null,
+        logicalOperators
+    };
+}
+/**
+ * Get the term at a specific cursor position.
+ * Convenience function for quick lookups.
+ *
+ * @param input The query input string
+ * @param cursorPosition The cursor position
+ * @returns The term at the cursor position, or null if none
+ */
+function getTermAtPosition(input, cursorPosition) {
+    const result = parseQueryInput(input, cursorPosition);
+    return result.activeTerm;
+}
+/**
+ * Check if the input appears to be a complete, valid query expression.
+ * This is a lightweight check - it doesn't guarantee the query will parse successfully.
+ *
+ * @param input The query input string
+ * @returns true if the input appears complete, false if it looks incomplete
+ */
+function isInputComplete(input) {
+    if (!input || input.trim().length === 0) {
+        return false;
+    }
+    const result = parseQueryInput(input);
+    // Check if any term is incomplete
+    for (const term of result.terms) {
+        // A key:value term is incomplete if it has an operator but no value
+        if (term.key !== null && term.operator !== null && term.value === null) {
+            return false;
+        }
+    }
+    // Check if the input ends with a logical operator
+    const trimmed = input.trim();
+    if (/\b(AND|OR|NOT)\s*$/i.test(trimmed)) {
+        return false;
+    }
+    // Check if there's an unclosed quote
+    const singleQuotes = (input.match(/'/g) || []).length;
+    const doubleQuotes = (input.match(/"/g) || []).length;
+    if (singleQuotes % 2 !== 0 || doubleQuotes % 2 !== 0) {
+        return false;
+    }
+    // Check for unclosed parentheses
+    const openParens = (input.match(/\(/g) || []).length;
+    const closeParens = (input.match(/\)/g) || []).length;
+    if (openParens !== closeParens) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Extract just the key and value from a simple input.
+ * Convenience function for the most common use case.
+ *
+ * @param input The query input string (e.g., "status:done")
+ * @returns Object with key and value, or null if not a key:value pattern
+ *
+ * @example
+ * ```typescript
+ * extractKeyValue('status:done');
+ * // { key: 'status', value: 'done' }
+ *
+ * extractKeyValue('status:');
+ * // { key: 'status', value: null }
+ *
+ * extractKeyValue('hello');
+ * // null (no key:value pattern)
+ * ```
+ */
+function extractKeyValue(input) {
+    const result = parseQueryInput(input.trim());
+    if (result.terms.length === 0) {
+        return null;
+    }
+    const term = result.terms[0];
+    if (term.key === null) {
+        return null;
+    }
+    return {
+        key: term.key,
+        value: term.value
+    };
+}
+/**
+ * Parse query input into an interleaved sequence of terms and operators.
+ *
+ * This provides a flat, ordered representation ideal for:
+ * - Rendering query tokens as UI chips/tags
+ * - Building visual query builders
+ * - Syntax highlighting with proper ordering
+ *
+ * @param input The query input string
+ * @param cursorPosition Optional cursor position to identify active token
+ * @returns Ordered sequence of term and operator tokens
+ *
+ * @example
+ * ```typescript
+ * const result = parseQueryTokens('status:done AND priority:high');
+ * // result.tokens = [
+ * //   { type: 'term', key: 'status', value: 'done', ... },
+ * //   { type: 'operator', operator: 'AND', ... },
+ * //   { type: 'term', key: 'priority', value: 'high', ... }
+ * // ]
+ *
+ * // For incomplete input like 'status:d'
+ * const result = parseQueryTokens('status:d');
+ * // result.tokens = [
+ * //   { type: 'term', key: 'status', value: 'd', ... }
+ * // ]
+ * ```
+ */
+function parseQueryTokens(input, cursorPosition) {
+    if (!input || input.trim().length === 0) {
+        return {
+            tokens: [],
+            input,
+            activeToken: null,
+            activeTokenIndex: -1
+        };
+    }
+    const context = parseQueryInput(input, cursorPosition);
+    // Build a combined list of all tokens with their positions
+    const allTokens = [];
+    // Add terms
+    for (const term of context.terms) {
+        allTokens.push({
+            position: term.startPosition,
+            token: {
+                type: 'term',
+                key: term.key,
+                operator: term.operator,
+                value: term.value,
+                startPosition: term.startPosition,
+                endPosition: term.endPosition,
+                raw: term.raw
+            }
+        });
+    }
+    // Add operators
+    for (const op of context.logicalOperators) {
+        const opLength = op.operator.length;
+        allTokens.push({
+            position: op.position,
+            token: {
+                type: 'operator',
+                operator: op.operator,
+                startPosition: op.position,
+                endPosition: op.position + opLength,
+                raw: op.operator
+            }
+        });
+    }
+    // Sort by position to get the interleaved order
+    allTokens.sort((a, b) => a.position - b.position);
+    const tokens = allTokens.map(t => t.token);
+    // Find active token based on cursor position
+    let activeToken = null;
+    let activeTokenIndex = -1;
+    if (cursorPosition !== undefined) {
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            if (cursorPosition >= token.startPosition &&
+                cursorPosition <= token.endPosition) {
+                activeToken = token;
+                activeTokenIndex = i;
+                break;
+            }
+        }
+        // If cursor is at the end and right after the last token
+        if (activeToken === null && tokens.length > 0) {
+            const lastToken = tokens[tokens.length - 1];
+            if (cursorPosition === lastToken.endPosition) {
+                activeToken = lastToken;
+                activeTokenIndex = tokens.length - 1;
+            }
+        }
+    }
+    return {
+        tokens,
+        input,
+        activeToken,
+        activeTokenIndex
+    };
+}

package/dist/parser/parser.d.ts

@@ -1,4 +1,4 @@
-import { IParserOptions, IQueryParser, QueryExpression } from './types';
+import { IParserOptions, IParseWithContextOptions, IQueryParser, IQueryParseResult, QueryExpression } from './types';
 /**
  * Error thrown when query parsing fails
  */
@@ -15,6 +15,35 @@ export declare class QueryParser implements IQueryParser {
      * Parse a query string into a QueryKit AST
      */
     parse(query: string): QueryExpression;
+    /**
+     * Pre-process a query string to convert non-standard syntax to Liqe-compatible syntax.
+     * Supports:
+     * - `field:[val1, val2, val3]` → `(field:val1 OR field:val2 OR field:val3)`
+     *
+     * This keeps the syntax consistent with the `key:value` pattern used throughout QueryKit:
+     * - `priority:>2` (comparison)
+     * - `status:active` (equality)
+     * - `status:[todo, doing, done]` (IN / multiple values)
+     */
+    private preprocessQuery;
+    /**
+     * Convert a field and comma-separated values to an OR expression string
+     */
+    private convertToOrExpression;
+    /**
+     * Parse a comma-separated string into values, respecting quoted strings.
+     * Commas inside quoted strings are preserved as part of the value.
+     *
+     * Examples:
+     * - `a, b, c` → ['a', 'b', 'c']
+     * - `"John, Jr.", Jane` → ['"John, Jr."', 'Jane']
+     * - `'hello, world', test` → ["'hello, world'", 'test']
+     */
+    private parseCommaSeparatedValues;
+    /**
+     * Format a field:value pair, quoting the value if necessary
+     */
+    private formatFieldValue;
     /**
      * Validate a query string
      */
@@ -35,6 +64,11 @@ export declare class QueryParser implements IQueryParser {
      * Create a comparison expression
      */
     private createComparisonExpression;
+    /**
+     * Convert a Liqe RangeExpression to a QueryKit logical AND expression
+     * E.g., `field:[2 TO 5]` becomes `(field >= 2 AND field <= 5)`
+     */
+    private convertRangeExpression;
     /**
      * Convert a Liqe operator to a QueryKit operator
      */
@@ -48,4 +82,117 @@ export declare class QueryParser implements IQueryParser {
      * Normalize a field name based on parser options
      */
     private normalizeFieldName;
+    /**
+     * Parse a query string with full context information.
+     *
+     * Unlike `parse()`, this method never throws. Instead, it returns a result object
+     * that indicates success or failure along with rich contextual information useful
+     * for building search UIs.
+     *
+     * @param query The query string to parse
+     * @param options Optional configuration (cursor position, etc.)
+     * @returns Rich parse result with tokens, AST/error, and structural analysis
+     *
+     * @example
+     * ```typescript
+     * const result = parser.parseWithContext('status:done AND priority:high');
+     *
+     * if (result.success) {
+     *   // Use result.ast for query execution
+     *   console.log('Valid query:', result.ast);
+     * } else {
+     *   // Show error to user
+     *   console.log('Error:', result.error?.message);
+     * }
+     *
+     * // Always available for UI rendering
+     * console.log('Tokens:', result.tokens);
+     * console.log('Structure:', result.structure);
+     * ```
+     */
+    parseWithContext(query: string, options?: IParseWithContextOptions): IQueryParseResult;
+    /**
+     * Convert tokens from input parser format to IQueryToken format
+     */
+    private convertTokens;
+    /**
+     * Convert a single token from input parser format
+     */
+    private convertSingleToken;
+    /**
+     * Analyze the structure of a query
+     */
+    private analyzeStructure;
+    /**
+     * Calculate the maximum nesting depth of parentheses
+     */
+    private calculateDepth;
+    /**
+     * Determine query complexity classification
+     */
+    private determineComplexity;
+    /**
+     * Try to extract error position from error message
+     */
+    private extractErrorPosition;
+    /**
+     * Try to extract the problematic text from the query based on error
+     */
+    private extractProblematicText;
+    /**
+     * Validate fields against the provided schema
+     */
+    private validateFields;
+    /**
+     * Find a similar field name (for typo suggestions)
+     */
+    private findSimilarField;
+    /**
+     * Calculate Levenshtein distance between two strings
+     */
+    private levenshteinDistance;
+    /**
+     * Perform security pre-check against the provided options
+     */
+    private performSecurityCheck;
+    /**
+     * Generate autocomplete suggestions based on cursor position
+     */
+    private generateAutocompleteSuggestions;
+    /**
+     * Suggest for empty/start context
+     */
+    private suggestForEmptyContext;
+    /**
+     * Suggest between tokens (after a complete term)
+     */
+    private suggestBetweenTokens;
+    /**
+     * Suggest field names
+     */
+    private suggestFields;
+    /**
+     * Get field suggestions based on partial input
+     */
+    private getFieldSuggestions;
+    /**
+     * Suggest operators
+     */
+    private suggestOperators;
+    /**
+     * Get operator suggestions based on field type
+     */
+    private getOperatorSuggestions;
+    /**
+     * Suggest values
+     */
+    private suggestValues;
+    /**
+     * Get value suggestions based on schema
+     */
+    private getValueSuggestions;
+    /**
+     * Generate error recovery suggestions
+     */
+    private generateErrorRecovery;
 }