3.8Core reference
Types
Reference for the recipe model that parseRecipe returns, the recipe input types you write, and the label pack type.
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
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
type ParsedRecipe = RecipeThe same type as Recipe, for files that also import @recipe-book/react as Recipe.
IngredientSection
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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. |
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
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
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
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
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
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
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
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
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
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
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
type NutrientInput = number | stringOne 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
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.