@tmlmt/cooklang-parser 3.0.0-alpha.20 → 3.0.0-alpha.22

package/dist/index.d.cts

@@ -509,7 +509,7 @@ interface IngredientExtras {
      * Used if: the ingredient is a recipe
      *
      * @example
-     * ```cooklang
+     * ```yaml
      * Take @./essentials/doughs/pizza dough{1} out of the freezer and let it unfreeze overnight
      * ```
      * Would lead to:
@@ -541,9 +541,12 @@ interface AlternativeIngredientRef {
 interface IngredientQuantityGroup extends QuantityWithPlainUnit {
     /**
      * References to alternative ingredients for this quantity group.
+     * Each inner array represents one alternative choice option (subgroup).
+     * Items within the same inner array are combined with "+" (AND),
+     * while different inner arrays represent "or" alternatives.
      * If undefined, this group has no alternatives.
      */
-    alternatives?: AlternativeIngredientRef[];
+    alternatives?: AlternativeIngredientRef[][];
 }
 /**
  * Represents an AND group of quantities when primary units are incompatible but equivalents can be summed.
@@ -557,9 +560,12 @@ interface IngredientQuantityAndGroup extends FlatAndGroup<QuantityWithPlainUnit>
     equivalents?: QuantityWithPlainUnit[];
     /**
      * References to alternative ingredients for this quantity group.
+     * Each inner array represents one alternative choice option (subgroup).
+     * Items within the same inner array are combined with "+" (AND),
+     * while different inner arrays represent "or" alternatives.
      * If undefined, this group has no alternatives.
      */
-    alternatives?: AlternativeIngredientRef[];
+    alternatives?: AlternativeIngredientRef[][];
 }
 /**
  * Represents an ingredient in a recipe.
@@ -1760,15 +1766,15 @@ declare function renderFractionAsVulgar(num: number, den: number): string;
  * Format a numeric value (decimal or fraction) to a string.
  *
  * @param value - The decimal or fraction value to format
- * @param useVulgar - Whether to use Unicode vulgar fraction characters (default: false)
+ * @param useVulgar - Whether to use Unicode vulgar fraction characters (default: true)
  * @returns The formatted string representation
  * @category Helpers
  *
  * @example
  * ```typescript
  * formatNumericValue({ type: "decimal", decimal: 1.5 }); // "1.5"
- * formatNumericValue({ type: "fraction", num: 1, den: 2 }); // "1/2"
- * formatNumericValue({ type: "fraction", num: 1, den: 2 }, true); // "½"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }); // "½"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }, false); // "1/2"
  * formatNumericValue({ type: "fraction", num: 5, den: 4 }, true); // "1¼"
  * ```
  */
@@ -1899,7 +1905,7 @@ declare function isGroupedItem(item: IngredientItem): boolean;
  * for (const item of step.items) {
  *   if (item.type === 'ingredient') {
  *     item.alternatives.forEach((alt, idx) => {
- *       const isSelected = isAlternativeSelected(item, idx, recipe, choices);
+ *       const isSelected = isAlternativeSelected(recipe, choices, item, idx);
  *       // Render differently based on isSelected
  *     });
  *   }
@@ -2033,15 +2039,18 @@ declare function isSimpleGroup(entry: IngredientQuantityGroup | IngredientQuanti
  * for (const entry of ingredient.quantities) {
  *   if (hasAlternatives(entry)) {
  *     // entry.alternatives is available and non-empty
- *     for (const alt of entry.alternatives) {
- *       console.log(`Alternative ingredient index: ${alt.index}`);
+ *     for (const subgroup of entry.alternatives) {
+ *       // Each subgroup is one "or" choice; items within are combined with "+"
+ *       for (const alt of subgroup) {
+ *         console.log(`Alternative ingredient index: ${alt.index}`);
+ *       }
  *     }
  *   }
  * }
  * ```
  */
 declare function hasAlternatives(entry: IngredientQuantityGroup | IngredientQuantityAndGroup): entry is (IngredientQuantityGroup | IngredientQuantityAndGroup) & {
-    alternatives: AlternativeIngredientRef[];
+    alternatives: AlternativeIngredientRef[][];
 };
 
 /**

package/dist/index.d.ts

@@ -509,7 +509,7 @@ interface IngredientExtras {
      * Used if: the ingredient is a recipe
      *
      * @example
-     * ```cooklang
+     * ```yaml
      * Take @./essentials/doughs/pizza dough{1} out of the freezer and let it unfreeze overnight
      * ```
      * Would lead to:
@@ -541,9 +541,12 @@ interface AlternativeIngredientRef {
 interface IngredientQuantityGroup extends QuantityWithPlainUnit {
     /**
      * References to alternative ingredients for this quantity group.
+     * Each inner array represents one alternative choice option (subgroup).
+     * Items within the same inner array are combined with "+" (AND),
+     * while different inner arrays represent "or" alternatives.
      * If undefined, this group has no alternatives.
      */
-    alternatives?: AlternativeIngredientRef[];
+    alternatives?: AlternativeIngredientRef[][];
 }
 /**
  * Represents an AND group of quantities when primary units are incompatible but equivalents can be summed.
@@ -557,9 +560,12 @@ interface IngredientQuantityAndGroup extends FlatAndGroup<QuantityWithPlainUnit>
     equivalents?: QuantityWithPlainUnit[];
     /**
      * References to alternative ingredients for this quantity group.
+     * Each inner array represents one alternative choice option (subgroup).
+     * Items within the same inner array are combined with "+" (AND),
+     * while different inner arrays represent "or" alternatives.
      * If undefined, this group has no alternatives.
      */
-    alternatives?: AlternativeIngredientRef[];
+    alternatives?: AlternativeIngredientRef[][];
 }
 /**
  * Represents an ingredient in a recipe.
@@ -1760,15 +1766,15 @@ declare function renderFractionAsVulgar(num: number, den: number): string;
  * Format a numeric value (decimal or fraction) to a string.
  *
  * @param value - The decimal or fraction value to format
- * @param useVulgar - Whether to use Unicode vulgar fraction characters (default: false)
+ * @param useVulgar - Whether to use Unicode vulgar fraction characters (default: true)
  * @returns The formatted string representation
  * @category Helpers
  *
  * @example
  * ```typescript
  * formatNumericValue({ type: "decimal", decimal: 1.5 }); // "1.5"
- * formatNumericValue({ type: "fraction", num: 1, den: 2 }); // "1/2"
- * formatNumericValue({ type: "fraction", num: 1, den: 2 }, true); // "½"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }); // "½"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }, false); // "1/2"
  * formatNumericValue({ type: "fraction", num: 5, den: 4 }, true); // "1¼"
  * ```
  */
@@ -1899,7 +1905,7 @@ declare function isGroupedItem(item: IngredientItem): boolean;
  * for (const item of step.items) {
  *   if (item.type === 'ingredient') {
  *     item.alternatives.forEach((alt, idx) => {
- *       const isSelected = isAlternativeSelected(item, idx, recipe, choices);
+ *       const isSelected = isAlternativeSelected(recipe, choices, item, idx);
  *       // Render differently based on isSelected
  *     });
  *   }
@@ -2033,15 +2039,18 @@ declare function isSimpleGroup(entry: IngredientQuantityGroup | IngredientQuanti
  * for (const entry of ingredient.quantities) {
  *   if (hasAlternatives(entry)) {
  *     // entry.alternatives is available and non-empty
- *     for (const alt of entry.alternatives) {
- *       console.log(`Alternative ingredient index: ${alt.index}`);
+ *     for (const subgroup of entry.alternatives) {
+ *       // Each subgroup is one "or" choice; items within are combined with "+"
+ *       for (const alt of subgroup) {
+ *         console.log(`Alternative ingredient index: ${alt.index}`);
+ *       }
  *     }
  *   }
  * }
  * ```
  */
 declare function hasAlternatives(entry: IngredientQuantityGroup | IngredientQuantityAndGroup): entry is (IngredientQuantityGroup | IngredientQuantityAndGroup) & {
-    alternatives: AlternativeIngredientRef[];
+    alternatives: AlternativeIngredientRef[][];
 };
 
 /**

package/dist/index.js

@@ -2033,7 +2033,7 @@ function unionOfSets(s1, s2) {
 }
 function getAlternativeSignature(alternatives) {
   if (!alternatives || alternatives.length === 0) return null;
-  return alternatives.map((a2) => a2.index).sort((a2, b) => a2 - b).join(",");
+  return alternatives.flat().map((a2) => a2.index).sort((a2, b) => a2 - b).join(",");
 }
 
 // src/classes/pantry.ts
@@ -2428,7 +2428,7 @@ var Section = class {
 };
 
 // src/quantities/alternatives.ts
-import Big3 from "big.js";
+import Big4 from "big.js";
 
 // src/units/lookup.ts
 function findListWithCompatibleQuantity(list, quantity) {
@@ -2451,7 +2451,40 @@ function findCompatibleQuantityWithinList(list, quantity) {
 }
 
 // src/utils/general.ts
-var deepClone = (v) => structuredClone(v);
+import Big3 from "big.js";
+var legacyDeepClone = (v) => {
+  if (v === null || typeof v !== "object") {
+    return v;
+  }
+  if (v instanceof Big3) {
+    return new Big3(v);
+  }
+  if (v instanceof Map) {
+    return new Map(
+      Array.from(v.entries()).map(([k, val]) => [
+        legacyDeepClone(k),
+        legacyDeepClone(val)
+      ])
+    );
+  }
+  if (v instanceof Set) {
+    return new Set(
+      Array.from(v).map((val) => legacyDeepClone(val))
+    );
+  }
+  if (v instanceof Date) {
+    return new Date(v.getTime());
+  }
+  if (Array.isArray(v)) {
+    return v.map((item) => legacyDeepClone(item));
+  }
+  const cloned = {};
+  for (const key of Object.keys(v)) {
+    cloned[key] = legacyDeepClone(v[key]);
+  }
+  return cloned;
+};
+var deepClone = (v) => legacyDeepClone(v);
 
 // src/quantities/alternatives.ts
 function getEquivalentUnitsLists(...quantities) {
@@ -2677,7 +2710,7 @@ function regroupQuantitiesAndExpandEquivalents(sum, unitsLists, system) {
       return main.reduce((acc, v) => {
         const mainInList = findCompatibleQuantityWithinList(list, v);
         const conversionRatio = getBaseUnitRatio(v, mainInList);
-        const valueInOriginalUnit = Big3(getAverageValue(v.quantity)).times(
+        const valueInOriginalUnit = Big4(getAverageValue(v.quantity)).times(
           conversionRatio
         );
         const newValue = {
@@ -2689,7 +2722,7 @@ function regroupQuantitiesAndExpandEquivalents(sum, unitsLists, system) {
                 decimal: valueInOriginalUnit.toNumber()
               }
             },
-            Big3(getAverageValue(equiv.quantity)).div(
+            Big4(getAverageValue(equiv.quantity)).div(
               getAverageValue(mainInList.quantity)
             )
           )
@@ -2773,7 +2806,7 @@ function recomputeEquivalents(primaries, ratioMap, equivUnits) {
 }
 
 // src/classes/recipe.ts
-import Big4 from "big.js";
+import Big5 from "big.js";
 var _Recipe = class _Recipe {
   /**
    * Creates a new Recipe instance.
@@ -3313,7 +3346,7 @@ var _Recipe = class _Recipe {
             const currentSubgroupIdx = groupSubgroups.findIndex(
               (sg) => sg.some((alt) => alt.itemId === item.id)
             );
-            alternativeRefs = groupSubgroups.filter((_, idx) => idx !== currentSubgroupIdx).flatMap(
+            alternativeRefs = groupSubgroups.filter((_, idx) => idx !== currentSubgroupIdx).map(
               (subgroup) => subgroup.map((otherAlt) => {
                 const ref = {
                   index: otherAlt.index
@@ -3352,7 +3385,7 @@ var _Recipe = class _Recipe {
                 };
                 ref.quantities = [altQty];
               }
-              return ref;
+              return [ref];
             });
           }
           const altIndices = getAlternativeSignature(alternativeRefs) ?? "";
@@ -3373,28 +3406,36 @@ var _Recipe = class _Recipe {
           if (!groupsForIng.has(signature)) {
             groupsForIng.set(signature, {
               quantities: [],
-              alternativeQuantities: /* @__PURE__ */ new Map()
+              alternativeQuantities: /* @__PURE__ */ new Map(),
+              alternativeSubgroups: []
             });
           }
           const group = groupsForIng.get(signature);
           group.quantities.push(quantityEntry);
-          for (const ref of alternativeRefs ?? []) {
-            if (!group.alternativeQuantities.has(ref.index)) {
-              group.alternativeQuantities.set(ref.index, []);
-            }
-            for (const altQty of ref.quantities ?? []) {
-              const extended = toExtendedUnit({
-                quantity: altQty.quantity,
-                unit: altQty.unit
-              });
-              if (altQty.equivalents?.length) {
-                const eqEntries = [
-                  extended,
-                  ...altQty.equivalents.map((eq) => toExtendedUnit(eq))
-                ];
-                group.alternativeQuantities.get(ref.index).push({ or: eqEntries });
-              } else {
-                group.alternativeQuantities.get(ref.index).push(extended);
+          if (alternativeRefs && alternativeRefs.length > 0 && group.alternativeSubgroups.length === 0) {
+            group.alternativeSubgroups = alternativeRefs.map(
+              (subgroup) => subgroup.map((ref) => ref.index)
+            );
+          }
+          for (const subgroup of alternativeRefs ?? []) {
+            for (const ref of subgroup) {
+              if (!group.alternativeQuantities.has(ref.index)) {
+                group.alternativeQuantities.set(ref.index, []);
+              }
+              for (const altQty of ref.quantities ?? []) {
+                const extended = toExtendedUnit({
+                  quantity: altQty.quantity,
+                  unit: altQty.unit
+                });
+                if (altQty.equivalents?.length) {
+                  const eqEntries = [
+                    extended,
+                    ...altQty.equivalents.map((eq) => toExtendedUnit(eq))
+                  ];
+                  group.alternativeQuantities.get(ref.index).push({ or: eqEntries });
+                } else {
+                  group.alternativeQuantities.get(ref.index).push(extended);
+                }
               }
             }
           }
@@ -3517,17 +3558,25 @@ var _Recipe = class _Recipe {
               this.unitSystem
             );
             const flattened = flattenPlainUnitGroup(summed);
-            const alternatives = group.alternativeQuantities.size > 0 ? [...group.alternativeQuantities].map(([altIdx, altQtys]) => ({
-              index: altIdx,
-              ...altQtys.length > 0 && {
-                quantities: flattenPlainUnitGroup(
-                  addEquivalentsAndSimplify(altQtys, this.unitSystem)
-                ).flatMap(
-                  /* v8 ignore next -- item.and branch requires complex nested AND-with-equivalents structure */
-                  (item) => "quantity" in item ? [item] : item.and
-                )
-              }
-            })) : void 0;
+            let alternatives;
+            if (group.alternativeSubgroups.length > 0) {
+              alternatives = group.alternativeSubgroups.map(
+                (subgroupIndices) => subgroupIndices.map((altIdx) => {
+                  const altQtys = group.alternativeQuantities.get(altIdx);
+                  return {
+                    index: altIdx,
+                    ...altQtys.length > 0 && {
+                      quantities: flattenPlainUnitGroup(
+                        addEquivalentsAndSimplify(altQtys, this.unitSystem)
+                      ).flatMap(
+                        /* v8 ignore next -- item.and branch requires complex nested AND-with-equivalents structure */
+                        (item) => "quantity" in item ? [item] : item.and
+                      )
+                    }
+                  };
+                })
+              );
+            }
             for (const gq of flattened) {
               if ("and" in gq) {
                 quantityGroups.push({
@@ -3805,7 +3854,7 @@ var _Recipe = class _Recipe {
     if (originalServings === void 0 || originalServings === 0) {
       originalServings = 1;
     }
-    const factor = Big4(newServings).div(originalServings);
+    const factor = Big5(newServings).div(originalServings);
     return this.scaleBy(factor);
   }
   /**
@@ -3824,7 +3873,7 @@ var _Recipe = class _Recipe {
     function scaleAlternativesBy(alternatives, factor2) {
       for (const alternative of alternatives) {
         if (alternative.quantity) {
-          const scaleFactor = alternative.scalable ? Big4(factor2) : 1;
+          const scaleFactor = alternative.scalable ? Big5(factor2) : 1;
           if (alternative.quantity.type !== "fixed" || alternative.quantity.value.type !== "text") {
             alternative.quantity = multiplyQuantityValue(
               alternative.quantity,
@@ -3897,10 +3946,10 @@ var _Recipe = class _Recipe {
       arbitrary.unit = optimized.unit;
     }
     newRecipe._populateIngredientQuantities();
-    newRecipe.servings = Big4(originalServings).times(factor).toNumber();
+    newRecipe.servings = Big5(originalServings).times(factor).toNumber();
     for (const metaVar of ["servings", "serves"]) {
       if (typeof newRecipe.metadata[metaVar] === "number") {
-        newRecipe.metadata[metaVar] = Big4(newRecipe.metadata[metaVar]).times(factor).toNumber();
+        newRecipe.metadata[metaVar] = Big5(newRecipe.metadata[metaVar]).times(factor).toNumber();
       }
     }
     if (newRecipe.metadata.yield && this.metadata.yield) {