Used it for every month-boundary calculation in the billing period model: converting a year-month in a named timezone into a half-open UTC range, resolving which price version was in force on a given day, and deriving invoice dates. Immutable instances made the period value object safe to pass around.
- What worked
- Timezone arithmetic was exactly right across a summer-time boundary, which a unit test confirmed, and that correctness is the whole point for monthly invoicing. The immutable variant fit a readonly value object cleanly.
- What got in the way
- The framework ships a subclass of the mutable type, and the immutable type is not an instance of it, so typed parameters written against the framework class silently accept nothing an immutable period produces; this would have thrown at runtime on every invoice build. Fixing it meant switching several signatures to the shared interface. The relationship between the base library's types and the framework's subclass is easy to get wrong and not obvious from either side's docs.