@vercel/flags-core 1.4.0 → 1.5.0-581a9c5-20260525125622

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @vercel/flags-core
 
+## 1.5.0-581a9c5-20260525125622
+
+### Minor Changes
+
+- [#385](https://github.com/vercel/flags/pull/385) [`5b2dc37`](https://github.com/vercel/flags/commit/5b2dc37041e24811f735beede41fc8c29f508cb7) Thanks [@dferber90](https://github.com/dferber90)! - Add `bulkEvaluate` method to `FlagsClient` for resolving multiple flags against shared entities in a single call.
+
+  ```ts
+  const results = await client.bulkEvaluate(
+    [
+      { key: "a", defaultValue: false },
+      { key: "b", defaultValue: "off" },
+    ],
+    entities
+  );
+
+  results.a; // EvaluationResult<boolean>
+  results.b; // EvaluationResult<string>
+  ```
+
+  Avoids the per-flag overhead of separate `evaluate()` calls — the datafile is read once, entities are resolved once, and all flags share the same environment/segments lookup. Each entry in the returned record is a full `EvaluationResult` with `value`, `reason`, `outcomeType`, and `metrics`.
+
+- [#371](https://github.com/vercel/flags/pull/371) [`bd4d01a`](https://github.com/vercel/flags/commit/bd4d01a9b2b5d70bf7ae62cda645d8cd7292ad83) Thanks [@vincent-derks](https://github.com/vincent-derks)! - Add jitter to ingest retries and the batch-flush window.
+
+  The usage tracker now uses AWS-style "Full Jitter" exponential backoff between
+  retry attempts (replacing the previous deterministic 100/200ms schedule) and
+  randomizes the 5s batch-flush window by ±20% to desynchronize concurrent
+  processes. When all retry attempts are exhausted the SDK now logs a structured
+  warning so consumers can alert on dropped batches.
+
+### Patch Changes
+
+- [#382](https://github.com/vercel/flags/pull/382) [`4d90e91`](https://github.com/vercel/flags/commit/4d90e912a4d7c9d4ef986d5e8dc609c30b203242) Thanks [@dferber90](https://github.com/dferber90)! - Speed up flag evaluation on the hot path.
+
+  - `handleOutcome` no longer recomputes `scaledWeights` on every split-outcome evaluation; the per-outcome scaled weights are cached on first call.
+  - `matchConditions` no longer recompiles `RegExp` on every REGEX / NOT_REGEX condition; the compiled regex is cached on first call.
+  - `Controller.read()` and `getDatafile()` no longer re-destructure and re-spread the in-memory datafile on every call; the result is cached and rebuilt only when stream/poll replaces the underlying data.
+
+  In micro-benchmarks the pure `evaluate()` path is ~22% faster for split outcomes and ~32% faster for regex conditions. The full `client.evaluate()` path is 14–22% faster across all scenarios.
+
 ## 1.4.0
 
 ### Minor Changes

package/dist/{chunk-OABKRAPP.js → chunk-IMGERCR6.js}

@@ -7,6 +7,7 @@ var __export = (target, all) => {
 // src/controller-fns.ts
 var controller_fns_exports = {};
 __export(controller_fns_exports, {
+  bulkEvaluate: () => bulkEvaluate2,
   controllerInstanceMap: () => controllerInstanceMap,
   evaluate: () => evaluate2,
   getDatafile: () => getDatafile,
@@ -46,6 +47,24 @@ var Packed;
 
 // src/evaluate.ts
 var MAX_REGEX_INPUT_LENGTH = 1e4;
+var UINT32_MAX = 4294967295;
+var SCALED_WEIGHTS = /* @__PURE__ */ Symbol("@vercel/flags-core:scaledWeights");
+var COMPILED_REGEX = /* @__PURE__ */ Symbol("@vercel/flags-core:compiledRegex");
+function getScaledWeights(outcome) {
+  const cached = outcome[SCALED_WEIGHTS];
+  if (cached) return cached;
+  const total = sum(outcome.weights);
+  const scaled = outcome.weights.map((w) => w / total * UINT32_MAX);
+  outcome[SCALED_WEIGHTS] = scaled;
+  return scaled;
+}
+function getCompiledRegex(rhs) {
+  const cached = rhs[COMPILED_REGEX];
+  if (cached) return cached;
+  const compiled = new RegExp(rhs.pattern, rhs.flags);
+  rhs[COMPILED_REGEX] = compiled;
+  return compiled;
+}
 function exhaustivenessCheck(_) {
   throw new Error("Exhaustiveness check failed");
 }
@@ -232,12 +251,12 @@ function matchConditions(conditions, params) {
           return (isNumber(rhs) || isString(rhs)) && lhs <= rhs;
         case "regex" /* REGEX */:
           if (isString(lhs) && lhs.length <= MAX_REGEX_INPUT_LENGTH && typeof rhs === "object" && !Array.isArray(rhs) && rhs?.type === "regex") {
-            return new RegExp(rhs.pattern, rhs.flags).test(lhs);
+            return getCompiledRegex(rhs).test(lhs);
           }
           return false;
         case "!regex" /* NOT_REGEX */:
           if (isString(lhs) && lhs.length <= MAX_REGEX_INPUT_LENGTH && typeof rhs === "object" && !Array.isArray(rhs) && rhs?.type === "regex") {
-            return !new RegExp(rhs.pattern, rhs.flags).test(lhs);
+            return !getCompiledRegex(rhs).test(lhs);
           }
           return false;
         case "before" /* BEFORE */: {
@@ -309,13 +328,9 @@ function handleOutcome(params, outcome) {
       if (typeof lhs !== "string") {
         return { value: defaultOutcome, outcomeType: "split" /* SPLIT */ };
       }
-      const maxValue = 4294967295;
       const value = hashInput(lhs, params.definition.seed);
-      const sumOfWeights = sum(outcome.weights);
-      const scaledWeights = outcome.weights.map(
-        (weight) => weight / sumOfWeights * maxValue
-      );
-      const variantIndex = findWeightedIndex(scaledWeights, value, maxValue);
+      const scaledWeights = getScaledWeights(outcome);
+      const variantIndex = findWeightedIndex(scaledWeights, value, UINT32_MAX);
       return {
         value: variantIndex === -1 ? defaultOutcome : getVariant(params.definition.variants, variantIndex),
         outcomeType: "split" /* SPLIT */
@@ -371,9 +386,8 @@ function handleOutcome(params, outcome) {
           outcomeType: "rollout" /* ROLLOUT */
         };
       }
-      const maxValue = 4294967295;
       const value = hashInput(lhs, params.definition.seed);
-      const threshold = currentPromille / 1e5 * maxValue;
+      const threshold = currentPromille / 1e5 * UINT32_MAX;
       return {
         value: value < threshold ? getVariant(params.definition.variants, outcome.rollToVariant) : getVariant(
           params.definition.variants,
@@ -440,6 +454,23 @@ function evaluate(params, _visited) {
     reason: "fallthrough" /* FALLTHROUGH */
   });
 }
+function bulkEvaluate(flags, shared) {
+  const params = {
+    entities: shared.entities,
+    environment: shared.environment,
+    segments: shared.segments,
+    definition: void 0,
+    defaultValue: void 0
+  };
+  const results = {};
+  for (const key in flags) {
+    const flag = flags[key];
+    params.definition = flag.definition;
+    params.defaultValue = flag.defaultValue;
+    results[key] = evaluate(params);
+  }
+  return results;
+}
 function findWeightedIndex(weights, value, maxValue) {
   if (value < 0 || value >= maxValue) return -1;
   let sum2 = 0;
@@ -451,7 +482,7 @@ function findWeightedIndex(weights, value, maxValue) {
 }
 
 // package.json
-var version = "1.4.0";
+var version = "1.5.0-581a9c5-20260525125622";
 
 // src/lib/report-value.ts
 function internalReportValue(key, value, data) {
@@ -557,6 +588,78 @@ async function evaluate2(id, flagKey, defaultValue, entities) {
     }
   });
 }
+async function bulkEvaluate2(id, flags, entities) {
+  const controller = getInstance(id).controller;
+  let datafile;
+  try {
+    datafile = await controller.read();
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Failed to read datafile";
+    const results2 = {};
+    for (const flag of flags) {
+      results2[flag.key] = {
+        value: flag.defaultValue,
+        reason: "error" /* ERROR */,
+        errorMessage
+      };
+    }
+    return results2;
+  }
+  const baseMetrics = {
+    readMs: datafile.metrics.readMs,
+    source: datafile.metrics.source,
+    cacheStatus: datafile.metrics.cacheStatus,
+    connectionState: datafile.metrics.connectionState,
+    mode: datafile.metrics.mode
+  };
+  const projectId = datafile.projectId;
+  const results = {};
+  const toEvaluate = {};
+  for (const flag of flags) {
+    const { key, defaultValue } = flag;
+    const flagDefinition = datafile.definitions[key];
+    if (flagDefinition === void 0) {
+      if (projectId) {
+        internalReportValue(key, defaultValue, {
+          originProjectId: projectId,
+          originProvider: "vercel",
+          reason: "error" /* ERROR */
+        });
+      }
+      results[key] = {
+        value: defaultValue,
+        reason: "error" /* ERROR */,
+        errorCode: "FLAG_NOT_FOUND" /* FLAG_NOT_FOUND */,
+        errorMessage: `@vercel/flags-core: Definition not found for flag "${key}"`,
+        metrics: { evaluationMs: 0, ...baseMetrics }
+      };
+      continue;
+    }
+    toEvaluate[key] = { definition: flagDefinition, defaultValue };
+  }
+  const evalStartTime = Date.now();
+  const evaluated = bulkEvaluate(toEvaluate, {
+    entities: entities ?? {},
+    environment: datafile.environment,
+    segments: datafile.segments
+  });
+  const evaluationDurationMs = Date.now() - evalStartTime;
+  for (const key in toEvaluate) {
+    const result = evaluated[key];
+    if (projectId) {
+      internalReportValue(key, result.value, {
+        originProjectId: projectId,
+        originProvider: "vercel",
+        reason: result.reason,
+        outcomeType: result.reason !== "error" /* ERROR */ ? result.outcomeType : void 0
+      });
+    }
+    results[key] = Object.assign(result, {
+      metrics: { evaluationMs: evaluationDurationMs, ...baseMetrics }
+    });
+  }
+  return results;
+}
 
 // src/create-raw-client.ts
 var idCount = 0;
@@ -623,6 +726,16 @@ function createCreateRawClient(fns) {
           }
         }
         return fns.evaluate(id, flagKey, defaultValue, entities);
+      },
+      bulkEvaluate: async (flags, entities) => {
+        const instance = controllerInstanceMap.get(id);
+        if (!instance?.initialized) {
+          try {
+            await api.initialize();
+          } catch {
+          }
+        }
+        return fns.bulkEvaluate(id, flags, entities);
       }
     };
     return api;
@@ -677,6 +790,23 @@ async function readBundledDefinitions(sdkKey) {
 
 // src/utils/usage-tracker.ts
 import { waitUntil } from "@vercel/functions";
+
+// src/utils/backoff.ts
+var DEFAULT_BASE_MS = 250;
+var DEFAULT_CAP_MS = 5e3;
+function getRetryDelayMs(attempt, options = {}) {
+  const baseMs = options.baseMs ?? DEFAULT_BASE_MS;
+  const capMs = options.capMs ?? DEFAULT_CAP_MS;
+  const ceiling = Math.min(capMs, baseMs * 2 ** Math.max(0, attempt - 1));
+  return Math.floor(Math.random() * ceiling);
+}
+function getJitteredWaitMs(baseMs, ratio) {
+  const min = baseMs * (1 - ratio);
+  const span = baseMs * 2 * ratio;
+  return Math.floor(min + Math.random() * span);
+}
+
+// src/utils/usage-tracker.ts
 var RESOLVED_VOID = Promise.resolve();
 var isDebugMode = process.env.DEBUG?.includes("@vercel/flags-core");
 var debugLog = (...args) => {
@@ -686,6 +816,7 @@ var debugLog = (...args) => {
 var MAX_RETRIES = 3;
 var MAX_BATCH_SIZE = 50;
 var MAX_BATCH_WAIT_MS = 5e3;
+var BATCH_WAIT_JITTER_RATIO = 0.2;
 var SYMBOL_FOR_REQ_CONTEXT = /* @__PURE__ */ Symbol.for("@vercel/request-context");
 var fromSymbol = globalThis;
 function getRequestContext() {
@@ -792,7 +923,10 @@ var UsageTracker = class {
       const pending = (async () => {
         await new Promise((res) => {
           this.batcher.resolveWait = res;
-          timeout = setTimeout(res, MAX_BATCH_WAIT_MS);
+          timeout = setTimeout(
+            res,
+            getJitteredWaitMs(MAX_BATCH_WAIT_MS, BATCH_WAIT_JITTER_RATIO)
+          );
         });
         this.batcher.pending = null;
         this.batcher.resolveWait = null;
@@ -846,7 +980,12 @@ Response body: ${await response.text().catch(() => null)}`
           error
         );
         if (attempt < MAX_RETRIES) {
-          await new Promise((res) => setTimeout(res, attempt * 100));
+          const delayMs = getRetryDelayMs(attempt);
+          await new Promise((res) => setTimeout(res, delayMs));
+        } else {
+          console.error(
+            `@vercel/flags-core: Dropped ${eventsToSend.length} events after ${MAX_RETRIES} attempts (flushId=${flushId})`
+          );
         }
       }
     }
@@ -1384,6 +1523,11 @@ var Controller = class {
   state = "idle";
   // Data state — tagged with origin
   data;
+  // Memoized data spread for read() / getDatafile().
+  // Rebuilt only when `this.data` reference changes (e.g. on stream/poll update).
+  // Holds the result of stripping `_origin`; metrics are appended per-call.
+  dataViewSource = void 0;
+  dataViewBase = void 0;
   // Sources (I/O delegates)
   streamSource;
   pollingSource;
@@ -1555,11 +1699,15 @@ var Controller = class {
     this.isFirstGetData = false;
     const [result, cacheStatus] = await this.resolveData();
     const readMs = Date.now() - startTime;
-    const { _origin, ...data } = result;
-    const source = originToMetricsSource(_origin);
+    const source = originToMetricsSource(result._origin);
     this.trackRead(startTime, cacheHadDefinitions, isFirstRead, source);
+    if (this.dataViewSource !== result) {
+      const { _origin, ...rest } = result;
+      this.dataViewBase = rest;
+      this.dataViewSource = result;
+    }
     return {
-      ...data,
+      ...this.dataViewBase,
       metrics: {
         readMs,
         source,
@@ -1619,8 +1767,13 @@ var Controller = class {
       }
     }
     const source = originToMetricsSource(result._origin);
+    if (this.dataViewSource !== result) {
+      const { _origin, ...rest } = result;
+      this.dataViewBase = rest;
+      this.dataViewSource = result;
+    }
     return {
-      ...result,
+      ...this.dataViewBase,
       metrics: {
         readMs: Date.now() - startTime,
         source,
@@ -2045,4 +2198,4 @@ export {
   resetDefaultFlagsClient,
   createClient
 };
-//# sourceMappingURL=chunk-OABKRAPP.js.map
+//# sourceMappingURL=chunk-IMGERCR6.js.map