@depup/mysql2 3.23.4-depup.0 → 3.24.0-depup.0

package/lib/packets/typed_parameter.js

@@ -0,0 +1,381 @@
+'use strict';
+
+const Types = require('../constants/types.js');
+const Packet = require('./packet.js');
+const StringParser = require('../parsers/string.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) => {
+    const parts = toTimeParts(value);
+    return {
+      value: parts,
+      length: Packet.timeLength(parts),
+      writer(v) {
+        this.writeTime(v);
+      },
+    };
+  };
+}
+
+function lengthCodedEncoder(encoding) {
+  return (value) => {
+    const buffer = Buffer.isBuffer(value)
+      ? value
+      : StringParser.encode(
+          typeof value === 'string' ? value : String(value),
+          encoding
+        );
+    return {
+      value: buffer,
+      length: Packet.lengthCodedNumberLength(buffer.length) + buffer.length,
+      writer: Packet.prototype.writeLengthCodedBuffer,
+    };
+  };
+}
+
+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/lib/parsers/binary_parser.js

@@ -233,11 +233,11 @@ function compile(fields, options, config) {
     if (options.typeCast === false) {
       parserFn(`${lvalue} = packet.readLengthCodedBuffer();`);
     } else {
-      const fieldWrapperVar = `fieldWrapper${i}`;
-      parserFn(`const ${fieldWrapperVar} = wrap(fields[${i}], packet);`);
       const readCode = readCodeFor(fields[i], config, options, i);
 
       if (typeof options.typeCast === 'function') {
+        const fieldWrapperVar = `fieldWrapper${i}`;
+        parserFn(`const ${fieldWrapperVar} = wrap(fields[${i}], packet);`);
         parserFn(
           `${lvalue} = options.typeCast(${fieldWrapperVar}, function() { return ${readCode} });`
         );

package/lib/parsers/parser_cache.js

@@ -6,8 +6,19 @@ const parserCache = createLRU({
   max: 15000,
 });
 
+// the fixed-size options head keeps JSON.stringify (cheap for a flat array,
+// and it normalizes exotic values the same way as before); the per-field part
+// is built by hand with length-prefixed strings, so no delimiter collision is
+// possible and no throwaway nested arrays are allocated per query
+function appendString(key, value) {
+  if (value === undefined || value === null) {
+    return `${key}u/`;
+  }
+  return `${key}${value.length}#${value}/`;
+}
+
 function keyFromFields(type, fields, options, config) {
-  const res = [
+  let key = JSON.stringify([
     type,
     typeof options.nestTables,
     options.nestTables,
@@ -21,25 +32,20 @@ function keyFromFields(type, fields, options, config) {
     Boolean(options.decimalNumbers),
     options.dateStrings,
     Boolean(config.jsonStrings),
-  ];
+  ]);
 
   for (let i = 0; i < fields.length; ++i) {
     const field = fields[i];
-
-    res.push([
-      field.name,
-      field.columnType,
-      field.length,
-      field.schema,
-      field.table,
-      field.flags,
-      field.characterSet,
-      field.extendedTypeName,
-      field.extendedFormat,
-    ]);
+    key = appendString(key, field.name);
+    key += `${field.columnType}/${field.length}/`;
+    key = appendString(key, field.schema);
+    key = appendString(key, field.table);
+    key += `${field.flags}/${field.characterSet}/`;
+    key = appendString(key, field.extendedTypeName);
+    key = appendString(key, field.extendedFormat);
   }
 
-  return JSON.stringify(res, null, 0);
+  return key;
 }
 
 function getParser(type, fields, options, config, compiler) {

package/lib/parsers/string.js

@@ -7,7 +7,48 @@ const decoderCache = createLRU({
   max: 500,
 });
 
+// Direct slice methods skip the per-call encoding normalization and dispatch
+// inside buffer.toString(); they have been stable Node internals for years
+// but fall back gracefully where missing (other runtimes)
+const hasFastSlices =
+  typeof Buffer.prototype.utf8Slice === 'function' &&
+  typeof Buffer.prototype.latin1Slice === 'function' &&
+  typeof Buffer.prototype.asciiSlice === 'function';
+
 exports.decode = function (buffer, encoding, start, end, options) {
+  if (hasFastSlices) {
+    // replicate buffer.toString() bounds coercion exactly (the *Slice
+    // methods throw on anything out of range): negative, NaN, fractional
+    // and oversized offsets all clamp instead of throwing
+    const len = buffer.length;
+    if (start <= 0) {
+      start = 0;
+    } else if (start >= len) {
+      return '';
+    } else {
+      start |= 0;
+    }
+    if (end === undefined || end > len) {
+      end = len;
+    } else {
+      end |= 0;
+    }
+    if (end <= start) {
+      return '';
+    }
+    switch (encoding) {
+      case 'utf8':
+      case 'utf-8':
+        return buffer.utf8Slice(start, end);
+      case 'latin1':
+      case 'binary':
+        return buffer.latin1Slice(start, end);
+      case 'ascii':
+        return buffer.asciiSlice(start, end);
+      default:
+        break;
+    }
+  }
   if (Buffer.isEncoding(encoding)) {
     return buffer.toString(encoding, start, end);
   }

package/lib/promise/connection.js

@@ -30,7 +30,9 @@ class PromiseConnection extends EventEmitter {
 
   query(query, params) {
     const c = this.connection;
-    const stackHolder = captureStackHolder(PromiseConnection.prototype.query);
+    const stackHolder = c.config.trace
+      ? captureStackHolder(PromiseConnection.prototype.query)
+      : undefined;
     if (typeof params === 'function') {
       throw new Error(
         'Callback function is not available with promise clients.'
@@ -48,7 +50,9 @@ class PromiseConnection extends EventEmitter {
 
   execute(query, params) {
     const c = this.connection;
-    const stackHolder = captureStackHolder(PromiseConnection.prototype.execute);
+    const stackHolder = c.config.trace
+      ? captureStackHolder(PromiseConnection.prototype.execute)
+      : undefined;
     if (typeof params === 'function') {
       throw new Error(
         'Callback function is not available with promise clients.'

package/lib/promise/pool.js

@@ -37,7 +37,9 @@ class PromisePool extends EventEmitter {
 
   query(sql, args) {
     const corePool = this.pool;
-    const stackHolder = captureStackHolder(PromisePool.prototype.query);
+    const stackHolder = corePool.config.connectionConfig.trace
+      ? captureStackHolder(PromisePool.prototype.query)
+      : undefined;
     if (typeof args === 'function') {
       throw new Error(
         'Callback function is not available with promise clients.'
@@ -55,7 +57,9 @@ class PromisePool extends EventEmitter {
 
   execute(sql, args) {
     const corePool = this.pool;
-    const stackHolder = captureStackHolder(PromisePool.prototype.execute);
+    const stackHolder = corePool.config.connectionConfig.trace
+      ? captureStackHolder(PromisePool.prototype.execute)
+      : undefined;
     if (typeof args === 'function') {
       throw new Error(
         'Callback function is not available with promise clients.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@depup/mysql2",
-  "version": "3.23.4-depup.0",
+  "version": "3.24.0-depup.0",
   "description": "fast mysql driver. Implements core protocol, prepared statements, ssl and compression in native JS (with updated dependencies)",
   "main": "index.js",
   "typings": "typings/mysql/index",
@@ -95,8 +95,8 @@
     "changes": {},
     "depsUpdated": 0,
     "originalPackage": "mysql2",
-    "originalVersion": "3.23.4",
-    "processedAt": "2026-08-20T08:13:45.307Z",
+    "originalVersion": "3.24.0",
+    "processedAt": "2026-08-24T00:15:48.665Z",
     "smokeTest": "passed"
   }
 }

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