typescript-best-practices

Type external data as unknown instead of any, since any disables type checking everywhere it touches. Narrow unknown with typeof, instanceof, or the in operator before accessing properties, or parse it with a schema library like Zod.

Use a discriminated union with a shared literal discriminant field like kind, with variants for loading, ready, and error. This makes contradictory combinations like loading true with data present impossible to represent, unlike boolean-plus-optional-field shapes.

Prefer the repository's existing schema library before hand-writing property-by-property guards for external data. Define one schema, derive the type with z.infer, and use safeParse when failure is an expected branch, avoiding drift between schema, interface, and guard.

Every as cast is a potential runtime crash because it overrides the compiler without verifying the claim. Cast only after full validation of the value, and prefer satisfies, which validates the value while preserving literal types instead of widening them.

Add a default arm that assigns the discriminant to a never-typed local, such as const _exhaustive: never = s. The compiler then errors when a new union variant is added without a matching case, catching incomplete handling at compile time.

Keep plain T[] when every operation on it stays total, like summing numbers where empty is valid. Strengthen to NonEmpty<T> or branded primitives only where the loose type forces a non-null assertion, a cast, or a should-never-happen throw at a use site.