npm - http-request-manager - Versions diffs - 18.15.34 → 18.16.1 - Mend

http-request-manager 18.15.34 → 18.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (300) hide show

package/src/docs/SQL_DIXIE_README.md DELETED Viewed

@@ -1,574 +0,0 @@
-# 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}`;
-    }
-  }
-});
-```