@gblikas/querykit 0.1.0 → 0.3.0

package/.cursor/BUGBOT.md

@@ -1,21 +1,84 @@
 # Project review guidelines
 
-Bellow is a list of generally accepted best-practices to prevent bugs in projects. Not all guidelines may apply to the current project; please make sure to read any README.md files in order to correlate goals for bug detection. 
+Below is a list of generally accepted best-practices to prevent bugs in QueryKit. Not all guidelines may apply to every component; please make sure to read the README.md for context on the project's goals.
 
 ## Security focus areas
 
 - Validate user input in API endpoints
 - Check for SQL injection vulnerabilities in database queries
 - Ensure proper authentication on protected routes
+- Validate query inputs using `parseWithContext` with security options
+- Use `allowedFields` and `denyFields` to restrict queryable fields
+- Set `maxQueryDepth` and `maxClauseCount` to prevent DoS attacks
+
+### Query parsing security
+
+When using the input parser or `parseWithContext`:
+
+1. **Never trust user-provided queries** - Always validate with security options:
+   ```typescript
+   const result = parser.parseWithContext(userQuery, {
+     securityOptions: {
+       allowedFields: ['name', 'status', 'priority'],
+       denyFields: ['password', 'secret'],
+       maxQueryDepth: 5,
+       maxClauseCount: 20
+     }
+   });
+   
+   if (!result.security?.passed) {
+     // Reject query - contains violations
+   }
+   ```
+
+2. **Schema validation** - Use schema to detect typos and invalid fields early:
+   ```typescript
+   const result = parser.parseWithContext(userQuery, { schema });
+   if (!result.fieldValidation?.valid) {
+     // Show user-friendly error with suggestions
+   }
+   ```
+
+3. **Input parser limitations** - The input parser (`parseQueryInput`, `parseQueryTokens`) is regex-based for performance. It may accept inputs that the main parser rejects. Always validate with `parseWithContext` or `parser.parse()` before executing queries.
 
 ## Architecture patterns
 
 - Use dependency injection for services
 - Follow the repository pattern for data access
 - Implement proper error handling with custom error classes
+- Parser components follow Single Responsibility Principle:
+  - `input-parser.ts` - Fast, regex-based tokenization for UI feedback
+  - `parser.ts` - Full Liqe-based parsing with AST generation
+  - `parseWithContext` - Orchestrates both for rich context
+
+### Parser architecture
+
+The parsing system has two tiers:
+
+1. **Input Parser** (`parseQueryInput`, `parseQueryTokens`)
+   - Purpose: Real-time UI feedback (highlighting, cursor context)
+   - Performance: O(n) regex-based, no AST generation
+   - Error handling: Best-effort, never throws
+   - Use for: Search bar highlighting, autocomplete triggering
+
+2. **Query Parser** (`parser.parse`, `parseWithContext`)
+   - Purpose: Query validation and execution
+   - Performance: Full Liqe grammar parsing
+   - Error handling: Strict validation, detailed error messages
+   - Use for: Query execution, security validation
 
 ## Common issues
 
 - Memory leaks in React components (check useEffect cleanup)
 - Missing error boundaries in UI components
-- Inconsistent naming conventions (use camelCase for functions)
+- Inconsistent naming conventions (use camelCase for functions)
+- Not checking `result.success` before accessing `result.ast`
+- Using input parser for security validation (use `parseWithContext` instead)
+- Forgetting to provide `cursorPosition` when autocomplete is needed
+
+## Testing guidelines
+
+- All parser features require co-located tests
+- Use divergence tests to document differences between input parser and main parser
+- Token consistency tests verify `parseWithContext` tokens match `parseQueryTokens`
+- Security tests should cover field restrictions, depth limits, and value sanitization

package/README.md

@@ -275,6 +275,165 @@ const publicSearchKit = createQueryKit({
 });
 ```
 
+## Input Parsing for Search UIs
+
+QueryKit provides utilities for building rich search bar experiences with real-time feedback, including key:value highlighting, autocomplete suggestions, and error recovery hints.
+
+### Real-Time Token Parsing
+
+Use `parseQueryInput` and `parseQueryTokens` for lightweight, real-time parsing as users type:
+
+```typescript
+import { parseQueryInput, parseQueryTokens } from '@gblikas/querykit';
+
+// Parse input to get terms and cursor context
+const input = 'status:done AND priority:';
+const result = parseQueryInput(input, { cursorPosition: 25 });
+
+// result.terms contains parsed terms:
+// [{ key: 'status', value: 'done', ... }, { key: 'priority', value: null, ... }]
+
+// result.cursorContext tells you where the cursor is: 'key', 'value', or 'operator'
+console.log(result.cursorContext); // 'value' (cursor is after 'priority:')
+
+// Get interleaved tokens (terms + operators) for highlighting
+const tokens = parseQueryTokens(input);
+// [
+//   { type: 'term', key: 'status', value: 'done', startPosition: 0, endPosition: 11 },
+//   { type: 'operator', operator: 'AND', startPosition: 12, endPosition: 15 },
+//   { type: 'term', key: 'priority', value: null, startPosition: 16, endPosition: 25 }
+// ]
+```
+
+### Rich Context with parseWithContext
+
+For comprehensive parsing with schema validation, autocomplete, and error recovery:
+
+```typescript
+import { QueryParser } from '@gblikas/querykit';
+
+const parser = new QueryParser();
+
+// Define your schema for validation and autocomplete
+const schema = {
+  status: {
+    type: 'string',
+    allowedValues: ['todo', 'doing', 'done'],
+    description: 'Task status'
+  },
+  priority: { type: 'number', description: 'Priority level (1-5)' },
+  assignee: { type: 'string', description: 'Assigned user' }
+};
+
+const result = parser.parseWithContext('status:do', {
+  cursorPosition: 9,
+  schema,
+  securityOptions: { maxClauseCount: 10 }
+});
+
+// Always returns a result object (never throws)
+console.log(result.success);    // true/false - whether parsing succeeded
+console.log(result.tokens);     // Tokenized input (always available)
+console.log(result.structure);  // Query structure analysis
+console.log(result.ast);        // AST (if successful)
+console.log(result.error);      // Error details (if failed)
+
+// Autocomplete suggestions based on cursor position
+console.log(result.suggestions);
+// {
+//   context: 'value',
+//   currentField: 'status',
+//   values: [
+//     { value: 'doing', score: 80 },
+//     { value: 'done', score: 80 }
+//   ]
+// }
+
+// Schema validation results
+console.log(result.fieldValidation);
+// { valid: true, fields: [...], unknownFields: [] }
+
+// Security pre-check
+console.log(result.security);
+// { passed: true, violations: [], warnings: [] }
+```
+
+### Error Recovery
+
+When parsing fails, `parseWithContext` provides helpful recovery hints:
+
+```typescript
+const result = parser.parseWithContext('status:"incomplete');
+
+console.log(result.recovery);
+// {
+//   issue: 'unclosed_quote',
+//   message: 'Unclosed double quote detected',
+//   suggestion: 'Add a closing " to complete the quoted value',
+//   autofix: 'status:"incomplete"',
+//   position: 7
+// }
+```
+
+Error types detected:
+- `unclosed_quote` - Missing closing quote (with autofix)
+- `unclosed_parenthesis` - Unbalanced parentheses (with autofix)
+- `trailing_operator` - Query ends with AND/OR/NOT (with autofix)
+- `missing_value` - Field has colon but no value
+- `syntax_error` - Generic syntax issue
+
+### Building a Search Bar with Highlighting
+
+Here's a React example using the input parser for highlighting:
+
+```tsx
+import { parseQueryTokens } from '@gblikas/querykit';
+
+function SearchBar({ value, onChange }) {
+  const tokens = parseQueryTokens(value);
+
+  const renderHighlightedQuery = () => {
+    if (!value) return null;
+
+    return tokens.map((token, idx) => {
+      const text = value.slice(token.startPosition, token.endPosition);
+
+      if (token.type === 'operator') {
+        return <span key={idx} className="text-purple-500">{text}</span>;
+      }
+
+      // Term token - highlight key and value differently
+      if (token.key && token.operator) {
+        const keyEnd = token.startPosition + token.key.length;
+        const opEnd = keyEnd + token.operator.length;
+        return (
+          <span key={idx}>
+            <span className="text-orange-400">{token.key}</span>
+            <span className="text-gray-500">{token.operator}</span>
+            <span className="text-blue-400">{value.slice(opEnd, token.endPosition)}</span>
+          </span>
+        );
+      }
+
+      return <span key={idx}>{text}</span>;
+    });
+  };
+
+  return (
+    <div className="relative">
+      <div className="absolute inset-0 pointer-events-none">
+        {renderHighlightedQuery()}
+      </div>
+      <input
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="bg-transparent text-transparent caret-black"
+      />
+    </div>
+  );
+}
+```
+
 ## Roadmap
 
 ### Core Parsing Engine and DSL
@@ -283,6 +442,9 @@ const publicSearchKit = createQueryKit({
 - [x] Develop internal AST representation
 - [x] Implement consistent syntax for logical operators (AND, OR, NOT)
 - [x] Support standard comparison operators (==, !=, >, >=, <, <=)
+- [x] Real-time input parsing for search UIs
+- [x] Autocomplete suggestions with schema awareness
+- [x] Error recovery hints with autofix
 
 ### First Adapters
 - [x] Drizzle ORM integration
@@ -299,7 +461,7 @@ const publicSearchKit = createQueryKit({
 - [ ] Pagination helpers
 
 ### Ecosystem Expansion
-- [ ] Frontend query builder components
+- [x] Frontend query builder components (input parser)
 - [ ] Additional ORM adapters
 - [ ] Server middleware for Express/Fastify
 - [ ] TypeScript SDK generation

package/dist/parser/index.d.ts

@@ -1,2 +1,3 @@
 export * from './types';
 export * from './parser';
+export * from './input-parser';

package/dist/parser/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./parser"), exports);
+__exportStar(require("./input-parser"), exports);

package/dist/parser/input-parser.d.ts

@@ -0,0 +1,215 @@
+/**
+ * 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
+ */
+/**
+ * Represents the context of where the cursor is within a query term
+ */
+export type CursorContext = 'key' | 'operator' | 'value' | 'empty' | 'between';
+/**
+ * Represents the parsed context of a single query term
+ */
+export interface IQueryInputTerm {
+    /**
+     * The field/key being typed (e.g., "status" in "status:done")
+     * Will be null if only a bare value is being typed
+     */
+    key: string | null;
+    /**
+     * The operator being used (e.g., ":", ">", ">=", "<", "<=", "!=")
+     * Will be null if no operator has been typed yet
+     */
+    operator: string | null;
+    /**
+     * The value being typed (e.g., "done" in "status:done")
+     * Will be null if no value has been typed yet
+     */
+    value: string | null;
+    /**
+     * The start position of this term in the original input string
+     */
+    startPosition: number;
+    /**
+     * The end position of this term in the original input string
+     */
+    endPosition: number;
+    /**
+     * The original raw text of this term
+     */
+    raw: string;
+}
+/**
+ * Represents the result of parsing query input
+ */
+export interface IQueryInputContext {
+    /**
+     * All terms found in the input
+     */
+    terms: IQueryInputTerm[];
+    /**
+     * The term where the cursor is currently positioned (if cursorPosition was provided)
+     * Will be null if cursor is not within any term
+     */
+    activeTerm: IQueryInputTerm | null;
+    /**
+     * Where the cursor is within the active term
+     */
+    cursorContext: CursorContext;
+    /**
+     * The original input string
+     */
+    input: string;
+    /**
+     * The cursor position (if provided)
+     */
+    cursorPosition: number | null;
+    /**
+     * Logical operators found between terms (AND, OR, NOT)
+     */
+    logicalOperators: Array<{
+        operator: string;
+        position: number;
+    }>;
+}
+/**
+ * Options for parsing query input
+ */
+export interface IQueryInputParserOptions {
+    /**
+     * Whether to treat the input as case-insensitive for keys
+     * @default false
+     */
+    caseInsensitiveKeys?: boolean;
+}
+/**
+ * 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)
+ * ```
+ */
+export declare function parseQueryInput(input: string, cursorPosition?: number, options?: IQueryInputParserOptions): IQueryInputContext;
+/**
+ * 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
+ */
+export declare function getTermAtPosition(input: string, cursorPosition: number): IQueryInputTerm | null;
+/**
+ * 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
+ */
+export declare function isInputComplete(input: string): boolean;
+/**
+ * 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)
+ * ```
+ */
+export declare function extractKeyValue(input: string): {
+    key: string;
+    value: string | null;
+} | null;
+import type { IQueryToken } from './types';
+/**
+ * A token in the query sequence - either a term or a logical operator
+ * This is an alias for IQueryToken from types.ts
+ */
+export type QueryToken = IQueryToken;
+/**
+ * Result of parsing query input into an interleaved token sequence
+ */
+export interface IQueryTokenSequence {
+    /**
+     * Ordered sequence of tokens (terms and operators interleaved)
+     */
+    tokens: QueryToken[];
+    /**
+     * The original input string
+     */
+    input: string;
+    /**
+     * The token where the cursor is currently positioned (if cursorPosition was provided)
+     */
+    activeToken: QueryToken | null;
+    /**
+     * Index of the active token in the tokens array (-1 if none)
+     */
+    activeTokenIndex: number;
+}
+/**
+ * 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', ... }
+ * // ]
+ * ```
+ */
+export declare function parseQueryTokens(input: string, cursorPosition?: number): IQueryTokenSequence;