@jclind/ingredient-parser 1.2.13 → 1.3.0

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.js

@@ -5,15 +5,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createIngredientServerHttp = exports.spoonacularHttp = void 0;
 const axios_1 = __importDefault(require("axios"));
+// Webpack 5 can resolve require("axios") to the ESM entry without setting
+// __esModule, causing __importDefault to double-wrap it. The result is that
+// _axios is the module namespace object rather than the axios instance, so
+// .create lands one level deeper than expected.
+const axios = typeof axios_1.default.create === 'function'
+    ? axios_1.default
+    : axios_1.default.default;
 const DEFAULT_SERVER_URL = 'https://ingredient-parser-service-production-2635.up.railway.app';
-exports.spoonacularHttp = axios_1.default.create({
+exports.spoonacularHttp = axios.create({
     baseURL: 'https://api.spoonacular.com/food/ingredients/',
     headers: {
         'Content-type': 'application/json',
     },
     timeout: 8000,
 });
-const createIngredientServerHttp = (serverUrl) => axios_1.default.create({
+const createIngredientServerHttp = (serverUrl) => axios.create({
     baseURL: serverUrl || DEFAULT_SERVER_URL,
     headers: {
         'Content-type': 'application/json',

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

@@ -1,4 +1,5 @@
 import { IngredientData } from '../../types.js';
-export declare const parseAndEnrich: (ingredientString: string, spoonacularApiKey: string, serverUrl?: string) => Promise<IngredientData | null>;
+export declare const getIngredientFromServer: (name: string, serverUrl?: string) => Promise<IngredientData | null>;
+export declare const saveIngredientToServer: (name: string, ingredientData: IngredientData, serverUrl?: string) => void;
 export declare const searchIngredient: (name: string, spoonacularAPIKey: string) => Promise<import("axios").AxiosResponse<any, any, {}>>;
 export declare const getIngredientInformation: (ingrId: number, unit: boolean, spoonacularAPIKey: string) => Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/src/api/requests.js

@@ -8,16 +8,13 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getIngredientInformation = exports.searchIngredient = exports.parseAndEnrich = void 0;
-const axios_1 = __importDefault(require("axios"));
+exports.getIngredientInformation = exports.searchIngredient = exports.saveIngredientToServer = exports.getIngredientFromServer = void 0;
+const axios_1 = require("axios");
 const http_js_1 = require("./http.js");
 function handleRequestError(error) {
     var _a, _b, _c;
-    if (axios_1.default.isAxiosError(error)) {
+    if ((0, axios_1.isAxiosError)(error)) {
         const status = (_a = error.response) === null || _a === void 0 ? void 0 : _a.status;
         const code = (_c = (_b = error.response) === null || _b === void 0 ? void 0 : _b.data) === null || _c === void 0 ? void 0 : _c.code;
         if (status === 401 || code === 401)
@@ -30,21 +27,28 @@ function handleRequestError(error) {
     }
     throw new Error('Network error, please try again');
 }
-const parseAndEnrich = (ingredientString, spoonacularApiKey, serverUrl) => __awaiter(void 0, void 0, void 0, function* () {
+const getIngredientFromServer = (name, serverUrl) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     try {
         const serverHttp = (0, http_js_1.createIngredientServerHttp)(serverUrl);
-        const response = yield serverHttp.post('/parse', {
-            ingredientString,
-            spoonacularApiKey,
-        });
+        const response = yield serverHttp.get(`/ingredient/${encodeURIComponent(name)}`);
         return (_a = response.data.data) !== null && _a !== void 0 ? _a : null;
     }
-    catch (error) {
-        handleRequestError(error);
+    catch (_b) {
+        // Treat any server error as a cache miss and fall through to Spoonacular
+        return null;
     }
 });
-exports.parseAndEnrich = parseAndEnrich;
+exports.getIngredientFromServer = getIngredientFromServer;
+const saveIngredientToServer = (name, ingredientData, serverUrl) => {
+    const serverHttp = (0, http_js_1.createIngredientServerHttp)(serverUrl);
+    serverHttp
+        .post('/ingredient', { name, ingredientData })
+        .catch(() => {
+        // Fire-and-forget — a failed write doesn't affect the caller
+    });
+};
+exports.saveIngredientToServer = saveIngredientToServer;
 const searchIngredient = (name, spoonacularAPIKey) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         return yield http_js_1.spoonacularHttp.get(`search?query=${name}&number=1&apiKey=${spoonacularAPIKey}`);

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

@@ -1,2 +1,2 @@
 import { IngredientData } from '../../types.js';
-export declare function getIngredientInfo(ingredientString: string, spoonacularAPIKey: string, serverUrl?: string): Promise<IngredientData | null>;
+export declare function getIngredientInfo(ingredientName: string, spoonacularAPIKey: string, serverUrl?: string): Promise<IngredientData | null>;

package/dist/src/funcs/getIngredientInfo.js

@@ -11,13 +11,16 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getIngredientInfo = getIngredientInfo;
 const requests_js_1 = require("../api/requests.js");
-function getIngredientInfo(ingredientString, spoonacularAPIKey, serverUrl) {
+const getSpoonacularIngrData_js_1 = require("./getSpoonacularIngrData.js");
+function getIngredientInfo(ingredientName, spoonacularAPIKey, serverUrl) {
     return __awaiter(this, void 0, void 0, function* () {
-        try {
-            return yield (0, requests_js_1.parseAndEnrich)(ingredientString, spoonacularAPIKey, serverUrl);
-        }
-        catch (error) {
-            throw new Error(error.message || 'Failed to fetch ingredient data');
-        }
+        const cached = yield (0, requests_js_1.getIngredientFromServer)(ingredientName, serverUrl);
+        if (cached)
+            return cached;
+        const spoonacularData = yield (0, getSpoonacularIngrData_js_1.getSpoonacularIngrData)(ingredientName, spoonacularAPIKey);
+        if (!spoonacularData)
+            return null;
+        (0, requests_js_1.saveIngredientToServer)(ingredientName, spoonacularData, serverUrl);
+        return spoonacularData;
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jclind/ingredient-parser",
-  "version": "1.2.13",
+  "version": "1.3.0",
   "description": "Parses given sentence including ingredient information and attempts to return quantity, measurement and ingredient data",
   "keywords": [
     "recipe",