app/kb/procedures/json-ld.mjs

Functions

Imports

It imports app/kb/procedures/cite.mjs, app/kb/procedures/marks.mjs. Imported by app/routes/procedure.tsx, app/routes/procedure.version.tsx.

Source

1// The structured data a procedure page carries, from its D1 record: Bioschemas LabProtocol for a protocol
2// (https://bioschemas.org/profiles/LabProtocol/0.9-DRAFT; every LabProtocol version is a draft), schema.org Recipe for a
3// recipe, following Google's recipe structured-data guidance, and schema.org HowTo for a computational procedure, the closest type
4// for a sequence of commands with tools and supplies. Only facts the record states: a gap stays out.
5
6import { citeFacts } from "./cite.mjs";
7import { readConditions } from "./marks.mjs";
8
9const LAB_PROTOCOL_PROFILE = "https://bioschemas.org/profiles/LabProtocol/0.9-DRAFT";
10
11/** A number as a step writes it: "13,000" is 13000. @param {string} n */
12const numeral = (n) => Number(n.replaceAll(",", ""));
13
14/**
15 * The protocol's conditions as 0.9-DRAFT's `parameter` (docs/KNOWLEDGE-BASE.md, P4): every temperature and spin its steps
16 * state, once each, in the order first stated. The profile puts them on the protocol as a whole, not on a step, and these
17 * are the conditions the compile already reads (marks.mjs readConditions): from a step's words, and the g-force its
18 * SPIN flag states. Nothing is typed twice.
19 *
20 * @param {import("./render.mjs").ProcedureRecord} record
21 */
22export function protocolParameters(record) {
23  // Keyed by the condition, so one stated in several steps is one parameter, at the place it was first stated.
24  /** @type {Map<string, Record<string, unknown>>} */
25  const seen = new Map();
26  for (const section of record.sections) {
27    for (const block of section.blocks) {
28      if (block.type !== "steps") continue;
29      for (const step of block.steps) {
30        // A row compiled before the conditions were stored has none until the next sync rewrites it.
31        for (const t of step.temperatures ?? []) {
32          seen.set(`t:${t.min}:${t.max}`, { "@type": "PropertyValue", name: "Temperature", ...(t.min === t.max ? { value: t.min } : { minValue: t.min, maxValue: t.max }), unitCode: "CEL", unitText: "°C" });
33        }
34        const flagged = (step.spin ?? []).flatMap((s) => readConditions(s).spins);
35        for (const spin of [...(step.spins ?? []), ...flagged]) {
36          const [low = "", high] = spin.speed.split(/\s*to\s*/);
37          const range = high === undefined ? { value: numeral(low) } : { minValue: numeral(low), maxValue: numeral(high) };
38          seen.set(`s:${spin.speed}:${spin.unit}`, { "@type": "PropertyValue", name: spin.unit === "rpm" ? "Rotor speed" : "Relative centrifugal force", ...range, unitText: spin.unit === "rpm" ? "rpm" : "x g" });
39        }
40      }
41    }
42  }
43  return [...seen.values()];
44}
45
46/**
47 * The procedure a variant was copied from, as `isBasedOn` names it (P3): its address, at the version copied when there is
48 * a frozen copy of it, and its title. Resolved at request time from the parent's row (lineage.server.ts).
49 *
50 * @param {import("./lineage.mjs").Lineage | null} lineage
51 * @param {string} origin
52 */
53function lineageWork(lineage, origin) {
54  if (!lineage?.href) return [];
55  return [{ "@type": "CreativeWork", name: lineage.title, url: `${origin}${lineage.href}`, ...(lineage.version ? { version: lineage.version } : {}) }];
56}
57
58/** @param {string | null | undefined} html */
59function text(html) {
60  return String(html ?? "")
61    .replace(/<[^>]+>/g, "")
62    .replace(/&amp;/g, "&")
63    .replace(/&lt;/g, "<")
64    .replace(/&gt;/g, ">")
65    .replace(/&quot;/g, '"')
66    .replace(/&#x27;|&#39;/g, "'")
67    .replace(/\s+/g, " ")
68    .trim();
69}
70
71/**
72 * "20 minutes", "1.5 hours" as ISO 8601; null for anything else.
73 *
74 * @param {string | null} value
75 */
76function isoDuration(value) {
77  const m = /^(\d+(?:\.\d+)?) (minutes?|hours?)$/.exec(String(value ?? ""));
78  if (!m) return null;
79  const minutes = Math.round(Number(m[1]) * (m[2]?.startsWith("hour") ? 60 : 1));
80  const h = Math.floor(minutes / 60);
81  const min = minutes % 60;
82  return `PT${h ? `${h}H` : ""}${min || !h ? `${min}M` : ""}`;
83}
84
85/**
86 * @param {import("./render.mjs").ProcedureRecord} record
87 * @param {string} origin
88 * @param {{ "@type": string, "@id": string, name: string, url: string }} person
89 * @param {import("./lineage.mjs").Lineage | null} [lineage] the procedure this one is a variant of
90 */
91export function procedureJsonLd(record, origin, person, lineage = null) {
92  const url = `${origin}${record.path}`;
93  const steps = record.sections.flatMap((section) => {
94    const items = section.blocks.flatMap((b) => (b.type === "steps" ? b.steps : []));
95    if (items.length === 0) return [];
96    return [
97      {
98        "@type": "HowToSection",
99        name: section.title,
100        itemListElement: items.map((step) => ({
101          "@type": "HowToStep",
102          position: step.number,
103          text: step.text,
104          url: `${url}#${section.id}`,
105          ...(step.photos[0] ? { image: `${origin}${step.photos[0].src}` } : {}),
106        })),
107      },
108    ];
109  });
110  const basedOn = [...lineageWork(lineage, origin), ...record.basedOn.map((s) => ({
111    "@type": "CreativeWork",
112    name: s.citation,
113    ...(s.doi ? { identifier: `https://doi.org/${s.doi}`, url: `https://doi.org/${s.doi}` } : s.url ? { url: s.url } : {}),
114  }))];
115  const cite = citeFacts(record);
116  const common = {
117    "@context": "https://schema.org",
118    "@id": `${url}#procedure`,
119    name: record.title,
120    description: record.description,
121    url,
122    author: person,
123    ...(record.updated ? { dateModified: record.updated } : {}),
124    ...(record.version ? { version: record.version } : {}),
125    ...(cite?.doi ? { identifier: `https://doi.org/${cite.doi}` } : {}),
126    ...(basedOn.length ? { isBasedOn: basedOn } : {}),
127    ...(record.references.length ? { citation: record.references.map(text) } : {}),
128  };
129
130  if (record.profile === "protocol") {
131    return {
132      ...common,
133      "@type": "LabProtocol",
134      "http://purl.org/dc/terms/conformsTo": { "@id": LAB_PROTOCOL_PROFILE },
135      reagent: record.materials.map((m) => m.display),
136      labEquipment: record.equipment.map((e) => e.name),
137      ...(record.biosafetyLevel ? { additionalProperty: { "@type": "PropertyValue", name: "Biosafety level", value: record.biosafetyLevel } } : {}),
138      ...(record.biosafety ? { bioSample: [record.biosafety.organism, record.biosafety.strain].filter(Boolean).join(" ") } : {}),
139      ...(record.expectedResultsHtml ? { protocolOutcome: text(record.expectedResultsHtml) } : {}),
140      ...(record.limitationsHtml ? { protocolLimitation: text(record.limitationsHtml) } : {}),
141      ...(isoDuration(record.time.total) ? { totalTime: isoDuration(record.time.total) } : {}),
142      ...(protocolParameters(record).length ? { parameter: protocolParameters(record) } : {}),
143      step: steps,
144    };
145  }
146
147  if (record.profile === "recipe") {
148    const prep = isoDuration(record.prepTime);
149    const cook = isoDuration(record.cookTime);
150    const minutes = (/** @type {string | null} */ d) => {
151      const m = /^PT(?:(\d+)H)?(?:(\d+)M)?$/.exec(d ?? "");
152      return m ? Number(m[1] ?? 0) * 60 + Number(m[2] ?? 0) : null;
153    };
154    const total = prep && cook ? isoDuration(`${(minutes(prep) ?? 0) + (minutes(cook) ?? 0)} minutes`) : null;
155    return {
156      ...common,
157      "@type": "Recipe",
158      ...(record.image ? { image: [`${origin}${record.image.src}`] } : {}),
159      ...(record.servings ? { recipeYield: String(record.servings) } : {}),
160      ...(record.cuisine ? { recipeCuisine: record.cuisine } : {}),
161      ...(record.category ? { recipeCategory: record.category } : {}),
162      ...(prep ? { prepTime: prep } : {}),
163      ...(cook ? { cookTime: cook } : {}),
164      ...(total ? { totalTime: total } : {}),
165      recipeIngredient: record.materials.map((m) => (m.amount ? `${m.amount} ${m.display}` : m.display)),
166      recipeInstructions: steps,
167    };
168  }
169
170  return {
171    ...common,
172    "@type": "HowTo",
173    tool: record.materials
174      .filter((m) => m.kind === "software")
175      .map((m) => ({ "@type": "HowToTool", name: m.version ? `${m.display} ${m.version}` : m.display })),
176    supply: record.materials
177      .filter((m) => m.kind !== "software")
178      .map((m) => ({ "@type": "HowToSupply", name: m.display })),
179    step: steps,
180  };
181}