Merge pull request #13 from ReforgeHQ/mfaga-better-typing

feat: introduce type safety

Author: mjfaga

.eslintrc.js

@@ -25,6 +25,8 @@ module.exports = {
     "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
     "@typescript-eslint/no-empty-function": "off",
     "@typescript-eslint/no-explicit-any": "off",
+    "no-shadow": "off", // disable base rule for TypeScript
+    "@typescript-eslint/no-shadow": ["error"],
     "import/prefer-default-export": "off",
     "import/extensions": [
       "error",

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.0.0-pre.6 - 2025-09-30
+
+- Support extendable typescript types w/typegen from cli
+
 ## 0.0.0-pre.5 - 2025-09-24
 
 - Use reforge.com endpoints

index.ts

@@ -1,14 +1,19 @@
-import { reforge, Reforge, ReforgeBootstrap } from "./src/reforge";
+import { reforge, Reforge, ReforgeInitParams, ReforgeBootstrap } from "./src/reforge";
 import { Config } from "./src/config";
 import Context from "./src/context";
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const { version } = require("./package.json");
 
-export { reforge, Reforge, Config, Context, version };
+export { reforge, Reforge, ReforgeInitParams, Config, Context, version };
 
 export { ReforgeBootstrap };
 
-export type { Duration } from "./src/configValue";
-export type { default as ConfigValue } from "./src/configValue";
-export type { default as ContextValue } from "./src/contextValue";
+export type { ConfigValue } from "./src/config";
+export type {
+  Duration,
+  ContextValue,
+  Contexts,
+  TypedFrontEndConfigurationRaw,
+  FrontEndConfigurationRaw,
+} from "./src/types";
 export type { CollectContextModeType } from "./src/loader";

package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "yarn@4.9.2",
   "name": "@reforge-com/javascript",
-  "version": "0.0.0-pre.5",
+  "version": "0.0.0-pre.6",
   "description": "Feature Flags & Dynamic Configuration as a Service",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",

src/config.ts

@@ -1,30 +1,136 @@
-import ConfigKey from "./configKey";
-import ConfigValue from "./configValue";
+import { ReforgeLogLevel } from "./logger";
+import { TypedFrontEndConfigurationRaw, ConfigEvaluationMetadata } from "./types";
 
-export type RawConfigWithoutTypes = { [key: string]: any };
-
-export type ConfigEvaluationMetadata = {
-  configRowIndex: number;
-  conditionalValueIndex: number;
-  type: string;
-  configId: string;
-};
+export type RawConfigWithoutTypes = Record<string, any>;
 
 type APIKeyMetadata = {
   id: string | number;
 };
 
+// TODO: Why is this definition different from the one in ./types.ts?
 type Duration = {
   definition: string;
   millis: number;
 };
 
-type Value = {
-  [key: string]: number | string | string[] | boolean | Duration;
-};
+export interface IntRange {
+  /** if empty treat as Number.MIN_VALUE. Inclusive */
+  start?: bigint | undefined;
+  /** if empty treat as Number.MAX_VALUE. Exclusive */
+  end?: bigint | undefined;
+}
+
+export enum ProvidedSource {
+  EnvVar = "ENV_VAR",
+}
+export interface Provided {
+  source?: ProvidedSource | undefined;
+  /** eg MY_ENV_VAR */
+  lookup?: string | undefined;
+}
+
+export enum SchemaType {
+  UNKNOWN = 0,
+  ZOD = 1,
+  JSON_SCHEMA = 2,
+}
+
+export interface Schema {
+  schema: string;
+  schemaType: SchemaType;
+}
+
+export interface WeightedValue {
+  /** out of 1000 */
+  weight: number;
+  // eslint-disable-next-line no-use-before-define
+  value: ConfigValue | undefined;
+}
+
+export enum LimitResponse_LimitPolicyNames {
+  SecondlyRolling = 1,
+  MinutelyRolling = 3,
+  HourlyRolling = 5,
+  DailyRolling = 7,
+  MonthlyRolling = 8,
+  Infinite = 9,
+  YearlyRolling = 10,
+}
+
+export enum LimitDefinition_SafetyLevel {
+  L4_BEST_EFFORT = 4,
+  L5_BOMBPROOF = 5,
+}
+
+export interface LimitDefinition {
+  policyName: LimitResponse_LimitPolicyNames;
+  limit: number;
+  burst: number;
+  accountId: number;
+  lastModified: number;
+  returnable: boolean;
+  /** [default = L4_BEST_EFFORT]; // Overridable by request */
+  safetyLevel: LimitDefinition_SafetyLevel;
+}
+export interface WeightedValues {
+  weightedValues: WeightedValue[];
+  hashByPropertyName?: string | undefined;
+}
+
+export type ConfigValue =
+  | {
+      int: number | undefined;
+    }
+  | {
+      string: string | undefined;
+    }
+  | {
+      bytes: Buffer | undefined;
+    }
+  | {
+      double: number | undefined;
+    }
+  | {
+      bool: boolean | undefined;
+    }
+  | {
+      weightedValues?: WeightedValues | undefined;
+    }
+  | {
+      limitDefinition?: LimitDefinition | undefined;
+    }
+  | {
+      logLevel: ReforgeLogLevel | undefined;
+    }
+  | {
+      stringList: string[] | undefined;
+    }
+  | {
+      intRange: IntRange | undefined;
+    }
+  | {
+      provided: Provided | undefined;
+    }
+  | {
+      duration: Duration | undefined;
+    }
+  | {
+      json: string | undefined;
+    }
+  | {
+      schema: Schema | undefined;
+    }
+  | {
+      /** don't log or telemetry this value */
+      confidential: boolean | undefined;
+    }
+  | {
+      /** key name to decrypt with */
+      decryptWith: string | undefined;
+    };
 
 type Evaluation = {
-  value: Value;
+  value: ConfigValue;
   configEvaluationMetadata: {
     configRowIndex: string | number;
     conditionalValueIndex: string | number;
@@ -47,7 +153,11 @@ const parseRawMetadata = (metadata: any) => ({
   configId: metadata.id,
 });
 
-const valueFor = (value: Value, type: string, key: string): ConfigValue => {
+const valueFor = <K extends keyof TypedFrontEndConfigurationRaw>(
+  value: ConfigValue,
+  type: keyof ConfigValue,
+  key: K
+): TypedFrontEndConfigurationRaw[K] => {
   const rawValue = value[type];
 
   switch (type) {
@@ -77,7 +187,7 @@ export const parseEvaluationPayload = (payload: EvaluationPayload) => {
   Object.keys(payload.evaluations).forEach((key) => {
     const evaluation = payload.evaluations[key];
 
-    const type = Object.keys(evaluation.value)[0];
+    const type = Object.keys(evaluation.value)[0] as keyof ConfigValue;
 
     // eslint-disable-next-line no-use-before-define
     configs[key] = new Config(
@@ -98,30 +208,32 @@ const parseRawConfigWithoutTypes = (payload: RawConfigWithoutTypes) => {
   // eslint-disable-next-line no-use-before-define
   const configs = {} as { [key: string]: Config };
   Object.keys(payload).forEach((key) => {
-    const type = typeof payload[key];
+    const type = typeof payload[key] as keyof ConfigValue;
     // eslint-disable-next-line no-use-before-define
     configs[key] = new Config(key, valueFor({ [type]: payload[key] }, type, key), type);
   });
 
   return configs;
 };
 
-export class Config {
-  key: ConfigKey;
+export class Config<
+  K extends keyof TypedFrontEndConfigurationRaw = keyof TypedFrontEndConfigurationRaw,
+> {
+  key: K;
 
-  value: ConfigValue;
+  value: TypedFrontEndConfigurationRaw[K];
 
-  rawValue: Value | undefined;
+  rawValue: ConfigValue | undefined;
 
-  type: string;
+  type: keyof ConfigValue;
 
   configEvaluationMetadata: ConfigEvaluationMetadata | undefined;
 
   constructor(
-    key: ConfigKey,
-    value: ConfigValue,
-    type: string,
-    rawValue?: Value,
+    key: K,
+    value: TypedFrontEndConfigurationRaw[K],
+    type: keyof ConfigValue,
+    rawValue?: ConfigValue,
     metadata?: ConfigEvaluationMetadata
   ) {
     this.key = key;

src/configKey.ts

@@ -1,9 +1,6 @@
-import Key from "./key";
-import ContextValue from "./contextValue";
+import { Contexts, ContextValue } from "./types";
 import base64Encode from "./base64Encode";
 
-export type Contexts = { [key: Key]: Record<string, ContextValue> };
-
 const isEqual = (a: Contexts, b: Contexts) => {
   const aKeys = Object.keys(a);
   const bKeys = Object.keys(b);

src/configValue.ts

@@ -1,9 +1,6 @@
-import {
-  massageSelectedValue,
-  massageConfigForTelemetry,
-  ConfigEvaluationCounter,
-} from "./evaluationSummaryAggregator";
-import { Config, parseEvaluationPayload, EvaluationPayload } from "./config";
+import { massageSelectedValue, massageConfigForTelemetry } from "./evaluationSummaryAggregator";
+import { Config, parseEvaluationPayload, EvaluationPayload, ConfigValue } from "./config";
+import { ConfigEvaluationCounter } from "./types";
 
 describe("massageSelectedValue", () => {
   [
@@ -21,7 +18,11 @@ describe("massageSelectedValue", () => {
     [{ stringList: ["a", "b", "c"] }, { values: ["a", "b", "c"] }],
   ].forEach(([value, expected]) => {
     it(`should massage ${JSON.stringify(value)} to ${JSON.stringify(expected)}`, () => {
-      const config = new Config("key", Object.values(value)[0], Object.keys(value)[0]);
+      const config = new Config(
+        "key",
+        Object.values(value)[0],
+        Object.keys(value)[0] as keyof ConfigValue
+      );
       const massagedValue = massageSelectedValue(config);
 
       expect(massagedValue).toEqual(expected);