@gblikas/querykit 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -10,9 +10,11 @@ import { QueryParser, IParserOptions } from './parser';
 import { SqlTranslator } from './translators/sql';
 import { ISecurityOptions } from './security';
 import { IAdapter, IAdapterOptions } from './adapters';
+import { IQueryContext, VirtualFieldsConfig } from './virtual-fields';
 export { QueryParser, IParserOptions, QueryBuilder, IQueryBuilderOptions, SqlTranslator };
 export * from './translators';
 export * from './adapters';
+export * from './virtual-fields';
 /**
  * Create a new QueryBuilder instance
  */
@@ -24,7 +26,7 @@ export declare function createQueryParser(options?: IParserOptions): QueryParser
 /**
  * Options for creating a new QueryKit instance
  */
-export interface IQueryKitOptions<TSchema extends Record<string, object> = Record<string, Record<string, unknown>>> {
+export interface IQueryKitOptions<TSchema extends Record<string, object> = Record<string, Record<string, unknown>>, TContext extends IQueryContext = IQueryContext> {
     /**
      * The adapter to use for database connections
      */
@@ -43,6 +45,37 @@ export interface IQueryKitOptions<TSchema extends Record<string, object> = Recor
     adapterOptions?: IAdapterOptions & {
         [key: string]: unknown;
     };
+    /**
+     * Virtual field definitions for context-aware query expansion.
+     * Virtual fields allow shortcuts like `my:assigned` that expand to
+     * real schema fields at query execution time.
+     *
+     * @example
+     * virtualFields: {
+     *   my: {
+     *     allowedValues: ['assigned', 'created'] as const,
+     *     resolve: (input, ctx, { fields }) => ({
+     *       type: 'comparison',
+     *       field: fields({ assigned: 'assignee_id', created: 'creator_id' })[input.value],
+     *       operator: '==',
+     *       value: ctx.currentUserId
+     *     })
+     *   }
+     * }
+     */
+    virtualFields?: VirtualFieldsConfig<TSchema, TContext>;
+    /**
+     * Factory function to create query execution context.
+     * Called once per query execution to provide runtime values
+     * for virtual field resolution.
+     *
+     * @example
+     * createContext: async () => ({
+     *   currentUserId: await getCurrentUserId(),
+     *   currentUserTeamIds: await getUserTeamIds()
+     * })
+     */
+    createContext?: () => TContext | Promise<TContext>;
 }
 export interface IQueryExecutor<TResult> {
     execute(): Promise<TResult[]>;
@@ -66,10 +99,10 @@ export type QueryKit<TSchema extends Record<string, object>, TRows extends {
 /**
  * Create a new QueryKit instance
  */
-export declare function createQueryKit<TSchema extends Record<string, object>, TRows extends {
+export declare function createQueryKit<TSchema extends Record<string, object>, TContext extends IQueryContext = IQueryContext, TRows extends {
     [K in keyof TSchema & string]: unknown;
 } = {
     [K in keyof TSchema & string]: unknown;
-}>(options: IQueryKitOptions<TSchema>): QueryKit<TSchema, TRows>;
+}>(options: IQueryKitOptions<TSchema, TContext>): QueryKit<TSchema, TRows>;
 export * from './parser';
 export * from './security';

package/dist/index.js

@@ -33,9 +33,11 @@ Object.defineProperty(exports, "QueryParser", { enumerable: true, get: function
 const sql_1 = require("./translators/sql");
 Object.defineProperty(exports, "SqlTranslator", { enumerable: true, get: function () { return sql_1.SqlTranslator; } });
 const security_1 = require("./security");
+const virtual_fields_1 = require("./virtual-fields");
 // Re-export from modules
 __exportStar(require("./translators"), exports);
 __exportStar(require("./adapters"), exports);
+__exportStar(require("./virtual-fields"), exports);
 /**
  * Create a new QueryBuilder instance
  */
@@ -75,9 +77,8 @@ function createQueryKit(options) {
         query: (table) => {
             return {
                 where: (queryString) => {
-                    // Parse and validate the query
+                    // Parse the query
                     const expressionAst = parser.parse(queryString);
-                    securityValidator.validate(expressionAst, options.schema);
                     // Execution state accumulated via fluent calls
                     let orderByState = {};
                     let limitState;
@@ -96,8 +97,24 @@ function createQueryKit(options) {
                             return executor;
                         },
                         execute: async () => {
+                            // Validate that if virtual fields are configured, createContext must also be provided
+                            if (options.virtualFields && !options.createContext) {
+                                throw new Error('createContext must be provided when virtualFields is configured');
+                            }
+                            // Get context if virtual fields are configured
+                            let context;
+                            if (options.virtualFields && options.createContext) {
+                                context = await options.createContext();
+                            }
+                            // Resolve virtual fields if configured and context is available
+                            let resolvedExpression = expressionAst;
+                            if (options.virtualFields && context) {
+                                resolvedExpression = (0, virtual_fields_1.resolveVirtualFields)(expressionAst, options.virtualFields, context);
+                            }
+                            // Validate the resolved query
+                            securityValidator.validate(resolvedExpression, options.schema);
                             // Delegate to adapter
-                            const results = await options.adapter.execute(table, expressionAst, {
+                            const results = await options.adapter.execute(table, resolvedExpression, {
                                 orderBy: Object.keys(orderByState).length > 0
                                     ? orderByState
                                     : undefined,

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;