@tmlmt/cooklang-parser 3.0.0-alpha.17 → 3.0.0-alpha.20

package/dist/index.d.cts

@@ -16,11 +16,17 @@ declare class Section {
     name: string;
     /** An array of steps and notes that make up the content of the section. */
     content: (Step | Note)[];
+    /** Optional list of variant names this section belongs to. */
+    variants?: string[];
+    /** Whether the section has been marked as optional ([?]) */
+    optional?: boolean;
     /**
      * Creates an instance of Section.
      * @param name - The name of the section. Defaults to an empty string.
+     * @param variants - Optional variant names for this section.
+     * @param optional - Whether the section is optional.
      */
-    constructor(name?: string);
+    constructor(name?: string, variants?: string[], optional?: boolean);
     /**
      * Checks if the section is blank (has no name and no content).
      * Used during recipe parsing
@@ -207,6 +213,25 @@ declare class Recipe {
      * ```
      */
     getIngredientQuantities(options?: GetIngredientQuantitiesOptions): Ingredient[];
+    /**
+     * Returns the list of cookware items that are used in the active variant.
+     * Cookware in steps/sections not matching the active variant are excluded.
+     * Hidden cookware is always excluded.
+     *
+     * @param options - Options for filtering:
+     *   - `choices`: The choices to apply (only `variant` is used)
+     * @returns Array of Cookware objects referenced by active steps
+     *
+     * @example
+     * ```typescript
+     * // Get all cookware for the default variant
+     * const cookware = recipe.getCookwareForVariant();
+     *
+     * // Get cookware for a specific variant
+     * const veganCookware = recipe.getCookwareForVariant({ choices: { variant: 'vegan' } });
+     * ```
+     */
+    getCookwareForVariant(options?: Pick<GetIngredientQuantitiesOptions, "choices">): Cookware[];
     /**
      * Parses a recipe from a string.
      * @param content - The recipe content to parse.
@@ -274,16 +299,17 @@ interface MetadataSource {
     author?: string;
 }
 /**
- * Represents scaling variable information for a recipe.
+ * Represents a yield metadata value for a recipe.
+ * Supports plain quantities (e.g. `yield: 300%g`), complex format with
+ * surrounding text (e.g. `yield: about {{300%g}} of bread`), or simple
+ * numbers (e.g. `yield: 2`).
  * @category Types
  */
-interface MetadataScalingVar extends QuantityWithPlainUnit {
-    /** The text before the scaling variable. */
+interface Yield extends QuantityWithPlainUnit {
+    /** The text before the scaling variable (complex `{{}}` format). */
     textBefore?: string;
-    /** The text after the scaling variable. */
+    /** The text after the scaling variable (complex `{{}}` format). */
     textAfter?: string;
-    /** The text precising a numerical scaling variable. */
-    text?: string;
 }
 /**
  * Represents time information for a recipe.
@@ -308,7 +334,7 @@ interface MetadataObject {
  * Represents any value that can appear in recipe metadata.
  * @category Types
  */
-type MetadataValue = string | number | (string | number)[] | MetadataObject | MetadataSource | MetadataTime | MetadataScalingVar | undefined;
+type MetadataValue = string | number | (string | number)[] | MetadataObject | MetadataSource | MetadataTime | Yield | undefined;
 /**
  * Represents the metadata of a recipe.
  * @category Types
@@ -326,55 +352,54 @@ interface Metadata {
     /** The author of the recipe (separate from source author). */
     author?: string;
     /** The number of servings the recipe makes.
-     * Can be given either as:
-     * - a number
-     * - a string which starts with a number (which will be used for scaling) followed by a comma and then whatever you want
-     * - or an arbitrary scalable number, optionally preceded and/or followed by text.
+     * Stored as a number when the value is numeric, or as a string when non-numeric
+     * (e.g. `servings: two`). Non-numeric values default the internal scaling baseline to 1.
      *
-     * Interchangeable with `yield` or `serves`. If multiple ones are defined,
-     * the prevailance order for the number which will used for scaling
-     * is `servings` \> `yield` \> `serves`.
+     * Interchangeable with `yield` or `serves` for the purpose of setting
+     * {@link Recipe.servings}. If multiple ones are defined, the prevalence
+     * order is `servings` \> `serves` \> `yield`.
      *
      * @example
      * ```yaml
      * servings: 4
      * ```
+     */
+    servings?: number | string;
+    /** The yield of the recipe.
+     * Can be given as:
+     * - a plain quantity with optional unit: `yield: 300%g` or `yield: 2`
+     * - a complex format with `{{}}` and optional surrounding text:
+     *   `yield: about {{300%g}} of bread`
+     *
+     * Interchangeable with `servings` or `serves` for the purpose of setting
+     * {@link Recipe.servings}. If multiple ones are defined, the prevalence
+     * order is `servings` \> `serves` \> `yield`.
      *
      * @example
      * ```yaml
-     * servings: 2, a few
+     * yield: 300%g
      * ```
      *
-     * * @example
+     * @example
      * ```yaml
-     * servings: {{1.5%kg}} of bread
+     * yield: about {{300%g}} of bread
      * ```
      */
-    servings?: MetadataScalingVar;
-    /** The yield of the recipe.
-     * Can be given either as:
-     * - a number
-     * - a string which starts with a number (which will be used for scaling) followed by a comma and then whatever you want
-     * - or an arbitrary scalable number, optionally preceded and/or followed by text.
-     *
-     * Interchangeable with `servings` or `serves`. If multiple ones are defined,
-     * the prevailance order for the number which will used for scaling
-     * is `servings` \> `yield` \> `serves`. See {@link Metadata.servings | servings}
-     * for examples.
-     */
-    yield?: MetadataScalingVar;
+    yield?: Yield;
     /** The number of people the recipe serves.
-     * Can be given either as:
-     * - a number
-     * - a string which starts with a number (which will be used for scaling) followed by a comma and then whatever you want
-     * - or an arbitrary scalable number, optionally preceded and/or followed by text.
+     * Stored as a number when the value is numeric, or as a string when non-numeric
+     * (e.g. `serves: two`). Non-numeric values default the internal scaling baseline to 1.
+     *
+     * Interchangeable with `servings` or `yield` for the purpose of setting
+     * {@link Recipe.servings}. If multiple ones are defined, the prevalence
+     * order is `servings` \> `serves` \> `yield`.
      *
-     * Interchangeable with `servings` or `yield`. If multiple ones are defined,
-     * the prevailance order for the number which will used for scaling
-     * is `servings` \> `yield` \> `serves`. See {@link Metadata.servings | servings}
-     * for examples.
+     * @example
+     * ```yaml
+     * serves: 4
+     * ```
      */
-    serves?: MetadataScalingVar;
+    serves?: number | string;
     /** The course of the recipe. */
     course?: string;
     /** The category of the recipe. */
@@ -407,6 +432,8 @@ interface Metadata {
      * This stores the original value as written by the user.
      */
     unitSystem?: string;
+    /** The list of available variant names for this recipe. */
+    variants?: string[];
     /**
      * Index signature for additional metadata fields not explicitly typed.
      * Any metadata key in the frontmatter will be captured here.
@@ -567,6 +594,12 @@ interface Ingredient {
     /** The collection of potential additional metadata for the ingredient */
     extras?: IngredientExtras;
 }
+/**
+ * Represents a quantity with extended unit and additional information
+ * about its scalability and potential equivalents
+ *
+ * @category Types
+ */
 type MaybeScalableQuantity = QuantityWithExtendedUnit & {
     /** Indicates whether this quantity should be scaled when the recipe serving size changes. */
     scalable: boolean;
@@ -574,6 +607,15 @@ type MaybeScalableQuantity = QuantityWithExtendedUnit & {
      * For `@salt{1%tsp|5%g}`, the main quantity is 1 tsp and the equivalents will contain 5 g. */
     equivalents?: QuantityWithExtendedUnit[];
 };
+/**
+ * Defines a type containing an optional {@link QuantityWithExtendedUnit} with scalability and potential info about equivalents
+ *
+ * Used in {@link IngredientAlternative}
+ *
+ * @param T - The base type to which the optional quantity properties will be added.
+ *
+ * @category Types
+ */
 type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
     quantity?: undefined;
     scalable?: never;
@@ -581,8 +623,7 @@ type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
     equivalents?: never;
 });
 /**
- * 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.
+ * Base type of {@link IngredientAlternative}
  * @category Types
  */
 type IngredientAlternativeBase = {
@@ -597,6 +638,14 @@ type IngredientAlternativeBase = {
      * Can be useful for creating alternative selection UI elements with anchor links */
     itemId?: string;
 };
+/**
+ * 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.
+ *
+ * Used in {@link IngredientItem} and for the various maps of {@link RecipeAlternatives}
+ *
+ * @category Types
+ */
 type IngredientAlternative = WithOptionalQuantity<IngredientAlternativeBase>;
 /**
  * Represents an ingredient item in a recipe step.
@@ -644,6 +693,11 @@ interface RecipeAlternatives {
      *   their own single-element subgroup.
      */
     ingredientGroups: Map<string, IngredientAlternative[][]>;
+    /**
+     * All variant names discovered in the recipe (from metadata, step tags,
+     * and section tags). Includes `*` if any step/section uses the default tag.
+     */
+    variants: string[];
 }
 /**
  * Represents the choices to apply when computing ingredient quantities.
@@ -655,6 +709,8 @@ interface RecipeChoices {
     ingredientItems?: Map<string, number>;
     /** Map of choices that can be made for Grouped Ingredient StepItem's */
     ingredientGroups?: Map<string, number>;
+    /** The selected variant name */
+    variant?: string;
 }
 /**
  * Options for the {@link Recipe.getIngredientQuantities | getIngredientQuantities()} method.
@@ -679,9 +735,9 @@ interface GetIngredientQuantitiesOptions {
 }
 /**
  * Represents a raw (unprocessed) group of quantities for a single ingredient.
- * Returned by {@link Recipe.getRawQuantityGroups | getRawQuantityGroups()},
- * these are the pre-addition quantities that can be fed directly into
- * {@link addEquivalentsAndSimplify} for cross-recipe aggregation.
+ * Returned by {@link Recipe.getRawQuantityGroups},
+ * these are the pre-addition quantities that are fed internally
+ * to another non-public helper function for cross-recipe aggregation.
  * @category Types
  */
 interface RawQuantityGroup {
@@ -782,6 +838,10 @@ interface Step {
     type: "step";
     /** The items in the step. */
     items: StepItem[];
+    /** Optional list of variant names this step belongs to */
+    variants?: string[];
+    /** Whether the step has been marked as optional ("[?]") */
+    optional?: boolean;
 }
 /**
  * Represents an item in a note (can be text or arbitrary scalable).
@@ -852,6 +912,9 @@ interface RecipeWithServings {
 type AddedRecipe = RecipeWithFactor | RecipeWithServings;
 /**
  * Options for adding a recipe to a shopping list
+ *
+ * Used in {@link ShoppingList.addRecipe}
+ *
  * @category Types
  */
 type AddedRecipeOptions = {
@@ -1376,7 +1439,7 @@ declare class Pantry {
  * 14141 = { name = "Big pack", size = "6%kg", price = 10 }
  * `
  * const catalog = new ProductCatalog(catalog);
- * const eggs = catalog.find("oeuf");
+ * const eggs = catalog.products.find(p => p.ingredientName === "eggs");
  * ```
  */
 declare class ProductCatalog {
@@ -1480,19 +1543,6 @@ declare class ShoppingList {
      * and updates the resultingPantry to reflect consumed stock.
      */
     private applyPantrySubtraction;
-    /**
-     * Builds a ratio map from equivalence lists.
-     * For each equivalence list, stores ratio = equiv_value / primary_value
-     * for every pair of units, so equivalents can be recomputed after
-     * pantry subtraction modifies primary quantities.
-     */
-    private static buildEquivalenceRatioMap;
-    /**
-     * Recomputes equivalent quantities from current primary values and stored ratios.
-     * For each equivalent unit in equivUnits, new_value = Σ (primary_value × ratio[equivUnit][primaryUnit]).
-     * Returns undefined if all equivalents compute to zero.
-     */
-    private static recomputeEquivalents;
     /**
      * Adds a recipe to the shopping list, then automatically
      * recalculates the quantities and recategorize the ingredients.
@@ -1857,6 +1907,81 @@ declare function isGroupedItem(item: IngredientItem): boolean;
  * ```
  */
 declare function isAlternativeSelected(recipe: Recipe, choices: RecipeChoices, item: IngredientItem, alternativeIndex?: number): boolean;
+/**
+ * Determines if a section is active (should be displayed or processed) for a given variant.
+ *
+ * - Sections with no `variants` property are always active.
+ * - When no variant is selected (default), sections tagged `[*]` are active,
+ *   and sections tagged with named variants are not.
+ * - When a named variant is selected, sections whose `variants` array includes
+ *   that name are active.
+ *
+ * @param section - The Section to check
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
+ * @returns `true` if the section should be displayed
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * const recipe = new Recipe(cooklangText);
+ * for (const section of recipe.sections) {
+ *   if (isSectionActive(section, choices.variant)) {
+ *     // render section
+ *   }
+ * }
+ * ```
+ */
+declare function isSectionActive(section: Section, variant?: string): boolean;
+/**
+ * Determines if a step is active (should be displayed) for a given variant.
+ *
+ * - Steps with no `variants` property are always active.
+ * - When no variant is selected (default), steps tagged `[*]` are active,
+ *   and steps tagged with named variants are not.
+ * - When a named variant is selected, steps whose `variants` array includes
+ *   that name are active.
+ *
+ * @param step - The Step to check
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
+ * @returns `true` if the step should be displayed
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const item of section.content) {
+ *   if (item.type === 'step' && isStepActive(item, choices.variant)) {
+ *     // render step
+ *   }
+ * }
+ * ```
+ */
+declare function isStepActive(step: Step, variant?: string): boolean;
+/**
+ * Returns the effective choices for a recipe given a variant selection.
+ *
+ * When a named variant is active, this scans ingredient alternatives whose
+ * `note` contains the variant name (case-insensitive substring match) and
+ * returns a `RecipeChoices` object with auto-selected alternatives.
+ *
+ * For inline alternatives: auto-selects the first alternative whose note
+ * matches the variant name.
+ *
+ * For grouped alternatives: auto-selects the first subgroup that has any
+ * alternative whose note matches the variant name.
+ *
+ * @param recipe - The Recipe instance
+ * @param variant - The active variant name, or `undefined`/`*` for defaults
+ * @returns A `RecipeChoices` with the `variant` set and auto-selected alternatives
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * const recipe = new Recipe(cooklangText);
+ * const choices = getEffectiveChoices(recipe, "vegan");
+ * const ingredients = recipe.getIngredientQuantities({ choices });
+ * ```
+ */
+declare function getEffectiveChoices(recipe: Recipe, variant?: string): RecipeChoices;
 
 /**
  * Type guard to check if an ingredient quantity-like object is an AND group.
@@ -1946,11 +2071,5 @@ declare class NoProductCatalogForCartError extends Error {
 declare class NoShoppingListForCartError extends Error {
     constructor();
 }
-declare class NoTabAsIndentError extends Error {
-    constructor();
-}
-declare class BadIndentationError extends Error {
-    constructor();
-}
 
-export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, BadIndentationError, 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 IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataScalingVar, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, NoTabAsIndentError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, 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, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSimpleGroup, renderFractionAsVulgar };
+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 IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, 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, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, type Yield, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, getEffectiveChoices, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSectionActive, isSimpleGroup, isStepActive, renderFractionAsVulgar };