@magrinj/parse-ingredients

A multi-language recipe ingredient parser. Parse, combine, and format ingredients with zero dependencies.

Why this library?

• Multi-language support — 6 languages built-in: English, French, Spanish, Italian, German, and Portuguese. Extensible locale system makes adding new languages straightforward.
• Parse + Combine + Pretty — Three complementary functions for the full ingredient workflow: parse strings into structured objects, combine duplicates across recipes, and format them back into readable text.
• Zero runtime dependencies — Pure TypeScript, lightweight and fast. Nothing to audit, nothing to worry about.

Installation

# npm
npm install @magrinj/parse-ingredients

# yarn
yarn add @magrinj/parse-ingredients

# pnpm
pnpm add @magrinj/parse-ingredients

# bun
bun add @magrinj/parse-ingredients

Quick Start

import parse from '@magrinj/parse-ingredients';

parse('1 teaspoon of basil');
// {
//   quantity: '1',
//   unit: 'teaspoon',
//   ingredient: 'basil',
//   article: 'of',
//   symbol: 'tsp',
//   minQty: '1',
//   maxQty: '1'
// }

French

import parse from '@magrinj/parse-ingredients';
import '@magrinj/parse-ingredients/locale/fr';

parse('2 cuillères à soupe de sucre');
// {
//   quantity: '2',
//   unit: 'cuillère à soupe',
//   ingredient: 'sucre',
//   article: 'de',
//   symbol: 'c. à s.',
//   minQty: '2',
//   maxQty: '2'
// }

API

parse(line: string, options?: Options): Ingredient

Parses a single ingredient string into a structured object. Handles quantities (integers, decimals, fractions, ranges, Unicode fractions), units, articles, and ingredient names.

parse('1-2 cups of flour');
// { quantity: '1', unit: 'cup', ingredient: 'flour', minQty: '1', maxQty: '2', ... }

combine(ingredients: Ingredient[]): Ingredient[]

Aggregates duplicate ingredients by summing quantities. Ingredients match when they have the same name and unit.

import {combine} from '@magrinj/parse-ingredients';

combine([
  {quantity: '1', unit: 'cup', ingredient: 'flour', article: 'of', symbol: 'c', minQty: '1', maxQty: '1'},
  {quantity: '2', unit: 'cup', ingredient: 'flour', article: 'of', symbol: 'c', minQty: '2', maxQty: '2'},
]);
// [{ quantity: '3', unit: 'cup', ingredient: 'flour', minQty: '3', maxQty: '3', ... }]

pretty(ingredient: Ingredient): string

Formats an Ingredient object back into a human-readable string. Converts decimals to fractions (0.5 → 1/2, 0.333 → 1/3, etc.).

import {pretty} from '@magrinj/parse-ingredients';

pretty({quantity: '1.5', unit: 'cup', ingredient: 'milk', article: 'of', symbol: 'c', minQty: '1.5', maxQty: '1.5'});
// "1 1/2 cups of milk"

Types

interface Ingredient {
  ingredient: string;
  quantity: string | null;
  unit: string | null;
  article: string | null;
  symbol: string | null;
  minQty: string | null;
  maxQty: string | null;
}

interface Options {
  language: {
    from: string;
    to: string;
  };
}

Supported Languages

| Language | Locale Code | Import | |----------|-------------|--------| | English | en | Default (no import needed) | | French | fr | import '@magrinj/parse-ingredients/locale/fr' | | Spanish | es | import '@magrinj/parse-ingredients/locale/es' | | Italian | it | import '@magrinj/parse-ingredients/locale/it' | | German | de | import '@magrinj/parse-ingredients/locale/de' | | Portuguese | pt | import '@magrinj/parse-ingredients/locale/pt' |

Documentation

For detailed guides and API reference, visit the documentation site.

Support

If you find this library useful, consider supporting its development:

License

MIT