Refactor: create options types (#188)

docs/_config.yml

@@ -1,4 +1,4 @@
-title: Fabricate 0.9.12
+title: Fabricate 0.10.0
 email: [email protected]
 description: >- 
   End user documentation for the Foundry Virtual Tabletop (VTT) Module, "Fabricate".

docs/api/components.md

@@ -362,24 +362,19 @@ interface Component extends Identifiable, Serializable<ComponentJson> {
     readonly hasEssences: boolean;
 
     /**
-     * The essences that this component contains, if any. May be an empty Combination.
+     * The essences that this component contains, if any. Might be an empty Combination.
      */
     essences: Combination<EssenceReference>;
 
     /**
-     * Indicates whether this component is disabled. Disabled components cannot used in crafting.
+     * Indicates whether this component is disabled. Disabled components cannot be used in crafting.
      */
     isDisabled: boolean;
 
     /**
      * The Salvage options for this component
      */
-    salvageOptions: SelectableOptions<SalvageOptionJson, SalvageOption>;
-
-    /**
-     * The Salvage options for this component, indexed by ID
-     */
-    readonly salvageOptionsById: Map<string, SalvageOption>;
+    salvageOptions: Options<Salvage>;
 
     /**
      * The Fabricate item data for this component, containing the item's name, image URL, and any errors that occurred
@@ -393,16 +388,6 @@ interface Component extends Identifiable, Serializable<ComponentJson> {
      */
     readonly hasErrors: boolean;
 
-    /**
-     * The errors that occurred while loading the item data, if any. May be an empty array.
-     */
-    readonly errors: ItemLoadingError[];
-
-    /**
-     * The codes for the errors that occurred while loading the item data, if any. May be an empty array.
-     */
-    readonly errorCodes: string[];
-
     /**
      * Indicates whether this component's item data has been loaded
      */
@@ -434,10 +419,10 @@ interface Component extends Identifiable, Serializable<ComponentJson> {
      * Sets the Salvage option for this component. If the Salvage option has an ID, it will be used to attempt to
      * overwrite an existing salvage option. Otherwise, a new Salvage option will be created with a new ID.
      *
-     * @param {SalvageOptionConfig | SalvageOption} salvageOption - The Salvage option to set. Accepts a SalvageOption
-     *  instance or a SalvageOptionConfig object.
+     * @param {SerializableOption<SalvageJson, Salvage> | SalvageOptionConfig} salvageOption - The Salvage option to set.
+     *  Accepts a SerializableOption instance or a SalvageOptionConfig object.
      */
-    setSalvageOption(salvageOption: SalvageOptionConfig | SalvageOption): void;
+    setSalvageOption(salvageOption: SerializableOption<SalvageJson, Salvage> | SalvageOptionConfig): void;
 
     /**
      * Adds the given quantity of the essence with the given ID to this component
@@ -456,14 +441,14 @@ interface Component extends Identifiable, Serializable<ComponentJson> {
     subtractEssence(essenceId: string, quantity?: number): void;
 
     /**
-     * Lists all the components referenced by this component's Salvage options. May be an empty array.
+     * Lists all the components referenced by this component's Salvage options. Might be an empty array.
      *
      * @returns {ComponentReference[]} - The components referenced by this component, if any
      */
     getUniqueReferencedComponents(): ComponentReference[];
 
     /**
-     * Lists all the essences referenced by this component. May be an empty array.
+     * Lists all the essences referenced by this component. Might be an empty array.
      *
      * @returns {EssenceReference[]} - The essences referenced by this component, if any
      */

docs/api/recipe.md

@@ -245,12 +245,6 @@ interface RecipeOptions {
      * */
     craftingSystemId: string;
 
-    /**
-     * Optional dictionary of the essences required for the recipe. The dictionary is keyed on the essence ID and with
-     * the values representing the required quantities.
-     */
-    essences?: Record<string, number>;
-
     /**
      * Whether the recipe is disabled. Defaults to false.
      */
@@ -390,14 +384,14 @@ interface Recipe extends Identifiable, Serializable<RecipeJson> {
     itemData: FabricateItemData;
 
     /**
-     * The options for the requirements of this recipe. May be empty.
+     * The options for the requirements of this recipe
      */
-    readonly requirementOptions: SelectableOptions<RequirementOptionJson, RequirementOption>;
+    readonly requirementOptions: SerializableOptions<RequirementJson, Requirement>;
 
     /**
-     * The options for the results of this recipe. May be empty.
+     * The options for the results of this recipe
      */
-    readonly resultOptions: SelectableOptions<ResultOptionJson, ResultOption>;
+    readonly resultOptions: SerializableOptions<ResultJson, Result>;
 
     /**
      * Whether this recipe has any requirement options. This is a convenience function for checking if the requirement
@@ -436,37 +430,30 @@ interface Recipe extends Identifiable, Serializable<RecipeJson> {
     readonly hasErrors: boolean;
 
     /**
-     * The codes for the errors that occurred while loading the item data, if any. May be an empty array.
-     */
-    readonly errorCodes: string[];
-
-    /**
-     * The errors that occurred while loading the item data, if any. May be an empty array.
-     */
-    readonly errors: ItemLoadingError[];
-
-    /**
-     * Indicates whether this recipe's item data has been loaded
+     * Indicates whether this recipe's item data has been loaded. This is a convenience function for checking if the
+     *  item data has been loaded.
      */
     readonly loaded: boolean;
 
     /**
      * Sets the result option for this recipe. If the result option has an ID, it will be used to attempt to overwrite
      * an existing result option. Otherwise, a new result option will be created with a new ID.
      *
-     * @param {ResultOptionConfig | ResultOption} resultOption - The result option to set. Accepts a ResultOption
-     *  instance or a ResultOptionConfig object.
+     * @param {SerializableOption<ResultJson, Result> | Option<Result>} resultOption - The result option to set. Accepts a
+     * SerializableOption instance or a ResultOptionConfig object. ResultOptionConfig is deprecated and will be removed
+     * in a future version.
      */
-    setResultOption(resultOption: ResultOptionConfig | ResultOption): void;
+    setResultOption(resultOption: SerializableOption<ResultJson, Result> | ResultOptionConfig): void;
 
     /**
      * Sets the requirement option for this recipe. If the requirement option has an ID, it will be used to attempt to
      * overwrite an existing requirement option. Otherwise, a new requirement option will be created with a new ID.
      *
-     * @param {RequirementOptionConfig | RequirementOption} requirementOption - The requirement option to set. Accepts
-     * a RequirementOption instance or a RequirementOptionConfig object.
+     * @param {SerializableOption<RequirementJson, Requirement> | RequirementOptionConfig} requirementOption - The requirement option
+     * to set. Accepts a SerializableOption instance or a RequirementOptionConfig object. RequirementOptionConfig is deprecated
+     * and will be removed in a future version.
      */
-    setRequirementOption(requirementOption: RequirementOptionConfig | RequirementOption): void;
+    setRequirementOption(requirementOption: SerializableOption<RequirementJson, Requirement> | RequirementOptionConfig): void;
 
     /**
      * Deletes the result option with the given ID from this recipe
@@ -501,7 +488,7 @@ interface Recipe extends Identifiable, Serializable<RecipeJson> {
         craftingSystemId,
         substituteEssenceIds,
         substituteComponentIds,
-      }: {
+    }: {
         id: string;
         craftingSystemId?: string;
         substituteEssenceIds?: Map<string, string>;
@@ -577,6 +564,80 @@ interface Recipe extends Identifiable, Serializable<RecipeJson> {
 
 </details>
 
+<details markdown="block">
+<summary>
+RequirementOptionConfig interface
+</summary>
+
+```typescript
+/**
+ * The RequirementOptionConfig interface. This interface is used to define the structure of the JSON object used to
+ *   define a requirement option without instantiating one directly.
+ */
+interface RequirementOptionConfig {
+
+    /**
+     * The ID of the requirement option. If not provided, a new ID will be generated.
+     */
+    id?: string,
+
+    /**
+     * The display name of the requirement option
+     */
+    name: string,
+
+    /**
+     * The type and number of catalyst components required by this requirement option, keyed on the component ID
+     */
+    catalysts?: Record<string, number>;
+
+    /**
+     * The type and number of ingredient components required by this requirement option, keyed on the component ID
+     */
+    ingredients?: Record<string, number>;
+
+    /**
+     * The type and number of essences required by this requirement option, keyed on the essence ID
+     */
+    essences?: Record<string, number>;
+
+}
+```
+
+</details>
+
+<details markdown="block">
+<summary>
+ResultOptionConfig interface
+</summary>
+
+```typescript
+/**
+ * The ResultOptionConfig interface. This interface is used to define the structure of the JSON object used to define
+ *  a result option without instantiating one directly.
+ */
+interface ResultOptionConfig {
+
+    /**
+     * The ID of the result option. If not provided, a new ID will be generated.
+     */
+    id?: string;
+
+    /**
+     * The display name of the result option
+     */
+    name: string;
+
+    /**
+     * The type and number of components produced by this result option, keyed on the component ID
+     */
+    results: Record<string, number>;
+
+}
+```
+
+</details>
+
 ## Examples 
 
 The examples below illustrate how to use the recipe API to create, modify and delete recipes.

docs/api/types.md

@@ -442,6 +442,141 @@ interface ComponentSelection {
 
 </details>
 
+## Options
+
+An `Options` object is used to specify the options for a crafting operation.
+
+<details markdown="block">
+<summary>
+The Options interface
+</summary>
+
+```typescript
+/**
+ * A collection of options.
+ */
+interface Options<T> {
+
+    /**
+     * All options.
+     */
+    readonly all: Option<T>[];
+
+    /**
+     * The number of options.
+     */
+    readonly size: number;
+
+    /**
+     * Whether there are no options.
+     */
+    readonly isEmpty: boolean;
+
+    /**
+     * A map of options by id.
+     */
+    readonly byId: Map<string, Option<T>>;
+
+    /**
+     * Set an option. If the option has no ID one will be generated. If the option has an ID and an option with that ID
+     * already exists it will be replaced.
+     * 
+     * @param option - The option to set.
+     */
+    set(option: Option<T>): void;
+
+    /**
+     * Get an option by ID.
+     * 
+     * @param id - The ID of the option.
+     * @returns Option<T> The option or undefined if no option with the given ID exists.
+     */
+    get(id: string): Option<T>;
+
+    /**
+     * Remove an option.
+     * 
+     * @param option - The id of the option to remove or the  option itself.
+     */
+    remove(option: string | Option<T>): void;
+
+    /**
+     * Whether an option exists.
+     * 
+     * @param option - The id of the option to check or the option itself.
+     */
+    has(option: string | Option<T>): boolean;
+
+    /**
+     * Clone the options.
+     */
+    clone(): Options<T>;
+
+    /**
+     * Whether the options are equal to another set of options.
+     * 
+     * @param other - The other options.
+     * @returns boolean Whether the options are equal.
+     */
+    equals(other: Options<T>): boolean;
+
+}
+```
+
+</details>
+
+## Option
+
+An `Option` is a data structure that represents a single option for a crafting operation.
+
+<details markdown="block">
+<summary>
+The Option interface
+</summary>
+
+```typescript
+/**
+ * An option.
+ */
+interface Option<T> extends Identifiable {
+
+    /**
+     * The unique id of the option within the set of options.
+     */
+    id: string;
+
+    /**
+     * The display name of the option.
+     */
+    name: string;
+
+    /**
+     * The value (or contents) of the option.
+     */
+    value: T;
+
+    /**
+     * Clone the option.
+     *
+     * @param id - The id of the cloned option.
+     * @returns Option<T> The cloned option.
+     */
+    clone(id: string): Option<T>;
+
+    /**
+     * Whether the option is equal to another option.
+     *
+     * @param other - The other option.
+     * @returns boolean Whether the options are equal.
+     */
+    equals(other: Option<T>): boolean;
+
+}
+```
+
+</details>
+
+