@sqlitecloud/drivers 1.0.715 → 1.0.738-rc.0

package/README.md

@@ -8,18 +8,25 @@
 
 ## Install
 
+### Web / Node.js / Next.js
+
 ```bash
 npm install @sqlitecloud/drivers
 ```
 
-## React Native / Expo Install
+No additional dependencies required - the package works out of the box.
+
+### React Native / Expo
 
-You also have to install Peer Dependencies
+When using this package in React Native or Expo projects, you must install the required peer dependencies. These dependencies are optional and not installed automatically to avoid polluting web and Node.js projects with unnecessary packages.
 
 ```bash
-npm install @sqlitecloud/drivers react-native-tcp-socket react-native-quick-base64
+npm install @sqlitecloud/drivers
+npm install react-native-tcp-socket react-native-quick-base64 @craftzdog/react-native-buffer react-native-url-polyfill
 ```
 
+If you forget to install these dependencies, the package will throw clear error messages indicating which dependency is missing and how to install it.
+
 React Native run iOS
 
 ```bash

package/lib/drivers/connection-tls.js

@@ -2,48 +2,21 @@
 /**
  * connection-tls.ts - connection via tls socket and sqlitecloud protocol
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLiteCloudTlsConnection = void 0;
 const connection_1 = require("./connection");
 const protocol_1 = require("./protocol");
 const types_1 = require("./types");
 const utilities_1 = require("./utilities");
+const safe_imports_1 = require("./safe-imports");
 // explicitly importing buffer library to allow cross-platform support by replacing it
-const buffer_1 = require("buffer");
-const tls = __importStar(require("tls"));
+// In React Native: Metro resolves 'buffer' to '@craftzdog/react-native-buffer' via package.json react-native field
+// In Web/Node: Uses standard buffer package
+const Buffer = (0, safe_imports_1.getSafeBuffer)();
+// In React Native: Metro resolves 'tls' to 'react-native-tcp-socket' via package.json react-native field
+// In Node: Uses native tls module
+// In Browser: Returns null (browser field sets tls to false)
+const tls = (0, safe_imports_1.getSafeTLS)();
 /**
  * Implementation of SQLiteCloudConnection that connects to the database using specific tls APIs
  * that connect to native sockets or tls sockets and communicates via raw, binary protocol.
@@ -55,7 +28,7 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
         // onData is called when data is received, it will process the data until all data is retrieved for a response
         // when response is complete or there's an error, finish is called to call the results callback set by processCommands...
         // buffer to accumulate incoming data until an whole command is received and can be parsed
-        this.buffer = buffer_1.Buffer.alloc(0);
+        this.buffer = Buffer.alloc(0);
         this.startedOn = new Date();
         this.pendingChunks = [];
     }
@@ -66,6 +39,15 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
     /* Opens a connection with the server and sends the initialization commands. Will throw in case of errors. */
     connectTransport(config, callback) {
         console.assert(!this.connected, 'SQLiteCloudTlsConnection.connect - connection already established');
+        // Check if tls is available (it's null in browser contexts)
+        if (!tls) {
+            const error = new types_1.SQLiteCloudError('TLS connections are not available in this environment. Use WebSocket connections instead by setting usewebsocket: true in your configuration.', { errorCode: 'ERR_TLS_NOT_AVAILABLE' });
+            if (callback) {
+                callback.call(this, error);
+                return this;
+            }
+            throw error;
+        }
         if (this.config.verbose) {
             console.debug(`-> connecting ${config === null || config === void 0 ? void 0 : config.host}:${config === null || config === void 0 ? void 0 : config.port}`);
         }
@@ -106,10 +88,10 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
         // disable Nagle algorithm because we want our writes to be sent ASAP
         // https://brooker.co.za/blog/2024/05/09/nagle.html
         this.socket.setNoDelay(true);
-        this.socket.on('data', data => {
+        this.socket.on('data', (data) => {
             this.processCommandsData(data);
         });
-        this.socket.on('error', error => {
+        this.socket.on('error', (error) => {
             this.close();
             this.processCommandsFinish(new types_1.SQLiteCloudError('Connection error', { errorCode: 'ERR_CONNECTION_ERROR', cause: error }));
         });
@@ -140,7 +122,7 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
             commands = { query: commands };
         }
         // reset buffer and rowset chunks, define response callback
-        this.buffer = buffer_1.Buffer.alloc(0);
+        this.buffer = Buffer.alloc(0);
         this.startedOn = new Date();
         this.processCallback = callback;
         this.executingCommands = commands;
@@ -173,7 +155,7 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
             // append data to buffer as it arrives
             if (data.length && data.length > 0) {
                 // console.debug(`processCommandsData - received ${data.length} bytes`)
-                this.buffer = buffer_1.Buffer.concat([this.buffer, data]);
+                this.buffer = Buffer.concat([this.buffer, data]);
             }
             let dataType = (_a = this.buffer) === null || _a === void 0 ? void 0 : _a.subarray(0, 1).toString();
             if ((0, protocol_1.hasCommandLength)(dataType)) {
@@ -194,7 +176,7 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
                         if (decompressResults.dataType === protocol_1.CMD_ROWSET_CHUNK) {
                             this.pendingChunks.push(decompressResults.buffer);
                             this.buffer = decompressResults.remainingBuffer;
-                            this.processCommandsData(buffer_1.Buffer.alloc(0));
+                            this.processCommandsData(Buffer.alloc(0));
                             return;
                         }
                         else {
@@ -247,7 +229,7 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
         if (this.processCallback) {
             this.processCallback(error, result);
         }
-        this.buffer = buffer_1.Buffer.alloc(0);
+        this.buffer = Buffer.alloc(0);
         this.pendingChunks = [];
     }
     /** Disconnect immediately, release connection, no events. */

package/lib/drivers/protocol.d.ts

@@ -1,6 +1,5 @@
 import { SQLiteCloudRowset } from './rowset';
 import { SQLiteCloudCommand, type SQLCloudRowsetMetadata, type SQLiteCloudDataTypes } from './types';
-import { Buffer } from 'buffer';
 export declare const CMD_STRING = "+";
 export declare const CMD_ZEROSTRING = "!";
 export declare const CMD_ERROR = "-";

package/lib/drivers/protocol.js

@@ -17,8 +17,11 @@ exports.popData = popData;
 exports.formatCommand = formatCommand;
 const rowset_1 = require("./rowset");
 const types_1 = require("./types");
+const safe_imports_1 = require("./safe-imports");
 // explicitly importing buffer library to allow cross-platform support by replacing it
-const buffer_1 = require("buffer");
+// In React Native: Metro resolves 'buffer' to '@craftzdog/react-native-buffer' via package.json react-native field
+// In Web/Node: Uses standard buffer package
+const Buffer = (0, safe_imports_1.getSafeBuffer)();
 // https://www.npmjs.com/package/lz4js
 const lz4 = require('lz4js');
 // The server communicates with clients via commands defined in
@@ -70,12 +73,12 @@ function decompressBuffer(buffer) {
     commandBuffer = commandBuffer.subarray(commandBuffer.indexOf(' ') + 1);
     // extract compressed dataType
     const dataType = commandBuffer.subarray(0, 1).toString('utf8');
-    let decompressedBuffer = buffer_1.Buffer.alloc(decompressedSize);
+    let decompressedBuffer = Buffer.alloc(decompressedSize);
     const compressedBuffer = commandBuffer.subarray(commandBuffer.length - compressedSize);
     // lz4js library is javascript and doesn't have types so we silence the type check
     const decompressionResult = lz4.decompressBlock(compressedBuffer, decompressedBuffer, 0, compressedSize, 0);
     // the entire command is composed of the header (which is not compressed) + the decompressed block
-    decompressedBuffer = buffer_1.Buffer.concat([commandBuffer.subarray(0, commandBuffer.length - compressedSize), decompressedBuffer]);
+    decompressedBuffer = Buffer.concat([commandBuffer.subarray(0, commandBuffer.length - compressedSize), decompressedBuffer]);
     if (decompressionResult <= 0 || decompressionResult !== decompressedSize) {
         throw new Error(`lz4 decompression error at offset ${decompressionResult}`);
     }
@@ -199,7 +202,7 @@ function bufferEndsWith(buffer, suffix) {
  * @see https://github.com/sqlitecloud/sdk/blob/master/PROTOCOL.md#scsp-rowset-chunk
  */
 function parseRowsetChunks(buffers) {
-    let buffer = buffer_1.Buffer.concat(buffers);
+    let buffer = Buffer.concat(buffers);
     if (!bufferStartsWith(buffer, exports.CMD_ROWSET_CHUNK) || !bufferEndsWith(buffer, exports.ROWSET_CHUNKS_END)) {
         throw new Error('SQLiteCloudConnection.parseRowsetChunks - invalid chunks buffer');
     }
@@ -251,7 +254,7 @@ function popData(buffer) {
         return { data, fwdBuffer };
     }
     // first character is the data type
-    console.assert(buffer && buffer instanceof buffer_1.Buffer);
+    console.assert(buffer && buffer instanceof Buffer);
     let dataType = buffer.subarray(0, 1).toString('utf8');
     if (dataType == exports.CMD_COMPRESSED)
         throw new Error('Compressed data should be decompressed before parsing');
@@ -324,15 +327,15 @@ function formatCommand(command) {
 }
 function serializeCommand(data, zeroString = false) {
     const n = data.length;
-    let serializedData = buffer_1.Buffer.from(`${n} `);
+    let serializedData = Buffer.from(`${n} `);
     for (let i = 0; i < n; i++) {
         // the first string is the sql and it must be zero-terminated
         const zs = i == 0 || zeroString;
-        serializedData = buffer_1.Buffer.concat([serializedData, serializeData(data[i], zs)]);
+        serializedData = Buffer.concat([serializedData, serializeData(data[i], zs)]);
     }
     const bytesTotal = serializedData.byteLength;
-    const header = buffer_1.Buffer.from(`${exports.CMD_ARRAY}${bytesTotal} `);
-    return buffer_1.Buffer.concat([header, serializedData]);
+    const header = Buffer.from(`${exports.CMD_ARRAY}${bytesTotal} `);
+    return Buffer.concat([header, serializedData]);
 }
 function serializeData(data, zeroString = false) {
     if (typeof data === 'string') {
@@ -341,26 +344,26 @@ function serializeData(data, zeroString = false) {
             cmd = exports.CMD_ZEROSTRING;
             data += '\0';
         }
-        const header = `${cmd}${buffer_1.Buffer.byteLength(data, 'utf-8')} `;
-        return buffer_1.Buffer.from(header + data);
+        const header = `${cmd}${Buffer.byteLength(data, 'utf-8')} `;
+        return Buffer.from(header + data);
     }
     if (typeof data === 'number') {
         if (Number.isInteger(data)) {
-            return buffer_1.Buffer.from(`${exports.CMD_INT}${data} `);
+            return Buffer.from(`${exports.CMD_INT}${data} `);
         }
         else {
-            return buffer_1.Buffer.from(`${exports.CMD_FLOAT}${data} `);
+            return Buffer.from(`${exports.CMD_FLOAT}${data} `);
         }
     }
     if (typeof data === 'bigint') {
-        return buffer_1.Buffer.from(`${exports.CMD_INT}${data} `);
+        return Buffer.from(`${exports.CMD_INT}${data} `);
     }
-    if (buffer_1.Buffer.isBuffer(data)) {
+    if (Buffer.isBuffer(data)) {
         const header = `${exports.CMD_BLOB}${data.byteLength} `;
-        return buffer_1.Buffer.concat([buffer_1.Buffer.from(header), data]);
+        return Buffer.concat([Buffer.from(header), data]);
     }
     if (data === null || data === undefined) {
-        return buffer_1.Buffer.from(`${exports.CMD_NULL} `);
+        return Buffer.from(`${exports.CMD_NULL} `);
     }
     if (Array.isArray(data)) {
         return serializeCommand(data, zeroString);

package/lib/drivers/safe-imports.d.ts

@@ -0,0 +1,31 @@
+/**
+ * safe-imports.ts - Safe imports for optional React Native dependencies
+ *
+ * This module provides safe imports for dependencies that are optional peer dependencies.
+ * When these dependencies are not installed (e.g., using the package in a web/Next.js context),
+ * the imports will still work. However, in React Native contexts where these dependencies are
+ * required but not installed, clear error messages will be thrown.
+ */
+/**
+ * Detects if we're running in React Native environment
+ */
+export declare function isReactNative(): boolean;
+/**
+ * Safely imports the URL class from whatwg-url or react-native-url-polyfill
+ * In React Native: Uses react-native-url-polyfill (via react-native field mapping)
+ * In Web/Node: Uses whatwg-url
+ */
+export declare function getSafeURL(): typeof import('whatwg-url').URL;
+/**
+ * Safely imports the Buffer class from buffer or @craftzdog/react-native-buffer
+ * In React Native: Uses @craftzdog/react-native-buffer (via react-native field mapping)
+ * In Web/Node: Uses buffer package
+ */
+export declare function getSafeBuffer(): typeof import('buffer').Buffer;
+/**
+ * Safely imports the tls module or react-native-tcp-socket
+ * In React Native: Uses react-native-tcp-socket (via react-native field mapping)
+ * In Node: Uses native tls module
+ * In Browser: Will return null (browser field sets tls to false)
+ */
+export declare function getSafeTLS(): typeof import('tls') | null;

package/lib/drivers/safe-imports.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * safe-imports.ts - Safe imports for optional React Native dependencies
+ *
+ * This module provides safe imports for dependencies that are optional peer dependencies.
+ * When these dependencies are not installed (e.g., using the package in a web/Next.js context),
+ * the imports will still work. However, in React Native contexts where these dependencies are
+ * required but not installed, clear error messages will be thrown.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isReactNative = isReactNative;
+exports.getSafeURL = getSafeURL;
+exports.getSafeBuffer = getSafeBuffer;
+exports.getSafeTLS = getSafeTLS;
+const types_1 = require("./types");
+/**
+ * Detects if we're running in React Native environment
+ */
+function isReactNative() {
+    return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+}
+/**
+ * Safely imports the URL class from whatwg-url or react-native-url-polyfill
+ * In React Native: Uses react-native-url-polyfill (via react-native field mapping)
+ * In Web/Node: Uses whatwg-url
+ */
+function getSafeURL() {
+    try {
+        // In React Native, Metro bundler will resolve this to react-native-url-polyfill
+        // In Web/Node, this will resolve to whatwg-url
+        const { URL } = require('whatwg-url');
+        return URL;
+    }
+    catch (error) {
+        if (isReactNative()) {
+            throw new types_1.SQLiteCloudError('Missing required React Native dependency: react-native-url-polyfill. ' +
+                'Please install it using: npm install react-native-url-polyfill', { errorCode: 'ERR_MISSING_DEPENDENCY', cause: error });
+        }
+        throw new types_1.SQLiteCloudError('Failed to load URL parser. Please ensure whatwg-url is installed.', { errorCode: 'ERR_MISSING_DEPENDENCY', cause: error });
+    }
+}
+/**
+ * Safely imports the Buffer class from buffer or @craftzdog/react-native-buffer
+ * In React Native: Uses @craftzdog/react-native-buffer (via react-native field mapping)
+ * In Web/Node: Uses buffer package
+ */
+function getSafeBuffer() {
+    try {
+        // In React Native, Metro bundler will resolve this to @craftzdog/react-native-buffer
+        // In Web/Node, this will resolve to buffer package
+        const { Buffer } = require('buffer');
+        return Buffer;
+    }
+    catch (error) {
+        if (isReactNative()) {
+            throw new types_1.SQLiteCloudError('Missing required React Native dependency: @craftzdog/react-native-buffer. ' +
+                'Please install it using: npm install @craftzdog/react-native-buffer', { errorCode: 'ERR_MISSING_DEPENDENCY', cause: error });
+        }
+        throw new types_1.SQLiteCloudError('Failed to load Buffer library. Please ensure buffer package is installed.', { errorCode: 'ERR_MISSING_DEPENDENCY', cause: error });
+    }
+}
+/**
+ * Safely imports the tls module or react-native-tcp-socket
+ * In React Native: Uses react-native-tcp-socket (via react-native field mapping)
+ * In Node: Uses native tls module
+ * In Browser: Will return null (browser field sets tls to false)
+ */
+function getSafeTLS() {
+    try {
+        // In React Native, Metro bundler will resolve this to react-native-tcp-socket
+        // In Node, this will resolve to native tls module
+        // In Browser, the browser field in package.json sets tls to false
+        const tls = require('tls');
+        if (tls === false || !tls) {
+            return null;
+        }
+        return tls;
+    }
+    catch (error) {
+        if (isReactNative()) {
+            throw new types_1.SQLiteCloudError('Missing required React Native dependency: react-native-tcp-socket. ' +
+                'Please install it using: npm install react-native-tcp-socket', { errorCode: 'ERR_MISSING_DEPENDENCY', cause: error });
+        }
+        // In browser context, tls is not available (WebSocket should be used instead)
+        return null;
+    }
+}

package/lib/drivers/utilities.js

@@ -15,8 +15,11 @@ exports.parseconnectionstring = parseconnectionstring;
 exports.parseBoolean = parseBoolean;
 exports.parseBooleanToZeroOne = parseBooleanToZeroOne;
 const types_1 = require("./types");
+const safe_imports_1 = require("./safe-imports");
 // explicitly importing these libraries to allow cross-platform support by replacing them
-const whatwg_url_1 = require("whatwg-url");
+// In React Native: Metro resolves 'whatwg-url' to 'react-native-url-polyfill' via package.json react-native field
+// In Web/Node: Uses standard whatwg-url package
+const URL = (0, safe_imports_1.getSafeURL)();
 //
 // determining running environment, thanks to browser-or-node
 // https://www.npmjs.com/package/browser-or-node
@@ -193,7 +196,7 @@ function parseconnectionstring(connectionstring) {
         // the sqlitecloud: protocol is not recognized by the URL constructor in browsers
         // so we need to replace it with https: to make it work
         const knownProtocolUrl = connectionstring.replace('sqlitecloud:', 'https:');
-        const url = new whatwg_url_1.URL(knownProtocolUrl);
+        const url = new URL(knownProtocolUrl);
         // all lowecase options
         const options = {};
         url.searchParams.forEach((value, key) => {