@tmlmt/cooklang-parser 3.0.0-alpha.8 → 3.0.0-alpha.9

package/dist/index.d.cts

@@ -66,8 +66,7 @@ declare class Recipe {
      */
     metadata: Metadata;
     /**
-     * The default or manual choice of alternative ingredients.
-     * Contains the full context including alternatives list and active selection index.
+     * The possible choices of alternative ingredients for this recipe.
      */
     choices: RecipeAlternatives;
     /**
@@ -145,14 +144,33 @@ declare class Recipe {
      */
     private _populate_ingredient_quantities;
     /**
-     * Calculates ingredient quantities based on the provided choices.
-     * Returns a list of computed ingredients with their total quantities.
+     * Gets ingredients with their quantities populated, optionally filtered by section/step
+     * and respecting user choices for alternatives.
      *
-     * @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.
+     * 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]]) }
+     * });
+     * ```
      */
-    calc_ingredient_quantities(choices?: RecipeChoices): ComputedIngredient[];
+    getIngredientQuantities(options?: GetIngredientQuantitiesOptions): Ingredient[];
     /**
      * Parses a recipe from a string.
      * @param content - The recipe content to parse.
@@ -409,11 +427,10 @@ interface IngredientQuantityGroup extends QuantityWithPlainUnit {
  * @category Types
  */
 interface IngredientQuantityAndGroup {
-    type: "and";
     /**
      * The incompatible primary quantities (e.g., "1 large" and "2 small").
      */
-    entries: QuantityWithPlainUnit[];
+    and: QuantityWithPlainUnit[];
     /**
      * The summed equivalent quantities (e.g., "5 cups" from summing "1.5 cup + 2 cup + 1.5 cup").
      */
@@ -558,6 +575,27 @@ interface RecipeChoices {
     /** 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.
  * @category Types
@@ -913,16 +951,14 @@ type QuantityWithUnitLike = QuantityWithPlainUnit | QuantityWithExtendedUnit | Q
  * @category Types
  */
 interface MaybeNestedOrGroup<T = QuantityWithUnitLike> {
-    type: "or";
-    entries: (T | MaybeNestedGroup<T>)[];
+    or: (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>)[];
+    and: (T | MaybeNestedGroup<T>)[];
 }
 /**
  * Represents any group type that may include nested groups
@@ -1089,8 +1125,16 @@ declare class ShoppingList {
      * recalculates the quantities and recategorize the ingredients.
      * @param recipe - The recipe to add.
      * @param options - Options for adding the recipe.
+     * @throws Error if the recipe has alternatives without corresponding choices.
      */
     add_recipe(recipe: Recipe, options?: AddedRecipeOptions): void;
+    /**
+     * 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.
+     */
+    private getUnresolvedAlternativesError;
     /**
      * Removes a recipe from the shopping list, then automatically
      * recalculates the quantities and recategorize the ingredients.s
@@ -1255,6 +1299,34 @@ declare class ShoppingCart {
     summarize(): ShoppingCartSummary;
 }
 
+/**
+ * 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;
+
 /**
  * Error thrown when trying to build a shopping cart without a product catalog
  * @category Errors
@@ -1270,4 +1342,4 @@ declare class NoShoppingListForCartError extends Error {
     constructor();
 }
 
-export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type ArbitraryScalable, type ArbitraryScalableItem, 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 MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type Metadata, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, type Note, type NoteItem, 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 };
+export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type ArbitraryScalable, type ArbitraryScalableItem, 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 GetIngredientQuantitiesOptions, 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, 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, isAlternativeSelected };

package/dist/index.d.ts

@@ -66,8 +66,7 @@ declare class Recipe {
      */
     metadata: Metadata;
     /**
-     * The default or manual choice of alternative ingredients.
-     * Contains the full context including alternatives list and active selection index.
+     * The possible choices of alternative ingredients for this recipe.
      */
     choices: RecipeAlternatives;
     /**
@@ -145,14 +144,33 @@ declare class Recipe {
      */
     private _populate_ingredient_quantities;
     /**
-     * Calculates ingredient quantities based on the provided choices.
-     * Returns a list of computed ingredients with their total quantities.
+     * Gets ingredients with their quantities populated, optionally filtered by section/step
+     * and respecting user choices for alternatives.
      *
-     * @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.
+     * 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]]) }
+     * });
+     * ```
      */
-    calc_ingredient_quantities(choices?: RecipeChoices): ComputedIngredient[];
+    getIngredientQuantities(options?: GetIngredientQuantitiesOptions): Ingredient[];
     /**
      * Parses a recipe from a string.
      * @param content - The recipe content to parse.
@@ -409,11 +427,10 @@ interface IngredientQuantityGroup extends QuantityWithPlainUnit {
  * @category Types
  */
 interface IngredientQuantityAndGroup {
-    type: "and";
     /**
      * The incompatible primary quantities (e.g., "1 large" and "2 small").
      */
-    entries: QuantityWithPlainUnit[];
+    and: QuantityWithPlainUnit[];
     /**
      * The summed equivalent quantities (e.g., "5 cups" from summing "1.5 cup + 2 cup + 1.5 cup").
      */
@@ -558,6 +575,27 @@ interface RecipeChoices {
     /** 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.
  * @category Types
@@ -913,16 +951,14 @@ type QuantityWithUnitLike = QuantityWithPlainUnit | QuantityWithExtendedUnit | Q
  * @category Types
  */
 interface MaybeNestedOrGroup<T = QuantityWithUnitLike> {
-    type: "or";
-    entries: (T | MaybeNestedGroup<T>)[];
+    or: (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>)[];
+    and: (T | MaybeNestedGroup<T>)[];
 }
 /**
  * Represents any group type that may include nested groups
@@ -1089,8 +1125,16 @@ declare class ShoppingList {
      * recalculates the quantities and recategorize the ingredients.
      * @param recipe - The recipe to add.
      * @param options - Options for adding the recipe.
+     * @throws Error if the recipe has alternatives without corresponding choices.
      */
     add_recipe(recipe: Recipe, options?: AddedRecipeOptions): void;
+    /**
+     * 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.
+     */
+    private getUnresolvedAlternativesError;
     /**
      * Removes a recipe from the shopping list, then automatically
      * recalculates the quantities and recategorize the ingredients.s
@@ -1255,6 +1299,34 @@ declare class ShoppingCart {
     summarize(): ShoppingCartSummary;
 }
 
+/**
+ * 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;
+
 /**
  * Error thrown when trying to build a shopping cart without a product catalog
  * @category Errors
@@ -1270,4 +1342,4 @@ declare class NoShoppingListForCartError extends Error {
     constructor();
 }
 
-export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type ArbitraryScalable, type ArbitraryScalableItem, 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 MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type Metadata, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, type Note, type NoteItem, 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 };
+export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type ArbitraryScalable, type ArbitraryScalableItem, 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 GetIngredientQuantitiesOptions, 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, 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, isAlternativeSelected };