@tmlmt/cooklang-parser 2.1.6 → 3.0.0-alpha.3

package/dist/index.d.ts

@@ -65,6 +65,11 @@ declare class Recipe {
      * The parsed recipe metadata.
      */
     metadata: Metadata;
+    /**
+     * The default or manual choice of alternative ingredients.
+     * Contains the full context including alternatives list and active selection index.
+     */
+    choices: RecipeAlternatives;
     /**
      * The parsed recipe ingredients.
      */
@@ -89,11 +94,48 @@ declare class Recipe {
      * @see {@link Recipe.scaleBy | scaleBy()} and {@link Recipe.scaleTo | scaleTo()} methods
      */
     servings?: number;
+    /**
+     * External storage for item count (not a property on instances).
+     * Used for giving ID numbers to items during parsing.
+     */
+    private static itemCounts;
+    /**
+     * Gets the current item count for this recipe.
+     */
+    private getItemCount;
+    /**
+     * Gets the current item count and increments it.
+     */
+    private getAndIncrementItemCount;
     /**
      * Creates a new Recipe instance.
      * @param content - The recipe content to parse.
      */
     constructor(content?: string);
+    private _parseQuantityRecursive;
+    private _parseIngredientWithAlternativeRecursive;
+    private _parseIngredientWithGroupKey;
+    /**
+     * Populates the `quantities` property for each ingredient based on
+     * how they appear in the recipe preparation. Only primary ingredients
+     * get quantities populated. Primary ingredients get `usedAsPrimary: true` flag.
+     *
+     * For inline alternatives (e.g. `\@a|b|c`), the first alternative is primary.
+     * For grouped alternatives (e.g. `\@|group|a`, `\@|group|b`), the first item in the group is primary.
+     *
+     * Quantities are grouped by their alternative signature and summed using addEquivalentsAndSimplify.
+     * @internal
+     */
+    private _populate_ingredient_quantities;
+    /**
+     * Calculates ingredient quantities based on the provided choices.
+     * Returns a list of computed ingredients with their total quantities.
+     *
+     * @param choices - The recipe choices to apply when computing quantities.
+     *   If not provided, uses the default choices (first alternative for each item).
+     * @returns An array of ComputedIngredient with quantityTotal calculated based on choices.
+     */
+    calc_ingredient_quantities(choices?: RecipeChoices): ComputedIngredient[];
     /**
      * Parses a recipe from a string.
      * @param content - The recipe content to parse.
@@ -128,11 +170,6 @@ declare class Recipe {
     clone(): Recipe;
 }
 
-interface Quantity {
-    value: FixedValue | Range;
-    unit?: string;
-}
-
 /**
  * Represents the metadata of a recipe.
  * @category Types
@@ -250,7 +287,7 @@ interface Metadata {
  */
 interface TextValue {
     type: "text";
-    value: string;
+    text: string;
 }
 /**
  * Represents a quantity described by a decimal number, e.g. "1.5"
@@ -258,7 +295,7 @@ interface TextValue {
  */
 interface DecimalValue {
     type: "decimal";
-    value: number;
+    decimal: number;
 }
 /**
  * Represents a quantity described by a fraction, e.g. "1/2"
@@ -280,6 +317,15 @@ interface FixedValue {
     type: "fixed";
     value: TextValue | DecimalValue | FractionValue;
 }
+/**
+ * Represents a single, fixed numeric quantity.
+ * This can be a decimal or fraction.
+ * @category Types
+ */
+interface FixedNumericValue {
+    type: "fixed";
+    value: DecimalValue | FractionValue;
+}
 /**
  * Represents a range of quantities, e.g. "1-2"
  * @category Types
@@ -289,16 +335,6 @@ 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
@@ -324,6 +360,59 @@ interface IngredientExtras {
      */
     path: string;
 }
+/**
+ * Represents a reference to an alternative ingredient along with its quantities.
+ *
+ * Used in {@link IngredientQuantityGroup} to describe what other ingredients
+ * could be used in place of the main ingredient.
+ * @category Types
+ */
+interface AlternativeIngredientRef {
+    /** The index of the alternative ingredient within the {@link Recipe.ingredients} array. */
+    index: number;
+    /** The quantities of the alternative ingredient. Multiple entries when units are incompatible. */
+    alternativeQuantities?: QuantityWithPlainUnit[];
+}
+/**
+ * Represents a group of summed quantities for an ingredient, optionally with alternatives.
+ * Quantities with the same alternative signature are summed together into a single group.
+ * When units are incompatible, separate IngredientQuantityGroup entries are created instead of merging.
+ * @category Types
+ */
+interface IngredientQuantityGroup {
+    /**
+     * References to alternative ingredients for this quantity group.
+     * If undefined, this group has no alternatives.
+     */
+    alternatives?: AlternativeIngredientRef[];
+    /**
+     * The summed quantity for this group, potentially with equivalents.
+     * OR groups from addEquivalentsAndSimplify are converted back to QuantityWithPlainUnit
+     * (first entry as main, rest as equivalents).
+     */
+    groupQuantity: QuantityWithPlainUnit;
+}
+/**
+ * Represents an AND group of quantities when primary units are incompatible but equivalents can be summed.
+ * For example: 1 large carrot + 2 small carrots, both with cup equivalents that sum to 5 cups.
+ * @category Types
+ */
+interface IngredientQuantityAndGroup {
+    type: "and";
+    /**
+     * The incompatible primary quantities (e.g., "1 large" and "2 small").
+     */
+    entries: QuantityWithPlainUnit[];
+    /**
+     * The summed equivalent quantities (e.g., "5 cups" from summing "1.5 cup + 2 cup + 1.5 cup").
+     */
+    equivalents?: QuantityWithPlainUnit[];
+    /**
+     * References to alternative ingredients for this quantity group.
+     * If undefined, this group has no alternatives.
+     */
+    alternatives?: AlternativeIngredientRef[];
+}
 /**
  * Represents an ingredient in a recipe.
  * @category Types
@@ -331,40 +420,84 @@ interface IngredientExtras {
 interface Ingredient {
     /** The name of the ingredient. */
     name: string;
-    /** The quantity of the ingredient. */
-    quantity?: FixedValue | Range;
-    /** The unit of the ingredient. */
-    unit?: string;
-    /** The array of contributors to the ingredient's total quantity. */
-    quantityParts?: QuantityPart[];
+    /**
+     * Represents the quantities list for an ingredient as groups.
+     * Each group contains summed quantities that share the same alternative signature.
+     * Groups can be either simple (single unit) or AND groups (incompatible primary units with summed equivalents).
+     * Only populated for primary ingredients (not alternative-only).
+     * Quantities without alternatives are merged opportunistically when units are compatible.
+     * Quantities with alternatives are only merged if the alternatives are exactly the same.
+     */
+    quantities?: (IngredientQuantityGroup | IngredientQuantityAndGroup)[];
     /** The preparation of the ingredient. */
     preparation?: string;
+    /** The list of indexes of the ingredients mentioned in the preparation as alternatives to this ingredient */
+    alternatives?: Set<number>;
+    /**
+     * True if this ingredient appears as the primary choice (first in an alternatives list).
+     * Only primary ingredients have quantities populated directly.
+     *
+     * Alternative-only ingredients (usedAsPrimary undefined/false) have their quantities
+     * available via the {@link Recipe.choices} structure.
+     */
+    usedAsPrimary?: 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.
+ * Represents a computed ingredient with its total quantity after applying choices.
+ * Used as the return type of {@link Recipe.calc_ingredient_quantities}.
  * @category Types
  */
-interface Timer {
-    /** The name of the timer. */
-    name?: string;
-    /** The duration of the timer. */
-    duration: FixedValue | Range;
-    /** The unit of the timer. */
-    unit: string;
+interface ComputedIngredient {
+    /** The name of the ingredient. */
+    name: string;
+    /** The total quantity of the ingredient after applying choices. */
+    quantityTotal?: QuantityWithPlainUnit | MaybeNestedGroup<QuantityWithPlainUnit>;
+    /** The preparation of the ingredient. */
+    preparation?: string;
+    /** The list of ingredients mentioned in the preparation as alternatives to this ingredient */
+    alternatives?: Set<number>;
+    /** 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 text item in a recipe step.
+ * Represents a contributor to an ingredient's total quantity, corresponding
+ * to a single mention in the recipe text. It can contain multiple
+ * equivalent quantities (e.g., in different units).
  * @category Types
  */
-interface TextItem {
-    /** The type of the item. */
-    type: "text";
-    /** The content of the text item. */
-    value: string;
+interface IngredientItemQuantity extends QuantityWithExtendedUnit {
+    /**
+     * A list of equivalent quantities/units for this ingredient mention besides the primary quantity.
+     * For `@salt{1%tsp|5%g}`, the main quantity is 1 tsp and the equivalents will contain 5 g.
+     */
+    equivalents?: QuantityWithExtendedUnit[];
+    /** Indicates whether this quantity should be scaled when the recipe serving size changes. */
+    scalable: boolean;
+}
+/**
+ * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
+ * to a specific ingredient and its corresponding quantity information.
+ * @category Types
+ */
+interface IngredientAlternative {
+    /** The index of the ingredient within the {@link Recipe.ingredients} array. */
+    index: number;
+    /** The quantity of this specific mention of the ingredient */
+    itemQuantity?: IngredientItemQuantity;
+    /** The alias/name of the ingredient as it should be displayed for this occurrence. */
+    displayName: string;
+    /** An optional note for this specific choice (e.g., "for a vegan version"). */
+    note?: string;
+    /** When {@link Recipe.choices} is populated for alternatives ingredients
+     * with group keys: the id of the corresponding ingredient item (e.g. "ingredient-item-2").
+     * Can be useful for creating alternative selection UI elements with anchor links */
+    itemId?: string;
 }
 /**
  * Represents an ingredient item in a recipe step.
@@ -373,14 +506,46 @@ interface TextItem {
 interface IngredientItem {
     /** The type of the item. */
     type: "ingredient";
-    /** 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;
+    /** The item identifier */
+    id: string;
+    /**
+     * A list of alternative ingredient choices. For a standard ingredient,
+     * this array will contain a single element.
+     */
+    alternatives: IngredientAlternative[];
+    /**
+     * An optional identifier for linking distributed alternatives. If multiple
+     * `IngredientItem`s in a recipe share the same `group` ID (e.g., from
+     * `@|group|...` syntax), they represent a single logical choice.
+     */
+    group?: string;
+}
+/**
+ * Represents the choices one can make in a recipe
+ * @category Types
+ */
+interface RecipeAlternatives {
+    /** Map of choices that can be made at Ingredient Item level
+     * - Keys are the Ingredient Item IDs (e.g. "ingredient-item-2")
+     * - Values are arrays of IngredientAlternative objects representing the choices available for that item
+     */
+    ingredientItems: Map<string, IngredientAlternative[]>;
+    /** Map of choices that can be made for Grouped Ingredient Item's
+     * - Keys are the Group IDs (e.g. "eggs" for `@|eggs|...`)
+     * - Values are arrays of IngredientAlternative objects representing the choices available for that group
+     */
+    ingredientGroups: Map<string, IngredientAlternative[]>;
+}
+/**
+ * Represents the choices to apply when computing ingredient quantities.
+ * Maps item/group IDs to the index of the selected alternative.
+ * @category Types
+ */
+interface RecipeChoices {
+    /** Map of choices that can be made at Ingredient Item level */
+    ingredientItems?: Map<string, number>;
+    /** Map of choices that can be made for Grouped Ingredient Item's */
+    ingredientGroups?: Map<string, number>;
 }
 /**
  * Represents a cookware item in a recipe step.
@@ -391,9 +556,8 @@ interface CookwareItem {
     type: "cookware";
     /** 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;
+    /** The quantity of this specific mention of the cookware */
+    quantity?: FixedValue | Range;
 }
 /**
  * Represents a timer item in a recipe step.
@@ -405,6 +569,28 @@ interface TimerItem {
     /** The index of the timer, within the {@link Recipe.timers | list of timers} */
     index: number;
 }
+/**
+ * Represents a timer in a recipe.
+ * @category Types
+ */
+interface Timer {
+    /** The name of the timer. */
+    name?: string;
+    /** The duration of the timer. */
+    duration: FixedValue | Range;
+    /** The unit of the timer. */
+    unit: string;
+}
+/**
+ * Represents a text item in a recipe step.
+ * @category Types
+ */
+interface TextItem {
+    /** The type of the item. */
+    type: "text";
+    /** The content of the text item. */
+    value: string;
+}
 /**
  * Represents an item in a recipe step.
  * @category Types
@@ -442,17 +628,15 @@ interface Cookware {
     name: string;
     /** The quantity of cookware */
     quantity?: FixedValue | Range;
-    /** 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[];
+    flags?: CookwareFlag[];
 }
 /**
  * Represents categorized ingredients.
  * @category Types
  */
 interface CategorizedIngredients {
-    [category: string]: Ingredient[];
+    [category: string]: AddedIngredient[];
 }
 /**
  * Represents a recipe together with a scaling factor
@@ -463,6 +647,8 @@ interface RecipeWithFactor {
     recipe: Recipe;
     /** The factor the recipe is scaled by. */
     factor: number;
+    /** The choices for alternative ingredients. */
+    choices?: RecipeChoices;
 }
 /**
  * Represents a recipe together with a servings value for scaling
@@ -473,12 +659,33 @@ interface RecipeWithServings {
     recipe: Recipe;
     /** The servings the recipe is scaled to */
     servings: number;
+    /** The choices for alternative ingredients. */
+    choices?: RecipeChoices;
 }
 /**
  * Represents a recipe that has been added to a shopping list.
  * @category Types
  */
 type AddedRecipe = RecipeWithFactor | RecipeWithServings;
+/**
+ * Options for adding a recipe to a shopping list
+ * @category Types
+ */
+type AddedRecipeOptions = {
+    /** The scaling option for the recipe. Can be either a factor or a number of servings */
+    scaling?: {
+        factor: number;
+    } | {
+        servings: number;
+    };
+    /** The choices for alternative ingredients. */
+    choices?: RecipeChoices;
+};
+/**
+ * Represents an ingredient that has been added to a shopping list
+ * @category Types
+ */
+type AddedIngredient = Pick<ComputedIngredient, "name" | "quantityTotal">;
 /**
  * Represents an ingredient in a category.
  * @category Types
@@ -499,6 +706,191 @@ interface Category {
     /** The ingredients in the category. */
     ingredients: CategoryIngredient[];
 }
+/**
+ * Represents a single size expression for a product (value + optional unit)
+ * @category Types
+ */
+interface ProductSize {
+    /** The numeric size value */
+    size: FixedNumericValue;
+    /** The unit of the size (optional) */
+    unit?: string;
+}
+/**
+ * Core properties for {@link ProductOption}
+ * @category Types
+ */
+interface ProductOptionCore {
+    /** The ID of the product */
+    id: string;
+    /** The name of the product */
+    productName: string;
+    /** The name of the ingredient it corresponds to */
+    ingredientName: string;
+    /** The aliases of the ingredient it also corresponds to */
+    ingredientAliases?: string[];
+    /** The price of the product */
+    price: number;
+}
+/**
+ * Base type for {@link ProductOption} allowing arbitrary additional metadata
+ * @category Types
+ */
+type ProductOptionBase = ProductOptionCore & Record<string, unknown>;
+/**
+ * Represents a product option in a {@link ProductCatalog}
+ * @category Types
+ */
+type ProductOption = ProductOptionBase & {
+    /** The size(s) of the product. Multiple sizes allow equivalent expressions (e.g., "1%dozen" and "12") */
+    sizes: ProductSize[];
+};
+/**
+ * Represents a product selection in a {@link ShoppingCart}
+ * @category Types
+ */
+interface ProductSelection {
+    /** The selected product */
+    product: ProductOption;
+    /** The quantity of the selected product */
+    quantity: number;
+    /** The total price for this selected product */
+    totalPrice: number;
+}
+/**
+ * Represents the content of the actual cart of the {@link ShoppingCart}
+ * @category Types
+ */
+type CartContent = ProductSelection[];
+/**
+ * Represents a successful match between a ingredient and product(s) in the product catalog, in a {@link ShoppingCart}
+ * @category Types
+ */
+interface ProductMatch {
+    ingredient: Ingredient;
+    selection: ProductSelection[];
+}
+/**
+ * Represents all successful matches between ingredients and the product catalog, in a {@link ShoppingCart}
+ * @category Types
+ */
+type CartMatch = ProductMatch[];
+/**
+ * Represents the error codes for an ingredient which didn't match with any product in the product catalog, in a {@link ShoppingCart}
+ * @category Types
+ */
+type NoProductMatchErrorCode = "incompatibleUnits" | "textValue" | "textValue_incompatibleUnits" | "noProduct" | "noQuantity";
+/**
+ * Represents an ingredient which didn't match with any product in the product catalog, in a {@link ShoppingCart}
+ * @category Types
+ */
+interface ProductMisMatch {
+    ingredient: Ingredient;
+    reason: NoProductMatchErrorCode;
+}
+/**
+ * Represents all ingredients which didn't match with any product in the product catalog, in a {@link ShoppingCart}
+ * @category Types
+ */
+type CartMisMatch = ProductMisMatch[];
+/**
+ * Represents the type category of a unit used for quantities
+ * @category Types
+ */
+type UnitType = "mass" | "volume" | "count";
+/**
+ * Represents the measurement system a unit belongs to
+ * @category Types
+ */
+type UnitSystem = "metric" | "imperial";
+/**
+ * Represents a unit used to describe quantities
+ * @category Types
+ */
+interface Unit {
+    name: string;
+    /** This property is set to true when the unit is prefixed by an `=` sign in the cooklang file, e.g. `=g`
+     * Indicates that quantities with this unit should be treated as integers only (no decimal/fractional values). */
+    integerProtected?: boolean;
+}
+/**
+ * Represents a fully defined unit with conversion and alias information
+ * @category Types
+ */
+interface UnitDefinition extends Unit {
+    type: UnitType;
+    system: UnitSystem;
+    /** e.g. ['gram', 'grams'] */
+    aliases: string[];
+    /** Conversion factor to the base unit of its type */
+    toBase: number;
+}
+/**
+ * Represents a resolved unit definition or a lightweight placeholder for non-standard units
+ * @category Types
+ */
+type UnitDefinitionLike = UnitDefinition | {
+    name: string;
+    type: "other";
+    system: "none";
+    integerProtected?: boolean;
+};
+/**
+ * Core quantity container holding a fixed value or a range
+ * @category Types
+ */
+interface QuantityBase {
+    quantity: FixedValue | Range;
+}
+/**
+ * Represents a quantity with an optional plain (string) unit
+ * @category Types
+ */
+interface QuantityWithPlainUnit extends QuantityBase {
+    unit?: string;
+    /** Optional equivalent quantities in different units (for alternative units like `@flour{100%g|3.5%oz}`) */
+    equivalents?: QuantityWithPlainUnit[];
+}
+/**
+ * Represents a quantity with an optional extended `Unit` object
+ * @category Types
+ */
+interface QuantityWithExtendedUnit extends QuantityBase {
+    unit?: Unit;
+}
+/**
+ * Represents a quantity with a resolved unit definition
+ * @category Types
+ */
+interface QuantityWithUnitDef extends QuantityBase {
+    unit: UnitDefinitionLike;
+}
+/**
+ * Represents any quantity shape supported by the parser (plain, extended, or resolved unit)
+ * @category Types
+ */
+type QuantityWithUnitLike = QuantityWithPlainUnit | QuantityWithExtendedUnit | QuantityWithUnitDef;
+/**
+ * Represents an "or" group of alternative quantities that may contain nested groups (alternatives with nested structure)
+ * @category Types
+ */
+interface MaybeNestedOrGroup<T = QuantityWithUnitLike> {
+    type: "or";
+    entries: (T | MaybeNestedGroup<T>)[];
+}
+/**
+ * Represents an "and" group of quantities that may contain nested groups (combinations with nested structure)
+ * @category Types
+ */
+interface MaybeNestedAndGroup<T = QuantityWithUnitLike> {
+    type: "and";
+    entries: (T | MaybeNestedGroup<T>)[];
+}
+/**
+ * Represents any group type that may include nested groups
+ * @category Types
+ */
+type MaybeNestedGroup<T = QuantityWithUnitLike> = MaybeNestedAndGroup<T> | MaybeNestedOrGroup<T>;
 
 /**
  * Parser for category configurations specified à-la-cooklang.
@@ -549,6 +941,62 @@ declare class CategoryConfig {
     parse(config: string): void;
 }
 
+/**
+ * Product Catalog Manager: used in conjunction with {@link ShoppingCart}
+ *
+ * ## Usage
+ *
+ * You can either directly populate the products by feeding the {@link ProductCatalog.products | products} property. Alternatively,
+ * you can provide a catalog in TOML format to either the constructor itself or to the {@link ProductCatalog.parse | parse()} method.
+ *
+ * @category Classes
+ *
+ * @example
+ * ```typescript
+ * import { ProductCatalog } from "@tmlmt/cooklang-parser";
+ *
+ * const catalog = `
+ * [eggs]
+ * aliases = ["oeuf", "huevo"]
+ * 01123 = { name = "Single Egg", size = "1", price = 2 }
+ * 11244 = { name = "Pack of 6 eggs", size = "6", price = 10 }
+ *
+ * [flour]
+ * aliases = ["farine", "Mehl"]
+ * 01124 = { name = "Small pack", size = "100%g", price = 1.5 }
+ * 14141 = { name = "Big pack", size = "6%kg", price = 10 }
+ * `
+ * const catalog = new ProductCatalog(catalog);
+ * const eggs = catalog.find("oeuf");
+ * ```
+ */
+declare class ProductCatalog {
+    products: ProductOption[];
+    constructor(tomlContent?: string);
+    /**
+     * Parses a TOML string into a list of product options.
+     * @param tomlContent - The TOML string to parse.
+     * @returns A parsed list of `ProductOption`.
+     */
+    parse(tomlContent: string): ProductOption[];
+    /**
+     * Stringifies the catalog to a TOML string.
+     * @returns The TOML string representation of the catalog.
+     */
+    stringify(): string;
+    /**
+     * Adds a product to the catalog.
+     * @param productOption - The product to add.
+     */
+    add(productOption: ProductOption): void;
+    /**
+     * Removes a product from the catalog by its ID.
+     * @param productId - The ID of the product to remove.
+     */
+    remove(productId: string): void;
+    private isValidTomlContent;
+}
+
 /**
  * Shopping List generator.
  *
@@ -579,7 +1027,7 @@ declare class ShoppingList {
     /**
      * The ingredients in the shopping list.
      */
-    ingredients: Ingredient[];
+    ingredients: AddedIngredient[];
     /**
      * The recipes in the shopping list.
      */
@@ -602,21 +1050,9 @@ declare class ShoppingList {
      * Adds a recipe to the shopping list, then automatically
      * recalculates the quantities and recategorize the ingredients.
      * @param recipe - The recipe to add.
-     * @param scaling - The scaling option for the recipe. Can be either a factor or a number of servings
+     * @param options - Options for adding the recipe.
      */
-    add_recipe(recipe: Recipe, scaling?: {
-        factor: number;
-    } | {
-        servings: number;
-    }): void;
-    /**
-     * 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.
-     * @deprecated since v2.0.3. Use the other call signature with `scaling` instead. Will be removed in v3
-     */
-    add_recipe(recipe: Recipe, factor?: number): void;
+    add_recipe(recipe: Recipe, options?: AddedRecipeOptions): void;
     /**
      * Removes a recipe from the shopping list, then automatically
      * recalculates the quantities and recategorize the ingredients.s
@@ -636,4 +1072,164 @@ declare class ShoppingList {
     categorize(): void;
 }
 
-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, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingList, type Step, type TextItem, type TextValue, type Timer, type TimerItem };
+/**
+ * Options for the {@link ShoppingCart} constructor
+ * @category Types
+ */
+interface ShoppingCartOptions {
+    /**
+     * A product catalog to connect to the cart
+     */
+    catalog?: ProductCatalog;
+    /**
+     * A shopping list to connect to the cart
+     */
+    list?: ShoppingList;
+}
+/**
+ * Key information about the {@link ShoppingCart}
+ * @category Types
+ */
+interface ShoppingCartSummary {
+    /**
+     * The total price of the cart
+     */
+    totalPrice: number;
+    /**
+     * The total number of items in the cart
+     */
+    totalItems: number;
+}
+/**
+ * Shopping Cart Manager: a tool to find the best combination of products to buy (defined in a {@link ProductCatalog}) to satisfy a {@link ShoppingList}.
+ *
+ * @example
+ * ```ts
+ * const shoppingList = new ShoppingList();
+ * const recipe = new Recipe("@flour{600%g}");
+ * shoppingList.add_recipe(recipe);
+ *
+ * const catalog = new ProductCatalog();
+ * catalog.products = [
+ *   {
+ *     id: "flour-1kg",
+ *     productName: "Flour (1kg)",
+ *     ingredientName: "flour",
+ *     price: 10,
+ *     size: { type: "fixed", value: { type: "decimal", value: 1000 } },
+ *     unit: "g",
+ *   },
+ *   {
+ *     id: "flour-500g",
+ *     productName: "Flour (500g)",
+ *     ingredientName: "flour",
+ *     price: 6,
+ *     size: { type: "fixed", value: { type: "decimal", value: 500 } },
+ *     unit: "g",
+ *   },
+ * ];
+ *
+ * const shoppingCart = new ShoppingCart({list: shoppingList, catalog}))
+ * shoppingCart.buildCart();
+ * ```
+ *
+ * @category Classes
+ */
+declare class ShoppingCart {
+    /**
+     * The product catalog to use for matching products
+     */
+    productCatalog?: ProductCatalog;
+    /**
+     * The shopping list to build the cart from
+     */
+    shoppingList?: ShoppingList;
+    /**
+     * The content of the cart
+     */
+    cart: CartContent;
+    /**
+     * The ingredients that were successfully matched with products
+     */
+    match: CartMatch;
+    /**
+     * The ingredients that could not be matched with products
+     */
+    misMatch: CartMisMatch;
+    /**
+     * Key information about the shopping cart
+     */
+    summary: ShoppingCartSummary;
+    /**
+     * Creates a new ShoppingCart instance
+     * @param options - {@link ShoppingCartOptions | Options} for the constructor
+     */
+    constructor(options?: ShoppingCartOptions);
+    /**
+     * Sets the product catalog to use for matching products
+     * To use if a catalog was not provided at the creation of the instance
+     * @param catalog - The {@link ProductCatalog} to set
+     */
+    setProductCatalog(catalog: ProductCatalog): void;
+    /**
+     * Sets the shopping list to build the cart from.
+     * To use if a shopping list was not provided at the creation of the instance
+     * @param list - The {@link ShoppingList} to set
+     */
+    setShoppingList(list: ShoppingList): void;
+    /**
+     * Builds the cart from the shopping list and product catalog
+     * @remarks
+     * - If a combination of product(s) is successfully found for a given ingredient, the latter will be listed in the {@link ShoppingCart.match | match} array
+     * in addition to that combination being added to the {@link ShoppingCart.cart | cart}.
+     * - Otherwise, the latter will be listed in the {@link ShoppingCart.misMatch | misMatch} array. Possible causes can be:
+     *   - No product is listed in the catalog for that ingredient
+     *   - The ingredient has no quantity, a text quantity
+     *   - The ingredient's quantity unit is incompatible with the units of the candidate products listed in the catalog
+     * @throws {@link NoProductCatalogForCartError} if no product catalog is set
+     * @throws {@link NoShoppingListForCartError} if no shopping list is set
+     * @returns `true` if all ingredients in the shopping list have been matched to products in the catalog, or `false` otherwise
+     */
+    buildCart(): boolean;
+    /**
+     * Gets the product options for a given ingredient
+     * @param ingredient - The ingredient to get the product options for
+     * @returns An array of {@link ProductOption}
+     */
+    private getProductOptions;
+    /**
+     * Gets the optimum match for a given ingredient and product option
+     * @param ingredient - The ingredient to match
+     * @param options - The product options to choose from
+     * @returns An array of {@link ProductSelection}
+     * @throws {@link NoProductMatchError} if no match can be found
+     */
+    private getOptimumMatch;
+    /**
+     * Reset the cart's properties
+     */
+    private resetCart;
+    /**
+     * Calculate the cart's key info and store it in the cart's {@link ShoppingCart.summary | summary} property.
+     * This function is automatically invoked by {@link ShoppingCart.buildCart | buildCart() } method.
+     * @returns the total price and number of items in the cart
+     */
+    summarize(): ShoppingCartSummary;
+}
+
+/**
+ * Error thrown when trying to build a shopping cart without a product catalog
+ * @category Errors
+ */
+declare class NoProductCatalogForCartError extends Error {
+    constructor();
+}
+/**
+ * Error thrown when trying to build a shopping cart without a shopping list
+ * @category Errors
+ */
+declare class NoShoppingListForCartError extends Error {
+    constructor();
+}
+
+export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type ComputedIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FractionValue, type Ingredient, type IngredientAlternative, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientItemQuantity, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type Item, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type Metadata, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, type Note, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type Step, type TextItem, type TextValue, type Timer, type TimerItem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitSystem, type UnitType };