@quintal/environment 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@quintal/environment",
+  "version": "0.1.0",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "20.10.2",
+    "@vitest/coverage-v8": "0.34.6",
+    "happy-dom": "12.10.3",
+    "typescript": "5.3.2",
+    "vite": "5.0.4",
+    "vitest": "0.34.6",
+    "zod": "3.22.4",
+    "@quintal/config": "0.2.0"
+  },
+  "scripts": {
+    "build": "run-s build:*",
+    "build:clean": "shx rm -rf dist",
+    "build:code": "vite build",
+    "clean": "shx rm -rf .coverage .coverage-ts .turbo dist node_modules",
+    "dev": "vitest --watch",
+    "lint": "pnpm lint:fix && pnpm lint:types",
+    "lint:check": "eslint .",
+    "lint:fix": "pnpm lint:check --fix",
+    "lint:types": "tsc",
+    "test": "vitest"
+  }
+}

package/src/index.ts

@@ -0,0 +1,152 @@
+import { z } from 'zod';
+import type { ZodError, ZodType } from 'zod';
+
+type EnvValue = {
+  /**
+   * The value
+   * @example process.env.NODE_ENV
+   * @example process.env.DATABASE_URL
+   * @example process.env.NEXT_PUBLIC_ENVIRONMENT
+   */
+  value: string | undefined;
+  /**
+   * Zod schema that validates the value of the environment variable.
+   * @defaultValue z.string()
+   */
+  schema?: ZodType;
+  /**
+   * Only make environment variable available to server usages.
+   * @defaultValue false
+   */
+  isServerOnly?: boolean;
+};
+
+type EnvValues = { [key: string]: EnvValue | EnvValues };
+
+type UnwrapEnvValue<T> = T extends EnvValue
+  ? T extends Required<Pick<EnvValue, 'schema'>>
+    ? ReturnType<T['schema']['parse']>
+    : string
+  : T extends Record<string, unknown>
+    ? { [TKey in keyof T]: UnwrapEnvValue<T[TKey]> }
+    : never;
+
+type UnwrapEnvValues<TEnvValues extends EnvValues> = {
+  [TKey in keyof TEnvValues]: UnwrapEnvValue<TEnvValues[TKey]>;
+  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents -- This needs to be here for "prettify" effect
+} & unknown;
+
+type CreateEnvironmentOptions<TEnvValues extends EnvValues> = {
+  /**
+   * Whether or not the application is running on the server.
+   * @defaultValue typeof window === 'undefined'
+   */
+  isServer?: boolean;
+  /**
+   * Called when validation fails.
+   * Default behaviour: throw Error
+   */
+  onValidationError?: (error: ZodError) => never;
+  /**
+   * Called when a server-side environment variable is accessed on the client.
+   * Default behaviour: throw Error
+   */
+  onAccessError?: (variableName: string) => never;
+  /**
+   * The values in the typed environment object.
+   */
+  values: TEnvValues;
+};
+
+function makeValues(values: EnvValues): Record<string, unknown> {
+  return Object.entries(values).reduce(
+    (prev, [name, obj]) => {
+      if ('value' in obj) prev[name] = obj.value || undefined;
+      else prev[name] = makeValues(obj);
+      return prev;
+    },
+    {} as Record<string, unknown>,
+  );
+}
+
+function makeSchema(values: EnvValues, isServer: boolean): ZodType {
+  const o = Object.entries(values).reduce(
+    (prev, [name, obj]) => {
+      if ('value' in obj) {
+        if (!obj.isServerOnly || isServer)
+          prev[name] = (obj.schema as ZodType | undefined) ?? z.string();
+      } else prev[name] = makeSchema(obj, isServer);
+      return prev;
+    },
+    {} as Record<string, ZodType>,
+  );
+  return z.object(o);
+}
+
+function createProxy<TEnvValues extends EnvValues>(
+  values: UnwrapEnvValues<TEnvValues>,
+  originalValues: EnvValues,
+  isServer: boolean,
+  onAccessError: (variableName: string) => never,
+  prefix?: string,
+): UnwrapEnvValues<TEnvValues> {
+  return new Proxy(values, {
+    get(target, prop: string) {
+      const targetValue = originalValues[prop];
+      if (!targetValue) return undefined;
+
+      const variableName = prefix ? `${prefix}.${prop}` : prop;
+
+      if (!('value' in targetValue))
+        return createProxy(
+          values[prop] as UnwrapEnvValues<TEnvValues>,
+          originalValues[prop] as EnvValues,
+          isServer,
+          onAccessError,
+          variableName,
+        );
+
+      if (targetValue.isServerOnly && !isServer)
+        return onAccessError(variableName);
+
+      return target[prop];
+    },
+  });
+}
+
+export function createEnvironment<TEnvValues extends EnvValues>(
+  opts: CreateEnvironmentOptions<TEnvValues>,
+): UnwrapEnvValues<TEnvValues> {
+  const isServer = opts.isServer ?? typeof window === 'undefined';
+
+  const onValidationError =
+    opts.onValidationError ??
+    ((error: ZodError) => {
+      throw new Error(
+        `❌ Invalid environment variables: ${error.issues
+          .map(({ path, message }) => `${path.join('.')}: ${message}`)
+          .join(', ')}`,
+      );
+    });
+
+  const onAccessError =
+    opts.onAccessError ??
+    ((variableName: string) => {
+      throw new Error(
+        `❌ Attempted to access server-side environment variable '${variableName}' on the client`,
+      );
+    });
+
+  const schema = makeSchema(opts.values, isServer);
+  const values = makeValues(opts.values);
+
+  const parsed = schema.safeParse(values);
+  if (!parsed.success) return onValidationError(parsed.error);
+
+  return createProxy(
+    parsed.data as UnwrapEnvValues<TEnvValues>,
+    opts.values,
+    isServer,
+    onAccessError,
+  );
+}

package/test/index.spec.ts

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { createEnvironment } from '../src';
+
+describe('environment', () => {
+  it('returns a strongly-typed environment object', () => {
+    if (false as boolean) {
+      const environment = createEnvironment({
+        values: {
+          environment: {
+            value: process.env.NEXT_PUBLIC_ENVIRONMENT,
+            schema: z
+              .enum(['DEVELOPMENT', 'PREVIEW', 'PRODUCTION'])
+              .default('DEVELOPMENT'),
+          },
+          port: {
+            value: process.env.PORT,
+            schema: z.coerce.number().int().default(4000),
+            isServerOnly: true,
+          },
+          isFeatureEnabled: {
+            value: process.env.NEXT_PUBLIC_IS_FEATURE_ENABLED,
+            schema: z.enum(['true', 'false']).transform((s) => s === 'true'),
+          },
+          baseUrl: {
+            self: {
+              value: process.env.NEXT_PUBLIC_BASE_URL_SELF,
+              schema: z.string().url().default('http://localhost:3000'),
+            },
+            api: {
+              value: process.env.NEXT_PUBLIC_BASE_URL_API,
+              schema: z.string().url().default('http://localhost:4000'),
+            },
+          },
+          database: {
+            url: {
+              value: process.env.DATABASE_URL,
+              schema: z.string().url(),
+              isServerOnly: true,
+            },
+            token: {
+              value: process.env.DATABASE_TOKEN,
+              isServerOnly: true,
+            },
+          },
+        },
+      });
+
+      expectTypeOf(environment).toEqualTypeOf<{
+        environment: 'DEVELOPMENT' | 'PREVIEW' | 'PRODUCTION';
+        port: number;
+        isFeatureEnabled: boolean;
+        baseUrl: {
+          self: string;
+          api: string;
+        };
+        database: {
+          url: string;
+          token: string;
+        };
+      }>();
+    }
+  });
+
+  it('throws when an environment variable is incorrect', () => {
+    expect(() =>
+      createEnvironment({
+        values: {
+          undefined: { value: undefined },
+          nestedUndefined: { undefined: { value: undefined } },
+          emptyString: { value: '' },
+          emptyStringToNumber: { value: '', schema: z.number() },
+          emptyStringWithDefault: {
+            value: '',
+            schema: z.string().default('test'),
+          },
+          emptyStringToNumberWithDefault: {
+            value: '',
+            schema: z.number().default(42),
+          },
+        },
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      '"❌ Invalid environment variables: undefined: Required, nestedUndefined.undefined: Required, emptyString: Required, emptyStringToNumber: Required"',
+    );
+  });
+
+  it('does not throw when accessing a client environment variable and server variables are missing', () => {
+    const environment = createEnvironment({
+      isServer: false,
+      values: {
+        correct: { value: 'hello world' },
+        incorrect: { value: undefined, isServerOnly: true },
+      },
+    });
+
+    expect(environment.correct).toBe('hello world');
+  });
+
+  it('throws when trying to access server-only variables from the client', () => {
+    const values = {
+      serverOnly: { value: 'hello', isServerOnly: true },
+      notServerOnly: { value: 'world', isServerOnly: false },
+      nested: {
+        serverOnly: { value: 'helloNested', isServerOnly: true },
+        notServerOnly: { value: 'worldNested', isServerOnly: false },
+      },
+    };
+
+    const clientEnvironment = createEnvironment({ isServer: false, values });
+    expect(
+      () => clientEnvironment.serverOnly,
+    ).toThrowErrorMatchingInlineSnapshot(
+      '"❌ Attempted to access server-side environment variable \'serverOnly\' on the client"',
+    );
+    expect(clientEnvironment.notServerOnly).toBe('world');
+    expect(
+      () => clientEnvironment.nested.serverOnly,
+    ).toThrowErrorMatchingInlineSnapshot(
+      '"❌ Attempted to access server-side environment variable \'nested.serverOnly\' on the client"',
+    );
+    expect(clientEnvironment.nested.notServerOnly).toBe('worldNested');
+
+    const serverEnvironment = createEnvironment({ isServer: true, values });
+    expect(serverEnvironment.serverOnly).toBe('hello');
+    expect(serverEnvironment.notServerOnly).toBe('world');
+    expect(serverEnvironment.nested.serverOnly).toBe('helloNested');
+    expect(serverEnvironment.nested.notServerOnly).toBe('worldNested');
+  });
+
+  it('parses (nested) environment variables to be in the correct datatype', () => {
+    const environment = createEnvironment({
+      values: {
+        string: { value: 'hello world', schema: z.string() },
+        number: { value: '42', schema: z.coerce.number().int() },
+        boolean: {
+          value: 'true',
+          schema: z.enum(['true', 'false']).transform((s) => s === 'true'),
+        },
+        nested: {
+          string: { value: 'nested hello world', schema: z.string() },
+          number: { value: '4242', schema: z.coerce.number().int() },
+          boolean: {
+            value: 'false',
+            schema: z.enum(['true', 'false']).transform((s) => s === 'true'),
+          },
+        },
+      },
+    });
+
+    expect(environment.string).toBe('hello world');
+    expect(environment.number).toBe(42);
+    expect(environment.boolean).toBe(true);
+    expect(
+      // @ts-expect-error -- testing invalid access
+      environment.never,
+    ).toBe(undefined);
+    expect(environment.nested.string).toBe('nested hello world');
+    expect(environment.nested.number).toBe(4242);
+    expect(environment.nested.boolean).toBe(false);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@quintal/config/tsconfig/base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["**/*.ts", "vite.config.js"],
+  "exclude": ["node_modules", "dist"]
+}

package/vite.config.js

@@ -0,0 +1 @@
+module.exports = require('@quintal/config/vite');