Type Safety

The Type Safety Problem

Traditional feature flag systems use string literals and untyped values:

// ❌ Problems with traditional approach
const isEnabled = flags.get("new_checkout"); // Typo in flag name
const theme = flags.get("theme"); // What type is this?
const maxItems = flags.get("maxItems"); // Could be undefined

// Runtime errors waiting to happen!
if (theme.toUpperCase() === "DARK") {
  // TypeError if theme is undefined
  // ...
}

FlagKit’s Type-Safe Approach

FlagKit generates TypeScript types from your flag definitions:

// ✅ FlagKit with full type safety
import { flags } from "./.flagkit/generated/client";

// Autocomplete knows all available flags
const isEnabled = flags.get("newCheckout"); // boolean
//                          ^ Autocomplete suggests: newCheckout, theme, maxItems

// Type is enforced
const theme = flags.get("theme"); // 'light' | 'dark' | 'auto'

// Compiler catches typos
const broken = flags.get("them"); // ❌ Compile error: 'them' doesn't exist

Generated Types

Running flagkit generate creates comprehensive TypeScript types:

// All flag names as union type
export type FlagName = 
  | 'newCheckout'
  | 'theme'
  | 'maxItems'
  | 'apiEndpoint';

// Map of flag names to their value types
export type FlagValues = {
  newCheckout: boolean;
  theme: "light" | "dark" | "auto";
  maxItems: number;
  apiEndpoint: string;
};

// User context with type hints
export type FlagContext = {
  userId?: string;
  rolloutPercent?: number;
  email?: string;
  plan?: "free" | "pro" | "enterprise";
  environment?: "development" | "staging" | "production";
  [key: string]: any; // Allow custom properties
};

Type-Checked API

The flags.get() method is fully type-checked:

// Generic signature
function get<K extends FlagName>(name: K, context?: FlagContext): FlagValues[K];

// Usage examples
const a: boolean = flags.get("newCheckout"); // ✅ Correct type
const b: string = flags.get("newCheckout"); // ❌ Type error!

const c: "light" | "dark" | "auto" = flags.get("theme"); // ✅
const d: string = flags.get("theme"); // ❌ Type error - too broad!

// Type inference works
const theme = flags.get("theme");
if (theme === "dark") {
  // ✅ TypeScript knows theme is the enum
  applyDarkMode();
}

Compile-Time Validation

FlagKit catches errors at compile time, not runtime:

1. Typos in Flag Names

// ❌ Compile error
const value = flags.get("newChckout");
//                      ~~~~~~~~~~~~
// Error: Argument of type '"newChckout"' is not assignable
// to parameter of type 'FlagName'

2. Invalid Default Values

flags.config.ts

// ❌ Compile error
export const flags = defineFlags({
  theme: flag.enum(["light", "dark"]).default("auto"), // 'auto' not in enum!
  //       ~~~~~~
  // Error: Argument of type '"auto"' is not assignable to
  // parameter of type '"light" | "dark"'
});

3. Type Mismatches

// ❌ Compile error
const maxItems: string = flags.get("maxItems");
//    ~~~~~~~~
// Error: Type 'number' is not assignable to type 'string'

Refactoring Safety

Rename flags confidently using TypeScript’s refactoring tools:

// Before: Flag named 'newCheckout'
const isEnabled = flags.get("newCheckout");

// After: Rename to 'newCheckoutFlow'
// 1. Rename in flags.config.ts
// 2. Run `flagkit generate`
// 3. TypeScript shows all places that need updating

const isEnabled = flags.get("newCheckout");
//                          ~~~~~~~~~~~~
// Error: Argument of type '"newCheckout"' is not assignable...

Use your IDE’s “Find All References” feature to locate all usages of a flag before renaming.

Type-Safe Context

Context values are also type-checked:

// Define custom context type
export type AppContext = {
  userId: string; // Required
  plan: "free" | "pro";
  betaTester?: boolean;
};

// Use with flags
const isEnabled = flags.get("newCheckout", {
  userId: user.id,
  plan: user.plan,
  betaTester: user.isBeta,
  // unknownKey: 'value'  // ❌ Error if context is strictly typed
});

Enum Flags

Enum flags get full type safety:

flags.config.ts

export const flags = defineFlags({
  theme: flag.enum(["light", "dark", "auto"]).default("auto"),
});

// Usage is type-safe
const theme = flags.get("theme");

// TypeScript knows exact values
if (theme === "light") {
  // ✅
  setLightMode();
} else if (theme === "dark") {
  // ✅
  setDarkMode();
} else {
  setAutoMode(); // theme is 'auto'
}

// Invalid values caught
if (theme === "blue") {
  // ❌ Compile error
  //          ~~~~~~
  // Error: This condition will always return 'false'
}

Number Flags with Constraints

Number flags can have min/max constraints:

flags.config.ts

export const flags = defineFlags({
  pageSize: flag.number().min(1).max(100).default(20),
});

// Runtime validation
const pageSize = flags.get("pageSize"); // number (1-100)

// TypeScript can't enforce numeric ranges, but runtime will
// If someone edits decision-tree.json to set pageSize: 200,
// FlagKit will clamp to 100

TypeScript can enforce type (string, number, boolean) but not value ranges. Runtime validation ensures values stay within constraints.

Pattern-Based String Flags

String flags can use regex patterns for validation:

flags.config.ts

export const flags = defineFlags({
  apiEndpoint: flag
    .string()
    .pattern(/^https:\/\//)
    .default("https://api.example.com"),

  emailDomain: flag
    .string()
    .pattern(/^[\w-]+(\.[\w-]+)*\.\w+$/)
    .default("example.com"),
});

Benefits Summary

Catch Errors Early

Compile-time validation prevents runtime failures

IDE Support

Autocomplete, go-to-definition, and refactoring tools

Self-Documenting

Types serve as inline documentation

Refactor Safely

Rename flags without breaking code

Next Steps

Deterministic Rollouts

Learn about type-safe percentage-based rollouts

Getting Started

Core Concepts

Guides

The Type Safety Problem

FlagKit’s Type-Safe Approach

Generated Types

Type-Checked API

Compile-Time Validation

1. Typos in Flag Names

2. Invalid Default Values

3. Type Mismatches

Refactoring Safety

Type-Safe Context

Enum Flags

Number Flags with Constraints

Pattern-Based String Flags

Benefits Summary

Catch Errors Early

IDE Support

Self-Documenting

Refactor Safely

Next Steps

Deterministic Rollouts

​The Type Safety Problem

​FlagKit’s Type-Safe Approach

​Generated Types

​Type-Checked API

​Compile-Time Validation

​1. Typos in Flag Names

​2. Invalid Default Values

​3. Type Mismatches

​Refactoring Safety

​Type-Safe Context

​Enum Flags

​Number Flags with Constraints

​Pattern-Based String Flags

​Benefits Summary

Catch Errors Early

IDE Support

Self-Documenting

Refactor Safely

​Next Steps

Deterministic Rollouts

The Type Safety Problem

FlagKit’s Type-Safe Approach

Generated Types

Type-Checked API

Compile-Time Validation

1. Typos in Flag Names

2. Invalid Default Values

3. Type Mismatches

Refactoring Safety

Type-Safe Context

Enum Flags

Number Flags with Constraints

Pattern-Based String Flags

Benefits Summary

Next Steps