@wcaservices/config 1.0.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wcaservices/config",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "",
   "license": "ISC",
   "author": "Jørgen Vatle <Jorgen@WcAServices.net> (https://github.com/JorgenVatle)",

package/src/environment/EnvironmentVariables.ts

@@ -0,0 +1,103 @@
+import { envFlag } from '@wcaservices/util/lib';
+import { EnvironmentVariableError, RequiredEnvironmentVariableError } from './Errors.ts';
+import type { VariableDefinitionMap, VariableOutputType } from './Types.ts';
+
+export class EnvironmentVariables<TVariables extends VariableDefinitionMap> {
+    constructor(protected readonly variables: TVariables) {
+        return new Proxy(this, {
+            get(target, prop, receiver) {
+                if (prop in target) {
+                    return Reflect.get(target, prop, receiver);
+                }
+                return target.getVariable(prop as string);
+            },
+            set(target, prop, value, receiver) {
+                return target.setVariable(prop as string, value);
+            }
+        })
+    }
+    
+    public validate(): void {
+        this.validateRequiredVariables();
+    }
+    
+    protected validateRequiredVariables(): void {
+        Object.entries(this.variables).forEach(([key, config]) => {
+            if (!config.required) {
+                return;
+            }
+            
+            const value = this.getVariable(key);
+            
+            if (typeof value === 'undefined') {
+                throw new RequiredEnvironmentVariableError(Object.assign({ name: key }, config));
+            }
+        })
+    }
+    
+    protected getVariable(key: string): unknown {
+        const config = this.variables[key];
+        
+        if (!config) {
+            throw new EnvironmentVariableError(`No configuration found for environment variable '${key}'`);
+        }
+        
+        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;
+        }
+        
+        if (config.transform) {
+            value = config.transform(value);
+        }
+        
+        return value;
+    }
+    
+    protected setVariable(key: string, value: unknown): boolean {
+        const config = this.variables[key];
+        
+        if (!config) {
+            throw new EnvironmentVariableError(`No configuration found for environment variable '${key}'`);
+        }
+        
+        if (config.transform) {
+            throw new EnvironmentVariableError('Setting environment variables with transform functions is not yet supported.');
+        }
+        
+        switch (config.type) {
+            case 'BOOLEAN':
+            case 'NUMBER':
+            case 'default':
+                process.env[key] = String(value);
+                return true;
+            case 'JSON':
+                process.env[key] = JSON.stringify(value);
+                return true;
+        }
+        
+        throw new EnvironmentVariableError(`Invalid type '${config.type}' for environment variable '${key}'`);
+    }
+}
+
+export type EnvironmentVariablesInstance<TVariables extends VariableDefinitionMap> = EnvironmentVariables<TVariables> & {
+    [key in keyof TVariables]: VariableOutputType<TVariables[key]>;
+}

package/src/environment/Errors.ts

@@ -0,0 +1,10 @@
+import type { EnvironmentVariableConfig } from './Types.ts';
+
+export class EnvironmentVariableError extends Error {
+}
+
+export 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!`);
+    }
+}

package/src/environment/Types.ts

@@ -0,0 +1,50 @@
+export interface EnvironmentVariableConfig<
+    TRequired extends boolean = boolean,
+    TTypeCast extends keyof VariableTypeCast = keyof VariableTypeCast,
+    TTransform = unknown
+> {
+    required?: TRequired;
+    type?: TTypeCast;
+    default?: VariableTypeCast[TTypeCast];
+    transform?: TransformFn<any, TTransform>;
+}
+
+export type VariableDefinitionMap = {
+    [key in keyof NodeJS.ProcessEnv]: EnvironmentVariableConfig;
+}
+export type VariableOutputType<
+    TConfig extends EnvironmentVariableConfig,
+    TTypeCast extends keyof VariableTypeCast = TConfig['type'] extends keyof VariableTypeCast
+                                               ? TConfig['type']
+                                               : 'default',
+    TType = VariableTypeCast[TTypeCast],
+    TCastOutputType = TConfig['required'] extends true
+                      ? TType
+                      : TType | undefined,
+> = TConfig['transform'] extends TransformFn<TCastOutputType, infer TTransformOutput>
+    ? TTransformOutput
+    : TCastOutputType;
+
+type TransformFn<TInput, TOutput> = (value: TInput) => TOutput;
+
+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/{defineEnvironmentVariables.test-d.ts → environment/defineEnvironmentVariables.test-d.ts}

@@ -1,5 +1,5 @@
-import { expectTypeOf, describe, it } from 'vitest';
-import { defineEnvironmentVariables } from './defineEnvironmentVariables';
+import { describe, expectTypeOf, it } from 'vitest';
+import { defineEnvironmentVariables } from './defineEnvironmentVariables.ts';
 
 describe('Type inference for string types', () => {
     const env = defineEnvironmentVariables({
@@ -97,3 +97,66 @@ describe('Type inference for BOOLEAN types', () => {
         expectTypeOf(env.REQUIRED_ENV_VAR).not.toEqualTypeOf<undefined>();
     });
 });
+
+describe('Type inference with transformer functions', () => {
+    const env = defineEnvironmentVariables({
+        EXPLICIT_RETURN_TYPE: {
+            transform: (value): 'yes' | 'no' => value === 'yes' ? 'yes' : 'no',
+        },
+        IMPLICIT_RETURN_TYPE: {
+            transform: (value) => value === 'yes' ? 'yes' as const : 'no' as const,
+        },
+    });
+    
+    it('Can infer types with explicit return types', () => {
+        expectTypeOf(env.EXPLICIT_RETURN_TYPE).toEqualTypeOf<'yes' | 'no'>();
+    });
+    
+    it('Can infer types with implicit return types', () => {
+        expectTypeOf(env.IMPLICIT_RETURN_TYPE).toEqualTypeOf<'yes' | 'no'>();
+    });
+    
+    it.todo('Will infer input types for required variables', () => {
+        const env = defineEnvironmentVariables({
+            IMPLICIT_REQUIRED_ARGUMENT_TYPE: {
+                required: true,
+                transform: (value) => {
+                    // @ts-expect-error TODO: fix transform input type inference
+                    expectTypeOf(value).toEqualTypeOf<string>()
+                    return 'ok' as const;
+                }
+            },
+        });
+        
+        expectTypeOf(env.IMPLICIT_REQUIRED_ARGUMENT_TYPE).toEqualTypeOf<'ok'>();
+    });
+    
+    it.todo('Will infer input types for optional variables', () => {
+        const env = defineEnvironmentVariables({
+            IMPLICIT_OPTIONAL_ARGUMENT_TYPE: {
+                transform: (value) => {
+                    // @ts-expect-error TODO: fix transform input type inference
+                    expectTypeOf(value).toEqualTypeOf<string | undefined>()
+                    return 'ok' as const;
+                }
+            },
+        });
+        
+        expectTypeOf(env.IMPLICIT_OPTIONAL_ARGUMENT_TYPE).toEqualTypeOf<'ok'>();
+    });
+    
+    it('Will allow explicit argument types', () => {
+        const env = defineEnvironmentVariables({
+            EXPLICIT_REQUIRED_ARGUMENT_TYPE: {
+                required: true,
+                transform: (value: string) => 'ok' as const,
+            },
+            EXPLICIT_OPTIONAL_ARGUMENT_TYPE: {
+                transform: (value: string | undefined) => 'ok' as const,
+            },
+        });
+        
+        expectTypeOf(env.EXPLICIT_REQUIRED_ARGUMENT_TYPE).toEqualTypeOf<'ok'>();
+        expectTypeOf(env.EXPLICIT_OPTIONAL_ARGUMENT_TYPE).toEqualTypeOf<'ok'>();
+    })
+})

package/src/environment/defineEnvironmentVariables.test.ts

@@ -0,0 +1,50 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { defineEnvironmentVariables } from './defineEnvironmentVariables.ts';
+import { RequiredEnvironmentVariableError } from './Errors.ts';
+
+const ORIGINAL_ENV = Object.freeze({
+    ...process.env,
+})
+
+describe('Environment variable parsing', () => {
+    beforeEach(() => {
+        process.env = {
+            ...ORIGINAL_ENV,
+            TEST_STRING_HELLO: 'world',
+            TEST_NUMBER_123: '123',
+            TEST_BOOLEAN_TRUE: 'true',
+            TEST_BOOLEAN_FALSE: 'false',
+        };
+    });
+    
+    it('should enforce required environment variables', () => {
+        expect(() => {
+            const env = defineEnvironmentVariables({
+                REQUIRED_ENV_VALUE: {
+                    required: true,
+                }
+            })
+        }).toThrow(RequiredEnvironmentVariableError);
+    });
+    
+    it('should apply transform functions', () => {
+        const transform = (value: boolean) => value ? 'yes' : 'no';
+        
+        const env = defineEnvironmentVariables({
+            TEST_BOOLEAN_TRUE: {
+                type: 'BOOLEAN',
+                required: true,
+                transform,
+            },
+            TEST_BOOLEAN_FALSE: {
+                type: 'BOOLEAN',
+                required: true,
+                transform,
+            }
+        });
+        
+        expect(env.TEST_BOOLEAN_TRUE).toEqual('yes');
+        expect(env.TEST_BOOLEAN_FALSE).toEqual('no');
+    })
+})
+

package/src/environment/defineEnvironmentVariables.ts

@@ -0,0 +1,14 @@
+import { EnvironmentVariables, type EnvironmentVariablesInstance } from './EnvironmentVariables.ts';
+import type { VariableDefinitionMap } from './Types.ts';
+
+export function defineEnvironmentVariables<
+    TVariables extends VariableDefinitionMap
+>(variables: TVariables): EnvironmentVariablesInstance<TVariables> {
+    const instance = new EnvironmentVariables(variables);
+    
+    instance.validate();
+    
+    // @ts-expect-error Type mismatch between result and explicit return type
+    return instance;
+}
+

package/src/environment/index.ts

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

package/src/index.ts

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

package/src/defineEnvironmentVariables.ts

@@ -1,92 +0,0 @@
-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
-}