@tmlmt/cooklang-parser 3.0.0-alpha.14 → 3.0.0-alpha.16

package/dist/index.d.cts

@@ -155,6 +155,25 @@ declare class Recipe {
      * @internal
      */
     private _populateIngredientQuantities;
+    /** @internal */
+    private collectQuantityGroups;
+    /**
+     * Gets the raw (unprocessed) quantity groups for each ingredient, before
+     * any summation or equivalents simplification. This is useful for cross-recipe
+     * aggregation (e.g., in {@link ShoppingList}), where quantities from multiple
+     * recipes should be combined before processing.
+     *
+     * @param options - Options for filtering and choice selection (same as {@link getIngredientQuantities}).
+     * @returns Array of {@link RawQuantityGroup} objects, one per ingredient with quantities.
+     *
+     * @example
+     * ```typescript
+     * const rawGroups = recipe.getRawQuantityGroups();
+     * // Each group has: name, usedAsPrimary, flags, quantities[]
+     * // quantities are the raw QuantityWithExtendedUnit or FlatOrGroup entries
+     * ```
+     */
+    getRawQuantityGroups(options?: GetIngredientQuantitiesOptions): RawQuantityGroup[];
     /**
      * Gets ingredients with their quantities populated, optionally filtered by section/step
      * and respecting user choices for alternatives.
@@ -249,6 +268,18 @@ interface MetadataSource {
     /** The author at the source. */
     author?: string;
 }
+/**
+ * Represents scaling variable information for a recipe.
+ * @category Types
+ */
+interface MetadataScalingVar extends QuantityWithPlainUnit {
+    /** The text before the scaling variable. */
+    textBefore?: string;
+    /** The text after the scaling variable. */
+    textAfter?: string;
+    /** The text precising a numerical scaling variable. */
+    text?: string;
+}
 /**
  * Represents time information for a recipe.
  * @category Types
@@ -272,7 +303,7 @@ interface MetadataObject {
  * Represents any value that can appear in recipe metadata.
  * @category Types
  */
-type MetadataValue = string | number | (string | number)[] | MetadataObject | MetadataSource | MetadataTime | undefined;
+type MetadataValue = string | number | (string | number)[] | MetadataObject | MetadataSource | MetadataTime | MetadataScalingVar | undefined;
 /**
  * Represents the metadata of a recipe.
  * @category Types
@@ -290,9 +321,10 @@ interface Metadata {
     /** The author of the recipe (separate from source author). */
     author?: string;
     /** The number of servings the recipe makes.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * 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 `yield` or `serves`. If multiple ones are defined,
      * the prevailance order for the number which will used for scaling
@@ -307,30 +339,37 @@ interface Metadata {
      * ```yaml
      * servings: 2, a few
      * ```
+     *
+     * * @example
+     * ```yaml
+     * servings: {{1.5%kg}} of bread
+     * ```
      */
-    servings?: number | string;
+    servings?: MetadataScalingVar;
     /** The yield of the recipe.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * 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?: number | string;
+    yield?: MetadataScalingVar;
     /** The number of people the recipe serves.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * 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 `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.
      */
-    serves?: number | string;
+    serves?: MetadataScalingVar;
     /** The course of the recipe. */
     course?: string;
     /** The category of the recipe. */
@@ -623,6 +662,23 @@ interface GetIngredientQuantitiesOptions {
      */
     choices?: RecipeChoices;
 }
+/**
+ * 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.
+ * @category Types
+ */
+interface RawQuantityGroup {
+    /** The name of the ingredient. */
+    name: string;
+    /** Whether this ingredient is used as a primary choice. */
+    usedAsPrimary?: boolean;
+    /** Flags on the ingredient (e.g., "hidden", "optional"). */
+    flags?: IngredientFlag[];
+    /** The raw, unprocessed quantities for this ingredient across all its mentions. */
+    quantities: (QuantityWithExtendedUnit | FlatOrGroup<QuantityWithExtendedUnit>)[];
+}
 /**
  * Represents a cookware item in a recipe step.
  * @category Types
@@ -797,10 +853,7 @@ type AddedRecipeOptions = {
  * 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>;
-};
+type AddedIngredient = Pick<Ingredient, "name" | "quantities">;
 /**
  * Represents an ingredient in a category.
  * @category Types
@@ -860,6 +913,48 @@ type ProductOption = ProductOptionBase & {
     /** The size(s) of the product. Multiple sizes allow equivalent expressions (e.g., "1%dozen" and "12") */
     sizes: ProductSize[];
 };
+/**
+ * Represents a pantry item entry in the TOML file.
+ * Can be a simple quantity string (e.g. `"500%g"`) or an object with details.
+ * @category Types
+ */
+type PantryItemToml = string | {
+    quantity?: string;
+    bought?: string;
+    expire?: string;
+    low?: string;
+};
+/**
+ * Represents a parsed pantry item.
+ * @category Types
+ */
+interface PantryItem {
+    /** The name of the item. */
+    name: string;
+    /** The storage location (TOML section name, e.g. "freezer", "fridge"). */
+    location: string;
+    /** The quantity value of the item. */
+    quantity?: FixedValue | Range;
+    /** The unit of the item's quantity. */
+    unit?: string;
+    /** The date when the item was purchased. */
+    bought?: Date;
+    /** The expiration date of the item. */
+    expire?: Date;
+    /** The low stock threshold value. */
+    low?: FixedValue | Range;
+    /** The unit of the low stock threshold. */
+    lowUnit?: string;
+}
+/**
+ * Options for configuring a {@link Pantry}.
+ * @category Types
+ */
+interface PantryOptions {
+    /** Date format pattern for parsing date strings (e.g. `"DD.MM.YYYY"`, `"MM/DD/YYYY"`, `"YYYY-MM-DD"`).
+     * If not provided, dates are parsed with fuzzy detection defaulting to day-first when ambiguous. */
+    dateFormat?: string;
+}
 /**
  * Represents a product selection in a {@link ShoppingCart}
  * @category Types
@@ -1119,6 +1214,127 @@ declare class CategoryConfig {
     parse(config: string): void;
 }
 
+/**
+ * Pantry Inventory Manager: parses and queries a pantry inventory file.
+ *
+ * ## Usage
+ *
+ * Create a new Pantry instance with optional TOML content and options
+ * (see {@link Pantry."constructor" | constructor}), then query items
+ * using {@link Pantry.getDepletedItems | getDepletedItems()},
+ * {@link Pantry.getExpiredItems | getExpiredItems()},
+ * {@link Pantry.isLow | isLow()}, or {@link Pantry.isExpired | isExpired()}.
+ *
+ * A Pantry can also be attached to a {@link ShoppingList} via
+ * {@link ShoppingList.addPantry | addPantry()} so that on-hand stock
+ * is subtracted from recipe ingredient needs.
+ *
+ * @example
+ * ```typescript
+ * import { Pantry } from "@tmlmt/cooklang-parser";
+ *
+ * const pantryToml = `
+ * [fridge]
+ * milk = { expire = "10.05.2024", quantity = "1%L" }
+ *
+ * [freezer]
+ * spinach = { quantity = "1%kg", low = "200%g" }
+ * `;
+ *
+ * const pantry = new Pantry(pantryToml);
+ * console.log(pantry.getExpiredItems());
+ * console.log(pantry.isLow("spinach"));
+ * ```
+ *
+ * @see [Pantry Configuration](https://cooklang.org/docs/spec/#pantry-configuration) section of the cooklang specs
+ *
+ * @category Classes
+ */
+declare class Pantry {
+    /**
+     * The parsed pantry items.
+     */
+    items: PantryItem[];
+    /**
+     * Options for date parsing and other configuration.
+     */
+    private options;
+    /**
+     * Optional category configuration for alias-based lookups.
+     */
+    private categoryConfig?;
+    /**
+     * Creates a new Pantry instance.
+     * @param tomlContent - Optional TOML content to parse.
+     * @param options - Optional configuration options.
+     */
+    constructor(tomlContent?: string, options?: PantryOptions);
+    /**
+     * Parses a TOML string into pantry items.
+     * @param tomlContent - The TOML string to parse.
+     * @returns The parsed list of pantry items.
+     */
+    parse(tomlContent: string): PantryItem[];
+    /**
+     * Parses a single pantry item from its TOML representation.
+     */
+    private parseItem;
+    /**
+     * Parses a date string using the configured format or fuzzy detection.
+     */
+    private parseDate;
+    /**
+     * Sets a category configuration for alias-based item lookups.
+     * @param config - The category configuration to use.
+     */
+    setCategoryConfig(config: CategoryConfig): void;
+    /**
+     * Finds a pantry item by name, using exact match first, then alias lookup
+     * via the stored CategoryConfig.
+     * @param name - The name to search for.
+     * @returns The matching pantry item, or undefined if not found.
+     */
+    findItem(name: string): PantryItem | undefined;
+    /**
+     * Gets the numeric value of a pantry item's quantity, optionally converted to base units.
+     * Returns undefined if the quantity has a text value or is not set.
+     */
+    private getItemNumericValue;
+    /**
+     * Returns all items that are depleted (quantity = 0) or below their low threshold.
+     * @returns An array of depleted pantry items.
+     */
+    getDepletedItems(): PantryItem[];
+    /**
+     * Returns all items whose expiration date is within `nbDays` days from today
+     * (or already passed).
+     * @param nbDays - Number of days ahead to check. Defaults to 0 (already expired).
+     * @returns An array of expired pantry items.
+     */
+    getExpiredItems(nbDays?: number): PantryItem[];
+    /**
+     * Checks if a specific item is low (quantity = 0 or below `low` threshold).
+     * @param itemName - The name of the item to check (supports aliases if CategoryConfig is set).
+     * @returns true if the item is low, false otherwise. Returns false if item not found.
+     */
+    isLow(itemName: string): boolean;
+    /**
+     * Checks if a specific item is expired or expires within `nbDays` days.
+     * @param itemName - The name of the item to check (supports aliases if CategoryConfig is set).
+     * @param nbDays - Number of days ahead to check. Defaults to 0.
+     * @returns true if the item is expired, false otherwise. Returns false if item not found.
+     */
+    isExpired(itemName: string, nbDays?: number): boolean;
+    /**
+     * Internal: checks if a pantry item is low.
+     */
+    private isItemLow;
+    /**
+     * Internal: checks if a pantry item is expired.
+     */
+    private isItemExpired;
+}
+
 /**
  * Product Catalog Manager: used in conjunction with {@link ShoppingCart}
  *
@@ -1218,12 +1434,50 @@ declare class ShoppingList {
      * The categorized ingredients in the shopping list.
      */
     categories?: CategorizedIngredients;
+    /**
+     * The unit system to use for quantity simplification.
+     * When set, overrides per-recipe unit systems.
+     */
+    unitSystem?: SpecificUnitSystem;
+    /**
+     * Per-ingredient equivalence ratio maps for recomputing equivalents
+     * after pantry subtraction. Keyed by ingredient name.
+     * @internal
+     */
+    private equivalenceRatios;
+    /**
+     * The original pantry (never mutated by recipe calculations).
+     */
+    pantry?: Pantry;
+    /**
+     * The pantry with quantities updated after subtracting recipe needs.
+     * Recomputed on every {@link ShoppingList.calculateIngredients | calculateIngredients()} call.
+     */
+    private resultingPantry?;
     /**
      * Creates a new ShoppingList instance
      * @param categoryConfigStr - The category configuration to parse.
      */
     constructor(categoryConfigStr?: string | CategoryConfig);
     private calculateIngredients;
+    /**
+     * Subtracts pantry item quantities from calculated ingredient quantities
+     * 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.
@@ -1245,9 +1499,24 @@ declare class ShoppingList {
      * @param index - The index of the recipe to remove.
      */
     removeRecipe(index: number): void;
+    /**
+     * Adds a pantry to the shopping list. On-hand pantry quantities will be
+     * subtracted from recipe ingredient needs on each recalculation.
+     * @param pantry - A Pantry instance or a TOML string to parse.
+     * @param options - Options for pantry parsing (only used when providing a TOML string).
+     */
+    addPantry(pantry: Pantry | string, options?: PantryOptions): void;
+    /**
+     * Returns the resulting pantry with quantities updated to reflect
+     * what was consumed by the shopping list's recipes.
+     * Returns undefined if no pantry was added.
+     * @returns The resulting Pantry, or undefined.
+     */
+    getPantry(): Pantry | undefined;
     /**
      * Sets the category configuration for the shopping list
      * and automatically categorize current ingredients from the list.
+     * Also propagates the configuration to the pantry if one is set.
      * @param config - The category configuration to parse.
      */
     setCategoryConfig(config: string | CategoryConfig): void;
@@ -1669,4 +1938,4 @@ 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 MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, NoTabAsIndentError, 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 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, 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 };