@tmlmt/cooklang-parser 2.0.0 → 2.0.1

package/dist/index.d.ts

@@ -1,11 +1,16 @@
 /**
  * Represents a recipe section
- * Wrapped as a Class and not as a simple type to expose some useful helper
- * classes (e.g. `isBlank()`)
+ *
+ * Wrapped as a _Class_ and not defined as a simple _Type_ to expose some useful helper
+ * classes (e.g. {@link Section.isBlank | isBlank()})
+ *
  * @category Types
  */
 declare class Section {
-    /** The name of the section. Can be an empty string for the default (first) section. */
+    /**
+     * The name of the section. Can be an empty string for the default (first) section.
+     * @defaultValue `""`
+     */
     name: string;
     /** An array of steps and notes that make up the content of the section. */
     content: (Step | Note)[];
@@ -23,37 +28,63 @@ declare class Section {
 }
 
 /**
- * Represents a recipe.
+ * Recipe parser.
+ *
+ * ## Usage
+ *
+ * You can either directly provide the recipe string when creating the instance
+ * e.g. `const recipe = new Recipe('Add @eggs{3}')`, or create it first and then pass
+ * the recipe string to the {@link Recipe.parse | parse()} method.
+ *
+ * Look at the [properties](#properties) to see how the recipe's properties are parsed.
+ *
  * @category Classes
+ *
+ * @example
+ * ```typescript
+ * import { Recipe } from "@tmlmt/cooklang-parser";
+ *
+ * const recipeString = `
+ * ---
+ * title: Pancakes
+ * tags: [breakfast, easy]
+ * ---
+ * Crack the @eggs{3} with @flour{100%g} and @milk{200%mL}
+ *
+ * Melt some @butter{50%g} in a #pan on medium heat.
+ *
+ * Cook for ~{5%minutes} on each side.
+ * `
+ * const recipe = new Recipe(recipeString);
+ * ```
  */
 declare class Recipe {
     /**
-     * The recipe's metadata.
-     * @see {@link Metadata}
+     * The parsed recipe metadata.
      */
     metadata: Metadata;
     /**
-     * The recipe's ingredients.
-     * @see {@link Ingredient}
+     * The parsed recipe ingredients.
      */
     ingredients: Ingredient[];
     /**
-     * The recipe's sections.
-     * @see {@link Section}
+     * The parsed recipe sections.
      */
     sections: Section[];
     /**
-     * The recipe's cookware.
-     * @see {@link Cookware}
+     * The parsed recipe cookware.
      */
     cookware: Cookware[];
     /**
-     * The recipe's timers.
-     * @see {@link Timer}
+     * The parsed recipe timers.
      */
     timers: Timer[];
     /**
-     * The recipe's servings. Used for scaling
+     * The parsed recipe servings. Used for scaling. Parsed from one of
+     * {@link Metadata.servings}, {@link Metadata.yield} or {@link Metadata.serves}
+     * metadata fields.
+     *
+     * @see {@link Recipe.scaleBy | scaleBy()} and {@link Recipe.scaleTo | scaleTo()} methods
      */
     servings?: number;
     /**
@@ -67,9 +98,12 @@ declare class Recipe {
      */
     parse(content: string): void;
     /**
-     * Scales the recipe to a new number of servings.
+     * Scales the recipe to a new number of servings. In practice, it calls
+     * {@link Recipe.scaleBy | scaleBy} with a factor corresponding to the ratio between `newServings`
+     *   and the recipe's {@link Recipe.servings | servings} value.
      * @param newServings - The new number of servings.
      * @returns A new Recipe instance with the scaled ingredients.
+     * @throws `Error` if the recipe does not contains an initial {@link Recipe.servings | servings} value
      */
     scaleTo(newServings: number): Recipe;
     /**
@@ -91,6 +125,11 @@ declare class Recipe {
     clone(): Recipe;
 }
 
+interface Quantity {
+    value: FixedValue | Range;
+    unit?: string;
+}
+
 /**
  * Represents the metadata of a recipe.
  * @category Types
@@ -102,26 +141,62 @@ interface Metadata {
     tags?: string[];
     /** The source of the recipe. */
     source?: string;
+    /** The source name of the recipe. */
+    "source.name"?: string;
+    /** The source url of the recipe. */
+    "source.url"?: string;
+    /** The source author of the recipe. */
+    "source.author"?: string;
     /** The author of the recipe. */
     author?: string;
     /** The number of servings the recipe makes.
-     * Complex info can be given, as long as the first part before a comma has a numerical value, which will be used for scaling
-     * Interchangeable with `yield` or `serves`. If multiple ones are defined, the latest one will be used for scaling */
-    servings?: string;
+     * Should be either a number or a string which starts with a number
+     * (which will be used for scaling) followed by a comma and then
+     * whatever you want.
+     *
+     * Interchangeable with `yield` or `serves`. If multiple ones are defined,
+     * the prevailance order for the number which will used for scaling
+     * is `servings` \> `yield` \> `serves`.
+     *
+     * @example
+     * ```yaml
+     * servings: 4
+     * ```
+     *
+     * @example
+     * ```yaml
+     * servings: 2, a few
+     * ```
+     */
+    servings?: number | string;
     /** The yield of the recipe.
-     *  Complex info can be given, as long as the first part before a comma has a numerical value, which will be used for scaling
-     *  Interchangeable with `servings` or `serves`. If multiple ones are defined, the latest one will be used for scaling
-     */
-    yield?: string;
+     * Should be either a number or a string which starts with a number
+     * (which will be used for scaling) followed by a comma and then
+     * whatever you want.
+     *
+     * Interchangeable with `servings` or `serves`. If multiple ones are defined,
+     * the prevailance order for the number which will used for scaling
+     * is `servings` \> `yield` \> `serves`. See {@link Metadata.servings | servings}
+     * for examples.
+     */
+    yield?: number | string;
     /** The number of people the recipe serves.
-     *  Complex info can be given, as long as the first part before a comma has a numerical value, which will be used for scaling
-     *  Interchangeable with `servings` or `yield`. If multiple ones are defined, the latest one will be used for scaling
-     */
-    serves?: string;
+     * Should be either a number or a string which starts with a number
+     * (which will be used for scaling) followed by a comma and then
+     * whatever you want.
+     *
+     * Interchangeable with `servings` or `yield`. If multiple ones are defined,
+     * the prevailance order for the number which will used for scaling
+     * is `servings` \> `yield` \> `serves`. See {@link Metadata.servings | servings}
+     * for examples.
+     */
+    serves?: number | string;
     /** The course of the recipe. */
     course?: string;
     /** The category of the recipe. */
     category?: string;
+    /** The locale of the recipe. */
+    locale?: string;
     /**
      *  The preparation time of the recipe.
      *  Will not be further parsed into any DateTime format nor normalize
@@ -155,18 +230,16 @@ interface Metadata {
     diet?: string;
     /** The description of the recipe. */
     description?: string;
-    /** The images of the recipe. */
+    /** The images of the recipe. Alias of `pictures` */
     images?: string[];
-}
-/**
- * Represents the extracted metadata from a recipe.
- * @category Types
- */
-interface MetadataExtract {
-    /** The metadata of the recipe. */
-    metadata: Metadata;
-    /** The number of servings the recipe makes. Used for scaling */
-    servings?: number;
+    /** The images of the recipe. Alias of `images` */
+    pictures?: string[];
+    /** The picture of the recipe. Alias of `picture` */
+    image?: string;
+    /** The picture of the recipe. Alias of `image` */
+    picture?: string;
+    /** The introduction of the recipe. */
+    introduction?: string;
 }
 /**
  * Represents a quantity described by text, e.g. "a pinch"
@@ -213,6 +286,41 @@ interface Range {
     min: DecimalValue | FractionValue;
     max: DecimalValue | FractionValue;
 }
+/**
+ * Represents a contributor to an ingredient's total quantity
+ * @category Types
+ */
+interface QuantityPart extends Quantity {
+    /** - If _true_, the quantity will scale
+     * - If _false_, the quantity is fixed
+     */
+    scalable: boolean;
+}
+/**
+ * Represents a possible state modifier or other flag for an ingredient in a recipe
+ * @category Types
+ */
+type IngredientFlag = "optional" | "hidden" | "recipe";
+/**
+ * Represents the collection of possible additional metadata for an ingredient in a recipe
+ * @category Types
+ */
+interface IngredientExtras {
+    /**
+     * The path of the ingredient-recipe, relative to the present recipe
+     * Used if: the ingredient is a recipe
+     *
+     * @example
+     * ```cooklang
+     * Take @./essentials/doughs/pizza dough{1} out of the freezer and let it unfreeze overnight
+     * ```
+     * Would lead to:
+     * ```yaml
+     * path: 'essentials/doughts/pizza dough.cook'
+     * ```
+     */
+    path: string;
+}
 /**
  * Represents an ingredient in a recipe.
  * @category Types
@@ -224,14 +332,14 @@ interface Ingredient {
     quantity?: FixedValue | Range;
     /** The unit of the ingredient. */
     unit?: string;
+    /** The array of contributors to the ingredient's total quantity. */
+    quantityParts?: QuantityPart[];
     /** The preparation of the ingredient. */
     preparation?: string;
-    /** Whether the ingredient is optional. */
-    optional?: boolean;
-    /** Whether the ingredient is hidden. */
-    hidden?: boolean;
-    /** Whether the ingredient is a recipe. */
-    isRecipe?: boolean;
+    /** A list of potential state modifiers or other flags for the ingredient */
+    flags?: IngredientFlag[];
+    /** The collection of potential additional metadata for the ingredient */
+    extras?: IngredientExtras;
 }
 /**
  * Represents a timer in a recipe.
@@ -252,7 +360,7 @@ interface Timer {
 interface TextItem {
     /** The type of the item. */
     type: "text";
-    /** The value of the item. */
+    /** The content of the text item. */
     value: string;
 }
 /**
@@ -262,14 +370,14 @@ interface TextItem {
 interface IngredientItem {
     /** The type of the item. */
     type: "ingredient";
-    /** The value of the item. */
-    value: number;
-    /** The alias/name of the ingredient as it should be displayed in the preparation */
+    /** The index of the ingredient, within the {@link Recipe.ingredients | list of ingredients} */
+    index: number;
+    /** Index of the quantity part corresponding to this item / this occurence
+     * of the ingredient, which may be referenced elsewhere. */
+    quantityPartIndex?: number;
+    /** The alias/name of the ingredient as it should be displayed in the preparation
+     * for this occurence */
     displayName: string;
-    /** Quantity specific to this step item for this ingredient which may also be referenced elsewhere */
-    itemQuantity?: FixedValue | Range;
-    /** Unit specific to this step item for this ingredient which may also be referenced elsewhere */
-    itemUnit?: string;
 }
 /**
  * Represents a cookware item in a recipe step.
@@ -278,10 +386,11 @@ interface IngredientItem {
 interface CookwareItem {
     /** The type of the item. */
     type: "cookware";
-    /** The value of the item. */
-    value: number;
-    /** Quantity specific to this step item for this cookware which may also be referenced elsewhere */
-    itemQuantity?: FixedValue | Range;
+    /** The index of the cookware, within the {@link Recipe.cookware | list of cookware} */
+    index: number;
+    /** Index of the quantity part corresponding to this item / this occurence
+     * of the cookware, which may be referenced elsewhere. */
+    quantityPartIndex?: number;
 }
 /**
  * Represents a timer item in a recipe step.
@@ -290,8 +399,8 @@ interface CookwareItem {
 interface TimerItem {
     /** The type of the item. */
     type: "timer";
-    /** The value of the item. */
-    value: number;
+    /** The index of the timer, within the {@link Recipe.timers | list of timers} */
+    index: number;
 }
 /**
  * Represents an item in a recipe step.
@@ -316,6 +425,11 @@ interface Note {
     /** The content of the note. */
     note: string;
 }
+/**
+ * Represents a possible state modifier or other flag for cookware used in a recipe
+ * @category Types
+ */
+type CookwareFlag = "optional" | "hidden";
 /**
  * Represents a piece of cookware in a recipe.
  * @category Types
@@ -325,17 +439,16 @@ interface Cookware {
     name: string;
     /** The quantity of cookware */
     quantity?: FixedValue | Range;
-    /** Whether the cookware is optional. */
-    optional?: boolean;
-    /** Whether the cookware is hidden. */
-    hidden?: boolean;
+    /** The array of contributors to the cookware's total quantity. */
+    quantityParts?: (FixedValue | Range)[];
+    /** A list of potential state modifiers or other flags for the cookware */
+    flags: CookwareFlag[];
 }
 /**
  * Represents categorized ingredients.
  * @category Types
  */
 interface CategorizedIngredients {
-    /** The category of the ingredients. */
     [category: string]: Ingredient[];
 }
 /**
@@ -349,100 +462,148 @@ interface AddedRecipe {
     factor: number;
 }
 /**
- * Represents an ingredient in an aisle.
+ * Represents an ingredient in a category.
  * @category Types
  */
-interface AisleIngredient {
+interface CategoryIngredient {
     /** The name of the ingredient. */
     name: string;
     /** The aliases of the ingredient. */
     aliases: string[];
 }
 /**
- * Represents a category of aisles.
+ * Represents a category of ingredients.
  * @category Types
  */
-interface AisleCategory {
+interface Category {
     /** The name of the category. */
     name: string;
     /** The ingredients in the category. */
-    ingredients: AisleIngredient[];
+    ingredients: CategoryIngredient[];
 }
 
 /**
- * Represents the aisle configuration for a shopping list.
+ * Parser for category configurations specified à-la-cooklang.
+ *
+ * ## Usage
+ *
+ * You can either directly provide the category configuration string when creating the instance
+ * e.g. `const categoryConfig = new CategoryConfig(<...>)`, or create it first and then pass
+ * the category configuration string to the {@link CategoryConfig.parse | parse()} method.
+ *
+ * The initialized `CategoryConfig` can then be fed to a {@link ShoppingList}
+ *
+ * @example
+ * ```typescript
+ * import { CategoryConfig } from @tmlmt/cooklang-parser;
+ *
+ * const categoryConfigString = `
+ * [Dairy]
+ * milk
+ * butter
+ *
+ * [Bakery]
+ * flour
+ * sugar`;
+ *
+ * const categoryConfig = new CategoryConfig(categoryConfigString);
+ * ```
+ *
+ * @see [Category Configuration](https://cooklang.org/docs/spec/#shopping-lists) section of the cooklang specs
+ *
  * @category Classes
  */
-declare class AisleConfig {
+declare class CategoryConfig {
     /**
-     * The categories of aisles.
-     * @see {@link AisleCategory}
+     * The parsed categories of ingredients.
      */
-    categories: AisleCategory[];
+    categories: Category[];
     /**
-     * Creates a new AisleConfig instance.
-     * @param config - The aisle configuration to parse.
+     * Creates a new CategoryConfig instance.
+     * @param config - The category configuration to parse.
      */
     constructor(config?: string);
     /**
-     * Parses an aisle configuration from a string.
-     * @param config - The aisle configuration to parse.
+     * Parses a category configuration from a string into property
+     *   {@link CategoryConfig.categories | categories}
+     * @param config - The category configuration to parse.
      */
     parse(config: string): void;
 }
 
 /**
- * Represents a shopping list.
+ * Shopping List generator.
+ *
+ * ## Usage
+ *
+ * - Create a new ShoppingList instance with an optional category configuration (see {@link ShoppingList."constructor" | constructor})
+ * - Add recipes, scaling them as needed (see {@link ShoppingList.add_recipe | add_recipe()})
+ * - Categorize the ingredients (see {@link ShoppingList.categorize | categorize()})
+ *
+ * @example
+ *
+ * ```typescript
+ * import * as fs from "fs";
+ * import { ShoppingList } from @tmlmt/cooklang-parser;
+ *
+ * const categoryConfig = fs.readFileSync("./myconfig.txt", "utf-8")
+ * const recipe1 = new Recipe(fs.readFileSync("./myrecipe.cook", "utf-8"));
+ * const shoppingList = new ShoppingList();
+ * shoppingList.set_category_config(categoryConfig);
+ * // Quantities are automatically calculated and ingredients categorized
+ * // when adding a recipe
+ * shoppingList.add_recipe(recipe1);
+ * ```
+ *
  * @category Classes
  */
 declare class ShoppingList {
     /**
      * The ingredients in the shopping list.
-     * @see {@link Ingredient}
      */
     ingredients: Ingredient[];
     /**
      * The recipes in the shopping list.
-     * @see {@link AddedRecipe}
      */
     recipes: AddedRecipe[];
     /**
-     * The aisle configuration for the shopping list.
-     * @see {@link AisleConfig}
+     * The category configuration for the shopping list.
      */
-    aisle_config?: AisleConfig;
+    category_config?: CategoryConfig;
     /**
      * The categorized ingredients in the shopping list.
-     * @see {@link CategorizedIngredients}
      */
     categories?: CategorizedIngredients;
     /**
-     * Creates a new ShoppingList instance.
-     * @param aisle_config_str - The aisle configuration to parse.
+     * Creates a new ShoppingList instance
+     * @param category_config_str - The category configuration to parse.
      */
-    constructor(aisle_config_str?: string);
+    constructor(category_config_str?: string | CategoryConfig);
     private calculate_ingredients;
     /**
-     * Adds a recipe to the shopping list.
+     * Adds a recipe to the shopping list, then automatically
+     * recalculates the quantities and recategorize the ingredients.
      * @param recipe - The recipe to add.
      * @param factor - The factor to scale the recipe by.
      */
     add_recipe(recipe: Recipe, factor?: number): void;
     /**
-     * Removes a recipe from the shopping list.
+     * Removes a recipe from the shopping list, then automatically
+     * recalculates the quantities and recategorize the ingredients.s
      * @param index - The index of the recipe to remove.
      */
     remove_recipe(index: number): void;
     /**
-     * Sets the aisle configuration for the shopping list.
-     * @param config - The aisle configuration to parse.
+     * Sets the category configuration for the shopping list
+     * and automatically categorize current ingredients from the list.
+     * @param config - The category configuration to parse.
      */
-    set_aisle_config(config: string): void;
+    set_category_config(config: string | CategoryConfig): void;
     /**
      * Categorizes the ingredients in the shopping list
-     * Will use the aisle config if any, otherwise all ingredients will be placed in the "other" category
+     * Will use the category config if any, otherwise all ingredients will be placed in the "other" category
      */
     categorize(): void;
 }
 
-export { type AddedRecipe, type AisleCategory, AisleConfig, type AisleIngredient, type CategorizedIngredients, type Cookware, type CookwareItem, type DecimalValue, type FixedValue, type FractionValue, type Ingredient, type IngredientItem, type Item, type Metadata, type MetadataExtract, type Note, type Range, Recipe, Section, ShoppingList, type Step, type TextItem, type TextValue, type Timer, type TimerItem };
+export { type AddedRecipe, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedValue, type FractionValue, type Ingredient, type IngredientExtras, type IngredientFlag, type IngredientItem, type Item, type Metadata, type Note, type QuantityPart, type Range, Recipe, Section, ShoppingList, type Step, type TextItem, type TextValue, type Timer, type TimerItem };