# CacheManager

## Обзор

`CacheManager` основан на <a href="https://github.com/node-cache-manager/node-cache-manager" target="_blank">node-cache-manager</a> и предоставляет NocoBase функциональность управления модулями кеширования. Встроенные типы кеша:

- `memory` – `lru-cache`, предоставляемый по умолчанию `node-cache-manager`.
- `redis` – поддерживается `node-cache-manager-redis-yet`.

Дополнительные типы можно зарегистрировать и расширить через API.

### Основные понятия

- **Store**: Определяет способ кеширования, включающий фабричный метод для создания кешей и другие связанные конфигурации. Каждый способ кеширования имеет уникальный идентификатор, который предоставляется при регистрации.
  Уникальные идентификаторы для двух встроенных способов кеширования — это `memory` и `redis`.

- **Фабричный метод Store**: Метод, предоставляемый `node-cache-manager` и связанными пакетами расширений для создания кешей. Например, `'memory'`, предоставляемый по умолчанию `node-cache-manager`, или `redisStore`, предоставляемый `node-cache-manager-redis-yet`. Это соответствует первому параметру метода `caching` в `node-cache-manager`.

- **Cache**: Класс, инкапсулированный NocoBase, который предоставляет методы для работы с кешем. При фактическом использовании кеша вы работаете с экземпляром `Cache`. Каждый экземпляр `Cache` имеет уникальный идентификатор, который можно использовать в качестве пространства имён для различения различных модулей.

## Методы класса

### `constructor()`

#### Сигнатура

- `constructor(options?: CacheManagerOptions)`

#### Типы

```ts
export type CacheManagerOptions = Partial<{
  defaultStore: string;
  stores: {
    [storeType: string]: StoreOptions;
  };
}>;

type StoreOptions = {
  store?: 'memory' | FactoryStore<Store, any>;
  close?: (store: Store) => Promise<void>;
  // глобальная конфигурация
  [key: string]: any;
};
```

#### Подробности

##### CacheManagerOptions

| Свойство       | Тип                            | Описание                                                                                                                                                                                                                         |
| -------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultStore` | `string`                       | Уникальный идентификатор для типа кеша по умолчанию.                                                                                                                                                                                   |
| `stores`       | `Record<string, StoreOptions>` | Регистрирует типы кеша. Ключом является уникальный идентификатор типа кеша, а значением — объект, содержащий метод регистрации и глобальную конфигурацию для этого типа кеша.<br />В `node-cache-manager` метод для создания кеша — это `await caching(store, config)`. Здесь необходимо предоставить объект [`StoreOptions`](#storeoptions). |

##### StoreOptions

| Свойство        | Тип                                   | Описание                                                                                                                                                                                            |
| --------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `store`         | `memory` \| `FactoryStore<Store, any>` | Фабричный метод `store`, соответствующий первому параметру `caching`.                                                                                                                         |
| `close`         | `(store: Store) => Promise<void>`      | Необязательно. Для промежуточного ПО, такого как Redis, требующего соединения, необходимо предоставить метод обратного вызова для закрытия соединения. Входным параметром является объект, возвращаемый фабричным методом `store`. |
| `[key: string]` | `any`                                  | Другие глобальные конфигурации `store`, соответствующие второму параметру `caching`.                                                                                                               |

#### Параметры `options` по умолчанию

```ts
import { redisStore, RedisStore } from 'cache-manager-redis-yet';

const defaultOptions: CacheManagerOptions = {
  defaultStore: 'memory',
  stores: {
    memory: {
      store: 'memory',
      // глобальная конфигурация
      max: 2000,
    },
    redis: {
      store: redisStore,
      close: async (redis: RedisStore) => {
        await redis.client.quit();
      },
    },
  },
};
```

Параметр `options` будет объединён с параметрами по умолчанию. Свойства, уже присутствующие в параметрах по умолчанию, можно опустить. Например:

```ts
const cacheManager = new CacheManager({
  stores: {
    defaultStore: 'redis',
    redis: {
      // redisStore уже предоставлен в параметрах по умолчанию, поэтому достаточно указать только конфигурацию redisStore.
      url: 'redis://localhost:6379',
    },
  },
});
```

### `registerStore()`

Регистрирует новый способ кеширования. Например:

```ts
import { redisStore } from 'cache-manager-redis-yet';

cacheManager.registerStore({
  // уникальный идентификатор store
  name: 'redis',
  // фабричный метод для создания store
  store: redisStore,
  // закрытие соединения store
  close: async (redis: RedisStore) => {
    await redis.client.quit();
  },
  // глобальная конфигурация
  url: 'xxx',
});
```

#### Сигнатура

- `registerStore(options: { name: string } & StoreOptions)`

### `createCache()`

Создаёт кеш. Например:

```ts
await cacheManager.createCache({
  name: 'default', // уникальный идентификатор кеша
  store: 'memory', // уникальный идентификатор store
  prefix: 'mycache', // автоматически добавляет префикс 'mycache:' к ключам кеша, необязательно
  // другие конфигурации store, пользовательские настройки будут объединены с глобальной конфигурацией store
  max: 2000,
});
```

#### Сигнатура

- `createCache(options: { name: string; prefix?: string; store?: string; [key: string]: any }): Promise<Cache>`

#### Подробности

##### options

| Свойство        | Тип      | Описание                                           |
| --------------- | -------- | -------------------------------------------------- |
| `name`          | `string` | Уникальный идентификатор кеша.                      |
| `store`         | `string` | Уникальный идентификатор store.                      |
| `prefix`        | `string` | Необязательно, префикс ключа кеша.           |
| `[key: string]` | `any`    | Другие пользовательские параметры конфигурации, связанные со store. |

Если `store` опущен, будет использоваться `defaultStore`. В этом случае способ кеширования будет меняться в соответствии со способом кеширования по умолчанию в системе.

При отсутствии пользовательских конфигураций возвращается пространство кеша по умолчанию, созданное глобальной конфигурацией и используемое текущим способом кеширования. Рекомендуется добавить `prefix` во избежание конфликтов ключей.

```ts
// Использование кеша по умолчанию с глобальной конфигурацией
await cacheManager.createCache({ name: 'default', prefix: 'mycache' });
```

##### Cache

См. [Cache](./cache.md)

### `getCache()`

Получает соответствующий кеш.

```ts
cacheManager.getCache('default');
```

#### Сигнатура

- `getCache(name: string): Cache`

### `flushAll()`

Сбрасывает все кеши.

```ts
await cacheManager.flushAll();
```

### `close()`

Закрывает все соединения промежуточного ПО кеширования.

```ts
await cacheManager.close();
```