@voltro/plugin-flags 0.85.0 → 0.87.0

package/dist/config-inspect.d.ts

@@ -0,0 +1,33 @@
+import { Schema } from 'effect';
+
+export declare const ConfigKeySummarySchema: Schema.Struct<{
+    readonly key: Schema.String;
+    readonly valueType: Schema.String;
+    readonly public: Schema.Boolean;
+    readonly restartRequired: Schema.Literals<readonly ["room", "live"]>;
+    readonly min: Schema.NullOr<Schema.Number>;
+    readonly max: Schema.NullOr<Schema.Number>;
+}>;
+
+export declare type ConfigStatus = typeof ConfigStatusSchema.Type;
+
+export declare const ConfigStatusSchema: Schema.Struct<{
+    readonly bound: Schema.Boolean;
+    readonly backend: Schema.Literals<readonly ["flags", "custom"]>;
+    readonly version: Schema.String;
+    readonly resolver: Schema.Literals<readonly ["default", "custom", "app-owned"]>;
+    readonly keys: Schema.$Array<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly valueType: Schema.String;
+        readonly public: Schema.Boolean;
+        readonly restartRequired: Schema.Literals<readonly ["room", "live"]>;
+        readonly min: Schema.NullOr<Schema.Number>;
+        readonly max: Schema.NullOr<Schema.Number>;
+    }>>;
+    readonly publicKeys: Schema.$Array<Schema.String>;
+    readonly maxValueBytes: Schema.Literal<16384>;
+    readonly roomBindingInstalled: Schema.Literal<false>;
+    readonly gmEditInstalled: Schema.Literal<false>;
+}>;
+
+export { }

package/dist/config-inspect.js

@@ -0,0 +1,29 @@
+import { Schema as e } from "effect";
+//#region src/configInspect.ts
+var t = e.String.pipe(e.check(e.isPattern(/^[A-Za-z][A-Za-z0-9._-]{0,119}$/))), n = e.NullOr(e.Number.pipe(e.check(e.isFinite()))), r = e.Struct({
+	key: t,
+	valueType: e.String,
+	public: e.Boolean,
+	restartRequired: e.Literals(["room", "live"]),
+	min: n,
+	max: n
+}), i = e.Struct({
+	bound: e.Boolean,
+	backend: e.Literals(["flags", "custom"]),
+	version: t,
+	resolver: e.Literals([
+		"default",
+		"custom",
+		"app-owned"
+	]),
+	keys: e.Array(r).pipe(e.check(e.isMinLength(1)), e.check(e.isMaxLength(128))),
+	publicKeys: e.Array(t),
+	maxValueBytes: e.Literal(16384),
+	roomBindingInstalled: e.Literal(!1),
+	gmEditInstalled: e.Literal(!1)
+}).pipe(e.check(e.makeFilter((e) => {
+	let t = e.keys.map((e) => e.key);
+	return new Set(t).size === t.length && e.keys.every((e) => e.min === null || e.max === null || e.min <= e.max) && JSON.stringify(e.publicKeys) === JSON.stringify(e.keys.filter((e) => e.public).map((e) => e.key)) && (e.backend === "custom" ? e.resolver === "app-owned" && e.version !== "default.v1" : e.resolver !== "app-owned" && (e.resolver === "default" || e.version !== "default.v1"));
+})));
+//#endregion
+export { r as ConfigKeySummarySchema, i as ConfigStatusSchema };

package/dist/config-port.d.ts

@@ -0,0 +1,247 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+/** `TypedFlag` with the value type erased — what the plugin and the registry
+ *  hold. Sound because `TypedFlag` is covariant in `A` (see the annotation). */
+declare type AnyTypedFlag = TypedFlag<unknown>;
+
+export declare const captureConfigService: (input: ConfigService) => ConfigService;
+
+declare interface ConfigEntry<out A> {
+    readonly key: string;
+    readonly flag: TypedFlag<A>;
+    readonly public: boolean;
+    readonly restartRequired: 'room' | 'live';
+    readonly min: number | null;
+    readonly max: number | null;
+}
+
+/** Typed Config failures contain no private value, subject or decode body. */
+declare class ConfigError extends ConfigError_base {
+}
+
+declare const ConfigError_base: Schema.Class<ConfigError, Schema.TaggedStruct<"ConfigError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "invalid_value", "not_found", "unavailable"]>;
+}>, YieldableError>;
+
+export declare class ConfigPort extends ConfigPort_base {
+}
+
+declare const ConfigPort_base: Context.ServiceClass<ConfigPort, "@voltro/ConfigPort", ConfigService>;
+
+export declare interface ConfigResolutionContext {
+    readonly entry: ConfigEntry<unknown>;
+    readonly value: FlagValue;
+    readonly subject: FlagSubject;
+    readonly now: number;
+}
+
+export declare type ConfigResolver = (context: ConfigResolutionContext) => unknown;
+
+export declare interface ConfigService {
+    readonly get: (key: string, subject: FlagSubject) => Effect.Effect<unknown, ConfigError>;
+    readonly mine: (subject: FlagSubject) => Effect.Effect<Readonly<Record<string, unknown>>, ConfigError>;
+    /** Snapshot outside a Room tick, then pass it through creation or app messages. */
+    readonly snapshot: (subject: FlagSubject, mode: 'room' | 'live') => Effect.Effect<Readonly<Record<string, unknown>>, ConfigError>;
+}
+
+export declare const configValue: <Values extends Readonly<Record<string, unknown>>, Key extends keyof Values & string>(catalog: DefinedConfig<Values>, service: ConfigService, key: Key, subject: FlagSubject) => Effect.Effect<Values[Key], ConfigError>;
+
+/** Reuse Flag targeting/schedule/bucketing. Off Config always serves its default. */
+export declare const defaultConfigResolver: ConfigResolver;
+
+declare interface DefinedConfig<Values extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
+    readonly entries: {
+        readonly [Key in keyof Values]: ConfigEntry<Values[Key]>;
+    };
+    readonly keys: readonly (keyof Values & string)[];
+    readonly typedFlags: readonly AnyTypedFlag[];
+}
+
+/** A read facade over this plugin instance's actual merged Flag snapshot. */
+export declare const flagConfigService: (input: {
+    readonly catalog: DefinedConfig;
+    readonly flags: () => Readonly<Record<string, FlagValue>>;
+    readonly active: () => boolean;
+    readonly revision: () => number;
+    readonly resolver?: ConfigResolver;
+    readonly replacement?: ConfigService;
+}) => ConfigService;
+
+/** The result of decoding an UNTRUSTED value (a DB override, a dashboard edit)
+ *  against a flag's Schema. Deliberately not an exception: the caller's correct
+ *  response is to keep the code-declared value and say so, not to unwind. */
+declare type FlagDecodeResult<A> = {
+    readonly ok: true;
+    readonly value: A;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+
+declare interface FlagDefinition {
+    /** Master switch. `false` → off for everyone regardless of rollout/targeting. Default true. */
+    readonly enabled?: boolean;
+    /** Percentage rollout 0..100 — deterministic per (key, subject/tenant) so a
+     *  caller stays in/out consistently. Omit = 100 (everyone the targeting allows). */
+    readonly rollout?: number;
+    /** OR-of-rules targeting. When present, the caller must match at least one
+     *  rule (in addition to passing the rollout). Omit = everyone. */
+    readonly targeting?: ReadonlyArray<FlagTargetingRule>;
+    /** Bucket on the tenant id instead of the subject id (rollout by tenant). */
+    readonly rolloutBy?: 'subject' | 'tenant';
+    /** Multivariate flag — a set of named variants the flag resolves ONE of per
+     *  subject, deterministically weighted (see `FlagVariant.weight`). A subject
+     *  stays in the same variant across calls. When present, `variant.evaluate`
+     *  serves the resolved variant; the boolean resolution is `enabled && variant
+     *  is served` (the flag is "on" for the caller unless a variant named in
+     *  `offVariant` is served — omit ⇒ any served variant counts as on). */
+    readonly variants?: ReadonlyArray<FlagVariant>;
+    /** Variant name treated as the "off" state for boolean resolution. Omit ⇒
+     *  passing targeting+rollout with any served variant counts as on. */
+    readonly offVariant?: string;
+    /** Time-boxed / ramping schedule, evaluated against the current time. */
+    readonly schedule?: FlagSchedule;
+    /** Surfaced in the dashboard / `flags.evaluate`. */
+    readonly description?: string;
+}
+
+/** A time-boxed / ramping schedule. Evaluated against the current time.
+ *  Order: outside [activateAt, deactivateAt) ⇒ off; a `ramp` interpolates the
+ *  effective rollout % linearly across its window. */
+declare interface FlagSchedule {
+    /** Flag is off before this instant (epoch millis or ISO string). Omit ⇒ no lower bound. */
+    readonly activateAt?: number | string;
+    /** Flag is off at/after this instant (epoch millis or ISO string). Omit ⇒ no upper bound. */
+    readonly deactivateAt?: number | string;
+    /** A ramping rollout: exposure grows linearly from `from`% to `to`% across
+     *  [`startAt`, `endAt`). Before `startAt` ⇒ `from`%, after `endAt` ⇒ `to`%.
+     *  The interpolated % REPLACES the flag's static `rollout` while active. */
+    readonly ramp?: {
+        readonly from: number;
+        readonly to: number;
+        readonly startAt: number | string;
+        readonly endAt: number | string;
+    };
+}
+
+/** The minimal subject shape evaluation needs (avoids a hard `Subject` dep). */
+/**
+ * The subject shape the flag guards read. Deliberately LOOSER than the
+ * framework `Subject` so a bare `{ tenantId }` works in a test — but it has to
+ * be a genuine supertype, and every optional therefore spells `| undefined`
+ * explicitly. Under `exactOptionalPropertyTypes` (which this repo enables)
+ * `id?: string | null` means "absent or string-or-null" and REJECTS an
+ * explicit `undefined`, so a real `Subject` — whose fields are `?: T |
+ * undefined` — did not satisfy it. That is what made `requireFlag(ctx, …)`
+ * refuse the very `AppContext` its doc comment promises to accept.
+ */
+declare interface FlagSubject {
+    readonly id?: string | null | undefined;
+    readonly type?: string | undefined;
+    readonly tenantId?: string | null | undefined;
+    /**
+     * READONLY index signature, not `Record<string, unknown>`.
+     *
+     * The framework's `Subject.metadata` is `{ readonly [x: string]: unknown }`,
+     * and a readonly index signature is not assignable to a mutable one — so the
+     * mutable form made `requireFlag(ctx, …)` reject the very `AppContext` its
+     * own doc comment promises to accept ("the framework `AppContext`
+     * (`ctx.request.subject`)"). The shipped `api-feature-flags` template failed
+     * to typecheck on exactly that line while its tests passed, because
+     * `voltro test` transpiles without checking.
+     */
+    readonly metadata?: {
+        readonly [key: string]: unknown;
+    } | null | undefined;
+}
+
+/** One targeting rule — ANDs its conditions; a flag's `targeting` is an OR of rules. */
+declare interface FlagTargetingRule {
+    /** Match specific subject ids. */
+    readonly subjectIds?: ReadonlyArray<string>;
+    /** Match specific tenant ids. */
+    readonly tenantIds?: ReadonlyArray<string>;
+    /** Match `subject.type` (user / apiKey / serviceAccount / anonymous). */
+    readonly subjectTypes?: ReadonlyArray<string>;
+    /** Match `subject.metadata[key] === value` for every entry. */
+    readonly metadata?: Record<string, string>;
+}
+
+/** A flag value as authored: bare boolean (kill-switch) OR a rich definition. */
+declare type FlagValue = boolean | FlagDefinition;
+
+/** One multivariate variant: a named value with an optional rollout weight. */
+declare interface FlagVariant {
+    /** Stable variant name (the resolution returns this). */
+    readonly name: string;
+    /** The value served for this variant (string / number / boolean / JSON). */
+    readonly value: FlagVariantValue;
+    /** Relative allocation weight. Omit ⇒ equal split of the remaining weight.
+     *  Weights are normalised, so `[3, 1]` is 75% / 25%. */
+    readonly weight?: number;
+}
+
+/** A concrete variant value — string / number / boolean / JSON. Kept browser-safe. */
+declare type FlagVariantValue = string | number | boolean | null | ReadonlyArray<unknown> | Record<string, unknown>;
+
+/**
+ * A flag with a value type.
+ *
+ * `out A` is load-bearing rather than decorative: the plugin holds these in one
+ * `ReadonlyArray<TypedFlag<unknown>>`, which is only sound while every member
+ * that mentions `A` is a read position. If you add a field that CONSUMES an `A`
+ * (a `(value: A) => …` callback, say), that annotation is what will stop you —
+ * and the fix is to erase it behind a function returning a result, the way
+ * `decode` already does, not to drop the annotation.
+ */
+declare interface TypedFlag<out A> {
+    /** Brand — lets the plugin discriminate a typed flag from a bare `FlagValue`. */
+    readonly _voltroTypedFlag: true;
+    /** The flag key. Shares the flag namespace with `flags: { … }` entries; a
+     *  duplicate is refused at plugin construction. */
+    readonly key: string;
+    /** Human label of the value Schema (`number`, `"a" | "b"`, …) — for the
+     *  dashboard panel and for the refusal message when an override fails to
+     *  decode. Derived from the Schema's AST, so it cannot drift from it. */
+    readonly valueType: string;
+    /** The value served whenever the flag does not resolve to a variant: it is
+     *  off for this caller, or it declares no variants at all. Compile-checked
+     *  against the Schema. */
+    readonly defaultValue: A;
+    /** The value arms. Empty ⇒ the flag always serves `defaultValue` (which the
+     *  lifecycle report classifies as `constantOn`/`constantOff` — a flag that
+     *  cannot serve anything else is one to delete). */
+    readonly variants: ReadonlyArray<TypedFlagVariant<A>>;
+    /** Decode an untrusted value against the flag's Schema — the runtime half of
+     *  the contract `default` gets at compile time. */
+    readonly decode: (input: unknown) => FlagDecodeResult<A>;
+    /** The evaluator-facing definition. This is what goes into the registry the
+     *  existing `evaluateFlag` / `resolveVariant` already read; nothing about
+     *  evaluation changes because a flag is typed. */
+    readonly definition: FlagDefinition;
+    /**
+     * IN-11 — the `defineExperiment` this flag's variants report uplift for.
+     *
+     * A NAME rather than the definition object, on purpose: `defineExperiment`
+     * lives in `@voltro/runtime`, which is server-only, and this module has to
+     * stay loadable in a browser bundle. The link is validated at BOOT, where
+     * both sides are known (`assertFlagExperimentLinkage`) — a flag naming an
+     * experiment that does not exist, or whose arms disagree with the flag's,
+     * refuses to start rather than reporting uplift for arms nobody is served.
+     */
+    readonly experiment?: string;
+}
+
+/** One named arm of a typed flag. `value` is checked against the flag's Schema
+ *  at COMPILE time. Weights behave exactly as `FlagVariant.weight`. */
+declare interface TypedFlagVariant<out A> {
+    readonly name: string;
+    readonly value: A;
+    /** Relative allocation weight. Omit ⇒ equal split. */
+    readonly weight?: number;
+}
+
+export { }

package/dist/config-port.js

@@ -0,0 +1,125 @@
+import { ConfigError as e } from "./errors.js";
+import { evaluateVariant as t } from "./evaluate.js";
+import { captureConfigValue as n, captureDefinedConfig as r, configData as i, configError as a, configKey as o } from "./config.js";
+import { Context as s, Effect as c } from "effect";
+//#region src/configPort.ts
+var l = ({ entry: e, value: n, subject: r, now: i }) => {
+	let o = t(e.key, n, r, i);
+	if (!o.enabled || typeof n == "boolean" || !n.variants?.length) return e.flag.defaultValue;
+	let s = e.flag.decode(o.value);
+	if (!s.ok) throw a("invalid_value");
+	return s.value;
+}, u = class extends s.Service()("@voltro/ConfigPort") {}, d = (e) => {
+	if (!e || typeof e != "object" || Array.isArray(e)) throw a("invalid_input");
+	let t = Object.create(null);
+	for (let n of [
+		"get",
+		"mine",
+		"snapshot"
+	]) {
+		let r = e, i = !1;
+		for (let o = 0; r && o < 8; o++, r = Object.getPrototypeOf(r)) {
+			let o = Object.getOwnPropertyDescriptor(r, n);
+			if (o) {
+				if (!("value" in o) || typeof o.value != "function") throw a("invalid_input");
+				Object.defineProperty(t, n, {
+					value: o.value.bind(e),
+					enumerable: !0
+				}), i = !0;
+				break;
+			}
+		}
+		if (!i) throw a("invalid_input");
+	}
+	return Object.freeze(t);
+}, f = (t) => {
+	let s = i(t, [
+		"catalog",
+		"flags",
+		"active",
+		"revision",
+		"resolver",
+		"replacement"
+	]), u = r(s.catalog), f = s.flags, p = s.active, m = s.revision, h = s.resolver ?? l, g = s.replacement === void 0 ? void 0 : d(s.replacement);
+	if (typeof f != "function" || typeof p != "function" || typeof m != "function" || typeof h != "function" || g && s.resolver !== void 0) throw a("invalid_input");
+	let _ = (e) => {
+		let t = o(e);
+		if (!Object.hasOwn(u.entries, t)) throw a("not_found");
+		return u.entries[t];
+	}, v = (e) => {
+		if (!e || typeof e != "object") throw a("invalid_input");
+		let t = Object.create(null);
+		for (let n of [
+			"id",
+			"tenantId",
+			"type",
+			"metadata"
+		]) {
+			let r = Object.getOwnPropertyDescriptor(e, n);
+			if (r) {
+				if (!("value" in r)) throw a("invalid_input");
+				r.value !== void 0 && (t[n] = r.value);
+			}
+		}
+		for (let e of [
+			"id",
+			"tenantId",
+			"type"
+		]) if (t[e] !== void 0 && t[e] !== null && typeof t[e] != "string") throw a("invalid_input");
+		return n(t);
+	}, y = (e, t) => {
+		let r = e.flag.decode(t);
+		if (!r.ok) throw a("invalid_value");
+		return n(r.value);
+	}, b = (t) => c.try({
+		try: t,
+		catch: (t) => t instanceof e ? t : a("invalid_value")
+	}), x = (t) => {
+		try {
+			let e = m(), n = t();
+			return c.suspend(() => p() && m() === e ? n : c.fail(a("unavailable"))).pipe(c.flatMap((t) => p() && m() === e ? c.succeed(t) : c.fail(a("unavailable"))), c.catchDefect(() => c.fail(a("unavailable"))));
+		} catch (t) {
+			return c.fail(t instanceof e ? t : a("invalid_input"));
+		}
+	}, S = (e, t, n, r) => y(e, h({
+		entry: e,
+		value: r[e.key] ?? e.flag.definition,
+		subject: t,
+		now: n
+	})), C = (e, t) => {
+		let n = i(e, t), r = Object.create(null);
+		if (Object.keys(n).length !== t.length) throw a("invalid_value");
+		for (let e of t) r[e] = y(_(e), n[e]);
+		return Object.freeze(r);
+	};
+	return Object.freeze({
+		get: (e, t) => x(() => {
+			let n = _(e), r = v(t);
+			return g ? g.get(n.key, r).pipe(c.flatMap((e) => b(() => y(n, e)))) : b(() => S(n, r, Date.now(), f()));
+		}),
+		mine: (e) => x(() => {
+			let t = v(e), n = u.keys.filter((e) => _(e).public);
+			return g ? g.mine(t).pipe(c.flatMap((e) => b(() => C(e, n)))) : b(() => {
+				let e = Date.now(), r = f();
+				return Object.freeze(Object.fromEntries(n.map((n) => [n, S(_(n), t, e, r)])));
+			});
+		}),
+		snapshot: (e, t) => x(() => {
+			if (t !== "room" && t !== "live") throw a("invalid_input");
+			let n = v(e), r = u.keys.filter((e) => _(e).restartRequired === t);
+			return g ? g.snapshot(n, t).pipe(c.flatMap((e) => b(() => C(e, r)))) : b(() => {
+				let e = Date.now(), t = f();
+				return Object.freeze(Object.fromEntries(r.map((r) => [r, S(_(r), n, e, t)])));
+			});
+		})
+	});
+}, p = (e, t, n, r) => t.get(n, r).pipe(c.flatMap((t) => c.try({
+	try: () => {
+		let r = e.entries[n].flag.decode(t);
+		if (!r.ok) throw a("invalid_value");
+		return r.value;
+	},
+	catch: () => a("invalid_value")
+})));
+//#endregion
+export { u as ConfigPort, d as captureConfigService, p as configValue, l as defaultConfigResolver, f as flagConfigService };