v14

.github/patches/testbox-full-null.patch

@@ -0,0 +1,69 @@
+diff --git a/testbox/system/coverage/CoverageService.cfc b/testbox/system/coverage/CoverageService.cfc
+--- a/testbox/system/coverage/CoverageService.cfc
++++ b/testbox/system/coverage/CoverageService.cfc
+@@ -175 +175 @@
+-		if ( isNull( opts.coverageTresholds ) ) {
++		if ( !structKeyExists( opts, "coverageTresholds" ) || isNull( opts.coverageTresholds ) ) {
+@@ -178 +178 @@
+-		if ( isNull( opts.coverageTresholds.good ) ) {
++		if ( !structKeyExists( opts.coverageTresholds, "good" ) || isNull( opts.coverageTresholds.good ) ) {
+@@ -181 +181 @@
+-		if ( isNull( opts.coverageTresholds.bad ) ) {
++		if ( !structKeyExists( opts.coverageTresholds, "bad" ) || isNull( opts.coverageTresholds.bad ) ) {
+diff --git a/testbox/system/TestBox.cfc b/testbox/system/TestBox.cfc
+--- a/testbox/system/TestBox.cfc
++++ b/testbox/system/TestBox.cfc
+@@ -408 +408 @@
+-		if ( !isNull( url.testBundles ) ) {
++		if ( structKeyExists( url, "testBundles" ) && !isNull( url.testBundles ) ) {
+@@ -411 +411 @@
+-		if ( !isNull( url.testSuites ) ) {
++		if ( structKeyExists( url, "testSuites" ) && !isNull( url.testSuites ) ) {
+@@ -414 +414 @@
+-		if ( !isNull( url.testSpecs ) ) {
++		if ( structKeyExists( url, "testSpecs" ) && !isNull( url.testSpecs ) ) {
+@@ -417 +417 @@
+-		if ( !isNull( url.testMethod ) ) {
++		if ( structKeyExists( url, "testMethod" ) && !isNull( url.testMethod ) ) {
+@@ -259 +259 @@
+-		if ( isNull( variables.env ) ) {
++		if ( !structKeyExists( variables, "env" ) || isNull( variables.env ) ) {
+diff --git a/testbox/system/util/Util.cfc b/testbox/system/util/Util.cfc
+--- a/testbox/system/util/Util.cfc
++++ b/testbox/system/util/Util.cfc
+@@ -203 +203 @@
+-		if ( isNull( variables.engineMappingHelper ) ) {
++		if ( !structKeyExists( variables, "engineMappingHelper" ) || isNull( variables.engineMappingHelper ) ) {
+diff --git a/testbox/system/util/Env.cfc b/testbox/system/util/Env.cfc
+--- a/testbox/system/util/Env.cfc
++++ b/testbox/system/util/Env.cfc
+@@ -87 +87 @@
+-		if ( isNull( variables.javaSystem ) ) {
++		if ( !structKeyExists( variables, "javaSystem" ) || isNull( variables.javaSystem ) ) {
+diff --git a/testbox/system/BaseSpec.cfc b/testbox/system/BaseSpec.cfc
+--- a/testbox/system/BaseSpec.cfc
++++ b/testbox/system/BaseSpec.cfc
+@@ -1627 +1627 @@
+-		if ( isNull( variables.$cbMockData ) ) {
++		if ( !structKeyExists( variables, "$cbMockData" ) || isNull( variables.$cbMockData ) ) {
+@@ -1640 +1640 @@
+-		if ( isNull( variables.$utility ) ) {
++		if ( !structKeyExists( variables, "$utility" ) || isNull( variables.$utility ) ) {
+@@ -1653 +1653 @@
+-		if ( isNull( variables.$env ) ) {
++		if ( !structKeyExists( variables, "$env" ) || isNull( variables.$env ) ) {
+@@ -1668 +1668 @@
+-		if ( isNull( this.$mockbox ) ) {
++		if ( !structKeyExists( this, "$mockbox" ) || isNull( this.$mockbox ) ) {
+diff --git a/testbox/system/runners/BDDRunner.cfc b/testbox/system/runners/BDDRunner.cfc
+--- a/testbox/system/runners/BDDRunner.cfc
++++ b/testbox/system/runners/BDDRunner.cfc
+@@ -159 +159 @@
+-						isNull( thisSuite ) ? {} : thisSuite
++						!structKeyExists( local, "thisSuite" ) || isNull( local.thisSuite ) ? {} : local.thisSuite
+diff --git a/testbox/system/runners/BaseRunner.cfc b/testbox/system/runners/BaseRunner.cfc
+--- a/testbox/system/runners/BaseRunner.cfc
++++ b/testbox/system/runners/BaseRunner.cfc
+@@ -275 +275 @@
+-		if ( isNull( md.skip ) ) {
++		if ( !md.keyExists( "skip" ) || isNull( md.skip ) ) {

.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"
@@ -40,8 +38,11 @@ jobs:
       - name: Install dependencies
         run: |
           box install
+          git apply --unidiff-zero .github/patches/testbox-full-null.patch
 
       - 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 +51,4 @@ jobs:
         env:
           FULL_NULL: ${{matrix.fullNull}}
         continue-on-error: ${{ matrix.experimental }}
-        run: box testbox run
+        run: box testbox run reporter=mintext

.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
@@ -48,8 +48,11 @@ jobs:
       - name: Install dependencies
         run: |
           box install
+          git apply --unidiff-zero .github/patches/testbox-full-null.patch
 
       - 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
@@ -58,7 +61,7 @@ jobs:
         env:
           FULL_NULL: ${{matrix.fullNull}}
         continue-on-error: ${{ matrix.experimental }}
-        run: box testbox run
+        run: box testbox run reporter=mintext
 
   format:
     runs-on: ubuntu-latest
@@ -80,9 +83,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

@@ -36,8 +36,11 @@ jobs:
       - name: Install dependencies
         run: |
           box install
+          git apply --unidiff-zero .github/patches/testbox-full-null.patch
 
       - 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
@@ -46,7 +49,7 @@ jobs:
         env:
           FULL_NULL: ${{matrix.fullNull}}
         continue-on-error: ${{ matrix.experimental }}
-        run: box testbox run
+        run: box testbox run reporter=mintext
 
   release:
     name: Semantic Release
@@ -104,4 +107,4 @@ jobs:
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_ACCESS_SECRET }}
           SOURCE_DIR: ".tmp/apidocs"
-          DEST_DIR: "${{ github.repository }}/${{ steps.current_version.outputs.version }}"
+          DEST_DIR: "${{ github.repository }}/${{ steps.current_version.outputs.version }}"

ModuleConfig.cfc

@@ -12,11 +12,14 @@ component {
             "defaultReturnFormat": "array",
             "preventDuplicateJoins": false,
             "validateOperatorsAndCombinators": true,
+            "validateDuplicateSelectColumns": false,
+            "validateQueryExecuteReturnType": false,
             "collectQueryLog": true,
             "convertEmptyStringsToNull": true,
+            "shouldWrapValues": true,
             "validateQueryParamStructKeys": true,
-            "numericSQLType": "NUMERIC",
             "integerSQLType": "INTEGER",
+            "bigIntegerSQLType": "BIGINT",
             "decimalSQLType": "DECIMAL",
             "defaultOptions": {},
             "sqlCommenter": {
@@ -29,7 +32,8 @@ component {
             },
             "shouldMaxRowsOverrideToAll": function( maxRows ) {
                 return maxRows <= 0;
-            }
+            },
+            "returnFormatters": {}
         };
 
         interceptorSettings = { "customInterceptionPoints": "preQBExecute,postQBExecute" };
@@ -51,17 +55,26 @@ 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 = "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 +84,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

@@ -71,6 +71,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 +200,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
-