footprintjs - v11.2.0
    Preparing search index...

    Class SequenceStore<T>

    SequenceStore — concrete, composable storage for ordered sequence data.

    Pattern: COMPOSITION primitive. Concrete class — instantiate with new SequenceStore<T>() and own it as a field on your recorder. Replaces the abstract SequenceRecorder<T> base class for the v5 "one purpose per recorder" rule: stores ARE storage; recorders ARE event handlers; consumers COMPOSE. Role: Dual-indexed append-only sequence: a flat array preserving insertion order plus a Map<runtimeStageId, T[]> for O(1) per-step lookup. Plus a precomputed range index for time- travel scrubbing.

    import { SequenceStore } from 'footprintjs/trace';
    import type { ScopeRecorder, ReadEvent, WriteEvent } from 'footprintjs';

    interface AuditEntry {
      runtimeStageId?: string;
      type: 'read' | 'write' | 'decision';
      detail: string;
    }

    // ONE PURPOSE: scope-event handler. Storage is composed in.
    class AuditRecorder implements ScopeRecorder {
      readonly id = 'audit';
      private readonly store = new SequenceStore<AuditEntry>();

      onRead(event: ReadEvent) {
        this.store.push({
          runtimeStageId: event.runtimeStageId,
          type: 'read',
          detail: event.key,
        });
      }
      onWrite(event: WriteEvent) {
        this.store.push({
          runtimeStageId: event.runtimeStageId,
          type: 'write',
          detail: event.key,
        });
      }

      getAudit() { return this.store.getAll(); }
      getAuditUpTo(ids: ReadonlySet<string>) {
        return this.store.getEntriesUpTo(ids);
      }

      clear() { this.store.clear(); }
    }

    Contrast with KeyedStore<T>: SequenceStore stores 1:N entries per runtimeStageId in insertion order. Use KeyedStore for 1:1 (one record per step — token counts, metric snapshots).

    Type Parameters

    • T extends { runtimeStageId?: string }
    Index
    constructor
    keyCount size
    accumulate aggregate clear forEach getAll getByKey getEntriesUpTo getEntryRanges push

    • Type Parameters

      • T extends { runtimeStageId?: string }

      Returns SequenceStore<T>

    • Reduce entries, optionally filtered by a set of runtimeStageIds. For time-travel progressive view: pass the runtimeStageIds visible at the current slider position. Entries without runtimeStageId (structural markers) are excluded when keys are provided. Without keys, reduces all entries (same as aggregate).

      Type Parameters

      • R

      Parameters

      • fn: (acc: R, entry: T) => R
      • initial: R
      • Optionalkeys: ReadonlySet<string>

      Returns R

    • Reduce ALL entries to a single value. For dashboards, totals, summaries.

      Type Parameters

      • R

      Parameters

      • fn: (acc: R, entry: T) => R
      • initial: R

      Returns R

    • Clear all stored data. Recorders typically call this from their own clear() method, which the executor invokes before each run.

      Returns void

    • Zero-copy iteration. Avoids the getAll() spread when the caller just needs to walk the entries (e.g., aggregating, rendering).

      Parameters

      • fn: (entry: T) => void

      Returns void

    • O(1) lookup: all entries for a specific execution step. Returns a copy.

      Parameters

      • runtimeStageId: string

      Returns T[]

    • Progressive reveal: entries whose runtimeStageId is in the visible set. Preserves insertion order. Entries without runtimeStageId (structural markers) are buffered and included only when surrounded by visible steps on both sides — trailing markers after the last visible step are discarded.

      Parameters

      • visibleIds: ReadonlySet<string>

      Returns T[]

    • Pre-built range index: runtimeStageId → half-open [firstIdx, endIdx) range in the entries array. Maintained during push() — no rebuild needed. Use for O(1) per-step lookups during time-travel scrubbing. endIdx includes trailing keyless entries (structural markers following a step).

      Returns ReadonlyMap<string, { endIdx: number; firstIdx: number }>

    • Append an entry to both the ordered sequence, keyed index, and range index. All three reference the SAME entry object — no duplication.

      Parameters

      • entry: T

      Returns void

    Settings
    Member Visibility

    On This Page
    Constructors
    Accessors
    Methods