mysql2 3.23.4 → 3.23.5-canary.8ec20f1

package/index.js

@@ -60,6 +60,11 @@ exports.__defineGetter__(
 
 exports.__defineGetter__('Types', () => require('./lib/constants/types.js'));
 
+exports.__defineGetter__(
+  'TypedParameter',
+  () => require('./lib/packets/typed_parameter.js').types
+);
+
 exports.__defineGetter__('Charsets', () =>
   require('./lib/constants/charsets.js')
 );

package/lib/commands/execute.js

@@ -54,7 +54,8 @@ class Execute extends Command {
       connection.config.timezone,
       this._executeOptions.attributes,
       clientFlags,
-      connection._isMariaDB
+      connection._isMariaDB,
+      this.statement.parameters
     );
     //For reasons why this try-catch is here, please see
     // https://github.com/sidorares/node-mysql2/pull/689

package/lib/constants/types.js

@@ -18,6 +18,7 @@ module.exports = {
   0x0e: 'NEWDATE', // aka ?
   0x0f: 'VARCHAR', // aka VARCHAR (?)
   0x10: 'BIT', // aka BIT, 1-8 byte
+  0xf2: 'VECTOR',
   0xf5: 'JSON',
   0xf6: 'NEWDECIMAL', // aka DECIMAL
   0xf7: 'ENUM', // aka ENUM

package/lib/packets/encode_parameter.js

@@ -2,6 +2,12 @@
 
 const Types = require('../constants/types');
 const Packet = require('../packets/packet');
+const {
+  TypedParameter,
+  encodeTypedParameter,
+  integerHint,
+} = require('./typed_parameter.js');
+const FieldFlags = require('../constants/field_flags.js');
 
 function isJSON(value) {
   return (
@@ -11,7 +17,20 @@ function isJSON(value) {
   );
 }
 
-function toParameter(value, encoding, timezone, jsonAsString) {
+function toParameter(value, encoding, timezone, jsonAsString, hint) {
+  if (value instanceof TypedParameter) {
+    return encodeTypedParameter(value, encoding, timezone, jsonAsString);
+  }
+  if (hint) {
+    const hinted = integerHint(
+      value,
+      hint.columnType,
+      Boolean(hint.flags & FieldFlags.UNSIGNED)
+    );
+    if (hinted) {
+      return encodeTypedParameter(hinted, encoding, timezone, jsonAsString);
+    }
+  }
   let type = Types.VAR_STRING;
   let length;
   let writer = function (value) {
@@ -71,7 +90,14 @@ function toParameter(value, encoding, timezone, jsonAsString) {
   if (!length) {
     length = Packet.lengthCodedStringLength(value, encoding);
   }
-  return { value, type, length, writer };
+  return {
+    value,
+    type,
+    length,
+    writer,
+    unsigned: false,
+    isNull: type === Types.NULL,
+  };
 }
 
 module.exports = { toParameter, isJSON };

package/lib/packets/execute.js

@@ -16,7 +16,8 @@ class Execute {
     timezone,
     attributes,
     clientFlags,
-    jsonAsString
+    jsonAsString,
+    parameterDefinitions
   ) {
     this.id = id;
     this.parameters = parameters;
@@ -25,6 +26,7 @@ class Execute {
     this.attributes = attributes;
     this.clientFlags = clientFlags || 0;
     this.jsonAsString = jsonAsString || false;
+    this.parameterDefinitions = parameterDefinitions || [];
   }
 
   static fromPacket(packet, encoding) {
@@ -124,8 +126,14 @@ class Execute {
     if (totalParams > 0) {
       const bindParams =
         numParams > 0
-          ? this.parameters.map((v) =>
-              toParameter(v, this.encoding, this.timezone, this.jsonAsString)
+          ? this.parameters.map((v, i) =>
+              toParameter(
+                v,
+                this.encoding,
+                this.timezone,
+                this.jsonAsString,
+                this.parameterDefinitions[i]
+              )
             )
           : [];
       const attrParams = attrNames.map((name) =>
@@ -137,7 +145,7 @@ class Execute {
       let bitmap = 0;
       let bitValue = 1;
       allParams.forEach((parameter) => {
-        if (parameter.type === Types.NULL) {
+        if (parameter.isNull) {
           bitmap += bitValue;
         }
         bitValue *= 2;
@@ -156,7 +164,7 @@ class Execute {
       // types (and names for attributes)
       for (let i = 0; i < allParams.length; i++) {
         packet.writeInt8(allParams[i].type);
-        packet.writeInt8(0); // unsigned flag
+        packet.writeInt8(allParams[i].unsigned ? 0x80 : 0);
         if (useQueryAttributes) {
           const name = i < numParams ? '' : attrNames[i - numParams];
           packet.writeLengthCodedString(name, this.encoding);
@@ -165,7 +173,7 @@ class Execute {
 
       // values
       allParams.forEach((parameter) => {
-        if (parameter.type !== Types.NULL) {
+        if (!parameter.isNull) {
           parameter.writer.call(packet, parameter.value);
         }
       });

package/lib/packets/packet.js

@@ -11,6 +11,7 @@ const Long = require('long');
 const StringParser = require('../parsers/string.js');
 const Types = require('../constants/types.js');
 const INVALID_DATE = new Date(NaN);
+const ZERO_DATE = '0000-00-00';
 
 // this is nearly duplicate of previous function so generated code is not slower
 // due to "if (dateStrings)" branching
@@ -317,7 +318,7 @@ class Packet {
       return new Date(y, m - 1, d, H, M, S, ms);
     }
     let str = this.readDateTimeString(6, 'T', null);
-    if (!str) {
+    if (str.startsWith(ZERO_DATE)) {
       return INVALID_DATE;
     }
     if (str.length === 10) {
@@ -335,7 +336,7 @@ class Packet {
     let M = 0;
     let S = 0;
     let ms = 0;
-    let str;
+    let str = ZERO_DATE;
     if (length > 3) {
       y = this.readInt16();
       m = this.readInt8();
@@ -863,6 +864,36 @@ class Packet {
     this.offset += 8;
   }
 
+  writeFloat(n) {
+    this.buffer.writeFloatLE(n, this.offset);
+    this.offset += 4;
+  }
+
+  writeUIntLE(n, bytes) {
+    if (bytes === 8) {
+      this.buffer.writeBigUInt64LE(n, this.offset);
+    } else {
+      this.buffer.writeUIntLE(Number(n), this.offset, bytes);
+    }
+    this.offset += bytes;
+  }
+
+  writeTime({ negative, days, hours, minutes, seconds, microseconds }) {
+    if (!days && !hours && !minutes && !seconds && !microseconds) {
+      this.writeInt8(0);
+      return;
+    }
+    this.writeInt8(microseconds ? 12 : 8);
+    this.writeInt8(negative ? 1 : 0);
+    this.writeInt32(days);
+    this.writeInt8(hours);
+    this.writeInt8(minutes);
+    this.writeInt8(seconds);
+    if (microseconds) {
+      this.writeInt32(microseconds);
+    }
+  }
+
   writeBuffer(b) {
     b.copy(this.buffer, this.offset);
     this.offset += b.length;

package/lib/packets/typed_parameter.js

@@ -0,0 +1,381 @@
+'use strict';
+
+const Types = require('../constants/types.js');
+const Packet = require('./packet.js');
+
+const INTEGER_BYTES = {
+  [Types.TINY]: 1,
+  [Types.SHORT]: 2,
+  [Types.YEAR]: 2,
+  [Types.INT24]: 4,
+  [Types.LONG]: 4,
+  [Types.LONGLONG]: 8,
+};
+
+const TEMPORAL = [Types.DATE, Types.DATETIME, Types.TIMESTAMP];
+
+// MySQL rejects INT24, YEAR, ENUM, SET, BIT and GEOMETRY as bind types, and
+// MariaDB rejects JSON and VECTOR. Each is transmitted as the narrowest type
+// both servers accept, which carries the same value.
+const WIRE_TYPE = {
+  [Types.INT24]: Types.LONG,
+  [Types.YEAR]: Types.SHORT,
+  [Types.ENUM]: Types.STRING,
+  [Types.SET]: Types.STRING,
+  [Types.VECTOR]: Types.BLOB,
+};
+
+// Only these may be adopted from a server hint: they are valid bind types on
+// every server, so upgrading can never make a working statement fail.
+const HINT_UPGRADABLE = new Set([
+  Types.TINY,
+  Types.SHORT,
+  Types.LONG,
+  Types.LONGLONG,
+]);
+
+const LENGTH_CODED = [
+  Types.DECIMAL,
+  Types.NEWDECIMAL,
+  Types.VARCHAR,
+  Types.VAR_STRING,
+  Types.STRING,
+  Types.ENUM,
+  Types.SET,
+  Types.JSON,
+  Types.VECTOR,
+  Types.TINY_BLOB,
+  Types.MEDIUM_BLOB,
+  Types.LONG_BLOB,
+  Types.BLOB,
+];
+
+function writeNothing() {}
+
+const TIME_PATTERN = /^(-)?(\d+):([0-5]?\d):([0-5]?\d)(?:\.(\d{1,6}))?$/;
+
+class TypedParameter {
+  constructor(type, value, unsigned) {
+    this.type = type;
+    this.value = value;
+    this.unsigned = unsigned;
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')]() {
+    const name = Types[this.type] || `0x${this.type.toString(16)}`;
+    return `${name}${this.unsigned ? ' UNSIGNED' : ''}(${String(this.value)})`;
+  }
+}
+
+function toInteger(value, name) {
+  switch (typeof value) {
+    case 'bigint':
+      return value;
+    case 'boolean':
+      return value ? 1n : 0n;
+    case 'number':
+      if (!Number.isInteger(value)) {
+        throw new TypeError(
+          `${name} parameter must be an integer, got ${value}`
+        );
+      }
+      if (!Number.isSafeInteger(value)) {
+        throw new RangeError(
+          `${name} parameter ${value} exceeds Number.MAX_SAFE_INTEGER and has already lost precision; pass a string or BigInt instead`
+        );
+      }
+      return BigInt(value);
+    case 'string':
+      try {
+        return BigInt(value.trim());
+      } catch (cause) {
+        throw new TypeError(
+          `${name} parameter must be an integer, got ${JSON.stringify(value)}`,
+          { cause }
+        );
+      }
+    default:
+      throw new TypeError(
+        `${name} parameter must be an integer, got ${typeof value}`
+      );
+  }
+}
+
+function checkedInteger(value, type, bytes, unsigned) {
+  const name = Types[type];
+  const bits = BigInt(bytes * 8);
+  const n = toInteger(value, name);
+  const min = unsigned ? 0n : -(1n << (bits - 1n));
+  const max = unsigned ? (1n << bits) - 1n : (1n << (bits - 1n)) - 1n;
+  if (n < min || n > max) {
+    throw new RangeError(
+      `${name}${unsigned ? ' UNSIGNED' : ''} parameter out of range: ${n} is not within ${min}..${max}`
+    );
+  }
+  return n;
+}
+
+// The server reports an integer type whenever it knows a placeholder holds one,
+// and MySQL rejects a DOUBLE in some of those positions. Adopting the hint is
+// only safe when the value is already an integer that fits, so every other case
+// returns null and keeps the type inferred from JavaScript.
+function integerHint(value, type, unsigned) {
+  const bytes = INTEGER_BYTES[type];
+  if (!bytes || !HINT_UPGRADABLE.has(type)) {
+    return null;
+  }
+  let n;
+  if (typeof value === 'bigint') {
+    n = value;
+  } else if (typeof value === 'boolean') {
+    n = value ? 1n : 0n;
+  } else if (typeof value === 'number' && Number.isSafeInteger(value)) {
+    n = BigInt(value);
+  } else {
+    return null;
+  }
+  const bits = BigInt(bytes * 8);
+  const min = unsigned ? 0n : -(1n << (bits - 1n));
+  const max = unsigned ? (1n << bits) - 1n : (1n << (bits - 1n)) - 1n;
+  if (n < min || n > max) {
+    return null;
+  }
+  return new TypedParameter(type, n, unsigned);
+}
+
+function wireType(type, jsonAsString) {
+  if (type === Types.JSON && jsonAsString) {
+    return Types.VAR_STRING;
+  }
+  return WIRE_TYPE[type] || type;
+}
+
+function integerEncoder(type, bytes) {
+  return (value, unsigned) => {
+    const wire = BigInt.asUintN(
+      bytes * 8,
+      checkedInteger(value, type, bytes, unsigned)
+    );
+    return {
+      value: bytes === 8 ? wire : Number(wire),
+      length: bytes,
+      writer(v) {
+        this.writeUIntLE(v, bytes);
+      },
+    };
+  };
+}
+
+function toDate(value, name) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError(
+      `${name} parameter must be a valid Date, got ${String(value)}`
+    );
+  }
+  return date;
+}
+
+function temporalEncoder(type, timezone) {
+  const name = Types[type];
+  return (value) => ({
+    value: toDate(value, name),
+    length: 12,
+    writer(v) {
+      this.writeDate(v, timezone);
+    },
+  });
+}
+
+function toTimeParts(value) {
+  if (typeof value === 'number') {
+    const negative = value < 0;
+    let rest = Math.abs(value);
+    const microseconds = Math.round((rest % 1000) * 1000);
+    rest = Math.floor(rest / 1000);
+    const seconds = rest % 60;
+    const minutes = Math.floor(rest / 60) % 60;
+    const totalHours = Math.floor(rest / 3600);
+    return {
+      negative,
+      days: Math.floor(totalHours / 24),
+      hours: totalHours % 24,
+      minutes,
+      seconds,
+      microseconds,
+    };
+  }
+  const match = TIME_PATTERN.exec(String(value));
+  if (!match) {
+    throw new TypeError(
+      `TIME parameter must be 'HH:MM:SS[.ffffff]' or milliseconds, got ${JSON.stringify(String(value))}`
+    );
+  }
+  const hours = Number(match[2]);
+  return {
+    negative: Boolean(match[1]),
+    days: Math.floor(hours / 24),
+    hours: hours % 24,
+    minutes: Number(match[3]),
+    seconds: Number(match[4]),
+    microseconds: match[5] ? Number(match[5].padEnd(6, '0')) : 0,
+  };
+}
+
+function timeEncoder() {
+  return (value) => ({
+    value: toTimeParts(value),
+    length: 13,
+    writer(v) {
+      this.writeTime(v);
+    },
+  });
+}
+
+function lengthCodedEncoder(encoding) {
+  return (value) => {
+    if (Buffer.isBuffer(value)) {
+      return {
+        value,
+        length: Packet.lengthCodedNumberLength(value.length) + value.length,
+        writer: Packet.prototype.writeLengthCodedBuffer,
+      };
+    }
+    const str = typeof value === 'string' ? value : String(value);
+    return {
+      value: str,
+      length: Packet.lengthCodedStringLength(str, encoding),
+      writer(v) {
+        Packet.prototype.writeLengthCodedString.call(this, v, encoding);
+      },
+    };
+  };
+}
+
+function jsonEncoder(encoding) {
+  const encodeText = lengthCodedEncoder(encoding);
+  return (value) =>
+    encodeText(
+      typeof value === 'string' || Buffer.isBuffer(value)
+        ? value
+        : JSON.stringify(value)
+    );
+}
+
+function encoderFor(type, encoding, timezone) {
+  if (INTEGER_BYTES[type]) {
+    return integerEncoder(type, INTEGER_BYTES[type]);
+  }
+  if (type === Types.DOUBLE) {
+    return (value) => ({
+      value: Number(value),
+      length: 8,
+      writer: Packet.prototype.writeDouble,
+    });
+  }
+  if (type === Types.FLOAT) {
+    return (value) => ({
+      value: Number(value),
+      length: 4,
+      writer: Packet.prototype.writeFloat,
+    });
+  }
+  if (TEMPORAL.includes(type)) {
+    return temporalEncoder(type, timezone);
+  }
+  if (type === Types.TIME) {
+    return timeEncoder();
+  }
+  if (type === Types.JSON) {
+    return jsonEncoder(encoding);
+  }
+  if (LENGTH_CODED.includes(type)) {
+    return lengthCodedEncoder(encoding);
+  }
+  throw new TypeError(
+    `No parameter encoder for MySQL type 0x${type.toString(16)}`
+  );
+}
+
+function encodeTypedParameter(parameter, encoding, timezone, jsonAsString) {
+  if (parameter.value === null || parameter.type === Types.NULL) {
+    return {
+      value: '',
+      type: wireType(parameter.type, jsonAsString),
+      length: 0,
+      writer: writeNothing,
+      unsigned: parameter.unsigned,
+      isNull: true,
+    };
+  }
+  const encoded = encoderFor(
+    parameter.type,
+    encoding,
+    timezone
+  )(parameter.value, parameter.unsigned);
+  return {
+    ...encoded,
+    type: wireType(parameter.type, jsonAsString),
+    unsigned: parameter.unsigned,
+  };
+}
+
+const ALIASES = {
+  MEDIUMTEXT: 'MEDIUM_BLOB',
+  LONGTEXT: 'LONG_BLOB',
+  TINYINT: 'TINY',
+  SMALLINT: 'SHORT',
+  MEDIUMINT: 'INT24',
+  INT: 'LONG',
+  INTEGER: 'LONG',
+  BIGINT: 'LONGLONG',
+  REAL: 'DOUBLE',
+  CHAR: 'STRING',
+  VARBINARY: 'VAR_STRING',
+  BINARY: 'STRING',
+  TEXT: 'BLOB',
+};
+
+const SUPPORTED = [
+  ...Object.keys(INTEGER_BYTES),
+  Types.FLOAT,
+  Types.DOUBLE,
+  Types.TIME,
+  ...TEMPORAL,
+  ...LENGTH_CODED,
+].map(Number);
+
+const types = Object.create(null);
+
+for (const type of SUPPORTED) {
+  const name = Types[type];
+  const bytes = INTEGER_BYTES[type];
+  const build = bytes
+    ? (value, unsigned) =>
+        new TypedParameter(
+          type,
+          value === null ? null : checkedInteger(value, type, bytes, unsigned),
+          unsigned
+        )
+    : (value, unsigned) => new TypedParameter(type, value, unsigned);
+  const factory = (value) => build(value, false);
+  if (bytes) {
+    factory.unsigned = (value) => build(value, true);
+  }
+  types[name] = factory;
+}
+
+types.NULL = () => new TypedParameter(Types.NULL, null, false);
+
+for (const [alias, target] of Object.entries(ALIASES)) {
+  if (types[target] && !types[alias]) {
+    types[alias] = types[target];
+  }
+}
+
+module.exports = {
+  TypedParameter,
+  encodeTypedParameter,
+  integerHint,
+  types,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mysql2",
-  "version": "3.23.4",
+  "version": "3.23.5-canary.8ec20f1",
   "description": "fast mysql driver. Implements core protocol, prepared statements, ssl and compression in native JS",
   "main": "index.js",
   "typings": "typings/mysql/index",

package/promise.js

@@ -192,6 +192,11 @@ exports.PromisePoolConnection = PromisePoolConnection;
 
 exports.__defineGetter__('Types', () => require('./lib/constants/types.js'));
 
+exports.__defineGetter__(
+  'TypedParameter',
+  () => require('./lib/packets/typed_parameter.js').types
+);
+
 exports.__defineGetter__('Charsets', () =>
   require('./lib/constants/charsets.js')
 );

package/typings/mysql/index.d.ts

@@ -46,6 +46,7 @@ export * from './lib/protocol/packets/index.js';
 export * from './lib/Auth.js';
 export * from './lib/constants/index.js';
 export * from './lib/parsers/index.js';
+export * from './lib/TypedParameter.js';
 export * from './lib/Connection.js';
 export * from './lib/PoolConnection.js';
 

package/typings/mysql/lib/TypedParameter.d.ts

@@ -0,0 +1,84 @@
+/**
+ * A bind parameter carrying an explicit MySQL type.
+ *
+ * Produced by the `TypedParameter` factories and accepted anywhere
+ * `execute()` takes a value. The declared type is sent verbatim in
+ * `COM_STMT_EXECUTE` instead of being inferred from the JavaScript type.
+ */
+export interface TypedParameterValue {
+  readonly type: number;
+  readonly value: unknown;
+  readonly unsigned: boolean;
+}
+
+export type TypedParameterInput =
+  string | number | bigint | boolean | Date | Buffer | Uint8Array | null;
+
+export interface TypedParameterFactory {
+  (value: TypedParameterInput): TypedParameterValue;
+}
+
+export interface IntegerTypedParameterFactory extends TypedParameterFactory {
+  unsigned(value: TypedParameterInput): TypedParameterValue;
+}
+
+export interface JsonTypedParameterFactory {
+  (value: TypedParameterInput | object): TypedParameterValue;
+}
+
+export interface TypedParameter {
+  TINY: IntegerTypedParameterFactory;
+  SHORT: IntegerTypedParameterFactory;
+  YEAR: IntegerTypedParameterFactory;
+  INT24: IntegerTypedParameterFactory;
+  LONG: IntegerTypedParameterFactory;
+  LONGLONG: IntegerTypedParameterFactory;
+
+  TINYINT: IntegerTypedParameterFactory;
+  SMALLINT: IntegerTypedParameterFactory;
+  MEDIUMINT: IntegerTypedParameterFactory;
+  INT: IntegerTypedParameterFactory;
+  INTEGER: IntegerTypedParameterFactory;
+  BIGINT: IntegerTypedParameterFactory;
+
+  FLOAT: TypedParameterFactory;
+  DOUBLE: TypedParameterFactory;
+  REAL: TypedParameterFactory;
+
+  DATE: TypedParameterFactory;
+  DATETIME: TypedParameterFactory;
+  TIMESTAMP: TypedParameterFactory;
+  TIME: TypedParameterFactory;
+
+  DECIMAL: TypedParameterFactory;
+  NEWDECIMAL: TypedParameterFactory;
+  VARCHAR: TypedParameterFactory;
+  VAR_STRING: TypedParameterFactory;
+  STRING: TypedParameterFactory;
+  CHAR: TypedParameterFactory;
+  VARBINARY: TypedParameterFactory;
+  BINARY: TypedParameterFactory;
+  ENUM: TypedParameterFactory;
+  SET: TypedParameterFactory;
+  BIT: TypedParameterFactory;
+  GEOMETRY: TypedParameterFactory;
+  VECTOR: TypedParameterFactory;
+  TINY_BLOB: TypedParameterFactory;
+  MEDIUM_BLOB: TypedParameterFactory;
+  LONG_BLOB: TypedParameterFactory;
+  BLOB: TypedParameterFactory;
+  TEXT: TypedParameterFactory;
+
+  JSON: JsonTypedParameterFactory;
+
+  NULL(): TypedParameterValue;
+}
+
+/**
+ * Constant `TypedParameter`.
+ *
+ * Please note that `TypedParameter` can only be accessed from the `mysql` object and not imported directly.
+ */
+declare const TypedParameter: TypedParameter;
+
+export { TypedParameter };

package/typings/mysql/lib/protocol/sequences/Query.d.ts

@@ -3,8 +3,10 @@ import { OkPacket, RowDataPacket, FieldPacket } from '../packets/index.js';
 import { Readable } from 'stream';
 import { Raw, Timezone } from 'sql-escaper';
 import { TypeCast } from '../../parsers/typeCast.js';
+import { TypedParameterValue } from '../../TypedParameter.js';
 
 export type ExecuteValues =
+  | TypedParameterValue
   | string
   | number
   | bigint