@tmlmt/cooklang-parser 1.2.5 → 1.4.0

package/dist/index.d.cts

@@ -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;
     /**
@@ -112,16 +146,19 @@ interface Metadata {
     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;
     /** 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
+     * 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;
     /** 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
+     * 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;
     /** The course of the recipe. */
@@ -174,16 +211,6 @@ interface Metadata {
     /** The introduction of the recipe. */
     introduction?: 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;
-}
 /**
  * Represents a quantity described by text, e.g. "a pinch"
  * @category Types
@@ -351,7 +378,6 @@ interface Cookware {
  * @category Types
  */
 interface CategorizedIngredients {
-    /** The category of the ingredients. */
     [category: string]: Ingredient[];
 }
 /**
@@ -365,100 +391,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 CookwareItem, type DecimalValue, type FixedValue, type FractionValue, type Ingredient, type IngredientItem, type Item, type Metadata, type Note, type Range, Recipe, Section, ShoppingList, type Step, type TextItem, type TextValue, type Timer, type TimerItem };

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;
     /**
@@ -112,16 +146,19 @@ interface Metadata {
     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;
     /** 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
+     * 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;
     /** 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
+     * 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;
     /** The course of the recipe. */
@@ -174,16 +211,6 @@ interface Metadata {
     /** The introduction of the recipe. */
     introduction?: 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;
-}
 /**
  * Represents a quantity described by text, e.g. "a pinch"
  * @category Types
@@ -351,7 +378,6 @@ interface Cookware {
  * @category Types
  */
 interface CategorizedIngredients {
-    /** The category of the ingredients. */
     [category: string]: Ingredient[];
 }
 /**
@@ -365,100 +391,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 CookwareItem, type DecimalValue, type FixedValue, type FractionValue, type Ingredient, type IngredientItem, type Item, type Metadata, type Note, type Range, Recipe, Section, ShoppingList, type Step, type TextItem, type TextValue, type Timer, type TimerItem };