v14

.github/workflows/cron.yml

@@ -15,8 +15,6 @@ jobs:
         experimental: [ false ]
         fullNull: ["true", "false"]
         include:
-          - cfengine: "lucee@be"
-            experimental: true
           - cfengine: "adobe@be"
             experimental: true
           - cfengine: "boxlang@be"
@@ -42,6 +40,8 @@ jobs:
           box install
 
       - name: Start server
+        env:
+          FULL_NULL: ${{matrix.fullNull}}
         run: |
           box server start serverConfigFile="server-${{ matrix.cfengine }}.json" --noSaveSettings --debug
           curl http://127.0.0.1:60298
@@ -50,4 +50,4 @@ jobs:
         env:
           FULL_NULL: ${{matrix.fullNull}}
         continue-on-error: ${{ matrix.experimental }}
-        run: box testbox run
+        run: box testbox run

.github/workflows/pr.yml

@@ -23,12 +23,12 @@ jobs:
         experimental: [ false ]
         fullNull: ["true", "false"]
         include:
-          - cfengine: "lucee@be"
-            experimental: true
           - cfengine: "adobe@be"
             experimental: true
+            fullNull: "true"
           - cfengine: "boxlang@be"
             experimental: true
+            fullNull: "true"
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v7
@@ -50,6 +50,8 @@ jobs:
           box install
 
       - name: Start server
+        env:
+          FULL_NULL: ${{matrix.fullNull}}
         run: |
           box server start serverConfigFile="server-${{ matrix.cfengine }}.json" --noSaveSettings --debug
           curl http://127.0.0.1:60298
@@ -80,9 +82,4 @@ jobs:
         run: box install commandbox-cfformat
 
       - name: Run CFFormat
-        run: box run-script format
-
-      - name: Commit Format Changes
-        uses: stefanzweifel/git-auto-commit-action@v7.2.0
-        with:
-          commit_message: Apply cfformat changes
+        run: box run-script format:check

.github/workflows/release.yml

@@ -38,6 +38,8 @@ jobs:
           box install
 
       - name: Start server
+        env:
+          FULL_NULL: ${{matrix.fullNull}}
         run: |
           box server start serverConfigFile="server-${{ matrix.cfengine }}.json" --noSaveSettings --debug
           curl http://127.0.0.1:60298

ModuleConfig.cfc

@@ -12,11 +12,15 @@ component {
             "defaultReturnFormat": "array",
             "preventDuplicateJoins": false,
             "validateOperatorsAndCombinators": true,
+            "validateDuplicateSelectColumns": false,
+            "validateQueryExecuteReturnType": false,
             "collectQueryLog": true,
             "convertEmptyStringsToNull": true,
+            "shouldWrapValues": true,
             "validateQueryParamStructKeys": true,
-            "numericSQLType": "NUMERIC",
+            "throwOnUnsafeNumericInference": false,
             "integerSQLType": "INTEGER",
+            "bigIntegerSQLType": "BIGINT",
             "decimalSQLType": "DECIMAL",
             "defaultOptions": {},
             "sqlCommenter": {
@@ -29,7 +33,8 @@ component {
             },
             "shouldMaxRowsOverrideToAll": function( maxRows ) {
                 return maxRows <= 0;
-            }
+            },
+            "returnFormatters": {}
         };
 
         interceptorSettings = { "customInterceptionPoints": "preQBExecute,postQBExecute" };
@@ -51,17 +56,27 @@ component {
             .to( "qb.models.Query.QueryUtils" )
             .initArg( name = "convertEmptyStringsToNull", value = settings.convertEmptyStringsToNull )
             .initArg( name = "validateQueryParamStructKeys", value = settings.validateQueryParamStructKeys )
-            .initArg( name = "numericSQLType", value = settings.numericSQLType )
+            .initArg( name = "throwOnUnsafeNumericInference", value = settings.throwOnUnsafeNumericInference )
             .initArg( name = "integerSQLType", value = settings.integerSQLType )
+            .initArg( name = "bigIntegerSQLType", value = settings.bigIntegerSQLType )
             .initArg( name = "decimalSQLType", value = settings.decimalSQLType );
 
+        binder
+            .map( alias = "ReturnFormatterRegistry@qb", force = true )
+            .to( "qb.models.Query.ReturnFormatterRegistry" )
+            .initArg( name = "utils", ref = "QueryUtils@qb" )
+            .initArg( name = "returnFormatters", value = settings.returnFormatters );
+
         binder
             .map( alias = "QueryBuilder@qb", force = true )
             .to( "qb.models.Query.QueryBuilder" )
             .initArg( name = "grammar", ref = settings.defaultGrammar )
             .initArg( name = "utils", ref = "QueryUtils@qb" )
+            .initArg( name = "returnFormatterRegistry", ref = "ReturnFormatterRegistry@qb" )
             .initArg( name = "preventDuplicateJoins", value = settings.preventDuplicateJoins )
             .initArg( name = "validateOperatorsAndCombinators", value = settings.validateOperatorsAndCombinators )
+            .initArg( name = "validateDuplicateSelectColumns", value = settings.validateDuplicateSelectColumns )
+            .initArg( name = "validateQueryExecuteReturnType", value = settings.validateQueryExecuteReturnType )
             .initArg( name = "collectQueryLog", value = settings.collectQueryLog )
             .initArg( name = "returnFormat", value = settings.defaultReturnFormat )
             .initArg( name = "defaultOptions", value = settings.defaultOptions )
@@ -71,7 +86,15 @@ component {
         binder
             .map( alias = "SchemaBuilder@qb", force = true )
             .to( "qb.models.Schema.SchemaBuilder" )
-            .initArg( name = "grammar", ref = settings.defaultGrammar );
+            .initArg( name = "grammar", ref = settings.defaultGrammar )
+            .initArg( name = "defaultOptions", value = settings.defaultOptions );
+
+        // Apply shouldWrapValues setting to the configured grammar singleton.
+        // When defaultGrammar is AutoDiscover@qb, the setting is forwarded via
+        // onMissingMethod to whatever concrete grammar AutoDiscover resolves at runtime.
+        if ( structKeyExists( settings, "shouldWrapValues" ) ) {
+            wirebox.getInstance( settings.defaultGrammar ).setShouldWrapValues( settings.shouldWrapValues );
+        }
     }
 
 }

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:
@@ -71,6 +88,88 @@ q = queryExecute(
 
 qb enables you to explore new ways of organizing your code by letting you pass around a query builder object that will compile down to the right SQL without you having to keep track of the order, whitespace, or other SQL gotchas!
 
+## Bulk WHERE IN
+
+For large value collections, `whereInBulk` serializes the values into one bound parameter and lets the active grammar expand them into rows. This avoids database parameter limits without changing the behavior or performance of regular `whereIn` calls.
+
+```cfc
+query
+    .from( "users" )
+    .whereInBulk( "id", userIds )
+    .get();
+```
+
+qb infers a common type from the values and translates it to the active database grammar. Matching `cfsqltype` values in query parameter structs are preserved. Mixed values fall back to the grammar's string type.
+
+You can pass an explicit `sqlType` as the third argument when the column needs a more specific database type, such as `BIGINT`, `UUID`, or a particular decimal precision:
+
+```cfc
+query
+    .from( "users" )
+    .whereInBulk( "id", userIds, "BIGINT" )
+    .get();
+```
+
+The explicit `sqlType` should match the constrained column so the database can avoid implicit conversions. `whereNotInBulk`, `andWhereInBulk`, `orWhereInBulk`, `andWhereNotInBulk`, and `orWhereNotInBulk` are also available.
+
+Bulk value expansion is supported by these grammars and database features:
+
++ SQL Server 2016+ using `OPENJSON`; database compatibility level 130+ is required
++ PostgreSQL 9.4+ using `JSONB_ARRAY_ELEMENTS_TEXT`
++ MySQL 8.0.4+ and MariaDB 10.6+ using `JSON_TABLE`
++ Oracle Database 12c Release 1 (12.1.0.2)+ using `JSON_TABLE`
++ SQLite with JSON functions enabled; they are built in by default as of SQLite 3.38.0
+
+Derby does not support bulk value expansion and throws an `UnsupportedOperation` exception for non-empty collections.
+
+## Development Validation
+
+qb can detect statically identifiable duplicate select output names before they are silently collapsed by CFML query results. Enable this validation in development and leave it disabled in production:
+
+```cfc
+moduleSettings = {
+    "qb": {
+        "validateDuplicateSelectColumns": true
+    }
+};
+```
+
+The validation checks the final selection when the query is compiled, including simple columns, explicit aliases, subselect aliases, and explicitly aliased typed columns. Wildcards and expressions without explicit aliases are skipped because their output names cannot be known until the query executes.
+
+## Return Formatters
+
+qb includes named return formatters for `array`, `query`, `none`, and `struct`. The `struct` formatter returns a struct of rows keyed by a selected column:
+
+```cfc
+usersByUsername = query
+    .setReturnFormat( "struct", { "columnKey": "username" } )
+    .from( "users" )
+    .get();
+```
+
+Applications can register reusable custom formatter factories in their qb module settings:
+
+```cfc
+moduleSettings = {
+    "qb": {
+        "returnFormatters": {
+            "ids": function( options ) {
+                return function( q ) {
+                    return queryColumnData( q, options.column );
+                };
+            }
+        }
+    }
+};
+
+ids = query
+    .setReturnFormat( "ids", { "column": "id" } )
+    .from( "users" )
+    .get();
+```
+
+Formatter factories can also be WireBox mapping names or components with a `toFormatter( options )` method.
+
 Here's a gist with an example of the powerful models you can create with this!
 https://gist.github.com/elpete/80d641b98025f16059f6476561d88202
 
@@ -118,4 +217,3 @@ For both Lucee and ACF you need to set the JDBC Driver class to `org.sqlite.JDBC
 ## Full Docs
 
 You can browse the full documentation at https://qb.ortusbooks.com
-

models/Grammars/AutoDiscover.cfc

@@ -2,34 +2,59 @@ component singleton {
 
     property name="wirebox" inject="wirebox";
     property name="grammar";
+    property name="shouldWrapValues";
 
     function autoDiscoverGrammar() {
         cfdbinfo( type = "Version", name = "local.dbInfo" );
 
+        var discoveredGrammar = "";
         switch ( dbInfo.DATABASE_PRODUCTNAME ) {
             case "MySQL":
             case "MariaDB":
-                return wirebox.getInstance( "MySQLGrammar@qb" );
+                discoveredGrammar = wirebox.getInstance( "MySQLGrammar@qb" );
+                break;
             case "Derby":
-                return wirebox.getInstance( "DerbyGrammar@qb" );
+                discoveredGrammar = wirebox.getInstance( "DerbyGrammar@qb" );
+                break;
             case "PostgreSQL":
-                return wirebox.getInstance( "PostgresGrammar@qb" );
+                discoveredGrammar = wirebox.getInstance( "PostgresGrammar@qb" );
+                break;
             case "Microsoft SQL Server":
-                return wirebox.getInstance( "SQLServerGrammar@qb" );
+                discoveredGrammar = wirebox.getInstance( "SQLServerGrammar@qb" );
+                break;
             case "Oracle":
-                return wirebox.getInstance( "OracleGrammar@qb" );
+                discoveredGrammar = wirebox.getInstance( "OracleGrammar@qb" );
+                break;
             case "SQLite":
-                return wirebox.getInstance( "SQLiteGrammar@qb" );
+                discoveredGrammar = wirebox.getInstance( "SQLiteGrammar@qb" );
+                break;
             default:
-                return wirebox.getInstance( "BaseGrammar@qb" );
+                discoveredGrammar = wirebox.getInstance( "BaseGrammar@qb" );
         }
+
+        return discoveredGrammar;
     }
 
-    function onMissingMethod( missingMethodName, missingMethodArguments ) {
-        if ( isNull( variables.grammar ) || !structKeyExists( variables, "grammar" ) ) {
+    public AutoDiscover function setShouldWrapValues( required boolean shouldWrapValues ) {
+        variables.shouldWrapValues = arguments.shouldWrapValues;
+        if ( structKeyExists( variables, "grammar" ) && !isNull( variables.grammar ) ) {
+            variables.grammar.setShouldWrapValues( arguments.shouldWrapValues );
+        }
+        return this;
+    }
+
+    public any function getResolvedGrammar() {
+        if ( !structKeyExists( variables, "grammar" ) || isNull( variables.grammar ) ) {
             variables.grammar = autoDiscoverGrammar();
+            if ( structKeyExists( variables, "shouldWrapValues" ) && !isNull( variables.shouldWrapValues ) ) {
+                variables.grammar.setShouldWrapValues( variables.shouldWrapValues );
+            }
         }
-        return invoke( variables.grammar, missingMethodName, missingMethodArguments );
+        return variables.grammar;
+    }
+
+    function onMissingMethod( missingMethodName, missingMethodArguments ) {
+        return invoke( getResolvedGrammar(), missingMethodName, missingMethodArguments );
     }
 
 }