@pylonsync/feature-flags 0.3.83

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@pylonsync/feature-flags",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.3.83",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@pylonsync/sdk": "0.3.81",
+    "@pylonsync/functions": "0.3.81"
+  },
+  "peerDependencies": {
+    "bun-types": "*"
+  },
+  "peerDependenciesMeta": {
+    "bun-types": {
+    "optional": true
+  }
+}
+}

package/src/eval.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, test } from "bun:test";
+
+import { evaluate, hashBucket } from "./eval";
+import type { BooleanFlag, MultivariateFlag } from "./types";
+
+describe("hashBucket", () => {
+	test("0% rollout always returns false", () => {
+		expect(hashBucket("user_1", 0)).toBe(false);
+		expect(hashBucket("user_2", 0)).toBe(false);
+	});
+
+	test("100% rollout always returns true", () => {
+		expect(hashBucket("user_1", 100)).toBe(true);
+		expect(hashBucket("user_2", 100)).toBe(true);
+	});
+
+	test("50% rollout distributes ~uniformly", () => {
+		let hits = 0;
+		const N = 10000;
+		for (let i = 0; i < N; i++) {
+			if (hashBucket(`u_${i}`, 50)) hits++;
+		}
+		const ratio = hits / N;
+		expect(ratio).toBeGreaterThan(0.45);
+		expect(ratio).toBeLessThan(0.55);
+	});
+
+	test("same key + percent = same answer (deterministic)", () => {
+		const v1 = hashBucket("user_42", 25);
+		const v2 = hashBucket("user_42", 25);
+		expect(v1).toBe(v2);
+	});
+});
+
+describe("boolean flag evaluation", () => {
+	test("default value when no rollout", () => {
+		const flag: BooleanFlag = { type: "boolean", default: true };
+		const r = evaluate(flag, { userId: "u_1" });
+		expect(r.value).toBe(true);
+		expect(r.matched).toBe("default");
+	});
+
+	test("rollout splits users", () => {
+		const flag: BooleanFlag = {
+			type: "boolean",
+			default: true,
+			rollout: { percent: 100 },
+		};
+		const r = evaluate(flag, { userId: "u_1" });
+		expect(r.value).toBe(true);
+		expect(r.matched).toBe("rollout");
+	});
+
+	test("targeting rule beats rollout", () => {
+		const flag: BooleanFlag = {
+			type: "boolean",
+			default: false,
+			rollout: { percent: 0 },
+			targeting: [
+				{
+					value: true,
+					when: [{ property: "plan", op: "eq", value: "enterprise" }],
+				},
+			],
+		};
+		const r = evaluate(flag, {
+			userId: "u_1",
+			properties: { plan: "enterprise" },
+		});
+		expect(r.value).toBe(true);
+		expect(r.matched).toBe("targeting");
+	});
+
+	test("targeting predicates AND together", () => {
+		const flag: BooleanFlag = {
+			type: "boolean",
+			default: false,
+			targeting: [
+				{
+					value: true,
+					when: [
+						{ property: "plan", op: "eq", value: "pro" },
+						{ property: "betaTester", op: "eq", value: true },
+					],
+				},
+			],
+		};
+		// Only one predicate satisfied — should fall back to default.
+		const r1 = evaluate(flag, {
+			userId: "u_1",
+			properties: { plan: "pro", betaTester: false },
+		});
+		expect(r1.value).toBe(false);
+		// Both satisfied — rule fires.
+		const r2 = evaluate(flag, {
+			userId: "u_1",
+			properties: { plan: "pro", betaTester: true },
+		});
+		expect(r2.value).toBe(true);
+	});
+
+	test("contains / starts_with / ends_with predicates", () => {
+		const flag: BooleanFlag = {
+			type: "boolean",
+			default: false,
+			targeting: [
+				{
+					value: true,
+					when: [{ property: "email", op: "ends_with", value: "@acme.com" }],
+				},
+			],
+		};
+		expect(
+			evaluate(flag, {
+				userId: "u_1",
+				properties: { email: "ceo@acme.com" },
+			}).value,
+		).toBe(true);
+		expect(
+			evaluate(flag, {
+				userId: "u_1",
+				properties: { email: "ceo@elsewhere.com" },
+			}).value,
+		).toBe(false);
+	});
+});
+
+describe("multivariate flag evaluation", () => {
+	test("variants distribute by weight", () => {
+		const flag: MultivariateFlag = {
+			type: "multivariate",
+			default: "control",
+			variants: [
+				{ name: "control", weight: 50 },
+				{ name: "treatment", weight: 50 },
+			],
+		};
+		let treatment = 0;
+		const N = 10000;
+		for (let i = 0; i < N; i++) {
+			const r = evaluate(flag, { userId: `u_${i}` });
+			if (r.value === "treatment") treatment++;
+		}
+		const ratio = treatment / N;
+		expect(ratio).toBeGreaterThan(0.45);
+		expect(ratio).toBeLessThan(0.55);
+	});
+
+	test("payload is returned when set", () => {
+		const flag: MultivariateFlag = {
+			type: "multivariate",
+			default: "v1",
+			variants: [
+				{ name: "v1", weight: 100, payload: { maxTokens: 1000 } },
+			],
+		};
+		const r = evaluate(flag, { userId: "u_1" });
+		expect(r.value).toEqual({ maxTokens: 1000 });
+	});
+});

package/src/eval.ts

@@ -0,0 +1,178 @@
+/**
+ * Flag evaluation. Pure functions over a flag catalog + an eval
+ * context. No state, no I/O — making this trivially testable +
+ * cheap to call on hot paths.
+ */
+
+import type {
+	BooleanFlag,
+	EvalContext,
+	FlagDefinition,
+	FlagValue,
+	MultivariateFlag,
+	TargetingPredicate,
+	TargetingRule,
+} from "./types";
+
+export function evaluate(
+	flag: FlagDefinition,
+	ctx: EvalContext,
+): { value: FlagValue; matched: "default" | "targeting" | "rollout" } {
+	// Targeting rules are first — they override rollout. First
+	// match wins.
+	if (flag.type === "boolean") {
+		const ruleHit = firstMatchingRule(flag.targeting ?? [], ctx);
+		if (ruleHit !== undefined) return { value: ruleHit, matched: "targeting" };
+		return evalBooleanRollout(flag, ctx);
+	}
+	const ruleHit = firstMatchingRule(flag.targeting ?? [], ctx);
+	if (ruleHit !== undefined) {
+		const variant = flag.variants.find((v) => v.name === ruleHit);
+		return {
+			value: (variant?.payload as FlagValue) ?? ruleHit,
+			matched: "targeting",
+		};
+	}
+	return evalMultivariate(flag, ctx);
+}
+
+function evalBooleanRollout(
+	flag: BooleanFlag,
+	ctx: EvalContext,
+): { value: boolean; matched: "default" | "rollout" } {
+	if (!flag.rollout) {
+		return { value: flag.default, matched: "default" };
+	}
+	const bucketKey = pickBucketKey(flag.rollout.key ?? "userId", ctx);
+	if (!bucketKey) return { value: flag.default, matched: "default" };
+	const bucket = hashBucket(bucketKey, flag.rollout.percent);
+	return {
+		value: bucket ? flag.default : !flag.default,
+		matched: "rollout",
+	};
+}
+
+function evalMultivariate(
+	flag: MultivariateFlag,
+	ctx: EvalContext,
+): { value: string | Record<string, unknown>; matched: "default" } {
+	const bucketKey = pickBucketKey("userId", ctx);
+	if (!bucketKey) {
+		const def = flag.variants.find((v) => v.name === flag.default);
+		return {
+			value: (def?.payload as Record<string, unknown>) ?? flag.default,
+			matched: "default",
+		};
+	}
+	const variant = weightedPick(flag.variants, bucketKey);
+	return {
+		value: (variant.payload as Record<string, unknown>) ?? variant.name,
+		matched: "default",
+	};
+}
+
+function firstMatchingRule<T>(
+	rules: TargetingRule<T>[],
+	ctx: EvalContext,
+): T | undefined {
+	for (const rule of rules) {
+		if (rule.when.every((p) => matchPredicate(p, ctx))) return rule.value;
+	}
+	return undefined;
+}
+
+function matchPredicate(p: TargetingPredicate, ctx: EvalContext): boolean {
+	const props = ctx.properties ?? {};
+	// Specials: userId / orgId / deviceId come from the top-level
+	// context fields, not the properties bag.
+	let actual: unknown;
+	if (p.property === "userId") actual = ctx.userId;
+	else if (p.property === "orgId") actual = ctx.orgId;
+	else if (p.property === "deviceId") actual = ctx.deviceId;
+	else actual = props[p.property];
+
+	switch (p.op) {
+		case "eq":
+			return actual === p.value;
+		case "neq":
+			return actual !== p.value;
+		case "in":
+			return Array.isArray(p.value) && p.value.includes(actual as never);
+		case "not_in":
+			return Array.isArray(p.value) && !p.value.includes(actual as never);
+		case "gt":
+			return typeof actual === "number" && actual > (p.value as number);
+		case "gte":
+			return typeof actual === "number" && actual >= (p.value as number);
+		case "lt":
+			return typeof actual === "number" && actual < (p.value as number);
+		case "lte":
+			return typeof actual === "number" && actual <= (p.value as number);
+		case "contains":
+			return typeof actual === "string" && actual.includes(p.value as string);
+		case "starts_with":
+			return typeof actual === "string" && actual.startsWith(p.value as string);
+		case "ends_with":
+			return typeof actual === "string" && actual.endsWith(p.value as string);
+		case "regex":
+			try {
+				return (
+					typeof actual === "string" &&
+					new RegExp(p.value as string).test(actual)
+				);
+			} catch {
+				return false;
+			}
+	}
+	return false;
+}
+
+function pickBucketKey(
+	keyName: string,
+	ctx: EvalContext,
+): string | undefined {
+	if (keyName === "userId") return ctx.userId;
+	if (keyName === "orgId") return ctx.orgId;
+	if (keyName === "deviceId") return ctx.deviceId;
+	const v = ctx.properties?.[keyName];
+	return typeof v === "string" ? v : undefined;
+}
+
+/**
+ * Deterministic bucketing. The hash is FNV-1a (cheap, well-
+ * distributed) over the bucketKey; map to 0..99 and compare against
+ * the rollout percent.
+ *
+ * Why not SHA-256: bucket calls are on the hot path (every
+ * isEnabled() check), and FNV-1a gives near-uniform distribution
+ * for the input domain (32-char IDs) at a fraction of the cost.
+ * Same primitive PostHog uses for local-eval bucketing.
+ */
+export function hashBucket(key: string, percent: number): boolean {
+	let h = 0x811c9dc5;
+	for (let i = 0; i < key.length; i++) {
+		h ^= key.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	const bucket = ((h >>> 0) % 10000) / 100; // 0..99.99
+	return bucket < percent;
+}
+
+function weightedPick<T extends { name: string; weight: number }>(
+	variants: T[],
+	key: string,
+): T {
+	const totalWeight = variants.reduce((s, v) => s + v.weight, 0);
+	let h = 0x811c9dc5;
+	for (let i = 0; i < key.length; i++) {
+		h ^= key.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	const point = ((h >>> 0) % totalWeight) + 1;
+	let acc = 0;
+	for (const v of variants) {
+		acc += v.weight;
+		if (point <= acc) return v;
+	}
+	return variants[variants.length - 1];
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+/**
+ * Public API.
+ *
+ * Two surfaces:
+ *   - Inline catalog: declare flags in TS, evaluate via `isEnabled` /
+ *     `getVariant` / `getPayload` over a process-local `flags` object.
+ *   - Editable catalog: stored in a `FeatureFlag` entity, mutated via
+ *     admin actions, cached in-process. Useful for kill switches that
+ *     ops needs to flip without a redeploy.
+ *
+ * The plugin doesn't ship an A/B testing analyzer — that's a different
+ * concern (compute statistical significance from event logs). Pair
+ * with @pylonsync/audit-log to record `flag.assigned` events for
+ * downstream analysis.
+ */
+
+export { evaluate, hashBucket } from "./eval";
+export type {
+	BooleanFlag,
+	MultivariateFlag,
+	FlagDefinition,
+	FlagValue,
+	RolloutConfig,
+	TargetingRule,
+	TargetingPredicate,
+	EvalContext,
+	FlagPluginConfig,
+} from "./types";
+
+import { evaluate } from "./eval";
+import type { EvalContext, FlagDefinition } from "./types";
+
+/**
+ * Boolean check. Returns the resolved boolean for the flag in the
+ * given eval context. Unknown flag names return `false` (closed by
+ * default — apps that want different semantics for unknown keys
+ * check via `getRawValue`).
+ */
+export function isEnabled(
+	flags: Record<string, FlagDefinition>,
+	name: string,
+	ctx: EvalContext,
+): boolean {
+	const def = flags[name];
+	if (!def || def.type !== "boolean") return false;
+	const r = evaluate(def, ctx);
+	return Boolean(r.value);
+}
+
+/**
+ * Multivariate check. Returns the variant name (or default if the
+ * flag is missing / typed wrong).
+ */
+export function getVariant(
+	flags: Record<string, FlagDefinition>,
+	name: string,
+	ctx: EvalContext,
+): string {
+	const def = flags[name];
+	if (!def || def.type !== "multivariate") return "";
+	const r = evaluate(def, ctx);
+	return typeof r.value === "string" ? r.value : "";
+}
+
+/**
+ * Variant payload (JSON config). Useful for remote-config style flags
+ * where each variant carries different settings (rate limits, model
+ * choice, copy strings).
+ */
+export function getPayload(
+	flags: Record<string, FlagDefinition>,
+	name: string,
+	ctx: EvalContext,
+): unknown {
+	const def = flags[name];
+	if (!def) return undefined;
+	const r = evaluate(def, ctx);
+	return r.value;
+}
+
+/**
+ * Bulk evaluation — useful for SSR bootstrapping where the client
+ * receives every flag's resolved value with the initial page load.
+ * Returns `{ [flagName]: value }`.
+ */
+export function evaluateAll(
+	flags: Record<string, FlagDefinition>,
+	ctx: EvalContext,
+): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const [name, def] of Object.entries(flags)) {
+		out[name] = evaluate(def, ctx).value;
+	}
+	return out;
+}

package/src/types.ts

@@ -0,0 +1,120 @@
+/**
+ * `@pylonsync/feature-flags` — local-eval feature flags for Pylon
+ * apps. Boolean + multivariate flags, percentage rollouts, targeting
+ * rules, JSON payloads per variant, kill switches.
+ *
+ * Local-eval means there's no network call per check — flag
+ * definitions are loaded into the process once at startup, and
+ * `isEnabled(flag, ctx)` is a deterministic in-memory computation.
+ * That's the same model PostHog/LaunchDarkly local-eval mode uses
+ * and is what makes flag checks viable on hot request paths
+ * (e.g. inside auth or middleware).
+ *
+ * Flag definitions live in the app's `FeatureFlag` entity (declared
+ * via the manifest fragment); apps mutate them via the dashboard
+ * actions exposed in `handlers/`. The plugin caches the flag list
+ * in-process and invalidates on `setFlag` mutations.
+ */
+
+export type FlagValue = boolean | string | Record<string, unknown>;
+
+export interface BooleanFlag {
+	type: "boolean";
+	default: boolean;
+	/**
+	 * Rollout config. If absent, the default value is returned for
+	 * everyone. If `percent` is set, `default` is the value for
+	 * users in the rollout; non-rollout users get `!default`.
+	 */
+	rollout?: RolloutConfig;
+	/** Optional targeting rules — first match wins. */
+	targeting?: TargetingRule<boolean>[];
+}
+
+export interface MultivariateFlag {
+	type: "multivariate";
+	/** Variant catalog. Weights must sum to 100. */
+	variants: Array<{ name: string; weight: number; payload?: unknown }>;
+	/** Default variant name when no targeting rule matches. */
+	default: string;
+	/** Optional targeting rules — first match wins. */
+	targeting?: TargetingRule<string>[];
+}
+
+export type FlagDefinition = BooleanFlag | MultivariateFlag;
+
+export interface RolloutConfig {
+	/** 0..100 — percentage of distinct-ids that get the rollout. */
+	percent: number;
+	/**
+	 * Hashing key used to bucket users. Default `userId`. Set to
+	 * `orgId` for per-tenant rollouts (every member of the tenant
+	 * sees the same value), or a custom key for cohort experiments.
+	 */
+	key?: "userId" | "orgId" | "deviceId" | string;
+}
+
+export interface TargetingRule<TValue> {
+	value: TValue;
+	when: TargetingPredicate[];
+}
+
+/**
+ * Composable predicate. Multiple predicates AND together. Each
+ * compares a `property` (looked up on the eval context) to a
+ * literal `value` via an operator.
+ */
+export interface TargetingPredicate {
+	property: string;
+	op:
+		| "eq"
+		| "neq"
+		| "in"
+		| "not_in"
+		| "gt"
+		| "gte"
+		| "lt"
+		| "lte"
+		| "contains"
+		| "starts_with"
+		| "ends_with"
+		| "regex";
+	value: string | number | boolean | Array<string | number>;
+}
+
+export interface EvalContext {
+	/** Stable user identifier — drives default bucketing. */
+	userId?: string;
+	orgId?: string;
+	deviceId?: string;
+	/**
+	 * Free-form properties consulted by targeting rules. Apps
+	 * stuff whatever signal they want here (`country`, `plan`,
+	 * `betaTester`, `signupDaysAgo`, etc.).
+	 */
+	properties?: Record<string, unknown>;
+	/**
+	 * Server-side `now` injectable for tests. Defaults to
+	 * `Date.now()`.
+	 */
+	now?: number;
+}
+
+export interface FlagPluginConfig {
+	/**
+	 * Inline flag catalog. Apps that want their flags in code (e.g.
+	 * to keep them in version control) declare them here. Apps that
+	 * want runtime-editable flags omit this and use the
+	 * `FeatureFlag` entity instead.
+	 */
+	flags?: Record<string, FlagDefinition>;
+	/**
+	 * Database-backed flags. When true, the manifest fragment adds
+	 * a `FeatureFlag` entity + a `setFlag`/`deleteFlag` admin
+	 * mutation pair. The runtime merges inline + database flags
+	 * with database winning.
+	 */
+	editable?: boolean;
+	/** Entity name override. */
+	entityName?: string;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun-types"]
+  },
+  "include": [
+    "src"
+  ]
+}