feat: added local persistence to ofrep-web provider (#1508)

Signed-off-by: Salaber <jason.salaber@dynatrace.com>

Author: jsalaber

libs/providers/ofrep-web/README.md

@@ -82,6 +82,33 @@ OpenFeature.setProvider(
 );
 ```
 
+### Caching
+
+The provider supports persistent local caching via `localStorage` to reduce latency on startup and improve resilience to transient network failures. Caching is controlled with three options.
+
+**`cacheMode`** — controls the startup strategy:
+
+- `'local-cache-first'` _(default)_ — `initialize()` resolves immediately from the persisted cache if one exists, then refreshes from the network in the background. Evaluations served before the refresh completes will have reason `CACHED`.
+- `'network-first'` — `initialize()` blocks on the network request. The persisted cache is used as a fallback only on transient failures (network unavailable, timeout, 5xx). Auth and configuration errors (400, 401, 403, 404) are always surfaced immediately and never masked by cached values.
+- `'disabled'` — no persistence. `initialize()` always blocks on the network and the other cache options have no effect.
+
+**`cacheTTL`** — maximum age in seconds of a persisted cache entry before it is treated as a miss and removed. Defaults to `2_592_000` (30 days).
+
+**`cacheKeyPrefix`** — a string included in the cache key to avoid collisions when multiple provider instances share the same browser origin. A good value is the OFREP base URL or a project key.
+
+```ts
+import { OFREPWebProvider } from '@openfeature/ofrep-web-provider';
+
+OpenFeature.setProvider(
+  new OFREPWebProvider({
+    baseUrl: 'https://localhost:8080',
+    cacheMode: 'local-cache-first',
+    cacheTTL: 3600, // 1 hour
+    cacheKeyPrefix: 'my-app',
+  }),
+);
+```
+
 ### Fetch implementation
 
 If needed, a custom fetch implementation can be injected, if e.g. the platform does not have fetch built in.

libs/providers/ofrep-web/jest.polyfills.js

@@ -30,3 +30,25 @@ Object.defineProperties(globalThis, {
   Request: { value: Request },
   Response: { value: Response },
 });
+
+const localStorageData = new Map();
+// eslint-disable-next-line no-undef
+Object.defineProperty(globalThis, 'localStorage', {
+  value: {
+    getItem: (key) => (localStorageData.has(key) ? localStorageData.get(key) : null),
+    setItem: (key, value) => {
+      localStorageData.set(String(key), String(value));
+    },
+    removeItem: (key) => {
+      localStorageData.delete(String(key));
+    },
+    clear: () => {
+      localStorageData.clear();
+    },
+    key: (index) => Array.from(localStorageData.keys())[index] ?? null,
+    get length() {
+      return localStorageData.size;
+    },
+  },
+  writable: true,
+});

libs/providers/ofrep-web/src/lib/model/ofrep-web-provider-options.ts

@@ -1,12 +1,51 @@
 import type { OFREPProviderBaseOptions } from '@openfeature/ofrep-core';
 
+export type CacheMode = 'local-cache-first' | 'network-first' | 'disabled';
+
+/** Default cache TTL: 30 days in seconds. */
+export const DEFAULT_CACHE_TTL_SECONDS = 30 * 24 * 60 * 60;
+
 export type OFREPWebProviderOptions = OFREPProviderBaseOptions & {
   /**
-   * pollInterval is the time in milliseconds to wait between we call the OFREP
+   * pollInterval is the time in milliseconds to wait between calls to the OFREP
    * API to get the latest evaluation of your flags.
    *
-   * If a negative number is provided, the provider will not poll the OFREP API.
+   * If the value is 0 or negative, polling is disabled.
    * Default: 30000
    */
-  pollInterval?: number; // in milliseconds
+  pollInterval?: number;
+
+  /**
+   * cacheMode controls whether and how the provider uses local persistent storage.
+   *
+   * - `'local-cache-first'` (default): load from the persisted cache immediately on startup
+   *   so `initialize()` can return right away, then refresh from the network in the background.
+   * - `'network-first'`: block `initialize()` on the network request and only fall back to the
+   *   persisted cache on transient or server errors (network unavailable, 5xx, timeout).
+   *   Auth and configuration errors (401, 403, 400) are surfaced immediately and never masked
+   *   by cached values.
+   * - `'disabled'`: no persistence at all. `initialize()` always blocks on the network.
+   *   Persistence-related options have no effect.
+   *
+   * Default: `'local-cache-first'`
+   */
+  cacheMode?: CacheMode;
+
+  /**
+   * cacheTTL is the maximum age (in seconds) of a persisted cache entry before it is
+   * treated as a cache miss. Expired entries are removed from storage on read.
+   *
+   * Default: 2_592_000 (30 days)
+   */
+  cacheTTL?: number;
+
+  /**
+   * cacheKeyPrefix is included in the cache key hash to prevent collisions when multiple
+   * OFREP provider instances share the same storage partition (e.g. the same browser origin).
+   * When set, the cache key becomes `hash(cacheKeyPrefix + ":" + targetingKey)`.
+   *
+   * A sensible value is the OFREP base URL, a project key, or any other string that
+   * uniquely identifies this provider instance.
+   */
+  cacheKeyPrefix?: string;
 };