app/kb/procedures/cite.mjs

Functions

Imports

It imports app/kb/procedures/taxonomy.mjs. Imported by app/components/procedure.tsx, app/kb/procedures/json-ld.mjs, app/kb/procedures/lineage.mjs, app/kb/procedures/save.server.ts, app/kb/procedures/validate.mjs, app/routes/procedure.sheet.tsx, app/routes/procedure.version.sheet.tsx, app/routes/procedure.version.tsx.

Source

1// How a procedure version is addressed and cited: the address of its frozen copy, the citation line, the BibTeX
2// entry and the metadata Zenodo takes for a deposit. All of it is derived from the record (its path, its version,
3// its history and its title), never typed, so a version bumped in the file changes every place that cites it.
4//
5// A procedure with no version cannot be cited: a DOI is minted only for a version being cited (decisions.md,
6// Protocols), so there is nothing to cite until one has been assigned. The DOI of a version is written once, on that version's
7// entry in `history`, after Zenodo has minted it; this module never invents one.
8//
9// A cited version is a frozen copy (drizzle/0027_procedure_versions.sql), so a citation and a printed sheet's QR
10// code point at `<page>/v/<version>`, which never changes, and not at the page, which moves on to the next version.
11
12import { METHODS } from "./taxonomy.mjs";
13
14/**
15 * @typedef {{ name: string, affiliation: string }} Creator
16 * @typedef {{ version: string, date: string, doi: string | null }} CiteFacts
17 */
18
19/** The shape Zenodo's DOIs and DataCite's share: the registrant prefix, a slash, the suffix. */
20export const DOI_PATTERN = /^10\.\d{4,9}\/\S+$/;
21
22/** A version that can sit in a URL and a file name: letters, digits, dots, hyphens and underscores. */
23export const VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
24
25/**
26 * The path of a version's frozen copy. The newest version also answers here, so a citation made today still
27 * resolves to the same words when the page has moved on.
28 *
29 * @param {string} path the procedure's own path
30 * @param {string} version
31 */
32export function versionPath(path, version) {
33  return `${path}/v/${encodeURIComponent(version)}`;
34}
35
36/**
37 * Whether saving this record freezes a copy: a published procedure with an assigned version. A draft is never
38 * frozen, and a procedure with no version has no version to freeze.
39 *
40 * @param {{ draft: boolean, version: string | null }} record
41 */
42export function needsFreeze(record) {
43  return !record.draft && record.version !== null && record.version !== "";
44}
45
46/**
47 * The address a printed sheet's QR code opens, and the sheet prints: the frozen copy of the version on it, so the code
48 * opens the words the sheet was printed from even after the page has moved on. A procedure with no published version
49 * has no copy, so its sheet points at the page.
50 *
51 * @param {{ draft: boolean, version: string | null, path: string }} record
52 * @param {string} origin
53 */
54export function sheetAddress(record, origin) {
55  return `${origin}${needsFreeze(record) ? versionPath(record.path, String(record.version)) : record.path}`;
56}
57
58/**
59 * What a citation of the record's current version needs, or null when it has no version or no date to cite.
60 * The date is the one the history gives the version, else the date the page was last updated.
61 *
62 * @param {{ version: string | null, updated: string | null, history?: Array<{ version: string, date: string, doi: string | null }> }} record
63 * @returns {CiteFacts | null}
64 */
65export function citeFacts(record) {
66  if (!record.version) return null;
67  const entry = record.history?.find((h) => h.version === String(record.version));
68  const date = entry?.date ?? record.updated;
69  if (!date) return null;
70  return { version: String(record.version), date, doi: entry?.doi ?? null };
71}
72
73/**
74 * "Dustin Edwards" as the family name and the given name. For a name written given-first, as the CV writes
75 * the owner's; the last word is the family name.
76 *
77 * @param {string} name
78 */
79export function familyGiven(name) {
80  const words = name.trim().split(/\s+/);
81  const family = words.pop() ?? "";
82  return { family, given: words.join(" ") };
83}
84
85/** @param {string} given */
86const initials = (given) =>
87  given
88    .split(/\s+/)
89    .filter(Boolean)
90    .map((w) => `${w.charAt(0).toUpperCase()}.`)
91    .join(" ");
92
93/**
94 * The address a citation points at: the version's DOI when it has one, else its frozen copy.
95 *
96 * @param {{ path: string }} record
97 * @param {CiteFacts} facts
98 * @param {string} origin
99 */
100const target = (record, facts, origin) => (facts.doi ? `https://doi.org/${facts.doi}` : `${origin}${versionPath(record.path, facts.version)}`);
101
102/**
103 * @param {{ title: string, path: string }} record
104 * @param {CiteFacts} facts
105 * @param {{ origin: string, creator: Creator }} where
106 */
107export function citationText(record, facts, { origin, creator }) {
108  const { family, given } = familyGiven(creator.name);
109  const host = new URL(origin).host;
110  return `${family}, ${initials(given)} (${facts.date.slice(0, 4)}). ${record.title} (Version ${facts.version}) [Laboratory protocol]. ${host}. ${target(record, facts, origin)}`;
111}
112
113/**
114 * @param {{ slug: string, title: string, path: string }} record
115 * @param {CiteFacts} facts
116 * @param {{ origin: string, creator: Creator }} where
117 */
118export function bibtex(record, facts, { origin, creator }) {
119  const { family, given } = familyGiven(creator.name);
120  const year = facts.date.slice(0, 4);
121  const field = (/** @type {string} */ name, /** @type {string} */ value) => `  ${name} = {${value.replace(/[{}]/g, "")}},`;
122  return [
123    `@misc{${family.toLowerCase()}${year}${record.slug}v${facts.version.replace(/[^A-Za-z0-9.]/g, "")},`,
124    field("author", `${family}, ${given}`),
125    field("title", record.title),
126    field("year", year),
127    field("version", facts.version),
128    field("howpublished", "Laboratory protocol"),
129    ...(facts.doi ? [field("doi", facts.doi)] : []),
130    field("url", target(record, facts, origin)),
131    "}",
132  ].join("\n");
133}
134
135/**
136 * The metadata for depositing this version on Zenodo (its `.zenodo.json` or its upload form). No `doi` is
137 * written: Zenodo mints it, and the maintainer then records it on the version's `history` entry. Earlier
138 * versions that already have a DOI are linked as the ones this supersedes. The license is left out: it is
139 * Dustin's to choose, and Zenodo asks for it at upload.
140 *
141 * @param {{ title: string, description: string, path: string, methods: string[], basedOn: Array<{ doi: string | null }>, history?: Array<{ version: string, date: string, doi: string | null }> }} record
142 * @param {CiteFacts} facts
143 * @param {{ origin: string, creator: Creator }} where
144 */
145export function zenodoMetadata(record, facts, { origin, creator }) {
146  const { family, given } = familyGiven(creator.name);
147  const history = record.history ?? [];
148  const here = history.findIndex((h) => h.version === facts.version);
149  const previous = here >= 0 ? history.slice(here + 1).find((h) => h.doi) : undefined;
150  return {
151    upload_type: "publication",
152    publication_type: "other",
153    title: `${record.title} (Version ${facts.version})`,
154    description: record.description,
155    version: facts.version,
156    publication_date: facts.date,
157    creators: [{ name: `${family}, ${given}`, affiliation: creator.affiliation }],
158    access_right: "open",
159    keywords: record.methods.map((id) => /** @type {Record<string, string>} */ (METHODS)[id] ?? id),
160    related_identifiers: [
161      { identifier: `${origin}${versionPath(record.path, facts.version)}`, relation: "isAlternateIdentifier", scheme: "url" },
162      ...(previous?.doi ? [{ identifier: previous.doi, relation: "isNewVersionOf", scheme: "doi" }] : []),
163      ...record.basedOn.filter((s) => s.doi).map((s) => ({ identifier: /** @type {string} */ (s.doi), relation: "isDerivedFrom", scheme: "doi" })),
164    ],
165  };
166}