@nodora/client 0.0.2 → 0.0.4

package/README.md

@@ -24,7 +24,7 @@ const result = await checkout.evaluate("IsDiscountEligible", {
 });
 ```
 
-For configuration options, caching strategies, and detailed usage, see the official [documentation](https://docs.nodora.org).
+For detailed information, see the official [documentation](https://nodora.org/docs).
 
 ## License
 

package/lib/client.d.ts

@@ -10,24 +10,56 @@ export type Environment = "staging" | "production";
 /**
  * Caching strategy configuration.
  *
- * Currently supports a stale-while-revalidate approach:
- * - Returns cached data immediately (even if stale)
- * - Fetches fresh data in the background and updates cache
+ * - `stale-while-revalidate`: returns cached data immediately (even if stale)
+ *   and re-fetches in the background once the TTL has elapsed. Revalidation is
+ *   lazy: it is only triggered by an evaluation. This is the default strategy 
+ *   and a good general-purpose choice.
+ * - `poll`: re-fetches on a fixed wall-clock interval regardless of evaluation
+ *   activity. Bounds staleness to roughly `interval` even when the ruleset is
+ *   evaluated rarely, at the cost of background traffic while the client is
+ *   alive. Prefer this for low-frequency evaluations where a stale decision is
+ *   costly.
+ * - `immutable`: fetches the ruleset once and caches it for the lifetime of
+ *   the client. It is never revalidated, so a rule released after the first
+ *   fetch will not be picked up until the client is recreated (or you call
+ *   `refresh()` manually).
  */
-export type Strategy = {
-  /**
-   * Strategy type.
-   */
-  type: "stale-while-revalidate";
+export type Strategy =
+  | {
+      /**
+       * Serve cached data immediately and revalidate in the background.
+       */
+      type: "stale-while-revalidate";
 
-  /**
-   * Time-to-live for cached data (in milliseconds).
-   * After this duration, cached data is considered stale and will revalidate.
-   *
-   * @example 60000 // 1 minute
-   */
-  ttl: number;
-};
+      /**
+       * Time-to-live for cached data (in milliseconds).
+       * After this duration, cached data is considered stale and the next
+       * evaluation triggers a background revalidation.
+       *
+       * @example 60000 // 1 minute
+       */
+      ttl: number;
+    }
+  | {
+      /**
+       * Revalidate on a fixed interval, independent of evaluation activity.
+       */
+      type: "poll";
+
+      /**
+       * Interval between background re-fetches (in milliseconds). Polling
+       * starts on the first `prefetch()`/`evaluate()` and stops on `destroy()`.
+       *
+       * @example 60000 // 1 minute
+       */
+      interval: number;
+    }
+  | {
+      /**
+       * Fetch once and cache indefinitely; never revalidate automatically.
+       */
+      type: "immutable";
+    };
 
 export interface ClientOptions {
   /**
@@ -55,9 +87,14 @@ export interface ClientOptions {
   /**
    * Optional caching strategy.
    *
-   * If omitted, caching is disabled.
+   * Defaults to `{ type: "stale-while-revalidate", ttl: 60000 }` so released
+   * rule edits reach long-running clients within the TTL without a restart.
+   * Pass `{ type: "poll", interval }` to revalidate on a fixed interval even
+   * when evaluations are infrequent, or `{ type: "immutable" }` to fetch once
+   * and cache indefinitely.
    *
-   * @example { type: "stale-while-revalidate", ttl: 30000 }
+   * @default { type: "stale-while-revalidate", ttl: 60000 }
+   * @example { type: "poll", interval: 30000 }
    */
   strategy?: Strategy;
 
@@ -130,6 +167,38 @@ export declare class RulesetHandle {
     rule: string,
     input?: Record<string, any>,
   ): Promise<EvaluationResult>;
+
+  /**
+   * Registers a handler to be invoked when the given signal is emitted
+   * during an `evaluate()` call on this handle.
+   *
+   * Multiple handlers can be registered for the same signal; all are
+   * called in registration order. Returns the handle for chaining.
+   *
+   * @param signal - The name of the signal to listen for.
+   * @param handler - Called with the signal's arguments when emitted.
+   *
+   * @example
+   * client.ruleset("Checkout")
+   *   .on("discount_applied", (amount) => log(amount))
+   *   .on("fraud_flagged", (reason) => alert(reason));
+   */
+  on(
+    signal: string,
+    handler: (...args: any[]) => void,
+  ): this;
+
+  /**
+   * Removes a previously registered handler for the given signal.
+   * The handler reference must match the one passed to `on()`.
+   *
+   * @param signal - The name of the signal.
+   * @param handler - The handler to remove.
+   */
+  off(
+    signal: string,
+    handler: (...args: any[]) => void,
+  ): this;
 }
 
 /**
@@ -163,6 +232,20 @@ export declare class NodoraClient {
    */
   prefetch(): Promise<void>;
 
+  /**
+   * Forces an immediate revalidation of all cached rulesets, replacing them
+   * with the currently released versions.
+   *
+   * Useful with `{ type: "immutable" }`, which never revalidates on its own,
+   * or to pick up a release on demand instead of waiting for the TTL.
+   *
+   * @returns A promise that resolves once the refresh completes.
+   *
+   * @example
+   * await client.refresh();
+   */
+  refresh(): Promise<void>;
+
   /**
    * Returns a handle for a specific ruleset.
    *

package/lib/client.js

@@ -2,6 +2,9 @@ import { createEvaluator } from "@nodora/js";
 import { MetricAccumulator } from "./metrics";
 import { asyncGate } from "./utils";
 
+const DEFAULT_RETRY_AFTER_MS = 60000;
+const MAX_RETRY_AFTER_MS = 3600000;
+
 export class NodoraClient {
   constructor(options) {
     if (!options || !options.apiKey) {
@@ -15,14 +18,18 @@ export class NodoraClient {
       flushInterval: 10000,
       maxBufferSize: 300,
       timeout: 10000,
+      strategy: { type: "stale-while-revalidate", ttl: 60000 },
     };
 
     this._options = { ...defaultOptions, ...options };
     this._onError = options.onError || (() => {});
     this._cache = new Map();
     this._lastFetchedAt = 0;
+    this._retryAfterUntil = 0;
     this._flushTimer = null;
+    this._pollTimer = null;
     this._eventBuffer = [];
+    this._pendingFlush = null;
     this._initPromise = null;
     this._refreshGate = asyncGate();
     this._flushGate = asyncGate();
@@ -37,6 +44,10 @@ export class NodoraClient {
     return this._initPromise;
   }
 
+  async refresh() {
+    return this._refreshGate(() => this._refresh());
+  }
+
   async flush() {
     return this._flushEvents();
   }
@@ -46,11 +57,13 @@ export class NodoraClient {
   }
 
   _evaluate(rulesetName, ruleName, input) {
-    if (this._abortController.signal.aborted) return;
+    if (this._abortController.signal.aborted) {
+      throw new Error("client is destroyed");
+    }
 
     const entry = this._cache.get(rulesetName);
     if (!entry) {
-      throw new Error(`Ruleset "${rulesetName}" not found`);
+      throw new Error(`ruleset "${rulesetName}" not found`);
     }
 
     let result;
@@ -89,7 +102,7 @@ export class NodoraClient {
       Date.now() - this._lastFetchedAt > strategy.ttl
     ) {
       this._refreshGate(() => this._refresh()).catch((err) =>
-        this._onError(err)
+        this._onError(err),
       );
     }
 
@@ -104,7 +117,7 @@ export class NodoraClient {
   }
 
   async _init() {
-    await this._refresh();
+    await this._refreshGate(() => this._refresh());
 
     if (this._flushTimer) return;
     this._flushTimer = setInterval(() => {
@@ -115,6 +128,20 @@ export class NodoraClient {
       }
       this._flushEvents();
     }, this._options.flushInterval);
+
+    const strategy = this._options.strategy;
+    if (strategy && strategy.type === "poll" && !this._pollTimer) {
+      this._pollTimer = setInterval(() => {
+        if (this._abortController.signal.aborted) {
+          clearInterval(this._pollTimer);
+          this._pollTimer = null;
+          return;
+        }
+        this._refreshGate(() => this._refresh()).catch((err) =>
+          this._onError(err),
+        );
+      }, strategy.interval);
+    }
   }
 
   async _fetch() {
@@ -128,13 +155,39 @@ export class NodoraClient {
       ]),
     });
 
+    if (res.status === 429) {
+      const delayMs = this._parseRetryAfter(res.headers.get("retry-after"));
+      this._retryAfterUntil = Date.now() + delayMs;
+      throw new Error(
+        `rate limited fetching releases, backing off for ${Math.ceil(
+          delayMs / 1000,
+        )}s`,
+      );
+    }
+
     if (!res.ok) {
-      throw new Error(`Failed to fetch releases: HTTP ${res.status}`);
+      throw new Error(`failed to fetch releases: HTTP ${res.status}`);
     }
 
     return res.json();
   }
 
+  _parseRetryAfter(headerValue) {
+    if (!headerValue) return DEFAULT_RETRY_AFTER_MS;
+
+    const seconds = Number(headerValue); // Retry-After: <delay-seconds>
+    if (Number.isFinite(seconds)) {
+      return Math.min(Math.max(seconds * 1000, 0), MAX_RETRY_AFTER_MS);
+    }
+
+    const date = Date.parse(headerValue); // Retry-After: <HTTP-date>
+    if (!Number.isNaN(date)) {
+      return Math.min(Math.max(date - Date.now(), 0), MAX_RETRY_AFTER_MS);
+    }
+
+    return DEFAULT_RETRY_AFTER_MS;
+  }
+
   async _syncEvaluators(data) {
     const entries = Object.entries(data);
     await Promise.all(
@@ -145,17 +198,18 @@ export class NodoraClient {
           return;
         }
 
-        if (existing && existing.evaluator) {
-          existing.evaluator.destroy();
-        }
-
         const evaluator = await createEvaluator(release.compiled);
         this._cache.set(rulesetName, {
           rulesetId: release.rulesetId,
           checksum: release.checksum,
           evaluator,
         });
-      })
+
+        // clean up old evaluator
+        if (existing && existing.evaluator) {
+          existing.evaluator.destroy();
+        }
+      }),
     );
 
     // clean up deleted rulesets
@@ -169,9 +223,13 @@ export class NodoraClient {
   }
 
   async _refresh() {
+    // honor a 429 backoff window
+    if (Date.now() < this._retryAfterUntil) return;
+
     try {
       const data = await this._fetch();
       this._lastFetchedAt = Date.now();
+      this._retryAfterUntil = 0;
       await this._syncEvaluators(data);
     } catch (err) {
       if (this._abortController.signal.aborted) return;
@@ -183,9 +241,12 @@ export class NodoraClient {
     for (const event of this._metrics.drain()) {
       this._eventBuffer.push(event);
     }
-    if (this._eventBuffer.length === 0) return Promise.resolve();
+    // nothing buffered: still await an in-flight flush
+    if (this._eventBuffer.length === 0) {
+      return this._pendingFlush ?? Promise.resolve();
+    }
 
-    return this._flushGate(async () => {
+    const flush = this._flushGate(async () => {
       const batch = this._eventBuffer.splice(0);
       const { baseUrl, apiKey, timeout } = this._options;
 
@@ -203,6 +264,9 @@ export class NodoraClient {
           ]),
         });
       } catch (err) {
+        // the request was aborted by destroy()
+        if (this._abortController.signal.aborted) return;
+
         this._eventBuffer.unshift(...batch);
         const max = this._options.maxBufferSize;
         if (this._eventBuffer.length > max) {
@@ -211,6 +275,12 @@ export class NodoraClient {
         this._onError(err);
       }
     });
+
+    this._pendingFlush = flush;
+    flush.finally(() => {
+      if (this._pendingFlush === flush) this._pendingFlush = null;
+    });
+    return flush;
   }
 
   async destroy() {
@@ -221,6 +291,11 @@ export class NodoraClient {
       this._flushTimer = null;
     }
 
+    if (this._pollTimer) {
+      clearInterval(this._pollTimer);
+      this._pollTimer = null;
+    }
+
     this._eventBuffer.length = 0;
     this._metrics.clear();
 
@@ -238,10 +313,45 @@ class RulesetHandle {
   constructor(client, ruleset) {
     this._client = client;
     this._ruleset = ruleset;
+    this._signals = new Map();
   }
 
   async evaluate(rule, input = {}) {
     await this._client.prefetch();
-    return this._client._evaluate(this._ruleset, rule, input);
+    const result = this._client._evaluate(this._ruleset, rule, input);
+
+    if (result.emitted_signals && result.emitted_signals.length > 0) {
+      for (const signal of result.emitted_signals) {
+        const handlers = this._signals.get(signal.name);
+        if (handlers) {
+          for (const handler of handlers) {
+            try {
+              handler(...signal.args);
+            } catch (err) {
+              this._client._onError(err);
+            }
+          }
+        }
+      }
+    }
+    return result;
+  }
+
+  on(signal, handler) {
+    let handlers = this._signals.get(signal);
+    if (!handlers) {
+      handlers = new Set();
+      this._signals.set(signal, handlers);
+    }
+    handlers.add(handler);
+    return this;
+  }
+
+  off(signal, handler) {
+    const handlers = this._signals.get(signal);
+    if (!handlers) return this;
+    handlers.delete(handler);
+    if (handlers.size === 0) this._signals.delete(signal);
+    return this;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodora/client",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Nodora platform client for ruleset evaluation",
   "main": "lib/client.js",
   "types": "lib/client.d.ts",