@tmlmt/cooklang-parser 2.1.7 → 3.0.0-alpha.10

package/dist/index.d.cts

@@ -65,6 +65,10 @@ declare class Recipe {
      * The parsed recipe metadata.
      */
     metadata: Metadata;
+    /**
+     * The possible choices of alternative ingredients for this recipe.
+     */
+    choices: RecipeAlternatives;
     /**
      * The parsed recipe ingredients.
      */
@@ -81,6 +85,10 @@ declare class Recipe {
      * The parsed recipe timers.
      */
     timers: Timer[];
+    /**
+     * The parsed arbitrary quantities.
+     */
+    arbitraries: ArbitraryScalable[];
     /**
      * The parsed recipe servings. Used for scaling. Parsed from one of
      * {@link Metadata.servings}, {@link Metadata.yield} or {@link Metadata.serves}
@@ -89,11 +97,80 @@ 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);
+    /**
+     * Parses a matched arbitrary scalable quantity and adds it to the given array.
+     * @private
+     * @param regexMatchGroups - The regex match groups from arbitrary scalable regex.
+     * @param intoArray - The array to push the parsed arbitrary scalable item into.
+     */
+    private _parseArbitraryScalable;
+    /**
+     * Parses text for arbitrary scalables and returns NoteItem array.
+     * @param text - The text to parse for arbitrary scalables.
+     * @returns Array of NoteItem (text and arbitrary scalable items).
+     */
+    private _parseNoteText;
+    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;
+    /**
+     * Gets ingredients with their quantities populated, optionally filtered by section/step
+     * and respecting user choices for alternatives.
+     *
+     * When no options are provided, returns all recipe ingredients with quantities
+     * calculated using primary alternatives (same as after parsing).
+     *
+     * @param options - Options for filtering and choice selection:
+     *   - `section`: Filter to a specific section (Section object or 0-based index)
+     *   - `step`: Filter to a specific step (Step object or 0-based index)
+     *   - `choices`: Choices for alternative ingredients (defaults to primary)
+     * @returns Array of Ingredient objects with quantities populated
+     *
+     * @example
+     * ```typescript
+     * // Get all ingredients with primary alternatives
+     * const ingredients = recipe.getIngredientQuantities();
+     *
+     * // Get ingredients for a specific section
+     * const sectionIngredients = recipe.getIngredientQuantities({ section: 0 });
+     *
+     * // Get ingredients with specific choices applied
+     * const withChoices = recipe.getIngredientQuantities({
+     *   choices: { ingredientItems: new Map([['ingredient-item-2', 1]]) }
+     * });
+     * ```
+     */
+    getIngredientQuantities(options?: GetIngredientQuantitiesOptions): Ingredient[];
     /**
      * Parses a recipe from a string.
      * @param content - The recipe content to parse.
@@ -128,11 +205,6 @@ declare class Recipe {
     clone(): Recipe;
 }
 
-interface Quantity {
-    value: FixedValue | Range;
-    unit?: string;
-}
-
 /**
  * Represents the metadata of a recipe.
  * @category Types
@@ -250,7 +322,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 +330,7 @@ interface TextValue {
  */
 interface DecimalValue {
     type: "decimal";
-    value: number;
+    decimal: number;
 }
 /**
  * Represents a quantity described by a fraction, e.g. "1/2"
@@ -280,6 +352,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 +370,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 +395,48 @@ 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. */
+    quantities?: 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 extends QuantityWithPlainUnit {
+    /**
+     * References to alternative ingredients for this quantity group.
+     * If undefined, this group has no alternatives.
+     */
+    alternatives?: AlternativeIngredientRef[];
+}
+/**
+ * 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 (resp. 2 cup and 1.5 cup) that sum to 5 cups.
+ * @category Types
+ */
+interface IngredientQuantityAndGroup extends FlatAndGroup<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 +444,65 @@ 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 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 Timer {
-    /** The name of the timer. */
-    name?: string;
-    /** The duration of the timer. */
-    duration: FixedValue | Range;
-    /** The unit of the timer. */
-    unit: 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 text item in a recipe step.
+ * 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 TextItem {
-    /** The type of the item. */
-    type: "text";
-    /** The content of the text item. */
-    value: string;
+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 +511,67 @@ 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 StepItem level
+     * - Keys are the Ingredient StepItem 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 StepItem'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 StepItem level */
+    ingredientItems?: Map<string, number>;
+    /** Map of choices that can be made for Grouped Ingredient StepItem's */
+    ingredientGroups?: Map<string, number>;
+}
+/**
+ * Options for the {@link Recipe.getIngredientQuantities | getIngredientQuantities()} method.
+ * @category Types
+ */
+interface GetIngredientQuantitiesOptions {
+    /**
+     * Filter ingredients to only those appearing in a specific section.
+     * Can be a Section object or section index (0-based).
+     */
+    section?: Section | number;
+    /**
+     * Filter ingredients to only those appearing in a specific step.
+     * Can be a Step object or step index (0-based within the section, or global if no section specified).
+     */
+    step?: Step | number;
+    /**
+     * The choices to apply when computing quantities.
+     * If not provided, uses primary alternatives (index 0 for all).
+     */
+    choices?: RecipeChoices;
 }
 /**
  * Represents a cookware item in a recipe step.
@@ -391,9 +582,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,11 +595,55 @@ 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 arbitrary scalable quantity in a recipe.
+ * @category Types
+ */
+interface ArbitraryScalable {
+    /** The name of the arbitrary scalable quantity. */
+    name?: string;
+    /** The numerical value of the arbitrary scalable quantity. */
+    quantity: FixedNumericValue;
+    /** The unit of the arbitrary scalable quantity. */
+    unit?: string;
+}
+/**
+ * Represents an arbitrary scalable quantity item in a recipe step.
+ * @category Types
+ */
+interface ArbitraryScalableItem {
+    /** The type of the item. */
+    type: "arbitrary";
+    /** The index of the arbitrary scalable quantity, within the {@link Recipe.arbitraries | list of arbitrary scalable quantities} */
+    index: number;
+}
 /**
  * Represents an item in a recipe step.
  * @category Types
  */
-type Item = TextItem | IngredientItem | CookwareItem | TimerItem;
+type StepItem = TextItem | IngredientItem | CookwareItem | TimerItem | ArbitraryScalableItem;
 /**
  * Represents a step in a recipe.
  * @category Types
@@ -417,16 +651,21 @@ type Item = TextItem | IngredientItem | CookwareItem | TimerItem;
 interface Step {
     type: "step";
     /** The items in the step. */
-    items: Item[];
+    items: StepItem[];
 }
+/**
+ * Represents an item in a note (can be text or arbitrary scalable).
+ * @category Types
+ */
+type NoteItem = TextItem | ArbitraryScalableItem;
 /**
  * Represents a note in a recipe.
  * @category Types
  */
 interface Note {
     type: "note";
-    /** The content of the note. */
-    note: string;
+    /** The items in the note. */
+    items: NoteItem[];
 }
 /**
  * Represents a possible state modifier or other flag for cookware used in a recipe
@@ -442,17 +681,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 +700,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 +712,36 @@ 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<Ingredient, "name"> & {
+    /** The total quantity of the ingredient after applying choices. */
+    quantityTotal?: QuantityWithPlainUnit | MaybeNestedGroup<QuantityWithPlainUnit>;
+};
 /**
  * Represents an ingredient in a category.
  * @category Types
@@ -499,6 +762,223 @@ 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 a flat "or" group of alternative quantities (for alternative units)
+ * @category Types
+ */
+interface FlatOrGroup<T = QuantityWithUnitLike> {
+    or: T[];
+}
+/**
+ * Represents an "or" group of alternative quantities that may contain nested groups (alternatives with nested structure)
+ * @category Types
+ */
+interface MaybeNestedOrGroup<T = QuantityWithUnitLike> {
+    or: (T | MaybeNestedGroup<T>)[];
+}
+/**
+ * Represents a flat "and" group of quantities (combined quantities)
+ * @category Types
+ */
+interface FlatAndGroup<T = QuantityWithUnitLike> {
+    and: T[];
+}
+/**
+ * Represents an "and" group of quantities that may contain nested groups (combinations with nested structure)
+ * @category Types
+ */
+interface MaybeNestedAndGroup<T = QuantityWithUnitLike> {
+    and: (T | MaybeNestedGroup<T>)[];
+}
+/**
+ * Represents any flat group type ("and" or "or")
+ * @category Types
+ */
+type FlatGroup<T = QuantityWithUnitLike> = FlatAndGroup<T> | FlatOrGroup<T>;
+/**
+ * Represents any group type that may include nested groups
+ * @category Types
+ */
+type MaybeNestedGroup<T = QuantityWithUnitLike> = MaybeNestedAndGroup<T> | MaybeNestedOrGroup<T>;
+/**
+ * Represents any group type (flat or nested)
+ * @category Types
+ */
+type Group<T = QuantityWithUnitLike> = MaybeNestedGroup<T> | FlatGroup<T>;
+/**
+ * Represents any "or" group (flat or nested)
+ * @category Types
+ */
+type OrGroup<T = QuantityWithUnitLike> = MaybeNestedOrGroup<T> | FlatOrGroup<T>;
+/**
+ * Represents any "and" group (flat or nested)
+ * @category Types
+ */
+type AndGroup<T = QuantityWithUnitLike> = MaybeNestedAndGroup<T> | FlatAndGroup<T>;
 
 /**
  * Parser for category configurations specified à-la-cooklang.
@@ -549,6 +1029,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 +1115,7 @@ declare class ShoppingList {
     /**
      * The ingredients in the shopping list.
      */
-    ingredients: Ingredient[];
+    ingredients: AddedIngredient[];
     /**
      * The recipes in the shopping list.
      */
@@ -602,21 +1138,17 @@ 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.
+     * @throws Error if the recipe has alternatives without corresponding choices.
      */
-    add_recipe(recipe: Recipe, scaling?: {
-        factor: number;
-    } | {
-        servings: number;
-    }): void;
+    add_recipe(recipe: Recipe, options?: AddedRecipeOptions): 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
+     * Checks if a recipe has unresolved alternatives (alternatives without provided choices).
+     * @param recipe - The recipe to check.
+     * @param choices - The choices provided for the recipe.
+     * @returns An error message if there are unresolved alternatives, undefined otherwise.
      */
-    add_recipe(recipe: Recipe, factor?: number): void;
+    private getUnresolvedAlternativesError;
     /**
      * Removes a recipe from the shopping list, then automatically
      * recalculates the quantities and recategorize the ingredients.s
@@ -636,4 +1168,374 @@ 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;
+}
+
+/**
+ * Format a numeric value (decimal or fraction) to a string.
+ *
+ * @param value - The decimal or fraction value to format
+ * @returns The formatted string representation
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * formatNumericValue({ type: "decimal", decimal: 1.5 }); // "1.5"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }); // "1/2"
+ * ```
+ */
+declare function formatNumericValue(value: DecimalValue | FractionValue): string;
+/**
+ * Format a single value (text, decimal, or fraction) to a string.
+ *
+ * @param value - The value to format
+ * @returns The formatted string representation
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * formatSingleValue({ type: "text", text: "a pinch" }); // "a pinch"
+ * formatSingleValue({ type: "decimal", decimal: 2 }); // "2"
+ * formatSingleValue({ type: "fraction", num: 3, den: 4 }); // "3/4"
+ * ```
+ */
+declare function formatSingleValue(value: TextValue | DecimalValue | FractionValue): string;
+/**
+ * Format a quantity (fixed value or range) to a string.
+ *
+ * @param quantity - The quantity to format
+ * @returns The formatted string representation
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * formatQuantity({ type: "fixed", value: { type: "decimal", decimal: 100 } }); // "100"
+ * formatQuantity({ type: "range", min: { type: "decimal", decimal: 1 }, max: { type: "decimal", decimal: 2 } }); // "1-2"
+ * ```
+ */
+declare function formatQuantity(quantity: FixedValue | Range): string;
+/**
+ * Format a unit to a string. Handles both plain string units and Unit objects.
+ *
+ * @param unit - The unit to format (string, Unit object, or undefined)
+ * @returns The formatted unit string, or empty string if undefined
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * formatUnit("g"); // "g"
+ * formatUnit({ name: "grams" }); // "grams"
+ * formatUnit(undefined); // ""
+ * ```
+ */
+declare function formatUnit(unit: string | Unit | undefined): string;
+/**
+ * Format a quantity with its unit to a string.
+ *
+ * @param quantity - The quantity to format
+ * @param unit - The unit to append (string, Unit object, or undefined)
+ * @returns The formatted string with quantity and unit
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * formatQuantityWithUnit({ type: "fixed", value: { type: "decimal", decimal: 100 } }, "g"); // "100 g"
+ * formatQuantityWithUnit({ type: "fixed", value: { type: "decimal", decimal: 2 } }, undefined); // "2"
+ * ```
+ */
+declare function formatQuantityWithUnit(quantity: FixedValue | Range | undefined, unit: string | Unit | undefined): string;
+/**
+ * Format a QuantityWithExtendedUnit to a string.
+ *
+ * @param item - The quantity with extended unit to format
+ * @returns The formatted string
+ * @category Helpers
+ */
+declare function formatExtendedQuantity(item: QuantityWithExtendedUnit): string;
+/**
+ * Format an IngredientItemQuantity with all its equivalents to a string.
+ *
+ * @param itemQuantity - The ingredient item quantity to format
+ * @param separator - The separator between primary and equivalent quantities (default: " | ")
+ * @returns The formatted string with all quantities
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * // For an ingredient like @flour{100%g|3.5%oz}
+ * formatItemQuantity(itemQuantity); // "100 g | 3.5 oz"
+ * formatItemQuantity(itemQuantity, " / "); // "100 g / 3.5 oz"
+ * ```
+ */
+declare function formatItemQuantity(itemQuantity: IngredientItemQuantity, separator?: string): string;
+/**
+ * Check if an ingredient item is a grouped alternative (vs inline alternative).
+ *
+ * Grouped alternatives are ingredients that share a group key (e.g., `@|milk|...`)
+ * and are distributed across multiple tokens in the recipe.
+ *
+ * @param item - The ingredient item to check
+ * @returns true if this is a grouped alternative
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const item of step.items) {
+ *   if (item.type === 'ingredient') {
+ *     if (isGroupedItem(item)) {
+ *       // Handle grouped alternative (e.g., show with strikethrough if not selected)
+ *     } else {
+ *       // Handle inline alternative (e.g., hide if not selected)
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function isGroupedItem(item: IngredientItem): boolean;
+/**
+ * Determines if a specific alternative in an IngredientItem is selected
+ * based on the applied choices.
+ *
+ * Use this in renderers to determine how an ingredient alternative should be displayed.
+ *
+ * @param recipe - The Recipe instance containing choices
+ * @param choices - The choices that have been made
+ * @param item - The IngredientItem to check
+ * @param alternativeIndex - The index within item.alternatives to check (for inline alternatives only)
+ * @returns true if this alternative is the selected one
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * const recipe = new Recipe(cooklangText);
+ * for (const item of step.items) {
+ *   if (item.type === 'ingredient') {
+ *     item.alternatives.forEach((alt, idx) => {
+ *       const isSelected = isAlternativeSelected(item, idx, recipe, choices);
+ *       // Render differently based on isSelected
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare function isAlternativeSelected(recipe: Recipe, choices: RecipeChoices, item: IngredientItem, alternativeIndex?: number): boolean;
+
+/**
+ * Type guard to check if an ingredient quantity-like object is an AND group.
+ * *
+ * @param x - The quantity-like entry to check
+ * @returns true if this is an AND group (has `and` property)
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const entry of ingredient.quantities) {
+ *   if (isAndGroup(entry)) {
+ *     // entry.and contains the list of quantities in the AND group
+ *   }
+ * }
+ * ```
+ */
+declare function isAndGroup(x: IngredientQuantityGroup | IngredientQuantityAndGroup): x is IngredientQuantityAndGroup;
+declare function isAndGroup(x: QuantityWithUnitLike | Group): x is AndGroup;
+/**
+ * Type guard to check if an ingredient quantity entry is a simple group.
+ *
+ * Simple groups have a single quantity with optional unit and equivalents.
+ *
+ * @param entry - The quantity entry to check
+ * @returns true if this is a simple group (has `quantity` property)
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const entry of ingredient.quantities) {
+ *   if (isSimpleGroup(entry)) {
+ *     // entry.quantity is available
+ *     // entry.unit is available
+ *   }
+ * }
+ * ```
+ */
+declare function isSimpleGroup(entry: IngredientQuantityGroup | IngredientQuantityAndGroup): entry is IngredientQuantityGroup;
+/**
+ * Type guard to check if an ingredient quantity entry has alternatives.
+ *
+ * @param entry - The quantity entry to check
+ * @returns true if this entry has alternatives
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const entry of ingredient.quantities) {
+ *   if (hasAlternatives(entry)) {
+ *     // entry.alternatives is available and non-empty
+ *     for (const alt of entry.alternatives) {
+ *       console.log(`Alternative ingredient index: ${alt.index}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function hasAlternatives(entry: IngredientQuantityGroup | IngredientQuantityAndGroup): entry is (IngredientQuantityGroup | IngredientQuantityAndGroup) & {
+    alternatives: AlternativeIngredientRef[];
+};
+
+/**
+ * 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 AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FlatAndGroup, type FlatGroup, type FlatOrGroup, type FractionValue, type GetIngredientQuantitiesOptions, type Group, type Ingredient, type IngredientAlternative, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientItemQuantity, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type Metadata, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, type Note, type NoteItem, type OrGroup, 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 StepItem, type TextItem, type TextValue, type Timer, type TimerItem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitSystem, type UnitType, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSimpleGroup };