@voltro/plugin-flags 0.32.0 → 0.34.0

package/dist/web.d.ts

@@ -1,7 +1,90 @@
+/** 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;
+    };
+}
+
 export declare type FlagSet = Readonly<Record<string, boolean>>;
 
+/** 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>;
+}
+
+/** 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;
+}
+
 export declare type FlagVariantSet = Readonly<Record<string, FlagVariantView>>;
 
+/** A concrete variant value — string / number / boolean / JSON. Kept browser-safe. */
+declare type FlagVariantValue = string | number | boolean | null | ReadonlyArray<unknown> | Record<string, unknown>;
+
 /** A resolved multivariate variant on the wire: name + value + on/off. */
 export declare interface FlagVariantView {
     readonly name: string;
@@ -9,6 +92,63 @@ export declare interface FlagVariantView {
     readonly enabled: boolean;
 }
 
+/**
+ * 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;
+}
+
 /** `true` iff a single flag is on for the caller. */
 export declare const useFlag: (key: string, apiName?: string) => boolean;
 
@@ -16,6 +156,26 @@ export declare const useFlag: (key: string, apiName?: string) => boolean;
  *  on reconnect. Returns `{}` until the first response. */
 export declare const useFlags: (apiName?: string) => FlagSet;
 
+/**
+ * The TYPED value of a `defineFlag()` flag — `A`, not `unknown`.
+ *
+ * ```ts
+ * import { checkoutButton } from '../lib/flags'
+ * const colour = useFlagValue(checkoutButton)   //  'blue' | 'green'
+ * ```
+ *
+ * The flag object is the SAME one `app.config.ts` registers (`defineFlag` is
+ * browser-safe by construction), so the type the server serves and the type the
+ * component reads cannot drift — and neither can the fallback: `typedValueOf`
+ * is the one resolution both sides use.
+ *
+ * Before the first response, and for a value the server sent that does not
+ * decode, the declared `default` is returned. That branch is real rather than
+ * theoretical: an older replica mid-deploy can still be serving a variant set a
+ * newer schema has narrowed.
+ */
+export declare const useFlagValue: <A>(flag: TypedFlag<A>, apiName?: string) => A;
+
 /** The served variant for a single multivariate flag (or `undefined` until the
  *  first response / for an unknown key). Read `.value` for the variant payload. */
 export declare const useVariant: (key: string, apiName?: string) => FlagVariantView | undefined;

package/dist/web.js

@@ -1,11 +1,12 @@
-import { useSubscription as e } from "@voltro/client";
+import { i as e } from "./define-D9Eet7wA.js";
+import { useSubscription as t } from "@voltro/client";
 //#region src/web.ts
-var t = (t = "app") => {
-	let { data: n } = e(t, "flags.evaluate", {});
+var n = (e = "app") => {
+	let { data: n } = t(e, "flags.evaluate", {});
 	return n ?? {};
-}, n = (e, n = "app") => t(n)[e] === !0, r = (t = "app") => {
-	let { data: n } = e(t, "flags.variants", {});
+}, r = (e, t = "app") => n(t)[e] === !0, i = (e = "app") => {
+	let { data: n } = t(e, "flags.variants", {});
 	return n ?? {};
-}, i = (e, t = "app") => r(t)[e];
+}, a = (e, t = "app") => i(t)[e], o = (t, n = "app") => e(t, i(n)[t.key]);
 //#endregion
-export { n as useFlag, t as useFlags, i as useVariant, r as useVariants };
+export { r as useFlag, o as useFlagValue, n as useFlags, a as useVariant, i as useVariants };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-flags",
-  "version": "0.32.0",
+  "version": "0.34.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",
@@ -37,7 +37,8 @@
       "types": "./dist/rpc.d.ts",
       "import": "./dist/rpc.js",
       "default": "./dist/rpc.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -47,10 +48,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.32.0",
-    "@voltro/database": "0.32.0",
-    "@voltro/logger": "0.32.0",
-    "@voltro/protocol": "0.32.0"
+    "@voltro/client": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/logger": "0.34.0",
+    "@voltro/protocol": "0.34.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"