TState

TState is a term used in programming to denote a type parameter that encodes the state of an object at the type level. It is commonly associated with the type-state pattern, where state information is carried by types rather than by runtime fields. In this approach, TState is typically a phantom type—present only at compile time and not instantiated as a runtime value.

The primary purpose of TState is to enforce correct usage of an API through the type system. By representing possible states as distinct types (for example Uninitialized, Open, Closed), code can require specific states for certain operations. Transitioning from one state to another is represented by returning a new object whose TState reflects the new state, making illegal sequences unrepresentable in the type system.

Mechanically, a generic container or resource type is declared with a type parameter TState. Marker types are defined to represent valid states. Methods may be constrained to accept or produce particular TState values, and some state transitions are encoded as operations that return a new instance with a different TState. Because TState is typically phantom, these transitions incur little or no runtime overhead while providing stronger compile-time guarantees.

Use cases include resource management, protocol handling, and any scenario where certain operations must occur only after a prerequisite state. The approach can reduce runtime errors by catching misuse at compile time, though it can increase API complexity and affect ergonomics.

See also: type state, phantom type, generics, state machine patterns.