@gblikas/querykit 0.2.0 → 0.4.0

package/dist/parser/types.d.ts

@@ -65,4 +65,436 @@ export interface IQueryParser {
      * @returns true if the query is valid, false otherwise
      */
     validate(query: string): boolean;
+    /**
+     * Parse a query string with full context information
+     * @param query The query string to parse
+     * @param options Options for context parsing
+     * @returns Rich parse result with tokens, AST, structure, and more
+     */
+    parseWithContext(query: string, options?: IParseWithContextOptions): IQueryParseResult;
+}
+/**
+ * Options for parseWithContext
+ */
+export interface IParseWithContextOptions {
+    /**
+     * Cursor position in the input (for cursor-aware features)
+     */
+    cursorPosition?: number;
+    /**
+     * Schema to validate fields against.
+     * Keys are field names, values describe the field type.
+     * When provided, enables field validation in the result.
+     */
+    schema?: Record<string, IFieldSchema>;
+    /**
+     * Security options for pre-validation.
+     * When provided, enables security pre-check in the result.
+     */
+    securityOptions?: ISecurityOptionsForContext;
+}
+/**
+ * Field schema definition for validation
+ */
+export interface IFieldSchema {
+    /**
+     * The type of the field
+     */
+    type: 'string' | 'number' | 'boolean' | 'date' | 'array' | 'unknown';
+    /**
+     * Whether the field is required (for documentation purposes)
+     */
+    required?: boolean;
+    /**
+     * Allowed values for the field (for enums)
+     */
+    allowedValues?: Array<string | number | boolean>;
+    /**
+     * Human-readable description of the field
+     */
+    description?: string;
+}
+/**
+ * Security options for parseWithContext (subset of full security options)
+ */
+export interface ISecurityOptionsForContext {
+    /**
+     * List of fields that are allowed to be queried
+     */
+    allowedFields?: string[];
+    /**
+     * List of fields that are denied from being queried
+     */
+    denyFields?: string[];
+    /**
+     * Maximum query depth allowed
+     */
+    maxQueryDepth?: number;
+    /**
+     * Maximum number of clauses allowed
+     */
+    maxClauseCount?: number;
+    /**
+     * Whether to allow dot notation in field names
+     */
+    allowDotNotation?: boolean;
+}
+/**
+ * Structural analysis of a query
+ */
+export interface IQueryStructure {
+    /**
+     * Maximum nesting depth of the query
+     * e.g., "a:1 AND (b:2 OR c:3)" has depth 2
+     */
+    depth: number;
+    /**
+     * Total number of comparison clauses
+     * e.g., "a:1 AND b:2 OR c:3" has 3 clauses
+     */
+    clauseCount: number;
+    /**
+     * Number of logical operators (AND, OR, NOT)
+     */
+    operatorCount: number;
+    /**
+     * Whether parentheses are balanced
+     */
+    hasBalancedParentheses: boolean;
+    /**
+     * Whether all quotes are closed
+     */
+    hasBalancedQuotes: boolean;
+    /**
+     * Whether the query appears structurally complete
+     * (no trailing operators, no unclosed constructs)
+     */
+    isComplete: boolean;
+    /**
+     * List of fields referenced in the query
+     */
+    referencedFields: string[];
+    /**
+     * Complexity classification
+     */
+    complexity: 'simple' | 'moderate' | 'complex';
+}
+/**
+ * Error information when parsing fails
+ */
+export interface IQueryParseErrorInfo {
+    /**
+     * Error message
+     */
+    message: string;
+    /**
+     * Position in the input where the error occurred (if known)
+     */
+    position?: number;
+    /**
+     * The portion of input that caused the error (if identifiable)
+     */
+    problematicText?: string;
+}
+/**
+ * Result of parseWithContext - provides rich context about the query
+ */
+export interface IQueryParseResult {
+    /**
+     * Whether parsing succeeded
+     */
+    success: boolean;
+    /**
+     * The original input string
+     */
+    input: string;
+    /**
+     * Parsed AST (only present if success is true)
+     */
+    ast?: QueryExpression;
+    /**
+     * Error information (only present if success is false)
+     */
+    error?: IQueryParseErrorInfo;
+    /**
+     * Tokenized representation of the input
+     * Always present, even if parsing failed
+     */
+    tokens: IQueryToken[];
+    /**
+     * The token at the cursor position (if cursorPosition was provided)
+     */
+    activeToken?: IQueryToken;
+    /**
+     * Index of the active token (-1 if none)
+     */
+    activeTokenIndex: number;
+    /**
+     * Structural analysis of the query
+     */
+    structure: IQueryStructure;
+    /**
+     * Field validation results (only present if schema was provided in options)
+     */
+    fieldValidation?: IFieldValidationResult;
+    /**
+     * Security pre-check results (only present if securityOptions was provided)
+     */
+    security?: ISecurityCheckResult;
+    /**
+     * Autocomplete suggestions based on cursor position
+     * Only present if cursorPosition was provided in options
+     */
+    suggestions?: IAutocompleteSuggestions;
+    /**
+     * Error recovery hints (only present if parsing failed)
+     */
+    recovery?: IErrorRecovery;
+}
+/**
+ * Autocomplete suggestions based on cursor context
+ */
+export interface IAutocompleteSuggestions {
+    /**
+     * The context where the cursor is positioned
+     */
+    context: 'field' | 'operator' | 'value' | 'logical_operator' | 'empty';
+    /**
+     * The current field being edited (if in value context)
+     */
+    currentField?: string;
+    /**
+     * Suggested field names (when in field context)
+     */
+    fields?: IFieldSuggestion[];
+    /**
+     * Suggested values (when in value context and schema has allowedValues)
+     */
+    values?: IValueSuggestion[];
+    /**
+     * Suggested operators (when in operator context)
+     */
+    operators?: IOperatorSuggestion[];
+    /**
+     * Suggested logical operators (AND, OR, NOT)
+     */
+    logicalOperators?: string[];
+    /**
+     * The text that would be replaced by the suggestion
+     */
+    replaceText?: string;
+    /**
+     * Position range that would be replaced
+     */
+    replaceRange?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * A field suggestion for autocomplete
+ */
+export interface IFieldSuggestion {
+    /**
+     * The field name
+     */
+    field: string;
+    /**
+     * The field type (from schema)
+     */
+    type?: string;
+    /**
+     * Description of the field (from schema)
+     */
+    description?: string;
+    /**
+     * Match score (higher is better match)
+     */
+    score: number;
+}
+/**
+ * A value suggestion for autocomplete
+ */
+export interface IValueSuggestion {
+    /**
+     * The suggested value
+     */
+    value: string | number | boolean;
+    /**
+     * Display label (may differ from value)
+     */
+    label?: string;
+    /**
+     * Match score (higher is better match)
+     */
+    score: number;
+}
+/**
+ * An operator suggestion for autocomplete
+ */
+export interface IOperatorSuggestion {
+    /**
+     * The operator symbol
+     */
+    operator: string;
+    /**
+     * Human-readable description
+     */
+    description: string;
+    /**
+     * Whether this operator is applicable to the current field type
+     */
+    applicable: boolean;
+}
+/**
+ * Error recovery suggestions
+ */
+export interface IErrorRecovery {
+    /**
+     * The type of issue detected
+     */
+    issue: 'unclosed_quote' | 'unclosed_parenthesis' | 'trailing_operator' | 'missing_value' | 'missing_operator' | 'syntax_error';
+    /**
+     * Human-readable description of the issue
+     */
+    message: string;
+    /**
+     * Suggested fix description
+     */
+    suggestion: string;
+    /**
+     * The corrected query (if auto-fix is possible)
+     */
+    autofix?: string;
+    /**
+     * Position where the issue was detected
+     */
+    position?: number;
+}
+/**
+ * Result of field validation against schema
+ */
+export interface IFieldValidationResult {
+    /**
+     * Whether all fields passed validation
+     */
+    valid: boolean;
+    /**
+     * Validation details for each field
+     */
+    fields: IFieldValidationDetail[];
+    /**
+     * Fields that were referenced but not found in schema
+     */
+    unknownFields: string[];
+}
+/**
+ * Validation detail for a single field
+ */
+export interface IFieldValidationDetail {
+    /**
+     * The field name
+     */
+    field: string;
+    /**
+     * Whether this field is valid
+     */
+    valid: boolean;
+    /**
+     * The expected type from schema (if known)
+     */
+    expectedType?: string;
+    /**
+     * Reason for validation failure (if invalid)
+     */
+    reason?: 'unknown_field' | 'type_mismatch' | 'invalid_value' | 'denied';
+    /**
+     * Suggested correction (for typos)
+     */
+    suggestion?: string;
+    /**
+     * Allowed values (if field has enum constraint)
+     */
+    allowedValues?: Array<string | number | boolean>;
+}
+/**
+ * Result of security pre-check
+ */
+export interface ISecurityCheckResult {
+    /**
+     * Whether the query passes all security checks
+     */
+    passed: boolean;
+    /**
+     * List of security violations found
+     */
+    violations: ISecurityViolation[];
+    /**
+     * Warnings that don't block execution but should be noted
+     */
+    warnings: ISecurityWarning[];
+}
+/**
+ * A security violation that blocks query execution
+ */
+export interface ISecurityViolation {
+    /**
+     * Type of violation
+     */
+    type: 'denied_field' | 'depth_exceeded' | 'clause_limit' | 'dot_notation' | 'field_not_allowed';
+    /**
+     * Human-readable message
+     */
+    message: string;
+    /**
+     * The field that caused the violation (if applicable)
+     */
+    field?: string;
+}
+/**
+ * A security warning (doesn't block execution)
+ */
+export interface ISecurityWarning {
+    /**
+     * Type of warning
+     */
+    type: 'approaching_depth_limit' | 'approaching_clause_limit' | 'complex_query';
+    /**
+     * Human-readable message
+     */
+    message: string;
+    /**
+     * Current value
+     */
+    current?: number;
+    /**
+     * Limit value
+     */
+    limit?: number;
+}
+/**
+ * A token in the parsed query (term or operator)
+ */
+export type IQueryToken = IQueryTermToken | IQueryOperatorToken;
+/**
+ * A term token (field:value pair or bare value)
+ */
+export interface IQueryTermToken {
+    type: 'term';
+    key: string | null;
+    operator: string | null;
+    value: string | null;
+    startPosition: number;
+    endPosition: number;
+    raw: string;
+}
+/**
+ * A logical operator token (AND, OR, NOT)
+ */
+export interface IQueryOperatorToken {
+    type: 'operator';
+    operator: 'AND' | 'OR' | 'NOT';
+    startPosition: number;
+    endPosition: number;
+    raw: string;
 }

package/dist/virtual-fields/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Virtual Fields module exports
+ */
+export * from './types';
+export * from './resolver';

package/dist/virtual-fields/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Virtual Fields module exports
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./resolver"), exports);

package/dist/virtual-fields/resolver.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Virtual field resolution logic
+ */
+import { QueryExpression } from '../parser/types';
+import { IQueryContext, VirtualFieldsConfig } from './types';
+/**
+ * Resolve virtual fields in a query expression.
+ * Recursively walks the AST and replaces virtual field references with
+ * their resolved expressions based on the provided context.
+ *
+ * @param expr - The query expression to resolve
+ * @param virtualFields - Virtual field configuration
+ * @param context - Runtime context for resolution
+ * @returns The resolved query expression
+ * @throws {QueryParseError} If a virtual field value is invalid or operator is not allowed
+ */
+export declare function resolveVirtualFields<TSchema extends Record<string, object>, TContext extends IQueryContext>(expr: QueryExpression, virtualFields: VirtualFieldsConfig<TSchema, TContext>, context: TContext): QueryExpression;

package/dist/virtual-fields/resolver.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Virtual field resolution logic
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVirtualFields = resolveVirtualFields;
+const parser_1 = require("../parser/parser");
+/**
+ * Resolve virtual fields in a query expression.
+ * Recursively walks the AST and replaces virtual field references with
+ * their resolved expressions based on the provided context.
+ *
+ * @param expr - The query expression to resolve
+ * @param virtualFields - Virtual field configuration
+ * @param context - Runtime context for resolution
+ * @returns The resolved query expression
+ * @throws {QueryParseError} If a virtual field value is invalid or operator is not allowed
+ */
+function resolveVirtualFields(expr, virtualFields, context) {
+    // Base case: comparison expression
+    if (expr.type === 'comparison') {
+        return resolveComparisonExpression(expr, virtualFields, context);
+    }
+    // Recursive case: logical expression
+    if (expr.type === 'logical') {
+        return resolveLogicalExpression(expr, virtualFields, context);
+    }
+    // Unknown expression type, return as-is
+    return expr;
+}
+/**
+ * Resolve a comparison expression.
+ * If the field is a virtual field, resolve it using the configuration.
+ * Otherwise, return the expression unchanged.
+ */
+function resolveComparisonExpression(expr, virtualFields, context) {
+    const fieldName = expr.field;
+    const virtualFieldDef = virtualFields[fieldName];
+    // Not a virtual field, return as-is
+    if (!virtualFieldDef) {
+        return expr;
+    }
+    // Validate the value is a string (virtual fields require string values)
+    if (typeof expr.value !== 'string') {
+        const valueType = Array.isArray(expr.value)
+            ? `array (${JSON.stringify(expr.value)})`
+            : typeof expr.value === 'object'
+                ? `object (${JSON.stringify(expr.value)})`
+                : typeof expr.value;
+        throw new parser_1.QueryParseError(`Virtual field "${fieldName}" requires a string value, got ${valueType}`);
+    }
+    const value = expr.value;
+    // Validate the value is in allowedValues
+    if (!virtualFieldDef.allowedValues.includes(value)) {
+        const allowedValuesStr = virtualFieldDef.allowedValues
+            .map(v => `"${v}"`)
+            .join(', ');
+        throw new parser_1.QueryParseError(`Invalid value "${value}" for virtual field "${fieldName}". Allowed values: ${allowedValuesStr}`);
+    }
+    // Validate operator usage
+    const allowOperators = virtualFieldDef.allowOperators ?? false;
+    if (!allowOperators && expr.operator !== '==') {
+        throw new parser_1.QueryParseError(`Virtual field "${fieldName}" does not allow comparison operators. Only equality (":") is permitted.`);
+    }
+    // Create the input for the resolver
+    const input = {
+        field: fieldName,
+        operator: expr.operator,
+        value: value
+    };
+    // Create the helpers object with type-safe fields() helper
+    // The fields() method is generic at the method level, allowing TypeScript to
+    // infer TValues from the mapping object at call-time without needing type assertions
+    const helpers = {
+        fields: (mapping) => {
+            // Validate that all keys in the mapping are in the virtual field's allowed values
+            const mappingKeys = Object.keys(mapping);
+            const allowedValues = virtualFieldDef.allowedValues;
+            for (const key of mappingKeys) {
+                if (!allowedValues.includes(key)) {
+                    throw new parser_1.QueryParseError(`Invalid key "${key}" in field mapping for virtual field "${fieldName}". ` +
+                        `Allowed keys are: ${allowedValues.map(v => `"${v}"`).join(', ')}`);
+                }
+            }
+            // Runtime: this is just an identity function
+            // Compile-time: TypeScript validates the mapping structure
+            return mapping;
+        }
+    };
+    // Resolve the virtual field - no type assertions needed!
+    const resolved = virtualFieldDef.resolve(input, context, helpers);
+    return resolved;
+}
+/**
+ * Resolve a logical expression.
+ * Recursively resolve both left and right sides.
+ */
+function resolveLogicalExpression(expr, virtualFields, context) {
+    return {
+        type: 'logical',
+        operator: expr.operator,
+        left: resolveVirtualFields(expr.left, virtualFields, context),
+        right: expr.right
+            ? resolveVirtualFields(expr.right, virtualFields, context)
+            : undefined
+    };
+}