⚠️ This is pre-release documentation for v3. For stable docs, visit v2.
Skip to content

Parse diagnostics ​

Recipe.parse() (and the Recipe constructor) collects known recipe problems as diagnostics. All of them, including non-fatal errors, are available on recipe.diagnostics, and the recipe instance holds the partial result. Only fatal errors (COOKLANG_E9…) make parse() throw a DiagnosticError. A zero-denominator fraction stops parsing immediately and throws ParseStoppedError, a DiagnosticError subclass that identifies the premature stop.

typescript
import {
  DiagnosticError,
  ParseStoppedError,
  Recipe,
  formatDiagnostics,
} from "@tmlmt/cooklang-parser";

const recipe = new Recipe();
try {
  recipe.parse(source);
  // Reaching this point means no fatal error occurred. Non-fatal errors and
  // warnings may still be present in recipe.diagnostics.
} catch (error) {
  if (error instanceof DiagnosticError) {
    if (error instanceof ParseStoppedError) {
      console.error("Parsing stopped early");
    }
    console.error(formatDiagnostics(error.diagnostics, error.source));
  } else {
    throw error;
  }
}

// Non-fatal errors and warnings are always available
console.log(recipe.diagnostics);

Each diagnostic contains a stable code, human-readable message, optional fix and docs URL, severity, and an optional source span. Lines and columns are 1-based. Offsets are 0-based UTF-16 code-unit indices into DiagnosticError.source, which is exactly the input passed to parse().

CategoryConfig, Pantry and ProductCatalog behave identically: parse() and the constructors throw DiagnosticError only for fatal errors, and expose all diagnostics and the source on the instance.

Diagnostic codes ​

Codes follow the pattern COOKLANG_<L><T><D><NN>: L is the letter (E for error, W for warning, I for internal/library bug); T is a tier digit used only for E codes (0 = recoverable — collected alongside other diagnostics while parsing continues, and the call returns the partial result instead of throwing; 9 = fatal — it is not safe to continue, so the call throws DiagnosticError). T is always 0 for W and I codes: warnings never make the call fail, and internal errors always behave like fatal ones but indicate a library bug rather than a problem with your input. The tier describes whether the call succeeds, not necessarily when parsing stops: the parser stops immediately when it cannot safely continue, and may otherwise finish collecting diagnostics before throwing. D is the domain digit (0 generic/internal, 1 syntax, 2 references, 3 metadata, 4 quantities and units, 5 shopping list, 6 cart and product catalog, 7 pantry and category configuration) and NN a 2-digit sequence number.

Each code has its own page, linked from diagnostic.docs (/v3/e/<code in lowercase>). See the full list of codes.

Parse-time diagnostics, reported by Recipe.parse():

CodeLevelMeaning
COOKLANG_E0101errorA recipe quantity cannot be parsed.
COOKLANG_E0102errorA timer has a value but no unit.
COOKLANG_W0101warningA block comment is never closed.
COOKLANG_E0201errorAn ingredient reference has no earlier definition.
COOKLANG_E0202errorA cookware reference has no earlier definition.
COOKLANG_E0203errorA cookware reference does not match the flags of an earlier definition.
COOKLANG_E0204errorAn ingredient reference does not match the flags and preparation of an earlier definition.
COOKLANG_W0201warningAn unreferenced ingredient duplicates an earlier ingredient with the same flags and preparation.
COOKLANG_W0202warningAn unreferenced cookware duplicates an earlier cookware with the same flags.
COOKLANG_E0301errorMetadata indentation contains a tab.
COOKLANG_E0302errorMetadata indentation levels are inconsistent.
COOKLANG_W0301warningservings or serves is not a number.
COOKLANG_E9401error (fatal)A text equivalent could not be merged with another occurrence of the same ingredient.
COOKLANG_E9402error (fatal)A fraction has a zero denominator; parsing stops immediately.
COOKLANG_W0401warningA text quantity could not be added to a numeric quantity and was kept separate.

Warnings and non-fatal errors (E0…) never make parse() throw: they are collected so that the whole recipe gets reported in one pass, and you can display them next to the partially parsed result. Fatal errors (E9…) make the call throw. The catalog and the severity of a code are available programmatically through diagnosticCatalog and severityOfCode().

Errors thrown by other APIs ​

Every other error thrown by the library (shopping list, cart, product catalog, pantry, category configuration, quantity arithmetic) extends SingleDiagnosticError, which exposes the same structured diagnostic (code, message, fix, docs) as parse diagnostics:

typescript
import { SingleDiagnosticError } from "@tmlmt/cooklang-parser";

try {
  list.removeRecipe(42);
} catch (error) {
  if (error instanceof SingleDiagnosticError) {
    console.error(error.code, error.diagnostic.fix, error.diagnostic.docs);
  }
}

These are always thrown directly — missing prerequisites (no product catalog set, no pantry provided), bad arguments (an out-of-range index, an unknown recipe path, a value of the wrong type) and invalid TOML syntax all abort the call immediately rather than being collected into a diagnostics array.

Internal errors (I…) ​

Codes starting with I (e.g. COOKLANG_I0401) indicate a bug in the library itself, not a problem with your input. They behave like fatal errors (always thrown immediately) but should never actually be reachable through normal, documented usage of the public API. If you see one, please open an issue with a minimal reproduction.

Recovery ​

Known token-level errors are collected and the parser continues with later tokens and lines. Invalid tokens may be omitted from the partial recipe. A zero-denominator fraction is an exception: ParseStoppedError signals that no later tokens or lines were parsed. Unknown exceptions and internal invariant failures are not converted into diagnostics; they still throw because they indicate unsupported input or a library defect.

Migrating from earlier v3 alphas ​

Code that catches a specific typed error from parse() or a constructor of CategoryConfig, Pantry or ProductCatalog (e.g. DuplicateCategoryError) now receives a DiagnosticError; inspect error.diagnostics[].code instead.