@shopify/flash-list 2.0.0-alpha.9 → 2.0.0-rc.2

package/src/recyclerview/RecyclerViewManager.ts

@@ -3,103 +3,88 @@ import ViewabilityManager from "../viewability/ViewabilityManager";
 import { ConsecutiveNumbers } from "./helpers/ConsecutiveNumbers";
 import { RVGridLayoutManagerImpl } from "./layout-managers/GridLayoutManager";
 import {
+  LayoutParams,
   RVDimension,
   RVLayoutInfo,
   RVLayoutManager,
+  SpanSizeInfo,
 } from "./layout-managers/LayoutManager";
 import { RVLinearLayoutManagerImpl } from "./layout-managers/LinearLayoutManager";
 import { RVMasonryLayoutManagerImpl } from "./layout-managers/MasonryLayoutManager";
-import { RecycleKeyManagerImpl, RecycleKeyManager } from "./RecycleKeyManager";
 import { RecyclerViewProps } from "./RecyclerViewProps";
 import {
   RVEngagedIndicesTracker,
   RVEngagedIndicesTrackerImpl,
   Velocity,
 } from "./helpers/EngagedIndicesTracker";
-
-// Abstracts layout manager, key manager and viewability manager and generates render stack (progressively on load)
+import { RenderStackManager } from "./RenderStackManager";
+// Abstracts layout manager, render stack manager and viewability manager and generates render stack (progressively on load)
 export class RecyclerViewManager<T> {
   private initialDrawBatchSize = 1;
   private engagedIndicesTracker: RVEngagedIndicesTracker;
-  private recycleKeyManager: RecycleKeyManager;
+  private renderStackManager: RenderStackManager;
   private layoutManager?: RVLayoutManager;
   // Map of index to key
-  private renderStack: Map<number, string> = new Map();
   private isFirstLayoutComplete = false;
   private hasRenderedProgressively = false;
-  private props: RecyclerViewProps<T>;
+  private propsRef: RecyclerViewProps<T>;
   private itemViewabilityManager: ViewabilityManager<T>;
-  private allocatedKeyTracker: Set<string> = new Set();
+  private _isDisposed = false;
+  private _isLayoutManagerDirty = false;
 
-  public disableRecycling = false;
   public firstItemOffset = 0;
   public ignoreScrollEvents = false;
 
+  public get isOffsetProjectionEnabled() {
+    return this.engagedIndicesTracker.enableOffsetProjection;
+  }
+
+  public get isDisposed() {
+    return this._isDisposed;
+  }
+
   constructor(props: RecyclerViewProps<T>) {
-    this.props = props;
+    this.getStableId = this.getStableId.bind(this);
+    this.getItemType = this.getItemType.bind(this);
+    this.overrideItemLayout = this.overrideItemLayout.bind(this);
+    this.propsRef = props;
     this.engagedIndicesTracker = new RVEngagedIndicesTrackerImpl();
-    this.recycleKeyManager = new RecycleKeyManagerImpl();
+    this.renderStackManager = new RenderStackManager(
+      props.maxItemsInRecyclePool
+    );
     this.itemViewabilityManager = new ViewabilityManager<T>(this as any);
   }
 
   // updates render stack based on the engaged indices which are sorted. Recycles unused keys.
-  // TODO: Write comprehensive tests for this function
   private updateRenderStack = (engagedIndices: ConsecutiveNumbers): void => {
-    // console.log("updateRenderStack", engagedIndices);
-
-    this.allocatedKeyTracker.clear();
-    const newRenderStack = new Map<number, string>();
-    for (const [index, key] of this.renderStack) {
-      if (!engagedIndices.includes(index)) {
-        this.recycleKeyManager.recycleKey(key);
-      }
-    }
-    if (this.disableRecycling) {
-      this.recycleKeyManager.clearPool();
-    }
-    for (const index of engagedIndices) {
-      const currentKey = this.renderStack.get(index);
-
-      if (
-        currentKey &&
-        !this.disableRecycling &&
-        !this.allocatedKeyTracker.has(currentKey)
-      ) {
-        this.recycleKeyManager.recycleKey(currentKey);
-      }
+    this.renderStackManager.sync(
+      this.getStableId,
+      this.getItemType,
+      engagedIndices,
+      this.getDataLength()
+    );
+  };
 
-      const newKey = this.recycleKeyManager.getKey(
-        this.getItemType(index),
-        this.getStableId(index),
-        currentKey
-      );
-      this.allocatedKeyTracker.add(newKey);
-      newRenderStack.set(index, newKey);
-    }
-    //  DANGER
-    for (const [index, key] of this.renderStack) {
-      if (
-        this.recycleKeyManager.hasKeyInPool(key) &&
-        !newRenderStack.has(index) &&
-        index < (this.props.data?.length ?? 0)
-      ) {
-        this.allocatedKeyTracker.add(key);
-        newRenderStack.set(index, key);
-      }
-    }
+  get props() {
+    return this.propsRef;
+  }
 
-    this.renderStack = newRenderStack;
-  };
+  setOffsetProjectionEnabled(value: boolean) {
+    this.engagedIndicesTracker.enableOffsetProjection = value;
+  }
 
   updateProps(props: RecyclerViewProps<T>) {
-    this.props = props;
+    this.propsRef = props;
     this.engagedIndicesTracker.drawDistance =
       props.drawDistance ?? this.engagedIndicesTracker.drawDistance;
-    if (this.props.drawDistance === 0) {
+    if (this.propsRef.drawDistance === 0) {
       this.initialDrawBatchSize = 1;
     } else {
       this.initialDrawBatchSize = (props.numColumns ?? 1) * 2;
     }
+    this.initialDrawBatchSize =
+      this.propsRef.overrideProps?.initialDrawBatchSize ??
+      this.initialDrawBatchSize;
   }
 
   /**
@@ -111,7 +96,7 @@ export class RecyclerViewManager<T> {
     offset: number,
     velocity?: Velocity
   ): ConsecutiveNumbers | undefined {
-    if (this.layoutManager) {
+    if (this.layoutManager && !this._isDisposed) {
       const engagedIndices = this.engagedIndicesTracker.updateScrollOffset(
         offset - this.firstItemOffset,
         velocity,
@@ -126,10 +111,18 @@ export class RecyclerViewManager<T> {
     return undefined;
   }
 
+  updateAverageRenderTime(time: number) {
+    this.engagedIndicesTracker.averageRenderTime = time;
+  }
+
   getIsFirstLayoutComplete() {
     return this.isFirstLayoutComplete;
   }
 
+  disableRecycling(disable: boolean) {
+    this.renderStackManager.disableRecycling = disable;
+  }
+
   getLayout(index: number) {
     if (!this.layoutManager) {
       throw new Error(
@@ -139,6 +132,17 @@ export class RecyclerViewManager<T> {
     return this.layoutManager.getLayout(index);
   }
 
+  tryGetLayout(index: number) {
+    if (
+      this.layoutManager &&
+      index >= 0 &&
+      index < this.layoutManager.getLayoutCount()
+    ) {
+      return this.layoutManager.getLayout(index);
+    }
+    return undefined;
+  }
+
   // Doesn't include header / foot etc
   getChildContainerDimensions() {
     if (!this.layoutManager) {
@@ -150,7 +154,7 @@ export class RecyclerViewManager<T> {
   }
 
   getRenderStack() {
-    return this.renderStack;
+    return this.renderStackManager.getRenderStack();
   }
 
   getWindowSize() {
@@ -170,10 +174,10 @@ export class RecyclerViewManager<T> {
   getMaxScrollOffset() {
     return Math.max(
       0,
-      (this.props.horizontal
+      (this.propsRef.horizontal
         ? this.getChildContainerDimensions().width
         : this.getChildContainerDimensions().height) -
-        (this.props.horizontal
+        (this.propsRef.horizontal
           ? this.getWindowSize().width
           : this.getWindowSize().height) +
         this.firstItemOffset
@@ -189,46 +193,43 @@ export class RecyclerViewManager<T> {
     this.engagedIndicesTracker.setScrollDirection(scrollDirection);
   }
 
+  resetVelocityCompute() {
+    this.engagedIndicesTracker.resetVelocityHistory();
+  }
+
   updateLayoutParams(windowSize: RVDimension, firstItemOffset: number) {
     this.firstItemOffset = firstItemOffset;
     const LayoutManagerClass = this.getLayoutManagerClass();
     if (
       this.layoutManager &&
       Boolean(this.layoutManager?.isHorizontal()) !==
-        Boolean(this.props.horizontal)
+        Boolean(this.propsRef.horizontal)
     ) {
       throw new Error(
         "Horizontal prop cannot be toggled, you can use a key on FlashList to recreate it."
       );
     }
+    if (this._isLayoutManagerDirty) {
+      this.layoutManager = undefined;
+      this._isLayoutManagerDirty = false;
+    }
+    const layoutManagerParams: LayoutParams = {
+      windowSize,
+      maxColumns: this.propsRef.numColumns ?? 1,
+      horizontal: Boolean(this.propsRef.horizontal),
+      optimizeItemArrangement: this.propsRef.optimizeItemArrangement ?? true,
+      overrideItemLayout: this.overrideItemLayout,
+      getItemType: this.getItemType,
+    };
     if (!(this.layoutManager instanceof LayoutManagerClass)) {
       // console.log("-----> new LayoutManagerClass");
 
       this.layoutManager = new LayoutManagerClass(
-        {
-          windowSize,
-          maxColumns: this.props.numColumns ?? 1,
-          horizontal: Boolean(this.props.horizontal),
-          optimizeItemArrangement: this.props.optimizeItemArrangement ?? true,
-          overrideItemLayout: (index, layout) => {
-            this.props?.overrideItemLayout?.(
-              layout,
-              this.props.data![index],
-              index,
-              this.props.numColumns ?? 1,
-              this.props.extraData
-            );
-          },
-        },
+        layoutManagerParams,
         this.layoutManager
       );
     } else {
-      this.layoutManager.updateLayoutParams({
-        windowSize,
-        maxColumns: this.props.numColumns ?? 1,
-        horizontal: Boolean(this.props.horizontal),
-        optimizeItemArrangement: this.props.optimizeItemArrangement ?? true,
-      });
+      this.layoutManager.updateLayoutParams(layoutManagerParams);
     }
   }
 
@@ -236,7 +237,7 @@ export class RecyclerViewManager<T> {
     return this.layoutManager !== undefined;
   }
 
-  getVisibleIndices() {
+  computeVisibleIndices() {
     if (!this.layoutManager) {
       throw new Error(
         "LayoutManager is not initialized, visible indices are not unavailable"
@@ -274,9 +275,9 @@ export class RecyclerViewManager<T> {
     // Using higher buffer for masonry to avoid missing items
     this.itemViewabilityManager.shouldListenToVisibleIndices &&
       this.itemViewabilityManager.updateViewableItems(
-        this.props.masonry
+        this.propsRef.masonry
           ? this.engagedIndicesTracker.getEngagedIndices().toArray()
-          : this.getVisibleIndices().toArray()
+          : this.computeVisibleIndices().toArray()
       );
   }
 
@@ -290,7 +291,7 @@ export class RecyclerViewManager<T> {
 
   processDataUpdate() {
     if (this.hasLayout()) {
-      this.modifyChildrenLayout([], this.props.data?.length ?? 0);
+      this.modifyChildrenLayout([], this.propsRef.data?.length ?? 0);
       if (!this.recomputeEngagedIndices()) {
         // recomputeEngagedIndices will update the render stack if there are any changes in the engaged indices.
         // It's important to update render stack so that elements are assgined right keys incase items were deleted.
@@ -304,33 +305,46 @@ export class RecyclerViewManager<T> {
   }
 
   dispose() {
+    this._isDisposed = true;
     this.itemViewabilityManager.dispose();
   }
 
+  markLayoutManagerDirty() {
+    this._isLayoutManagerDirty = true;
+  }
+
   getInitialScrollIndex() {
     return (
-      this.props.initialScrollIndex ??
-      (this.props.maintainVisibleContentPosition?.startRenderingFromBottom
+      this.propsRef.initialScrollIndex ??
+      (this.propsRef.maintainVisibleContentPosition?.startRenderingFromBottom
         ? this.getDataLength() - 1
         : undefined)
     );
   }
 
+  shouldMaintainVisibleContentPosition() {
+    // Return true if maintainVisibleContentPosition is enabled and not horizontal
+    return (
+      !this.propsRef.maintainVisibleContentPosition?.disabled &&
+      !this.propsRef.horizontal
+    );
+  }
+
   getDataLength() {
-    return this.props.data?.length ?? 0;
+    return this.propsRef.data?.length ?? 0;
   }
 
   private getLayoutManagerClass() {
     // throw errors for incompatible props
-    if (this.props.masonry && this.props.horizontal) {
+    if (this.propsRef.masonry && this.propsRef.horizontal) {
       throw new Error("Masonry and horizontal props are incompatible");
     }
-    if ((this.props.numColumns ?? 1) > 1 && this.props.horizontal) {
+    if ((this.propsRef.numColumns ?? 1) > 1 && this.propsRef.horizontal) {
       throw new Error("numColumns and horizontal props are incompatible");
     }
-    return this.props.masonry
+    return this.propsRef.masonry
       ? RVMasonryLayoutManagerImpl
-      : (this.props.numColumns ?? 1) > 1 && !this.props.horizontal
+      : (this.propsRef.numColumns ?? 1) > 1 && !this.propsRef.horizontal
       ? RVGridLayoutManagerImpl
       : RVLinearLayoutManagerImpl;
   }
@@ -344,7 +358,7 @@ export class RecyclerViewManager<T> {
     const initialItemLayout = this.layoutManager?.getLayout(
       initialScrollIndex ?? 0
     );
-    const initialItemOffset = this.props.horizontal
+    const initialItemOffset = this.propsRef.horizontal
       ? initialItemLayout?.x
       : initialItemLayout?.y;
 
@@ -369,7 +383,7 @@ export class RecyclerViewManager<T> {
     const layoutManager = this.layoutManager;
     if (layoutManager) {
       this.applyInitialScrollAdjustment();
-      const visibleIndices = this.getVisibleIndices();
+      const visibleIndices = this.computeVisibleIndices();
       // console.log("---------> visibleIndices", visibleIndices);
       this.hasRenderedProgressively = visibleIndices.every(
         (index) =>
@@ -390,7 +404,7 @@ export class RecyclerViewManager<T> {
             0,
             Math.min(
               visibleIndices.length,
-              this.renderStack.size + this.initialDrawBatchSize
+              this.getRenderStack().size + this.initialDrawBatchSize
             )
           )
         );
@@ -399,14 +413,25 @@ export class RecyclerViewManager<T> {
 
   private getItemType(index: number): string {
     return (
-      this.props.getItemType?.(this.props.data![index], index) ?? "default"
+      this.propsRef.getItemType?.(this.propsRef.data![index], index) ??
+      "default"
     ).toString();
   }
 
   private getStableId(index: number): string {
     return (
-      this.props.keyExtractor?.(this.props.data![index], index) ??
+      this.propsRef.keyExtractor?.(this.propsRef.data![index], index) ??
       index.toString()
     );
   }
+
+  private overrideItemLayout(index: number, layout: SpanSizeInfo) {
+    this.propsRef?.overrideItemLayout?.(
+      layout,
+      this.propsRef.data![index],
+      index,
+      this.propsRef.numColumns ?? 1,
+      this.propsRef.extraData
+    );
+  }
 }

package/src/recyclerview/RenderStackManager.ts

@@ -0,0 +1,291 @@
+import { ConsecutiveNumbers } from "./helpers/ConsecutiveNumbers";
+
+/**
+ * Manages the recycling of rendered items in a virtualized list.
+ * This class handles tracking, recycling, and reusing item keys to optimize
+ * rendering performance by minimizing creation/destruction of components.
+ */
+export class RenderStackManager {
+  public disableRecycling = false;
+
+  // Maximum number of items that can be in the recycle pool
+  private maxItemsInRecyclePool: number;
+
+  // Stores pools of recycled keys for each item type
+  private recycleKeyPools: Map<string, Set<string>>;
+
+  // Maps active keys to their metadata (item type and stable ID)
+  private keyMap: Map<
+    string,
+    { itemType: string; index: number; stableId: string }
+  >;
+
+  // Maps stable IDs to their corresponding keys for quick lookups
+  private stableIdMap: Map<string, string>;
+
+  // Counter for generating unique sequential keys
+  private keyCounter: number;
+
+  /**
+   * @param maxItemsInRecyclePool - Maximum number of items that can be in the recycle pool
+   */
+  constructor(maxItemsInRecyclePool: number = Number.MAX_SAFE_INTEGER) {
+    this.maxItemsInRecyclePool = maxItemsInRecyclePool;
+    this.recycleKeyPools = new Map();
+    this.keyMap = new Map();
+    this.stableIdMap = new Map();
+    this.keyCounter = 0;
+  }
+
+  /**
+   * Synchronizes the render stack with the current state of data.
+   * This method is the core orchestrator that:
+   * 1. Recycles keys for items that are no longer valid
+   * 2. Updates existing keys for items that remain visible
+   * 3. Assigns new keys for newly visible items
+   * 4. Cleans up excess items to maintain the recycling pool size
+   *
+   * @param getStableId - Function to get a stable identifier for an item at a specific index
+   * @param getItemType - Function to get the type of an item at a specific index
+   * @param engagedIndices - Collection of indices that are currently visible or engaged
+   * @param dataLength - Total length of the data set
+   */
+  public sync(
+    getStableId: (index: number) => string,
+    getItemType: (index: number) => string,
+    engagedIndices: ConsecutiveNumbers,
+    dataLength: number
+  ) {
+    this.clearRecyclePool();
+
+    // Recycle keys for items that are no longer valid or visible
+    this.keyMap.forEach((keyInfo, key) => {
+      const { index, stableId, itemType } = keyInfo;
+      if (index >= dataLength) {
+        this.recycleKey(key);
+        return;
+      }
+      if (!engagedIndices.includes(index)) {
+        this.recycleKey(key);
+        return;
+      }
+      const newStableId = getStableId(index);
+      const newItemType = getItemType(index);
+      if (stableId !== newStableId || itemType !== newItemType) {
+        this.recycleKey(key);
+      }
+    });
+
+    // First pass: process items that already have optimized keys
+    for (const index of engagedIndices) {
+      if (this.hasOptimizedKey(getStableId(index))) {
+        this.syncItem(index, getItemType(index), getStableId(index));
+      }
+    }
+
+    // Second pass: process remaining items that need new keys
+    for (const index of engagedIndices) {
+      if (!this.hasOptimizedKey(getStableId(index))) {
+        this.syncItem(index, getItemType(index), getStableId(index));
+      }
+    }
+
+    // create indices that are not in the engagedIndices and less than dataLength
+    // select only indices that are not in the engagedIndices
+    const validIndicesInPool: number[] = [];
+    for (const keyInfo of this.keyMap.values()) {
+      const index = keyInfo.index;
+      if (index < dataLength && !engagedIndices.includes(index)) {
+        validIndicesInPool.push(index);
+      }
+    }
+
+    // First pass: process items that already have optimized keys
+    for (const index of validIndicesInPool) {
+      if (this.hasOptimizedKey(getStableId(index))) {
+        this.syncItem(index, getItemType(index), getStableId(index));
+      }
+    }
+
+    for (const index of validIndicesInPool) {
+      if (!this.hasOptimizedKey(getStableId(index))) {
+        this.syncItem(index, getItemType(index), getStableId(index));
+      }
+    }
+
+    // Clean up stale items and manage the recycle pool size
+    this.cleanup(getStableId, engagedIndices, dataLength);
+  }
+
+  /**
+   * Checks if a stable ID already has an assigned key
+   */
+  private hasOptimizedKey(stableId: string): boolean {
+    return this.stableIdMap.has(stableId);
+  }
+
+  /**
+   * Cleans up stale keys and manages the recycle pool size.
+   * This ensures we don't maintain references to items that are no longer in the dataset,
+   * and limits the number of recycled items to avoid excessive memory usage.
+   */
+  private cleanup(
+    getStableId: (index: number) => string,
+    engagedIndices: ConsecutiveNumbers,
+    dataLength: number
+  ) {
+    const itemsToDelete = new Array<string>();
+
+    // Remove items that are no longer in the dataset
+    for (const [key, keyInfo] of this.keyMap.entries()) {
+      const { index, itemType, stableId } = keyInfo;
+      if (index >= dataLength || getStableId(index) !== stableId) {
+        // TODO: Find a way to reusue the key, instead of deleting it
+        this.deleteKeyFromRecyclePool(itemType, key);
+        this.stableIdMap.delete(stableId);
+        itemsToDelete.push(key);
+      }
+    }
+
+    for (const key of itemsToDelete) {
+      this.keyMap.delete(key);
+    }
+
+    // Limit the size of the recycle pool
+    const itemsRenderedForRecycling = this.keyMap.size - engagedIndices.length;
+    if (itemsRenderedForRecycling > this.maxItemsInRecyclePool) {
+      const deleteCount =
+        itemsRenderedForRecycling - this.maxItemsInRecyclePool;
+      let deleted = 0;
+
+      // Use a for loop so we can break early once we've deleted enough items
+      const entries = Array.from(this.keyMap.entries()).reverse();
+      for (let i = 0; i < entries.length && deleted < deleteCount; i++) {
+        const [key, keyInfo] = entries[i];
+        const { index, itemType, stableId } = keyInfo;
+
+        if (!engagedIndices.includes(index)) {
+          this.deleteKeyFromRecyclePool(itemType, key);
+          this.stableIdMap.delete(stableId);
+          this.keyMap.delete(key);
+          deleted++;
+        }
+      }
+    }
+  }
+
+  /**
+   * Places a key back into its type-specific recycle pool for future reuse
+   */
+  private recycleKey(key: string): void {
+    if (this.disableRecycling) {
+      return;
+    }
+    const keyInfo = this.keyMap.get(key);
+
+    if (!keyInfo) {
+      return;
+    }
+
+    const { itemType } = keyInfo;
+
+    // Add key back to its type's pool
+    const pool = this.getRecyclePoolForType(itemType);
+
+    pool.add(key);
+  }
+
+  /**
+   * Returns the current render stack containing all active keys and their metadata
+   */
+  public getRenderStack() {
+    return this.keyMap;
+  }
+
+  /**
+   * Syncs an individual item by assigning it an appropriate key.
+   * Will use an existing key if available, or generate a new one.
+   *
+   * @returns The key assigned to the item
+   */
+  private syncItem(index: number, itemType: string, stableId: string): string {
+    // Try to reuse an existing key, or get one from the recycle pool, or generate a new one
+    const newKey =
+      this.stableIdMap.get(stableId) ||
+      this.getKeyFromRecyclePool(itemType) ||
+      this.generateKey();
+
+    const keyInfo = this.keyMap.get(newKey);
+    if (keyInfo) {
+      // Update an existing key's metadata
+      this.deleteKeyFromRecyclePool(itemType, newKey);
+      this.deleteKeyFromRecyclePool(keyInfo.itemType, newKey);
+      this.stableIdMap.delete(keyInfo.stableId);
+      keyInfo.index = index;
+      keyInfo.itemType = itemType;
+      keyInfo.stableId = stableId;
+    } else {
+      // Create a new entry in the key map
+      this.keyMap.set(newKey, {
+        itemType,
+        index,
+        stableId,
+      });
+    }
+    this.stableIdMap.set(stableId, newKey);
+
+    return newKey;
+  }
+
+  /**
+   * Clears all recycled keys from the pool, effectively resetting the recycling system.
+   * This operation does not affect currently active keys.
+   */
+  private clearRecyclePool() {
+    // iterate over all pools and clear them
+    for (const pool of this.recycleKeyPools.values()) {
+      pool.clear();
+    }
+  }
+
+  /**
+   * Generates a unique sequential key using an internal counter.
+   * @returns A unique key as a string
+   */
+  private generateKey(): string {
+    return (this.keyCounter++).toString();
+  }
+
+  /**
+   * Removes a specific key from its type's recycle pool
+   */
+  private deleteKeyFromRecyclePool(itemType: string, key: string) {
+    this.recycleKeyPools.get(itemType)?.delete(key);
+  }
+
+  /**
+   * Gets or creates a recycle pool for a specific item type
+   */
+  private getRecyclePoolForType(itemType: string) {
+    let pool = this.recycleKeyPools.get(itemType);
+    if (!pool) {
+      pool = new Set();
+      this.recycleKeyPools.set(itemType, pool);
+    }
+    return pool;
+  }
+
+  /**
+   * Retrieves and removes a key from the type's recycle pool
+   * @returns A recycled key or undefined if none available
+   */
+  private getKeyFromRecyclePool(itemType: string) {
+    const pool = this.getRecyclePoolForType(itemType);
+    if (pool.size > 0) {
+      const key = pool.values().next().value;
+      pool.delete(key);
+      return key;
+    }
+    return undefined;
+  }
+}