cvc-catalog-sync-plugin 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Контракт каркаса 2.0.0 для портов трёх функций.
3
+ *
4
+ * Читают: catalog-porter (lib/catalog-sync.js), ports-porter
5
+ * (lib/coefficients.js, lib/balance.js), client-builder (src/client/**).
6
+ * Держит его architect; менять сигнатуры — только через lead.
7
+ *
8
+ * @module cvc-catalog-sync-plugin/lib/CONTRACT
9
+ */
10
+
11
+ /**
12
+ * `deps` каждой функции — замороженный объект:
13
+ *
14
+ * - `ctx` — контекст плагина;
15
+ * - `config(): NormalizedConfig` — актуальный нормализованный конфиг 2.x
16
+ * (те же группы, что в схеме: features/providers/catalog/coefficients/balance);
17
+ * - `features(): {catalogSync, coefficients, balance}` — переключатели;
18
+ * - `log(level, message)` — 'info' | 'warn' | 'error', префикс уже внутри;
19
+ * - `route(path, handler): () => void` — подмаршрут `/cvc/<path>` в общей
20
+ * таблице; handler(req, res) как у Node HTTP, лучше `async`; выключение
21
+ * функции снимает маршрут само;
22
+ * - `http` — `lib/http.js`: `sendJson`, `readJsonBody`, `methodNotAllowed`,
23
+ * `isJsonRequest`, `isCrossSite`, `HttpError`, `BODY_LIMIT`, `CVC_PREFIX`;
24
+ * - `api` — `lib/cvc-api.js`: `fetchModels`, `fetchBalance`, `fetchLevels`,
25
+ * `parseReasoningLevels`, `apiRoot`, `CvcApiError`;
26
+ * - `providers` — `lib/providers.js`: `resolveRoutes`, `resolveKey`,
27
+ * `apiKeyFor`, `pickRoute`, `hostOf`, `matchesProvider`;
28
+ * - `cache` — общий кэш каталога `lib/cache.js` (`get({force})`, `refresh`,
29
+ * `peek`, `clear`, `ttl`); данные — результат `loadCatalog()`:
30
+ * `{ models, providers: [{provider, displayName}], fetchedAt }`;
31
+ * - `store` — реестр состояния `lib/state.js` (`setLastRun`, `setRunning`,
32
+ * `setError`, `lastRun`, `snapshot`);
33
+ * - `routes()` — маршруты CheapVibeCode по текущему конфигу
34
+ * (`[{provider, displayName, baseURL, apiKeyEnv, api, models, entryId}]`);
35
+ * - `key(ref)` — ключ по ссылке через credentials (пустая строка, если нет);
36
+ * - `apiKeyFor(route)` — имя записи ключа с учётом запасного имени;
37
+ * - `version`, `rowId` (см. `lib/state.js`, `index.js`).
38
+ *
39
+ * Правила:
40
+ * 1. `register(ctx, deps)` вызывается при включении функции, возвращает
41
+ * disposer; всё зарегистрированное (маршруты, таймеры, инструменты) снимается им.
42
+ * 2. `tool(deps)` возвращает описание инструмента DSH или `null`; индекс
43
+ * регистрирует его только при включённой функции.
44
+ * 3. Секреты: ключ не уходит ни в ответ маршрута, ни в текст ошибки — в
45
+ * браузер только `keySet: true|false`.
46
+ * 4. Конфиг читается только через `deps.config()`, не замыкается: правка
47
+ * настроек перемонтирует функцию без перезапуска плагина.
48
+ * 5. Время (таймеры) работает; после выключения функции таймеры сняты.
49
+ */
50
+ export const CONTRACT = 'lib/CONTRACT.js'
51
+
52
+ /**
53
+ * Маршруты, которые каркас уже держит, и их владельцы.
54
+ * Заглушки отвечают 501 (run) или пустой заготовкой; порт заменяет тела.
55
+ */
56
+ export const ROUTES = Object.freeze({
57
+ state: 'lib/state.js (каркас, установлен index.js)',
58
+ config: 'lib/state.js (каркас, установлен index.js)',
59
+ health: 'index.js (каркас)',
60
+ run: 'lib/catalog-sync.js: POST {action: plan|apply, force?}',
61
+ coefficients: 'lib/coefficients.js: GET',
62
+ balance: 'lib/balance.js: GET',
63
+ })
package/lib/balance.js ADDED
@@ -0,0 +1,412 @@
1
+ /**
2
+ * Баланс ключа CheapVibeCode: снимок по всем маршрутам, дельта «с прошлого
3
+ * замера» и инструмент `cvc_balance`.
4
+ *
5
+ * Запрос идёт через `deps.api.fetchBalance({ baseURL, key, timeoutMs,
6
+ * fetchImpl })` — тот единственный модуль, который говорит с провайдером:
7
+ * таймаут, разбор `token_balance`, ошибка с кодом и вырезание ключа из текста.
8
+ * `fetchImpl` инъектируется (каркас передаёт его в `deps`, в тестах — подделка),
9
+ * поэтому в самом модуле сети нет по построению.
10
+ *
11
+ * Обнаружение провайдеров перенесено в `lib/providers.js` каркаса, и это
12
+ * осознанное изменение против 1.1.0: там поиск шёл через
13
+ * `llm.listConfigurableProviders()` и `settings.describe()`, потому что иначе
14
+ * до строки композиции было не добраться. В 2.0.0 маршруты провайдера — это
15
+ * запись профильного патча, и каркас читает её напрямую
16
+ * (`configEditor.entries()`), поэтому здесь достаточно `deps.routes()`.
17
+ *
18
+ * Ключ остаётся на хосте: в ответе только `keySet: true|false`. Текст ошибки
19
+ * составляется из кода и статуса, без тела апстрима, — тело может содержать
20
+ * что угодно, включая ключ.
21
+ *
22
+ * @module cvc-catalog-sync-plugin/lib/balance
23
+ */
24
+
25
+ /** Путь маршрута в общей таблице каркаса. */
26
+ export const ROUTE_PATH = 'balance'
27
+
28
+ /** Имя инструмента, который каркас регистрирует вместе с функцией. */
29
+ export const TOOL_NAME = 'cvc_balance'
30
+
31
+ /**
32
+ * Нормализовать baseURL маршрута до `apiRoot`.
33
+ *
34
+ * Маршрут задаётся OpenAI-совместимой базой (`…/v1`), а `/v1/balance` живёт
35
+ * уровнем выше, поэтому хвостовой `/v1` отбрасывается. В ответе показывается
36
+ * именно этот адрес: он без секрета и совпадает с тем, куда ушёл запрос.
37
+ *
38
+ * @param {unknown} baseURL — настроенный `baseURL` маршрута.
39
+ * @returns {string}
40
+ */
41
+ export function apiRootOf(baseURL) {
42
+ return String(baseURL ?? '').trim().replace(/\/+$/, '').replace(/\/v1$/, '')
43
+ }
44
+
45
+ /**
46
+ * Текст ошибки одного провайдера: только код и, если он пришёл, статус HTTP.
47
+ *
48
+ * Тело ответа апстрима сюда намеренно не попадает: оно может содержать ключ
49
+ * или эхо заголовка `Authorization`, а это панель показывает пользователю.
50
+ *
51
+ * @param {unknown} error — ошибка `CvcApiError` или любая другая.
52
+ * @returns {string}
53
+ */
54
+ export function balanceErrorText(error) {
55
+ const source = /** @type {any} */ (error)
56
+ const code = typeof source?.code === 'string' && source.code.length > 0 ? source.code : 'unavailable'
57
+ const status = source?.status
58
+ return typeof status === 'number' && Number.isFinite(status) ? `${code} (HTTP ${status})` : code
59
+ }
60
+
61
+ /**
62
+ * Учёт прошлого замера: «сколько юнитов ушло с прошлого раза».
63
+ *
64
+ * Живёт в памяти процесса и теряется при перезапуске — после перезапуска
65
+ * прошлого замера нет, и вычитать не из чего. Рост баланса (пополнение) не
66
+ * считается расходом и даёт `null`, а не отрицательное число. Прошлый замер
67
+ * обновляется только успешным чтением: ошибка апстрима не должна стирать базу
68
+ * для следующей дельты. Ключ учёта — `provider`, поэтому два маршрута с одним
69
+ * id получают общую строку истории (как и в 1.1.0).
70
+ *
71
+ * @returns {{ observe: (provider: string, units: number) => number | null, reset: () => void, peek: () => Map<string, number> }}
72
+ */
73
+ export function createBalanceTracker() {
74
+ /** @type {Map<string, number>} */
75
+ const lastBalanceByProvider = new Map()
76
+ return {
77
+ /**
78
+ * Отметить замер и посчитать расход с прошлого.
79
+ * @param {string} provider
80
+ * @param {number} units
81
+ * @returns {number | null} расход или `null`, если сравнить не с чем.
82
+ */
83
+ observe(provider, units) {
84
+ const previous = lastBalanceByProvider.get(provider)
85
+ lastBalanceByProvider.set(provider, units)
86
+ if (typeof previous !== 'number' || !Number.isFinite(previous)) return null
87
+ return units < previous ? previous - units : null
88
+ },
89
+ reset() {
90
+ lastBalanceByProvider.clear()
91
+ },
92
+ peek() {
93
+ return lastBalanceByProvider
94
+ },
95
+ }
96
+ }
97
+
98
+ /**
99
+ * Строка ответа по одному маршруту.
100
+ *
101
+ * Ошибка маршрута (нет ключа, отказ апстрима, нечитаемый ответ) остаётся его
102
+ * собственной строкой: остальные маршруты отвечают, а прошлый замер не
103
+ * перезаписывается.
104
+ *
105
+ * @param {ReturnType<typeof createBalanceTracker>} tracker — учёт прошлых замеров.
106
+ * @param {object} deps — зависимости каркаса.
107
+ * @param {{ provider?: unknown, displayName?: unknown, baseURL?: unknown, apiKeyEnv?: unknown }} route — маршрут CVC.
108
+ * @returns {Promise<{provider: string, displayName: string, baseURL: string, apiKeyEnv: string, keySet: boolean, balanceUnits: number | null, spentSinceLast: number | null, balanceError: string}>}
109
+ */
110
+ export async function readRoute(tracker, deps, route) {
111
+ const profile = route !== null && typeof route === 'object' ? route : {}
112
+ const provider = typeof profile.provider === 'string' ? profile.provider : ''
113
+ const apiKeyEnv = deps.apiKeyFor(profile)
114
+ const row = {
115
+ provider,
116
+ displayName: typeof profile.displayName === 'string' && profile.displayName.trim().length > 0
117
+ ? profile.displayName.trim()
118
+ : provider,
119
+ baseURL: apiRootOf(profile.baseURL),
120
+ apiKeyEnv,
121
+ keySet: false,
122
+ balanceUnits: null,
123
+ spentSinceLast: null,
124
+ balanceError: '',
125
+ }
126
+
127
+ let key = ''
128
+ try {
129
+ key = await deps.key(apiKeyEnv)
130
+ } catch {
131
+ // Сервис credentials недоступен — это «ключа нет», а не падение панели.
132
+ key = ''
133
+ }
134
+ if (typeof key !== 'string' || key.trim().length === 0) {
135
+ row.balanceError = `Ключ не найден: ${apiKeyEnv || '(apiKeyEnv не задан)'}`
136
+ return row
137
+ }
138
+ row.keySet = true
139
+
140
+ let units
141
+ try {
142
+ const result = await deps.api.fetchBalance({
143
+ baseURL: profile.baseURL,
144
+ key,
145
+ timeoutMs: deps.config().providers.timeoutMs,
146
+ fetchImpl: typeof deps.fetchImpl === 'function' ? deps.fetchImpl : undefined,
147
+ })
148
+ units = result?.units
149
+ } catch (error) {
150
+ row.balanceError = balanceErrorText(error)
151
+ return row
152
+ }
153
+
154
+ if (typeof units !== 'number' || !Number.isFinite(units)) {
155
+ row.balanceError = 'invalid-payload'
156
+ return row
157
+ }
158
+
159
+ row.balanceUnits = units
160
+ row.spentSinceLast = tracker.observe(provider, units)
161
+ return row
162
+ }
163
+
164
+ /**
165
+ * Собрать снимок баланса по всем маршрутам CheapVibeCode текущего конфига.
166
+ *
167
+ * Маршруты читаются последовательно: ключей обычно один-два, а параллельные
168
+ * запросы к одному хосту с разными ключами ничего не ускоряют. Ошибка чтения
169
+ * маршрутов не бросает — снимок остаётся пустым, а причина едет в поле `note`,
170
+ * чтобы панель деградировала, а не падала с 500.
171
+ *
172
+ * @param {object} deps — зависимости каркаса.
173
+ * @param {ReturnType<typeof createBalanceTracker>} tracker — учёт прошлых замеров.
174
+ * @returns {Promise<{providers: Array<object>, fetchedAt: string, note?: string}>}
175
+ */
176
+ export async function snapshot(deps, tracker) {
177
+ let routes = []
178
+ let note = ''
179
+ try {
180
+ const found = deps.routes()
181
+ if (Array.isArray(found)) routes = found
182
+ } catch (error) {
183
+ note = 'provider routes are unreadable'
184
+ deps.log('warn', `balance: provider routes are unreadable (${typeof /** @type {any} */ (error)?.code === 'string' ? /** @type {any} */ (error).code : 'unavailable'})`)
185
+ }
186
+ const providers = []
187
+ for (const route of routes) {
188
+ providers.push(await readRoute(tracker, deps, route))
189
+ }
190
+ const payload = { providers, fetchedAt: new Date().toISOString() }
191
+ if (note.length > 0) payload.note = note
192
+ return payload
193
+ }
194
+
195
+ /**
196
+ * Состояние функции на набор `deps`: учёт замеров и последний снимок.
197
+ *
198
+ * `deps` — замороженный объект, созданный один раз на процесс плагина
199
+ * (`index.js`, `createFeatureDeps`), поэтому `WeakMap` по нему даёт ровно
200
+ * «память процесса»: функция может быть выключена и включена заново, но
201
+ * прошлый замер и последнее чтение остаются. В тестах каждый набор `deps`
202
+ * получает своё состояние, поэтому кейсы не протекают друг в друга.
203
+ *
204
+ * @type {WeakMap<object, { tracker: ReturnType<typeof createBalanceTracker>, last: { providers: Array<object>, fetchedAt: string } | null, inflight: Promise<any> | null }>}
205
+ */
206
+ const FEATURE_STATE = new WeakMap()
207
+
208
+ /**
209
+ * Состояние функции для набора `deps`; создаётся при первом обращении.
210
+ * @param {object} deps
211
+ */
212
+ export function stateFor(deps) {
213
+ let state = FEATURE_STATE.get(deps)
214
+ if (state === undefined) {
215
+ state = { tracker: createBalanceTracker(), last: null, inflight: null }
216
+ FEATURE_STATE.set(deps, state)
217
+ }
218
+ return state
219
+ }
220
+
221
+ /**
222
+ * Прочитать снимок, не открывая второе чтение поверх идущего.
223
+ *
224
+ * Два «Обновить» подряд (две вкладки, кнопка и панель) получают один и тот же
225
+ * ответ: лишний запрос к апстриму — лишняя квота, а два параллельных замера
226
+ * посчитали бы дельту от одной и той же базы дважды.
227
+ *
228
+ * @param {object} deps
229
+ * @param {ReturnType<typeof stateFor>} state
230
+ * @returns {Promise<{providers: Array<object>, fetchedAt: string}>}
231
+ */
232
+ export function readSnapshot(deps, state) {
233
+ if (state.inflight !== null) return state.inflight
234
+ const run = (async () => {
235
+ try {
236
+ const payload = await snapshot(deps, state.tracker)
237
+ state.last = payload
238
+ return payload
239
+ } finally {
240
+ if (state.inflight === run) state.inflight = null
241
+ }
242
+ })()
243
+ state.inflight = run
244
+ return run
245
+ }
246
+
247
+ /**
248
+ * Подключить функцию баланса: маршрут `GET /cvc/balance`.
249
+ *
250
+ * @param {import('@deepseek-ai/cordis').Context} ctx — контекст плагина.
251
+ * @param {object} deps — общие зависимости каркаса (см. `lib/CONTRACT.js`).
252
+ * @returns {() => void} disposer, снимающий маршрут.
253
+ */
254
+ export function register(ctx, deps) {
255
+ const state = stateFor(deps)
256
+ const disposeRoute = deps.route(ROUTE_PATH, async (req, res) => {
257
+ if (String(req.method ?? 'GET').toUpperCase() !== 'GET') {
258
+ deps.http.methodNotAllowed(res, ['GET'])
259
+ return
260
+ }
261
+ const payload = await readSnapshot(deps, state)
262
+ const failed = payload.providers.filter((row) => row.balanceError.length > 0)
263
+ if (failed.length > 0) {
264
+ // В лог уходят только id маршрутов: тел ответа апстрима в логе быть не должно.
265
+ deps.log('warn', `balance: ${failed.length} of ${payload.providers.length} route(s) failed (${failed.map((row) => row.provider || '?').join(', ')})`)
266
+ }
267
+ deps.http.sendJson(res, 200, payload)
268
+ })
269
+
270
+ return () => {
271
+ disposeRoute()
272
+ }
273
+ }
274
+
275
+ /**
276
+ * Значение инструмента `cvc_balance` (`action: 'status'`).
277
+ *
278
+ * Сети не касается: отдаёт последний снимок, который снял маршрут. Маршруты,
279
+ * которых в текущем конфиге больше нет, из ответа убираются — панель не должна
280
+ * показывать баланс удалённого провайдера.
281
+ *
282
+ * В строках оставлено только то, что нужно агенту для ответа на вопрос «сколько
283
+ * осталось»: `provider`, `displayName`, `keySet`, `balanceUnits`,
284
+ * `spentSinceLast`, `balanceError`. `baseURL` и `apiKeyEnv` сюда не попадают:
285
+ * это подробности конфигурации, а не состояние ключа.
286
+ *
287
+ * @param {object} deps
288
+ * @param {ReturnType<typeof stateFor>} state
289
+ * @param {unknown} args — аргументы инструмента (`{action?: 'status'}`).
290
+ * @returns {object} значение инструмента.
291
+ */
292
+ export function toolStatus(deps, state, args) {
293
+ const action = args !== null && typeof args === 'object' ? /** @type {any} */ (args).action : undefined
294
+ if (action !== undefined && action !== 'status') {
295
+ return {
296
+ ok: false,
297
+ action: typeof action === 'string' ? action : 'unknown',
298
+ error: 'cvc_balance supports only action "status": it returns the last readings and does not spend an API request',
299
+ }
300
+ }
301
+ if (state.last === null) {
302
+ return {
303
+ ok: true,
304
+ action: 'status',
305
+ providers: [],
306
+ fetchedAt: null,
307
+ note: 'No balance reading yet. Open the CVC balance panel, or read GET /cvc/balance, then call this tool again.',
308
+ }
309
+ }
310
+ const current = new Set()
311
+ try {
312
+ for (const route of deps.routes()) {
313
+ if (typeof route?.provider === 'string') current.add(route.provider)
314
+ }
315
+ } catch {
316
+ // Нечитаемые маршруты: показываем последний снимок как есть.
317
+ }
318
+ const rows = current.size === 0
319
+ ? state.last.providers
320
+ : state.last.providers.filter((row) => current.has(row.provider))
321
+ const providers = rows.map((row) => ({
322
+ provider: row.provider,
323
+ displayName: row.displayName,
324
+ keySet: row.keySet,
325
+ balanceUnits: row.balanceUnits,
326
+ spentSinceLast: row.spentSinceLast,
327
+ balanceError: row.balanceError,
328
+ }))
329
+ return { ok: true, action: 'status', providers, fetchedAt: state.last.fetchedAt }
330
+ }
331
+
332
+ /**
333
+ * Текст инструмента для модели: «провайдер — остаток».
334
+ *
335
+ * @param {any} value — результат `execute`.
336
+ * @returns {string}
337
+ */
338
+ export function renderToolText(value) {
339
+ if (value?.ok !== true) return String(value?.error ?? 'balance is unavailable')
340
+ const rows = Array.isArray(value.providers) ? value.providers : []
341
+ if (rows.length === 0) {
342
+ return typeof value.note === 'string' && value.note.length > 0
343
+ ? value.note
344
+ : 'No CheapVibeCode balance reading yet.'
345
+ }
346
+ const lines = rows.map((row) => {
347
+ const units = typeof row.balanceUnits === 'number' ? row.balanceUnits : 'no reading'
348
+ const spent = typeof row.spentSinceLast === 'number' && row.spentSinceLast > 0 ? `, spent ${row.spentSinceLast}` : ''
349
+ return `${row.displayName ?? row.provider}: ${units}${spent}`
350
+ })
351
+ const at = typeof value.fetchedAt === 'string' ? ` (last readings at ${value.fetchedAt})` : ''
352
+ return `${lines.join('\n')}${at}`
353
+ }
354
+
355
+ /**
356
+ * Описание инструмента `cvc_balance` (только чтение).
357
+ *
358
+ * Форма — `ToolDefinition` DSH: `name`, `description`, JSON Schema `parameters`,
359
+ * `output.schema` + `output.render`, `execute(args, exec)`. Действий записи у
360
+ * инструмента нет: маршрут баланса тоже только читает.
361
+ *
362
+ * @param {object} deps
363
+ * @returns {object}
364
+ */
365
+ export function tool(deps) {
366
+ const state = stateFor(deps)
367
+ return {
368
+ name: TOOL_NAME,
369
+ description: 'Return the last CheapVibeCode balance readings per provider without spending a request: remaining units and the spend since the previous reading. Read-only.',
370
+ parameters: {
371
+ type: 'object',
372
+ additionalProperties: false,
373
+ properties: {
374
+ action: {
375
+ type: 'string',
376
+ enum: ['status'],
377
+ description: 'Only "status": the cached readings from the last panel refresh.',
378
+ },
379
+ },
380
+ },
381
+ output: {
382
+ schema: {
383
+ type: 'object',
384
+ additionalProperties: false,
385
+ properties: {
386
+ ok: { type: 'boolean' },
387
+ action: { type: 'string' },
388
+ fetchedAt: { type: ['string', 'null'] },
389
+ providers: {
390
+ type: 'array',
391
+ items: {
392
+ type: 'object',
393
+ additionalProperties: false,
394
+ properties: {
395
+ provider: { type: 'string' },
396
+ displayName: { type: 'string' },
397
+ keySet: { type: 'boolean' },
398
+ balanceUnits: { type: ['number', 'null'] },
399
+ spentSinceLast: { type: ['number', 'null'] },
400
+ balanceError: { type: 'string' },
401
+ },
402
+ },
403
+ },
404
+ note: { type: 'string' },
405
+ error: { type: 'string' },
406
+ },
407
+ },
408
+ render: (_args, value) => [{ type: 'text', text: renderToolText(value) }],
409
+ },
410
+ execute: (args) => Promise.resolve(toolStatus(deps, state, args)),
411
+ }
412
+ }
package/lib/cache.js ADDED
@@ -0,0 +1,114 @@
1
+ /**
2
+ * Общий кэш каталога `GET /v1/models` на три функции плагина.
3
+ *
4
+ * Синхронизация каталога, коэффициенты и баланс читают один и тот же ответ,
5
+ * поэтому запрос к апстриму не дублируется. Поведение при ошибке: пока есть
6
+ * прошлый снимок, он отдаётся с `stale: true` и текстом ошибки; когда снимка
7
+ * ещё нет — ошибка пробрасывается.
8
+ *
9
+ * @module cvc-catalog-sync-plugin/lib/cache
10
+ */
11
+
12
+ /** TTL по умолчанию: 10 минут, как `coefficients.refreshMinutes`. */
13
+ export const DEFAULT_TTL_MS = 10 * 60 * 1000
14
+
15
+ /**
16
+ * Создать кэш каталога.
17
+ *
18
+ * `client` — асинхронная функция без аргументов, отдающая данные каталога;
19
+ * `ttlMs` — число или функция от текущего конфига (тогда TTL меняется вместе с
20
+ * настройками без пересоздания кэша).
21
+ *
22
+ * @param {{ client: () => Promise<any>, ttlMs?: number | (() => number), now?: () => number }} options
23
+ * @returns {{
24
+ * get: (options?: { force?: boolean }) => Promise<{ data: any, fetchedAt: number, stale: boolean, error: string, ageMs: number }>,
25
+ * refresh: () => Promise<{ data: any, fetchedAt: number, stale: boolean, error: string, ageMs: number }>,
26
+ * peek: () => { data: any, fetchedAt: number, ageMs: number } | null,
27
+ * clear: () => void,
28
+ * ttl: () => number,
29
+ * }}
30
+ */
31
+ export function createCatalogCache(options = {}) {
32
+ const { client } = options
33
+ if (typeof client !== 'function') throw new TypeError('createCatalogCache: client must be a function')
34
+ const now = typeof options.now === 'function' ? options.now : Date.now
35
+ const ttlSource = options.ttlMs
36
+
37
+ /** @type {{ data: any, fetchedAt: number } | null} */
38
+ let entry = null
39
+ /** @type {Promise<any> | null} */
40
+ let inflight = null
41
+ /** Поколение кэша: `clear()` отменяет право старых ответов записываться. */
42
+ let generation = 0
43
+
44
+ /** Действующий TTL в миллисекундах. */
45
+ function ttl() {
46
+ const requested = typeof ttlSource === 'function' ? ttlSource() : ttlSource
47
+ if (typeof requested !== 'number' || !Number.isFinite(requested) || requested <= 0) return DEFAULT_TTL_MS
48
+ return requested
49
+ }
50
+
51
+ /** Снимок текущего значения без сети. */
52
+ function peek() {
53
+ if (entry === null) return null
54
+ return { data: entry.data, fetchedAt: entry.fetchedAt, ageMs: Math.max(0, now() - entry.fetchedAt) }
55
+ }
56
+
57
+ /**
58
+ * Прочитать данные: из кэша, если снимок свежий, иначе из `client()`.
59
+ * @param {boolean} force
60
+ */
61
+ function load(force) {
62
+ const time = now()
63
+ if (!force && entry !== null && time - entry.fetchedAt < ttl()) {
64
+ return Promise.resolve({
65
+ data: entry.data,
66
+ fetchedAt: entry.fetchedAt,
67
+ stale: false,
68
+ error: '',
69
+ ageMs: Math.max(0, time - entry.fetchedAt),
70
+ })
71
+ }
72
+ if (inflight !== null) return inflight
73
+ const startedGeneration = generation
74
+ const promise = (async () => {
75
+ try {
76
+ const data = await client()
77
+ const fetchedAt = now()
78
+ if (startedGeneration === generation) entry = { data, fetchedAt }
79
+ return { data, fetchedAt, stale: false, error: '', ageMs: 0 }
80
+ } catch (error) {
81
+ const message = error instanceof Error ? error.message : String(error)
82
+ if (entry !== null) {
83
+ return {
84
+ data: entry.data,
85
+ fetchedAt: entry.fetchedAt,
86
+ stale: true,
87
+ error: message,
88
+ ageMs: Math.max(0, now() - entry.fetchedAt),
89
+ }
90
+ }
91
+ throw error
92
+ } finally {
93
+ if (inflight === promise) inflight = null
94
+ }
95
+ })()
96
+ inflight = promise
97
+ return promise
98
+ }
99
+
100
+ return {
101
+ get(options = {}) {
102
+ return load(options.force === true)
103
+ },
104
+ refresh() {
105
+ return load(true)
106
+ },
107
+ peek,
108
+ clear() {
109
+ entry = null
110
+ generation += 1
111
+ },
112
+ ttl,
113
+ }
114
+ }