@gblikas/querykit 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * QueryKit - A comprehensive query toolkit for TypeScript
+ *
+ * QueryKit simplifies how you build and execute data queries across different
+ * environments with a unified, intuitive syntax for filtering, sorting, and
+ * transforming data.
+ */
+import { QueryBuilder, IQueryBuilderOptions } from './query';
+import { QueryParser, IParserOptions } from './parser';
+import { SqlTranslator } from './translators/sql';
+import { ISecurityOptions } from './security';
+import { IAdapter, IAdapterOptions } from './adapters';
+export { QueryParser, IParserOptions, QueryBuilder, IQueryBuilderOptions, SqlTranslator };
+export * from './translators';
+export * from './adapters';
+/**
+ * Create a new QueryBuilder instance
+ */
+export declare function createQueryBuilder<T>(options?: IQueryBuilderOptions<T>): QueryBuilder<T>;
+/**
+ * Create a new QueryParser instance
+ */
+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>>> {
+    /**
+     * The adapter to use for database connections
+     */
+    adapter: IAdapter;
+    /**
+     * The schema to use for query validation
+     */
+    schema: TSchema;
+    /**
+     * Security options for query validation
+     */
+    security?: ISecurityOptions;
+    /**
+     * Options to initialize the provided adapter
+     */
+    adapterOptions?: IAdapterOptions & {
+        [key: string]: unknown;
+    };
+}
+export interface IQueryExecutor<TResult> {
+    execute(): Promise<TResult[]>;
+    orderBy(field: string, direction?: 'asc' | 'desc'): IQueryExecutor<TResult>;
+    limit(count: number): IQueryExecutor<TResult>;
+    offset(count: number): IQueryExecutor<TResult>;
+}
+export interface IWhereClause<TResult> {
+    where(queryString: string): IQueryExecutor<TResult>;
+}
+/**
+ * Public QueryKit type
+ */
+export type QueryKit<TSchema extends Record<string, object>, TRows extends {
+    [K in keyof TSchema & string]: unknown;
+} = {
+    [K in keyof TSchema & string]: unknown;
+}> = {
+    query<K extends keyof TSchema & string>(table: K): IWhereClause<TRows[K]>;
+};
+/**
+ * Create a new QueryKit instance
+ */
+export declare function createQueryKit<TSchema extends Record<string, object>, TRows extends {
+    [K in keyof TSchema & string]: unknown;
+} = {
+    [K in keyof TSchema & string]: unknown;
+}>(options: IQueryKitOptions<TSchema>): QueryKit<TSchema, TRows>;
+export * from './parser';
+export * from './security';

package/dist/index.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * QueryKit - A comprehensive query toolkit for TypeScript
+ *
+ * QueryKit simplifies how you build and execute data queries across different
+ * environments with a unified, intuitive syntax for filtering, sorting, and
+ * transforming data.
+ */
+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 });
+exports.SqlTranslator = exports.QueryBuilder = exports.QueryParser = void 0;
+exports.createQueryBuilder = createQueryBuilder;
+exports.createQueryParser = createQueryParser;
+exports.createQueryKit = createQueryKit;
+// Core exports
+const query_1 = require("./query");
+Object.defineProperty(exports, "QueryBuilder", { enumerable: true, get: function () { return query_1.QueryBuilder; } });
+const parser_1 = require("./parser");
+Object.defineProperty(exports, "QueryParser", { enumerable: true, get: function () { return parser_1.QueryParser; } });
+const sql_1 = require("./translators/sql");
+Object.defineProperty(exports, "SqlTranslator", { enumerable: true, get: function () { return sql_1.SqlTranslator; } });
+const security_1 = require("./security");
+// Re-export from modules
+__exportStar(require("./translators"), exports);
+__exportStar(require("./adapters"), exports);
+/**
+ * Create a new QueryBuilder instance
+ */
+function createQueryBuilder(options) {
+    return new query_1.QueryBuilder(options);
+}
+/**
+ * Create a new QueryParser instance
+ */
+function createQueryParser(options) {
+    return new parser_1.QueryParser(options);
+}
+/**
+ * Create a new QueryKit instance
+ */
+function createQueryKit(options) {
+    const parser = new parser_1.QueryParser();
+    const securityValidator = new security_1.QuerySecurityValidator(options.security);
+    // Initialize adapter if options provided. If adapter is already initialized,
+    // calling initialize again with the same options should be a no-op for most adapters.
+    if (options.adapterOptions) {
+        const mergedAdapterOptions = {
+            // Ensure adapter receives schema information if not already provided
+            schema: options.adapterOptions.schema ?? options.schema,
+            ...options.adapterOptions
+        };
+        try {
+            options.adapter.initialize(mergedAdapterOptions);
+        }
+        catch {
+            // If initialization fails here, the adapter might already be initialized
+            // or require a different init path; we'll let execute-time errors surface.
+        }
+    }
+    // This function would be expanded to include all QueryKit functionality
+    return {
+        query: (table) => {
+            return {
+                where: (queryString) => {
+                    // Parse and validate the query
+                    const expressionAst = parser.parse(queryString);
+                    securityValidator.validate(expressionAst, options.schema);
+                    // Execution state accumulated via fluent calls
+                    let orderByState = {};
+                    let limitState;
+                    let offsetState;
+                    const executor = {
+                        orderBy: (field, direction = 'asc') => {
+                            orderByState = { ...orderByState, [field]: direction };
+                            return executor;
+                        },
+                        limit: (count) => {
+                            limitState = count;
+                            return executor;
+                        },
+                        offset: (count) => {
+                            offsetState = count;
+                            return executor;
+                        },
+                        execute: async () => {
+                            // Delegate to adapter
+                            const results = await options.adapter.execute(table, expressionAst, {
+                                orderBy: Object.keys(orderByState).length > 0
+                                    ? orderByState
+                                    : undefined,
+                                limit: limitState,
+                                offset: offsetState
+                            });
+                            return results;
+                        }
+                    };
+                    return executor;
+                }
+            };
+        }
+    };
+}
+// Export all public APIs
+__exportStar(require("./parser"), exports);
+__exportStar(require("./security"), exports);

package/dist/parser/index.d.ts

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

package/dist/parser/index.js

@@ -0,0 +1,18 @@
+"use strict";
+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("./parser"), exports);

package/dist/parser/parser.d.ts

@@ -0,0 +1,51 @@
+import { IParserOptions, IQueryParser, QueryExpression } from './types';
+/**
+ * Error thrown when query parsing fails
+ */
+export declare class QueryParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Implementation of the QueryKit parser using Liqe
+ */
+export declare class QueryParser implements IQueryParser {
+    private options;
+    constructor(options?: IParserOptions);
+    /**
+     * Parse a query string into a QueryKit AST
+     */
+    parse(query: string): QueryExpression;
+    /**
+     * Validate a query string
+     */
+    validate(query: string): boolean;
+    /**
+     * Convert a Liqe AST node to a QueryKit expression
+     */
+    private convertLiqeAst;
+    /**
+     * Convert a Liqe logical operator to a QueryKit operator
+     */
+    private convertLogicalOperator;
+    /**
+     * Create a logical expression from Liqe nodes
+     */
+    private createLogicalExpression;
+    /**
+     * Create a comparison expression
+     */
+    private createComparisonExpression;
+    /**
+     * Convert a Liqe operator to a QueryKit operator
+     */
+    private convertLiqeOperator;
+    /**
+     * Convert a Liqe value to a QueryKit value
+     * Security: Strict type checking to prevent NoSQL injection via objects
+     */
+    private convertLiqeValue;
+    /**
+     * Normalize a field name based on parser options
+     */
+    private normalizeFieldName;
+}

package/dist/parser/parser.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryParser = exports.QueryParseError = void 0;
+const liqe_1 = require("liqe");
+/**
+ * Error thrown when query parsing fails
+ */
+class QueryParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'QueryParseError';
+    }
+}
+exports.QueryParseError = QueryParseError;
+/**
+ * Implementation of the QueryKit parser using Liqe
+ */
+class QueryParser {
+    constructor(options = {}) {
+        this.options = {
+            caseInsensitiveFields: options.caseInsensitiveFields ?? false,
+            fieldMappings: options.fieldMappings ?? {}
+        };
+    }
+    /**
+     * Parse a query string into a QueryKit AST
+     */
+    parse(query) {
+        try {
+            const liqeAst = (0, liqe_1.parse)(query);
+            return this.convertLiqeAst(liqeAst);
+        }
+        catch (error) {
+            throw new QueryParseError(`Failed to parse query: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Validate a query string
+     */
+    validate(query) {
+        try {
+            const ast = (0, liqe_1.parse)(query);
+            this.convertLiqeAst(ast);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Convert a Liqe AST node to a QueryKit expression
+     */
+    convertLiqeAst(node) {
+        if (!node || typeof node !== 'object') {
+            throw new QueryParseError('Invalid AST node');
+        }
+        switch (node.type) {
+            case 'LogicalExpression': {
+                const logicalNode = node;
+                const operator = logicalNode.operator.operator;
+                return this.createLogicalExpression(this.convertLogicalOperator(operator), logicalNode.left, logicalNode.right);
+            }
+            case 'UnaryOperator': {
+                const unaryNode = node;
+                return this.createLogicalExpression('NOT', unaryNode.operand);
+            }
+            case 'Tag': {
+                const tagNode = node;
+                const field = tagNode.field;
+                const expression = tagNode.expression;
+                if (!field || !expression) {
+                    throw new QueryParseError('Invalid field or expression in Tag node');
+                }
+                const fieldName = this.normalizeFieldName(field.name);
+                const operator = this.convertLiqeOperator(tagNode.operator.operator);
+                const value = this.convertLiqeValue(expression.value);
+                // Check for wildcard patterns in string values
+                if (operator === '==' && typeof value === 'string' && (value.includes('*') || value.includes('?'))) {
+                    return this.createComparisonExpression(fieldName, 'LIKE', value);
+                }
+                return this.createComparisonExpression(fieldName, operator, value);
+            }
+            case 'EmptyExpression':
+                if ('left' in node && node.left) {
+                    return this.convertLiqeAst(node.left);
+                }
+                throw new QueryParseError('Invalid empty expression');
+            case 'ParenthesizedExpression': {
+                const parenNode = node;
+                if (parenNode.expression) {
+                    return this.convertLiqeAst(parenNode.expression);
+                }
+                throw new QueryParseError('Invalid parenthesized expression');
+            }
+            default:
+                throw new QueryParseError(`Unsupported node type: ${node.type}`);
+        }
+    }
+    /**
+     * Convert a Liqe logical operator to a QueryKit operator
+     */
+    convertLogicalOperator(operator) {
+        switch (operator.toLowerCase()) {
+            case 'and':
+                return 'AND';
+            case 'or':
+                return 'OR';
+            case 'not':
+                return 'NOT';
+            default:
+                throw new QueryParseError(`Unsupported logical operator: ${operator}`);
+        }
+    }
+    /**
+     * Create a logical expression from Liqe nodes
+     */
+    createLogicalExpression(operator, left, right) {
+        return {
+            type: 'logical',
+            operator,
+            left: this.convertLiqeAst(left),
+            ...(right && { right: this.convertLiqeAst(right) })
+        };
+    }
+    /**
+     * Create a comparison expression
+     */
+    createComparisonExpression(field, operator, value) {
+        return {
+            type: 'comparison',
+            field,
+            operator,
+            value
+        };
+    }
+    /**
+     * Convert a Liqe operator to a QueryKit operator
+     */
+    convertLiqeOperator(operator) {
+        // Handle the case where operator is part of the value for comparison operators
+        if (operator === ':') {
+            return '==';
+        }
+        // Check if the operator is prefixed with a colon
+        const actualOperator = operator.startsWith(':') ? operator.substring(1) : operator;
+        // Map Liqe operators to QueryKit operators
+        const operatorMap = {
+            '=': '==',
+            '!=': '!=',
+            '>': '>',
+            '>=': '>=',
+            '<': '<',
+            '<=': '<=',
+            'in': 'IN',
+            'not in': 'NOT IN'
+        };
+        const queryKitOperator = operatorMap[actualOperator.toLowerCase()];
+        if (!queryKitOperator) {
+            throw new QueryParseError(`Unsupported operator: ${operator}`);
+        }
+        return queryKitOperator;
+    }
+    /**
+     * Convert a Liqe value to a QueryKit value
+     * Security: Strict type checking to prevent NoSQL injection via objects
+     */
+    convertLiqeValue(value) {
+        // Security fix: Strict type checking to prevent object injection
+        if (value === null) {
+            return null;
+        }
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            // Security fix: Recursively validate array elements
+            const validatedArray = value.map(item => {
+                if (typeof item === 'object' && item !== null) {
+                    throw new QueryParseError('Object values are not allowed in arrays');
+                }
+                return this.convertLiqeValue(item);
+            });
+            return validatedArray;
+        }
+        // Security fix: Reject all object types to prevent NoSQL injection
+        if (typeof value === 'object') {
+            throw new QueryParseError('Object values are not supported for security reasons');
+        }
+        throw new QueryParseError(`Unsupported value type: ${typeof value}`);
+    }
+    /**
+     * Normalize a field name based on parser options
+     */
+    normalizeFieldName(field) {
+        const normalizedField = this.options.caseInsensitiveFields
+            ? field.toLowerCase()
+            : field;
+        return this.options.fieldMappings[normalizedField] ?? normalizedField;
+    }
+}
+exports.QueryParser = QueryParser;

package/dist/parser/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Core AST types for QueryKit's parser
+ */
+/**
+ * Represents a comparison operator in a query expression
+ */
+export type ComparisonOperator = '==' | '!=' | '>' | '>=' | '<' | '<=' | 'IN' | 'NOT IN' | 'LIKE';
+/**
+ * Represents a logical operator in a query expression
+ */
+export type LogicalOperator = 'AND' | 'OR' | 'NOT';
+/**
+ * Represents a value that can be used in a query expression
+ */
+export type QueryValue = string | number | boolean | null | Array<string | number | boolean | null>;
+/**
+ * Represents a comparison expression node in the AST
+ */
+export interface IComparisonExpression {
+    type: 'comparison';
+    field: string;
+    operator: ComparisonOperator;
+    value: QueryValue;
+}
+/**
+ * Represents a logical expression node in the AST
+ */
+export interface ILogicalExpression {
+    type: 'logical';
+    operator: LogicalOperator;
+    left: QueryExpression;
+    right?: QueryExpression;
+}
+/**
+ * Represents any valid query expression node
+ */
+export type QueryExpression = IComparisonExpression | ILogicalExpression;
+/**
+ * Configuration options for the parser
+ */
+export interface IParserOptions {
+    /**
+     * Whether to allow case-insensitive field names
+     */
+    caseInsensitiveFields?: boolean;
+    /**
+     * Custom field name mappings
+     */
+    fieldMappings?: Record<string, string>;
+}
+/**
+ * Interface for the query parser
+ */
+export interface IQueryParser {
+    /**
+     * Parse a query string into an AST
+     * @param query The query string to parse
+     * @returns The parsed AST
+     * @throws {QueryParseError} If the query is invalid
+     */
+    parse(query: string): QueryExpression;
+    /**
+     * Validate a query string without fully parsing it
+     * @param query The query string to validate
+     * @returns true if the query is valid, false otherwise
+     */
+    validate(query: string): boolean;
+}

package/dist/parser/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Core AST types for QueryKit's parser
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/query/builder.d.ts

@@ -0,0 +1,61 @@
+import { QueryExpression } from '../parser/types';
+import { ComparisonOperator, IQueryBuilder, IQueryBuilderOptions, QueryField, QueryValue, SortDirection } from './types';
+/**
+ * Implementation of the type-safe query builder
+ */
+export declare class QueryBuilder<T> implements IQueryBuilder<T> {
+    private parser;
+    private expression;
+    private orderByClause;
+    private limitClause;
+    private offsetClause;
+    constructor(options?: IQueryBuilderOptions<T>);
+    /**
+     * Add a where clause to the query
+     */
+    where(queryString: string): IQueryBuilder<T>;
+    where(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+    /**
+     * Add an AND where clause to the query
+     */
+    andWhere(queryString: string): IQueryBuilder<T>;
+    andWhere(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+    /**
+     * Add an OR where clause to the query
+     */
+    orWhere(queryString: string): IQueryBuilder<T>;
+    orWhere(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+    /**
+     * Add a NOT where clause to the query
+     */
+    notWhere(queryString: string): IQueryBuilder<T>;
+    notWhere(field: QueryField<T>, operator: ComparisonOperator, value: QueryValue): IQueryBuilder<T>;
+    /**
+     * Add an order by clause to the query
+     */
+    orderBy(field: QueryField<T>, direction?: SortDirection): IQueryBuilder<T>;
+    /**
+     * Add a limit to the query
+     */
+    limit(count: number): IQueryBuilder<T>;
+    /**
+     * Add an offset to the query
+     */
+    offset(count: number): IQueryBuilder<T>;
+    /**
+     * Get the current query expression
+     */
+    getExpression(): QueryExpression;
+    /**
+     * Get the current query as a string
+     */
+    toString(): string;
+    /**
+     * Build a comparison expression
+     */
+    private buildComparison;
+    /**
+     * Format a value for use in a query
+     */
+    private formatValue;
+}