first-class-collection

name	first-class-collection
description	Use when wrapping collections in a domain-specific class to centralize collection rules, invariants, and behavior. Trigger for scattered list logic, collection wrappers, raw Order lists becoming `Orders`, enforcing collection invariants, or reviewing collection-heavy domain code.

First Class Collection

A first-class collection gives a collection a domain name and keeps collection rules in one place.

Rule

The wrapper should own one collection field and behavior around that collection. Extra unrelated fields usually mean it is an entity or aggregate instead.

Workflow

1. Find repeated collection operations, filters, totals, limits, ordering, or validation.

2. Name the collection as a domain concept.

3. Move rules into methods on the wrapper.

4. Keep the internal collection immutable or defensively copied.

5. Expose intention-revealing operations instead of raw mutation.

Checks

• Good: OrderLines.totalAmount(), Members.hasQuorum().

• Bad: exposing items and expecting callers to remember invariants.

• Avoid wrapping a collection that has no domain behavior.

Reference

Read references/patterns.md for implementation patterns.

Detailed Reference

For non-trivial implementation, review, or refactoring work, read references/details.md before giving final guidance. It contains the detailed rules, examples, smells, and migration notes that do not belong in the short invocation body.

Output

Return wrapper candidates, APIs, invariants, and migration steps.