@itd-api/cache 0.1.0 → 0.3.0

package/README.md

@@ -12,8 +12,7 @@ TTL/LRU-кэш и дедупликация одновременных запро
 npm install itd-api @itd-api/cache
 ```
 
-Поддерживается `itd-api >=0.5.0 <1.0.0`: cache использует namespace
-`RequestOptions.extensions` и стабильный `operationId` запроса.
+Требуется `itd-api >=0.9.0 <1.0.0`.
 
 ## Быстрый старт
 
@@ -33,13 +32,17 @@ const first = await itd.posts.get(postId);  // запрос к API
 const second = await itd.posts.get(postId); // ответ из кэша
 ```
 
+Операции подключаемых модулей тоже можно кэшировать. Например, модуль Pixel Battle задаёт
+`CachePolicyKind.Query` в `annotations.cache`, а пользователь добавляет полный `operationId`
+в `operations`.
+
 Кэшируются только перечисленные операции. Query, path и body входят в ключ, поэтому
 разные страницы ленты, профили и наборы идентификаторов хранятся отдельно. Одинаковые
 запросы, запущенные одновременно, выполняют один сетевой вызов.
 
-Имена в `operations` — стабильные `operationId`, а не HTTP-пути. Поэтому перенос endpoint не ломает
-правила кэша. Низкоуровневый `itd.request()` без явного ID считается операцией `raw`: одно лишь
-совпадение его URL со встроенным resource не включает кэш автоматически.
+Имена в `operations` — постоянные `operationId`, а не HTTP-пути. Изменение маршрута не ломает
+правила кэша. Низкоуровневый `itd.request()` без явного идентификатора операции считается
+операцией `raw`; совпадение URL со встроенным ресурсом не включает кэш автоматически.
 
 ## Настройки
 
@@ -100,11 +103,11 @@ cached.clear();
 `clear()` очищает всё хранилище. Оба метода защищены от гонки: запрос, начатый до очистки,
 не запишет устаревший результат после неё.
 
-## Realtime
+## События
 
 ```ts
-const stream = itd.realtime();
-const detachCache = cached.attachRealtime(stream);
+const stream = itd.notifications.events;
+const detachCache = cached.attachNotificationEvents(stream);
 
 await stream.connect();
 
@@ -118,8 +121,12 @@ stream.disconnect();
 пользователем, событие `unreadCount` — их счётчик. Кэш других аккаунтов и остальные операции
 поток не изменяет.
 
-У стороннего realtime-объекта без доступных идентификатора пользователя и базового URL
-используется безопасный fallback: операции уведомлений инвалидируются во всех аккаунтах.
+Инвалидация подключается как промежуточный обработчик. Вызывайте
+`attachNotificationEvents()` до прикладных обработчиков, которые могут не вызвать `next()`:
+тогда отфильтрованное для интерфейса обновление всё равно не оставит устаревший кэш.
+
+У стороннего событийного объекта без доступных идентификатора пользователя и базового URL
+операции уведомлений инвалидируются во всех аккаунтах.
 
 ## Несколько клиентов
 
@@ -151,7 +158,7 @@ clientB.use(shared);
 копиями не объединяет.
 
 `maxEntries` ограничивает весь экземпляр `shared`, а `clear()` и `invalidate()` управляют
-всеми его разделами. `attachRealtime()` затрагивает аккаунт создавшего поток клиента.
+всеми его разделами. `attachNotificationEvents()` затрагивает аккаунт создавшего поток клиента.
 Смена сессии сохраняет общий кэш, смена пользователя автоматически выбирает другой раздел.
 
 ## Ключ
@@ -161,11 +168,11 @@ clientB.use(shared);
 - имя операции, HTTP-метод и path;
 - базовый URL и идентификатор пользователя; для `auth.sessions` также идентификатор сессии;
 - `service` или разовый `baseUrl`;
-- query и JSON-body;
+- параметры строки запроса и JSON-тело;
 - режим `raw`, `skipAuth` и опции других плагинов, влияющие на ответ.
 
 Токен и заголовки в ключ не входят. Также не учитываются `signal`, `timeout` и настройки
-повторов. Несериализуемый JSON-body выполняется без кэширования.
+повторов. Запрос с несериализуемым JSON-телом выполняется без кэширования.
 
 Ответ хранится как независимая копия: изменение полученного объекта не меняет следующие
 результаты.
@@ -184,7 +191,8 @@ clientB.use(shared);
 | Files | `files.get` |
 | Subscription | `subscription.status`, `subscription.methods` |
 | Verification | `verification.status` |
-| Platform | `platform.changelog`, `platform.announcements`, `platform.portal`, `platform.status` |
+| Platform | `platform.changelog`, `platform.announcements`, `platform.portal`, `status.get` |
+| Shop | `shop.products.list`, `shop.products.get`, `shop.delivery.countries`, `shop.delivery.cities`, `shop.delivery.points`, `shop.delivery.calculate` |
 
 Страницы, загружаемые итераторами, используют операцию соответствующего списочного метода:
 `posts.iterate()` — `posts.list`, `users.iterateFollowers()` — `users.followers` и так

package/dist/index.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let itd_api = require("itd-api");
 let lru_cache = require("lru-cache");
 //#region src/errors.ts
 /** Ошибка настройки или использования плагина кэша. */
@@ -210,8 +211,32 @@ const CACHE_OPERATIONS = freezeOperations([
 		category: "platform"
 	},
 	{
-		id: "platform.status",
+		id: "status.get",
 		category: "platform"
+	},
+	{
+		id: "shop.products.list",
+		category: "shop"
+	},
+	{
+		id: "shop.products.get",
+		category: "shop"
+	},
+	{
+		id: "shop.delivery.countries",
+		category: "shop"
+	},
+	{
+		id: "shop.delivery.cities",
+		category: "shop"
+	},
+	{
+		id: "shop.delivery.points",
+		category: "shop"
+	},
+	{
+		id: "shop.delivery.calculate",
+		category: "shop"
 	}
 ]);
 const OPERATIONS = new Map(CACHE_OPERATIONS.map((operation) => [operation.id, operation]));
@@ -224,6 +249,20 @@ function cacheOperation(operationId) {
 	return OPERATIONS.get(operationId);
 }
 //#endregion
+//#region src/policy.ts
+/** Виды политики кэша, объявляемой в метаданных операции. */
+const CachePolicyKind = Object.freeze({
+	Query: "query",
+	Mutation: "mutation"
+});
+/** Области изоляции данных кэша. */
+const CachePolicyScope = Object.freeze({
+	Account: "account",
+	Session: "session"
+});
+/** Способы инвалидации кэша после мутации. */
+const CacheInvalidation = Object.freeze({ All: "all" });
+//#endregion
 //#region src/mutations.ts
 const POST_CONTENT = [
 	"posts.list",
@@ -337,37 +376,37 @@ const CACHE_MUTATIONS = Object.freeze([
 	},
 	{
 		operationId: "auth.signUp",
-		invalidates: "all"
+		invalidates: CacheInvalidation.All
 	},
 	{
 		operationId: "auth.signIn",
-		invalidates: "all"
+		invalidates: CacheInvalidation.All
 	},
 	{
 		operationId: "auth.verifyOtp",
-		invalidates: "all"
+		invalidates: CacheInvalidation.All
 	},
 	{
 		operationId: "auth.logout",
-		invalidates: "all"
+		invalidates: CacheInvalidation.All
 	},
 	{
 		operationId: "auth.resetPassword",
-		invalidates: "all"
+		invalidates: CacheInvalidation.All
 	},
 	{
 		operationId: "auth.changePassword",
-		invalidates: "all"
+		invalidates: CacheInvalidation.All
 	},
 	{
 		operationId: "auth.revokeSession",
 		invalidates: ["auth.sessions"],
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "auth.revokeOtherSessions",
 		invalidates: ["auth.sessions"],
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "posts.create",
@@ -492,22 +531,22 @@ const CACHE_MUTATIONS = Object.freeze([
 	{
 		operationId: "notifications.markRead",
 		invalidates: NOTIFICATIONS,
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "notifications.markReadBatch",
 		invalidates: NOTIFICATIONS,
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "notifications.markAllRead",
 		invalidates: NOTIFICATIONS,
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "notifications.updateSettings",
 		invalidates: ["notifications.getSettings"],
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "files.upload",
@@ -520,32 +559,32 @@ const CACHE_MUTATIONS = Object.freeze([
 	{
 		operationId: "verification.submit",
 		invalidates: ["verification.status"],
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "subscription.pay",
 		invalidates: SUBSCRIPTION,
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "subscription.setAutoRenewal",
 		invalidates: SUBSCRIPTION,
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "subscription.bindCard",
 		invalidates: SUBSCRIPTION,
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "subscription.setDefaultMethod",
 		invalidates: SUBSCRIPTION,
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "subscription.removeMethod",
 		invalidates: SUBSCRIPTION,
-		scope: "account"
+		scope: CachePolicyScope.Account
 	},
 	{
 		operationId: "reports.create",
@@ -591,7 +630,7 @@ function resolveOptions(options) {
 	if (!Array.isArray(options.operations) || options.operations.length === 0) throw new CacheError("cache.operations должен содержать хотя бы одну операцию");
 	const operations = /* @__PURE__ */ new Set();
 	for (const operation of options.operations) {
-		if (typeof operation !== "string" || !isCacheOperationId(operation)) throw new CacheError(`Неизвестная операция кэша: ${JSON.stringify(operation)}`);
+		if (typeof operation !== "string" || (0, itd_api.isBuiltInOperationId)(operation) && !isCacheOperationId(operation)) throw new CacheError(`Неизвестная операция кэша: ${JSON.stringify(operation)}`);
 		operations.add(operation);
 	}
 	const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
@@ -623,7 +662,7 @@ function cacheMode(request) {
 	if (!CACHE_MODES.has(mode)) throw new CacheError(`cache должен быть '${CacheModes.Default}', '${CacheModes.Reload}' или '${CacheModes.NoStore}', получено: ${String(mode)}`);
 	return mode;
 }
-/** Создаёт TTL/LRU-кэш разобранных ответов itd-api. */
+/** Создаёт TTL/LRU-кэш нормализованных результатов itd-api. */
 function cache(options) {
 	const config = resolveOptions(options);
 	const values = new lru_cache.LRUCache({
@@ -649,9 +688,10 @@ function cache(options) {
 		if (operations.length === 0) return;
 		const selected = /* @__PURE__ */ new Set();
 		for (const operation of operations) {
-			if (!isCacheOperationId(operation)) throw new CacheError(`Неизвестная операция кэша: ${JSON.stringify(operation)}`);
-			selected.add(operation);
-			operationGenerations.set(operation, (operationGenerations.get(operation) ?? 0) + 1);
+			if (typeof operation !== "string") throw new CacheError(`Неизвестная операция кэша: ${JSON.stringify(operation)}`);
+			const operationId = operation;
+			selected.add(operationId);
+			operationGenerations.set(operationId, (operationGenerations.get(operationId) ?? 0) + 1);
 		}
 		for (const [key, entry] of values.entries()) if (selected.has(entry.operation)) values.delete(key);
 		for (const [key, entry] of pending) if (selected.has(entry.operation)) pending.delete(key);
@@ -672,11 +712,24 @@ function cache(options) {
 		for (const [key, entry] of pending) if (entry.accountScope === accountScope && selected.has(entry.operation)) pending.delete(key);
 	};
 	const applyMutation = (accountScope, mutation) => {
-		if (mutation.invalidates === "all") clearScope(accountScope);
-		else if (mutation.scope === "account") invalidateScope(accountScope, mutation.invalidates);
+		if (mutation.invalidates === CacheInvalidation.All) clearScope(accountScope);
+		else if (mutation.scope === CachePolicyScope.Account) invalidateScope(accountScope, mutation.invalidates);
 		else invalidate(...mutation.invalidates);
 	};
-	const createTransformer = (installation, baseUrl, getAuthIdentity, getAuthScope) => {
+	const invalidateNotificationStream = (stream, ...operations) => {
+		const identity = stream.getAuthIdentity();
+		const streamBaseUrl = stream.baseUrl;
+		const legacyScope = stream.getAuthScope();
+		const accountScope = identity?.userId ? JSON.stringify([streamBaseUrl, identity.userId]) : legacyScope !== void 0 ? JSON.stringify([streamBaseUrl, legacyScope]) : void 0;
+		if (accountScope === void 0) invalidate(...operations);
+		else invalidateScope(accountScope, operations);
+	};
+	const notificationMiddleware = async (context, next) => {
+		if (context.update.type === itd_api.NotificationUpdateType.Notification) invalidateNotificationStream(context.stream, "notifications.list", "notifications.count");
+		else if (context.update.type === itd_api.NotificationUpdateType.UnreadCount) invalidateNotificationStream(context.stream, "notifications.count");
+		await next();
+	};
+	const createTransformer = (installation, baseUrl, getAuthIdentity, getAuthScope, getOperation) => {
 		const fallbackAuthScope = JSON.stringify([baseUrl, `installation:${installation}`]);
 		const resolveIdentity = async () => {
 			const identity = await getAuthIdentity?.();
@@ -691,16 +744,24 @@ function cache(options) {
 			};
 		};
 		return async (request, next) => {
-			const operation = cacheOperation(request.operationId);
+			const policy = getOperation(request.operationId)?.annotations?.cache;
+			const operation = cacheOperation(request.operationId) ?? (policy?.kind === CachePolicyKind.Query ? {
+				id: request.operationId,
+				category: request.operationId.split(".", 1)[0] ?? "feature"
+			} : void 0);
 			const method = request.method.toUpperCase();
-			if (!(operation !== void 0 || method === "GET" || method === "HEAD")) {
-				const mutation = cacheMutation(request.operationId);
+			if (!(policy !== void 0 ? policy.kind === CachePolicyKind.Query : operation !== void 0 || method === "GET" || method === "HEAD")) {
+				const mutation = cacheMutation(request.operationId) ?? (policy?.kind === CachePolicyKind.Mutation ? {
+					operationId: request.operationId,
+					invalidates: policy.invalidates,
+					...policy.scope === void 0 ? {} : { scope: policy.scope }
+				} : void 0);
 				const startedIdentity = mutation ? await resolveIdentity() : void 0;
 				const result = await next(request);
 				if (mutation && startedIdentity) {
 					applyMutation(startedIdentity.accountScope, mutation);
 					const currentIdentity = await resolveIdentity();
-					if (currentIdentity.accountScope !== startedIdentity.accountScope && (mutation.invalidates === "all" || mutation.scope === "account")) applyMutation(currentIdentity.accountScope, mutation);
+					if (currentIdentity.accountScope !== startedIdentity.accountScope && (mutation.invalidates === CacheInvalidation.All || mutation.scope === CachePolicyScope.Account)) applyMutation(currentIdentity.accountScope, mutation);
 				} else clear();
 				return result;
 			}
@@ -710,7 +771,7 @@ function cache(options) {
 			const unscopedKey = buildCacheKey(operation.id, request);
 			if (unscopedKey === void 0) return next(request);
 			const identity = await resolveIdentity();
-			const scope = operation.id === "auth.sessions" ? identity.sessionScope : identity.accountScope;
+			const scope = operation.id === "auth.sessions" || policy?.kind === CachePolicyKind.Query && policy.scope === CachePolicyScope.Session ? identity.sessionScope : identity.accountScope;
 			const key = JSON.stringify([scope, unscopedKey]);
 			if (mode === CacheModes.Reload) {
 				const state = keyStates.get(key) ?? {
@@ -749,7 +810,7 @@ function cache(options) {
 					const result = await next(request);
 					const stored = cloneValue(result);
 					const currentIdentity = await resolveIdentity();
-					const currentScope = operation.id === "auth.sessions" ? currentIdentity.sessionScope : currentIdentity.accountScope;
+					const currentScope = operation.id === "auth.sessions" || policy?.kind === CachePolicyKind.Query && policy.scope === CachePolicyScope.Session ? currentIdentity.sessionScope : currentIdentity.accountScope;
 					if (stored.cacheable && currentScope === scope && generation === startedGeneration && (scopeGenerations.get(identity.accountScope) ?? 0) === startedScopeGeneration && (operationGenerations.get(operation.id) ?? 0) === startedOperationGeneration && (scopeOperationGenerations.get(scopedOperationKey) ?? 0) === startedScopeOperationGeneration && keyState.generation === startedKeyGeneration) values.set(key, {
 						accountScope: identity.accountScope,
 						operation: operation.id,
@@ -786,34 +847,24 @@ function cache(options) {
 		},
 		clear,
 		invalidate,
-		attachRealtime(stream) {
-			if (!stream || typeof stream.on !== "function") throw new CacheError("attachRealtime() принимает поток из itd.realtime()");
-			const invalidateStream = (...operations) => {
-				const identity = typeof stream.getAuthIdentity === "function" ? stream.getAuthIdentity() : void 0;
-				const streamBaseUrl = typeof stream.baseUrl === "string" && stream.baseUrl.length > 0 ? stream.baseUrl : void 0;
-				const legacyScope = typeof stream.getAuthScope === "function" ? stream.getAuthScope() : void 0;
-				const accountScope = identity?.userId && streamBaseUrl ? JSON.stringify([streamBaseUrl, identity.userId]) : legacyScope !== void 0 && streamBaseUrl ? JSON.stringify([streamBaseUrl, legacyScope]) : void 0;
-				if (accountScope === void 0) invalidate(...operations);
-				else invalidateScope(accountScope, operations);
-			};
-			invalidateStream("notifications.list", "notifications.count");
-			const offNotification = stream.on("notification", () => invalidateStream("notifications.list", "notifications.count"));
-			const offUnreadCount = stream.on("unreadCount", () => invalidateStream("notifications.count"));
-			return () => {
-				offNotification();
-				offUnreadCount();
-			};
+		attachNotificationEvents(stream) {
+			if (!stream || typeof stream.use !== "function" || typeof stream.getAuthIdentity !== "function" || typeof stream.getAuthScope !== "function" || typeof stream.baseUrl !== "string") throw new CacheError("attachNotificationEvents() принимает канал itd.notifications.events");
+			invalidateNotificationStream(stream, "notifications.list", "notifications.count");
+			return stream.use(notificationMiddleware);
 		},
 		install({ operations, baseUrl, getAuthIdentity, getAuthScope }) {
 			installationSequence += 1;
-			operations.use(createTransformer(installationSequence, baseUrl, getAuthIdentity, getAuthScope));
+			operations.use(createTransformer(installationSequence, baseUrl, getAuthIdentity, getAuthScope, operations.get));
 		}
 	};
 }
 //#endregion
 exports.CACHE_OPERATIONS = CACHE_OPERATIONS;
 exports.CacheError = CacheError;
+exports.CacheInvalidation = CacheInvalidation;
 exports.CacheModes = CacheModes;
+exports.CachePolicyKind = CachePolicyKind;
+exports.CachePolicyScope = CachePolicyScope;
 exports.buildCacheKey = buildCacheKey;
 exports.cache = cache;
 exports.cacheOperation = cacheOperation;