@gblikas/querykit 0.0.0

package/README.md

@@ -0,0 +1,237 @@
+# QueryKit
+
+QueryKit is a modern query toolkit for Lucene-style search, designed to give developers a head-start for dynamic search. QueryKit simplifies how you build and execute fielded searchs across different databases and ORMs. It provides a unified, intuitive SDK for filtering, sorting, and transforming data, and handles the heavy lifting of parsing and translating those queries to your data source. 
+
+## What Does QueryKit Do?
+
+QueryKit allows developers to define queries in a high-level, readable format and then run those queries anywhere (in the browser, on the server, or via CLI). Instead of writing different query logic for each layer of your stack, you can use QueryKit's consistent API to:
+
+- **Filter and sort data with a Lucene-like query language** – For example, `status:done AND in:todos`. 
+
+- **Translate high-level queries to concrete implementations** – QueryKit takes your schema definition and converts it into the appropriate form for the environment. 
+
+- **Unify front‑end and back‑end filtering logic** – The same QueryKit query can be run in a front-end app for client-side filtering or on a server for database queries. This ensures consistency in how data is filtered across your application.
+
+## Quick Start
+
+Below are various examples of how to use QueryKit.
+
+**Drizzle ORM**
+
+```typescript
+
+// schema.ts
+import { serial, text, pgTable } from 'drizzle-orm/pg-core';
+import { type InferSelectModel, type InferInsertModel } from 'drizzle-orm'
+
+const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+  status: text('status').notNull().default('draft')
+});
+
+type SelectUser = InferSelectModel<typeof users>;
+
+// example.ts
+import { SelectUser } from './schema';
+import { createQueryKit } from 'querykit';
+import { drizzleAdapter } from 'querykit/adapters/drizzle';
+
+// Create a QueryKit instance with Drizzle adapter
+const qk = createQueryKit({
+  adapter: drizzleAdapter,
+  schema: { users },
+});
+
+// Build a query using the Lucene-like query syntax
+const query = qk.query('users')
+  .where('status:done AND name:"John *"')
+  .orderBy('name', 'asc')
+  .limit(10);
+
+// Execute the query against your database
+const results = await query.execute();
+```
+
+## Query Syntax
+
+QueryKit uses Liqe Query Language (LQL), which is a Lucene-like syntax for filtering data:
+
+```
+# Basic field queries
+status:active         # Field equals value (case insensitive)
+status:"Active"       # Field equals value (case sensitive)
+
+# Comparison operators
+priority:>2               # Greater than
+priority:>=2              # Greater than or equal
+priority:<2               # Less than
+priority:<=2              # Less than or equal
+priority:=2               # Exact equals
+
+# Ranges
+dueDate:[2023-01-01 TO 2023-01-31]      # Inclusive range
+dueDate:{2023-01-01 TO 2023-01-31}      # Exclusive range
+
+# Pattern matching
+name:/Todo.*/         # Regular expression
+title:intro*          # Wildcard matching
+
+# Boolean operators
+status:active AND priority:>2     # AND operator
+status:active OR status:pending   # OR operator
+NOT expired:true      # NOT operator
+-expired:true         # Alternative NOT syntax
+
+# Grouping
+(status:active OR status:pending) AND priority:<3
+
+# Implicit AND (space between expressions)
+status:active priority:>2
+```
+
+## Installation
+
+```bash
+npm install querykit
+```
+
+## Dependencies
+
+QueryKit leverages several key dependencies to provide its functionality:
+
+- [**Liqe**](https://github.com/gajus/liqe): A lightweight and performant Lucene-like parser, serializer, and search engine. QueryKit uses Liqe for parsing the query syntax into an abstract syntax tree (AST) that can then be translated to various target languages.
+
+- [**Drizzle ORM**](https://github.com/drizzle-team/drizzle-orm): A TypeScript ORM that's used for SQL database interactions. QueryKit's Drizzle adapter translates queries into Drizzle ORM queries.
+
+Additional dependencies will be added as the project evolves.
+
+## Security Features
+
+QueryKit provides configurable security guardrails to protect your database from potentially harmful queries while maintaining flexibility. These features can be configured during initialization:
+
+> **IMPORTANT DISCLAIMER**: While QueryKit provides guardrails to help protect against common query-related vulnerabilities, it is not a comprehensive security solution. These features are provided as helpful tools, not guarantees. You are still responsible for implementing proper authentication, authorization, and other security measures in your application. QueryKit does not guarantee protection against all forms of database attacks or query exploits.
+
+```typescript
+import { createQueryKit } from 'querykit';
+import { drizzleAdapter } from 'querykit/adapters/drizzle';
+
+const qk = createQueryKit({
+  adapter: drizzleAdapter,
+  schema: { users },
+  security: {
+    // Field restrictions
+    allowedFields: ['name', 'email', 'priority', 'status'], // Only these fields can be queried
+    denyFields: ['password', 'secretKey'],            // These fields can never be queried
+    
+    // Query complexity limits
+    maxQueryDepth: 5,          // Maximum nesting level of expressions
+    maxClauseCount: 20,        // Maximum number of clauses (AND/OR operations)
+    
+    // Resource protection
+    defaultLimit: 100,         // Default result limit if none specified
+    maxLimit: 1000,            // Maximum allowed limit for pagination
+    
+    // Value sanitization
+    maxValueLength: 100,       // Maximum string length for query values
+    sanitizeWildcards: true,   // Prevent regex DoS with wildcards in LIKE queries
+    
+    // Performance safeguards
+    queryTimeout: 5000,        // Timeout in milliseconds for query execution
+  }
+});
+```
+
+By default, QueryKit applies sensible security defaults even without explicit configuration:
+
+```typescript
+// Default security configuration
+const DEFAULT_SECURITY = {
+  // Field restrictions - by default, all schema fields are allowed
+  allowedFields: [],           // Empty means "use schema fields"
+  denyFields: [],              // Empty means no denied fields
+  
+  // Query complexity limits
+  maxQueryDepth: 10,           // Maximum nesting level of expressions
+  maxClauseCount: 50,          // Maximum number of clauses (AND/OR operations)
+  
+  // Resource protection
+  defaultLimit: 100,           // Default result limit if none specified
+  maxLimit: 1000,              // Maximum allowed limit for pagination
+  
+  // Value sanitization
+  maxValueLength: 1000,        // Maximum string length for query values
+  sanitizeWildcards: true,     // Prevent regex DoS with wildcards in LIKE queries
+  
+  // Performance safeguards
+  queryTimeout: 30000,         // 30 second timeout by default
+}
+```
+
+Security configurations can be stored in a separate file and imported:
+
+```typescript
+// security-config.json
+{
+  "allowedFields": ["name", "email", "priority", "status"],
+  "maxQueryDepth": 5,
+  "maxClauseCount": 20,
+  "defaultLimit": 100
+}
+
+// In your app
+import securityConfig from './security-config.json';
+
+const qk = createQueryKit({
+  adapter: drizzleAdapter,
+  schema: { users },
+  security: securityConfig
+});
+```
+
+### Additional Security Recommendations
+
+When using QueryKit in production, consider these additional security practices:
+
+1. **Implement Authentication and Authorization**: QueryKit doesn't handle auth - integrate with your existing auth system.
+2. **Use Rate Limiting**: Limit the number of queries a user can make in a given time period.
+3. **Audit Logging**: Log all queries for security monitoring and debugging.
+4. **Field-Level Access Control**: Use dynamic allowedFields based on user roles/permissions.
+5. **Separate Query Context**: Consider separate QueryKit instances with different security settings for different contexts (admin vs. user).
+
+## Roadmap
+
+### Core Parsing Engine and DSL
+- [x] Implement Lucene-style query syntax parser using Liqe
+- [x] Create type-safe query building API
+- [x] Develop internal AST representation
+- [x] Implement consistent syntax for logical operators (AND, OR, NOT)
+- [x] Support standard comparison operators (==, !=, >, >=, <, <=)
+
+### First Adapters
+- [x] Drizzle ORM integration
+- [x] Implement SQL translation layer
+- [ ] In-memory JavaScript filtering
+- [x] Query validation and error handling
+- [x] Support for schema-aware queries
+
+### Advanced Features
+- [ ] CLI tools for testing and debugging
+- [x] Performance optimizations for SQL generation
+- [x] Support for complex nested expressions
+- [ ] Custom function support
+- [ ] Pagination helpers
+
+### Ecosystem Expansion
+- [ ] Frontend query builder components
+- [ ] Additional ORM adapters
+- [ ] Server middleware for Express/Fastify
+- [ ] TypeScript SDK generation
+
+## Contributing
+
+See the [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to get started.
+
+## License
+
+This project is licensed under the GPL License - see the [LICENSE](LICENSE) file for details. 

package/dist/adapters/drizzle/index.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Drizzle ORM Adapter for QueryKit
+ *
+ * This adapter connects QueryKit to Drizzle ORM for database queries.
+ */
+import { IAdapter, IAdapterOptions, IQueryExecutionOptions } from '../types';
+import { QueryExpression } from '../../parser/types';
+import { SQL } from 'drizzle-orm';
+import { QueryKit } from '../../index';
+/**
+ * Type for Drizzle ORM database instance
+ */
+export interface IDrizzleDatabase {
+    select: () => {
+        from: (table: unknown) => IDrizzleQueryBuilder;
+    };
+}
+/**
+ * Type for Drizzle query builder
+ */
+export interface IDrizzleQueryBuilder {
+    where: (condition: SQL) => IDrizzleQueryBuilder;
+    orderBy: (...clauses: SQL[]) => IDrizzleQueryBuilder;
+    limit: (limit: number) => IDrizzleQueryBuilder;
+    offset: (offset: number) => IDrizzleQueryBuilder;
+    [Symbol.toStringTag]: string;
+    then<TResult1 = unknown, TResult2 = never>(onfulfilled?: ((value: unknown[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
+/**
+ * Options specific to the Drizzle adapter
+ */
+export interface IDrizzleAdapterOptions<TSchema extends Record<string, unknown> = Record<string, unknown>> extends IAdapterOptions {
+    /**
+     * The Drizzle ORM database instance
+     */
+    db: IDrizzleDatabase | unknown;
+    /**
+     * Schema information with Drizzle table definitions
+     */
+    schema: TSchema;
+    /**
+     * Whether to normalize field names (e.g., lowercase them)
+     */
+    normalizeFieldNames?: boolean;
+}
+/**
+ * Options for Drizzle query execution
+ */
+export interface IDrizzleQueryExecutionOptions extends IQueryExecutionOptions {
+    /**
+     * Sort fields in the format: { field: 'asc' | 'desc' }
+     */
+    orderBy?: Record<string, 'asc' | 'desc'>;
+    /**
+     * Maximum number of records to return
+     */
+    limit?: number;
+    /**
+     * Number of records to skip
+     */
+    offset?: number;
+}
+/**
+ * Error thrown when adapter operations fail
+ */
+export declare class DrizzleAdapterError extends Error {
+    constructor(message: string);
+}
+/**
+ * Adapter for Drizzle ORM
+ */
+export declare class DrizzleAdapter<TSchema extends Record<string, unknown> = Record<string, unknown>> implements IAdapter<IDrizzleAdapterOptions<TSchema>> {
+    private db;
+    private schema;
+    private translator;
+    private initialized;
+    /**
+     * Optionally initialize via constructor for convenience
+     */
+    constructor(options?: IDrizzleAdapterOptions<TSchema>);
+    /**
+     * Initialize the adapter with options
+     */
+    initialize(options: IDrizzleAdapterOptions<TSchema>): void;
+    /**
+     * Execute a QueryKit expression using Drizzle ORM
+     */
+    execute<TResult = unknown>(tableName: string, expression: QueryExpression, options?: IDrizzleQueryExecutionOptions): Promise<TResult[]>;
+    /**
+     * Check if an expression can be executed by this adapter
+     */
+    canExecute(expression: QueryExpression): boolean;
+    /**
+     * Get a table from the schema
+     */
+    private getTable;
+    /**
+     * Get a field from the schema
+     */
+    private getSchemaField;
+    /**
+     * Ensure the adapter is initialized
+     */
+    private ensureInitialized;
+}
+/**
+ * Convenience factory to create a pre-initialized Drizzle adapter
+ */
+export declare function drizzleAdapter<TSchema extends Record<string, unknown>>(options: IDrizzleAdapterOptions<TSchema>): DrizzleAdapter<TSchema>;
+export type RowTypeFromDrizzleTable<TTable> = TTable extends {
+    $inferSelect: infer R;
+} ? R : unknown;
+export type RowMapFromDrizzleSchema<TSchema extends Record<string, unknown>> = {
+    [K in keyof TSchema]: RowTypeFromDrizzleTable<TSchema[K]>;
+};
+export declare function createDrizzleQueryKit<TSchema extends Record<string, object>>(args: {
+    db: unknown;
+    schema: TSchema;
+    normalizeFieldNames?: boolean;
+    fieldMappings?: Record<string, string>;
+    security?: import('../../security').ISecurityOptions;
+}): QueryKit<TSchema, RowMapFromDrizzleSchema<TSchema>>;

package/dist/adapters/drizzle/index.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Drizzle ORM Adapter for QueryKit
+ *
+ * This adapter connects QueryKit to Drizzle ORM for database queries.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DrizzleAdapter = exports.DrizzleAdapterError = void 0;
+exports.drizzleAdapter = drizzleAdapter;
+exports.createDrizzleQueryKit = createDrizzleQueryKit;
+const drizzle_1 = require("../../translators/drizzle");
+const drizzle_orm_1 = require("drizzle-orm");
+const index_1 = require("../../index");
+/**
+ * Error thrown when adapter operations fail
+ */
+class DrizzleAdapterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DrizzleAdapterError';
+    }
+}
+exports.DrizzleAdapterError = DrizzleAdapterError;
+/**
+ * Adapter for Drizzle ORM
+ */
+class DrizzleAdapter {
+    /**
+     * Optionally initialize via constructor for convenience
+     */
+    constructor(options) {
+        this.initialized = false;
+        if (options) {
+            this.initialize(options);
+        }
+    }
+    /**
+     * Initialize the adapter with options
+     */
+    initialize(options) {
+        if (!options.db) {
+            throw new DrizzleAdapterError('Drizzle db instance is required');
+        }
+        if (!options.schema) {
+            throw new DrizzleAdapterError('Schema definition is required');
+        }
+        this.db = options.db;
+        this.schema = options.schema;
+        this.translator = new drizzle_1.DrizzleTranslator({
+            normalizeFieldNames: options.normalizeFieldNames,
+            fieldMappings: options.fieldMappings,
+            schema: options.schema
+        });
+        this.initialized = true;
+    }
+    /**
+     * Execute a QueryKit expression using Drizzle ORM
+     */
+    async execute(tableName, expression, options) {
+        this.ensureInitialized();
+        const table = this.getTable(tableName);
+        if (!table) {
+            throw new DrizzleAdapterError(`Table ${tableName} not found in schema`);
+        }
+        try {
+            // Start with a base query
+            let query = this.db.select().from(table);
+            // Add where condition if expression is provided
+            if (expression) {
+                const condition = this.translator.translate(expression);
+                query = query.where(condition);
+            }
+            // Add ordering if specified
+            if (options?.orderBy) {
+                const orderClauses = [];
+                Object.entries(options.orderBy).forEach(([field, direction]) => {
+                    // Try to find the field in the schema
+                    const schemaField = this.getSchemaField(tableName, field);
+                    if (schemaField) {
+                        // If field exists in schema, use it directly
+                        orderClauses.push(direction === 'asc' ? (0, drizzle_orm_1.asc)(schemaField) : (0, drizzle_orm_1.desc)(schemaField));
+                    }
+                    else {
+                        // Otherwise use raw SQL
+                        orderClauses.push((0, drizzle_orm_1.sql) `${drizzle_orm_1.sql.identifier(field)} ${drizzle_orm_1.sql.raw(direction.toUpperCase())}`);
+                    }
+                });
+                if (orderClauses.length > 0) {
+                    query = query.orderBy(...orderClauses);
+                }
+            }
+            // Add limit if specified
+            if (options?.limit !== undefined) {
+                query = query.limit(options.limit);
+            }
+            // Add offset if specified
+            if (options?.offset !== undefined) {
+                query = query.offset(options.offset);
+            }
+            // Execute the query
+            const result = await query;
+            return result;
+        }
+        catch (error) {
+            throw new DrizzleAdapterError(`Failed to execute query: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Check if an expression can be executed by this adapter
+     */
+    canExecute(expression) {
+        try {
+            this.ensureInitialized();
+            return this.translator.canTranslate(expression);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get a table from the schema
+     */
+    getTable(tableName) {
+        return this.schema[tableName];
+    }
+    /**
+     * Get a field from the schema
+     */
+    getSchemaField(tableName, fieldName) {
+        const schemaAsColumns = this.schema;
+        const table = schemaAsColumns[tableName];
+        if (table && fieldName in table) {
+            return table[fieldName];
+        }
+        return null;
+    }
+    /**
+     * Ensure the adapter is initialized
+     */
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new DrizzleAdapterError('Adapter has not been initialized');
+        }
+    }
+}
+exports.DrizzleAdapter = DrizzleAdapter;
+/**
+ * Convenience factory to create a pre-initialized Drizzle adapter
+ */
+function drizzleAdapter(options) {
+    return new DrizzleAdapter(options);
+}
+function createDrizzleQueryKit(args) {
+    const adapter = new DrizzleAdapter();
+    adapter.initialize({
+        db: args.db,
+        schema: args.schema,
+        normalizeFieldNames: args.normalizeFieldNames,
+        fieldMappings: args.fieldMappings
+    });
+    return (0, index_1.createQueryKit)({
+        adapter,
+        schema: args.schema,
+        security: args.security
+    });
+}

package/dist/adapters/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * QueryKit Adapters
+ *
+ * Exports all adapter implementations for different database systems.
+ */
+export * from './types';
+export * from './drizzle';

package/dist/adapters/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * QueryKit Adapters
+ *
+ * Exports all adapter implementations for different database systems.
+ */
+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 });
+// Export base types
+__exportStar(require("./types"), exports);
+// Export Drizzle adapter
+__exportStar(require("./drizzle"), exports);

package/dist/adapters/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * QueryKit Adapter Types
+ *
+ * These are the core interfaces for adapters, which connect QueryKit to
+ * external systems or libraries like Drizzle ORM.
+ */
+import { QueryExpression } from '../parser/types';
+/**
+ * Options for configuring an adapter
+ */
+export interface IAdapterOptions {
+    /**
+     * Schema information for type safety and validation
+     */
+    schema?: Record<string, unknown>;
+    /**
+     * Field mappings from QueryKit fields to target database fields
+     */
+    fieldMappings?: Record<string, string>;
+}
+/**
+ * Options for a query execution
+ */
+export interface IQueryExecutionOptions {
+    /**
+     * Optional transaction object
+     */
+    transaction?: unknown;
+    /**
+     * Additional parameters specific to the adapter
+     */
+    [key: string]: unknown;
+}
+/**
+ * Interface for a query adapter
+ */
+export interface IAdapter<TOptions extends IAdapterOptions = IAdapterOptions> {
+    /**
+     * Initialize the adapter with options
+     *
+     * @param options Adapter-specific options
+     */
+    initialize(options: TOptions): void;
+    /**
+     * Execute a QueryKit expression and return results
+     *
+     * @param tableName The table/collection name to query
+     * @param expression The QueryKit expression to execute
+     * @param options Optional execution options
+     * @returns The query results
+     */
+    execute<T = unknown>(tableName: string, expression: QueryExpression, options?: IQueryExecutionOptions): Promise<T[]>;
+    /**
+     * Check if an expression can be executed by this adapter
+     *
+     * @param expression The QueryKit expression to check
+     * @returns true if the expression can be executed, false otherwise
+     */
+    canExecute(expression: QueryExpression): boolean;
+}

package/dist/adapters/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * QueryKit Adapter Types
+ *
+ * These are the core interfaces for adapters, which connect QueryKit to
+ * external systems or libraries like Drizzle ORM.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });