@edumalin/platform 3.0.0

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

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+
+import { type EnvironmentVariables } from './environment-variables.js';
+import { environmentVariablesToValues } from './environment-variables-to-values.js';
+
+describe('Environment variables to values', () => {
+  it('builds a list of values from environment variables', () => {
+    // given: environment variables
+    const environmentVariables: EnvironmentVariables = {
+      PREFIX_0_A: 'a0',
+      PREFIX_0_B: 'b0',
+      PREFIX_1_A: 'a1',
+      PREFIX_1_B: 'b1',
+    };
+
+    // when: creating a function that builds values from environment variables
+    const func = environmentVariablesToValues({
+      prefix: 'PREFIX',
+      definitions: {
+        a: {
+          description: 'Variable A',
+          name: 'A',
+        },
+        b: {
+          description: 'Variable B',
+          name: 'B',
+        },
+      },
+    });
+    // and: calling it
+    const variables = func(environmentVariables);
+
+    // then: the correct number of objects is returned
+    expect(variables.length).toBe(2);
+    // and: the objects to have the correct properties
+    const object1 = variables[0];
+    expect(object1).toBeDefined();
+    expect(object1?.a).toBe('a0');
+    expect(object1?.b).toBe('b0');
+    const object2 = variables[1];
+    expect(object2).toBeDefined();
+    expect(object2?.a).toBe('a1');
+    expect(object2?.b).toBe('b1');
+  });
+
+  it('builds a map of objects from environment variables when given a projection function', () => {
+    // given: environment variables
+    const environmentVariables: EnvironmentVariables = {
+      PREFIX_0_A: 'a0',
+      PREFIX_0_B: 'b0',
+      PREFIX_1_A: 'a1',
+      PREFIX_1_B: 'b1',
+    };
+
+    // when: creating a function that builds values from environment variables
+    const func = environmentVariablesToValues(
+      {
+        prefix: 'PREFIX',
+        definitions: {
+          a: {
+            description: 'Variable A',
+            name: 'A',
+          },
+          b: {
+            description: 'Variable B',
+            name: 'B',
+          },
+        },
+      },
+      definition => [definition.a, definition]
+    );
+    // and: calling it
+    const variables = func(environmentVariables);
+
+    // then: the correct number of objects is returned
+    expect(variables.size).toBe(2);
+    // and: the objects to have the correct properties
+    const object1 = variables.get('a0');
+    expect(object1).toBeDefined();
+    expect(object1?.a).toBe('a0');
+    expect(object1?.b).toBe('b0');
+    const object2 = variables.get('a1');
+    expect(object2).toBeDefined();
+    expect(object2?.a).toBe('a1');
+    expect(object2?.b).toBe('b1');
+  });
+});

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

@@ -0,0 +1,63 @@
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EnvironmentVariableDefinition } from './definition/environment-variable-definition.js';
+import { type EnvironmentVariableObject } from './definition/environment-variable-object.js';
+import { type EnvironmentVariables } from './environment-variables.js';
+import { getIndexedEnvironmentVariablesCount } from './indexed/get-indexed-environment-variables-count.js';
+import { indexToIndexedEnvironmentVariables } from './indexed/index-to-indexed-environment-variables.js';
+import { type IndexedEnvironmentVariableDefinitions } from './indexed/indexed-environment-variable-definitions.js';
+
+/**
+ * Creates a function that returns a list of indexed environment variables
+ *
+ * @param definitions Indexed environment variable definitions
+ * @returns Function that returns a list of indexed environment variables
+ * @template VariableDefinitions Environment variable definitions
+ */
+export function environmentVariablesToValues<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<unknown, boolean>>,
+>(
+  definitions: IndexedEnvironmentVariableDefinitions<VariableDefinitions>
+): (environmentVariables: EnvironmentVariables) => ReadonlyArray<EnvironmentVariableObject<VariableDefinitions>>;
+
+/**
+ * Creates a function that returns a map of indexed environment variables
+ *
+ * @param definitions Indexed environment variable definitions
+ * @param project Projection function
+ * @returns Function that returns a map of indexed environment variables
+ * @template VariableDefinitions Environment variable definitions
+ * @template KeyType Key type
+ * @template ValueType Value type
+ */
+export function environmentVariablesToValues<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<unknown, boolean>>,
+  KeyType,
+  ValueType,
+>(
+  definitions: IndexedEnvironmentVariableDefinitions<VariableDefinitions>,
+  project: (variableObject: EnvironmentVariableObject<VariableDefinitions>) => readonly [key: KeyType, value: ValueType]
+): (environmentVariables: EnvironmentVariables) => ReadonlyMap<KeyType, ValueType>;
+
+export function environmentVariablesToValues<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<unknown, boolean>>,
+  KeyType,
+  ValueType,
+>(
+  definitions: IndexedEnvironmentVariableDefinitions<VariableDefinitions>,
+  project?: (
+    variableObject: EnvironmentVariableObject<VariableDefinitions>
+  ) => readonly [key: KeyType, value: ValueType]
+): (
+  environmentVariables: EnvironmentVariables
+) => ReadonlyArray<EnvironmentVariableObject<VariableDefinitions>> | ReadonlyMap<KeyType, ValueType> {
+  return environmentVariables => {
+    const length = getIndexedEnvironmentVariablesCount(environmentVariables, definitions);
+    const toEnvironmentVariables = indexToIndexedEnvironmentVariables(environmentVariables, definitions);
+    const variableDefinitions = Array.from({ length })
+      .map((_, index) => index)
+      .map(toEnvironmentVariables);
+
+    return project !== undefined ? new Map(variableDefinitions.map(project)) : variableDefinitions;
+  };
+}

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

@@ -0,0 +1,6 @@
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+/**
+ * Environment variables
+ */
+export type EnvironmentVariables = ReadonlyRecord<string, string | undefined>;

package/src/environment/variable/indexed/get-indexed-environment-variables-count.spec.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+
+import { type EnvironmentVariables } from '../environment-variables.js';
+import { getIndexedEnvironmentVariablesCount } from './get-indexed-environment-variables-count.js';
+
+describe('Get indexed enviroment variables count', () => {
+  it('can return the number of indexed environment variables', () => {
+    // given: indexed environment variables
+    const environmentVariables: EnvironmentVariables = {
+      PREFIX_0_A: 'a0',
+      PREFIX_0_B: 'b0',
+      PREFIX_1_A: 'a1',
+      PREFIX_1_B: 'b1',
+    };
+
+    // when: getting the number of indexed environment variables
+    const count = getIndexedEnvironmentVariablesCount(environmentVariables, {
+      prefix: 'PREFIX',
+      definitions: {
+        a: {
+          description: 'Variable A',
+          name: 'A',
+        },
+        b: {
+          description: 'Variable B',
+          name: 'B',
+        },
+      },
+    });
+
+    // expect: the correct indexed environment variable count to be returned
+    expect(count).toBe(2);
+  });
+
+  it('returns 0 if no matching environment variables are found', () => {
+    // given: indexed environment variables
+    const environmentVariables: EnvironmentVariables = {
+      PREFIX_A: 'a0',
+    };
+
+    // when: getting the number of indexed environment variables
+    const count = getIndexedEnvironmentVariablesCount(environmentVariables, {
+      prefix: 'PREFIX',
+      definitions: {
+        a: {
+          description: 'Variable A',
+          name: 'A',
+        },
+      },
+    });
+
+    // expect: 0 to have been returned
+    expect(count).toBe(0);
+  });
+
+  it('ignores missing optional variables', () => {
+    // given: indexed environment variables
+    const environmentVariables: EnvironmentVariables = {
+      PREFIX_0_A: 'a0',
+      PREFIX_0_B: 'b0',
+      PREFIX_1_A: 'a1',
+    };
+
+    // when: getting the number of indexed environment variables
+    const count = getIndexedEnvironmentVariablesCount(environmentVariables, {
+      prefix: 'PREFIX',
+      definitions: {
+        a: {
+          description: 'Variable A',
+          name: 'A',
+        },
+        b: {
+          description: 'Variable B',
+          name: 'B',
+          optional: true,
+        },
+      },
+    });
+
+    // expect: the correct indexed environment variable count to be returned
+    expect(count).toBe(2);
+  });
+
+  it('stops at the first incomplete group', () => {
+    // given: indexed environment variables
+    const environmentVariables: EnvironmentVariables = {
+      PREFIX_0_A: 'a0',
+      PREFIX_0_B: 'b0',
+      PREFIX_0_C: 'c0',
+      PREFIX_1_A: 'a1',
+      PREFIX_1_C: 'c1',
+      PREFIX_2_A: 'a2',
+      PREFIX_2_B: 'b2',
+    };
+
+    // when: getting the number of indexed environment variables
+    const count = getIndexedEnvironmentVariablesCount(environmentVariables, {
+      prefix: 'PREFIX',
+      definitions: {
+        a: {
+          description: 'Variable A',
+          name: 'A',
+        },
+        b: {
+          description: 'Variable B',
+          name: 'B',
+        },
+        c: {
+          description: 'Variable C',
+          name: 'C',
+          optional: true,
+        },
+      },
+    });
+
+    // expect: the correct indexed environment variable count to be returned
+    expect(count).toBe(1);
+  });
+});

package/src/environment/variable/indexed/get-indexed-environment-variables-count.ts

@@ -0,0 +1,41 @@
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EnvironmentVariableDefinition } from '../definition/environment-variable-definition.js';
+import { type EnvironmentVariables } from '../environment-variables.js';
+import { type IndexedEnvironmentVariableDefinitions } from './indexed-environment-variable-definitions.js';
+
+/**
+ * Returns the number of indices available for a group of indexed environment variables
+ *
+ * @param environmentVariables Environment variables
+ * @param variableDefinitions Indexed environment variable definitions
+ * @returns Number of indices
+ * @template VariableDefinitions Indexed environment variable definitions
+ */
+export function getIndexedEnvironmentVariablesCount<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<any, boolean>>,
+>(
+  environmentVariables: EnvironmentVariables,
+  variableDefinitions: IndexedEnvironmentVariableDefinitions<VariableDefinitions>
+): number {
+  const { definitions, prefix } = variableDefinitions;
+  const requiredSuffixes = Object.values(definitions)
+    .filter(({ optional }) => optional !== true)
+    .map(({ name }) => name);
+
+  let count = 0;
+  let validIteration = false;
+
+  do {
+    const countString = count.toString();
+    const baseVariableName = `${prefix}_${countString}_`;
+    const variableNames = requiredSuffixes.map(suffix => baseVariableName + suffix);
+
+    validIteration = variableNames.every(variableName => environmentVariables[variableName] !== undefined);
+    if (validIteration) {
+      ++count;
+    }
+  } while (validIteration);
+
+  return count;
+}

package/src/environment/variable/indexed/index-to-indexed-environment-variables.spec.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+
+import { type EnvironmentVariables } from '../environment-variables.js';
+import { indexToIndexedEnvironmentVariables } from './index-to-indexed-environment-variables.js';
+
+describe('Index to indexed environment variables', () => {
+  it('returns an environment variable object, given an index', () => {
+    // given: environment variables
+    const environmentVariables: EnvironmentVariables = {
+      PREFIX_0_A: 'a0',
+      PREFIX_0_B: 'b0',
+      PREFIX_1_A: 'a1',
+      PREFIX_1_B: 'b1',
+    };
+    // and: an index
+    const index = 0;
+
+    // when: creating a function that returns an object from an index
+    const func = indexToIndexedEnvironmentVariables(environmentVariables, {
+      prefix: 'PREFIX',
+      definitions: {
+        a: {
+          description: 'Variable A',
+          name: 'A',
+        },
+        b: {
+          description: 'Variable B',
+          name: 'B',
+        },
+      },
+    });
+
+    // when: getting an environment variable object
+    const object = func(index);
+
+    // then: an object matching the index is returned
+    expect(object.a).toBe('a0');
+    expect(object.b).toBe('b0');
+  });
+});

package/src/environment/variable/indexed/index-to-indexed-environment-variables.ts

@@ -0,0 +1,39 @@
+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';
+import { type IndexedEnvironmentVariableDefinitions } from './indexed-environment-variable-definitions.js';
+
+/**
+ * Creates a function that returns indexed environment variables for a specific index
+ *
+ * @param environmentVariables Environment variables
+ * @param variableDefinitions Environment variable definitions
+ * @returns Function that returns indexed environment variables for a specific index
+ * @template VariableDefinitions Environment variable definitions
+ */
+export function indexToIndexedEnvironmentVariables<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<any, boolean>>,
+>(
+  environmentVariables: EnvironmentVariables,
+  variableDefinitions: IndexedEnvironmentVariableDefinitions<VariableDefinitions>
+): (index: number) => EnvironmentVariableObject<VariableDefinitions> {
+  const { definitions } = variableDefinitions;
+  const variableResolvers = environmentVariableDefinitionsToResolvers(definitions);
+
+  return index => {
+    const indexString = index.toString();
+    const prefix = `${variableDefinitions.prefix}_${indexString}_`;
+    const object = variableResolvers.reduce(
+      environmentVariableEntriesToObject<VariableDefinitions>(
+        environmentVariables,
+        definition => prefix + definition.name
+      ),
+      {} as Record<keyof VariableDefinitions, unknown>
+    );
+    return object as EnvironmentVariableObject<VariableDefinitions>;
+  };
+}

package/src/environment/variable/indexed/indexed-environment-variable-definitions.ts

@@ -0,0 +1,21 @@
+import { type ReadonlyRecord } from '@edumalin/platform/typescript';
+
+import { type EnvironmentVariableDefinition } from '../definition/environment-variable-definition.js';
+
+/**
+ * Indexed environment variable definitions
+ *
+ * @template VariableDefinitions Variable definitions
+ */
+export interface IndexedEnvironmentVariableDefinitions<
+  VariableDefinitions extends ReadonlyRecord<string, EnvironmentVariableDefinition<any, boolean>>,
+> {
+  /**
+   * Variable definitions
+   */
+  readonly definitions: VariableDefinitions;
+  /**
+   * Prefix for all environment variable names
+   */
+  readonly prefix: string;
+}

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

@@ -0,0 +1,22 @@
+import { type PlatformEnvironment } from '../platform-environment.js';
+import { type EnvironmentVariables } from './environment-variables.js';
+
+/**
+ * Returns environments variables, given a platform environment
+ *
+ * @param platformEnvironment Platform environment
+ * @returns Environment variables
+ */
+export function platformEnvironmentToEnvironmentVariables(
+  platformEnvironment: PlatformEnvironment
+): EnvironmentVariables {
+  const { id, name, provider, region, type } = platformEnvironment;
+
+  return {
+    EDU_ENV_ID: id,
+    EDU_ENV_NAME: name,
+    EDU_ENV_PROVIDER: provider,
+    EDU_ENV_REGION: region,
+    EDU_ENV_TYPE: type,
+  };
+}

package/src/error/creator/error-creator.ts

@@ -0,0 +1,14 @@
+import { type TypeCreator } from '@edumalin/platform/typescript';
+
+/**
+ * Error creator
+ *
+ * @template ErrorCode Error code
+ * @template TypeCreatorType Type creator type
+ */
+export type ErrorCreator<ErrorCode extends string, TypeCreatorType extends TypeCreator<any, any>> = {
+  /**
+   * Error code
+   */
+  readonly code: ErrorCode;
+} & TypeCreatorType;

package/src/error/creator/error-from-creator.ts

@@ -0,0 +1,10 @@
+import { type TypeCreator } from '@edumalin/platform/typescript';
+
+import { type ErrorCreator } from './error-creator.js';
+
+/**
+ * Error from a creator type
+ *
+ * @template CreatorType Creator type
+ */
+export type ErrorFromCreator<CreatorType extends ErrorCreator<string, TypeCreator<any, any>>> = ReturnType<CreatorType>;

package/src/error/index.ts

@@ -0,0 +1,14 @@
+export { catchPlatformError } from './operator/catch-platform-error.js';
+export { createErrorType } from './type/create-error-type.js';
+export { type ErrorFromType } from './type/error-from-type.js';
+export { type ErrorType } from './type/error-type.js';
+export { errorProperties } from './properties/error-properties.js';
+export { type ErrorPropertiesFromErrorDefinitions } from './properties/error-properties-from-error-definitions.js';
+export { type ErrorPropertiesSchema } from './properties/error-properties-schema.js';
+export { isErrorOfType } from './is-error-of-type.js';
+export { isError } from './is-error.js';
+export { isPlatformError } from './is-platform-error.js';
+export { mapPlatformError } from './operator/map-platform-error.js';
+export { type PlatformError } from './platform-error.js';
+export { PlatformErrorInstance } from './platform-error-instance.js';
+export { platformErrorToPlatformErrorInstance } from './platform-error-to-platform-error-instance.js';

package/src/error/is-error-of-type.spec.ts

@@ -0,0 +1,8 @@
+import { describe, it } from 'vitest';
+
+//import { isErrorOfType } from './is-error-of-type.js';
+
+describe('Is error of type', () => {
+  //isErrorOfType;
+  it.todo('works');
+});

package/src/error/is-error-of-type.ts

@@ -0,0 +1,54 @@
+import { type TypeCreator } from '@edumalin/platform/typescript';
+
+import { type ErrorCreator } from './creator/error-creator.js';
+import { type ErrorFromCreator } from './creator/error-from-creator.js';
+import { isPlatformError } from './is-platform-error.js';
+import { type ErrorFromType } from './type/error-from-type.js';
+import { type ErrorType as GenericErrorType } from './type/error-type.js';
+
+/**
+ * Creates a function that tests whether an error is of a specific type
+ *
+ * @param errorType Error type
+ * @returns Function that tests whether an error is of a specific type
+ * @template ErrorType Error type
+ */
+export function isErrorOfType<ErrorType extends GenericErrorType>(
+  errorType: ErrorType
+): (error: unknown) => error is ErrorFromType<ErrorType>;
+
+/**
+ * Creates a function that tests whether an error is of a specific type and code
+ *
+ * @param errorType Error type
+ * @returns Function that tests whether an error is of a specific type and code
+ * @template ErrorCreatorType Error creator type
+ */
+export function isErrorOfType<ErrorCreatorType extends ErrorCreator<string, TypeCreator<any, any>>>(
+  errorType: ErrorCreatorType
+): (error: unknown) => error is ErrorFromCreator<ErrorCreatorType>;
+
+export function isErrorOfType<
+  ErrorTypeOrCreatorType extends GenericErrorType | ErrorCreator<string, TypeCreator<any, any>>,
+>(errorType: ErrorTypeOrCreatorType): (error: unknown) => boolean {
+  if ('code' in errorType) {
+    const { code } = errorType;
+    // TODO: include domain
+    return error => isPlatformError(error) && error.code === code;
+  } else {
+    return error => {
+      if (!isPlatformError(error)) {
+        return false;
+      }
+
+      // TODO:
+      // this doesn't check for collisions with similar error codes across types/domains
+      // keep the domain as an internal symbol in the error type?
+      // keep the type as an internal symbol in the error instance?
+      // (keeping the type directly on the error instance can cause cyclic issues)
+      // support expected code(s) as an optional param?
+      const { code } = error;
+      return code in errorType;
+    };
+  }
+}

package/src/error/is-error.spec.ts

@@ -0,0 +1,8 @@
+import { describe, it } from 'vitest';
+
+//import { isError } from './is-error.js';
+
+describe('Is error', () => {
+  //isError;
+  it.todo('works');
+});

package/src/error/is-error.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests whether a value is an error
+ *
+ * @param value Value
+ * @returns true if the value is an error
+ */
+export function isError(value: unknown): value is Error {
+  return value instanceof Error;
+}

package/src/error/is-platform-error.ts

@@ -0,0 +1,20 @@
+import { type PlatformError } from './platform-error.js';
+
+/**
+ * Tests whether a value is a platform error
+ *
+ * @param value Value
+ * @returns true if the value is an error
+ */
+export function isPlatformError(value: unknown): value is PlatformError {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'domain' in value &&
+    typeof value.domain === 'object' &&
+    value.domain !== null &&
+    'name' in value.domain &&
+    'code' in value &&
+    typeof value.code === 'string'
+  );
+}

package/src/error/operator/catch-platform-error.ts

@@ -0,0 +1,15 @@
+import { type OperatorFunction } from 'rxjs';
+
+import { catchErrorIf } from '@edumalin/platform/reactive';
+
+import { isPlatformError } from '../is-platform-error.js';
+import { type PlatformError } from '../platform-error.js';
+
+/**
+ * Operator function that catches a platform error
+ */
+export function catchPlatformError<InputType, OutputType>(
+  selector: (error: PlatformError) => Observable<OutputType>
+): OperatorFunction<InputType, InputType | OutputType> {
+  return catchErrorIf(isPlatformError, selector);
+}

package/src/error/operator/map-platform-error.ts

@@ -0,0 +1,15 @@
+import { of, type OperatorFunction } from 'rxjs';
+
+import { type PlatformError } from '../platform-error.js';
+import { catchPlatformError } from './catch-platform-error.js';
+
+/**
+ * Operator function that maps a caught platform error to a value
+ *
+ * @param project Projection function
+ */
+export function mapPlatformError<InputType, OutputType>(
+  project: (error: PlatformError) => OutputType
+): OperatorFunction<InputType, InputType | OutputType> {
+  return catchPlatformError(error => of(project(error)));
+}

package/src/error/platform-error-instance.spec.ts

@@ -0,0 +1,28 @@
+import { createDomain } from '@edumalin/platform/domain';
+import { describe, expect, it } from 'vitest';
+
+import { PlatformErrorInstance } from './platform-error-instance';
+
+describe('Platform error instance', () => {
+  const testDomain = createDomain('test');
+
+  it('has an PlatformError name', () => {
+    // given: an Platform error
+    const error = new PlatformErrorInstance(testDomain, 'test', {});
+
+    // expect: the error name to be PlatformError
+    expect(error.name).toBe('PlatformError');
+  });
+
+  it('builds an error message from the domain name and error code', () => {
+    // given: a domain and an error code
+    const domain = testDomain;
+    const errorCode = 'test';
+
+    // and: an PlatformError instance
+    const error = new PlatformErrorInstance(domain, errorCode, {});
+
+    // then: the error message is built from the domain name and error code
+    expect(error.message).toBe(`${domain.name}:error:${errorCode}`);
+  });
+});