@jclind/ingredient-parser 1.3.0 → 1.3.2

package/README.md

@@ -1,211 +1,250 @@
-# @jclind/ingredient-parser
-
-[![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)
-
-A TypeScript package for parsing ingredient strings and retrieving structured ingredient data from the Spoonacular API.
-
-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
-```
-
-## 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)
-```
-
-## 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
-{
-  id: string
-  parsedIngredient: ParsedIngredientType
-  ingredientData: IngredientDataType | null
-  error?: {
-    message: string
-  }
-}
-```
-
----
-
-### `parsedIngredient`
-
-```ts
-{
-  quantity: 1,
-  unit: 'cup',
-  unitPlural: 'cups',
-  symbol: 'c',
-  ingredient: 'rice',
-  originalIngredientString: '1 cup rice, washed',
-  minQty: 1,
-  maxQty: 1,
-  comment: 'washed'
-}
-```
-
----
-
-### `ingredientData`
-
-```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 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' },
-  ingredientData: null,
-  parsedIngredient: {
-    quantity: 0,
-    unit: 'q.b.',
-    unitPlural: 'q.b.',
-    symbol: null,
-    ingredient: 'Invalid Text',
-    originalIngredientString: 'Invalid Text',
-    minQty: 0,
-    maxQty: 0,
-    comment: null
-  }
-}
-*/
-```
-
-### Invalid API Key
-
-```ts
-parseIngredient('1 cup rice', INVALID_API_KEY)
-
-/*
-{
-  error: { message: 'API Key Not Valid' },
-  ingredientData: null,
-  parsedIngredient: {
-    quantity: 1,
-    unit: 'cup',
-    unitPlural: 'cups',
-    symbol: 'c',
-    ingredient: 'rice',
-    originalIngredientString: '1 cup rice',
-    minQty: 1,
-    maxQty: 1,
-    comment: null
-  }
-}
-*/
-```
-
-## TypeScript
-
-This package ships with full TypeScript definitions. No additional `@types` package required.
-
-```ts
-import {
-  parseIngredient,
-  ParsedIngredientType,
-  IngredientDataType,
-  IngredientResponseType,
-} from '@jclind/ingredient-parser'
-
-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 | 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.
+# @jclind/ingredient-parser
+
+[![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)
+
+A TypeScript package for parsing ingredient strings and retrieving structured ingredient data from the Spoonacular API.
+
+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
+```
+
+## Quick Start
+
+```ts
+import { ingredientParser } from '@jclind/ingredient-parser'
+
+const result = await ingredientParser('1 cup rice, washed', 'YOUR_API_KEY', {
+  returnNutritionData: true,
+})
+
+console.log(result)
+```
+
+## API
+
+### `ingredientParser(ingredientString, apiKey, options?)`
+
+Parses an ingredient string and returns both the parsed ingredient data and ingredient metadata retrieved from Spoonacular.
+
+```ts
+import { ingredientParser } from '@jclind/ingredient-parser'
+
+ingredientParser(
+  ingredientString: string,
+  apiKey: string,
+  options?: {
+    returnNutritionData?: boolean
+    imageSize?: '100x100' | '250x250' | '500x500'
+    serverUrl?: string
+  }
+): Promise<IngredientResponse>
+```
+
+| Parameter          | Type     | Required | Description                                             |
+| ------------------ | -------- | -------- | ------------------------------------------------------- |
+| `ingredientString` | `string` | Yes      | Ingredient string formatted like `2 cups onions, diced` |
+| `apiKey`           | `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`       |
+| `imageSize`           | `'100x100' \| '250x250' \| '500x500'`  | `'100x100'` | Size of the ingredient image returned in `imagePath`          |
+| `serverUrl`           | `string`                                | —           | Override the default proxy server URL used to call Spoonacular |
+
+---
+
+### `parseIngredientString(ingredientString)`
+
+Parses an ingredient string locally without any network calls. Use this when you only need quantity, unit, and ingredient name extraction.
+
+```ts
+import { parseIngredientString } from '@jclind/ingredient-parser'
+
+parseIngredientString(ingredientString: string): ParsedIngredient
+```
+
+```ts
+parseIngredientString('1 cup rice, washed')
+// {
+//   quantity: 1,
+//   unit: 'cup',
+//   unitPlural: 'cups',
+//   symbol: 'c',
+//   ingredient: 'rice',
+//   originalIngredientString: '1 cup rice, washed',
+//   minQty: 1,
+//   maxQty: 1,
+//   comment: 'washed'
+// }
+```
+
+---
+
+## Response Structure
+
+`ingredientParser` returns a discriminated union. On success, `ingredientData` is always present. On error, `error` is present and `ingredientData` is `null`.
+
+```ts
+// Success
+{
+  parsedIngredient: ParsedIngredient
+  ingredientData: IngredientData
+  id?: string
+}
+
+// Error
+{
+  error: { message: string }
+  parsedIngredient: ParsedIngredient
+  ingredientData: null
+  id?: string
+}
+```
+
+---
+
+### `parsedIngredient`
+
+```ts
+{
+  quantity: 1,
+  unit: 'cup',
+  unitPlural: 'cups',
+  symbol: 'c',
+  ingredient: 'rice',
+  originalIngredientString: '1 cup rice, washed',
+  minQty: 1,
+  maxQty: 1,
+  comment: 'washed'
+}
+```
+
+---
+
+### `ingredientData`
+
+```ts
+{
+  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: [...],
+    properties: [...],
+    flavonoids: [...],
+    caloricBreakdown: {...},
+    weightPerServing: {...}
+  },
+  totalPriceUSACents: 75.71
+}
+```
+
+---
+
+## Error Handling
+
+The function returns an error object (and `ingredientData: null`) when the ingredient cannot be identified or the API key is invalid. `parsedIngredient` is always populated.
+
+### Unknown Ingredient
+
+```ts
+const result = await ingredientParser('Invalid Text', 'YOUR_API_KEY')
+
+/*
+{
+  error: { message: 'Ingredient not formatted correctly or Ingredient Unknown. Please pass ingredient comments/instructions after a comma' },
+  ingredientData: null,
+  parsedIngredient: {
+    quantity: null,
+    unit: null,
+    unitPlural: null,
+    symbol: null,
+    ingredient: 'Invalid Text',
+    originalIngredientString: 'Invalid Text',
+    minQty: null,
+    maxQty: null,
+    comment: null
+  }
+}
+*/
+```
+
+### Invalid API Key
+
+```ts
+const result = await ingredientParser('1 cup rice', 'INVALID_KEY')
+
+/*
+{
+  error: { message: 'API Key Not Valid' },
+  ingredientData: null,
+  parsedIngredient: {
+    quantity: 1,
+    unit: 'cup',
+    unitPlural: 'cups',
+    symbol: 'c',
+    ingredient: 'rice',
+    originalIngredientString: '1 cup rice',
+    minQty: 1,
+    maxQty: 1,
+    comment: null
+  }
+}
+*/
+```
+
+---
+
+## TypeScript
+
+This package ships with full TypeScript definitions. No additional `@types` package required.
+
+```ts
+import {
+  ingredientParser,
+  parseIngredientString,
+  ParsedIngredient,
+  IngredientData,
+  IngredientResponse,
+} from '@jclind/ingredient-parser'
+
+const result: IngredientResponse = await ingredientParser(
+  '1 cup rice, washed',
+  'YOUR_API_KEY'
+)
+
+if ('error' in result) {
+  console.error(result.error.message)
+} else {
+  const parsed: ParsedIngredient = result.parsedIngredient
+  const data: IngredientData = result.ingredientData
+}
+```
+
+---
+
+## Notes
+
+- A valid Spoonacular API key is required for ingredient lookups via `ingredientParser`.
+- `parseIngredientString` works offline with no API key.
+- Nutrition data is optional and disabled by default to reduce API usage.
+- `parsedIngredient` is always populated, even when the API call 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.3.0",
+  "version": "1.3.2",
   "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"
   }
 }