fix: safely widen numeric list bindings

Author: elpete

ModuleConfig.cfc

@@ -18,6 +18,7 @@ component {
             "convertEmptyStringsToNull": true,
             "shouldWrapValues": true,
             "validateQueryParamStructKeys": true,
+            "throwOnUnsafeNumericInference": false,
             "integerSQLType": "INTEGER",
             "bigIntegerSQLType": "BIGINT",
             "decimalSQLType": "DECIMAL",
@@ -55,6 +56,7 @@ component {
             .to( "qb.models.Query.QueryUtils" )
             .initArg( name = "convertEmptyStringsToNull", value = settings.convertEmptyStringsToNull )
             .initArg( name = "validateQueryParamStructKeys", value = settings.validateQueryParamStructKeys )
+            .initArg( name = "throwOnUnsafeNumericInference", value = settings.throwOnUnsafeNumericInference )
             .initArg( name = "integerSQLType", value = settings.integerSQLType )
             .initArg( name = "bigIntegerSQLType", value = settings.bigIntegerSQLType )
             .initArg( name = "decimalSQLType", value = settings.decimalSQLType );

README.md

@@ -20,6 +20,23 @@ Using qb, you can:
 
 Installation is easy through [CommandBox](https://www.ortussolutions.com/products/commandbox) and [ForgeBox](https://www.coldbox.org/forgebox).  Simply type `box install qb` to get started.
 
+## Numeric list inference
+
+qb combines numeric array members using a common SQL type that covers their declared ranges. For example, `[ 1, 3000000000 ]` uses `BIGINT`, and integers mixed with fractional values use `DECIMAL`. Explicit member types such as `TINYINT`, `SMALLINT`, `REAL`, `FLOAT`, and `DOUBLE` also participate in inference.
+
+When there is no portable numeric promotion without potential precision loss, qb falls back to `VARCHAR`. Examples include `BIGINT` mixed with `DOUBLE`, and `DECIMAL` mixed with `FLOAT`. This preserves the binding representation; the database can still apply its own conversion when executing the query.
+
+We recommend enabling `throwOnUnsafeNumericInference` in development to catch these combinations early:
+
+```cfc
+// config/ColdBox.cfc, in your development environment configuration
+moduleSettings.qb.throwOnUnsafeNumericInference = true;
+```
+
+The setting defaults to `false`. When enabled, unsafe numeric array inference throws `QBUnsafeNumericInference` with the conflicting SQL types. Safe promotions and ordinary mixed text arrays retain their normal behavior. For standalone usage, pass `throwOnUnsafeNumericInference = true` to the `QueryUtils` constructor.
+
+An explicit `cfsqltype` or `sqltype` on the outer binding always takes precedence; this setting does not validate caller-selected conversions or database column precision and scale.
+
 ## Code Samples
 
 Compare these two examples:

models/Query/QueryUtils.cfc

@@ -33,6 +33,12 @@ component singleton displayname="QueryUtils" accessors="true" {
      */
     property name="decimalSQLType" default="DECIMAL";
 
+    /**
+     * Throw when numeric array types cannot be combined without potential precision loss.
+     * Recommended in development; otherwise inference falls back to VARCHAR.
+     */
+    property name="throwOnUnsafeNumericInference" default="false";
+
     variables.numericValueTypes = {
         "AtomicInteger": true,
         "AtomicLong": true,
@@ -85,12 +91,14 @@ component singleton displayname="QueryUtils" accessors="true" {
         string integerSqlType = "INTEGER",
         string decimalSqlType = "DECIMAL",
         any log,
-        string bigIntegerSqlType = "BIGINT"
+        string bigIntegerSqlType = "BIGINT",
+        boolean throwOnUnsafeNumericInference = false
     ) {
         variables.convertEmptyStringsToNull = arguments.convertEmptyStringsToNull;
         variables.validateQueryParamStructKeys = arguments.validateQueryParamStructKeys;
         variables.integerSqlType = arguments.integerSqlType;
         variables.bigIntegerSqlType = arguments.bigIntegerSqlType;
+        variables.throwOnUnsafeNumericInference = arguments.throwOnUnsafeNumericInference;
         variables.decimalSqlType = arguments.decimalSqlType;
         if ( !isNull( arguments.log ) ) {
             variables.log = arguments.log;
@@ -561,8 +569,7 @@ component singleton displayname="QueryUtils" accessors="true" {
         }
 
         if ( isArray( value ) ) {
-            var inferredType = "";
-            var hasInferredType = false;
+            var inferredTypes = {};
             for ( var valueIndex = 1; valueIndex <= arguments.value.len(); valueIndex++ ) {
                 if ( !arrayIsDefined( arguments.value, valueIndex ) || isNull( arguments.value[ valueIndex ] ) ) {
                     continue;
@@ -572,14 +579,15 @@ component singleton displayname="QueryUtils" accessors="true" {
                     continue;
                 }
                 var itemType = inferSqlType( item, arguments.grammar );
-                if ( !hasInferredType ) {
-                    inferredType = itemType;
-                    hasInferredType = true;
-                } else if ( itemType != inferredType ) {
-                    return "VARCHAR";
-                }
+                inferredTypes[ itemType ] = true;
+            }
+            if ( inferredTypes.isEmpty() ) {
+                return "VARCHAR";
             }
-            return hasInferredType ? inferredType : "VARCHAR";
+            if ( inferredTypes.count() == 1 ) {
+                return inferredTypes.keyArray()[ 1 ];
+            }
+            return combineNumericSqlTypes( inferredTypes );
         }
 
         if ( isStruct( value ) ) {
@@ -938,6 +946,60 @@ component singleton displayname="QueryUtils" accessors="true" {
         return isSimpleValue( arguments.value ) && variables.numericValueTypes.keyExists( type );
     }
 
+    /**
+     * Combine declared numeric ranges, rather than narrowing them to the current values.
+     * Exact decimals and approximate types have no portable, lossless common type.
+     */
+    private string function combineNumericSqlTypes( required struct types ) {
+        var integerTypes = "BIT,TINYINT,SMALLINT,INTEGER,BIGINT";
+        var numericTypes = integerTypes & ",MONEY4,MONEY,DECIMAL,NUMERIC,REAL,FLOAT,DOUBLE";
+        var integerRank = 0;
+        for ( var sqlType in arguments.types ) {
+            if ( !listFindNoCase( numericTypes, sqlType ) ) {
+                return "VARCHAR";
+            }
+            integerRank = max( integerRank, listFindNoCase( integerTypes, sqlType ) );
+        }
+
+        var hasDecimal = arguments.types.keyExists( "DECIMAL" ) || arguments.types.keyExists( "NUMERIC" );
+        var hasMoney = arguments.types.keyExists( "MONEY" ) || arguments.types.keyExists( "MONEY4" );
+        var hasApproximate = arguments.types.keyExists( "REAL" ) || arguments.types.keyExists( "FLOAT" ) || arguments.types.keyExists( "DOUBLE" );
+        if ( hasApproximate ) {
+            if ( hasDecimal || hasMoney || integerRank == 5 ) {
+                if ( variables.throwOnUnsafeNumericInference ) {
+                    throw(
+                        type = "QBUnsafeNumericInference",
+                        message = "Cannot infer a common numeric SQL type without potential precision loss.",
+                        detail = "Numeric types: [#arguments.types
+                            .keyArray()
+                            .sort( "textnocase" )
+                            .toList( ", " )#]. Specify a SQL type on the outer binding, or disable throwOnUnsafeNumericInference to fall back to VARCHAR."
+                    );
+                }
+                return "VARCHAR";
+            }
+            if ( arguments.types.keyExists( "DOUBLE" ) ) {
+                return "DOUBLE";
+            }
+            if ( arguments.types.keyExists( "FLOAT" ) ) {
+                return "FLOAT";
+            }
+            // REAL has 24 significant binary digits; use DOUBLE for the full INTEGER range.
+            return integerRank == 4 ? "DOUBLE" : "REAL";
+        }
+
+        if ( hasDecimal ) {
+            return arguments.types.keyExists( "DECIMAL" ) ? "DECIMAL" : "NUMERIC";
+        }
+        if ( hasMoney ) {
+            if ( integerRank == 5 ) {
+                return "DECIMAL";
+            }
+            return arguments.types.keyExists( "MONEY" ) || integerRank == 4 ? "MONEY" : "MONEY4";
+        }
+        return listGetAt( integerTypes, integerRank );
+    }
+
     private string function deriveNumericSqlType( required numeric value ) {
         var isInteger = reFind( "^-?\d+$", arguments.value ) > 0;
         if ( !isInteger ) {
@@ -1139,6 +1201,30 @@ component singleton displayname="QueryUtils" accessors="true" {
             return 0;
         }
 
+        if ( isArray( arguments.binding.value ) ) {
+            var scale = 0;
+            for ( var valueIndex = 1; valueIndex <= arguments.binding.value.len(); valueIndex++ ) {
+                if (
+                    !arrayIsDefined( arguments.binding.value, valueIndex ) || isNull(
+                        arguments.binding.value[ valueIndex ]
+                    )
+                ) {
+                    continue;
+                }
+                var item = arguments.binding.value[ valueIndex ];
+                var itemBinding = isStruct( item ) ? {
+                    value: isNull( item.value ) ? javacast( "null", "" ) : item.value,
+                    null: structKeyExists( item, "null" ) && item.null
+                } : { value: item, null: false };
+                if ( isStruct( item ) && structKeyExists( item, "scale" ) && !itemBinding.null ) {
+                    scale = max( scale, item.scale );
+                } else {
+                    scale = max( scale, calculateNumberOfDecimalDigits( itemBinding ) );
+                }
+            }
+            return scale;
+        }
+
         if ( isInstanceOf( arguments.binding.value, "java.math.BigDecimal" ) ) {
             return max( 0, arguments.binding.value.scale() );
         }

tests/specs/ModuleConfigSpec.cfc

@@ -16,6 +16,7 @@ component extends="testbox.system.BaseSpec" {
                 moduleConfig.configure();
 
                 var settings = moduleConfig.$getProperty( "settings", "variables" );
+                expect( settings.throwOnUnsafeNumericInference ).toBeFalse();
                 expect( settings.integerSQLType ).toBe( "INTEGER" );
                 expect( settings.bigIntegerSQLType ).toBe( "BIGINT" );
                 expect( settings.decimalSQLType ).toBe( "DECIMAL" );