FastStats Feature Flags for the Flags SDK

[!IMPORTANT] This repository is in early development and not intended for production use.

An adapter that lets the Flags SDK resolve flags from FastStats. Flags are evaluated on the server by the FastStats flags service, and every evaluation shows up in the project's flag analytics.

npm install flags @faststats/flags-sdk

Set FASTSTATS_FLAGS_TOKEN to the project token (or an API key scoped to the project with the featureFlagEvaluation:evaluate permission), then declare flags:

import { type FastStatsEntities, fastStatsAdapter } from "@faststats/flags-sdk";
import { dedupe, flag } from "flags/next";

const identify = dedupe(async ({ cookies }): Promise<FastStatsEntities> => ({
	identifier: cookies.get("visitor")?.value,
	userId: cookies.get("user")?.value,
	attributes: { plan: "pro" },
}));

export const newCheckout = flag<boolean, FastStatsEntities>({
	key: "new-checkout",
	adapter: fastStatsAdapter,
	identify,
	defaultValue: false,
});

identify must return an identifier (a stable device or install ID) or a userId (your ID for a signed-in user). Rollouts bucket by userId when it is set, so they follow a user across devices.

The visitor's User-Agent is forwarded so rules can match on browser, os and device, and country is filled from x-vercel-ip-country or cf-ipcountry unless attributes already sets it.

A flag falls back to its defaultValue when it does not exist, is archived, or the service cannot be reached within timeoutMs.

Evaluating several flags

evaluate() resolves flags that share an adapter and identify in one request:

import { evaluate } from "flags/next";

const [checkout, limit] = await evaluate([newCheckout, maxUploads]);

Configuring the adapter

import { createFastStatsAdapter } from "@faststats/flags-sdk";

export const fastStatsAdapter = createFastStatsAdapter({
	token: process.env.MY_TOKEN,
	endpoint: "https://flags.example.com",
	timeoutMs: 1000,
	origin: (key) =>
		`https://faststats.dev/project/my-project/feature-flags?flag=${key}`,
});

token and endpoint fall back to the env when left out. They are read on the first evaluation, so a build does not need them.

| Variable | Default for | | -------------------------- | --------------------------------------------------------- | | FASTSTATS_FLAGS_TOKEN | token. Project token or API key. Required if unset. | | FASTSTATS_FLAGS_ENDPOINT | endpoint. Base URL of the flags service, when self-run. |