Luxar Viewer API Documentation - v2026.9.22
    Preparing search index...

    Interface MultiLevelCacheStats

    Snapshot returned by MultiLevelCachingStore.getStats(). Aggregates the L1 segmented-LRU stats, the L2 OPFS stats, network counters, per-tier demand-hit counters, cache health (validation mode + OPFS availability), and the ?clearCache invocation counter.

    Consumed by the data-loading monitor, the debug overlay, and the cache E2E suite.

    interface MultiLevelCacheStats {
        l1: CacheStats;
        l2: {
            size: number;
            count: number;
            reads: number;
            writes: number;
            misses: number;
            canceledReads: number;
            activeReads: number;
            queuedReads: number;
            maxSize?: number;
            oversizedWriteSkipped?: number;
            quotaWriteSkipped?: number;
            evictions?: number;
            writeFailures?: number;
            corruptedEntries?: number;
            metadataParseFailures?: number;
            orphanedFilesRemoved?: number;
        };
        l2WriteQueue: {
            depth: number;
            pendingBytes: number;
            inFlight: number;
            dropped: number;
            concurrency: number;
            maxDepth: number;
            maxBytes: number;
        };
        network: {
            bytesTransferred: number;
            requestCount: number;
            bandwidth: number;
            totalBytesServed: number;
            totalRequestsServed: number;
        };
        demand: { l1Hits: number; l2Hits: number; networkRequests: number };
        health: {
            validationMode: CacheValidationMode;
            lastValidatedAt: number | null;
            unvalidatedExternalDataset: boolean;
            opfsAvailable: boolean;
        };
        clearOnInitCount: number;
    }
    Index
    l1 l2 l2WriteQueue network demand health clearOnInitCount
    l1: CacheStats
    l2: {
        size: number;
        count: number;
        reads: number;
        writes: number;
        misses: number;
        canceledReads: number;
        activeReads: number;
        queuedReads: number;
        maxSize?: number;
        oversizedWriteSkipped?: number;
        quotaWriteSkipped?: number;
        evictions?: number;
        writeFailures?: number;
        corruptedEntries?: number;
        metadataParseFailures?: number;
        orphanedFilesRemoved?: number;
    }

    Type Declaration

    • size: number
    • count: number
    • reads: number
    • writes: number
    • misses: number
    • canceledReads: number

      Reads canceled before filesystem I/O; excluded from the hit-rate denominator.

    • activeReads: number
    • queuedReads: number
    • OptionalmaxSize?: number

      Configured byte budget (fixed OPFS/disk cap).

    • OptionaloversizedWriteSkipped?: number
    • OptionalquotaWriteSkipped?: number
    • Optionalevictions?: number
    • OptionalwriteFailures?: number
    • OptionalcorruptedEntries?: number
    • OptionalmetadataParseFailures?: number
    • OptionalorphanedFilesRemoved?: number
    l2WriteQueue: {
        depth: number;
        pendingBytes: number;
        inFlight: number;
        dropped: number;
        concurrency: number;
        maxDepth: number;
        maxBytes: number;
    }

    Background L2 write-queue backpressure snapshot. L2 (OPFS) writes are deferred off the fetch critical path and drained at a bounded concurrency; this exposes the queue's live depth / retained bytes / in-flight count and the cumulative count of writes dropped by either overflow policy.

    network: {
        bytesTransferred: number;
        requestCount: number;
        bandwidth: number;
        totalBytesServed: number;
        totalRequestsServed: number;
    }

    Type Declaration

    • bytesTransferred: number

      Bytes fetched over the network (L3) — excludes cache-served bytes.

    • requestCount: number

      Count of actual network fetches (L3).

    • bandwidth: number

      Current network bandwidth (bytes/sec, ~10s sliding window).

    • totalBytesServed: number

      Cumulative bytes delivered to demand callers across ALL tiers (L1 + L2 + network). Unlike bytesTransferred, this stays non-zero on a warm/cache-served reload, so the monitor's "data loaded" figure reflects real I/O even with zero network.

    • totalRequestsServed: number

      Count of demand reads served across all tiers.

    demand: { l1Hits: number; l2Hits: number; networkRequests: number }

    Per-tier demand-hit counters (user demand only — prefetch traffic is excluded). Each user-demand getResult call increments exactly one of l1Hits, l2Hits, or networkRequests. Combined with the L0 provider's stats, this lets the monitor surface an effective demand hit-rate rather than the L1-only ratio.

    health: {
        validationMode: CacheValidationMode;
        lastValidatedAt: number | null;
        unvalidatedExternalDataset: boolean;
        opfsAvailable: boolean;
    }

    Cache health snapshot. Surfaced by the data monitor status badges and debug diagnostics.

    Type Declaration

    • validationMode: CacheValidationMode

      Validation mode the dataset is using (or 'none' if external + no TTL).

    • lastValidatedAt: number | null

      Wall-clock millis at last successful validation, or null.

    • unvalidatedExternalDataset: boolean

      true when the dataset has no content_hash AND no TTL is configured — surfaced as a UI warning since the cache may be stale indefinitely.

    • opfsAvailable: boolean

      S2: true when OPFS is available and L2 is operational, or when caching is disabled (no L2 expected). false only when caching is enabled but OPFS could not be acquired — drives the opfs-unavailable status badge.

    clearOnInitCount: number

    S4: number of times ?clearCache triggered a clearAll on init for this store. Increments at most once per store lifetime today but typed as a counter so future re-init paths stay observable.

    Settings
    Member Visibility

    On This Page
    Properties