TypeScript Record Type Patterns

The Record utility type creates object types with specific key and value types. Here's how to use it effectively.

Basic Record#

// Record<Keys, Type>
// Creates object type with keys of type Keys and values of type Type

// String keys with specific value type
type StringToNumber = Record<string, number>;

const scores: StringToNumber = {
  alice: 95,
  bob: 87,
  charlie: 92,
};

// Union of string literals as keys
type Status = 'pending' | 'active' | 'completed';
type StatusCounts = Record<Status, number>;

const counts: StatusCounts = {
  pending: 5,
  active: 10,
  completed: 25,
};
// All keys required!

Enum Keys#

enum Color {
  Red = 'red',
  Green = 'green',
  Blue = 'blue',
}

// Record with enum keys
type ColorHex = Record<Color, string>;

const colorMap: ColorHex = {
  [Color.Red]: '#ff0000',
  [Color.Green]: '#00ff00',
  [Color.Blue]: '#0000ff',
};

// All enum values must be present
// Missing one would be an error

// Access
const redHex = colorMap[Color.Red]; // '#ff0000'

Complex Value Types#

interface User {
  id: number;
  name: string;
  email: string;
}

// Record with complex values
type UserMap = Record<string, User>;

const users: UserMap = {
  'user-1': { id: 1, name: 'John', email: 'john@example.com' },
  'user-2': { id: 2, name: 'Jane', email: 'jane@example.com' },
};

// Nested records
type NestedConfig = Record<string, Record<string, string>>;

const config: NestedConfig = {
  database: {
    host: 'localhost',
    port: '5432',
  },
  cache: {
    host: 'redis',
    port: '6379',
  },
};

Mapped Type Comparison#

// Record is a built-in mapped type
// These are equivalent:

type RecordVersion = Record<'a' | 'b', number>;

type MappedVersion = {
  [K in 'a' | 'b']: number;
};

// Both result in:
// { a: number; b: number; }

// Record is simpler for basic cases
// Mapped types allow more complex transformations

Partial Record#

// All keys optional
type PartialStatusMap = Partial<Record<Status, string>>;

const partial: PartialStatusMap = {
  pending: 'Waiting',
  // active and completed are optional
};

// Or use Partial inline with Record
type OptionalUserMap = Record<string, User | undefined>;

const maybeUsers: OptionalUserMap = {
  'user-1': { id: 1, name: 'John', email: 'john@example.com' },
  'user-2': undefined,
};

Record with Index Signature#

// Record creates an index signature
type StringRecord = Record<string, unknown>;

// Same as:
interface IndexSignature {
  [key: string]: unknown;
}

// But Record is more flexible with key types
type NumberRecord = Record<number, string>;

const indexed: NumberRecord = {
  0: 'zero',
  1: 'one',
  2: 'two',
};

Type-Safe Configuration#

// Define allowed config keys
type ConfigKey = 'apiUrl' | 'timeout' | 'maxRetries' | 'debug';

// Values can be different types
type ConfigValues = {
  apiUrl: string;
  timeout: number;
  maxRetries: number;
  debug: boolean;
};

// Type-safe config object
const config: ConfigValues = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
  maxRetries: 3,
  debug: false,
};

// For uniform value types, use Record
type FeatureFlags = Record<string, boolean>;

const features: FeatureFlags = {
  darkMode: true,
  newUI: false,
  betaFeatures: true,
};

Lookup Tables#

// HTTP status codes
type HttpStatus = 200 | 201 | 400 | 401 | 404 | 500;

type StatusMessages = Record<HttpStatus, string>;

const statusMessages: StatusMessages = {
  200: 'OK',
  201: 'Created',
  400: 'Bad Request',
  401: 'Unauthorized',
  404: 'Not Found',
  500: 'Internal Server Error',
};

function getStatusMessage(code: HttpStatus): string {
  return statusMessages[code];
}

// Type-safe route handlers
type Routes = '/home' | '/about' | '/contact';
type RouteHandler = () => void;

const handlers: Record<Routes, RouteHandler> = {
  '/home': () => console.log('Home page'),
  '/about': () => console.log('About page'),
  '/contact': () => console.log('Contact page'),
};

State Machines#

// Define states
type State = 'idle' | 'loading' | 'success' | 'error';

// Define transitions
type Transitions = Record<State, State[]>;

const validTransitions: Transitions = {
  idle: ['loading'],
  loading: ['success', 'error'],
  success: ['idle', 'loading'],
  error: ['idle', 'loading'],
};

function canTransition(from: State, to: State): boolean {
  return validTransitions[from].includes(to);
}

// State handlers
type StateHandler<T> = (data: T) => void;
type StateHandlers<T> = Record<State, StateHandler<T>>;

const handlers: StateHandlers<string> = {
  idle: () => console.log('Idle'),
  loading: () => console.log('Loading...'),
  success: (data) => console.log('Success:', data),
  error: (error) => console.log('Error:', error),
};

Translation/i18n#

type Language = 'en' | 'es' | 'fr' | 'de';

type TranslationKey = 'greeting' | 'farewell' | 'thanks';

type Translations = Record<Language, Record<TranslationKey, string>>;

const translations: Translations = {
  en: {
    greeting: 'Hello',
    farewell: 'Goodbye',
    thanks: 'Thank you',
  },
  es: {
    greeting: 'Hola',
    farewell: 'Adiós',
    thanks: 'Gracias',
  },
  fr: {
    greeting: 'Bonjour',
    farewell: 'Au revoir',
    thanks: 'Merci',
  },
  de: {
    greeting: 'Hallo',
    farewell: 'Auf Wiedersehen',
    thanks: 'Danke',
  },
};

function t(lang: Language, key: TranslationKey): string {
  return translations[lang][key];
}

Event Handlers#

// DOM event types
type EventType = 'click' | 'mouseover' | 'keydown';

type EventHandler = (event: Event) => void;

type EventHandlers = Record<EventType, EventHandler>;

const handlers: EventHandlers = {
  click: (e) => console.log('Clicked', e),
  mouseover: (e) => console.log('Mouseover', e),
  keydown: (e) => console.log('Keydown', e),
};

// Or with generics
type TypedEventHandlers = {
  [K in EventType]: (event: K extends 'keydown' ? KeyboardEvent : MouseEvent) => void;
};

API Response Mapping#

// Map endpoints to response types
interface User {
  id: number;
  name: string;
}

interface Post {
  id: number;
  title: string;
}

type Endpoints = {
  '/users': User[];
  '/users/:id': User;
  '/posts': Post[];
  '/posts/:id': Post;
};

// Generic fetch function
async function fetchApi<K extends keyof Endpoints>(
  endpoint: K
): Promise<Endpoints[K]> {
  const response = await fetch(endpoint);
  return response.json();
}

// Type-safe usage
const users = await fetchApi('/users');    // User[]
const user = await fetchApi('/users/:id'); // User

Record with keyof#

interface User {
  id: number;
  name: string;
  email: string;
}

// Create record from interface keys
type UserValidation = Record<keyof User, (value: unknown) => boolean>;

const validators: UserValidation = {
  id: (v) => typeof v === 'number' && v > 0,
  name: (v) => typeof v === 'string' && v.length > 0,
  email: (v) => typeof v === 'string' && v.includes('@'),
};

// Validate user
function validateUser(user: unknown): user is User {
  if (typeof user !== 'object' || user === null) return false;

  return (Object.keys(validators) as (keyof User)[]).every(
    (key) => validators[key]((user as any)[key])
  );
}

Best Practices#

When to Use Record:
✓ Dictionary/map structures
✓ Lookup tables
✓ Configuration objects
✓ Known set of keys

Patterns:
✓ Union types as keys
✓ Enum values as keys
✓ keyof for interface keys
✓ Combine with Partial

Type Safety:
✓ All keys required by default
✓ Use Partial for optional keys
✓ Leverage autocomplete
✓ Exhaustiveness checking

Avoid:
✗ Using 'any' as key type
✗ Overcomplicating simple objects
✗ Ignoring undefined values
✗ Mixing with index signatures

Record is a powerful utility type for creating type-safe dictionaries and mappings. Use it with union types or enums for exhaustive key checking, combine with Partial for optional keys, and leverage it for configuration objects, lookup tables, and state machines. It provides better type inference and autocomplete compared to plain index signatures.