@zudojs/feature-flags 1.4.2 → 1.5.0

package/README.md

@@ -105,7 +105,15 @@ default was `true`. For a variant flag, declare the variant to fall back to:
 
 Rules are evaluated in declaration order and the first match wins. The
 subject for `percentage` and `variant` is `userId`, then `tenantId`, then
-`sessionId`, then `"anonymous"`.
+`sessionId`, then `"anonymous"`. That default splits an organisation whenever
+the context carries both a `userId` and a `tenantId`; pin the subject with
+`bucketBy` to roll out per tenant (or per session):
+
+```ts
+{ type: "percentage", percentage: 10, value: true, bucketBy: "tenantId" }
+```
+
+With `bucketBy` set, a context missing that field does not match the rule.
 
 Operators: `equals`, `not_equals`, `contains`, `starts_with`, `ends_with`,
 `in`, `not_in`, `greater_than`, `greater_than_or_equal`, `less_than`,

package/dist/evaluator/evaluator.core.d.ts

@@ -35,4 +35,3 @@ export interface EvaluateFlagOptions {
  * @returns A structured evaluation result.
  */
 export declare function evaluateFlag<TValue extends FeatureFlagValue = FeatureFlagValue>(flag: FeatureFlag, context?: FeatureFlagContext, options?: EvaluateFlagOptions): FeatureFlagEvaluation<TValue>;
-//# sourceMappingURL=evaluator.core.d.ts.map

package/dist/evaluator/evaluator.core.js

@@ -85,4 +85,3 @@ export function evaluateFlag(flag, context = {}, options = {}) {
         defaulted: true,
     };
 }
-//# sourceMappingURL=evaluator.core.js.map

package/dist/evaluator/evaluatorAttribute.d.ts

@@ -28,4 +28,3 @@ export declare function resolvePath(obj: unknown, path: string): unknown;
  * @returns Whether the condition matches.
  */
 export declare function matchAttribute(actual: unknown, operator: FeatureFlagOperator, expected: unknown): boolean;
-//# sourceMappingURL=evaluatorAttribute.d.ts.map

package/dist/evaluator/evaluatorAttribute.js

@@ -143,4 +143,3 @@ export function matchAttribute(actual, operator, expected) {
             return false;
     }
 }
-//# sourceMappingURL=evaluatorAttribute.js.map

package/dist/evaluator/evaluatorGate.core.d.ts

@@ -32,4 +32,3 @@ export declare function gateReason(flag: FeatureFlag, options: EvaluateFlagOptio
  * @returns The value to serve.
  */
 export declare function offValueOf(flag: FeatureFlag): FeatureFlagValue;
-//# sourceMappingURL=evaluatorGate.core.d.ts.map

package/dist/evaluator/evaluatorGate.core.js

@@ -65,4 +65,3 @@ export function offValueOf(flag) {
         return false;
     return flag.defaultValue;
 }
-//# sourceMappingURL=evaluatorGate.core.js.map

package/dist/evaluator/evaluatorPattern.safety.d.ts

@@ -20,4 +20,3 @@ export declare const MAX_MATCH_INPUT_LENGTH = 1024;
  * `^(beta|alpha)-` — contain neither.
  */
 export declare function isUnsafePattern(pattern: string): boolean;
-//# sourceMappingURL=evaluatorPattern.safety.d.ts.map

package/dist/evaluator/evaluatorPattern.safety.js

@@ -76,4 +76,3 @@ export function isUnsafePattern(pattern) {
     }
     return false;
 }
-//# sourceMappingURL=evaluatorPattern.safety.js.map

package/dist/evaluator/evaluatorRule.core.d.ts

@@ -26,4 +26,3 @@ export interface RuleEvaluationResult {
  * @returns The evaluation result.
  */
 export declare function evaluateRule(rule: FeatureFlagRule, context: FeatureFlagContext, flagKey: string): RuleEvaluationResult;
-//# sourceMappingURL=evaluatorRule.core.d.ts.map

package/dist/evaluator/evaluatorRule.core.js

@@ -5,7 +5,7 @@
  *
  * @module evaluator/evaluatorRule
  */
-import { getBucket, isInRollout } from "../rollout/rolloutBucketing.js";
+import { getBucket, isInRollout, resolveRolloutSubject, } from "../rollout/rolloutBucketing.js";
 import { matchAttribute, resolvePath } from "./evaluatorAttribute.js";
 /** Bucket resolution for variant assignment — 0.01% precision. */
 const VARIANT_BUCKETS = 10_000;
@@ -42,7 +42,9 @@ export function evaluateRule(rule, context, flagKey) {
             return { matched, value: matched ? (rule.result ?? true) : undefined };
         }
         case "percentage": {
-            const subject = context.userId ?? context.tenantId ?? context.sessionId ?? "anonymous";
+            const subject = resolveRolloutSubject(context, rule.bucketBy);
+            if (subject === undefined)
+                return { matched: false };
             const matched = isInRollout(flagKey, subject, rule.percentage);
             return { matched, value: matched ? rule.value : undefined };
         }
@@ -58,7 +60,9 @@ export function evaluateRule(rule, context, flagKey) {
             return { matched, value: matched ? rule.value : undefined };
         }
         case "variant": {
-            const subject = context.userId ?? context.tenantId ?? context.sessionId ?? "anonymous";
+            const subject = resolveRolloutSubject(context, rule.bucketBy);
+            if (subject === undefined)
+                return { matched: false };
             // Negative or non-finite weights would make the cumulative walk
             // non-monotonic, shifting every downstream variant's band, so they are
             // treated as zero.
@@ -95,4 +99,3 @@ export function evaluateRule(rule, context, flagKey) {
             return { matched: false };
     }
 }
-//# sourceMappingURL=evaluatorRule.core.js.map

package/dist/evaluator/index.d.ts

@@ -7,4 +7,3 @@ export { resolvePath, matchAttribute } from "./evaluatorAttribute.js";
 export { evaluateRule } from "./evaluatorRule.core.js";
 export type { RuleEvaluationResult } from "./evaluatorRule.core.js";
 export { evaluateFlag } from "./evaluator.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/evaluator/index.js

@@ -6,4 +6,3 @@
 export { resolvePath, matchAttribute } from "./evaluatorAttribute.js";
 export { evaluateRule } from "./evaluatorRule.core.js";
 export { evaluateFlag } from "./evaluator.core.js";
-//# sourceMappingURL=index.js.map

package/dist/featureFlagErrors/featureFlagError.base.d.ts

@@ -21,4 +21,3 @@ export interface FeatureFlagErrorOptions {
 export declare class FeatureFlagError extends ApplicationError {
     constructor(message: string, options?: FeatureFlagErrorOptions);
 }
-//# sourceMappingURL=featureFlagError.base.d.ts.map

package/dist/featureFlagErrors/featureFlagError.base.js

@@ -21,4 +21,3 @@ export class FeatureFlagError extends ApplicationError {
         this.name = "FeatureFlagError";
     }
 }
-//# sourceMappingURL=featureFlagError.base.js.map

package/dist/featureFlagErrors/featureFlagError.types.d.ts

@@ -35,4 +35,3 @@ export declare class FeatureFlagConfigurationError extends FeatureFlagError {
 export declare class FeatureFlagTypeError extends FeatureFlagError {
     constructor(key: string, expected: string, actual: string);
 }
-//# sourceMappingURL=featureFlagError.types.d.ts.map

package/dist/featureFlagErrors/featureFlagError.types.js

@@ -76,4 +76,3 @@ export class FeatureFlagTypeError extends FeatureFlagError {
         this.name = "FeatureFlagTypeError";
     }
 }
-//# sourceMappingURL=featureFlagError.types.js.map

package/dist/featureFlagErrors/index.d.ts

@@ -6,4 +6,3 @@
 export { FeatureFlagError } from "./featureFlagError.base.js";
 export type { FeatureFlagErrorOptions } from "./featureFlagError.base.js";
 export { FeatureFlagNotFoundError, FeatureFlagProviderError, FeatureFlagEvaluationError, FeatureFlagRuleError, FeatureFlagDependencyError, FeatureFlagConfigurationError, FeatureFlagTypeError, } from "./featureFlagError.types.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/featureFlagErrors/index.js

@@ -5,4 +5,3 @@
  */
 export { FeatureFlagError } from "./featureFlagError.base.js";
 export { FeatureFlagNotFoundError, FeatureFlagProviderError, FeatureFlagEvaluationError, FeatureFlagRuleError, FeatureFlagDependencyError, FeatureFlagConfigurationError, FeatureFlagTypeError, } from "./featureFlagError.types.js";
-//# sourceMappingURL=index.js.map

package/dist/featureFlagTypes/featureFlag.interface.d.ts

@@ -56,4 +56,3 @@ export interface FeatureFlag {
     /** Additional metadata. */
     readonly metadata?: FeatureFlagMetadata;
 }
-//# sourceMappingURL=featureFlag.interface.d.ts.map

package/dist/featureFlagTypes/featureFlag.interface.js

@@ -6,4 +6,3 @@
  * @module featureFlagTypes/featureFlag
  */
 export {};
-//# sourceMappingURL=featureFlag.interface.js.map

package/dist/featureFlagTypes/featureFlagContext.d.ts

@@ -18,4 +18,3 @@ export interface FeatureFlagContext {
     /** Custom attributes for attribute-based targeting. */
     readonly attributes?: Readonly<Record<string, unknown>>;
 }
-//# sourceMappingURL=featureFlagContext.d.ts.map

package/dist/featureFlagTypes/featureFlagContext.js

@@ -6,4 +6,3 @@
  * @module featureFlagTypes/featureFlagContext
  */
 export {};
-//# sourceMappingURL=featureFlagContext.js.map

package/dist/featureFlagTypes/featureFlagEvaluation.d.ts

@@ -23,4 +23,3 @@ export interface FeatureFlagEvaluation<TValue = FeatureFlagValue> {
     /** Whether the default value was used. */
     readonly defaulted: boolean;
 }
-//# sourceMappingURL=featureFlagEvaluation.d.ts.map

package/dist/featureFlagTypes/featureFlagEvaluation.js

@@ -6,4 +6,3 @@
  * @module featureFlagTypes/featureFlagEvaluation
  */
 export {};
-//# sourceMappingURL=featureFlagEvaluation.js.map

package/dist/featureFlagTypes/featureFlagProvider.d.ts

@@ -31,4 +31,3 @@ export interface FeatureFlagProvider {
 export interface RefreshableFeatureFlagProvider extends FeatureFlagProvider {
     refresh(): Promise<void>;
 }
-//# sourceMappingURL=featureFlagProvider.d.ts.map

package/dist/featureFlagTypes/featureFlagProvider.js

@@ -6,4 +6,3 @@
  * @module featureFlagTypes/featureFlagProvider
  */
 export {};
-//# sourceMappingURL=featureFlagProvider.js.map

package/dist/featureFlagTypes/featureFlagRule/featureFlagRule.type.d.ts

@@ -42,11 +42,24 @@ export interface FeatureFlagAttributeRule {
     /** The value served when the rule matches. Default: `true`. */
     readonly result?: FeatureFlagValue;
 }
+/**
+ * Which context field a rollout hashes on.
+ *
+ * Without `bucketBy`, the subject is `userId`, then `tenantId`, then
+ * `sessionId`, then `"anonymous"` — so for a context carrying both a user
+ * and a tenant, members of one tenant land in different buckets. Set
+ * `bucketBy: "tenantId"` to roll a flag out per organisation. When the
+ * named field is absent from the context the rule does not match, rather
+ * than silently bucketing on something else.
+ */
+export type FeatureFlagBucketBy = "userId" | "tenantId" | "sessionId";
 /** Percentage-based rollout — deterministic per subject. */
 export interface FeatureFlagPercentageRule {
     readonly type: "percentage";
     readonly percentage: number;
     readonly value: FeatureFlagValue;
+    /** Context field to bucket on; see {@link FeatureFlagBucketBy}. */
+    readonly bucketBy?: FeatureFlagBucketBy;
 }
 /** Time-windowed rule — enabled only within a date range. */
 export interface FeatureFlagScheduleRule {
@@ -59,6 +72,8 @@ export interface FeatureFlagScheduleRule {
 export interface FeatureFlagVariantRule {
     readonly type: "variant";
     readonly variants: readonly FeatureFlagVariant[];
+    /** Context field to bucket on; see {@link FeatureFlagBucketBy}. */
+    readonly bucketBy?: FeatureFlagBucketBy;
 }
 /** A variant with a weight for percentage-based assignment. */
 export interface FeatureFlagVariant {
@@ -67,4 +82,3 @@ export interface FeatureFlagVariant {
 }
 /** Union of all feature flag rule types. */
 export type FeatureFlagRule = FeatureFlagStaticRule | FeatureFlagUserRule | FeatureFlagTenantRule | FeatureFlagAttributeRule | FeatureFlagPercentageRule | FeatureFlagScheduleRule | FeatureFlagVariantRule;
-//# sourceMappingURL=featureFlagRule.type.d.ts.map

package/dist/featureFlagTypes/featureFlagRule/featureFlagRule.type.js

@@ -6,4 +6,3 @@
  * @module featureFlagTypes/featureFlagRule
  */
 export {};
-//# sourceMappingURL=featureFlagRule.type.js.map

package/dist/featureFlagTypes/featureFlagRule/featureFlagValue.type.d.ts

@@ -11,4 +11,3 @@ export type FeatureFlagValue = boolean | string | number | null | Record<string,
 export type FeatureFlagState = "active" | "disabled" | "archived" | "draft";
 /** Feature flag visibility scope. */
 export type FeatureFlagVisibility = "server" | "client";
-//# sourceMappingURL=featureFlagValue.type.d.ts.map

package/dist/featureFlagTypes/featureFlagRule/featureFlagValue.type.js

@@ -6,4 +6,3 @@
  * @module featureFlagTypes/featureFlagValue
  */
 export {};
-//# sourceMappingURL=featureFlagValue.type.js.map

package/dist/featureFlagTypes/featureFlagRule/index.d.ts

@@ -5,4 +5,3 @@
  */
 export * from "./featureFlagRule.type.js";
 export * from "./featureFlagValue.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/featureFlagTypes/featureFlagRule/index.js

@@ -5,4 +5,3 @@
  */
 export * from "./featureFlagRule.type.js";
 export * from "./featureFlagValue.type.js";
-//# sourceMappingURL=index.js.map

package/dist/featureFlagTypes/index.d.ts

@@ -6,4 +6,3 @@ export type { FeatureFlagContext } from "./featureFlagContext.js";
 export type { FeatureFlagMetadata, FeatureFlag, } from "./featureFlag.interface.js";
 export type { FeatureFlagEvaluationReason, FeatureFlagEvaluation, } from "./featureFlagEvaluation.js";
 export type { FeatureFlagProvider, RefreshableFeatureFlagProvider, FeatureFlagChangeListener, Unsubscribe, } from "./featureFlagProvider.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/featureFlagTypes/index.js

@@ -2,4 +2,3 @@
  * Feature flag type definitions.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/featureFlags/featureFlags.cooloff.d.ts

@@ -24,4 +24,3 @@ export interface ProviderCooloff {
  * clears the window immediately. `cooloffMs <= 0` disables the gate.
  */
 export declare function createProviderCooloff(cooloffMs: number): ProviderCooloff;
-//# sourceMappingURL=featureFlags.cooloff.d.ts.map

package/dist/featureFlags/featureFlags.cooloff.js

@@ -31,4 +31,3 @@ export function createProviderCooloff(cooloffMs) {
         },
     };
 }
-//# sourceMappingURL=featureFlags.cooloff.js.map

package/dist/featureFlags/featureFlags.core.d.ts

@@ -67,4 +67,3 @@ export interface FeatureFlags {
  * @returns A FeatureFlags API object.
  */
 export declare function createFeatureFlags(options: FeatureFlagsOptions): FeatureFlags;
-//# sourceMappingURL=featureFlags.core.d.ts.map

package/dist/featureFlags/featureFlags.core.js

@@ -200,4 +200,3 @@ export function createFeatureFlags(options) {
     };
     return api;
 }
-//# sourceMappingURL=featureFlags.core.js.map

package/dist/featureFlags/featureFlags.dependency.d.ts

@@ -31,4 +31,3 @@ export declare function isDependencyOn(evaluation: FeatureFlagEvaluation): boole
  * @param memo - Results for this context, so a diamond is walked once.
  */
 export declare function dependenciesOn(flag: FeatureFlag, registry: FeatureFlagRegistry, context: FeatureFlagContext, chain?: Set<string>, memo?: Map<string, boolean>): boolean;
-//# sourceMappingURL=featureFlags.dependency.d.ts.map

package/dist/featureFlags/featureFlags.dependency.js

@@ -69,4 +69,3 @@ export function dependenciesOn(flag, registry, context, chain = new Set([flag.ke
     }
     return true;
 }
-//# sourceMappingURL=featureFlags.dependency.js.map

package/dist/featureFlags/featureFlags.missCache.d.ts

@@ -23,4 +23,3 @@ export interface MissCache {
  * evicted). `ttlMs <= 0` disables it.
  */
 export declare function createMissCache(ttlMs: number): MissCache;
-//# sourceMappingURL=featureFlags.missCache.d.ts.map

package/dist/featureFlags/featureFlags.missCache.js

@@ -46,4 +46,3 @@ export function createMissCache(ttlMs) {
         },
     };
 }
-//# sourceMappingURL=featureFlags.missCache.js.map

package/dist/featureFlags/featureFlags.resolve.d.ts

@@ -24,4 +24,3 @@ export declare function resolveDependencies(key: string, registry: FeatureFlagRe
  * Merge default context with provided context.
  */
 export declare function mergeContext(defaultContext: FeatureFlagContext, context?: FeatureFlagContext): FeatureFlagContext;
-//# sourceMappingURL=featureFlags.resolve.d.ts.map

package/dist/featureFlags/featureFlags.resolve.js

@@ -46,4 +46,3 @@ export function mergeContext(defaultContext, context) {
         },
     };
 }
-//# sourceMappingURL=featureFlags.resolve.js.map

package/dist/featureFlags/index.d.ts

@@ -5,4 +5,3 @@
  */
 export { createFeatureFlags } from "./featureFlags.core.js";
 export type { FeatureFlagsOptions } from "./featureFlags.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/featureFlags/index.js

@@ -4,4 +4,3 @@
  * @module featureFlags
  */
 export { createFeatureFlags } from "./featureFlags.core.js";
-//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { FeatureFlagError } from "./featureFlagErrors/featureFlagError.base.js";
 export type { FeatureFlagErrorOptions } from "./featureFlagErrors/featureFlagError.base.js";
 export { FeatureFlagNotFoundError, FeatureFlagProviderError, FeatureFlagEvaluationError, FeatureFlagRuleError, FeatureFlagDependencyError, FeatureFlagConfigurationError, FeatureFlagTypeError, } from "./featureFlagErrors/featureFlagError.types.js";
 export { hashString } from "./rollout/rolloutHashing.js";
-export { getBucket, isInRollout } from "./rollout/rolloutBucketing.js";
+export { getBucket, isInRollout, resolveRolloutSubject, } from "./rollout/rolloutBucketing.js";
 export { createMemoryProvider } from "./provider/providerMemory.core.js";
 export type { MemoryFeatureFlagProvider } from "./provider/providerMemory.core.js";
 export { createEnvironmentProvider } from "./provider/providerEnvironment.core.js";
@@ -29,4 +29,3 @@ export { createFeatureFlags } from "./featureFlags/featureFlags.core.js";
 export type { FeatureFlags, FeatureFlagsOptions, } from "./featureFlags/featureFlags.core.js";
 export { resolveDependencies, mergeContext, } from "./featureFlags/featureFlags.resolve.js";
 export { isPlainObject, valuesEqual } from "./utils/utils.helper.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -10,7 +10,7 @@ export { FeatureFlagError } from "./featureFlagErrors/featureFlagError.base.js";
 export { FeatureFlagNotFoundError, FeatureFlagProviderError, FeatureFlagEvaluationError, FeatureFlagRuleError, FeatureFlagDependencyError, FeatureFlagConfigurationError, FeatureFlagTypeError, } from "./featureFlagErrors/featureFlagError.types.js";
 // ─── Rollout ──────────────────────────────────────────────────────────────
 export { hashString } from "./rollout/rolloutHashing.js";
-export { getBucket, isInRollout } from "./rollout/rolloutBucketing.js";
+export { getBucket, isInRollout, resolveRolloutSubject, } from "./rollout/rolloutBucketing.js";
 // ─── Providers ────────────────────────────────────────────────────────────
 export { createMemoryProvider } from "./provider/providerMemory.core.js";
 export { createEnvironmentProvider } from "./provider/providerEnvironment.core.js";
@@ -27,4 +27,3 @@ export { createFeatureFlags } from "./featureFlags/featureFlags.core.js";
 export { resolveDependencies, mergeContext, } from "./featureFlags/featureFlags.resolve.js";
 // ─── Utils ────────────────────────────────────────────────────────────────
 export { isPlainObject, valuesEqual } from "./utils/utils.helper.js";
-//# sourceMappingURL=index.js.map

package/dist/provider/index.d.ts

@@ -9,4 +9,3 @@ export type { EnvironmentProviderOptions } from "./providerEnvironment.core.js";
 export { createCompositeProvider } from "./providerComposite.core.js";
 export { createCachedProvider } from "./providerCached.core.js";
 export type { CachedProviderOptions } from "./providerCached.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/provider/index.js

@@ -7,4 +7,3 @@ export { createMemoryProvider } from "./providerMemory.core.js";
 export { createEnvironmentProvider } from "./providerEnvironment.core.js";
 export { createCompositeProvider } from "./providerComposite.core.js";
 export { createCachedProvider } from "./providerCached.core.js";
-//# sourceMappingURL=index.js.map

package/dist/provider/providerCached.core.d.ts

@@ -25,4 +25,3 @@ export interface CachedProviderOptions {
  * @returns A provider with in-memory TTL caching.
  */
 export declare function createCachedProvider(inner: FeatureFlagProvider, options?: CachedProviderOptions): RefreshableFeatureFlagProvider;
-//# sourceMappingURL=providerCached.core.d.ts.map

package/dist/provider/providerCached.core.js

@@ -78,4 +78,3 @@ export function createCachedProvider(inner, options = {}) {
         },
     };
 }
-//# sourceMappingURL=providerCached.core.js.map

package/dist/provider/providerComposite.core.d.ts

@@ -16,4 +16,3 @@ import type { FeatureFlagProvider, RefreshableFeatureFlagProvider } from "../fea
  * @returns A composite FeatureFlagProvider.
  */
 export declare function createCompositeProvider(providers: readonly FeatureFlagProvider[]): RefreshableFeatureFlagProvider;
-//# sourceMappingURL=providerComposite.core.d.ts.map

package/dist/provider/providerComposite.core.js

@@ -93,4 +93,3 @@ export function createCompositeProvider(providers) {
         },
     };
 }
-//# sourceMappingURL=providerComposite.core.js.map

package/dist/provider/providerEnvironment.core.d.ts

@@ -44,4 +44,3 @@ export declare function toEnvironmentFlagKey(key: string): string;
  * @returns A provider that reads from environment variables.
  */
 export declare function createEnvironmentProvider(options?: EnvironmentProviderOptions): RefreshableFeatureFlagProvider;
-//# sourceMappingURL=providerEnvironment.core.d.ts.map

package/dist/provider/providerEnvironment.core.js

@@ -79,4 +79,3 @@ export function createEnvironmentProvider(options = {}) {
         },
     };
 }
-//# sourceMappingURL=providerEnvironment.core.js.map

package/dist/provider/providerMemory.core.d.ts

@@ -30,4 +30,3 @@ export interface MemoryFeatureFlagProvider extends FeatureFlagProvider {
  * @returns A FeatureFlagProvider backed by a Map.
  */
 export declare function createMemoryProvider(flags?: readonly FeatureFlag[]): MemoryFeatureFlagProvider;
-//# sourceMappingURL=providerMemory.core.d.ts.map

package/dist/provider/providerMemory.core.js

@@ -67,4 +67,3 @@ export function createMemoryProvider(flags = []) {
         },
     };
 }
-//# sourceMappingURL=providerMemory.core.js.map

package/dist/registry/index.d.ts

@@ -5,4 +5,3 @@
  */
 export { createFeatureFlagRegistry } from "./registry.core.js";
 export type { FeatureFlagRegistry } from "./registry.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.js

@@ -4,4 +4,3 @@
  * @module registry
  */
 export { createFeatureFlagRegistry } from "./registry.core.js";
-//# sourceMappingURL=index.js.map

package/dist/registry/registry.core.d.ts

@@ -32,4 +32,3 @@ export interface FeatureFlagRegistry {
  * @returns A FeatureFlagRegistry instance.
  */
 export declare function createFeatureFlagRegistry(flags?: readonly FeatureFlag[]): FeatureFlagRegistry;
-//# sourceMappingURL=registry.core.d.ts.map

package/dist/registry/registry.core.js

@@ -44,4 +44,3 @@ export function createFeatureFlagRegistry(flags = []) {
         },
     };
 }
-//# sourceMappingURL=registry.core.js.map

package/dist/rollout/index.d.ts

@@ -4,5 +4,4 @@
  * @module rollout
  */
 export { hashString } from "./rolloutHashing.js";
-export { getBucket, isInRollout } from "./rolloutBucketing.js";
-//# sourceMappingURL=index.d.ts.map
+export { getBucket, isInRollout, resolveRolloutSubject, } from "./rolloutBucketing.js";

package/dist/rollout/index.js

@@ -4,5 +4,4 @@
  * @module rollout
  */
 export { hashString } from "./rolloutHashing.js";
-export { getBucket, isInRollout } from "./rolloutBucketing.js";
-//# sourceMappingURL=index.js.map
+export { getBucket, isInRollout, resolveRolloutSubject, } from "./rolloutBucketing.js";

package/dist/rollout/rolloutBucketing.d.ts

@@ -6,6 +6,8 @@
  *
  * @module rollout/rolloutBucketing
  */
+import type { FeatureFlagContext } from "../featureFlagTypes/featureFlagContext.js";
+import type { FeatureFlagBucketBy } from "../featureFlagTypes/featureFlagRule/featureFlagRule.type.js";
 /**
  * Compute a deterministic bucket for a flag rollout.
  *
@@ -24,4 +26,16 @@ export declare function getBucket(key: string, subject: string, buckets?: number
  * @returns Whether the subject is in the rollout.
  */
 export declare function isInRollout(key: string, subject: string, percentage: number): boolean;
-//# sourceMappingURL=rolloutBucketing.d.ts.map
+/**
+ * Pick the identifier a percentage or variant rule buckets on.
+ *
+ * With `bucketBy` set, only that field counts: `undefined` is returned when
+ * the context lacks it, and the caller treats the rule as not matched.
+ * Without it, the default chain applies — `userId`, then `tenantId`, then
+ * `sessionId`, then `"anonymous"`.
+ *
+ * @param context - The evaluation context.
+ * @param bucketBy - The rule's `bucketBy`, if any.
+ * @returns The subject to hash, or `undefined` when a pinned field is absent.
+ */
+export declare function resolveRolloutSubject(context: FeatureFlagContext, bucketBy?: FeatureFlagBucketBy): string | undefined;

package/dist/rollout/rolloutBucketing.js

@@ -39,4 +39,22 @@ export function isInRollout(key, subject, percentage) {
     const bucket = getBucket(key, subject, buckets);
     return bucket < threshold;
 }
-//# sourceMappingURL=rolloutBucketing.js.map
+/**
+ * Pick the identifier a percentage or variant rule buckets on.
+ *
+ * With `bucketBy` set, only that field counts: `undefined` is returned when
+ * the context lacks it, and the caller treats the rule as not matched.
+ * Without it, the default chain applies — `userId`, then `tenantId`, then
+ * `sessionId`, then `"anonymous"`.
+ *
+ * @param context - The evaluation context.
+ * @param bucketBy - The rule's `bucketBy`, if any.
+ * @returns The subject to hash, or `undefined` when a pinned field is absent.
+ */
+export function resolveRolloutSubject(context, bucketBy) {
+    if (bucketBy !== undefined) {
+        const pinned = context[bucketBy];
+        return typeof pinned === "string" && pinned.length > 0 ? pinned : undefined;
+    }
+    return context.userId ?? context.tenantId ?? context.sessionId ?? "anonymous";
+}

package/dist/rollout/rolloutHashing.d.ts

@@ -12,4 +12,3 @@
  * @returns An unsigned 32-bit integer hash.
  */
 export declare function hashString(value: string): number;
-//# sourceMappingURL=rolloutHashing.d.ts.map

package/dist/rollout/rolloutHashing.js

@@ -23,4 +23,3 @@ export function hashString(value) {
     }
     return hash >>> 0;
 }
-//# sourceMappingURL=rolloutHashing.js.map

package/dist/utils/index.d.ts

@@ -4,4 +4,3 @@
  * @module utils
  */
 export { isPlainObject, valuesEqual } from "./utils.helper.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -4,4 +4,3 @@
  * @module utils
  */
 export { isPlainObject, valuesEqual } from "./utils.helper.js";
-//# sourceMappingURL=index.js.map

package/dist/utils/utils.helper.d.ts

@@ -24,4 +24,3 @@ export { isPlainObject } from "@zudojs/types";
  * so the walk lives here rather than pulling in a new dependency.
  */
 export declare function valuesEqual(a: FeatureFlagValue, b: FeatureFlagValue): boolean;
-//# sourceMappingURL=utils.helper.d.ts.map

package/dist/utils/utils.helper.js

@@ -77,4 +77,3 @@ function isComparableObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
-//# sourceMappingURL=utils.helper.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/feature-flags",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Feature flag system with deterministic rollouts, rule engine, providers, variants, snapshots, and evaluation context.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,8 +11,8 @@
     }
   },
   "dependencies": {
-    "@zudojs/errors": "1.3.2",
-    "@zudojs/types": "1.2.0"
+    "@zudojs/errors": "1.4.0",
+    "@zudojs/types": "1.3.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",