⚠️ This is pre-release documentation for v3. For stable docs, visit v2.
@tmlmt/cooklang-parser

Appearance

@tmlmt/cooklang-parser / ShoppingList

Class: ShoppingList ​

Shopping List generator.

Usage ​

  • Create a new ShoppingList instance with an optional category configuration (see constructor)
  • Add recipes, scaling them as needed (see addRecipe())
  • Categorize the ingredients (see categorize())

Example ​

typescript
import * as fs from "fs";
import { ShoppingList } from @tmlmt/cooklang-parser;

const categoryConfig = fs.readFileSync("./myconfig.txt", "utf-8")
const recipe1 = new Recipe(fs.readFileSync("./myrecipe.cook", "utf-8"));
const shoppingList = new ShoppingList();
shoppingList.setCategoryConfig(categoryConfig);
// Quantities are automatically calculated and ingredients categorized
// when adding a recipe
shoppingList.addRecipe(recipe1);

Constructors ​

Constructor ​

new ShoppingList(categoryConfigStr?): ShoppingList

Creates a new ShoppingList instance

Parameters ​

categoryConfigStr? ​

string | CategoryConfig

The category configuration to parse.

Returns ​

ShoppingList

Properties ​

categories? ​

optional categories?: CategorizedIngredients

The categorized ingredients in the shopping list.

categoryConfig? ​

optional categoryConfig?: CategoryConfig

The category configuration for the shopping list.

checkedItems ​

checkedItems: Set<string>

Set of checked ingredient names (lowercased for case-insensitive matching).

ingredients ​

ingredients: AddedIngredient[] = []

The ingredients in the shopping list.

manualItems ​

manualItems: AddedIngredient[] = []

Free-hand ingredient lines not tied to any recipe.

pantry? ​

optional pantry?: Pantry

The original pantry (never mutated by recipe calculations).

recipes ​

recipes: AddedRecipe[] = []

The recipes in the shopping list.

unitSystem? ​

optional unitSystem?: SpecificUnitSystem

The unit system to use for quantity simplification. When set, overrides per-recipe unit systems.

Methods ​

addManualItem() ​

addManualItem(item): void

Adds a free-hand ingredient item to the shopping list, then automatically recalculates the quantities and recategorize the ingredients.

Parameters ​

item ​

AddedIngredient

The ingredient item to add.

Returns ​

void

addPantry() ​

addPantry(pantry, options?): void

Adds a pantry to the shopping list. On-hand pantry quantities will be subtracted from recipe ingredient needs on each recalculation.

Parameters ​

pantry ​

string | Pantry

A Pantry instance or a TOML string to parse.

options? ​

PantryOptions

Options for pantry parsing (only used when providing a TOML string).

Returns ​

void

addRecipe() ​

addRecipe(recipe, options?): void

Adds a recipe to the shopping list, then automatically recalculates the quantities and recategorize the ingredients.

Parameters ​

recipe ​

Recipe

The recipe to add.

options? ​

AddedRecipeOptions = {}

Options for adding the recipe.

Returns ​

void

Throws ​

Error if the recipe has alternatives without corresponding choices.

categorize() ​

categorize(): void

Categorizes the ingredients in the shopping list Will use the category config if any, otherwise all ingredients will be placed in the "other" category

Returns ​

void

check() ​

check(ingredientName): void

Mark an ingredient as checked (case-insensitive).

Parameters ​

ingredientName ​

string

The ingredient name.

Returns ​

void

checkedAppendLine() ​

static checkedAppendLine(ingredientName, checked): string

Generate a single line to append to a .shopping-checked file.

Parameters ​

ingredientName ​

string

The ingredient name.

checked ​

boolean

Whether the ingredient is being checked or unchecked.

Returns ​

string

A line like "+ name\n" or "- name\n".

compactCheckedFile() ​

static compactCheckedFile(content): string

Compact a .shopping-checked file content string. Replays the log and returns a clean file with only final + entries, sorted.

Parameters ​

content ​

string

The raw .shopping-checked file content.

Returns ​

string

The compacted file content.

getPantry() ​

getPantry(): Pantry | undefined

Returns the resulting pantry with quantities updated to reflect what was consumed by the shopping list's recipes. Returns undefined if no pantry was added.

Returns ​

Pantry | undefined

The resulting Pantry, or undefined.

hydrateRecipe() ​

hydrateRecipe(path, recipe): void

After loadFile(), call this for each recipe ref once the .cook file has been loaded and parsed into a Recipe object.

Parameters ​

path ​

string

The recipe path as returned by loadFile().

recipe ​

Recipe

The parsed Recipe object.

Returns ​

void

Throws ​

Error if the path was not found in the loaded refs.

isChecked() ​

isChecked(ingredientName): boolean

Query whether an ingredient is checked (case-insensitive).

Parameters ​

ingredientName ​

string

The ingredient name.

Returns ​

boolean

True if the ingredient is checked.

loadCheckedFile() ​

loadCheckedFile(content): void

Parse a .shopping-checked file content string and populate checkedItems. Replays the append-only log: last entry per ingredient wins.

Parameters ​

content ​

string

The .shopping-checked file content.

Returns ​

void

loadFile() ​

loadFile(content): ShoppingListRecipeRef[]

Parse a .shopping-list file content string and populate internal state. Returns the unresolved recipe refs — the consuming app must load each Recipe object and call hydrateRecipe() for each one.

Parameters ​

content ​

string

The .shopping-list file content.

Returns ​

ShoppingListRecipeRef[]

Array of recipe references to resolve.

removeManualItem() ​

removeManualItem(index): void

Removes a free-hand ingredient item from the shopping list, then automatically recalculates the quantities and recategorize the ingredients.

Parameters ​

index ​

number

The index of the item to remove within ShoppingList.manualItems.

Returns ​

void

removeRecipe() ​

removeRecipe(index): void

Removes a recipe from the shopping list, then automatically recalculates the quantities and recategorize the ingredients.

Parameters ​

index ​

number

The index of the recipe to remove.

Returns ​

void

serializeCheckedFile() ​

serializeCheckedFile(): string

Serialize checkedItems to .shopping-checked file content string (compacted). One + name line per checked item, sorted alphabetically.

Returns ​

string

The serialized file content.

serializeFile() ​

serializeFile(): string

Serialize current state to .shopping-list file content string.

Returns ​

string

The serialized file content.

setCategoryConfig() ​

setCategoryConfig(config): void

Sets the category configuration for the shopping list and automatically categorize current ingredients from the list. Also propagates the configuration to the pantry if one is set.

Parameters ​

config ​

string | CategoryConfig

The category configuration to parse.

Returns ​

void

uncheck() ​

uncheck(ingredientName): void

Mark an ingredient as unchecked (case-insensitive).

Parameters ​

ingredientName ​

string

The ingredient name.

Returns ​

void

uncheckAll() ​

uncheckAll(): void

Clear all checked items.

Returns ​

void