@anfenn/dync 1.0.0

package/src/storage/sqlite/SQLiteWhereClause.ts

@@ -0,0 +1,341 @@
+import type { StorageWhereClause, StorageCollection } from '../types';
+import type { SQLiteCondition } from './types';
+import { SQLiteTable } from './SQLiteTable';
+import { SQLiteCollection } from './SQLiteCollection';
+
+export class SQLiteWhereClause<T = any> implements StorageWhereClause<T> {
+    private readonly table: SQLiteTable<T>;
+    private readonly index: string | string[];
+    private readonly baseCollection?: SQLiteCollection<T>;
+
+    constructor(table: SQLiteTable<T>, index: string | string[], baseCollection?: SQLiteCollection<T>) {
+        this.table = table;
+        this.index = index;
+        this.baseCollection = baseCollection;
+    }
+
+    private getColumn(): string {
+        // For compound indexes, we only support the first column in SQL conditions
+        // Complex compound index queries fall back to JS
+        if (Array.isArray(this.index)) {
+            return this.index[0]!;
+        }
+        return this.index;
+    }
+
+    private isCompoundIndex(): boolean {
+        return Array.isArray(this.index) && this.index.length > 1;
+    }
+
+    private getCompoundColumns(): string[] {
+        return Array.isArray(this.index) ? this.index : [this.index];
+    }
+
+    private getCompoundValues(value: unknown): unknown[] {
+        // For compound indexes, value should be an array of values matching each column
+        if (Array.isArray(value)) {
+            return value;
+        }
+        // Single value for single-column index
+        return [value];
+    }
+
+    private createCollectionWithCondition(condition: SQLiteCondition): SQLiteCollection<T> {
+        const base = this.baseCollection ?? this.table.createCollection();
+        return base.addSqlCondition(condition);
+    }
+
+    private createCollectionWithJsPredicate(predicate: (record: T) => boolean): SQLiteCollection<T> {
+        const base = this.baseCollection ?? this.table.createCollection();
+        return base.jsFilter(predicate) as SQLiteCollection<T>;
+    }
+
+    private getIndexValue(record: T): unknown {
+        return this.table.getIndexValue(record, this.index);
+    }
+
+    private flattenArgs<TValue>(args: any[]): TValue[] {
+        if (args.length === 1 && Array.isArray(args[0])) {
+            return args[0] as TValue[];
+        }
+        return args as TValue[];
+    }
+
+    equals(value: any): StorageCollection<T> {
+        if (this.isCompoundIndex()) {
+            // Use native SQL: WHERE col1 = ? AND col2 = ? AND ...
+            const columns = this.getCompoundColumns();
+            const values = this.getCompoundValues(value);
+            return this.createCollectionWithCondition({
+                type: 'compoundEquals',
+                columns,
+                values,
+            });
+        }
+        return this.createCollectionWithCondition({
+            type: 'equals',
+            column: this.getColumn(),
+            value,
+        });
+    }
+
+    above(value: any): StorageCollection<T> {
+        if (this.isCompoundIndex()) {
+            return this.createCollectionWithJsPredicate((record) => this.table.compareValues(this.getIndexValue(record), value) > 0);
+        }
+        return this.createCollectionWithCondition({
+            type: 'comparison',
+            column: this.getColumn(),
+            op: '>',
+            value,
+        });
+    }
+
+    aboveOrEqual(value: any): StorageCollection<T> {
+        if (this.isCompoundIndex()) {
+            return this.createCollectionWithJsPredicate((record) => this.table.compareValues(this.getIndexValue(record), value) >= 0);
+        }
+        return this.createCollectionWithCondition({
+            type: 'comparison',
+            column: this.getColumn(),
+            op: '>=',
+            value,
+        });
+    }
+
+    below(value: any): StorageCollection<T> {
+        if (this.isCompoundIndex()) {
+            return this.createCollectionWithJsPredicate((record) => this.table.compareValues(this.getIndexValue(record), value) < 0);
+        }
+        return this.createCollectionWithCondition({
+            type: 'comparison',
+            column: this.getColumn(),
+            op: '<',
+            value,
+        });
+    }
+
+    belowOrEqual(value: any): StorageCollection<T> {
+        if (this.isCompoundIndex()) {
+            return this.createCollectionWithJsPredicate((record) => this.table.compareValues(this.getIndexValue(record), value) <= 0);
+        }
+        return this.createCollectionWithCondition({
+            type: 'comparison',
+            column: this.getColumn(),
+            op: '<=',
+            value,
+        });
+    }
+
+    between(lower: any, upper: any, includeLower = true, includeUpper = false): StorageCollection<T> {
+        if (this.isCompoundIndex()) {
+            return this.createCollectionWithJsPredicate((record) => {
+                const value = this.getIndexValue(record);
+                const lowerCmp = this.table.compareValues(value, lower);
+                const upperCmp = this.table.compareValues(value, upper);
+                const lowerPass = includeLower ? lowerCmp >= 0 : lowerCmp > 0;
+                const upperPass = includeUpper ? upperCmp <= 0 : upperCmp < 0;
+                return lowerPass && upperPass;
+            });
+        }
+        return this.createCollectionWithCondition({
+            type: 'between',
+            column: this.getColumn(),
+            lower,
+            upper,
+            includeLower,
+            includeUpper,
+        });
+    }
+
+    inAnyRange(ranges: Array<[any, any]>, options?: { includeLower?: boolean; includeUpper?: boolean }): StorageCollection<T> {
+        // inAnyRange with multiple ranges uses OR logic - can be expressed in SQL
+        if (this.isCompoundIndex() || ranges.length === 0) {
+            return this.createCollectionWithJsPredicate((record) => {
+                const value = this.getIndexValue(record);
+                return ranges.some(([lower, upper]) => {
+                    const lowerCmp = this.table.compareValues(value, lower);
+                    const upperCmp = this.table.compareValues(value, upper);
+                    const lowerPass = options?.includeLower !== false ? lowerCmp >= 0 : lowerCmp > 0;
+                    const upperPass = options?.includeUpper ? upperCmp <= 0 : upperCmp < 0;
+                    return lowerPass && upperPass;
+                });
+            });
+        }
+
+        const column = this.getColumn();
+        const orConditions: SQLiteCondition[] = ranges.map(([lower, upper]) => ({
+            type: 'between' as const,
+            column,
+            lower,
+            upper,
+            includeLower: options?.includeLower !== false,
+            includeUpper: options?.includeUpper ?? false,
+        }));
+
+        return this.createCollectionWithCondition({
+            type: 'or',
+            conditions: orConditions,
+        });
+    }
+
+    startsWith(prefix: string): StorageCollection<T> {
+        if (this.isCompoundIndex()) {
+            return this.createCollectionWithJsPredicate((record) => String(this.getIndexValue(record) ?? '').startsWith(prefix));
+        }
+        // SQLite LIKE pattern: 'prefix%' matches strings starting with prefix
+        // Escape special LIKE characters in the prefix
+        const escapedPrefix = prefix.replace(/[%_\\]/g, '\\$&');
+        return this.createCollectionWithCondition({
+            type: 'like',
+            column: this.getColumn(),
+            pattern: `${escapedPrefix}%`,
+        });
+    }
+
+    startsWithIgnoreCase(prefix: string): StorageCollection<T> {
+        if (this.isCompoundIndex()) {
+            return this.createCollectionWithJsPredicate((record) =>
+                String(this.getIndexValue(record) ?? '')
+                    .toLowerCase()
+                    .startsWith(prefix.toLowerCase()),
+            );
+        }
+        const escapedPrefix = prefix.replace(/[%_\\]/g, '\\$&');
+        return this.createCollectionWithCondition({
+            type: 'like',
+            column: this.getColumn(),
+            pattern: `${escapedPrefix}%`,
+            caseInsensitive: true,
+        });
+    }
+
+    startsWithAnyOf(...args: any[]): StorageCollection<T> {
+        const prefixes = this.flattenArgs<string>(args);
+        if (this.isCompoundIndex() || prefixes.length === 0) {
+            return this.createCollectionWithJsPredicate((record) => {
+                const value = String(this.getIndexValue(record) ?? '');
+                return prefixes.some((prefix) => value.startsWith(prefix));
+            });
+        }
+
+        const column = this.getColumn();
+        const orConditions: SQLiteCondition[] = prefixes.map((prefix) => {
+            const escapedPrefix = prefix.replace(/[%_\\]/g, '\\$&');
+            return {
+                type: 'like' as const,
+                column,
+                pattern: `${escapedPrefix}%`,
+            };
+        });
+
+        return this.createCollectionWithCondition({
+            type: 'or',
+            conditions: orConditions,
+        });
+    }
+
+    startsWithAnyOfIgnoreCase(...args: any[]): StorageCollection<T> {
+        const prefixes = this.flattenArgs<string>(args);
+        if (this.isCompoundIndex() || prefixes.length === 0) {
+            const lowerPrefixes = prefixes.map((p) => p.toLowerCase());
+            return this.createCollectionWithJsPredicate((record) => {
+                const value = String(this.getIndexValue(record) ?? '').toLowerCase();
+                return lowerPrefixes.some((prefix) => value.startsWith(prefix));
+            });
+        }
+
+        const column = this.getColumn();
+        const orConditions: SQLiteCondition[] = prefixes.map((prefix) => {
+            const escapedPrefix = prefix.replace(/[%_\\]/g, '\\$&');
+            return {
+                type: 'like' as const,
+                column,
+                pattern: `${escapedPrefix}%`,
+                caseInsensitive: true,
+            };
+        });
+
+        return this.createCollectionWithCondition({
+            type: 'or',
+            conditions: orConditions,
+        });
+    }
+
+    equalsIgnoreCase(value: string): StorageCollection<T> {
+        if (this.isCompoundIndex()) {
+            return this.createCollectionWithJsPredicate((record) => String(this.getIndexValue(record) ?? '').toLowerCase() === value.toLowerCase());
+        }
+        return this.createCollectionWithCondition({
+            type: 'equals',
+            column: this.getColumn(),
+            value,
+            caseInsensitive: true,
+        });
+    }
+
+    anyOf(...args: any[]): StorageCollection<T> {
+        const values = this.flattenArgs<any>(args);
+        if (this.isCompoundIndex()) {
+            // Use native SQL: (col1 = ? AND col2 = ?) OR (col1 = ? AND col2 = ?) OR ...
+            const columns = this.getCompoundColumns();
+            const orConditions: SQLiteCondition[] = values.map((value) => ({
+                type: 'compoundEquals' as const,
+                columns,
+                values: this.getCompoundValues(value),
+            }));
+            return this.createCollectionWithCondition({
+                type: 'or',
+                conditions: orConditions,
+            });
+        }
+        return this.createCollectionWithCondition({
+            type: 'in',
+            column: this.getColumn(),
+            values,
+        });
+    }
+
+    anyOfIgnoreCase(...args: any[]): StorageCollection<T> {
+        const values = this.flattenArgs<string>(args);
+        if (this.isCompoundIndex()) {
+            const lowerValues = values.map((v) => v.toLowerCase());
+            return this.createCollectionWithJsPredicate((record) => {
+                const value = String(this.getIndexValue(record) ?? '').toLowerCase();
+                return lowerValues.includes(value);
+            });
+        }
+        return this.createCollectionWithCondition({
+            type: 'in',
+            column: this.getColumn(),
+            values,
+            caseInsensitive: true,
+        });
+    }
+
+    noneOf(...args: any[]): StorageCollection<T> {
+        const values = this.flattenArgs<any>(args);
+        if (this.isCompoundIndex()) {
+            return this.createCollectionWithJsPredicate((record) =>
+                values.every((candidate) => this.table.compareValues(this.getIndexValue(record), candidate) !== 0),
+            );
+        }
+        return this.createCollectionWithCondition({
+            type: 'notIn',
+            column: this.getColumn(),
+            values,
+        });
+    }
+
+    notEqual(value: any): StorageCollection<T> {
+        if (this.isCompoundIndex()) {
+            return this.createCollectionWithJsPredicate((record) => this.table.compareValues(this.getIndexValue(record), value) !== 0);
+        }
+        return this.createCollectionWithCondition({
+            type: 'comparison',
+            column: this.getColumn(),
+            op: '!=',
+            value,
+        });
+    }
+}

package/src/storage/sqlite/SqliteQueryContext.ts

@@ -0,0 +1,30 @@
+import type { StorageTable, StorageTransactionContext, TransactionMode } from '../types';
+import type { SQLiteDatabaseDriver, SQLiteRunResult } from './types';
+import { SQLiteAdapter } from './SQLiteAdapter';
+
+export class SqliteQueryContext {
+    constructor(
+        private readonly driver: SQLiteDatabaseDriver,
+        private readonly adapter: SQLiteAdapter,
+    ) {}
+
+    table<T = any>(name: string): StorageTable<T> {
+        return this.adapter.table(name);
+    }
+
+    transaction<T>(mode: TransactionMode, tableNames: string[], callback: (context: StorageTransactionContext) => Promise<T>): Promise<T> {
+        return this.adapter.transaction(mode, tableNames, callback);
+    }
+
+    async execute(statement: string): Promise<void> {
+        return this.driver.execute(statement);
+    }
+
+    async run(statement: string, values?: any[]): Promise<SQLiteRunResult> {
+        return this.driver.run(statement, values);
+    }
+
+    async queryRows(statement: string, values?: any[]): Promise<Array<Record<string, any>>> {
+        return this.adapter.queryRows(statement, values);
+    }
+}

package/src/storage/sqlite/drivers/BetterSqlite3Driver.ts

@@ -0,0 +1,156 @@
+import type { SQLiteDatabaseDriver, SQLiteQueryResult, SQLiteRunResult } from '../types';
+
+/**
+ * Options for configuring the BetterSqlite3Driver.
+ */
+export interface BetterSqlite3DriverOptions {
+    /**
+     * Open the database in readonly mode.
+     * @default false
+     */
+    readonly?: boolean;
+
+    /**
+     * Create the database file if it doesn't exist.
+     * Set to false to throw an error if the file doesn't exist.
+     * @default true
+     */
+    fileMustExist?: boolean;
+
+    /**
+     * Timeout in milliseconds when waiting for the database to become unlocked.
+     * @default 5000
+     */
+    timeout?: number;
+
+    /**
+     * Enable verbose mode for debugging SQL statements.
+     */
+    verbose?: (message?: unknown, ...additionalArgs: unknown[]) => void;
+
+    /**
+     * Enable WAL (Write-Ahead Logging) mode for better concurrent access.
+     * Recommended for most use cases.
+     * @default true
+     */
+    wal?: boolean;
+}
+
+/**
+ * SQLite driver for Node.js using better-sqlite3.
+ * This driver is synchronous but wraps operations in Promises for API compatibility.
+ *
+ * @example
+ * ```ts
+ * import { BetterSqlite3Driver } from '@anfenn/dync/node';
+ * import { SQLiteAdapter } from '@anfenn/dync';
+ *
+ * const driver = new BetterSqlite3Driver('myapp.db', { wal: true });
+ * const adapter = new SQLiteAdapter('myapp', driver);
+ * ```
+ */
+export class BetterSqlite3Driver implements SQLiteDatabaseDriver {
+    readonly type = 'BetterSqlite3Driver';
+    private db: import('better-sqlite3').Database | null = null;
+    private readonly options: BetterSqlite3DriverOptions;
+    private opened = false;
+    readonly name: string;
+
+    constructor(databasePath: string, options: BetterSqlite3DriverOptions = {}) {
+        this.name = databasePath;
+        this.options = {
+            wal: true,
+            ...options,
+        };
+    }
+
+    async open(): Promise<void> {
+        if (this.opened) return;
+
+        // Dynamic import to avoid bundling issues in non-Electron environments
+        const Database = (await import('better-sqlite3')).default;
+
+        this.db = new Database(this.name, {
+            readonly: this.options.readonly ?? false,
+            fileMustExist: this.options.fileMustExist ?? false,
+            timeout: this.options.timeout ?? 5000,
+            verbose: this.options.verbose,
+        });
+
+        // Enable WAL mode for better concurrent access (recommended)
+        if (this.options.wal && !this.options.readonly) {
+            this.db.pragma('journal_mode = WAL');
+        }
+
+        this.opened = true;
+    }
+
+    async close(): Promise<void> {
+        if (!this.db) return;
+
+        this.db.close();
+        this.db = null;
+        this.opened = false;
+    }
+
+    async execute(statement: string): Promise<void> {
+        await this.open();
+        this.db!.exec(statement);
+    }
+
+    async run(statement: string, values: unknown[] = []): Promise<SQLiteRunResult> {
+        await this.open();
+
+        const stmt = this.db!.prepare(statement);
+        const result = stmt.run(...values);
+
+        return {
+            changes: result.changes,
+            lastId: result.lastInsertRowid !== undefined ? Number(result.lastInsertRowid) : undefined,
+        };
+    }
+
+    async query(statement: string, values: unknown[] = []): Promise<SQLiteQueryResult> {
+        await this.open();
+
+        const stmt = this.db!.prepare(statement);
+        const rows = stmt.all(...values) as Record<string, unknown>[];
+
+        if (rows.length === 0) {
+            return { columns: [], values: [] };
+        }
+
+        const firstRow = rows[0]!;
+        const columns = Object.keys(firstRow);
+        const valuesMatrix = rows.map((row) => columns.map((col) => row[col]));
+
+        return { columns, values: valuesMatrix };
+    }
+
+    /**
+     * Access the underlying better-sqlite3 Database instance for advanced operations.
+     * Returns null if the database is not open.
+     */
+    getDatabase(): import('better-sqlite3').Database | null {
+        return this.db;
+    }
+
+    /**
+     * Execute a function within a transaction.
+     * This provides better performance when doing many writes.
+     *
+     * @example
+     * ```ts
+     * await driver.transaction(() => {
+     *   driver.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
+     *   driver.run('INSERT INTO users (name) VALUES (?)', ['Bob']);
+     * });
+     * ```
+     */
+    transaction<T>(fn: () => T): T {
+        if (!this.db) {
+            throw new Error('Database not open. Call open() first.');
+        }
+        return this.db.transaction(fn)();
+    }
+}

package/src/storage/sqlite/drivers/CapacitorFastSqlDriver.ts

@@ -0,0 +1,114 @@
+import type { SQLConnection, SQLValue } from '@capgo/capacitor-fast-sql';
+
+import type { SQLiteDatabaseDriver, SQLiteRunResult, SQLiteQueryResult } from '../types';
+
+export interface FastSqlDriverOptions {
+    encrypted?: boolean;
+    getEncryptionKey?: () => string;
+    readonly?: boolean;
+}
+
+// Lazily loaded module cache to avoid top-level imports that break web bundlers
+let fastSqlModuleCache: typeof import('@capgo/capacitor-fast-sql') | null = null;
+
+async function getFastSqlModule(): Promise<typeof import('@capgo/capacitor-fast-sql')> {
+    if (!fastSqlModuleCache) {
+        fastSqlModuleCache = await import('@capgo/capacitor-fast-sql');
+    }
+    return fastSqlModuleCache;
+}
+
+/**
+ * SQLiteDatabaseDriver implementation for @capgo/capacitor-fast-sql plugin.
+ *
+ * This driver provides a compatible interface with the existing SQLiteAdapter
+ * while using the Capgo Fast SQL plugin which offers better performance through
+ * a local HTTP server approach that bypasses Capacitor's bridge.
+ * 
+ * Update your AndroidManifest.xml to allow cleartext traffic:
+ * <application
+        ...
+        android:usesCleartextTraffic="true">
+
+    Requires Capacitor HTTP plugin to prevent CORS, as FastSql server runs on localhost:9000, not Capacitor's localhost
+ */
+export class CapacitorFastSqlDriver implements SQLiteDatabaseDriver {
+    readonly type = 'CapacitorFastSqlDriver';
+    private readonly options: FastSqlDriverOptions;
+    private db?: SQLConnection;
+    private openPromise?: Promise<void>;
+    private opened = false;
+    readonly name: string;
+
+    constructor(databaseName: string, options: FastSqlDriverOptions = {}) {
+        this.name = databaseName;
+        this.options = options;
+    }
+
+    async open(): Promise<void> {
+        if (this.opened) return;
+        if (this.openPromise) return this.openPromise;
+
+        this.openPromise = (async () => {
+            if (!this.db) {
+                const { FastSQL } = await getFastSqlModule();
+                const encryptionKey = this.options.getEncryptionKey?.();
+                if (!encryptionKey && this.options.encrypted) {
+                    throw new Error('FastSqlDriverOptions.encrypted=true but no encryption key was provided (getEncryptionKey).');
+                }
+                this.db = await FastSQL.connect({
+                    database: this.name,
+                    encrypted: this.options.encrypted,
+                    encryptionKey,
+                    readOnly: this.options.readonly,
+                });
+                this.opened = true;
+            }
+        })();
+
+        try {
+            await this.openPromise;
+        } finally {
+            this.openPromise = undefined;
+        }
+    }
+
+    async close(): Promise<void> {
+        if (this.db) {
+            const { FastSQL } = await getFastSqlModule();
+            await FastSQL.disconnect(this.name);
+            this.db = undefined;
+            this.opened = false;
+            this.openPromise = undefined;
+        }
+    }
+
+    async execute(statement: string): Promise<void> {
+        await this.open();
+        await this.db!.execute(statement);
+    }
+
+    async run(statement: string, values: any[] = []): Promise<SQLiteRunResult> {
+        await this.open();
+        const result = await this.db!.run(statement, values as SQLValue[]);
+        return {
+            changes: result.rowsAffected,
+            lastId: result.insertId,
+        };
+    }
+
+    async query(statement: string, values: any[] = []): Promise<SQLiteQueryResult> {
+        await this.open();
+        const rows = await this.db!.query(statement, values as SQLValue[]);
+
+        // Convert array of objects to columns + values format expected by adapter
+        if (!rows.length) {
+            return { columns: [], values: [] };
+        }
+
+        const columns = Object.keys(rows[0]!);
+        const resultValues = rows.map((row) => columns.map((col) => (row as Record<string, any>)[col]));
+
+        return { columns, values: resultValues };
+    }
+}