@voltro/plugin-flags 0.85.0 → 0.86.0

package/dist/lifecycle.js

@@ -0,0 +1,82 @@
+import { toDefinition as e } from "./evaluate.js";
+//#region src/lifecycle.ts
+var t = 864e5, n = (e) => typeof e == "number" ? e : Date.parse(e), r = (t, r) => {
+	let i = e(t);
+	if (i.enabled === !1) return {
+		shape: "constantOff",
+		reason: "enabled: false — resolves false for every caller"
+	};
+	if (i.schedule) {
+		let { activateAt: e, deactivateAt: t } = i.schedule;
+		if (t != null && r >= n(t)) return {
+			shape: "expired",
+			reason: `schedule.deactivateAt (${String(t)}) has passed — the flag can never be on again`
+		};
+		if (e != null && r < n(e)) return {
+			shape: "notYetActive",
+			reason: `schedule.activateAt (${String(e)}) is in the future — pending, not dead`
+		};
+	}
+	let a = i.rollout ?? 100;
+	if (a <= 0) return {
+		shape: "constantOff",
+		reason: `rollout: ${a} — nobody is in the rollout`
+	};
+	let o = (i.targeting?.length ?? 0) > 0, s = (i.variants?.length ?? 0) > 1, c = i.schedule !== void 0 && (i.schedule.ramp !== void 0 || i.schedule.deactivateAt != null && r < n(i.schedule.deactivateAt));
+	return a >= 100 && !o && !s && !c ? {
+		shape: "constantOn",
+		reason: "rollout 100 with no targeting, no variants and no live schedule — resolves true for every caller"
+	} : {
+		shape: "conditional",
+		reason: `still selects between callers (${[
+			a < 100 ? `rollout ${a}%` : void 0,
+			o ? `${i.targeting?.length} targeting rule(s)` : void 0,
+			s ? `${i.variants?.length} variants` : void 0,
+			c ? "a live schedule" : void 0
+		].filter((e) => e !== void 0).join(", ")})`
+	};
+}, i = [
+	"Reachability is not decided. \"Not evaluated since <date>\" is a measurement; \"this code path is dead\" is not decidable in general. A seasonal flag, a flag behind a route nobody visited this month, and a flag whose last call site was deleted are indistinguishable from here.",
+	"Only SERVER-side reads are counted as use: isFlagEnabled / requireFlag / flagValue and a gatedBy interception. A flag consulted only in the browser via useFlag() / useFlagValue() reads from the bulk set the server already sent, so it never reaches this report as a named read.",
+	"A \"bulk\" observation means the flag was INCLUDED in a flags.evaluate / flags.variants response. It does not mean any client read that key — one useFlags() poll evaluates the whole registry.",
+	"The window is bounded by retention (see coverage.retentionDays). Nothing older is evidence: a flag last read BEFORE the window has no observation at all and reads \"neverObserved\", which is exactly what a flag declared this morning reads.",
+	"\"neverObserved\" is not a removal candidate. A flag declared yesterday and a flag abandoned last year produce the identical row; only a flag that WAS observed and then stopped (\"stale\") is proven unused."
+], a = (e) => {
+	let n = e.now ?? Date.now(), a = e.staleAfterDays, o = n - a * t, s = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Map(), l;
+	for (let t of e.usage) {
+		let e = t.lastAt.getTime();
+		if (!Number.isFinite(e)) continue;
+		(l === void 0 || e < l) && (l = e);
+		let n = t.source === "bulk" ? c : s, r = n.get(t.flag);
+		(r === void 0 || e > r) && n.set(t.flag, e);
+	}
+	let u = l === void 0 ? 0 : Math.floor((n - l) / t);
+	return {
+		coverage: {
+			tracking: e.tracking,
+			observedSince: l === void 0 ? null : new Date(l).toISOString().slice(0, 10),
+			observedDays: u,
+			retentionDays: e.retentionDays,
+			staleAfterDays: a
+		},
+		findings: Object.entries(e.flags).map(([t, i]) => {
+			let { shape: l, reason: d } = r(i, n), f = s.get(t), p = c.get(t), m = [d], h;
+			e.tracking ? f !== void 0 && f >= o ? (h = "evaluated", m.push(`last server-side read ${new Date(f).toISOString()}`)) : f === void 0 ? (h = "neverObserved", m.push(u > 0 ? `no server-side read in the ${u}-day observation window` : "no server-side read observed yet (the observation window is empty)"), p !== void 0 && m.push("the flag WAS delivered to a client in a bulk flags.evaluate response — which does not prove it was read")) : (h = "stale", m.push(`last server-side read ${new Date(f).toISOString()}, more than ${a} day(s) ago, over an observation window of ${u} day(s)`)) : (h = "untracked", m.push("evaluation tracking is off — no usage evidence exists for this deployment"));
+			let g = l === "constantOn" || l === "constantOff" || l === "expired";
+			return g && m.push("the definition alone makes this flag a constant — it selects nothing"), {
+				key: t,
+				shape: l,
+				shapeReason: d,
+				usage: h,
+				lastTargetedAt: f === void 0 ? null : new Date(f).toISOString(),
+				lastBulkAt: p === void 0 ? null : new Date(p).toISOString(),
+				liveTargetedEvaluations: e.liveCounts?.get(t) ?? 0,
+				removalCandidate: g || h === "stale",
+				why: m
+			};
+		}),
+		limits: i
+	};
+};
+//#endregion
+export { i as FLAG_LIFECYCLE_LIMITS, r as classifyShape, a as flagLifecycleReport };

package/dist/store.js

@@ -0,0 +1,154 @@
+import { toDefinition as e } from "./evaluate.js";
+import { boolean as t, derivedRowId as n, eq as r, id as i, integer as a, json as o, queryFor as s, table as c, text as l, timestamp as u } from "@voltro/database";
+//#region src/store.ts
+var d = "_voltro_feature_flag_audit", f = "_voltro_feature_flags", p = c(f, {
+	id: i({ prefix: "flag" }),
+	key: l().unique(),
+	enabled: t().default(!0),
+	rollout: a().nullable(),
+	rolloutBy: l().nullable(),
+	targeting: o().nullable(),
+	variants: o().nullable(),
+	offVariant: l().nullable(),
+	schedule: o().nullable(),
+	description: l().nullable(),
+	updatedAt: u().default("now").onUpdate("now")
+}), m = c(d, {
+	id: i({ prefix: "flagaud" }),
+	flag: l(),
+	enabled: t(),
+	previousEnabled: t().nullable(),
+	actorId: l().nullable(),
+	at: u().default("now")
+}).index("byFlagAuditFlag", ["flag"]).index("byFlagAuditAt", ["at"]), h = (e, t) => {
+	let n = { ...e };
+	for (let e of t) {
+		let t = {
+			enabled: e.enabled,
+			...e.rollout == null ? {} : { rollout: e.rollout },
+			...e.rolloutBy === "tenant" || e.rolloutBy === "subject" ? { rolloutBy: e.rolloutBy } : {},
+			...Array.isArray(e.targeting) ? { targeting: e.targeting } : {},
+			...Array.isArray(e.variants) ? { variants: e.variants } : {},
+			...e.offVariant == null ? {} : { offVariant: e.offVariant },
+			...e.schedule != null && typeof e.schedule == "object" ? { schedule: e.schedule } : {},
+			...e.description == null ? {} : { description: e.description }
+		};
+		n[e.key] = t;
+	}
+	return n;
+}, g = class {
+	flags = {};
+	set(e) {
+		this.flags = e;
+	}
+	all() {
+		return this.flags;
+	}
+	get(e) {
+		return this.flags[e];
+	}
+}, _ = new g(), v = (e, t) => y(e, t) !== null, y = (t, n) => {
+	let r = _.get(t);
+	if (r === void 0) return null;
+	let i = e(r), a = i.enabled !== !1;
+	return _.set({
+		..._.all(),
+		[t]: {
+			...i,
+			enabled: n
+		}
+	}), a;
+}, b = (t) => Object.entries(t).map(([t, n]) => {
+	let r = e(n);
+	return {
+		key: t,
+		enabled: r.enabled !== !1,
+		rollout: r.rollout ?? 100,
+		variants: r.variants && r.variants.length > 0 ? r.variants.map((e) => e.name) : void 0,
+		scheduled: r.schedule != null,
+		description: r.description
+	};
+}), x = (t, n) => {
+	let r = e(n);
+	return {
+		key: t,
+		enabled: r.enabled !== !1,
+		rollout: r.rollout ?? null,
+		rolloutBy: r.rolloutBy ?? null,
+		targeting: r.targeting ?? null,
+		variants: r.variants ?? null,
+		offVariant: r.offVariant ?? null,
+		schedule: r.schedule ?? null,
+		description: r.description ?? null
+	};
+}, S = (e) => ({
+	loadOverrides: async () => (await e.query(s(p).descriptor)).map((e) => ({
+		key: String(e.key),
+		enabled: e.enabled === !0 || e.enabled === 1,
+		rollout: e.rollout == null ? null : Number(e.rollout),
+		rolloutBy: e.rolloutBy ?? null,
+		targeting: e.targeting ?? null,
+		variants: e.variants ?? null,
+		offVariant: e.offVariant ?? null,
+		schedule: e.schedule ?? null,
+		description: e.description ?? null
+	})),
+	upsertOverride: async (t) => {
+		let n = C(t);
+		await e.upsert(f, n, { conflictColumns: ["key"] });
+	}
+}), C = (e) => ({
+	id: n("flag", e.key),
+	key: e.key,
+	enabled: e.enabled,
+	rollout: e.rollout,
+	rolloutBy: e.rolloutBy,
+	targeting: e.targeting,
+	variants: e.variants,
+	offVariant: e.offVariant,
+	schedule: e.schedule,
+	description: e.description,
+	updatedAt: /* @__PURE__ */ new Date()
+}), w = (e) => ({
+	flag: String(e.flag),
+	enabled: e.enabled === !0 || e.enabled === 1,
+	previousEnabled: e.previousEnabled == null ? null : e.previousEnabled === !0 || e.previousEnabled === 1,
+	actorId: e.actorId ?? null,
+	at: e.at instanceof Date ? e.at : new Date(String(e.at))
+}), T = (e) => ({
+	record: async (t) => {
+		await e.insert(d, {
+			id: `flagaud_${t.at.getTime()}_${Math.random().toString(36).slice(2, 10)}`,
+			flag: t.flag,
+			enabled: t.enabled,
+			previousEnabled: t.previousEnabled,
+			actorId: t.actorId,
+			at: t.at
+		});
+	},
+	list: async (t) => {
+		let n = s(m).orderBy("at", "desc");
+		return t?.flag != null && (n = n.where(r("flag", t.flag))), t?.limit != null && (n = n.limit(t.limit)), (await e.query(n.descriptor)).map(w);
+	}
+}), E = async (e, t, i, a, o) => {
+	await e.transactional(async (e) => {
+		await e.insertIgnore(f, {
+			...C(x(t, i)),
+			id: n("flag", crypto.randomUUID())
+		}, { conflictColumns: ["key"] });
+		let c = (await e.query(s(p).where(r("key", t)).forUpdate().descriptor))[0];
+		if (!c) throw Error("flag override disappeared during toggle");
+		await e.update(f, String(c.id), {
+			enabled: a,
+			updatedAt: /* @__PURE__ */ new Date()
+		}), await T(e).record({
+			flag: t,
+			enabled: a,
+			previousEnabled: c.enabled === !0 || c.enabled === 1,
+			actorId: o,
+			at: /* @__PURE__ */ new Date()
+		});
+	});
+};
+//#endregion
+export { d as FLAGS_AUDIT_TABLE, f as FLAGS_TABLE, g as FlagRegistry, T as dataStoreFlagAuditStore, S as dataStoreFlagStore, b as describeFlags, p as featureFlagsTable, m as flagAuditTable, x as flagValueToRow, y as flipFlagEnabled, h as mergeOverrides, E as persistFlagToggle, _ as registry, v as setFlagEnabled };

package/dist/usage.js

@@ -0,0 +1,113 @@
+import { id as e, queryFor as t, registerRetention as n, retentionTtlMsFromEnv as r, table as i, text as a, timestamp as o } from "@voltro/database";
+//#region src/usage.ts
+var s = "_voltro_feature_flag_usage", c = i(s, {
+	id: e({ prefix: "flagusg" }),
+	flag: a(),
+	day: a(),
+	source: a(),
+	lastAt: o()
+}).unique([
+	"flag",
+	"day",
+	"source"
+]).index("byFlagUsageLastAt", ["lastAt"]).index("byFlagUsageFlag", ["flag"]), l = (e) => e.toISOString().slice(0, 10), u = (e) => {
+	let t = 2166136261;
+	for (let n = 0; n < e.length; n++) t ^= e.charCodeAt(n), t = Math.imul(t, 16777619);
+	return (t >>> 0).toString(16).padStart(8, "0");
+}, d = (e, t, n) => `flagusg_${t.replace(/-/g, "")}_${n === "targeted" ? "t" : "b"}_${u(e)}`, f = new class {
+	on = !1;
+	pending = /* @__PURE__ */ new Map();
+	liveCounts = /* @__PURE__ */ new Map();
+	enable() {
+		this.on = !0;
+	}
+	disable() {
+		this.on = !1, this.pending.clear();
+	}
+	get enabled() {
+		return this.on;
+	}
+	record(e, t, n = Date.now()) {
+		if (!this.on) return;
+		let r = `${t}\u0000${e}`, i = this.pending.get(r);
+		i ? i.lastAt = n : this.pending.set(r, {
+			flag: e,
+			source: t,
+			lastAt: n
+		}), t === "targeted" && this.liveCounts.set(e, (this.liveCounts.get(e) ?? 0) + 1);
+	}
+	drain() {
+		let e = [...this.pending.values()];
+		return this.pending.clear(), e;
+	}
+	restore(e) {
+		if (this.on) for (let t of e) {
+			let e = `${t.source}\u0000${t.flag}`, n = this.pending.get(e);
+			(!n || n.lastAt < t.lastAt) && this.pending.set(e, { ...t });
+		}
+	}
+	liveTargetedCounts() {
+		return this.liveCounts;
+	}
+	reset() {
+		this.on = !1, this.pending.clear(), this.liveCounts.clear();
+	}
+}(), p = (e, t, n) => f.record(e, t, n), m = (e) => e === "bulk" ? "bulk" : "targeted", h = (e) => ({
+	upsertMany: async (t) => {
+		for (let n of t) {
+			let t = l(n.lastAt);
+			await e.upsert(s, {
+				id: d(n.flag, t, n.source),
+				flag: n.flag,
+				day: t,
+				source: n.source,
+				lastAt: n.lastAt
+			}, { conflictColumns: [
+				"flag",
+				"day",
+				"source"
+			] });
+		}
+	},
+	load: async () => (await e.query(t(c).descriptor)).map((e) => ({
+		flag: String(e.flag),
+		day: String(e.day),
+		source: m(e.source),
+		lastAt: e.lastAt instanceof Date ? e.lastAt : new Date(String(e.lastAt))
+	}))
+}), g = 3e5, _ = (e) => {
+	let t = e.intervalMs ?? 3e5, n = !1, r = async () => {
+		let t = f.drain();
+		if (t.length !== 0) try {
+			await e.store.upsertMany(t.map((e) => ({
+				flag: e.flag,
+				source: e.source,
+				lastAt: new Date(e.lastAt)
+			})));
+		} catch (n) {
+			f.restore(t), e.log?.warn?.("flag usage flush failed — observations retained for the next pass", {
+				pending: t.length,
+				cause: n.message
+			});
+		}
+	}, i = setInterval(() => {
+		r();
+	}, t);
+	return typeof i.unref == "function" && i.unref(), {
+		flushNow: r,
+		stop: async () => {
+			n || (n = !0, clearInterval(i), await r());
+		}
+	};
+}, v = (e = process.env, t = 90) => {
+	let i = r(e.VOLTRO_FLAG_USAGE_TTL_HOURS, 24 * t);
+	return n({
+		table: s,
+		timeColumn: "lastAt",
+		source: "plugin",
+		ttlMs: i,
+		envVar: "VOLTRO_FLAG_USAGE_TTL_HOURS"
+	}), i;
+};
+//#endregion
+export { g as DEFAULT_FLAG_USAGE_FLUSH_MS, s as FLAG_USAGE_TABLE, h as dataStoreFlagUsageStore, f as flagUsageBuffer, d as flagUsageRowId, c as flagUsageTable, p as recordFlagEvaluation, v as registerFlagUsageRetention, _ as startFlagUsageFlush, l as utcDay };

package/dist/web.js

@@ -1,5 +1,5 @@
 import { BASE_NAME as e } from "./rpc.js";
-import { i as t } from "./define-BHpLJh1F.js";
+import { typedValueOf as t } from "./define.js";
 import { pluginTag as n } from "@voltro/protocol";
 import { useSubscription as r } from "@voltro/client";
 //#region src/web.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-flags",
-  "version": "0.85.0",
+  "version": "0.86.0",
   "description": "Feature flags — per-subject / per-tenant targeting, deterministic % rollouts, kill-switch. Gate mutations/queries/actions declaratively or guard in-handler; evaluate flags client-side for UI gating. Config-as-code (memory) or runtime-toggleable (postgres).",
   "keywords": [
     "voltro",
@@ -48,10 +48,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.85.0",
-    "@voltro/database": "0.85.0",
-    "@voltro/logger": "0.85.0",
-    "@voltro/protocol": "0.85.0"
+    "@voltro/client": "0.86.0",
+    "@voltro/database": "0.86.0",
+    "@voltro/logger": "0.86.0",
+    "@voltro/protocol": "0.86.0"
   },
   "peerDependencies": {
     "effect": "4.0.1"