Add caching

[DavidMANZI-093]

Introducing minimal caching. This implementation preservers existing behavior but minimizes re-computation and allocations.

• eliminates repeated traversals + allocations for repeated calls (first call does the flatten, subsequent calls return the cached array)
• Per-parameter caches (Keyed values are Mapped to avoid re-computation for queries that target a particular nested scope)

Closes #15

[DavidMANZI-093]

The memory cost of this implementation is considerably small. Caches store arrays that are already present in the JSON file. No deep copies are performed.

In the images below, you can see the comparison of both performances.

[DavidMANZI-093]

To recreate the test,

• Step 1: add the following code to src/main.ts,

import { getCountry, getProvinces, getDistricts, getSectors, getCells, getVillages, getDistrictsByProvince, getRandomLocation, getSectorsByDistrict, getCellsBySector, getVillagesByCell } from "./rwanda.ts";

(() => {
  const startTime = performance.now();

  // Suppose the functions are called frequently
  // in a hot path (many requests/second)
  for (let i = 0; i < 10000; i++) {
    getCountry();
    getProvinces();
    getDistricts();
    getSectors();
    getCells();
    getVillages();

    const randomLocation = getRandomLocation();

    getDistrictsByProvince(
      randomLocation.province
    );

    getSectorsByDistrict(
      randomLocation.province,
      randomLocation.district
    );

    getCellsBySector(
      randomLocation.province,
      randomLocation.district,
      randomLocation.sector
    );

    getVillagesByCell(
      randomLocation.province,
      randomLocation.district,
      randomLocation.sector,
      randomLocation.cell
    );
  }

  const endTime = performance.now();
  console.log(`Execution time: ${endTime - startTime} ms\n`);
})();

• Step 2: in the tsconfig.json file under "compilerOptions": { ... }, ensure the configs below are present and set as indicated (tempory - can be reverted after tests),

...
"target": "es2022",
"module": "commonjs",
"resolveJsonModule": true,
"allowImportingTsExtensions": true,
"noEmit": true,
...

• Step 3: from project root, run npx ts-node src/main.ts

[DavidMANZI-093]

Is your feature request related to a problem? Please describe. Add a caching layer to improve performance and reduce redundant data processing.

Describe the solution you'd like

• Enable/disable cache
• Clear cache
• Get cache statistics

Checklist

• enableCache
• clearCache
• getCacheStats

Additional context See recommendations.md section 'Caching & Performance'.

After taking a closer look at the description, decided to explore ways to clean the cache.

• Thought of LRU Cache but it'd have been overkill (slightly higher performance cost) as cache could only get as large as 477, 912 bytes... ❌
• Decided to add manual cleanup method to be invoked if need be. ✅

For cache size observation, use the images below and observe how cache size relates to iteration counts (more counts maximize cache population).

[DavidMANZI-093]

While generating build files, I got an error where webpack and all frontend/browser kinda environments could not support a serializer I got from v8 (node module). I needed it for the getCacheSize() method which could only work in a server/node environment only. (Since webpack 5, polyfill for node dependencies is no longer available)

Tried to switch to TextEncoder() but it glitched and kept reporting a static similar value for different iterations (even at almost none). I decided to leave it to ensure we keep support on both browser and server environments. Could be a good next issue!