@cooklang/cooklang

Official Cooklang parser for JavaScript and TypeScript.

This is a high-performance WASM implementation powered by the Rust cooklang-rs parser. It provides fast, reliable recipe parsing with full support for the Cooklang specification.

Installation

npm install @cooklang/cooklang

Quick Start

import { Parser } from '@cooklang/cooklang';

const parser = new Parser();
const recipe = parser.parse(`
>> servings: 4

Add @salt and @pepper to taste.
Cook for ~{10%minutes}.
`);

console.log(recipe.sections[0].content);

Why WASM?

This package uses WebAssembly for several key benefits:

• Performance: Native-speed parsing, significantly faster than pure JavaScript
• Reliability: Shared implementation with the official Rust parser means consistent behavior across platforms
• Maintainability: Changes to the Cooklang spec are implemented once in Rust and automatically available here

Migration from @cooklang/cooklang-ts

If you're migrating from the previous TypeScript-native @cooklang/cooklang-ts package (v1.x), please see the Migration Guide.

Key differences:

• Different package name: @cooklang/cooklang-ts → @cooklang/cooklang
• API changes: The WASM implementation has a different API surface
• Version numbering: This package tracks the Rust core version (currently 0.17.x)

API Reference

Parser

import { Parser } from '@cooklang/cooklang';

const parser = new Parser();
const recipe = parser.parse(recipeText);

Recipe Structure

The parsed recipe contains:

interface Recipe {
  sections: Section[];
  metadata: Record<string, string>;
  ingredients: Ingredient[];
  cookware: Cookware[];
  timers: Timer[];
}

Helper Functions

import {
  ingredient_should_be_listed,
  ingredient_display_name,
  cookware_should_be_listed,
  cookware_display_name,
  quantity_display,
  grouped_quantity_display,
  grouped_quantity_is_empty
} from '@cooklang/cooklang';

Value Extraction

Utility functions for working with quantities:

import { getNumericValue, extractNumericRange } from '@cooklang/cooklang';

const value = ingredient.quantity?.value;
const numeric = getNumericValue(value); // 2.5
const range = extractNumericRange(value); // { start: 2, end: 3 }

Version Synchronization

This package version tracks the Rust cooklang-rs version. For example:

• npm @cooklang/[email protected] = Rust [email protected]

We use 0.x versioning to match the Rust core library. The parser is production-ready and actively maintained. We'll bump to 1.0 when the Rust core reaches 1.0.

Browser Support

This package works in:

• Node.js 16+
• Modern browsers (Chrome, Firefox, Safari, Edge)
• Bundlers (Webpack, Vite, Rollup, etc.)

Contributing

This package is part of the cooklang-rs monorepo. Contributions are welcome!

License

MIT - see LICENSE

Links

• Cooklang Specification
• Cooklang Website
• GitHub Repository
• Issue Tracker