recipe-scrapers-js 1.0.0-rc.1 → 1.0.0-rc.3

package/CHANGELOG.md

@@ -6,26 +6,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0-rc.3] - 2025-12-21
+
+### Changed
+
+- Enforce positive integer values for recipe time fields (`totalTime`, `cookTime`, `prepTime`)
+- Rename schema helper `zPositiveNumber` to `zPositiveInteger`
+- Stop defaulting nullable schema fields to `null`
+
+## [1.0.0-rc.2] - 2025-12-20
+
+### Added
+
+- Add `schemaVersion` to recipe schema
+
+### Changed
+
+- Make `links` optional; it stays `undefined` unless link parsing is enabled
+- Extract schema transform/refinement validations into `applyRecipeValidations`
+
 ## [1.0.0-rc.1] - 2025-12-20
 
 ### Added
 
-- chore: tsdown configuration file
+- Add `tsdown` configuration file
 
 ### Fixed
 
-- fix: main/module/type entriess in package.json; add exports field
+- Fix `main`/`module`/`types` entries in `package.json`; add `exports`
 
 ## [1.0.0-rc.0] - 2025-12-20
 
 ### Added
 
 - Optional ingredient parsing via [parse-ingredient](https://github.com/jakeboone02/parse-ingredient)
-- `parse()` and `safeParse()` methods for Zod schema validated recipe extraction
+- `parse()` and `safeParse()` methods for Zod-validated recipe extraction
 
 ### Changed
 
-- **BREAKING**: Renamed `toObject()` method to `toRecipeObject()` for clarity
+- **BREAKING**: Rename `toObject()` method to `toRecipeObject()` for clarity
 - **BREAKING**: Ingredients and instructions now require grouped structures (each group has `name` and `items`) instead of flat arrays
 
 ---

package/dist/index.d.mts

@@ -3,7 +3,45 @@ import { CheerioAPI } from "cheerio";
 import z$1, { z } from "zod";
 import { ParseIngredientOptions } from "parse-ingredient";
 
+//#region src/logger.d.ts
+declare enum LogLevel {
+  VERBOSE = 0,
+  DEBUG = 1,
+  INFO = 2,
+  WARN = 3,
+  ERROR = 4,
+}
+declare class Logger {
+  private context;
+  private logLevel;
+  constructor(context: string, logLevel?: LogLevel);
+  verbose(...args: unknown[]): void;
+  debug(...args: unknown[]): void;
+  log(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+//#endregion
+//#region src/abstract-plugin.d.ts
+declare abstract class AbstractPlugin {
+  readonly $: CheerioAPI;
+  /** The name of the plugin */
+  abstract name: string;
+  /** The priority of the plugin */
+  abstract priority: number;
+  constructor($: CheerioAPI);
+}
+//#endregion
 //#region src/schemas/recipe.schema.d.ts
+/**
+ * Current schema version for recipe objects.
+ * Increment this when making breaking changes to the schema.
+ *
+ * Version history:
+ * - 1.0.0: Initial schema version
+ */
+declare const RECIPE_SCHEMA_VERSION: "1.0.0";
 /**
  * Schema for a parsed ingredient from the parse-ingredient library.
  * This represents the structured data extracted from an ingredient string.
@@ -35,7 +73,7 @@ declare const IngredientItemSchema: z.ZodObject<{
  * Schema for a group of ingredients
  */
 declare const IngredientGroupSchema: z.ZodObject<{
-  name: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+  name: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
   items: z.ZodArray<z.core.$ZodType<{
     value: string;
     parsed?: {
@@ -63,7 +101,7 @@ declare const IngredientGroupSchema: z.ZodObject<{
  * Must have at least one group with at least one ingredient
  */
 declare const IngredientsSchema: z.ZodArray<z.ZodObject<{
-  name: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+  name: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
   items: z.ZodArray<z.core.$ZodType<{
     value: string;
     parsed?: {
@@ -96,7 +134,7 @@ declare const InstructionItemSchema: z.ZodObject<{
  * Schema for a group of instruction steps
  */
 declare const InstructionGroupSchema: z.ZodObject<{
-  name: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+  name: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
   items: z.ZodArray<z.core.$ZodType<{
     value: string;
   }, unknown, z.core.$ZodTypeInternals<{
@@ -108,7 +146,7 @@ declare const InstructionGroupSchema: z.ZodObject<{
  * Must have at least one group with at least one step
  */
 declare const InstructionsSchema: z.ZodArray<z.ZodObject<{
-  name: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+  name: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
   items: z.ZodArray<z.core.$ZodType<{
     value: string;
   }, unknown, z.core.$ZodTypeInternals<{
@@ -123,15 +161,28 @@ declare const LinkSchema: z.ZodObject<{
   text: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
 }, z.core.$strip>;
 /**
- * Base RecipeObject schema without cross-field validations
- * Used as the foundation for both strict and lenient schemas
+ * Base RecipeObject schema without cross-field validations.
+ * Use this schema when you need to extend the recipe object with custom fields.
+ *
+ * @example
+ * ```ts
+ * import { RecipeObjectBaseSchema, applyRecipeValidations } from 'recipe-scrapers-js'
+ *
+ * const MyCustomRecipeSchema = RecipeObjectBaseSchema.extend({
+ *   customField: z.string(),
+ * })
+ *
+ * // Apply the standard recipe validations
+ * const MyValidatedRecipeSchema = applyRecipeValidations(MyCustomRecipeSchema)
+ * ```
  */
 declare const RecipeObjectBaseSchema: z.ZodObject<{
+  schemaVersion: z.ZodDefault<z.ZodLiteral<"1.0.0">>;
   host: z.ZodCustomStringFormat<"hostname">;
   title: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
   author: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
   ingredients: z.ZodArray<z.ZodObject<{
-    name: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+    name: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
     items: z.ZodArray<z.core.$ZodType<{
       value: string;
       parsed?: {
@@ -155,7 +206,7 @@ declare const RecipeObjectBaseSchema: z.ZodObject<{
     }, unknown>>>;
   }, z.core.$strip>>;
   instructions: z.ZodArray<z.ZodObject<{
-    name: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+    name: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
     items: z.ZodArray<z.core.$ZodType<{
       value: string;
     }, unknown, z.core.$ZodTypeInternals<{
@@ -164,22 +215,22 @@ declare const RecipeObjectBaseSchema: z.ZodObject<{
   }, z.core.$strip>>;
   canonicalUrl: z.ZodURL;
   image: z.ZodURL;
-  totalTime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
-  cookTime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
-  prepTime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+  totalTime: z.ZodNullable<z.ZodInt>;
+  cookTime: z.ZodNullable<z.ZodInt>;
+  prepTime: z.ZodNullable<z.ZodInt>;
   ratings: z.ZodDefault<z.ZodNumber>;
   ratingsCount: z.ZodDefault<z.ZodInt>;
   yields: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
   description: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
   language: z.ZodDefault<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  siteName: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  cookingMethod: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+  siteName: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+  cookingMethod: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
   category: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
   cuisine: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
   keywords: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
   dietaryRestrictions: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
   equipment: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  links: z.ZodDefault<z.ZodArray<z.ZodObject<{
+  links: z.ZodOptional<z.ZodArray<z.ZodObject<{
     href: z.ZodURL;
     text: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
   }, z.core.$strip>>>;
@@ -187,15 +238,38 @@ declare const RecipeObjectBaseSchema: z.ZodObject<{
   reviews: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
 /**
- * Strict RecipeObject schema with all validations enforced
+ * Applies recipe-specific transformations and validations to a schema.
+ * Use this when extending RecipeObjectBaseSchema with custom fields.
+ *
+ * @param schema - A Zod object schema that includes
+ * all RecipeObjectBaseSchema fields
+ * @returns A schema with transforms and field validations applied
+ *
+ * @example
+ * ```ts
+ * const CustomSchema = RecipeObjectBaseSchema.extend({
+ *   tags: z.array(z.string()),
+ * })
+ *
+ * const ValidatedCustomSchema = applyRecipeValidations(CustomSchema)
+ * ```
  */
-declare const RecipeObjectSchema: z.ZodPipe<z.ZodObject<{
-  host: z.ZodCustomStringFormat<"hostname">;
-  title: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
-  author: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
-  ingredients: z.ZodArray<z.ZodObject<{
-    name: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-    items: z.ZodArray<z.core.$ZodType<{
+declare function applyRecipeValidations<T extends z.infer<typeof RecipeObjectBaseSchema>>(schema: z.ZodType<T>): z.ZodPipe<z.ZodType<T, unknown, z.core.$ZodTypeInternals<T, unknown>>, z.ZodTransform<Awaited<T>, T>>;
+/**
+ * Strict RecipeObject schema with all validations enforced.
+ * This is the standard schema used by recipe scrapers.
+ *
+ * For custom extensions, use RecipeObjectBaseSchema.extend() and then
+ * apply validations with applyRecipeValidations().
+ */
+declare const RecipeObjectSchema: z.ZodPipe<z.ZodType<{
+  schemaVersion: "1.0.0";
+  host: string;
+  title: string;
+  author: string;
+  ingredients: {
+    name: string | null;
+    items: {
       value: string;
       parsed?: {
         quantity: number | null;
@@ -205,7 +279,45 @@ declare const RecipeObjectSchema: z.ZodPipe<z.ZodObject<{
         description: string;
         isGroupHeader: boolean;
       } | undefined;
-    }, unknown, z.core.$ZodTypeInternals<{
+    }[];
+  }[];
+  instructions: {
+    name: string | null;
+    items: {
+      value: string;
+    }[];
+  }[];
+  canonicalUrl: string;
+  image: string;
+  totalTime: number | null;
+  cookTime: number | null;
+  prepTime: number | null;
+  ratings: number;
+  ratingsCount: number;
+  yields: string;
+  description: string;
+  language: string;
+  siteName: string | null;
+  cookingMethod: string | null;
+  category: string[];
+  cuisine: string[];
+  keywords: string[];
+  dietaryRestrictions: string[];
+  equipment: string[];
+  nutrients: Record<string, string>;
+  reviews: Record<string, string>;
+  links?: {
+    href: string;
+    text: string;
+  }[] | undefined;
+}, unknown, z.core.$ZodTypeInternals<{
+  schemaVersion: "1.0.0";
+  host: string;
+  title: string;
+  author: string;
+  ingredients: {
+    name: string | null;
+    items: {
       value: string;
       parsed?: {
         quantity: number | null;
@@ -215,40 +327,39 @@ declare const RecipeObjectSchema: z.ZodPipe<z.ZodObject<{
         description: string;
         isGroupHeader: boolean;
       } | undefined;
-    }, unknown>>>;
-  }, z.core.$strip>>;
-  instructions: z.ZodArray<z.ZodObject<{
-    name: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-    items: z.ZodArray<z.core.$ZodType<{
-      value: string;
-    }, unknown, z.core.$ZodTypeInternals<{
+    }[];
+  }[];
+  instructions: {
+    name: string | null;
+    items: {
       value: string;
-    }, unknown>>>;
-  }, z.core.$strip>>;
-  canonicalUrl: z.ZodURL;
-  image: z.ZodURL;
-  totalTime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
-  cookTime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
-  prepTime: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
-  ratings: z.ZodDefault<z.ZodNumber>;
-  ratingsCount: z.ZodDefault<z.ZodInt>;
-  yields: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
-  description: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
-  language: z.ZodDefault<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  siteName: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  cookingMethod: z.ZodDefault<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  category: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  cuisine: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  keywords: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  dietaryRestrictions: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  equipment: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
-  links: z.ZodDefault<z.ZodArray<z.ZodObject<{
-    href: z.ZodURL;
-    text: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
-  }, z.core.$strip>>>;
-  nutrients: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
-  reviews: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
-}, z.core.$strip>, z.ZodTransform<{
+    }[];
+  }[];
+  canonicalUrl: string;
+  image: string;
+  totalTime: number | null;
+  cookTime: number | null;
+  prepTime: number | null;
+  ratings: number;
+  ratingsCount: number;
+  yields: string;
+  description: string;
+  language: string;
+  siteName: string | null;
+  cookingMethod: string | null;
+  category: string[];
+  cuisine: string[];
+  keywords: string[];
+  dietaryRestrictions: string[];
+  equipment: string[];
+  nutrients: Record<string, string>;
+  reviews: Record<string, string>;
+  links?: {
+    href: string;
+    text: string;
+  }[] | undefined;
+}, unknown>>, z.ZodTransform<{
+  schemaVersion: "1.0.0";
   host: string;
   title: string;
   author: string;
@@ -289,13 +400,14 @@ declare const RecipeObjectSchema: z.ZodPipe<z.ZodObject<{
   keywords: string[];
   dietaryRestrictions: string[];
   equipment: string[];
-  links: {
-    href: string;
-    text: string;
-  }[];
   nutrients: Record<string, string>;
   reviews: Record<string, string>;
+  links?: {
+    href: string;
+    text: string;
+  }[] | undefined;
 }, {
+  schemaVersion: "1.0.0";
   host: string;
   title: string;
   author: string;
@@ -336,44 +448,13 @@ declare const RecipeObjectSchema: z.ZodPipe<z.ZodObject<{
   keywords: string[];
   dietaryRestrictions: string[];
   equipment: string[];
-  links: {
-    href: string;
-    text: string;
-  }[];
   nutrients: Record<string, string>;
   reviews: Record<string, string>;
+  links?: {
+    href: string;
+    text: string;
+  }[] | undefined;
 }>>;
-type RecipeObjectValidated = z.infer<typeof RecipeObjectSchema>;
-//#endregion
-//#region src/logger.d.ts
-declare enum LogLevel {
-  VERBOSE = 0,
-  DEBUG = 1,
-  INFO = 2,
-  WARN = 3,
-  ERROR = 4,
-}
-declare class Logger {
-  private context;
-  private logLevel;
-  constructor(context: string, logLevel?: LogLevel);
-  verbose(...args: unknown[]): void;
-  debug(...args: unknown[]): void;
-  log(...args: unknown[]): void;
-  info(...args: unknown[]): void;
-  warn(...args: unknown[]): void;
-  error(...args: unknown[]): void;
-}
-//#endregion
-//#region src/abstract-plugin.d.ts
-declare abstract class AbstractPlugin {
-  readonly $: CheerioAPI;
-  /** The name of the plugin */
-  abstract name: string;
-  /** The priority of the plugin */
-  abstract priority: number;
-  constructor($: CheerioAPI);
-}
 //#endregion
 //#region src/types/recipe.interface.d.ts
 type List = Set<string>;
@@ -405,6 +486,10 @@ type InstructionGroup = z.infer<typeof InstructionGroupSchema>;
  * All recipe instructions as an array of groups
  */
 type Instructions = InstructionGroup[];
+/**
+ * The complete recipe object
+ */
+type RecipeObject = z.infer<typeof RecipeObjectSchema>;
 /**
  * A link with href and display text
  */
@@ -461,8 +546,9 @@ interface RecipeData {
   /**
    * An list of all links found in the page HTML defined within an anchor
    * `<a>` element.
+   * Only present when `linksEnabled` option is set to `true`.
    */
-  links: Link[];
+  links?: Link[];
   /**
    * A description of the recipe. This is normally a sentence or short
    * paragraph describing the recipe. Often the website defines the
@@ -613,20 +699,7 @@ type RecipeFields = Omit<RecipeData, 'host'>;
 /**
  * The fields that aren't required for a recipe to be valid.
  */
-type OptionalRecipeFields = Pick<RecipeFields, 'siteName' | 'category' | 'cookTime' | 'prepTime' | 'totalTime' | 'cuisine' | 'cookingMethod' | 'ratings' | 'ratingsCount' | 'equipment' | 'reviews' | 'nutrients' | 'dietaryRestrictions' | 'keywords'>;
-/**
- * The validated recipe object output from the schema.
- * This represents a recipe that has passed all validation rules.
- */
-interface RecipeObject extends Omit<RecipeData, 'category' | 'cuisine' | 'dietaryRestrictions' | 'equipment' | 'keywords' | 'nutrients' | 'reviews'> {
-  category: string[];
-  cuisine: string[];
-  dietaryRestrictions: string[];
-  equipment: string[];
-  keywords: string[];
-  nutrients: Record<string, string>;
-  reviews: Record<string, string>;
-}
+type OptionalRecipeFields = Pick<RecipeFields, 'siteName' | 'category' | 'cookTime' | 'prepTime' | 'totalTime' | 'cuisine' | 'cookingMethod' | 'ratings' | 'ratingsCount' | 'equipment' | 'reviews' | 'nutrients' | 'dietaryRestrictions' | 'keywords' | 'links'>;
 //#endregion
 //#region src/abstract-extractor-plugin.d.ts
 declare abstract class ExtractorPlugin extends AbstractPlugin {
@@ -764,19 +837,21 @@ declare abstract class AbstractScraper {
   scrape(): Promise<RecipeData>;
   /**
    * Converts the scraper's data into a JSON-serializable object.
+   * Note: schemaVersion is added during validation by parse() or safeParse().
    */
-  toRecipeObject(): Promise<RecipeObject>;
+  toRecipeObject(): Promise<Omit<RecipeObject, 'schemaVersion'>>;
   /**
    * Get the Zod schema to use for validation.
    * Subclasses can override to provide custom schemas.
    */
-  protected getSchema(): z$1.ZodPipe<z$1.ZodObject<{
-    host: z$1.ZodCustomStringFormat<"hostname">;
-    title: z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>;
-    author: z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>;
-    ingredients: z$1.ZodArray<z$1.ZodObject<{
-      name: z$1.ZodDefault<z$1.ZodNullable<z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>>>;
-      items: z$1.ZodArray<z$1.core.$ZodType<{
+  protected getSchema(): z$1.ZodPipe<z$1.ZodType<{
+    schemaVersion: "1.0.0";
+    host: string;
+    title: string;
+    author: string;
+    ingredients: {
+      name: string | null;
+      items: {
         value: string;
         parsed?: {
           quantity: number | null;
@@ -786,7 +861,45 @@ declare abstract class AbstractScraper {
           description: string;
           isGroupHeader: boolean;
         } | undefined;
-      }, unknown, z$1.core.$ZodTypeInternals<{
+      }[];
+    }[];
+    instructions: {
+      name: string | null;
+      items: {
+        value: string;
+      }[];
+    }[];
+    canonicalUrl: string;
+    image: string;
+    totalTime: number | null;
+    cookTime: number | null;
+    prepTime: number | null;
+    ratings: number;
+    ratingsCount: number;
+    yields: string;
+    description: string;
+    language: string;
+    siteName: string | null;
+    cookingMethod: string | null;
+    category: string[];
+    cuisine: string[];
+    keywords: string[];
+    dietaryRestrictions: string[];
+    equipment: string[];
+    nutrients: Record<string, string>;
+    reviews: Record<string, string>;
+    links?: {
+      href: string;
+      text: string;
+    }[] | undefined;
+  }, unknown, z$1.core.$ZodTypeInternals<{
+    schemaVersion: "1.0.0";
+    host: string;
+    title: string;
+    author: string;
+    ingredients: {
+      name: string | null;
+      items: {
         value: string;
         parsed?: {
           quantity: number | null;
@@ -796,40 +909,39 @@ declare abstract class AbstractScraper {
           description: string;
           isGroupHeader: boolean;
         } | undefined;
-      }, unknown>>>;
-    }, z$1.core.$strip>>;
-    instructions: z$1.ZodArray<z$1.ZodObject<{
-      name: z$1.ZodDefault<z$1.ZodNullable<z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>>>;
-      items: z$1.ZodArray<z$1.core.$ZodType<{
-        value: string;
-      }, unknown, z$1.core.$ZodTypeInternals<{
+      }[];
+    }[];
+    instructions: {
+      name: string | null;
+      items: {
         value: string;
-      }, unknown>>>;
-    }, z$1.core.$strip>>;
-    canonicalUrl: z$1.ZodURL;
-    image: z$1.ZodURL;
-    totalTime: z$1.ZodDefault<z$1.ZodNullable<z$1.ZodNumber>>;
-    cookTime: z$1.ZodDefault<z$1.ZodNullable<z$1.ZodNumber>>;
-    prepTime: z$1.ZodDefault<z$1.ZodNullable<z$1.ZodNumber>>;
-    ratings: z$1.ZodDefault<z$1.ZodNumber>;
-    ratingsCount: z$1.ZodDefault<z$1.ZodInt>;
-    yields: z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>;
-    description: z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>;
-    language: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>>>;
-    siteName: z$1.ZodDefault<z$1.ZodNullable<z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>>>;
-    cookingMethod: z$1.ZodDefault<z$1.ZodNullable<z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>>>;
-    category: z$1.ZodDefault<z$1.ZodArray<z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>>>;
-    cuisine: z$1.ZodDefault<z$1.ZodArray<z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>>>;
-    keywords: z$1.ZodDefault<z$1.ZodArray<z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>>>;
-    dietaryRestrictions: z$1.ZodDefault<z$1.ZodArray<z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>>>;
-    equipment: z$1.ZodDefault<z$1.ZodArray<z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>>>;
-    links: z$1.ZodDefault<z$1.ZodArray<z$1.ZodObject<{
-      href: z$1.ZodURL;
-      text: z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<string, string>>;
-    }, z$1.core.$strip>>>;
-    nutrients: z$1.ZodDefault<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
-    reviews: z$1.ZodDefault<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
-  }, z$1.core.$strip>, z$1.ZodTransform<{
+      }[];
+    }[];
+    canonicalUrl: string;
+    image: string;
+    totalTime: number | null;
+    cookTime: number | null;
+    prepTime: number | null;
+    ratings: number;
+    ratingsCount: number;
+    yields: string;
+    description: string;
+    language: string;
+    siteName: string | null;
+    cookingMethod: string | null;
+    category: string[];
+    cuisine: string[];
+    keywords: string[];
+    dietaryRestrictions: string[];
+    equipment: string[];
+    nutrients: Record<string, string>;
+    reviews: Record<string, string>;
+    links?: {
+      href: string;
+      text: string;
+    }[] | undefined;
+  }, unknown>>, z$1.ZodTransform<{
+    schemaVersion: "1.0.0";
     host: string;
     title: string;
     author: string;
@@ -870,13 +982,14 @@ declare abstract class AbstractScraper {
     keywords: string[];
     dietaryRestrictions: string[];
     equipment: string[];
-    links: {
-      href: string;
-      text: string;
-    }[];
     nutrients: Record<string, string>;
     reviews: Record<string, string>;
+    links?: {
+      href: string;
+      text: string;
+    }[] | undefined;
   }, {
+    schemaVersion: "1.0.0";
     host: string;
     title: string;
     author: string;
@@ -917,12 +1030,12 @@ declare abstract class AbstractScraper {
     keywords: string[];
     dietaryRestrictions: string[];
     equipment: string[];
-    links: {
-      href: string;
-      text: string;
-    }[];
     nutrients: Record<string, string>;
     reviews: Record<string, string>;
+    links?: {
+      href: string;
+      text: string;
+    }[] | undefined;
   }>>;
   /**
    * Extract and validate recipe data.
@@ -931,14 +1044,14 @@ declare abstract class AbstractScraper {
    * @returns Validated recipe object
    * @throws {ZodError} If validation fails
    */
-  parse(): Promise<RecipeObjectValidated>;
+  parse(): Promise<RecipeObject>;
   /**
    * Extract and validate recipe data without throwing.
    * Returns a result object indicating success or failure.
    *
    * @returns Result object with either data or error
    */
-  safeParse(): Promise<z$1.ZodSafeParseResult<RecipeObjectValidated>>;
+  safeParse(): Promise<z$1.ZodSafeParseResult<RecipeObject>>;
 }
 //#endregion
 //#region src/scrapers/allrecipes.d.ts
@@ -961,4 +1074,4 @@ declare const scrapers: {
  */
 declare function getScraper(url: string): typeof AllRecipes;
 //#endregion
-export { ExtractorPlugin, IngredientGroup, IngredientGroupSchema, IngredientItem, IngredientItemSchema, Ingredients, IngredientsSchema, InstructionGroup, InstructionGroupSchema, InstructionItem, InstructionItemSchema, Instructions, InstructionsSchema, Link, LinkSchema, List, LogLevel, Logger, OptionalRecipeFields, ParsedIngredient, ParsedIngredientSchema, PostProcessorPlugin, RecipeData, RecipeFields, RecipeObject, RecipeObjectBaseSchema, RecipeObjectSchema, RecipeObjectValidated, ScraperOptions, getScraper, scrapers };
+export { ExtractorPlugin, IngredientGroup, IngredientGroupSchema, IngredientItem, IngredientItemSchema, Ingredients, IngredientsSchema, InstructionGroup, InstructionGroupSchema, InstructionItem, InstructionItemSchema, Instructions, InstructionsSchema, Link, LinkSchema, List, LogLevel, Logger, OptionalRecipeFields, ParsedIngredient, ParsedIngredientSchema, PostProcessorPlugin, RECIPE_SCHEMA_VERSION, RecipeData, RecipeFields, RecipeObject, RecipeObjectBaseSchema, RecipeObjectSchema, ScraperOptions, applyRecipeValidations, getScraper, scrapers };

package/dist/index.mjs

@@ -48,14 +48,22 @@ const zString = (fieldName, { min = 1, max = 0 } = {}) => z.string(`${fieldName}
 */
 const zHttpUrl = (fieldName) => z.httpUrl(`${fieldName} must be a valid URL`);
 /**
-* Helper to create a positive number field
+* Helper to create a positive integer field
 */
-const zPositiveNumber = (fieldName) => z.number(`${fieldName} must be a number`).positive(`${fieldName} must be positive`).nullable().default(null);
+const zPositiveInteger = (fieldName) => z.int(`${fieldName} must be an integer`).positive(`${fieldName} must be positive`).nullable();
 const zNonEmptyArray = (schema, fieldName) => z.array(schema, `${fieldName} items must be an array`).min(1, `${fieldName} group must have at least one item`);
 
 //#endregion
 //#region src/schemas/recipe.schema.ts
 /**
+* Current schema version for recipe objects.
+* Increment this when making breaking changes to the schema.
+*
+* Version history:
+* - 1.0.0: Initial schema version
+*/
+const RECIPE_SCHEMA_VERSION = "1.0.0";
+/**
 * Schema for a parsed ingredient from the parse-ingredient library.
 * This represents the structured data extracted from an ingredient string.
 * @see https://github.com/jakeboone02/parse-ingredient
@@ -79,7 +87,7 @@ const IngredientItemSchema = z.object({
 * Schema for a group of ingredients
 */
 const IngredientGroupSchema = z.object({
-	name: zString("Ingredient group name").nullable().default(null),
+	name: zString("Ingredient group name").nullable(),
 	items: zNonEmptyArray(IngredientItemSchema, "Ingredient")
 });
 /**
@@ -95,7 +103,7 @@ const InstructionItemSchema = z.object({ value: zString("Instruction value") });
 * Schema for a group of instruction steps
 */
 const InstructionGroupSchema = z.object({
-	name: zString("Instruction group name").nullable().default(null),
+	name: zString("Instruction group name").nullable(),
 	items: zNonEmptyArray(InstructionItemSchema, "Instruction")
 });
 /**
@@ -111,10 +119,23 @@ const LinkSchema = z.object({
 	text: zString("Link text")
 });
 /**
-* Base RecipeObject schema without cross-field validations
-* Used as the foundation for both strict and lenient schemas
+* Base RecipeObject schema without cross-field validations.
+* Use this schema when you need to extend the recipe object with custom fields.
+*
+* @example
+* ```ts
+* import { RecipeObjectBaseSchema, applyRecipeValidations } from 'recipe-scrapers-js'
+*
+* const MyCustomRecipeSchema = RecipeObjectBaseSchema.extend({
+*   customField: z.string(),
+* })
+*
+* // Apply the standard recipe validations
+* const MyValidatedRecipeSchema = applyRecipeValidations(MyCustomRecipeSchema)
+* ```
 */
 const RecipeObjectBaseSchema = z.object({
+	schemaVersion: z.literal(RECIPE_SCHEMA_VERSION).default(RECIPE_SCHEMA_VERSION).describe("Schema version for recipe data migrations"),
 	host: z.hostname("Host must be a valid hostname"),
 	title: zString("Title", { max: 500 }),
 	author: zString("Author", { max: 255 }),
@@ -122,42 +143,67 @@ const RecipeObjectBaseSchema = z.object({
 	instructions: InstructionsSchema,
 	canonicalUrl: zHttpUrl("Canonical URL"),
 	image: zHttpUrl("Image"),
-	totalTime: zPositiveNumber("Total time"),
-	cookTime: zPositiveNumber("Cook time"),
-	prepTime: zPositiveNumber("Prep time"),
+	totalTime: zPositiveInteger("Total time"),
+	cookTime: zPositiveInteger("Cook time"),
+	prepTime: zPositiveInteger("Prep time"),
 	ratings: z.number("Ratings must be a number").min(0, "Ratings must be at least 0").max(5, "Ratings must be at most 5").default(0),
 	ratingsCount: z.int("Ratings count must be an integer").nonnegative("Ratings count must be non-negative").default(0),
 	yields: zString("Yields"),
 	description: zString("Description"),
 	language: zString("Language", { min: 2 }).optional().default("en"),
-	siteName: zString("Site name").nullable().default(null),
-	cookingMethod: zString("Cooking method").nullable().default(null),
+	siteName: zString("Site name").nullable(),
+	cookingMethod: zString("Cooking method").nullable(),
 	category: z.array(zString("Category item"), "Category must be an array").default([]),
 	cuisine: z.array(zString("Cuisine item"), "Cuisine must be an array").default([]),
 	keywords: z.array(zString("Keyword item"), "Keywords must be an array").default([]),
 	dietaryRestrictions: z.array(zString("Dietary restriction item"), "Dietary restrictions must be an array").default([]),
 	equipment: z.array(zString("Equipment item"), "Equipment must be an array").default([]),
-	links: z.array(LinkSchema, "Links must be an array").default([]),
+	links: z.array(LinkSchema, "Links must be an array").optional(),
 	nutrients: z.record(z.string(), z.string(), "Nutrients must be an object").default({}),
 	reviews: z.record(z.string(), z.string(), "Reviews must be an object").default({})
 });
 /**
-* Strict RecipeObject schema with all validations enforced
+* Applies recipe-specific transformations and validations to a schema.
+* Use this when extending RecipeObjectBaseSchema with custom fields.
+*
+* @param schema - A Zod object schema that includes
+* all RecipeObjectBaseSchema fields
+* @returns A schema with transforms and field validations applied
+*
+* @example
+* ```ts
+* const CustomSchema = RecipeObjectBaseSchema.extend({
+*   tags: z.array(z.string()),
+* })
+*
+* const ValidatedCustomSchema = applyRecipeValidations(CustomSchema)
+* ```
 */
-const RecipeObjectSchema = RecipeObjectBaseSchema.transform((data) => {
-	if (!data.totalTime && !isNull(data.cookTime) && !isNull(data.prepTime)) data.totalTime = data.cookTime + data.prepTime;
-	return data;
-}).refine((data) => {
-	const { totalTime, cookTime, prepTime } = data;
-	if (!isNull(totalTime) && !isNull(cookTime) && !isNull(prepTime)) return totalTime >= cookTime + prepTime;
-	return true;
-}, {
-	message: "Total time should be at least the sum of cook time and prep time",
-	path: ["totalTime"]
-}).refine((data) => data.ratings === 0 || data.ratingsCount > 0, {
-	message: "Ratings count should be greater than 0 when ratings exist",
-	path: ["ratingsCount"]
-});
+function applyRecipeValidations(schema) {
+	return schema.transform((data) => {
+		if (!data.totalTime && !isNull(data.cookTime) && !isNull(data.prepTime)) data.totalTime = data.cookTime + data.prepTime;
+		return data;
+	}).refine(({ totalTime, cookTime, prepTime }) => {
+		if (!isNull(totalTime) && !isNull(cookTime) && !isNull(prepTime)) return totalTime >= cookTime + prepTime;
+		return true;
+	}, {
+		message: "Total time should be at least the sum of cook time and prep time",
+		path: ["totalTime"]
+	}).refine((data) => {
+		return data.ratings === 0 || data.ratingsCount > 0;
+	}, {
+		message: "Ratings count should be greater than 0 when ratings exist",
+		path: ["ratingsCount"]
+	});
+}
+/**
+* Strict RecipeObject schema with all validations enforced.
+* This is the standard schema used by recipe scrapers.
+*
+* For custom extensions, use RecipeObjectBaseSchema.extend() and then
+* apply validations with applyRecipeValidations().
+*/
+const RecipeObjectSchema = applyRecipeValidations(RecipeObjectBaseSchema);
 
 //#endregion
 //#region src/exceptions/index.ts
@@ -1235,7 +1281,7 @@ var AbstractScraper = class {
 		return "en";
 	}
 	links() {
-		if (!this.options.linksEnabled) return [];
+		if (!this.options.linksEnabled) return void 0;
 		return this.$("a[href]").map((_, el) => {
 			const href = this.$(el).attr("href");
 			if (!href?.startsWith("http")) return null;
@@ -1282,6 +1328,7 @@ var AbstractScraper = class {
 	}
 	/**
 	* Converts the scraper's data into a JSON-serializable object.
+	* Note: schemaVersion is added during validation by parse() or safeParse().
 	*/
 	async toRecipeObject() {
 		const { category, cuisine, dietaryRestrictions, equipment, keywords, nutrients, reviews, ...rest } = await this.scrape();
@@ -1600,4 +1647,4 @@ function getScraper(url) {
 }
 
 //#endregion
-export { ExtractorPlugin, IngredientGroupSchema, IngredientItemSchema, IngredientsSchema, InstructionGroupSchema, InstructionItemSchema, InstructionsSchema, LinkSchema, LogLevel, Logger, ParsedIngredientSchema, PostProcessorPlugin, RecipeObjectBaseSchema, RecipeObjectSchema, getScraper, scrapers };
+export { ExtractorPlugin, IngredientGroupSchema, IngredientItemSchema, IngredientsSchema, InstructionGroupSchema, InstructionItemSchema, InstructionsSchema, LinkSchema, LogLevel, Logger, ParsedIngredientSchema, PostProcessorPlugin, RECIPE_SCHEMA_VERSION, RecipeObjectBaseSchema, RecipeObjectSchema, applyRecipeValidations, getScraper, scrapers };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recipe-scrapers-js",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.3",
   "license": "MIT",
   "description": "A recipe scrapers library",
   "author": {