hazo_connect 2.2.0 → 2.3.2

package/docs/techdoc.md

@@ -0,0 +1,824 @@
+# Hazo Connect - Technical Documentation
+
+This document provides technical details about the internal architecture, file structure, services, key assumptions, and dependencies of the `hazo_connect` package. It is intended for developers maintaining or extending the codebase.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [File Structure](#file-structure)
+- [Entry Points](#entry-points)
+- [Core Components](#core-components)
+  - [Factory](#factory)
+  - [Query Builder](#query-builder)
+  - [Adapters](#adapters)
+  - [Helpers](#helpers)
+- [SQLite Subsystem](#sqlite-subsystem)
+  - [SQLite Adapter](#sqlite-adapter)
+  - [Query Translator](#query-translator)
+  - [Admin Service](#admin-service)
+- [Next.js Integration](#nextjs-integration)
+- [Utility Modules](#utility-modules)
+- [Key Assumptions](#key-assumptions)
+- [Dependencies](#dependencies)
+- [Build Process](#build-process)
+- [Testing Strategy](#testing-strategy)
+- [Extension Points](#extension-points)
+
+---
+
+## Overview
+
+`hazo_connect` is a database abstraction layer that provides a unified interface for interacting with different database backends. It follows the adapter pattern, where each database type (PostgREST, SQLite, Supabase, File) has its own adapter implementation that conforms to the `HazoConnectAdapter` interface.
+
+### Design Principles
+
+1. **Zero Dependencies in Core**: The core types and query builder have no external dependencies
+2. **Dependency Injection**: Logger and configuration are injected, not imported
+3. **Server-Side Only**: Runtime guards prevent client-side usage
+4. **Type Safety**: Full TypeScript support with strict typing
+5. **Adapter Pattern**: Each database type implements a common interface
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           Application Layer                              │
+│  (Next.js API Routes, Server Components, Server Actions)                │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Entry Points                                     │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
+│  │  /server    │  │  /nextjs    │  │  /nextjs/   │  │    /ui      │    │
+│  │  (runtime)  │  │  (helpers)  │  │   setup     │  │  (types)    │    │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          Core Layer                                      │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐         │
+│  │    Factory      │  │  Query Builder  │  │    Helpers      │         │
+│  │ createHazoConnect│ │  QueryBuilder   │  │ createCrudService│        │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘         │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Adapter Layer                                    │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
+│  │ PostgrestAd │  │ SqliteAdapt │  │ SupabaseAd  │  │  FileAdapt  │    │
+│  │   apter     │  │    er       │  │   apter     │  │    er       │    │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
+│         │                │                │                │            │
+│         └────────────────┴────────────────┴────────────────┘            │
+│                          extends BaseAdapter                             │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                       Database Layer                                     │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
+│  │  PostgREST  │  │  sql.js     │  │  Supabase   │  │ File System │    │
+│  │    API      │  │  (WASM)     │  │    API      │  │             │    │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## File Structure
+
+```
+src/lib/
+├── index.ts                    # Main entry point (types only)
+├── types.ts                    # Core TypeScript interfaces and types
+├── factory.ts                  # Factory function to create adapters
+├── query-builder.ts            # Query builder with fluent API
+├── helpers.ts                  # CRUD service and query helpers
+├── README.md                   # Library documentation
+│
+├── adapters/                   # Database adapter implementations
+│   ├── base-adapter.ts         # Abstract base class for adapters
+│   ├── postgrest-adapter.ts    # PostgREST API adapter
+│   ├── sqlite-adapter.ts       # SQLite adapter (sql.js)
+│   ├── supabase-adapter.ts     # Supabase adapter (stub)
+│   └── file-adapter.ts         # File system adapter (stub)
+│
+├── server/                     # Server-only entry point
+│   └── index.ts                # Exports with 'use server' directive
+│
+├── nextjs/                     # Next.js-specific helpers
+│   ├── index.ts                # Main Next.js exports
+│   ├── api-route-helpers.ts    # API route handler utilities
+│   ├── setup-helpers.ts        # Environment-based setup, singleton
+│   └── server-only.ts          # Server-only guard utilities
+│
+├── sqlite/                     # SQLite-specific modules
+│   ├── admin-service.ts        # Admin UI service functions
+│   └── query-translator.ts     # QueryBuilder to SQL translator
+│
+├── ui/                         # UI-safe entry point
+│   └── index.ts                # Type-only exports for client components
+│
+├── utils/                      # Utility modules
+│   ├── config-validator.ts     # Configuration validation
+│   ├── sqlite-utils.ts         # SQLite helper functions
+│   ├── wasm-resolver.ts        # WASM file resolution
+│   └── where-builder.ts        # WHERE clause builder
+│
+└── __tests__/                  # Unit tests
+    ├── factory.test.ts
+    ├── postgrest_adapter.test.ts
+    ├── query_builder.test.ts
+    └── sqlite_adapter.test.ts
+
+app/                            # Next.js app directory (Admin UI)
+└── hazo_connect/
+    ├── api/sqlite/             # Admin API routes
+    │   ├── data/route.ts       # CRUD operations
+    │   ├── schema/route.ts     # Schema retrieval
+    │   └── tables/route.ts     # Table listing
+    └── sqlite_admin/           # Admin UI pages
+        ├── page.tsx            # Server component
+        └── sqlite-admin-client.tsx  # Client component
+
+docs/                           # Documentation
+├── examples/                   # Code examples
+├── migration-guide.md
+├── nextjs-setup.md
+├── troubleshooting.md
+└── types.md
+
+tests/                          # Integration tests
+└── integration/
+    ├── postgrest.integration.test.ts
+    ├── sqlite.integration.test.ts
+    └── sqlite-singleton.test.ts
+```
+
+---
+
+## Entry Points
+
+### `hazo_connect` (Main)
+
+**File:** `src/lib/index.ts`
+
+Exports types only. Safe for client-side imports.
+
+```typescript
+export type { HazoConnectConfig, HazoConnectAdapter, Logger, ... }
+```
+
+### `hazo_connect/server`
+
+**File:** `src/lib/server/index.ts`
+
+Server-side runtime exports with `'use server'` directive.
+
+```typescript
+export { createHazoConnect, QueryBuilder, createCrudService, ... }
+export type { HazoConnectConfig, CrudService, ... }
+```
+
+**Runtime Guard:** Throws error if imported in browser environment.
+
+### `hazo_connect/nextjs`
+
+**File:** `src/lib/nextjs/index.ts`
+
+Next.js-specific helpers for API routes.
+
+```typescript
+export { createApiRouteHandler, getServerHazoConnect }
+```
+
+### `hazo_connect/nextjs/setup`
+
+**File:** `src/lib/nextjs/setup-helpers.ts`
+
+Environment-based configuration and singleton pattern.
+
+```typescript
+export { createHazoConnectFromEnv, getHazoConnectSingleton }
+```
+
+### `hazo_connect/ui`
+
+**File:** `src/lib/ui/index.ts`
+
+UI-safe types for client components.
+
+```typescript
+export type { TableSummary, TableSchema, SqliteFilterOperator, ... }
+```
+
+---
+
+## Core Components
+
+### Factory
+
+**File:** `src/lib/factory.ts`
+
+The `createHazoConnect` function is the main entry point for creating adapter instances.
+
+**Responsibilities:**
+- Parse and validate configuration
+- Extract configuration from ConfigProvider if provided
+- Resolve environment variables for paths and credentials
+- Instantiate the appropriate adapter based on `type`
+- Register SQLite adapters with admin service when `enable_admin_ui` is true
+
+**Flow:**
+```
+createHazoConnect(config)
+    │
+    ├─── Validate type
+    │
+    ├─── Extract config from ConfigProvider or direct config
+    │
+    ├─── Resolve environment variables (paths, API keys)
+    │
+    ├─── Switch on type:
+    │    ├─── 'postgrest' → new PostgrestAdapter(...)
+    │    ├─── 'sqlite' → new SqliteAdapter(...)
+    │    ├─── 'supabase' → new SupabaseAdapter(...)
+    │    └─── 'file' → new FileAdapter(...)
+    │
+    └─── If SQLite + enable_admin_ui → registerSqliteAdapter(adapter)
+```
+
+### Query Builder
+
+**File:** `src/lib/query-builder.ts`
+
+Fluent API for building database queries.
+
+**State:**
+- `_table`: Target table name
+- `_selectFields`: Fields to select
+- `_whereConditions`: WHERE conditions (AND)
+- `_whereOrConditions`: OR condition groups
+- `_orderBy`: ORDER BY clauses
+- `_limitValue`: LIMIT value
+- `_offsetValue`: OFFSET value
+- `_joins`: JOIN clauses
+- `_nestedSelects`: Nested select for PostgREST
+
+**Methods:**
+```typescript
+from(table: string): this
+select(fields: string | string[]): this
+where(field: string, operator: QueryOperator, value: any): this
+whereIn(field: string, values: any[]): this
+whereOr(conditions: Array<{...}>): this
+order(field: string, direction: OrderDirection): this
+limit(count: number): this
+offset(count: number): this
+join(table: string, on: string, type: JoinType): this
+nestedSelect(table: string, fields: string[]): this
+clone(): QueryBuilder
+```
+
+### Adapters
+
+**Base Class:** `src/lib/adapters/base-adapter.ts`
+
+Abstract base class providing common functionality:
+- Configuration storage
+- Logger integration
+- Error handling utilities
+- Query logging
+
+**Interface:** `HazoConnectAdapter`
+```typescript
+interface HazoConnectAdapter {
+  query(builder: QueryBuilder, method?: string, body?: any): Promise<any>
+  rawQuery(endpoint: string, options?: RequestInit): Promise<any>
+  getConfig(): Promise<any>
+}
+```
+
+#### PostgrestAdapter
+
+**File:** `src/lib/adapters/postgrest-adapter.ts`
+
+Translates QueryBuilder to PostgREST URL syntax and makes HTTP requests.
+
+**URL Building:**
+- `from('users')` → `/users`
+- `where('id', 'eq', '123')` → `?id=eq.123`
+- `select(['id', 'name'])` → `?select=id,name`
+- `nestedSelect('posts', ['title'])` → `?select=*,posts(title)`
+
+#### SqliteAdapter
+
+**File:** `src/lib/adapters/sqlite-adapter.ts`
+
+Uses sql.js (WebAssembly SQLite) for local database operations.
+
+**Key Features:**
+- In-memory and file-backed databases
+- Read-only mode support
+- Initial SQL execution for schema setup
+- Automatic persistence after writes
+- WASM file resolution
+
+**Initialization Flow:**
+```
+constructor()
+    │
+    ├─── normalizeConfig()
+    │
+    ├─── resolveWasmDirectory()
+    │
+    ├─── loadSqlJs() → Promise<SqlJsStatic>
+    │
+    └─── initializeDatabase() → Promise<SqlJsDatabase>
+         │
+         ├─── If file exists → Load from file
+         │
+         ├─── Else → Create new database
+         │    │
+         │    └─── Execute initial_sql if provided
+         │
+         └─── If database_path → Persist to file
+```
+
+### Helpers
+
+**File:** `src/lib/helpers.ts`
+
+#### createCrudService
+
+Creates a CRUD service wrapper for a table:
+
+```typescript
+function createCrudService<T>(
+  adapter: HazoConnectAdapter,
+  table: string,
+  options?: { primaryKeys?: string[]; logger?: Logger }
+): CrudService<T>
+```
+
+**Methods:**
+- `list()`: Get all records
+- `findBy(criteria)`: Find by criteria
+- `findOneBy(criteria)`: Find single record
+- `findById(id)`: Find by primary key
+- `insert(data)`: Insert record(s)
+- `updateById(id, patch)`: Update by primary key
+- `deleteById(id)`: Delete by primary key
+- `query()`: Get executable query builder
+
+#### attachExecute
+
+Attaches `execute()` method to a QueryBuilder:
+
+```typescript
+function attachExecute(
+  builder: QueryBuilder,
+  adapter: HazoConnectAdapter,
+  logger?: Logger
+): ExecutableQueryBuilder
+```
+
+---
+
+## SQLite Subsystem
+
+### SQLite Adapter
+
+**File:** `src/lib/adapters/sqlite-adapter.ts`
+
+**Query Execution Flow:**
+```
+query(builder, method, body)
+    │
+    ├─── GET → executeSelect(builder)
+    │         │
+    │         └─── translateSelect(builder) → SQL + params
+    │              │
+    │              └─── executeStatements(database, [translation])
+    │
+    ├─── POST → executeInsert(builder, body)
+    │          │
+    │          └─── translateInsert(builder, payload) → SQL statements
+    │               │
+    │               └─── executeStatements() → persistDatabase()
+    │
+    ├─── PATCH/PUT → executeUpdate(builder, body)
+    │               │
+    │               └─── translateUpdate(builder, updates) → SQL
+    │                    │
+    │                    └─── executeStatements() → persistDatabase()
+    │
+    └─── DELETE → executeDelete(builder)
+                 │
+                 └─── translateDelete(builder) → SQL
+                      │
+                      └─── executeStatements() → persistDatabase()
+```
+
+### Query Translator
+
+**File:** `src/lib/sqlite/query-translator.ts`
+
+Translates QueryBuilder state to parameterized SQL statements.
+
+**Functions:**
+- `translateSelect(builder)`: SELECT query
+- `translateInsert(builder, payload)`: INSERT statement(s)
+- `translateUpdate(builder, updates)`: UPDATE statement
+- `translateDelete(builder)`: DELETE statement
+
+**SQL Generation:**
+```typescript
+// QueryBuilder state
+builder.from('users').where('status', 'eq', 'active').limit(10)
+
+// Translated SQL
+{
+  sql: 'SELECT * FROM "users" WHERE "status" = ? LIMIT 10',
+  params: ['active']
+}
+```
+
+### Admin Service
+
+**File:** `src/lib/sqlite/admin-service.ts`
+
+Provides admin functionality for the SQLite Admin UI.
+
+**Singleton Pattern:**
+- `registeredAdapter`: Adapter registered by factory/singleton
+- `cachedAdapter`: Fallback adapter from environment variables
+- `adminUiEnabled`: Flag to enable/disable admin UI
+
+**Functions:**
+```typescript
+getSqliteAdminService(): SqliteAdminService
+initializeAdminService(config): void
+registerSqliteAdapter(adapter): void
+clearRegisteredAdapter(): void  // For testing
+```
+
+**Service Methods:**
+- `listTables()`: List all tables and views
+- `getTableSchema(table)`: Get column and FK definitions
+- `getTableData(table, options)`: Paginated data retrieval
+- `insertRow(table, data)`: Insert single row
+- `updateRows(table, criteria, data)`: Update matching rows
+- `deleteRows(table, criteria)`: Delete matching rows
+
+---
+
+## Next.js Integration
+
+### Setup Helpers
+
+**File:** `src/lib/nextjs/setup-helpers.ts`
+
+#### createHazoConnectFromEnv
+
+Creates adapter from environment variables:
+
+```typescript
+function createHazoConnectFromEnv(options?: {
+  type?: 'sqlite' | 'postgrest' | 'supabase' | 'file'
+  sqlitePath?: string
+  readOnly?: boolean
+  enableAdminUi?: boolean
+  logger?: Logger
+}): HazoConnectAdapter
+```
+
+**Environment Variable Resolution:**
+1. Check option overrides
+2. Fall back to `HAZO_CONNECT_*` variables
+3. Fall back to legacy variable names
+4. Apply defaults
+
+#### getHazoConnectSingleton
+
+Creates/returns singleton adapter instance:
+
+```typescript
+function getHazoConnectSingleton(options?: CreateHazoConnectFromEnvOptions): HazoConnectAdapter
+```
+
+**Singleton Behavior:**
+- Creates adapter on first call
+- Returns cached instance on subsequent calls
+- Recreates if configuration signature changes
+- Registers SQLite adapter with admin service
+
+### API Route Helpers
+
+**File:** `src/lib/nextjs/api-route-helpers.ts`
+
+#### createApiRouteHandler
+
+Wraps handler with automatic adapter initialization:
+
+```typescript
+function createApiRouteHandler(
+  handler: (hazo: HazoConnectAdapter, request: NextRequest) => Promise<Response>,
+  options?: {
+    config?: ApiRouteHazoConfig
+    getConfig?: (request: NextRequest) => ApiRouteHazoConfig
+    logger?: Logger
+  }
+): (request: NextRequest) => Promise<Response>
+```
+
+#### getServerHazoConnect
+
+Creates adapter for manual use in API routes:
+
+```typescript
+function getServerHazoConnect(config: ApiRouteHazoConfig, logger?: Logger): HazoConnectAdapter
+```
+
+---
+
+## Utility Modules
+
+### Config Validator
+
+**File:** `src/lib/utils/config-validator.ts`
+
+Validates Next.js configuration for SQLite compatibility.
+
+```typescript
+function validateNextJsConfig(): ValidationResult
+function getConfigurationTips(): string[]
+```
+
+### SQLite Utils
+
+**File:** `src/lib/utils/sqlite-utils.ts`
+
+Helper functions for SQLite operations:
+
+```typescript
+function quoteIdentifier(name: string): string
+function normalizeValue(value: unknown): unknown
+function sanitizeTableName(table: string): string
+function isPlainObject(value: unknown): boolean
+```
+
+### WASM Resolver
+
+**File:** `src/lib/utils/wasm-resolver.ts`
+
+Resolves sql-wasm.wasm file location:
+
+```typescript
+function resolveWasmDirectory(config: SqliteAdapterOptions): string
+function createSqlJsConfig(wasmDirectory: string): SqlJsConfig
+```
+
+**Resolution Order:**
+1. Explicit `wasm_directory` in config
+2. `HAZO_CONNECT_SQLITE_WASM_DIR` environment variable
+3. Auto-detect from node_modules
+
+### Where Builder
+
+**File:** `src/lib/utils/where-builder.ts`
+
+Builds WHERE clauses from filter specifications:
+
+```typescript
+function buildWhereClause(filters: SqliteWhereFilter[]): { clause: string; params: unknown[] }
+function buildFiltersFromCriteria(criteria: Record<string, unknown>): SqliteWhereFilter[]
+```
+
+---
+
+## Key Assumptions
+
+### Database Assumptions
+
+1. **SQLite**: Uses sql.js (WebAssembly), not native SQLite bindings
+2. **PostgREST**: Assumes standard PostgREST API format
+3. **Primary Keys**: Defaults to `id` column if not specified
+4. **Table Names**: Must be valid SQL identifiers
+
+### Environment Assumptions
+
+1. **Server-Side Only**: All runtime code assumes Node.js environment
+2. **Next.js 14+**: Next.js helpers assume App Router
+3. **File System Access**: SQLite file persistence requires write access
+4. **WASM Support**: sql.js requires WebAssembly support
+
+### Configuration Assumptions
+
+1. **Environment Variables**: Loaded via dotenv from `.env.local`
+2. **Path Resolution**: Relative paths resolved from `process.cwd()`
+3. **Admin UI Disabled**: By default for security
+
+---
+
+## Dependencies
+
+### Production Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `dotenv` | ^16.4.5 | Environment variable loading |
+| `hazo_config` | ^1.3.0 | Configuration provider interface |
+| `sql.js` | ^1.13.0 | WebAssembly SQLite implementation |
+
+### Peer Dependencies (Optional)
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `next` | >=14.0.0 | Next.js framework (Admin UI) |
+| `react` | >=18.0.0 | React library (Admin UI) |
+| `react-dom` | >=18.0.0 | React DOM (Admin UI) |
+| `lucide-react` | ^0.553.0 | Icons (Admin UI) |
+| `sonner` | ^2.0.7 | Toast notifications (Admin UI) |
+
+### Development Dependencies
+
+- TypeScript 5.5+
+- Jest 30+ for testing
+- Next.js 14+ for development server
+- Storybook for component development
+
+---
+
+## Build Process
+
+### Library Build
+
+```bash
+npm run build:lib
+```
+
+Uses `tsconfig.lib.json`:
+- Compiles `src/lib/**/*.ts` to `dist/`
+- Generates `.d.ts` type declarations
+- Excludes tests and app directory
+
+### Next.js Build
+
+```bash
+npm run build
+```
+
+Builds the Next.js application including Admin UI.
+
+### Package Exports
+
+Defined in `package.json`:
+
+```json
+{
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./server": { "types": "./dist/server/index.d.ts", "default": "./dist/server/index.js" },
+    "./nextjs": { "types": "./dist/nextjs/index.d.ts", "default": "./dist/nextjs/index.js" },
+    "./nextjs/setup": { "types": "./dist/nextjs/setup-helpers.d.ts", "default": "./dist/nextjs/setup-helpers.js" },
+    "./ui": { "types": "./dist/ui/index.d.ts", "default": "./dist/ui/index.js" }
+  }
+}
+```
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+
+**Location:** `src/lib/__tests__/`
+
+- `factory.test.ts`: Factory function tests
+- `query_builder.test.ts`: QueryBuilder API tests
+- `postgrest_adapter.test.ts`: PostgREST adapter tests
+- `sqlite_adapter.test.ts`: SQLite adapter tests
+
+### Integration Tests
+
+**Location:** `tests/integration/`
+
+- `sqlite.integration.test.ts`: SQLite CRUD operations
+- `sqlite-singleton.test.ts`: Singleton pattern and admin service
+- `postgrest.integration.test.ts`: PostgREST API integration
+
+### Running Tests
+
+```bash
+# All tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage
+npm run test:coverage
+
+# Integration only
+npm run test:integration:sqlite
+```
+
+---
+
+## Extension Points
+
+### Adding a New Adapter
+
+1. Create adapter class extending `BaseAdapter`:
+
+```typescript
+// src/lib/adapters/new-adapter.ts
+export class NewAdapter extends BaseAdapter implements HazoConnectAdapter {
+  async query(builder: QueryBuilder, method?: string, body?: any): Promise<any> {
+    // Implementation
+  }
+  
+  async rawQuery(endpoint: string, options?: RequestInit): Promise<any> {
+    // Implementation
+  }
+  
+  async getConfig(): Promise<any> {
+    return { ...this.config }
+  }
+}
+```
+
+2. Add to factory:
+
+```typescript
+// src/lib/factory.ts
+case 'new':
+  adapter = new NewAdapter(providerConfig, logger)
+  break
+```
+
+3. Update types:
+
+```typescript
+// src/lib/types.ts
+export type ConnectionType = 'postgrest' | 'supabase' | 'sqlite' | 'file' | 'new'
+```
+
+4. Export from server entry point:
+
+```typescript
+// src/lib/server/index.ts
+export { NewAdapter } from '../adapters/new-adapter'
+```
+
+### Adding New Query Operators
+
+1. Update types:
+
+```typescript
+// src/lib/types.ts
+export type QueryOperator = 'eq' | 'neq' | ... | 'new_operator'
+```
+
+2. Update query translator (for SQLite):
+
+```typescript
+// src/lib/sqlite/query-translator.ts
+function translateOperator(operator: QueryOperator, value: unknown): string {
+  switch (operator) {
+    case 'new_operator':
+      return 'NEW_SQL_SYNTAX ?'
+    // ...
+  }
+}
+```
+
+3. Update PostgREST adapter (for PostgREST):
+
+```typescript
+// src/lib/adapters/postgrest-adapter.ts
+// Add operator to URL building logic
+```
+
+---
+
+## Version History
+
+See [CHANGELOG.md](../CHANGELOG.md) for version history.
+
+---
+
+## Contributing
+
+1. Follow existing code style and conventions
+2. Add tests for new functionality
+3. Update documentation for API changes
+4. Run `npm run build:lib` and `npm test` before submitting
+