Merge pull request #1920 from wheels-dev/peter/query-scopes-1907

Query scopes: 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
+- 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 Scopes](database-interaction-through-models/query-scopes.md)
 * [Batch Processing](database-interaction-through-models/batch-processing.md)
 * [Automatic Time Stamps](database-interaction-through-models/automatic-time-stamps.md)
 * [Database Migrations](database-interaction-through-models/database-migrations/README.md)

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

@@ -0,0 +1,117 @@
+# Query Scopes
+
+Query scopes let you define reusable, composable query fragments on your models. Instead of repeating the same `where` or `order` clauses across your application, define them once in the model's `config()` and chain them together.
+
+## Defining Scopes
+
+Add scopes in your model's `config()` function using `scope()`:
+
+```cfm
+component extends="Model" {
+    function config() {
+        // Static scopes — fixed query fragments
+        scope(name="active", where="status = 'active'");
+        scope(name="recent", order="createdAt DESC");
+        scope(name="limited", maxRows=10);
+
+        // Dynamic scope — accepts arguments at call time
+        scope(name="byRole", handler="scopeByRole");
+    }
+
+    private struct function scopeByRole(required string role) {
+        return {where: "role = '#arguments.role#'"};
+    }
+}
+```
+
+### Static Scopes
+
+Static scopes define a fixed set of query parameters. The `scope()` function accepts these keys:
+
+| Parameter | Description |
+|-----------|-------------|
+| `name` | The scope name (becomes the chainable method) |
+| `where` | SQL WHERE clause fragment |
+| `order` | SQL ORDER BY clause |
+| `select` | Columns to select |
+| `include` | Associated models to include |
+| `maxRows` | Limit the number of rows returned |
+
+### Dynamic Scopes
+
+Dynamic scopes use a `handler` function that returns a struct of query parameters. The handler receives whatever arguments the caller passes:
+
+```cfm
+scope(name="olderThan", handler="scopeOlderThan");
+
+private struct function scopeOlderThan(required numeric age) {
+    return {where: "age > #arguments.age#"};
+}
+```
+
+## Using Scopes
+
+Call scopes as methods on the model, then finish with a terminal method like `findAll()`, `findOne()`, `count()`, or `exists()`:
+
+```cfm
+// Single scope
+users = model("User").active().findAll();
+
+// Chained scopes — conditions are AND'd together
+users = model("User").active().recent().findAll();
+
+// Dynamic scope with argument
+admins = model("User").byRole("admin").findAll();
+
+// With additional finder arguments
+users = model("User").active().findAll(page=1, perPage=25);
+```
+
+## How Scopes Combine
+
+When you chain multiple scopes:
+
+- **WHERE** clauses are combined with `AND`
+- **ORDER BY** clauses are appended (first scope's order comes first)
+- **INCLUDE** clauses are appended
+- **SELECT** uses the last scope's value (last wins)
+- **maxRows** uses the smallest value
+
+```cfm
+// These two WHERE clauses become: (status = 'active') AND (role = 'admin')
+model("User").active().byRole("admin").findAll();
+```
+
+## Terminal Methods
+
+After building a scope chain, call one of these to execute the query:
+
+| Method | Returns |
+|--------|---------|
+| `findAll()` | Query result set |
+| `findOne()` | Single model object |
+| `findByKey(key)` | Model object by primary key |
+| `count()` | Number of matching records |
+| `exists()` | Boolean |
+| `average(property)` | Average value |
+| `sum(property)` | Sum of values |
+| `maximum(property)` | Maximum value |
+| `minimum(property)` | Minimum value |
+| `updateAll(...)` | Updates matching records |
+| `deleteAll()` | Deletes matching records |
+| `findEach(callback)` | Batch iteration (one at a time) |
+| `findInBatches(callback)` | Batch iteration (groups) |
+
+## Transitioning to the Query Builder
+
+You can move from a scope chain into the chainable query builder at any point:
+
+```cfm
+model("User")
+    .active()
+    .where("age", ">", 18)
+    .orderBy("name", "ASC")
+    .get();
+```
+
+See [Query Builder](query-builder.md) for the full fluent API.

tests/_assets/models/AuthorScoped.cfc

@@ -0,0 +1,16 @@
+component extends="Model" {
+
+	function config() {
+		table("c_o_r_e_authors");
+
+		scope(name = "withLastNameDjurner", where = "lastname = 'Djurner'");
+		scope(name = "orderedByFirstName", order = "firstname ASC");
+		scope(name = "firstThree", maxRows = 3);
+		scope(name = "byLastName", handler = "scopeByLastName");
+	}
+
+	private struct function scopeByLastName(required string lastName) {
+		return {where: "lastname = '#arguments.lastName#'"};
+	}
+
+}

tests/specs/models/QueryScopesSpec.cfc

@@ -0,0 +1,92 @@
+component extends="wheels.WheelsTest" {
+
+	function run() {
+
+		describe("Query Scopes", () => {
+
+			describe("static scopes", () => {
+
+				it("filters with a where scope", () => {
+					var result = model("authorScoped").withLastNameDjurner().findAll();
+					expect(result.recordcount).toBe(1);
+					expect(result.lastname).toBe("Djurner");
+				})
+
+				it("orders with an order scope", () => {
+					var result = model("authorScoped").orderedByFirstName().findAll();
+					expect(result.firstname[1]).toBe("Adam");
+				})
+
+				it("limits with a maxRows scope", () => {
+					var result = model("authorScoped").firstThree().findAll(order = "id");
+					expect(result.recordcount).toBe(3);
+				})
+
+			})
+
+			describe("chaining", () => {
+
+				it("chains multiple scopes together", () => {
+					var result = model("authorScoped").orderedByFirstName().firstThree().findAll();
+					expect(result.recordcount).toBe(3);
+					expect(result.firstname[1]).toBe("Adam");
+				})
+
+				it("returns a chainable object, not a query", () => {
+					var chain = model("authorScoped").withLastNameDjurner();
+					expect(IsQuery(chain)).toBeFalse();
+					expect(IsSimpleValue(chain)).toBeFalse();
+				})
+
+				it("merges scope WHERE with finder WHERE using AND", () => {
+					var result = model("authorScoped").withLastNameDjurner().findAll(where = "firstname = 'Per'");
+					expect(result.recordcount).toBe(1);
+					expect(result.firstname).toBe("Per");
+				})
+
+			})
+
+			describe("dynamic scopes", () => {
+
+				it("accepts arguments via a handler function", () => {
+					var result = model("authorScoped").byLastName("Petruzzi").findAll();
+					expect(result.recordcount).toBe(1);
+					expect(result.lastname).toBe("Petruzzi");
+				})
+
+			})
+
+			describe("terminal methods", () => {
+
+				it("works with count()", () => {
+					var result = model("authorScoped").withLastNameDjurner().count();
+					expect(result).toBe(1);
+				})
+
+				it("works with findOne()", () => {
+					var result = model("authorScoped").withLastNameDjurner().findOne();
+					expect(IsObject(result)).toBeTrue();
+					expect(result.lastName).toBe("Djurner");
+				})
+
+				it("works with exists()", () => {
+					var result = model("authorScoped").withLastNameDjurner().exists();
+					expect(result).toBeTrue();
+				})
+
+				it("accepts additional finder args", () => {
+					var result = model("authorScoped").orderedByFirstName().findAll(select = "firstname");
+					expect(result.recordcount).toBeGT(0);
+				})
+
+			})
+
+			it("returns empty results for non-matching scope", () => {
+				var result = model("authorScoped").byLastName("NonExistent").findAll();
+				expect(result.recordcount).toBe(0);
+			})
+
+		})
+
+	}
+}