@zudojs/feature-flags 0.0.1

package/dist/rollout/rolloutBucketing.js

@@ -0,0 +1,42 @@
+/**
+ * Deterministic bucketing for percentage rollouts.
+ *
+ * Maps a (flag key, subject) pair to a bucket in [0, buckets).
+ * Supports sub-percent precision with 10,000 buckets.
+ *
+ * @module rollout/rolloutBucketing
+ */
+import { hashString } from "./rolloutHashing.js";
+/** Default number of buckets — 10,000 allows 0.01% precision. */
+const DEFAULT_BUCKETS = 10_000;
+/**
+ * Compute a deterministic bucket for a flag rollout.
+ *
+ * @param key - The feature flag key.
+ * @param subject - The subject identifier (e.g. userId, tenantId).
+ * @param buckets - Total number of buckets (default 10,000).
+ * @returns A bucket number in [0, buckets).
+ */
+export function getBucket(key, subject, buckets = DEFAULT_BUCKETS) {
+    const hash = hashString(`${key}:${subject}`);
+    return hash % buckets;
+}
+/**
+ * Check whether a subject falls within a percentage rollout.
+ *
+ * @param key - The feature flag key.
+ * @param subject - The subject identifier.
+ * @param percentage - Percentage from 0 to 100 (supports decimals like 25.5).
+ * @returns Whether the subject is in the rollout.
+ */
+export function isInRollout(key, subject, percentage) {
+    if (percentage <= 0)
+        return false;
+    if (percentage >= 100)
+        return true;
+    const buckets = 10_000;
+    const threshold = Math.round((percentage / 100) * buckets);
+    const bucket = getBucket(key, subject, buckets);
+    return bucket < threshold;
+}
+//# sourceMappingURL=rolloutBucketing.js.map

package/dist/rollout/rolloutBucketing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rolloutBucketing.js","sourceRoot":"","sources":["../../src/rollout/rolloutBucketing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,iEAAiE;AACjE,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CACvB,GAAW,EACX,OAAe,EACf,OAAO,GAAW,eAAe;IAEjC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,GAAG,IAAI,OAAO,EAAE,CAAC,CAAC;IAC7C,OAAO,IAAI,GAAG,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,GAAW,EACX,OAAe,EACf,UAAkB;IAElB,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,UAAU,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IAEnC,MAAM,OAAO,GAAG,MAAM,CAAC;IACvB,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAChD,OAAO,MAAM,GAAG,SAAS,CAAC;AAC5B,CAAC"}

package/dist/rollout/rolloutHashing.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deterministic string hashing using FNV-1a.
+ *
+ * Used for sticky percentage rollouts — same input always produces the same bucket.
+ *
+ * @module rollout/rolloutHashing
+ */
+/**
+ * Compute a deterministic 32-bit unsigned hash of a string using FNV-1a.
+ *
+ * @param value - The string to hash.
+ * @returns An unsigned 32-bit integer hash.
+ */
+export declare function hashString(value: string): number;
+//# sourceMappingURL=rolloutHashing.d.ts.map

package/dist/rollout/rolloutHashing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rolloutHashing.d.ts","sourceRoot":"","sources":["../../src/rollout/rolloutHashing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAShD"}

package/dist/rollout/rolloutHashing.js

@@ -0,0 +1,26 @@
+/**
+ * Deterministic string hashing using FNV-1a.
+ *
+ * Used for sticky percentage rollouts — same input always produces the same bucket.
+ *
+ * @module rollout/rolloutHashing
+ */
+/** FNV offset basis (32-bit). */
+const FNV_OFFSET_BASIS = 2166136261;
+/** FNV prime (32-bit). */
+const FNV_PRIME = 16777619;
+/**
+ * Compute a deterministic 32-bit unsigned hash of a string using FNV-1a.
+ *
+ * @param value - The string to hash.
+ * @returns An unsigned 32-bit integer hash.
+ */
+export function hashString(value) {
+    let hash = FNV_OFFSET_BASIS;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, FNV_PRIME);
+    }
+    return hash >>> 0;
+}
+//# sourceMappingURL=rolloutHashing.js.map

package/dist/rollout/rolloutHashing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rolloutHashing.js","sourceRoot":"","sources":["../../src/rollout/rolloutHashing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,iCAAiC;AACjC,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAEpC,0BAA0B;AAC1B,MAAM,SAAS,GAAG,QAAQ,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,IAAI,GAAG,gBAAgB,CAAC;IAE5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Feature flag utility helpers.
+ *
+ * @module utils
+ */
+export { isPlainObject, valuesEqual } from "./utils.helper.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,7 @@
+/**
+ * Feature flag utility helpers.
+ *
+ * @module utils
+ */
+export { isPlainObject, valuesEqual } from "./utils.helper.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

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

@@ -0,0 +1,15 @@
+/**
+ * Utility helpers for feature flags.
+ *
+ * @module utils/utils
+ */
+import type { FeatureFlagValue } from "../featureFlagTypes/featureFlagRule/featureFlagValue.type.js";
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Check if two feature flag values are equal.
+ */
+export declare function valuesEqual(a: FeatureFlagValue, b: FeatureFlagValue): boolean;
+//# sourceMappingURL=utils.helper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.helper.d.ts","sourceRoot":"","sources":["../../src/utils/utils.helper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8DAA8D,CAAC;AAErG;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAElC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAQ7E"}

package/dist/utils/utils.helper.js

@@ -0,0 +1,27 @@
+/**
+ * Utility helpers for feature flags.
+ *
+ * @module utils/utils
+ */
+/**
+ * Check if a value is a plain object (not null, not array).
+ */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Check if two feature flag values are equal.
+ */
+export function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a === "object" && typeof b === "object") {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    return false;
+}
+//# sourceMappingURL=utils.helper.js.map

package/dist/utils/utils.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.helper.js","sourceRoot":"","sources":["../../src/utils/utils.helper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,CAAmB,EAAE,CAAmB;IAClE,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,OAAO,CAAC,KAAK,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@zudojs/feature-flags",
+  "version": "0.0.1",
+  "description": "Feature flag system with deterministic rollouts, rule engine, providers, variants, snapshots, and evaluation context.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@zudojs/errors": "0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "module": "./dist/index.js",
+  "keywords": [
+    "zudojs",
+    "feature-flags",
+    "rollout",
+    "a-b-testing"
+  ],
+  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oyinlola-tech/zudo"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}