Recipe Book0.6.0

5.2Errors

incompatible_units

convert received two units it can't convert between, such as cups and grams, or a count with no fixed size, such as a clove or a quantity without a unit.

§ 5.22 min readView as Markdown

convert received two units it can’t convert between: one measures volume and the other mass, such as cups and grams, or one is a count with no fixed size, such as clove or a quantity without a unit.

Text
RecipeBookError: Cannot convert cup (volume) to g (mass). Add an equivalent to the ingredient, e.g. equivalents: ["120 g"].
See https://recipe-book.siraj.page/errors/incompatible_units/

A cup of flour and a cup of sugar weigh different amounts, so converting volume to mass needs a density that only the recipe author knows.

Received Message
Volume and mass Cannot convert cup (volume) to g (mass). Add an equivalent to the ingredient, e.g. equivalents: ["120 g"].
Mass and volume Cannot convert g (mass) to cup (volume). Add an equivalent to the ingredient, e.g. equivalents: ["250 ml"].
A count unit Cannot convert clove to g; clove is a count unit with no fixed size. Add an equivalent to the ingredient, e.g. equivalents: ["120 g"].
Mass and a count unit Cannot convert oz to piece; piece is a count unit with no fixed size. Add an equivalent to the ingredient, e.g. equivalents: ["1 piece"].
A quantity without a unit Cannot convert a quantity without a unit to g; a bare count such as "2 eggs" has no fixed size. Add an equivalent to the ingredient, e.g. equivalents: ["120 g"].

Units by dimension

Units convert only to units of the same dimension, and count units only to themselves:

Dimension Unit IDs
Mass mg, g, kg, oz, lb
Volume ml, cl, dl, l, tsp, tbsp, tbsp-au, fl-oz, cup, cup-metric, pint, quart, gallon
Count pinch, dash, clove, slice, piece, can, package, stick, sprig, bunch, head, bag, handful, jar, stalk

The unit registry lists each unit’s size and the aliases findUnit accepts.

Add an equivalent to the ingredient

The message suggests an equivalent: a quantity the author supplies for an ingredient in recipe input, such as equivalents: ['190 g'] for 1 ½ cups of flour. The quantity in the message is a placeholder, not a conversion.

With that equivalent, resolveRecipe in the metric system shows the flour as 190 g instead of converting the cups to milliliters.

Convert to a measurement system instead

To show a US recipe in metric units, you don’t need grams. toSystem converts to a metric unit of the same dimension:

TypeScript
import { toSystem } from '@recipe-book/core'

toSystem({ amount: 1.5, unit: 'cup' }, 'metric') // { amount: 354.88235475, unit: 'ml' }

Check units before converting

Quantities from data can hold any unit, or none, and convert throws for one without a unit:

TypeScript
import { convert, type Quantity } from '@recipe-book/core'

function toGrams(quantity: Quantity) {
  return convert(quantity, 'g')
}

toGrams({ amount: 2 })

Check with canConvert first, and keep quantities it rejects as they are:

TypeScript
import { canConvert, convert, type Quantity } from '@recipe-book/core'

function toGrams(quantity: Quantity) {
  if (!canConvert(quantity.unit, 'g')) return quantity
  return convert(quantity, 'g')
}

toGrams({ amount: 1, unit: 'lb' }) // { amount: 453.59237, unit: 'g' }
toGrams({ amount: 2 }) // { amount: 2 }
Contents