app/kb/registry/reagent.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/kb/registry/host.server.ts, app/kb/registry/kinds.mjs.

Source

1// The reagent kind of the lab registry (docs/REGISTRY.md): the substances the lab's protocols use up, as distinct from the
2// samples they work on (a lysate, soil, an eluate), the primers (their own kind) and the cultures (strains). The reagents are one
3// table (the library's Reagents tab) and each has a page of its own, listing the protocols that use it (docs/KNOWLEDGE-BASE.md,
4// A1); each protocol's own Reagents table is drawn from these records with that protocol's amount, stock and final.
5//
6// A record states what the lab's own pages state about one substance: its name, an abbreviation or what it is made of where a
7// protocol says so, and where it comes from. A BOUGHT reagent has a supplier and a catalog number (each stated, or
8// `MISSING: <why>` where no record in the repository says, listed for Dustin) and a product link where a protocol linked it. A
9// reagent PREPARED IN THE LAB says so (`prepared_in_lab: true`) and carries a link to its recipe in place of a supplier and a
10// catalog number; the recipe is a procedure with the recipe profile, and where none exists yet the link is MISSING and listed for
11// Dustin, because recipes are written by the lab and never invented here.
12//
13// What the protocols use of it is COMPUTED: a protocol names a reagent on one of its materials by id (`reagent: <id>`), keeps its
14// own amount, stock and final, and the table lists the protocols that name it.
15
16const LINE = /^[^\r\n]+$/;
17
18/** @param {unknown} value @param {number} max */
19const oneLine = (value, max) =>
20  typeof value === "string" && LINE.test(value) && value === value.trim() && value.length <= max ? null : `is one line of at most ${max} characters`;
21
22/** A field the file does not carry reads as null (compile.mjs). @param {unknown} value */
23const absent = (value) => value === undefined || value === null;
24
25/** @param {unknown} value */
26const isGap = (value) => typeof value === "string" && value.startsWith("MISSING");
27
28/** @type {import("./kinds.mjs").KindSpec} */
29export const REAGENT = {
30  singular: "reagent",
31  plural: "reagents",
32  fields: {
33    // What a protocol calls it in one phrase, as the protocols' own words give it: ZnCl2 for zinc chloride.
34    abbreviation: { check: (value) => oneLine(value, 40) },
35    // What it is made of, where a protocol says: DNase I plus RNase A.
36    contents: { check: (value) => oneLine(value, 120) },
37    // Bought (a supplier and a catalog number) or prepared in the lab (a recipe): setErrors holds each item to one of the two.
38    supplier: { check: (value) => oneLine(value, 80) },
39    catalog_number: { check: (value) => oneLine(value, 40) },
40    product_url: { check: (value) => (typeof value === "string" && /^https:\/\/[^\s]+$/.test(value) ? null : "is an https address") },
41    prepared_in_lab: { check: (value) => (value === true ? null : "is true, or absent for a reagent that is bought") },
42    // The recipe of a reagent prepared in the lab: the file key of a procedure with the recipe profile, or MISSING.
43    recipe: {
44      check: async (value, { host }) =>
45        typeof value === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value) && (await host.recipe(value))
46          ? null
47          : "is the file key of a procedure with the recipe profile (content/procedures/<key>.md, profile: recipe), or MISSING: <why>",
48    },
49  },
50  /**
51   * A bought reagent states a supplier and a catalog number (or a gap for each) and no recipe; a reagent prepared in the lab states
52   * a recipe (or a gap) and no supplier, catalog number or product link, because it has none.
53   */
54  setErrors(items) {
55    /** @type {string[]} */
56    const errors = [];
57    for (const { id, fields } of items) {
58      if (fields.prepared_in_lab === true) {
59        if (absent(fields.recipe)) errors.push(`reagent/${id} is prepared in the lab, so it states its recipe, or MISSING: <why>`);
60        for (const field of ["supplier", "catalog_number", "product_url"]) {
61          if (!absent(fields[field])) errors.push(`reagent/${id} is prepared in the lab, so it has no ${field}`);
62        }
63      } else {
64        for (const field of ["supplier", "catalog_number"]) {
65          if (absent(fields[field])) errors.push(`reagent/${id} is bought, so it states its ${field}, or MISSING: <why>`);
66        }
67        if (!absent(fields.recipe) && !isGap(fields.recipe)) errors.push(`reagent/${id} is not prepared in the lab, so it has no recipe`);
68      }
69    }
70    return errors;
71  },
72};
73
74/**
75 * A reagent as a protocol carries it (`StoredReagent` in app/kb/procedures/render.mjs): the registry's stated facts, none computed,
76 * so the protocol's Reagents table, twin and frozen versions say where each came from as it was when the protocol was published.
77 *
78 * @param {import("./kinds.mjs").RegistryItem} item
79 * @returns {import("../procedures/render.mjs").StoredReagent}
80 */
81export function storedReagent(item) {
82  const f = /** @type {Record<string, unknown>} */ (item.fields);
83  const text = (/** @type {unknown} */ value) => (typeof value === "string" && value !== "" && !value.startsWith("MISSING") ? value : null);
84  return {
85    id: item.id,
86    name: item.name,
87    status: item.status,
88    preparedInLab: f.prepared_in_lab === true,
89    supplier: text(f.supplier),
90    catalogNumber: text(f.catalog_number),
91    productUrl: text(f.product_url),
92    recipe: text(f.recipe),
93  };
94}