Data shapes

Required

• Use typed objects instead of loose arrays

  Required

  Pass data between functions as a named type, such as a DTO or value object. Never use object, a plain dictionary or an untyped array that says nothing.

• Never type anything as mixed or any

  Required

  No mixed, any or untyped value in signatures, properties or docblocks. Each one turns off the type checker for everything it touches.

• Convert to arrays and JSON only at the edge

  Required

  Keep typed objects inside the app. Turn them into arrays, JSON or strings only where data leaves, such as an HTTP response or a database write.

• Parse input once at the boundary

  Required

  Turn outside input into a typed, valid object as soon as it arrives. Code after that point trusts the type and does not check again.

• Use enums instead of magic strings

  Required

  Give every fixed set of values an enum or union type. Never compare against loose strings such as "paid".

• Give each function one return type

  Required

  A function or endpoint always returns the same shape. It never returns an object in one case, an array in another and false in a third.

• Insert text literally when you replace

  Required

  When you insert outside text with a replace function, make sure the text goes in exactly as written. Many replace functions treat parts of the replacement as commands.

Recommended

• Wrap domain values in their own types

  Recommended

  Give each domain value with its own rules a small type, such as EmailAddress, OrderId or Money. Never pass it around as a bare string or number.

• Make data objects immutable

  Recommended

  Make DTOs and value objects read-only. Create a new object for a change instead of editing one that others may hold.

• Model each state as its own type

  Recommended

  When an object moves through states, give each state its own type with only the fields it has. Never pair a status field with optional fields that some states leave empty.