@sqlitecloud/drivers 0.0.34

package/lib/types.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * types.ts - shared types and interfaces
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLiteCloudArrayType = exports.SQLiteCloudError = void 0;
+/** Custom error reported by SQLiteCloud drivers */
+class SQLiteCloudError extends Error {
+    constructor(message, args) {
+        super(message);
+        this.name = 'SQLiteCloudError';
+        if (args) {
+            Object.assign(this, args);
+        }
+    }
+}
+exports.SQLiteCloudError = SQLiteCloudError;
+/**
+ * Certain responses include arrays with various types of metadata.
+ * The first entry is always an array type from this list. This enum
+ * is called SQCLOUD_ARRAY_TYPE in the C API.
+ */
+var SQLiteCloudArrayType;
+(function (SQLiteCloudArrayType) {
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_SQLITE_EXEC"] = 10] = "ARRAY_TYPE_SQLITE_EXEC";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_DB_STATUS"] = 11] = "ARRAY_TYPE_DB_STATUS";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_METADATA"] = 12] = "ARRAY_TYPE_METADATA";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_VM_STEP"] = 20] = "ARRAY_TYPE_VM_STEP";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_VM_COMPILE"] = 21] = "ARRAY_TYPE_VM_COMPILE";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_VM_STEP_ONE"] = 22] = "ARRAY_TYPE_VM_STEP_ONE";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_VM_SQL"] = 23] = "ARRAY_TYPE_VM_SQL";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_VM_STATUS"] = 24] = "ARRAY_TYPE_VM_STATUS";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_VM_LIST"] = 25] = "ARRAY_TYPE_VM_LIST";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_BACKUP_INIT"] = 40] = "ARRAY_TYPE_BACKUP_INIT";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_BACKUP_STEP"] = 41] = "ARRAY_TYPE_BACKUP_STEP";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_BACKUP_END"] = 42] = "ARRAY_TYPE_BACKUP_END";
+    SQLiteCloudArrayType[SQLiteCloudArrayType["ARRAY_TYPE_SQLITE_STATUS"] = 50] = "ARRAY_TYPE_SQLITE_STATUS"; // used in sqlite_status
+})(SQLiteCloudArrayType = exports.SQLiteCloudArrayType || (exports.SQLiteCloudArrayType = {}));

package/lib/utilities.d.ts

@@ -0,0 +1,23 @@
+import { SQLiteCloudConfig, SQLiteCloudDataTypes } from './types';
+export declare const isBrowser: boolean;
+export declare const isNode: boolean;
+/** Takes a generic value and escapes it so it can replace ? as a binding in a prepared SQL statement */
+export declare function escapeSqlParameter(param: SQLiteCloudDataTypes): string;
+/** Take a sql statement and replaces ? or $named parameters that are properly serialized and escaped. */
+export declare function prepareSql(sql: string, ...params: (SQLiteCloudDataTypes | SQLiteCloudDataTypes[])[]): string;
+/**
+ * Many of the methods in our API may contain a callback as their last argument.
+ * This method will take the arguments array passed to the method and return an object
+ * containing the arguments array with the callbacks removed (if any), and the callback itself.
+ * If there are multiple callbacks, the first one is returned as 'callback' and the last one
+ * as 'completeCallback'.
+ */
+export declare function popCallback<T extends ErrorCallback = ErrorCallback>(args: (SQLiteCloudDataTypes | T | ErrorCallback)[]): {
+    args: SQLiteCloudDataTypes[];
+    callback?: T | undefined;
+    complete?: ErrorCallback;
+};
+/** Parse connectionString like sqlitecloud://username:password@host:port/database?option1=xxx&option2=xxx into its components */
+export declare function parseConnectionString(connectionString: string): SQLiteCloudConfig;
+/** Returns true if value is 1 or true */
+export declare function parseBoolean(value: string | boolean | null | undefined): boolean;

package/lib/utilities.js

@@ -0,0 +1,136 @@
+"use strict";
+//
+// utilities.ts - utility methods to manipulate SQL statements
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBoolean = exports.parseConnectionString = exports.popCallback = exports.prepareSql = exports.escapeSqlParameter = exports.isNode = exports.isBrowser = void 0;
+const types_1 = require("./types");
+//
+// determining running environment, thanks to browser-or-node
+// https://www.npmjs.com/package/browser-or-node
+//
+exports.isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+exports.isNode = typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+//
+// utility methods
+//
+/** Takes a generic value and escapes it so it can replace ? as a binding in a prepared SQL statement */
+function escapeSqlParameter(param) {
+    if (param === null || param === undefined) {
+        return 'NULL';
+    }
+    if (typeof param === 'string') {
+        // replace single quote with two single quotes
+        param = param.replace(/'/g, "''");
+        return `'${param}'`;
+    }
+    if (typeof param === 'number') {
+        return param.toString();
+    }
+    if (typeof param === 'boolean') {
+        return param ? '1' : '0';
+    }
+    // serialize buffer as X'...' hex encoded string
+    if (Buffer.isBuffer(param)) {
+        return `X'${param.toString('hex')}'`;
+    }
+    if (typeof param === 'object') {
+        // serialize json then escape single quotes
+        let json = JSON.stringify(param);
+        json = json.replace(/'/g, "''");
+        return `'${json}'`;
+    }
+    throw new types_1.SQLiteCloudError(`Unsupported parameter type: ${typeof param}`);
+}
+exports.escapeSqlParameter = escapeSqlParameter;
+/** Take a sql statement and replaces ? or $named parameters that are properly serialized and escaped. */
+function prepareSql(sql, ...params) {
+    // parameters where passed as an array of parameters?
+    if ((params === null || params === void 0 ? void 0 : params.length) === 1 && Array.isArray(params[0])) {
+        params = params[0];
+    }
+    // replace ? or ?idx parameters passed as args or as an array
+    let parameterIndex = 1;
+    let preparedSql = sql.replace(/\?(\d+)?/g, (match, matchIndex) => {
+        const index = matchIndex ? parseInt(matchIndex) : parameterIndex;
+        parameterIndex++;
+        let sqlParameter;
+        if (params[0] && typeof params[0] === 'object' && !(params[0] instanceof Buffer)) {
+            sqlParameter = params[0][index];
+        }
+        if (!sqlParameter) {
+            if (index > params.length) {
+                throw new types_1.SQLiteCloudError('Not enough parameters');
+            }
+            sqlParameter = params[index - 1];
+        }
+        return sqlParameter !== null && sqlParameter !== undefined ? escapeSqlParameter(sqlParameter) : 'NULL';
+    });
+    // replace $named or :named parameters passed as an object
+    if ((params === null || params === void 0 ? void 0 : params.length) === 1 && params[0] && typeof params[0] === 'object') {
+        const namedParams = params[0];
+        for (const [paramKey, param] of Object.entries(namedParams)) {
+            const firstChar = paramKey.charAt(0);
+            if (firstChar == '$' || firstChar == ':' || firstChar == '@') {
+                const escapedParam = escapeSqlParameter(param);
+                preparedSql = preparedSql.replace(new RegExp(`\\${paramKey}`, 'g'), escapedParam);
+            }
+        }
+    }
+    return preparedSql;
+}
+exports.prepareSql = prepareSql;
+/**
+ * Many of the methods in our API may contain a callback as their last argument.
+ * This method will take the arguments array passed to the method and return an object
+ * containing the arguments array with the callbacks removed (if any), and the callback itself.
+ * If there are multiple callbacks, the first one is returned as 'callback' and the last one
+ * as 'completeCallback'.
+ */
+function popCallback(args) {
+    const remaining = args;
+    // at least 1 callback?
+    if (args && args.length > 0 && typeof args[args.length - 1] === 'function') {
+        // at least 2 callbacks?
+        if (args.length > 1 && typeof args[args.length - 2] === 'function') {
+            return { args: remaining.slice(0, -2), callback: args[args.length - 2], complete: args[args.length - 1] };
+        }
+        return { args: remaining.slice(0, -1), callback: args[args.length - 1] };
+    }
+    return { args: remaining };
+}
+exports.popCallback = popCallback;
+/** Parse connectionString like sqlitecloud://username:password@host:port/database?option1=xxx&option2=xxx into its components */
+function parseConnectionString(connectionString) {
+    try {
+        // The URL constructor throws a TypeError if the URL is not valid.
+        // in spite of having the same structure as a regular url
+        // protocol://username:password@host:port/database?option1=xxx&option2=xxx)
+        // 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 URL(knownProtocolUrl);
+        const options = {};
+        url.searchParams.forEach((value, key) => {
+            options[key] = value;
+        });
+        const config = Object.assign({ username: url.username, password: url.password, host: url.hostname, port: url.port ? parseInt(url.port) : undefined }, options);
+        const database = url.pathname.replace('/', ''); // pathname is database name, remove the leading slash
+        if (database) {
+            config.database = database;
+        }
+        return config;
+    }
+    catch (error) {
+        throw new types_1.SQLiteCloudError(`Invalid connection string: ${connectionString}`);
+    }
+}
+exports.parseConnectionString = parseConnectionString;
+/** Returns true if value is 1 or true */
+function parseBoolean(value) {
+    if (typeof value === 'string') {
+        return value.toLowerCase() === 'true' || value === '1';
+    }
+    return value ? true : false;
+}
+exports.parseBoolean = parseBoolean;

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@sqlitecloud/drivers",
+  "version": "0.0.34",
+  "description": "SQLiteCloud drivers for Typescript/Javascript in edge, web and node clients",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib/**/*"
+  ],
+  "scripts": {
+    "test": "jest --coverage",
+    "build": "rm -rf ./lib/ && tsc --project tsconfig.build.json && npx webpack",
+    "publish": "npm run build && npm publish --access public",
+    "prettier": "prettier --write 'src/**/*'",
+    "lint": "eslint ./src/ --fix && tsc --noEmit",
+    "typedoc": "rm -rf ./docs/ && typedoc --out docs && typedoc --plugin typedoc-plugin-markdown --out docs/markdown",
+    "npmgui": "npx npm-gui@latest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sqlitecloud/sqlitecloud-js.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "SQLiteCloud, Inc.",
+    "email": "support@sqlitecloud.io",
+    "url": "https://sqlitecloud.io/"
+  },
+  "engines": {
+    "node": ">=18.0"
+  },
+  "keywords": [
+    "sql",
+    "sqlite",
+    "sqlite3",
+    "sqlitecloud",
+    "database",
+    "cloud"
+  ],
+  "bugs": {
+    "url": "https://github.com/sqlitecloud/sqlitecloud-js/issues"
+  },
+  "homepage": "https://github.com/sqlitecloud/sqlitecloud-js#readme",
+  "dependencies": {
+    "eventemitter3": "^5.0.1",
+    "lz4js": "^0.2.0",
+    "socket.io-client": "^4.7.4"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.11",
+    "@types/lz4": "^0.6.4",
+    "@types/node": "^12.20.55",
+    "@typescript-eslint/eslint-plugin": "^4.22.0",
+    "@typescript-eslint/parser": "^4.22.0",
+    "dotenv": "^16.4.1",
+    "eslint": "^7.32.0",
+    "eslint-config-prettier": "^8.10.0",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-prettier": "^3.4.1",
+    "jest": "^29.7.0",
+    "prettier": "^2.2.1",
+    "sqlite3": "^5.1.6",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.25.3",
+    "typedoc-plugin-markdown": "^3.17.1",
+    "typescript": "^4.9.5",
+    "webpack": "^5.90.0",
+    "webpack-cli": "^5.1.4"
+  },
+  "config": {},
+  "release": {
+    "branches": [
+      "main"
+    ]
+  },
+  "prettier": {
+    "semi": false,
+    "singleQuote": true,
+    "trailingComma": "none",
+    "arrowParens": "avoid",
+    "printWidth": 160
+  }
+}