Merge pull request #762 from monwiss/refactor/tile-budget

refactor(providers): move the tile budget helpers out of the TomTom module

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).

scripts/format-scope.json

@@ -112,6 +112,8 @@
   "src/data/terrainHeightsProxy.test.mjs",
   "src/data/tomtomTiles.js",
   "src/data/tomtomTiles.test.mjs",
+  "src/data/tileBudget.js",
+  "src/data/tileBudget.test.mjs",
   "src/data/firmsCsv.js",
   "src/data/firmsCsv.test.mjs",
   "src/tooling/environmentProviders.test.mjs",

scripts/package-boundaries.json

@@ -319,6 +319,7 @@
       "src/sources/httpBody.js",
       "src/i18n/marker.js",
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "server/providers/common/same-site.js",
       "src/localRequestGate.mjs"
     ],
@@ -326,7 +327,7 @@
   },
   "traffic-source": {
     "exports": ["./sources/traffic"],
-    "modules": ["src/data/tomtomTiles.js"],
+    "modules": ["src/data/tomtomTiles.js", "src/data/tileBudget.js"],
     "external": []
   },
   "firms-csv": {
@@ -1787,6 +1788,7 @@
       "src/layers/installations/viewport.js",
       "src/data/inputOwnership.js",
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "src/sources/capability.js",
       "src/sources/httpBody.js",
       "src/i18n/marker.js",
@@ -1875,6 +1877,7 @@
       "src/data/cameraSensitivity.js",
       "src/data/flowMatch.js",
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "src/data/trafficBounds.js",
       "src/geoDistance.js",
       "src/data/trafficFlowStyle.js",
@@ -2107,6 +2110,7 @@
       "src/data/inputOwnership.js",
       "src/layers/alpr/records.js",
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "src/layers/alpr/tileRecords.js",
       "src/sources/capability.js",
       "src/sources/httpBody.js",
@@ -2578,6 +2582,7 @@
       "src/data/telegeographySubmarineCables.js",
       "src/data/terrainHeights.js",
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "src/data/tr3bRegistry.js",
       "src/data/trackedCamera.js",
       "src/data/trackedModelRegime.js",
@@ -3574,6 +3579,7 @@
       "src/data/scenePick.js",
       "src/data/spriteOrder.js",
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "src/data/tr3bRegistry.js",
       "src/data/trackedCamera.js",
       "src/data/trackedModelRegime.js",
@@ -4171,6 +4177,7 @@
       "src/sources/phaseTiming.js",
       "src/sources/militaryTileGeometry.js",
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "src/data/installationNames.js",
       "src/annotations/outlineRungs.js",
       "src/sources/openFreeMapOutlines.js",
@@ -4534,6 +4541,7 @@
       "src/layers/alpr/records.js",
       "src/layers/alpr/source.js",
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "src/layers/alpr/tileRecords.js",
       "src/sources/httpBody.js",
       "src/i18n/marker.js",
@@ -4572,6 +4580,7 @@
       "src/data/militaryInstallationData.js",
       "src/data/installationNames.js",
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "src/sources/capability.js",
       "src/sources/httpBody.js",
       "src/i18n/marker.js",
@@ -4614,6 +4623,7 @@
     "exports": ["./layers/traffic/source"],
     "modules": [
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "src/layers/traffic/flowDecode.js",
       "src/layers/traffic/flowSource.js",
       "src/layers/traffic/footprint.js",
@@ -5188,6 +5198,7 @@
       "src/sources/vectorTiles.js",
       "src/sources/phaseTiming.js",
       "src/data/tomtomTiles.js",
+      "src/data/tileBudget.js",
       "src/sources/capability.js",
       "src/data/militaryInstallationData.js",
       "src/layers/launches/source.js",

src/data/tileBudget.js

@@ -0,0 +1,53 @@
+/**
+ * @file Upstream-request accounting shared by the keyed tile proxies.
+ *
+ * A soft cap per UTC period, persisted as `{date, count}` so it survives a
+ * restart. Nothing here is provider-specific: the caller picks the period by
+ * the key it passes, and decides what happens over the cap.
+ *
+ * Zero dependencies and Cesium-free, so providers and browser helpers can
+ * import it and node:test can exercise it directly.
+ *
+ * @module data/tileBudget
+ */
+
+/**
+ * UTC calendar-day key for budget bucketing.
+ *
+ * @param {number} [epochMs=Date.now()] - Timestamp in ms.
+ * @returns {string} 'YYYY-MM-DD' in UTC.
+ */
+export function utcDayKey(epochMs = Date.now()) {
+  return new Date(epochMs).toISOString().slice(0, 10);
+}
+
+/**
+ * Normalize a persisted budget state against the current period key.
+ * Rolls the counter to zero when the period changes; replaces missing/corrupt
+ * state. Returns the SAME object when it is already valid for `periodKey`
+ * (cheap to call on every request).
+ *
+ * @param {{date:string, count:number}|null|undefined} state - Persisted state.
+ * @param {string} periodKey - Current period key, e.g. from `utcDayKey`.
+ * @returns {{date:string, count:number}} Valid state for `periodKey`.
+ */
+export function normalizeBudget(state, periodKey) {
+  const valid =
+    Boolean(state) &&
+    state.date === periodKey &&
+    Number.isFinite(state.count) &&
+    state.count >= 0;
+  return valid ? state : { date: periodKey, count: 0 };
+}
+
+/**
+ * Whether the soft cap for the current period has been reached.
+ *
+ * @param {{count:number}} state - Normalized budget state.
+ * @param {number} limit - Budget per period; non-positive/invalid never blocks.
+ * @returns {boolean} True when `count >= limit`.
+ */
+export function isOverBudget(state, limit) {
+  if (!Number.isFinite(limit) || limit <= 0) return false;
+  return state.count >= limit;
+}

src/data/tileBudget.test.mjs

@@ -0,0 +1,10 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { isOverBudget, normalizeBudget, utcDayKey } from './tileBudget.js';
+import * as tomtom from './tomtomTiles.js';
+
+test('tile budget helpers live in one module and TomTom re-exports them', () => {
+  assert.equal(tomtom.utcDayKey, utcDayKey);
+  assert.equal(tomtom.normalizeBudget, normalizeBudget);
+  assert.equal(tomtom.isOverBudget, isOverBudget);
+});

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
@@ -131,42 +132,7 @@ export function tilesForBounds(bounds, zoom = 12, { maxTiles = 64 } = {}) {
 // ─── Daily budget accounting ───────────────────────────────
 
 /**
- * UTC calendar-day key for budget bucketing.
- *
- * @param {number} [epochMs=Date.now()] - Timestamp in ms.
- * @returns {string} 'YYYY-MM-DD' in UTC.
+ * Re-exported from `./tileBudget.js`, which keyed tile proxies share. The
+ * traffic provider and its tests keep one import for tile math and budget.
  */
-export function utcDayKey(epochMs = Date.now()) {
-  return new Date(epochMs).toISOString().slice(0, 10);
-}
-
-/**
- * Normalize a persisted budget state against today's UTC day key.
- * Rolls the counter to zero on day change; replaces missing/corrupt state.
- * Returns the SAME object when it is already valid for `dayKey` (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`).
- * @returns {{date:string, count:number}} Valid state for `dayKey`.
- */
-export function normalizeBudget(state, dayKey) {
-  const valid =
-    Boolean(state) &&
-    state.date === dayKey &&
-    Number.isFinite(state.count) &&
-    state.count >= 0;
-  return valid ? state : { date: dayKey, count: 0 };
-}
-
-/**
- * Whether the daily soft cap has been reached.
- *
- * @param {{count:number}} state - Normalized budget state.
- * @param {number} limit - Daily tile budget; non-positive/invalid never blocks.
- * @returns {boolean} True when `count >= limit`.
- */
-export function isOverBudget(state, limit) {
-  if (!Number.isFinite(limit) || limit <= 0) return false;
-  return state.count >= limit;
-}
+export { utcDayKey, normalizeBudget, isOverBudget } from './tileBudget.js';