codify-plugin-lib 1.0.100 → 1.0.102

package/dist/index.d.ts

@@ -7,6 +7,6 @@ export * from './plugin/plugin.js';
 export * from './resource/parsed-resource-settings.js';
 export * from './resource/resource.js';
 export * from './resource/resource-settings.js';
-export * from './resource/stateful-parameter.js';
+export * from './stateful-parameter/stateful-parameter.js';
 export * from './utils/utils.js';
 export declare function runPlugin(plugin: Plugin): Promise<void>;

package/dist/index.js

@@ -7,7 +7,7 @@ export * from './plugin/plugin.js';
 export * from './resource/parsed-resource-settings.js';
 export * from './resource/resource.js';
 export * from './resource/resource-settings.js';
-export * from './resource/stateful-parameter.js';
+export * from './stateful-parameter/stateful-parameter.js';
 export * from './utils/utils.js';
 export async function runPlugin(plugin) {
     const messageHandler = new MessageHandler(plugin);

package/dist/plan/change-set.d.ts

@@ -1,5 +1,5 @@
 import { ParameterOperation, ResourceOperation, StringIndexedObject } from 'codify-schemas';
-import { ParameterSetting } from '../resource/resource-settings.js';
+import { ParsedParameterSetting } from '../resource/parsed-resource-settings.js';
 /**
  * A parameter change describes a parameter level change to a resource.
  */
@@ -30,7 +30,7 @@ export declare class ChangeSet<T extends StringIndexedObject> {
     static empty<T extends StringIndexedObject>(): ChangeSet<T>;
     static create<T extends StringIndexedObject>(desired: Partial<T>): ChangeSet<T>;
     static destroy<T extends StringIndexedObject>(current: Partial<T>): ChangeSet<T>;
-    static calculateModification<T extends StringIndexedObject>(desired: Partial<T>, current: Partial<T>, parameterSettings?: Partial<Record<keyof T, ParameterSetting>>): ChangeSet<T>;
+    static calculateModification<T extends StringIndexedObject>(desired: Partial<T>, current: Partial<T>, parameterSettings?: Partial<Record<keyof T, ParsedParameterSetting>>): ChangeSet<T>;
     /**
      * Calculates the differences between the desired and current parameters,
      * and returns a list of parameter changes that describe what needs to be added,

package/dist/plan/plan.js

@@ -144,10 +144,14 @@ export class Plan {
                 .filter(([k]) => keys.has(k)));
         }
         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)))
+            if (settings.parameterSettings?.[k]?.type === 'stateful') {
+                const statefulSetting = settings.parameterSettings[k];
+                return statefulSetting.nestedSettings.type === 'array' &&
+                    (statefulSetting.nestedSettings.filterInStatelessMode ?? true)
+                    && Array.isArray(v);
+            }
+            return 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
@@ -155,11 +159,10 @@ export class Plan {
             const desiredArray = desired[k];
             const matcher = settings.parameterSettings[k].type === 'stateful'
                 ? settings.parameterSettings[k]
-                    .definition
-                    .getSettings()
-                    .isElementEqual ?? ((a, b) => a === b)
+                    .nestedSettings
+                    .isElementEqual
                 : settings.parameterSettings[k]
-                    .isElementEqual ?? ((a, b) => a === b);
+                    .isElementEqual;
             const desiredCopy = [...desiredArray];
             const currentCopy = [...v];
             const result = [];

package/dist/resource/config-parser.d.ts

@@ -1,10 +1,10 @@
 import { ResourceConfig, StringIndexedObject } from 'codify-schemas';
-import { StatefulParameter } from './stateful-parameter.js';
+import { StatefulParameterController } from '../stateful-parameter/stateful-parameter-controller.js';
 export declare class ConfigParser<T extends StringIndexedObject> {
     private readonly desiredConfig;
     private readonly stateConfig;
     private statefulParametersMap;
-    constructor(desiredConfig: Partial<T> & ResourceConfig | null, stateConfig: Partial<T> & ResourceConfig | null, statefulParameters: Map<keyof T, StatefulParameter<T, T[keyof T]>>);
+    constructor(desiredConfig: Partial<T> & ResourceConfig | null, stateConfig: Partial<T> & ResourceConfig | null, statefulParameters: Map<keyof T, StatefulParameterController<T, T[keyof T]>>);
     get coreParameters(): ResourceConfig;
     get desiredParameters(): Partial<T> | null;
     get stateParameters(): Partial<T> | null;

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

@@ -1,6 +1,19 @@
 import { StringIndexedObject } from 'codify-schemas';
-import { ParameterSetting, ResourceSettings } from './resource-settings.js';
-import { StatefulParameter as StatefulParameterImpl } from './stateful-parameter.js';
+import { StatefulParameterController } from '../stateful-parameter/stateful-parameter-controller.js';
+import { ArrayParameterSetting, DefaultParameterSetting, ResourceSettings } from './resource-settings.js';
+export interface ParsedStatefulParameterSetting extends DefaultParameterSetting {
+    type: 'stateful';
+    controller: StatefulParameterController<any, unknown>;
+    order?: number;
+    nestedSettings: ParsedParameterSetting;
+}
+export type ParsedArrayParameterSetting = {
+    isElementEqual: (a: unknown, b: unknown) => boolean;
+    isEqual: (a: unknown, b: unknown) => boolean;
+} & ArrayParameterSetting;
+export type ParsedParameterSetting = {
+    isEqual: (desired: unknown, current: unknown) => boolean;
+} & (DefaultParameterSetting | ParsedArrayParameterSetting | ParsedStatefulParameterSetting);
 export declare class ParsedResourceSettings<T extends StringIndexedObject> implements ResourceSettings<T> {
     private cache;
     id: string;
@@ -14,8 +27,8 @@ export declare class ParsedResourceSettings<T extends StringIndexedObject> imple
     private settings;
     constructor(settings: ResourceSettings<T>);
     get typeId(): string;
-    get statefulParameters(): Map<keyof T, StatefulParameterImpl<T, T[keyof T]>>;
-    get parameterSettings(): Record<keyof T, ParameterSetting>;
+    get statefulParameters(): Map<keyof T, StatefulParameterController<T, T[keyof T]>>;
+    get parameterSettings(): Record<keyof T, ParsedParameterSetting>;
     get defaultValues(): Partial<Record<keyof T, unknown>>;
     get inputTransformations(): Partial<Record<keyof T, (a: unknown) => unknown>>;
     get statefulParameterOrder(): Map<keyof T, number>;

package/dist/resource/parsed-resource-settings.js

@@ -1,4 +1,5 @@
-import { resolveEqualsFn, resolveParameterTransformFn } from './resource-settings.js';
+import { StatefulParameterController } from '../stateful-parameter/stateful-parameter-controller.js';
+import { resolveEqualsFn, resolveFnFromEqualsFnOrString, resolveParameterTransformFn } from './resource-settings.js';
 export class ParsedResourceSettings {
     cache = new Map();
     id;
@@ -25,7 +26,10 @@ export class ParsedResourceSettings {
         return this.getFromCacheOrCreate('statefulParameters', () => {
             const statefulParameters = Object.entries(this.settings.parameterSettings ?? {})
                 .filter(([, p]) => p?.type === 'stateful')
-                .map(([k, v]) => [k, v.definition]);
+                .map(([k, v]) => [
+                k,
+                new StatefulParameterController(v.definition)
+            ]);
             return new Map(statefulParameters);
         });
     }
@@ -34,7 +38,25 @@ export class ParsedResourceSettings {
             const settings = Object.entries(this.settings.parameterSettings ?? {})
                 .map(([k, v]) => [k, v])
                 .map(([k, v]) => {
-                v.isEqual = resolveEqualsFn(v, k);
+                v.isEqual = resolveEqualsFn(v);
+                if (v.type === 'stateful') {
+                    const spController = this.statefulParameters.get(k);
+                    const parsed = {
+                        ...v,
+                        controller: spController,
+                        nestedSettings: spController?.parsedSettings,
+                        definition: undefined,
+                    };
+                    return [k, parsed];
+                }
+                if (v.type === 'array') {
+                    const parsed = {
+                        ...v,
+                        isElementEqual: resolveFnFromEqualsFnOrString(v.isElementEqual)
+                            ?? ((a, b) => a === b),
+                    };
+                    return [k, parsed];
+                }
                 return [k, v];
             });
             return Object.fromEntries(settings);

package/dist/resource/resource-controller.js

@@ -37,7 +37,8 @@ export class ResourceController {
         const { parameters, coreParameters } = splitUserConfig(configToValidate);
         this.addDefaultValues(parameters);
         if (this.schemaValidator) {
-            const isValid = this.schemaValidator(parameters);
+            // Schema validator uses pre transformation parameters
+            const isValid = this.schemaValidator(desiredConfig);
             if (!isValid) {
                 return {
                     isValid: false,

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

@@ -1,5 +1,5 @@
 import { StringIndexedObject } from 'codify-schemas';
-import { StatefulParameter } from './stateful-parameter.js';
+import { ArrayStatefulParameter, StatefulParameter } from '../stateful-parameter/stateful-parameter.js';
 /**
  * The configuration and settings for a resource.
  */
@@ -107,7 +107,7 @@ export interface ResourceSettings<T extends StringIndexedObject> {
  * config with desired config. Certain types will have additional options to help support it. For example the type
  * stateful requires a stateful parameter definition and type array takes an isElementEqual method.
  */
-export type ParameterSettingType = 'any' | 'array' | 'boolean' | 'directory' | 'number' | 'setting' | 'stateful' | 'string' | 'version';
+export type ParameterSettingType = 'any' | 'array' | 'boolean' | 'directory' | 'number' | 'object' | 'setting' | 'stateful' | 'string' | 'version';
 /**
  * Typing information for the parameter setting. This represents a setting on a specific parameter within a
  * resource. Options for configuring parameters operations including overriding the equals function, adding default values
@@ -146,7 +146,7 @@ export interface DefaultParameterSetting {
      *
      * @return Return true if equal
      */
-    isEqual?: (desired: any, current: any) => boolean;
+    isEqual?: ((desired: any, current: any) => boolean) | ParameterSettingType;
     /**
      * Chose if the resource can be modified instead of re-created when there is a change to this parameter.
      * Defaults to false (re-create).
@@ -172,7 +172,7 @@ export interface ArrayParameterSetting extends DefaultParameterSetting {
      *
      * @return Return true if desired is equivalent to current.
      */
-    isElementEqual?: (desired: any, current: any) => boolean;
+    isElementEqual?: ((desired: any, current: any) => boolean) | ParameterSettingType;
     /**
      * 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.
@@ -208,11 +208,12 @@ export interface StatefulParameterSetting extends DefaultParameterSetting {
      * as a resource and taps, formulas and casks are represented as a stateful parameter. A formula can be installed,
      * modified and removed (has state) but it is still tied to the overall lifecycle of homebrew.
      */
-    definition: StatefulParameter<any, unknown>;
+    definition: ArrayStatefulParameter<any, unknown> | StatefulParameter<any, unknown>;
     /**
      * The order multiple stateful parameters should be applied in. The order is applied in ascending order (1, 2, 3...).
      */
     order?: number;
 }
-export declare function resolveEqualsFn(parameter: ParameterSetting, key: string): (desired: unknown, current: unknown) => boolean;
+export declare function resolveEqualsFn(parameter: ParameterSetting): (desired: unknown, current: unknown) => boolean;
+export declare function resolveFnFromEqualsFnOrString(fnOrString: ((a: unknown, b: unknown) => boolean) | ParameterSettingType | undefined): ((a: unknown, b: unknown) => boolean) | undefined;
 export declare function resolveParameterTransformFn(parameter: ParameterSetting): ((input: any) => Promise<any> | any) | undefined;

package/dist/resource/resource-settings.js

@@ -1,3 +1,4 @@
+import isObjectsEqual from 'lodash.isequal';
 import path from 'node:path';
 import { areArraysEqual, untildify } from '../utils/utils.js';
 const ParameterEqualsDefaults = {
@@ -6,16 +7,31 @@ const ParameterEqualsDefaults = {
     'number': (a, b) => Number(a) === Number(b),
     'string': (a, b) => String(a) === String(b),
     'version': (desired, current) => String(current).includes(String(desired)),
-    'setting': (a, b) => true,
+    'setting': () => true,
+    'object': isObjectsEqual,
 };
-export function resolveEqualsFn(parameter, key) {
+export function resolveEqualsFn(parameter) {
+    const isEqual = resolveFnFromEqualsFnOrString(parameter.isEqual);
     if (parameter.type === 'array') {
-        return parameter.isEqual ?? areArraysEqual.bind(areArraysEqual, parameter);
+        const arrayParameter = parameter;
+        const isElementEqual = resolveFnFromEqualsFnOrString(arrayParameter.isElementEqual);
+        return isEqual ?? areArraysEqual.bind(areArraysEqual, isElementEqual);
     }
     if (parameter.type === 'stateful') {
-        return resolveEqualsFn(parameter.definition.getSettings(), key);
+        return resolveEqualsFn(parameter.definition.getSettings());
     }
-    return parameter.isEqual ?? ParameterEqualsDefaults[parameter.type] ?? (((a, b) => a === b));
+    return isEqual ?? ParameterEqualsDefaults[parameter.type] ?? (((a, b) => a === b));
+}
+// This resolves the fn if it is a string.
+// A string can be specified to use a default equals method
+export function resolveFnFromEqualsFnOrString(fnOrString) {
+    if (fnOrString && typeof fnOrString === 'string') {
+        if (!ParameterEqualsDefaults[fnOrString]) {
+            throw new Error(`isEqual of type ${fnOrString} was not found`);
+        }
+        return ParameterEqualsDefaults[fnOrString];
+    }
+    return fnOrString;
 }
 const ParameterTransformationDefaults = {
     'directory': (a) => path.resolve(untildify(String(a))),

package/dist/stateful-parameter/stateful-parameter-controller.d.ts

@@ -0,0 +1,21 @@
+import { StringIndexedObject } from 'codify-schemas';
+import { Plan } from '../plan/plan.js';
+import { ParsedParameterSetting } from '../resource/parsed-resource-settings.js';
+import { ParameterSetting } from '../resource/resource-settings.js';
+import { ArrayStatefulParameter, StatefulParameter } from './stateful-parameter.js';
+/**
+ * This class is analogous to what {@link ResourceController} is for {@link Resource}
+ * It's a bit messy because this class supports both {@link StatefulParameter} and {@link ArrayStatefulParameter}
+ */
+export declare class StatefulParameterController<T extends StringIndexedObject, V extends T[keyof T]> {
+    readonly sp: ArrayStatefulParameter<T, V> | StatefulParameter<T, V>;
+    readonly settings: ParameterSetting;
+    readonly parsedSettings: ParsedParameterSetting;
+    private readonly isArrayStatefulParameter;
+    constructor(statefulParameter: ArrayStatefulParameter<T, V> | StatefulParameter<T, V>);
+    refresh(desired: V | null, config: Partial<T>): Promise<V | null>;
+    add(valueToAdd: V, plan: Plan<T>): Promise<void>;
+    modify(newValue: V, previousValue: V, plan: Plan<T>): Promise<void>;
+    remove(valueToRemove: V, plan: Plan<T>): Promise<void>;
+    private calculateIsArrayStatefulParameter;
+}

package/dist/stateful-parameter/stateful-parameter-controller.js

@@ -0,0 +1,82 @@
+import { resolveEqualsFn, resolveFnFromEqualsFnOrString } from '../resource/resource-settings.js';
+/**
+ * This class is analogous to what {@link ResourceController} is for {@link Resource}
+ * It's a bit messy because this class supports both {@link StatefulParameter} and {@link ArrayStatefulParameter}
+ */
+export class StatefulParameterController {
+    sp;
+    settings;
+    parsedSettings;
+    isArrayStatefulParameter;
+    constructor(statefulParameter) {
+        this.sp = statefulParameter;
+        this.settings = statefulParameter.getSettings();
+        this.isArrayStatefulParameter = this.calculateIsArrayStatefulParameter();
+        this.parsedSettings = (this.isArrayStatefulParameter || this.settings.type === 'array') ? {
+            ...this.settings,
+            isEqual: resolveEqualsFn(this.settings),
+            isElementEqual: resolveFnFromEqualsFnOrString(this.settings.isElementEqual)
+                ?? ((a, b) => a === b)
+        } : {
+            ...this.settings,
+            isEqual: resolveEqualsFn(this.settings),
+        };
+    }
+    async refresh(desired, config) {
+        return await this.sp.refresh(desired, config);
+    }
+    async add(valueToAdd, plan) {
+        if (!this.isArrayStatefulParameter) {
+            const sp = this.sp;
+            return sp.add(valueToAdd, plan);
+        }
+        const sp = this.sp;
+        const valuesToAdd = valueToAdd;
+        for (const value of valuesToAdd) {
+            await sp.addItem(value, plan);
+        }
+    }
+    async modify(newValue, previousValue, plan) {
+        if (!this.isArrayStatefulParameter) {
+            const sp = this.sp;
+            return sp.modify(newValue, previousValue, plan);
+        }
+        const sp = this.sp;
+        const settings = this.parsedSettings;
+        const newValues = newValue;
+        const previousValues = previousValue;
+        // TODO: I don't think this works with duplicate elements. Solve at another time
+        const valuesToAdd = newValues.filter((n) => !previousValues.some((p) => {
+            if (settings.isElementEqual) {
+                return settings.isElementEqual(n, p);
+            }
+            return n === p;
+        }));
+        const valuesToRemove = previousValues.filter((p) => !newValues.some((n) => {
+            if (settings.isElementEqual) {
+                return settings.isElementEqual(n, p);
+            }
+            return n === p;
+        }));
+        for (const value of valuesToAdd) {
+            await sp.addItem(value, plan);
+        }
+        for (const value of valuesToRemove) {
+            await sp.removeItem(value, plan);
+        }
+    }
+    async remove(valueToRemove, plan) {
+        if (!this.isArrayStatefulParameter) {
+            const sp = this.sp;
+            return sp.remove(valueToRemove, plan);
+        }
+        const sp = this.sp;
+        const valuesToRemove = valueToRemove;
+        for (const value of valuesToRemove) {
+            await sp.removeItem(value, plan);
+        }
+    }
+    calculateIsArrayStatefulParameter() {
+        return Object.hasOwn(this.sp, 'addItem') && Object.hasOwn(this.sp, 'removeItem');
+    }
+}

package/dist/stateful-parameter/stateful-parameter.d.ts

@@ -0,0 +1,144 @@
+import { StringIndexedObject } from 'codify-schemas';
+import { Plan } from '../plan/plan.js';
+import { ArrayParameterSetting, ParameterSetting } from '../resource/resource-settings.js';
+/**
+ * A stateful parameter represents a parameter that holds state on the system (can be created, destroyed) but
+ * is still tied to the overall lifecycle of a resource.
+ *
+ * **Examples include:**
+ * 1. Homebrew formulas are stateful parameters. They can be installed and uninstalled but they are still tied to the
+ * overall lifecycle of homebrew
+ * 2. Nvm installed node versions are stateful parameters. Nvm can install and uninstall different versions of Node but
+ * these versions are tied to the lifecycle of nvm. If nvm is uninstalled then so are the Node versions.
+ */
+export declare abstract class StatefulParameter<T extends StringIndexedObject, V extends T[keyof T]> {
+    /**
+     * Parameter settings for the stateful parameter. Stateful parameters share the same parameter settings as
+     * regular parameters except that they cannot be of type 'stateful'. See {@link ParameterSetting} for more
+     * information on available settings.
+     *
+     * @return The parameter settings
+     */
+    getSettings(): ParameterSetting;
+    /**
+     * Refresh the status of the stateful parameter on the system. This method works similarly to {@link Resource.refresh}.
+     * Return the value of the stateful parameter or null if not found.
+     *
+     * @param desired The desired value of the user.
+     * @param config The desired config
+     *
+     * @return The value of the stateful parameter currently on the system or null if not found
+     */
+    abstract refresh(desired: V | null, config: Partial<T>): Promise<V | null>;
+    /**
+     * Create the stateful parameter on the system. This method is similar {@link Resource.create} except that its only
+     * applicable to the stateful parameter. For resource `CREATE` operations, this method will be called after the
+     * resource is successfully created. The add method is called when a ParameterChange is ADD in a plan. The add
+     * method is only called when the stateful parameter does not currently exist.
+     *
+     * **Example (Homebrew formula):**
+     * 1. Add is called with a value of:
+     * ```
+     * ['jq', 'jenv']
+     * ```
+     * 2. Add handles the request by calling `brew install --formulae jq jenv`
+     *
+     * @param valueToAdd The desired value of the stateful parameter.
+     * @param plan The overall plan that contains the ADD
+     */
+    abstract add(valueToAdd: V, plan: Plan<T>): Promise<void>;
+    /**
+     * Modify the state of a stateful parameter on the system. This method is similar to {@link Resource.modify} except that its only
+     * applicable to the stateful parameter.
+     *
+     * **Example (Git email parameter):**
+     * 1. Add is called with a value of:
+     * ```
+     * newValue: 'email+new@gmail.com', previousValue: 'email+old@gmail.com'
+     * ```
+     * 2. Modify handles the request by calling `git config --global user.email email+new@gmail.com`
+     *
+     * @param newValue The desired value of the stateful parameter
+     * @param previousValue The current value of the stateful parameter
+     * @param plan The overall plan
+     */
+    abstract modify(newValue: V, previousValue: V, plan: Plan<T>): Promise<void>;
+    /**
+     * Create the stateful parameter on the system. This method is similar {@link Resource.destroy} except that its only
+     * applicable to the stateful parameter. The remove method is only called when the stateful parameter already currently exist.
+     * This method corresponds to REMOVE parameter operations in a plan.
+     * For resource `DESTORY`, this method is only called if the {@link ResourceSettings.removeStatefulParametersBeforeDestroy}
+     * is set to true. This method will be called before the resource is destroyed.
+     *
+     * **Example (Homebrew formula):**
+     * 1. Remove is called with a value of:
+     * ```
+     * ['jq', 'jenv']
+     * ```
+     * 2. Remove handles the request by calling `brew uninstall --formulae jq jenv`
+     *
+     * @param valueToRemove The value to remove from the stateful parameter.
+     * @param plan The overall plan that contains the REMOVE
+     */
+    abstract remove(valueToRemove: V, plan: Plan<T>): Promise<void>;
+}
+/**
+ * A specialized version of {@link StatefulParameter } that is used for stateful parameters which are arrays.
+ * A stateful parameter represents a parameter that holds state on the system (can be created, destroyed) but
+ * is still tied to the overall lifecycle of a resource.
+ *
+ * **Examples:**
+ * - Homebrew formulas are arrays
+ * - Pyenv python versions are arrays
+ */
+export declare abstract class ArrayStatefulParameter<T extends StringIndexedObject, V> {
+    /**
+     * Parameter settings for the stateful parameter. Stateful parameters share the same parameter settings as
+     * regular parameters except that they cannot be of type 'stateful'. See {@link ParameterSetting} for more
+     * information on available settings. Type must be 'array'.
+     *
+     * @return The parameter settings
+     */
+    getSettings(): ArrayParameterSetting;
+    /**
+     * See {@link StatefulParameter.refresh} for more info.
+     *
+     * @param desired The desired value to refresh
+     * @param config The desired config
+     *
+     * @return The current value on the system or null if not found.
+     */
+    abstract refresh(desired: V[] | null, config: Partial<T>): Promise<V[] | null>;
+    /**
+     * Helper method that gets called when individual elements of the array need to be added. See {@link StatefulParameter.add}
+     * for more information.
+     *
+     * Example (Homebrew formula):
+     * 1. The stateful parameter receives an input of:
+     * ```
+     * ['jq', 'jenv', 'docker']
+     * ```
+     * 2. Internally the stateful parameter will iterate the array and call `addItem` for each element
+     * 3. Override addItem and install each formula using `brew install --formula jq`
+     *
+     * @param item The item to add (install)
+     * @param plan The overall plan
+     */
+    abstract addItem(item: V, plan: Plan<T>): Promise<void>;
+    /**
+     * Helper method that gets called when individual elements of the array need to be removed. See {@link StatefulParameter.remove}
+     * for more information.
+     *
+     * Example (Homebrew formula):
+     * 1. The stateful parameter receives an input of:
+     * ```
+     * ['jq', 'jenv', 'docker']
+     * ```
+     * 2. Internally the stateful parameter will iterate the array and call `removeItem` for each element
+     * 3. Override removeItem and uninstall each formula using `brew uninstall --formula jq`
+     *
+     * @param item The item to remove (uninstall)
+     * @param plan The overall plan
+     */
+    abstract removeItem(item: V, plan: Plan<T>): Promise<void>;
+}

package/dist/stateful-parameter/stateful-parameter.js

@@ -0,0 +1,43 @@
+/**
+ * A stateful parameter represents a parameter that holds state on the system (can be created, destroyed) but
+ * is still tied to the overall lifecycle of a resource.
+ *
+ * **Examples include:**
+ * 1. Homebrew formulas are stateful parameters. They can be installed and uninstalled but they are still tied to the
+ * overall lifecycle of homebrew
+ * 2. Nvm installed node versions are stateful parameters. Nvm can install and uninstall different versions of Node but
+ * these versions are tied to the lifecycle of nvm. If nvm is uninstalled then so are the Node versions.
+ */
+export class StatefulParameter {
+    /**
+     * Parameter settings for the stateful parameter. Stateful parameters share the same parameter settings as
+     * regular parameters except that they cannot be of type 'stateful'. See {@link ParameterSetting} for more
+     * information on available settings.
+     *
+     * @return The parameter settings
+     */
+    getSettings() {
+        return {};
+    }
+}
+/**
+ * A specialized version of {@link StatefulParameter } that is used for stateful parameters which are arrays.
+ * A stateful parameter represents a parameter that holds state on the system (can be created, destroyed) but
+ * is still tied to the overall lifecycle of a resource.
+ *
+ * **Examples:**
+ * - Homebrew formulas are arrays
+ * - Pyenv python versions are arrays
+ */
+export class ArrayStatefulParameter {
+    /**
+     * Parameter settings for the stateful parameter. Stateful parameters share the same parameter settings as
+     * regular parameters except that they cannot be of type 'stateful'. See {@link ParameterSetting} for more
+     * information on available settings. Type must be 'array'.
+     *
+     * @return The parameter settings
+     */
+    getSettings() {
+        return { type: 'array' };
+    }
+}

package/dist/utils/utils.d.ts

@@ -1,7 +1,6 @@
 /// <reference types="node" resolution-mode="require"/>
 import { ResourceConfig, StringIndexedObject } from 'codify-schemas';
 import { SpawnOptions } from 'node:child_process';
-import { ArrayParameterSetting } from '../resource/resource-settings.js';
 export declare enum SpawnStatus {
     SUCCESS = "success",
     ERROR = "error"
@@ -37,5 +36,5 @@ export declare function splitUserConfig<T extends StringIndexedObject>(config: R
 };
 export declare function setsEqual(set1: Set<unknown>, set2: Set<unknown>): boolean;
 export declare function untildify(pathWithTilde: string): string;
-export declare function areArraysEqual(parameter: ArrayParameterSetting, desired: unknown, current: unknown): boolean;
+export declare function areArraysEqual(isElementEqual: ((desired: unknown, current: unknown) => boolean) | undefined, desired: unknown, current: unknown): boolean;
 export {};

package/dist/utils/utils.js

@@ -72,7 +72,7 @@ const homeDirectory = os.homedir();
 export function untildify(pathWithTilde) {
     return homeDirectory ? pathWithTilde.replace(/^~(?=$|\/|\\)/, homeDirectory) : pathWithTilde;
 }
-export function areArraysEqual(parameter, desired, current) {
+export function areArraysEqual(isElementEqual, desired, current) {
     if (!Array.isArray(desired) || !Array.isArray(current)) {
         throw new Error(`A non-array value:
           
@@ -91,7 +91,8 @@ Was provided even though type array was specified.
     // Algorithm for to check equality between two un-ordered; un-hashable arrays using
     // an isElementEqual method. Time: O(n^2)
     for (let counter = desiredCopy.length - 1; counter >= 0; counter--) {
-        const idx = currentCopy.findIndex((e2) => (parameter.isElementEqual ?? ((a, b) => a === b))(desiredCopy[counter], e2));
+        const idx = currentCopy.findIndex((e2) => (isElementEqual
+            ?? ((a, b) => a === b))(desiredCopy[counter], e2));
         if (idx === -1) {
             return false;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codify-plugin-lib",
-  "version": "1.0.100",
+  "version": "1.0.102",
   "description": "Library plugin library",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -16,7 +16,8 @@
     "ajv-formats": "^2.1.1",
     "codify-schemas": "1.0.52",
     "@npmcli/promise-spawn": "^7.0.1",
-    "uuid": "^10.0.0"
+    "uuid": "^10.0.0",
+    "lodash.isequal": "^4.5.0"
   },
   "devDependencies": {
     "@oclif/prettier-config": "^0.2.1",
@@ -26,6 +27,7 @@
     "@types/semver": "^7.5.4",
     "@types/sinon": "^17.0.3",
     "@types/uuid": "^10.0.0",
+    "@types/lodash.isequal": "^4.5.8",
     "chai-as-promised": "^7.1.1",
     "vitest": "^1.4.0",
     "vitest-mock-extended": "^1.3.1",

package/src/index.ts

@@ -9,7 +9,7 @@ export * from './plugin/plugin.js'
 export * from './resource/parsed-resource-settings.js';
 export * from './resource/resource.js'
 export * from './resource/resource-settings.js'
-export * from './resource/stateful-parameter.js'
+export * from './stateful-parameter/stateful-parameter.js'
 export * from './utils/utils.js'
 
 export async function runPlugin(plugin: Plugin) {