@quazardous/qdadm 2.15.0 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -52,7 +52,7 @@
   ],
   "dependencies": {
     "@quazardous/qdcore": "^1.1.0",
-    "@quazardous/qddebug": "^1.0.0",
+    "@quazardous/qddebug": "^1.1.0",
     "@quazardous/quarkernel": "^2.1.0",
     "yaml": "^2.8.4"
   },

package/src/i18n/I18n.ts

@@ -70,6 +70,8 @@ export class I18n {
   // Concurrent domain loads — share one in-flight promise per (locale, domain)
   // pair across providers and t() callers.
   private _inflightDomains: Map<string, Promise<void>> = new Map()
+  // (locale::key) pairs already announced on the bus — see onMissing.
+  private _missingReported: Set<string> = new Set()
 
   constructor(options: I18nOptions = {}, deps: I18nDeps = {}) {
     this._defaultLocale = options.defaultLocale ?? 'en'
@@ -101,7 +103,16 @@ export class I18n {
       fallbackLocale: this._fallbackLocale,
       globalAliases: this._currentStrategyAliases(),
       onMissing: (key, locale) => {
-        if (this._emitMissing) this._signals?.emit('i18n:missing', { key, locale })
+        if (!this._emitMissing) return
+        // A missing key is a FACT, not a stream: knowing it once is the whole
+        // diagnostic value. Emitting on every resolution turned a signal into
+        // a firehose — the same seven nav keys fired 1616 times in two seconds
+        // downstream, and each emission was recorded by two collectors, which
+        // fed the tick that triggered the next resolution (#1896).
+        const seenKey = `${locale}::${key}`
+        if (this._missingReported.has(seenKey)) return
+        this._missingReported.add(seenKey)
+        this._signals?.emit('i18n:missing', { key, locale })
       },
     })
 
@@ -184,6 +195,7 @@ export class I18n {
     if (this.locale.value === locale && this._loadedLocales.has(locale)) return
     await this._loadLocale(locale)
     this.locale.value = locale
+    this._resetMissingReports()
     this._signals?.emit('locale:changed', locale)
   }
 
@@ -247,6 +259,17 @@ export class I18n {
   // Internals
   // ---------------------------------------------------------------------------
 
+  /**
+   * Forget which missing keys were already announced.
+   *
+   * Called whenever new messages arrive or the locale changes: a key that was
+   * missing may now resolve, and one that goes missing again afterwards is
+   * news worth reporting once more.
+   */
+  private _resetMissingReports(): void {
+    this._missingReported.clear()
+  }
+
   private async _loadLocale(locale: string): Promise<void> {
     for (const p of this._providers) {
       const bundle = await p.load(locale)
@@ -300,6 +323,7 @@ export class I18n {
       this._loadedDomains.add(cacheKey)
       this._inflightDomains.delete(cacheKey)
       if (merged) {
+        this._resetMissingReports()
         this._signals?.emit('i18n:domain-loaded', { locale, domain })
       }
     })()

package/src/i18n/__tests__/I18n.missingCap.test.ts

@@ -0,0 +1,82 @@
+/**
+ * A missing key is announced once, not on every resolution (#1896).
+ *
+ * Downstream, seven nav labels fired 1616 `i18n:missing` each in two seconds:
+ * every render resolved them, every resolution emitted, and each emission was
+ * recorded by two collectors that bumped the tick driving the next render.
+ * Capping the signal removes the fuel — the diagnostic value of a missing key
+ * is knowing it exists, which takes exactly one signal.
+ */
+import { describe, it, expect, beforeEach } from 'vitest'
+import { I18n } from '../I18n'
+
+function makeI18n(options = {}) {
+  const emitted: Array<{ signal: string; payload: unknown }> = []
+  const signals = {
+    emit: (signal: string, payload?: unknown) => {
+      emitted.push({ signal, payload })
+    },
+    on: () => () => {},
+  }
+  const i18n = new I18n({ disableDefaultCoreBundle: true, ...options }, { signals })
+  const missing = () => emitted.filter((e) => e.signal === 'i18n:missing')
+  return { i18n, emitted, missing }
+}
+
+describe('I18n — missing keys are announced once', () => {
+  it('emits once however many times the key is resolved', () => {
+    const { i18n, missing } = makeI18n()
+
+    for (let i = 0; i < 200; i++) i18n.t('nav.sections.Control')
+
+    const announced = missing()
+    expect(announced).toHaveLength(1)
+    expect((announced[0]!.payload as { key: string }).key).toBe('nav.sections.Control')
+  })
+
+  it('still announces each distinct key', () => {
+    const { i18n, missing } = makeI18n()
+
+    for (let i = 0; i < 50; i++) {
+      i18n.t('nav.routes.run')
+      i18n.t('nav.routes.job')
+      i18n.t('breadcrumb.details')
+    }
+
+    expect(missing()).toHaveLength(3)
+    expect(missing().map((m) => (m.payload as { key: string }).key).sort()).toEqual([
+      'breadcrumb.details',
+      'nav.routes.job',
+      'nav.routes.run',
+    ])
+  })
+
+  it('keeps returning the fallback — capping the signal changes no output', () => {
+    const { i18n } = makeI18n()
+
+    const first = i18n.t('nav.routes.run')
+    const later = i18n.t('nav.routes.run')
+
+    expect(later).toBe(first)
+  })
+
+  it('honours emitMissing: false', () => {
+    const { i18n, missing } = makeI18n({ emitMissing: false })
+
+    i18n.t('nav.routes.run')
+
+    expect(missing()).toHaveLength(0)
+  })
+
+  it('announces again after the locale changes — the fact may no longer hold', async () => {
+    const { i18n, missing } = makeI18n()
+
+    i18n.t('nav.routes.run')
+    expect(missing()).toHaveLength(1)
+
+    await i18n.changeLocale('fr')
+    i18n.t('nav.routes.run')
+
+    expect(missing()).toHaveLength(2)
+  })
+})