🍳 Foodlang

For Developers

Foodlang is a small TypeScript monorepo. Everything that runs in the CLI also runs in the browser, because the core and compiler are dependency-light and free of Node-only APIs (the one filesystem helper is isolated and tree-shaken out of browser builds).

Packages

Package Responsibility
@foodlang/core types, parser, normalizer, validator
@foodlang/compiler compiler targets + registry
@foodlang/cli the foodlang command-line tool

The pipeline

.food.yaml
  -> parse      (YAML -> raw object)
  -> normalize  (ORF single-key maps -> typed FoodRecipe)
  -> validate   (errors, warnings, level classification)
  -> compile    (FoodRecipe -> target output)

Parsing

import { parseFoodRecipe, parseFoodFile } from "@foodlang/core";

const a = parseFoodRecipe(yamlString); // browser-safe
const b = await parseFoodFile("recipe.food.yaml"); // Node-only

Both return a normalized FoodRecipe. Unknown fields are preserved on recipe.raw, so nothing is ever lost.

Writing a compiler target

A target implements the CompilerTarget interface:

import type { CompilerTarget, FoodRecipe } from "@foodlang/core";

export const myTarget: CompilerTarget = {
  name: "my-target",
  description: "What this produces.",
  fidelity: "mapping", // "executable" | "mapping" | "illustrative"
  compile(recipe: FoodRecipe): string | object {
    return { hello: recipe.recipe_name };
  },
};

Register it in packages/compiler/src/index.ts and it's instantly available to the CLI (--target my-target) and the browser playground.

Fidelity is mandatory

Every target declares whether its output is executable, a mapping, or illustrative. This is the contract that keeps Foodlang honest — see Philosophy.

Determinism

Every target produces deterministic output: the same recipe always compiles to byte-identical results. That makes outputs diffable and testable. The test suite asserts this for the text targets.

Testing

pnpm test        # run the Vitest suite
pnpm typecheck   # tsc --noEmit across all packages
pnpm build       # compile all packages

JSON Schemas

The format is described by JSON Schemas in schemas/: foodlang-core, foodlang-process, foodlang-appliance, foodlang-robot, and foodlang-industrial.