Skip to content
Sarj Sarj Sarj Standards

prefer-nominal-id-types

Distinguish identifier roles sharing primitive types at callable boundaries.

preferNominalIds Rule source Tests Catalog JSON

Why

Two identifier roles represented by the same primitive accept each other's values, so swapped arguments survive type checking. Transparent aliases do not prevent this.

Fix

Introduce distinct branded identifier types at a validated domain boundary and use them in the callable contract. Keep wire representations primitive until validation; suppress a required external signature locally with a reason.

Examples

Before — flagged Do not accept interchangeable identifiers
src/store.ts
function load(accountId: string, invoiceId: string): void {}
After — preferred Distinguish domain identifiers
src/store.ts
type AccountId = string & { readonly account: unique symbol };
type InvoiceId = string & { readonly invoice: unique symbol };
function load(accountId: AccountId, invoiceId: InvoiceId): void {}