/**
 * Required environment defaults for every flag.
 *
 * Additional environments can be declared on `FlagDefaults` by name.
 *
 * @example
 * ```ts
 * const environment: FlagEnvironment = "production";
 * ```
 */
export type FlagEnvironment = "development" | "production";

/**
 * Environment-aware boolean defaults for a flag.
 *
 * `development` and `production` are required. Extra keys, such as `staging`
 * or `preview`, are matched against `NODE_ENV` during resolution.
 *
 * @example
 * ```ts
 * const defaults = {
 *   development: true,
 *   staging: true,
 *   production: false,
 * } satisfies FlagDefaults;
 * ```
 */
export type FlagDefaults = Readonly<
  Record<FlagEnvironment, boolean> & Record<string, boolean | undefined>
>;

/**
 * A single feature flag entry in an application registry.
 *
 * @example
 * ```ts
 * const flag = {
 *   description: "Enable the new checkout experience.",
 *   defaults: { development: true, production: false },
 * } satisfies FlagDefinition;
 * ```
 */
export type FlagDefinition = {
  /**
   * Human-readable purpose for the flag.
   */
  readonly description: string;
  /**
   * Values to use when no local override is present.
   */
  readonly defaults: FlagDefaults;
};

/**
 * Application-owned map of feature flag keys to definitions.
 *
 * @example
 * ```ts
 * const registry = {
 *   NEW_CHECKOUT: {
 *     description: "Enable the new checkout experience.",
 *     defaults: { development: true, production: false },
 *   },
 * } satisfies FlagRegistry;
 * ```
 */
export type FlagRegistry = Readonly<Record<string, FlagDefinition>>;

/**
 * String literal union of keys from a typed flag registry.
 *
 * @example
 * ```ts
 * type AppFlagKey = FlagKey<typeof flags>;
 * ```
 */
export type FlagKey<TRegistry extends FlagRegistry> = Extract<
  keyof TRegistry,
  string
>;

/**
 * Resolved boolean values for every flag in a registry.
 *
 * @example
 * ```ts
 * type AppFlagSnapshot = FlagSnapshot<typeof flags>;
 * ```
 */
export type FlagSnapshot<TRegistry extends FlagRegistry = FlagRegistry> = {
  readonly [TKey in FlagKey<TRegistry>]: boolean;
};

/**
 * Preserves literal flag keys and defaults for type-safe resolution.
 *
 * @example
 * ```ts
 * export const flags = defineFlags({
 *   NEW_CHECKOUT: {
 *     description: "Enable the new checkout experience.",
 *     defaults: { development: true, production: false },
 *   },
 * });
 * ```
 */
export function defineFlags<const TRegistry extends FlagRegistry>(
  registry: TRegistry
): TRegistry {
  return registry;
}