Document numeric intent
Use a meaningful name such as DurationSeconds or RetryCount when a codebase repeatedly passes numbers with a specific domain meaning.
TypeScript · Type Alias
number
A number type alias assigns a domain-specific name to TypeScript’s existing number type. It improves readability but does not create a distinct or nominal numeric type.
How it works
A type alias gives the existing number type another name; it does not create a distinct type. Values typed with the alias have the same assignability and behavior as values typed directly as number, so the alias is mainly useful for domain terminology or consistent declarations in a large codebase.
Syntax
type AliasName = number;Key points
- Declare the alias with the
typekeyword followed by an identifier, an equals sign, and the aliased type. - The basic declaration for this card is
type Second = number;, which names the built-in numeric type. - Unlike an interface, a type alias can directly name a primitive such as number, as well as composite forms.
- A value annotated directly as number demonstrates the underlying type represented by the alias.
- A value annotated with the alias accepts numeric values just as the direct number annotation does.
Common mistakes
- A number alias does not enforce a separate numeric domain or add nominal safety; it primarily documents intent.
- Do not use a number alias when distinct, non-interchangeable types are required; the alias remains interchangeable with number.
Example: A documented number alias
type NumberValue = number;
function add(a: NumberValue, b: NumberValue): NumberValue {
return a + b;
}
const total: NumberValue = add(2.5, 3.5);
console.log(total);The alias documents that these values are numbers while preserving the original number type.
When to use it
Standardize repeated annotations
Give a shared numeric concept one canonical name across function parameters, return types, and object properties.
Name library-facing values
Expose a public API using a stable domain term while retaining ordinary number assignability.
Interview questions
QWhat does a number type alias create?
A type alias such as type NumberValue = number introduces an alternate name for the existing number type. It does not create a new nominal type, so NumberValue and number are assignable in the same way.
Follow-up: How would you model a union instead? Use a type alias such as type Result = number | string; aliases can name unions as well as primitives.
QWhen is a primitive alias useful?
It can make a repeated primitive clearer by expressing domain intent, such as type DurationSeconds = number. The compiler still treats the alias as number, so it does not validate units or distinguish durations from other numbers.
Follow-up: How can stronger distinction be added? Use a branded or otherwise structurally distinctive type pattern rather than a plain primitive alias.
QWhat kinds of types can aliases name?
Type aliases can name primitives, unions, tuples, object types, and other types that would otherwise be written directly. For a plain number alias, the declaration is type Name = number;.
Follow-up: Can a type alias be generic? Yes; the documentation shows aliases with type parameters, such as type Container<T> = { value: T }.
Related
numbertype aliasesinterfacesunion typestuple typesgeneric type aliases