@wcaservices/config 1.0.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@wcaservices/config",
+  "version": "1.0.0",
+  "description": "",
+  "license": "ISC",
+  "author": "Jørgen Vatle <Jorgen@WcAServices.net> (https://github.com/JorgenVatle)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "scripts": {
+    "test": "vitest",
+    "build": "tsdown",
+    "lint": "tsgo --noEmit"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    "types": "./dist/index.d.mts",
+    "import": "./dist/index.mjs",
+    "require": "./dist/index.cjs",
+    "default": "./dist/index.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "@wcaservices/tsconfig": "^1.0.0",
+    "@wcaservices/tsdown": "^1.0.0",
+    "tsdown": "^0.20.0-beta.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@wcaservices/util": "^2.1.1-beta.0"
+  },
+  "peerDependencies": {
+    "valibot": "^1.2.0"
+  },
+  "peerDependenciesMeta": {
+    "valibot": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/defineEnvironmentVariables.test-d.ts

@@ -0,0 +1,99 @@
+import { expectTypeOf, describe, it } from 'vitest';
+import { defineEnvironmentVariables } from './defineEnvironmentVariables';
+
+describe('Type inference for string types', () => {
+    const env = defineEnvironmentVariables({
+        NON_REQUIRED_ENV_VAR: {},
+        REQUIRED_ENV_VAR: { required: true },
+    });
+    
+    it('Only yields the configured variables', () => {
+        expectTypeOf(env).toMatchTypeOf<{
+            REQUIRED_ENV_VAR: string,
+            NON_REQUIRED_ENV_VAR: string | undefined
+        }>();
+        
+        expectTypeOf(env).not.toMatchTypeOf<{
+            REQUIRED_ENV_VAR: string,
+            NON_REQUIRED_ENV_VAR: string | undefined,
+            UNKNOWN_REQUIRED_ENV_VAR: string,
+            UNKNOWN_NON_REQUIRED_ENV_VAR: string | undefined
+        }>();
+    })
+    
+    it('Should yield string or undefined for non-required variables', () => {
+        expectTypeOf(env.NON_REQUIRED_ENV_VAR).toEqualTypeOf<string | undefined>();
+        expectTypeOf(env.NON_REQUIRED_ENV_VAR).not.toEqualTypeOf<string>();
+    })
+    
+    it(`Should omit 'undefined' type for required variables`, () => {
+        expectTypeOf(env.REQUIRED_ENV_VAR).toEqualTypeOf<string>();
+        expectTypeOf(env.REQUIRED_ENV_VAR).not.toEqualTypeOf<undefined>();
+        expectTypeOf(env.REQUIRED_ENV_VAR).not.toEqualTypeOf<undefined>();
+    });
+})
+
+describe('Type inference for NUMBER types', () => {
+    const env = defineEnvironmentVariables({
+        NON_REQUIRED_ENV_VAR: { type: 'NUMBER' },
+        REQUIRED_ENV_VAR: { type: 'NUMBER', required: true },
+    });
+    
+    it('Only yields the configured variables', () => {
+        expectTypeOf(env).toMatchTypeOf<{
+            REQUIRED_ENV_VAR: number,
+            NON_REQUIRED_ENV_VAR: number | undefined
+        }>();
+        
+        expectTypeOf(env).not.toMatchTypeOf<{
+            REQUIRED_ENV_VAR: number,
+            NON_REQUIRED_ENV_VAR: number | undefined,
+            UNKNOWN_REQUIRED_ENV_VAR: number,
+            UNKNOWN_NON_REQUIRED_ENV_VAR: number | undefined
+        }>();
+    })
+    
+    it('Should yield number or undefined for non-required variables', () => {
+        expectTypeOf(env.NON_REQUIRED_ENV_VAR).toEqualTypeOf<number | undefined>();
+        expectTypeOf(env.NON_REQUIRED_ENV_VAR).not.toEqualTypeOf<number>();
+    })
+    
+    it(`Should omit 'undefined' type for required variables`, () => {
+        expectTypeOf(env.REQUIRED_ENV_VAR).toEqualTypeOf<number>();
+        expectTypeOf(env.REQUIRED_ENV_VAR).not.toEqualTypeOf<undefined>();
+        expectTypeOf(env.REQUIRED_ENV_VAR).not.toEqualTypeOf<undefined>();
+    });
+});
+
+
+describe('Type inference for BOOLEAN types', () => {
+    const env = defineEnvironmentVariables({
+        NON_REQUIRED_ENV_VAR: { type: 'BOOLEAN' },
+        REQUIRED_ENV_VAR: { type: 'BOOLEAN', required: true },
+    });
+    
+    it('Only yields the configured variables', () => {
+        expectTypeOf(env).toMatchTypeOf<{
+            REQUIRED_ENV_VAR: boolean,
+            NON_REQUIRED_ENV_VAR: boolean | undefined
+        }>();
+        
+        expectTypeOf(env).not.toMatchTypeOf<{
+            REQUIRED_ENV_VAR: boolean,
+            NON_REQUIRED_ENV_VAR: boolean | undefined,
+            UNKNOWN_REQUIRED_ENV_VAR: boolean,
+            UNKNOWN_NON_REQUIRED_ENV_VAR: boolean | undefined
+        }>();
+    })
+    
+    it('Should yield boolean or undefined for non-required variables', () => {
+        expectTypeOf(env.NON_REQUIRED_ENV_VAR).toEqualTypeOf<boolean | undefined>();
+        expectTypeOf(env.NON_REQUIRED_ENV_VAR).not.toEqualTypeOf<boolean>();
+    })
+    
+    it(`Should omit 'undefined' type for required variables`, () => {
+        expectTypeOf(env.REQUIRED_ENV_VAR).toEqualTypeOf<boolean>();
+        expectTypeOf(env.REQUIRED_ENV_VAR).not.toEqualTypeOf<undefined>();
+        expectTypeOf(env.REQUIRED_ENV_VAR).not.toEqualTypeOf<undefined>();
+    });
+});

package/src/defineEnvironmentVariables.ts

@@ -0,0 +1,92 @@
+import { envFlag } from '@wcaservices/util/lib';
+
+export function defineEnvironmentVariables<
+    TVariables extends VariableDefinitionMap
+>(variables: TVariables): {
+    [key in keyof TVariables]: VariableOutputType<TVariables[key]>;
+} {
+    const result = {};
+    
+    for (const [key, config] of Object.entries(variables)) {
+        const originalValue = process.env[key] ?? config.default;
+        let value: unknown = originalValue;
+        const cast = config.type ?? 'default';
+        
+        if (config.required && typeof value === 'undefined') {
+            throw new RequiredEnvironmentVariableError(Object.assign({ name: key }, config));
+        }
+        
+        switch (cast) {
+            case 'BOOLEAN':
+                value = envFlag(key);
+                break;
+            case 'NUMBER':
+                value = Number(value);
+                if (Number.isNaN(value)) {
+                    throw new EnvironmentVariableError(`Invalid number type for '${key}': ${originalValue}`);
+                }
+                break;
+            case 'JSON':
+                JSON.parse(String(value));
+                break;
+        }
+        
+        Object.assign(result, { [key]: value });
+    }
+    
+    // @ts-expect-error Type mismatch between result and explicit return type
+    return result;
+}
+
+interface EnvironmentVariableConfig<
+    TRequired extends boolean = boolean,
+    TTypeCast extends keyof VariableTypeCast = keyof VariableTypeCast,
+> {
+    required?: TRequired;
+    type?: TTypeCast;
+    default?: VariableTypeCast[TTypeCast];
+}
+
+type VariableDefinitionMap = {
+    [key in keyof NodeJS.ProcessEnv]: EnvironmentVariableConfig;
+}
+
+type VariableOutputType<
+    TConfig extends EnvironmentVariableConfig,
+    TTypeCast extends keyof VariableTypeCast = TConfig['type'] extends keyof VariableTypeCast
+                                               ? TConfig['type']
+                                               : 'default',
+    TType = VariableTypeCast[TTypeCast]
+> = TConfig['required'] extends true
+    ? TType
+    : TType | undefined;
+
+class EnvironmentVariableError extends Error {}
+
+class RequiredEnvironmentVariableError extends EnvironmentVariableError {
+    constructor(public readonly config: EnvironmentVariableConfig & { name: string }) {
+        super(`Required environment variable "${config.name}" is missing. Make sure one is set before starting the process!`);
+    }
+}
+
+interface VariableTypeCast {
+    /**
+     * Default type for environment variables.
+     */
+    default: string;
+    
+    /**
+     * Boolean flag (1, 0, true, false, yes, no)
+     */
+    BOOLEAN: boolean;
+    
+    /**
+     * Cast inputs to number.
+     */
+    NUMBER: number;
+    
+    /**
+     * Parse input as JSON
+     */
+    JSON: unknown; // todo
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './defineEnvironmentVariables';