@davidlee49/launchgate 0.0.0-stage → 0.5.1

package/dist/resolver-B2cstRTq.d.ts

@@ -0,0 +1,161 @@
+/** What a flag can resolve to. Boolean is the common case, not the only one (Decision 1). */
+type FlagValue = boolean | string | number;
+/**
+ * A flag's retirement — the terminal state of its lifecycle (Decision 11).
+ *
+ * Presence is the retirement: a def carrying this resolves to `value` and **no
+ * source is consulted**, not the env kill switch and not a signed override
+ * cookie. That ordering is the point. A retirement is a decision someone
+ * committed to git, so the only way to reverse it is to revert the commit —
+ * never a leftover `FLAG_X=on` secret or a cookie an engineer is still holding.
+ *
+ * The entry **stays in the registry** after retirement, which is Unleash's
+ * archive-rather-than-delete rule and buys the same property: the key cannot be
+ * silently reused by a new feature (a duplicate key in the registry literal is
+ * a type error), so a stale override can never attach to something it was never
+ * about. Delete the entry only once its code is gone.
+ */
+interface Retirement<T extends FlagValue = FlagValue> {
+    /**
+     * When retirement was decided, `YYYY-MM-DD`. Required, because the clock is
+     * the whole point: retired code that nobody deletes is the flag debt this
+     * state exists to make visible. `auditRegistry` warns once it is older than
+     * the budget.
+     */
+    since: string;
+    /**
+     * What every evaluation returns from now on — and the *disposition record*:
+     * Unleash makes you declare an outcome when completing a flag, because the
+     * cleanup PR has to know which branch of the code survives. `false` retires a
+     * feature outright; `"v1"` on a dynamic-config flag says v1 is what the code
+     * keeps.
+     */
+    value: T;
+}
+interface FlagDef<T extends FlagValue = FlagValue> {
+    /**
+     * The value used when no source decides, and when a source throws.
+     *
+     * Per flag, never global (Decision 3): a work-in-progress gate's safe state is
+     * `false`, but a kill switch on a year-old feature's safe state is `true` —
+     * failing that one closed would take down working functionality because a
+     * database blipped.
+     */
+    fallback: T;
+    /** Why this flag exists. Greppability plus this line is the whole flag-debt mitigation. */
+    description: string;
+    /** May a signed visitor cookie force this flag? Default false — see `cookieOverride`. */
+    overridable?: boolean;
+    /** Per-environment value, consulted by the `envDefault` source. */
+    byEnv?: Record<string, T>;
+    /**
+     * Retired: resolve to `retired.value` and consult no source at all. See
+     * `Retirement` — this outranks every source, including the kill switch.
+     */
+    retired?: Retirement<T>;
+    /**
+     * Projects may hang their own fields here — a stage, a tier, an owner — and
+     * read them back inside a custom source. The registry keeps their real types
+     * (`flags.network.stage` is a `string`); only the erased view a `Source` sees
+     * widens to `unknown`.
+     */
+    [projectField: string]: unknown;
+}
+type FlagRegistry = Record<string, FlagDef>;
+/**
+ * The type a flag resolves to.
+ *
+ * `fallback: false` infers as the *literal* `false` rather than `boolean`,
+ * because `boolean` is itself `true | false` and TypeScript preserves a literal
+ * whose contextual type contains it. Left alone, every boolean flag would be
+ * unable to hold the opposite value. Strings and numbers do not have this
+ * problem (their contextual types are not literal unions), so they keep whatever
+ * the author declared — which is what makes `fallback: "v1" as "v1" | "v2"` work.
+ */
+type FlagValueOf<T extends FlagRegistry, K extends keyof T> = T[K]["fallback"] extends boolean ? boolean : T[K]["fallback"];
+/**
+ * Data a source may target on. Named for OpenFeature's evaluation context, and
+ * `targetingKey` is its field — the CNCF spec every major SDK implements, so
+ * this reads as a familiar dialect rather than a private vocabulary.
+ *
+ * `targetingKey` is **optional** by design, where OpenFeature makes it merely
+ * conventional: an anonymous visitor to a static site has none, and a launch
+ * gate must still resolve for them.
+ */
+interface EvaluationContext {
+    /** Who is being evaluated — a user id, org id, device id. Absent for anonymous visitors. */
+    targetingKey?: string;
+    /** Reads a request cookie. Supplied by a framework adapter; absent means "no cookies here". */
+    cookie?: (name: string) => string | undefined;
+    /** Anything else a project-supplied source needs. */
+    [key: string]: unknown;
+}
+/** @deprecated Renamed to `EvaluationContext` in 0.3.0 to match OpenFeature. */
+type Context = EvaluationContext;
+/** A source's answer. `undefined` means *undecided — ask the next source* (Decision 2). */
+type Decision = FlagValue | undefined;
+interface FlagMeta {
+    key: string;
+    def: FlagDef;
+}
+/**
+ * One link in the resolution chain. Sources are typed against `unknown` values
+ * rather than the registry's inferred types (Decision 8) — the call site keeps
+ * its types, the four built-in sources give theirs up.
+ */
+interface Source {
+    /** Reported to `onError` when this source throws. */
+    readonly name: string;
+    decide(flag: FlagMeta, ctx: Context): Decision | Promise<Decision>;
+}
+interface SourceErrorInfo {
+    flag: string;
+    source: string;
+}
+
+/**
+ * Declares a project's flags. Identity at runtime; it exists to infer each flag's
+ * value type so `resolve()` is typed at the call site.
+ *
+ * The registry lives in the project that reads the flags, not in a table and not
+ * in library config (Decision 4): flags ship with the code they gate, so deleting
+ * one is a pull request and a key nobody reads is visibly dead.
+ */
+declare function defineFlags<T extends FlagRegistry>(flags: T): T;
+interface ResolverOptions<T extends FlagRegistry> {
+    flags: T;
+    /**
+     * Consulted in order; the first definite answer wins. Recommended ordering:
+     * `envOverride` (kill switch), `cookieOverride`, project sources (grants,
+     * opt-in, entitlement), `envDefault`. The flag's `fallback` is terminal and is
+     * not a source, so it cannot be left out.
+     */
+    sources: Source[];
+    /** Called when a source throws or answers with the wrong type. */
+    onError?: (error: unknown, info: SourceErrorInfo) => void;
+}
+/** Every flag in a registry, evaluated. */
+type ResolvedFlags<T extends FlagRegistry> = {
+    [K in keyof T]: FlagValueOf<T, K>;
+};
+interface Resolver<T extends FlagRegistry> {
+    resolve<K extends keyof T & string>(key: K, ctx?: EvaluationContext): Promise<FlagValueOf<T, K>>;
+    /**
+     * Evaluate the whole registry at once — LaunchDarkly's `allFlagsState()`
+     * pattern: resolve server-side, hand the map to the client, and the UI never
+     * flickers because it never had to ask.
+     *
+     * Resolution is concurrent and shares the context object, so subject-backed
+     * sources hit their per-request cache; with `subjectStore({ loadAll })` the
+     * whole registry costs one read.
+     *
+     * Pass the **values** to a client, never the registry — flag keys name
+     * unshipped work, and a viewer who can't see a surface shouldn't learn its
+     * name from the payload.
+     */
+    resolveAll(ctx?: EvaluationContext): Promise<ResolvedFlags<T>>;
+    readonly flags: T;
+}
+declare function createResolver<T extends FlagRegistry>(options: ResolverOptions<T>): Resolver<T>;
+
+export { type Context as C, type Decision as D, type EvaluationContext as E, type FlagValue as F, type Resolver as R, type Source as S, type FlagMeta as a, type FlagRegistry as b, type FlagValueOf as c, type FlagDef as d, type ResolvedFlags as e, type ResolverOptions as f, type Retirement as g, type SourceErrorInfo as h, createResolver as i, defineFlags as j };

package/package.json

@@ -1,6 +1,53 @@
-{
-  "name": "@davidlee49/launchgate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+	"name": "@davidlee49/launchgate",
+	"version": "0.5.1",
+	"description": "A launch-gate library: hide work in progress, kill a shipped feature, no platform required.",
+	"license": "MIT",
+	"type": "module",
+	"files": [
+		"dist",
+		"API.md"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./next": {
+			"types": "./dist/next/index.d.ts",
+			"import": "./dist/next/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsup",
+		"check": "tsc --noEmit && vitest run && tsup",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"prepublishOnly": "pnpm check"
+	},
+	"devDependencies": {
+		"tsup": "^8.5.0",
+		"typescript": "^5.9.2",
+		"vitest": "^3.2.4",
+		"next": "^16.0.0",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"@types/react": "^19.0.0"
+	},
+	"packageManager": "pnpm@10.29.2",
+	"peerDependencies": {
+		"next": ">=15"
+	},
+	"peerDependenciesMeta": {
+		"next": {
+			"optional": true
+		}
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/davidlee49/launchgate.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}