js-data-structures

Native Data Structures (JavaScript)

Choosing a native collection

• Fixed schema / DTO / JSON: use Object (avoid Map, no JSON.stringify)
• Dynamic string-to-value dict: use Map or Object.create(null) (avoid plain {} if keys are user input)
• Non-string keys, insertion order, .size: use Map (avoid Object)
• Ordered list, index access, transform: use Array (avoid Set, no indexes)
• Unique values, fast membership: use Set (avoid Array.includes on large/dynamic sets)
• Attach data to objects without retaining them: use WeakMap (avoid Map, leaks)
• Track object presence without retaining: use WeakSet (avoid Set, leaks)
• Numeric / binary data, I/O, crypto: use TypedArray / ArrayBuffer (avoid number[] for hot binary work)
• Hot queue / deque / stack ends: do not rely on Array.shift/unshift — use a custom ring or linked structure

Complexity and code characteristics

Choose a structure for the property you need to control — not only for speed.

Big-O (typical average case; n = collection size):

• Object field access: O(1) for fixed shapes; dynamic/delete-heavy objects degrade toward dictionary mode
• Array index get/set, push/pop: O(1); includes/indexOf/splice/shift/unshift: O(n)
• Map get/set/has/delete, Set add/has/delete: amortized O(1); iteration: O(n)
• WeakMap/WeakSet get/set/has/delete: amortized O(1); no iteration
• TypedArray index get/set: O(1); grow/copy: O(n)
• Prefer the structure whose hot operation is O(1); measure before optimizing rare paths

Readability and semantics:

• Let the type state the intent: Set = unique membership; Map = keyed registry; Array = ordered sequence; plain Object = record/DTO
• Prefer a named collection over encoding the same idea in ad-hoc flags, parallel arrays, or stringly keys
• Use array methods (.map, .filter, .reduce) when they match the transform; use explicit loops when control flow or performance matters
• Avoid over-abstracting: a small static Array allowlist is clearer than a Set used once