@tmlmt/cooklang-parser 3.0.0-alpha.15 → 3.0.0-alpha.17

package/dist/index.d.cts

@@ -114,6 +114,11 @@ declare class Recipe {
      * Used for giving ID numbers to items during parsing.
      */
     private static itemCounts;
+    /**
+     * External storage for subgroup index tracking during parsing.
+     * Maps groupKey → subgroupKey → index within the subgroups array.
+     */
+    private static subgroupIndices;
     /**
      * Gets the current item count for this recipe.
      */
@@ -268,6 +273,18 @@ interface MetadataSource {
     /** The author at the source. */
     author?: string;
 }
+/**
+ * Represents scaling variable information for a recipe.
+ * @category Types
+ */
+interface MetadataScalingVar extends QuantityWithPlainUnit {
+    /** The text before the scaling variable. */
+    textBefore?: string;
+    /** The text after the scaling variable. */
+    textAfter?: string;
+    /** The text precising a numerical scaling variable. */
+    text?: string;
+}
 /**
  * Represents time information for a recipe.
  * @category Types
@@ -291,7 +308,7 @@ interface MetadataObject {
  * Represents any value that can appear in recipe metadata.
  * @category Types
  */
-type MetadataValue = string | number | (string | number)[] | MetadataObject | MetadataSource | MetadataTime | undefined;
+type MetadataValue = string | number | (string | number)[] | MetadataObject | MetadataSource | MetadataTime | MetadataScalingVar | undefined;
 /**
  * Represents the metadata of a recipe.
  * @category Types
@@ -309,9 +326,10 @@ interface Metadata {
     /** The author of the recipe (separate from source author). */
     author?: string;
     /** The number of servings the recipe makes.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * Can be given either as:
+     * - a number
+     * - a string which starts with a number (which will be used for scaling) followed by a comma and then whatever you want
+     * - or an arbitrary scalable number, optionally preceded and/or followed by text.
      *
      * Interchangeable with `yield` or `serves`. If multiple ones are defined,
      * the prevailance order for the number which will used for scaling
@@ -326,30 +344,37 @@ interface Metadata {
      * ```yaml
      * servings: 2, a few
      * ```
+     *
+     * * @example
+     * ```yaml
+     * servings: {{1.5%kg}} of bread
+     * ```
      */
-    servings?: number | string;
+    servings?: MetadataScalingVar;
     /** The yield of the recipe.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * Can be given either as:
+     * - a number
+     * - a string which starts with a number (which will be used for scaling) followed by a comma and then whatever you want
+     * - or an arbitrary scalable number, optionally preceded and/or followed by text.
      *
      * Interchangeable with `servings` or `serves`. If multiple ones are defined,
      * the prevailance order for the number which will used for scaling
      * is `servings` \> `yield` \> `serves`. See {@link Metadata.servings | servings}
      * for examples.
      */
-    yield?: number | string;
+    yield?: MetadataScalingVar;
     /** The number of people the recipe serves.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * Can be given either as:
+     * - a number
+     * - a string which starts with a number (which will be used for scaling) followed by a comma and then whatever you want
+     * - or an arbitrary scalable number, optionally preceded and/or followed by text.
      *
      * Interchangeable with `servings` or `yield`. If multiple ones are defined,
      * the prevailance order for the number which will used for scaling
      * is `servings` \> `yield` \> `serves`. See {@link Metadata.servings | servings}
      * for examples.
      */
-    serves?: number | string;
+    serves?: MetadataScalingVar;
     /** The course of the recipe. */
     course?: string;
     /** The category of the recipe. */
@@ -593,6 +618,12 @@ interface IngredientItem {
      * `@|group|...` syntax), they represent a single logical choice.
      */
     group?: string;
+    /**
+     * An optional subgroup identifier for binding multiple ingredients together
+     * within a group. Ingredients sharing the same `group` and `subgroup` are
+     * selected together as a unit (e.g., from `@|group/1|...` syntax).
+     */
+    subgroup?: string;
 }
 /**
  * Represents the choices one can make in a recipe
@@ -606,9 +637,13 @@ interface RecipeAlternatives {
     ingredientItems: Map<string, IngredientAlternative[]>;
     /** Map of choices that can be made for Grouped Ingredient StepItem's
      * - Keys are the Group IDs (e.g. "eggs" for `@|eggs|...`)
-     * - Values are arrays of IngredientAlternative objects representing the choices available for that group
+     * - Values are arrays of subgroups, where each subgroup is an array of
+     *   bound IngredientAlternative objects that are selected together.
+     *   Items sharing the same subgroup key (e.g., `@|group/1|...`) are
+     *   in the same inner array. Items without a subgroup key each form
+     *   their own single-element subgroup.
      */
-    ingredientGroups: Map<string, IngredientAlternative[]>;
+    ingredientGroups: Map<string, IngredientAlternative[][]>;
 }
 /**
  * Represents the choices to apply when computing ingredient quantities.
@@ -1918,4 +1953,4 @@ declare class BadIndentationError extends Error {
     constructor();
 }
 
-export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, BadIndentationError, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FlatAndGroup, type FlatGroup, type FlatOrGroup, type FractionValue, type GetIngredientQuantitiesOptions, type Group, type Ingredient, type IngredientAlternative, type IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, NoTabAsIndentError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSimpleGroup, renderFractionAsVulgar };
+export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, BadIndentationError, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FlatAndGroup, type FlatGroup, type FlatOrGroup, type FractionValue, type GetIngredientQuantitiesOptions, type Group, type Ingredient, type IngredientAlternative, type IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataScalingVar, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, NoTabAsIndentError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSimpleGroup, renderFractionAsVulgar };

package/dist/index.d.ts

@@ -114,6 +114,11 @@ declare class Recipe {
      * Used for giving ID numbers to items during parsing.
      */
     private static itemCounts;
+    /**
+     * External storage for subgroup index tracking during parsing.
+     * Maps groupKey → subgroupKey → index within the subgroups array.
+     */
+    private static subgroupIndices;
     /**
      * Gets the current item count for this recipe.
      */
@@ -268,6 +273,18 @@ interface MetadataSource {
     /** The author at the source. */
     author?: string;
 }
+/**
+ * Represents scaling variable information for a recipe.
+ * @category Types
+ */
+interface MetadataScalingVar extends QuantityWithPlainUnit {
+    /** The text before the scaling variable. */
+    textBefore?: string;
+    /** The text after the scaling variable. */
+    textAfter?: string;
+    /** The text precising a numerical scaling variable. */
+    text?: string;
+}
 /**
  * Represents time information for a recipe.
  * @category Types
@@ -291,7 +308,7 @@ interface MetadataObject {
  * Represents any value that can appear in recipe metadata.
  * @category Types
  */
-type MetadataValue = string | number | (string | number)[] | MetadataObject | MetadataSource | MetadataTime | undefined;
+type MetadataValue = string | number | (string | number)[] | MetadataObject | MetadataSource | MetadataTime | MetadataScalingVar | undefined;
 /**
  * Represents the metadata of a recipe.
  * @category Types
@@ -309,9 +326,10 @@ interface Metadata {
     /** The author of the recipe (separate from source author). */
     author?: string;
     /** The number of servings the recipe makes.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * Can be given either as:
+     * - a number
+     * - a string which starts with a number (which will be used for scaling) followed by a comma and then whatever you want
+     * - or an arbitrary scalable number, optionally preceded and/or followed by text.
      *
      * Interchangeable with `yield` or `serves`. If multiple ones are defined,
      * the prevailance order for the number which will used for scaling
@@ -326,30 +344,37 @@ interface Metadata {
      * ```yaml
      * servings: 2, a few
      * ```
+     *
+     * * @example
+     * ```yaml
+     * servings: {{1.5%kg}} of bread
+     * ```
      */
-    servings?: number | string;
+    servings?: MetadataScalingVar;
     /** The yield of the recipe.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * Can be given either as:
+     * - a number
+     * - a string which starts with a number (which will be used for scaling) followed by a comma and then whatever you want
+     * - or an arbitrary scalable number, optionally preceded and/or followed by text.
      *
      * Interchangeable with `servings` or `serves`. If multiple ones are defined,
      * the prevailance order for the number which will used for scaling
      * is `servings` \> `yield` \> `serves`. See {@link Metadata.servings | servings}
      * for examples.
      */
-    yield?: number | string;
+    yield?: MetadataScalingVar;
     /** The number of people the recipe serves.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * Can be given either as:
+     * - a number
+     * - a string which starts with a number (which will be used for scaling) followed by a comma and then whatever you want
+     * - or an arbitrary scalable number, optionally preceded and/or followed by text.
      *
      * Interchangeable with `servings` or `yield`. If multiple ones are defined,
      * the prevailance order for the number which will used for scaling
      * is `servings` \> `yield` \> `serves`. See {@link Metadata.servings | servings}
      * for examples.
      */
-    serves?: number | string;
+    serves?: MetadataScalingVar;
     /** The course of the recipe. */
     course?: string;
     /** The category of the recipe. */
@@ -593,6 +618,12 @@ interface IngredientItem {
      * `@|group|...` syntax), they represent a single logical choice.
      */
     group?: string;
+    /**
+     * An optional subgroup identifier for binding multiple ingredients together
+     * within a group. Ingredients sharing the same `group` and `subgroup` are
+     * selected together as a unit (e.g., from `@|group/1|...` syntax).
+     */
+    subgroup?: string;
 }
 /**
  * Represents the choices one can make in a recipe
@@ -606,9 +637,13 @@ interface RecipeAlternatives {
     ingredientItems: Map<string, IngredientAlternative[]>;
     /** Map of choices that can be made for Grouped Ingredient StepItem's
      * - Keys are the Group IDs (e.g. "eggs" for `@|eggs|...`)
-     * - Values are arrays of IngredientAlternative objects representing the choices available for that group
+     * - Values are arrays of subgroups, where each subgroup is an array of
+     *   bound IngredientAlternative objects that are selected together.
+     *   Items sharing the same subgroup key (e.g., `@|group/1|...`) are
+     *   in the same inner array. Items without a subgroup key each form
+     *   their own single-element subgroup.
      */
-    ingredientGroups: Map<string, IngredientAlternative[]>;
+    ingredientGroups: Map<string, IngredientAlternative[][]>;
 }
 /**
  * Represents the choices to apply when computing ingredient quantities.
@@ -1918,4 +1953,4 @@ declare class BadIndentationError extends Error {
     constructor();
 }
 
-export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, BadIndentationError, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FlatAndGroup, type FlatGroup, type FlatOrGroup, type FractionValue, type GetIngredientQuantitiesOptions, type Group, type Ingredient, type IngredientAlternative, type IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, NoTabAsIndentError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSimpleGroup, renderFractionAsVulgar };
+export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, BadIndentationError, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FlatAndGroup, type FlatGroup, type FlatOrGroup, type FractionValue, type GetIngredientQuantitiesOptions, type Group, type Ingredient, type IngredientAlternative, type IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataScalingVar, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, NoTabAsIndentError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSimpleGroup, renderFractionAsVulgar };