@jclind/ingredient-parser 1.2.14 → 1.3.1

package/README.md

@@ -1,80 +1,136 @@
-# `@jclind/ingredient-parser`
+# @jclind/ingredient-parser
 
-A package for parsing ingredient strings and retrieving data about the ingredient.
+[![npm version](https://img.shields.io/npm/v/@jclind/ingredient-parser)](https://www.npmjs.com/package/@jclind/ingredient-parser)
+[![license](https://img.shields.io/npm/l/@jclind/ingredient-parser)](https://github.com/jclind/ingredient-parser/blob/main/LICENSE)
 
-## About
-This package is built with [recipe-ingredient-parser-v3](https://www.npmjs.com/package/recipe-ingredient-parser-v3) and also returns ingredient data along with parsing the ingredient. If you don't need the ingredient data, just the parsed ingredient, I recommend using [recipe-ingredient-parser-v3](https://www.npmjs.com/package/recipe-ingredient-parser-v3).
+A TypeScript package for parsing ingredient strings and retrieving structured ingredient data from the Spoonacular API.
 
-## Installation:
-`npm install @jclind/ingredient-parser`
-  
-## Usage
+Built on top of [recipe-ingredient-parser-v3](https://www.npmjs.com/package/recipe-ingredient-parser-v3). If you only need ingredient parsing without ingredient metadata, nutrition, or API lookups, you may prefer using that package directly.
+
+## Installation
+
+```sh
+npm install @jclind/ingredient-parser
 ```
-import { parseIngredient } from '@jclind/ingredient-parser';
 
-const ingredientString = '1 cup rice, washed';
-const apiKey = 'YOUR_API_KEY';
-const options = { returnNutritionData: true };
-parseIngredient(ingredientString, apiKey, options);
+## Quick Start
+
+```ts
+import { parseIngredient } from '@jclind/ingredient-parser'
+
+const ingredientString = '1 cup rice, washed'
+const apiKey = 'YOUR_API_KEY'
+
+const result = await parseIngredient(ingredientString, apiKey, {
+  returnNutritionData: true,
+})
+
+console.log(result)
 ```
-Returns an object `{id: (randomly generated id unique to every request), parsedIngredient, ingredientData}` with the following properties/values.
 
-`parsedIngredient`:
+## API
+
+### `parseIngredient(ingredientString, SPOONACULAR_API_KEY, options?)`
+
+Parses an ingredient string and returns both the parsed ingredient data and ingredient metadata retrieved from Spoonacular.
+
+```ts
+import { parseIngredient } from '@jclind/ingredient-parser'
+
+parseIngredient(
+  ingredientString: string,
+  SPOONACULAR_API_KEY: string,
+  options?: {
+    returnNutritionData?: boolean
+  }
+): Promise<IngredientResponseType>
 ```
+
+| Parameter             | Type     | Required | Description                                             |
+| --------------------- | -------- | -------- | ------------------------------------------------------- |
+| `ingredientString`    | `string` | Yes      | Ingredient string formatted like `2 cups onions, diced` |
+| `SPOONACULAR_API_KEY` | `string` | Yes      | Your Spoonacular API key                                |
+| `options`             | `object` | No       | Additional parsing options                              |
+
+### Options
+
+| Option                | Type      | Default | Description                                             |
+| --------------------- | --------- | ------- | ------------------------------------------------------- |
+| `returnNutritionData` | `boolean` | `false` | Includes Spoonacular nutrition data in `ingredientData` |
+
+---
+
+## Response Structure
+
+Returns an object with the following shape:
+
+```ts
 {
-    quantity: 1,
-    unit: 'cup',
-    unitPlural: 'cups',
-    symbol: 'c',
-    ingredient: 'rice',
-    originalIngredientString: '1 cup rice, washed'
-    minQty: 1,
-    maxQty: 1,
-    comment: 'washed'
+  id: string
+  parsedIngredient: ParsedIngredientType
+  ingredientData: IngredientDataType | null
+  error?: {
+    message: string
+  }
 }
 ```
 
-`ingredientData:`
-```
+---
+
+### `parsedIngredient`
+
+```ts
 {
-    _id: '63caeabf4762c87be39c3795',    
-    ingredientId: 20444,
-    originalName: 'rice',
-    name: 'rice',
-    amount: 1,
-    possibleUnits: [ 'g', 'oz', 'cup' ],
-    consistency: 'solid',
-    shoppingListUnits: [ 'ounces', 'pounds' ],
-    aisle: 'Pasta and Rice',
-    image: 'uncooked-white-rice.png',
-    imagePath: 'https://spoonacular.com/cdn/ingredients_100x100/uncooked-white-rice.png',
-    nutrition?: {
-      nutrients: [Array],
-      properties: [Array],
-      flavonoids: [Array],
-      caloricBreakdown: [Object],
-      weightPerServing: [Object]
-    },
-    names: [ 'rice' ],
-    dateAdded: 1674242751000,
-    totalPriceUSACents: 75.71
+  quantity: 1,
+  unit: 'cup',
+  unitPlural: 'cups',
+  symbol: 'c',
+  ingredient: 'rice',
+  originalIngredientString: '1 cup rice, washed',
+  minQty: 1,
+  maxQty: 1,
+  comment: 'washed'
 }
 ```
 
-## API
-`parseIngredient(ingredientString: string, SPOONACULAR_API_KEY: string) => { parsedIngredient, IngredientData }` Takes an ingredient string and a spoonacular API key and returns the parsed ingredient and the ingredient data.
+---
 
-- `ingredientString` (string) [required] : preferably formatted as such: (quantity) (unit) (ingredient), (comment separated by a comment) i.e. 2 cups onions, diced
-- `SPOONACULAR_API_KEY` (string) [required] : your unique [spoonacular](https://spoonacular.com/food-api) API key.
-- `options` (object) [optional] : an object containing additional options. Currently, the only supported option is `returnNutritionData`, which, if set to `true`, will include nutrition data in the ingredientData object.
+### `ingredientData`
 
-Note: You need to sign up for a free API key from [spoonacular website](https://spoonacular.com/food-api).
+```ts
+{
+  _id: '63caeabf4762c87be39c3795',
+  ingredientId: 20444,
+  originalName: 'rice',
+  name: 'rice',
+  amount: 1,
+  possibleUnits: ['g', 'oz', 'cup'],
+  consistency: 'solid',
+  shoppingListUnits: ['ounces', 'pounds'],
+  aisle: 'Pasta and Rice',
+  image: 'uncooked-white-rice.png',
+  imagePath: 'https://spoonacular.com/cdn/ingredients_100x100/uncooked-white-rice.png',
+  nutrition?: {
+    nutrients: [Array],
+    properties: [Array],
+    flavonoids: [Array],
+    caloricBreakdown: [Object],
+    weightPerServing: [Object]
+  },
+  dateAdded: 1674242751000,
+  totalPriceUSACents: 75.71
+}
+```
 
 ## Error Handling
-If the passed ingredient isn't formatted correctly or the ingredient is unknown, an error will be returned with the original object.
-With invalid text:
-```
+
+If the ingredient cannot be identified or the API key is invalid, the function returns an error object while still including the parsed ingredient structure.
+
+### Unknown Ingredient
+
+```ts
 parseIngredient('Invalid Text', YOUR_API_KEY)
+
 /*
 {
   error: { message: 'No Data Found, unknown ingredient: invalid text' },
@@ -93,9 +149,12 @@ parseIngredient('Invalid Text', YOUR_API_KEY)
 }
 */
 ```
-With an inavlid API_KEY:
-```
+
+### Invalid API Key
+
+```ts
 parseIngredient('1 cup rice', INVALID_API_KEY)
+
 /*
 {
   error: { message: 'API Key Not Valid' },
@@ -106,7 +165,7 @@ parseIngredient('1 cup rice', INVALID_API_KEY)
     unitPlural: 'cups',
     symbol: 'c',
     ingredient: 'rice',
-    originalIngredientString: '1 cup rice'
+    originalIngredientString: '1 cup rice',
     minQty: 1,
     maxQty: 1,
     comment: null
@@ -115,16 +174,38 @@ parseIngredient('1 cup rice', INVALID_API_KEY)
 */
 ```
 
-## Typescript
-Typescript definitions are also included in the ingredient-parser package:
-```
-import { parseIngredient, ParsedIngredientType, IngredientDataType, IngredientResponseType, } from '@jclind/ingredient-parser';
+## TypeScript
+
+This package ships with full TypeScript definitions. No additional `@types` package required.
 
-const ingredientString: string = '1 cup rice, washed';
-const apiKey: string = 'YOUR_API_KEY';
+```ts
+import {
+  parseIngredient,
+  ParsedIngredientType,
+  IngredientDataType,
+  IngredientResponseType,
+} from '@jclind/ingredient-parser'
 
-const parsed: IngredientResponseType = parseIngredient(ingredientString, apiKey);
+const ingredientString: string = '1 cup rice, washed'
+const apiKey: string = 'YOUR_API_KEY'
+
+const parsed: IngredientResponseType = await parseIngredient(
+  ingredientString,
+  apiKey,
+)
 
 const parsedIngredient: ParsedIngredientType = parsed.parsedIngredient
-const ingredientData: IngredientDataType = parsed.ingredientData
+
+const ingredientData: IngredientDataType | null = parsed.ingredientData
 ```
+
+## Notes
+
+- A valid Spoonacular API key is required for ingredient lookups.
+- Ingredient parsing is powered by `recipe-ingredient-parser-v3`.
+- Nutrition data is optional and disabled by default to reduce API usage.
+- Parsed ingredient results are returned even when ingredient lookup fails.
+
+## Issues & Contributing
+
+Found a bug or have a feature request? [Open an issue](https://github.com/jclind/ingredient-parser/issues) on GitHub. PRs are welcome.

package/dist/src/api/http.d.ts

@@ -1,2 +1,3 @@
-export declare const spoonacularHttp: import("axios").AxiosInstance;
-export declare const createIngredientServerHttp: (serverUrl?: string) => import("axios").AxiosInstance;
+import _axios from 'axios';
+export declare const spoonacularHttp: _axios.AxiosInstance;
+export declare const createIngredientServerHttp: (serverUrl?: string) => _axios.AxiosInstance;

package/dist/src/funcs/parseIngredientString.js

@@ -4,7 +4,85 @@ exports.parseIngredientString = void 0;
 const convertFractions_js_1 = require("./convertFractions.js");
 const parseStringConsecutiveTs_js_1 = require("./parseStringConsecutiveTs.js");
 const parseIngredientString = (ingrStr) => {
-    var _a, _b;
+    var _a, _b, _c;
+    // Input validation
+    if (typeof ingrStr !== 'string' || ingrStr === null || ingrStr === undefined) {
+        throw new TypeError('parseIngredientString expects a string input');
+    }
+    // Store original input before any modifications
+    const originalInput = ingrStr;
+    // Extract range quantities (e.g., "1-2 cups", "2 to 3 cups")
+    let minQty = null;
+    let maxQty = null;
+    const hyphenRangeMatch = ingrStr.match(/(\d+(?:\.\d+)?)\s*[-–]\s*(\d+(?:\.\d+)?)/);
+    const toRangeMatch = ingrStr.match(/(\d+(?:\.\d+)?)\s+to\s+(\d+(?:\.\d+)?)/i);
+    if (hyphenRangeMatch) {
+        minQty = parseFloat(hyphenRangeMatch[1]);
+        maxQty = parseFloat(hyphenRangeMatch[2]);
+        // Replace the range with minQty for parsing
+        ingrStr = ingrStr.replace(hyphenRangeMatch[0], String(minQty));
+    }
+    else if (toRangeMatch) {
+        minQty = parseFloat(toRangeMatch[1]);
+        maxQty = parseFloat(toRangeMatch[2]);
+        // Replace the range with minQty for parsing
+        ingrStr = ingrStr.replace(toRangeMatch[0], String(minQty));
+    }
+    // Store extracted ranges for later use
+    const extractedMinQty = minQty;
+    const extractedMaxQty = maxQty;
+    // Pre-processing: handle informal quantity patterns ("a pinch of", "handful", "dash")
+    // These patterns aren't well-handled by the upstream parser
+    const informalQtyPatterns = [
+        {
+            // "a pinch of salt"
+            regex: /^a\s+(pinch|dash|handful)\s+of\s+(.+)$/i,
+            extract: (match) => ({
+                quantity: 1,
+                unit: match[1].toLowerCase(),
+                ingredient: match[2].trim(),
+            })
+        },
+        {
+            // "pinch of salt", "dash of hot sauce"
+            regex: /^(pinch|dash|handful)\s+of\s+(.+)$/i,
+            extract: (match) => ({
+                quantity: 1,
+                unit: match[1].toLowerCase(),
+                ingredient: match[2].trim(),
+            })
+        },
+        {
+            // "handful spinach" (no "of")
+            regex: /^(pinch|dash|handful)\s+(.+)$/i,
+            extract: (match) => ({
+                quantity: 1,
+                unit: match[1].toLowerCase(),
+                ingredient: match[2].trim(),
+            })
+        },
+    ];
+    for (const pattern of informalQtyPatterns) {
+        const match = ingrStr.match(pattern.regex);
+        if (match) {
+            const { quantity, unit, ingredient } = pattern.extract(match);
+            // Apply descriptor stripping to ingredient
+            const wordsToRemove = ['small', 'medium', 'large', 'fresh', 'canned', 'freshly', 'finely', 'roughly', 'coarsely', 'grated', 'chopped'];
+            const regex = new RegExp('\\b(' + wordsToRemove.join('|') + ')\\b', 'gi');
+            const cleanedIngredient = ingredient.replace(regex, '').trim();
+            return {
+                quantity,
+                unit,
+                unitPlural: unit + 's',
+                symbol: null,
+                ingredient: cleanedIngredient,
+                originalIngredientString: originalInput,
+                minQty: quantity,
+                maxQty: quantity,
+                comment: '',
+            };
+        }
+    }
     // Define regular expressions for text inside parentheses and text before the first comma
     const parenRegex = /(\(.*?\))/;
     const commaRegex = /^(.*?)(?=,)/;
@@ -49,14 +127,83 @@ const parseIngredientString = (ingrStr) => {
         ml: 'milliliter',
         lb: 'pound',
         g: 'gram',
+        // Additional unit recognitions
+        sprigs: 'sprig',
+        sprig: 'sprig',
+        'bay leaves': 'bay leaf',
+        'bay leaf': 'bay leaf',
+        sheets: 'sheet',
+        sheet: 'sheet',
+        tblsp: 'tablespoon',
+        dessertspoon: 'dessertspoon',
+        dessertspoons: 'dessertspoon',
+        'fl oz': 'fluid ounce',
+        'fluid oz': 'fluid ounce',
     };
     const unitPattern = new RegExp('\\b(' + Object.keys(unitNormalizations).join('|') + ')\\b', 'gi');
     const prepIngrText = ingrText.replace(unitPattern, match => { var _a; return (_a = unitNormalizations[match.toLowerCase()]) !== null && _a !== void 0 ? _a : match; });
-    const parsedIngrRes = (0, parseStringConsecutiveTs_js_1.parseStringConsecutiveTs)(prepIngrText);
+    let parsedIngrRes;
+    try {
+        parsedIngrRes = (0, parseStringConsecutiveTs_js_1.parseStringConsecutiveTs)(prepIngrText);
+    }
+    catch (_d) {
+        // Return degraded result for malformed input (e.g., division by zero)
+        return {
+            quantity: 0,
+            unit: null,
+            unitPlural: null,
+            symbol: null,
+            ingredient: ingrStr.replace(/[^a-zA-Z\s]/g, '').trim(),
+            minQty: null,
+            maxQty: null,
+            originalIngredientString: originalInput,
+            comment,
+        };
+    }
+    // Post-processing: check if ingredient name starts with an unrecognized unit
+    // The upstream parser doesn't recognize some units, so we extract them manually
+    const unrecognizedUnits = [
+        'sprig', 'sprigs',
+        'strip', 'strips',
+        'sheet', 'sheets',
+        'dessertspoon', 'dessertspoons',
+        'handful', 'handfuls',
+        'dash', 'dashes',
+        'bay leaf', 'bay leaves',
+    ];
+    const unrecognizedUnitPattern = new RegExp('^(' + unrecognizedUnits.join('|') + ')\\b', 'i');
+    if (parsedIngrRes.ingredient && parsedIngrRes.unit === null) {
+        const unitMatch = parsedIngrRes.ingredient.match(unrecognizedUnitPattern);
+        if (unitMatch) {
+            let unit = unitMatch[1].toLowerCase();
+            // Normalize plural forms to singular
+            const unitSingular = {
+                sprigs: 'sprig',
+                strips: 'strip',
+                sheets: 'sheet',
+                dessertspoons: 'dessertspoon',
+                handfuls: 'handful',
+                dashes: 'dash',
+                'bay leaves': 'bay leaf',
+            };
+            parsedIngrRes.unit = (_c = unitSingular[unit]) !== null && _c !== void 0 ? _c : unit;
+            parsedIngrRes.ingredient = parsedIngrRes.ingredient
+                .replace(unrecognizedUnitPattern, '')
+                .trim();
+        }
+    }
+    // Post-processing: handle "fl oz" / "fluid ounce" which upstream parser normalizes to "ounce"
+    if (parsedIngrRes.unit === 'ounce' &&
+        (originalInput.toLowerCase().includes('fl oz') ||
+            originalInput.toLowerCase().includes('fluid ounce'))) {
+        parsedIngrRes.unit = 'fluid ounce';
+        // Also fix the symbol
+        parsedIngrRes.symbol = 'fl oz';
+    }
     if (!parsedIngrRes.ingredient) {
-        return Object.assign(Object.assign({}, parsedIngrRes), { originalIngredientString: ingrStr, comment });
+        return Object.assign(Object.assign({}, parsedIngrRes), { originalIngredientString: originalInput, comment });
     }
-    const wordsToRemove = ['small', 'medium', 'large', 'fresh', 'canned'];
+    const wordsToRemove = ['small', 'medium', 'large', 'fresh', 'canned', 'freshly', 'finely', 'roughly', 'coarsely', 'grated', 'chopped'];
     const regex = new RegExp('\\b(' + wordsToRemove.join('|') + ')\\b', 'gi');
     const descriptorSet = new Set(wordsToRemove.map(w => w.toLowerCase()));
     const unit = parsedIngrRes.unit && descriptorSet.has(parsedIngrRes.unit.toLowerCase())
@@ -69,6 +216,6 @@ const parseIngredientString = (ingrStr) => {
         .replace(/^(fluid|fl|oz) /, '') // Remove "fluid ", "fl ", or "oz " at the beginning of the string
         .replace(regex, '')
         .trim();
-    return Object.assign(Object.assign({}, parsedIngrRes), { unit, ingredient: formattedIngrName, originalIngredientString: ingrStr, comment });
+    return Object.assign(Object.assign({}, parsedIngrRes), { unit, ingredient: formattedIngrName, originalIngredientString: originalInput, comment, minQty: extractedMinQty !== null && extractedMinQty !== void 0 ? extractedMinQty : parsedIngrRes.minQty, maxQty: extractedMaxQty !== null && extractedMaxQty !== void 0 ? extractedMaxQty : parsedIngrRes.maxQty });
 };
 exports.parseIngredientString = parseIngredientString;

package/dist/src/funcs/parseStringConsecutiveTs.d.ts

@@ -1,4 +1,3 @@
 import { ParsedIngredient } from '../../types.js';
-type ParsedIngredientOmitType = Omit<ParsedIngredient, 'originalIngredientString' | 'comment'>;
+export type ParsedIngredientOmitType = Omit<ParsedIngredient, 'originalIngredientString' | 'comment'>;
 export declare const parseStringConsecutiveTs: (ingrStr: string) => ParsedIngredientOmitType;
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jclind/ingredient-parser",
-  "version": "1.2.14",
+  "version": "1.3.1",
   "description": "Parses given sentence including ingredient information and attempts to return quantity, measurement and ingredient data",
   "keywords": [
     "recipe",
@@ -37,15 +37,15 @@
   "homepage": "https://github.com/jclind/ingredient-parser#readme",
   "dependencies": {
     "@jclind/ingredient-unit-converter": "^1.1.0",
-    "axios": "^1.0.0",
+    "axios": "^1.16.0",
     "recipe-ingredient-parser-v3": "^1.5.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.6.0",
     "jest": "^30.3.0",
-    "rimraf": "^5.0.0",
+    "rimraf": "^6.1.3",
     "ts-jest": "^29.4.9",
-    "typescript": "^5.0.0"
+    "typescript": "^6.0.3"
   }
 }