soustack 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,336 @@
+/**
+ * Soustack Recipe Schema v0.1
+ * A portable, scalable, interoperable recipe format.
+ */
+interface Recipe {
+    /** Unique identifier (slug or UUID) */
+    id?: string;
+    /** The title of the recipe */
+    name: string;
+    /** Semantic versioning (e.g., 1.0.0) */
+    version?: string;
+    description?: string;
+    /** Primary category (e.g., "Main Course") */
+    category?: string;
+    /** Additional tags for filtering */
+    tags?: string[];
+    /** URL to recipe image */
+    image?: string;
+    /** ISO 8601 date string */
+    dateAdded?: string;
+    /** Last updated timestamp */
+    dateModified?: string;
+    source?: Source;
+    yield?: Yield;
+    time?: Time;
+    equipment?: Equipment[];
+    ingredients: IngredientItem[];
+    instructions: InstructionItem[];
+    storage?: Storage;
+    substitutions?: Substitution[];
+    nutrition?: NutritionFacts;
+}
+interface Source {
+    author?: string;
+    url?: string;
+    name?: string;
+    adapted?: boolean;
+}
+interface Yield {
+    amount: number;
+    unit: string;
+    servings?: number;
+    description?: string;
+}
+interface ParsedYield {
+    amount: number;
+    unit: string;
+    servings?: number;
+    description?: string;
+}
+/**
+ * Time can be structured (machine-readable) or simple (strings).
+ * Structured time takes precedence if both exist.
+ */
+type Time = StructuredTime | SimpleTime;
+interface StructuredTime {
+    prep?: number;
+    active?: number;
+    passive?: number;
+    total?: number;
+}
+interface SimpleTime {
+    prepTime?: string;
+    cookTime?: string;
+}
+interface Equipment {
+    id?: string;
+    name: string;
+    required?: boolean;
+    label?: string;
+    capacity?: Quantity;
+    scalingLimit?: number;
+    alternatives?: string[];
+}
+interface Quantity {
+    amount: number;
+    /** Unit string (e.g. "g", "cup") or null for count-based items (e.g. "2 eggs") */
+    unit: string | null;
+}
+type IngredientItem = string | Ingredient | IngredientSubsection;
+interface IngredientSubsection {
+    subsection: string;
+    items: (string | Ingredient)[];
+}
+interface Ingredient {
+    id?: string;
+    /** Full human-readable text (e.g. "2 cups flour") */
+    item: string;
+    quantity?: Quantity;
+    name?: string;
+    aisle?: string;
+    /** Required prep state (e.g. "diced") */
+    prep?: string;
+    prepAction?: string;
+    prepTime?: number;
+    /** ID of equipment where this ingredient goes */
+    destination?: string;
+    scaling?: Scaling;
+    critical?: boolean;
+    optional?: boolean;
+    notes?: string;
+}
+interface ParsedIngredient {
+    item: string;
+    quantity?: {
+        amount: number | null;
+        unit: string | null;
+    };
+    name?: string;
+    prep?: string;
+    optional?: boolean;
+    notes?: string;
+    scaling?: Scaling;
+}
+/**
+ * Intelligent Scaling Logic
+ * Defines how an ingredient behaves when the recipe yield changes.
+ */
+type Scaling = ScalingLinear | ScalingDiscrete | ScalingProportional | ScalingFixed | ScalingBakersPercentage;
+interface ScalingBase {
+    min?: number;
+    max?: number;
+}
+interface ScalingLinear extends ScalingBase {
+    type: "linear";
+}
+interface ScalingDiscrete extends ScalingBase {
+    type: "discrete";
+    roundTo?: number;
+}
+interface ScalingProportional extends ScalingBase {
+    type: "proportional";
+    factor?: number;
+}
+interface ScalingFixed extends ScalingBase {
+    type: "fixed";
+}
+interface ScalingBakersPercentage extends ScalingBase {
+    type: 'bakers_percentage';
+    /** The ID of the flour/base ingredient this is relative to */
+    referenceId: string;
+    /** The percentage relative to the reference (e.g. 0.02 for 2%) */
+    factor?: number;
+}
+type InstructionItem = string | Instruction | InstructionSubsection;
+interface InstructionSubsection {
+    subsection: string;
+    items: (string | Instruction)[];
+}
+interface Instruction {
+    id?: string;
+    text: string;
+    destination?: string;
+    /** IDs of steps that must complete before this one starts */
+    dependsOn?: string[];
+    /** IDs of ingredients used in this step */
+    inputs?: string[];
+    timing?: StepTiming;
+}
+interface StepTiming {
+    duration: number;
+    type: "active" | "passive";
+    scaling?: "linear" | "fixed" | "sqrt";
+}
+interface Storage {
+    roomTemp?: StorageMethod;
+    refrigerated?: StorageMethod;
+    frozen?: FrozenStorageMethod;
+    reheating?: string;
+    makeAhead?: MakeAheadComponent[];
+}
+interface StorageMethod {
+    /** ISO 8601 duration (e.g. P3D) */
+    duration: string;
+    method?: string;
+    notes?: string;
+}
+interface FrozenStorageMethod extends StorageMethod {
+    thawing?: string;
+}
+interface MakeAheadComponent extends StorageMethod {
+    component: string;
+    storage: "roomTemp" | "refrigerated" | "frozen";
+}
+interface Substitution {
+    ingredient: string;
+    critical?: boolean;
+    notes?: string;
+    alternatives?: Alternative[];
+}
+interface Alternative {
+    name: string;
+    ratio: string;
+    notes?: string;
+    impact?: string;
+    dietary?: string[];
+}
+interface NutritionFacts {
+    calories?: string;
+    fatContent?: string;
+    carbohydrateContent?: string;
+    proteinContent?: string;
+    fiberContent?: string;
+    sugarContent?: string;
+    sodiumContent?: string;
+    servingSize?: string;
+    [key: string]: string | number | null | string[] | undefined;
+}
+
+/**
+ * A "Computed Recipe" is the result of running the parser.
+ * It is flat, strict, and ready for the UI to render.
+ */
+interface ComputedRecipe {
+    metadata: {
+        targetYield: number;
+        baseYield: number;
+        multiplier: number;
+    };
+    ingredients: ComputedIngredient[];
+    instructions: ComputedInstruction[];
+    timing: {
+        active: number;
+        passive: number;
+        total: number;
+    };
+}
+interface ComputedIngredient {
+    id: string;
+    name: string;
+    amount: number;
+    unit: string | null;
+    text: string;
+    notes?: string;
+}
+interface ComputedInstruction {
+    id: string;
+    text: string;
+    durationMinutes: number;
+    type: 'active' | 'passive';
+}
+declare function scaleRecipe(recipe: Recipe, targetYieldAmount: number): ComputedRecipe;
+
+declare function validateRecipe(data: any): data is Recipe;
+
+declare function fromSchemaOrg(input: unknown): Recipe | null;
+
+interface SchemaOrgRecipe {
+    '@context'?: string;
+    '@type'?: string | string[];
+    name: string;
+    description?: string;
+    image?: SchemaOrgImage;
+    recipeIngredient?: SchemaOrgIngredientList;
+    recipeInstructions?: SchemaOrgInstructionList;
+    recipeYield?: string | number | SchemaOrgYield | Array<string | number | SchemaOrgYield>;
+    prepTime?: string;
+    cookTime?: string;
+    totalTime?: string;
+    recipeCategory?: string | string[];
+    recipeCuisine?: string | string[];
+    keywords?: string;
+    author?: SchemaOrgPersonOrOrganization | SchemaOrgPersonOrOrganization[] | string | string[];
+    publisher?: SchemaOrgPersonOrOrganization | SchemaOrgPersonOrOrganization[] | string | string[];
+    url?: string;
+    mainEntityOfPage?: string;
+    datePublished?: string;
+    dateModified?: string;
+    nutrition?: NutritionInformation;
+    '@graph'?: unknown;
+}
+type SchemaOrgIngredientList = string | string[];
+type SchemaOrgInstructionList = string | HowToStep | HowToSection | Array<string | HowToStep | HowToSection>;
+interface SchemaOrgImageObject {
+    '@type'?: string;
+    url?: string;
+    contentUrl?: string;
+}
+type SchemaOrgImage = string | SchemaOrgImageObject | Array<string | SchemaOrgImageObject>;
+interface SchemaOrgYield {
+    amount?: number;
+    unit?: string;
+    description?: string;
+}
+interface HowToStep {
+    '@type': 'HowToStep';
+    text?: string;
+    name?: string;
+    url?: string;
+    image?: string;
+}
+interface HowToSection {
+    '@type': 'HowToSection';
+    name: string;
+    itemListElement: Array<string | HowToStep | HowToSection>;
+}
+interface SchemaOrgPersonOrOrganization {
+    '@type'?: 'Person' | 'Organization';
+    name?: string;
+    url?: string;
+}
+interface NutritionInformation {
+    [key: string]: string | number | null | undefined;
+}
+
+declare function toSchemaOrg(recipe: Recipe): SchemaOrgRecipe;
+
+interface FetchOptions {
+    timeout?: number;
+    userAgent?: string;
+    maxRetries?: number;
+}
+interface ScrapeRecipeOptions extends FetchOptions {
+}
+
+declare function scrapeRecipe(url: string, options?: ScrapeRecipeOptions): Promise<Recipe>;
+
+declare function normalizeIngredientInput(input: string): string;
+declare function parseIngredient(text: string): ParsedIngredient;
+declare function parseIngredientLine(text: string): ParsedIngredient;
+declare function parseIngredients(texts: string[]): ParsedIngredient[];
+
+declare function parseDuration(iso: string): number | null;
+declare function parseDuration(iso: string | null | undefined): number | null;
+declare function formatDuration(minutes: number): string;
+declare function formatDuration(minutes: number | null | undefined): string;
+declare function parseHumanDuration(text: string): number | null;
+declare function parseHumanDuration(text: string | null | undefined): number | null;
+declare function smartParseDuration(input: string): number | null;
+declare function smartParseDuration(input: string | null | undefined): number | null;
+
+declare function normalizeYield(text: string): string;
+declare function parseYield(text: string): ParsedYield | null;
+declare function formatYield(value: ParsedYield): string;
+
+export { type Alternative, type ComputedIngredient, type ComputedInstruction, type ComputedRecipe, type Equipment, type FrozenStorageMethod, type Ingredient, type IngredientItem, type IngredientSubsection, type Instruction, type InstructionItem, type InstructionSubsection, type MakeAheadComponent, type NutritionFacts, type ParsedIngredient, type ParsedYield, type Quantity, type Recipe, type Scaling, type ScalingBakersPercentage, type ScalingBase, type ScalingDiscrete, type ScalingFixed, type ScalingLinear, type ScalingProportional, type SimpleTime, type Source, type StepTiming, type Storage, type StorageMethod, type StructuredTime, type Substitution, type Time, type Yield, formatDuration, formatYield, fromSchemaOrg, normalizeIngredientInput, normalizeYield, parseDuration, parseHumanDuration, parseIngredient, parseIngredientLine, parseIngredients, parseYield, scaleRecipe, scrapeRecipe, smartParseDuration, toSchemaOrg, validateRecipe };

package/dist/index.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Soustack Recipe Schema v0.1
+ * A portable, scalable, interoperable recipe format.
+ */
+interface Recipe {
+    /** Unique identifier (slug or UUID) */
+    id?: string;
+    /** The title of the recipe */
+    name: string;
+    /** Semantic versioning (e.g., 1.0.0) */
+    version?: string;
+    description?: string;
+    /** Primary category (e.g., "Main Course") */
+    category?: string;
+    /** Additional tags for filtering */
+    tags?: string[];
+    /** URL to recipe image */
+    image?: string;
+    /** ISO 8601 date string */
+    dateAdded?: string;
+    /** Last updated timestamp */
+    dateModified?: string;
+    source?: Source;
+    yield?: Yield;
+    time?: Time;
+    equipment?: Equipment[];
+    ingredients: IngredientItem[];
+    instructions: InstructionItem[];
+    storage?: Storage;
+    substitutions?: Substitution[];
+    nutrition?: NutritionFacts;
+}
+interface Source {
+    author?: string;
+    url?: string;
+    name?: string;
+    adapted?: boolean;
+}
+interface Yield {
+    amount: number;
+    unit: string;
+    servings?: number;
+    description?: string;
+}
+interface ParsedYield {
+    amount: number;
+    unit: string;
+    servings?: number;
+    description?: string;
+}
+/**
+ * Time can be structured (machine-readable) or simple (strings).
+ * Structured time takes precedence if both exist.
+ */
+type Time = StructuredTime | SimpleTime;
+interface StructuredTime {
+    prep?: number;
+    active?: number;
+    passive?: number;
+    total?: number;
+}
+interface SimpleTime {
+    prepTime?: string;
+    cookTime?: string;
+}
+interface Equipment {
+    id?: string;
+    name: string;
+    required?: boolean;
+    label?: string;
+    capacity?: Quantity;
+    scalingLimit?: number;
+    alternatives?: string[];
+}
+interface Quantity {
+    amount: number;
+    /** Unit string (e.g. "g", "cup") or null for count-based items (e.g. "2 eggs") */
+    unit: string | null;
+}
+type IngredientItem = string | Ingredient | IngredientSubsection;
+interface IngredientSubsection {
+    subsection: string;
+    items: (string | Ingredient)[];
+}
+interface Ingredient {
+    id?: string;
+    /** Full human-readable text (e.g. "2 cups flour") */
+    item: string;
+    quantity?: Quantity;
+    name?: string;
+    aisle?: string;
+    /** Required prep state (e.g. "diced") */
+    prep?: string;
+    prepAction?: string;
+    prepTime?: number;
+    /** ID of equipment where this ingredient goes */
+    destination?: string;
+    scaling?: Scaling;
+    critical?: boolean;
+    optional?: boolean;
+    notes?: string;
+}
+interface ParsedIngredient {
+    item: string;
+    quantity?: {
+        amount: number | null;
+        unit: string | null;
+    };
+    name?: string;
+    prep?: string;
+    optional?: boolean;
+    notes?: string;
+    scaling?: Scaling;
+}
+/**
+ * Intelligent Scaling Logic
+ * Defines how an ingredient behaves when the recipe yield changes.
+ */
+type Scaling = ScalingLinear | ScalingDiscrete | ScalingProportional | ScalingFixed | ScalingBakersPercentage;
+interface ScalingBase {
+    min?: number;
+    max?: number;
+}
+interface ScalingLinear extends ScalingBase {
+    type: "linear";
+}
+interface ScalingDiscrete extends ScalingBase {
+    type: "discrete";
+    roundTo?: number;
+}
+interface ScalingProportional extends ScalingBase {
+    type: "proportional";
+    factor?: number;
+}
+interface ScalingFixed extends ScalingBase {
+    type: "fixed";
+}
+interface ScalingBakersPercentage extends ScalingBase {
+    type: 'bakers_percentage';
+    /** The ID of the flour/base ingredient this is relative to */
+    referenceId: string;
+    /** The percentage relative to the reference (e.g. 0.02 for 2%) */
+    factor?: number;
+}
+type InstructionItem = string | Instruction | InstructionSubsection;
+interface InstructionSubsection {
+    subsection: string;
+    items: (string | Instruction)[];
+}
+interface Instruction {
+    id?: string;
+    text: string;
+    destination?: string;
+    /** IDs of steps that must complete before this one starts */
+    dependsOn?: string[];
+    /** IDs of ingredients used in this step */
+    inputs?: string[];
+    timing?: StepTiming;
+}
+interface StepTiming {
+    duration: number;
+    type: "active" | "passive";
+    scaling?: "linear" | "fixed" | "sqrt";
+}
+interface Storage {
+    roomTemp?: StorageMethod;
+    refrigerated?: StorageMethod;
+    frozen?: FrozenStorageMethod;
+    reheating?: string;
+    makeAhead?: MakeAheadComponent[];
+}
+interface StorageMethod {
+    /** ISO 8601 duration (e.g. P3D) */
+    duration: string;
+    method?: string;
+    notes?: string;
+}
+interface FrozenStorageMethod extends StorageMethod {
+    thawing?: string;
+}
+interface MakeAheadComponent extends StorageMethod {
+    component: string;
+    storage: "roomTemp" | "refrigerated" | "frozen";
+}
+interface Substitution {
+    ingredient: string;
+    critical?: boolean;
+    notes?: string;
+    alternatives?: Alternative[];
+}
+interface Alternative {
+    name: string;
+    ratio: string;
+    notes?: string;
+    impact?: string;
+    dietary?: string[];
+}
+interface NutritionFacts {
+    calories?: string;
+    fatContent?: string;
+    carbohydrateContent?: string;
+    proteinContent?: string;
+    fiberContent?: string;
+    sugarContent?: string;
+    sodiumContent?: string;
+    servingSize?: string;
+    [key: string]: string | number | null | string[] | undefined;
+}
+
+/**
+ * A "Computed Recipe" is the result of running the parser.
+ * It is flat, strict, and ready for the UI to render.
+ */
+interface ComputedRecipe {
+    metadata: {
+        targetYield: number;
+        baseYield: number;
+        multiplier: number;
+    };
+    ingredients: ComputedIngredient[];
+    instructions: ComputedInstruction[];
+    timing: {
+        active: number;
+        passive: number;
+        total: number;
+    };
+}
+interface ComputedIngredient {
+    id: string;
+    name: string;
+    amount: number;
+    unit: string | null;
+    text: string;
+    notes?: string;
+}
+interface ComputedInstruction {
+    id: string;
+    text: string;
+    durationMinutes: number;
+    type: 'active' | 'passive';
+}
+declare function scaleRecipe(recipe: Recipe, targetYieldAmount: number): ComputedRecipe;
+
+declare function validateRecipe(data: any): data is Recipe;
+
+declare function fromSchemaOrg(input: unknown): Recipe | null;
+
+interface SchemaOrgRecipe {
+    '@context'?: string;
+    '@type'?: string | string[];
+    name: string;
+    description?: string;
+    image?: SchemaOrgImage;
+    recipeIngredient?: SchemaOrgIngredientList;
+    recipeInstructions?: SchemaOrgInstructionList;
+    recipeYield?: string | number | SchemaOrgYield | Array<string | number | SchemaOrgYield>;
+    prepTime?: string;
+    cookTime?: string;
+    totalTime?: string;
+    recipeCategory?: string | string[];
+    recipeCuisine?: string | string[];
+    keywords?: string;
+    author?: SchemaOrgPersonOrOrganization | SchemaOrgPersonOrOrganization[] | string | string[];
+    publisher?: SchemaOrgPersonOrOrganization | SchemaOrgPersonOrOrganization[] | string | string[];
+    url?: string;
+    mainEntityOfPage?: string;
+    datePublished?: string;
+    dateModified?: string;
+    nutrition?: NutritionInformation;
+    '@graph'?: unknown;
+}
+type SchemaOrgIngredientList = string | string[];
+type SchemaOrgInstructionList = string | HowToStep | HowToSection | Array<string | HowToStep | HowToSection>;
+interface SchemaOrgImageObject {
+    '@type'?: string;
+    url?: string;
+    contentUrl?: string;
+}
+type SchemaOrgImage = string | SchemaOrgImageObject | Array<string | SchemaOrgImageObject>;
+interface SchemaOrgYield {
+    amount?: number;
+    unit?: string;
+    description?: string;
+}
+interface HowToStep {
+    '@type': 'HowToStep';
+    text?: string;
+    name?: string;
+    url?: string;
+    image?: string;
+}
+interface HowToSection {
+    '@type': 'HowToSection';
+    name: string;
+    itemListElement: Array<string | HowToStep | HowToSection>;
+}
+interface SchemaOrgPersonOrOrganization {
+    '@type'?: 'Person' | 'Organization';
+    name?: string;
+    url?: string;
+}
+interface NutritionInformation {
+    [key: string]: string | number | null | undefined;
+}
+
+declare function toSchemaOrg(recipe: Recipe): SchemaOrgRecipe;
+
+interface FetchOptions {
+    timeout?: number;
+    userAgent?: string;
+    maxRetries?: number;
+}
+interface ScrapeRecipeOptions extends FetchOptions {
+}
+
+declare function scrapeRecipe(url: string, options?: ScrapeRecipeOptions): Promise<Recipe>;
+
+declare function normalizeIngredientInput(input: string): string;
+declare function parseIngredient(text: string): ParsedIngredient;
+declare function parseIngredientLine(text: string): ParsedIngredient;
+declare function parseIngredients(texts: string[]): ParsedIngredient[];
+
+declare function parseDuration(iso: string): number | null;
+declare function parseDuration(iso: string | null | undefined): number | null;
+declare function formatDuration(minutes: number): string;
+declare function formatDuration(minutes: number | null | undefined): string;
+declare function parseHumanDuration(text: string): number | null;
+declare function parseHumanDuration(text: string | null | undefined): number | null;
+declare function smartParseDuration(input: string): number | null;
+declare function smartParseDuration(input: string | null | undefined): number | null;
+
+declare function normalizeYield(text: string): string;
+declare function parseYield(text: string): ParsedYield | null;
+declare function formatYield(value: ParsedYield): string;
+
+export { type Alternative, type ComputedIngredient, type ComputedInstruction, type ComputedRecipe, type Equipment, type FrozenStorageMethod, type Ingredient, type IngredientItem, type IngredientSubsection, type Instruction, type InstructionItem, type InstructionSubsection, type MakeAheadComponent, type NutritionFacts, type ParsedIngredient, type ParsedYield, type Quantity, type Recipe, type Scaling, type ScalingBakersPercentage, type ScalingBase, type ScalingDiscrete, type ScalingFixed, type ScalingLinear, type ScalingProportional, type SimpleTime, type Source, type StepTiming, type Storage, type StorageMethod, type StructuredTime, type Substitution, type Time, type Yield, formatDuration, formatYield, fromSchemaOrg, normalizeIngredientInput, normalizeYield, parseDuration, parseHumanDuration, parseIngredient, parseIngredientLine, parseIngredients, parseYield, scaleRecipe, scrapeRecipe, smartParseDuration, toSchemaOrg, validateRecipe };