@quark-fw/cache 0.1.18

package/README.md

@@ -0,0 +1,38 @@
+# @quark-fw/cache
+
+Read-through cache for Quark apps on top of the Redis plugin: cache a fetcher result under a key, attach tags, invalidate by tag from any instance.
+
+## Install
+
+```sh
+npm i @quark-fw/cache
+```
+
+Peers: `@quark-fw/core`, `@quark-fw/plugin-redis`, `ioredis`.
+
+## Usage
+
+```ts
+import "@quark-fw/plugin-redis";
+import "@quark-fw/cache"; // registers the plugin, provides quark.cache
+
+// in a tRPC procedure
+const city = await quark.cache.get(
+  cacheKey("geo.city", input), // stable key from name + args
+  () => loadCity(input.slug), // runs only on a miss
+  { ttl: 600, tags: ["geo"] }, // seconds; tags for invalidation
+);
+
+// after an admin edit or a parser import
+await quark.cache.invalidate("geo", "listings");
+```
+
+- Values go through JSON: a `Date` comes back as a string (the same shape the tRPC client sees), on the first call too.
+- Concurrent misses for one key share a single fetcher call in the process.
+- Tags live in Redis, so invalidation reaches every instance.
+- A Redis failure never fails the request: the fetcher runs and the error goes to `onError` (console by default).
+- Env: `CACHE_PREFIX` (default `quark:cache:`), `CACHE_TTL` (default 600 s), `CACHE_DISABLED=1` to bypass.
+
+`QuarkCache` and `cacheKey` are exported for use outside the plugin (scripts, workers): `new QuarkCache({ client: () => redis })`.
+
+Part of the [Quark framework](https://www.npmjs.com/package/@quark-fw/core).

package/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "@quark-fw/cache",
+	"version": "0.1.18",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"type": "module",
+	"scripts": {
+		"build": "echo raw-src package, no build",
+		"test": "vitest run"
+	},
+	"files": [
+		"src"
+	],
+	"keywords": [
+		"quark",
+		"cache",
+		"redis"
+	],
+	"author": "",
+	"license": "ISC",
+	"description": "Redis-backed read-through cache with tag invalidation for the Quark framework (published as raw TS sources; consumers run tsx)",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@quark-fw/plugin": "0.1.18"
+	},
+	"peerDependencies": {
+		"@quark-fw/core": "0.1.18",
+		"@quark-fw/plugin-redis": "0.1.18",
+		"ioredis": "^5.9.3"
+	},
+	"devDependencies": {
+		"vitest": "^5.0.0"
+	}
+}

package/src/QuarkCache.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test, vi } from "vitest";
+import type { Redis } from "ioredis";
+import { cacheKey, QuarkCache } from "./QuarkCache.js";
+
+// Фейковый ioredis: ровно те команды, которыми пользуется кэш
+function fakeRedis() {
+	const store = new Map<string, string>();
+	const sets = new Map<string, Set<string>>();
+	const client = {
+		get: vi.fn(async (key: string) => store.get(key) ?? null),
+		set: vi.fn(async (key: string, value: string) => {
+			store.set(key, value);
+			return "OK";
+		}),
+		del: vi.fn(async (...keys: string[]) => {
+			let n = 0;
+			for (const key of keys) {
+				if (store.delete(key)) n++;
+				if (sets.delete(key)) n++;
+			}
+			return n;
+		}),
+		sadd: vi.fn(async (key: string, member: string) => {
+			if (!sets.has(key)) sets.set(key, new Set());
+			sets.get(key)!.add(member);
+			return 1;
+		}),
+		smembers: vi.fn(async (key: string) => [...(sets.get(key) ?? [])]),
+		expire: vi.fn(async () => 1),
+		scan: vi.fn(async (_cursor: string, _m: string, pattern: string) => {
+			const prefix = pattern.replace(/\*$/, "");
+			return [
+				"0",
+				[...store.keys(), ...sets.keys()].filter((k) =>
+					k.startsWith(prefix),
+				),
+			];
+		}),
+	};
+	return { client: client as unknown as Redis, store, sets };
+}
+
+describe("QuarkCache", () => {
+	test("промах зовёт fetcher один раз, попадание — из Redis, Date становится строкой", async () => {
+		const { client } = fakeRedis();
+		const cache = new QuarkCache({ client: () => client, prefix: "t:" });
+		const fetcher = vi.fn(async () => ({
+			at: new Date("2026-01-01T00:00:00Z"),
+			n: 1,
+		}));
+
+		const first = await cache.get("a", fetcher);
+		const second = await cache.get("a", fetcher);
+
+		expect(fetcher).toHaveBeenCalledTimes(1);
+		expect(first).toEqual({ at: "2026-01-01T00:00:00.000Z", n: 1 });
+		expect(second).toEqual(first);
+		expect(client.set).toHaveBeenCalledWith(
+			"t:a",
+			JSON.stringify({ at: "2026-01-01T00:00:00.000Z", n: 1 }),
+			"EX",
+			600,
+		);
+	});
+
+	test("параллельные промахи одного ключа делят один fetcher", async () => {
+		const { client } = fakeRedis();
+		const cache = new QuarkCache({ client: () => client });
+		let calls = 0;
+		const fetcher = () =>
+			new Promise<number>((resolve) => {
+				calls++;
+				setTimeout(() => resolve(42), 10);
+			});
+
+		const [a, b, c] = await Promise.all([
+			cache.get("k", fetcher),
+			cache.get("k", fetcher),
+			cache.get("k", fetcher),
+		]);
+
+		expect([a, b, c]).toEqual([42, 42, 42]);
+		expect(calls).toBe(1);
+	});
+
+	test("invalidate по тегу удаляет только помеченные ключи", async () => {
+		const { client, store } = fakeRedis();
+		const cache = new QuarkCache({ client: () => client, prefix: "t:" });
+		await cache.get("listings:1", async () => 1, { tags: ["listings"] });
+		await cache.get("listings:2", async () => 2, {
+			tags: ["listings", "geo"],
+		});
+		await cache.get("cities", async () => 3, { tags: ["geo"] });
+		await cache.get("plain", async () => 4);
+
+		const removed = await cache.invalidate("listings");
+
+		expect(removed).toBe(2);
+		expect(store.has("t:listings:1")).toBe(false);
+		expect(store.has("t:listings:2")).toBe(false);
+		expect(store.has("t:cities")).toBe(true);
+		expect(store.has("t:plain")).toBe(true);
+	});
+
+	test("clear удаляет всё с префиксом", async () => {
+		const { client, store } = fakeRedis();
+		const cache = new QuarkCache({ client: () => client, prefix: "t:" });
+		await cache.get("a", async () => 1, { tags: ["x"] });
+		await cache.get("b", async () => 2);
+		store.set("other:z", "1");
+
+		await cache.clear();
+
+		expect([...store.keys()]).toEqual(["other:z"]);
+	});
+
+	test("сбой Redis не валит запрос: значение из источника, ошибка в onError", async () => {
+		const broken = {
+			get: async () => {
+				throw new Error("ECONNREFUSED");
+			},
+			set: async () => {
+				throw new Error("ECONNREFUSED");
+			},
+		} as unknown as Redis;
+		const onError = vi.fn();
+		const cache = new QuarkCache({ client: () => broken, onError });
+
+		const value = await cache.get("k", async () => ({ ok: true }));
+
+		expect(value).toEqual({ ok: true });
+		expect(onError).toHaveBeenCalled();
+	});
+
+	test("disabled: всегда к источнику, Redis не трогается", async () => {
+		const { client } = fakeRedis();
+		const cache = new QuarkCache({ client: () => client, disabled: true });
+		const fetcher = vi.fn(async () => 1);
+		await cache.get("k", fetcher);
+		await cache.get("k", fetcher);
+		expect(fetcher).toHaveBeenCalledTimes(2);
+		expect(client.get).not.toHaveBeenCalled();
+	});
+
+	test("cacheKey стабилен к порядку полей и игнорирует undefined", () => {
+		expect(cacheKey("geo.city", { slug: "tbilisi", page: 1 })).toBe(
+			cacheKey("geo.city", { page: 1, slug: "tbilisi", x: undefined }),
+		);
+		expect(cacheKey("geo.cities")).toBe("geo.cities");
+	});
+});

package/src/QuarkCache.ts

@@ -0,0 +1,226 @@
+import type { Redis } from "ioredis";
+
+/**
+ * Значение, прошедшее через JSON: Date становится строкой, undefined
+ * пропадает. Кэш отдаёт именно такую форму — ту же, что получает клиент tRPC.
+ */
+export type Jsonified<T> = T extends Date
+	? string
+	: T extends (infer U)[]
+		? Jsonified<U>[]
+		: T extends object
+			? { [K in keyof T]: Jsonified<T[K]> }
+			: T;
+
+export type CacheOptions = {
+	/** время жизни в секундах (по умолчанию defaultTtl конструктора) */
+	ttl?: number;
+	/**
+	 * Теги зависимости: invalidate(tag) удаляет все ключи, записанные с
+	 * этим тегом. Теги живут в Redis, поэтому инвалидация видна всем
+	 * инстансам приложения, а не только тому, кто писал.
+	 */
+	tags?: string[];
+};
+
+export type QuarkCacheConfig = {
+	/** клиент берётся лениво: плагин redis может быть ещё не готов */
+	client: () => Redis;
+	/** префикс ключей в Redis */
+	prefix?: string;
+	/** TTL по умолчанию, сек */
+	defaultTtl?: number;
+	/** выключатель: при true всегда идёт к источнику (dev, тесты) */
+	disabled?: boolean;
+	/** куда писать о сбоях Redis (по умолчанию console.error) */
+	onError?: (error: unknown) => void;
+};
+
+// Минимальный набор команд ioredis, которым пользуется кэш: так тесты
+// подсовывают фейковый клиент, а тип не тянет весь Redis.
+type RedisLike = Pick<
+	Redis,
+	"get" | "set" | "del" | "sadd" | "smembers" | "expire" | "scan"
+>;
+
+/**
+ * Read-through кэш поверх Redis (идея UglyCache из parkmobile).
+ *
+ * `get(key, fetcher, { ttl, tags })` отдаёт значение из Redis либо вызывает
+ * fetcher, кладёт результат и привязывает ключ к тегам. Параллельные
+ * вызовы одного ключа в одном процессе делят один fetcher. Сбой Redis не
+ * валит запрос: значение берётся из источника, ошибка уходит в onError.
+ */
+export class QuarkCache {
+	private readonly client: () => RedisLike;
+	private readonly prefix: string;
+	private readonly defaultTtl: number;
+	private readonly disabled: boolean;
+	private readonly onError: (error: unknown) => void;
+	// ключ → промис в полёте: дедупликация одновременных промахов
+	private readonly inflight = new Map<string, Promise<unknown>>();
+
+	constructor({
+		client,
+		prefix = "quark:cache:",
+		defaultTtl = 600,
+		disabled = false,
+		onError = (error) => console.error("[cache]", error),
+	}: QuarkCacheConfig) {
+		this.client = client as () => RedisLike;
+		this.prefix = prefix;
+		this.defaultTtl = defaultTtl;
+		this.disabled = disabled;
+		this.onError = onError;
+	}
+
+	private dataKey(key: string) {
+		return `${this.prefix}${key}`;
+	}
+
+	private tagKey(tag: string) {
+		return `${this.prefix}tag:${tag}`;
+	}
+
+	/** Значение по ключу или undefined (промах, выключенный кэш, сбой Redis). */
+	async peek<T>(key: string): Promise<Jsonified<T> | undefined> {
+		if (this.disabled) return undefined;
+		try {
+			const raw = await this.client().get(this.dataKey(key));
+			return raw === null ? undefined : (JSON.parse(raw) as Jsonified<T>);
+		} catch (error) {
+			this.onError(error);
+			return undefined;
+		}
+	}
+
+	/** Кладёт значение и привязывает ключ к тегам. */
+	async set<T>(
+		key: string,
+		value: T,
+		{ ttl = this.defaultTtl, tags = [] }: CacheOptions = {},
+	): Promise<void> {
+		if (this.disabled) return;
+		try {
+			const client = this.client();
+			const dataKey = this.dataKey(key);
+			await client.set(dataKey, JSON.stringify(value ?? null), "EX", ttl);
+			for (const tag of tags) {
+				const tagKey = this.tagKey(tag);
+				await client.sadd(tagKey, dataKey);
+				// набор тега живёт не меньше самого длинного значения в нём,
+				// иначе инвалидация потеряла бы ещё живые ключи
+				await client.expire(tagKey, Math.max(ttl, this.defaultTtl) * 2);
+			}
+		} catch (error) {
+			this.onError(error);
+		}
+	}
+
+	/**
+	 * Read-through: значение из кэша либо из fetcher (с записью в кэш).
+	 * Результат — JSON-форма значения, даже при промахе: иначе первый
+	 * ответ (с Date) отличался бы от последующих (со строками).
+	 */
+	async get<T>(
+		key: string,
+		fetcher: () => Promise<T> | T,
+		options: CacheOptions = {},
+	): Promise<Jsonified<T>> {
+		const cached = await this.peek<T>(key);
+		if (cached !== undefined) return cached;
+
+		const pending = this.inflight.get(key);
+		if (pending) return pending as Promise<Jsonified<T>>;
+
+		const promise = (async () => {
+			const value = await fetcher();
+			await this.set(key, value, options);
+			return JSON.parse(JSON.stringify(value ?? null)) as Jsonified<T>;
+		})();
+		this.inflight.set(key, promise);
+		try {
+			return await promise;
+		} finally {
+			this.inflight.delete(key);
+		}
+	}
+
+	/** Удаляет ключ (без тегов — они зачистятся при инвалидации или по TTL). */
+	async delete(key: string): Promise<void> {
+		if (this.disabled) return;
+		try {
+			await this.client().del(this.dataKey(key));
+		} catch (error) {
+			this.onError(error);
+		}
+	}
+
+	/** Удаляет все ключи, записанные с любым из тегов. Возвращает число удалённых. */
+	async invalidate(...tags: string[]): Promise<number> {
+		if (this.disabled || tags.length === 0) return 0;
+		try {
+			const client = this.client();
+			let removed = 0;
+			for (const tag of tags) {
+				const tagKey = this.tagKey(tag);
+				const keys = await client.smembers(tagKey);
+				if (keys.length) removed += await client.del(...keys);
+				await client.del(tagKey);
+			}
+			return removed;
+		} catch (error) {
+			this.onError(error);
+			return 0;
+		}
+	}
+
+	/** Полная очистка кэша (все ключи с префиксом), через SCAN — без блокировки Redis. */
+	async clear(): Promise<number> {
+		if (this.disabled) return 0;
+		try {
+			const client = this.client();
+			let cursor = "0";
+			let removed = 0;
+			do {
+				const [next, keys] = await client.scan(
+					cursor,
+					"MATCH",
+					`${this.prefix}*`,
+					"COUNT",
+					500,
+				);
+				cursor = next;
+				if (keys.length) removed += await client.del(...keys);
+			} while (cursor !== "0");
+			return removed;
+		} catch (error) {
+			this.onError(error);
+			return 0;
+		}
+	}
+}
+
+/** Ключ кэша из имени и аргументов: стабильная сериализация с сортировкой полей. */
+export function cacheKey(name: string, args?: unknown): string {
+	if (args === undefined) return name;
+	const stable = (value: unknown): unknown =>
+		Array.isArray(value)
+			? value.map(stable)
+			: value && typeof value === "object"
+				? Object.fromEntries(
+						Object.keys(value as Record<string, unknown>)
+							.sort()
+							.filter(
+								(k) =>
+									(value as Record<string, unknown>)[k] !==
+									undefined,
+							)
+							.map((k) => [
+								k,
+								stable((value as Record<string, unknown>)[k]),
+							]),
+					)
+				: value;
+	return `${name}:${JSON.stringify(stable(args))}`;
+}

package/src/global.d.ts

@@ -0,0 +1,11 @@
+import "@quark-fw/core/src/global.d.ts";
+import type { QuarkCache } from "./QuarkCache.js";
+
+export {};
+
+declare global {
+	interface Quark {
+		/** read-through кэш в Redis с инвалидацией по тегам */
+		cache: QuarkCache;
+	}
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+import { QuarkPlugin } from "@quark-fw/plugin";
+import {} from "@quark-fw/plugin-redis/src/global.js";
+import {} from "@quark-fw/cache/src/global.js";
+import { QuarkCache } from "./QuarkCache.js";
+
+export { QuarkCache, cacheKey } from "./QuarkCache.js";
+export type {
+	CacheOptions,
+	Jsonified,
+	QuarkCacheConfig,
+} from "./QuarkCache.js";
+
+// Плагин: quark.cache поверх клиента plugin-redis. Параметры — из окружения:
+// CACHE_PREFIX (ключи), CACHE_TTL (сек), CACHE_DISABLED=1 (всегда к источнику).
+await quark.registerPlugin({
+	name: "cache",
+	dependsOn: ["redis"],
+	extend(quark) {
+		quark.cache = new QuarkCache({
+			client: () => quark.redis.client.value,
+			prefix: process.env.CACHE_PREFIX || "quark:cache:",
+			defaultTtl: Number(process.env.CACHE_TTL) || 600,
+			disabled: process.env.CACHE_DISABLED === "1",
+		});
+	},
+} satisfies QuarkPlugin);