Flag Types

Understanding FlagFlow's comprehensive flag type system for different use cases

Overview

FlagFlow supports 7 different flag types, each designed for specific use cases and providing type-safe configuration management. Each flag type includes built-in validation, TypeScript support, and configurable constraints to ensure data integrity.

Type Safety: All flag types generate complete TypeScript definitions with IntelliSense support and runtime Zod schema validation.

Flag Types Reference

Type	Description	TypeScript Type	Example Value
`BOOLEAN`	Simple on/off features and kill switches. Perfect for feature toggles, enabling/disabling functionality, or binary configuration options. No additional constraints or properties required.	`boolean`	`true`
`INTEGER`	Numeric configuration values with optional min/max constraints. Ideal for retry counts, timeouts, rate limits, batch sizes, and any numeric thresholds that require validation within specific ranges.	`number`	`42`
`STRING`	Text-based configuration with optional length and regex pattern validation. Perfect for API endpoints, messages, identifiers, and any textual configuration that needs format validation or length constraints.	`string`	`"api.example.com"`
`ENUM`	Select one option from a predefined set of choices. Excellent for theme selection, environment modes, algorithm choices, or any configuration where you need to restrict values to specific valid options with type safety.	`"red" \| "green" \| "blue"`	`"red"`
`TAG`	Multiple selections from predefined choices with optional min/max count constraints. Ideal for feature module selection, multi-option configuration, categorization, or any scenario requiring multiple valid selections.	`("analytics" \| "chat" \| "notifications" \| "reporting")[]`	`["analytics", "notifications"]`
`OBJECT`	Complex structured data with JavaScript object syntax. Supports nested objects, arrays, and complex type definitions with schema validation. Perfect for configuration objects, nested settings, API payloads, and any structured data requirements.	`{ server: string; port: number }`	`{ server: "api.example.com", port: 8080 }`
`AB-TEST`	A/B testing and split testing with configurable probability distribution. Returns "A" or "B" based on specified percentage chance for variant B. Perfect for gradual rollouts, experimental features, and controlled testing.	`"A" \| "B"`	`"A"` (75% chance) `"B"` (25% chance)

Type Constraints and Validation

Each flag type supports specific constraints and validation rules to ensure data integrity:

Type	Available Constraints	Example Configuration
`BOOLEAN`	No additional constraints	`defaultValue: true`
`INTEGER`	`minValue`, `maxValue`	`minValue: 1, maxValue: 100`
`STRING`	`maxLength`, `regexPattern`	`maxLength: 255, regexPattern: "^https?://"`
`ENUM`	`enumValues` (required)	`enumValues: ["light", "dark", "auto"]`
`TAG`	`enumValues` (required), `minCount`, `maxCount`	`enumValues: ["core", "analytics", "notifications", "reporting"], minCount: 1, maxCount: 4`
`OBJECT`	`objectSchema` (JavaScript object syntax)	`objectSchema: "{ server: string, port: number }"`
`AB-TEST`	`chancePercentB` (0-100)	`chancePercentB: 25.0`

TypeScript Integration

FlagFlow generates complete TypeScript definitions for all flag types, providing full IntelliSense support and compile-time type checking:

Generated TypeScript Types and Schemas

// Generated TypeScript definitions
export interface FLAGS {
  enable_new_dashboard: boolean;           // BOOLEAN type
  max_retries: number;                     // INTEGER type
  api_endpoint: string;                    // STRING type
  theme_mode: "light" | "dark" | "auto";   // ENUM type
  enabled_modules: ("core" | "analytics" | "notifications" | "reporting")[]; // TAG type
  api_config: {                           // OBJECT type
    server: string;
    port: number;
    timeout: number;
  };
  ab_test_variant: "A" | "B";             // AB-TEST type
}

// Runtime Zod schemas for validation
const FLAGS_SCHEMA = {
  enable_new_dashboard: z.boolean().default(false),
  max_retries: z.number().min(1).max(10).default(3),
  api_endpoint: z.string().max(255).regex(/^https?:///).default("https://api.example.com"),
  theme_mode: z.enum(["light", "dark", "auto"]).default("auto"),
  enabled_modules: z.array(z.enum(["core", "analytics", "notifications", "reporting"])).min(1).max(4).default(["core"]),
  api_config: z.object({                  // OBJECT type with schema
    server: z.string(),
    port: z.number(),
    timeout: z.number()
  }).default({
    server: "api.example.com",
    port: 8080,
    timeout: 5000
  }),
  ab_test_variant: z.string().default("A") // Runtime logic handles A/B distribution
};

Validation and Error Handling

Schema Validation

Runtime validation using Zod schemas
Type coercion and default value handling
Constraint validation (min/max, regex, enum values)
Detailed error messages for invalid values

Hash Validation

Generated hash constants for schema integrity
Compile-time detection of schema changes
Prevents runtime errors from schema mismatches
Ensures client-server schema synchronization

Object Flags Deep Dive

Object flags represent FlagFlow's most powerful flag type, supporting complex structured data with full TypeScript integration and runtime validation. They use JavaScript object syntax for schema definition and support nested objects, arrays, and all primitive types.

JavaScript Object Syntax

Object flags use familiar JavaScript object syntax for schema definition, making them intuitive for developers:

Object Schema Examples

// Simple object schema
{ server: string, port: number }

// Database configuration with optional properties
{
  database: {
    host: string,
    port: number,
    name: string,
    ssl?: boolean,
    timeout: number
  }
}

// API configuration with nested settings
{
  api: {
    endpoint: string,
    timeout: number,
    retries: number,
    headers: { [key: string]: string }
  },
  cache: {
    enabled: boolean,
    ttl: number,
    providers: ("memory" | "redis" | "disk")[]
  }
}

Type Generation and Validation

FlagFlow automatically generates TypeScript interfaces and Zod schemas for object flags, providing complete type safety and runtime validation:

Generated Types and Usage

// Generated TypeScript interface
export interface DatabaseConfig {
  database: {
    host: string;
    port: number;
    name: string;
    ssl?: boolean;
    timeout: number;
  };
}

// Generated Zod schema
const DatabaseConfigSchema = z.object({
  database: z.object({
    host: z.string(),
    port: z.number(),
    name: z.string(),
    ssl: z.boolean().optional(),
    timeout: z.number()
  })
});

// Usage with full type safety
const config: DatabaseConfig = FLAGS.database_config;
console.log(config.database.host);     // TypeScript IntelliSense available
console.log(config.database.port);     // Number type fully validated

Practical Use Cases

Service Configuration

{
  redis: {
    host: string,
    port: number,
    password: string,
    database: number
  },
  api: {
    baseUrl: string,
    timeout: number,
    retries: number
  }
}

Feature Settings

{
  email: {
    provider: "smtp" | "sendgrid" | "ses",
    host: string,
    port: number,
    secure: boolean
  },
  logging: {
    level: "error" | "warn" | "info" | "debug",
    destinations: string[]
  }
}

Best Practices

Choosing the Right Type

BOOLEAN: Use for simple on/off features and kill switches
INTEGER: Use for numeric configs that need range validation
STRING: Use for text configs that may need format validation
OBJECT: Use for complex structured data, nested configurations, and API payloads
ENUM: Use when you need to restrict to specific valid options
TAG: Use for multi-selection scenarios with validation
AB-TEST: Use for split testing and gradual rollouts

Performance Considerations

All types have minimal runtime overhead
AB-TEST uses deterministic hashing for consistent results
ENUM and TAG types use efficient union type checking
OBJECT types use optimized parsing and comprehensive validation
Schema validation happens only during flag updates

On this page