@capgo/capacitor-fast-sql 8.2.17 → 8.3.0

package/dist/esm/native-sql-connection.js

@@ -1,3 +1,4 @@
+import { BINARY_CONTENT_TYPE, decodeBinaryFrame, encodeBinaryFrame, MAX_FRAME_BYTES } from './binary-frame';
 import { IsolationLevel } from './definitions';
 import { assertSupportedIsolation } from './transaction-isolation';
 /**
@@ -7,8 +8,20 @@ import { assertSupportedIsolation } from './transaction-isolation';
  * Inspired by capacitor-blob-writer's approach to avoid serialization overhead.
  */
 export class NativeSQLConnection {
-    constructor(database, port, token) {
+    /** Cumulative data-request payload bytes and JS codec time; excludes HTTP headers/compression. */
+    getTransportMetrics() {
+        return Object.assign({}, this.metrics);
+    }
+    constructor(database, port, token, transport = 'http-json') {
+        this.transport = transport;
         this.inTransaction = false;
+        this.metrics = {
+            dataRequests: 0,
+            requestBytes: 0,
+            responseBytes: 0,
+            encodeMs: 0,
+            decodeMs: 0,
+        };
         this.database = database;
         this.port = port;
         this.token = token;
@@ -33,24 +46,7 @@ export class NativeSQLConnection {
      * @returns Query results
      */
     async execute(statement, params) {
-        const response = await this.browserFetch(`${this.baseUrl}/execute`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${this.token}`,
-                'X-Database': this.database,
-            },
-            body: JSON.stringify({
-                statement,
-                params: params ? this.serializeParams(params) : [],
-            }),
-        });
-        if (!response.ok) {
-            const error = await response.text();
-            throw new Error(`SQL execution failed: ${error}`);
-        }
-        const result = await response.json();
-        return this.deserializeResult(result);
+        return this.parseResult(await this.request('/execute', { statement, params: params !== null && params !== void 0 ? params : [] }));
     }
     /**
      * Execute multiple SQL statements in a batch for better performance
@@ -59,26 +55,138 @@ export class NativeSQLConnection {
      * @returns Array of results for each operation
      */
     async executeBatch(operations) {
-        const response = await this.browserFetch(`${this.baseUrl}/batch`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${this.token}`,
-                'X-Database': this.database,
-            },
-            body: JSON.stringify({
-                operations: operations.map((op) => ({
-                    statement: op.statement,
-                    params: op.params ? this.serializeParams(op.params) : [],
-                })),
-            }),
+        const result = await this.request('/batch', {
+            operations: operations.map((operation) => { var _a; return ({ statement: operation.statement, params: (_a = operation.params) !== null && _a !== void 0 ? _a : [] }); }),
         });
-        if (!response.ok) {
-            const error = await response.text();
-            throw new Error(`SQL batch execution failed: ${error}`);
+        if (!Array.isArray(result))
+            throw new Error('Invalid batch response');
+        return result.map((item) => this.parseResult(item));
+    }
+    /** Authenticated transport round trip without SQLite, for diagnostic benchmarks. */
+    async echo(value) {
+        const result = this.parseResult(await this.request('/echo', { statement: '', params: [value] }));
+        if (result.rows.length !== 1 || !('value' in result.rows[0]))
+            throw new Error('Invalid echo response');
+        return result.rows[0].value;
+    }
+    async request(path, payload) {
+        var _a;
+        const binary = this.transport === 'http-binary';
+        const start = performance.now();
+        const body = binary
+            ? encodeBinaryFrame(payload)
+            : new TextEncoder().encode(JSON.stringify('params' in payload
+                ? Object.assign(Object.assign({}, payload), { params: this.serializeParams(payload.params) }) : {
+                operations: payload.operations.map((operation) => (Object.assign(Object.assign({}, operation), { params: this.serializeParams(operation.params) }))),
+            }));
+        if (body.byteLength > MAX_FRAME_BYTES)
+            throw new Error('Request exceeds 64 MiB');
+        this.metrics.encodeMs += performance.now() - start;
+        this.metrics.dataRequests++;
+        this.metrics.requestBytes += body.byteLength;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 600000);
+        try {
+            const response = await this.browserFetch(`${this.baseUrl}${path}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': binary ? BINARY_CONTENT_TYPE : 'application/json',
+                    Authorization: `Bearer ${this.token}`,
+                    'X-Database': this.database,
+                },
+                body: body.buffer,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorBody = await this.readResponse(response);
+                throw new Error(`SQL request failed (${response.status}): ${new TextDecoder().decode(errorBody).slice(0, 4096)}`);
+            }
+            if (binary && ((_a = response.headers.get('content-type')) === null || _a === void 0 ? void 0 : _a.split(';')[0].trim()) !== BINARY_CONTENT_TYPE)
+                throw new Error('Server did not return binary HTTP v1');
+            const bytes = await this.readResponse(response);
+            this.metrics.responseBytes += bytes.byteLength;
+            const decodeStart = performance.now();
+            const result = binary ? decodeBinaryFrame(bytes) : JSON.parse(new TextDecoder().decode(bytes));
+            this.metrics.decodeMs += performance.now() - decodeStart;
+            return result;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async readResponse(response) {
+        var _a;
+        const declared = response.headers.get('content-length');
+        if (declared !== null && Number(declared) > MAX_FRAME_BYTES) {
+            await ((_a = response.body) === null || _a === void 0 ? void 0 : _a.cancel());
+            throw new Error('Response exceeds 64 MiB');
+        }
+        if (!response.body)
+            return new Uint8Array();
+        const reader = response.body.getReader();
+        const chunks = [];
+        let length = 0;
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                length += chunk.value.byteLength;
+                if (length > MAX_FRAME_BYTES) {
+                    await reader.cancel();
+                    throw new Error('Response exceeds 64 MiB');
+                }
+                chunks.push(chunk.value);
+            }
+        }
+        finally {
+            reader.releaseLock();
         }
-        const results = await response.json();
-        return results.map((r) => this.deserializeResult(r));
+        const result = new Uint8Array(length);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return result;
+    }
+    parseResult(result) {
+        const start = performance.now();
+        if (!result ||
+            typeof result !== 'object' ||
+            !('rows' in result) ||
+            !Array.isArray(result.rows) ||
+            !('rowsAffected' in result) ||
+            typeof result.rowsAffected !== 'number')
+            throw new Error('Invalid SQL response');
+        const rows = result.rows.map((row) => {
+            if (!row || typeof row !== 'object' || Array.isArray(row))
+                throw new Error('Invalid SQL row');
+            const parsed = {};
+            for (const [key, value] of Object.entries(row)) {
+                let scalar;
+                if (value === null ||
+                    typeof value === 'string' ||
+                    typeof value === 'boolean' ||
+                    value instanceof Uint8Array ||
+                    (typeof value === 'number' && Number.isFinite(value)))
+                    scalar = value;
+                else if (value &&
+                    typeof value === 'object' &&
+                    '_type' in value &&
+                    value._type === 'binary' &&
+                    '_data' in value &&
+                    typeof value._data === 'string')
+                    scalar = this.base64ToUint8Array(value._data);
+                else
+                    throw new Error('Invalid SQL value');
+                Object.defineProperty(parsed, key, { value: scalar, enumerable: true, writable: true, configurable: true });
+            }
+            return parsed;
+        });
+        const insertId = 'insertId' in result && typeof result.insertId === 'number' ? result.insertId : undefined;
+        this.metrics.decodeMs += performance.now() - start;
+        return { rows, rowsAffected: result.rowsAffected, insertId };
     }
     /**
      * Begin a transaction
@@ -205,28 +313,6 @@ export class NativeSQLConnection {
             return param;
         });
     }
-    /**
-     * Deserialize result from server
-     * Base64-encoded binary data is converted back to Uint8Array
-     */
-    deserializeResult(result) {
-        return {
-            rows: result.rows.map((row) => {
-                const deserializedRow = {};
-                for (const [key, value] of Object.entries(row)) {
-                    if (value && typeof value === 'object' && value._type === 'binary') {
-                        deserializedRow[key] = this.base64ToUint8Array(value._data);
-                    }
-                    else {
-                        deserializedRow[key] = value;
-                    }
-                }
-                return deserializedRow;
-            }),
-            rowsAffected: result.rowsAffected || 0,
-            insertId: result.insertId,
-        };
-    }
     /**
      * Convert Uint8Array to base64 string
      */

package/dist/esm/web.d.ts

@@ -23,6 +23,7 @@ export declare class CapgoCapacitorFastSqlWeb extends WebPlugin implements Capgo
         port: number;
         token: string;
         database: string;
+        persistent: boolean;
     }>;
     disconnect(options: {
         database: string;
@@ -32,6 +33,7 @@ export declare class CapgoCapacitorFastSqlWeb extends WebPlugin implements Capgo
     }): Promise<{
         port: number;
         token: string;
+        persistent: boolean;
     }>;
     execute(options: {
         database: string;

package/dist/esm/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5C,OAAO,KAAK,EACV,2BAA2B,EAC3B,oBAAoB,EACpB,SAAS,EACT,QAAQ,EACR,cAAc,EACd,SAAS,EACV,MAAM,eAAe,CAAC;AAevB;;;;;;GAMG;AACH,qBAAa,wBAAyB,SAAQ,SAAU,YAAW,2BAA2B;IAC5F,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,eAAe,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,SAAS,CAAiB;IAElC;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,MAAM;IAOR,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAsDlG,UAAU,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxD,aAAa,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAYtF,OAAO,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IA+ClG,gBAAgB,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/F,iBAAiB,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/D,mBAAmB,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAOzD,sBAAsB;IAkBpC,OAAO,CAAC,aAAa;IAMf,gBAAgB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAGvD"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5C,OAAO,KAAK,EACV,2BAA2B,EAC3B,oBAAoB,EACpB,SAAS,EACT,QAAQ,EACR,cAAc,EACd,SAAS,EACV,MAAM,eAAe,CAAC;AAevB;;;;;;GAMG;AACH,qBAAa,wBAAyB,SAAQ,SAAU,YAAW,2BAA2B;IAC5F,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,eAAe,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,SAAS,CAAiB;IAElC;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAWpD,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,MAAM;IAOR,OAAO,CACX,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;IAkE5E,UAAU,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxD,aAAa,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;IAa3G,OAAO,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IA+ClG,gBAAgB,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/F,iBAAiB,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/D,mBAAmB,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAOzD,sBAAsB;IAkBpC,OAAO,CAAC,aAAa;IAMf,gBAAgB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAGvD"}

package/dist/esm/web.js

@@ -21,7 +21,13 @@ export class CapgoCapacitorFastSqlWeb extends WebPlugin {
      * Must be called before connect() when overriding the default worker.
      */
     async configureWeb(config) {
-        this.webConfig = config;
+        if (this.promiserPromise || this.databases.size > 0) {
+            throw new Error('Configure web storage before opening the first database');
+        }
+        if (config.requirePersistence && config.useOpfs === false) {
+            throw new Error('requirePersistence requires OPFS');
+        }
+        this.webConfig = Object.assign({}, config);
         this.promiserPromise = null;
     }
     getPromiser() {
@@ -38,6 +44,8 @@ export class CapgoCapacitorFastSqlWeb extends WebPlugin {
         return `/capgo-fast-sql/${database}.sqlite3`;
     }
     async connect(options) {
+        if (options.transport === 'http-binary')
+            throw new Error('Binary HTTP transport requires iOS or Android');
         if (options.readOnly) {
             throw new Error('Read-only opens are not supported by the SQLite Wasm Worker transport');
         }
@@ -47,6 +55,7 @@ export class CapgoCapacitorFastSqlWeb extends WebPlugin {
                 port: existing.port,
                 token: existing.token,
                 database: options.database,
+                persistent: existing.persistent,
             };
         }
         const path = this.dbPath(options.database);
@@ -60,6 +69,8 @@ export class CapgoCapacitorFastSqlWeb extends WebPlugin {
                 });
             }
             catch (opfsError) {
+                if (this.webConfig.requirePersistence)
+                    throw opfsError;
                 console.warn('[CapgoCapacitorFastSql] OPFS unavailable; web database will not persist across reloads. ' +
                     'Serve with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp.', opfsError);
                 openResult = await promiser('open', { filename: path });
@@ -73,7 +84,16 @@ export class CapgoCapacitorFastSqlWeb extends WebPlugin {
         if (!dbId) {
             throw new Error('Failed to open SQLite Wasm database: missing dbId');
         }
-        await this.applyPerformanceConfig(promiser, dbId, options);
+        try {
+            if (this.webConfig.requirePersistence && !persistent) {
+                throw new Error('SQLite Worker did not confirm persistent storage');
+            }
+            await this.applyPerformanceConfig(promiser, dbId, options);
+        }
+        catch (error) {
+            await promiser({ type: 'close', dbId, args: {} });
+            throw error;
+        }
         const token = this.generateToken();
         const port = this.nextPort++;
         this.databases.set(options.database, { dbId, token, port, persistent });
@@ -81,6 +101,7 @@ export class CapgoCapacitorFastSqlWeb extends WebPlugin {
             port,
             token,
             database: options.database,
+            persistent,
         };
     }
     async disconnect(options) {
@@ -101,6 +122,7 @@ export class CapgoCapacitorFastSqlWeb extends WebPlugin {
         return {
             port: dbInfo.port,
             token: dbInfo.token,
+            persistent: dbInfo.persistent,
         };
     }
     async execute(options) {