mise API - v0.0.0
    Preparing search index...

    Class ListCache

    Singleton cache for directory listings with TTL and dirty tracking.

    Generic cache that stores any data type keyed by path. Eliminates redundant API calls by caching directory contents after ls operations.

    Enhanced features:

    • TTL-based expiration: Different paths have different TTLs
    • Dirty flag tracking: Local mutations mark cache as needing refresh
    • LRU eviction: Bounded memory usage
    • Optimistic serving: Serve stale cache immediately, refresh in background

    Usage:

    const cache = listCache_get();

    // Check cache (returns CacheResult with freshness info)
    const cached = cache.cache_get("/PUBLIC");
    if (cached) {
      console.log(cached.data);  // Show immediately
      if (!cached.fresh) {
        console.log('Refreshing...');
        // Fetch fresh data in background
      }
    }

    // Store data
    cache.cache_set("/PUBLIC", items);

    // Mark dirty after mutation
    cache.cache_markDirty("/home/user");

    // Optimistic update
    cache.cache_update("/home/user", (items) => items.filter(i => i.name !== 'deleted.txt'));
    Index
    cache_get cache_invalidate cache_invalidateTree cache_markDirty cache_set cache_update changeListener_add cwd_update folder_get folder_set folders_count paths_get snapshot_create snapshot_restore stamp_take stats_get stats_reset instance_get

    • Invalidates cache for a specific path or clears entire cache. Called by file operations that modify directory contents (mkdir, touch, rm, upload).

      Parameters

      • Optionalpath: string

        Optional specific path to invalidate. If omitted, clears entire cache.

      Returns void

    • Invalidates a path and every cached listing beneath it. Called by operations that remove or replace an entire directory tree (rm -r, a directory re-upload): nested listings cached before the mutation would otherwise serve the old tree's contents until their TTL expires, with no refresh hint.

      Parameters

      • path: string

        Root of the subtree to invalidate. The entry for the path itself is removed along with all entries under path + '/'.

      Returns void

    • Stores data in cache with optional TTL override.

      Type Parameters

      • T = unknown

      Parameters

      • path: string

        The path to cache.

      • data: T

        The data to cache.

      • Optionaloptions: CacheOptions

        Optional TTL and dirty flag.

      Returns void

    • Optimistically updates cache after a mutation. Example: After rm, remove item from parent directory cache.

      Type Parameters

      • T = unknown

      Parameters

      • path: string

        The parent directory path.

      • updater: (data: T) => T

        Function to transform cached data.

      Returns void

    • Registers a callback for checkpoint-worthy mutations (set, update, dirty, invalidate).

      Parameters

      • listener: () => void

        Callback invoked after a mutation.

      Returns () => void

      Function that unregisters the callback.

    • Parameters

      • _newCwd: string

        Ignored.

      Returns void

      Use cache without cwd tracking. Cache persists across navigation. This method is kept for backward compatibility but does nothing.

    • The folder record kept for a path, while its listing's TTL holds.

      Parameters

      • path: string

        The folder's path.

      Returns Promise<unknown> | null

      The lookup's promise, or null when none is kept or it expired.

    • Keeps a folder lookup for a path, under the listing's own TTL (one clock). A lookup that rejects is forgotten as it settles: a failure is not an answer. One that answers no folder is an answer and is kept like any other: a shared feed's logical path has no folder of its own, and every resolver, check and listing asked CUBE so again. A folder made here invalidates its parent, which drops the misses kept for it and every folder above; one made elsewhere is seen when the TTL runs out, as a listing's change is.

      Parameters

      • path: string

        The folder's path.

      • promise: Promise<unknown>

        The lookup under way.

      Returns void

    • Every path the cache currently holds.

      Returned as a snapshot so a caller may mark or invalidate while iterating without mutating the map underneath itself.

      Returns string[]

      The cached paths, least recently used first.

    • Merges a snapshot's entries into the cache, keeping their original timestamps: what was stale stays stale and is revalidated on its next visit. A path already cached in this process is newer than anything on disk and is kept as is. Entries beyond the LRU bound are dropped oldest-first.

      Parameters

      Returns void

    Settings
    Member Visibility

    On This Page
    Methods