codify-plugin-lib 1.0.98 → 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/parsed-resource-settings.js

@@ -115,10 +115,26 @@ export class ParsedResourceSettings {
                 'determine the prompt to ask users during imports. It can\'t parse which parameters are needed when ' +
                 'required is declared conditionally.');
         }
-        const importRequiredParameterNotInSchema = this.settings.import?.requiredParameters?.filter((p) => !(schema?.properties[p]));
-        if (schema && importRequiredParameterNotInSchema && importRequiredParameterNotInSchema.length > 0) {
-            throw new Error(`The following properties were declared in settings.import.requiredParameters but were not found in the schema:
-${JSON.stringify(importRequiredParameterNotInSchema, null, 2)}`);
+        if (this.settings.import) {
+            const { requiredParameters, refreshKeys, defaultRefreshValues } = this.settings.import;
+            const requiredParametersNotInSchema = requiredParameters
+                ?.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)}`);
+            }
+            const refreshKeyNotInSchema = refreshKeys
+                ?.filter((k) => schema && !(schema.properties[k]));
+            if (schema && refreshKeyNotInSchema && refreshKeyNotInSchema.length > 0) {
+                throw new Error(`The following properties were declared in settings.import.refreshKeys but were not found in the schema:
+${JSON.stringify(requiredParametersNotInSchema, null, 2)}`);
+            }
+            const refreshValueNotInRefreshKey = Object.entries(defaultRefreshValues ?? {})
+                .filter(([k]) => schema && !(schema.properties[k])).map(([k]) => k);
+            if (schema && refreshValueNotInRefreshKey.length > 0) {
+                throw new Error(`Properties declared in defaultRefreshValues must already be declared in refreshKeys:
+${JSON.stringify(refreshValueNotInRefreshKey, null, 2)}`);
+            }
         }
     }
     validateParameterEqualsFn(parameter, key) {

package/dist/resource/resource-controller.js

@@ -134,13 +134,15 @@ export class ResourceController {
         this.addDefaultValues(config);
         await this.applyTransformParameters(config);
         // Use refresh parameters if specified, otherwise try to refresh as many parameters as possible here
-        const parametersToRefresh = this.settings.import?.refreshParameters
+        const parametersToRefresh = this.settings.import?.refreshKeys
             ? {
-                ...Object.fromEntries(this.settings.import?.refreshParameters.map((k) => [k, null])),
+                ...Object.fromEntries(this.settings.import?.refreshKeys.map((k) => [k, null])),
+                ...this.settings.import?.defaultRefreshValues,
                 ...config,
             }
             : {
                 ...Object.fromEntries(this.getAllParameterKeys().map((k) => [k, null])),
+                ...this.settings.import?.defaultRefreshValues,
                 ...config,
             };
         // Parse data from the user supplied config

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

@@ -52,9 +52,54 @@ 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>>;
-        refreshParameters?: 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>;
     };
 }
 /**
@@ -128,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.98",
+  "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.test.ts

@@ -63,19 +63,16 @@ describe('Resource options parser tests', () => {
       schema,
     }
 
-    expect(() => new ParsedResourceSettings(option)).throws;
+    expect(() => new ParsedResourceSettings(option)).toThrowError();
   })
 
   it('Throws an error when an import.requiredParameters is declared improperly', () => {
     const schema = {
       '$schema': 'http://json-schema.org/draft-07/schema',
-      '$id': 'https://www.codifycli.com/git-clone.json',
-      'title': 'Git-clone resource',
       'type': 'object',
       'properties': {
         'remote': {
           'type': 'string',
-          'description': 'Remote tracking url to clone repo from. Equivalent to repository and only one should be specified'
         },
       },
       'additionalProperties': false,
@@ -89,6 +86,77 @@ describe('Resource options parser tests', () => {
       }
     }
 
-    expect(() => new ParsedResourceSettings(option)).throws;
+    expect(() => new ParsedResourceSettings(option)).toThrowError();
+  })
+
+  it('Throws an error when an import.refreshKeys is declared improperly', () => {
+    const schema = {
+      '$schema': 'http://json-schema.org/draft-07/schema',
+      'type': 'object',
+      'properties': {
+        'remote': {
+          'type': 'string',
+        },
+      },
+      'additionalProperties': false,
+    }
+
+    const option: ResourceSettings<TestConfig> = {
+      id: 'typeId',
+      schema,
+      import: {
+        refreshKeys: ['import-error']
+      }
+    }
+
+    expect(() => new ParsedResourceSettings(option)).toThrowError();
+  })
+
+  it('Doesn\'t throw an error when an import.refreshValues is declared properly', () => {
+    const schema = {
+      '$schema': 'http://json-schema.org/draft-07/schema',
+      'type': 'object',
+      'properties': {
+        'remote': {
+          'type': 'string',
+        },
+      },
+      'additionalProperties': false,
+    }
+
+    const option: ResourceSettings<TestConfig> = {
+      id: 'typeId',
+      schema,
+      import: {
+        refreshKeys: ['remote'],
+      }
+    }
+
+    expect(() => new ParsedResourceSettings(option)).not.toThrowError()
+  })
+
+  it('Throws an error if defaultRefreshValue is not found in refreshKeys', () => {
+    const schema = {
+      '$schema': 'http://json-schema.org/draft-07/schema',
+      'type': 'object',
+      'properties': {
+        'remote': {
+          'type': 'string',
+        },
+      },
+      'additionalProperties': false,
+    }
+
+    const option: ResourceSettings<TestConfig> = {
+      id: 'typeId',
+      schema,
+      import: {
+        defaultRefreshValues: {
+          repository: 'abc'
+        }
+      }
+    }
+
+    expect(() => new ParsedResourceSettings(option)).toThrowError()
   })
 })

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

@@ -167,11 +167,37 @@ export class ParsedResourceSettings<T extends StringIndexedObject> implements Re
       )
     }
 
-    const importRequiredParameterNotInSchema =
-      this.settings.import?.requiredParameters?.filter((p) => !(schema?.properties[p]))
-    if (schema && importRequiredParameterNotInSchema && importRequiredParameterNotInSchema.length > 0) {
-      throw new Error(`The following properties were declared in settings.import.requiredParameters but were not found in the schema:
-${JSON.stringify(importRequiredParameterNotInSchema, null, 2)}`)
+    if (this.settings.import) {
+      const { requiredParameters, refreshKeys, defaultRefreshValues } = this.settings.import;
+
+      const requiredParametersNotInSchema = requiredParameters
+        ?.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)}`)
+      }
+
+      const refreshKeyNotInSchema = refreshKeys
+        ?.filter(
+          (k) => schema && !(schema.properties[k])
+        )
+      if (schema && refreshKeyNotInSchema && refreshKeyNotInSchema.length > 0) {
+        throw new Error(`The following properties were declared in settings.import.refreshKeys but were not found in the schema:
+${JSON.stringify(requiredParametersNotInSchema, null, 2)}`)
+      }
+
+      const refreshValueNotInRefreshKey =
+        Object.entries(defaultRefreshValues ?? {})
+          .filter(
+            ([k]) => schema && !(schema.properties[k])
+          ).map(([k]) => k)
+
+      if (schema && refreshValueNotInRefreshKey.length > 0) {
+        throw new Error(`Properties declared in defaultRefreshValues must already be declared in refreshKeys:
+${JSON.stringify(refreshValueNotInRefreshKey, null, 2)}`)
+      }
     }
   }
 

package/src/resource/resource-controller.ts

@@ -190,19 +190,21 @@ export class ResourceController<T extends StringIndexedObject> {
     await this.applyTransformParameters(config);
 
     // Use refresh parameters if specified, otherwise try to refresh as many parameters as possible here
-    const parametersToRefresh = this.settings.import?.refreshParameters
+    const parametersToRefresh = this.settings.import?.refreshKeys
       ? {
         ...Object.fromEntries(
-          this.settings.import?.refreshParameters.map((k) => [k, null])
+          this.settings.import?.refreshKeys.map((k) => [k, null])
         ),
+        ...this.settings.import?.defaultRefreshValues,
         ...config,
       }
       : {
-      ...Object.fromEntries(
-        this.getAllParameterKeys().map((k) => [k, null])
-      ),
-      ...config,
-    };
+        ...Object.fromEntries(
+          this.getAllParameterKeys().map((k) => [k, null])
+        ),
+        ...this.settings.import?.defaultRefreshValues,
+        ...config,
+      };
 
     // Parse data from the user supplied config
     const parsedConfig = new ConfigParser(parametersToRefresh, null, this.parsedSettings.statefulParameters)

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

@@ -612,4 +612,21 @@ describe('Resource parameter tests', () => {
 
     expect(plan.changeSet.operation).to.eq(ResourceOperation.NOOP);
   })
+
+  it('Accepts an input parameters for imports', () => {
+    const resource = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'resourceType',
+          import: {
+            requiredParameters: ['propA'],
+            refreshKeys: ['propB', 'propA'],
+            defaultRefreshValues: {
+              propB: 6,
+            }
+          }
+        }
+      }
+    };
+  })
 })

package/src/resource/resource-settings.ts

@@ -65,10 +65,57 @@ 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>>;
 
-    refreshParameters?: 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>
   }
 }
 
@@ -164,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);
   })
 })