@recipe-book/core 0.0.3 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,116 @@
+# @recipe-book/core
+
+## 0.1.1
+
+### Patch Changes
+
+- `convert`, `toSystem`, and `scaleQuantity` throw `invalid_argument` when the result overflows to `Infinity` or underflows to 0, and `convertTemperature` throws it when the result overflows to `Infinity` or `-Infinity`. ([#1014](https://github.com/SirajChokshi/recipe-book/pull/1014) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - They used to return the `Infinity` or 0, which no recipe can use.
+  - A result only gets there from an amount near the largest or smallest number a JavaScript number can hold, such as `convert({ amount: 1e308, unit: 'gallon' }, 'cup')`, or from a `scaleQuantity` factor that takes an amount there, such as `scaleQuantity({ amount: 2, unit: 'cup' }, 1e308)`.
+
+- `fromJsonLd` leaves a field that nests more than 32 levels deep out of `extra`, with a warning, so a page with a deeply nested `author` no longer gives a result that `JSON.stringify` can't serialize. ([#383](https://github.com/SirajChokshi/recipe-book/pull/383) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+- `fromJsonLd` no longer throws a `TypeError` for arrays that only JSON-LD built in code can have, never plain `JSON.parse` output. ([#948](https://github.com/SirajChokshi/recipe-book/pull/948) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - A `tool` list with a hole in it is read without the hole.
+  - An array with another prototype, such as `null`, or with a `constructor` that isn't one, such as a number, is read as a list.
+  - It also orders a list with a hole in it by `position` when every element it holds has one.
+
+- `findRecipeJsonLd` and `fromJsonLd` find the Recipes in an `ItemList`, such as a roundup page's list of recipes, when they find no other Recipe. ([#995](https://github.com/SirajChokshi/recipe-book/pull/995) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - They find each Recipe in a list's `itemListElement`, or in a `ListItem`'s `item` there, in document order.
+  - They read a list at the top level, in arrays and `@graph`, and as the `mainEntity` of a node there.
+  - They skip a `ListItem` with only a `url`. To read its recipe, fetch that page and find it there.
+  - JSON-LD in which they already find a Recipe gives the same result as before, so they ignore a "related recipes" list beside a page's own Recipe.
+  - Given a roundup's JSON-LD, `fromJsonLd` now reads its first Recipe, with an `ignored_value` warning for the others, instead of failing.
+  - `fromJsonLd`'s `invalid_type` message for input with no Recipe now says "an array, @graph, mainEntity, or ItemList that holds one".
+
+- `scaleQuantity` and `toSystem` now scale or convert the `amount` and `unit` they checked, so a quantity whose `amount`, range ends, or `unit` are getters can't pass the checks with one value and be used with another. ([#1013](https://github.com/SirajChokshi/recipe-book/pull/1013) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - Before, `scaleQuantity` could return `NaN`, a negative amount, or a range whose `min` is above its `max`, and `toSystem` could convert `NaN` or the wrong unit.
+  - `convert` already worked this way.
+
+- `fromJsonLd` no longer lets a step, section step, or tool it ignores come back from a polluted `Object.prototype`, and `parseRecipe` skips a hole in a list, including `equivalents`, instead of reading it from the prototype. ([#1012](https://github.com/SirajChokshi/recipe-book/pull/1012) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+- `fromJsonLd` reads a `ListItem` in `recipeIngredient` or `recipeInstructions` as the item it holds. ([#972](https://github.com/SirajChokshi/recipe-book/pull/972) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - A `ListItem` whose `item` is a list adds each entry, and one whose `item` is a named `HowToSection` adds that section.
+  - One with no `item`, or with blank text as its `item`, is read by its name.
+  - An item in nested `ListItem`s is left out more than 32 levels deep, like any other, with the same `invalid_type` warning at its path.
+  - An image more than 32 levels deep is left out whether it's a URL or an `ImageObject`, with an `invalid_type` warning that says it's nested more than 32 levels deep.
+
+- The `invalid_argument` message for a bad `locale` now says it must be a language tag that `Intl` accepts, such as `"en-US"`, rather than any BCP 47 language tag. ([#967](https://github.com/SirajChokshi/recipe-book/pull/967) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - `Intl` rejects some BCP 47 tags, such as `'i-klingon'` and `'x-private'`, and those still throw.
+
+- `fromJsonLd` reads each node once when several images share it, and gives its warnings once, so a page that shares a node of `data:` URLs among many images no longer takes seconds to read. ([#381](https://github.com/SirajChokshi/recipe-book/pull/381) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+- `fromJsonLd` leaves out an image URL longer than 4,096 UTF-16 code units, with an `invalid_url` warning. ([#385](https://github.com/SirajChokshi/recipe-book/pull/385) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - Each step that refers to an image holds its own copy of the URL, so this bounds how much a long image URL can grow the recipe.
+
+- `parseIngredientLine`, `parseRecipe`, and `fromJsonLd` read an amount and unit after a name and a colon, so `'salt: 1.25 g'`, which they used to read whole as the name, gets `name: 'salt'` and `quantity: { amount: 1.25, unit: 'g' }`. ([#1025](https://github.com/SirajChokshi/recipe-book/pull/1025) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - Only a note after a comma can follow the unit: `'nagaimo: 160 g, grated'` also gets `note: 'grated'`.
+  - After a leading `optional`, `'Optional salt: 1 g'` also gets `optional: true`.
+  - Text before the colon isn't read as a name if it has a digit or starts with the word `for`, `to`, `a`, `an`, `yield`, `yields`, or `total`, so `'For the sauce: 1 cup'` and `'Yield: 2 cups'` are unchanged.
+  - Text that is just `makes`, `serves`, `serving`, `servings`, `serving size`, `protein`, `carbs`, `carbohydrate`, `carbohydrates`, `fiber`, `fibre`, `sodium`, `cholesterol`, `saturated fat`, or `fat` isn't read as a name either. So `'Serves: 2 cups'` and `'Protein: 12 g'` are unchanged, but `'Protein powder: 30 g'` gets `name: 'Protein powder'`.
+  - A bare count after the colon, as in `'shiitake: 6'`, or a word that isn't a unit alias, as in `'salt: 1 zork'`, leaves the whole line as the name.
+
+- `parseIngredientLine`, `parseRecipe`, and `fromJsonLd` read a bare count followed by a word that starts with `or`, `to`, `and`, `plus`, or `half` and continues with an accented letter, so `'2 orégano sprigs'`, which they used to keep whole as the name with an `invalid_quantity` warning, gets `name: 'orégano sprig'` and `quantity: { amount: 2 }`. ([#1090](https://github.com/SirajChokshi/recipe-book/pull/1090) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - After a unit, a word that starts with `and` or `plus` and continues with an accented letter is read as part of the name, so `'1 kg Andújar olives'`, which they also kept whole with an `invalid_quantity` warning, gets `name: 'Andújar olives'` and `quantity: { amount: 1, unit: 'kg' }`.
+
+- `parseRecipe` reports an amount below 1e-300 or above 1e290 as `invalid_amount`, and `recipeSchema` and `createRecipeSchema` reject it. ([#1037](https://github.com/SirajChokshi/recipe-book/pull/1037) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - Before, they accepted any finite amount greater than 0, so a large or small enough one could resolve to `Infinity` or 0 when scaled and converted, and `formatIngredient`, `formatServings`, and `formatYield` threw on it. Within the limits, scaling by up to 1e6 either way and converting to any unit keeps an amount finite and greater than 0.
+  - The limits apply to ingredient quantities and equivalents, both ends of a range, servings, and yield, whether written as numbers, objects, or text.
+  - `fromJsonLd` leaves out a yield or ingredient line that holds such an amount, with a warning, as it does other values it can't read.
+  - `parseQuantity` and `parseIngredientLine` still accept such amounts.
+
+- `parseRecipe` no longer throws for arrays that only code can build, never `JSON.parse` output, and reads them as lists. ([#1069](https://github.com/SirajChokshi/recipe-book/pull/1069) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - An array with another prototype, such as `null`, is read as a list. So is one with its own `forEach` or `flatMap` that isn't a function, or its own `constructor` that isn't a constructor, such as a number.
+  - An `Array` subclass whose `Symbol.species` getter throws is read as a list too, instead of `parseRecipe` throwing that error.
+  - This holds for `ingredients`, a section's `items`, `steps`, `notes`, `equipment`, `times.custom`, and `equivalents`, and for `recipeSchema`.
+
+- `recipeSchema`, and `createRecipeSchema` without `parseIngredientLine`, now end the message for an ingredient written as text with `To read ingredient lines, use createRecipeSchema({ parseIngredientLine }).` ([#965](https://github.com/SirajChokshi/recipe-book/pull/965) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - The message used to say to pass `parseIngredientLine` to `parseRecipe`, which isn't how a schema reads lines.
+  - `parseRecipe`'s own message is unchanged.
+
+- `resolveRecipe` accepts `servings` of exactly a millionth or a million times the scaling base, such as 700000 for a base of 0.7 or 0.0000161 for a base of 16.1, which dividing by the base put just outside the window. ([#911](https://github.com/SirajChokshi/recipe-book/pull/911) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - It also stops accepting a number just past a bound that rounding used to let in.
+  - The `scale` for servings at a bound stays from 1e-6 to 1e6, as `ResolvedRecipe.scale` says.
+
+- `segmentStepText` no longer reads part of a word with an accented letter, such as the `f` in "200 fèves", as a temperature unit, a fan marker, or a word such as "is" or "by". ([#1093](https://github.com/SirajChokshi/recipe-book/pull/1093) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - `'Ajoutez 200 fèves et mélangez.'` and `'Cuire à 180° côté peau.'` are text. Before, they read as 200 °F and 180 °C.
+  - The same goes for a Cyrillic word that starts with `С`, as in `'Нагреть до 180 °Сначала'`.
+  - `'Asse os pastéis 180 °.'` is text, even with `assumeTemperatureUnit`, since the "is" that ends "pastéis" isn't the word "is". Before, it read as 180 °C.
+  - `'Ofen 200 °C Umluftöfen'` reads as 200 °C without `fan`. Before, `200 °C Umluft` was a fan setting.
+  - `'Stéfan 180 °C'` reads as 180 °C without `fan`. Before, `fan 180 °C` was a fan setting.
+  - `'Upečte chléby 220 °C'` reads as 220 °C. Before, the "by" that ends "chléby" made it a change in temperature, so it stayed text.
+  - A unit right before Chinese, Japanese, or Korean text is still read, as in `'45°C/113°F的温水'` and `'180°Cで20分焼く'`.
+
+- `parseIngredientLine` and `parseRecipe` read a unit before `of` with no amount as 1 when it has a period or two words, or follows a size word, as they already did for a unit written in letters only. ([#970](https://github.com/SirajChokshi/recipe-book/pull/970) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+  - `'tsp. of salt'` gets `quantity: { amount: 1, unit: 'tsp' }`, `'fl oz of water'` gets `quantity: { amount: 1, unit: 'fl-oz' }`, and `'big pinch of salt'` gets `quantity: { amount: 1, unit: 'pinch' }` and `note: 'big'`. Before, the whole line was the name.
+  - `'pinch of the salt'` gets `name: 'salt'`, as `'1 pinch of the salt'` does.
+  - A line with nothing after `of`, such as `'pinch of'`, gets the same warning as `'2 cups of'`.
+
+- `toJsonLd` now replaces a fragment in `url` even when the fragment holds a line break, so each step's `url` is everything before the first `#`, with the step's id, percent-encoded, as the fragment. ([#420](https://github.com/SirajChokshi/recipe-book/pull/420) by [@SirajChokshi](https://github.com/SirajChokshi))
+
+## 0.1.0
+
+- `parseRecipe` validates recipe input and returns a normalized `Recipe`, or every issue it found, each with a code, a path and, for a likely typo, a suggestion. `recipeSchema` is the same check as a Standard Schema.
+- `parseIngredientLine` reads a line such as `'1 ½ cups (190 g) flour, sifted'`, and `parseQuantity` reads quantity text.
+- A unit registry with exact sizes, `findUnit` for unit text, and `convert`, `toSystem` and `convertTemperature`.
+- `resolveRecipe` scales a recipe and expresses each ingredient in metric or US units.
+- `formatQuantity`, `formatIngredient` and the other `format*` functions write display text. With the default `en-US` locale, that text is the same on a server and in a browser, because English output doesn't use `Intl`. Other locales format numbers with the runtime's `Intl` data.
+- `segmentStepText` finds the temperatures in step text.
+- `@recipe-book/core/schema-org` reads recipes from schema.org Recipe JSON-LD and writes a recipe as JSON-LD.
+- ESM and CommonJS builds, each with type declarations and source maps. Requires Node 22 or later.
+- The ESM build keeps each source module in its own file. With Next.js (Turbopack or webpack), and with Vite when each page loads as its own chunk, such as a lazy route, only the pages that import a parser, or an export built on one such as `recipeSchema`, `createRecipeSchema`, or `fromJsonLd`, download it, so a page that renders `@recipe-book/react` parts or formats quantities stays free of the parser even when another page parses in the browser. `import('@recipe-book/core')` can still download a parser, on the page that calls it in Next.js and on every page that uses `@recipe-book/react` in Vite.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Siraj Chokshi
+
+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

@@ -1,11 +1,54 @@
 # @recipe-book/core
 
-A toolkit to build recipe interfaces in any framework. Supports unit conversions, ingredient highlighting, and more.
+Parse, validate, scale, convert, and format recipes. Core has no runtime dependencies and doesn't use React, so it works in scripts, on servers, in browsers, and in React Server Components. To render recipes with unstyled React components, install [`@recipe-book/react`](https://www.npmjs.com/package/@recipe-book/react) instead, and import core's functions and types from `@recipe-book/react/core`.
 
-## Packages
+## Install
 
-| Package                         | Description                                   |
-| :------------------------------ | :-------------------------------------------- |
-| [`core`](./packages/core)       | Core logic for parsing and formatting recipes |
-| [`react`](./packages/react)     | React components for displaying recipes       |
-| [`website`](./packages/website) | Demo website for Recipe components.           |
+```sh
+npm i @recipe-book/core
+```
+
+## Usage
+
+Parse recipe input with [`parseRecipe`](https://recipe-book.siraj.page/reference/core/parsing/#parserecipe). Then resolve the parsed recipe to a number of servings and a measurement system with [`resolveRecipe`](https://recipe-book.siraj.page/reference/core/resolving/#resolverecipe), and format each ingredient as a line with [`formatIngredient`](https://recipe-book.siraj.page/reference/core/formatting/#formatingredient).
+
+```ts
+import { formatIngredient, parseRecipe, resolveRecipe } from '@recipe-book/core'
+
+const result = parseRecipe({
+  name: 'Buttermilk pancakes',
+  servings: 4,
+  ingredients: [
+    { name: 'all-purpose flour', quantity: '1 ½ cups', equivalents: ['190 g'] },
+    { name: 'buttermilk', quantity: '1 ¼ cups' },
+    { name: 'egg', plural: 'eggs', quantity: 2 },
+  ],
+  steps: [
+    'Whisk the flour, buttermilk, and eggs.',
+    'Cook ¼-cup portions on a buttered griddle, 2–3 minutes per side.',
+  ],
+})
+if (!result.success) throw result.error
+
+const recipe = resolveRecipe(result.data, { servings: 8, system: 'metric' })
+
+for (const section of recipe.ingredients) {
+  for (const item of section.items) {
+    console.log(formatIngredient(item).text)
+  }
+}
+```
+
+It prints:
+
+```text
+380 g all-purpose flour
+591 mL buttermilk
+4 eggs
+```
+
+The recipe has 4 servings, so 8 servings doubles each quantity. In metric, the flour uses its 190 g equivalent. The buttermilk has no metric equivalent, so `resolveRecipe` converts it from cups, and `formatIngredient` rounds it for display.
+
+## Documentation
+
+[recipe-book.siraj.page](https://recipe-book.siraj.page)