@voltro/plugin-flags 0.84.0 → 0.86.0

package/THIRD-PARTY-NOTICES.md

@@ -1,70 +1,14 @@
 # Third-Party Notices — @voltro/plugin-flags
 
-This package depends on the open-source software listed below. Each is the
+This package uses the open-source software listed below. Each is the
 property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/plugin-flags itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (13 packages).
+Generated from the resolved runtime dependency closure (10 packages).
 
 ---
 
-## @effect/experimental@0.61.1
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2023-present The Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
-## @effect/sql@0.52.1
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2023-present The Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ## @tanstack/devtools-event-client@0.4.4
 
 License: MIT
@@ -233,34 +177,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## layerr@3.0.0
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2020 Perry Mitchell
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ## typeid-js@1.2.0
 
 License: Apache-2.0
@@ -469,14 +385,14 @@ Apache License
    limitations under the License.
 ```
 
-## ulidx@2.4.1
+## ulid@3.0.2
 
 License: MIT
 
 ```
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2021 Perry Mitchell
+Copyright (c) 2017 Alizain Feerasta
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/{define-D9Eet7wA.js → define.js}

@@ -1,4 +1,4 @@
-import { Either as e, Schema as t } from "effect";
+import { Result as e, Schema as t } from "effect";
 //#region src/define.ts
 var n = (e) => typeof e == "object" && !!e && e._voltroTypedFlag === !0, r = (e) => e, i = (n) => {
 	let i = (e) => /* @__PURE__ */ Error(`defineFlag(${JSON.stringify(n.key)}): ${e}`);
@@ -13,17 +13,17 @@ var n = (e) => typeof e == "object" && !!e && e._voltroTypedFlag === !0, r = (e)
 	if (n.offVariant !== void 0 && !o.has(n.offVariant)) throw i(`offVariant ${JSON.stringify(n.offVariant)} is not one of the declared variants`);
 	if (n.rollout !== void 0 && !(Number.isFinite(n.rollout) && n.rollout >= 0 && n.rollout <= 100)) throw i("rollout must be a number in 0..100");
 	if (n.experiment !== void 0 && (typeof n.experiment != "string" || n.experiment.length === 0)) throw i("experiment, when present, must be a non-empty experiment name");
-	let s = t.decodeUnknownEither(n.value, {
+	let s = t.decodeUnknownResult(n.value, {
 		errors: "all",
 		onExcessProperty: "ignore"
 	}), c = (t) => {
 		let n = s(t);
-		return e.isRight(n) ? {
+		return e.isSuccess(n) ? {
 			ok: !0,
-			value: n.right
+			value: n.success
 		} : {
 			ok: !1,
-			reason: n.left.message
+			reason: n.failure.message
 		};
 	}, l = c(n.default);
 	if (!l.ok) throw i(`\`default\` does not satisfy the value Schema: ${l.reason}`);
@@ -76,4 +76,4 @@ var n = (e) => typeof e == "object" && !!e && e._voltroTypedFlag === !0, r = (e)
 	};
 };
 //#endregion
-export { a as i, o as n, n as r, i as t };
+export { i as defineFlag, o as gateOverride, n as isTypedFlag, a as typedValueOf };

package/dist/errors.d.ts

@@ -1,14 +1,13 @@
 import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
 
 /** Raised when a flag-gated call hits a disabled flag. Merged into every
  *  procedure's wire-error union so the client decodes it typed. */
 export declare class FlagDisabled extends FlagDisabled_base {
 }
 
-declare const FlagDisabled_base: Schema.TaggedErrorClass<FlagDisabled, "FlagDisabled", {
-    readonly _tag: Schema.tag<"FlagDisabled">;
-} & {
-    flag: typeof Schema.String;
-}>;
+declare const FlagDisabled_base: Schema.Class<FlagDisabled, Schema.TaggedStruct<"FlagDisabled", {
+    readonly flag: Schema.String;
+}>, YieldableError>;
 
 export { }

package/dist/evaluate.js

@@ -0,0 +1,81 @@
+//#region src/evaluate.ts
+var e = (e) => typeof e == "boolean" ? { enabled: e } : e, t = (e, t) => {
+	let n = 2166136261, r = `${e}:${t}`;
+	for (let e = 0; e < r.length; e++) n ^= r.charCodeAt(e), n = Math.imul(n, 16777619);
+	return n >>> 0;
+}, n = (e, n) => t(e, n) % 100, r = (e, n) => t(`${e}:variant`, n) % 1e4, i = (e, t) => {
+	if (e.subjectIds && !(t.id != null && e.subjectIds.includes(t.id)) || e.tenantIds && !(t.tenantId != null && e.tenantIds.includes(t.tenantId)) || e.subjectTypes && !(t.type != null && e.subjectTypes.includes(t.type))) return !1;
+	if (e.metadata) {
+		let n = t.metadata ?? {};
+		for (let [t, r] of Object.entries(e.metadata)) if (String(n[t]) !== r) return !1;
+	}
+	return !0;
+}, a = (e) => typeof e == "number" ? e : Date.parse(e), o = (e, t) => (e.rolloutBy === "tenant" ? t.tenantId : t.id) ?? "anon", s = (e, t) => {
+	if (e.activateAt != null && t < a(e.activateAt) || e.deactivateAt != null && t >= a(e.deactivateAt)) return { active: !1 };
+	if (e.ramp) {
+		let { from: n, to: r, startAt: i, endAt: o } = e.ramp, s = a(i), c = a(o);
+		if (t <= s) return {
+			active: !0,
+			rollout: n
+		};
+		if (t >= c || c <= s) return {
+			active: !0,
+			rollout: r
+		};
+		let l = (t - s) / (c - s);
+		return {
+			active: !0,
+			rollout: n + (r - n) * l
+		};
+	}
+	return { active: !0 };
+}, c = (t, n, r, i = Date.now()) => {
+	let a = e(n);
+	return l(t, a, r, i) ? !a.variants?.length || a.offVariant == null || d(t, a, r).name !== a.offVariant : !1;
+}, l = (e, t, r, a) => {
+	if (t.enabled === !1) return !1;
+	let c;
+	if (t.schedule) {
+		let e = s(t.schedule, a);
+		if (!e.active) return !1;
+		c = e.rollout;
+	}
+	if (t.targeting && t.targeting.length > 0 && !t.targeting.some((e) => i(e, r))) return !1;
+	let l = c ?? t.rollout ?? 100;
+	if (l < 100 && l > 0) {
+		if (!(n(e, o(t, r)) < l)) return !1;
+	} else if (l <= 0) return !1;
+	return !0;
+}, u = (e) => {
+	let t = e.reduce((e, t) => e + (t.weight ?? 1), 0) || e.length, n = 0;
+	return e.map((r, i) => (n += r.weight ?? 1, i === e.length - 1 ? 1e4 : Math.round(n / t * 1e4)));
+}, d = (e, t, n) => {
+	let i = t.variants ?? [];
+	if (i.length === 0) throw Error(`flag "${e}" has no variants`);
+	let a = r(e, o(t, n)), s = u(i);
+	for (let e = 0; e < i.length; e++) if (a < s[e]) return i[e];
+	return i[i.length - 1];
+}, f = (t, n, r, i = Date.now()) => {
+	let a = e(n), o = l(t, a, r, i);
+	if (!a.variants || a.variants.length === 0) return {
+		name: o ? "on" : "off",
+		value: o,
+		enabled: o
+	};
+	let s = d(t, a, r);
+	return {
+		name: s.name,
+		value: s.value,
+		enabled: o && s.name !== a.offVariant
+	};
+}, p = (e, t, n = Date.now()) => {
+	let r = {};
+	for (let [i, a] of Object.entries(e)) r[i] = c(i, a, t, n);
+	return r;
+}, m = (e, t, n = Date.now()) => {
+	let r = {};
+	for (let [i, a] of Object.entries(e)) r[i] = f(i, a, t, n);
+	return r;
+};
+//#endregion
+export { p as evaluateAll, m as evaluateAllVariants, c as evaluateFlag, s as evaluateSchedule, f as evaluateVariant, d as resolveVariant, e as toDefinition };

package/dist/experimentLink.js

@@ -0,0 +1,48 @@
+//#region src/experimentLink.ts
+var e = (e, t) => {
+	let n = new Map(t.map((e) => [e.name, e])), r = [];
+	for (let t of e) {
+		let e = t.experiment;
+		if (e === void 0) continue;
+		let i = n.get(e);
+		if (i === void 0) {
+			r.push({
+				flag: t.key,
+				experiment: e,
+				problem: `no experiment named ${JSON.stringify(e)} was passed to flagsPlugin({ experiments }). Pass the defineExperiment() definitions the app declares, or drop the \`experiment\` link.`
+			});
+			continue;
+		}
+		(i.variantFrom === void 0 || i.variantFrom === null) && r.push({
+			flag: t.key,
+			experiment: e,
+			problem: `the experiment assigns its own arms (\`subject\` mode), so it would measure a split this flag never served — the two bucketings are independent hashes. Persist the served arm (\`flagVariant(ctx, ${JSON.stringify(t.key)})\`) on the watched table and declare the experiment with \`variantFrom: <that column>\`.`
+		}), typeof i.holdout == "number" && i.holdout > 0 && r.push({
+			flag: t.key,
+			experiment: e,
+			problem: `holdout ${i.holdout} is carved at ASSIGNMENT, and this flag does the assigning — the experiment can never place a row there. Declare the holdout as a flag variant instead.`
+		});
+		let a = new Set(t.variants.map((e) => e.name)), o = new Set(i.variants.map((e) => e.name));
+		if (a.size === 0) r.push({
+			flag: t.key,
+			experiment: e,
+			problem: "the flag declares no variants, so it serves one value to everyone and there is nothing to compare."
+		});
+		else {
+			let n = [...a].filter((e) => !o.has(e)), i = [...o].filter((e) => !a.has(e));
+			(n.length > 0 || i.length > 0) && r.push({
+				flag: t.key,
+				experiment: e,
+				problem: `the arms disagree — ${n.length > 0 ? `served by the flag but not declared by the experiment: ${n.join(", ")}` : ""}${n.length > 0 && i.length > 0 ? "; " : ""}${i.length > 0 ? `declared by the experiment but never served: ${i.join(", ")}` : ""}. A row assigned to an arm the experiment does not declare is EXCLUDED, so the mismatch shows up as an empty arm rather than an error.`
+			});
+		}
+	}
+	return r;
+}, t = (t, n) => {
+	let r = e(t, n);
+	if (r.length === 0) return;
+	let i = r.map((e) => `  · flag "${e.flag}" → experiment "${e.experiment}": ${e.problem}`);
+	throw Error(`@voltro/plugin-flags: ${r.length} flag→experiment link problem(s):\n${i.join("\n")}`);
+};
+//#endregion
+export { t as assertFlagExperimentLinks, e as checkFlagExperimentLinks };

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { FieldDefinitions } from '@voltro/database';
 import { Schema } from 'effect';
 import { Table } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
+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). */
@@ -78,9 +79,9 @@ export declare const DEFAULT_FLAG_USAGE_FLUSH_MS = 300000;
  * a duplicate variant name, an `offVariant` naming no variant, a non-positive
  * weight, a rollout outside 0..100.
  */
-export declare const defineFlag: <S extends Schema.Schema.AnyNoContext>(spec: DefineFlagSpec<S>) => TypedFlag<Schema.Schema.Type<S>>;
+export declare const defineFlag: <S extends Schema.Top>(spec: DefineFlagSpec<S>) => TypedFlag<Schema.Schema.Type<S>>;
 
-export declare interface DefineFlagSpec<S extends Schema.Schema.AnyNoContext> {
+export declare interface DefineFlagSpec<S extends Schema.Top> {
     /** The flag key — `dotted.camelCase`, matching the `flags: { … }` record. */
     readonly key: string;
     /** The value Schema. Everything else in this spec is checked against it. */
@@ -254,11 +255,9 @@ export declare interface FlagDefinition {
 export declare class FlagDisabled extends FlagDisabled_base {
 }
 
-declare const FlagDisabled_base: Schema.TaggedErrorClass<FlagDisabled, "FlagDisabled", {
-    readonly _tag: Schema.tag<"FlagDisabled">;
-} & {
-    flag: typeof Schema.String;
-}>;
+declare const FlagDisabled_base: Schema.Class<FlagDisabled, Schema.TaggedStruct<"FlagDisabled", {
+    readonly flag: Schema.String;
+}>, YieldableError>;
 
 export declare interface FlagExperimentLinkProblem {
     readonly flag: string;