codify-plugin-lib 1.0.99 → 1.0.100

package/dist/plan/plan.js

@@ -126,7 +126,7 @@ export class Plan {
         }
         // TODO: Add object handling here in addition to arrays in the future
         const arrayStatefulParameters = Object.fromEntries(Object.entries(filteredCurrent)
-            .filter(([k, v]) => isArrayStatefulParameter(k, v))
+            .filter(([k, v]) => isArrayParameterWithFiltering(k, v))
             .map(([k, v]) => [k, filterArrayStatefulParameter(k, v)]));
         return { ...filteredCurrent, ...arrayStatefulParameters };
         function filterCurrent() {
@@ -143,18 +143,23 @@ export class Plan {
             return Object.fromEntries(Object.entries(current)
                 .filter(([k]) => keys.has(k)));
         }
-        function isArrayStatefulParameter(k, v) {
-            return settings.parameterSettings?.[k]?.type === 'stateful'
-                && settings.parameterSettings[k].definition.getSettings().type === 'array'
+        function isArrayParameterWithFiltering(k, v) {
+            return (((settings.parameterSettings?.[k]?.type === 'stateful'
+                && settings.parameterSettings[k].definition.getSettings().type === 'array')
+                && (settings.parameterSettings[k].definition.getSettings().filterInStatelessMode ?? true)) || (settings.parameterSettings?.[k]?.type === 'array'
+                && ((settings.parameterSettings?.[k]).filterInStatelessMode ?? true)))
                 && Array.isArray(v);
         }
         // For stateless mode, we must filter the current array so that the diff algorithm will not detect any deletes
         function filterArrayStatefulParameter(k, v) {
             const desiredArray = desired[k];
-            const matcher = settings.parameterSettings[k]
-                .definition
-                .getSettings()
-                .isElementEqual ?? ((a, b) => a === b);
+            const matcher = settings.parameterSettings[k].type === 'stateful'
+                ? settings.parameterSettings[k]
+                    .definition
+                    .getSettings()
+                    .isElementEqual ?? ((a, b) => a === b)
+                : settings.parameterSettings[k]
+                    .isElementEqual ?? ((a, b) => a === b);
             const desiredCopy = [...desiredArray];
             const currentCopy = [...v];
             const result = [];

package/dist/resource/resource-settings.d.ts

@@ -52,9 +52,53 @@ export interface ResourceSettings<T extends StringIndexedObject> {
      * @param desired
      */
     inputTransformation?: (desired: Partial<T>) => Promise<unknown> | unknown;
+    /**
+     * Customize the import behavior of the resource. By default, <code>codify import</code> will call `refresh()` with
+     * every parameter set to null and return the result of the refresh as the imported config. It looks for required parameters
+     * in the schema and will prompt the user for these values before performing the import.
+     *
+     * <b>Example:</b><br>
+     * Resource `alias` with parameters
+     *
+     * ```
+     * { alias <b>(*required)</b>: string; value: string;  }
+     * ```
+     *
+     * When the user calls `codify import alias`, they will first be prompted to enter the value for `alias`. Refresh
+     * is then called with `refresh({ alias: 'user-input', value: null })`. The result returned to the user will then be:
+     *
+     * ```
+     * { type: 'alias', alias: 'user-input', value: 'git push' }
+     * ```
+     */
     import?: {
+        /**
+         * Customize the required parameters needed to import this resource. By default, the `requiredParameters` are taken
+         * from the JSON schema. The `requiredParameters` parameter must be declared if a complex required is declared in
+         * the schema (contains `oneOf`, `anyOf`, `allOf`, `if`, `then`, `else`).
+         * <br>
+         * The user will be prompted for the required parameters before the import starts. This is done because for most resources
+         * the required parameters change the behaviour of the refresh (for example for the `alias` resource, the `alias` parmaeter
+         * chooses which alias the resource is managing).
+         *
+         * See {@link import} for more information on how importing works.
+         */
         requiredParameters?: Array<Partial<keyof T>>;
+        /**
+         * Customize which keys will be refreshed in the import. Typically, `refresh()` statements only refresh
+         * the parameters provided as the input. Use `refreshKeys` to control which parameter keys are passed in.
+         * <br>
+         * By default all parameters (except for {@link requiredParameters }) are passed in with the value `null`. The passed
+         * in value can be customized using {@link defaultRefreshValues}
+         *
+         * See {@link import} for more information on how importing works.
+         */
         refreshKeys?: Array<Partial<keyof T>>;
+        /**
+         * Customize the value that is passed into refresh when importing. This must only contain keys found in {@link refreshKeys}.
+         *
+         * See {@link import} for more information on how importing works.
+         */
         defaultRefreshValues?: Partial<T>;
     };
 }
@@ -129,6 +173,25 @@ export interface ArrayParameterSetting extends DefaultParameterSetting {
      * @return Return true if desired is equivalent to current.
      */
     isElementEqual?: (desired: any, current: any) => boolean;
+    /**
+     * Filter the contents of the refreshed array by the desired. This way items currently on the system but not
+     * in desired don't show up in the plan.
+     *
+     * <b>For example, for the nvm resource:</b>
+     * <ul>
+     *   <li>Desired (20.18.0, 18.9.0, 16.3.1)</li>
+     *   <li>Current (20.18.0, 22.1.3, 12.1.0)</li>
+     * </ul>
+     *
+     * Without filtering the plan will be:
+     * (~20.18.0, +18.9.0, +16.3.1, -22.1.3, -12.1.0)<br>
+     * With filtering the plan is: (~20.18.0, +18.9.0, +16.3.1)
+     *
+     * As you can see, filtering prevents items currently installed on the system from being removed.
+     *
+     * Defaults to true.
+     */
+    filterInStatelessMode?: boolean;
 }
 /**
  * Stateful parameter type specific settings. A stateful parameter is a sub-resource that can hold its own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codify-plugin-lib",
-  "version": "1.0.99",
+  "version": "1.0.100",
   "description": "Library plugin library",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",

package/src/plan/plan.test.ts

@@ -147,6 +147,79 @@ describe('Plan entity tests', () => {
       operation: ResourceOperation.RECREATE
     })
   })
+
+  it('Filters array parameters in stateless mode (by default)', async () => {
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<any> {
+        return {
+          id: 'type',
+          parameterSettings: {
+            propZ: { type: 'array', isElementEqual: (a, b) => b.includes(a) }
+          }
+        }
+      }
+
+      async refresh(): Promise<Partial<any> | null> {
+        return {
+          propZ: [
+            '20.15.0',
+            '20.15.1'
+          ]
+        }
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan({
+      propZ: ['20.15'],
+    } as any)
+
+    expect(plan.changeSet.operation).to.eq(ResourceOperation.NOOP);
+  })
+
+  it('Doesn\'t filters array parameters if filtering is disabled', async () => {
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<any> {
+        return {
+          id: 'type',
+          parameterSettings: {
+            propZ: { type: 'array', canModify: true, isElementEqual: (a, b) => b.includes(a), filterInStatelessMode: false }
+          }
+        }
+      }
+
+      async refresh(): Promise<Partial<any> | null> {
+        return {
+          propZ: [
+            '20.15.0',
+            '20.15.1'
+          ]
+        }
+      }
+    }
+
+    const controller = new ResourceController(resource);
+    const plan = await controller.plan({
+      propZ: ['20.15'],
+    } as any)
+
+    expect(plan.changeSet).toMatchObject({
+      operation: ResourceOperation.MODIFY,
+      parameterChanges: expect.arrayContaining([
+        expect.objectContaining({
+          name: 'propZ',
+          previousValue: expect.arrayContaining([
+            '20.15.0',
+            '20.15.1'
+          ]),
+          newValue: expect.arrayContaining([
+            '20.15'
+          ]),
+          operation: 'modify'
+        })
+      ])
+    })
+  })
 })
 
 function createTestResource() {

package/src/plan/plan.ts

@@ -220,7 +220,7 @@ export class Plan<T extends StringIndexedObject> {
     // TODO: Add object handling here in addition to arrays in the future
     const arrayStatefulParameters = Object.fromEntries(
       Object.entries(filteredCurrent)
-        .filter(([k, v]) => isArrayStatefulParameter(k, v))
+        .filter(([k, v]) => isArrayParameterWithFiltering(k, v))
         .map(([k, v]) => [k, filterArrayStatefulParameter(k, v)])
     )
 
@@ -247,19 +247,27 @@ export class Plan<T extends StringIndexedObject> {
       ) as Partial<T>;
     }
 
-    function isArrayStatefulParameter(k: string, v: T[keyof T]): boolean {
-      return settings.parameterSettings?.[k]?.type === 'stateful'
-        && (settings.parameterSettings[k] as StatefulParameterSetting).definition.getSettings().type === 'array'
+    function isArrayParameterWithFiltering(k: string, v: T[keyof T]): boolean {
+      return (((settings.parameterSettings?.[k]?.type === 'stateful'
+          && (settings.parameterSettings[k] as StatefulParameterSetting).definition.getSettings().type === 'array')
+          && (((settings.parameterSettings[k] as StatefulParameterSetting).definition.getSettings() as ArrayParameterSetting).filterInStatelessMode ?? true)
+        ) || (
+          settings.parameterSettings?.[k]?.type === 'array'
+          && ((settings.parameterSettings?.[k] as ArrayParameterSetting).filterInStatelessMode ?? true)
+        ))
         && Array.isArray(v)
     }
 
     // For stateless mode, we must filter the current array so that the diff algorithm will not detect any deletes
     function filterArrayStatefulParameter(k: string, v: unknown[]): unknown[] {
       const desiredArray = desired![k] as unknown[];
-      const matcher = ((settings.parameterSettings![k] as StatefulParameterSetting)
-        .definition
-        .getSettings() as ArrayParameterSetting)
-        .isElementEqual ?? ((a, b) => a === b);
+      const matcher = settings.parameterSettings![k]!.type === 'stateful'
+        ? ((settings.parameterSettings![k] as StatefulParameterSetting)
+          .definition
+          .getSettings() as ArrayParameterSetting)
+          .isElementEqual ?? ((a, b) => a === b)
+        : (settings.parameterSettings![k] as ArrayParameterSetting)
+          .isElementEqual ?? ((a, b) => a === b)
 
       const desiredCopy = [...desiredArray];
       const currentCopy = [...v];

package/src/resource/parsed-resource-settings.ts

@@ -171,9 +171,9 @@ export class ParsedResourceSettings<T extends StringIndexedObject> implements Re
       const { requiredParameters, refreshKeys, defaultRefreshValues } = this.settings.import;
 
       const requiredParametersNotInSchema = requiredParameters
-          ?.filter(
-            (p) => schema && !(schema.properties[p])
-          )
+        ?.filter(
+          (p) => schema && !(schema.properties[p])
+        )
       if (schema && requiredParametersNotInSchema && requiredParametersNotInSchema.length > 0) {
         throw new Error(`The following properties were declared in settings.import.requiredParameters but were not found in the schema:
 ${JSON.stringify(requiredParametersNotInSchema, null, 2)}`)

package/src/resource/resource-settings.ts

@@ -65,11 +65,56 @@ export interface ResourceSettings<T extends StringIndexedObject> {
    */
   inputTransformation?: (desired: Partial<T>) => Promise<unknown> | unknown;
 
+  /**
+   * Customize the import behavior of the resource. By default, <code>codify import</code> will call `refresh()` with
+   * every parameter set to null and return the result of the refresh as the imported config. It looks for required parameters
+   * in the schema and will prompt the user for these values before performing the import.
+   *
+   * <b>Example:</b><br>
+   * Resource `alias` with parameters
+   *
+   * ```
+   * { alias <b>(*required)</b>: string; value: string;  }
+   * ```
+   *
+   * When the user calls `codify import alias`, they will first be prompted to enter the value for `alias`. Refresh
+   * is then called with `refresh({ alias: 'user-input', value: null })`. The result returned to the user will then be:
+   *
+   * ```
+   * { type: 'alias', alias: 'user-input', value: 'git push' }
+   * ```
+   */
   import?: {
+
+    /**
+     * Customize the required parameters needed to import this resource. By default, the `requiredParameters` are taken
+     * from the JSON schema. The `requiredParameters` parameter must be declared if a complex required is declared in
+     * the schema (contains `oneOf`, `anyOf`, `allOf`, `if`, `then`, `else`).
+     * <br>
+     * The user will be prompted for the required parameters before the import starts. This is done because for most resources
+     * the required parameters change the behaviour of the refresh (for example for the `alias` resource, the `alias` parmaeter
+     * chooses which alias the resource is managing).
+     *
+     * See {@link import} for more information on how importing works.
+     */
     requiredParameters?: Array<Partial<keyof T>>;
 
+    /**
+     * Customize which keys will be refreshed in the import. Typically, `refresh()` statements only refresh
+     * the parameters provided as the input. Use `refreshKeys` to control which parameter keys are passed in.
+     * <br>
+     * By default all parameters (except for {@link requiredParameters }) are passed in with the value `null`. The passed
+     * in value can be customized using {@link defaultRefreshValues}
+     *
+     * See {@link import} for more information on how importing works.
+     */
     refreshKeys?: Array<Partial<keyof T>>;
 
+    /**
+     * Customize the value that is passed into refresh when importing. This must only contain keys found in {@link refreshKeys}.
+     *
+     * See {@link import} for more information on how importing works.
+     */
     defaultRefreshValues?: Partial<T>
   }
 }
@@ -166,6 +211,26 @@ export interface ArrayParameterSetting extends DefaultParameterSetting {
    * @return Return true if desired is equivalent to current.
    */
   isElementEqual?: (desired: any, current: any) => boolean
+
+  /**
+   * Filter the contents of the refreshed array by the desired. This way items currently on the system but not
+   * in desired don't show up in the plan.
+   *
+   * <b>For example, for the nvm resource:</b>
+   * <ul>
+   *   <li>Desired (20.18.0, 18.9.0, 16.3.1)</li>
+   *   <li>Current (20.18.0, 22.1.3, 12.1.0)</li>
+   * </ul>
+   *
+   * Without filtering the plan will be:
+   * (~20.18.0, +18.9.0, +16.3.1, -22.1.3, -12.1.0)<br>
+   * With filtering the plan is: (~20.18.0, +18.9.0, +16.3.1)
+   *
+   * As you can see, filtering prevents items currently installed on the system from being removed.
+   *
+   * Defaults to true.
+   */
+  filterInStatelessMode?: boolean,
 }
 
 /**

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

@@ -151,8 +151,6 @@ describe('Stateful parameter tests', () => {
       nodeVersions: ['20.15'],
     } as any)
 
-    console.log(JSON.stringify(plan, null, 2))
-
     expect(plan.changeSet.operation).to.eq(ResourceOperation.NOOP);
   })
 })