@gblikas/querykit 0.0.0

package/.cursor/BUGBOT.md

@@ -0,0 +1,21 @@
+# 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. 
+
+## Security focus areas
+
+- Validate user input in API endpoints
+- Check for SQL injection vulnerabilities in database queries
+- Ensure proper authentication on protected routes
+
+## Architecture patterns
+
+- Use dependency injection for services
+- Follow the repository pattern for data access
+- Implement proper error handling with custom error classes
+
+## Common issues
+
+- Memory leaks in React components (check useEffect cleanup)
+- Missing error boundaries in UI components
+- Inconsistent naming conventions (use camelCase for functions)

package/.cursor/rules/01-project-structure.mdc

@@ -0,0 +1,77 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# QueryKit Project Structure
+
+QueryKit is organized into several key architectural components, each with a specific responsibility. This guide outlines where different types of code should be located and how they relate to each other.
+
+## Core Components
+
+### Parser
+- Location: `src/parser`
+- Purpose: Core query parsing engine that converts QueryKit DSL expressions into structured internal format
+- Key files:
+  - Parser implementation
+  - AST type definitions
+  - Validation logic
+
+### Translators
+- Location: `src/translators`
+- Purpose: Convert parsed queries into target-specific formats
+- Each translator should be in its own subdirectory
+- Must implement the standard translator interface
+
+### Adapters
+- Location: `src/adapters`
+- Purpose: Connect QueryKit to external systems/libraries
+- Each adapter (e.g. Drizzle) has its own subdirectory
+- Must implement the standard adapter interface
+
+### CLI
+- Location: `src/cli`
+- Purpose: Command-line interface for QueryKit
+- Includes commands for:
+  - Query parsing/testing
+  - Query translation debugging
+  - Code generation utilities
+
+### Frontend Utilities
+- Location: `src/frontend`
+- Purpose: Browser-specific implementations and components
+- Includes:
+  - Query builder components
+  - Client-side filtering utilities
+  - Browser-optimized query parsing
+
+### Server Helpers
+- Location: `src/server`
+- Purpose: Server-side integration utilities
+- Includes:
+  - Middleware implementations
+  - Request parsing helpers
+  - Database integration utilities
+
+## Code Organization Guidelines
+
+1. Each major component should have its own directory
+2. Shared utilities go in `src/common`
+3. Types and interfaces should be in `types.ts` files within their relevant component
+4. Tests should be co-located with the code they test
+5. Examples should be in an `examples` directory at the root
+
+## TypeScript Guidelines
+
+1. Use strict TypeScript configuration
+2. Explicit return types on exported functions
+3. Prefer interfaces over type aliases for public APIs
+4. Use generics to ensure type safety across query operations
+
+## Testing Guidelines
+
+1. Jest for unit and integration tests
+2. Co-locate test files with implementation
+3. Use `.test.ts` or `.spec.ts` suffix
+4. Include both unit and integration tests
+5. Mock external dependencies appropriately

package/.cursor/rules/02-typescript-standards.mdc

@@ -0,0 +1,105 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# TypeScript Coding Standards
+
+## Basic Principles
+
+1. Use English for all code and documentation
+2. Always declare explicit types
+3. Document public APIs with JSDoc
+4. One export per file
+5. Avoid blank lines within functions
+6. Follow SOLID principles (see `05-solid-principles.mdc`)
+
+## Naming Conventions
+
+### Case Styles
+- `PascalCase` for:
+  - Classes
+  - Interfaces
+  - Type aliases
+  - Enums
+- `camelCase` for:
+  - Variables
+  - Functions
+  - Methods
+  - Properties
+- `kebab-case` for:
+  - File names
+  - Directory names
+- `UPPERCASE` for:
+  - Constants
+  - Environment variables
+- `I` prefix for interfaces (e.g., `ITranslator`)
+
+### Naming Rules
+1. Start boolean variables with verbs:
+   - `isLoading`
+   - `hasError`
+   - `canDelete`
+2. Start functions with verbs
+3. Use complete words (no abbreviations except standard ones)
+   - Allowed: `API`, `URL`, `i` (loop), `err`, `ctx`, `req`, `res`
+4. Interface names should describe capabilities
+
+## Function Guidelines
+
+1. Keep functions short (< 20 instructions)
+2. Single responsibility principle
+3. Use early returns to avoid nesting
+4. Prefer higher-order functions (`map`, `filter`, `reduce`)
+5. Use default parameters instead of null checks
+6. Follow RO-RO (Receive Object, Return Object) pattern
+7. Maintain single level of abstraction
+8. Design for extension (OCP)
+
+## Interface and Class Design
+
+1. Program to interfaces, not implementations
+2. Keep interfaces focused and cohesive (ISP)
+3. Use composition over inheritance
+4. Implement dependency injection (DIP)
+5. Ensure proper interface segregation
+6. Make base classes substitutable (LSP)
+
+## Type Safety
+
+1. Avoid `any` type
+2. Create specific types/interfaces
+3. Use generics for reusable components
+4. Prefer `unknown` over `any` when type is uncertain
+5. Use union types for finite possibilities
+6. Leverage TypeScript's strict mode
+
+## Error Handling
+
+1. Use typed errors
+2. Prefer error objects over strings
+3. Handle async errors with try/catch
+4. Document error cases in JSDoc
+5. Create specific error types for different cases
+
+## Code Organization
+
+1. Group related types together
+2. Export types from dedicated type files
+3. Keep circular dependencies in check
+4. Use barrel exports for public APIs
+5. Separate interfaces from implementations
+6. Use dependency injection containers where appropriate
+
+## Documentation
+
+1. JSDoc for all public APIs
+2. Include example usage in docs
+3. Document generic type parameters
+4. Note any side effects
+5. Specify error cases and conditions
+6. Document interface contracts and invariants
+
+## Additional Context
+
+1. Use pnpm 

package/.cursor/rules/03-testing-standards.mdc

@@ -0,0 +1,78 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Testing Standards
+
+## Test Organization
+
+1. Co-locate tests with source files
+2. Use descriptive test file names:
+   - `[feature].test.ts`
+   - `[feature].spec.ts`
+3. Group related tests in describe blocks
+4. Use clear test case descriptions
+
+## Test Structure
+
+### Unit Tests
+1. Follow Arrange-Act-Assert pattern
+2. One assertion per test when possible
+3. Clear setup and teardown
+4. Mock external dependencies
+
+### Integration Tests
+1. Test component interactions
+2. Focus on public APIs
+3. Minimize mocking where possible
+4. Test error cases and edge conditions
+
+## Naming Conventions
+
+1. Test variables:
+   - `inputX` for test inputs
+   - `expectedX` for expected results
+   - `actualX` for actual results
+   - `mockX` for mocks
+2. Test descriptions:
+   - Should describe the scenario
+   - Include expected behavior
+   - Mention important conditions
+
+## Test Coverage
+
+1. Required coverage:
+   - Public APIs: 100%
+   - Internal implementation: 80%
+   - Edge cases and error conditions
+2. Types of tests needed:
+   - Unit tests for individual components
+   - Integration tests for component interaction
+   - E2E tests for critical paths
+
+## Mocking Guidelines
+
+1. Mock external dependencies
+2. Use Jest mock functions
+3. Clear mock setup and verification
+4. Reset mocks between tests
+5. Document mock behavior
+
+## Best Practices
+
+1. Keep tests focused and simple
+2. Avoid test interdependence
+3. Clean up test resources
+4. Use appropriate assertions
+5. Test both success and failure cases
+6. Include performance tests where relevant
+7. Attempt feature-first development
+
+## Test Data
+
+1. Use factories for test data
+2. Keep test data minimal
+3. Make test data intention clear
+4. Avoid sharing mutable test data
+5. Use meaningful test values

package/.cursor/rules/04-query-language.mdc

@@ -0,0 +1,79 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Query Language Design Principles
+
+## Core Concepts
+
+1. QueryKit DSL should be:
+   - Readable and intuitive
+   - Consistent across environments
+   - Type-safe
+   - Extensible
+
+## Query Structure
+
+### Filtering
+1. Basic operators:
+   - Comparison: `==`, `!=`, `>`, `>=`, `<`, `<=`
+   - Logical: `&&`, `||`, `!`
+2. Complex operations:
+   - String matching
+   - Array operations
+   - Nested property access
+
+### Sorting
+1. Sort syntax:
+   - Single field: `field ASC|DESC`
+   - Multiple fields: `field1 ASC, field2 DESC`
+2. Sort priorities respected in order
+
+## Type Safety
+
+1. All queries must be type-safe
+2. Runtime validation must match compile-time types
+3. Clear error messages for type mismatches
+4. Generic type parameters for reusability
+
+## Parser Implementation
+
+1. Clear separation of:
+   - Lexical analysis
+   - Syntax parsing
+   - Semantic validation
+2. Detailed error reporting
+3. Performance optimization
+4. Extensible grammar
+
+## Translation Layer
+
+1. Consistent translation interface
+2. Support for multiple targets:
+   - SQL (via Drizzle)
+   - In-memory filtering
+   - Future adapters
+3. Optimization opportunities
+4. Type preservation
+
+## Error Handling
+
+1. Clear error messages
+2. Validation at parse time
+3. Runtime safety checks
+4. Debugging support
+
+## Security
+
+1. Input validation
+2. Query size limits
+3. Resource usage controls
+4. Safe evaluation
+
+## Performance
+
+1. Efficient parsing
+2. Optimized translation
+3. Caching where appropriate
+4. Resource management

package/.cursor/rules/05-solid-principles.mdc

@@ -0,0 +1,118 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# SOLID Principles in QueryKit
+
+## Single Responsibility Principle (SRP)
+
+1. Each module should have one reason to change
+2. Implementation guidelines:
+   - Parser only handles parsing
+   - Translators only handle translation
+   - Adapters only handle integration
+3. Examples:
+   - `Parser` class focuses only on converting DSL to AST
+   - `DrizzleTranslator` only handles Drizzle-specific translation
+   - `ValidationService` only handles query validation
+
+## Open/Closed Principle (OCP)
+
+1. Software entities should be open for extension but closed for modification
+2. Implementation guidelines:
+   - Use interfaces for core components
+   - Implement new features through extension
+   - Avoid modifying existing, tested code
+3. Examples:
+   - New query operators via operator registry
+   - Custom translators via translator interface
+   - New adapters via adapter interface
+
+## Liskov Substitution Principle (LSP)
+
+1. Subtypes must be substitutable for their base types
+2. Implementation guidelines:
+   - Maintain contract consistency
+   - Preserve invariants
+   - Follow interface specifications
+3. Examples:
+   - All translators must preserve query semantics
+   - Custom operators must maintain type safety
+   - Adapters must handle all valid queries
+
+## Interface Segregation Principle (ISP)
+
+1. Clients should not depend on interfaces they don't use
+2. Implementation guidelines:
+   - Split large interfaces
+   - Create focused, cohesive interfaces
+   - Allow selective implementation
+3. Examples:
+   ```typescript
+   // Instead of one large interface:
+   interface QueryProcessor {
+     parse(): AST;
+     validate(): boolean;
+     translate(): string;
+   }
+   
+   // Split into focused interfaces:
+   interface Parser {
+     parse(): AST;
+   }
+   
+   interface Validator {
+     validate(): boolean;
+   }
+   
+   interface Translator {
+     translate(): string;
+   }
+   ```
+
+## Dependency Inversion Principle (DIP)
+
+1. High-level modules should not depend on low-level modules
+2. Implementation guidelines:
+   - Depend on abstractions
+   - Use dependency injection
+   - Define clear interfaces
+3. Examples:
+   ```typescript
+   // Instead of:
+   class QueryExecutor {
+     private drizzleTranslator = new DrizzleTranslator();
+   }
+   
+   // Use:
+   class QueryExecutor {
+     constructor(private translator: ITranslator) {}
+   }
+   ```
+
+## Practical Application
+
+### Component Design
+1. Create interfaces before implementations
+2. Use abstract factories for component creation
+3. Implement dependency injection
+4. Design for extensibility
+
+### Code Organization
+1. Group related interfaces together
+2. Separate interface definitions from implementations
+3. Use meaningful namespaces
+4. Maintain clear dependency hierarchy
+
+### Testing
+1. Test against interfaces, not implementations
+2. Use mock implementations for testing
+3. Verify LSP compliance
+4. Test extension points
+
+### Documentation
+1. Document interface contracts
+2. Specify invariants
+3. Explain extension points
+4. Provide implementation examples