@joinremba/beacon 0.1.0 → 0.4.0

package/src/index.test.ts

@@ -1,4 +1,4 @@
-import { expect, test, beforeAll } from "bun:test";
+import { expect, test, beforeEach, mock } from "bun:test";
 import { createBeacon, ConfigValidationError } from "./index";
 import { z } from "zod";
 
@@ -6,11 +6,11 @@ const zodStringMin3 = z.string().min(3);
 
 const ORIGINAL_ENV = { ...process.env };
 
-beforeAll(() => {
+beforeEach(() => {
   process.env = { ...ORIGINAL_ENV };
 });
 
-test("returns typed config values after ensure()", () => {
+test("returns typed config values after ensure()", async () => {
   process.env.DATABASE_URL = "https://example.com/db";
   process.env.REDIS_URL = "https://example.com/redis";
 
@@ -19,44 +19,44 @@ test("returns typed config values after ensure()", () => {
     REDIS_URL: { type: "url", required: true },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<string>("DATABASE_URL")).toBe("https://example.com/db");
   expect(config.get<string>("REDIS_URL")).toBe("https://example.com/redis");
 });
 
-test("throws ValidationError for missing required vars", () => {
+test("throws ValidationError for missing required vars", async () => {
   delete process.env.MISSING_VAR;
 
   const config = createBeacon({
     MISSING_VAR: { type: "string", required: true },
   });
 
-  expect(() => config.ensure()).toThrow(ConfigValidationError);
+  await expect(config.ensure()).rejects.toThrow(ConfigValidationError);
 });
 
-test("does not throw for optional vars with defaults", () => {
+test("does not throw for optional vars with defaults", async () => {
   delete process.env.MY_PORT;
 
   const config = createBeacon({
     MY_PORT: { type: "port", default: 3000 },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<number>("MY_PORT")).toBe(3000);
 });
 
-test("coerces number types", () => {
+test("coerces number types", async () => {
   process.env.MY_NUMBER = "42";
 
   const config = createBeacon({
     MY_NUMBER: { type: "number" },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<number>("MY_NUMBER")).toBe(42);
 });
 
-test("coerces boolean types", () => {
+test("coerces boolean types", async () => {
   process.env.FEATURE_X = "true";
   process.env.FEATURE_Y = "false";
   process.env.FEATURE_Z = "1";
@@ -67,13 +67,13 @@ test("coerces boolean types", () => {
     FEATURE_Z: { type: "boolean" },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<boolean>("FEATURE_X")).toBe(true);
   expect(config.get<boolean>("FEATURE_Y")).toBe(false);
   expect(config.get<boolean>("FEATURE_Z")).toBe(true);
 });
 
-test("validates enum values", () => {
+test("validates enum values", async () => {
   process.env.NODE_ENV = "production";
 
   const config = createBeacon({
@@ -83,11 +83,11 @@ test("validates enum values", () => {
     },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<string>("NODE_ENV")).toBe("production");
 });
 
-test("throws for invalid enum values", () => {
+test("throws for invalid enum values", async () => {
   process.env.NODE_ENV = "invalid";
 
   const config = createBeacon({
@@ -97,17 +97,17 @@ test("throws for invalid enum values", () => {
     },
   });
 
-  expect(() => config.ensure()).toThrow();
+  await expect(config.ensure()).rejects.toThrow();
 });
 
-test("validates port range", () => {
+test("validates port range", async () => {
   process.env.PORT = "99999";
 
   const config = createBeacon({
     PORT: { type: "port" },
   });
 
-  expect(() => config.ensure()).toThrow();
+  await expect(config.ensure()).rejects.toThrow();
 });
 
 test("throws when accessing before ensure()", () => {
@@ -118,7 +118,7 @@ test("throws when accessing before ensure()", () => {
   expect(() => config.get("DB_URL")).toThrow("Call beacon.ensure()");
 });
 
-test("uses profile overrides when profile is set", () => {
+test("uses profile overrides when profile is set", async () => {
   process.env.DB_HOST = "prod.example.com";
 
   const config = createBeacon(
@@ -135,22 +135,22 @@ test("uses profile overrides when profile is set", () => {
     }
   );
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<string>("DB_HOST")).toBe("prod.example.com");
 });
 
-test("accepts Zod schemas directly", () => {
+test("accepts Zod schemas directly", async () => {
   process.env.ZOD_VAR = "hello";
 
   const config = createBeacon({
     ZOD_VAR: { schema: zodStringMin3 },
   });
 
-  config.ensure();
+  await config.ensure();
   expect(config.get<string>("ZOD_VAR")).toBe("hello");
 });
 
-test("collects all errors before throwing", () => {
+test("collects all errors before throwing", async () => {
   delete process.env.VAR_A;
   delete process.env.VAR_B;
 
@@ -159,13 +159,18 @@ test("collects all errors before throwing", () => {
     VAR_B: { type: "number", required: true },
   });
 
-  try {
-    config.ensure();
-    expect.unreachable();
-  } catch (err) {
-    expect(err).toBeInstanceOf(ConfigValidationError);
-    expect((err as ConfigValidationError).errors).toHaveLength(2);
-  }
+  await expect(config.ensure()).rejects.toBeInstanceOf(ConfigValidationError);
+});
+
+test("ensure({ strict: false }) skips missing required vars without throwing", async () => {
+  delete process.env.STRICT_VAR;
+
+  const config = createBeacon({
+    STRICT_VAR: { type: "string", required: true },
+    OPTIONAL_VAR: { type: "number", required: false },
+  });
+
+  await expect(config.ensure({ strict: false })).resolves.toBeDefined();
 });
 
 test("tracks secret keys", () => {
@@ -176,3 +181,158 @@ test("tracks secret keys", () => {
 
   expect(config.secret).toEqual({ API_KEY: true });
 });
+
+test("isEnabled returns false for undefined feature", () => {
+  const config = createBeacon({ PORT: { type: "port", default: 3000 } });
+  expect(config.isEnabled("nonexistent")).toBe(false);
+});
+
+test("isEnabled returns true for enabled feature", () => {
+  const config = createBeacon(
+    { PORT: { type: "port", default: 3000 } },
+    { features: { newDashboard: { enabled: true } } }
+  );
+  expect(config.isEnabled("newDashboard")).toBe(true);
+});
+
+test("isEnabled returns false for disabled feature", () => {
+  const config = createBeacon(
+    { PORT: { type: "port", default: 3000 } },
+    { features: { darkMode: { enabled: false } } }
+  );
+  expect(config.isEnabled("darkMode")).toBe(false);
+});
+
+test("isEnabled respects env override", () => {
+  const prev = process.env.FEATURE_NEW_DASHBOARD;
+  try {
+    process.env.FEATURE_NEW_DASHBOARD = "false";
+    const config = createBeacon(
+      { PORT: { type: "port", default: 3000 } },
+      { features: { newDashboard: { enabled: true } } }
+    );
+    expect(config.isEnabled("newDashboard")).toBe(false);
+  } finally {
+    if (prev === undefined) {
+      delete process.env.FEATURE_NEW_DASHBOARD;
+    } else {
+      process.env.FEATURE_NEW_DASHBOARD = prev;
+    }
+  }
+});
+
+test("isEnabled uses rollout when enabled is true", () => {
+  const config = createBeacon(
+    { PORT: { type: "port", default: 3000 } },
+    { features: { gradual: { enabled: true, rollout: 1 } } }
+  );
+  expect(config.isEnabled("gradual")).toBe(true);
+});
+
+test("isKilled returns false by default", () => {
+  const config = createBeacon({ PORT: { type: "port", default: 3000 } });
+  expect(config.isKilled("newDashboard")).toBe(false);
+});
+
+test("isKilled returns true when set in options", () => {
+  const config = createBeacon(
+    { PORT: { type: "port", default: 3000 } },
+    { killSwitches: { newDashboard: true } }
+  );
+  expect(config.isKilled("newDashboard")).toBe(true);
+});
+
+test("isKilled respects KILL_ env override", () => {
+  const prev = process.env.KILL_NEW_DASHBOARD;
+  try {
+    process.env.KILL_NEW_DASHBOARD = "true";
+    const config = createBeacon(
+      { PORT: { type: "port", default: 3000 } },
+      { killSwitches: { newDashboard: false } }
+    );
+    expect(config.isKilled("newDashboard")).toBe(true);
+  } finally {
+    if (prev === undefined) delete process.env.KILL_NEW_DASHBOARD;
+    else process.env.KILL_NEW_DASHBOARD = prev;
+  }
+});
+
+test("isEnabled returns false when feature is killed", () => {
+  const config = createBeacon(
+    { PORT: { type: "port", default: 3000 } },
+    {
+      features: { newDashboard: { enabled: true } },
+      killSwitches: { newDashboard: true },
+    }
+  );
+  expect(config.isEnabled("newDashboard")).toBe(false);
+});
+
+test("fetches remote config when client is provided", async () => {
+  const config = createBeacon(
+    { LOCAL_VAR: { type: "string", default: "local" } },
+    {
+      client: {
+        getConfig: mock(async () => [
+          { key: "REMOTE_VAR", value: "from-cloud", secret: false, updatedAt: "" },
+        ]),
+      } as any,
+    }
+  );
+
+  await config.ensure();
+  expect(config.get<string>("REMOTE_VAR")).toBe("from-cloud");
+  expect(config.get<string>("LOCAL_VAR")).toBe("local");
+});
+
+test("schema entries take priority over remote config", async () => {
+  const config = createBeacon(
+    { SHARED_KEY: { type: "string", default: "from-schema" } },
+    {
+      client: {
+        getConfig: mock(async () => [
+          { key: "SHARED_KEY", value: "from-cloud", secret: false, updatedAt: "" },
+        ]),
+      } as any,
+    }
+  );
+
+  await config.ensure();
+  expect(config.get<string>("SHARED_KEY")).toBe("from-schema");
+});
+
+test("remote config fills gaps not in schema", async () => {
+  const config = createBeacon(
+    { DEFINED_KEY: { type: "string", default: "schema-val" } },
+    {
+      client: {
+        getConfig: mock(async () => [
+          { key: "DEFINED_KEY", value: "remote-val", secret: false, updatedAt: "" },
+          { key: "REMOTE_ONLY", value: "remote-only", secret: false, updatedAt: "" },
+        ]),
+      } as any,
+    }
+  );
+
+  await config.ensure();
+  expect(config.get<string>("DEFINED_KEY")).toBe("schema-val");
+  expect(config.get<string>("REMOTE_ONLY")).toBe("remote-only");
+});
+
+test("network error on remote config silently falls back to local", async () => {
+  const { NetworkError } = await import("@joinremba/core");
+
+  const config = createBeacon(
+    { LOCAL_VAR: { type: "string", default: "fallback" } },
+    {
+      client: {
+        getConfig: mock(async () => {
+          throw new NetworkError("connection lost");
+        }),
+      } as any,
+    }
+  );
+
+  await config.ensure();
+  expect(config.get<string>("LOCAL_VAR")).toBe("fallback");
+});

package/src/index.ts

@@ -2,66 +2,27 @@ import { z } from "zod";
 import type {
   Beacon as BeaconInterface,
   BeaconOptions,
+  EnsureOptions,
+  FeatureGate,
   FieldDefinition,
   FieldDefinitionWithSchema,
   SchemaEntry,
   FieldType,
 } from "./types";
 import { ConfigError, ConfigValidationError } from "./errors";
+import { typeToSchema } from "./schema";
 
-export type { BeaconOptions, FieldDefinition, FieldDefinitionWithSchema, SchemaEntry, FieldType };
+export type {
+  BeaconOptions,
+  FeatureGate,
+  FieldDefinition,
+  FieldDefinitionWithSchema,
+  SchemaEntry,
+  FieldType,
+};
 export { ConfigError, ConfigValidationError };
 export type { BeaconInterface as Beacon };
 
-const typeToSchema = (entry: FieldDefinition): { schema: z.ZodType<unknown>; secret: boolean } => {
-  const secret = entry.secret ?? false;
-  const { type } = entry;
-
-  let base: z.ZodType<unknown>;
-
-  switch (type) {
-    case "string":
-    case "host":
-      base = z.string();
-      break;
-    case "url":
-      base = z.string().url();
-      break;
-    case "number":
-      base = z.coerce.number();
-      break;
-    case "integer":
-      base = z.coerce.number().int();
-      break;
-    case "boolean":
-      base = z
-        .string()
-        .transform((v) => v === "true" || v === "1")
-        .pipe(z.boolean());
-      break;
-    case "enum":
-      if (!entry.values || entry.values.length === 0) {
-        throw new Error(`Enum field must have values defined`);
-      }
-      base = z.enum(entry.values as [string, ...string[]]);
-      break;
-    case "port":
-      base = z.coerce.number().int().min(1).max(65535);
-      break;
-    case "email":
-      base = z.string().email();
-      break;
-    default:
-      base = z.string();
-  }
-
-  if (entry.default !== undefined) {
-    base = base.default(entry.default);
-  }
-
-  return { schema: base, secret };
-};
-
 const resolveEntry = (
   entry: SchemaEntry
 ): {
@@ -72,20 +33,21 @@ const resolveEntry = (
   description?: string;
 } => {
   if ("schema" in entry && entry.schema instanceof z.ZodType) {
+    const hasDefault = entry.schema.safeParse(undefined).success;
     return {
       schema: entry.schema,
       required: entry.required ?? true,
       secret: entry.secret ?? false,
-      hasDefault: false,
+      hasDefault,
       description: entry.description,
     };
   }
   const field = entry as FieldDefinition;
-  const { schema, secret } = typeToSchema(field);
+  const schema = typeToSchema(field);
   return {
     schema,
     required: field.required ?? true,
-    secret,
+    secret: field.secret ?? false,
     hasDefault: field.default !== undefined,
     description: field.description,
   };
@@ -93,10 +55,27 @@ const resolveEntry = (
 
 const SECRET_CENSOR = "[REDACTED]";
 
+const featureEnvName = (name: string): string =>
+  `FEATURE_${name
+    .replace(/([a-z])([A-Z])/g, "$1_$2")
+    .replace(/[^a-zA-Z0-9]/g, "_")
+    .toUpperCase()}`;
+
+const parseEnvBoolean = (val: string): boolean => val === "true" || val === "1" || val === "yes";
+
+const featureRollup = (name: string): number => {
+  let hash = 5381;
+  for (let i = 0; i < name.length; i++) {
+    hash = ((hash << 5) + hash + name.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash % 10000) / 10000;
+};
+
 export function createBeacon(
   schema: Record<string, SchemaEntry>,
   options?: BeaconOptions
 ): BeaconInterface {
+  const client = options?.client;
   const mergedSchema: Record<string, SchemaEntry> = { ...schema };
 
   if (options?.profile && options?.profiles?.[options.profile]) {
@@ -111,35 +90,51 @@ export function createBeacon(
   const secretKeys = new Set(resolved.filter((e) => e.secret).map((e) => e.key));
 
   let validated: Record<string, unknown> | null = null;
+  const features: Record<string, FeatureGate> = options?.features ?? {};
+  const killSwitches: Record<string, boolean> = options?.killSwitches ?? {};
 
   const beacon: BeaconInterface = {
-    ensure(): BeaconInterface {
+    async ensure(options?: EnsureOptions): Promise<BeaconInterface> {
+      const strict = options?.strict ?? true;
       const errors: ConfigError[] = [];
 
+      if (client) {
+        try {
+          const remote = await client.getConfig();
+          for (const entry of remote) {
+            if (process.env[entry.key] !== undefined) continue;
+            if (mergedSchema[entry.key]) continue;
+            (validated ??= {})[entry.key] = entry.value;
+          }
+        } catch {
+          // Network error — fall back to local-only
+        }
+      }
+
       for (const { key, schema, required, secret, hasDefault } of resolved) {
         const raw = process.env[key];
         const isMissing = raw === undefined || raw === "";
 
-        if (isMissing && hasDefault) {
-          try {
-            const parsed = schema.parse(undefined);
-            (validated ??= {})[key] = parsed;
-          } catch (err) {
-            if (err instanceof z.ZodError) {
-              errors.push(
-                new ConfigError(
-                  key,
-                  `Environment variable ${key}: ${err.issues[0]?.message ?? "Invalid value"}`,
-                  secret
-                )
-              );
+        if (isMissing) {
+          if (hasDefault) {
+            try {
+              const parsed = schema.parse(undefined);
+              (validated ??= {})[key] = parsed;
+            } catch (err) {
+              if (err instanceof z.ZodError) {
+                errors.push(
+                  new ConfigError(
+                    key,
+                    `Environment variable ${key}: ${err.issues[0]?.message ?? "Invalid value"}`,
+                    secret
+                  )
+                );
+              }
             }
+            continue;
           }
-          continue;
-        }
-
-        if (isMissing) {
           if (!required) continue;
+          if (!strict) continue;
           errors.push(
             new ConfigError(key, `Missing required environment variable: ${key}`, secret)
           );
@@ -153,6 +148,7 @@ export function createBeacon(
           if (err instanceof z.ZodError) {
             const issue = err.issues[0];
             const val = secret ? SECRET_CENSOR : raw;
+            if (!strict) continue;
             errors.push(
               new ConfigError(
                 key,
@@ -189,6 +185,34 @@ export function createBeacon(
       }
       return map;
     },
+
+    isKilled(feature: string): boolean {
+      const envName = `KILL_${feature
+        .replace(/([a-z])([A-Z])/g, "$1_$2")
+        .replace(/[^a-zA-Z0-9]/g, "_")
+        .toUpperCase()}`;
+      const envVal = process.env[envName];
+      if (envVal !== undefined && envVal !== "") {
+        return parseEnvBoolean(envVal);
+      }
+      return killSwitches[feature] ?? false;
+    },
+
+    isEnabled(feature: string): boolean {
+      if (this.isKilled(feature)) return false;
+      const envName = featureEnvName(feature);
+      const envVal = process.env[envName];
+      if (envVal !== undefined && envVal !== "") {
+        return parseEnvBoolean(envVal);
+      }
+      const gate = features[feature];
+      if (!gate) return false;
+      if (!gate.enabled) return false;
+      if (gate.rollout !== undefined) {
+        return featureRollup(feature) < gate.rollout;
+      }
+      return true;
+    },
   };
 
   return beacon;

package/src/schema.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+export interface SchemaField {
+  type?: string;
+  default?: unknown;
+  values?: readonly string[];
+}
+
+export function typeToSchema(field: SchemaField): z.ZodType<unknown> {
+  const type = field.type ?? "string";
+  let base: z.ZodType<unknown>;
+
+  switch (type) {
+    case "string":
+    case "host":
+      base = z.string();
+      break;
+    case "url":
+      base = z.string().url();
+      break;
+    case "number":
+      base = z.coerce.number();
+      break;
+    case "integer":
+      base = z.coerce.number().int();
+      break;
+    case "boolean":
+      base = z
+        .string()
+        .transform((v) => v === "true" || v === "1" || v === "yes")
+        .pipe(z.boolean());
+      break;
+    case "enum": {
+      const values = field.values;
+      if (!values || values.length === 0) {
+        throw new Error("Enum field must have values defined");
+      }
+      base = z.enum(values as [string, ...string[]]);
+      break;
+    }
+    case "port":
+      base = z.coerce.number().int().min(1).max(65535);
+      break;
+    case "email":
+      base = z.string().email();
+      break;
+    default:
+      base = z.string();
+  }
+
+  if (field.default !== undefined) {
+    base = base.default(field.default as string | number | boolean);
+  }
+
+  return base;
+}

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import type { Client } from "@joinremba/core";
 
 export type FieldType =
   | "string"
@@ -29,13 +30,30 @@ export interface FieldDefinitionWithSchema {
 
 export type SchemaEntry = FieldDefinition | FieldDefinitionWithSchema;
 
+export interface FeatureGate {
+  enabled: boolean;
+  rollout?: number;
+  description?: string;
+}
+
 export interface BeaconOptions {
   profile?: string;
   profiles?: Record<string, Record<string, SchemaEntry>>;
+  features?: Record<string, FeatureGate>;
+  killSwitches?: Record<string, boolean>;
+  client?: Client;
+}
+
+export interface EnsureOptions {
+  /** When true (default), throws ConfigValidationError for missing required vars.
+   *  When false, silently skips missing required vars — useful in test environments. */
+  strict?: boolean;
 }
 
 export interface Beacon {
-  ensure(): Beacon;
+  ensure(options?: EnsureOptions): Promise<Beacon>;
   get<T = unknown>(key: string): T;
   readonly secret: Record<string, boolean>;
+  isEnabled(feature: string): boolean;
+  isKilled(feature: string): boolean;
 }