docs/objects/fields-and-elements.md

# Field Representations and Elements Kinds

This document explains how V8 optimizes object properties and array elements by specializing their storage representation based on the types of values they contain.

## Overview

JavaScript is dynamically typed, but V8 attempts to treat objects as if they had static types to improve performance. Two key mechanisms for this are **Field Representations** (for named properties) and **Elements Kinds** (for indexed properties/array elements).

---

## Field Representations

When properties are stored in the **Descriptor Array** of a Map, V8 tracks the **Representation** of each data property. This allows V8 to avoid boxing numbers or storing full pointers when not necessary.

### Representation Types
Defined in `src/objects/property-details.h`, the main representations are:

*   **`kSmi`**: The property always holds a Small Integer (Smi). Stored directly in the object without allocation.
*   **`kDouble`**: The property holds a double-precision float. It is stored as a boxed `HeapNumber` (in-object unboxing is no longer supported). Tracking this representation allows V8 to avoid type checks. Furthermore, the boxed number is allowed to be mutated in-place on store (normally `HeapNumber`s are immutable), avoiding allocation. However, reading it requires a copy unless in optimized code that can handle raw float64 values.
    *   *Note on Size*: Fields can be double-sized (even without pointer compression), in which case they take up 8 bytes but are still referenced by a single descriptor.
*   **`kHeapObject`**: The property always holds a reference to a heap object. It can store a specific "field type" in the property descriptor (i.e., the expected `Map` of the field), or it can be a generic non-Smi `HeapObject`.
*   **`kWasmValue`**: Used for WasmObject fields. It indicates that the actual field type information must be taken from the Wasm RTT (Runtime Type) associated with the map.
*   **`kTagged`**: The most general representation. It can hold any valid JavaScript value (Smi or HeapObject).
*   **`kNone`**: Uninitialized property.

### PropertyDetails
Every property has an associated `PropertyDetails` value (a 32-bit integer) that packs:
*   **Kind**: Data or Accessor.
*   **Location**: Field (in object or property array) or Descriptor (stored in the Map itself).
*   **Constness**: Mutable or Const.
*   **Representation**: As listed above.

#### Deep Dive: PropertyDetails Bit Layout

V8 packs this information tightly into a 32-bit integer. The layout differs between **fast mode** (using descriptor arrays) and **slow mode** (dictionary properties).

**For Fast Mode Properties:**
*   **Kind** (Data vs Accessor): 1 bit
*   **Constness** (Mutable vs Const): 1 bit
*   **Attributes** (ReadOnly, DontEnum, DontDelete): 3 bits
*   **Location** (Field vs Descriptor): 1 bit
*   **Representation** (None, Smi, Double, HeapObject, Tagged): 3 bits
*   **Descriptor Pointer**: 10 bits (index in the descriptor array)
*   **Field Offset In Words**: 11 bits (offset in storage header)
*   **In-Object**: 1 bit (whether stored directly in JSObject)

**For Dictionary Mode Properties:**
*   **Kind**: 1 bit
*   **Constness**: 1 bit
*   **Attributes**: 3 bits
*   **PropertyCellType**: 3 bits (Mutable, Undefined, Constant, ConstantType, InTransition, NoCell)
*   **Dictionary Storage Index**: 23 bits (enumeration index)

This bit-packing allows V8 to pass property metadata efficiently and perform quick checks using bitmasks.

### Generalization vs. Transitions

It is important to distinguish between **Generalization** (representation changes) and **Transitions** (adding fields):
*   **Transition**: Occurs when a new property is added to an object, leading to a new Map.
*   **Generalization**: Occurs when the value assigned to an *existing* property requires a broader representation (e.g., storing a double in a field previously marked as `kSmi`).

If a property is initialized as a `Smi` and later assigned a `Double`, V8 will **generalize** the representation. This may require **Map Deprecation** (marking the old map as invalid for new objects) and creating a new map with the generalized representation. Objects with the old deprecated map are not updated immediately; instead, they are lazily migrated to the new map when they are next accessed or mutated. V8 cannot generalize "backwards" to a more specific representation.

> [!NOTE]
> A field representation change (generalization) is one of the ways to trigger a **Lazy Deoptimization** in optimized code that relied on the more specific representation. See [Deoptimization](../runtime/deoptimization.md) for details.

> Some representation changes can be done **in-place** without deprecating the map. Specifically, generalizing from `Smi`, `Double`, or `HeapObject` to `Tagged` can be done in-place. However, changing representation from `Smi` to `Double` requires deprecation because doubles might require a box allocation (e.g., `HeapNumber`).

### Slack Tracking

When V8 allocates a new object instance, it often allocates more space than currently needed for properties (in-object slack).
*   **Purpose**: To allow adding more properties without needing to resize the object or allocate an out-of-object property array.
*   **Mechanism**: V8 tracks the number of properties added to instances of a specific map. After a certain number of allocations (typically 7), V8 determines the "actual" number of properties needed and stops slack tracking.
*   **Result**: Future instances are allocated with the exact size needed, and any unused slack in existing instances is filled with a filler object (which can be reclaimed by the GC if it is at the end of the object).

---

## Property Locations: Fields vs. Descriptors

In addition to representation, V8 tracks *where* a property's value is stored, defined by `PropertyLocation` in `src/objects/property-details.h`:

*   **`kField`**: The value is stored in the object instance itself.
    *   **In-Object**: Stored directly within the `JSObject` memory layout at a fixed offset.
    *   **Out-of-Object**: Stored in a separate `PropertyArray` pointed to by the object.
*   **`kDescriptor`**: The value is stored in the **Descriptor Array** attached to the `Map`.
    *   This is an optimization for values that are constant across all instances sharing the map.
    *   **Data Constants**: If a property is assigned a value that V8 determines is constant, it can store the value directly in the descriptor array, saving space in every instance.
    *   **Accessor Constants**: Getters and setters (methods or `AccessorPair`s) are typically stored here. All instances share the same accessor function references.

By combining `PropertyKind` (Data vs. Accessor) and `PropertyLocation` (Field vs. Descriptor), V8 can represent:
*   **Data Field**: Standard property stored in the instance.
*   **Data Descriptor**: Constant property stored in the map.
*   **Accessor Descriptor**: Getter/Setter stored in the map.

---

## Elements Kinds

For indexed properties (arrays), V8 uses **Elements Kinds** to specialize the backing store (`FixedArray` or `FixedDoubleArray`) and optimize operations like `map`, `reduce`, and `forEach`.

### Common Elements Kinds
Defined in `src/objects/elements-kind.h`, the most common "fast" kinds are:

*   **`PACKED_SMI_ELEMENTS`**: Array contains only Smis and has no holes. Backed by a `FixedArray`.
*   **`HOLEY_SMI_ELEMENTS`**: Contains only Smis but has missing indices (holes).
*   **`PACKED_DOUBLE_ELEMENTS`**: Contains only unboxed doubles. Backed by a `FixedDoubleArray`. Highly efficient for numerical work.
*   **`HOLEY_DOUBLE_ELEMENTS`**: Contains unboxed doubles but has holes.
*   **`PACKED_ELEMENTS`**: Contains arbitrary JS objects (tagged values). Backed by a `FixedArray`.
*   **`HOLEY_ELEMENTS`**: Contains arbitrary JS objects and has holes.

### Other Elements Kinds
For completeness, V8 also defines elements kinds for special cases:
*   **Non-extensible, Sealed, and Frozen Elements**: Used when objects are made non-extensible, sealed, or frozen (e.g., `PACKED_FROZEN_ELEMENTS`, `HOLEY_SEALED_ELEMENTS`).
*   **Sloppy Arguments Elements**: `FAST_SLOPPY_ARGUMENTS_ELEMENTS` and `SLOW_SLOPPY_ARGUMENTS_ELEMENTS` are used for `arguments` objects in sloppy mode.
*   **String Wrapper Elements**: `FAST_STRING_WRAPPER_ELEMENTS` and `SLOW_STRING_WRAPPER_ELEMENTS` are used for string wrapper objects.

### Dictionary Mode Elements

When an array becomes very sparse or has a large number of elements, V8 may switch from a flat backing store (`FixedArray` or `FixedDoubleArray`) to a dictionary-based representation (`NumberDictionary`).
*   **`DICTIONARY_ELEMENTS`**: Elements are stored in a hash table. This saves memory for sparse arrays but makes access slower.

### Packed vs. Holey
*   **Packed**: Every index from `0` to `length-1` is initialized. Accessing elements is direct and fast.
*   **Holey**: Some indices are missing (holes). Accessing a hole requires V8 to perform a costly lookup up the prototype chain to see if a value is defined there.

### Elements Kind Transitions
Elements kinds only transition from more specific to more general through a **lattice**. Once transitioned, they rarely go back:
*   `PACKED_SMI` -> `PACKED_DOUBLE` -> `PACKED_ELEMENTS`
*   Any `PACKED` kind can transition to its `HOLEY` counterpart.

> [!NOTE]
> While conceptually elements kinds form a lattice of generalization, V8's implementation in the transition tree linearizes transitions for fast elements kinds to keep the tree simple and avoid path explosion. The linear sequence used is:
> `PACKED_SMI` -> `HOLEY_SMI` -> `PACKED_DOUBLE` -> `HOLEY_DOUBLE` -> `PACKED_ELEMENTS` -> `HOLEY_ELEMENTS`
> This means V8 may create intermediate transition maps (e.g., creating a `HOLEY_SMI` map when transitioning from `PACKED_SMI` to `PACKED_DOUBLE`) even if they are not strictly needed for the final representation.

**Examples of Transitions:**
```javascript
const array = [1, 2, 3]; // PACKED_SMI_ELEMENTS
array.push(4.56);        // Transitions to PACKED_DOUBLE_ELEMENTS
array.push('x');         // Transitions to PACKED_ELEMENTS
array[9] = 1;            // Transitions to HOLEY_ELEMENTS (indices 5-8 are holes)
```


## File Structure
*   `src/objects/property-details.h`: `Representation` and `PropertyDetails` definitions.
*   `src/objects/elements-kind.h`: `ElementsKind` enum and helper predicates.