@tallyui/storage-sqlite 0.2.0

package/src/mango-to-sql.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from 'vitest';
+import { mangoQueryToSQL, buildQuerySQL, buildCountSQL } from './mango-to-sql';
+import type { FilledMangoQuery } from 'rxdb';
+
+function makeQuery(overrides: Partial<FilledMangoQuery<any>> = {}): FilledMangoQuery<any> {
+  return {
+    selector: {},
+    sort: [],
+    skip: 0,
+    ...overrides,
+  };
+}
+
+describe('mangoQueryToSQL', () => {
+  describe('basic selectors', () => {
+    it('should produce WHERE with only _deleted filter for empty selector', () => {
+      const result = mangoQueryToSQL(makeQuery());
+      expect(result.where).toBe(`WHERE json_extract(data, '$._deleted') = 0`);
+      expect(result.params).toEqual([]);
+    });
+
+    it('should handle equality ($eq) for a field', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { name: 'Alice' } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.name') = ?`);
+      expect(result.params).toContain('Alice');
+    });
+
+    it('should handle explicit $eq operator', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { name: { $eq: 'Alice' } } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.name') = ?`);
+      expect(result.params).toEqual(['Alice']);
+    });
+  });
+
+  describe('comparison operators', () => {
+    it('should handle $gt', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { age: { $gt: 25 } } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.age') > ?`);
+      expect(result.params).toContain(25);
+    });
+
+    it('should handle $gte', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { age: { $gte: 25 } } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.age') >= ?`);
+      expect(result.params).toContain(25);
+    });
+
+    it('should handle $lt', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { age: { $lt: 30 } } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.age') < ?`);
+      expect(result.params).toContain(30);
+    });
+
+    it('should handle $lte', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { age: { $lte: 30 } } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.age') <= ?`);
+      expect(result.params).toContain(30);
+    });
+
+    it('should handle $ne', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { status: { $ne: 'inactive' } } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.status') != ?`);
+      expect(result.params).toContain('inactive');
+    });
+  });
+
+  describe('array operators', () => {
+    it('should handle $in', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { status: { $in: ['active', 'pending'] } } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.status') IN (?, ?)`);
+      expect(result.params).toEqual(['active', 'pending']);
+    });
+
+    it('should handle empty $in as always-false', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { status: { $in: [] } } as any,
+      }));
+      expect(result.where).toContain('0');
+    });
+
+    it('should handle $nin', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { status: { $nin: ['deleted', 'archived'] } } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.status') NOT IN (?, ?)`);
+      expect(result.params).toEqual(['deleted', 'archived']);
+    });
+  });
+
+  describe('regex', () => {
+    it('should convert $regex to LIKE with wildcards', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { name: { $regex: '^Al' } } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.name') LIKE ?`);
+      expect(result.params).toContain('Al%');
+    });
+
+    it('should handle unanchored regex with wrapping wildcards', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { name: { $regex: 'lic' } } as any,
+      }));
+      expect(result.params).toContain('%lic%');
+    });
+
+    it('should handle end-anchored regex', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: { name: { $regex: 'ice$' } } as any,
+      }));
+      expect(result.params).toContain('%ice');
+    });
+  });
+
+  describe('logical operators', () => {
+    it('should handle $and', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: {
+          $and: [
+            { age: { $gte: 18 } },
+            { age: { $lte: 65 } },
+          ],
+        } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.age') >= ?`);
+      expect(result.where).toContain(`json_extract(data, '$.age') <= ?`);
+      expect(result.where).toContain(' AND ');
+      expect(result.params).toEqual([18, 65]);
+    });
+
+    it('should handle $or', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        selector: {
+          $or: [
+            { name: 'Alice' },
+            { name: 'Bob' },
+          ],
+        } as any,
+      }));
+      expect(result.where).toContain(`json_extract(data, '$.name') = ?`);
+      expect(result.where).toContain(' OR ');
+      expect(result.params).toEqual(['Alice', 'Bob']);
+    });
+  });
+
+  describe('sort', () => {
+    it('should generate ORDER BY clause for ascending', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        sort: [{ name: 'asc' }] as any,
+      }));
+      expect(result.orderBy).toBe(`ORDER BY json_extract(data, '$.name') ASC`);
+    });
+
+    it('should generate ORDER BY clause for descending', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        sort: [{ age: 'desc' }] as any,
+      }));
+      expect(result.orderBy).toBe(`ORDER BY json_extract(data, '$.age') DESC`);
+    });
+
+    it('should handle multiple sort fields', () => {
+      const result = mangoQueryToSQL(makeQuery({
+        sort: [{ name: 'asc' }, { age: 'desc' }] as any,
+      }));
+      expect(result.orderBy).toBe(
+        `ORDER BY json_extract(data, '$.name') ASC, json_extract(data, '$.age') DESC`
+      );
+    });
+  });
+
+  describe('limit and skip', () => {
+    it('should generate LIMIT clause', () => {
+      const result = mangoQueryToSQL(makeQuery({ limit: 10 }));
+      expect(result.limit).toBe('LIMIT ?');
+      expect(result.limitParams).toEqual([10]);
+    });
+
+    it('should generate LIMIT + OFFSET for skip', () => {
+      const result = mangoQueryToSQL(makeQuery({ limit: 10, skip: 5 }));
+      expect(result.limit).toBe('LIMIT ? OFFSET ?');
+      expect(result.limitParams).toEqual([10, 5]);
+    });
+
+    it('should generate LIMIT -1 OFFSET for skip without limit', () => {
+      const result = mangoQueryToSQL(makeQuery({ skip: 5 }));
+      expect(result.limit).toBe('LIMIT -1 OFFSET ?');
+      expect(result.limitParams).toEqual([5]);
+    });
+  });
+});
+
+describe('buildQuerySQL', () => {
+  it('should build a complete SELECT statement', () => {
+    const query = makeQuery({
+      selector: { name: 'Alice' } as any,
+      sort: [{ name: 'asc' }] as any,
+      limit: 10,
+      skip: 0,
+    });
+    const { sql, params } = buildQuerySQL('my_table', query);
+    expect(sql).toContain('SELECT data FROM "my_table"');
+    expect(sql).toContain('WHERE');
+    expect(sql).toContain('ORDER BY');
+    expect(sql).toContain('LIMIT');
+    expect(params).toContain('Alice');
+  });
+});
+
+describe('buildCountSQL', () => {
+  it('should build a COUNT statement without sort/limit/skip', () => {
+    const query = makeQuery({
+      selector: { age: { $gt: 20 } } as any,
+      sort: [{ name: 'asc' }] as any,
+      limit: 10,
+      skip: 5,
+    });
+    const { sql, params } = buildCountSQL('my_table', query);
+    expect(sql).toContain('SELECT COUNT(*) as count FROM "my_table"');
+    expect(sql).toContain('WHERE');
+    expect(sql).not.toContain('ORDER BY');
+    expect(sql).not.toContain('LIMIT');
+    expect(params).toContain(20);
+  });
+});

package/src/mango-to-sql.ts

@@ -0,0 +1,274 @@
+/**
+ * Translates RxDB Mango-style queries into SQL WHERE clauses
+ * that use SQLite's json_extract() to access document fields.
+ *
+ * Supported operators:
+ *   Comparison: $eq (default), $gt, $gte, $lt, $lte, $ne
+ *   Array:      $in, $nin
+ *   String:     $regex
+ *   Logical:    $and, $or
+ *
+ * Plus: sort, limit, skip
+ */
+
+import type { FilledMangoQuery, MangoQuerySelector } from 'rxdb';
+
+export interface MangoSqlResult {
+  where: string;
+  params: any[];
+  orderBy: string;
+  limit: string;
+  limitParams: any[];
+}
+
+/**
+ * Convert a Mango selector + sort/skip/limit into SQL fragments.
+ * The returned `where` always starts with `WHERE ...` (including the
+ * mandatory `_deleted = 0` filter for non-deleted documents).
+ *
+ * All document field access goes through `json_extract(data, '$.fieldName')`.
+ */
+export function mangoQueryToSQL<RxDocType>(
+  query: FilledMangoQuery<RxDocType>,
+): MangoSqlResult {
+  const params: any[] = [];
+  const conditions: string[] = [];
+
+  // Always filter out deleted docs -- RxDB's query() contract.
+  conditions.push(`json_extract(data, '$._deleted') = 0`);
+
+  // Process the selector
+  if (query.selector && Object.keys(query.selector).length > 0) {
+    const selectorSql = selectorToSQL(query.selector as Record<string, any>, params);
+    if (selectorSql) {
+      conditions.push(selectorSql);
+    }
+  }
+
+  const where = conditions.length > 0
+    ? `WHERE ${conditions.join(' AND ')}`
+    : '';
+
+  // ORDER BY
+  let orderBy = '';
+  if (query.sort && query.sort.length > 0) {
+    const orderParts = query.sort.map((sortPart) => {
+      const entries = Object.entries(sortPart);
+      if (entries.length === 0) return '';
+      const [field, direction] = entries[0];
+      const jsonPath = fieldToJsonExtract(field);
+      return `${jsonPath} ${direction === 'desc' ? 'DESC' : 'ASC'}`;
+    }).filter(Boolean);
+    if (orderParts.length > 0) {
+      orderBy = `ORDER BY ${orderParts.join(', ')}`;
+    }
+  }
+
+  // LIMIT / OFFSET
+  const limitParams: any[] = [];
+  let limit = '';
+  if (query.limit !== undefined && query.limit !== null) {
+    limit = 'LIMIT ?';
+    limitParams.push(query.limit);
+  }
+  if (query.skip && query.skip > 0) {
+    if (!limit) {
+      // SQLite requires LIMIT before OFFSET
+      limit = 'LIMIT -1';
+    }
+    limit += ' OFFSET ?';
+    limitParams.push(query.skip);
+  }
+
+  return { where, params, orderBy, limit, limitParams };
+}
+
+/**
+ * Build the full SQL SELECT query from mango query result.
+ */
+export function buildQuerySQL<RxDocType>(
+  tableName: string,
+  query: FilledMangoQuery<RxDocType>,
+): { sql: string; params: any[] } {
+  const result = mangoQueryToSQL(query);
+  const allParams = [...result.params, ...result.limitParams];
+  const parts = [
+    `SELECT data FROM "${tableName}"`,
+    result.where,
+    result.orderBy,
+    result.limit,
+  ].filter(Boolean);
+  return { sql: parts.join(' '), params: allParams };
+}
+
+/**
+ * Build a COUNT SQL query from mango query result.
+ * Ignores sort, skip, and limit per RxDB's count() contract.
+ */
+export function buildCountSQL<RxDocType>(
+  tableName: string,
+  query: FilledMangoQuery<RxDocType>,
+): { sql: string; params: any[] } {
+  const result = mangoQueryToSQL(query);
+  const parts = [
+    `SELECT COUNT(*) as count FROM "${tableName}"`,
+    result.where,
+  ].filter(Boolean);
+  return { sql: parts.join(' '), params: result.params };
+}
+
+// ------------------------------------------------------------------
+// Internal helpers
+// ------------------------------------------------------------------
+
+function fieldToJsonExtract(field: string): string {
+  return `json_extract(data, '$.${field}')`;
+}
+
+function selectorToSQL(
+  selector: Record<string, any>,
+  params: any[],
+): string {
+  const conditions: string[] = [];
+
+  for (const [key, value] of Object.entries(selector)) {
+    if (key === '$and') {
+      const andConditions = (value as Record<string, any>[]).map(
+        (sub) => selectorToSQL(sub, params),
+      ).filter(Boolean);
+      if (andConditions.length > 0) {
+        conditions.push(`(${andConditions.join(' AND ')})`);
+      }
+    } else if (key === '$or') {
+      const orConditions = (value as Record<string, any>[]).map(
+        (sub) => selectorToSQL(sub, params),
+      ).filter(Boolean);
+      if (orConditions.length > 0) {
+        conditions.push(`(${orConditions.join(' OR ')})`);
+      }
+    } else {
+      // It's a field name with either a value or an operator object
+      const fieldSql = fieldConditionToSQL(key, value, params);
+      if (fieldSql) {
+        conditions.push(fieldSql);
+      }
+    }
+  }
+
+  return conditions.join(' AND ');
+}
+
+function fieldConditionToSQL(
+  field: string,
+  value: any,
+  params: any[],
+): string {
+  const jsonPath = fieldToJsonExtract(field);
+
+  // Plain value means $eq
+  if (value === null || value === undefined || typeof value !== 'object' || Array.isArray(value)) {
+    params.push(value);
+    return `${jsonPath} = ?`;
+  }
+
+  // Object with operators
+  const conditions: string[] = [];
+  for (const [op, opValue] of Object.entries(value)) {
+    switch (op) {
+      case '$eq':
+        params.push(opValue);
+        conditions.push(`${jsonPath} = ?`);
+        break;
+      case '$ne':
+        params.push(opValue);
+        conditions.push(`${jsonPath} != ?`);
+        break;
+      case '$gt':
+        params.push(opValue);
+        conditions.push(`${jsonPath} > ?`);
+        break;
+      case '$gte':
+        params.push(opValue);
+        conditions.push(`${jsonPath} >= ?`);
+        break;
+      case '$lt':
+        params.push(opValue);
+        conditions.push(`${jsonPath} < ?`);
+        break;
+      case '$lte':
+        params.push(opValue);
+        conditions.push(`${jsonPath} <= ?`);
+        break;
+      case '$in': {
+        const arr = opValue as any[];
+        if (arr.length === 0) {
+          conditions.push('0'); // always false
+        } else {
+          const placeholders = arr.map(() => '?').join(', ');
+          params.push(...arr);
+          conditions.push(`${jsonPath} IN (${placeholders})`);
+        }
+        break;
+      }
+      case '$nin': {
+        const arr = opValue as any[];
+        if (arr.length === 0) {
+          // No exclusions, always true -- skip
+        } else {
+          const placeholders = arr.map(() => '?').join(', ');
+          params.push(...arr);
+          conditions.push(`${jsonPath} NOT IN (${placeholders})`);
+        }
+        break;
+      }
+      case '$regex': {
+        // SQLite does not natively support regex, but we can use LIKE for simple patterns
+        // or GLOB. For a more complete solution we'd need a regex extension.
+        // Here we convert simple regex patterns to LIKE patterns.
+        const regexStr = typeof opValue === 'string' ? opValue : (opValue as RegExp).source;
+        const likePattern = regexToLike(regexStr);
+        params.push(likePattern);
+        conditions.push(`${jsonPath} LIKE ?`);
+        break;
+      }
+      default:
+        // Unknown operator -- skip (RxDB might send $options etc.)
+        break;
+    }
+  }
+
+  return conditions.join(' AND ');
+}
+
+/**
+ * Convert a simple regex pattern to a SQLite LIKE pattern.
+ * Only handles basic patterns:
+ *   ^foo  -> foo%
+ *   foo$  -> %foo
+ *   ^foo$ -> foo
+ *   foo   -> %foo%
+ *   .*    -> %
+ */
+function regexToLike(regex: string): string {
+  let pattern = regex;
+  let prefix = '%';
+  let suffix = '%';
+
+  if (pattern.startsWith('^')) {
+    prefix = '';
+    pattern = pattern.slice(1);
+  }
+  if (pattern.endsWith('$')) {
+    suffix = '';
+    pattern = pattern.slice(0, -1);
+  }
+
+  // Replace .* with %
+  pattern = pattern.replace(/\.\*/g, '%');
+  // Replace . with _
+  pattern = pattern.replace(/\./g, '_');
+  // Escape existing % and _ that aren't our wildcards
+  // (This is approximate -- a real implementation would need more care)
+
+  return `${prefix}${pattern}${suffix}`;
+}