@jewel998/config 0.2.2 → 0.2.6

package/README.md

@@ -1,5 +1,7 @@
 # @jewel998/config
 
+> See also: [Getting Started](/guide/getting-started) · [SDK Reference](/api/) · [Self-Hosting](/guide/self-hosting) · [Cloud Functions](/api/cloud-functions)
+
 [![npm version](https://img.shields.io/npm/v/@jewel998/config)](https://www.npmjs.com/package/@jewel998/config)
 [![npm downloads](https://img.shields.io/npm/dm/@jewel998/config)](https://www.npmjs.com/package/@jewel998/config)
 [![license](https://img.shields.io/npm/l/@jewel998/config)](./LICENSE)
@@ -12,12 +14,16 @@ A free, self-hostable feature flag and remote configuration platform. Deploy to
 ## Features
 
 - **Feature flags** — Boolean, string, number, JSON, array value types
-- **Targeting rules** — Serve different values based on user attributes (plan, country, etc.)
-- **Segments** — Reusable audience groups with one-click targeting
-- **Percentage rollouts** — Gradually roll out features with deterministic bucketing
-- **Prerequisites** — Flag dependencies with operator support (equals, greater_than, etc.)
-- **Scheduling** — Schedule config changes for a future date/time
-- **Environments** — Separate dev/staging/production configs
+- **A/B testing & multivariate testing** — Targeting rules with variant arms; sticky bucketing keeps users in a consistent group
+- **Canary releases & progressive delivery** — Percentage rollouts with deterministic bucketing (MurmurHash3); ramp 5% → 100% safely
+- **Kill switch** — Instantly revert any feature to its safe state with zero code deploy
+- **Targeting rules** — User segmentation: serve different values based on attributes (plan, country, role, etc.)
+- **Segments** — Reusable audience cohorts with one-click targeting across all flags
+- **Ring deployments** — Combine segments + rollouts to release through internal → beta → general rings
+- **Dark launch** — Deploy code behind a flag, activate on schedule without a new deploy
+- **Timed release** — Schedule flag changes for a precise date/time
+- **Prerequisites / guard flags** — Dependency-based feature gating; prevent inconsistent feature states
+- **Environments** — Separate dev/staging/production configs, keys, and targeting rules
 - **Audit log** — Track every change with actor, timestamp, and diff viewer
 - **Webhooks** — Notify Slack, Discord, Google Chat, MS Teams, or custom endpoints
 - **RBAC** — Viewer, Editor, Admin roles per project
@@ -52,21 +58,30 @@ import { initConfig, autoContext } from "@jewel998/config";
 
 const flags = initConfig({
   clientId: "cid_xxx", // From your Portal → API Keys
-  baseUrl: "https://your-project.web.app/api", // Your Firebase URL
+  baseUrl: "https://your-project.web.app/api",
+  prefetch: ["app.maintenance_mode"], // Fetch these immediately, block ready()
   defaults: {
     "feature.dark_mode": false,
     "app.upload_limit": 50,
   },
   context: autoContext({ userId: "user_123", plan: "pro" }),
+  onError: (err) => console.error(err.type, err.key),
 });
 
-// Instant — returns default value, no loading state
-flags.get("feature.dark_mode"); // → false
+// Wait for prefetched keys before rendering
+await flags.ready();
 
-// After API responds, returns resolved value
-flags.on("updated", () => {
-  flags.get("feature.dark_mode"); // → true (matched targeting rule)
-});
+// Instant — in memory or has a default
+const darkMode = await flags.get<boolean>("feature.dark_mode"); // → true
+
+// Declare page-level keys (Tier 2, fire-and-forget)
+flags.prefetch(["feature.new_checkout", "app.upload_limit"]);
+
+// React to any key changing
+flags.on("updated", ({ keys }) => rerender());
+
+// React to a specific key changing
+flags.on("updated:feature.dark_mode", (value) => applyTheme(value));
 ```
 
 ### API Key Types
@@ -103,7 +118,7 @@ config.getFlag("feature.checkout_v2"); // Evaluated locally — no round-trip
 │                                                     │
 │  import { initConfig } from "@jewel998/config"      │
 │  const flags = initConfig({ clientId, baseUrl })    │
-│  flags.get("feature.dark_mode") → true              │
+│  await flags.get("feature.dark_mode") → true        │
 └──────────────────────┬──────────────────────────────┘
                        │ POST /api/v1/config
                        ▼
@@ -192,6 +207,7 @@ apps/
   landing/     — Marketing site (Astro + React)
   docs/        — Documentation (VitePress)
 packages/
+  api/         — Internal micro-framework for Cloud Functions (@jewel998/api)
   config/      — SDK (@jewel998/config)
   tour/        — Tour framework (@jewel998/tour)
 functions/     — Firebase Cloud Functions (API + webhooks)

package/dist/cache/types.d.ts

@@ -1,2 +1,2 @@
-export type { CacheEntry, CacheStorage, BrowserStorageOptions, } from "../types.js";
+export type { CacheEntry, CacheStorage, BrowserStorageOptions } from "../types.js";
 export { DEFAULT_CACHE_TTL } from "../types.js";

package/dist/createConfig.js

@@ -15,9 +15,14 @@ export function createConfig(options) {
     if (!options.clientId) {
         throw new ConfigError("clientId is required", "MISSING_CLIENT_ID");
     }
-    // 2. Check browser environment
-    if (typeof window === "undefined") {
-        throw new ConfigError("@jewel998/config is browser-only. Server-side usage is not supported.", "INITIALIZATION_FAILED");
+    // 2. Check browser environment (for client keys only)
+    // Server keys (svr_) can run in any environment.
+    // Client keys (cid_) require a browser because they rely on server-side evaluation
+    // with origin/referer headers for domain validation.
+    if (typeof window === "undefined" && !options.clientId.startsWith("svr_")) {
+        throw new ConfigError("Client keys (cid_) require a browser environment. " +
+            "For server-side usage, use `initServerConfig` from '@jewel998/config/server' " +
+            "with a server key (svr_).", "INITIALIZATION_FAILED");
     }
     // 3. Resolve defaults
     const strategy = options.loadingStrategy ?? "optimistic";
@@ -42,9 +47,7 @@ export function createConfig(options) {
         getContext: () => currentContext,
     });
     const events = new TypedEventEmitter();
-    const fetcher = granularity === "batch"
-        ? createBatchFetcher(transport)
-        : createProjectedFetcher(transport);
+    const fetcher = granularity === "batch" ? createBatchFetcher(transport) : createProjectedFetcher(transport);
     // 6. Create loading context
     const context = {
         clientId: options.clientId,

package/dist/errors/index.d.ts

@@ -19,3 +19,21 @@ export declare class TimeoutError extends ConfigError {
 export declare class AuthenticationError extends ConfigError {
     constructor(message: string);
 }
+/**
+ * Error type passed to onError and thrown by get() on failure.
+ *
+ * type:
+ *   TIMEOUT       — get() waited longer than global timeout, no default provided
+ *   FETCH_FAILED  — network error or non-2xx response during any tier fetch
+ *   KEY_NOT_FOUND — key does not exist in the project
+ *   AUTH          — 401/403 from the API (circuit breaker opens)
+ *   RATE_LIMITED  — 429 from the API
+ */
+export type SdkErrorType = "TIMEOUT" | "FETCH_FAILED" | "KEY_NOT_FOUND" | "AUTH" | "RATE_LIMITED";
+export declare class SdkError extends Error {
+    readonly type: SdkErrorType;
+    readonly key?: string | undefined;
+    readonly cause?: Error | undefined;
+    name: string;
+    constructor(type: SdkErrorType, message: string, key?: string | undefined, cause?: Error | undefined);
+}

package/dist/errors/index.js

@@ -35,4 +35,16 @@ export class AuthenticationError extends ConfigError {
         this.name = "AuthenticationError";
     }
 }
+export class SdkError extends Error {
+    type;
+    key;
+    cause;
+    name = "SdkError";
+    constructor(type, message, key, cause) {
+        super(message);
+        this.type = type;
+        this.key = key;
+        this.cause = cause;
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/events/EventEmitter.d.ts

@@ -1,8 +1,29 @@
 import type { ConfigEventCallback, ConfigEventPayloads, ConfigEventType, EventEmitterInterface } from "../types.js";
+/**
+ * TypedEventEmitter supports two event patterns:
+ *
+ * 1. Typed batch events (ConfigEventType):
+ *      emitter.on("updated", ({ keys }) => ...)
+ *      emitter.on("fetchError", ({ error }) => ...)
+ *
+ * 2. Key-specific events (template literal `updated:${key}`):
+ *      emitter.on("updated:feature.dark_mode", (value) => ...)
+ *    Fired individually per key alongside the batch "updated" event.
+ */
 export declare class TypedEventEmitter implements EventEmitterInterface {
     private listeners;
+    private keyListeners;
     on<E extends ConfigEventType>(event: E, callback: ConfigEventCallback<E>): void;
     off<E extends ConfigEventType>(event: E, callback: ConfigEventCallback<E>): void;
+    /**
+     * Subscribe to a key-specific update event.
+     * Fires when that exact key's value is updated.
+     *
+     * @example
+     * emitter.onKey("feature.dark_mode", (value) => applyTheme(value));
+     */
+    onKey(key: string, callback: (value: unknown) => void): void;
+    offKey(key: string, callback: (value: unknown) => void): void;
     emit<E extends ConfigEventType>(event: E, payload: ConfigEventPayloads[E]): void;
     removeAllListeners(): void;
 }

package/dist/events/EventEmitter.js

@@ -1,5 +1,17 @@
+/**
+ * TypedEventEmitter supports two event patterns:
+ *
+ * 1. Typed batch events (ConfigEventType):
+ *      emitter.on("updated", ({ keys }) => ...)
+ *      emitter.on("fetchError", ({ error }) => ...)
+ *
+ * 2. Key-specific events (template literal `updated:${key}`):
+ *      emitter.on("updated:feature.dark_mode", (value) => ...)
+ *    Fired individually per key alongside the batch "updated" event.
+ */
 export class TypedEventEmitter {
     listeners = new Map();
+    keyListeners = new Map();
     on(event, callback) {
         if (!this.listeners.has(event)) {
             this.listeners.set(event, new Set());
@@ -9,22 +21,56 @@ export class TypedEventEmitter {
     off(event, callback) {
         this.listeners.get(event)?.delete(callback);
     }
+    /**
+     * Subscribe to a key-specific update event.
+     * Fires when that exact key's value is updated.
+     *
+     * @example
+     * emitter.onKey("feature.dark_mode", (value) => applyTheme(value));
+     */
+    onKey(key, callback) {
+        if (!this.keyListeners.has(key)) {
+            this.keyListeners.set(key, new Set());
+        }
+        this.keyListeners.get(key).add(callback);
+    }
+    offKey(key, callback) {
+        this.keyListeners.get(key)?.delete(callback);
+    }
     emit(event, payload) {
+        // Fire batch listeners
         const callbacks = this.listeners.get(event);
-        if (!callbacks) {
-            return;
-        }
-        for (const cb of callbacks) {
-            try {
-                cb(payload);
+        if (callbacks) {
+            for (const cb of callbacks) {
+                try {
+                    cb(payload);
+                }
+                catch (err) {
+                    console.error(`[config] Event handler error for "${event}":`, err);
+                }
             }
-            catch (err) {
-                console.error(`[Alpha] Event handler error for "${event}":`, err);
+        }
+        // For "updated" events, also fire per-key listeners
+        if (event === "updated") {
+            const updatedPayload = payload;
+            for (const key of updatedPayload.keys) {
+                const keyCallbacks = this.keyListeners.get(key);
+                if (keyCallbacks) {
+                    for (const cb of keyCallbacks) {
+                        try {
+                            cb(key); // value is read from data store by the subscriber
+                        }
+                        catch (err) {
+                            console.error(`[config] Key listener error for "updated:${key}":`, err);
+                        }
+                    }
+                }
             }
         }
     }
     removeAllListeners() {
         this.listeners.clear();
+        this.keyListeners.clear();
     }
 }
 //# sourceMappingURL=EventEmitter.js.map

package/dist/fetch/TierFetcher.d.ts

@@ -0,0 +1,77 @@
+import type { ConfigFetcher } from "../types.js";
+export type FetchTier = "prefetch" | "page" | "idle";
+/**
+ * TierFetcher — wraps a ConfigFetcher with three responsibilities:
+ *
+ * 1. Tier tracking: records which keys were fetched under which tier
+ *    so context re-fetches are scoped to already-fetched keys only.
+ *
+ * 2. Cross-tier deduplication: a key registered in a higher-priority tier
+ *    is never re-fetched by a lower-priority tier call.
+ *    Priority order: prefetch > page > idle
+ *
+ * 3. Pending waiters: get() calls that arrive for an unfetched key
+ *    register a waiter here. When the key eventually arrives (via idle
+ *    fetch or refresh), all waiters for that key are resolved.
+ */
+export declare class TierFetcher {
+    private readonly fetcher;
+    private readonly fetchedKeys;
+    private readonly allFetched;
+    private readonly waiters;
+    constructor(fetcher: ConfigFetcher);
+    /**
+     * 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>>;
+    /**
+     * Fetch all remaining keys (idle tier).
+     * Only keys not already tracked are added to the idle set.
+     */
+    fetchAll(): Promise<Record<string, unknown>>;
+    /** Check the remote version (passthrough). */
+    checkVersion(): ReturnType<ConfigFetcher["checkVersion"]>;
+    /**
+     * Re-fetch specific keys without deduplication check.
+     * 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>>;
+    /**
+     * 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.
+     */
+    waitForKey(key: string): Promise<unknown>;
+    /**
+     * Notify all waiters for the given keys with their resolved values.
+     * Called by initConfig after any successful fetch.
+     */
+    notifyWaiters(result: Record<string, unknown>): void;
+    /**
+     * Reject all waiters for all pending keys.
+     * Called when a fetch fails and we need to unblock all suspended get() calls.
+     */
+    rejectAllWaiters(error: Error): void;
+    /**
+     * Reject waiters for specific keys only.
+     * Used when a targeted fetch fails for a subset of keys.
+     */
+    rejectWaiters(keys: string[], error: Error): void;
+    /** Whether there are any pending waiters for a given key. */
+    hasWaiters(key: string): boolean;
+    getFetchedKeys(): {
+        prefetch: string[];
+        page: string[];
+        idle: string[];
+    };
+    isKeyFetched(key: string): boolean;
+    hasFetchedTier(tier: FetchTier): boolean;
+    private recordKeys;
+}

package/dist/fetch/TierFetcher.js

@@ -0,0 +1,162 @@
+/**
+ * TierFetcher — wraps a ConfigFetcher with three responsibilities:
+ *
+ * 1. Tier tracking: records which keys were fetched under which tier
+ *    so context re-fetches are scoped to already-fetched keys only.
+ *
+ * 2. Cross-tier deduplication: a key registered in a higher-priority tier
+ *    is never re-fetched by a lower-priority tier call.
+ *    Priority order: prefetch > page > idle
+ *
+ * 3. Pending waiters: get() calls that arrive for an unfetched key
+ *    register a waiter here. When the key eventually arrives (via idle
+ *    fetch or refresh), all waiters for that key are resolved.
+ */
+export class TierFetcher {
+    fetcher;
+    // Keys fetched per tier — used to scope context re-fetches
+    fetchedKeys = new Map([
+        ["prefetch", new Set()],
+        ["page", new Set()],
+        ["idle", new Set()],
+    ]);
+    // All fetched keys across all tiers — fast membership check for deduplication
+    allFetched = new Set();
+    // Pending waiters for suspended get() calls
+    // key → array of { resolve, reject } pairs
+    waiters = new Map();
+    constructor(fetcher) {
+        this.fetcher = fetcher;
+    }
+    // ─── Fetch methods ───────────────────────────────────────────
+    /**
+     * Fetch a specific set of keys under a given tier.
+     * Keys already tracked under any tier are skipped (deduplication).
+     */
+    async fetchTier(keys, tier) {
+        const toFetch = keys.filter((k) => !this.allFetched.has(k));
+        if (toFetch.length === 0)
+            return {};
+        const result = await this.fetcher.fetchKeys(toFetch);
+        this.recordKeys(Object.keys(result), tier);
+        return result;
+    }
+    /**
+     * Fetch all remaining keys (idle tier).
+     * Only keys not already tracked are added to the idle set.
+     */
+    async fetchAll() {
+        const result = await this.fetcher.fetchAll();
+        for (const key of Object.keys(result)) {
+            if (!this.allFetched.has(key)) {
+                this.fetchedKeys.get("idle").add(key);
+                this.allFetched.add(key);
+            }
+        }
+        return result;
+    }
+    /** Check the remote version (passthrough). */
+    checkVersion() {
+        return this.fetcher.checkVersion();
+    }
+    /**
+     * Re-fetch specific keys without deduplication check.
+     * Used by doRefresh() — we're intentionally re-fetching already-fetched keys
+     * with a new context, so the allFetched deduplication should be bypassed.
+     */
+    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.
+     * Returns a Promise that resolves when the key arrives, or rejects on error.
+     */
+    waitForKey(key) {
+        return new Promise((resolve, reject) => {
+            if (!this.waiters.has(key)) {
+                this.waiters.set(key, []);
+            }
+            this.waiters.get(key).push({ resolve, reject });
+        });
+    }
+    /**
+     * Notify all waiters for the given keys with their resolved values.
+     * Called by initConfig after any successful fetch.
+     */
+    notifyWaiters(result) {
+        for (const [key, value] of Object.entries(result)) {
+            const keyWaiters = this.waiters.get(key);
+            if (keyWaiters && keyWaiters.length > 0) {
+                for (const { resolve } of keyWaiters) {
+                    resolve(value);
+                }
+                this.waiters.delete(key);
+            }
+        }
+    }
+    /**
+     * Reject all waiters for all pending keys.
+     * Called when a fetch fails and we need to unblock all suspended get() calls.
+     */
+    rejectAllWaiters(error) {
+        for (const [key, keyWaiters] of this.waiters) {
+            for (const { reject } of keyWaiters) {
+                reject(error);
+            }
+            this.waiters.delete(key);
+        }
+    }
+    /**
+     * Reject waiters for specific keys only.
+     * Used when a targeted fetch fails for a subset of keys.
+     */
+    rejectWaiters(keys, error) {
+        for (const key of keys) {
+            const keyWaiters = this.waiters.get(key);
+            if (keyWaiters) {
+                for (const { reject } of keyWaiters) {
+                    reject(error);
+                }
+                this.waiters.delete(key);
+            }
+        }
+    }
+    /** Whether there are any pending waiters for a given key. */
+    hasWaiters(key) {
+        return (this.waiters.get(key)?.length ?? 0) > 0;
+    }
+    // ─── Tier introspection ──────────────────────────────────────
+    getFetchedKeys() {
+        return {
+            prefetch: Array.from(this.fetchedKeys.get("prefetch")),
+            page: Array.from(this.fetchedKeys.get("page")),
+            idle: Array.from(this.fetchedKeys.get("idle")),
+        };
+    }
+    isKeyFetched(key) {
+        return this.allFetched.has(key);
+    }
+    hasFetchedTier(tier) {
+        return this.fetchedKeys.get(tier).size > 0;
+    }
+    // ─── Private helpers ─────────────────────────────────────────
+    recordKeys(keys, tier) {
+        const tierSet = this.fetchedKeys.get(tier);
+        for (const key of keys) {
+            if (!this.allFetched.has(key)) {
+                tierSet.add(key);
+                this.allFetched.add(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=TierFetcher.js.map

package/dist/index.d.ts

@@ -9,5 +9,5 @@ export { WEBHOOK_FORMATS, WEBHOOK_FORMAT_INFO, TEMPLATE_VARIABLES, WEBHOOK_EVENT
 export type { WebhookFormat, WebhookEventType, WebhookResourceCategory, } from "./webhook-formats.js";
 export { memoryStorage } from "./cache/memoryStorage.js";
 export { browserStorage } from "./cache/browserStorage.js";
-export { AuthenticationError, ConfigError, InitializationError, RateLimitError, TimeoutError, } from "./errors/index.js";
-export type { ConfigErrorCode } from "./errors/index.js";
+export { AuthenticationError, ConfigError, InitializationError, RateLimitError, SdkError, TimeoutError, } from "./errors/index.js";
+export type { ConfigErrorCode, SdkErrorType } from "./errors/index.js";

package/dist/index.js

@@ -14,5 +14,5 @@ export { WEBHOOK_FORMATS, WEBHOOK_FORMAT_INFO, TEMPLATE_VARIABLES, WEBHOOK_EVENT
 export { memoryStorage } from "./cache/memoryStorage.js";
 export { browserStorage } from "./cache/browserStorage.js";
 // Errors
-export { AuthenticationError, ConfigError, InitializationError, RateLimitError, TimeoutError, } from "./errors/index.js";
+export { AuthenticationError, ConfigError, InitializationError, RateLimitError, SdkError, TimeoutError, } from "./errors/index.js";
 //# sourceMappingURL=index.js.map