feat: add tests and docs for enum support (#1910)

- PostWithEnum test model with status enum (draft/published/archived)
- 11 unit tests covering is*() checkers, auto-scopes, validation
- Added status column to c_o_r_e_posts test table with seed data
- Framework documentation page with usage examples
- SUMMARY.md and CHANGELOG.md entries

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bpamiri

CHANGELOG.md

@@ -18,6 +18,13 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 ----
 
+## [Unreleased]
+
+### Added
+- Enum support with `enum()` for named property values, auto-generated `is*()` checkers, auto-scopes, and inclusion validation
+
+----
+
 
 # [3.0.0](https://github.com/wheels-dev/wheels/releases/tag/v3.0.0) => 2026-01-10
 

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)
+* [Enums](database-interaction-through-models/enums.md)
 * [Automatic Time Stamps](database-interaction-through-models/automatic-time-stamps.md)
 * [Database Migrations](database-interaction-through-models/database-migrations/README.md)
   * [Migrations in Production](database-interaction-through-models/database-migrations/migrations-in-production.md)

docs/src/database-interaction-through-models/enums.md

@@ -0,0 +1,118 @@
+# Enums
+
+Enums let you define a fixed set of allowed values for a model property. Wheels automatically generates boolean checker methods, query scopes, and inclusion validation for each enum.
+
+## Defining Enums
+
+Add enums in your model's `config()` function:
+
+```cfm
+component extends="Model" {
+    function config() {
+        // String list — each value is both the name and stored value
+        enum(property="status", values="draft,published,archived");
+
+        // Struct mapping — names map to different stored values
+        enum(property="priority", values={low: 0, medium: 1, high: 2});
+    }
+}
+```
+
+### String List
+
+When you pass a comma-delimited string, each value serves as both the display name and the stored database value:
+
+```cfm
+enum(property="status", values="draft,published,archived");
+// Stores "draft", "published", or "archived" in the database
+```
+
+### Struct Mapping
+
+When you pass a struct, the keys are the names and the values are what gets stored in the database:
+
+```cfm
+enum(property="priority", values={low: 0, medium: 1, high: 2});
+// Stores 0, 1, or 2 in the database
+```
+
+## What Enums Generate
+
+Defining an enum automatically creates three things:
+
+### 1. Boolean Checker Methods
+
+For each enum value, an `is<Value>()` method is generated on model instances:
+
+```cfm
+post = model("Post").findByKey(1);
+
+post.isDraft();      // true or false
+post.isPublished();  // true or false
+post.isArchived();   // true or false
+```
+
+### 2. Query Scopes
+
+Each enum value becomes a named scope you can chain:
+
+```cfm
+// Find all draft posts
+drafts = model("Post").draft().findAll();
+
+// Find all published posts, ordered by date
+published = model("Post").published().findAll(order="createdAt DESC");
+
+// Count archived posts
+archivedCount = model("Post").archived().count();
+```
+
+### 3. Inclusion Validation
+
+A `validatesInclusionOf` validation is automatically registered, preventing invalid values:
+
+```cfm
+post = model("Post").new();
+post.status = "invalid_value";
+post.valid();  // false — "invalid_value" is not in the enum
+
+post.status = "published";
+post.valid();  // true (assuming other validations pass)
+post.errorsOn("status");  // empty array
+```
+
+The validation uses `allowBlank=true`, so blank/empty values are permitted unless you add a separate `validatesPresenceOf`.
+
+## Examples
+
+### Filtering by Enum Value
+
+```cfm
+// Using auto-generated scopes
+model("Post").published().findAll(page=1, perPage=25);
+
+// Using standard WHERE clause
+model("Post").findAll(where="status = 'published'");
+
+// Using query builder
+model("Post").where("status", "published").get();
+```
+
+### Checking State in Views
+
+```cfm
+<cfif post.isPublished()>
+    <span class="badge badge-success">Published</span>
+<cfelseif post.isDraft()>
+    <span class="badge badge-warning">Draft</span>
+<cfelse>
+    <span class="badge badge-secondary">Archived</span>
+</cfif>
+```
+
+### Combining Scopes
+
+```cfm
+// Enum scopes compose with other scopes
+model("Post").published().recent().findAll();
+```

vendor/wheels/tests/_assets/models/PostWithEnum.cfc

@@ -0,0 +1,9 @@
+component extends="Model" {
+
+	function config() {
+		table("c_o_r_e_posts");
+		belongsTo("author");
+		enum(property = "status", values = "draft,published,archived");
+	}
+
+}

vendor/wheels/tests/model/properties/enums.cfc

@@ -0,0 +1,77 @@
+component extends="wheels.tests.Test" {
+
+	/* --- isDraft() / isPublished() / isArchived() boolean checkers --- */
+
+	function test_isDraft_returns_true_for_draft_post() {
+		post = model("postWithEnum").findOne(where = "status = 'draft'", order = "id");
+		assert("IsObject(post)");
+		assert("post.isDraft() IS true");
+	}
+
+	function test_isDraft_returns_false_for_published_post() {
+		post = model("postWithEnum").findOne(where = "status = 'published'", order = "id");
+		assert("IsObject(post)");
+		assert("post.isDraft() IS false");
+	}
+
+	function test_isPublished_returns_true_for_published_post() {
+		post = model("postWithEnum").findOne(where = "status = 'published'", order = "id");
+		assert("post.isPublished() IS true");
+	}
+
+	function test_isArchived_returns_true_for_archived_post() {
+		post = model("postWithEnum").findOne(where = "status = 'archived'", order = "id");
+		assert("post.isArchived() IS true");
+	}
+
+	function test_isArchived_returns_false_for_draft_post() {
+		post = model("postWithEnum").findOne(where = "status = 'draft'", order = "id");
+		assert("post.isArchived() IS false");
+	}
+
+	/* --- Enum validation --- */
+
+	function test_validates_inclusion_of_enum_values() {
+		post = model("postWithEnum").findOne(order = "id");
+		post.status = "invalid_status";
+		assert("post.valid() IS false");
+	}
+
+	function test_valid_enum_value_passes_validation() {
+		post = model("postWithEnum").findOne(order = "id");
+		post.status = "published";
+		// Should pass the enum inclusion validation (other validations may fail)
+		post.valid();
+		errors = post.errorsOn("status");
+		assert("ArrayLen(errors) IS 0");
+	}
+
+	/* --- Auto-generated scopes per enum value --- */
+
+	function test_draft_scope_returns_draft_posts() {
+		result = model("postWithEnum").draft().findAll();
+		assert("result.recordcount GT 0");
+		assert("result.status IS 'draft'");
+	}
+
+	function test_published_scope_returns_published_posts() {
+		result = model("postWithEnum").published().findAll();
+		assert("result.recordcount GT 0");
+		assert("result.status IS 'published'");
+	}
+
+	function test_archived_scope_returns_archived_posts() {
+		result = model("postWithEnum").archived().findAll();
+		assert("result.recordcount GT 0");
+		assert("result.status IS 'archived'");
+	}
+
+	function test_enum_scope_with_count() {
+		draftCount = model("postWithEnum").draft().count();
+		publishedCount = model("postWithEnum").published().count();
+		archivedCount = model("postWithEnum").archived().count();
+		totalCount = model("postWithEnum").count();
+		assert("draftCount + publishedCount + archivedCount IS totalCount");
+	}
+
+}

vendor/wheels/tests/populate.cfm

@@ -174,6 +174,7 @@ CREATE TABLE c_o_r_e_posts
 	,deletedat #local.datetimeColumnType# NULL
 	,views #local.intColumnType# DEFAULT 0 NOT NULL
 	,averagerating #local.floatColumnType# NULL
+	,status varchar(20) DEFAULT 'draft' NOT NULL
 	,PRIMARY KEY(id)
 ) #local.storageEngine#
 </cfquery>
@@ -416,6 +417,14 @@ FROM c_o_r_e_users u INNER JOIN c_o_r_e_galleries g ON u.id = g.userid
 	views = 2,
 	averageRating = "3.6"
 )>
+<!--- set some post statuses for enum testing --->
+<cfquery datasource="#application.wheels.dataSourceName#">
+	UPDATE c_o_r_e_posts SET status = 'published' WHERE id IN (1, 2)
+</cfquery>
+<cfquery datasource="#application.wheels.dataSourceName#">
+	UPDATE c_o_r_e_posts SET status = 'archived' WHERE id = 3
+</cfquery>
+
 <cfset local.chris = model("author").create(firstName = "Chris", lastName = "Peters")>
 <cfset local.peter = model("author").create(firstName = "Peter", lastName = "Amiri")>
 <cfset local.james = model("author").create(firstName = "James", lastName = "Gibson")>