Merge pull request #1922 from wheels-dev/peter/query-builder-1908

Query builder: tests and documentation

Author: bpamiri

CHANGELOG.md

@@ -21,6 +21,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 ## [Unreleased]
 
 ### Added
+- Chainable query builder with `where()`, `orWhere()`, `whereNull()`, `whereBetween()`, `whereIn()`, `orderBy()`, `limit()`, and more for injection-safe fluent queries
 - Enum support with `enum()` for named property values, auto-generated `is*()` checkers, auto-scopes, and inclusion validation
 - Query scopes with `scope()` for reusable, composable query fragments in models
 - Batch processing with `findEach()` and `findInBatches()` for memory-efficient record iteration

docs/src/SUMMARY.md

@@ -177,6 +177,7 @@
 * [Transactions](database-interaction-through-models/transactions.md)
 * [Dirty Records](database-interaction-through-models/dirty-records.md)
 * [Soft Delete](database-interaction-through-models/soft-delete.md)
+* [Query Builder](database-interaction-through-models/query-builder.md)
 * [Enums](database-interaction-through-models/enums.md)
 * [Query Scopes](database-interaction-through-models/query-scopes.md)
 * [Batch Processing](database-interaction-through-models/batch-processing.md)

docs/src/database-interaction-through-models/query-builder.md

@@ -0,0 +1,160 @@
+# Query Builder
+
+The query builder provides a fluent, chainable API for constructing database queries. It is an alternative to passing raw SQL strings to `findAll(where="...")`, with the added benefit of automatic value quoting for SQL injection safety.
+
+## Basic Usage
+
+Start a query chain by calling `.where()` on any model, then finish with a terminal method like `.get()`:
+
+```cfm
+users = model("User")
+    .where("status", "active")
+    .where("age", ">", 18)
+    .orderBy("name", "ASC")
+    .limit(25)
+    .get();
+```
+
+## WHERE Conditions
+
+### Equality
+
+```cfm
+// Two arguments: property, value
+model("User").where("status", "active").get();
+// Generates: status = 'active'
+```
+
+### Operators
+
+```cfm
+// Three arguments: property, operator, value
+model("User").where("age", ">", 18).get();
+model("User").where("views", ">=", 100).get();
+model("User").where("name", "LIKE", "%smith%").get();
+```
+
+### Raw Strings
+
+```cfm
+// One argument: raw WHERE clause (no auto-quoting)
+model("User").where("status = 'active' AND role = 'admin'").get();
+```
+
+### OR Conditions
+
+```cfm
+model("User")
+    .where("role", "admin")
+    .orWhere("role", "superadmin")
+    .get();
+// Generates: role = 'admin' OR role = 'superadmin'
+```
+
+### NULL Checks
+
+```cfm
+model("User").whereNull("deletedAt").get();
+model("User").whereNotNull("emailVerifiedAt").get();
+```
+
+### BETWEEN
+
+```cfm
+model("Product").whereBetween("price", 10, 50).get();
+// Generates: price BETWEEN 10 AND 50
+```
+
+### IN / NOT IN
+
+```cfm
+// With a comma-delimited list
+model("User").whereIn("role", "admin,editor,author").get();
+
+// With an array
+model("User").whereIn("role", ["admin", "editor"]).get();
+
+// NOT IN
+model("User").whereNotIn("status", "banned,suspended").get();
+```
+
+## Ordering
+
+```cfm
+model("User").orderBy("name", "ASC").get();
+model("User").orderBy("createdAt", "DESC").get();
+
+// Multiple order clauses
+model("User")
+    .orderBy("lastName", "ASC")
+    .orderBy("firstName", "ASC")
+    .get();
+```
+
+## Limiting Results
+
+```cfm
+model("User").limit(10).get();
+model("User").offset(20).limit(10).get();
+```
+
+## Other Builder Methods
+
+```cfm
+// Select specific columns
+model("User").select("id,name,email").get();
+
+// Include associations
+model("User").include("profile,orders").get();
+
+// Group by
+model("Order").select("status,COUNT(id) as orderCount").group("status").get();
+
+// Distinct
+model("User").select("city").distinct().get();
+```
+
+## Terminal Methods
+
+Call one of these to execute the built query:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get()` | query | Alias for `findAll()` |
+| `findAll()` | query | All matching records |
+| `first()` | object | Alias for `findOne()` |
+| `findOne()` | object | First matching record |
+| `count()` | numeric | Number of matching records |
+| `exists()` | boolean | Whether any records match |
+| `updateAll(...)` | numeric | Update matching records |
+| `deleteAll()` | numeric | Delete matching records |
+| `findEach(callback)` | void | Batch iterate one at a time |
+| `findInBatches(callback)` | void | Batch iterate in groups |
+
+## Combining with Scopes
+
+You can transition from scopes to the query builder at any point in the chain:
+
+```cfm
+model("User")
+    .active()                    // scope
+    .where("role", "admin")      // query builder
+    .orderBy("name", "ASC")
+    .get();
+```
+
+See [Query Scopes](query-scopes.md) for defining reusable scope fragments.
+
+## SQL Injection Safety
+
+All values passed to `where()`, `whereBetween()`, `whereIn()`, and `whereNotIn()` are automatically quoted using the model's database adapter. You do not need to manually escape values:
+
+```cfm
+// Safe — value is auto-quoted
+model("User").where("name", userInput).get();
+
+// Also safe
+model("User").whereIn("id", userSuppliedIds).get();
+```
+
+Raw string WHERE clauses (single-argument `where()`) are passed through as-is. Avoid interpolating user input into raw strings.

tests/specs/models/QueryBuilderSpec.cfc

@@ -0,0 +1,157 @@
+component extends="wheels.WheelsTest" {
+
+	function run() {
+
+		describe("Query Builder", () => {
+
+			describe("where()", () => {
+
+				it("filters with equality (2-arg form)", () => {
+					var result = model("author").where("lastName", "Djurner").get();
+					expect(result.recordcount).toBe(1);
+					expect(result.lastname).toBe("Djurner");
+				})
+
+				it("filters with an operator (3-arg form)", () => {
+					var result = model("post").where("views", ">", 0).get();
+					expect(result.recordcount).toBeGT(0);
+				})
+
+				it("passes through raw SQL strings (1-arg form)", () => {
+					var result = model("author").where("lastName = 'Djurner'").get();
+					expect(result.recordcount).toBe(1);
+				})
+
+				it("chains multiple where conditions with AND", () => {
+					var result = model("author").where("firstName", "Per").where("lastName", "Djurner").get();
+					expect(result.recordcount).toBe(1);
+				})
+
+			})
+
+			describe("orWhere()", () => {
+
+				it("combines conditions with OR", () => {
+					var result = model("author").where("lastName", "Djurner").orWhere("lastName", "Petruzzi").get();
+					expect(result.recordcount).toBe(2);
+				})
+
+			})
+
+			describe("NULL checks", () => {
+
+				it("filters with whereNull()", () => {
+					var result = model("post").whereNull("deletedat").get();
+					expect(result.recordcount).toBeGT(0);
+				})
+
+				it("filters with whereNotNull()", () => {
+					var result = model("post").whereNotNull("averagerating").get();
+					expect(result.recordcount).toBeGT(0);
+				})
+
+			})
+
+			describe("whereBetween()", () => {
+
+				it("filters values in a range", () => {
+					var result = model("post").whereBetween("views", 1, 5).get();
+					expect(result.recordcount).toBeGT(0);
+				})
+
+			})
+
+			describe("whereIn() / whereNotIn()", () => {
+
+				it("matches values in a list", () => {
+					var result = model("author").whereIn("lastName", "Djurner,Petruzzi").get();
+					expect(result.recordcount).toBe(2);
+				})
+
+				it("matches values in an array", () => {
+					var result = model("author").whereIn("lastName", ["Djurner", "Petruzzi"]).get();
+					expect(result.recordcount).toBe(2);
+				})
+
+				it("excludes values with whereNotIn()", () => {
+					var totalCount = model("author").count();
+					var result = model("author").whereNotIn("lastName", "Djurner,Petruzzi").get();
+					expect(result.recordcount).toBe(totalCount - 2);
+				})
+
+			})
+
+			describe("orderBy()", () => {
+
+				it("orders ascending", () => {
+					var result = model("author").orderBy("firstName", "ASC").get();
+					expect(result.firstname[1]).toBe("Adam");
+				})
+
+				it("orders descending", () => {
+					var result = model("author").orderBy("firstName", "DESC").get();
+					expect(result.firstname[1]).toBe("Tony");
+				})
+
+			})
+
+			describe("limit()", () => {
+
+				it("limits the number of results", () => {
+					var result = model("author").limit(3).orderBy("id", "ASC").get();
+					expect(result.recordcount).toBe(3);
+				})
+
+			})
+
+			describe("terminal methods", () => {
+
+				it("get() is an alias for findAll()", () => {
+					var r1 = model("author").where("lastName", "Djurner").get();
+					var r2 = model("author").where("lastName", "Djurner").findAll();
+					expect(r1.recordcount).toBe(r2.recordcount);
+				})
+
+				it("first() returns a model object", () => {
+					var result = model("author").where("lastName", "Djurner").first();
+					expect(IsObject(result)).toBeTrue();
+					expect(result.lastName).toBe("Djurner");
+				})
+
+				it("findOne() returns a model object", () => {
+					var result = model("author").where("lastName", "Djurner").findOne();
+					expect(IsObject(result)).toBeTrue();
+				})
+
+				it("count() returns the matching count", () => {
+					var result = model("author").where("lastName", "Djurner").count();
+					expect(result).toBe(1);
+				})
+
+				it("exists() returns true for matching records", () => {
+					var result = model("author").where("lastName", "Djurner").exists();
+					expect(result).toBeTrue();
+				})
+
+				it("exists() returns false for no matches", () => {
+					var result = model("author").where("lastName", "NonExistent").exists();
+					expect(result).toBeFalse();
+				})
+
+			})
+
+			it("handles complex chains", () => {
+				var result = model("author")
+					.where("firstName", "Per")
+					.whereNotNull("lastName")
+					.orderBy("id", "ASC")
+					.limit(10)
+					.get();
+				expect(result.recordcount).toBe(1);
+				expect(result.firstname).toBe("Per");
+			})
+
+		})
+
+	}
+}