TypeScript Readonly and Const Assertions

TypeScript provides tools for enforcing immutability at the type level. Here's how to use them effectively.

Readonly Properties#

// Readonly property modifier
interface User {
  readonly id: number;
  name: string;
  email: string;
}

const user: User = {
  id: 1,
  name: 'John',
  email: 'john@example.com'
};

user.name = 'Jane';    // OK
user.id = 2;           // Error: Cannot assign to 'id'

// Class readonly properties
class Config {
  readonly apiUrl: string;
  readonly maxRetries: number;

  constructor(url: string, retries: number) {
    this.apiUrl = url;
    this.maxRetries = retries;
  }
}

const config = new Config('https://api.example.com', 3);
config.apiUrl = 'new-url'; // Error: Cannot assign to 'apiUrl'

Readonly<T> Utility Type#

// Make all properties readonly
interface MutableUser {
  id: number;
  name: string;
  settings: {
    theme: string;
    language: string;
  };
}

type ReadonlyUser = Readonly<MutableUser>;

const user: ReadonlyUser = {
  id: 1,
  name: 'John',
  settings: { theme: 'dark', language: 'en' }
};

user.name = 'Jane';           // Error
user.settings = {};           // Error
user.settings.theme = 'light'; // OK! Shallow readonly

// Deep readonly
type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object
    ? DeepReadonly<T[P]>
    : T[P];
};

type FullyReadonlyUser = DeepReadonly<MutableUser>;

ReadonlyArray<T>#

// Readonly array
const numbers: ReadonlyArray<number> = [1, 2, 3];
// or: readonly number[]

numbers.push(4);     // Error: Property 'push' does not exist
numbers[0] = 10;     // Error: Index signature only permits reading
numbers.length = 0;  // Error

// Allowed operations
const first = numbers[0];           // OK
const doubled = numbers.map(n => n * 2);  // OK (returns new array)
const filtered = numbers.filter(n => n > 1);  // OK

// Function parameter
function processItems(items: readonly string[]) {
  // Can't modify items
  items.push('new');  // Error
  return items.join(', ');  // OK
}

Const Assertions#

// as const makes literal types
const point = { x: 10, y: 20 } as const;
// Type: { readonly x: 10; readonly y: 20; }

point.x = 15;  // Error: Cannot assign to 'x'

// Array becomes readonly tuple
const colors = ['red', 'green', 'blue'] as const;
// Type: readonly ['red', 'green', 'blue']

colors.push('yellow');  // Error
colors[0] = 'orange';   // Error

// Literal types preserved
type Colors = typeof colors[number];
// 'red' | 'green' | 'blue'

// Without as const
const colorsNormal = ['red', 'green', 'blue'];
// Type: string[]

Object Literals with as const#

// Config object
const config = {
  api: {
    baseUrl: 'https://api.example.com',
    timeout: 5000,
  },
  features: {
    darkMode: true,
    notifications: false,
  },
} as const;

// All properties are readonly and literal types
type Config = typeof config;
// {
//   readonly api: {
//     readonly baseUrl: "https://api.example.com";
//     readonly timeout: 5000;
//   };
//   readonly features: {
//     readonly darkMode: true;
//     readonly notifications: false;
//   };
// }

// Extract literal values
type BaseUrl = typeof config.api.baseUrl;
// "https://api.example.com"

Enum-like Constants#

// Instead of enum, use as const
const Status = {
  Pending: 'pending',
  Active: 'active',
  Completed: 'completed',
} as const;

type Status = typeof Status[keyof typeof Status];
// 'pending' | 'active' | 'completed'

function updateStatus(status: Status) {
  console.log(status);
}

updateStatus(Status.Active);     // OK
updateStatus('pending');         // OK
updateStatus('invalid');         // Error

// With numeric values
const HttpStatus = {
  Ok: 200,
  NotFound: 404,
  ServerError: 500,
} as const;

type HttpStatus = typeof HttpStatus[keyof typeof HttpStatus];
// 200 | 404 | 500

Tuple Types#

// Regular array
const arr = [1, 'hello'];
// Type: (string | number)[]

// Const assertion creates tuple
const tuple = [1, 'hello'] as const;
// Type: readonly [1, 'hello']

// Explicit tuple type
const point: [number, number] = [10, 20];
point[0] = 15;  // OK, not readonly

// Readonly tuple
const readonlyPoint: readonly [number, number] = [10, 20];
readonlyPoint[0] = 15;  // Error

// Function returning tuple
function getCoordinates(): readonly [number, number] {
  return [10, 20] as const;
}

Readonly in Functions#

// Readonly parameter
function processUsers(users: readonly User[]) {
  // Can't modify the array
  users.push(newUser);     // Error
  users.sort();            // Error

  // Can read and create new arrays
  return users.filter(u => u.active);
}

// Return readonly
function getConfig(): Readonly<Config> {
  return {
    apiKey: 'secret',
    timeout: 5000,
  };
}

const config = getConfig();
config.apiKey = 'new';  // Error

// Generic readonly function
function freeze<T>(obj: T): Readonly<T> {
  return Object.freeze(obj);
}

Satisfies with as const#

// satisfies + as const for type checking with literals
const routes = {
  home: '/',
  about: '/about',
  users: '/users',
} as const satisfies Record<string, string>;

// Type preserves literal strings
type Route = typeof routes[keyof typeof routes];
// '/' | '/about' | '/users'

// Error if value doesn't match
const badRoutes = {
  home: '/',
  about: 123,  // Error: Type 'number' is not assignable to 'string'
} as const satisfies Record<string, string>;

Readonly Maps and Sets#

// ReadonlyMap
const userMap: ReadonlyMap<string, User> = new Map([
  ['1', { id: 1, name: 'John' }],
  ['2', { id: 2, name: 'Jane' }],
]);

userMap.get('1');       // OK
userMap.set('3', user); // Error: Property 'set' does not exist

// ReadonlySet
const allowedRoles: ReadonlySet<string> = new Set([
  'admin',
  'user',
  'guest',
]);

allowedRoles.has('admin');  // OK
allowedRoles.add('new');    // Error

Mutable from Readonly#

// Remove readonly modifier
type Mutable<T> = {
  -readonly [P in keyof T]: T[P];
};

interface ReadonlyUser {
  readonly id: number;
  readonly name: string;
}

type MutableUser = Mutable<ReadonlyUser>;
// { id: number; name: string; }

// Mutable array
type MutableArray<T> = T extends readonly (infer U)[]
  ? U[]
  : T;

type Numbers = MutableArray<readonly number[]>;
// number[]

Patterns and Use Cases#

// Immutable state
interface State {
  readonly users: readonly User[];
  readonly loading: boolean;
  readonly error: string | null;
}

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'ADD_USER':
      return {
        ...state,
        users: [...state.users, action.payload],
      };
    default:
      return state;
  }
}

// Builder pattern with readonly result
class ConfigBuilder {
  private config: Partial<Config> = {};

  setApiUrl(url: string): this {
    this.config.apiUrl = url;
    return this;
  }

  setTimeout(timeout: number): this {
    this.config.timeout = timeout;
    return this;
  }

  build(): Readonly<Config> {
    return this.config as Config;
  }
}

// Freeze deep objects
function deepFreeze<T extends object>(obj: T): DeepReadonly<T> {
  Object.keys(obj).forEach(key => {
    const value = (obj as any)[key];
    if (typeof value === 'object' && value !== null) {
      deepFreeze(value);
    }
  });
  return Object.freeze(obj) as DeepReadonly<T>;
}

Best Practices#

When to Use Readonly:
✓ Configuration objects
✓ Function parameters you won't modify
✓ Redux/state management
✓ Public API return types

When to Use as const:
✓ Object literal constants
✓ Array constants (enum-like)
✓ Preserving literal types
✓ Tuple creation

Patterns:
✓ Readonly for interfaces
✓ as const for values
✓ DeepReadonly for nested
✓ Mutable when needed

Avoid:
✗ Readonly on primitives (unnecessary)
✗ Over-using DeepReadonly
✗ Forgetting shallow nature
✗ Mixing mutable and readonly

TypeScript's readonly modifiers and const assertions provide compile-time immutability guarantees. Use readonly for interface properties, Readonly<T> for entire types, and as const for literal value preservation. Remember that readonly is shallow by default - use DeepReadonly for nested immutability. These tools help prevent accidental mutations and make code intent clearer.