import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/en/functional-basic/Classes/CacheItem - Advanced Cache Management'/>

# CacheItem Class

> **⚠️ Deprecated** — This class is obsolete and should not be used. / Этот класс устарел и не рекомендуется к использованию.

The internal engine driving individual cache entries. While `Cache` and `CacheStatic` provide the public interfaces for retrieving cached data across your application, it is the `CacheItem` class that securely manages the lifecycle, storage, and invalidation rules for each specific value.

> `CacheItem` is an **auxiliary class**, designed for internal management of individual cache entries. In most cases, it is recommended to interact with caching through the `Cache` or `CacheStatic` classes.

## Key Features

- **Dependency Tracking** — maintains comparison arrays used to determine if a cached value remains valid.
- **Lazy Evaluation** — ensures the expensive callback function only runs when dependencies have changed.
- **Historical Memory** — keeps a reference to the previously cached value (`getCacheOld`) even after a recalculation occurs.
- **Async Support** — natively handles both synchronous (`getCache`) and `Promise`-based asynchronous (`getCacheAsync`) data loading.
- **Strict Invalidation** — uses deep comparison logic to trigger updates only when necessary.

## Initialization

As an auxiliary component, `CacheItem` is usually instantiated by higher-level managers. However, it can be created manually if custom, isolated caching logic is required.

### Generic Constraints

The class supports the following generic to ensure strict typing of the cached value:
- `T` — The type of the value being cached.

**Parameters:**
- `callback: () => T` — a function that will generate or fetch data for the cache.

```typescript
import { CacheItem } from '@dxtmisha/functional-basic'

// 1. Initialization with a data retrieval function
const userCache = new CacheItem(() => fetchUserData())

// 2. Using generics for strict typing
const numberCache = new CacheItem<number>(() => Math.random())
```

## Methods

### Cache Access

- `getCache(comparison?: any[]): T` — Retrieves the value from the cache. If the comparison dependencies have changed, it triggers a recalculation.
- `getCacheAsync(comparison?: any[]): Promise<T>` — Asynchronous version of `getCache`. Returns a Promise that resolves to the cached or newly fetched data.

### History

- `getCacheOld(): T | undefined` — Returns the value that was stored in the cache immediately prior to the last update.

## Examples

### Dependency-Based Invalidation
```javascript
let count = 0
const counterCache = new CacheItem(() => ++count)

// First call: evaluates and caches 1
counterCache.getCache([10]) // returns 1

// Second call: dependencies match [10], returns cached 1
counterCache.getCache([10]) // returns 1

// Third call: dependencies changed to [20], evaluates and caches 2
counterCache.getCache([20]) // returns 2

// Check history:
console.log(counterCache.getCacheOld()) // returns 1
```

### Async API Caching
```javascript
const apiCache = new CacheItem(async () => {
  const response = await fetch('/api/data')
  return response.json()
})

// Fetches from the network for the first 'v1' request
const data1 = await apiCache.getCacheAsync(['v1'])

// Returns from cache instantly for subsequent 'v1' requests
const data2 = await apiCache.getCacheAsync(['v1'])
```
