recipe-scrapers-js 0.1.0-alpha.4 → 0.1.0-alpha.6

package/README.md

@@ -19,14 +19,16 @@ A TypeScript/JavaScript library for scraping recipe data from various cooking we
 
 ## Installation
 
+Add the `recipe-scrapers-js` package and its peer dependencies.
+
 ```bash
-npm install recipe-scrapers-js
+npm install recipe-scrapers-js cheerio zod
 # or
-yarn add recipe-scrapers-js
+yarn add recipe-scrapers-js cheerio zod
 # or
-pnpm add recipe-scrapers-js
+pnpm add recipe-scrapers-js cheerio zod
 # or
-bun add recipe-scrapers-js
+bun add recipe-scrapers-js cheerio zod
 ```
 
 ## Usage
@@ -195,6 +197,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - Original [recipe-scrapers](https://github.com/hhursev/recipe-scrapers) Python library by [hhursev](https://github.com/hhursev)
 - [Schema.org Recipe specification](https://schema.org/Recipe)
 - [Cheerio](https://cheerio.js.org/) for HTML parsing
+- [Zod](https://zod.dev/) for schema validation
 
 ## Copyright and Usage
 

package/dist/index.js

@@ -1,5 +1,6 @@
 import * as cheerio from "cheerio";
 import { parse, toSeconds } from "iso8601-duration";
+import z from "zod/v4";
 
 //#region src/utils/index.ts
 function isDefined(value) {
@@ -145,7 +146,7 @@ function parseMinutes(value) {
 
 //#endregion
 //#region src/utils/ingredients.ts
-const DEFAULT_GROUP_NAME = "Ingredients";
+const DEFAULT_INGREDIENTS_GROUP_NAME = "Ingredients";
 const DEFAULT_GROUPING_SELECTORS = {
 	wprm: {
 		headingSelectors: [".wprm-recipe-ingredient-group h4", ".wprm-recipe-group-name"],
@@ -227,13 +228,13 @@ function groupIngredients($, ingredientsList, headingSelector, itemSelector) {
 		const $el = $(el);
 		if ($el.is(groupNameSelector)) {
 			const headingText = normalizeString($el.text());
-			currentHeading = headingText || DEFAULT_GROUP_NAME;
+			currentHeading = headingText || DEFAULT_INGREDIENTS_GROUP_NAME;
 			if (!groupings.has(currentHeading)) groupings.set(currentHeading, /* @__PURE__ */ new Set());
 		} else if ($el.is(ingredientSelector)) {
 			const text = normalizeString($el.text());
 			if (!text) continue;
 			const matched = bestMatch(text, ingredients);
-			const heading = currentHeading || DEFAULT_GROUP_NAME;
+			const heading = currentHeading || DEFAULT_INGREDIENTS_GROUP_NAME;
 			if (!groupings.has(heading)) groupings.set(heading, /* @__PURE__ */ new Set());
 			groupings.get(heading)?.add(matched);
 		}
@@ -652,7 +653,7 @@ var SchemaOrgPlugin = class SchemaOrgPlugin extends ExtractorPlugin {
 		"title",
 		"@id"
 	]) {
-		let text = void 0;
+		let text;
 		if (isString(value)) text = value;
 		else if (isNumber(value)) text = value.toString();
 		else if (Array.isArray(value)) text = this.getSchemaTextValue(value[0], props);
@@ -1076,6 +1077,127 @@ var AllRecipes = class extends AbstractScraper {
 	extractors = {};
 };
 
+//#endregion
+//#region src/scrapers/americastestkitchen.ts
+const recipeIngredientItemSchema = z.object({ fields: z.object({
+	qty: z.string(),
+	preText: z.string(),
+	postText: z.string(),
+	measurement: z.string().nullable(),
+	pluralIngredient: z.boolean(),
+	ingredient: z.object({
+		contentType: z.string(),
+		fields: z.object({
+			title: z.string(),
+			pluralTitle: z.string(),
+			kind: z.string()
+		})
+	})
+}) });
+const recipeIngredientGroupSchema = z.object({ fields: z.object({
+	title: z.string(),
+	recipeIngredientItems: z.array(recipeIngredientItemSchema)
+}) });
+const recipeInstructionSchema = z.object({ fields: z.object({ content: z.string() }) });
+const recipeDataSchema = z.object({
+	totalCookTime: z.number(),
+	recipeTimeNote: z.string().optional(),
+	ingredientGroups: z.array(recipeIngredientGroupSchema),
+	headnote: z.string().optional(),
+	instructions: z.array(recipeInstructionSchema)
+});
+const pagePropsDataSchema = z.object({ props: z.object({ pageProps: z.object({ data: recipeDataSchema }) }) });
+var AmericasTestKitchen = class extends AbstractScraper {
+	data = null;
+	static host() {
+		return "americastestkitchen.com";
+	}
+	extractors = {
+		ingredients: this.ingredients.bind(this),
+		instructions: this.instructions.bind(this),
+		siteName: this.siteName.bind(this)
+	};
+	siteName() {
+		return "America's Test Kitchen";
+	}
+	ingredients(prevValue) {
+		let ingredients = this.parseIngredients();
+		if (!ingredients) ingredients = this.parseHtmlIngredients(prevValue);
+		if (!ingredients) throw new Error("Failed to extract ingredients");
+		return ingredients;
+	}
+	instructions(prevValue) {
+		const data = this.getRecipeData();
+		if (!data) {
+			if (prevValue) return prevValue;
+			throw new Error("Failed to extract instructions");
+		}
+		const { headnote } = data;
+		let headnoteText = "";
+		if (headnote) headnoteText = `Note: ${normalizeString(headnote)}`;
+		const instructionTexts = [];
+		for (const instruction of data.instructions) instructionTexts.push(normalizeString(instruction.fields.content));
+		return new Set([headnoteText, ...instructionTexts]);
+	}
+	parseHtmlIngredients(prevValue) {
+		const headingSelector = "[class*=\"RecipeIngredientGroups_group\"] > span";
+		const ingredientSelector = "[class*=\"RecipeIngredient\"] label";
+		if (isList(prevValue) && prevValue.size > 0) {
+			const result = groupIngredients(this.$, prevValue, headingSelector, ingredientSelector);
+			return result;
+		}
+		return null;
+	}
+	getRecipeData() {
+		if (this.data === null) {
+			const jsonElement = this.$("script[type=\"application/json\"]");
+			const jsonString = jsonElement.html();
+			if (!jsonString) {
+				this.logger.warn("Could not find JSON data script tag");
+				return null;
+			}
+			try {
+				const parsed = pagePropsDataSchema.parse(JSON.parse(jsonString));
+				this.data = parsed.props.pageProps.data;
+			} catch (error) {
+				this.logger.error("Failed to parse JSON data:", error);
+				return null;
+			}
+		}
+		return this.data;
+	}
+	parseIngredientItem(ingredientItem) {
+		const { fields } = ingredientItem;
+		const fragments = [
+			fields.qty || "",
+			fields.measurement || "",
+			fields.ingredient.fields.title || "",
+			fields.postText || ""
+		];
+		const filteredFragments = [];
+		for (const fragment of fragments) if (fragment) filteredFragments.push(fragment.trimEnd());
+		return filteredFragments.join(" ").trimEnd().replace(" ,", ",");
+	}
+	parseIngredients() {
+		const data = this.getRecipeData();
+		if (!data) return null;
+		const { ingredientGroups } = data;
+		if (ingredientGroups.length === 1) {
+			const ingredientSet = /* @__PURE__ */ new Set();
+			for (const item of ingredientGroups[0].fields.recipeIngredientItems) ingredientSet.add(this.parseIngredientItem(item));
+			return ingredientSet;
+		}
+		const ingredientMap = /* @__PURE__ */ new Map();
+		for (const group of ingredientGroups) {
+			const groupTitle = group.fields.title || DEFAULT_INGREDIENTS_GROUP_NAME;
+			const ingredientSet = /* @__PURE__ */ new Set();
+			for (const item of group.fields.recipeIngredientItems) ingredientSet.add(this.parseIngredientItem(item));
+			ingredientMap.set(groupTitle, ingredientSet);
+		}
+		return ingredientMap;
+	}
+};
+
 //#endregion
 //#region src/scrapers/bbcgoodfood.ts
 var BBCGoodFood = class extends AbstractScraper {
@@ -1083,16 +1205,6 @@ var BBCGoodFood = class extends AbstractScraper {
 		return "bbcgoodfood.com";
 	}
 	extractors = { ingredients: this.ingredients.bind(this) };
-	/**
-	* The NYTimes website appears to auto generate it's CSS class names,
-	* which results in them ending with a string a random characters.
-	* Matching the exact class name is likely to break fairly quickly
-	* so instead we are going to match on a partial class name.
-	* For example, h3[class*='ingredientgroup_name'] matches an h3 element
-	* with a class that contains the value 'ingredient_groupname' at least once
-	* anywhere in the element class attribute.
-	* @link https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors
-	*/
 	ingredients(prevValue) {
 		const headingSelector = ".recipe__ingredients h3";
 		const ingredientSelector = ".recipe__ingredients li";
@@ -1104,6 +1216,15 @@ var BBCGoodFood = class extends AbstractScraper {
 	}
 };
 
+//#endregion
+//#region src/scrapers/eatingwell.ts
+var EatingWell = class extends AbstractScraper {
+	static host() {
+		return "eatingwell.com";
+	}
+	extractors = {};
+};
+
 //#endregion
 //#region src/scrapers/epicurious.ts
 var Epicurious = class extends AbstractScraper {
@@ -1124,16 +1245,6 @@ var NYTimes = class extends AbstractScraper {
 		return "cooking.nytimes.com";
 	}
 	extractors = { ingredients: this.ingredients.bind(this) };
-	/**
-	* The NYTimes website appears to auto generate it's CSS class names,
-	* which results in them ending with a string a random characters.
-	* Matching the exact class name is likely to break fairly quickly
-	* so instead we are going to match on a partial class name.
-	* For example, h3[class*='ingredientgroup_name'] matches an h3 element
-	* with a class that contains the value 'ingredient_groupname' at least once
-	* anywhere in the element class attribute.
-	* @link https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors
-	*/
 	ingredients(prevValue) {
 		const headingSelector = "h3[class*=\"ingredientgroup_name\"]";
 		const ingredientSelector = "li[class*=\"ingredient\"]";
@@ -1184,7 +1295,9 @@ var SimplyRecipes = class extends AbstractScraper {
 */
 const scrapers = {
 	[AllRecipes.host()]: AllRecipes,
+	[AmericasTestKitchen.host()]: AmericasTestKitchen,
 	[BBCGoodFood.host()]: BBCGoodFood,
+	[EatingWell.host()]: EatingWell,
 	[Epicurious.host()]: Epicurious,
 	[SeriousEats.host()]: SeriousEats,
 	[SimplyRecipes.host()]: SimplyRecipes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recipe-scrapers-js",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "license": "MIT",
   "description": "A recipe scrapers library",
   "author": {
@@ -12,11 +12,21 @@
     "url": "git+https://github.com/nerdstep/recipe-scrapers-js.git"
   },
   "type": "module",
-  "module": "src/index.ts",
+  "module": "dist/index.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist", "src", "README.md", "LICENSE"],
-  "keywords": ["recipe", "scraper", "parser", "food", "cooking"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "recipe",
+    "scraper",
+    "parser",
+    "food",
+    "cooking"
+  ],
   "scripts": {
     "build": "tsdown src/index.ts --outdir dist",
     "test": "bun test",
@@ -29,17 +39,18 @@
     "prepublishOnly": "bun run lint && bun run build"
   },
   "peerDependencies": {
-    "cheerio": "^1.0.0"
+    "cheerio": "^1.1.0",
+    "zod": "^3.25.74"
   },
   "dependencies": {
     "iso8601-duration": "^2.1.2",
     "schema-dts": "^1.1.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "@types/bun": "^1.2.15",
-    "cheerio": "^1.0.0",
-    "tsdown": "^0.12.7",
+    "@biomejs/biome": "^2.0.6",
+    "@types/bun": "^1.2.17",
+    "cheerio": "^1.1.0",
+    "tsdown": "^0.12.9",
     "typescript": "^5.8.3"
   }
 }

package/src/__tests__/abstract-extractor-plugin.test.ts

@@ -1,234 +0,0 @@
-import { beforeEach, describe, expect, it } from 'bun:test'
-import {
-  NotImplementedException,
-  UnsupportedFieldException,
-} from '@/exceptions'
-import { load } from 'cheerio'
-import { ExtractorPlugin } from '../abstract-extractor-plugin'
-import type { RecipeFields } from '../types/recipe.interface'
-
-class MockExtractorPlugin extends ExtractorPlugin {
-  name = 'MockExtractorPlugin'
-  priority = 100
-
-  private supportedFields: Set<keyof RecipeFields>
-
-  constructor(supportedFields: (keyof RecipeFields)[] = []) {
-    const $ = load('<html><body></body></html>')
-    super($)
-    this.supportedFields = new Set(supportedFields)
-  }
-
-  supports(field: keyof RecipeFields): boolean {
-    return this.supportedFields.has(field)
-  }
-
-  extract<Key extends keyof RecipeFields>(field: Key): RecipeFields[Key] {
-    if (!this.supports(field)) {
-      throw new UnsupportedFieldException(field)
-    }
-
-    // Mock extraction logic
-    switch (field) {
-      case 'title':
-        return 'Mock Recipe Title' as RecipeFields[Key]
-      case 'description':
-        return 'Mock Recipe Description' as RecipeFields[Key]
-      case 'ingredients':
-        return new Set(['ingredient 1', 'ingredient 2']) as RecipeFields[Key]
-      case 'instructions':
-        return new Set(['step 1', 'step 2']) as RecipeFields[Key]
-      case 'prepTime':
-        return 15 as RecipeFields[Key]
-      case 'cookTime':
-        return 30 as RecipeFields[Key]
-      case 'totalTime':
-        return 45 as RecipeFields[Key]
-      case 'yields':
-        return '4 servings' as RecipeFields[Key]
-      default:
-        throw new NotImplementedException(field)
-    }
-  }
-}
-
-class AsyncMockExtractorPlugin extends ExtractorPlugin {
-  name = 'AsyncMockExtractorPlugin'
-  priority = 100
-
-  constructor() {
-    const $ = load('<html><body></body></html>')
-    super($)
-  }
-
-  supports(field: keyof RecipeFields): boolean {
-    return ['title', 'description'].includes(field)
-  }
-
-  async extract<Key extends keyof RecipeFields>(
-    field: Key,
-  ): Promise<RecipeFields[Key]> {
-    await new Promise((resolve) => setTimeout(resolve, 10))
-
-    if (!this.supports(field)) {
-      throw new UnsupportedFieldException(field)
-    }
-
-    switch (field) {
-      case 'title':
-        return 'Async Recipe Title' as RecipeFields[Key]
-      case 'description':
-        return 'Async Recipe Description' as RecipeFields[Key]
-      default:
-        throw new NotImplementedException(field)
-    }
-  }
-}
-
-class ThrowingExtractorPlugin extends ExtractorPlugin {
-  name = 'ThrowingExtractorPlugin'
-  priority = 100
-
-  constructor() {
-    const $ = load('<html><body></body></html>')
-    super($)
-  }
-
-  supports(field: keyof RecipeFields): boolean {
-    return true
-  }
-
-  extract<Key extends keyof RecipeFields>(field: Key): RecipeFields[Key] {
-    throw new Error(`Extraction failed for field: ${String(field)}`)
-  }
-}
-
-describe('ExtractorPlugin', () => {
-  let plugin: MockExtractorPlugin
-
-  beforeEach(() => {
-    plugin = new MockExtractorPlugin([
-      'title',
-      'description',
-      'ingredients',
-      'prepTime',
-    ])
-  })
-
-  describe('inheritance', () => {
-    it('should extend AbstractPlugin', () => {
-      expect(plugin).toBeInstanceOf(ExtractorPlugin)
-    })
-
-    it('should have access to cheerio instance from parent', () => {
-      expect(plugin.$).toBeDefined()
-      expect(typeof plugin.$).toBe('function')
-    })
-  })
-
-  describe('supports method', () => {
-    it('should return true for supported fields', () => {
-      expect(plugin.supports('title')).toBe(true)
-      expect(plugin.supports('description')).toBe(true)
-      expect(plugin.supports('ingredients')).toBe(true)
-      expect(plugin.supports('prepTime')).toBe(true)
-    })
-
-    it('should return false for unsupported fields', () => {
-      expect(plugin.supports('cookTime')).toBe(false)
-      expect(plugin.supports('totalTime')).toBe(false)
-      expect(plugin.supports('yields')).toBe(false)
-      expect(plugin.supports('author')).toBe(false)
-    })
-
-    it('should handle empty supported fields', () => {
-      const emptyPlugin = new MockExtractorPlugin([])
-      expect(emptyPlugin.supports('title')).toBe(false)
-      expect(emptyPlugin.supports('description')).toBe(false)
-    })
-
-    it('should handle all fields as supported', () => {
-      const allFieldsPlugin = new MockExtractorPlugin([
-        'title',
-        'description',
-        'ingredients',
-        'instructions',
-        'prepTime',
-        'cookTime',
-        'totalTime',
-        'yields',
-      ])
-
-      expect(allFieldsPlugin.supports('title')).toBe(true)
-      expect(allFieldsPlugin.supports('cookTime')).toBe(true)
-      expect(allFieldsPlugin.supports('yields')).toBe(true)
-    })
-  })
-
-  describe('extract method', () => {
-    it('should extract supported fields', () => {
-      expect(plugin.extract('title')).toBe('Mock Recipe Title')
-      expect(plugin.extract('description')).toBe('Mock Recipe Description')
-      expect(plugin.extract('prepTime')).toBe(15)
-      expect(plugin.extract('ingredients')).toEqual(
-        new Set(['ingredient 1', 'ingredient 2']),
-      )
-    })
-
-    it('should throw error for unsupported fields', () => {
-      expect(() => plugin.extract('cookTime')).toThrow(
-        'Extraction not supported for field: cookTime',
-      )
-      expect(() => plugin.extract('totalTime')).toThrow(
-        'Extraction not supported for field: totalTime',
-      )
-    })
-  })
-
-  describe('async extraction', () => {
-    let asyncPlugin: AsyncMockExtractorPlugin
-
-    beforeEach(() => {
-      asyncPlugin = new AsyncMockExtractorPlugin()
-    })
-
-    it('should handle async extraction', async () => {
-      const title = await asyncPlugin.extract('title')
-      expect(title).toBe('Async Recipe Title')
-      const description = await asyncPlugin.extract('description')
-      expect(description).toBe('Async Recipe Description')
-    })
-
-    it('should throw error for unsupported fields in async mode', async () => {
-      await expect(asyncPlugin.extract('cookTime')).rejects.toThrow(
-        'Extraction not supported for field: cookTime',
-      )
-    })
-  })
-
-  describe('error handling', () => {
-    let throwingPlugin: ThrowingExtractorPlugin
-
-    beforeEach(() => {
-      throwingPlugin = new ThrowingExtractorPlugin()
-    })
-
-    it('should propagate extraction errors', () => {
-      expect(() => throwingPlugin.extract('title')).toThrow(
-        'Extraction failed for field: title',
-      )
-      expect(() => throwingPlugin.extract('description')).toThrow(
-        'Extraction failed for field: description',
-      )
-    })
-  })
-
-  describe('edge cases', () => {
-    it('should throw on undefined extractor', () => {
-      const plugin = new MockExtractorPlugin(['author'])
-      expect(() => plugin.extract('author')).toThrow(
-        'Method should be implemented: author',
-      )
-    })
-  })
-})