@jewel998/config 0.2.4 → 0.2.7

package/dist/client/ConfigClient.js

@@ -32,7 +32,7 @@ export const buildConfigClient = (internals) => {
             batchFetchTriggered = true;
             void (async () => {
                 try {
-                    const result = await withRetry(() => fetcher.fetchAll(), retry);
+                    const { data: result } = await withRetry(() => fetcher.fetchAll(), retry);
                     cache.set("__all__", result, DEFAULT_CACHE_TTL);
                     for (const [key, value] of Object.entries(result)) {
                         cache.set(key, value, DEFAULT_CACHE_TTL);
@@ -58,7 +58,7 @@ export const buildConfigClient = (internals) => {
             return;
         void (async () => {
             try {
-                const result = await fetcher.fetchKeys([key]);
+                const { data: result } = await fetcher.fetchKeys([key]);
                 for (const [k, v] of Object.entries(result)) {
                     cache.set(k, v, DEFAULT_CACHE_TTL);
                     data[k] = v;

package/dist/client/RefreshManager.js

@@ -59,7 +59,11 @@ export class RefreshManager {
                 catch {
                     // If version check fails, proceed with full fetch as fallback
                 }
-                const result = await withRetry(() => fetcher.fetchAll(), retry);
+                const { data: result, version: responseVersion } = await withRetry(() => fetcher.fetchAll(), retry);
+                // Sync the version from the config response itself — avoids drifting
+                // from the value learned by the earlier checkVersion() probe.
+                if (responseVersion !== null)
+                    this.cachedVersion = responseVersion;
                 cache.set("__all__", result, DEFAULT_CACHE_TTL);
                 for (const [key, value] of Object.entries(result)) {
                     cache.set(key, value, DEFAULT_CACHE_TTL);

package/dist/fetch/TierFetcher.d.ts

@@ -1,4 +1,4 @@
-import type { ConfigFetcher } from "../types.js";
+import type { ConfigFetcher, FetchResult } from "../types.js";
 export type FetchTier = "prefetch" | "page" | "idle";
 /**
  * TierFetcher — wraps a ConfigFetcher with three responsibilities:
@@ -24,12 +24,12 @@ export declare class TierFetcher {
      * Fetch a specific set of keys under a given tier.
      * Keys already tracked under any tier are skipped (deduplication).
      */
-    fetchTier(keys: string[], tier: FetchTier): Promise<Record<string, unknown>>;
+    fetchTier(keys: string[], tier: FetchTier): Promise<FetchResult>;
     /**
      * Fetch all remaining keys (idle tier).
      * Only keys not already tracked are added to the idle set.
      */
-    fetchAll(): Promise<Record<string, unknown>>;
+    fetchAll(): Promise<FetchResult>;
     /** Check the remote version (passthrough). */
     checkVersion(): ReturnType<ConfigFetcher["checkVersion"]>;
     /**
@@ -37,7 +37,13 @@ export declare class TierFetcher {
      * Used by doRefresh() — we're intentionally re-fetching already-fetched keys
      * with a new context, so the allFetched deduplication should be bypassed.
      */
-    refetchKeys(keys: string[]): Promise<Record<string, unknown>>;
+    refetchKeys(keys: string[]): Promise<FetchResult>;
+    /**
+     * Record keys as fetched under a tier WITHOUT performing a network fetch.
+     * Used when values are hydrated from persistent storage (the boot gate),
+     * so later context re-fetches correctly scope to these keys.
+     */
+    markFetched(keys: string[], tier: FetchTier): void;
     /**
      * Register a waiter for a key that hasn't been fetched yet.
      * Returns a Promise that resolves when the key arrives, or rejects on error.

package/dist/fetch/TierFetcher.js

@@ -36,9 +36,9 @@ export class TierFetcher {
     async fetchTier(keys, tier) {
         const toFetch = keys.filter((k) => !this.allFetched.has(k));
         if (toFetch.length === 0)
-            return {};
+            return { data: {}, version: null };
         const result = await this.fetcher.fetchKeys(toFetch);
-        this.recordKeys(Object.keys(result), tier);
+        this.recordKeys(Object.keys(result.data), tier);
         return result;
     }
     /**
@@ -47,7 +47,7 @@ export class TierFetcher {
      */
     async fetchAll() {
         const result = await this.fetcher.fetchAll();
-        for (const key of Object.keys(result)) {
+        for (const key of Object.keys(result.data)) {
             if (!this.allFetched.has(key)) {
                 this.fetchedKeys.get("idle").add(key);
                 this.allFetched.add(key);
@@ -67,6 +67,14 @@ export class TierFetcher {
     async refetchKeys(keys) {
         return this.fetcher.fetchKeys(keys);
     }
+    /**
+     * Record keys as fetched under a tier WITHOUT performing a network fetch.
+     * Used when values are hydrated from persistent storage (the boot gate),
+     * so later context re-fetches correctly scope to these keys.
+     */
+    markFetched(keys, tier) {
+        this.recordKeys(keys, tier);
+    }
     // ─── Waiter management ───────────────────────────────────────
     /**
      * Register a waiter for a key that hasn't been fetched yet.

package/dist/fetch/batchFetcher.js

@@ -1,12 +1,12 @@
 export const createBatchFetcher = (transport) => ({
     async fetchAll() {
         const response = await transport.request("v1/config");
-        return response.data;
+        return { data: response.data, version: response.version ?? null };
     },
     async fetchKeys(_keys) {
         // Batch mode always fetches everything
         const response = await transport.request("v1/config");
-        return response.data;
+        return { data: response.data, version: response.version ?? null };
     },
     async checkVersion() {
         const response = await transport.request("v1/version");

package/dist/fetch/projectedFetcher.js

@@ -4,7 +4,7 @@ export const createProjectedFetcher = (transport) => {
     return {
         async fetchAll() {
             const response = await transport.request("v1/config");
-            return response.data;
+            return { data: response.data, version: response.version ?? null };
         },
         async fetchKeys(keys) {
             for (const key of keys) {
@@ -20,7 +20,7 @@ export const createProjectedFetcher = (transport) => {
                             const response = await transport.request("v1/config", {
                                 keys: batchedKeys,
                             });
-                            resolve(response.data);
+                            resolve({ data: response.data, version: response.version ?? null });
                         }
                         catch (err) {
                             reject(err);
@@ -32,11 +32,11 @@ export const createProjectedFetcher = (transport) => {
             // Return only the keys this caller requested
             const filtered = {};
             for (const key of keys) {
-                if (key in result) {
-                    filtered[key] = result[key];
+                if (key in result.data) {
+                    filtered[key] = result.data[key];
                 }
             }
-            return filtered;
+            return { data: filtered, version: result.version };
         },
         async checkVersion() {
             const response = await transport.request("v1/version");

package/dist/initConfig.d.ts

@@ -22,7 +22,13 @@ export interface InitConfigOptions {
      * Default: https://jewel998-config.web.app/api (demo instance)
      */
     baseUrl?: string;
-    /** Cache storage adapter. Default: memoryStorage() */
+    /**
+     * Cache storage adapter. Default: `browserStorage()` (localStorage), which
+     * persists values and the config version across page loads so a reload or
+     * return visit skips the `/config` fetch when nothing changed. Falls back to
+     * in-memory automatically when `localStorage` is unavailable (SSR / Node /
+     * server keys). Pass `memoryStorage()` explicitly to opt out of persistence.
+     */
     storage?: CacheStorage;
     /**
      * Version polling interval in milliseconds.

package/dist/initConfig.js

@@ -26,7 +26,7 @@
 //   setContext() is fire-and-forget (debounced 100ms).
 //   Re-fetches only already-fetched keys in tier order.
 // ═══════════════════════════════════════════════════════════════
-import { memoryStorage } from "./cache/memoryStorage.js";
+import { browserStorage } from "./cache/browserStorage.js";
 import { SdkError, ConfigError } from "./errors/index.js";
 import { TypedEventEmitter } from "./events/EventEmitter.js";
 import { createProjectedFetcher } from "./fetch/projectedFetcher.js";
@@ -38,6 +38,34 @@ const DEFAULT_BASE_URL = "https://jewel998-config.web.app/api";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const CONTEXT_DEBOUNCE_MS = 100;
 const MIN_REFETCH_INTERVAL_MS = 30_000;
+/** Reserved storage keys for persisted gating metadata. */
+const VERSION_STORAGE_KEY = "__version__";
+const CONTEXT_FINGERPRINT_STORAGE_KEY = "__ctx__";
+/**
+ * Stable string fingerprint of an evaluation context. Keys are sorted so the
+ * same context always produces the same fingerprint regardless of insertion
+ * order. Used to detect when context changed across loads (which invalidates
+ * persisted values even if the config version is unchanged).
+ */
+function contextFingerprint(ctx) {
+    const stable = (value) => {
+        if (value === null || typeof value !== "object")
+            return value;
+        if (Array.isArray(value))
+            return value.map(stable);
+        const obj = value;
+        const sorted = {};
+        for (const k of Object.keys(obj).sort())
+            sorted[k] = stable(obj[k]);
+        return sorted;
+    };
+    try {
+        return JSON.stringify(stable(ctx ?? {}));
+    }
+    catch {
+        return "";
+    }
+}
 // ─── Implementation ────────────────────────────────────────────
 export function initConfig(options) {
     if (!options.clientId) {
@@ -49,7 +77,7 @@ export function initConfig(options) {
     const defaults = options.defaults ?? {};
     const pollInterval = options.pollInterval ?? 300_000;
     const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
-    const storage = options.storage ?? memoryStorage();
+    const storage = options.storage ?? browserStorage();
     const retry = { ...DEFAULT_RETRY };
     const timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
     const onError = options.onError;
@@ -67,6 +95,22 @@ export function initConfig(options) {
     const tierFetcher = new TierFetcher(baseFetcher);
     // ── In-memory data store ─────────────────────────────────────
     const data = {};
+    // Version known to the SDK. Hydrated from persistent storage on init so a
+    // reload can skip the config fetch when the version is unchanged.
+    let cachedVersion = storage.get(VERSION_STORAGE_KEY) ?? null;
+    const currentFingerprint = contextFingerprint(currentContext);
+    // If the persisted context fingerprint differs from this init's context, any
+    // persisted per-user values are stale — drop the persisted version so the
+    // boot gate re-fetches rather than serving values evaluated for old context.
+    if (storage.get(CONTEXT_FINGERPRINT_STORAGE_KEY) !== currentFingerprint) {
+        cachedVersion = null;
+    }
+    /** Persist the current version + context fingerprint next to the values. */
+    function persistVersion(version) {
+        cachedVersion = version;
+        storage.set(VERSION_STORAGE_KEY, version, DEFAULT_CACHE_TTL);
+        storage.set(CONTEXT_FINGERPRINT_STORAGE_KEY, currentFingerprint, DEFAULT_CACHE_TTL);
+    }
     function applyResult(result) {
         const keys = Object.keys(result);
         for (const key of keys) {
@@ -83,13 +127,65 @@ export function initConfig(options) {
             return;
         events.emit("updated", { keys, source });
     }
-    // ── Tier 1: init prefetch ────────────────────────────────────
+    // ── Remote version check (shared by boot gate + polling) ─────
+    async function fetchRemoteVersion() {
+        try {
+            const res = await fetch(`${baseUrl}/v1/version?clientId=${options.clientId}`, {
+                headers: cachedVersion ? { "If-None-Match": `"${cachedVersion}"` } : {},
+            });
+            // 304 => unchanged from the version we sent in If-None-Match.
+            if (res.status === 304)
+                return cachedVersion;
+            if (!res.ok)
+                return null;
+            const { version } = (await res.json());
+            return version ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** True when every key is already present in persistent storage. */
+    function allKeysCached(keys) {
+        return keys.every((k) => storage.get(k) !== undefined);
+    }
+    function hydrateFromStorage(keys) {
+        const hydrated = [];
+        for (const key of keys) {
+            const cached = storage.get(key);
+            if (cached !== undefined) {
+                data[key] = cached;
+                hydrated.push(key);
+            }
+        }
+        return hydrated;
+    }
+    // ── Tier 1: init prefetch (version-gated against persisted cache) ─
     const readyPromise = initPrefetch.length > 0
         ? (async () => {
             try {
+                // Boot gate: if we have a persisted version and values, confirm the
+                // remote version matches before spending a /config call. On match,
+                // serve from storage and skip the fetch entirely.
+                if (cachedVersion !== null && allKeysCached(initPrefetch)) {
+                    const remote = await fetchRemoteVersion();
+                    if (remote !== null && remote === cachedVersion) {
+                        const hydrated = hydrateFromStorage(initPrefetch);
+                        tierFetcher.markFetched(initPrefetch, "prefetch");
+                        emitUpdated(hydrated, "prefetch");
+                        return;
+                    }
+                    // Version advanced (or unknown) — fall through to a real fetch.
+                    if (remote !== null)
+                        cachedVersion = remote;
+                }
                 const result = await withRetry(() => tierFetcher.fetchTier(initPrefetch, "prefetch"), retry);
-                const fetched = applyResult(result);
-                tierFetcher.notifyWaiters(result);
+                const fetched = applyResult(result.data);
+                // Persist the version delivered alongside these values — no extra
+                // /version round trip needed; the /config response carries it.
+                if (result.version !== null)
+                    persistVersion(result.version);
+                tierFetcher.notifyWaiters(result.data);
                 emitUpdated(fetched, "prefetch");
             }
             catch (err) {
@@ -104,13 +200,24 @@ export function initConfig(options) {
             }
         })()
         : Promise.resolve();
-    // ── Tier 3: idle fetch ───────────────────────────────────────
+    // ── Tier 3: idle fetch (skipped when the full snapshot is fresh) ──
     readyPromise.then(() => {
         scheduleIdleFetch(async () => {
             try {
+                // If we already hold the full snapshot for the current version,
+                // there is nothing to fill in — skip the idle /config call.
+                if (cachedVersion !== null && storage.get("__all__") !== undefined) {
+                    const remote = await fetchRemoteVersion();
+                    if (remote !== null && remote === cachedVersion)
+                        return;
+                    if (remote !== null)
+                        cachedVersion = remote;
+                }
                 const result = await tierFetcher.fetchAll();
-                const fetched = applyResult(result);
-                tierFetcher.notifyWaiters(result);
+                const fetched = applyResult(result.data);
+                if (result.version !== null)
+                    persistVersion(result.version);
+                tierFetcher.notifyWaiters(result.data);
                 emitUpdated(fetched, "idle");
             }
             catch {
@@ -120,28 +227,17 @@ export function initConfig(options) {
         });
     });
     // ── Version polling ──────────────────────────────────────────
-    let cachedVersion = null;
     async function checkVersion() {
-        try {
-            const res = await fetch(`${baseUrl}/v1/version?clientId=${options.clientId}`, {
-                headers: cachedVersion ? { "If-None-Match": `"${cachedVersion}"` } : {},
-            });
-            if (res.status === 304)
-                return;
-            if (!res.ok)
-                return;
-            const { version } = (await res.json());
-            if (cachedVersion === null) {
-                cachedVersion = version;
-                return;
-            }
-            if (version !== cachedVersion) {
-                cachedVersion = version;
-                await doRefresh();
-            }
+        const version = await fetchRemoteVersion();
+        if (version === null)
+            return;
+        if (cachedVersion === null) {
+            persistVersion(version);
+            return;
         }
-        catch {
-            // Silently ignore polling errors
+        if (version !== cachedVersion) {
+            persistVersion(version);
+            await doRefresh();
         }
     }
     if (pollInterval > 0 && typeof window !== "undefined") {
@@ -164,18 +260,22 @@ export function initConfig(options) {
         if (pf.length > 0) {
             refetches.push(withRetry(() => tierFetcher.refetchKeys(pf), retry)
                 .then((r) => {
-                applyResult(r);
-                tierFetcher.notifyWaiters(r);
-                allFetched.push(...Object.keys(r));
+                applyResult(r.data);
+                if (r.version !== null)
+                    persistVersion(r.version);
+                tierFetcher.notifyWaiters(r.data);
+                allFetched.push(...Object.keys(r.data));
             })
                 .catch(() => { }));
         }
         if (page.length > 0) {
             refetches.push(withRetry(() => tierFetcher.refetchKeys(page), retry)
                 .then((r) => {
-                applyResult(r);
-                tierFetcher.notifyWaiters(r);
-                allFetched.push(...Object.keys(r));
+                applyResult(r.data);
+                if (r.version !== null)
+                    persistVersion(r.version);
+                tierFetcher.notifyWaiters(r.data);
+                allFetched.push(...Object.keys(r.data));
             })
                 .catch(() => { }));
         }
@@ -183,9 +283,11 @@ export function initConfig(options) {
             refetches.push(tierFetcher
                 .fetchAll()
                 .then((r) => {
-                applyResult(r);
-                tierFetcher.notifyWaiters(r);
-                allFetched.push(...Object.keys(r));
+                applyResult(r.data);
+                if (r.version !== null)
+                    persistVersion(r.version);
+                tierFetcher.notifyWaiters(r.data);
+                allFetched.push(...Object.keys(r.data));
             })
                 .catch(() => { }));
         }
@@ -203,8 +305,10 @@ export function initConfig(options) {
             void (async () => {
                 try {
                     const result = await withRetry(() => tierFetcher.fetchTier(keys, "page"), retry);
-                    const fetched = applyResult(result);
-                    tierFetcher.notifyWaiters(result);
+                    const fetched = applyResult(result.data);
+                    if (result.version !== null)
+                        persistVersion(result.version);
+                    tierFetcher.notifyWaiters(result.data);
                     emitUpdated(fetched, "page");
                 }
                 catch (err) {

package/dist/loading/optimistic.js

@@ -3,7 +3,7 @@ import { DEFAULT_CACHE_TTL } from "../types.js";
 const scheduleBackgroundFetch = (ctx) => {
     const doFetch = async () => {
         try {
-            const data = await withRetry(() => ctx.fetcher.fetchAll(), ctx.retry);
+            const { data } = await withRetry(() => ctx.fetcher.fetchAll(), ctx.retry);
             ctx.cache.set("__all__", data, DEFAULT_CACHE_TTL);
             for (const [key, value] of Object.entries(data)) {
                 ctx.cache.set(key, value, DEFAULT_CACHE_TTL);

package/dist/loading/pessimistic.js

@@ -7,7 +7,7 @@ export const executePessimistic = async (ctx) => {
         setTimeout(() => reject(new TimeoutError(ctx.timeout)), ctx.timeout);
     });
     try {
-        const data = await Promise.race([fetchPromise, timeoutPromise]);
+        const { data } = await Promise.race([fetchPromise, timeoutPromise]);
         ctx.cache.set("__all__", data, DEFAULT_CACHE_TTL);
         for (const [key, value] of Object.entries(data)) {
             ctx.cache.set(key, value, DEFAULT_CACHE_TTL);

package/dist/types.d.ts

@@ -137,11 +137,22 @@ export interface LoadingResult {
 export interface LoadingStrategyHandler {
     execute(context: LoadingContext): LoadingResult | Promise<LoadingResult>;
 }
+/**
+ * Result of a config fetch — the resolved values plus the config version
+ * they correspond to. The version comes from the same `/config` response
+ * that delivered the data, so the SDK can persist it without a second
+ * `/version` round trip.
+ */
+export interface FetchResult {
+    data: Record<string, unknown>;
+    /** Config version from the response, or null if the response omitted it. */
+    version: string | null;
+}
 export interface ConfigFetcher {
     /** Fetch all configs for the bound project+environment */
-    fetchAll(): Promise<Record<string, unknown>>;
+    fetchAll(): Promise<FetchResult>;
     /** Fetch specific keys only */
-    fetchKeys(keys: string[]): Promise<Record<string, unknown>>;
+    fetchKeys(keys: string[]): Promise<FetchResult>;
     /** Check current config version (lightweight — single Firestore read) */
     checkVersion(): Promise<{
         version: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jewel998/config",
-  "version": "0.2.4",
+  "version": "0.2.7",
   "private": false,
   "description": "Free, self-hosted feature flags and remote configuration SDK",
   "keywords": [