@jewel998/config 0.2.1 → 0.2.4

package/dist/initConfig.d.ts

@@ -1,78 +1,103 @@
-import type { CacheStorage, ConfigEventCallback, ConfigEventType } from "./types.js";
+import { SdkError } from "./errors/index.js";
 import type { EvaluationContext } from "./plugins/types.js";
+import type { CacheStorage } from "./types.js";
 export interface InitConfigOptions {
     /** Required. API key from the portal (cid_ for client, svr_ for server). */
     clientId: string;
     /**
-     * Default/fallback values returned instantly before the API responds.
-     * Keys are flag names, values are what your app uses immediately (optimistic).
+     * Tier 1 keys — fetched immediately, block ready() resolution.
+     * Use for values your app cannot render without.
+     * e.g. ["app.maintenance_mode", "feature.auth_provider"]
+     */
+    prefetch?: string[];
+    /**
+     * Default/fallback values returned instantly before any tier resolves.
+     * get() resolves immediately when a key has a default here.
      */
     defaults?: Record<string, unknown>;
-    /** User context for targeting evaluation. Use autoContext() to auto-detect browser info. */
+    /** User context for targeting evaluation. Use autoContext() to auto-detect. */
     context?: EvaluationContext;
     /**
-     * Your self-hosted API URL. Points to your Firebase deployment.
+     * Your self-hosted API URL.
      * Default: https://jewel998-config.web.app/api (demo instance)
-     *
-     * @example "https://your-project.web.app/api"
      */
     baseUrl?: string;
+    /** Cache storage adapter. Default: memoryStorage() */
+    storage?: CacheStorage;
     /**
-     * Cache storage adapter. Controls where resolved config values are persisted.
-     *
-     * - `memoryStorage()` (default) — In-memory, lost on page reload
-     * - `browserStorage()` — localStorage, persists across page reloads and sessions
-     *
-     * @example
-     * ```ts
-     * import { browserStorage } from "@jewel998/config";
-     * initConfig({ storage: browserStorage({ prefix: "myapp" }) })
-     * ```
+     * Version polling interval in milliseconds.
+     * Default: 300_000 (5 minutes). Set to 0 to disable.
      */
-    storage?: CacheStorage;
+    pollInterval?: number;
+    /**
+     * Global timeout in milliseconds for get() calls with no default.
+     * If a key does not arrive within this window, get() rejects with
+     * SdkError { type: "TIMEOUT" } and onError is called.
+     * Default: 30_000 (30 seconds).
+     */
+    timeout?: number;
     /**
-     * Polling interval in milliseconds for version checks.
-     * The SDK periodically calls /api/version (lightweight ~100 bytes)
-     * and only re-fetches full data when the version changes.
+     * Global error handler. Called on every SDK-level error:
+     * timeouts, fetch failures, auth errors, key-not-found, rate limits.
      *
-     * Default: 300000 (5 minutes). Set to 0 to disable polling.
+     * get() also rejects with the same error — onError is for centralised
+     * logging/monitoring, not a replacement for catch().
      */
-    pollInterval?: number;
+    onError?: (error: SdkError) => void;
 }
 export interface Flags {
-    /** Get a flag value. Returns the default until the API responds, then the resolved value. */
-    get<T = unknown>(key: string): T;
-    /** Get a boolean flag. Returns false if the flag doesn't exist. */
-    flag(key: string): boolean;
-    /** Get all resolved flag values. */
-    all(): Record<string, unknown>;
-    /** Update user context. Triggers a re-fetch in client-key mode. */
+    /**
+     * Resolves when Tier 1 (init prefetch) keys have been fetched.
+     * Resolves instantly if no prefetch keys were declared.
+     */
+    ready(): Promise<void>;
+    /**
+     * Tier 2 fetch hint — fire-and-forget.
+     * Keys already tracked in Tier 1 or already fetched are skipped.
+     * Emits "updated" and "updated:key" events per key on completion.
+     */
+    prefetch(keys: string[]): void;
+    /**
+     * Get a typed config value asynchronously.
+     *
+     * Resolution order:
+     *   1. Memory / cache hit         → resolves instantly
+     *   2. Default in defaults map    → resolves instantly
+     *   3. Inline defaultValue arg    → resolves instantly
+     *   4. No default                 → suspends until idle fetch or refresh
+     *                                   delivers the key
+     *
+     * On timeout (global, default 30s):
+     *   - onError is called with SdkError { type: "TIMEOUT", key }
+     *   - Promise rejects with the same SdkError
+     */
+    get<T = unknown>(key: string): Promise<T>;
+    get<T = unknown>(key: string, defaultValue: T): Promise<T>;
+    /**
+     * Returns a snapshot of all currently fetched values merged with defaults.
+     * Does not wait for any in-flight fetches — returns current state only.
+     */
+    all(): Promise<Record<string, unknown>>;
+    /**
+     * Update user context. Fire-and-forget, debounced 100ms.
+     * Re-fetches all already-fetched keys in tier order with the new context.
+     * Subscribe to "updated" events to react when the re-fetch completes.
+     */
     setContext(context: EvaluationContext): void;
-    /** Force re-fetch from the API. */
+    /**
+     * Re-fetch all already-fetched keys in tier order.
+     * Resolves when all re-fetches complete.
+     */
     refresh(): Promise<void>;
-    /** Subscribe to events: "ready", "updated", "fetchError" */
-    on<E extends ConfigEventType>(event: E, cb: ConfigEventCallback<E>): void;
+    /**
+     * Subscribe to events.
+     *
+     * Key-specific:   flags.on("updated:feature.dark_mode", (value) => ...)
+     * Batch updated:  flags.on("updated", ({ keys, source }) => ...)
+     * Fetch errors:   flags.on("fetchError", ({ error }) => ...)
+     */
+    on(event: string, cb: (payload: unknown) => void): void;
     /** Unsubscribe from events. */
-    off<E extends ConfigEventType>(event: E, cb: ConfigEventCallback<E>): void;
+    off(event: string, cb: (payload: unknown) => void): void;
 }
-/**
- * Initialize the feature flags SDK.
- *
- * Returns a Flags instance that immediately serves default values,
- * then resolves to real values from the API in the background.
- *
- * @example
- * ```ts
- * const flags = initConfig({
- *   clientId: "cid_xxx",
- *   defaults: { "feature.dark_mode": false },
- *   context: autoContext({ userId: "user_123", plan: "pro" }),
- * });
- *
- * flags.get("feature.dark_mode"); // → false (instant)
- * flags.on("updated", () => {
- *   flags.get("feature.dark_mode"); // → true (from API)
- * });
- * ```
- */
 export declare function initConfig(options: InitConfigOptions): Flags;

package/dist/initConfig.js

@@ -1,129 +1,302 @@
 // ═══════════════════════════════════════════════════════════════
 // initConfig — Primary SDK entry point
 //
-// Usage:
-//   const flags = initConfig({
-//     clientId: "cid_xxx",
-//     defaults: { "feature.dark_mode": false, "app.upload_limit": 50 },
-//     context: autoContext({ userId: "user_123", plan: "pro" }),
-//   });
+// Three-tier priority fetching model:
 //
-//   flags.get("feature.dark_mode") // → false (instant, from defaults)
-//   // ...API responds...
-//   flags.get("feature.dark_mode") // → true (resolved from server)
+//   Tier 1 — PREFETCH (init)
+//     Declared via `prefetch: [...]` at initConfig time.
+//     Fetched immediately. ready() blocks until this completes.
+//
+//   Tier 2 — PAGE (runtime)
+//     Declared via flags.prefetch(keys) per route/component.
+//     Fire-and-forget. Keys deduplicated against Tier 1.
+//
+//   Tier 3 — IDLE
+//     Full fetchAll() during browser idle time via requestIdleCallback.
+//     Fills in all remaining keys in the background.
+//
+// get() behaviour:
+//   - Memory/cache hit → resolves instantly
+//   - Default provided  → resolves instantly
+//   - No default        → suspends until idle fetch or refresh delivers
+//                         the key, or global timeout fires
+//   - Timeout           → onError called, Promise rejects with SdkError
+//
+// Context update:
+//   setContext() is fire-and-forget (debounced 100ms).
+//   Re-fetches only already-fetched keys in tier order.
 // ═══════════════════════════════════════════════════════════════
-import { createConfig } from "./createConfig.js";
-/**
- * Initialize the feature flags SDK.
- *
- * Returns a Flags instance that immediately serves default values,
- * then resolves to real values from the API in the background.
- *
- * @example
- * ```ts
- * const flags = initConfig({
- *   clientId: "cid_xxx",
- *   defaults: { "feature.dark_mode": false },
- *   context: autoContext({ userId: "user_123", plan: "pro" }),
- * });
- *
- * flags.get("feature.dark_mode"); // → false (instant)
- * flags.on("updated", () => {
- *   flags.get("feature.dark_mode"); // → true (from API)
- * });
- * ```
- */
+import { memoryStorage } from "./cache/memoryStorage.js";
+import { SdkError, ConfigError } from "./errors/index.js";
+import { TypedEventEmitter } from "./events/EventEmitter.js";
+import { createProjectedFetcher } from "./fetch/projectedFetcher.js";
+import { TierFetcher } from "./fetch/TierFetcher.js";
+import { withRetry } from "./retry/RetryEngine.js";
+import { createHttpTransport } from "./transport/HttpTransport.js";
+import { DEFAULT_CACHE_TTL, DEFAULT_RETRY } from "./types.js";
+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;
+// ─── Implementation ────────────────────────────────────────────
 export function initConfig(options) {
+    if (!options.clientId) {
+        throw new ConfigError("clientId is required", "MISSING_CLIENT_ID");
+    }
+    if (typeof window === "undefined" && !options.clientId.startsWith("svr_")) {
+        throw new ConfigError("Client keys (cid_) require a browser environment.", "INITIALIZATION_FAILED");
+    }
     const defaults = options.defaults ?? {};
-    const pollInterval = options.pollInterval ?? 300_000; // 5 minutes default
-    const baseUrl = options.baseUrl ?? "https://jewel998-config.web.app/api";
-    // Create the underlying config client (optimistic strategy = instant return + background fetch)
-    const client = createConfig({
-        clientId: options.clientId,
-        loadingStrategy: "optimistic",
-        context: options.context,
-        storage: options.storage,
+    const pollInterval = options.pollInterval ?? 300_000;
+    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    const storage = options.storage ?? memoryStorage();
+    const retry = { ...DEFAULT_RETRY };
+    const timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    const onError = options.onError;
+    const initPrefetch = options.prefetch ?? [];
+    const events = new TypedEventEmitter();
+    let currentContext = options.context ?? {};
+    // ── Transport + fetcher ──────────────────────────────────────
+    const transport = createHttpTransport({
         baseUrl,
+        clientId: options.clientId,
+        evaluationMode: "server",
+        getContext: () => currentContext,
+    });
+    const baseFetcher = createProjectedFetcher(transport);
+    const tierFetcher = new TierFetcher(baseFetcher);
+    // ── In-memory data store ─────────────────────────────────────
+    const data = {};
+    function applyResult(result) {
+        const keys = Object.keys(result);
+        for (const key of keys) {
+            data[key] = result[key];
+            storage.set(key, result[key], DEFAULT_CACHE_TTL);
+        }
+        // Update the __all__ snapshot incrementally
+        const existing = storage.get("__all__") ?? {};
+        storage.set("__all__", { ...existing, ...result }, DEFAULT_CACHE_TTL);
+        return keys;
+    }
+    function emitUpdated(keys, source) {
+        if (keys.length === 0)
+            return;
+        events.emit("updated", { keys, source });
+    }
+    // ── Tier 1: init prefetch ────────────────────────────────────
+    const readyPromise = initPrefetch.length > 0
+        ? (async () => {
+            try {
+                const result = await withRetry(() => tierFetcher.fetchTier(initPrefetch, "prefetch"), retry);
+                const fetched = applyResult(result);
+                tierFetcher.notifyWaiters(result);
+                emitUpdated(fetched, "prefetch");
+            }
+            catch (err) {
+                const sdkErr = new SdkError("FETCH_FAILED", `Prefetch failed: ${err.message}`, undefined, err);
+                onError?.(sdkErr);
+                events.emit("fetchError", {
+                    error: sdkErr,
+                    retryCount: retry.maxRetries,
+                    willRetry: false,
+                });
+                // Don't re-throw — app still runs on defaults
+            }
+        })()
+        : Promise.resolve();
+    // ── Tier 3: idle fetch ───────────────────────────────────────
+    readyPromise.then(() => {
+        scheduleIdleFetch(async () => {
+            try {
+                const result = await tierFetcher.fetchAll();
+                const fetched = applyResult(result);
+                tierFetcher.notifyWaiters(result);
+                emitUpdated(fetched, "idle");
+            }
+            catch {
+                // Idle fetch is best-effort — silently ignore
+                // Pending waiters will eventually time out via get()
+            }
+        });
     });
-    // Version-based polling: check /api/version periodically, delta-fetch on change
+    // ── Version polling ──────────────────────────────────────────
     let cachedVersion = null;
-    let pollTimer = null;
     async function checkVersion() {
         try {
-            const res = await fetch(`${baseUrl}/getVersion?clientId=${options.clientId}`, {
-                headers: cachedVersion
-                    ? { "If-None-Match": `"${cachedVersion}"` }
-                    : {},
+            const res = await fetch(`${baseUrl}/v1/version?clientId=${options.clientId}`, {
+                headers: cachedVersion ? { "If-None-Match": `"${cachedVersion}"` } : {},
             });
-            // 304 = version unchanged, no action needed
             if (res.status === 304)
                 return;
             if (!res.ok)
                 return;
-            const { version, changedKeys } = (await res.json());
-            // First check — just store version, no refetch (initial fetch already happened)
+            const { version } = (await res.json());
             if (cachedVersion === null) {
                 cachedVersion = version;
                 return;
             }
-            // Version changed — need to refresh
             if (version !== cachedVersion) {
                 cachedVersion = version;
-                // If we know which keys changed, we could delta-fetch in the future
-                // For now, full refresh (still efficient with CDN + deduplication)
-                await client.refresh();
+                await doRefresh();
             }
         }
         catch {
-            // Silently ignore polling errors — cache continues to work
+            // Silently ignore polling errors
         }
     }
-    // Start polling if interval > 0
     if (pollInterval > 0 && typeof window !== "undefined") {
-        // Initial version check after first fetch completes
-        client.on("ready", () => {
-            void checkVersion();
-        });
-        pollTimer = setInterval(checkVersion, pollInterval);
-        // Also check on tab visibility change (user returns to tab)
+        readyPromise.then(() => void checkVersion());
+        setInterval(checkVersion, pollInterval);
         document.addEventListener("visibilitychange", () => {
-            if (document.visibilityState === "visible") {
+            if (document.visibilityState === "visible")
                 void checkVersion();
-            }
         });
     }
-    return {
-        get(key) {
-            const resolved = client.getValue(key);
-            if (resolved !== undefined)
-                return resolved;
-            return defaults[key];
+    // ── Refresh (re-fetch fetched keys in tier order) ─────────────
+    let lastRefetchTime = 0;
+    async function doRefresh() {
+        if (Date.now() - lastRefetchTime < MIN_REFETCH_INTERVAL_MS)
+            return;
+        lastRefetchTime = Date.now();
+        const { prefetch: pf, page, idle } = tierFetcher.getFetchedKeys();
+        const allFetched = [];
+        const refetches = [];
+        if (pf.length > 0) {
+            refetches.push(withRetry(() => tierFetcher.refetchKeys(pf), retry)
+                .then((r) => {
+                applyResult(r);
+                tierFetcher.notifyWaiters(r);
+                allFetched.push(...Object.keys(r));
+            })
+                .catch(() => { }));
+        }
+        if (page.length > 0) {
+            refetches.push(withRetry(() => tierFetcher.refetchKeys(page), retry)
+                .then((r) => {
+                applyResult(r);
+                tierFetcher.notifyWaiters(r);
+                allFetched.push(...Object.keys(r));
+            })
+                .catch(() => { }));
+        }
+        if (idle.length > 0) {
+            refetches.push(tierFetcher
+                .fetchAll()
+                .then((r) => {
+                applyResult(r);
+                tierFetcher.notifyWaiters(r);
+                allFetched.push(...Object.keys(r));
+            })
+                .catch(() => { }));
+        }
+        await Promise.allSettled(refetches);
+        emitUpdated(allFetched, "refresh");
+    }
+    // ── Context re-fetch ─────────────────────────────────────────
+    let contextDebounce = null;
+    // ── Public API ───────────────────────────────────────────────
+    const flags = {
+        ready() {
+            return readyPromise;
         },
-        flag(key) {
-            const resolved = client.getFlag(key);
-            if (resolved)
-                return true;
-            const val = client.getValue(key);
-            if (val !== undefined)
-                return val === true;
-            return defaults[key] === true;
+        prefetch(keys) {
+            void (async () => {
+                try {
+                    const result = await withRetry(() => tierFetcher.fetchTier(keys, "page"), retry);
+                    const fetched = applyResult(result);
+                    tierFetcher.notifyWaiters(result);
+                    emitUpdated(fetched, "page");
+                }
+                catch (err) {
+                    const sdkErr = new SdkError("FETCH_FAILED", `Page prefetch failed: ${err.message}`, undefined, err);
+                    onError?.(sdkErr);
+                    events.emit("fetchError", {
+                        error: sdkErr,
+                        retryCount: retry.maxRetries,
+                        willRetry: false,
+                    });
+                }
+            })();
+        },
+        get(key, defaultValue) {
+            // 1. Memory hit
+            if (key in data)
+                return Promise.resolve(data[key]);
+            // 2. Cache hit
+            const cached = storage.get(key);
+            if (cached !== undefined) {
+                data[key] = cached;
+                return Promise.resolve(cached);
+            }
+            // 3. Default from map
+            if (key in defaults)
+                return Promise.resolve(defaults[key]);
+            // 4. Inline default
+            if (defaultValue !== undefined)
+                return Promise.resolve(defaultValue);
+            // 5. Suspend — wait for idle fetch or refresh to deliver this key
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    const err = new SdkError("TIMEOUT", `get("${key}") timed out after ${timeoutMs}ms — key was not delivered by idle fetch or refresh`, key);
+                    onError?.(err);
+                    reject(err);
+                }, timeoutMs);
+                tierFetcher.waitForKey(key).then((value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                }, (err) => {
+                    clearTimeout(timer);
+                    const sdkErr = new SdkError("FETCH_FAILED", err.message, key, err);
+                    onError?.(sdkErr);
+                    reject(sdkErr);
+                });
+            });
         },
-        all() {
-            const resolved = client.getAll();
-            return { ...defaults, ...resolved };
+        async all() {
+            const snapshot = storage.get("__all__") ?? {};
+            return { ...defaults, ...snapshot, ...data };
         },
         setContext(context) {
-            client.setContext(context);
+            currentContext = { ...context };
+            if (contextDebounce)
+                clearTimeout(contextDebounce);
+            contextDebounce = setTimeout(() => {
+                contextDebounce = null;
+                void doRefresh();
+            }, CONTEXT_DEBOUNCE_MS);
         },
-        refresh() {
-            return client.refresh();
+        async refresh() {
+            await doRefresh();
         },
         on(event, cb) {
-            client.on(event, cb);
+            // Key-specific: "updated:feature.dark_mode"
+            if (event.startsWith("updated:")) {
+                const key = event.slice("updated:".length);
+                events.onKey(key, cb);
+                return;
+            }
+            events.on(event, cb);
         },
         off(event, cb) {
-            client.off(event, cb);
+            if (event.startsWith("updated:")) {
+                const key = event.slice("updated:".length);
+                events.offKey(key, cb);
+                return;
+            }
+            events.off(event, cb);
         },
     };
+    return flags;
+}
+// ─── Idle scheduling ──────────────────────────────────────────
+function scheduleIdleFetch(fn) {
+    if (typeof window === "undefined")
+        return;
+    if ("requestIdleCallback" in window) {
+        window.requestIdleCallback(fn, { timeout: 2000 });
+    }
+    else {
+        setTimeout(fn, 200);
+    }
 }
 //# sourceMappingURL=initConfig.js.map

package/dist/plugins/lifecycle/index.d.ts

@@ -1,3 +1,3 @@
 export { archivedPlugin } from "./archivedPlugin.js";
-export { validateStateTransition, VALID_TRANSITIONS, } from "./stateTransitions.js";
+export { validateStateTransition, VALID_TRANSITIONS } from "./stateTransitions.js";
 export type { LifecycleState } from "./stateTransitions.js";

package/dist/plugins/lifecycle/index.js

@@ -2,5 +2,5 @@
 // Lifecycle Plugin — Public Barrel Export
 // ═══════════════════════════════════════════════════════════════
 export { archivedPlugin } from "./archivedPlugin.js";
-export { validateStateTransition, VALID_TRANSITIONS, } from "./stateTransitions.js";
+export { validateStateTransition, VALID_TRANSITIONS } from "./stateTransitions.js";
 //# sourceMappingURL=index.js.map

package/dist/plugins/rollout/murmurhash3.js

@@ -16,11 +16,7 @@ export function murmurhash3_32(key, seed = 0) {
     const c2 = 0x1b873593;
     let i = 0;
     while (i + 4 <= len) {
-        let k1 = (bytes[i] |
-            (bytes[i + 1] << 8) |
-            (bytes[i + 2] << 16) |
-            (bytes[i + 3] << 24)) >>>
-            0;
+        let k1 = (bytes[i] | (bytes[i + 1] << 8) | (bytes[i + 2] << 16) | (bytes[i + 3] << 24)) >>> 0;
         k1 = Math.imul(k1, c1) >>> 0;
         k1 = ((k1 << 15) | (k1 >>> 17)) >>> 0;
         k1 = Math.imul(k1, c2) >>> 0;

package/dist/retry/RetryEngine.js

@@ -1,4 +1,4 @@
-import { AuthenticationError, ConfigError } from "../errors/index.js";
+import { AuthenticationError, ConfigError, RateLimitError } from "../errors/index.js";
 import { DEFAULT_RETRY } from "../types.js";
 export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export const isNonRetryableError = (error) => {
@@ -20,6 +20,20 @@ export const isNonRetryableError = (error) => {
     }
     return false;
 };
+/**
+ * Get the retry delay for an error. If the error is a RateLimitError with
+ * a server-specified Retry-After value, use that instead of calculated backoff.
+ */
+const getRetryDelay = (error, attempt, config) => {
+    // Respect server-specified Retry-After for rate limit errors
+    if (error instanceof RateLimitError && error.retryAfterSeconds != null) {
+        return error.retryAfterSeconds * 1000;
+    }
+    // Default: exponential backoff with jitter
+    const delay = Math.min(config.baseDelay * Math.pow(config.multiplier, attempt), config.maxDelay);
+    // Add jitter (±25%) to prevent thundering herd
+    return delay * (0.75 + Math.random() * 0.5);
+};
 export const withRetry = async (fn, options, onRetry) => {
     const config = { ...DEFAULT_RETRY, ...options };
     let lastError;
@@ -33,11 +47,9 @@ export const withRetry = async (fn, options, onRetry) => {
                 throw error;
             }
             if (attempt < config.maxRetries) {
-                const delay = Math.min(config.baseDelay * Math.pow(config.multiplier, attempt), config.maxDelay);
-                // Add jitter (±25%) to prevent thundering herd
-                const jitter = delay * (0.75 + Math.random() * 0.5);
-                onRetry?.(attempt + 1, lastError, jitter);
-                await sleep(jitter);
+                const delay = getRetryDelay(lastError, attempt, config);
+                onRetry?.(attempt + 1, lastError, delay);
+                await sleep(delay);
             }
         }
     }