Resolving App Config in Three Layers: Merging Defaults, User, and Remote With Bounded Overrides

// config/resolver.ts
import { z } from "zod";
 
// Defaults schema. The source of truth for types + initial values lives only here.
const ConfigSchema = z.object({
  interstitialCooldownSec: z.number().int().min(30).max(600),
  reviewPromptAfterOpens: z.number().int().min(3).max(50),
  imagePrefetchCount: z.number().int().min(0).max(40),
  showOnboardingV2: z.boolean(),
});
 
export type AppConfig = z.infer<typeof ConfigSchema>;
 
const DEFAULTS: AppConfig = {
  interstitialCooldownSec: 90,
  reviewPromptAfterOpens: 8,
  imagePrefetchCount: 12,
  showOnboardingV2: false,
};
 
// Per-key override policy
//   locked … neither remote nor user may touch it
//   user   … only the user preference may override the default
//   remote … remote may override, but is always clamped to min/max
type Policy =
  | { kind: "locked" }
  | { kind: "user" }
  | { kind: "remote"; min: number; max: number };
 
const POLICIES: Record<keyof AppConfig, Policy> = {
  interstitialCooldownSec: { kind: "remote", min: 60, max: 300 },
  reviewPromptAfterOpens: { kind: "remote", min: 5, max: 20 },
  imagePrefetchCount: { kind: "user" },
  showOnboardingV2: { kind: "locked" },
};

type Sources = {
  user: Partial<AppConfig>;
  remote: Record<string, unknown>; // untrusted external input
};
 
const clamp = (v: number, min: number, max: number) =>
  Math.min(max, Math.max(min, v));
 
export function resolveConfig(sources: Sources): {
  config: AppConfig;
  rejected: string[];
} {
  const out: AppConfig = { ...DEFAULTS };
  const rejected: string[] = [];
 
  for (const key of Object.keys(DEFAULTS) as (keyof AppConfig)[]) {
    const policy = POLICIES[key];
 
    if (policy.kind === "locked") continue; // stays at the default
 
    if (policy.kind === "user") {
      const val = sources.user[key];
      if (val !== undefined) (out[key] as unknown) = val;
      continue;
    }
 
    // policy.kind === "remote"
    const raw = sources.remote[key];
    if (raw === undefined) continue;
 
    // If the type is off, drop just this one key back to the default (don't break the whole object)
    const field = ConfigSchema.shape[key];
    const parsed = field.safeParse(raw);
    if (!parsed.success) {
      rejected.push(`${key}: ${parsed.error.issues[0]?.message ?? "invalid"}`);
      continue;
    }
 
    // Numbers are always pulled inside the policy's bounds
    const value = parsed.data;
    (out[key] as unknown) =
      typeof value === "number" ? clamp(value, policy.min, policy.max) : value;
  }
 
  return { config: out, rejected };
}

// resolver.test.ts
import { resolveConfig } from "./resolver";
 
test("a broken remote value falls back to the app default", () => {
  const { config, rejected } = resolveConfig({
    user: { imagePrefetchCount: 24 },
    remote: {
      interstitialCooldownSec: 3,      // too small -> clamped to floor 60
      reviewPromptAfterOpens: "soon",  // type violation -> falls back to default 8
      showOnboardingV2: true,          // locked -> ignored
    },
  });
 
  expect(config.interstitialCooldownSec).toBe(60); // clamped
  expect(config.reviewPromptAfterOpens).toBe(8);   // fallback
  expect(config.imagePrefetchCount).toBe(24);      // user override
  expect(config.showOnboardingV2).toBe(false);     // still locked
  expect(rejected.length).toBe(1);
});

// config/useConfig.ts
import { useMemo } from "react";
import { resolveConfig, type AppConfig } from "./resolver";
import { useUserPrefs } from "./userPrefs";   // local to the device
import { useRemoteConfig } from "./remoteConfig"; // raw values from Firebase, etc.
 
export function useConfig(): AppConfig {
  const user = useUserPrefs();
  const remote = useRemoteConfig();
 
  return useMemo(() => {
    const { config, rejected } = resolveConfig({ user, remote });
    if (rejected.length > 0) {
      // In production, never swallow this. Always log it. This is what pays off.
      console.warn("[config] rejected keys", rejected);
    }
    return config;
  }, [user, remote]);
}