docs/objects/lookup-iterator.md

# LookupIterator Architecture

This document explains the design and functionality of the `LookupIterator` in V8, which is the central mechanism for resolving property accesses on JavaScript objects.

## Overview

The `LookupIterator` (`src/objects/lookup.h`) is a stateful iterator used to implement the ECMAScript specification's property lookup rules. It abstracts away the differences between:
*   Named properties vs. indexed elements.
*   Fast mode vs. dictionary mode objects.
*   In-object vs. out-of-object storage.
*   Prototype chain walking.
*   Special objects like JSProxies and Interceptors.

Whenever V8 needs to get, set, or delete a property and cannot do it via a fast Inline Cache (IC) hit, it falls back to the `LookupIterator`.

## The State Machine

The iterator operates as a state machine. Calling `Next()` advances the iterator to the next state or the next object in the prototype chain. States include:

*   **`NOT_FOUND`**: The property was not found. This is a terminal state.
*   **`STRING_LOOKUP_START_OBJECT`**: Initial state for lookup starting from a primitive string. Avoids wrapper object creation.
*   **`TYPED_ARRAY_INDEX_NOT_FOUND`**: Typed arrays return undefined immediately for invalid integer indices without walking the prototype chain.
*   **`ACCESS_CHECK`**: The object requires an access check (e.g., cross-origin iframe access) before proceeding.
*   **`INTERCEPTOR`**: API-level hooks for optionally handling a lookup in embedder code.
*   **`JSPROXY`**: The current holder is a `JSProxy`. The lookup must be forwarded to the proxy's handler.
*   **`ACCESSOR`**: The property is an accessor (getter/setter) defined by an `AccessorPair` or `AccessorInfo`.
*   **`DATA`**: The property was found as a data property (field or constant) in the current `holder`.
*   **`WASM_OBJECT`**: WasmGC objects are opaque in JS and appear to have no properties.
*   **`MODULE_NAMESPACE`**: The property is accessed on a deferred module namespace.
*   **`TRANSITION`**: Intermediate state during a data property write (not observed during lookup).

## Configuration

The iterator can be configured via `LookupIterator::Configuration`, which consists of bit flags and convenience combinations:

*   **`kInterceptor`**: Consult embedder interceptors.
*   **`kPrototypeChain`**: Walk the prototype chain.

Convenience combinations:
*   **`OWN_SKIP_INTERCEPTOR`**: Only look at the receiver, skip interceptors.
*   **`OWN`**: Only look at the receiver, consult interceptors. (Equivalent to `kInterceptor`).
*   **`PROTOTYPE_CHAIN_SKIP_INTERCEPTOR`**: Full chain, skip interceptors. (Equivalent to `kPrototypeChain`).
*   **`PROTOTYPE_CHAIN`**: Full chain, consult interceptors. (Equivalent to `kPrototypeChain | kInterceptor`).
*   **`DEFAULT`**: Same as `PROTOTYPE_CHAIN`.

## Deep Dive: The Lookup Process

The core logic of `LookupIterator` is implemented in `src/objects/lookup.cc`. Let's examine the key phases:

### 1. Start()
When the iterator is created, it calls `Start()`.
*   **Fast Path**: If the lookup start object is a `JSReceiver`, it reads its `Map` and calls `LookupInHolder`.
*   **Primitive Wrappers**: If the receiver is a primitive (like a string), V8 avoids creating a wrapper object if possible. For strings, it directly checks for the `"length"` property or valid index lookups within the string's length. If not found, it falls back to the prototype of the primitive (e.g., `String.prototype`).

### 2. LookupInHolder()
This method checks the current `holder` (the object currently being inspected in the chain) for the property.
*   **Fast Objects**: It searches the **Descriptor Array** of the holder's Map using a binary search or linear scan depending on size.
*   **Dictionary Objects**: It probes the hash table (Property Dictionary) directly.
*   If found, it sets the state to `DATA` or `ACCESSOR` and fills in `PropertyDetails`.

### 3. Next() and NextInternal()
If the property is not found in the current holder, `Next()` is called to move up the prototype chain.
*   **Prototype Walking**: `NextInternal` calls `NextHolder(map)` to get the prototype of the current map.
*   **Interceptors**: If a holder has an interceptor, the state becomes `INTERCEPTOR`. V8 may need to invoke embedder callbacks.
    *   **Masking Interceptors**: Can hide properties on the prototype chain.
    *   **Non-Masking Interceptors**: Cannot hide properties. If a lookup fails on the chain, V8 may restart the lookup to check non-masking interceptors.

### 4. Property Modification and Transitions
The `LookupIterator` is not just for reading; it also prepares for writes.
*   **`PrepareForDataProperty`**: Called before writing to an existing data property. It handles:
    *   **Elements Kind Transitions**: If writing a double to a SMI array, it transitions the array to `DOUBLE_ELEMENTS`.
    *   **Representation Generalization**: If writing a double to a SMI field, it triggers a map transition to generalize the field representation.
*   **`PrepareTransitionToDataProperty`**: Called when adding a *new* property. It finds or creates a new Map with the added property and sets the iterator state to `TRANSITION`.

## Elements vs. Properties

The `LookupIterator` handles both named properties and indexed elements by templating key methods with a `bool is_element` parameter.
*   For elements, it bypasses the descriptor array and goes directly to the `ElementsAccessor` of the object to check the backing store.
*   Typed arrays have special handling where out-of-bounds accesses immediately return undefined (via `TYPED_ARRAY_INDEX_NOT_FOUND` state) without walking the prototype chain.

## ConcurrentLookupIterator

V8 also provides a `ConcurrentLookupIterator` (`src/objects/lookup.h`) for concurrent accesses from a background thread. Despite the name, it is currently an all-static class and not a stateful iterator. It implements safe lookups for specific cases like own data property lookup on fixed COW arrays, strings, and property cells in global objects, handling concurrency issues defensively.

## File Structure
*   `src/objects/lookup.h`: Main header file defining `LookupIterator` and its states.
*   `src/objects/lookup.cc`: Implementation of the lookup logic, state transitions, and property accessors.