hospitality.allergen-matrix Unreviewed

export function allergenMatrix(ingredients: readonly IngredientAllergens[], jurisdiction: string, onDate: string): readonly AllergenRow[]

/** One ingredient and what its specification or label declares. */
export interface IngredientAllergens {
  readonly name: string;
  /** allergen codes the ingredient contains */
  readonly contains: readonly string[];
  /** codes of precautionary "may contain" statements */
  readonly mayContain: readonly string[];
}

export type AllergenStatus = "contains" | "may-contain" | "none";

/** One allergen and whether the dish has it. */
export interface AllergenRow {
  readonly code: string;
  readonly name: string;
  /** contains beats may-contain */
  readonly status: AllergenStatus;
  /** the ingredients responsible, in the order given */
  readonly sources: readonly string[];
}

import { allergenMatrix } from "#fune/hospitality.allergen-matrix@^1";

import { addDays } from "./dates_add_days.ts";  ← from dates.add-days ^1.0.0 · built alongside by fune
import { ALLERGENS, ALLERGENS_HISTORY, type Allergen } from "./hospitality_allergen_matrix_data.ts";  ← this capability’s own data, compiled from data/allergens.json into the same file by fune build
import { type AllergenRow, type IngredientAllergens } from "./hospitality_allergen_matrix_types.ts";

function listInForce(jurisdiction: string, onDate: string): Allergen[] {
  const rows = ALLERGENS.filter(
    (a) => a.jurisdiction === jurisdiction && a.validFrom <= onDate && (a.validTo === null || onDate <= a.validTo),
  );
  if (rows.length > 0) return [...rows].sort((a, b) => a.annexNumber - b.annexNumber);
  // A history-pruned build may have dropped the list that applied then; say so
  // rather than answering with nothing.
  if (ALLERGENS_HISTORY !== "full") {
    const earliest = ALLERGENS.filter((a) => a.jurisdiction === jurisdiction).reduce<string | null>(
      (e, a) => (e === null || a.validFrom < e ? a.validFrom : e),
      null,
    );
    if (earliest !== null && onDate < earliest) {
      throw new RangeError(
        `no allergen list for ${jurisdiction} on ${onDate}: this build was installed with history=${ALLERGENS_HISTORY}, so it only carries lists from ${earliest}`,
      );
    }
  }
  throw new RangeError(`no allergen list for ${jurisdiction} on ${onDate}`);
}

/**
 * The regulated allergens in a dish, from what its ingredients declare.
 *
 * Every allergen on the list gets a row, in the legal order, so a menu or
 * allergen chart shows "none" as a decision rather than a gap. An allergen any
 * ingredient contains is "contains"; otherwise one any ingredient may contain
 * is "may-contain". The sources say which ingredients to check.
 */
export function allergenMatrix(ingredients: readonly IngredientAllergens[], jurisdiction: string, onDate: string): readonly AllergenRow[] {
  addDays(onDate, 0);
  const list = listInForce(jurisdiction, onDate);
  const known = new Set(list.map((a) => a.code));
  for (const ingredient of ingredients) {
    for (const code of [...ingredient.contains, ...ingredient.mayContain]) {
      if (!known.has(code)) {
        throw new RangeError(`unknown allergen "${code}" in "${ingredient.name}": not on the ${jurisdiction} list on ${onDate}`);
      }
    }
  }
  return list.map((allergen) => {
    const contains = ingredients.filter((i) => i.contains.includes(allergen.code)).map((i) => i.name);
    const may = ingredients.filter((i) => i.mayContain.includes(allergen.code)).map((i) => i.name);
    const sources = contains.length > 0 ? contains : may;
    return {
      code: allergen.code,
      name: allergen.name,
      status: contains.length > 0 ? "contains" : may.length > 0 ? "may-contain" : "none",
      sources: sources.filter((name, i) => sources.indexOf(name) === i),
    };
  });
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add hospitality.allergen-matrix

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./hospitality.allergen-matrix-1.0.1-typescript.fune, or fetch it from a terminal with fune pull hospitality.allergen-matrix@1.0.1:typescript.

The whole function, every language, is one file too: hospitality.allergen-matrix-1.0.1.fune, 42,005 bytes, sha256 165cf7187dce0c180a786df1838560e799c843dd61036fdd85213befacfe38b2. It installs into a project of any language.

// fune: before hospitality.allergen-matrix

// fune: after hospitality.allergen-matrix

// fune: replace dates.add-days in hospitality.allergen-matrix

// fune: step hospitality.allergen-matrix after <n|label>

More from the author

## How the status is decided

- **contains**: at least one ingredient declares it. The sources are those ingredients only. - **may-contain**: no ingredient contains it, but at least one carries a precautionary "may contain" statement for it. That is a cross-contamination warning from the supplier, not an ingredient, and it is kept separate so the menu can say so rather than claim the allergen is an ingredient or leave it out. - **none**: nothing declared. Every allergen gets a row, so "none" is shown as a checked answer, not left out.

Sources keep the order the ingredients were given, without duplicates.

## Codes

`gluten`, `crustaceans`, `eggs`, `fish`, `peanuts`, `soybeans`, `milk`, `nuts`, `celery`, `mustard`, `sesame`, `sulphites`, `lupin`, `molluscs`. An unknown code (`tree-nuts`, `gluten free`) is an error rather than being ignored, because an allergen dropped by a typo is the failure that hurts someone.

## What it does not do

- It does **not** detect allergens. It trusts the declarations it is given, and an ingredient whose specification is missing or out of date gives a wrong answer. Keep specifications current, and re-run the matrix when a supplier or recipe changes. - It does not name the specific cereal or nut. The law requires "wheat", "almonds" and so on, not just "cereals containing gluten" or "nuts". Carry that detail in the ingredient name. - Sulphites only count above 10 mg/kg or 10 mg/litre (as SO2). Whether an ingredient crosses that threshold is for its declaration to say. - It says nothing about cross-contact in your own kitchen, which the FSA expects a business to manage and communicate separately.

## The list is data

The 14 are dated rows in `data/allergens.json`, keyed by jurisdiction, and the function takes the date the food is served. If the list changes, that is a data release, not a code change. The rows apply from 13 December 2014, when Regulation (EU) No 1169/2011 (FIC) began to apply. Lupin and molluscs were already on the earlier list, added by Directive 2006/142/EC. A date before then, or a jurisdiction with no rows, is an error.

`GB` covers England, Scotland and Wales under the retained regulation. Northern Ireland applies the EU regulation directly and has the same 14 today, but it is not in this data.

## Sources

- Regulation (EU) No 1169/2011 on the provision of food information to consumers, Annex II, *Substances or products causing allergies or intolerances*, as retained in GB law: https://www.legislation.gov.uk/eur/2011/1169/annex/II - The Food Information Regulations 2014 (SI 2014/1855), which enforce it in England. Regulation 5 covers allergen information for food that is not prepacked, and regulation 5A covers food prepacked for direct sale ("Natasha's Law", from 1 October 2021): https://www.legislation.gov.uk/uksi/2014/1855/contents . Scotland, Wales and Northern Ireland have parallel regulations. Note that the list of 14 itself is in Annex II of the EU regulation, not in a Schedule of the 2014 Regulations. - Food Standards Agency, *Allergen guidance for food businesses*: https://www.food.gov.uk/business-guidance/allergen-guidance-for-food-businesses

## Before you rely on this

**Not professional advice.** This capability calculates food-safety figures from published rules. It is a software component for developers, not food-safety advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a food safety officer (EHO) review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified food safety officer (EHO) has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

## Notices

Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

Legislation: Crown copyright and database right.

1.0.1 marks it unreviewed and adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files