Recipe Book0.6.0

3.8Core reference

Types

Reference for the recipe model that parseRecipe returns, the recipe input types you write, and the label pack type.

§ 3.832 min readView as Markdown

Use these types to read a parsed recipe and to type-check recipe input. Import them with import type from @recipe-book/core. In a React app, import this page’s types from @recipe-book/react/core. Import your language from @recipe-book/react/core/labels to format with it, and from @recipe-book/react/labels to pass it to the parts, which covers their controls too. The terms of <Recipe.Times> and <Recipe.Nutrition> and the label of <Recipe.CookMode> stay in English unless you set them. Under every pack, <Recipe.Times> writes its durations in English, <Recipe.Nutrition> writes kcal, g, and mg, and the parts show temperatures as °C and °F.

Optional fields are typed field?: T | undefined, so they work with exactOptionalPropertyTypes.

URLs, which are image on a recipe or step and url on an ingredient or equipment, must be http, https, or relative, including protocol-relative URLs such as '//cdn.example.com/a.jpg'. Any other scheme, such as javascript: or data:, is an invalid_url issue, so you can render a parsed URL as an href or src. So is a URL the URL parser rejects, such as 'http://[bad'.

Model types

parseRecipe returns a Recipe. It’s plain JSON data, so you can cache it, store it, or pass it from a Server Component to a Client Component.

Recipe

TypeScript
type Recipe = {
  id: string
  name: string
  description?: string | undefined
  image?: string | undefined
  servings?: Servings | undefined
  yield?: Yield | undefined
  system?: System | undefined
  times: Times
  ingredients: IngredientSection[]
  steps: StepSection[]
  notes: Note[]
  equipment: Equipment[]
  nutrition?: Nutrition | undefined
}

A normalized recipe. Every recipe that parseRecipe or fromJsonLd returns is also valid recipe input, and parsing it returns an equal recipe.

Name Type Description
id string The authored ID, or one derived from name, such as 'buttermilk-pancakes', or 'recipe' when name has no letters or numbers in its NFKD form.
name string The recipe name.
description string | undefined A short description of the recipe.
image string | undefined An image URL.
servings Servings | undefined How many servings the recipe makes.
yield Yield | undefined What a batch makes, such as 24 cookies.
system System | undefined The measurement system the recipe is written in: the authored one, or else the one its ingredient quantities imply. Absent when it isn’t authored and no ingredient’s quantity has a metric-only or US-only unit.
times Times Prep, cook, total, and custom times. It’s { custom: [] } when the input has none.
ingredients IngredientSection[] The ingredients, grouped in sections. It’s empty when the input has none.
steps StepSection[] The steps, grouped in sections. It’s empty when the input has none.
notes Note[] Notes, such as how to store the dish. It’s empty when the input has none.
equipment Equipment[] The tools the recipe needs. It’s empty when the input has none.
nutrition Nutrition | undefined Nutrition for one serving. It’s absent when the input has none.

ParsedRecipe

TypeScript
type ParsedRecipe = Recipe

The same type as Recipe, for files that also import @recipe-book/react as Recipe.

IngredientSection

TypeScript
type IngredientSection = {
  id: string
  title?: string | undefined
  items: Ingredient[]
}

A group of ingredients, such as “For the frosting”.

Name Type Description
id string The authored ID, or one derived from title and made unique among the ingredient sections: 'sauce', then 'sauce-2'. An untitled section, or one whose title has no letters or numbers in its NFKD form, gets 'ingredients', with -2 and so on added as for other repeated IDs.
title string | undefined The section heading. Absent for an untitled section.
items Ingredient[] The ingredients in the section.

Ingredient

TypeScript
type Ingredient = {
  id: string
  name: string
  plural?: string | undefined
  quantity?: Quantity | undefined
  equivalents: Quantity[]
  note?: string | undefined
  url?: string | undefined
  optional: boolean
}

A normalized ingredient.

Name Type Description
id string The authored ID, or one derived from name, or 'ingredient' when it has no letters or numbers in its NFKD form, made unique among the ingredients: 'egg', then 'egg-2'.
name string The name. When an ingredient line gives a plural, the name is singular, so '3 large eggs' gives 'large egg'. An object’s name is kept as written.
plural string | undefined The plural name, used after a bare count that prints as more than 1 or as a decimal, or a range, unless its ends round to the same number, which takes that number’s form: “2 eggs”, “1–2 eggs”, but “1 egg” for 1–1.04. 1.04 eggs, which kitchen rounding prints as 1, is “1 egg”. This goes by the printed ends, even with rounding: 'none', which prints 1–1.0004 as “1 egg” and 1–1.04 as “1–1.04 eggs”. 1 and fractions below 1, such as ½, use name. With a label pack, the pack’s language picks the form, so French uses name for 1 ½.
quantity Quantity | undefined The amount and unit. Absent for an ingredient without one, such as salt to taste.
equivalents Quantity[] Alternatives to quantity that the author supplied, in order of preference. When quantity is in a count unit, such as can, each is the amount for the whole count, not for each item, as in a count unit’s size. It’s empty when there are none.
note string | undefined A short note, such as “melted” or “to serve”.
url string | undefined A product page or another recipe, as an http, https, or relative URL. fromJsonLd reads it from the first such link in the ingredient’s line, decoded but not resolved, so a relative one is relative to the page the recipe came from. See Resolve ingredient links.
optional boolean Whether the recipe works without this ingredient.

StepSection

TypeScript
type StepSection = {
  id: string
  title?: string | undefined
  items: Step[]
}

A group of steps, such as “Make the frosting”.

Name Type Description
id string The authored ID, or one derived from title and made unique among the step sections: 'sauce', then 'sauce-2'. An untitled section, or one whose title has no letters or numbers in its NFKD form, gets 'steps', with -2 and so on added as for other repeated IDs.
title string | undefined The section heading. Absent for an untitled section.
items Step[] The steps in the section.

Step

TypeScript
type Step = {
  id: string
  text: string
  name?: string | undefined
  image?: string | undefined
}

One step. Step numbers run across sections and aren’t stored.

Name Type Description
id string The authored ID, or one derived from name, or 'step-3' for the third step across all sections, made unique among the steps: a second step named “Mix” gets 'mix-2'.
text string The step’s text. To find the temperatures and durations in it, use segmentStepText.
name string | undefined A short label, such as “Make the dough”.
image string | undefined An image URL.

Servings

TypeScript
type Servings = {
  amount: number
  max?: number | undefined
}

How many servings the recipe makes. Print it with formatServings. See Scale to a number of servings.

Name Type Description
amount number A positive number. Scaling uses it.
max number | undefined The upper end of a range, as in “4–6 servings”. It’s greater than amount.

Yield

TypeScript
type Yield = {
  amount: number
  max?: number | undefined
  unit: string
  plural?: string | undefined
}

What a batch makes, such as 24 cookies or 2–3 loaves. Only amount and max scale, so a number inside unit, such as one in parentheses, stays as written, and parseRecipe refuses text with a second number outside them, as in '24 cookies or 12 bars', as YieldInput describes. Print it with formatYield. See Servings and yield.

Name Type Description
amount number A positive number. Scaling uses it when the recipe has no servings.
max number | undefined The upper end of a range, as in “2–3 loaves”. It’s greater than amount.
unit string What the recipe makes, singular or as written, such as 'cookie' or 'dozen'.
plural string | undefined The plural of unit, such as 'cookies', used for amounts that print as more than 1 or as a decimal, and for ranges, unless a range’s ends round to the same number, which takes that number’s form, so formatYield writes amount: 1 with max: 1.1 as “1 loaf”. 1 and fractions below 1, such as ½, use unit. With a label pack, the pack’s language picks the form, so French uses unit for 1 ½.

Times

TypeScript
type Times = {
  prep?: number | undefined
  cook?: number | undefined
  total?: number | undefined
  custom: CustomTime[]
}

Durations in minutes.

Name Type Description
prep number | undefined The prep time.
cook number | undefined The cook time.
total number | undefined The total time as authored. It isn’t computed from prep and cook.
custom CustomTime[] Other named times, such as chilling or rising. It’s empty when the input has none.

CustomTime

TypeScript
type CustomTime = {
  id: string
  label: string
  minutes: number
}

A named time other than prep, cook, and total.

Name Type Description
id string The authored ID, or one derived from label, or 'time' when it has no letters or numbers in its NFKD form, made unique among the custom times: 'chill', then 'chill-2'.
label string The name to show, such as “Chill”.
minutes number The duration in minutes.

Note

TypeScript
type Note = {
  id: string
  title?: string | undefined
  text: string
}

A note about the recipe, such as how to store it.

Name Type Description
id string The authored ID, or one derived from title and made unique among the notes. An untitled note, or one whose title has no letters or numbers in its NFKD form, uses its position, as in 'note-2', with -2 and so on added as for other repeated IDs.
title string | undefined A heading, such as “Storage”. Absent for an untitled note.
text string The note. It’s plain text, so render it as text, not as HTML.

Equipment

TypeScript
type Equipment = {
  id: string
  name: string
  plural?: string | undefined
  quantity?: number | undefined
  url?: string | undefined
  note?: string | undefined
}

A tool the recipe needs, such as a whisk or a baking sheet. Equipment stays the same when a recipe is scaled.

Name Type Description
id string The authored ID, or one derived from name, or 'equipment' when it has no letters or numbers in its NFKD form, made unique among the equipment: 'whisk', then 'whisk-2'.
name string The name as written.
plural string | undefined The plural name, used when quantity prints as more than 1, as in “2 baking sheets”.
quantity number | undefined How many, as a whole number greater than 0.
url string | undefined A product page, as an http, https, or relative URL.
note string | undefined A short note, such as “or a cast-iron pan”.

Nutrition

TypeScript
type Nutrition = {
  servingSize?: string | undefined
  calories?: number | undefined
  fat?: number | undefined
  saturatedFat?: number | undefined
  transFat?: number | undefined
  unsaturatedFat?: number | undefined
  carbohydrates?: number | undefined
  sugar?: number | undefined
  fiber?: number | undefined
  protein?: number | undefined
  sodium?: number | undefined
  cholesterol?: number | undefined
}

Nutrition for one of the recipe’s servings. Nutrition stays the same when a recipe is scaled.

Name Type Description
servingSize string | undefined What one serving is, such as “1 slice” or “100 g”.
calories number | undefined Energy in kcal.
fat number | undefined Total fat in g.
saturatedFat number | undefined Saturated fat in g.
transFat number | undefined Trans fat in g.
unsaturatedFat number | undefined Unsaturated fat in g.
carbohydrates number | undefined Carbohydrates in g.
sugar number | undefined Sugar in g.
fiber number | undefined Fiber in g.
protein number | undefined Protein in g.
sodium number | undefined Sodium in mg.
cholesterol number | undefined Cholesterol in mg.

Input types

Recipe input is what you write. Check it with satisfies RecipeInput, and normalize it with parseRecipe. Author recipes shows each form.

RecipeInput

TypeScript
type RecipeInput<Line extends string = never> = {
  id?: string | undefined
  name: string
  description?: string | undefined
  image?: string | undefined
  servings?: ServingsInput | undefined
  yield?: YieldInput | undefined
  system?: System | undefined
  times?: TimesInput | undefined
  ingredients?:
    | readonly (Line | IngredientInput | IngredientSectionInput<Line>)[]
    | undefined
  steps?: readonly (string | StepInput | StepSectionInput)[] | undefined
  notes?: readonly (string | NoteInput)[] | undefined
  equipment?: readonly (string | EquipmentInput)[] | undefined
  nutrition?: NutritionInput | undefined
}

A recipe as you write it. RecipeInput holds ingredient objects. RecipeInput<string> also allows ingredient lines, for input you parse with parseIngredientLine.

Name Type Description
id string | undefined An ID that loses the whitespace at its ends, as with String.prototype.trim, and is derived from name when absent or left empty, or 'recipe' when name has no letters or numbers in its NFKD form.
name string The recipe name.
description string | undefined A short description of the recipe.
image string | undefined An image URL.
servings ServingsInput | undefined How many servings the recipe makes.
yield YieldInput | undefined What a batch makes. It needs a unit.
system System | undefined The measurement system the recipe is written in. It’s inferred from ingredient quantities when absent.
times TimesInput | undefined Prep, cook, total, and custom times.
ingredients readonly (Line | IngredientInput | IngredientSectionInput<Line>)[] | undefined Ingredient objects, sections, or a mix, and lines when Line is string. Any entry with items is a section.
steps readonly (string | StepInput | StepSectionInput)[] | undefined Steps as strings, objects, sections, or a mix.
notes readonly (string | NoteInput)[] | undefined Notes as strings or objects.
equipment readonly (string | EquipmentInput)[] | undefined Equipment as strings or objects.
nutrition NutritionInput | undefined Nutrition for one serving.

A missing or empty ingredients or steps list, or an empty section, is an empty_list issue with the severity warning.

IngredientInput

TypeScript
type IngredientInput = {
  id?: string | undefined
  name: string
  plural?: string | undefined
  quantity?: QuantityInput | undefined
  equivalents?: readonly QuantityInput[] | undefined
  note?: string | undefined
  url?: string | undefined
  optional?: boolean | undefined
}

An ingredient as you write it.

Name Type Description
id string | undefined An ID that loses the whitespace at its ends, as with String.prototype.trim, and is derived from name when absent or left empty, or 'ingredient', with -2 and so on added as for other repeated IDs, when name has no letters or numbers in its NFKD form.
name string The name, singular when you set plural.
plural string | undefined The plural name, used after a bare count that prints as more than 1 or as a decimal, or a range, unless its ends round to the same number, which takes that number’s form: “2 eggs”, “1–2 eggs”, but “1 egg” for 1–1.04. 1.04 eggs, which kitchen rounding prints as 1, is “1 egg”. 1 and fractions below 1, such as ½, use name. With a label pack, the pack’s language picks the form, so French uses name for 1 ½.
quantity QuantityInput | undefined The amount and unit.
equivalents readonly QuantityInput[] | undefined Alternatives to quantity, in order of preference. They need a quantity. When quantity is in a count unit, such as can, each is the amount for the whole count, not for each item: { quantity: '2 cans', equivalents: ['30 oz'] } has a size of 15 oz each, and 2–3 cans of 30 oz each are equivalents: ['60–90 oz'].
note string | undefined A short note, such as “melted”.
url string | undefined A product page or another recipe, as an http, https, or relative URL.
optional boolean | undefined Whether the recipe works without this ingredient. It’s false when absent.

IngredientSectionInput

TypeScript
type IngredientSectionInput<Line extends string = never> = {
  id?: string | undefined
  title?: string | undefined
  items: readonly (Line | IngredientInput)[]
}

A group of ingredients. Sections can’t be nested.

Name Type Description
id string | undefined An ID that loses the whitespace at its ends, as with String.prototype.trim, and is derived from title when absent or left empty, or 'ingredients', with -2 and so on added as for other repeated IDs, when there’s no title or it has no letters or numbers in its NFKD form.
title string | undefined The section heading.
items readonly (Line | IngredientInput)[] The ingredients in the section, and lines when Line is string.

IngredientLine

TypeScript
type IngredientLine = {
  name: string
  plural?: string | undefined
  quantity?: Quantity | undefined
  equivalents?: Quantity[] | undefined
  note?: string | undefined
  optional?: boolean | undefined
}

An ingredient read from a line of text by parseIngredientLine. It’s ingredient input with parsed quantities and no id or url. resolveIngredient takes it as it is. To use it in a recipe, pass it to parseRecipe, or put the line itself in recipe input and parse it with { parseIngredientLine }. Fields the line doesn’t have are absent.

Name Type Description
name string The name, singular when plural is set. The whole line when it couldn’t be read.
plural string | undefined The plural name, set after a bare count, as in “2 eggs”. See parseIngredientLine for every rule, such as when there’s none ('2 broccoli').
quantity Quantity | undefined The leading amount and unit. See parseIngredientLine for every rule, such as a unit with no amount ('pinch of salt'), a measure in parentheses ('Butter (100g)'), or a sum ('1 lb 2 oz flour').
equivalents Quantity[] | undefined A second measure, such as the 190 g in “1 ½ cups (190 g) flour”.
note string | undefined The text after the first comma outside parentheses that isn’t between two digits, text in parentheses that isn’t a measure or optional, and phrases such as “to taste”.
optional boolean | undefined true when the line is marked optional.

StepInput

TypeScript
type StepInput = {
  id?: string | undefined
  text: string
  name?: string | undefined
  image?: string | undefined
}

A step as you write it, when it needs a name, an image, or an ID. A string is a step with only text.

Name Type Description
id string | undefined An ID that loses the whitespace at its ends, as with String.prototype.trim, and is derived from name, or from the step number with -2 and so on added as for other repeated IDs, when absent or left empty.
text string The step’s text.
name string | undefined A short label, such as “Make the dough”.
image string | undefined An image URL.

StepSectionInput

TypeScript
type StepSectionInput = {
  id?: string | undefined
  title?: string | undefined
  items: readonly (string | StepInput)[]
}

A group of steps. Sections can’t be nested.

Name Type Description
id string | undefined An ID that loses the whitespace at its ends, as with String.prototype.trim, and is derived from title when absent or left empty, or 'steps', with -2 and so on added as for other repeated IDs, when there’s no title or it has no letters or numbers in its NFKD form.
title string | undefined The section heading.
items readonly (string | StepInput)[] The steps in the section.
TypeScript
import { parseRecipe } from '@recipe-book/core'

const result = parseRecipe({
  name: 'Pizza',
  steps: [
    { title: 'Dough', items: ['Knead the dough.'] },
    { title: 'Bake', items: ['Bake for 10 minutes.'] },
  ],
})
if (!result.success) throw result.error

result.data.steps.map((section) => section.id) // ['dough', 'bake']
result.data.steps[1]?.items[0]?.id // 'step-2'

NoteInput

TypeScript
type NoteInput = {
  id?: string | undefined
  title?: string | undefined
  text: string
}

A note as you write it, when it needs a title or an ID. A string is a note with only text.

Name Type Description
id string | undefined An ID that loses the whitespace at its ends, as with String.prototype.trim, and is derived from title, or from the note’s position with -2 and so on added as for other repeated IDs, when absent or left empty.
title string | undefined A heading, such as “Storage”.
text string The note, as plain text.

EquipmentInput

TypeScript
type EquipmentInput = {
  id?: string | undefined
  name: string
  plural?: string | undefined
  quantity?: number | undefined
  url?: string | undefined
  note?: string | undefined
}

Equipment as you write it, when it needs more than a name. A string is equipment with only a name.

Name Type Description
id string | undefined An ID that loses the whitespace at its ends, as with String.prototype.trim, and is derived from name when absent or left empty, or 'equipment', with -2 and so on added as for other repeated IDs, when name has no letters or numbers in its NFKD form.
name string The name, singular when you set plural.
plural string | undefined The plural name, used when quantity is above 1.
quantity number | undefined How many, as a whole number greater than 0.
url string | undefined A product page, as an http, https, or relative URL.
note string | undefined A short note.

QuantityInput

TypeScript
type QuantityInput =
  | QuantityString
  | number
  | {
      amount: number | { min: number; max: number }
      unit?: UnitAlias | `${UnitAlias}.` | undefined
    }

A quantity as you write it: quantity text, a count, or an object with an amount and a unit alias.

Name Type Description
amount number | { min: number; max: number } A number from 1e-300 to 1e290, or a range of such numbers as { min, max }. A range with equal ends reads as a number.
unit UnitAlias | `${UnitAlias}.` | undefined A unit alias, which may end in a period, as in 'tbsp.'. Without one, the quantity is a bare count.

The parsers’ units option applies to text only, so an object’s 'cup' stays a US cup. Write 'cup-metric' or 'tbsp-au' in an object instead.

QuantityString

TypeScript
type QuantityString =
  | `${string}${Digit | VulgarFraction}`
  | `${string} ${UnitAlias}`
  | `${string} ${UnitAlias}.`
  | `${number}${UnitAlias}`
  | `${number}${UnitAlias}.`

Quantity text, such as '1 ½ cups'. It must end in a digit, a fraction such as ½, or a unit alias with an optional period ('2 tbsp.'), so a misspelled unit is a compile error.

The type checks only the ending, and parseQuantity checks the rest at runtime, so '0 cups' type-checks but is an invalid_amount issue. The type is also stricter than the parser. For example, an alias must match its listed case, only a plain number can sit right before a unit, and the text can’t end in whitespace, so '2 Cups', '1½cups', and '2 cups ' parse but don’t type-check.

DurationInput

TypeScript
type DurationInput = number | `P${string}`

A duration in minutes, or an ISO 8601 duration such as 'PT1H30M'. ISO 8601 durations can use weeks, days, hours, minutes, and seconds, and only the smallest component can have a fraction, as in 'PT1.5H'. Years and months aren’t accepted, because their length varies, unless they’re zero, as in 'P0Y0M0DT0H30M'.

The type checks only the leading P, so 'P1Y' type-checks but is an invalid_duration issue. The parser also accepts lowercase letters and a decimal comma, as in 'PT1,5H', but 'pt1h30m' doesn’t type-check.

ServingsInput

TypeScript
type ServingsInput =
  | number
  | string
  | {
      amount: number
      max?: number | undefined
    }

A number of servings, range text such as '4–6' or '4 to 6', or a Servings object such as { amount: 4, max: 6 }. Text has only the number or range, so '4 servings' is an invalid_quantity issue. The amount must be positive.

Name Type Description
amount number A number from 1e-300 to 1e290.
max number | undefined The upper end of a range, as in “4–6 servings”. A max outside 1e-300 to 1e290, such as 0, NaN, or 1e300, is an invalid_amount issue, as for amount. Otherwise, a max less than amount is an invalid_range issue, and one equal to amount is dropped.

YieldInput

TypeScript
type YieldInput =
  | string
  | {
      amount: number
      max?: number | undefined
      unit: string
      plural?: string | undefined
    }

What a batch makes: text such as '24 cookies' or '2–3 loaves', or a Yield such as { amount: 24, unit: 'cookie', plural: 'cookies' }. Text starts with the amount, so 'Makes 24 cookies' is an invalid_quantity issue. The amount must be positive.

Name Type Description
amount number A number from 1e-300 to 1e290.
max number | undefined The upper end of a range, as in “2–3 loaves”. A max outside 1e-300 to 1e290, such as 0, NaN, or 1e300, is an invalid_amount issue, as for amount. Otherwise, a max less than amount is an invalid_range issue, and one equal to amount is dropped.
unit string What the recipe makes, singular or as written, such as 'cookie' or 'loaves'.
plural string | undefined The plural of unit, such as 'cookies'. Without it, every amount uses unit.

Text gets both forms the way a bare count in an ingredient line does, from the word before “of”, a leading container, or else the last word before a comma or parentheses, but a leading container such as “loaf” counts only when it’s plural, the last word outside parentheses, or before text ending in “bread”. So '1 sheet cake' doubles to “2 sheet cakes”, '1 cake (20 cm)' to “2 cakes (20 cm)”, '2 loaf cakes' halves to “1 loaf cake”, and '1 loaf banana bread' doubles to “2 loaves banana bread”. After a decimal below 1, as after a count above 1, that word is made singular, so '0.5 loaves' doubles to “1 loaf”. A unit with no other form stays as written. That includes dozen, the symbol of a unit Recipe Book knows that’s the same in the plural, such as L, kg, tbsp, or fl oz, the abbreviations T, t, tb, tl, el, fl-oz, tbsp-au, and c (but not C), and these nouns that are the same in the plural: sheep, deer, moose, fish, shrimp, squid, salmon, trout, bass, or anise. So '2 dozen' halves to “1 dozen”, '1 L' doubles to “2 L”, and '1 sheep' doubles to “2 sheep”. Another symbol or noun can still get a plural, so '1 cm' doubles to “2 cms” and '1 cod' to “2 cods”. The singular and plural are English whatever the recipe’s language, so '1 Kuchen (Ø 26 cm)' doubles to “2 Kuchens (Ø 26 cm)” and '2 Glas (200 ml)' becomes “1 Gla (200 ml)” at an amount of 1. A second number outside parentheses, which wouldn’t scale with the amount, is an invalid_quantity issue, as in '24 cookies or 12 bars' or '12 up to 16 rolls'. A size isn’t a second number: a number before oz, lb, lbs, pound, pounds, g, mg, kg, l, ml, or cm, in any case, later in the text, anywhere but right after the amount, as in '1 roast, 2 lb 4 oz' or '1 large 2 lb roast', or a size in digits, such as 9 or 9.5, written with “inch” or “inches” right after an amount in numerals, with or without a dash, so '1 9 inch layer cake' doubles to “2 9 inch layer cakes”. A single number before lb or another of those units right after the amount, as in '1 2 lb roast', is an invalid_quantity issue unless a dash joins it to the unit, as in '1 2-lb roast'. A range joined by a dash with no spaces right after the amount isn’t a second number when lb or another of those units, or “inch” or “inches”, comes after it, so '1 2–3 lb roast' doubles to “2 2–3 lb roasts” and '1 9-10 inch tart' to “2 9-10 inch tarts”. A range there with anything else after it is an invalid_quantity issue: a range of counts, as in '24 12–16 bars', and a range of sizes before any other unit, such as “quart”, “cup”, or “ounce”, as in '1 1–2 quart casserole' or '1 9–10 in pie'. Put such a size in parentheses: '1 casserole (1–2 quart)' doubles to “2 casseroles (1–2 quart)”. A range with a space before the dash, or “to”, as in '1 2 – 3 lb roast' or '1 2 to 3 lb roast', is an invalid_quantity issue too. Nor is a number between a “(” and the next “)”, so '1 loaf (about 8 slices)' doubles to “2 loaves (about 8 slices)”. Nor is a number, or a range such as 12–16 that doesn’t come right after the amount, with anything but a space right before it or anything but a space, ,, ., or / right after it, so '1 9x13 pan' doubles to “2 9x13 pans”, '1 2-layer cake' doubles to “2 2-layer cakes”, '1 #10 can' doubles to “2 #10 cans”, and '1 cake, x16' doubles to “2 cakes, x16”, while '24 cookies or 12–16 bars' is an invalid_quantity issue. A dash right after the amount makes a range, though, so '1 -2 layer cake' reads as 1–2. A size written with “in” after a space, as in '1 9 in pie', is an invalid_quantity issue, and so is a size with a fraction unless a dash joins it into one word, so '1 9½ inch tart' and '1 9 1/2-inch tart' are issues but '1 9½-inch tart' and '1 9-1/2 inch tart' aren’t. Other words after a singular container are counted, so '1 jar jam' doubles to “2 jar jams”. Write “of”, as in '1 jar of jam', to count the container. Write a range with a dash or “to”: '3 or 4 loaves' is an invalid_quantity issue. So is a + right after the amount, as in '1/2 + 1/4 cup' or '24+ cookies'. A number joined to the + doesn’t change that, so '2 +1 loaves' is one too. Text with a size anywhere but right after the amount keeps its noun as written, so '1 tart, 20 cm' doubles to “2 tart, 20 cm”, '1 large 2 lb roast' to “2 large 2 lb roast”, and '1 tart, 20–23 cm' to “2 tart, 20–23 cm”, but a size joined to its unit, as in '1 tart, 20cm', leaves the noun counted, so it doubles to “2 tarts, 20cm”. So does a range of sizes with more than one word after it, so '1 whole 3–4 lb chicken' doubles to “2 whole 3–4 lb chickens”. A range of sizes there with the unit only at the end and a space before the dash, or “to”, as in '1 tart, 20 – 23 cm' or '1 tart, 20 to 23 cm', is an invalid_quantity issue, but '1 tart, 20 cm to 23 cm' stays as written. A yield needs a unit, so a number such as 4 is an invalid_type issue, and for a finite number greater than 0 its message points to servings.

parseIngredientLine lists the endings that make that word singular, and their exceptions.

TimesInput

TypeScript
type TimesInput = {
  prep?: DurationInput | undefined
  cook?: DurationInput | undefined
  total?: DurationInput | undefined
  custom?: readonly CustomTimeInput[] | undefined
}

Times as you write them.

Name Type Description
prep DurationInput | undefined The prep time.
cook DurationInput | undefined The cook time.
total DurationInput | undefined The total time.
custom readonly CustomTimeInput[] | undefined Other named times, such as chilling or rising.

CustomTimeInput

TypeScript
type CustomTimeInput = {
  id?: string | undefined
  label: string
  minutes: DurationInput
}

A named time as you write it, such as { label: 'Chill', minutes: 120 } or { label: 'Rise', minutes: 'PT1H' }.

Name Type Description
id string | undefined An ID that loses the whitespace at its ends, as with String.prototype.trim, and is derived from label when absent or left empty, or 'time', with -2 and so on added as for other repeated IDs, when label has no letters or numbers in its NFKD form.
label string The name to show, such as “Chill”.
minutes DurationInput The duration in minutes or as an ISO 8601 duration.

NutritionInput

TypeScript
type NutritionInput = {
  servingSize?: string | undefined
  calories?: NutrientInput | undefined
  fat?: NutrientInput | undefined
  saturatedFat?: NutrientInput | undefined
  transFat?: NutrientInput | undefined
  unsaturatedFat?: NutrientInput | undefined
  carbohydrates?: NutrientInput | undefined
  sugar?: NutrientInput | undefined
  fiber?: NutrientInput | undefined
  protein?: NutrientInput | undefined
  sodium?: NutrientInput | undefined
  cholesterol?: NutrientInput | undefined
}

Nutrition as you write it, for one of the recipe’s servings. Each nutrient is a number in its unit, or text with a unit, which is converted: calories: '1046 kJ' becomes 250, sodium: '1.2 g' becomes 1200, and fat: '0.5 oz' becomes about 14.2. Text without a unit, such as fat: '12', is in the nutrient’s unit. The amount is read as in quantity text, so fiber: '1 ½ g' works. Zero is allowed, and empty text counts as absent.

Text that can’t be read as one number in the right kind of unit, such as a range or fat: '250 kcal', is an invalid_quantity issue. A negative or non-finite number is an invalid_amount issue.

Name Type Description
servingSize string | undefined What one serving is, such as “1 slice” or “100 g”.
calories NutrientInput | undefined Energy in kcal, or text in kcal or kJ.
fat NutrientInput | undefined Total fat in g, or text with a mass unit.
saturatedFat NutrientInput | undefined Saturated fat in g, or text with a mass unit.
transFat NutrientInput | undefined Trans fat in g, or text with a mass unit.
unsaturatedFat NutrientInput | undefined Unsaturated fat in g, or text with a mass unit.
carbohydrates NutrientInput | undefined Carbohydrates in g, or text with a mass unit.
sugar NutrientInput | undefined Sugar in g, or text with a mass unit.
fiber NutrientInput | undefined Fiber in g, or text with a mass unit.
protein NutrientInput | undefined Protein in g, or text with a mass unit.
sodium NutrientInput | undefined Sodium in mg, or text with a mass unit.
cholesterol NutrientInput | undefined Cholesterol in mg, or text with a mass unit.

NutrientInput

TypeScript
type NutrientInput = number | string

One nutrient as you write it: a number in the nutrient’s unit, or text with a unit, such as '12 g' or '1046 kJ'. Text without a unit, such as '12', is in the nutrient’s unit.

Label packs

A label pack holds one language’s words for units, durations, temperatures, and sizes, as What a pack holds lists.

LabelPack

What the formatting functions take as labels: a pack from @recipe-book/core/labels, or one that labelPack made. It’s a frozen LabelWords that also holds the words labelPack checked, under a key only Recipe Book reads. A copy of a pack made with a spread isn’t a pack, so pass the copy to labelPack. TypeScript rejects a spread copy as a LabelPack, but not a copy made with Object.assign or structuredClone, which throws all the same. Recipe Book tells a pack by that key alone, so an object that sets the key itself, rather than getting it from labelPack or from a pack it inherits from, as Object.create(de) does, isn’t checked again, and a formatting function given one can throw a TypeError.

LabelWords

TypeScript
type LabelWords = {
  readonly language?: string | undefined
  readonly units?:
    | {
        readonly [Id in UnitId]?:
          | {
              readonly short: { readonly one: string; readonly other: string }
              readonly long: { readonly one: string; readonly other: string }
              readonly aliases?: readonly string[] | undefined
            }
          | undefined
      }
    | undefined
  readonly durations?:
    | {
        readonly [Unit in 'day' | 'hour' | 'minute' | 'second']?:
          | {
              readonly short: { readonly one: string; readonly other: string }
              readonly long: { readonly one: string; readonly other: string }
            }
          | undefined
      }
    | undefined
  readonly temperature?:
    | {
        readonly degree: { readonly one: string; readonly other: string }
        readonly C: string
        readonly F: string
      }
    | undefined
  readonly size?:
    | {
        readonly each: string
        readonly total: string
      }
    | undefined
}

The words that the formatting functions write, which labelPack makes into a pack. A pack can hold only the units you want to change: any unit or duration unit it leaves out keeps its English labels, and without temperature or size, their words are English too.

Name Type Description
language string | undefined The language tag of the words, such as 'de', which picks their plural forms. Defaults to 'en'. Numbers follow locale instead.
units object | undefined Labels by unit ID: short, such as 'EL', and long, such as 'Esslöffel', each as one and other, and aliases, other spellings of the unit, such as 'Teel.', which are never written.
durations object | undefined Labels for formatDuration by unit: short, such as 'Std.', and long, such as 'Stunde' and 'Stunden'.
temperature { readonly degree: { readonly one: string; readonly other: string }; readonly C: string; readonly F: string } | undefined The words of formatTemperature’s long form: degree, as one and other, and the names C and F, as in 180 Grad Celsius. Its short form, 180 °C, doesn’t change.
size { readonly each: string; readonly total: string } | undefined The words after a count unit’s size: each after a size for each one, as in 2 Dosen (425 g pro Stück), and total after a size for the whole count, as in 2 Dosen (49 g insgesamt). Without it, they’re “each” and “total”.

The number as printed picks the form. A label takes one for a printed number the pack’s language puts in its one category. 1.04 tbsp, which kitchen rounding prints as 1, and a fraction below 1 take the form 1 takes, as in ½ Prise. It takes other for every other printed number and for a range, unless its ends round to the same number, which takes that number’s form, as in 1 Prise for 1–1.04 pinches. So a pack has two forms even for a language with more. English, en alone or with a region such as en-GB, uses Recipe Book’s own rule, singular only for 1. Other languages use the runtime’s Intl.PluralRules, so French writes 1 ½ pincée and German 1 ½ Prisen. A language the runtime doesn’t support uses the English rule, as does a runtime without Intl or without Intl.PluralRules.

labelPack reads a language, group, or entry that’s undefined as absent, but an entry that’s there needs every label.

The formatting functions take only a pack, so they throw invalid_argument for any other labels, whatever they write. formatServings ignores labels.

Contents