codify-plugin-lib 1.0.37 → 1.0.39

package/src/entities/change-set.ts

@@ -1,25 +1,49 @@
-import { ParameterOperation, ResourceConfig, ResourceOperation } from 'codify-schemas';
+import { ParameterOperation, ResourceOperation, StringIndexedObject } from 'codify-schemas';
+import { ParameterConfiguration } from './plan-types.js';
 
-export interface ParameterChange {
-  name: string;
+export interface ParameterChange<T extends StringIndexedObject> {
+  name: keyof T & string;
   operation: ParameterOperation;
   previousValue: any | null;
   newValue: any | null;
 }
 
-export class ChangeSet {
+export class ChangeSet<T extends StringIndexedObject> {
   operation: ResourceOperation
-  parameterChanges: Array<ParameterChange>
+  parameterChanges: Array<ParameterChange<T>>
 
   constructor(
     operation: ResourceOperation,
-    parameterChanges: Array<ParameterChange>
+    parameterChanges: Array<ParameterChange<T>>
   ) {
     this.operation = operation;
     this.parameterChanges = parameterChanges;
   }
 
-  static createForNullCurrentConfig(desiredConfig: ResourceConfig) {
+  get desiredParameters(): T {
+    return this.parameterChanges
+      .reduce((obj, pc) => ({
+        ...obj,
+        [pc.name]: pc.newValue,
+      }), {}) as T;
+  }
+
+  get currentParameters(): T {
+    return this.parameterChanges
+      .reduce((obj, pc) => ({
+        ...obj,
+        [pc.name]: pc.previousValue,
+      }), {}) as T;
+  }
+
+  // static create<T extends Record<string, unknown>>(prev: T, next: T, options: {
+  //   statefulMode: boolean,
+  // }): ChangeSet {
+  //   const parameterChanges = ChangeSet.calculateParameterChangeSet(prev, prev, options);
+  //   const operation = ChangeSet.combineResourceOperations(prev, );
+  // }
+
+  static newCreate<T extends {}>(desiredConfig: T) {
     const parameterChangeSet = Object.entries(desiredConfig)
       .filter(([k,]) => k !== 'type' && k !== 'name')
       .map(([k, v]) => {
@@ -34,21 +58,67 @@ export class ChangeSet {
     return new ChangeSet(ResourceOperation.CREATE, parameterChangeSet);
   }
 
-  static calculateParameterChangeSet(prev: ResourceConfig, next: ResourceConfig): ParameterChange[] {
-    const parameterChangeSet = new Array<ParameterChange>();
+  static calculateParameterChangeSet<T extends StringIndexedObject>(
+    desired: T | null,
+    current: T | null,
+    options: { statefulMode: boolean, parameterConfigurations?: Record<keyof T, ParameterConfiguration> },
+  ): ParameterChange<T>[] {
+    if (options.statefulMode) {
+      return ChangeSet.calculateStatefulModeChangeSet(desired, current, options.parameterConfigurations);
+    } else {
+      return ChangeSet.calculateStatelessModeChangeSet(desired, current, options.parameterConfigurations);
+    }
+  }
 
-    const filteredPrev = Object.fromEntries(
-      Object.entries(prev)
-        .filter(([k,]) => k !== 'type' && k !== 'name')
-    );
+  static combineResourceOperations(prev: ResourceOperation, next: ResourceOperation) {
+    const orderOfOperations = [
+      ResourceOperation.NOOP,
+      ResourceOperation.MODIFY,
+      ResourceOperation.RECREATE,
+      ResourceOperation.CREATE,
+      ResourceOperation.DESTROY,
+    ]
 
-    const filteredNext = Object.fromEntries(
-      Object.entries(next)
-        .filter(([k,]) => k !== 'type' && k !== 'name')
-    );
+    const indexPrev = orderOfOperations.indexOf(prev);
+    const indexNext = orderOfOperations.indexOf(next);
 
-    for (const [k, v] of Object.entries(filteredPrev)) {
-      if (!filteredNext[k]) {
+    return orderOfOperations[Math.max(indexPrev, indexNext)];
+  }
+
+  static isSame(
+    a: unknown,
+    b: unknown,
+    isEqual?: (a: unknown, b: unknown) => boolean,
+  ): boolean {
+    if (isEqual) {
+      return isEqual(a, b);
+    }
+
+    if (Array.isArray(a) && Array.isArray(b)) {
+      const sortedPrev = a.map((x) => x).sort();
+      const sortedNext = b.map((x) => x).sort();
+
+      return JSON.stringify(sortedPrev) === JSON.stringify(sortedNext);
+    }
+
+    return a === b;
+  }
+
+  // Explanation: Stateful mode means that codify maintains a stateful to keep track of resources it has added. 
+  // When a resource is removed from a stateful config, it will be deleted from the system.
+  private static calculateStatefulModeChangeSet<T extends StringIndexedObject>(
+    desired: T | null,
+    current: T | null,
+    parameterConfigurations?: Record<keyof T, ParameterConfiguration>,
+  ): ParameterChange<T>[] {
+    const parameterChangeSet = new Array<ParameterChange<T>>();
+    
+    const _desired = { ...desired };
+    const _current = { ...current };
+
+
+    for (const [k, v] of Object.entries(_current)) {
+      if (_desired[k] == null) {
         parameterChangeSet.push({
           name: k,
           previousValue: v,
@@ -56,39 +126,39 @@ export class ChangeSet {
           operation: ParameterOperation.REMOVE,
         })
 
-        delete filteredPrev[k];
+        delete _current[k];
         continue;
       }
 
-      if (!ChangeSet.isSame(filteredPrev[k], filteredNext[k])) {
+      if (!ChangeSet.isSame(_current[k], _desired[k], parameterConfigurations?.[k]?.isEqual)) {
         parameterChangeSet.push({
           name: k,
           previousValue: v,
-          newValue: filteredNext[k],
+          newValue: _desired[k],
           operation: ParameterOperation.MODIFY,
         })
 
-        delete filteredPrev[k];
-        delete filteredNext[k];
+        delete _current[k];
+        delete _desired[k];
         continue;
       }
 
       parameterChangeSet.push({
         name: k,
         previousValue: v,
-        newValue: filteredNext[k],
+        newValue: _desired[k],
         operation: ParameterOperation.NOOP,
       })
 
-      delete filteredPrev[k];
-      delete filteredNext[k];
+      delete _current[k];
+      delete _desired[k];
     }
 
-    if (Object.keys(filteredPrev).length !== 0) {
+    if (Object.keys(_current).length !== 0) {
       throw Error('Diff algorithm error');
     }
 
-    for (const [k, v] of Object.entries(filteredNext)) {
+    for (const [k, v] of Object.entries(_desired)) {
       parameterChangeSet.push({
         name: k,
         previousValue: null,
@@ -100,29 +170,50 @@ export class ChangeSet {
     return parameterChangeSet;
   }
 
-  static combineResourceOperations(prev: ResourceOperation, next: ResourceOperation) {
-    const orderOfOperations = [
-      ResourceOperation.NOOP,
-      ResourceOperation.MODIFY,
-      ResourceOperation.RECREATE,
-      ResourceOperation.CREATE,
-      ResourceOperation.DESTROY,
-    ]
+  // Explanation: Stateful mode means that codify does not keep track of state. Resources in stateless mode can only
+  // be added by Codify and not destroyed.
+  private static calculateStatelessModeChangeSet<T extends StringIndexedObject>(
+    desired: T | null,
+    current: T | null,
+    parameterConfigurations?: Record<keyof T, ParameterConfiguration>,
+  ): ParameterChange<T>[] {
+    const parameterChangeSet = new Array<ParameterChange<T>>();
 
-    const indexPrev = orderOfOperations.indexOf(prev);
-    const indexNext = orderOfOperations.indexOf(next);
+    const _desired = { ...desired };
+    const _current = { ...current };
 
-    return orderOfOperations[Math.max(indexPrev, indexNext)];
-  }
+    for (const [k, v] of Object.entries(_desired)) {
+      if (_current[k] == null) {
+        parameterChangeSet.push({
+          name: k,
+          previousValue: null,
+          newValue: v,
+          operation: ParameterOperation.ADD,
+        });
 
-  static isSame(a: unknown, b: unknown): boolean {
-    if (Array.isArray(a) && Array.isArray(b)) {
-      const sortedPrev = a.map((x) => x).sort();
-      const sortedNext = b.map((x) => x).sort();
+        continue;
+      }
 
-      return JSON.stringify(sortedPrev) === JSON.stringify(sortedNext);
+      if (!ChangeSet.isSame(_current[k], _desired[k], parameterConfigurations?.[k]?.isEqual)) {
+        parameterChangeSet.push({
+          name: k,
+          previousValue: _current[k],
+          newValue: _desired[k],
+          operation: ParameterOperation.MODIFY,
+        });
+
+        continue;
+      }
+
+      parameterChangeSet.push({
+        name: k,
+        previousValue: v,
+        newValue: v,
+        operation: ParameterOperation.NOOP,
+      })
     }
 
-    return a === b;
+    return parameterChangeSet;
   }
+    
 }

package/src/entities/plan-types.ts

@@ -0,0 +1,26 @@
+import { ResourceOperation } from 'codify-schemas';
+
+/**
+ * Customize properties for specific parameters. This will alter the way the library process changes to the parameter.
+ */
+export interface ParameterConfiguration {
+  /**
+   * Chose if the resource should be re-created or modified if this parameter is changed. Defaults to re-create.
+   */
+  planOperation?: ResourceOperation.MODIFY | ResourceOperation.RECREATE;
+  /**
+   * Customize the equality comparison for a parameter.
+   * @param a
+   * @param b
+   */
+  isEqual?: (a: any, b: any) => boolean;
+
+  isArrayElementEqual?: (a: any, b: any) => boolean;
+
+  isStatefulParameter?: boolean;
+}
+
+export interface PlanConfiguration<T> {
+  statefulMode: boolean;
+  parameterConfigurations?: Record<keyof T, ParameterConfiguration>;
+}

package/src/entities/plan.ts

@@ -1,38 +1,95 @@
-import { ChangeSet } from './change-set.js';
-import { ApplyRequestData, PlanResponseData, ResourceConfig, } from 'codify-schemas';
+import { ChangeSet, ParameterChange } from './change-set.js';
+import {
+  ApplyRequestData,
+  ParameterOperation,
+  PlanResponseData,
+  ResourceConfig,
+  ResourceOperation,
+  StringIndexedObject,
+} from 'codify-schemas';
 import { randomUUID } from 'crypto';
+import { ParameterConfiguration, PlanConfiguration } from './plan-types.js';
+import { splitUserConfig } from '../utils/utils.js';
 
-export class Plan<T extends ResourceConfig> {
+export class Plan<T extends StringIndexedObject> {
   id: string;
-  changeSet: ChangeSet;
-  resourceConfig: T
+  changeSet: ChangeSet<T>;
+  resourceMetadata: ResourceConfig
 
-  constructor(id: string, changeSet: ChangeSet, resourceConfig: T) {
+  constructor(id: string, changeSet: ChangeSet<T>, resourceMetadata: ResourceConfig) {
     this.id = id;
     this.changeSet = changeSet;
-    this.resourceConfig = resourceConfig;
+    this.resourceMetadata = resourceMetadata;
   }
 
-  static create<T extends ResourceConfig>(changeSet: ChangeSet, resourceConfig: T): Plan<T> {
+  static create<T extends StringIndexedObject>(
+    desiredConfig: Partial<T> & ResourceConfig,
+    currentConfig: Partial<T> & ResourceConfig | null,
+    configuration: PlanConfiguration<T>
+  ): Plan<T> {
+    const parameterConfigurations = configuration.parameterConfigurations ?? {} as Record<keyof T, ParameterConfiguration>;
+    const statefulParameterNames = new Set(
+      [...Object.entries(parameterConfigurations)]
+        .filter(([k, v]) => v.isStatefulParameter)
+        .map(([k, v]) => k)
+    );
+
+    const { resourceMetadata, parameters: desiredParameters } = splitUserConfig(desiredConfig);
+    const { parameters: currentParameters } = currentConfig != null ? splitUserConfig(currentConfig) : { parameters: null };
+
+
+    // TODO: After adding in state files, need to calculate deletes here
+    //  Where current config exists and state config exists but desired config doesn't
+
+    // Explanation: This calculates the change set of the parameters between the
+    // two configs and then passes it to ChangeSet to calculate the overall
+    // operation for the resource
+    const parameterChangeSet = ChangeSet.calculateParameterChangeSet(
+      desiredParameters,
+      currentParameters,
+      { statefulMode: configuration.statefulMode, parameterConfigurations }
+    );
+
+    let resourceOperation: ResourceOperation;
+    if (!currentConfig && desiredConfig) {
+      resourceOperation = ResourceOperation.CREATE;
+    } else if (currentConfig && !desiredConfig) {
+      resourceOperation = ResourceOperation.DESTROY;
+    } else {
+      resourceOperation = parameterChangeSet
+        .filter((change) => change.operation !== ParameterOperation.NOOP)
+        .reduce((operation: ResourceOperation, curr: ParameterChange<T>) => {
+          let newOperation: ResourceOperation;
+          if (statefulParameterNames.has(curr.name)) {
+            newOperation = ResourceOperation.MODIFY // All stateful parameters are modify only
+          } else if (parameterConfigurations[curr.name]?.planOperation) {
+            newOperation = parameterConfigurations[curr.name].planOperation!;
+          } else {
+            newOperation = ResourceOperation.RECREATE; // Default to Re-create. Should handle the majority of use cases
+          }
+          return ChangeSet.combineResourceOperations(operation, newOperation);
+        }, ResourceOperation.NOOP);
+    }
+
     return new Plan(
       randomUUID(),
-      changeSet,
-      resourceConfig,
-    )
+      new ChangeSet<T>(resourceOperation, parameterChangeSet),
+      resourceMetadata,
+    );
   }
 
   getResourceType(): string {
-    return this.resourceConfig.type;
+    return this.resourceMetadata.type
   }
 
-  static fromResponse(data: ApplyRequestData['plan']): Plan<ResourceConfig> {
+  static fromResponse<T extends ResourceConfig>(data: ApplyRequestData['plan']): Plan<T> {
     if (!data) {
       throw new Error('Data is empty');
     }
 
     return new Plan(
       randomUUID(),
-      new ChangeSet(
+      new ChangeSet<T>(
         data.operation,
         data.parameters.map(value => ({
           ...value,
@@ -50,12 +107,26 @@ export class Plan<T extends ResourceConfig> {
     );
   }
 
+  get desiredConfig(): T {
+    return {
+      ...this.resourceMetadata,
+      ...this.changeSet.desiredParameters,
+    }
+  }
+
+  get currentConfig(): T {
+    return {
+      ...this.resourceMetadata,
+      ...this.changeSet.currentParameters,
+    }
+  }
+
   toResponse(): PlanResponseData {
     return {
       planId: this.id,
       operation: this.changeSet.operation,
-      resourceName: this.resourceConfig.name,
-      resourceType: this.resourceConfig.type,
+      resourceName: this.resourceMetadata.name,
+      resourceType: this.resourceMetadata.type,
       parameters: this.changeSet.parameterChanges,
     }
   }

package/src/entities/plugin.ts

@@ -27,30 +27,32 @@ export class Plugin {
     return {
       resourceDefinitions: [...this.resources.values()]
         .map((r) => ({
-          type: r.getTypeId(),
+          type: r.typeId,
           dependencies: r.getDependencyTypeIds(),
         }))
     }
   }
 
   async validate(data: ValidateRequestData): Promise<ValidateResponseData> {
-    const totalErrors = [];
+    const validationResults = [];
     for (const config of data.configs) {
       if (!this.resources.has(config.type)) {
         throw new Error(`Resource type not found: ${config.type}`);
       }
 
-      const error = await this.resources.get(config.type)!.validate(config);
-      if (error) {
-        totalErrors.push(...error);
-      }
+      const validateResult = await this.resources.get(config.type)!.validate(config);
+
+      validationResults.push({
+        ...validateResult,
+        resourceType: config.type,
+        resourceName: config.name,
+      });
     }
 
     await this.crossValidateResources(data.configs);
     return {
-      isValid: true,
-      errors: totalErrors,
-    }
+      validationResults
+    };
   }
 
   async plan(data: PlanRequestData): Promise<PlanResponseData> {

package/src/entities/resource-parameters.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest';
+import { StatefulParameter, StatefulParameterConfiguration } from './stateful-parameter.js';
+import { Plan } from './plan.js';
+import { spy } from 'sinon';
+import { ResourceOperation } from 'codify-schemas';
+import { TestConfig, TestResource } from './resource.test.js';
+
+class TestParameter extends StatefulParameter<TestConfig, string> {
+  constructor(configuration?: StatefulParameterConfiguration<TestConfig>) {
+    super(configuration ?? {
+      name: 'propA'
+    })
+  }
+
+  applyAdd(valueToAdd: string, plan: Plan<TestConfig>): Promise<void> {
+    return Promise.resolve();
+  }
+  applyModify(newValue: string, previousValue: string, allowDeletes: boolean, plan: Plan<TestConfig>): Promise<void> {
+    return Promise.resolve();
+  }
+  applyRemove(valueToRemove: string, plan: Plan<TestConfig>): Promise<void> {
+    return Promise.resolve();
+  }
+  async refresh(): Promise<string | null> {
+    return '';
+  }
+}
+
+describe('Resource parameters tests', () => {
+  it('supports the creation of stateful parameters', async () => {
+
+    const statefulParameter = new class extends TestParameter {
+      async refresh(): Promise<string | null> {
+        return null;
+      }
+    }
+
+    const statefulParameterSpy = spy(statefulParameter);
+
+    const resource = new class extends TestResource {
+
+      constructor() {
+        super({
+          type: 'resource',
+          statefulParameters: [statefulParameterSpy],
+        });
+      }
+    }
+
+    const resourceSpy = spy(resource);
+    const result = await resourceSpy.apply(
+      Plan.create<TestConfig>(
+        { type: 'resource', propA: 'a', propB: 0, propC: 'b' },
+        null,
+        { statefulMode: false },
+      )
+    );
+
+    expect(statefulParameterSpy.applyAdd.calledOnce).to.be.true;
+    expect(resourceSpy.applyCreate.calledOnce).to.be.true;
+  })
+
+  it('supports the modification of stateful parameters', async () => {
+    const statefulParameter = new class extends TestParameter {
+      async refresh(): Promise<string | null> {
+        return 'b';
+      }
+    }
+
+    const statefulParameterSpy = spy(statefulParameter);
+
+    const resource = new class extends TestResource {
+
+      constructor() {
+        super({
+          type: 'resource',
+          statefulParameters: [statefulParameterSpy],
+          parameterConfigurations: {
+            propB: { planOperation: ResourceOperation.MODIFY },
+          }
+        });
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        return { propB: -1, propC: 'b' }
+      }
+    }
+
+    const plan = await resource.plan({ type: 'resource', propA: 'a', propB: 0, propC: 'b' })
+
+    const resourceSpy = spy(resource);
+    const result = await resourceSpy.apply(plan);
+
+    expect(statefulParameterSpy.applyModify.calledOnce).to.be.true;
+    expect(resourceSpy.applyModify.calledOnce).to.be.true;
+  })
+
+  it('Filters array results in stateless mode to prevent modify from being called', async () => {
+    const statefulParameter = new class extends TestParameter {
+      async refresh(): Promise<any | null> {
+        return ['a', 'b', 'c', 'd']
+      }
+    }
+
+    const statefulParameterSpy = spy(statefulParameter);
+
+    const resource = new class extends TestResource {
+      constructor() {
+        super({
+          type: 'resource',
+          statefulParameters: [statefulParameterSpy],
+        });
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        return null;
+      }
+    }
+
+    const plan = await resource.plan({ type: 'resource', propA: ['a', 'b'] } as any)
+
+    expect(plan).toMatchObject({
+      changeSet: {
+        operation: ResourceOperation.NOOP,
+      }
+    })
+  })
+
+  it('Filters array results in stateless mode to prevent modify from being called', async () => {
+    const statefulParameter = new class extends TestParameter {
+      async refresh(): Promise<any | null> {
+        return ['a', 'b']
+      }
+    }
+
+    const statefulParameterSpy = spy(statefulParameter);
+
+    const resource = new class extends TestResource {
+      constructor() {
+        super({
+          type: 'resource',
+          statefulParameters: [statefulParameterSpy],
+        });
+      }
+
+      async refresh(): Promise<Partial<TestConfig> | null> {
+        return null;
+      }
+    }
+
+    const plan = await resource.plan({ type: 'resource', propA: ['a', 'b', 'c', 'd'] } as any)
+
+    expect(plan).toMatchObject({
+      changeSet: {
+        operation: ResourceOperation.MODIFY,
+      }
+    })
+  })
+})

package/src/entities/resource-types.ts

@@ -0,0 +1,47 @@
+import { StatefulParameter } from './stateful-parameter.js';
+import { ResourceOperation, StringIndexedObject } from 'codify-schemas';
+import { Resource } from './resource.js';
+
+export type ErrorMessage = string;
+
+/**
+ * Customize properties for specific parameters. This will alter the way the library process changes to the parameter.
+ */
+export interface ResourceParameterConfiguration {
+  /**
+   * Chose if the resource should be re-created or modified if this parameter is changed. Defaults to re-create.
+   */
+  planOperation?: ResourceOperation.MODIFY | ResourceOperation.RECREATE;
+  /**
+   * Customize the equality comparison for a parameter.
+   * @param a
+   * @param b
+   */
+  isEqual?: (a: any, b: any) => boolean;
+}
+
+/**
+ * @param
+ */
+export interface ResourceConfiguration<T extends StringIndexedObject> {
+  type: string;
+  /**
+   * If true, statefulParameter.applyRemove() will be called before resource destruction.
+   * Defaults to false.
+   */
+  callStatefulParameterRemoveOnDestroy?: boolean,
+  dependencies?: Resource<any>[];
+  statefulParameters?: Array<StatefulParameter<T, T[keyof T]>>;
+  parameterConfigurations?: Partial<Record<keyof T, ResourceParameterConfiguration>>
+}
+
+export interface ResourceDefinition {
+  [x: string]: {
+    type: string;
+  }
+}
+
+export interface ValidationResult {
+  isValid: boolean;
+  errors?: unknown[],
+}