Rustacean

Using Type Aliases as Newtypes

5 min read

Using Type Aliases as Newtypes

Using a type alias when you need a distinct domain type is a footgun because aliases are synonyms, not wrappers.

The mistake

The mistake is writing type UserId = u64;, type Meters = u32;, or type Dollars = i64; and expecting the compiler to prevent accidental mixing with plain numbers or other aliases. Rust will not do that. The alias and the original type are the same type.

This often starts as harmless documentation and later becomes a bug when two aliases share the same underlying representation. For example, UserId and OrderId might both be u64, so the compiler accepts passing one where the other is expected.

Aliases are good for reducing repetition. They are the wrong tool for invariants, units, validation, or API boundaries.

Why it happens

The keyword type creates a synonym. It does not create a constructor, private field, separate trait implementation set, or conversion step. All methods and trait implementations of the underlying type remain available exactly as before.

The correct alternative is Newtype Pattern. A single-field tuple struct creates a distinct type while keeping runtime overhead negligible in normal optimized code. It also gives you a place to validate inputs, implement traits, and decide which operations are allowed.

This antipattern is especially easy to miss because the code looks more documented after the alias is introduced. type Dollars = i64 communicates intent to humans, but the compiler still sees i64. If a second alias type Cents = i64 appears later, both aliases silently interoperate with each other and with every plain i64.

Newtypes also change trait coherence. An alias cannot receive a separate Display, Serialize, Add, or validation API from the underlying type. A wrapper can, because it is a local nominal type.

Example

type UserIdAlias = u64;
 
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
struct UserId(u64);
 
fn load_alias(id: UserIdAlias) -> String {
    format!("alias user {id}")
}
 
fn load_newtype(id: UserId) -> String {
    format!("newtype user {}", id.0)
}
 
fn main() {
    let order_id: u64 = 99;
 
    assert_eq!(load_alias(order_id), "alias user 99");
 
    let user_id = UserId(99);
    assert_eq!(load_newtype(user_id), "newtype user 99");
    // load_newtype(order_id); // does not compile: expected UserId, found u64
}

More realistic example

type AccountIdAlias = u64;
type TenantIdAlias = u64;
 
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
struct AccountId(u64);
 
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
struct TenantId(u64);
 
fn load_account_for_tenant_alias(account: AccountIdAlias, tenant: TenantIdAlias) -> String {
    format!("account {account} in tenant {tenant}")
}
 
fn load_account_for_tenant(account: AccountId, tenant: TenantId) -> String {
    format!("account {} in tenant {}", account.0, tenant.0)
}
 
fn main() {
    let account: AccountIdAlias = 10;
    let tenant: TenantIdAlias = 20;
 
    let swapped = load_account_for_tenant_alias(tenant, account);
    assert_eq!(swapped, "account 20 in tenant 10");
 
    let account = AccountId(10);
    let tenant = TenantId(20);
    assert_eq!(load_account_for_tenant(account, tenant), "account 10 in tenant 20");
    // load_account_for_tenant(tenant, account); // error[E0308]: arguments to this function are incorrect
}

The alias version compiles with swapped arguments. The newtype version turns the same mistake into a compiler error.

Common errors

The dangerous part is often the absence of an error:

type Meters = u32;
type Seconds = u32;
 
fn speed(distance: Meters, time: Seconds) -> u32 {
    distance / time
}
 
fn main() {
    let seconds: Seconds = 5;
    let meters: Meters = 100;
 
    assert_eq!(speed(seconds, meters), 0); // compiles, but the arguments are swapped
}

Fix it with distinct wrappers:

struct Meters(u32);
struct Seconds(u32);
 
fn speed(distance: Meters, time: Seconds) -> u32 {
    distance.0 / time.0
}
 
fn main() {
    let seconds = Seconds(5);
    let meters = Meters(100);
 
    assert_eq!(speed(meters, seconds), 20);
    // speed(seconds, meters);
    // error[E0308]: arguments to this function are incorrect
}

Another symptom is trying to implement domain traits for the alias:

type Dollars = i64;
 
// impl std::fmt::Display for Dollars { ... }
// error[E0117]: only traits defined in the current crate can be implemented for primitive types

The fix is struct Dollars(i64);, plus explicit constructors and trait impls.

Best practice

  • ✅ Use Type Aliases for repeated shapes such as Result<T, Error> or boxed callbacks.
  • ✅ Use Newtype Pattern for units, IDs, validated strings, permissions, and domain-specific numbers.
  • ✅ Keep newtype fields private when construction must enforce invariants.
  • ✅ Add explicit conversions so boundary crossings are visible in code review.
  • ✅ Treat aliases as documentation and ergonomics only; treat wrappers as type-safety boundaries.
  • ✅ Convert aliases to newtypes early when a value crosses module, crate, or security boundaries.

Pitfalls

  • ⚠️ Do not rely on alias names for type safety; the compiler erases the distinction.
  • ⚠️ Do not implement domain behavior as free functions over primitive aliases if a newtype can make invalid states harder to express.
  • ⚠️ Avoid overusing aliases in public APIs where they obscure the real ownership, allocation, or error type.
  • ⚠️ Do not wait until two aliases share the same primitive before wrapping; the bug often appears when a second concept is added later.
  • ⚠️ Avoid exposing pub type UserId = u64 from a crate if you may later need validation or custom trait behavior; changing to a newtype is a breaking API change.

See also

Type Aliases · Newtype Pattern · Result Type Aliases · Operator Overloading · Custom Error Types · Ownership · Fully Qualified Syntax · Copy and Clone · Advanced Types & Features

Sources

Graph View

Backlinks