cooklang-parse 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Brian Sunter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# cooklang-parse
+
+> A simple, type-safe [Cooklang](https://cooklang.org) parser built with [Ohm.js](https://ohmjs.org)
+
+[![npm version](https://badge.fury.io/js/cooklang-parse.svg)](https://www.npmjs.com/package/cooklang-parse)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- Full Cooklang spec support including ingredients, cookware, timers, metadata, sections, notes, and YAML frontmatter
+- Written in TypeScript with exported type definitions
+- Single function API — `parseCooklang(source)` returns a structured recipe
+- 190 tests with canonical parity against the [Rust reference implementation](https://github.com/cooklang/cooklang-rs)
+- Source position tracking and parse error reporting
+
+## Installation
+
+```bash
+npm install cooklang-parse
+# or
+bun add cooklang-parse
+```
+
+## Quick Start
+
+```typescript
+import { parseCooklang } from "cooklang-parse"
+
+const recipe = parseCooklang(`
+>> servings: 4
+
+Preheat #oven to 180C.
+Mix @flour{250%g} and @eggs{3} in a #bowl{}.
+Bake for ~{20%minutes}.
+`)
+
+recipe.metadata    // { servings: 4 }
+recipe.ingredients // [{ type: "ingredient", name: "flour", quantity: 250, units: "g", fixed: false }, ...]
+recipe.cookware    // [{ type: "cookware", name: "oven", quantity: 1, units: "" }, ...]
+recipe.timers      // [{ type: "timer", name: "", quantity: 20, units: "minutes" }]
+recipe.steps       // [[{ type: "text", value: "Preheat " }, { type: "cookware", ... }, ...], ...]
+recipe.errors      // [] (parse errors and warnings)
+```
+
+## Cooklang Syntax
+
+| Syntax | Description | Example |
+|--------|-------------|---------|
+| `@name{qty%unit}` | Ingredient with quantity and unit | `@flour{250%g}` |
+| `@name{qty}` | Ingredient with quantity only | `@eggs{3}` |
+| `@name` | Ingredient (implicit "some") | `@salt` |
+| `@name{}` | Multi-word ingredient | `@olive oil{}` |
+| `#name{}` | Cookware | `#cast iron skillet{}` |
+| `~name{qty%unit}` | Named timer | `~resting{30%minutes}` |
+| `~{qty%unit}` | Anonymous timer | `~{20%minutes}` |
+| `-- comment` | Inline comment (space required after `--`) | `-- note to self` |
+| `[- text -]` | Block comment | `[- Chef's tip -]` |
+| `> text` | Note | `> Serve immediately` |
+| `== Title ==` | Section header | `== For the sauce ==` |
+| `>> key: value` | Metadata directive | `>> servings: 4` |
+| `---` | YAML frontmatter block | See below |
+| `=@name{qty}` | Fixed quantity (won't scale) | `=@salt{1%tsp}` |
+| `@name{=qty}` | Fixed quantity (alternate) | `@salt{=1%tsp}` |
+| `@name{}(prep)` | Ingredient with preparation | `@flour{100%g}(sifted)` |
+| `@name\|alias{}` | Pipe alias syntax | `@ground beef\|beef{}` |
+
+## API
+
+### `parseCooklang(source: string): CooklangRecipe`
+
+Parses a Cooklang source string into a structured recipe object.
+
+```typescript
+interface CooklangRecipe {
+  metadata: Record<string, unknown>
+  steps: RecipeStepItem[][]
+  ingredients: RecipeIngredient[]
+  cookware: RecipeCookware[]
+  timers: RecipeTimer[]
+  sections: string[]
+  notes: string[]
+  errors: ParseError[]
+}
+```
+
+**`steps`** is an array of steps, where each step is an array of items:
+
+```typescript
+type RecipeStepItem =
+  | { type: "text"; value: string }
+  | RecipeIngredient
+  | RecipeCookware
+  | RecipeTimer
+```
+
+**`ingredients`**, **`cookware`**, and **`timers`** are deduplicated across all steps.
+
+### Types
+
+```typescript
+interface RecipeIngredient {
+  type: "ingredient"
+  name: string
+  quantity: number | string
+  units: string
+  fixed: boolean
+  preparation?: string
+}
+
+interface RecipeCookware {
+  type: "cookware"
+  name: string
+  quantity: number | string
+  units: string
+}
+
+interface RecipeTimer {
+  type: "timer"
+  name: string
+  quantity: number | string
+  units: string
+}
+
+interface ParseError {
+  message: string
+  shortMessage?: string
+  position: { line: number; column: number; offset: number }
+  severity: "error" | "warning"
+}
+```
+
+### Grammar Access
+
+The underlying Ohm.js grammar is exported for advanced use cases:
+
+```typescript
+import { grammar } from "cooklang-parse"
+
+const match = grammar.match(source)
+```
+
+## Example: Recipe with Frontmatter and Sections
+
+```typescript
+const recipe = parseCooklang(`
+---
+title: Sourdough Bread
+source: My grandmother
+---
+
+>> servings: 2
+
+== Starter ==
+Mix @starter{100%g} with @water{100%g}
+Let ferment for ~{8%hours}
+
+== Dough ==
+Combine @flour{500%g} and @water{325%g}
+Add @starter{200%g} and @salt{10%g}
+Knead in #mixing bowl{} for ~kneading{10%minutes}
+`)
+
+recipe.metadata
+// { title: "Sourdough Bread", source: "My grandmother", servings: 2 }
+
+recipe.sections
+// ["Starter", "Dough"]
+
+recipe.ingredients.map(i => `${i.quantity} ${i.units} ${i.name}`.trim())
+// ["100 g starter", "100 g water", "500 g flour", ...]
+```
+
+## Development
+
+```bash
+bun install          # Install dependencies
+bun test             # Run all 190 tests
+bun run build        # Bundle + emit declarations
+bun run typecheck    # Type-check without emitting
+bun run lint         # Lint with Biome
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { grammar, parseCooklang } from "./semantics";
+export type * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AACpD,mBAAmB,SAAS,CAAA"}