Class LocalCacheManager

LocalCacheManager is a singleton that provides a unified caching abstraction for datasets, RunView results, and RunQuery results. It wraps ILocalStorageProvider for actual storage and maintains an internal registry of all cached items.

Key features:

  • Typed methods for datasets, RunViews, and RunQueries
  • Automatic cache metadata tracking (timestamps, access counts, sizes)
  • Hit/miss statistics for performance monitoring
  • Eviction policies (LRU, LFU, FIFO) for memory management
  • Dashboard-friendly registry queries

Usage:

// Initialize during app startup
await LocalCacheManager.Instance.Initialize(storageProvider);

// Cache a dataset
await LocalCacheManager.Instance.SetDataset('MyDataset', filters, dataset, keyPrefix);

// Retrieve cached data
const cached = await LocalCacheManager.Instance.GetDataset('MyDataset', filters, keyPrefix);

Hierarchy (view full)

Constructors

constructor

Properties

REGISTRY_KEY _config _initializePromise _initialized _persistTimeout _registry _stats _storageProvider

Accessors

Config GlobalKey IsInitialized Instance

Methods

ClearAll ClearByType ClearDataset GenerateRunQueryFingerprint GenerateRunViewFingerprint GetAllEntries GetDataset GetDatasetTimestamp GetEntriesByType GetGlobalObjectStore GetHitRate GetRunQueryCacheStatus GetRunQueryResult GetRunViewResult GetStats Initialize InvalidateEntityCaches InvalidateQueryCaches InvalidateRunQueryResult InvalidateRunViewResult IsDatasetCached ResetStats SetDataset SetRunQueryResult SetRunViewResult UpdateConfig buildDatasetKey debouncedPersistRegistry doInitialize estimateSize evict evictIfNeeded getCategoryForType loadRegistry persistRegistry recordAccess registerEntry unregisterEntry getInstance

Constructors

Protected constructor

Properties

Private Readonly REGISTRY_KEY

REGISTRY_KEY: "__MJ_CACHE_REGISTRY__" = '__MJ_CACHE_REGISTRY__'

Private _config

_config: LocalCacheManagerConfig = ...

Private _initializePromise

_initializePromise: Promise<void> = null

Private _initialized

_initialized: boolean = false

Private _persistTimeout

_persistTimeout: Timeout = null

Private _registry

_registry: Map<string, CacheEntryInfo> = ...

Private _stats

_stats: {
    hits: number;
    misses: number;
} = ...

Type declaration

  • hits: number
  • misses: number

Private _storageProvider

_storageProvider: ILocalStorageProvider = null

Accessors

Config

GlobalKey

  • get GlobalKey(): string

  • Returns string

IsInitialized

Static Instance

Methods

ClearAll

ClearByType

ClearDataset

GenerateRunQueryFingerprint

  • GenerateRunQueryFingerprint(queryId?, queryName?, parameters?, connectionPrefix?): string

  • Generates a human-readable cache fingerprint for a RunQuery request.

    Format: QueryName|QueryID|params|connection Example: GetActiveUsers|abc123|{"status":"active"}|localhost

    Parameters

    • Optional queryId: string

      The query ID

    • Optional queryName: string

      The query name

    • Optional parameters: Record<string, unknown>

      Optional query parameters

    • Optional connectionPrefix: string

      Prefix identifying the connection (e.g., server URL) to differentiate caches across connections

    Returns string

    A unique, human-readable fingerprint string

GenerateRunViewFingerprint

  • GenerateRunViewFingerprint(params, connectionPrefix?): string

  • Generates a human-readable cache fingerprint for a RunView request. This fingerprint uniquely identifies the query based on its parameters and connection.

    Format: EntityName|filter|orderBy|resultType|maxRows|startRow|connection Example: Users|Active=1|Name ASC|simple|100|0|localhost

    Parameters

    • params: RunViewParams

      The RunView parameters

    • Optional connectionPrefix: string

      Prefix identifying the connection (e.g., server URL) to differentiate caches across connections

    Returns string

    A unique, human-readable fingerprint string

GetAllEntries

GetDataset

GetDatasetTimestamp

  • GetDatasetTimestamp(name, itemFilters, keyPrefix): Promise<Date>

  • Gets the timestamp of a cached dataset.

    Parameters

    • name: string

      The dataset name

    • itemFilters: DatasetItemFilterType[]

      Optional filters applied to the dataset

    • keyPrefix: string

      Prefix for the cache key

    Returns Promise<Date>

    The cache timestamp or null if not found

GetEntriesByType

GetGlobalObjectStore

  • GetGlobalObjectStore(): typeof globalThis

  • The Global Object Store is a place to store global objects that need to be shared across the application. Depending on the execution environment, this could be the window object in a browser, or the global object in a node environment, or something else in other contexts. The key here is that in some cases static variables are not truly shared because it is possible that a given class might have copies of its code in multiple paths in a deployed application. This approach ensures that no matter how many code copies might exist, there is only one instance of the object in question by using the Global Object Store.

    Returns typeof globalThis

GetHitRate

GetRunQueryCacheStatus

  • GetRunQueryCacheStatus(fingerprint): Promise<{
        maxUpdatedAt: string;
        rowCount: number;
    }>

  • Gets the cache status (fingerprint data) for a RunQuery result. Used for smart cache validation with the server.

    Parameters

    • fingerprint: string

      The cache fingerprint

    Returns Promise<{
        maxUpdatedAt: string;
        rowCount: number;
    }>

    The cache status with maxUpdatedAt and rowCount, or null if not found/expired

GetRunQueryResult

  • GetRunQueryResult(fingerprint): Promise<{
        maxUpdatedAt: string;
        queryId?: string;
        results: unknown[];
        rowCount: number;
    }>

  • Retrieves a cached RunQuery result.

    Parameters

    • fingerprint: string

      The cache fingerprint

    Returns Promise<{
        maxUpdatedAt: string;
        queryId?: string;
        results: unknown[];
        rowCount: number;
    }>

    The cached results, maxUpdatedAt, rowCount, and queryId, or null if not found

GetRunViewResult

  • GetRunViewResult(fingerprint): Promise<{
        maxUpdatedAt: string;
        results: unknown[];
        rowCount: number;
    }>

  • Retrieves a cached RunView result.

    Parameters

    • fingerprint: string

      The cache fingerprint

    Returns Promise<{
        maxUpdatedAt: string;
        results: unknown[];
        rowCount: number;
    }>

    The cached results, maxUpdatedAt, and rowCount, or null if not found

GetStats

Initialize

  • Initialize(storageProvider, config?): Promise<void>

  • Initialize the cache manager with a storage provider. This should be called during app startup after the storage provider is available.

    This method is safe to call multiple times - subsequent calls will return the same promise as the first caller, ensuring initialization only happens once.

    Parameters

    Returns Promise<void>

    A promise that resolves when initialization is complete

InvalidateEntityCaches

  • InvalidateEntityCaches(entityName): Promise<void>

  • Invalidates all cached RunView results for a specific entity. Useful when an entity's data changes and all related caches should be cleared.

    Parameters

    • entityName: string

      The entity name to invalidate

    Returns Promise<void>

InvalidateQueryCaches

  • InvalidateQueryCaches(queryName): Promise<void>

  • Invalidates all cached RunQuery results for a specific query. Useful when a query's underlying data changes and all related caches should be cleared.

    Parameters

    • queryName: string

      The query name to invalidate

    Returns Promise<void>

InvalidateRunQueryResult

  • InvalidateRunQueryResult(fingerprint): Promise<void>

  • Invalidates a cached RunQuery result.

    Parameters

    • fingerprint: string

      The cache fingerprint to invalidate

    Returns Promise<void>

InvalidateRunViewResult

  • InvalidateRunViewResult(fingerprint): Promise<void>

  • Invalidates a cached RunView result.

    Parameters

    • fingerprint: string

      The cache fingerprint to invalidate

    Returns Promise<void>

IsDatasetCached

  • IsDatasetCached(name, itemFilters, keyPrefix): Promise<boolean>

  • Checks if a dataset is cached.

    Parameters

    • name: string

      The dataset name

    • itemFilters: DatasetItemFilterType[]

      Optional filters applied to the dataset

    • keyPrefix: string

      Prefix for the cache key

    Returns Promise<boolean>

    True if the dataset is cached

ResetStats

SetDataset

  • SetDataset(name, itemFilters, dataset, keyPrefix): Promise<void>

  • Stores a dataset in the local cache.

    Parameters

    • name: string

      The dataset name

    • itemFilters: DatasetItemFilterType[]

      Optional filters applied to the dataset

    • dataset: DatasetResultType

      The dataset result to cache

    • keyPrefix: string

      Prefix for the cache key (typically includes connection info)

    Returns Promise<void>

SetRunQueryResult

  • SetRunQueryResult(fingerprint, queryName, results, maxUpdatedAt, rowCount?, queryId?, ttlMs?): Promise<void>

  • Stores a RunQuery result in the cache.

    Parameters

    • fingerprint: string

      The cache fingerprint

    • queryName: string

      The query name for display

    • results: unknown[]

      The results to cache

    • maxUpdatedAt: string

      The latest update timestamp (for smart cache validation)

    • Optional rowCount: number

      Optional row count (defaults to results.length if not provided)

    • Optional queryId: string

      Optional query ID for reference

    • Optional ttlMs: number

      Optional TTL in milliseconds (for cache expiry tracking)

    Returns Promise<void>

SetRunViewResult

  • SetRunViewResult(fingerprint, params, results, maxUpdatedAt, rowCount?): Promise<void>

  • Stores a RunView result in the cache.

    Parameters

    • fingerprint: string

      The cache fingerprint (from GenerateRunViewFingerprint)

    • params: RunViewParams

      The original RunView parameters

    • results: unknown[]

      The results to cache

    • maxUpdatedAt: string

      The latest __mj_UpdatedAt from the results

    • Optional rowCount: number

      Optional row count (defaults to results.length if not provided)

    Returns Promise<void>

UpdateConfig

Private buildDatasetKey

Private debouncedPersistRegistry

Private doInitialize

Private estimateSize

Private evict

  • evict(targetBytes, targetCount): Promise<void>

  • Evicts entries based on the configured eviction policy.

    Parameters

    • targetBytes: number
    • targetCount: number

    Returns Promise<void>

Private evictIfNeeded

Private getCategoryForType

Private loadRegistry

Private persistRegistry

Private recordAccess

Private registerEntry

Private unregisterEntry

Protected Static getInstance

  • getInstance<T>(this, className?): T

  • Returns the singleton instance of the class. If the instance does not exist, it is created and stored in the Global Object Store. If className is provided it will be used as part of the key in the Global Object Store, otherwise the actual class name will be used. NOTE: the class name used by default is the lowest level of the object hierarchy, so if you have a class that extends another class, the lowest level class name will be used.

    Type Parameters

    Parameters

    • this: (new () => T)
        • new (): T

        • Returns T

    • Optional className: string

    Returns T

Settings

Member Visibility

Theme

On This Page

constructorREGISTRY_KEY_config_initializePromise_initialized_persistTimeout_registry_stats_storageProviderConfigGlobalKeyIsInitializedInstanceClearAllClearByTypeClearDatasetGenerateRunQueryFingerprintGenerateRunViewFingerprintGetAllEntriesGetDatasetGetDatasetTimestampGetEntriesByTypeGetGlobalObjectStoreGetHitRateGetRunQueryCacheStatusGetRunQueryResultGetRunViewResultGetStatsInitializeInvalidateEntityCachesInvalidateQueryCachesInvalidateRunQueryResultInvalidateRunViewResultIsDatasetCachedResetStatsSetDatasetSetRunQueryResultSetRunViewResultUpdateConfigbuildDatasetKeydebouncedPersistRegistrydoInitializeestimateSizeevictevictIfNeededgetCategoryForTypeloadRegistrypersistRegistryrecordAccessregisterEntryunregisterEntrygetInstance