For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/languages/typescript/state.md.
Quick start

State

An update produces the next value; it does not alter a value another caller already holds.

Immutable ownership

Why

An installation plan must stay stable while it is inspected and applied. Storing its file count separately or mutating its changes array introduces avoidable disagreement.

Rules

  • MUST regard received arguments and module-level data as readonly inputs. [review]
  • MUST return a fresh object or array when an operation changes domain data. [review]
  • MUST keep assignment, mutating array methods, and Object.assign away from arguments and shared state. [review]
  • MUST derive counts, totals, and filtered views from the authoritative collection. [review]
  • MUST maintain one authoritative representation of each domain value. [review]
  • MUST use immutable application collections rather than authored Map, Set, WeakMap, or WeakSet state. [review]
  • MUST keep mutable application data out of module bindings and factory closures. [review]
  • MAY capture resource clients in factories or keep handles at lifetimes owned by a framework. [review]

Example

type AppendEntryParams = {
  readonly entries: readonly string[]
  readonly entry: string
}

function appendEntry({ entries, entry }: AppendEntryParams): readonly string[] {
  return [...entries, entry]
}

[review]

Readonly types cover supported mutation paths. Tests and review check aliasing, nested fields, and mutable application state that annotations alone cannot prevent.

Enforcement

Readonly types cover supported mutation paths. Tests and review check aliasing, nested fields, and mutable application state that annotations alone cannot prevent.