@capgo/capacitor-fast-sql 8.2.18 → 8.3.1

package/android/src/main/java/app/capgo/capacitor/fastsql/SQLHTTPServer.java

@@ -3,15 +3,20 @@ package app.capgo.capacitor.fastsql;
 import com.getcapacitor.JSArray;
 import com.getcapacitor.JSObject;
 import fi.iki.elonen.NanoHTTPD; // Note: org.nanohttpd:nanohttpd:2.3.1 still uses fi.iki.elonen package
+import java.io.ByteArrayInputStream;
 import java.io.DataInputStream;
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.security.SecureRandom;
-import java.util.List;
 import java.util.Map;
+import java.util.concurrent.ArrayBlockingQueue;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.ExecutorService;
-import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.RejectedExecutionException;
+import java.util.concurrent.ThreadPoolExecutor;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
 import org.json.JSONArray;
 import org.json.JSONObject;
 
@@ -25,12 +30,19 @@ public class SQLHTTPServer extends NanoHTTPD {
 
     private final String token;
     private final Map<String, DatabaseConnection> databases;
-    private final ExecutorService requestExecutor = Executors.newSingleThreadExecutor((runnable) -> {
-        Thread thread = new Thread(runnable);
-        thread.setName("FastSQL-DB");
-        thread.setDaemon(true);
-        return thread;
-    });
+    private final ExecutorService requestExecutor = new ThreadPoolExecutor(
+        1,
+        1,
+        0,
+        TimeUnit.MILLISECONDS,
+        new ArrayBlockingQueue<>(32),
+        (runnable) -> {
+            Thread thread = new Thread(runnable);
+            thread.setName("FastSQL-DB");
+            thread.setDaemon(true);
+            return thread;
+        }
+    );
 
     public SQLHTTPServer(Map<String, DatabaseConnection> databases) throws IOException {
         super("127.0.0.1", 0);
@@ -54,6 +66,11 @@ public class SQLHTTPServer extends NanoHTTPD {
         return response;
     }
 
+    @Override
+    protected boolean useGzipWhenAccepted(Response response) {
+        return BinaryFrame.CONTENT_TYPE.equals(response.getMimeType()) || super.useGzipWhenAccepted(response);
+    }
+
     @Override
     public void stop() {
         super.stop();
@@ -81,9 +98,25 @@ public class SQLHTTPServer extends NanoHTTPD {
             return addCorsHeaders(newFixedLengthResponse(Response.Status.NOT_FOUND, "text/plain", "Database not found"));
         }
 
+        Future<Response> request = null;
         try {
-            return requestExecutor.submit(() -> routeRequest(session, db)).get();
+            request = requestExecutor.submit(() -> routeRequest(session, db));
+            return request.get(600, TimeUnit.SECONDS);
+        } catch (TimeoutException | RejectedExecutionException error) {
+            if (request != null) request.cancel(false);
+            Response response = newFixedLengthResponse(
+                Response.Status.SERVICE_UNAVAILABLE,
+                "text/plain",
+                "Request unavailable; a timed-out write may still complete. Do not automatically retry."
+            );
+            response.closeConnection(true);
+            return addCorsHeaders(response);
         } catch (ExecutionException e) {
+            if (e.getCause() instanceof IOException || e.getCause() instanceof org.json.JSONException) {
+                Response response = newFixedLengthResponse(Response.Status.BAD_REQUEST, "text/plain", "Invalid SQL/frame request");
+                response.closeConnection(true);
+                return addCorsHeaders(response);
+            }
             Throwable cause = e.getCause();
             String message = cause != null ? cause.getMessage() : e.getMessage();
             return addCorsHeaders(newFixedLengthResponse(Response.Status.INTERNAL_ERROR, "text/plain", "Error: " + message));
@@ -97,10 +130,8 @@ public class SQLHTTPServer extends NanoHTTPD {
         String uri = session.getUri();
         Method method = session.getMethod();
 
-        if (method == Method.POST && uri.equals("/execute")) {
-            return addCorsHeaders(handleExecute(session, db));
-        } else if (method == Method.POST && uri.equals("/batch")) {
-            return addCorsHeaders(handleBatch(session, db));
+        if (method == Method.POST && (uri.equals("/execute") || uri.equals("/batch") || uri.equals("/echo"))) {
+            return addCorsHeaders(handleDataRequest(session, db));
         } else if (method == Method.POST && uri.equals("/transaction/begin")) {
             return addCorsHeaders(handleBeginTransaction(session, db));
         } else if (method == Method.POST && uri.equals("/transaction/commit")) {
@@ -112,50 +143,64 @@ public class SQLHTTPServer extends NanoHTTPD {
         }
     }
 
-    private Response handleExecute(IHTTPSession session, DatabaseConnection db) throws Exception {
-        // Read request body
-        String body = readRequestBody(session);
-        JSONObject request = new JSONObject(body);
-
-        String statement = request.getString("statement");
-        JSONArray paramsJson = request.has("params") ? request.getJSONArray("params") : new JSONArray();
-
-        JSArray params = new JSArray();
-        String rawParamsArray = request.has("params") ? HttpRequestJsonParams.extractJsonArrayAfterKey(body, "params") : null;
-        HttpRequestJsonParams.populateJsArrayFromParamsJson(paramsJson, params, rawParamsArray);
-
-        // Execute query
-        JSObject result = db.execute(statement, params);
-
-        // Convert result to JSON
-        String resultJson = result.toString();
-        return newFixedLengthResponse(Response.Status.OK, "application/json", resultJson);
+    private Response handleDataRequest(IHTTPSession session, DatabaseConnection db) throws Exception {
+        boolean binary = BinaryFrame.CONTENT_TYPE.equals(session.getHeaders().get("content-type"));
+        byte[] bytes = readRequestBytes(session);
+        Object decoded = binary ? BinaryFrame.decode(bytes) : new JSONObject(new String(bytes, StandardCharsets.UTF_8));
+        if (!(decoded instanceof JSONObject)) throw new IOException("Expected SQL request object");
+        JSONObject request = (JSONObject) decoded;
+        Object result;
+        if (session.getUri().equals("/batch")) {
+            JSONArray operations = request.getJSONArray("operations");
+            if (operations.length() > 10000) throw new IOException("Too many batch operations");
+            for (int i = 0; i < operations.length(); i++) validateOperation(operations.getJSONObject(i));
+            JSONArray results = new JSONArray();
+            for (int i = 0; i < operations.length(); i++) results.put(executeOperation(db, operations.getJSONObject(i), binary));
+            result = results;
+        } else {
+            validateOperation(request);
+            if (session.getUri().equals("/echo")) {
+                JSObject row = new JSObject();
+                if (request.getJSONArray("params").length() != 1) throw new IOException("Echo requires one parameter");
+                row.put("value", request.getJSONArray("params").get(0));
+                JSObject echo = new JSObject();
+                echo.put("rows", new JSONArray().put(row));
+                echo.put("rowsAffected", 0);
+                result = echo;
+            } else result = executeOperation(db, request, binary);
+        }
+        if (!binary) return newFixedLengthResponse(Response.Status.OK, "application/json", result.toString());
+        byte[] response;
+        try {
+            response = BinaryFrame.encode(result);
+        } catch (Exception error) {
+            throw new IllegalStateException("Could not encode SQL response; a write may already be committed", error);
+        }
+        return newFixedLengthResponse(Response.Status.OK, BinaryFrame.CONTENT_TYPE, new ByteArrayInputStream(response), response.length);
     }
 
-    private Response handleBatch(IHTTPSession session, DatabaseConnection db) throws Exception {
-        // Read request body
-        String body = readRequestBody(session);
-        JSONObject request = new JSONObject(body);
-        JSONArray operations = request.getJSONArray("operations");
-
-        JSONArray results = new JSONArray();
-        String rawOperationsArray = HttpRequestJsonParams.extractJsonArrayAfterKey(body, "operations");
-        List<String> rawOperations = HttpRequestJsonParams.splitTopLevelJsonArrayElements(rawOperationsArray);
-        for (int i = 0; i < operations.length(); i++) {
-            JSONObject operation = operations.getJSONObject(i);
-            String statement = operation.getString("statement");
-            JSONArray paramsJson = operation.has("params") ? operation.getJSONArray("params") : new JSONArray();
-
-            JSArray params = new JSArray();
-            String rawOperation = rawOperations.get(i);
-            String rawParamsArray = operation.has("params") ? HttpRequestJsonParams.extractJsonArrayAfterKey(rawOperation, "params") : null;
-            HttpRequestJsonParams.populateJsArrayFromParamsJson(paramsJson, params, rawParamsArray);
-
-            JSObject result = db.execute(statement, params);
-            results.put(result);
+    private static void validateOperation(JSONObject operation) throws Exception {
+        if (!(operation.get("statement") instanceof String)) throw new IOException("Expected SQL statement");
+        JSONArray params = operation.optJSONArray("params");
+        if (operation.has("params") && params == null) throw new IOException("Expected parameter array");
+        if (params == null) return;
+        for (int i = 0; i < params.length(); i++) {
+            Object value = params.get(i);
+            if (value == JSONObject.NULL || value instanceof String || value instanceof Boolean || value instanceof byte[]) continue;
+            if (value instanceof Number && Double.isFinite(((Number) value).doubleValue())) continue;
+            if (value instanceof JSONObject) {
+                JSONObject blob = (JSONObject) value;
+                if ("binary".equals(blob.optString("_type")) && blob.opt("_data") instanceof String) continue;
+            }
+            throw new IOException("Unsupported SQL parameter");
         }
+    }
 
-        return newFixedLengthResponse(Response.Status.OK, "application/json", results.toString());
+    private static JSObject executeOperation(DatabaseConnection db, JSONObject operation, boolean binary) throws Exception {
+        JSONArray input = operation.optJSONArray("params");
+        JSArray params = new JSArray();
+        if (input != null) for (int i = 0; i < input.length(); i++) params.put(input.get(i));
+        return binary ? db.executeBinary(operation.getString("statement"), params) : db.execute(operation.getString("statement"), params);
     }
 
     private Response handleBeginTransaction(IHTTPSession session, DatabaseConnection db) throws Exception {
@@ -185,10 +230,22 @@ public class SQLHTTPServer extends NanoHTTPD {
     }
 
     private String readRequestBody(IHTTPSession session) throws IOException {
-        int contentLength = Integer.parseInt(session.getHeaders().get("content-length"));
-        byte[] buffer = new byte[contentLength];
-        new DataInputStream(session.getInputStream()).readFully(buffer);
-        return new String(buffer, StandardCharsets.UTF_8);
+        return new String(readRequestBytes(session), StandardCharsets.UTF_8);
+    }
+
+    private byte[] readRequestBytes(IHTTPSession session) throws IOException {
+        if (session.getHeaders().containsKey("transfer-encoding")) throw new IOException("Chunked requests are unsupported");
+        String header = session.getHeaders().get("content-length");
+        long length;
+        try {
+            length = header == null ? 0 : Long.parseLong(header);
+        } catch (NumberFormatException error) {
+            throw new IOException("Invalid Content-Length", error);
+        }
+        if (length < 0 || length > BinaryFrame.MAX_BYTES) throw new IOException("Request exceeds 64 MiB");
+        byte[] bytes = new byte[(int) length];
+        new DataInputStream(session.getInputStream()).readFully(bytes);
+        return bytes;
     }
 
     private static String generateToken() {

package/dist/esm/binary-frame.d.ts

@@ -0,0 +1,6 @@
+/** Version 1 frame: FSQ1, uint32-LE metadata length, uint32-LE attachment length. */
+export declare const BINARY_CONTENT_TYPE = "application/vnd.capgo.fast-sql.v1+binary";
+export declare const MAX_FRAME_BYTES: number;
+export declare function encodeBinaryFrame(value: unknown): Uint8Array<ArrayBuffer>;
+export declare function decodeBinaryFrame(frame: Uint8Array): unknown;
+//# sourceMappingURL=binary-frame.d.ts.map

package/dist/esm/binary-frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-frame.d.ts","sourceRoot":"","sources":["../../src/binary-frame.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,6CAA6C,CAAC;AAC9E,eAAO,MAAM,eAAe,QAAmB,CAAC;AAMhD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAAC,WAAW,CAAC,CAyCzE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAgD5D"}

package/dist/esm/binary-frame.js

@@ -0,0 +1,100 @@
+/** Version 1 frame: FSQ1, uint32-LE metadata length, uint32-LE attachment length. */
+export const BINARY_CONTENT_TYPE = 'application/vnd.capgo.fast-sql.v1+binary';
+export const MAX_FRAME_BYTES = 64 * 1024 * 1024;
+const MAX_METADATA_BYTES = 1024 * 1024;
+const MAX_ATTACHMENTS = 4096;
+const HEADER_BYTES = 12;
+const magic = [70, 83, 81, 49];
+export function encodeBinaryFrame(value) {
+    const attachments = [];
+    let size = 0;
+    let nodes = 0;
+    const encode = (item, depth) => {
+        if (++nodes > 100000 || depth > 32)
+            throw new Error('Binary metadata exceeds nesting or node limits');
+        if (typeof item === 'number' && !Number.isFinite(item))
+            throw new Error('Non-finite binary protocol number');
+        if (item instanceof Uint8Array) {
+            if (attachments.length >= MAX_ATTACHMENTS || size + item.byteLength > MAX_FRAME_BYTES - HEADER_BYTES)
+                throw new Error('Binary attachments exceed protocol limits');
+            const reference = { $blob: [size, item.byteLength] };
+            attachments.push(item);
+            size += item.byteLength;
+            return reference;
+        }
+        if (Array.isArray(item))
+            return item.map((value) => encode(value, depth + 1));
+        if (item && typeof item === 'object') {
+            if (Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null)
+                throw new Error('Unsupported binary metadata object');
+            return Object.fromEntries(Object.entries(item).map(([key, value]) => [key, encode(value, depth + 1)]));
+        }
+        return item;
+    };
+    const json = JSON.stringify(encode(value, 0));
+    if (json === undefined)
+        throw new Error('Missing binary metadata');
+    const metadata = new TextEncoder().encode(json);
+    const length = HEADER_BYTES + metadata.byteLength + size;
+    if (metadata.byteLength > MAX_METADATA_BYTES || length > MAX_FRAME_BYTES)
+        throw new Error('Binary frame exceeds protocol limits');
+    const frame = new Uint8Array(length);
+    frame.set(magic);
+    const view = new DataView(frame.buffer);
+    view.setUint32(4, metadata.byteLength, true);
+    view.setUint32(8, size, true);
+    frame.set(metadata, HEADER_BYTES);
+    let offset = HEADER_BYTES + metadata.byteLength;
+    for (const attachment of attachments) {
+        frame.set(attachment, offset);
+        offset += attachment.byteLength;
+    }
+    return frame;
+}
+export function decodeBinaryFrame(frame) {
+    if (frame.length < HEADER_BYTES ||
+        frame.length > MAX_FRAME_BYTES ||
+        magic.some((byte, index) => frame[index] !== byte)) {
+        throw new Error('Invalid binary frame version or length');
+    }
+    const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+    const metadataLength = view.getUint32(4, true);
+    const payloadLength = view.getUint32(8, true);
+    const payloadOffset = HEADER_BYTES + metadataLength;
+    if (metadataLength === 0 || metadataLength > MAX_METADATA_BYTES || payloadOffset + payloadLength !== frame.length) {
+        throw new Error('Invalid binary frame lengths');
+    }
+    const metadata = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(frame.subarray(HEADER_BYTES, payloadOffset)));
+    let nodes = 0;
+    let blobs = 0;
+    let referencedBytes = 0;
+    const decode = (value, depth) => {
+        if (++nodes > 100000 || depth > 32)
+            throw new Error('Binary metadata exceeds nesting or node limits');
+        if (Array.isArray(value))
+            return value.map((item) => decode(item, depth + 1));
+        if (value === null || typeof value !== 'object')
+            return value;
+        if ('$blob' in value && Object.keys(value).length === 1) {
+            const reference = value.$blob;
+            if (!Array.isArray(reference) || reference.length !== 2)
+                throw new Error('Invalid binary attachment reference');
+            const [offset, length] = reference;
+            if (typeof offset !== 'number' ||
+                typeof length !== 'number' ||
+                !Number.isSafeInteger(offset) ||
+                !Number.isSafeInteger(length) ||
+                offset < 0 ||
+                length < 0 ||
+                offset + length > payloadLength) {
+                throw new Error('Binary attachment is outside its frame');
+            }
+            referencedBytes += length;
+            if (++blobs > MAX_ATTACHMENTS || referencedBytes > MAX_FRAME_BYTES)
+                throw new Error('Decoded attachments exceed protocol limits');
+            return frame.slice(payloadOffset + offset, payloadOffset + offset + length);
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, decode(item, depth + 1)]));
+    };
+    return decode(metadata, 0);
+}

package/dist/esm/definitions.d.ts

@@ -38,10 +38,21 @@ export interface SQLBatchOperation {
      */
     params?: SQLValue[];
 }
+/** Native HTTP data encoding. JSON remains the compatibility default. */
+export type NativeSQLTransport = 'http-json' | 'http-binary';
 /**
  * Database connection options
  */
 export interface SQLConnectionOptions {
+    /**
+     * Native HTTP data encoding. Binary v1 sends BLOBs as raw bytes without base64.
+     * Opt-in on iOS/Android only; requires a native plugin advertising binary v1.
+     * JSON remains the default. Binary is experimental; reconsider the default only
+     * in a future major after device performance and conformance testing.
+     * No failed write is retried on another transport.
+     * @default 'http-json'
+     */
+    transport?: NativeSQLTransport;
     /**
      * Database name (file will be created in app data directory)
      */
@@ -148,6 +159,8 @@ export interface CapgoCapacitorFastSqlPlugin {
         database: string;
         /** Whether the web Worker confirms persistent storage. Absent on native. */
         persistent?: boolean;
+        /** Native binary HTTP protocol version, when supported. */
+        binaryProtocolVersion?: number;
     }>;
     /**
      * Close database connection and stop the HTTP server.
@@ -184,6 +197,8 @@ export interface CapgoCapacitorFastSqlPlugin {
         token: string;
         /** Whether the web Worker confirms persistent storage. Absent on native. */
         persistent?: boolean;
+        /** Native binary HTTP protocol version, when supported. */
+        binaryProtocolVersion?: number;
     }>;
     /**
      * Execute a SQL query via Capacitor bridge (for simple queries).
@@ -276,6 +291,8 @@ export interface CapgoCapacitorFastSqlPlugin {
      */
     getPluginVersion(): Promise<{
         version: string;
+        /** Native transport capability, available without opening a database or starting a server. */
+        binaryProtocolVersion?: number;
     }>;
     /**
      * Configure web-specific options for the official SQLite Wasm module.

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

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,UAAU,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,aAAa,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAE/B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;AACtD;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;;GAIG;AACH,oBAAY,cAAc;IACxB,eAAe,qBAAqB;IACpC,aAAa,mBAAmB;IAChC,cAAc,oBAAoB;IAClC,YAAY,iBAAiB;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAC9C,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,4EAA4E;QAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,2DAA2D;QAC3D,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC;IAEH;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QACpD,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,4EAA4E;QAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,2DAA2D;QAC3D,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC;IAEH;;;;;;;;;;;;;;;;;OAiBG;IACH,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,CAAC;IAEnG;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhG;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAAmB,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;;;;;;;;;OAWG;IACH,gBAAgB,IAAI,OAAO,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;QAChB,8FAA8F;QAC9F,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC;IAEH;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD"}

package/dist/esm/fast-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fast-sql.d.ts","sourceRoot":"","sources":["../../src/fast-sql.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD;;;;;GAKG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,MAAM,CAAC,OAAO,CAA6C;IACnE,OAAO,CAAC,MAAM,CAAC,WAAW,CAA2C;IACrE,OAAO,CAAC,MAAM,CAAC,WAAW,CAAyC;IACnE,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAA0B;IAC1D,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAkC;IACpE,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAA0B;IAE3D;;;;;OAKG;WACU,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IA0B3E,OAAO,CAAC,MAAM,CAAC,YAAY;mBAUN,IAAI;IAmBzB;;;;OAIG;WACU,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBxD;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAI5D;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIpD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAO/C;;OAEG;WACU,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBlE;;OAEG;WACU,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3C;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,IAAI,MAAM,EAAE;CAGpC"}
+{"version":3,"file":"fast-sql.d.ts","sourceRoot":"","sources":["../../src/fast-sql.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD;;;;;GAKG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,MAAM,CAAC,OAAO,CAA6C;IACnE,OAAO,CAAC,MAAM,CAAC,WAAW,CAA2C;IACrE,OAAO,CAAC,MAAM,CAAC,WAAW,CAAyC;IACnE,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAA0B;IAC1D,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAkC;IACpE,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAA0B;IAE3D;;;;;OAKG;WACU,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IA0B3E,OAAO,CAAC,MAAM,CAAC,YAAY;mBAWN,IAAI;IA0BzB;;;;OAIG;WACU,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBxD;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAI5D;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIpD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAO/C;;OAEG;WACU,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBlE;;OAEG;WACU,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3C;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,IAAI,MAAM,EAAE;CAGpC"}

package/dist/esm/fast-sql.js

@@ -43,20 +43,30 @@ export class FastSQL {
         }
     }
     static optionsMatch(left, right) {
-        return (Boolean(left.encrypted) === Boolean(right.encrypted) &&
+        var _a, _b;
+        return (((_a = left.transport) !== null && _a !== void 0 ? _a : 'http-json') === ((_b = right.transport) !== null && _b !== void 0 ? _b : 'http-json') &&
+            Boolean(left.encrypted) === Boolean(right.encrypted) &&
             left.encryptionKey === right.encryptionKey &&
             Boolean(left.readOnly) === Boolean(right.readOnly) &&
             Boolean(left.walMode) === Boolean(right.walMode) &&
             Boolean(left.performancePresets) === Boolean(right.performancePresets));
     }
     static async open(options) {
+        const platform = Capacitor.getPlatform();
+        if (options.transport === 'http-binary' && platform !== 'ios' && platform !== 'android') {
+            throw new Error('Binary HTTP transport requires iOS or Android');
+        }
+        if (options.transport === 'http-binary') {
+            const capabilities = await CapgoCapacitorFastSql.getPluginVersion();
+            if (capabilities.binaryProtocolVersion !== 1)
+                throw new Error('Native plugin does not support binary HTTP v1');
+        }
         // Connect via native plugin
         const info = await CapgoCapacitorFastSql.connect(options);
         // Create connection instance appropriate for the current platform
         let connection;
-        const platform = Capacitor.getPlatform();
         if (platform === 'android' || platform === 'ios') {
-            connection = new NativeSQLConnection(info.database, info.port, info.token);
+            connection = new NativeSQLConnection(info.database, info.port, info.token, options.transport);
         }
         else {
             connection = new WebSQLConnection(info.database, CapgoCapacitorFastSql);

package/dist/esm/native-sql-connection.d.ts

@@ -1,6 +1,13 @@
-import type { SQLValue, SQLRow, SQLResult, SQLBatchOperation } from './definitions';
+import type { SQLValue, SQLRow, SQLResult, SQLBatchOperation, NativeSQLTransport } from './definitions';
 import { IsolationLevel } from './definitions';
 import type { SQLConnection } from './sql-connection';
+export interface SQLTransportMetrics {
+    dataRequests: number;
+    requestBytes: number;
+    responseBytes: number;
+    encodeMs: number;
+    decodeMs: number;
+}
 /**
  * SQL Connection class that uses HTTP protocol for efficient communication
  * with native SQLite databases, bypassing Capacitor's standard bridge.
@@ -8,12 +15,16 @@ import type { SQLConnection } from './sql-connection';
  * Inspired by capacitor-blob-writer's approach to avoid serialization overhead.
  */
 export declare class NativeSQLConnection implements SQLConnection {
+    private readonly transport;
     private port;
     private token;
     private database;
     private baseUrl;
     private inTransaction;
-    constructor(database: string, port: number, token: string);
+    private metrics;
+    /** Cumulative data-request payload bytes and JS codec time; excludes HTTP headers/compression. */
+    getTransportMetrics(): SQLTransportMetrics;
+    constructor(database: string, port: number, token: string, transport?: NativeSQLTransport);
     private browserFetch;
     /**
      * Get the database name
@@ -34,6 +45,11 @@ export declare class NativeSQLConnection implements SQLConnection {
      * @returns Array of results for each operation
      */
     executeBatch(operations: SQLBatchOperation[]): Promise<SQLResult[]>;
+    /** Authenticated transport round trip without SQLite, for diagnostic benchmarks. */
+    echo(value: SQLValue): Promise<SQLValue>;
+    private request;
+    private readResponse;
+    private parseResult;
     /**
      * Begin a transaction
      *
@@ -79,11 +95,6 @@ export declare class NativeSQLConnection implements SQLConnection {
      * Binary data (Uint8Array) is converted to base64 for JSON transport
      */
     private serializeParams;
-    /**
-     * Deserialize result from server
-     * Base64-encoded binary data is converted back to Uint8Array
-     */
-    private deserializeResult;
     /**
      * Convert Uint8Array to base64 string
      */

package/dist/esm/native-sql-connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-sql-connection.d.ts","sourceRoot":"","sources":["../../src/native-sql-connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;gBAElB,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAOzD,OAAO,CAAC,YAAY;IAMpB;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;OAMG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAuBzE;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAyBzE;;;;OAIG;IACG,gBAAgB,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BtE;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB7B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB/B;;;;;OAKG;IACG,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAYhH;;;;;;OAMG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKtE;;;;;;OAMG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAQvG;;;OAGG;IACH,OAAO,CAAC,eAAe;IAYvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAQ3B"}
+{"version":3,"file":"native-sql-connection.d.ts","sourceRoot":"","sources":["../../src/native-sql-connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxG,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IAuBrD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAtB5B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,OAAO,CAMb;IAEF,kGAAkG;IAClG,mBAAmB,IAAI,mBAAmB;gBAKxC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACI,SAAS,GAAE,kBAAgC;IAQ9D,OAAO,CAAC,YAAY;IAMpB;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;OAMG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAIzE;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAQzE,oFAAoF;IAC9E,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;YAMhC,OAAO;YAwDP,YAAY;IAiC1B,OAAO,CAAC,WAAW;IA2CnB;;;;OAIG;IACG,gBAAgB,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BtE;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB7B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB/B;;;;;OAKG;IACG,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAYhH;;;;;;OAMG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKtE;;;;;;OAMG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAQvG;;;OAGG;IACH,OAAO,CAAC,eAAe;IAYvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAQ3B"}