@recipe-book/core 0.0.3 → 0.1.1

package/dist/types-BknM8KOd.d.cts

@@ -0,0 +1,628 @@
+/** Thrown, or returned by the `parse*` functions, when data fails validation. */
+declare class RecipeValidationError extends RecipeBookError {
+    readonly code: ValidationErrorCode;
+    /**
+     * Every problem found, errors and warnings, in a stable order: fields in
+     * model order (recipe fields, ingredients, steps, notes, equipment, then
+     * nutrition), list items in input order, and unknown fields last within
+     * their object.
+     */
+    readonly issues: readonly RecipeIssue[];
+    /**
+     * @param subject - What was validated, shown as given at the start of the
+     *   message, e.g. `'"Buttermilk pancakes"'`. Recipe Book's own errors quote
+     *   the recipe's name or the input text like a JSON string, cut with "…"
+     *   when longer than 60 UTF-16 code units.
+     */
+    constructor(code: ValidationErrorCode, issues: readonly RecipeIssue[], subject?: string);
+}
+
+/**
+ * Codes for errors thrown by Recipe Book. May grow in minor releases.
+ *
+ * @see https://recipe-book.siraj.page/errors
+ */
+type RecipeBookErrorCode = 'invalid_recipe' | 'invalid_quantity' | 'invalid_ingredient' | 'invalid_argument' | 'incompatible_units' | 'unknown_unit' | 'missing_parent';
+/** Codes for problems found in recipe data. May grow in minor releases. */
+type RecipeIssueCode = 'invalid_type' | 'missing_field' | 'unknown_unit' | 'invalid_quantity' | 'invalid_amount' | 'invalid_range' | 'invalid_duration' | 'invalid_url' | 'unknown_field' | 'duplicate_id' | 'empty_list' | 'ignored_value';
+/** A problem found in recipe data. Data problems are returned as values, never thrown one by one. */
+type RecipeIssue = {
+    code: RecipeIssueCode;
+    severity: 'error' | 'warning';
+    /** Location in the input, e.g. `['ingredients', 0, 'quantity']`. */
+    path: readonly (string | number)[];
+    /** A complete sentence that names the fix. */
+    message: string;
+    /** The value the input most likely meant, for "did you mean" hints. */
+    suggestion?: string | undefined;
+};
+/**
+ * Thrown for programmer errors, such as converting cups to grams or passing an
+ * unknown unit id. Each error has a stable `code` and a `docsUrl` that explains the fix.
+ *
+ * Use {@link isRecipeBookError} rather than `instanceof` to detect it, so the
+ * check also works when two copies of the package are installed.
+ */
+declare class RecipeBookError extends Error {
+    readonly name: string;
+    readonly code: RecipeBookErrorCode;
+    readonly docsUrl: string;
+    constructor(code: RecipeBookErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Codes for `RecipeValidationError`. May grow in minor releases. */
+type ValidationErrorCode = 'invalid_recipe' | 'invalid_quantity' | 'invalid_ingredient';
+/**
+ * What `parseRecipe`, `parseQuantity`, and `parseIngredientLine` return. They
+ * never throw for bad data: check `success`, or `throw result.error` to fail
+ * loudly.
+ *
+ * @example
+ * const result = parseRecipe(json)
+ * if (!result.success) throw result.error // message lists the first 10 issues with their paths
+ * result.data // Recipe
+ */
+type ParseResult<T> = {
+    success: true;
+    data: T;
+    warnings: RecipeIssue[];
+} | {
+    success: false;
+    error: RecipeValidationError;
+};
+/** True for errors thrown by any copy of Recipe Book. Checks `name` and `code`, not `instanceof`. */
+declare function isRecipeBookError(error: unknown): error is RecipeBookError;
+
+/** A measurement system. `'us'` is US customary. */
+type System = 'metric' | 'us';
+/** What a unit measures. Count units, such as `clove` or `pinch`, have no fixed size. */
+type Dimension = 'mass' | 'volume' | 'count';
+type Label = {
+    one: string;
+    other: string;
+};
+declare function definitions(): {
+    readonly mg: {
+        readonly dimension: "mass";
+        readonly systems: readonly ["metric"];
+        readonly toBase: 0.001;
+        readonly aliases: readonly ["milligram", "milligrams", "milligramme", "milligrammes"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly g: {
+        readonly dimension: "mass";
+        readonly systems: readonly ["metric"];
+        readonly toBase: 1;
+        readonly aliases: readonly ["gram", "grams", "gramme", "grammes"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly kg: {
+        readonly dimension: "mass";
+        readonly systems: readonly ["metric"];
+        readonly toBase: 1000;
+        readonly aliases: readonly ["kgs", "kilo", "kilos", "kilogram", "kilograms", "kilogramme", "kilogrammes"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly oz: {
+        readonly dimension: "mass";
+        readonly systems: readonly ["us"];
+        readonly toBase: 28.349523125;
+        readonly aliases: readonly ["ounce", "ounces"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly lb: {
+        readonly dimension: "mass";
+        readonly systems: readonly ["us"];
+        readonly toBase: number;
+        readonly aliases: readonly ["lbs", "pound", "pounds"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly ml: {
+        readonly dimension: "volume";
+        readonly systems: readonly ["metric"];
+        readonly toBase: 1;
+        readonly aliases: readonly ["mL", "milliliter", "milliliters", "millilitre", "millilitres"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly cl: {
+        readonly dimension: "volume";
+        readonly systems: readonly ["metric"];
+        readonly toBase: 10;
+        readonly aliases: readonly ["cL", "centiliter", "centiliters", "centilitre", "centilitres"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly dl: {
+        readonly dimension: "volume";
+        readonly systems: readonly ["metric"];
+        readonly toBase: 100;
+        readonly aliases: readonly ["dL", "deciliter", "deciliters", "decilitre", "decilitres"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly l: {
+        readonly dimension: "volume";
+        readonly systems: readonly ["metric"];
+        readonly toBase: 1000;
+        readonly aliases: readonly ["L", "liter", "liters", "litre", "litres"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly tsp: {
+        readonly dimension: "volume";
+        readonly systems: readonly ["metric", "us"];
+        readonly toBase: 4.92892159375;
+        readonly aliases: readonly ["t", "tsps", "teaspoon", "teaspoons"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly tbsp: {
+        readonly dimension: "volume";
+        readonly systems: readonly ["metric", "us"];
+        readonly toBase: number;
+        readonly aliases: readonly ["T", "tbs", "tbsps", "tablespoon", "tablespoons"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly 'fl-oz': {
+        readonly dimension: "volume";
+        readonly systems: readonly ["us"];
+        readonly toBase: number;
+        readonly aliases: readonly ["fl oz", "fluid ounce", "fluid ounces"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly cup: {
+        readonly dimension: "volume";
+        readonly systems: readonly ["us"];
+        readonly toBase: number;
+        readonly aliases: readonly ["cups", "c"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly pint: {
+        readonly dimension: "volume";
+        readonly systems: readonly ["us"];
+        readonly toBase: number;
+        readonly aliases: readonly ["pt", "pts", "pints"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly quart: {
+        readonly dimension: "volume";
+        readonly systems: readonly ["us"];
+        readonly toBase: number;
+        readonly aliases: readonly ["qt", "qts", "quarts"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly gallon: {
+        readonly dimension: "volume";
+        readonly systems: readonly ["us"];
+        readonly toBase: number;
+        readonly aliases: readonly ["gal", "gals", "gallons"];
+        readonly labels: {
+            readonly short: Label;
+            readonly long: Label;
+        };
+    };
+    readonly pinch: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["pinches"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+    readonly dash: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["dashes"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+    readonly clove: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["cloves"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+    readonly slice: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["slices"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+    readonly piece: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["pieces", "pc", "pcs"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+    readonly can: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["cans"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+    readonly package: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["packages", "pkg", "pkgs"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+    readonly stick: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["sticks"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+    readonly sprig: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["sprigs"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+    readonly bunch: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["bunches"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+    readonly head: {
+        dimension: "count";
+        systems: readonly ["metric", "us"];
+        aliases: readonly ["heads"];
+        labels: {
+            short: Label;
+            long: Label;
+        };
+    };
+};
+type Definitions = ReturnType<typeof definitions>;
+/**
+ * A unit id, such as `'g'`, `'ml'`, `'cup'`, or `'fl-oz'`. Quantities always
+ * store ids; use {@link findUnit} to turn author text into one. May grow in minor releases.
+ */
+type UnitId = keyof Definitions;
+type AliasOf<Id extends UnitId> = Id | Definitions[Id]['aliases'][number];
+/**
+ * A spelling of a unit in the registry, such as `'cups'`, `'T'`, or `'litre'`.
+ * {@link findUnit} also accepts it in any case (except `'T'`, `'t'`, and
+ * `'c'`) and with a trailing period.
+ */
+type UnitAlias = {
+    [Id in UnitId]: AliasOf<Id>;
+}[UnitId];
+/** The id of the unit an alias names: `UnitIdOf<'tablespoons'>` is `'tbsp'`. */
+type UnitIdOf<Alias extends UnitAlias> = {
+    [Id in UnitId]: Alias extends AliasOf<Id> ? Id : never;
+}[UnitId];
+/** One entry in the {@link units} registry. */
+type UnitDefinition = {
+    readonly id: UnitId;
+    readonly dimension: Dimension;
+    /** Systems where the unit is native. tsp, tbsp, and count units are native to both. */
+    readonly systems: readonly System[];
+    /** Exact size in grams (mass) or millilitres (volume). Absent for count units. */
+    readonly toBase?: number;
+    /**
+     * Every accepted spelling, starting with the id. Matched case-insensitively,
+     * except `'T'` (tbsp), `'t'` (tsp), and `'c'` (cup).
+     */
+    readonly aliases: readonly UnitAlias[];
+    /** English labels for one and for many, in short (`'tbsp'`) and long (`'tablespoon'`) form. */
+    readonly labels: {
+        readonly short: Readonly<Label>;
+        readonly long: Readonly<Label>;
+    };
+};
+type Registry = {
+    readonly [Id in UnitId]: UnitDefinition & {
+        readonly id: Id;
+    };
+};
+/**
+ * The read-only unit registry, keyed by id. Volume and mass units carry exact
+ * factors to millilitres and grams.
+ *
+ * @example
+ * units.cup.toBase // 236.5882365
+ * Object.values(units).filter((unit) => unit.dimension === 'mass')
+ */
+declare const units: Registry;
+
+/**
+ * An inclusive range, such as 2–3 tbsp. Both ends are finite and greater
+ * than 0, and `min < max`, though `convert`, `toSystem`, and
+ * `scaleQuantity` can return equal ends for a range whose ends differ only
+ * in their last digit.
+ */
+type Range = {
+    min: number;
+    max: number;
+};
+/** A finite number greater than 0, or a {@link Range}. */
+type Amount = number | Range;
+/**
+ * An amount with an optional unit id. No unit means a bare count, as in "2 eggs".
+ *
+ * @example
+ * const flour: Quantity = { amount: 1.5, unit: 'cup' }
+ * const oil: Quantity = { amount: { min: 2, max: 3 }, unit: 'tbsp' }
+ * const eggs: Quantity = { amount: 2 }
+ */
+type Quantity = {
+    amount: Amount;
+    unit?: UnitId | undefined;
+    /** Always left out or `undefined`; the quantity functions throw otherwise. A quantity range is `amount: { min, max }`. A `Servings` or `Yield` writes `{ amount, max }`, so it isn't a quantity. */
+    max?: undefined;
+};
+
+/**
+ * A normalized ingredient. Absent `quantity` means unquantified, as in "salt, to taste".
+ *
+ * @example
+ * const flour: Ingredient = {
+ *   id: 'all-purpose-flour',
+ *   name: 'all-purpose flour',
+ *   quantity: { amount: 1.5, unit: 'cup' },
+ *   equivalents: [{ amount: 190, unit: 'g' }],
+ *   optional: false,
+ * }
+ */
+type Ingredient = {
+    /** Authored, or derived from the name and de-duplicated: `'egg'`, `'egg-2'`. */
+    id: string;
+    /** Singular, or as written. */
+    name: string;
+    /**
+     * Used after a bare count above 1, a decimal, or a range: "2 eggs", "1–2
+     * eggs". 1 and fractions below 1 keep `name`: "1 egg", "½ egg".
+     */
+    plural?: string | undefined;
+    quantity?: Quantity | undefined;
+    /** Author-verified alternatives to `quantity`, in preference order. */
+    equivalents: Quantity[];
+    /** "sifted", "to taste", "melted". */
+    note?: string | undefined;
+    /** A product page or another recipe. An http or https URL, or a relative one, including protocol-relative `//host/path`. */
+    url?: string | undefined;
+    optional: boolean;
+};
+/** A group of ingredients, such as "For the frosting". Untitled sections have no `title`. */
+type IngredientSection = {
+    id: string;
+    title?: string | undefined;
+    items: Ingredient[];
+};
+/** One instruction. Display numbers run across sections and aren't stored. */
+type Step = {
+    /** Authored, or derived from `name`, else from the step number, and de-duplicated: `'step-1'`, `'mix-2'`. */
+    id: string;
+    text: string;
+    /** A short label, such as "Make the dough". */
+    name?: string | undefined;
+    /** An http or https URL, or a relative one, including protocol-relative `//host/path`. */
+    image?: string | undefined;
+};
+/** A group of steps, such as "Make the frosting". Untitled sections have no `title`. */
+type StepSection = {
+    id: string;
+    title?: string | undefined;
+    items: Step[];
+};
+/**
+ * How many people the recipe serves. `max` is the upper end of a range, as in
+ * "serves 4–6"; scaling uses `amount`. Print it with `formatServings`.
+ *
+ * @example
+ * const serves4: Servings = { amount: 4 }
+ * const serves4to6: Servings = { amount: 4, max: 6 }
+ */
+type Servings = {
+    amount: number;
+    /** Greater than `amount` when present. */
+    max?: number | undefined;
+};
+/**
+ * What a batch makes, such as 24 cookies or 2 loaves. `max` is the upper end
+ * of a range; scaling uses `amount`. Only `amount` and `max` scale, so a
+ * number inside `unit`, as in `'24 cookies or 12 bars'`, stays as written.
+ * Print it with `formatYield`.
+ *
+ * @example
+ * const cookies: Yield = { amount: 24, unit: 'cookie', plural: 'cookies' }
+ * const loaves: Yield = { amount: 2, max: 3, unit: 'loaf', plural: 'loaves' }
+ */
+type Yield = {
+    amount: number;
+    /** Greater than `amount` when present. */
+    max?: number | undefined;
+    /** Singular, or as written. */
+    unit: string;
+    /**
+     * Used for amounts above 1, decimals, and ranges. 1 and fractions below 1,
+     * such as ½, use `unit`.
+     */
+    plural?: string | undefined;
+};
+/** Durations in minutes. `total` is kept as authored, never computed. */
+type Times = {
+    prep?: number | undefined;
+    cook?: number | undefined;
+    total?: number | undefined;
+    /** Other named times, such as chilling or rising. */
+    custom: CustomTime[];
+};
+/**
+ * A named time, such as chilling or rising, in minutes.
+ *
+ * @example
+ * const chill: CustomTime = { id: 'chill', label: 'Chill', minutes: 120 }
+ */
+type CustomTime = {
+    /** Authored, or derived from the label and de-duplicated: `'chill'`, `'chill-2'`. */
+    id: string;
+    label: string;
+    minutes: number;
+};
+/**
+ * A recipe note, such as a tip or a substitution.
+ *
+ * @example
+ * const note: Note = { id: 'make-ahead', title: 'Make ahead', text: 'The dough keeps for 3 days.' }
+ */
+type Note = {
+    /** Authored, or derived from the title, falling back to its position, and de-duplicated: `'note-1'`, `'make-ahead-2'`. */
+    id: string;
+    title?: string | undefined;
+    /** Plain text. Renderers show it as text, never as HTML. */
+    text: string;
+};
+/**
+ * A tool the recipe needs. Equipment never scales with servings.
+ *
+ * @example
+ * const pans: Equipment = {
+ *   id: 'baking-sheet',
+ *   name: 'baking sheet',
+ *   plural: 'baking sheets',
+ *   quantity: 2,
+ * }
+ */
+type Equipment = {
+    /** Authored, or derived from the name and de-duplicated: `'whisk'`, `'whisk-2'`. */
+    id: string;
+    name: string;
+    /** Used when `quantity` is above 1: "2 baking sheets". */
+    plural?: string | undefined;
+    /** A whole number, such as `2` for two baking sheets. */
+    quantity?: number | undefined;
+    /** A product page. An http or https URL, or a relative one, including protocol-relative `//host/path`. */
+    url?: string | undefined;
+    note?: string | undefined;
+};
+/**
+ * Nutrition for one of the recipe's `servings`. It never scales.
+ *
+ * @example
+ * const nutrition: Nutrition = { servingSize: '1 slice', calories: 250, fat: 12, sodium: 300 }
+ */
+type Nutrition = {
+    /** "1 slice", "100 g". */
+    servingSize?: string | undefined;
+    /** kcal. */
+    calories?: number | undefined;
+    /** g. */
+    fat?: number | undefined;
+    /** g. */
+    saturatedFat?: number | undefined;
+    /** g. */
+    transFat?: number | undefined;
+    /** g. */
+    unsaturatedFat?: number | undefined;
+    /** g. */
+    carbohydrates?: number | undefined;
+    /** g. */
+    sugar?: number | undefined;
+    /** g. */
+    fiber?: number | undefined;
+    /** g. */
+    protein?: number | undefined;
+    /** mg. */
+    sodium?: number | undefined;
+    /** mg. */
+    cholesterol?: number | undefined;
+};
+/**
+ * A normalized recipe, as returned by `parseRecipe`. Plain JSON data: it can be
+ * cached, stored, or passed from a Server Component to a Client Component.
+ * A `Recipe` whose quantity, servings, and yield amounts are from 1e-300 to
+ * 1e290, as in every recipe that `parseRecipe` or `fromJsonLd` returns, is also
+ * a valid `RecipeInput`, and parsing it returns an equal recipe.
+ */
+type Recipe = {
+    id: string;
+    name: string;
+    description?: string | undefined;
+    /** An http or https URL, or a relative one, including protocol-relative `//host/path`. */
+    image?: string | undefined;
+    servings?: Servings | undefined;
+    yield?: Yield | undefined;
+    /** The system the recipe was written in, authored or inferred. Absent means system-neutral. */
+    system?: System | undefined;
+    times: Times;
+    ingredients: IngredientSection[];
+    steps: StepSection[];
+    notes: Note[];
+    equipment: Equipment[];
+    nutrition?: Nutrition | undefined;
+};
+
+export { RecipeBookError as i, RecipeValidationError as m, isRecipeBookError as o, units as u };
+export type { Amount as A, CustomTime as C, Dimension as D, Equipment as E, Ingredient as I, Note as N, ParseResult as P, Quantity as Q, Recipe as R, System as S, Times as T, UnitAlias as U, ValidationErrorCode as V, Yield as Y, Servings as a, Step as b, Range as c, UnitId as d, UnitIdOf as e, UnitDefinition as f, IngredientSection as g, Nutrition as h, RecipeBookErrorCode as j, RecipeIssue as k, RecipeIssueCode as l, StepSection as n };