codify-plugin-lib 1.0.49 → 1.0.51

package/src/entities/resource.ts

@@ -2,9 +2,13 @@ import { ParameterOperation, ResourceConfig, ResourceOperation, StringIndexedObj
 import { ParameterChange } from './change-set.js';
 import { Plan } from './plan.js';
 import { StatefulParameter } from './stateful-parameter.js';
-import { ResourceConfiguration, ValidationResult } from './resource-types.js';
+import { ResourceParameterOptions, ValidationResult } from './resource-types.js';
 import { setsEqual, splitUserConfig } from '../utils/utils.js';
-import { ParameterConfiguration, PlanConfiguration } from './plan-types.js';
+import { ParameterOptions, PlanOptions } from './plan-types.js';
+import { TransformParameter } from './transform-parameter.js';
+import { ResourceOptions, ResourceOptionsParser } from './resource-options.js';
+import Ajv from 'ajv';
+import Ajv2020, { ValidateFunction } from 'ajv/dist/2020.js';
 
 /**
  * Description of resource here
@@ -14,92 +18,99 @@ import { ParameterConfiguration, PlanConfiguration } from './plan-types.js';
  *
  */
 export abstract class Resource<T extends StringIndexedObject> {
-
   readonly typeId: string;
   readonly statefulParameters: Map<keyof T, StatefulParameter<T, T[keyof T]>>;
+  readonly transformParameters: Map<keyof T, TransformParameter<T>>
+  readonly resourceParameters: Map<keyof T, ResourceParameterOptions>;
+
+  readonly statefulParameterOrder: Map<keyof T, number>;
+  readonly transformParameterOrder: Map<keyof T, number>;
+
   readonly dependencies: string[]; // TODO: Change this to a string
-  readonly parameterConfigurations: Record<keyof T, ParameterConfiguration>
-  readonly configuration: ResourceConfiguration<T>;
+  readonly parameterOptions: Record<keyof T, ParameterOptions>
+  readonly options: ResourceOptions<T>;
   readonly defaultValues: Partial<Record<keyof T, unknown>>;
 
-  protected constructor(configuration: ResourceConfiguration<T>) {
-    this.validateResourceConfiguration(configuration);
+  protected ajv?: Ajv.default;
+  protected schemaValidator?: ValidateFunction;
+
+  protected constructor(options: ResourceOptions<T>) {
+    this.typeId = options.type;
+    this.dependencies = options.dependencies ?? [];
+    this.options = options;
 
-    this.typeId = configuration.type;
-    this.statefulParameters = new Map(configuration.statefulParameters?.map((sp) => [sp.name, sp]));
-    this.parameterConfigurations = this.initializeParameterConfigurations(configuration);
-    this.defaultValues = this.initializeDefaultValues(configuration);
+    if (this.options.schema) {
+      this.ajv = new Ajv2020.default({
+        strict: true,
+        strictRequired: false,
+      })
+      this.schemaValidator = this.ajv.compile(this.options.schema);
+    }
 
-    this.dependencies = configuration.dependencies ?? [];
-    this.configuration = configuration;
+    const parser = new ResourceOptionsParser<T>(options);
+    this.statefulParameters = parser.statefulParameters;
+    this.transformParameters = parser.transformParameters;
+    this.resourceParameters = parser.resourceParameters;
+    this.parameterOptions = parser.changeSetParameterOptions;
+    this.defaultValues = parser.defaultValues;
+    this.statefulParameterOrder = parser.statefulParameterOrder;
+    this.transformParameterOrder = parser.transformParameterOrder;
   }
 
   async onInitialize(): Promise<void> {}
 
+  async validateResource(parameters: unknown): Promise<ValidationResult> {
+    if (this.schemaValidator) {
+      const isValid = this.schemaValidator(parameters);
+
+      if (!isValid) {
+        return {
+          isValid: false,
+          errors: this.schemaValidator?.errors ?? [],
+        }
+      }
+    }
+
+    return this.validate(parameters);
+  }
+
   // TODO: Add state in later.
   //  Currently only calculating how to add things to reach desired state. Can't delete resources.
   //  Add previousConfig as a parameter for plan(desired, previous);
   async plan(desiredConfig: Partial<T> & ResourceConfig): Promise<Plan<T>> {
-
-    // Explanation: these are settings for how the plan will be generated
-    const planConfiguration: PlanConfiguration<T> = {
+    const planOptions: PlanOptions<T> = {
       statefulMode: false,
-      parameterConfigurations: this.parameterConfigurations,
+      parameterOptions: this.parameterOptions,
     }
 
-    const { resourceMetadata, parameters: desiredParameters } = splitUserConfig(desiredConfig);
-
-    this.addDefaultValues(desiredParameters);
+    // Parse data from the user supplied config
+    const parsedConfig = new ConfigParser(desiredConfig, this.statefulParameters, this.transformParameters)
+    const {
+      parameters: desiredParameters,
+      resourceMetadata,
+      resourceParameters,
+      statefulParameters
+    } = parsedConfig;
 
-    const resourceParameters = Object.fromEntries([
-      ...Object.entries(desiredParameters).filter(([key]) => !this.statefulParameters.has(key)),
-    ]) as Partial<T>;
+    this.addDefaultValues(resourceParameters);
+    await this.applyTransformParameters(resourceParameters);
 
-    const statefulParameters = [...this.statefulParameters.values()]
-      .filter((sp) => desiredParameters[sp.name] !== undefined) // Checking for undefined is fine here because JSONs can only have null.
+    // Refresh resource parameters. This refreshes the parameters that configure the resource itself
+    const currentParameters = await this.refreshResourceParameters(resourceParameters);
 
-    // Refresh resource parameters
-    // This refreshes the parameters that configure the resource itself
-    const entriesToRefresh = new Map(Object.entries(resourceParameters));
-    const currentParameters = await this.refresh(entriesToRefresh);
-
-    // Short circuit here. If resource is non-existent, then there's no point checking stateful parameters
+    // Short circuit here. If the resource is non-existent, there's no point checking stateful parameters
     if (currentParameters == null) {
-      return Plan.create(desiredParameters, null, resourceMetadata, planConfiguration);
+      return Plan.create(desiredParameters, null, resourceMetadata, planOptions);
     }
 
-    this.validateRefreshResults(currentParameters, entriesToRefresh);
-
-    // Refresh stateful parameters
-    // This refreshes parameters that are stateful (they can be added, deleted separately from the resource)
-    for(const statefulParameter of statefulParameters) {
-      const desiredValue = desiredParameters[statefulParameter.name];
-
-      let currentValue = await statefulParameter.refresh(desiredValue ?? null) ?? undefined;
-
-      // In stateless mode, filter the refreshed parameters by the desired to ensure that no deletes happen
-      if (Array.isArray(currentValue)
-        && Array.isArray(desiredValue)
-        && !planConfiguration.statefulMode
-        && !statefulParameter.configuration.disableStatelessModeArrayFiltering
-      ) {
-        currentValue = currentValue.filter((c) => desiredValue?.some((d) => {
-          const pc = planConfiguration?.parameterConfigurations?.[statefulParameter.name];
-          if (pc && pc.isElementEqual) {
-            return pc.isElementEqual(d, c);
-          }
-          return d === c;
-        })) as any;
-      }
-
-      currentParameters[statefulParameter.name] = currentValue;
-    }
+    // Refresh stateful parameters. These parameters have state external to the resource
+    const statefulCurrentParameters = await this.refreshStatefulParameters(statefulParameters, planOptions.statefulMode);
 
     return Plan.create(
-      desiredParameters,
-      currentParameters as Partial<T>,
+      { ...resourceParameters, ...statefulParameters },
+      { ...currentParameters, ...statefulCurrentParameters } as Partial<T>,
       resourceMetadata,
-      planConfiguration,
+      planOptions,
     )
   }
 
@@ -130,6 +141,8 @@ export abstract class Resource<T extends StringIndexedObject> {
 
     const statefulParameterChanges = plan.changeSet.parameterChanges
       .filter((pc: ParameterChange<T>) => this.statefulParameters.has(pc.name))
+      .sort((a, b) => this.statefulParameterOrder.get(a.name)! - this.statefulParameterOrder.get(b.name)!)
+
     for (const parameterChange of statefulParameterChanges) {
       const statefulParameter = this.statefulParameters.get(parameterChange.name)!;
       await statefulParameter.applyAdd(parameterChange.newValue, plan);
@@ -144,6 +157,7 @@ export abstract class Resource<T extends StringIndexedObject> {
 
     const statelessParameterChanges = parameterChanges
       .filter((pc: ParameterChange<T>) => !this.statefulParameters.has(pc.name))
+
     for (const pc of statelessParameterChanges) {
       // TODO: When stateful mode is added in the future. Dynamically choose if deletes are allowed
       await this.applyModify(pc.name, pc.newValue, pc.previousValue, false, plan);
@@ -151,6 +165,8 @@ export abstract class Resource<T extends StringIndexedObject> {
 
     const statefulParameterChanges = parameterChanges
       .filter((pc: ParameterChange<T>) => this.statefulParameters.has(pc.name))
+      .sort((a, b) => this.statefulParameterOrder.get(a.name)! - this.statefulParameterOrder.get(b.name)!)
+
     for (const parameterChange of statefulParameterChanges) {
       const statefulParameter = this.statefulParameters.get(parameterChange.name)!;
 
@@ -175,9 +191,11 @@ export abstract class Resource<T extends StringIndexedObject> {
   private async _applyDestroy(plan: Plan<T>): Promise<void> {
     // If this option is set (defaults to false), then stateful parameters need to be destroyed
     // as well. This means that the stateful parameter wouldn't have been normally destroyed with applyDestroy()
-    if (this.configuration.callStatefulParameterRemoveOnDestroy) {
+    if (this.options.callStatefulParameterRemoveOnDestroy) {
       const statefulParameterChanges = plan.changeSet.parameterChanges
         .filter((pc: ParameterChange<T>) => this.statefulParameters.has(pc.name))
+        .sort((a, b) => this.statefulParameterOrder.get(a.name)! - this.statefulParameterOrder.get(b.name)!)
+
       for (const parameterChange of statefulParameterChanges) {
         const statefulParameter = this.statefulParameters.get(parameterChange.name)!;
         await statefulParameter.applyRemove(parameterChange.previousValue, plan);
@@ -187,59 +205,6 @@ export abstract class Resource<T extends StringIndexedObject> {
     await this.applyDestroy(plan);
   }
 
-  private initializeParameterConfigurations(
-    resourceConfiguration: ResourceConfiguration<T>
-  ): Record<keyof T, ParameterConfiguration>  {
-    const resourceParameters = Object.fromEntries(
-      Object.entries(resourceConfiguration.parameterConfigurations ?? {})
-        ?.map(([name, value]) => ([name, { ...value, isStatefulParameter: false }]))
-    ) as Record<keyof T, ParameterConfiguration>
-
-    const statefulParameters = resourceConfiguration.statefulParameters
-      ?.reduce((obj, sp) => {
-        return {
-          ...obj,
-          [sp.name]: {
-            ...sp.configuration,
-            isStatefulParameter: true,
-          }
-        }
-      }, {}) ?? {}
-
-    return {
-      ...resourceParameters,
-      ...statefulParameters,
-    }
-
-  }
-
-  private initializeDefaultValues(
-    resourceConfiguration: ResourceConfiguration<T>
-  ): Partial<Record<keyof T, unknown>>  {
-    if (!resourceConfiguration.parameterConfigurations) {
-      return {};
-    }
-
-    return Object.fromEntries(
-      Object.entries(resourceConfiguration.parameterConfigurations)
-        .filter((p) => p[1]?.defaultValue !== undefined)
-        .map((config) => [config[0], config[1]!.defaultValue])
-    ) as Partial<Record<keyof T, unknown>>;
-  }
-
-  private validateResourceConfiguration(data: ResourceConfiguration<T>) {
-    // Stateful parameters are configured within the object not in the resource.
-    if (data.parameterConfigurations && data.statefulParameters) {
-      const parameters = [...Object.keys(data.parameterConfigurations)];
-      const statefulParameterSet = new Set(data.statefulParameters.map((sp) => sp.name));
-
-      const intersection = parameters.some((p) => statefulParameterSet.has(p));
-      if (intersection) {
-        throw new Error(`Resource ${this.typeId} cannot declare a parameter as both stateful and non-stateful`);
-      }
-    }
-  }
-
   private validateRefreshResults(refresh: Partial<T> | null, desiredMap: Map<keyof T, T[keyof T]>) {
     if (!refresh) {
       return;
@@ -250,7 +215,7 @@ export abstract class Resource<T extends StringIndexedObject> {
 
     if (!setsEqual(desiredKeys, refreshKeys)) {
       throw new Error(
-        `Resource ${this.configuration.type}
+        `Resource ${this.typeId}
 refresh() must return back exactly the keys that were provided
 Missing: ${[...desiredKeys].filter((k) => !refreshKeys.has(k))};
 Additional: ${[...refreshKeys].filter(k => !desiredKeys.has(k))};`
@@ -258,6 +223,28 @@ Additional: ${[...refreshKeys].filter(k => !desiredKeys.has(k))};`
     }
   }
 
+  private async applyTransformParameters(desired: Partial<T>): Promise<void> {
+    const orderedEntries = [...this.transformParameters.entries()]
+      .sort(([keyA], [keyB]) => this.transformParameterOrder.get(keyA)! - this.transformParameterOrder.get(keyB)!)
+
+    for (const [key, tp] of orderedEntries) {
+      if (desired[key] !== null) {
+        const transformedValue = await tp.transform(desired[key]);
+
+        if (Object.keys(transformedValue).some((k) => desired[k] !== undefined)) {
+          throw new Error(`Transform parameter ${key as string} is attempting to override existing value ${desired[key]}`);
+        }
+
+        Object.entries(transformedValue).forEach(([tvKey, tvValue]) => {
+          // @ts-ignore
+          desired[tvKey] = tvValue;
+        })
+
+        delete desired[key];
+      }
+    }
+  }
+
   private addDefaultValues(desired: Partial<T>): void {
     Object.entries(this.defaultValues)
       .forEach(([key, defaultValue]) => {
@@ -268,7 +255,59 @@ Additional: ${[...refreshKeys].filter(k => !desiredKeys.has(k))};`
       });
   }
 
-  abstract validate(parameters: unknown): Promise<ValidationResult>;
+  private async refreshResourceParameters(resourceParameters: Partial<T>): Promise<Partial<T> | null> {
+    const entriesToRefresh = new Map(Object.entries(resourceParameters));
+    const currentParameters = await this.refresh(entriesToRefresh);
+
+    this.validateRefreshResults(currentParameters, entriesToRefresh);
+    return currentParameters;
+  }
+
+  // Refresh stateful parameters
+  // This refreshes parameters that are stateful (they can be added, deleted separately from the resource)
+  private async refreshStatefulParameters(statefulParametersConfig: Partial<T>, isStatefulMode: boolean): Promise<Partial<T>> {
+    const currentParameters: Partial<T> = {}
+    const sortedEntries = Object.entries(statefulParametersConfig)
+      .sort(([key1], [key2]) => this.statefulParameterOrder.get(key1)! - this.statefulParameterOrder.get(key2)!)
+
+    for(const [key, desiredValue] of sortedEntries) {
+      const statefulParameter = this.statefulParameters.get(key);
+      if (!statefulParameter) {
+        throw new Error(`Stateful parameter ${key} was not found`);
+      }
+
+      let currentValue = await statefulParameter.refresh(desiredValue ?? null);
+
+      // In stateless mode, filter the refreshed parameters by the desired to ensure that no deletes happen
+      // Otherwise the change set will pick up the extra keys from the current and try to delete them
+      // This allows arrays within stateful parameters to be first class objects
+      if (Array.isArray(currentValue)
+        && Array.isArray(desiredValue)
+        && !isStatefulMode
+        && !statefulParameter.options.disableStatelessModeArrayFiltering
+      ) {
+        currentValue = currentValue.filter((c) => desiredValue?.some((d) => {
+          const parameterOptions = statefulParameter.options as any;
+          if (parameterOptions && parameterOptions.isElementEqual) {
+            return parameterOptions.isElementEqual(d, c);
+          }
+
+          return d === c;
+        })) as any;
+      }
+
+      // @ts-ignore
+      currentParameters[key] = currentValue;
+    }
+
+    return currentParameters;
+  }
+
+  async validate(parameters: unknown): Promise<ValidationResult> {
+    return {
+      isValid: true,
+    }
+  };
 
   abstract refresh(keys: Map<keyof T, T[keyof T]>): Promise<Partial<T> | null>;
 
@@ -278,3 +317,53 @@ Additional: ${[...refreshKeys].filter(k => !desiredKeys.has(k))};`
 
   abstract applyDestroy(plan: Plan<T>): Promise<void>;
 }
+
+class ConfigParser<T extends StringIndexedObject> {
+  private config: Partial<T> & ResourceConfig;
+  private statefulParametersMap: Map<keyof T, StatefulParameter<T, T[keyof T]>>;
+  private transformParametersMap: Map<keyof T, TransformParameter<T>>;
+
+  constructor(
+    config: Partial<T> & ResourceConfig,
+    statefulParameters: Map<keyof T, StatefulParameter<T, T[keyof T]>>,
+  transformParameters: Map<keyof T, TransformParameter<T>>,
+  ) {
+    this.config = config;
+    this.statefulParametersMap = statefulParameters;
+    this.transformParametersMap = transformParameters;
+  }
+
+  get resourceMetadata(): ResourceConfig {
+    const { resourceMetadata } = splitUserConfig(this.config);
+    return resourceMetadata;
+  }
+
+  get parameters(): Partial<T> {
+    const { parameters } = splitUserConfig(this.config);
+    return parameters;
+  }
+
+  get resourceParameters(): Partial<T> {
+    const parameters = this.parameters;
+
+    return Object.fromEntries([
+      ...Object.entries(parameters).filter(([key]) => !(this.statefulParametersMap.has(key) || this.transformParametersMap.has(key))),
+    ]) as Partial<T>;
+  }
+
+  get statefulParameters(): Partial<T> {
+    const parameters = this.parameters;
+
+    return Object.fromEntries([
+      ...Object.entries(parameters).filter(([key]) => this.statefulParametersMap.has(key)),
+    ]) as Partial<T>;
+  }
+
+  get transformParameters(): Partial<T> {
+    const parameters = this.parameters;
+
+    return Object.fromEntries([
+      ...Object.entries(parameters).filter(([key]) => this.transformParametersMap.has(key)),
+    ]) as Partial<T>;
+  }
+}

package/src/entities/stateful-parameter.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { ArrayStatefulParameter, ArrayStatefulParameterConfiguration, } from './stateful-parameter.js';
+import { ArrayStatefulParameter, ArrayStatefulParameterOptions, } from './stateful-parameter.js';
 import { Plan } from './plan.js';
 import { spy } from 'sinon';
 import { ParameterOperation, ResourceOperation } from 'codify-schemas';
@@ -10,8 +10,8 @@ interface TestConfig {
 }
 
 class TestArrayParameter extends ArrayStatefulParameter<TestConfig, string> {
-  constructor(configuration?: ArrayStatefulParameterConfiguration<TestConfig>) {
-    super(configuration ?? {
+  constructor(options?: ArrayStatefulParameterOptions<TestConfig>) {
+    super(options ?? {
       name: 'propA'
     })
   }
@@ -67,7 +67,7 @@ describe('Stateful parameter tests', () => {
       { propA: ['a', 'c', 'd', 'e', 'f'] }, // b to remove, d, e, f to add
       { propA: ['a', 'b', 'c'] },
       { type: 'typeA' },
-      { statefulMode: true, parameterConfigurations: { propA: { isStatefulParameter: true }} }
+      { statefulMode: true, parameterOptions: { propA: { isStatefulParameter: true }} }
     );
 
     expect(plan.changeSet.operation).to.eq(ResourceOperation.MODIFY);
@@ -90,7 +90,7 @@ describe('Stateful parameter tests', () => {
       { propA: ['9.12', '9.13'] }, // b to remove, d, e, f to add
       { propA: ['9.12.9'] },
       { type: 'typeA' },
-      { statefulMode: false, parameterConfigurations: { propA: { isStatefulParameter: true }} }
+      { statefulMode: false, parameterOptions: { propA: { isStatefulParameter: true }} }
     );
 
     expect(plan.changeSet.operation).to.eq(ResourceOperation.MODIFY);

package/src/entities/stateful-parameter.ts

@@ -1,7 +1,7 @@
 import { Plan } from './plan.js';
 import { StringIndexedObject } from 'codify-schemas';
 
-export interface StatefulParameterConfiguration<T> {
+export interface StatefulParameterOptions<T> {
   name: keyof T;
   isEqual?: (desired: any, current: any) => boolean;
 
@@ -17,7 +17,7 @@ export interface StatefulParameterConfiguration<T> {
   disableStatelessModeArrayFiltering?: boolean;
 }
 
-export interface ArrayStatefulParameterConfiguration<T> extends StatefulParameterConfiguration<T> {
+export interface ArrayStatefulParameterOptions<T> extends StatefulParameterOptions<T> {
   isEqual?: (desired: any[], current: any[]) => boolean;
   isElementEqual?: (desired: any, current: any) => boolean;
 }
@@ -25,11 +25,11 @@ export interface ArrayStatefulParameterConfiguration<T> extends StatefulParamete
 
 export abstract class StatefulParameter<T extends StringIndexedObject, V extends T[keyof T]> {
   readonly name: keyof T;
-  readonly configuration: StatefulParameterConfiguration<T>;
+  readonly options: StatefulParameterOptions<T>;
 
-  protected constructor(configuration: StatefulParameterConfiguration<T>) {
-    this.name = configuration.name;
-    this.configuration = configuration
+  protected constructor(options: StatefulParameterOptions<T>) {
+    this.name = options.name;
+    this.options = options
   }
 
   abstract refresh(desired: V | null): Promise<V | null>;
@@ -41,11 +41,11 @@ export abstract class StatefulParameter<T extends StringIndexedObject, V extends
 }
 
 export abstract class ArrayStatefulParameter<T extends StringIndexedObject, V> extends StatefulParameter<T, any>{
-  configuration: ArrayStatefulParameterConfiguration<T>;
+  options: ArrayStatefulParameterOptions<T>;
 
-  constructor(configuration: ArrayStatefulParameterConfiguration<T>) {
-    super(configuration);
-    this.configuration = configuration;
+  constructor(options: ArrayStatefulParameterOptions<T>) {
+    super(options);
+    this.options = options;
   }
 
   async applyAdd(valuesToAdd: V[], plan: Plan<T>): Promise<void> {
@@ -55,18 +55,18 @@ export abstract class ArrayStatefulParameter<T extends StringIndexedObject, V> e
   }
 
   async applyModify(newValues: V[], previousValues: V[], allowDeletes: boolean, plan: Plan<T>): Promise<void> {
-    const configuration = this.configuration as ArrayStatefulParameterConfiguration<T>;
+    const options = this.options as ArrayStatefulParameterOptions<T>;
 
     const valuesToAdd = newValues.filter((n) => !previousValues.some((p) => {
-      if ((configuration).isElementEqual) {
-        return configuration.isElementEqual(n, p);
+      if (options.isElementEqual) {
+        return options.isElementEqual(n, p);
       }
       return n === p;
     }));
 
     const valuesToRemove = previousValues.filter((p) => !newValues.some((n) => {
-      if ((configuration).isElementEqual) {
-        return configuration.isElementEqual(n, p);
+      if (options.isElementEqual) {
+        return options.isElementEqual(n, p);
       }
       return n === p;
     }));

package/src/entities/transform-parameter.ts

@@ -0,0 +1,7 @@
+import { StringIndexedObject } from 'codify-schemas';
+
+export abstract class TransformParameter<T extends StringIndexedObject> {
+
+  abstract transform(value: any): Promise<Partial<T>>
+
+}