scylladb-zpp-2024-javascript-driver · PiotrJunior · Apr 11, 2025 · Apr 22, 2025 · May 7, 2025 · Apr 28, 2025
diff --git a/docs/src/internal/parameter_wrapper.md b/docs/src/internal/parameter_wrapper.md
@@ -0,0 +1,25 @@
+# ParameterWrapper
+
+Parameter wrapper is used to pass parameters for all queries.
+It can pass any CQL Value, null and unset values.
+On the Rust side, the value is represented by:
+`Option<MaybeUnset<CqlValue>>`
+and on the JavaScript side it's represented by:
+`[ComplexType, Value]` with the null being: `[]` and unset: `[undefined]`.
+
+The conversion from the user provided values to accepted format is done in `types/cql-utils.js`.
+
+On the Rust side, `requests/parameter_wrappers.rs` is responsible for value conversion
+into format recognized by the Rust driver. It's done via the `FromNapiValue` trait.
+The specific format containing both type and value is necessary to create a correct CQL Value,
+without using [env](https://napi.rs/docs/compat-mode/concepts/env) in function.
+
+As driver allows values to be provided in multiple formats:
+
+- one of the predefined types,
+- as a string representation of the type,
+- as a pre-serialized byte array
+
+which are converted into predefined type, before passing it to the Rust.
+It's possible to do this conversion also on the Rust size
+(but it's necessary to check the performance impact of such change).
diff --git a/lib/new-utils.js b/lib/new-utils.js
@@ -1,6 +1,7 @@
 "use strict";
 const customErrors = require("./errors");
 const util = require("./utils");
+const Integer = require("./types/integer");

 const Long = require("long");

@@ -23,6 +24,22 @@ const errorTypeMap = {

 const concatenationMark = "#";

+// BigInt constants
+const isBigIntSupported = typeof BigInt !== "undefined";
+const bigInt8 = isBigIntSupported ? BigInt(8) : null;
+const bigInt0 = isBigIntSupported ? BigInt(0) : null;
+const bigIntMinus1 = isBigIntSupported ? BigInt(-1) : null;
+const bigInt8BitsOn = isBigIntSupported ? BigInt(0xff) : null;
+
+// Buffer constants
+const buffers = {
+    int16Zero: util.allocBufferFromArray([0, 0]),
+    int32Zero: util.allocBufferFromArray([0, 0, 0, 0]),
+    int8Zero: util.allocBufferFromArray([0]),
+    int8One: util.allocBufferFromArray([1]),
+    int8MaxValue: util.allocBufferFromArray([0xff]),
+};
+
 /**
 * A wrapper function to map napi errors to Node.js errors or custom errors.
 * Because NAPI-RS does not support throwing errors different that Error, for example
@@ -104,9 +121,117 @@ function arbitraryValueToBigInt(value) {
    );
 }

+/**
+ * Converts a value to a varint buffer.
+ * @param {Integer|Buffer|String|Number} value
+ * @returns {Buffer}
+ * @private
+ */
+function encodeVarint(value) {
+    if (typeof value === "number") {
+        value = Integer.fromNumber(value);
+    }
+    if (typeof value === "string") {
+        value = Integer.fromString(value);
+    }
+    let buf = null;
+    if (typeof value === "bigint") {
+        buf = encodeVarintFromBigInt(value);
+    }
+    if (value instanceof Buffer) {
+        buf = value;
+    }
+    if (value instanceof Integer) {
-    }
-    if (typeof value === "string") {
-        value = Integer.fromString(value);
-    }
-    let buf = null;
-    if (typeof value === "bigint") {
-        buf = encodeVarintFromBigInt(value);
-    }
-    if (value instanceof Buffer) {
-        buf = value;
-    }
-    if (value instanceof Integer) {
+    } else if (typeof value === "string") {
+        value = Integer.fromString(value);
+    }
+    let buf = null;
+    if (typeof value === "bigint") {
+        buf = encodeVarintFromBigInt(value);
+    } else if (value instanceof Buffer) {
+        buf = value;
+    } else if (value instanceof Integer) {
-    }
-    if (typeof value === "string") {
-        value = Integer.fromString(value);
-    }
-    let buf = null;
-    if (typeof value === "bigint") {
-        buf = encodeVarintFromBigInt(value);
-    }
-    if (value instanceof Buffer) {
-        buf = value;
-    }
-    if (value instanceof Integer) {
+    } else if (typeof value === "string") {
+        value = Integer.fromString(value);
+    }
+    let buf = null;
+    if (typeof value === "bigint") {
+        buf = encodeVarintFromBigInt(value);
+    } else if (value instanceof Buffer) {
+        buf = value;
+    } else if (value instanceof Integer) {
+        buf = Integer.toBuffer(value);
+    }
+    if (buf === null) {
+        throw new TypeError(
+            "Not a valid varint, expected Integer/Number/String/Buffer, obtained " +
+                util.inspect(value),
+        );
+    }
+    return buf;
+}
+
+/**
+ * Converts a BigInt to a varint buffer.
+ * @param {String|BigInt} value
+ * @returns {Buffer}
+ */
+function encodeVarintFromBigInt(value) {
+    if (typeof value === "string") {
+        // All numeric types are supported as strings for historical reasons
+        value = BigInt(value);
+    }
+
+    if (typeof value !== "bigint") {
+        throw new TypeError(
+            "Not a valid varint, expected BigInt, obtained " +
+                util.inspect(value),
+        );
+    }
+
+    if (value === bigInt0) {
+        return buffers.int8Zero;
+    } else if (value === bigIntMinus1) {
+        return buffers.int8MaxValue;
+    }
+
+    const parts = [];
+
+    if (value > bigInt0) {
+        while (value !== bigInt0) {
+            parts.unshift(Number(value & bigInt8BitsOn));
+            value = value >> bigInt8;
+        }
+
+        if (parts[0] > 0x7f) {
+            // Positive value needs a padding
+            parts.unshift(0);
+        }
+    } else {
+        while (value !== bigIntMinus1) {
+            parts.unshift(Number(value & bigInt8BitsOn));
+            value = value >> bigInt8;
+        }
+
+        if (parts[0] <= 0x7f) {
+            // Negative value needs a padding
+            parts.unshift(0xff);
+        }
+    }
+
+    return util.allocBufferFromArray(parts);
+}
+
+/**
+ * Converts a byte array to a BigInt
+ * @param {Buffer} bytes
+ * @returns {BigInt}
+ */
+function decodeVarintAsBigInt(bytes) {
+    let result = bigInt0;
+    if (bytes[0] <= 0x7f) {
+        for (let i = 0; i < bytes.length; i++) {
+            const b = BigInt(bytes[bytes.length - 1 - i]);
+            result = result | (b << BigInt(i * 8));
+        }
+    } else {
+        for (let i = 0; i < bytes.length; i++) {
+            const b = BigInt(bytes[bytes.length - 1 - i]);
+            result = result | ((~b & bigInt8BitsOn) << BigInt(i * 8));
+        }
+        result = ~result;
+    }
+
+    return result;
+}
+
 exports.throwNotSupported = throwNotSupported;
 exports.napiErrorHandler = napiErrorHandler;
 exports.throwNotSupported = throwNotSupported;
 exports.bigintToLong = bigintToLong;
 exports.longToBigint = longToBigint;
 exports.arbitraryValueToBigInt = arbitraryValueToBigInt;
+exports.encodeVarint = encodeVarint;
+exports.decodeVarintAsBigInt = decodeVarintAsBigInt;