# Flag types and values

Choose boolean, string, number, or object flags and handle type mismatches safely.

Every FeatureGate flag has one permanent value type. Environment fallbacks, rule outcomes, SDK
getters, and caller defaults must agree with it.

Choose the smallest type that expresses the decision. Smaller contracts are easier to validate,
review, migrate, and remove.

| Type    | Use it for                              | Example           |
| ------- | --------------------------------------- | ----------------- |
| Boolean | On/off decisions and emergency controls | `false`           |
| String  | A small named mode or variant           | `"compact"`       |
| Number  | A bounded runtime parameter             | `25`              |
| Object  | Cohesive structured configuration       | `{ "limit": 25 }` |

## Boolean flags

Use a boolean when application code has two branches. A release flag, maintenance guard, or kill
switch normally begins here.

```ts
const enabled = featuregate.getBooleanValue("new-checkout", false, context);

if (enabled) {
  return renderNewCheckout();
}

return renderExistingCheckout();
```

Avoid replacing one boolean with several overlapping booleans when the real domain has named modes.
Use a string flag so only one mode can be selected.

## String and number flags

Strings work well for compact named variants such as `"compact"`, `"comfortable"`, and `"dense"`.
Keep the accepted values in application code and handle unknown values defensively.

Numbers suit bounded parameters such as page size, timeout class, or concurrency. The application
must validate acceptable ranges. A correctly typed number can still be operationally unsafe.

```ts
const configuredPageSize = featuregate.getNumberValue("page-size", 25, context);
const pageSize = Math.min(100, Math.max(10, configuredPageSize));
```

Do not use numbers to encode categories. A string such as `"standard"` communicates intent better
than a magic value such as `2`.

## Object flags

Use objects when several fields must change as one coherent configuration. Values must be
JSON-compatible. Validate the returned shape before it controls consequential behaviour.

```ts
interface SearchLimits {
  pageSize: number;
  timeoutMs: number;
}

const fallback: SearchLimits = { pageSize: 25, timeoutMs: 800 };
const value = featuregate.getObjectValue("search-limits", fallback, context);
```

Object flags create a larger compatibility surface. Prefer separate flags when fields have different
owners, rollout schedules, or failure policies.

## Defaults and type mismatches

Every getter and HTTP evaluation supplies a typed default. A missing flag or type mismatch returns
that value rather than coercing data.

The boolean getter never treats the string `"true"` as enabled. A number getter never parses `"25"`.
This prevents configuration mistakes from changing application semantics silently.

Details getters reveal whether the default was used and why. Use them in tests, diagnostics, and
integration checks. Keep normal application branching on the typed value.

## Change a flag contract

Flag type cannot change after creation. When meaning or type must change:

1. Create a new key with the new contract.
2. Add code that can read the new flag safely.
3. Configure and validate it in non-production.
4. Roll callers onto the new key.
5. Remove the old guarded code.
6. Archive the old flag.

Never reuse an old key for a different meaning. Long-running processes, old deployments, and tests
may still interpret it under the original contract.

## Security and data handling

Do not place secrets or personal data in values. Server snapshots distribute values to every trusted
process holding the environment key. Client-exposed values can be delivered to browsers.

Flags are runtime decisions, not a secret store or database. Use application-owned storage for data
that needs access control, transactional updates, or durable history.

Related pages: [Configure flags across environments](/docs/flags/environment-configuration) and
[Errors and fallbacks](/docs/evaluate/errors-and-fallbacks).