@feathq/web-sdk 0.2.0 → 0.3.0

package/README.md

@@ -55,6 +55,19 @@ await client.setContext({
 
 `change` events fire per flag whose evaluated value flipped, after either a context change or a datafile refresh.
 
+## Live streaming
+
+The SDK can hold a Server-Sent Events connection so datafile changes land near-instantly instead of waiting for the next poll. On each update the server pushes the full datafile; the SDK adopts it in version order (no extra HTTP request) and fires `change` events.
+
+By default streaming **follows your subscription**: the stream opens when the first `change` listener is added and closes when the last one is removed, so a page that never listens pays nothing. Override with the `streaming` option:
+
+```ts
+new FeatWebClient({ apiKey, streaming: true });  // always stream, opens on ready
+new FeatWebClient({ apiKey, streaming: false }); // never stream
+```
+
+Polling stays on as a safety net in every mode, so a dropped stream still self-heals.
+
 ## OpenFeature
 
 ```ts
@@ -81,6 +94,7 @@ new FeatWebClient({ apiKey, bootstrap: serverProvidedDatafile });
 
 - Pre-evaluates every flag against the current context into a `Map` so `getValue` is synchronous.
 - Polls every 30 s by default; pauses while the tab is hidden and force-refreshes on visibility restore. Floored at 5 s.
+- Optional Server-Sent Events stream for near-instant updates (see [Live streaming](#live-streaming)); polling remains the fallback.
 - Cross-tab `BroadcastChannel` sync: when one tab fetches a new datafile, sibling tabs adopt it without their own network call.
 - 304-aware via `ETag` / `If-None-Match`.
 - `url` must use `https://` if you override it (the constructor rejects plaintext URLs except `http://localhost` for tests).

package/dist/index.cjs

@@ -267,8 +267,55 @@ function hasLocalStorage2() {
   }
 }
 
+// src/streaming.ts
+var EVENT_SOURCE_CLOSED = 2;
+var DatafileStream = class {
+  constructor(options) {
+    this.source = null;
+    this.warned = false;
+    this.options = options;
+  }
+  open() {
+    if (this.source) return;
+    const base = this.options.url.replace(/\/$/, "");
+    const streamUrl = `${base}/sdk/v1/datafile/stream?key=${encodeURIComponent(
+      this.options.apiKey
+    )}`;
+    const source = new this.options.eventSourceCtor(streamUrl);
+    this.source = source;
+    source.addEventListener("put", (ev) => {
+      const datafile = parsePut(ev.data);
+      if (datafile) this.options.onPut(datafile);
+    });
+    source.addEventListener("error", () => {
+      if (!this.warned) {
+        this.warned = true;
+        console.warn("feat: datafile stream error; falling back to polling");
+      }
+      if (this.source && this.source.readyState === EVENT_SOURCE_CLOSED) {
+        this.close();
+      }
+    });
+  }
+  close() {
+    this.source?.close();
+    this.source = null;
+  }
+};
+function parsePut(data) {
+  if (typeof data !== "string") return null;
+  try {
+    const parsed = JSON.parse(data);
+    if (parsed && typeof parsed === "object" && typeof parsed.version === "number") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+
 // src/version.ts
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = "0.3.0";
 
 // src/client.ts
 var CLIENT_SIDE_PREFIX = "feat_cs_";
@@ -288,6 +335,14 @@ var FeatWebClient = class {
     this.visibilityHandler = null;
     this.emitter = new Emitter();
     this.broadcast = null;
+    this.stream = null;
+    // The set of live `change` listeners. The streaming-follows-subscription
+    // policy keys off whether this is non-empty; tracking the listeners (rather
+    // than a counter) keeps the refcount correct whether the caller unsubscribes
+    // via the returned disposer or via off().
+    this.changeListeners = /* @__PURE__ */ new Set();
+    this.started = false;
+    this.warnedNoEventSource = false;
     this.closed = false;
     if (!config.apiKey.startsWith(CLIENT_SIDE_PREFIX)) {
       throw new Error(
@@ -297,6 +352,7 @@ var FeatWebClient = class {
     this.url = config.url ?? DEFAULT_URL;
     assertHttpsUrl(this.url);
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.eventSourceCtor = config.eventSource ?? (typeof globalThis.EventSource !== "undefined" ? globalThis.EventSource : void 0);
     this.pollIntervalMs = Math.max(
       config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
       MIN_POLL_INTERVAL_MS
@@ -389,10 +445,17 @@ var FeatWebClient = class {
     return new Map(this.cache);
   }
   on(event, listener) {
-    return this.emitter.on(event, listener);
+    if (event !== "change") return this.emitter.on(event, listener);
+    this.emitter.on(event, listener);
+    this.changeListeners.add(listener);
+    this.maybeUpdateStream();
+    return () => this.off(event, listener);
   }
   off(event, listener) {
     this.emitter.off(event, listener);
+    if (event === "change" && this.changeListeners.delete(listener)) {
+      this.maybeUpdateStream();
+    }
   }
   // Force a one-shot fetch. Returns true if the in-memory datafile changed.
   async refresh() {
@@ -407,6 +470,9 @@ var FeatWebClient = class {
       clearInterval(this.timer);
       this.timer = null;
     }
+    this.stream?.close();
+    this.stream = null;
+    this.changeListeners.clear();
     if (this.visibilityHandler && typeof document !== "undefined") {
       document.removeEventListener("visibilitychange", this.visibilityHandler);
       this.visibilityHandler = null;
@@ -424,6 +490,8 @@ var FeatWebClient = class {
       this.startPolling();
       this.attachVisibilityHandler();
       this.summarizer?.start();
+      this.started = true;
+      this.maybeUpdateStream();
       this.emitter.emit("ready", void 0);
     } catch (err) {
       this.emitter.emit("failed", err instanceof Error ? err : new Error(String(err)));
@@ -484,18 +552,73 @@ var FeatWebClient = class {
     await this.recomputeCache();
     return true;
   }
-  // Sibling-tab handler. Only adopt if the broadcast carries a newer
-  // version (or we have nothing); old broadcasts can race with our own
-  // fresh fetches and we don't want to regress.
+  // Sibling-tab handler. Adopt without republishing: this is the receive end
+  // of a BroadcastChannel message, so echoing it back would loop.
   async adoptFromBroadcast(datafile, etag) {
+    await this.adoptDatafile(datafile, etag, false);
+  }
+  // Version-guarded adopt for datafiles that arrive outside the fetch path
+  // (sibling-tab broadcast, SSE `put`). Only adopt a strictly newer version so
+  // an old broadcast or out-of-order frame can't regress us; the same guard
+  // stops a republished put from looping back through a sibling tab. When
+  // `publish` is set we mirror the fetch path and rebroadcast so sibling tabs
+  // stay fresh without their own network call.
+  async adoptDatafile(datafile, etag, publish) {
+    if (this.closed) return;
     if (this.datafile && datafile.version <= this.datafile.version) return;
     this.datafile = datafile;
     this.etag = etag;
     if (this.config.cache) {
       saveCachedDatafile(this.config.cache, { datafile, etag });
     }
+    if (publish) this.broadcast?.publish(datafile, etag);
     await this.recomputeCache();
   }
+  // Reconcile the SSE connection with the current streaming policy. Called
+  // whenever an input to that policy changes: ready, a `change` (un)subscribe,
+  // or close.
+  maybeUpdateStream() {
+    if (this.closed) return;
+    const want = this.wantsStream();
+    if (want) {
+      this.openStream();
+    } else if (this.stream) {
+      this.stream.close();
+      this.stream = null;
+    }
+  }
+  wantsStream() {
+    if (this.config.streaming === false) return false;
+    if (this.config.streaming === true) return this.started;
+    return this.changeListeners.size > 0;
+  }
+  openStream() {
+    if (!this.eventSourceCtor) {
+      if (!this.warnedNoEventSource) {
+        this.warnedNoEventSource = true;
+        console.warn("feat: streaming requested but EventSource is unavailable; using polling");
+      }
+      return;
+    }
+    if (!this.stream) {
+      this.stream = new DatafileStream({
+        url: this.url,
+        apiKey: this.config.apiKey,
+        eventSourceCtor: this.eventSourceCtor,
+        // A `put` carries the full datafile; reuse the version-ordered adopt
+        // path so a duplicate or out-of-order frame is ignored and the cache
+        // recomputes (firing `change`) only on a strictly newer version. Like
+        // the fetch path, a stream-adopted put republishes on the
+        // BroadcastChannel so sibling tabs stay fresh without their own fetch.
+        onPut: (datafile) => {
+          void this.adoptDatafile(datafile, datafile.etag, true).catch((err) => {
+            console.warn("feat: streamed datafile update failed:", messageOf(err));
+          });
+        }
+      });
+    }
+    this.stream.open();
+  }
   // Pre-evaluate every flag in the datafile against the current context
   // and diff against the previous cache. Skips silently if datafile or
   // context is missing; the caller will recompute as soon as both land.
@@ -562,7 +685,7 @@ function assertHttpsUrl(url) {
 }
 
 // src/index.ts
-var SDK_VERSION2 = "0.2.0";
+var SDK_VERSION2 = "0.3.0";
 
 exports.FeatWebClient = FeatWebClient;
 exports.SDK_VERSION = SDK_VERSION2;

package/dist/index.d.cts

@@ -13,6 +13,13 @@ interface DatafileCacheConfig {
     storage: DatafileCacheStorage;
 }
 
+interface EventSourceLike {
+    readyState: number;
+    addEventListener(type: string, listener: (ev: MessageEvent) => void): void;
+    close(): void;
+}
+type EventSourceConstructor = new (url: string, init?: EventSourceInit) => EventSourceLike;
+
 interface FeatWebClientConfig {
     apiKey: string;
     url?: string;
@@ -25,6 +32,8 @@ interface FeatWebClientConfig {
     events?: boolean;
     eventsFlushIntervalMs?: number;
     fetch?: typeof fetch;
+    streaming?: boolean;
+    eventSource?: EventSourceConstructor;
 }
 interface ChangeEvent {
     flagKey: string;
@@ -51,8 +60,13 @@ declare class FeatWebClient {
     private visibilityHandler;
     private emitter;
     private broadcast;
+    private stream;
+    private changeListeners;
+    private started;
+    private warnedNoEventSource;
     private readonly summarizer;
     private readonly fetchImpl;
+    private readonly eventSourceCtor;
     private readonly pollIntervalMs;
     private readonly url;
     private closed;
@@ -77,9 +91,13 @@ declare class FeatWebClient {
     private attachVisibilityHandler;
     private fetchDatafile;
     private adoptFromBroadcast;
+    private adoptDatafile;
+    private maybeUpdateStream;
+    private wantsStream;
+    private openStream;
     private recomputeCache;
 }
 
-declare const SDK_VERSION = "0.2.0";
+declare const SDK_VERSION = "0.3.0";
 
-export { type ChangeEvent, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };
+export { type ChangeEvent, type EventSourceConstructor, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };

package/dist/index.d.ts

@@ -13,6 +13,13 @@ interface DatafileCacheConfig {
     storage: DatafileCacheStorage;
 }
 
+interface EventSourceLike {
+    readyState: number;
+    addEventListener(type: string, listener: (ev: MessageEvent) => void): void;
+    close(): void;
+}
+type EventSourceConstructor = new (url: string, init?: EventSourceInit) => EventSourceLike;
+
 interface FeatWebClientConfig {
     apiKey: string;
     url?: string;
@@ -25,6 +32,8 @@ interface FeatWebClientConfig {
     events?: boolean;
     eventsFlushIntervalMs?: number;
     fetch?: typeof fetch;
+    streaming?: boolean;
+    eventSource?: EventSourceConstructor;
 }
 interface ChangeEvent {
     flagKey: string;
@@ -51,8 +60,13 @@ declare class FeatWebClient {
     private visibilityHandler;
     private emitter;
     private broadcast;
+    private stream;
+    private changeListeners;
+    private started;
+    private warnedNoEventSource;
     private readonly summarizer;
     private readonly fetchImpl;
+    private readonly eventSourceCtor;
     private readonly pollIntervalMs;
     private readonly url;
     private closed;
@@ -77,9 +91,13 @@ declare class FeatWebClient {
     private attachVisibilityHandler;
     private fetchDatafile;
     private adoptFromBroadcast;
+    private adoptDatafile;
+    private maybeUpdateStream;
+    private wantsStream;
+    private openStream;
     private recomputeCache;
 }
 
-declare const SDK_VERSION = "0.2.0";
+declare const SDK_VERSION = "0.3.0";
 
-export { type ChangeEvent, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };
+export { type ChangeEvent, type EventSourceConstructor, FeatWebClient, type FeatWebClientConfig, type FlagEventMap, SDK_VERSION };

package/dist/index.js

@@ -265,8 +265,55 @@ function hasLocalStorage2() {
   }
 }
 
+// src/streaming.ts
+var EVENT_SOURCE_CLOSED = 2;
+var DatafileStream = class {
+  constructor(options) {
+    this.source = null;
+    this.warned = false;
+    this.options = options;
+  }
+  open() {
+    if (this.source) return;
+    const base = this.options.url.replace(/\/$/, "");
+    const streamUrl = `${base}/sdk/v1/datafile/stream?key=${encodeURIComponent(
+      this.options.apiKey
+    )}`;
+    const source = new this.options.eventSourceCtor(streamUrl);
+    this.source = source;
+    source.addEventListener("put", (ev) => {
+      const datafile = parsePut(ev.data);
+      if (datafile) this.options.onPut(datafile);
+    });
+    source.addEventListener("error", () => {
+      if (!this.warned) {
+        this.warned = true;
+        console.warn("feat: datafile stream error; falling back to polling");
+      }
+      if (this.source && this.source.readyState === EVENT_SOURCE_CLOSED) {
+        this.close();
+      }
+    });
+  }
+  close() {
+    this.source?.close();
+    this.source = null;
+  }
+};
+function parsePut(data) {
+  if (typeof data !== "string") return null;
+  try {
+    const parsed = JSON.parse(data);
+    if (parsed && typeof parsed === "object" && typeof parsed.version === "number") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+
 // src/version.ts
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = "0.3.0";
 
 // src/client.ts
 var CLIENT_SIDE_PREFIX = "feat_cs_";
@@ -286,6 +333,14 @@ var FeatWebClient = class {
     this.visibilityHandler = null;
     this.emitter = new Emitter();
     this.broadcast = null;
+    this.stream = null;
+    // The set of live `change` listeners. The streaming-follows-subscription
+    // policy keys off whether this is non-empty; tracking the listeners (rather
+    // than a counter) keeps the refcount correct whether the caller unsubscribes
+    // via the returned disposer or via off().
+    this.changeListeners = /* @__PURE__ */ new Set();
+    this.started = false;
+    this.warnedNoEventSource = false;
     this.closed = false;
     if (!config.apiKey.startsWith(CLIENT_SIDE_PREFIX)) {
       throw new Error(
@@ -295,6 +350,7 @@ var FeatWebClient = class {
     this.url = config.url ?? DEFAULT_URL;
     assertHttpsUrl(this.url);
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.eventSourceCtor = config.eventSource ?? (typeof globalThis.EventSource !== "undefined" ? globalThis.EventSource : void 0);
     this.pollIntervalMs = Math.max(
       config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
       MIN_POLL_INTERVAL_MS
@@ -387,10 +443,17 @@ var FeatWebClient = class {
     return new Map(this.cache);
   }
   on(event, listener) {
-    return this.emitter.on(event, listener);
+    if (event !== "change") return this.emitter.on(event, listener);
+    this.emitter.on(event, listener);
+    this.changeListeners.add(listener);
+    this.maybeUpdateStream();
+    return () => this.off(event, listener);
   }
   off(event, listener) {
     this.emitter.off(event, listener);
+    if (event === "change" && this.changeListeners.delete(listener)) {
+      this.maybeUpdateStream();
+    }
   }
   // Force a one-shot fetch. Returns true if the in-memory datafile changed.
   async refresh() {
@@ -405,6 +468,9 @@ var FeatWebClient = class {
       clearInterval(this.timer);
       this.timer = null;
     }
+    this.stream?.close();
+    this.stream = null;
+    this.changeListeners.clear();
     if (this.visibilityHandler && typeof document !== "undefined") {
       document.removeEventListener("visibilitychange", this.visibilityHandler);
       this.visibilityHandler = null;
@@ -422,6 +488,8 @@ var FeatWebClient = class {
       this.startPolling();
       this.attachVisibilityHandler();
       this.summarizer?.start();
+      this.started = true;
+      this.maybeUpdateStream();
       this.emitter.emit("ready", void 0);
     } catch (err) {
       this.emitter.emit("failed", err instanceof Error ? err : new Error(String(err)));
@@ -482,18 +550,73 @@ var FeatWebClient = class {
     await this.recomputeCache();
     return true;
   }
-  // Sibling-tab handler. Only adopt if the broadcast carries a newer
-  // version (or we have nothing); old broadcasts can race with our own
-  // fresh fetches and we don't want to regress.
+  // Sibling-tab handler. Adopt without republishing: this is the receive end
+  // of a BroadcastChannel message, so echoing it back would loop.
   async adoptFromBroadcast(datafile, etag) {
+    await this.adoptDatafile(datafile, etag, false);
+  }
+  // Version-guarded adopt for datafiles that arrive outside the fetch path
+  // (sibling-tab broadcast, SSE `put`). Only adopt a strictly newer version so
+  // an old broadcast or out-of-order frame can't regress us; the same guard
+  // stops a republished put from looping back through a sibling tab. When
+  // `publish` is set we mirror the fetch path and rebroadcast so sibling tabs
+  // stay fresh without their own network call.
+  async adoptDatafile(datafile, etag, publish) {
+    if (this.closed) return;
     if (this.datafile && datafile.version <= this.datafile.version) return;
     this.datafile = datafile;
     this.etag = etag;
     if (this.config.cache) {
       saveCachedDatafile(this.config.cache, { datafile, etag });
     }
+    if (publish) this.broadcast?.publish(datafile, etag);
     await this.recomputeCache();
   }
+  // Reconcile the SSE connection with the current streaming policy. Called
+  // whenever an input to that policy changes: ready, a `change` (un)subscribe,
+  // or close.
+  maybeUpdateStream() {
+    if (this.closed) return;
+    const want = this.wantsStream();
+    if (want) {
+      this.openStream();
+    } else if (this.stream) {
+      this.stream.close();
+      this.stream = null;
+    }
+  }
+  wantsStream() {
+    if (this.config.streaming === false) return false;
+    if (this.config.streaming === true) return this.started;
+    return this.changeListeners.size > 0;
+  }
+  openStream() {
+    if (!this.eventSourceCtor) {
+      if (!this.warnedNoEventSource) {
+        this.warnedNoEventSource = true;
+        console.warn("feat: streaming requested but EventSource is unavailable; using polling");
+      }
+      return;
+    }
+    if (!this.stream) {
+      this.stream = new DatafileStream({
+        url: this.url,
+        apiKey: this.config.apiKey,
+        eventSourceCtor: this.eventSourceCtor,
+        // A `put` carries the full datafile; reuse the version-ordered adopt
+        // path so a duplicate or out-of-order frame is ignored and the cache
+        // recomputes (firing `change`) only on a strictly newer version. Like
+        // the fetch path, a stream-adopted put republishes on the
+        // BroadcastChannel so sibling tabs stay fresh without their own fetch.
+        onPut: (datafile) => {
+          void this.adoptDatafile(datafile, datafile.etag, true).catch((err) => {
+            console.warn("feat: streamed datafile update failed:", messageOf(err));
+          });
+        }
+      });
+    }
+    this.stream.open();
+  }
   // Pre-evaluate every flag in the datafile against the current context
   // and diff against the previous cache. Skips silently if datafile or
   // context is missing; the caller will recompute as soon as both land.
@@ -560,6 +683,6 @@ function assertHttpsUrl(url) {
 }
 
 // src/index.ts
-var SDK_VERSION2 = "0.2.0";
+var SDK_VERSION2 = "0.3.0";
 
 export { FeatWebClient, SDK_VERSION2 as SDK_VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feathq/web-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "feat feature-flag SDK for browsers. Polling client + sync evaluation cache. Pair with @feathq/openfeature-web for OpenFeature.",
   "keywords": [
     "feature-flags",