refactor(data): describe tile budgets per period, drop a duplicate test, add the changelog entry

changelog.d/762-tile-budget-module.md

@@ -0,0 +1,4 @@
+- Move the tile budget helpers `utcDayKey`, `normalizeBudget` and
+  `isOverBudget` out of the TomTom module into `src/data/tileBudget.js`, so
+  other keyed tile proxies can share them. `src/data/tomtomTiles.js`
+  re-exports them; behaviour does not change (monwiss, #762).

src/data/tileBudget.js

@@ -22,29 +22,29 @@ export function utcDayKey(epochMs = Date.now()) {
 }
 
 /**
- * Normalize a persisted budget state against today's UTC day key.
+ * Normalize a persisted budget state against the current period key.
- * Rolls the counter to zero on day change; replaces missing/corrupt state.
+ * Rolls the counter to zero when the period changes; replaces missing/corrupt
- * Returns the SAME object when it is already valid for `dayKey` (cheap to
+ * state. Returns the SAME object when it is already valid for `periodKey`
- * call on every request).
+ * (cheap to call on every request).
  *
  * @param {{date:string, count:number}|null|undefined} state - Persisted state.
- * @param {string} dayKey - Today's UTC day key (from `utcDayKey`).
+ * @param {string} periodKey - Current period key, e.g. from `utcDayKey`.
- * @returns {{date:string, count:number}} Valid state for `dayKey`.
+ * @returns {{date:string, count:number}} Valid state for `periodKey`.
  */
-export function normalizeBudget(state, dayKey) {
+export function normalizeBudget(state, periodKey) {
   const valid =
     Boolean(state) &&
-    state.date === dayKey &&
+    state.date === periodKey &&
     Number.isFinite(state.count) &&
     state.count >= 0;
-  return valid ? state : { date: dayKey, count: 0 };
+  return valid ? state : { date: periodKey, count: 0 };
 }
 
 /**
- * Whether the daily soft cap has been reached.
+ * Whether the soft cap for the current period has been reached.
  *
  * @param {{count:number}} state - Normalized budget state.
- * @param {number} limit - Daily tile budget; non-positive/invalid never blocks.
+ * @param {number} limit - Budget per period; non-positive/invalid never blocks.
  * @returns {boolean} True when `count >= limit`.
  */
 export function isOverBudget(state, limit) {

src/data/tileBudget.test.mjs

@@ -8,19 +8,3 @@ test('tile budget helpers live in one module and TomTom re-exports them', () =>
   assert.equal(tomtom.normalizeBudget, normalizeBudget);
   assert.equal(tomtom.isOverBudget, isOverBudget);
 });
-
-test('normalizeBudget keeps a valid state and resets another period', () => {
-  const state = { date: '2026-09-24', count: 3 };
-  assert.equal(normalizeBudget(state, '2026-09-24'), state);
-  assert.deepEqual(normalizeBudget(state, '2026-09-25'), {
-    date: '2026-09-25',
-    count: 0,
-  });
-  assert.deepEqual(
-    normalizeBudget({ date: '2026-09-24', count: -1 }, '2026-09-24'),
-    {
-      date: '2026-09-24',
-      count: 0,
-    },
-  );
-});

src/data/tomtomTiles.js

@@ -1,9 +1,10 @@
 /**
- * @file Pure tile math + budget accounting for the TomTom traffic-flow proxy.
+ * @file Pure tile math for the TomTom traffic-flow proxy; budget helpers are
+ * re-exported from `./tileBudget.js`.
  *
  * Shared by the `/api/tomtom` vite plugin (server-side: coordinate validation,
  * daily budget governor) and `src/layers/traffic/flowSource.js` (client-side: which tiles
- * cover the current traffic fetch bounds). Zero dependencies, Cesium-free, so
+ * cover the current traffic fetch bounds). No external dependencies, Cesium-free, so
  * both sides can unit-test against it with node:test.
  *
  * Slippy scheme: standard Web Mercator XYZ, y grows southward