# TypeScript Record vs Map: Choosing the Right Structure When Types Matter Most TypeScript data structure problems stem from conflating compile-time shape validation with runtime key management. Teams reach for `Record` when they need predictable property access and reach for `Map` when keys arrive dynamically. The distinction matters because choosing the wrong structure introduces silent failures that types cannot catch. The failure mode appears when developers treat `Record` as a general-purpose key-value store. A configuration object with known string keys works perfectly as a `Record`. The compiler enforces exhaustiveness checks, object spread works as expected, and JSON serialization is trivial. But when those keys come from user input or API responses, the `Record` type system breaks down. TypeScript assumes the key exists, but at runtime it returns `undefined`. The application crashes or silently corrupts data. ```mermaid flowchart LR A("User input key") --> B("Record access") B --> C("Compiler assumes key exists") C --> D("Runtime returns undefined") D --> E("Silent failure or crash") style E stroke:#ef4444,fill:#450a0a,color:#fca5a5 ``` The correct approach recognizes that `Record` and `Map` solve different problems. `Record` enforces a static schema where the compiler validates every key access. `Map` provides runtime guarantees for dynamic keys with methods that make absence explicit. When keys are known at compile time and the shape rarely changes, `Record` prevents entire categories of bugs. When keys arrive at runtime or the structure mutates frequently, `Map` prevents the exact failures that `Record` types hide. ```mermaid flowchart LR A("User input key") --> B("Map.get(key)") B --> C("Returns value | undefined") C --> D("Developer handles absence") D --> E("Safe fallback or error") style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` ## Key Takeaways - `Record` enforces compile-time key validation but assumes all keys exist at runtime, leading to silent `undefined` access bugs when keys are dynamic. - `Map` provides runtime guarantees for key existence through explicit `.has()` and `.get()` methods, preventing silent failures with dynamic data. - Static configuration objects with known keys benefit from `Record` because the compiler enforces exhaustiveness and enables object spread operations. - Cache layers and user-driven data structures require `Map` because keys arrive unpredictably and frequent additions/deletions demand efficient runtime operations. - Converting between structures is straightforward but each direction loses critical guarantees, `Record` to `Map` loses compile-time validation, `Map` to `Record` loses runtime safety. ## When Record Shines: Compile-Time Keys and Static Shapes `Record` enforces type safety when the set of keys is known before runtime. The compiler validates that every key access matches the declared type and catches typos during development. This structure works best for configuration objects, API response shapes, and any data where the schema stays fixed. A configuration object demonstrates the pattern. An application defines feature flags as a `Record` where `FeatureName` is a union of string literals. The compiler rejects access to undefined features and enforces exhaustiveness when iterating over all flags. Teams cannot accidentally check a non-existent flag or forget to handle a newly added feature. ```mermaid flowchart TD A("FeatureName union type") --> B("Record declaration") B --> C("Compiler validates key access") C --> D("Exhaustiveness check enforced") D --> E("Type-safe feature flags") style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style C stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px ``` The type system catches errors before they reach production: ```typescript type FeatureName = 'darkMode' | 'analytics' | 'experimental'; interface FeatureConfig { enabled: boolean; rolloutPercentage: number; } const features: Record = { darkMode: { enabled: true, rolloutPercentage: 100 }, analytics: { enabled: false, rolloutPercentage: 0 }, experimental: { enabled: true, rolloutPercentage: 10 }, }; // Compiler error: Property 'invalidFeature' does not exist const invalid = features.invalidFeature; // Exhaustiveness check forces handling all features type FeatureCheck = { [K in FeatureName]: (config: FeatureConfig) => void; }; ``` The JSON serialization advantage matters for persistence and network transport. `Record` is a plain JavaScript object that serializes directly with `JSON.stringify`. No custom serialization logic or prototype pollution concerns. Deserialization produces the same structure with the same prototype chain. Object spread and destructuring work naturally with `Record`. Developers merge configurations with `{ ...defaults, ...overrides }` and extract specific features with `const { darkMode, analytics } = features`. These operations fail or require manual iteration with `Map`. The limitation appears when keys become unpredictable. A user ID lookup table defined as `Record` compiles without warnings but crashes at runtime when accessing a non-existent ID. The type system cannot verify that every possible string key has a corresponding value. This is where `Map` provides safety that types cannot. ## When Map Is Superior: Runtime Keys and Frequent Mutations `Map` provides runtime guarantees that static types cannot enforce. The `.has()` method returns an explicit boolean for key existence, and `.get()` returns `undefined` for missing keys without assuming they exist. This structure prevents the silent failures that plague `Record` when keys arrive dynamically. Cache implementations demonstrate the pattern. A response cache stores fetch results by URL, but the set of cached URLs grows and shrinks during application lifetime. Using `Record` requires developers to remember that `cache[url]` might be `undefined` despite the type signature. Using `Map` makes absence explicit through the API. ```mermaid flowchart TD A("Dynamic cache keys") --> B("Map.set during fetch") B --> C("Map.has checks existence") C --> D{"Key exists?"} D -->|Yes| E("Map.get returns value") D -->|No| F("Map.get returns undefined") E --> G("Type-safe cache hit") F --> H("Explicit cache miss") style G stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style H stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style C stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px ``` The difference in iteration matters for performance. `Map` provides `.forEach()`, `.keys()`, `.values()`, and `.entries()` methods that iterate in insertion order. Developers iterate without `Object.keys()` or prototype chain concerns. Clearing all entries takes a single `.clear()` call instead of iterating and deleting properties. ```typescript class ResponseCache { private cache = new Map(); private maxSize = 100; set(url: string, response: Response): void { if (this.cache.size >= this.maxSize) { const firstKey = this.cache.keys().next().value; this.cache.delete(firstKey); } this.cache.set(url, response); } get(url: string): Response | undefined { return this.cache.get(url); } has(url: string): boolean { return this.cache.has(url); } clear(): void { this.cache.clear(); } } ``` The size property provides an O(1) count of entries. `Record` requires `Object.keys(record).length` which iterates every property. For structures that check size frequently, this performance difference compounds. Non-string keys unlock patterns that `Record` cannot support. `Map` accepts objects, symbols, and numbers as keys. A component instance cache keyed by DOM elements or a dependency graph keyed by class constructors requires `Map`. Attempting these patterns with `Record` forces key serialization that loses identity semantics. The prototype pollution protection matters for security-sensitive applications. `Record` inherits from `Object.prototype`, so accessing `record.toString` or `record.hasOwnProperty` returns inherited methods instead of stored values. `Map` has no prototype chain issues because keys and methods occupy separate namespaces. ## Type Safety Patterns: Record vs Map in Practice The type system enforces different guarantees depending on structure choice. `Record` provides compile-time exhaustiveness checks for union types but assumes keys exist at runtime. `Map` provides runtime existence checks but loses compile-time validation of key membership. A strict configuration pattern combines both structures. The application defines a `Record` for the canonical configuration shape and uses `Map` for runtime overrides. This approach preserves compile-time validation while supporting dynamic keys. ```typescript type ConfigKey = 'apiUrl' | 'timeout' | 'retries'; interface ConfigValue { value: string | number; source: 'default' | 'env' | 'runtime'; } const defaultConfig: Record = { apiUrl: { value: 'https://api.example.com', source: 'default' }, timeout: { value: 5000, source: 'default' }, retries: { value: 3, source: 'default' }, }; class ConfigManager { private overrides = new Map(); get(key: K): ConfigValue { // Check runtime overrides first const override = this.overrides.get(key); if (override) return override; // Fall back to compile-time validated defaults return defaultConfig[key]; } setOverride(key: string, value: ConfigValue): void { this.overrides.set(key, value); } clearOverrides(): void { this.overrides.clear(); } } ``` The discriminated union pattern strengthens type safety for heterogeneous values. Instead of `Record`, developers define a union of specific key-value pairs. This preserves type information for each key while maintaining the `Record` structure. ```typescript type ConfigEntry = | { key: 'apiUrl'; value: string } | { key: 'timeout'; value: number } | { key: 'retries'; value: number }; type Config = { [K in ConfigEntry['key']]: Extract['value']; }; const config: Config = { apiUrl: 'https://api.example.com', timeout: 5000, retries: 3, }; ``` The mapped type ensures that each key receives its corresponding value type. Assigning `config.timeout = "5000"` produces a compiler error because the type system knows `timeout` requires a number. For structures with optional keys, `Record` and `Map` diverge further. `Record` makes every value possibly undefined but provides no runtime existence check. `Map` guarantees that retrieved values are either `T` or explicitly `undefined` from `.get()`. ## Performance Comparison: Iteration, Lookup, and Memory Performance characteristics differ between `Record` and `Map` in ways that matter for large datasets and frequent operations. Lookup performance favors `Record` for small key sets and `Map` for large or dynamically changing collections. Iteration performance strongly favors `Map`. Memory overhead depends on key types and mutation frequency. ```mermaid flowchart LR subgraph Record["Record performance"] A("Small static keys") --> B("Fast property access") B --> C("Slow iteration") C --> D("Minimal memory overhead") end subgraph Map["Map performance"] E("Large dynamic keys") --> F("Hash-based lookup") F --> G("Fast iteration") G --> H("Higher memory overhead") end style B stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style G stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style C stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style H stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 ``` Lookup performance for `Record` relies on V8's hidden classes and inline caches. When the key set stays fixed and property access patterns repeat, the engine optimizes property access to near-native speed. Adding or deleting properties invalidates these optimizations and forces slower dictionary mode access. `Map` uses a hash table implementation that maintains consistent O(1) lookup regardless of mutation frequency. For applications that add and remove keys frequently, `Map` avoids the performance cliffs that come from transitioning between optimized and dictionary mode in plain objects. Iteration performance strongly favors `Map` because it maintains insertion order natively. Iterating a `Record` requires `Object.keys()`, `Object.values()`, or `Object.entries()`, each allocating a new array and iterating the prototype chain. `Map` provides iterator methods that produce values directly without intermediate allocations. ```typescript // Record iteration allocates intermediate arrays const recordKeys = Object.keys(record); for (const key of recordKeys) { const value = record[key]; } // Map iteration uses native iterators for (const [key, value] of map) { // Direct access without array allocation } ``` Memory overhead measurements show that `Map` consumes more memory per entry than `Record` for small datasets. The hash table structure and iterator support add bookkeeping overhead. For datasets under 100 entries, `Record` uses 20-30% less memory. Beyond 1000 entries, the difference becomes negligible as the relative overhead shrinks. Deletion performance matters for cache implementations and other structures with frequent turnover. Deleting a property from a `Record` with the `delete` operator deoptimizes the object and forces it into dictionary mode. `Map.delete()` maintains consistent performance because the hash table structure expects deletions. The size property difference affects applications that track collection length. `Map.size` reads a maintained counter in O(1) time. Computing `Object.keys(record).length` iterates all enumerable properties, making it O(n). For applications that check size in hot code paths, this difference compounds. ## Real-World Use Cases: Configuration Objects vs Cache Layers Configuration objects with known keys benefit from `Record` because the compiler enforces schema adherence and enables type-safe access. A feature flag system defines all flags as a union type, uses `Record` to map flags to configuration, and gains exhaustiveness checking when adding new flags. ```typescript type FeatureFlag = | 'enableBetaFeatures' | 'useNewPaymentFlow' | 'showExperimentalUI'; interface FlagConfig { enabled: boolean; allowedRoles: string[]; rolloutPercentage: number; } const featureFlags: Record = { enableBetaFeatures: { enabled: true, allowedRoles: ['admin', 'beta-tester'], rolloutPercentage: 100, }, useNewPaymentFlow: { enabled: false, allowedRoles: ['admin'], rolloutPercentage: 0, }, showExperimentalUI: { enabled: true, allowedRoles: ['admin'], rolloutPercentage: 25, }, }; function isFlagEnabled( flag: FeatureFlag, userRole: string, userId: string ): boolean { const config = featureFlags[flag]; if (!config.enabled) return false; if (!config.allowedRoles.includes(userRole)) return false; const userHash = hashUserId(userId); return userHash % 100 < config.rolloutPercentage; } ``` Cache layers with dynamic keys require `Map` because keys arrive from runtime data and the structure mutates frequently. A request cache stores responses by URL but cannot predict which URLs will be accessed. The cache implementation needs explicit existence checks and efficient deletion for eviction. ```mermaid flowchart LR A("Incoming request") --> B{"Cache.has(url)?"} B -->|Yes| C("Return cached response") B -->|No| D("Fetch from server") D --> E("Store in cache") E --> F{"Cache size > limit?"} F -->|Yes| G("Evict oldest entry") F -->|No| H("Return response") G --> H style C stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style G stroke:#7c9cf0,fill:#142544,color:#eaf2ff style B stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px ``` ```typescript interface CacheEntry { value: T; timestamp: number; hits: number; } class LRUCache { private cache = new Map>(); private maxSize: number; private maxAge: number; constructor(maxSize: number, maxAge: number) { this.maxSize = maxSize; this.maxAge = maxAge; } get(key: string): T | undefined { const entry = this.cache.get(key); if (!entry) return undefined; const age = Date.now() - entry.timestamp; if (age > this.maxAge) { this.cache.delete(key); return undefined; } entry.hits++; this.cache.delete(key); this.cache.set(key, entry); return entry.value; } set(key: string, value: T): void { if (this.cache.size >= this.maxSize) { const firstKey = this.cache.keys().next().value; this.cache.delete(firstKey); } this.cache.set(key, { value, timestamp: Date.now(), hits: 0, }); } clear(): void { this.cache.clear(); } } ``` The cache implementation relies on `Map` features that `Record` cannot provide. Moving the entry to the end of insertion order after each access maintains LRU semantics. Checking size with `.size` instead of `Object.keys().length` keeps the hot path fast. Deleting the oldest entry with a single `.delete()` call avoids deoptimizing the structure. Event emitter implementations demonstrate another case where `Map` prevents bugs. An event system stores listener arrays by event name, but event names come from application code at runtime. Using `Record` assumes every event name has a listener array, leading to `undefined` errors when emitting unregistered events. ```typescript class EventEmitter { private listeners = new Map>(); on(event: string, listener: Function): () => void { if (!this.listeners.has(event)) { this.listeners.set(event, new Set()); } this.listeners.get(event)!.add(listener); return () => this.off(event, listener); } off(event: string, listener: Function): void { const eventListeners = this.listeners.get(event); if (eventListeners) { eventListeners.delete(listener); if (eventListeners.size === 0) { this.listeners.delete(event); } } } emit(event: string, ...args: unknown[]): void { const eventListeners = this.listeners.get(event); if (eventListeners) { eventListeners.forEach((listener) => listener(...args)); } } } ``` The explicit `.has()` check prevents the common error of iterating a `undefined` array. The `.get()` method returns `undefined` when no listeners exist, making absence part of the API contract rather than a runtime surprise. ## Migration Patterns: Converting Between Record and Map Converting between `Record` and `Map` requires understanding what guarantees each structure provides and what the conversion loses. Moving from `Record` to `Map` sacrifices compile-time key validation but gains runtime safety. Moving from `Map` to `Record` sacrifices runtime guarantees but enables JSON serialization and object spread. Converting `Record` to `Map` preserves data but loses type information about specific keys. The type system cannot validate that a particular key exists in the `Map` because the key set becomes unbounded. This conversion makes sense when adding dynamic keys to a previously static structure. ```typescript type ConfigKey = 'apiUrl' | 'timeout' | 'retries'; const staticConfig: Record = { apiUrl: 'https://api.example.com', timeout: 5000, retries: 3, }; // Convert to Map for runtime additions const dynamicConfig = new Map(Object.entries(staticConfig)); // Add runtime keys that would not compile with Record dynamicConfig.set('customHeader', 'Bearer token'); dynamicConfig.set('debugMode', true); ``` Converting `Map` to `Record` requires runtime validation that the resulting object matches the expected type. The type system cannot verify that every required key exists in the `Map`, so developers must check explicitly or accept a partial type. ```typescript function mapToRecord( map: Map, requiredKeys: K[] ): Record | null { const record = Object.fromEntries(map) as Record; for (const key of requiredKeys) { if (!(key in record)) { return null; } } return record; } const userMap = new Map([ ['id', '123'], ['name', 'Alice'], ['email', 'alice@example.com'], ]); type User = { id: string; name: string; email: string }; const userRecord = mapToRecord(userMap, ['id', 'name', 'email']) as Record; ``` The conversion highlights the fundamental difference between structures. `Record` assumes keys exist and provides compile-time validation. `Map` makes existence a runtime question and provides methods to answer it. Converting between them moves the validation boundary but cannot eliminate the need for validation. A hybrid approach uses `Record` for core schema and `Map` for extensions. An API response type defines required fields as `Record` and optional metadata as `Map`. This pattern preserves type safety for known fields while supporting arbitrary metadata. ```typescript interface APIResponse { data: T; metadata: Map; headers: Record; } function createResponse(data: T): APIResponse { return { data, metadata: new Map(), headers: { 'content-type': 'application/json', 'cache-control': 'no-cache', }, }; } ``` The headers field uses `Record` because HTTP headers have known names and string values. The metadata field uses `Map` because applications attach arbitrary debugging information or tracing data that cannot be typed statically. ## Frequently Asked Questions ### When should developers prefer Record over Map in TypeScript? Developers should prefer `Record` when the key set is known at compile time and rarely changes. Configuration objects, API response types, and lookup tables with fixed keys benefit from compile-time validation and JSON serialization support that `Record` provides. ### Does Map provide better performance than Record for large datasets? `Map` provides better iteration and deletion performance regardless of size, and maintains consistent lookup performance for frequently mutated collections. For static collections under 100 entries, `Record` uses less memory, but the difference becomes negligible at scale. ### How do developers safely access Record values when keys might not exist? Developers must use optional chaining (`record?.[key]`) or explicit undefined checks (`if (key in record)`) when accessing `Record` values with dynamic keys. The type system cannot enforce existence, so runtime checks are required. For genuinely dynamic keys, `Map` provides safer defaults through explicit `.has()` and `.get()` methods. ### Can Map keys be non-string types in TypeScript? Yes, `Map` accepts objects, symbols, numbers, and any other type as keys. This enables patterns like caching by DOM element or indexing by class constructor that `Record` cannot support. The key comparison uses reference equality for objects rather than string serialization. ### What happens to type safety when converting between Record and Map? Converting `Record` to `Map` loses compile-time validation of specific keys but preserves runtime data. Converting `Map` to `Record` requires runtime validation to ensure required keys exist because the type system cannot verify `Map` contents. Both conversions require explicit handling of the safety-performance tradeoff. ## Choosing the Right Structure for Your TypeScript Project The choice between `Record` and `Map` determines whether bugs surface at compile time or runtime. Teams building configuration systems, API clients, and type-safe state machines benefit from `Record` because the compiler catches errors before deployment. Teams building caches, event systems, and dynamic indexes benefit from `Map` because runtime guarantees prevent the silent failures that types cannot see. Start with `Record` when the key set is known and the structure rarely changes. The compile-time validation catches typos, enforces exhaustiveness, and enables refactoring tools to update every access site. Move to `Map` when keys become unpredictable or the structure mutates frequently. The explicit existence checks and efficient mutations prevent the crashes that plague `Record` with dynamic data. That covers the essential patterns for choosing between `Record` and `Map` in TypeScript. Apply these principles in production and the difference will be immediate. Related patterns appear in [TypeScript generic constraints with extends and keyof](/typescript-generic-constraints-extends-keyof) for constraining key types and [TypeScript mapped types guide](/typescript-mapped-types-guide) for transforming `Record` structures.

Posts tagged “record”

TypeScript Record<K, V> vs Map<K, V>: Choosing the Right Structure When Types Matter