@vercel/flags-core 1.1.0-cea788b-20260305194413 → 1.1.0

package/dist/index.default.d.cts

@@ -1,10 +1,10 @@
-import { D as DatafileInput, S as StreamOptions, P as PollingOptions, a as DataSource, b as Datafile, B as BundledDefinitions, E as EvaluationParams, c as EvaluationResult, F as FlagsClient } from './types-CpRz8o4d.cjs';
-export { d as Packed, R as Reason } from './types-CpRz8o4d.cjs';
+import { D as DatafileInput, S as StreamOptions, P as PollingOptions, C as ControllerInterface, a as Datafile, B as BundledDefinitions, E as EvaluationParams, b as EvaluationResult, F as FlagsClient } from './types-DtnecWgl.cjs';
+export { c as Packed, R as Reason } from './types-DtnecWgl.cjs';
 
 /**
- * Configuration options for FlagNetworkDataSource
+ * Configuration options for Controller
  */
-type FlagNetworkDataSourceOptions = {
+type ControllerOptions = {
     /** SDK key for authentication (must start with "vf_") */
     sdkKey: string;
     /**
@@ -43,44 +43,61 @@ type FlagNetworkDataSourceOptions = {
      */
     fetch?: typeof globalThis.fetch;
 };
+
 /**
- * A DataSource implementation that connects to flags.vercel.com.
+ * Connects to flags.vercel.com and manages flag definitions.
  *
- * Behavior differs based on environment:
+ * Implemented as a state machine controller that delegates all I/O to
+ * source modules (StreamSource, PollingSource, BundledSource).
  *
  * **Build step** (CI=1 or Next.js build, or buildStep: true):
- * - Uses datafile (if provided) or bundled definitions
- * - No streaming or polling (avoids network during build)
+ * - Uses datafile (if provided), bundled definitions, or one-time fetch as fallback
+ * - No streaming or polling
+ *
+ * **Runtime — streaming mode** (stream enabled):
+ * - Uses streaming exclusively; polling is never started, even if configured
+ * - Init fallback (no data yet): constructor datafile → bundled → throw
+ * - Read fallback (post-init): in-memory value → constructor datafile → bundled → throw
  *
- * **Runtime** (default):
- * - Tries stream first, then poll, then datafile, then bundled
- * - Stream and polling never run simultaneously
- * - If stream reconnects while polling → stop polling
- * - If stream disconnects → start polling (if enabled)
+ * **Runtime — polling mode** (polling enabled, stream disabled):
+ * - Uses polling exclusively
+ * - Same fallback chains as streaming mode
+ *
+ * **Runtime — offline mode** (neither stream nor polling):
+ * - Init fallback: constructor datafile → bundled → one-time fetch → throw
+ * - Read fallback: in-memory value → constructor datafile → bundled → one-time fetch → throw
  */
-declare class FlagNetworkDataSource implements DataSource {
+declare class Controller implements ControllerInterface {
     private options;
-    private host;
+    private state;
     private data;
-    private bundledDefinitionsPromise;
-    private streamAbortController;
-    private streamPromise;
-    private isStreamConnected;
-    private hasWarnedAboutStaleData;
-    private pollingIntervalId;
-    private pollingAbortController;
-    private isInitializing;
+    private streamSource;
+    private pollingSource;
+    private bundledSource;
     private usageTracker;
     private isFirstGetData;
-    /**
-     * Creates a new FlagNetworkDataSource instance.
-     */
-    constructor(options: FlagNetworkDataSourceOptions);
+    private buildDataPromise;
+    private buildReadTracked;
+    private unauthorized;
+    constructor(options: ControllerOptions);
+    private onStreamData;
+    private onStreamPrimed;
+    private onStreamConnected;
+    private onStreamDisconnected;
+    private onPollData;
+    private onPollError;
+    private wireSourceEvents;
+    private unwireSourceEvents;
+    private transition;
+    private get isConnected();
+    private get mode();
     /**
      * Initializes the data source.
      *
-     * Build step: datafile → bundled → fetch
-     * Runtime: stream → poll → datafile → bundled
+     * Build step: datafile → bundled → one-time fetch
+     * Streaming mode: stream → datafile → bundled
+     * Polling mode (no stream): poll → datafile → bundled
+     * Offline mode (neither): datafile → bundled → one-time fetch
      */
     initialize(): Promise<void>;
     /**
@@ -93,81 +110,60 @@ declare class FlagNetworkDataSource implements DataSource {
     shutdown(): Promise<void>;
     /**
      * Returns the datafile with metrics.
-     *
-     * During builds this will read from the bundled file if available.
-     *
-     * This method never opens a streaming connection, but will read from
-     * the stream if it is already open. Otherwise it fetches over the network.
+     * Uses in-memory data if available, otherwise falls back to bundled,
+     * then to a one-time fetch if called without prior initialization.
      */
     getDatafile(): Promise<Datafile>;
     /**
      * Returns the bundled fallback datafile.
      */
     getFallbackDatafile(): Promise<BundledDefinitions>;
+    /**
+     * Resolves the current data, using the appropriate strategy for the
+     * current mode. Returns tagged data and cache status.
+     *
+     * Build step: cached → bundled → one-time fetch
+     * Runtime with cache: return cached data
+     * Runtime without cache: stream/poll → datafile → bundled → fetch → throw
+     */
+    private resolveData;
     /**
      * Attempts to initialize via stream with timeout.
      * Returns true if stream connected successfully within timeout.
      */
     private tryInitializeStream;
-    /**
-     * Starts the stream connection with callbacks for data and disconnect.
-     */
-    private startStream;
-    /**
-     * Stops the stream connection.
-     */
-    private stopStream;
     /**
      * Attempts to initialize via polling with timeout.
      * Returns true if first poll succeeded within timeout.
+     *
+     * Only used when streaming is disabled and polling is the primary source.
      */
     private tryInitializePolling;
-    /**
-     * Starts polling (initial poll + interval).
-     */
-    private startPolling;
-    /**
-     * Starts the polling interval (without initial poll).
-     */
-    private startPollingInterval;
-    /**
-     * Stops polling.
-     */
-    private stopPolling;
-    /**
-     * Performs a single poll request.
-     */
-    private performPoll;
-    /**
-     * Starts background updates (stream or polling) without blocking.
-     * Used when we already have data from provided datafile.
-     */
-    private startBackgroundUpdates;
     /**
      * Initializes data for build step environments.
      */
     private initializeForBuildStep;
     /**
      * Retrieves data during build steps.
+     * Concurrent callers share a single load promise. The first caller to
+     * populate `this.data` gets cacheStatus MISS; subsequent callers get HIT.
      */
-    private getDataForBuildStep;
+    private resolveDataForBuildStep;
     /**
-     * Returns data from the in-memory cache.
+     * Loads data for a build step: bundled → one-time fetch.
      */
-    private getDataFromCache;
+    private loadBuildData;
     /**
-     * Retrieves data using the fallback chain.
+     * Shared fallback chain used by both initialize() and resolveData().
      */
-    private getDataWithFallbacks;
+    private initializeFromFallbacks;
     /**
-     * Initializes from bundled definitions.
+     * Retrieves data using the fallback chain (called when no cached data exists).
+     * Streaming mode: stream → datafile → bundled.
+     * Polling mode: poll → datafile → bundled.
+     * Offline mode: datafile → bundled → one-time fetch.
      */
-    private initializeFromBundled;
-    /**
-     * Parses a configUpdatedAt value (number or string) into a numeric timestamp.
-     * Returns undefined if the value is missing or cannot be parsed.
-     */
-    private static parseConfigUpdatedAt;
+    private resolveDataWithFallbacks;
     /**
      * Checks if the incoming data is newer than the current in-memory data.
      * Returns true if the update should proceed, false if it should be skipped.
@@ -177,15 +173,12 @@ declare class FlagNetworkDataSource implements DataSource {
      * - The current data has no configUpdatedAt
      * - The incoming data has no configUpdatedAt
      *
-     * Skips the update only when both have configUpdatedAt and incoming is older.
+     * Skips the update only when both have configUpdatedAt and incoming is not newer.
      */
     private isNewerData;
-    /**
-     * Logs a warning if returning cached data while stream is disconnected.
-     */
-    private warnIfDisconnected;
     /**
      * Tracks a read operation for usage analytics.
+     * During build steps, only the first read is tracked.
      */
     private trackRead;
 }
@@ -197,7 +190,7 @@ declare class FlagNetworkDataSource implements DataSource {
 /**
  * Options for createClient
  */
-type CreateClientOptions = Omit<FlagNetworkDataSourceOptions, 'sdkKey'>;
+type CreateClientOptions = Omit<ControllerOptions, 'sdkKey'>;
 
 /**
  * Error thrown when the fallback definitions file does not exist.
@@ -227,7 +220,9 @@ declare function evaluate<T>(
 /**
  * The params used for the evaluation
  */
-params: EvaluationParams<T>): EvaluationResult<T>;
+params: EvaluationParams<T>, 
+/** Tracks visited environments to detect circular reuse. */
+_visited?: Set<string>): EvaluationResult<T>;
 
 declare const 
 /**
@@ -246,4 +241,4 @@ declare const /**
  */
 createClient: (sdkKeyOrConnectionString: string, options?: CreateClientOptions) => FlagsClient;
 
-export { BundledDefinitions, type CreateClientOptions, Datafile, DatafileInput, EvaluationParams, EvaluationResult, FallbackEntryNotFoundError, FallbackNotFoundError, FlagNetworkDataSource, type FlagNetworkDataSourceOptions, FlagsClient, PollingOptions, StreamOptions, createClient, evaluate, flagsClient, resetDefaultFlagsClient };
+export { BundledDefinitions, Controller, type ControllerOptions, type CreateClientOptions, Datafile, DatafileInput, EvaluationParams, EvaluationResult, FallbackEntryNotFoundError, FallbackNotFoundError, Controller as FlagNetworkDataSource, type ControllerOptions as FlagNetworkDataSourceOptions, FlagsClient, PollingOptions, StreamOptions, createClient, evaluate, flagsClient, resetDefaultFlagsClient };

package/dist/index.default.d.ts

@@ -1,10 +1,10 @@
-import { D as DatafileInput, S as StreamOptions, P as PollingOptions, a as DataSource, b as Datafile, B as BundledDefinitions, E as EvaluationParams, c as EvaluationResult, F as FlagsClient } from './types-CpRz8o4d.js';
-export { d as Packed, R as Reason } from './types-CpRz8o4d.js';
+import { D as DatafileInput, S as StreamOptions, P as PollingOptions, C as ControllerInterface, a as Datafile, B as BundledDefinitions, E as EvaluationParams, b as EvaluationResult, F as FlagsClient } from './types-DtnecWgl.js';
+export { c as Packed, R as Reason } from './types-DtnecWgl.js';
 
 /**
- * Configuration options for FlagNetworkDataSource
+ * Configuration options for Controller
  */
-type FlagNetworkDataSourceOptions = {
+type ControllerOptions = {
     /** SDK key for authentication (must start with "vf_") */
     sdkKey: string;
     /**
@@ -43,44 +43,61 @@ type FlagNetworkDataSourceOptions = {
      */
     fetch?: typeof globalThis.fetch;
 };
+
 /**
- * A DataSource implementation that connects to flags.vercel.com.
+ * Connects to flags.vercel.com and manages flag definitions.
  *
- * Behavior differs based on environment:
+ * Implemented as a state machine controller that delegates all I/O to
+ * source modules (StreamSource, PollingSource, BundledSource).
  *
  * **Build step** (CI=1 or Next.js build, or buildStep: true):
- * - Uses datafile (if provided) or bundled definitions
- * - No streaming or polling (avoids network during build)
+ * - Uses datafile (if provided), bundled definitions, or one-time fetch as fallback
+ * - No streaming or polling
+ *
+ * **Runtime — streaming mode** (stream enabled):
+ * - Uses streaming exclusively; polling is never started, even if configured
+ * - Init fallback (no data yet): constructor datafile → bundled → throw
+ * - Read fallback (post-init): in-memory value → constructor datafile → bundled → throw
  *
- * **Runtime** (default):
- * - Tries stream first, then poll, then datafile, then bundled
- * - Stream and polling never run simultaneously
- * - If stream reconnects while polling → stop polling
- * - If stream disconnects → start polling (if enabled)
+ * **Runtime — polling mode** (polling enabled, stream disabled):
+ * - Uses polling exclusively
+ * - Same fallback chains as streaming mode
+ *
+ * **Runtime — offline mode** (neither stream nor polling):
+ * - Init fallback: constructor datafile → bundled → one-time fetch → throw
+ * - Read fallback: in-memory value → constructor datafile → bundled → one-time fetch → throw
  */
-declare class FlagNetworkDataSource implements DataSource {
+declare class Controller implements ControllerInterface {
     private options;
-    private host;
+    private state;
     private data;
-    private bundledDefinitionsPromise;
-    private streamAbortController;
-    private streamPromise;
-    private isStreamConnected;
-    private hasWarnedAboutStaleData;
-    private pollingIntervalId;
-    private pollingAbortController;
-    private isInitializing;
+    private streamSource;
+    private pollingSource;
+    private bundledSource;
     private usageTracker;
     private isFirstGetData;
-    /**
-     * Creates a new FlagNetworkDataSource instance.
-     */
-    constructor(options: FlagNetworkDataSourceOptions);
+    private buildDataPromise;
+    private buildReadTracked;
+    private unauthorized;
+    constructor(options: ControllerOptions);
+    private onStreamData;
+    private onStreamPrimed;
+    private onStreamConnected;
+    private onStreamDisconnected;
+    private onPollData;
+    private onPollError;
+    private wireSourceEvents;
+    private unwireSourceEvents;
+    private transition;
+    private get isConnected();
+    private get mode();
     /**
      * Initializes the data source.
      *
-     * Build step: datafile → bundled → fetch
-     * Runtime: stream → poll → datafile → bundled
+     * Build step: datafile → bundled → one-time fetch
+     * Streaming mode: stream → datafile → bundled
+     * Polling mode (no stream): poll → datafile → bundled
+     * Offline mode (neither): datafile → bundled → one-time fetch
      */
     initialize(): Promise<void>;
     /**
@@ -93,81 +110,60 @@ declare class FlagNetworkDataSource implements DataSource {
     shutdown(): Promise<void>;
     /**
      * Returns the datafile with metrics.
-     *
-     * During builds this will read from the bundled file if available.
-     *
-     * This method never opens a streaming connection, but will read from
-     * the stream if it is already open. Otherwise it fetches over the network.
+     * Uses in-memory data if available, otherwise falls back to bundled,
+     * then to a one-time fetch if called without prior initialization.
      */
     getDatafile(): Promise<Datafile>;
     /**
      * Returns the bundled fallback datafile.
      */
     getFallbackDatafile(): Promise<BundledDefinitions>;
+    /**
+     * Resolves the current data, using the appropriate strategy for the
+     * current mode. Returns tagged data and cache status.
+     *
+     * Build step: cached → bundled → one-time fetch
+     * Runtime with cache: return cached data
+     * Runtime without cache: stream/poll → datafile → bundled → fetch → throw
+     */
+    private resolveData;
     /**
      * Attempts to initialize via stream with timeout.
      * Returns true if stream connected successfully within timeout.
      */
     private tryInitializeStream;
-    /**
-     * Starts the stream connection with callbacks for data and disconnect.
-     */
-    private startStream;
-    /**
-     * Stops the stream connection.
-     */
-    private stopStream;
     /**
      * Attempts to initialize via polling with timeout.
      * Returns true if first poll succeeded within timeout.
+     *
+     * Only used when streaming is disabled and polling is the primary source.
      */
     private tryInitializePolling;
-    /**
-     * Starts polling (initial poll + interval).
-     */
-    private startPolling;
-    /**
-     * Starts the polling interval (without initial poll).
-     */
-    private startPollingInterval;
-    /**
-     * Stops polling.
-     */
-    private stopPolling;
-    /**
-     * Performs a single poll request.
-     */
-    private performPoll;
-    /**
-     * Starts background updates (stream or polling) without blocking.
-     * Used when we already have data from provided datafile.
-     */
-    private startBackgroundUpdates;
     /**
      * Initializes data for build step environments.
      */
     private initializeForBuildStep;
     /**
      * Retrieves data during build steps.
+     * Concurrent callers share a single load promise. The first caller to
+     * populate `this.data` gets cacheStatus MISS; subsequent callers get HIT.
      */
-    private getDataForBuildStep;
+    private resolveDataForBuildStep;
     /**
-     * Returns data from the in-memory cache.
+     * Loads data for a build step: bundled → one-time fetch.
      */
-    private getDataFromCache;
+    private loadBuildData;
     /**
-     * Retrieves data using the fallback chain.
+     * Shared fallback chain used by both initialize() and resolveData().
      */
-    private getDataWithFallbacks;
+    private initializeFromFallbacks;
     /**
-     * Initializes from bundled definitions.
+     * Retrieves data using the fallback chain (called when no cached data exists).
+     * Streaming mode: stream → datafile → bundled.
+     * Polling mode: poll → datafile → bundled.
+     * Offline mode: datafile → bundled → one-time fetch.
      */
-    private initializeFromBundled;
-    /**
-     * Parses a configUpdatedAt value (number or string) into a numeric timestamp.
-     * Returns undefined if the value is missing or cannot be parsed.
-     */
-    private static parseConfigUpdatedAt;
+    private resolveDataWithFallbacks;
     /**
      * Checks if the incoming data is newer than the current in-memory data.
      * Returns true if the update should proceed, false if it should be skipped.
@@ -177,15 +173,12 @@ declare class FlagNetworkDataSource implements DataSource {
      * - The current data has no configUpdatedAt
      * - The incoming data has no configUpdatedAt
      *
-     * Skips the update only when both have configUpdatedAt and incoming is older.
+     * Skips the update only when both have configUpdatedAt and incoming is not newer.
      */
     private isNewerData;
-    /**
-     * Logs a warning if returning cached data while stream is disconnected.
-     */
-    private warnIfDisconnected;
     /**
      * Tracks a read operation for usage analytics.
+     * During build steps, only the first read is tracked.
      */
     private trackRead;
 }
@@ -197,7 +190,7 @@ declare class FlagNetworkDataSource implements DataSource {
 /**
  * Options for createClient
  */
-type CreateClientOptions = Omit<FlagNetworkDataSourceOptions, 'sdkKey'>;
+type CreateClientOptions = Omit<ControllerOptions, 'sdkKey'>;
 
 /**
  * Error thrown when the fallback definitions file does not exist.
@@ -227,7 +220,9 @@ declare function evaluate<T>(
 /**
  * The params used for the evaluation
  */
-params: EvaluationParams<T>): EvaluationResult<T>;
+params: EvaluationParams<T>, 
+/** Tracks visited environments to detect circular reuse. */
+_visited?: Set<string>): EvaluationResult<T>;
 
 declare const 
 /**
@@ -246,4 +241,4 @@ declare const /**
  */
 createClient: (sdkKeyOrConnectionString: string, options?: CreateClientOptions) => FlagsClient;
 
-export { BundledDefinitions, type CreateClientOptions, Datafile, DatafileInput, EvaluationParams, EvaluationResult, FallbackEntryNotFoundError, FallbackNotFoundError, FlagNetworkDataSource, type FlagNetworkDataSourceOptions, FlagsClient, PollingOptions, StreamOptions, createClient, evaluate, flagsClient, resetDefaultFlagsClient };
+export { BundledDefinitions, Controller, type ControllerOptions, type CreateClientOptions, Datafile, DatafileInput, EvaluationParams, EvaluationResult, FallbackEntryNotFoundError, FallbackNotFoundError, Controller as FlagNetworkDataSource, type ControllerOptions as FlagNetworkDataSourceOptions, FlagsClient, PollingOptions, StreamOptions, createClient, evaluate, flagsClient, resetDefaultFlagsClient };

package/dist/index.default.js

@@ -1,17 +1,18 @@
 import {
+  Controller,
   FallbackEntryNotFoundError,
   FallbackNotFoundError,
-  FlagNetworkDataSource,
   ResolutionReason,
   createClient,
   evaluate,
   flagsClient,
   resetDefaultFlagsClient
-} from "./chunk-EB6T2UJ6.js";
+} from "./chunk-J33BA25D.js";
 export {
+  Controller,
   FallbackEntryNotFoundError,
   FallbackNotFoundError,
-  FlagNetworkDataSource,
+  Controller as FlagNetworkDataSource,
   ResolutionReason as Reason,
   createClient,
   evaluate,

package/dist/index.next-js.cjs

@@ -7,7 +7,7 @@
 
 
 
-var _chunk326YN2YTcjs = require('./chunk-326YN2YT.cjs');
+var _chunkLBP3OTYAcjs = require('./chunk-LBP3OTYA.cjs');
 
 
 
@@ -17,5 +17,6 @@ var _chunk326YN2YTcjs = require('./chunk-326YN2YT.cjs');
 
 
 
-exports.FallbackEntryNotFoundError = _chunk326YN2YTcjs.FallbackEntryNotFoundError; exports.FallbackNotFoundError = _chunk326YN2YTcjs.FallbackNotFoundError; exports.FlagNetworkDataSource = _chunk326YN2YTcjs.FlagNetworkDataSource; exports.Reason = _chunk326YN2YTcjs.ResolutionReason; exports.createClient = _chunk326YN2YTcjs.createClient; exports.evaluate = _chunk326YN2YTcjs.evaluate; exports.flagsClient = _chunk326YN2YTcjs.flagsClient; exports.resetDefaultFlagsClient = _chunk326YN2YTcjs.resetDefaultFlagsClient;
+
+exports.Controller = _chunkLBP3OTYAcjs.Controller; exports.FallbackEntryNotFoundError = _chunkLBP3OTYAcjs.FallbackEntryNotFoundError; exports.FallbackNotFoundError = _chunkLBP3OTYAcjs.FallbackNotFoundError; exports.FlagNetworkDataSource = _chunkLBP3OTYAcjs.Controller; exports.Reason = _chunkLBP3OTYAcjs.ResolutionReason; exports.createClient = _chunkLBP3OTYAcjs.createClient; exports.evaluate = _chunkLBP3OTYAcjs.evaluate; exports.flagsClient = _chunkLBP3OTYAcjs.flagsClient; exports.resetDefaultFlagsClient = _chunkLBP3OTYAcjs.resetDefaultFlagsClient;
 //# sourceMappingURL=index.next-js.cjs.map

package/dist/index.next-js.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/flags/flags/packages/vercel-flags-core/dist/index.next-js.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,igBAAC","file":"/home/runner/work/flags/flags/packages/vercel-flags-core/dist/index.next-js.cjs"}
+{"version":3,"sources":["/home/runner/work/flags/flags/packages/vercel-flags-core/dist/index.next-js.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yiBAAC","file":"/home/runner/work/flags/flags/packages/vercel-flags-core/dist/index.next-js.cjs"}