⚠️ This is pre-release documentation for v3. For stable docs, visit v2.
@tmlmt/cooklang-parser

Appearance

@tmlmt/cooklang-parser / Recipe

Class: Recipe ​

Recipe parser.

Usage ​

You can either directly provide the recipe string when creating the instance e.g. const recipe = new Recipe('Add @eggs{3}'), or create it first and then pass the recipe string to the parse() method.

Look at the properties to see how the recipe's properties are parsed.

Example ​

typescript
import { Recipe } from "@tmlmt/cooklang-parser";

const recipeString = `
---
title: Pancakes
tags: [breakfast, easy]
---
Crack the @eggs{3} with @flour{100%g} and @milk{200%mL}

Melt some @butter{50%g} in a #pan on medium heat.

Cook for ~{5%minutes} on each side.
`
const recipe = new Recipe(recipeString);

Constructors ​

Constructor ​

new Recipe(content?): Recipe

Creates a new Recipe instance.

Parameters ​

content? ​

string

The recipe content to parse.

Returns ​

Recipe

Properties ​

arbitraries ​

arbitraries: ArbitraryScalable[] = []

The parsed arbitrary quantities.

choices ​

choices: RecipeAlternatives

The possible choices of alternative ingredients for this recipe.

cookware ​

cookware: Cookware[] = []

The parsed recipe cookware.

ingredients ​

ingredients: Ingredient[] = []

The parsed recipe ingredients.

metadata ​

metadata: Metadata = {}

The parsed recipe metadata.

sections ​

sections: Section[] = []

The parsed recipe sections.

servings? ​

optional servings?: number

The parsed recipe servings. Used for scaling. Parsed from one of Metadata.servings, Metadata.yield or Metadata.serves metadata fields.

See ​

scaleBy() and scaleTo() methods

timers ​

timers: Timer[] = []

The parsed recipe timers.

Accessors ​

unitSystem ​

Get Signature ​

get unitSystem(): SpecificUnitSystem | undefined

Gets the unit system specified in the recipe metadata. Used for resolving ambiguous units like tsp, tbsp, cup, etc.

Returns ​

SpecificUnitSystem | undefined

The unit system if specified, or undefined to use defaults

Methods ​

clone() ​

clone(): Recipe

Clones the recipe.

Returns ​

Recipe

A new Recipe instance with the same properties.

convertTo() ​

convertTo(system, method): Recipe

Converts all ingredient quantities in the recipe to a target unit system.

Parameters ​

system ​

SpecificUnitSystem

The target unit system to convert to (metric, US, UK, JP)

method ​

"replace" | "keep" | "remove"

How to handle existing quantities:

  • "keep": Keep all existing equivalents (swap if needed, or add converted)
  • "replace": Replace primary with target system quantity, discard equivalent used for conversion
  • "remove": Only keep target system quantity, delete all equivalents

Returns ​

Recipe

A new Recipe instance with converted quantities

Example ​

typescript
// Convert a recipe to metric, keeping original units as equivalents
const metricRecipe = recipe.convertTo("metric", "keep");

// Convert to US units, removing all other equivalents
const usRecipe = recipe.convertTo("US", "remove");

getChoicesForVariant() ​

getChoicesForVariant(variant?): RecipeAlternatives

Returns choices available for a given active variant.

For grouped alternatives, only groups with at least two available subgroups are returned.

Parameters ​

variant? ​

string

Returns ​

RecipeAlternatives

getCookwareForVariant() ​

getCookwareForVariant(options?): Cookware[]

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.

Parameters ​

options? ​

Pick<GetIngredientQuantitiesOptions, "choices">

Options for filtering:

  • choices: The choices to apply (only variant is used)

Returns ​

Cookware[]

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' } });

getIngredientQuantities() ​

getIngredientQuantities(options?): Ingredient[]

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).

Parameters ​

options? ​

GetIngredientQuantitiesOptions

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 ​

Ingredient[]

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]]) }
});

getRawQuantityGroups() ​

getRawQuantityGroups(options?): RawQuantityGroup[]

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 ShoppingList), where quantities from multiple recipes should be combined before processing.

Parameters ​

options? ​

GetIngredientQuantitiesOptions

Options for filtering and choice selection (same as getIngredientQuantities).

Returns ​

RawQuantityGroup[]

Array of 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

parse() ​

parse(content): void

Parses a recipe from a string.

Parameters ​

content ​

string

The recipe content to parse.

Returns ​

void

scaleBy() ​

scaleBy(factor): Recipe

Scales the recipe by a factor.

Parameters ​

factor ​

number | Big

The factor to scale the recipe by. While integers can be passed as-is, it is recommended to pass fractions as Big values, e.g. Big(num).div(den) in order to avoid undesirable floating point operation inaccuracies.

Returns ​

Recipe

A new Recipe instance with the scaled ingredients.

scaleTo() ​

scaleTo(newServings): Recipe

Scales the recipe to a new number of servings. In practice, it calls scaleBy with a factor corresponding to the ratio between newServings and the recipe's servings value.

Parameters ​

newServings ​

number

The new number of servings.

Returns ​

Recipe

A new Recipe instance with the scaled ingredients.

Throws ​

Error if the recipe does not contains an initial servings value