@sdxc/flags

import { createFlags } from "@sdxc/flags/client";
import { InMemoryProvider } from "@sdxc/flags/provider/memory";

let flags = createFlags({
	provider: () =>
		new InMemoryProvider({
			"new-checkout": { variants: { on: true, off: false }, defaultVariant: "off" },
		}),
});

let client = flags.getClient();

await client.boolean("new-checkout", false, { targetingKey: "user-1" }); // false

let details = await client.stringDetails("checkout-copy-variant", "control");
details.value; // "control", the default it was handed
details.reason; // "ERROR"
details.errorCode; // "FLAG_NOT_FOUND"

import * as s from "remix/data-schema";

let copy = await client.object(
	"checkout-copy",
	{ title: "Checkout", cta: "Pay" },
	{ schema: s.object({ title: s.string(), cta: s.string() }) },
);

import { defineFlags, flag } from "@sdxc/flags/catalog";
import * as s from "remix/data-schema";

export let features = defineFlags({
	newCheckout: flag.boolean("new-checkout", false),
	digestBatch: flag.number("digest-batch-size", 50),
	checkoutCopy: flag.object("checkout-copy", s.object({ title: s.string(), cta: s.string() }), {
		title: "Checkout",
		cta: "Pay",
	}),
});

await client.get(features.newCheckout); // Promise<boolean>
await client.get(features.digestBatch, { context: { targetingKey: "team-1" } }); // Promise<number>
await client.get(features.newCheckout, { defaultValue: true }); // a different fallback for this call
await client.details(features.checkoutCopy); // EvaluationDetails<{ title: string; cta: string }>

import featureFlags from "@sdxc/flags/middleware/router";
import { createRouter } from "remix/router";

import { flags } from "./flags.ts";

let router = createRouter({
	middleware: [
		featureFlags(flags, {
			context: (ctx) => ({ targetingKey: ctx.request.headers.get("x-user-id") ?? undefined }),
		}),
	],
});

router.get("/checkout", async (ctx) => {
	let enabled = await ctx.flags.boolean("new-checkout", false);
	return new Response(enabled ? "new checkout" : "classic checkout");
});

import featureFlags from "@sdxc/flags/middleware/dispatcher";
import { createJobDispatcher, createJobHandler } from "@sdxc/jobs";

import { flags } from "./flags.ts";
import { jobs } from "./jobs.ts";

export let dispatcher = createJobDispatcher({
	middleware: [featureFlags(flags, { context: (ctx) => ({ targetingKey: ctx.input.teamId }) })],
});

export default createJobHandler(jobs.sendWeeklyDigest, async (ctx) => {
	if (await ctx.flags.boolean("weekly-digest-v2", false)) return sendV2(ctx.input);
	return sendV1(ctx.input);
});

interface Provider {
	readonly metadata: ProviderMetadata;
	readonly hooks?: Hook[];
	readonly events?: ProviderEvents;
	readonly domainScoped?: boolean;
	resolveBoolean(key, defaultValue, context): MaybePromise<ResolutionDetails<boolean>>;
	resolveString(key, defaultValue, context): MaybePromise<ResolutionDetails<string>>;
	resolveNumber(key, defaultValue, context): MaybePromise<ResolutionDetails<number>>;
	resolveObject(key, defaultValue, context): MaybePromise<ResolutionDetails<JSONValue>>;
	initialize?(context: EvaluationContext, domain?: string): Promise<void>;
	shutdown?(): Promise<void>;
	track?(name: string, context: EvaluationContext, details?: TrackingEventDetails): void;
}

interface FlagConfiguration<T extends FlagValue = FlagValue> {
	variants: Record<string, T>;
	defaultVariant: string;
	disabled?: boolean;
	contextEvaluator?: (context: EvaluationContext) => string | undefined;
	flagMetadata?: FlagMetadata;
}

type FlagSet = Record<string, FlagConfiguration>;

import type { FlagValue, ResolutionDetails } from "@sdxc/flags";
import type { Provider } from "@sdxc/flags/provider";

import { failed, ProviderError, ProviderEvents, resolved } from "@sdxc/flags/provider";
import * as s from "remix/data-schema";

let RuleSchema = s.object({ value: s.boolean(), variant: s.string() });

export class ServiceProvider implements Provider {
	readonly metadata = { name: "flag-service" };
	readonly events = new ProviderEvents();

	#endpoint: string;
	#rules = new Map<string, { value: boolean; variant: string }>();

	constructor(endpoint = "https://flags.example.com/rules") {
		this.#endpoint = endpoint;
	}

	async initialize(): Promise<void> {
		let response = await fetch(this.#endpoint);
		if (!response.ok) {
			let message = `The flag service answered ${response.status}.`;
			this.events.emit("PROVIDER_ERROR", { errorCode: "PROVIDER_FATAL", message });
			throw new ProviderError("PROVIDER_FATAL", message);
		}
		for (let [key, rule] of Object.entries(await response.json())) {
			this.#rules.set(key, s.parse(RuleSchema, rule));
		}
		this.events.emit("PROVIDER_READY");
	}

	resolveBoolean(key: string, defaultValue: boolean): ResolutionDetails<boolean> {
		let rule = this.#rules.get(key);
		if (!rule) return failed(defaultValue, "FLAG_NOT_FOUND", `No flag named "${key}".`);
		return resolved(rule.value, { variant: rule.variant, reason: "STATIC" });
	}

	resolveString(key: string, defaultValue: string): ResolutionDetails<string> {
		return this.#booleansOnly(key, defaultValue);
	}

	resolveNumber(key: string, defaultValue: number): ResolutionDetails<number> {
		return this.#booleansOnly(key, defaultValue);
	}

	resolveObject(key: string, defaultValue: FlagValue): ResolutionDetails<FlagValue> {
		return this.#booleansOnly(key, defaultValue);
	}

	#booleansOnly<T extends FlagValue>(key: string, defaultValue: T): ResolutionDetails<T> {
		return failed(defaultValue, this.#rules.has(key) ? "TYPE_MISMATCH" : "FLAG_NOT_FOUND");
	}
}

import { conformance } from "@sdxc/flags/conformance";

import { ServiceProvider } from "./service-provider.ts";

conformance("flag-service", () => new ServiceProvider(), {
	lifecycle: true,
	failing: () => new ServiceProvider("https://flags.example.com/missing"),
});

import { createFlags } from "@sdxc/flags/client";
import { InMemoryProvider } from "@sdxc/flags/provider/memory";
import { expect, test } from "vitest";

test("serves the new checkout to the enrolled team", async () => {
	let provider = new InMemoryProvider({
		"new-checkout": {
			variants: { on: true, off: false },
			defaultVariant: "off",
			contextEvaluator: (context) => (context.targetingKey === "team-1" ? "on" : undefined),
		},
	});
	let flags = createFlags({ provider: () => provider });
	await flags.ready();

	let client = flags.getClient(undefined, { targetingKey: "team-1" });
	expect(await client.boolean("new-checkout", false)).toBe(true);
	expect(await client.boolean("new-checkout", false, { targetingKey: "team-2" })).toBe(false);

	provider.putConfiguration({
		"new-checkout": { variants: { on: true, off: false }, defaultVariant: "off", disabled: true },
	});
	expect((await client.booleanDetails("new-checkout", false)).reason).toBe("DISABLED");
});

import { asyncLocalStoragePropagator, createFlags } from "@sdxc/flags/client";
import featureFlags from "@sdxc/flags/middleware/router";
import { createRouter } from "remix/router";

import { ServiceProvider } from "./service-provider.ts";

export let flags = createFlags({
	provider: () => new ServiceProvider(),
	context: { service: "checkout" },
	propagator: asyncLocalStoragePropagator(),
});

let router = createRouter({
	middleware: [
		featureFlags(flags, {
			context: (ctx) => ({ targetingKey: ctx.request.headers.get("x-user-id") ?? undefined }),
		}),
	],
});

router.post("/orders", async (ctx) => {
	let plan = await planFor(ctx.request);
	return flags.setTransactionContext({ plan }, async () => {
		let express = await ctx.flags.boolean("express-shipping", false); // sees service, user and plan
		let forOwner = await ctx.flags.boolean("express-shipping", false, { targetingKey: "owner-1" });
		return Response.json({ express, forOwner });
	});
});

import { createFlags } from "@sdxc/flags/client";
import { InMemoryProvider } from "@sdxc/flags/provider/memory";
import featureFlags from "@sdxc/flags/middleware/router";
import { isFailure } from "@sdxc/result";

import { ServiceProvider } from "./service-provider.ts";

export let flags = createFlags({ provider: () => new ServiceProvider() });

let outcome = await flags.setProvider(
	"marketing",
	new InMemoryProvider({ "hero-copy": { variants: { a: "Hello", b: "Hi" }, defaultVariant: "a" } }),
);
if (isFailure(outcome)) throw outcome.error;

let marketing = flags.getClient("marketing");
await marketing.string("hero-copy", "Welcome"); // "Hello"
flags.providerMetadata("marketing").name; // "in-memory"

let middleware = featureFlags(flags, { domain: "marketing" }); // ctx.flags reads the same provider

import { createFlags } from "@sdxc/flags/client";

import { ServiceProvider } from "./service-provider.ts";

export let flags = createFlags({
	provider: () => new ServiceProvider(),
	handlers: {
		PROVIDER_ERROR: (details) => alert(`${details.providerName}: ${details.message}`),
		PROVIDER_CONFIGURATION_CHANGED: (details) => invalidate(details.flagsChanged ?? []),
	},
});

let client = flags.getClient();
let details = await client.booleanDetails("new-checkout", false);
if (details.reason === "ERROR" && client.providerStatus !== "READY") {
	degraded(details.errorCode, details.errorMessage);
}

client.track("checkout-completed", { targetingKey: "user-1" }, { value: 42.5 });

import type { Hook } from "@sdxc/flags";

import { createFlags, redactHook, wideEventHook } from "@sdxc/flags/client";
import featureFlags from "@sdxc/flags/middleware/router";
import { createLogger } from "@sdxc/logger";
import { log } from "@sdxc/logger/middleware";
import { createRouter } from "remix/router";

import { ServiceProvider } from "./service-provider.ts";

let timing: Hook = {
	before(hook) {
		hook.hookData.set("start", performance.now());
	},
	finally(hook) {
		let start = hook.hookData.get("start") as number;
		recordLatency(hook.flagKey, performance.now() - start);
	},
};

export let flags = createFlags({
	provider: () => new ServiceProvider(),
	hooks: [redactHook(["email", "ip"]), wideEventHook(), timing],
});

let router = createRouter({
	middleware: [log(createLogger({ service: "checkout" })), featureFlags(flags)],
});