app/lib/publications/cited-by.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/lib/publications/compile.mjs, app/lib/publications/save.server.ts, app/routes/publications.$slug.tsx.

Source

1// The shape is declared once here: the JSON import's literal type cannot be indexed by a string. null
2// (never fetched) and total 0 (fetched, uncited) are different facts.
3
4/**
5 * @typedef {object} CitingWork
6 * @property {string | null} title
7 * @property {number | null} year
8 * @property {string | null} venue
9 * @property {string | null} doi bare DOI name, not a URL
10 */
11
12/**
13 * @typedef {object} CitedBy
14 * @property {string | null} openalexId
15 * @property {number} total the TRUE count, which may exceed `citing.length`
16 * @property {CitingWork[]} citing newest first, capped by the artifact
17 */
18
19/**
20 * @param {unknown} artifact the parsed publications.cited-by.json
21 * @param {string} doi as deposited
22 * @returns {CitedBy | null}
23 */
24export function citedByFor(artifact, doi) {
25  const works = /** @type {{ works?: Record<string, CitedBy> }} */ (artifact)?.works;
26  if (!works || typeof works !== "object") return null;
27  // Own property only: a DOI spelled like constructor would return a function.
28  if (!Object.hasOwn(works, doi)) return null;
29  const entry = works[doi];
30  if (!entry || typeof entry !== "object") return null;
31  return {
32    openalexId: entry.openalexId ?? null,
33    total: Number(entry.total ?? 0),
34    citing: Array.isArray(entry.citing) ? entry.citing : [],
35  };
36}
37
38/**
39 * @param {unknown} artifact
40 * @returns {string | null}
41 */
42export function citedByFetchedAt(artifact) {
43  const value = /** @type {{ fetchedAt?: unknown }} */ (artifact)?.fetchedAt;
44  return typeof value === "string" && value.length > 0 ? value : null;
45}
46
47/**
48 * The citation counts an OpenAlex snapshot holds, as publication_citations rows, so a count is never blank on
49 * a database that has none yet. The lower-cased DOI is the key, as the table keys it. sync:content and the
50 * Worker's sync_publications both seed from here.
51 *
52 * @param {unknown} artifact the parsed publications.cited-by.json
53 * @param {string} source what to call the artifact in the error
54 * @returns {Array<{ doi: string, count: number, url: string | null, fetchedAt: string }>}
55 */
56export function citationSeedsFrom(artifact, source) {
57  const { fetchedAt, works } = /** @type {{ fetchedAt?: unknown, works?: Record<string, { openalexId?: string | null, total?: number }> }} */ (artifact);
58  if (typeof fetchedAt !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(fetchedAt) || !works) {
59    throw new Error(`${source} carries no fetchedAt date or no works, so the citation counts cannot be seeded.`);
60  }
61  return Object.entries(works).map(([doi, work]) => ({
62    doi: doi.trim().toLowerCase(),
63    count: Number(work.total ?? 0),
64    url: work.openalexId ? `https://openalex.org/${work.openalexId}` : null,
65    fetchedAt,
66  }));
67}