@snabcentr/client-core 3.20.0 → 3.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snabcentr/client-core",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "author": "Snabcentr Ltd.",
   "repository": "https://gitlab.snabcentr.met/web/angular/snabcentr-client-core-lib",
   "license": "Commercial",

package/public-api.d.ts

@@ -27,6 +27,7 @@ export * from './reclamation';
 export * from './references';
 export * from './search';
 export * from './seo';
+export * from './ssr-cache';
 export * from './suggestion';
 export * from './tokens';
 export * from './ui';

package/release_notes.tmp

@@ -1,6 +1,6 @@
-## 3.20.0 (2026-09-08)
+## 3.21.0 (2026-09-16)
 
-### added (1 change)
+### changed (1 change)
 
-- [#13774: Добавлен временный (302) редирект на канонический адрес товара или категории](web_soft/libs/angular/snabcentr-client-core-lib@1d6a56422f20fdc1876d4bccb911dde4f1a77481) ([merge request](web_soft/libs/angular/snabcentr-client-core-lib!343))
+- [#13636: Доработаны механизмы кэширования ответов при SSR](web_soft/libs/angular/snabcentr-client-core-lib@0ccbbc51fd20fe700e5ab833a1135c4a8eb254a4) ([merge request](web_soft/libs/angular/snabcentr-client-core-lib!345))
 

package/ssr-cache/classes/index.d.ts

@@ -0,0 +1 @@
+export * from './sc-ssr-response-cache';

package/ssr-cache/classes/sc-ssr-response-cache.d.ts

@@ -0,0 +1,59 @@
+import { HttpResponse } from '@angular/common/http';
+import { ScISsrResponseCacheStats } from '../interfaces/sc-i-ssr-response-cache-stats';
+/**
+ * Кэш ответов API, один на процесс: переживает пересоздание инжектора между SSR-рендерами.
+ * Одинаковые одновременные запросы склеиваются, при переполнении вытесняется самая давняя запись.
+ */
+export declare class ScSsrResponseCache {
+    /**
+     * Максимальное количество записей в кэше.
+     */
+    private readonly maxEntries;
+    /**
+     * Закэшированные ответы по ключу запроса.
+     */
+    private readonly entries;
+    /**
+     * Выполняемые запросы по ключу запроса.
+     */
+    private readonly pending;
+    /**
+     * Количество запросов, отданных без обращения к API.
+     */
+    private hits;
+    /**
+     * Количество запросов, выполненных к API.
+     */
+    private misses;
+    /**
+     * Инициализирует экземпляр класса {@link ScSsrResponseCache}.
+     *
+     * @param maxEntries Максимальное количество записей в кэше.
+     */
+    constructor(maxEntries?: number);
+    /**
+     * Возвращает ответ из кэша, при отсутствии или устаревании загружает и кэширует. Ошибка загрузки не кэшируется.
+     *
+     * @param key Ключ запроса.
+     * @param lifeTime Время жизни ответа (мс).
+     * @param loader Функция загрузки ответа.
+     */
+    getOrLoad(key: string, lifeTime: number, loader: () => Promise<HttpResponse<unknown>>): Promise<HttpResponse<unknown>>;
+    /**
+     * Возвращает статистику работы кэша.
+     */
+    getStats(): ScISsrResponseCacheStats;
+    /**
+     * Возвращает актуальную запись или `null`.
+     *
+     * @param key Ключ запроса.
+     */
+    private get;
+    /**
+     * Сохраняет запись, при переполнении вытесняя самую давнюю.
+     *
+     * @param key Ключ запроса.
+     * @param entry Запись кэша.
+     */
+    private set;
+}

package/ssr-cache/index.d.ts

@@ -0,0 +1,5 @@
+export * from './classes';
+export * from './interfaces';
+export * from './tokens';
+export * from './sc-ssr-response-cache.backend';
+export * from './sc-ssr-response-cache.providers';

package/ssr-cache/interfaces/index.d.ts

@@ -0,0 +1,2 @@
+export * from './sc-i-ssr-response-cache-settings';
+export * from './sc-i-ssr-response-cache-stats';

package/ssr-cache/interfaces/sc-i-ssr-response-cache-settings.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Настройки кэша ответов API, общего для всех SSR-рендеров.
+ */
+export interface ScISsrResponseCacheSettings {
+    /**
+     * Адреса API относительно `apiUrl`, ответы на которые кэшируются: точное совпадение (`/news`) или префикс с `*` (`/references/*`).
+     */
+    readonly endpoints: string[];
+    /**
+     * Время жизни закэшированного ответа (мс). При значении `0` кэш выключен.
+     */
+    readonly lifeTime: number;
+    /**
+     * Время ожидания ответа API (мс), чтобы зависший запрос не блокировал адрес для всех рендеров. `0`: без ограничения.
+     */
+    readonly loadTimeout: number;
+}

package/ssr-cache/interfaces/sc-i-ssr-response-cache-stats.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Статистика работы кэша ответов API между SSR-рендерами.
+ */
+export interface ScISsrResponseCacheStats {
+    /**
+     * Количество записей в кэше.
+     */
+    readonly size: number;
+    /**
+     * Количество запросов, отданных без обращения к API: из кэша или из уже выполняющегося запроса.
+     */
+    readonly hits: number;
+    /**
+     * Количество запросов, выполненных к API.
+     */
+    readonly misses: number;
+}

package/ssr-cache/internal/is-ssr-response-cacheable.d.ts

@@ -0,0 +1,14 @@
+import { HttpRequest } from '@angular/common/http';
+import { ScIApiKeys } from '../../config/sc-i-api-keys';
+import { ScISsrResponseCacheSettings } from '../interfaces/sc-i-ssr-response-cache-settings';
+/**
+ * Возвращает признак, что ответ можно кэшировать между SSR-рендерами: GET за JSON без ключей доступа по адресам из настроек.
+ *
+ * @param request Данные запроса.
+ * @param settings Настройки кэша.
+ * @param apiUrl Адрес API.
+ * @param apiKeys Названия заголовков ключей доступа к API.
+ *
+ * @internal
+ */
+export declare function isSsrResponseCacheable(request: HttpRequest<unknown>, settings: ScISsrResponseCacheSettings, apiUrl: string, apiKeys: ScIApiKeys): boolean;

package/ssr-cache/internal/sc-i-ssr-cached-response.d.ts

@@ -0,0 +1,16 @@
+import { HttpResponse } from '@angular/common/http';
+/**
+ * Ответ API, закэшированный между SSR-рендерами.
+ *
+ * @internal
+ */
+export interface ScISsrCachedResponse {
+    /**
+     * Момент времени (мс), после которого ответ считается устаревшим.
+     */
+    readonly expiresAt: number;
+    /**
+     * Закэшированный ответ на запрос.
+     */
+    readonly response: HttpResponse<unknown>;
+}

package/ssr-cache/sc-ssr-response-cache.backend.d.ts

@@ -0,0 +1,42 @@
+import { HttpBackend, HttpEvent, HttpRequest } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import * as i0 from "@angular/core";
+/**
+ * Обработчик запросов с кэшем ответов API между SSR-рендерами.
+ *
+ * Стоит на уровне {@link HttpBackend}, ниже перехватчиков: ответ из кэша проходит через перенос в браузер,
+ * а проверка ключей доступа видит итоговые заголовки. Отдаёт только итоговый {@link HttpResponse};
+ * запрос не отменяется при отписке рендера, а ограничен `loadTimeout` из настроек.
+ */
+export declare class ScSsrResponseCacheBackend implements HttpBackend {
+    /**
+     * Штатный обработчик, выполняющий запросы к API.
+     */
+    private readonly backend;
+    /**
+     * Кэш ответов API.
+     */
+    private readonly cache;
+    /**
+     * Настройки кэша.
+     */
+    private readonly settings;
+    /**
+     * Адрес API.
+     */
+    private readonly apiUrl;
+    /**
+     * Названия заголовков ключей доступа к API.
+     */
+    private readonly apiKeys;
+    /** @inheritDoc */
+    handle(request: HttpRequest<unknown>): Observable<HttpEvent<unknown>>;
+    /**
+     * Выполняет запрос к API и возвращает его ответ.
+     *
+     * @param request Данные запроса.
+     */
+    private load;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ScSsrResponseCacheBackend, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ScSsrResponseCacheBackend>;
+}

package/ssr-cache/sc-ssr-response-cache.providers.d.ts

@@ -0,0 +1,6 @@
+import { EnvironmentProviders } from '@angular/core';
+/**
+ * Возвращает провайдеры кэша ответов API между SSR-рендерами.
+ * Подключать только в серверной конфигурации после `provideHttpClient()`: подменяют {@link HttpBackend}.
+ */
+export declare function provideSsrResponseCache(): EnvironmentProviders;

package/ssr-cache/tokens/index.d.ts

@@ -0,0 +1,2 @@
+export * from './sc-ssr-response-cache';
+export * from './sc-ssr-response-cache-settings';

package/ssr-cache/tokens/sc-ssr-response-cache-settings.d.ts

@@ -0,0 +1,6 @@
+import { InjectionToken } from '@angular/core';
+import { ScISsrResponseCacheSettings } from '../interfaces/sc-i-ssr-response-cache-settings';
+/**
+ * Токен настроек кэша ответов API между SSR-рендерами. По умолчанию кэш выключен.
+ */
+export declare const SC_SSR_RESPONSE_CACHE_SETTINGS: InjectionToken<ScISsrResponseCacheSettings>;

package/ssr-cache/tokens/sc-ssr-response-cache.d.ts

@@ -0,0 +1,6 @@
+import { InjectionToken } from '@angular/core';
+import { ScSsrResponseCache } from '../classes/sc-ssr-response-cache';
+/**
+ * Токен кэша ответов API между SSR-рендерами. По умолчанию один экземпляр на процесс, можно переопределить провайдером.
+ */
+export declare const SC_SSR_RESPONSE_CACHE: InjectionToken<ScSsrResponseCache>;