http-request-manager 18.15.33 → 18.15.34

package/src/docs/SQL_DIXIE_README.md

@@ -0,0 +1,574 @@
+# SQL DexieJS Service
+
+`DexieSqlService` lets you query an IndexedDB database managed by `DatabaseManagerService` using familiar MySQL-syntax SQL strings. Queries are parsed at runtime, validated against the live schema, translated into a Dexie.js execution plan, and returned as an `Observable<any[]>`.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [DexieSqlService](#dexiesqlservice)
+  - [DexieSqlOptions](#dexiesqloptions)
+  - [Error Types](#error-types)
+- [SQL Feature Reference](#sql-feature-reference)
+  - [SELECT & Projection](#select--projection)
+  - [WHERE — Comparison Operators](#where--comparison-operators)
+  - [WHERE — IN / NOT IN](#where--in--not-in)
+  - [WHERE — BETWEEN](#where--between)
+  - [WHERE — LIKE](#where--like)
+  - [AND Conditions](#and-conditions)
+  - [OR Conditions](#or-conditions)
+  - [ORDER BY](#order-by)
+  - [LIMIT & OFFSET](#limit--offset)
+  - [DISTINCT](#distinct)
+  - [COUNT(*)](#count)
+  - [JOIN (INNER & LEFT)](#join-inner--left)
+- [Execution Plans](#execution-plans)
+- [Constraints & Limitations](#constraints--limitations)
+- [Examples](#examples)
+  - [Component injection](#component-injection)
+  - [Basic SELECT](#basic-select)
+  - [Filtering with WHERE](#filtering-with-where)
+  - [Multi-column AND](#multi-column-and)
+  - [IN / NOT IN lists](#in--not-in-lists)
+  - [BETWEEN range](#between-range)
+  - [LIKE prefix search](#like-prefix-search)
+  - [OR branching](#or-branching)
+  - [ORDER BY + LIMIT](#order-by--limit)
+  - [Pagination with OFFSET](#pagination-with-offset)
+  - [DISTINCT rows](#distinct-rows)
+  - [COUNT(*)](#count-rows)
+  - [INNER JOIN](#inner-join)
+  - [LEFT JOIN](#left-join)
+  - [Strict mode](#strict-mode)
+  - [Error handling](#error-handling)
+
+---
+
+## Overview
+
+The service is a three-stage pipeline:
+
+```
+SQL string
+   ↓  SqlParser        — parses SQL using node-sql-parser (MySQL dialect)
+   ↓  SchemaValidator  — validates all columns against the live DexieJS schema
+   ↓  QueryPlanner     — builds an ExecutionPlan matched to the available indexes
+   ↓  DexieQueryExecutor — runs the plan against IndexedDB via Dexie.js
+Observable<any[]>
+```
+
+Because IndexedDB supports only one index per query, the planner selects the best strategy automatically:
+
+| Strategy | When used |
+|---|---|
+| `SIMPLE` | No WHERE, or a single-column condition |
+| `AND_BOUNDED` | AND with no matching compound index — first column uses Dexie, rest filtered in JS |
+| `AND_COMPOUND` | AND whose columns exactly match a compound index `[a+b]` |
+| `OR_MERGE` | OR — each branch runs independently, results are deduplicated |
+| `JOIN_HASH` | Two-table JOIN — left scan + indexed right lookup + JS hash join |
+
+---
+
+## Installation
+
+The service is included in the `http-request-manager` library. No extra setup is required beyond the standard module import. `node-sql-parser` is listed as a peer dependency.
+
+```typescript
+// app.module.ts
+import { HttpRequestManagerModule } from 'http-request-manager';
+
+@NgModule({
+  imports: [
+    HttpRequestManagerModule.forRoot({ /* ... */ })
+  ]
+})
+export class AppModule {}
+```
+
+The tables you query must first exist in the DexieJS database. Use `DatabaseManagerService.createDatabaseTable()` to define them before issuing SQL queries.
+
+---
+
+## Quick Start
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { DexieSqlService } from 'http-request-manager';
+
+@Component({ /* ... */ })
+export class MyComponent {
+  private sql = inject(DexieSqlService);
+
+  loadData() {
+    this.sql.query('SELECT * FROM orders WHERE status = "open"')
+      .subscribe(rows => console.log(rows));
+  }
+}
+```
+
+---
+
+## API Reference
+
+### DexieSqlService
+
+#### `query(sql: string, options?: DexieSqlOptions): Observable<any[]>`
+
+Executes a SQL SELECT statement against the DexieJS IndexedDB database.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `sql` | `string` | MySQL-syntax SELECT statement |
+| `options` | `DexieSqlOptions` | Optional execution options (see below) |
+
+Returns an `Observable<any[]>` that:
+- **emits once** with the result array, then completes
+- **errors** with `SqlParseError` if the SQL cannot be parsed
+- **errors** with `SqlValidationError` if columns reference non-indexed fields, tables don't exist, or the query shape is unsupported
+
+---
+
+### DexieSqlOptions
+
+```typescript
+export interface DexieSqlOptions {
+  strict?: boolean;
+}
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `strict` | `false` | When `true`, AND queries without a matching compound index throw `SqlValidationError` instead of silently falling back to a JS-side filter |
+
+---
+
+### Error Types
+
+Both errors extend `Error` and have a typed `name` property for `instanceof` checks.
+
+#### `SqlParseError`
+
+Thrown when the SQL string cannot be parsed or is not a SELECT statement.
+
+```typescript
+import { SqlParseError } from 'http-request-manager';
+
+this.sql.query('DELETE FROM users').subscribe({
+  error: err => {
+    if (err instanceof SqlParseError) {
+      // only SELECT is supported
+    }
+  }
+});
+```
+
+#### `SqlValidationError`
+
+Thrown when the query is structurally valid SQL but cannot be executed against the DexieJS schema — for example, a column is not indexed, a table does not exist, or a LIKE pattern starts with `%`.
+
+```typescript
+import { SqlValidationError } from 'http-request-manager';
+
+this.sql.query('SELECT * FROM orders WHERE note LIKE "%text"').subscribe({
+  error: err => {
+    if (err instanceof SqlValidationError) {
+      // leading-wildcard LIKE is not supported
+    }
+  }
+});
+```
+
+---
+
+## SQL Feature Reference
+
+### SELECT & Projection
+
+Select all columns or a specific subset.
+
+```sql
+-- All columns
+SELECT * FROM orders
+
+-- Specific columns only
+SELECT id, name, amount FROM orders
+```
+
+When specific columns are listed the result objects contain only those keys.
+
+---
+
+### WHERE — Comparison Operators
+
+| SQL operator | Dexie method |
+|---|---|
+| `=` | `.equals()` |
+| `!=` / `<>` | `.notEqual()` |
+| `>` | `.above()` |
+| `>=` | `.aboveOrEqual()` |
+| `<` | `.below()` |
+| `<=` | `.belowOrEqual()` |
+
+```sql
+SELECT * FROM orders WHERE status = "open"
+SELECT * FROM products WHERE price > 100
+SELECT * FROM users WHERE age >= 18 AND age <= 65
+```
+
+---
+
+### WHERE — IN / NOT IN
+
+```sql
+SELECT * FROM orders WHERE status IN ("open", "pending", "processing")
+SELECT * FROM products WHERE category NOT IN ("archived", "hidden")
+```
+
+Maps to `.anyOf([...])` and `.noneOf([...])` respectively.
+
+---
+
+### WHERE — BETWEEN
+
+```sql
+SELECT * FROM transactions WHERE amount BETWEEN 50 AND 500
+SELECT * FROM events WHERE timestamp BETWEEN 1700000000 AND 1800000000
+```
+
+Both bounds are **inclusive**. Maps to `.between(lo, hi, true, true)`.
+
+---
+
+### WHERE — LIKE
+
+Only **prefix** patterns are supported (`'value%'`). Leading wildcards (`'%value'`) and mid-string wildcards (`'v%lue'`) throw `SqlValidationError`.
+
+```sql
+-- Supported: prefix match
+SELECT * FROM users WHERE last_name LIKE "Smi%"
+
+-- NOT supported — throws SqlValidationError
+SELECT * FROM users WHERE last_name LIKE "%ith"
+SELECT * FROM users WHERE last_name LIKE "%mit%"
+```
+
+A pattern without any `%` is treated as an exact equality match.
+
+---
+
+### AND Conditions
+
+Multi-column AND queries are handled in two ways:
+
+**1. Compound index match** — if the table has a compound Dexie index matching all the AND columns exactly (e.g. `[status+userId]`), the query uses that index directly with no JS filtering.
+
+**2. Pragmatic fallback (default)** — the first column uses Dexie's index; remaining columns are filtered in JavaScript. A `console.warn` is printed suggesting the compound index to add. Enable `strict: true` to throw instead.
+
+```sql
+SELECT * FROM orders WHERE status = "open" AND userId = 42
+```
+
+---
+
+### OR Conditions
+
+Each OR branch runs as a separate Dexie query. Results are merged and deduplicated by primary key.
+
+```sql
+SELECT * FROM orders WHERE status = "open" OR status = "pending"
+```
+
+---
+
+### ORDER BY
+
+```sql
+SELECT * FROM orders ORDER BY createdAt DESC
+SELECT * FROM products ORDER BY price ASC
+```
+
+Sorting is applied in JavaScript after the Dexie fetch. Only a single `ORDER BY` column is supported.
+
+---
+
+### LIMIT & OFFSET
+
+```sql
+SELECT * FROM orders LIMIT 10
+SELECT * FROM orders LIMIT 10 OFFSET 20
+```
+
+Applied after sorting. `OFFSET` skips the first N rows before applying the limit.
+
+---
+
+### DISTINCT
+
+```sql
+SELECT DISTINCT status FROM orders
+SELECT DISTINCT category, brand FROM products
+```
+
+Deduplication is performed in JavaScript using `JSON.stringify` on each projected row object.
+
+---
+
+### COUNT(*)
+
+Returns a single-element array `[{ count: N }]`.
+
+```sql
+SELECT COUNT(*) FROM orders
+SELECT COUNT(*) FROM orders WHERE status = "open"
+```
+
+---
+
+### JOIN (INNER & LEFT)
+
+Two-table hash join executed entirely in JavaScript:
+
+1. Full scan of the left table
+2. Extract foreign key values
+3. Dexie `.anyOf(ids)` on the right table's join key (must be indexed)
+4. Hash join in memory
+5. Post-join WHERE filters applied
+
+```sql
+-- INNER JOIN (excludes left rows with no match)
+SELECT * FROM orders INNER JOIN users ON orders.userId = users.id
+
+-- LEFT JOIN (left rows kept even with no matching right row)
+SELECT * FROM orders LEFT JOIN users ON orders.userId = users.id
+```
+
+Table aliases are supported:
+
+```sql
+SELECT * FROM orders o LEFT JOIN users u ON o.userId = u.id
+```
+
+---
+
+## Execution Plans
+
+The planner assigns one of these strategies, visible in the exported `ExecutionPlanType` enum:
+
+| Plan | Description |
+|---|---|
+| `SIMPLE` | Single Dexie `.where().op()` or full table scan |
+| `AND_BOUNDED` | First condition indexed, rest JS-filtered |
+| `AND_COMPOUND` | All conditions covered by a compound index |
+| `OR_MERGE` | Multiple independent Dexie queries, deduped |
+| `JOIN_HASH` | Left scan + indexed right `.anyOf()` + JS merge |
+
+---
+
+## Constraints & Limitations
+
+| Constraint | Detail |
+|---|---|
+| **SELECT only** | INSERT, UPDATE, DELETE are not supported |
+| **One table or two-table JOIN** | Sub-queries are not supported |
+| **Indexed columns only in WHERE** | Only columns registered as Dexie indexes can appear in WHERE or ORDER BY |
+| **Single ORDER BY column** | Only the first `ORDER BY` expression is used |
+| **LIKE leading wildcard** | `'%value'` patterns throw `SqlValidationError` |
+| **IndexedDB one-index limit** | AND without a compound index falls back to JS filtering for columns beyond the first |
+| **MySQL dialect** | The parser uses MySQL syntax; other dialects may work but are not tested |
+
+---
+
+## Examples
+
+### Component injection
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { DexieSqlService, SqlParseError, SqlValidationError } from 'http-request-manager';
+
+@Component({ /* ... */ })
+export class ExampleComponent {
+  private sql = inject(DexieSqlService);
+}
+```
+
+---
+
+### Basic SELECT
+
+```typescript
+this.sql.query('SELECT * FROM products')
+  .subscribe(rows => console.log(rows));
+```
+
+---
+
+### Filtering with WHERE
+
+```typescript
+this.sql.query('SELECT * FROM orders WHERE status = "open"')
+  .subscribe(rows => this.openOrders = rows);
+```
+
+```typescript
+this.sql.query('SELECT id, name, price FROM products WHERE price > 50')
+  .subscribe(rows => this.expensiveProducts = rows);
+```
+
+---
+
+### Multi-column AND
+
+```typescript
+// Pragmatic fallback (console.warn printed, no error)
+this.sql.query('SELECT * FROM orders WHERE status = "open" AND userId = 42')
+  .subscribe(rows => this.userOrders = rows);
+
+// If the table has a compound index [status+userId], no fallback occurs
+this.sql.query(
+  'SELECT * FROM orders WHERE status = "open" AND userId = 42',
+  { strict: false }
+).subscribe(rows => this.userOrders = rows);
+```
+
+---
+
+### IN / NOT IN lists
+
+```typescript
+this.sql.query('SELECT * FROM orders WHERE status IN ("open", "pending")')
+  .subscribe(rows => this.activeOrders = rows);
+
+this.sql.query('SELECT * FROM products WHERE category NOT IN ("archived")')
+  .subscribe(rows => this.visibleProducts = rows);
+```
+
+---
+
+### BETWEEN range
+
+```typescript
+this.sql.query('SELECT * FROM transactions WHERE amount BETWEEN 100 AND 999')
+  .subscribe(rows => this.midRangeTransactions = rows);
+```
+
+---
+
+### LIKE prefix search
+
+```typescript
+this.sql.query('SELECT * FROM users WHERE last_name LIKE "Smi%"')
+  .subscribe(rows => this.smiths = rows);
+```
+
+---
+
+### OR branching
+
+```typescript
+this.sql.query('SELECT * FROM orders WHERE status = "open" OR status = "pending"')
+  .subscribe(rows => this.pendingOrders = rows);
+```
+
+---
+
+### ORDER BY + LIMIT
+
+```typescript
+this.sql.query('SELECT * FROM orders ORDER BY createdAt DESC LIMIT 5')
+  .subscribe(rows => this.latestOrders = rows);
+```
+
+---
+
+### Pagination with OFFSET
+
+```typescript
+const page = 2;
+const pageSize = 10;
+
+this.sql.query(`SELECT * FROM products ORDER BY name ASC LIMIT ${pageSize} OFFSET ${page * pageSize}`)
+  .subscribe(rows => this.pageRows = rows);
+```
+
+---
+
+### DISTINCT rows
+
+```typescript
+this.sql.query('SELECT DISTINCT status FROM orders')
+  .subscribe(rows => this.statuses = rows.map(r => r['status']));
+```
+
+---
+
+### COUNT rows
+
+```typescript
+this.sql.query('SELECT COUNT(*) FROM orders WHERE status = "open"')
+  .subscribe(([result]) => this.openCount = result.count);
+```
+
+---
+
+### INNER JOIN
+
+```typescript
+this.sql.query(
+  'SELECT * FROM orders INNER JOIN users ON orders.userId = users.id'
+).subscribe(rows => this.enrichedOrders = rows);
+```
+
+---
+
+### LEFT JOIN
+
+```typescript
+this.sql.query(
+  'SELECT * FROM orders LEFT JOIN users ON orders.userId = users.id'
+).subscribe(rows => {
+  // rows without a matching user will still appear; user fields will be undefined
+  this.allOrders = rows;
+});
+```
+
+---
+
+### Strict mode
+
+```typescript
+// Throws SqlValidationError for AND without a compound index
+this.sql.query(
+  'SELECT * FROM orders WHERE status = "open" AND amount > 100',
+  { strict: true }
+).subscribe({
+  next:  rows => this.results = rows,
+  error: err  => this.error = err.message
+});
+```
+
+---
+
+### Error handling
+
+```typescript
+import { SqlParseError, SqlValidationError } from 'http-request-manager';
+
+this.sql.query(this.userInput).subscribe({
+  next: rows => {
+    this.results = rows;
+    this.error   = null;
+  },
+  error: err => {
+    if (err instanceof SqlParseError) {
+      this.error = `Invalid SQL: ${err.message}`;
+    } else if (err instanceof SqlValidationError) {
+      this.error = `Query error: ${err.message}`;
+    } else {
+      this.error = `Unexpected error: ${err.message}`;
+    }
+  }
+});
+```