@tmlmt/cooklang-parser 1.2.5 → 1.4.0

package/README.md

@@ -2,12 +2,16 @@
 
 A typescript library to parse and manipulate [cooklang](https://cooklang.org/) recipes.
 
+<picture><img src="https://badges.ws/maintenance/yes/2025" /></picture>
+<picture><img src="https://badges.ws/npm/dt/@tmlmt/cooklang-parser" /></picture>
+<picture><img src="https://badges.ws/npm/l/@tmlmt/cooklang-parser" /></picture>
+<picture><img src="https://badges.ws/github/release/tmlmt/cooklang-parser" /></picture>
+[<img src="https://badges.ws/badge/documentation-5672CD?icon=vitepress" />](https://cooklang-parser.tmlmt.com)
+
 ## Introduction
 
 This library provides a set of tools to work with recipes written in the Cooklang format. It allows you to parse recipes, extract ingredients, cookware, and timers, scale recipes, and generate shopping lists.
 
-The documentation is available at [https://cooklang-parser.tmlmt.com](https://cooklang-parser.tmlmt.com) (work in progress)
-
 ## Features
 
 - **Cooklang Compliant:** Fully compliant with the Cooklang specifications.
@@ -30,14 +34,16 @@ The documentation is available at [https://cooklang-parser.tmlmt.com](https://co
     - Also work with referencing etc., e.g. `Mix @wheat flour{100%g} with additional @&wheat flour|flour{50%g}` enables to get 150g of wheat flour in the ingredients list, and let you display "Mix wheat flour (100 g) with additional flour (50 g)" in your recipe renderer.
 - **Recipe Scaling:** Scale recipes by a given factor.
 - **Shopping Lists:** Generate shopping lists from one or more recipes.
-- **Aisle Configuration:** Categorize shopping list ingredients based on a custom aisle configuration.
+- **Category Configuration:** Categorize shopping list ingredients based on a custom category configuration.
 - **Typescript:** Written in Typescript, providing type safety for all the data structures.
 
 ## Quick start
 
-Install the package with your favorite package manager e.g. `npm install @tmlmt/cooklang-parser`
+- Install the package with your favorite package manager, e.g.:
+
+`npm install @tmlmt/cooklang-parser`
 
-To get started, you can use the `Recipe` class to parse a cooklang recipe:
+- Use the `Recipe` class to parse a cooklang recipe:
 
 ```typescript
 import { Recipe } from "@tmlmt/cooklang-parser";
@@ -59,50 +65,16 @@ Serve hot.
 const recipe = new Recipe(recipeString);
 
 console.log(recipe.metadata.title); // "Pancakes"
-console.log(recipe.ingredients);
-console.log(recipe.cookware);
-console.log(recipe.timers);
-```
-
-You can also create a shopping list from multiple recipes:
-
-```typescript
-import { ShoppingList, Recipe } from "@tmlmt/cooklang-parser";
-
-const recipe1 = new Recipe(/* ... */);
-const recipe2 = new Recipe(/* ... */);
-
-const shoppingList = new ShoppingList();
-shoppingList.add_recipe(recipe1);
-shoppingList.add_recipe(recipe2);
-
-console.log(shoppingList.ingredients);
+console.log(recipe.ingredients); // [{ name: "eggs", ...}, ...]
+console.log(recipe.cookware); // [{ name: "pan", ...}]
+console.log(recipe.timers); // [{ duration: 15, unit: "minutes", name: undefined}]
 ```
 
-And you can categorize those ingredients according to an aisle configuration defined in the cooklang format:
-
-```typescript
-const shoppingList = `
-[Dairy]
-milk
-butter
-
-[Bakery]
-flour
-sugar
-`;
-
-shoppingList.set_aisle_config(aisleConfig);
-shoppingList.categorize();
-
-console.log(shoppingList.categories);
-```
+- Browse the [API Reference](https://cooklang-parser.tmlmt.com/api/) to discover all functionalities
 
 ## Future plans
 
-I plan to further develop features depending on the needs I will encounter in using this library in a practical application. The current todo includes:
-
-- Ingredients aliases. See issue tmlmt/cooklang-parser#5
+I plan to further develop features depending on the needs I will encounter in using this library in a practical application. The main item on the todo list is to improve the documentation with detailed explanation of the extensions, as well as examples.
 
 ## Test coverage
 
@@ -111,7 +83,3 @@ This project includes a test setup aimed at eventually ensuring reliable parsing
 You can run the tests yourself by cloning the repository and running `pnpm test`. To see the coverage report, run `pnpm test:coverage`.
 
 If you find any issue with your own examples of recipes, feel free to open an Issue and if you want to help fix it, to submit a Pull Request.
-
-## License
-
-MIT

package/dist/index.cjs

@@ -22,23 +22,22 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  AisleConfig: () => AisleConfig,
+  CategoryConfig: () => CategoryConfig,
   Recipe: () => Recipe,
   Section: () => Section,
   ShoppingList: () => ShoppingList
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/classes/aisle_config.ts
-var AisleConfig = class {
+// src/classes/category_config.ts
+var CategoryConfig = class {
   /**
-   * 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) {
     /**
-     * The categories of aisles.
-     * @see {@link AisleCategory}
+     * The parsed categories of ingredients.
      */
     __publicField(this, "categories", []);
     if (config) {
@@ -46,8 +45,9 @@ var AisleConfig = class {
     }
   }
   /**
-   * 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) {
     let currentCategory = null;
@@ -97,7 +97,10 @@ var Section = class {
    * @param name - The name of the section. Defaults to an empty string.
    */
   constructor(name = "") {
-    /** 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 `""`
+     */
     __publicField(this, "name");
     /** An array of steps and notes that make up the content of the section. */
     __publicField(this, "content", []);
@@ -343,14 +346,14 @@ var units = [
     name: "g",
     type: "mass",
     system: "metric",
-    aliases: ["gram", "grams"],
+    aliases: ["gram", "grams", "grammes"],
     toBase: 1
   },
   {
     name: "kg",
     type: "mass",
     system: "metric",
-    aliases: ["kilogram", "kilograms"],
+    aliases: ["kilogram", "kilograms", "kilogrammes", "kilos", "kilo"],
     toBase: 1e3
   },
   // Mass (Imperial)
@@ -373,7 +376,7 @@ var units = [
     name: "ml",
     type: "volume",
     system: "metric",
-    aliases: ["milliliter", "milliliters", "millilitre", "millilitres"],
+    aliases: ["milliliter", "milliliters", "millilitre", "millilitres", "cc"],
     toBase: 1
   },
   {
@@ -438,7 +441,7 @@ var units = [
     name: "piece",
     type: "count",
     system: "metric",
-    aliases: ["pieces"],
+    aliases: ["pieces", "pc"],
     toBase: 1
   }
 ];
@@ -793,32 +796,31 @@ var Recipe = class _Recipe {
    */
   constructor(content) {
     /**
-     * The recipe's metadata.
-     * @see {@link Metadata}
+     * The parsed recipe metadata.
      */
     __publicField(this, "metadata", {});
     /**
-     * The recipe's ingredients.
-     * @see {@link Ingredient}
+     * The parsed recipe ingredients.
      */
     __publicField(this, "ingredients", []);
     /**
-     * The recipe's sections.
-     * @see {@link Section}
+     * The parsed recipe sections.
      */
     __publicField(this, "sections", []);
     /**
-     * The recipe's cookware.
-     * @see {@link Cookware}
+     * The parsed recipe cookware.
      */
     __publicField(this, "cookware", []);
     /**
-     * The recipe's timers.
-     * @see {@link Timer}
+     * The parsed recipe timers.
      */
     __publicField(this, "timers", []);
     /**
-     * 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
      */
     __publicField(this, "servings");
     if (content) {
@@ -980,9 +982,12 @@ var Recipe = class _Recipe {
     }
   }
   /**
-   * 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) {
     const originalServings = this.getServings();
@@ -1067,32 +1072,28 @@ var Recipe = class _Recipe {
 // src/classes/shopping_list.ts
 var ShoppingList = class {
   /**
-   * 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) {
+  constructor(category_config_str) {
     /**
      * The ingredients in the shopping list.
-     * @see {@link Ingredient}
      */
     __publicField(this, "ingredients", []);
     /**
      * The recipes in the shopping list.
-     * @see {@link AddedRecipe}
      */
     __publicField(this, "recipes", []);
     /**
-     * The aisle configuration for the shopping list.
-     * @see {@link AisleConfig}
+     * The category configuration for the shopping list.
      */
-    __publicField(this, "aisle_config");
+    __publicField(this, "category_config");
     /**
      * The categorized ingredients in the shopping list.
-     * @see {@link CategorizedIngredients}
      */
     __publicField(this, "categories");
-    if (aisle_config_str) {
-      this.set_aisle_config(aisle_config_str);
+    if (category_config_str) {
+      this.set_category_config(category_config_str);
     }
   }
   calculate_ingredients() {
@@ -1148,7 +1149,8 @@ var ShoppingList = class {
     }
   }
   /**
-   * 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.
    */
@@ -1158,7 +1160,8 @@ var ShoppingList = class {
     this.categorize();
   }
   /**
-   * 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) {
@@ -1170,31 +1173,35 @@ var ShoppingList = class {
     this.categorize();
   }
   /**
-   * 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) {
-    this.aisle_config = new AisleConfig(config);
+  set_category_config(config) {
+    if (typeof config === "string")
+      this.category_config = new CategoryConfig(config);
+    else if (config instanceof CategoryConfig) this.category_config = config;
+    else throw new Error("Invalid category configuration");
     this.categorize();
   }
   /**
    * 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() {
-    if (!this.aisle_config) {
+    if (!this.category_config) {
       this.categories = { other: this.ingredients };
       return;
     }
     const categories = { other: [] };
-    for (const category of this.aisle_config.categories) {
+    for (const category of this.category_config.categories) {
       categories[category.name] = [];
     }
     for (const ingredient of this.ingredients) {
       let found = false;
-      for (const category of this.aisle_config.categories) {
-        for (const aisleIngredient of category.ingredients) {
-          if (aisleIngredient.aliases.includes(ingredient.name)) {
+      for (const category of this.category_config.categories) {
+        for (const categoryIngredient of category.ingredients) {
+          if (categoryIngredient.aliases.includes(ingredient.name)) {
             categories[category.name].push(ingredient);
             found = true;
             break;
@@ -1213,7 +1220,7 @@ var ShoppingList = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  AisleConfig,
+  CategoryConfig,
   Recipe,
   Section,
   ShoppingList