Better environment value interface

packages/mongodb-rag-core/package.json

@@ -47,6 +47,7 @@
     "@babel/preset-typescript": "^7",
     "@babel/types": "^7",
     "@release-it/keep-a-changelog": "^4.0.0",
+    "@tsd/typescript": "^5.8.2",
     "@types/common-tags": "^1",
     "@types/deep-equal": "^1.0.4",
     "@types/express": "^4.17.17",
@@ -62,6 +63,7 @@
     "eslint-plugin-tsdoc": "^0.2.14",
     "express": "^4.19.2",
     "jest": "^29",
+    "jest-tsd": "^0.2.2",
     "mongodb-memory-server": "^10.1.2",
     "node-mocks-http": "^1.16.1",
     "prettier": "^2",

packages/mongodb-rag-core/src/getEnv.test-d.ts

@@ -0,0 +1,57 @@
+import { expectType, expectError } from "jest-tsd";
+import { getEnv } from "./getEnv";
+
+const originalEnv = process.env;
+
+beforeEach(() => {
+  process.env = { ...originalEnv };
+});
+
+afterEach(() => {
+  process.env = originalEnv;
+});
+
+test("required env vars are strings", () => {
+  process.env.TEST_ENV_VAR = "test";
+  const env = getEnv({ required: ["TEST_ENV_VAR"] });
+  expectType<string>(env.TEST_ENV_VAR);
+});
+
+test("optional env vars with string defaults are strings", () => {
+  process.env.TEST_ENV_VAR = "test";
+  const env = getEnv({
+    optional: { TEST_ENV_VAR: "default", TEST_ENV_VAR_2: "default" },
+  });
+  expectType<string>(env.TEST_ENV_VAR);
+  expectType<string>(env.TEST_ENV_VAR_2);
+});
+
+test("optional env vars with undefined defaults are strings or undefined", () => {
+  process.env.TEST_ENV_VAR = "test";
+  const env = getEnv({
+    optional: { TEST_ENV_VAR: "default", UNDEFINED_TEST_ENV_VAR: undefined },
+  });
+  expectType<string>(env.TEST_ENV_VAR);
+  expectType<string | undefined>(env.UNDEFINED_TEST_ENV_VAR);
+});
+
+test("accessing an unspecified env var is a type error", () => {
+  expectError(getEnv({}).FOO);
+});
+
+test("mixed env vars are the correct type", () => {
+  process.env.TEST_ENV_VAR = "test";
+  process.env.TEST_ENV_VAR_2 = "test";
+  const env = getEnv({
+    required: ["TEST_ENV_VAR"],
+    optional: {
+      TEST_ENV_VAR_2: "default",
+      TEST_ENV_VAR_3: "default",
+      TEST_ENV_VAR_4: undefined,
+    },
+  });
+  expectType<string>(env.TEST_ENV_VAR);
+  expectType<string>(env.TEST_ENV_VAR_2);
+  expectType<string>(env.TEST_ENV_VAR_3);
+  expectType<string | undefined>(env.TEST_ENV_VAR_4);
+});

packages/mongodb-rag-core/src/getEnv.test.ts

@@ -0,0 +1,94 @@
+import { expectTypeTestsToPassAsync } from "jest-tsd";
+import { getEnv } from "./getEnv";
+
+describe("getEnv", () => {
+  const ORIGINAL_ENV = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it("does not produce static type errors", async () => {
+    await expectTypeTestsToPassAsync(__filename);
+  });
+
+  it("returns required env vars that are defined", () => {
+    process.env.TEST_ENV_VAR = "test";
+    const env = getEnv({ required: ["TEST_ENV_VAR"] });
+    expect(env).toEqual({ TEST_ENV_VAR: "test" });
+  });
+
+  it("throws an error if a required env var is not defined", () => {
+    process.env.TEST_ENV_VAR = "test";
+    expect(() =>
+      getEnv({
+        required: ["TEST_ENV_VAR", "MISSING_ENV_VAR", "MISSING_ENV_VAR_2"],
+      })
+    ).toThrow(
+      "Missing required environment variables:\n - MISSING_ENV_VAR\n - MISSING_ENV_VAR_2"
+    );
+  });
+
+  it("returns optional env vars that are defined", () => {
+    process.env.TEST_ENV_VAR = "test";
+    process.env.TEST_ENV_VAR_2 = "test";
+    const env = getEnv({
+      optional: { TEST_ENV_VAR: "default", TEST_ENV_VAR_2: "default" },
+    });
+    expect(env).toEqual({ TEST_ENV_VAR: "test", TEST_ENV_VAR_2: "test" });
+  });
+
+  it("returns default values for optional env vars that don't exist", () => {
+    process.env.TEST_ENV_VAR = "test";
+    const env = getEnv({
+      optional: { TEST_ENV_VAR: "default", UNDEFINED_TEST_ENV_VAR: "default" },
+    });
+    expect(env).toEqual({
+      TEST_ENV_VAR: "test",
+      UNDEFINED_TEST_ENV_VAR: "default",
+    });
+  });
+
+  it("can default to a string or undefined", () => {
+    process.env.TEST_ENV_VAR = "test";
+    const env = getEnv({
+      optional: {
+        TEST_ENV_VAR: "default",
+        TEST_ENV_VAR_2: undefined,
+        UNDEFINED_TEST_ENV_VAR: "default",
+      },
+    });
+    expect(env).toEqual({
+      TEST_ENV_VAR: "test",
+      TEST_ENV_VAR_2: undefined,
+      UNDEFINED_TEST_ENV_VAR: "default",
+    });
+  });
+
+  it("works with a mix of required and optional env vars", () => {
+    process.env.TEST_ENV_VAR = "test";
+    process.env.TEST_ENV_VAR_2 = "test";
+    const env = getEnv({
+      required: ["TEST_ENV_VAR"],
+      optional: {
+        TEST_ENV_VAR_2: "default",
+        UNDEFINED_TEST_ENV_VAR: "default",
+      },
+    });
+    expect(env).toEqual({
+      TEST_ENV_VAR: "test",
+      TEST_ENV_VAR_2: "test",
+      UNDEFINED_TEST_ENV_VAR: "default",
+    });
+  });
+
+  it("returns an empty object if no env vars are requested", () => {
+    const env = getEnv({});
+    expect(env).toEqual({});
+  });
+});

packages/mongodb-rag-core/src/getEnv.ts

@@ -0,0 +1,56 @@
+interface GetEnvArgs<
+  R extends string,
+  O extends Record<string, string | undefined>
+> {
+  /**
+   A list of environment variables that are required.
+   If any of these are missing, an error will be thrown.
+   */
+  required?: readonly R[];
+  /**
+   An object of environment variables that are optional.
+   If any of these are missing, they will default to the value provided.
+   */
+  optional?: O;
+}
+
+// Helper type to determine the type of an optional env var based on its default value
+type OptionalEnvType<T extends string | undefined> = T extends undefined
+  ? string | undefined
+  : string;
+
+type EnvFromArgs<
+  R extends string,
+  O extends Record<string, string | undefined>
+> = {
+  [K in R]: string;
+} & {
+  [K in keyof O]: OptionalEnvType<O[K]>;
+};
+
+export function getEnv<
+  R extends string = never,
+  O extends Record<string, string | undefined> = Record<never, never>
+>({ required, optional }: GetEnvArgs<R, O>): EnvFromArgs<R, O> {
+  const env = { ...optional };
+  const missingRequired: string[] = [];
+  if (required) {
+    required.forEach((key) => {
+      env[key] = process.env[key];
+      if (!env[key]) {
+        missingRequired.push(key);
+      }
+    });
+  }
+  if (missingRequired.length > 0) {
+    throw new Error(
+      `Missing required environment variables:\n${missingRequired
+        .map((r) => ` - ${r}`)
+        .join("\n")}`
+    );
+  }
+  for (const key in optional) {
+    env[key] = process.env[key] ?? optional[key];
+  }
+  return env as EnvFromArgs<R, O>;
+}

packages/mongodb-rag-core/tsconfig.build.json

@@ -1,4 +1,4 @@
 {
   "extends": "./tsconfig.json",
-  "exclude": ["**/*.test.ts", "test/**/*.ts"]
+  "exclude": ["**/*.test.ts", "**/*.test-d.ts", "test/**/*.ts"]
 }