@edumalin/platform 3.0.0

package/src/environment/type/as-platform-environment-type.spec.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { environmentError } from '../environment.error.js';
+import { asPlatformEnvironmentType } from './as-platform-environment-type.js';
+
+describe('As platform environment type', () => {
+  it('safely casts a string to a platform environment type', () => {
+    // given: a platform environment type string
+    const value = 'development';
+
+    // when: casting the string to a platform environment type
+    const platformEnvironmentType = asPlatformEnvironmentType(value);
+
+    // then: the platform environment type is left untouched
+    expect(platformEnvironmentType).toBe(value);
+  });
+
+  it('throws an error when the string is not a valid platform environment type', () => {
+    // given: an invalid platform environment type string
+    const value = 'a';
+
+    // expect: casting the string to a platform environment type to throw
+    expect(() => asPlatformEnvironmentType(value)).toThrow(environmentError.invalidPlatformEnvironmentType({ value }));
+  });
+});

package/src/environment/type/as-platform-environment-type.ts

@@ -0,0 +1,13 @@
+import { type PlatformEnvironmentType } from './platform-environment-type.js';
+import { validatePlatformEnvironmentType } from './validate-platform-environment-type.js';
+
+/**
+ * Safely casts a value to a platform environment type
+ *
+ * @param value Value
+ * @returns Platform environment type
+ */
+export function asPlatformEnvironmentType(value: unknown): PlatformEnvironmentType {
+  validatePlatformEnvironmentType(value);
+  return value;
+}

package/src/environment/type/is-platform-environment-type.spec.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { isPlatformEnvironmentType } from './is-platform-environment-type.js';
+
+describe('Is platform environment type', () => {
+  it.each([
+    ['development', true],
+    ['dev', false],
+    ['staging', true],
+    ['production', true],
+    ['prod', false],
+  ])('properly determines whether a string is a platform environment type', (value, expectedResult) => {
+    // given: a string
+
+    // when: testing whether the string is a platform environment type
+    const result = isPlatformEnvironmentType(value);
+
+    // expect: true to be returned if it is
+    expect(result).toBe(expectedResult);
+  });
+});

package/src/environment/type/is-platform-environment-type.ts

@@ -0,0 +1,17 @@
+import { type PlatformEnvironmentType } from './platform-environment-type.js';
+import { platformEnvironmentTypes } from './platform-environment-types.js';
+
+/**
+ * Tests whether a value is a platform environment type
+ *
+ * @param value Value
+ * @returns true if the value is a platform environment type
+ */
+export function isPlatformEnvironmentType(value: unknown): value is PlatformEnvironmentType {
+  return typeof value === 'string' && set.has(value);
+}
+
+/**
+ * Set of possible values
+ */
+const set: ReadonlySet<string> = new Set(platformEnvironmentTypes);

package/src/environment/type/platform-environment-type.ts

@@ -0,0 +1,6 @@
+import { type platformEnvironmentTypes } from './platform-environment-types.js';
+
+/**
+ * Platform environment type
+ */
+export type PlatformEnvironmentType = (typeof platformEnvironmentTypes)[number];

package/src/environment/type/platform-environment-types.ts

@@ -0,0 +1,4 @@
+/**
+ * Platform environment types
+ */
+export const platformEnvironmentTypes = ['development', 'local', 'production', 'staging'] as const;

package/src/environment/type/validate-platform-environment-type.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { type PlatformEnvironmentType } from './platform-environment-type.js';
+import { validatePlatformEnvironmentType } from './validate-platform-environment-type.js';
+
+describe('Validate platform environment type', () => {
+  it('throws an error when an invalid string is passed', () => {
+    // given: an invalid platform environment type string
+    const value = 'dev';
+
+    // expect: validating the string to throw
+    expect(() => validatePlatformEnvironmentType(value)).toThrow(
+      `@edumalin/platform:error:invalidPlatformEnvironmentType`
+    );
+  });
+
+  it.each(['development', 'staging', 'production'])('does not throw an error when a valid string is passed', value => {
+    // given: a valid platform environment type string
+
+    // expect: validating the string not to throw
+    expect(() => validatePlatformEnvironmentType(value)).not.toThrow();
+  });
+
+  it('asserts the type of the parameter', () => {
+    // given: a platform environment type string
+    // oxlint-disable-next-line @typescript-eslint/no-inferrable-types
+    const value: string = 'development';
+
+    // when: validating the string
+    validatePlatformEnvironmentType(value);
+
+    // expect: its type to have been asserted
+    expectTypeOf(value).toEqualTypeOf<PlatformEnvironmentType>();
+  });
+});

package/src/environment/type/validate-platform-environment-type.ts

@@ -0,0 +1,14 @@
+import { environmentError } from '../environment.error.js';
+import { isPlatformEnvironmentType } from './is-platform-environment-type.js';
+import { type PlatformEnvironmentType } from './platform-environment-type.js';
+
+/**
+ * Validates that a value is a valid platform environment type
+ *
+ * @param value Value
+ */
+export function validatePlatformEnvironmentType(value: unknown): asserts value is PlatformEnvironmentType {
+  if (!isPlatformEnvironmentType(value)) {
+    throw environmentError.invalidPlatformEnvironmentType({ value });
+  }
+}

package/src/environment/variable/definition/environment-variable-definition-to-resolver.ts

@@ -0,0 +1,28 @@
+import { identity } from '@edumalin/platform/functional';
+
+import { type EnvironmentVariableDefinition } from './environment-variable-definition.js';
+import { type EnvironmentVariableResolver } from './environment-variable-resolver.js';
+
+/**
+ * Returns an environment variable resolver, given a definition
+ *
+ * @param environmentVariableDefinition Environment variable definition
+ * @returns Environment variable resolver
+ * @template T Variable type
+ * @template Optional Whether the variable is optional
+ */
+export function environmentVariableDefinitionToResolver<T, Optional extends boolean>(
+  environmentVariableDefinition: EnvironmentVariableDefinition<T, Optional>
+): EnvironmentVariableResolver<T> {
+  const { defaultValue, description, optional = false, parse = identity } = environmentVariableDefinition;
+
+  return (variableValue, name) => {
+    const value = variableValue !== undefined ? parse(variableValue) : defaultValue;
+
+    if (value === undefined && !optional) {
+      throw new Error(`missing environment variable "${name}" (${description})`);
+    }
+
+    return value as T;
+  };
+}

package/src/environment/variable/definition/environment-variable-definition-type.ts

@@ -0,0 +1,10 @@
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EnvironmentVariableDefinition } from './environment-variable-definition.js';
+
+/**
+ * Environment variable definition type
+ */
+export type EnvironmentVariableDefinitionType<
+  T extends ReadonlyRecord<string, EnvironmentVariableDefinition<unknown, boolean>>,
+> = T extends ReadonlyRecord<string, infer DefinitionType> ? DefinitionType : never;

package/src/environment/variable/definition/environment-variable-definition.ts

@@ -0,0 +1,28 @@
+/**
+ * Environment variable definition
+ *
+ * @template T Variable type
+ * @template Optional Whether the variable is optional
+ */
+export interface EnvironmentVariableDefinition<T = string, Optional extends boolean = false> {
+  /**
+   * Default value
+   */
+  readonly defaultValue?: T;
+  /**
+   * Environment variable description
+   */
+  readonly description: string;
+  /**
+   * Variable name
+   */
+  readonly name: string;
+  /**
+   * Whether the environment variable is optional
+   */
+  readonly optional?: Optional;
+  /**
+   * A parser that specializes the environment variable
+   */
+  readonly parse?: (variableValue: string) => T;
+}

package/src/environment/variable/definition/environment-variable-definitions-to-resolvers.ts

@@ -0,0 +1,22 @@
+import { objectToEntries } from '@edumalin/platform/functional';
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EnvironmentVariableDefinition } from './environment-variable-definition.js';
+import { environmentVariableDefinitionToResolver } from './environment-variable-definition-to-resolver.js';
+import { type EnvironmentVariableEntry } from './environment-variable-entry.js';
+
+/**
+ * Returns a list of resolvers, given environment variable definitions
+ *
+ * @param definitions  environment variable definitions
+ * @returns List of resolvers
+ * @template VariableDefinitions Variable definitions type
+ */
+export function environmentVariableDefinitionsToResolvers<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<unknown, boolean>>,
+>(definitions: VariableDefinitions): ReadonlyArray<EnvironmentVariableEntry<VariableDefinitions>> {
+  return objectToEntries(definitions).map(([propertyKey, variableDefinition]) => {
+    const variableResolver = environmentVariableDefinitionToResolver(variableDefinition);
+    return [propertyKey, variableDefinition, variableResolver] as const;
+  }) as unknown as ReadonlyArray<EnvironmentVariableEntry<VariableDefinitions>>;
+}

package/src/environment/variable/definition/environment-variable-entries-to-object.ts

@@ -0,0 +1,37 @@
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EnvironmentVariables } from '../environment-variables.js';
+import { type EnvironmentVariableDefinition } from './environment-variable-definition.js';
+import { type EnvironmentVariableDefinitionType } from './environment-variable-definition-type.js';
+import { type EnvironmentVariableEntry } from './environment-variable-entry.js';
+
+/**
+ * Creates a function that reduces environment variable entries to an environment variable object
+ *
+ * @param environmentVariables Environment variables
+ * @param variableNameResolver Variable name resolver
+ * @returns Function that reduces environment variable entries to an environment variable object
+ * @template VariableDefinitions Variable definitions type
+ */
+export function environmentVariableEntriesToObject<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<unknown, boolean>>,
+>(
+  environmentVariables: EnvironmentVariables,
+  variableNameResolver: (
+    definition: EnvironmentVariableDefinitionType<VariableDefinitions>,
+    propertyKey: keyof VariableDefinitions
+  ) => string
+): (
+  obj: ReadonlyRecord<keyof VariableDefinitions, unknown>,
+  environmentVariableEntry: EnvironmentVariableEntry<VariableDefinitions>
+) => ReadonlyRecord<keyof VariableDefinitions, unknown> {
+  return (obj, [propertyKey, definition, resolver]) => {
+    const variableName = variableNameResolver(definition, propertyKey);
+    const variableString = environmentVariables[variableName];
+    const propertyValue = resolver(variableString, variableName);
+    return {
+      ...obj,
+      [propertyKey]: propertyValue,
+    };
+  };
+}

package/src/environment/variable/definition/environment-variable-entry.ts

@@ -0,0 +1,18 @@
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EnvironmentVariableDefinition } from './environment-variable-definition.js';
+import { type EnvironmentVariableDefinitionType } from './environment-variable-definition-type.js';
+import { type EnvironmentVariableResolver } from './environment-variable-resolver.js';
+
+/**
+ * Environment variable entry
+ *
+ * @template VariableDefinitions Variable definitions type
+ */
+export type EnvironmentVariableEntry<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<unknown, boolean>>,
+> = readonly [
+  propertyKey: keyof VariableDefinitions,
+  variableDefinition: EnvironmentVariableDefinitionType<VariableDefinitions>,
+  resolver: EnvironmentVariableResolver<unknown>,
+];

package/src/environment/variable/definition/environment-variable-object-property-type.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import { type EnvironmentVariableObjectPropertyType } from './environment-variable-object-property-type.js';
+
+describe('Environment variable object property type', () => {
+  it('can extract a type from an environment variable definition with a parser', () => {
+    // given: an environment variable definition with a parser
+    // oxlint-disable-next-line @typescript-eslint/no-unused-vars
+    const environmentVariableDefinition = {
+      description: 'Test description',
+      name: 'Test name',
+      parse: (value: string) => new URL(value),
+    } as const;
+
+    // when: extracting the type from the environment variable definition
+    type ObjectProperty = EnvironmentVariableObjectPropertyType<typeof environmentVariableDefinition>;
+
+    // expect: a type to be extract from an environment variable definition
+    expectTypeOf<ObjectProperty>().toEqualTypeOf<URL>();
+  });
+
+  it('extracts a type from an environment variable definition without a parser', () => {
+    // given: an environment variable definition without a parser
+    // oxlint-disable-next-line @typescript-eslint/no-unused-vars
+    const environmentVariableDefinition = {
+      description: 'Test description',
+      name: 'Test name',
+    } as const;
+
+    // when: extracting the type from the environment variable definition
+    type ObjectProperty = EnvironmentVariableObjectPropertyType<typeof environmentVariableDefinition>;
+
+    // expect: a type to be extract from an environment variable definition
+    expectTypeOf<ObjectProperty>().toEqualTypeOf<string>();
+  });
+});

package/src/environment/variable/definition/environment-variable-object-property-type.ts

@@ -0,0 +1,8 @@
+import { type EnvironmentVariableDefinition } from './environment-variable-definition.js';
+
+/**
+ * Environment variable definition property type
+ */
+export type EnvironmentVariableObjectPropertyType<
+  VariableDefinition extends EnvironmentVariableDefinition<any, boolean>,
+> = VariableDefinition extends { readonly parse: (variableValue: string) => infer T } ? T : string;

package/src/environment/variable/definition/environment-variable-object-property.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import { type EnvironmentVariableObjectProperty } from './environment-variable-object-property.js';
+
+describe('Environment variable object property', () => {
+  it('can extract a type from an environment variable definition with a parser', () => {
+    // given: an environment variable definition with a parser
+    // oxlint-disable-next-line @typescript-eslint/no-unused-vars
+    const environmentVariableDefinition = {
+      description: 'Test description',
+      name: 'Test name',
+      parse: (value: string) => new URL(value),
+    } as const;
+
+    // when: extracting the type from the environment variable definition
+    type ObjectProperty = EnvironmentVariableObjectProperty<typeof environmentVariableDefinition>;
+
+    // expect: a type to be extract from an environment variable definition
+    expectTypeOf<ObjectProperty>().toEqualTypeOf<URL>();
+  });
+
+  it('extracts a type from an environment variable definition without a parser', () => {
+    // given: an environment variable definition without a parser
+    // oxlint-disable-next-line @typescript-eslint/no-unused-vars
+    const environmentVariableDefinition = {
+      description: 'Test description',
+      name: 'Test name',
+    } as const;
+
+    // when: extracting the type from the environment variable definition
+    type ObjectProperty = EnvironmentVariableObjectProperty<typeof environmentVariableDefinition>;
+
+    // expect: a type to be extract from an environment variable definition
+    expectTypeOf<ObjectProperty>().toEqualTypeOf<string>();
+  });
+});

package/src/environment/variable/definition/environment-variable-object-property.ts

@@ -0,0 +1,13 @@
+import { type EnvironmentVariableDefinition } from './environment-variable-definition.js';
+import { type EnvironmentVariableObjectPropertyType } from './environment-variable-object-property-type.js';
+
+/**
+ * Environment variable object property
+ *
+ * @template VariableDefinition Variable definition type
+ */
+export type EnvironmentVariableObjectProperty<
+  VariableDefinition extends EnvironmentVariableDefinition<unknown, boolean>,
+> = VariableDefinition extends { readonly optional: true }
+  ? EnvironmentVariableObjectPropertyType<VariableDefinition> | undefined
+  : EnvironmentVariableObjectPropertyType<VariableDefinition>;

package/src/environment/variable/definition/environment-variable-object.ts

@@ -0,0 +1,15 @@
+import { type Expand, type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EnvironmentVariableDefinition } from './environment-variable-definition.js';
+import { type EnvironmentVariableObjectProperty } from './environment-variable-object-property.js';
+
+/**
+ * Environment variable object
+ *
+ * @template VariableDefinitions Variable definitions type
+ */
+export type EnvironmentVariableObject<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<unknown, boolean>>,
+> = Expand<{
+  readonly [K in keyof VariableDefinitions]: EnvironmentVariableObjectProperty<VariableDefinitions[K]>;
+}>;

package/src/environment/variable/definition/environment-variable-resolver.ts

@@ -0,0 +1,6 @@
+/**
+ * Environment variable resolver
+ */
+export interface EnvironmentVariableResolver<T> {
+  (value: string | undefined, name: string): T;
+}

package/src/environment/variable/environment-variables-to-platform-environment.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+
+import { type EnvironmentVariables } from './environment-variables.js';
+import { environmentVariablesToPlatformEnvironment } from './environment-variables-to-platform-environment.js';
+
+describe('Environment variables to platform environment', () => {
+  const id = 'test';
+  const name = 'test';
+  const provider = 'local';
+  const region = 'eu-paas';
+  const type = 'development';
+
+  it('can build the platform environment from environment variables', () => {
+    // given: environment variables
+    const environmentVariables: EnvironmentVariables = {
+      EDU_ENV_ID: id,
+      EDU_ENV_NAME: name,
+      EDU_ENV_PROVIDER: provider,
+      EDU_ENV_REGION: region,
+      EDU_ENV_TYPE: type,
+    };
+
+    // when: creating a function that returns the platform environment
+    const func = environmentVariablesToPlatformEnvironment();
+    // and: calling it
+    const platformEnvironment = func(environmentVariables);
+
+    // then: the platform environment information is properly constructed
+    expect(platformEnvironment.id).toBe(id);
+    expect(platformEnvironment.name).toBe(name);
+    expect(platformEnvironment.provider).toBe(provider);
+    expect(platformEnvironment.region).toBe(region);
+    expect(platformEnvironment.type).toBe(type);
+  });
+});

package/src/environment/variable/environment-variables-to-platform-environment.ts

@@ -0,0 +1,43 @@
+import { asPlatformEnvironmentId } from '../id/as-platform-environment-id';
+import { type PlatformEnvironment } from '../platform-environment.js';
+import { asPlatformEnvironmentProvider } from '../provider/as-platform-environment-provider';
+import { asPlatformEnvironmentRegion } from '../region/as-platform-environment-region.js';
+import { asPlatformEnvironmentType } from '../type/as-platform-environment-type.js';
+import { type EnvironmentVariables } from './environment-variables.js';
+import { environmentVariablesToValue } from './environment-variables-to-value.js';
+
+/**
+ * Creates a function that returns the current platform environment, given environment variables
+ *
+ * @returns Function that returns the current platform environment, given environment variables
+ */
+export function environmentVariablesToPlatformEnvironment(): (
+  environmentVariables: EnvironmentVariables
+) => PlatformEnvironment {
+  return environmentVariablesToValue({
+    id: {
+      description: 'Edumalin platform environment identifier',
+      name: 'EDU_ENV_ID',
+      parse: asPlatformEnvironmentId,
+    },
+    name: {
+      description: 'Edumalin platform environment name',
+      name: 'EDU_ENV_NAME',
+    },
+    provider: {
+      description: 'Edumalin platform environment provider',
+      name: 'EDU_ENV_PROVIDER',
+      parse: asPlatformEnvironmentProvider,
+    },
+    region: {
+      description: 'Edumalin platform environment region',
+      name: 'EDU_ENV_REGION',
+      parse: asPlatformEnvironmentRegion,
+    },
+    type: {
+      description: 'Edumalin platform environment type',
+      name: 'EDU_ENV_TYPE',
+      parse: asPlatformEnvironmentType,
+    },
+  });
+}

package/src/environment/variable/environment-variables-to-value.spec.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+
+import { type EnvironmentVariables } from './environment-variables.js';
+import { environmentVariablesToValue } from './environment-variables-to-value.js';
+
+describe('Environment variables to value', () => {
+  it('builds an object from environment variables', () => {
+    // given: environment variables
+    const testName1 = 'TEST_NAME_1';
+    const testValue1 = 'test-variable-1';
+    const testName2 = 'TEST_NAME_2';
+    const testValue2 = 'test-variable-2';
+    const environmentVariables: EnvironmentVariables = {
+      [testName1]: testValue1,
+      [testName2]: testValue2,
+    };
+
+    // when: creating a function that maps environment variables to a value
+    const func = environmentVariablesToValue({
+      testProp1: {
+        description: 'Test name 1',
+        name: testName1,
+      },
+      testProp2: {
+        description: 'Test name 2',
+        name: testName2,
+      },
+    });
+    // and: calling it
+    const result = func(environmentVariables);
+
+    // then: the environment variables have been used to build a new object
+    expect(result.testProp1).toBe(testValue1);
+    expect(result.testProp2).toBe(testValue2);
+  });
+
+  it('throws an error if an environment variable is missing', () => {
+    // given: environment variables
+    const environmentVariables: EnvironmentVariables = {};
+    // and: an environment variable name that is not defined
+    const name = 'test-name';
+    const description = 'Test name';
+
+    // when: creating a function that maps environment variables to a value
+    const func = environmentVariablesToValue({
+      test: {
+        description,
+        name,
+      },
+    });
+
+    // expect: an error to be thrown when calling it with missing environment variables
+    expect(() => func(environmentVariables)).toThrow(`missing environment variable "${name}" (${description})`);
+  });
+});

package/src/environment/variable/environment-variables-to-value.ts

@@ -0,0 +1,29 @@
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EnvironmentVariableDefinition } from './definition/environment-variable-definition.js';
+import { environmentVariableDefinitionsToResolvers } from './definition/environment-variable-definitions-to-resolvers.js';
+import { environmentVariableEntriesToObject } from './definition/environment-variable-entries-to-object.js';
+import { type EnvironmentVariableObject } from './definition/environment-variable-object.js';
+import { type EnvironmentVariables } from './environment-variables.js';
+
+/**
+ * Creates a function that returns a value, given environment variables
+ *
+ * @param definitions Environment variable definitions
+ * @returns Function that returns a value, given environment variables
+ * @template VariableDefinitions Environment variable definitions
+ */
+export function environmentVariablesToValue<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<any, boolean>>,
+>(
+  definitions: VariableDefinitions
+): (environmentVariables: EnvironmentVariables) => EnvironmentVariableObject<VariableDefinitions> {
+  return environmentVariables => {
+    const variableResolvers = environmentVariableDefinitionsToResolvers(definitions);
+    const object = variableResolvers.reduce(
+      environmentVariableEntriesToObject<VariableDefinitions>(environmentVariables, definition => definition.name),
+      {} as ReadonlyRecord<keyof VariableDefinitions, any>
+    );
+    return object as EnvironmentVariableObject<VariableDefinitions>;
+  };
+}