@biolibs/europepmc 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +158 -2
- package/dist/article.d.ts +162 -0
- package/dist/article.d.ts.map +1 -0
- package/dist/article.js +336 -0
- package/dist/article.js.map +1 -0
- package/dist/ask.d.ts +91 -0
- package/dist/ask.d.ts.map +1 -0
- package/dist/ask.js +105 -0
- package/dist/ask.js.map +1 -0
- package/dist/index.d.ts +33 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +33 -0
- package/dist/index.js.map +1 -0
- package/dist/search.d.ts +94 -0
- package/dist/search.d.ts.map +1 -0
- package/dist/search.js +120 -0
- package/dist/search.js.map +1 -0
- package/dist/trail.d.ts +62 -0
- package/dist/trail.d.ts.map +1 -0
- package/dist/trail.js +76 -0
- package/dist/trail.js.map +1 -0
- package/package.json +47 -4
- package/src/article.ts +368 -0
- package/src/ask.ts +139 -0
- package/src/index.ts +33 -0
- package/src/search.ts +176 -0
- package/src/trail.ts +103 -0
package/src/search.ts
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Searching the literature, and what one result says about itself.
|
|
3
|
+
*
|
|
4
|
+
* Europe PMC indexes PubMed, PubMed Central, preprints, patents and theses together, which is why
|
|
5
|
+
* it is worth asking rather than PubMed alone: a method is as likely to be in a preprint as in a
|
|
6
|
+
* journal. What matters most for reading afterwards is not in the title at all — it is whether the
|
|
7
|
+
* paper is open access and whether its full text is actually here, because that decides whether
|
|
8
|
+
* anything beyond the abstract can be read. So {@link Found.fullText} says so plainly, instead of
|
|
9
|
+
* leaving a caller to work it out from three separate flags.
|
|
10
|
+
*/
|
|
11
|
+
import { ask, EuropePmcError } from "./ask.js";
|
|
12
|
+
|
|
13
|
+
/** The most results one search gives back. */
|
|
14
|
+
export const MOST_FOUND = 100;
|
|
15
|
+
|
|
16
|
+
/** How many it gives back when nobody says. */
|
|
17
|
+
export const USUAL_FOUND = 10;
|
|
18
|
+
|
|
19
|
+
/** Which part of the literature to search. */
|
|
20
|
+
export const CORPORA = ["all", "open-access", "preprints", "reviews"] as const;
|
|
21
|
+
|
|
22
|
+
/** One of them. */
|
|
23
|
+
export type Corpus = (typeof CORPORA)[number];
|
|
24
|
+
|
|
25
|
+
/** What one result says about itself. */
|
|
26
|
+
export interface Found {
|
|
27
|
+
/** Europe PMC's own ID for it, and which index it is in: `MED`, `PMC`, `PPR` for a preprint. */
|
|
28
|
+
id: string;
|
|
29
|
+
source: string;
|
|
30
|
+
/** The PubMed ID, the PubMed Central ID and the DOI, where it has them. */
|
|
31
|
+
pmid: string | null;
|
|
32
|
+
pmcid: string | null;
|
|
33
|
+
doi: string | null;
|
|
34
|
+
/** The title, with the full stop journals put on the end taken off. */
|
|
35
|
+
title: string;
|
|
36
|
+
/** The authors, as written. */
|
|
37
|
+
authors: string[];
|
|
38
|
+
/** Where and when it was published. */
|
|
39
|
+
journal: string | null;
|
|
40
|
+
year: number | null;
|
|
41
|
+
/** The abstract, if the search was asked for one. */
|
|
42
|
+
abstract: string | null;
|
|
43
|
+
/** How many papers Europe PMC has that cite it. A rough measure of whether anybody built on it. */
|
|
44
|
+
citedBy: number;
|
|
45
|
+
/** Whether the paper is open access, and whether its full text can actually be read here. */
|
|
46
|
+
openAccess: boolean;
|
|
47
|
+
fullText: boolean;
|
|
48
|
+
/** Whether it has data, supplementary files or a reference list worth following. */
|
|
49
|
+
hasSupplement: boolean;
|
|
50
|
+
hasReferences: boolean;
|
|
51
|
+
/** Where a person would read it. */
|
|
52
|
+
lookAt: string;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** What a search found. */
|
|
56
|
+
export interface Search {
|
|
57
|
+
/** What was asked. */
|
|
58
|
+
query: string;
|
|
59
|
+
/** How many matched in all, which is usually far more than are returned. */
|
|
60
|
+
matched: number;
|
|
61
|
+
/** The results. */
|
|
62
|
+
results: Found[];
|
|
63
|
+
/** A cursor for the next page, or `null` at the end. */
|
|
64
|
+
next: string | null;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** What the service sends back, in as much shape as is read. */
|
|
68
|
+
interface RawResult {
|
|
69
|
+
[field: string]: unknown;
|
|
70
|
+
journalInfo?: { journal?: { title?: string }; yearOfPublication?: number };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const words = (value: unknown): string | null => (typeof value === "string" && value.trim() !== "" ? value.trim() : null);
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* A title with its markup gone.
|
|
77
|
+
*
|
|
78
|
+
* The service sends a title as it was typed, markup and all, so a paper about α<sub>S1</sub>-casein
|
|
79
|
+
* arrives with the tags in it. Nothing downstream renders them, so they would be read aloud.
|
|
80
|
+
*/
|
|
81
|
+
const plain = (value: unknown): string | null => {
|
|
82
|
+
const said = words(value);
|
|
83
|
+
return said === null ? null : words(said.replace(/<[^>]{0,80}>/g, ""));
|
|
84
|
+
};
|
|
85
|
+
const yes = (value: unknown): boolean => value === "Y" || value === true;
|
|
86
|
+
|
|
87
|
+
/** The authors as a list, from the one string the service writes them in. */
|
|
88
|
+
const authorsOf = (value: unknown): string[] =>
|
|
89
|
+
(words(value) ?? "").replace(/\.$/, "").split(/,\s*/).map((one) => one.trim()).filter((one) => one !== "");
|
|
90
|
+
|
|
91
|
+
/** What the query is narrowed with, for a corpus that is a filter rather than an index. */
|
|
92
|
+
const NARROWED: Readonly<Record<Corpus, string>> = {
|
|
93
|
+
all: "",
|
|
94
|
+
"open-access": "OPEN_ACCESS:Y",
|
|
95
|
+
preprints: "SRC:PPR",
|
|
96
|
+
reviews: "PUB_TYPE:\"review\"",
|
|
97
|
+
};
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* One result, read into something steady.
|
|
101
|
+
*
|
|
102
|
+
* @param raw - What the service sent for it.
|
|
103
|
+
* @returns What it says about itself.
|
|
104
|
+
*/
|
|
105
|
+
export function oneFound(raw: RawResult): Found {
|
|
106
|
+
const id = words(raw["id"]) ?? "";
|
|
107
|
+
const source = words(raw["source"]) ?? "MED";
|
|
108
|
+
const pmcid = words(raw["pmcid"]);
|
|
109
|
+
const doi = words(raw["doi"]);
|
|
110
|
+
return {
|
|
111
|
+
id, source,
|
|
112
|
+
pmid: words(raw["pmid"]), pmcid, doi,
|
|
113
|
+
// Journals put a full stop on the end of a title; it is not part of the title.
|
|
114
|
+
title: (plain(raw["title"]) ?? "Untitled").replace(/\.$/, ""),
|
|
115
|
+
authors: authorsOf(raw["authorString"]),
|
|
116
|
+
journal: words(raw["journalTitle"]) ?? words(raw.journalInfo?.journal?.title) ?? null,
|
|
117
|
+
year: typeof raw["pubYear"] === "string" && /^\d{4}$/.test(raw["pubYear"]) ? Number(raw["pubYear"])
|
|
118
|
+
: typeof raw.journalInfo?.yearOfPublication === "number" ? raw.journalInfo.yearOfPublication : null,
|
|
119
|
+
abstract: words(raw["abstractText"]),
|
|
120
|
+
citedBy: typeof raw["citedByCount"] === "number" ? raw["citedByCount"] : 0,
|
|
121
|
+
openAccess: yes(raw["isOpenAccess"]),
|
|
122
|
+
// Open access is a licence; being in Europe PMC is whether the text is here to read. Both have
|
|
123
|
+
// to hold, and a caller that is about to read a paper cares only about the second.
|
|
124
|
+
fullText: yes(raw["inEPMC"]) && pmcid !== null,
|
|
125
|
+
hasSupplement: yes(raw["hasSuppl"]) || yes(raw["hasData"]),
|
|
126
|
+
hasReferences: yes(raw["hasReferences"]),
|
|
127
|
+
lookAt: `https://europepmc.org/article/${source}/${id}`,
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Search the literature.
|
|
133
|
+
*
|
|
134
|
+
* @param query - What to look for, in Europe PMC's own syntax: plain words, phrases in quotes, and
|
|
135
|
+
* fields such as `AUTH:`, `TITLE:`, `METHODS:`, `JOURNAL:`, `PUB_YEAR:`. `AND`, `OR` and `NOT`
|
|
136
|
+
* join them.
|
|
137
|
+
* @param options - `limit` is how many to bring back; `corpus` narrows to open access, preprints or
|
|
138
|
+
* reviews; `abstracts` asks for abstracts too, which makes the reply much larger; `cursor` carries
|
|
139
|
+
* on from a previous search's `next`; `sort` is `cited`, `date` or relevance, which is the default.
|
|
140
|
+
* @returns What matched.
|
|
141
|
+
* @throws {@link EuropePmcError} if the service could not be reached or did not answer with results.
|
|
142
|
+
*
|
|
143
|
+
* @example
|
|
144
|
+
* ```ts
|
|
145
|
+
* import { searchArticles } from "@biolibs/europepmc";
|
|
146
|
+
*
|
|
147
|
+
* const found = await searchArticles('"kappa-casein" AND "Pichia pastoris"', { corpus: "open-access", abstracts: true });
|
|
148
|
+
* found.results.filter((one) => one.fullText).map((one) => one.pmcid);
|
|
149
|
+
* ```
|
|
150
|
+
*/
|
|
151
|
+
export async function searchArticles(query: string, options: {
|
|
152
|
+
limit?: number; corpus?: Corpus; abstracts?: boolean; cursor?: string; sort?: "cited" | "date" | "relevance";
|
|
153
|
+
} = {}): Promise<Search> {
|
|
154
|
+
const asked = query.trim();
|
|
155
|
+
if (asked === "") throw new EuropePmcError("There is nothing to search for.", "", null);
|
|
156
|
+
const narrowed = NARROWED[options.corpus ?? "all"];
|
|
157
|
+
const whole = narrowed === "" ? asked : `(${asked}) AND ${narrowed}`;
|
|
158
|
+
const limit = Math.max(1, Math.min(MOST_FOUND, options.limit ?? USUAL_FOUND));
|
|
159
|
+
const body = await ask("search", {
|
|
160
|
+
query: whole, format: "json", pageSize: limit,
|
|
161
|
+
resultType: options.abstracts === true ? "core" : "lite",
|
|
162
|
+
cursorMark: options.cursor ?? "*",
|
|
163
|
+
...(options.sort === "cited" ? { sort: "CITED desc" } : options.sort === "date" ? { sort: "P_PDATE_D desc" } : {}),
|
|
164
|
+
});
|
|
165
|
+
let answer: { hitCount?: number; nextCursorMark?: string; resultList?: { result?: RawResult[] } };
|
|
166
|
+
try { answer = JSON.parse(body); } catch { throw new EuropePmcError("Europe PMC sent back something that is not the answer to a search.", "search"); }
|
|
167
|
+
const results = (answer.resultList?.result ?? []).map(oneFound);
|
|
168
|
+
const next = words(answer.nextCursorMark);
|
|
169
|
+
return {
|
|
170
|
+
query: whole,
|
|
171
|
+
matched: typeof answer.hitCount === "number" ? answer.hitCount : results.length,
|
|
172
|
+
results,
|
|
173
|
+
// The service always sends a cursor, including one that would fetch the same page again.
|
|
174
|
+
next: next === null || next === (options.cursor ?? "*") || results.length < limit ? null : next,
|
|
175
|
+
};
|
|
176
|
+
}
|
package/src/trail.ts
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Following a paper backwards and forwards: what it cited, and who has cited it since.
|
|
3
|
+
*
|
|
4
|
+
* A method is almost never described where you first meet it. A paper says it expressed the gene
|
|
5
|
+
* "as described previously" and gives a number, and the number is the paper that actually has the
|
|
6
|
+
* recipe. So being able to walk the reference list is not a nicety: it is often the only way to the
|
|
7
|
+
* thing somebody is looking for. Going the other way says whether anybody managed to repeat it.
|
|
8
|
+
*/
|
|
9
|
+
import { ask, EuropePmcError } from "./ask.js";
|
|
10
|
+
|
|
11
|
+
/** The most on one page of either list. */
|
|
12
|
+
export const MOST_ON_A_PAGE = 100;
|
|
13
|
+
|
|
14
|
+
/** One paper in a trail, said the same way whichever direction it was found in. */
|
|
15
|
+
export interface Linked {
|
|
16
|
+
/** Europe PMC's ID for it, and which index it is in. */
|
|
17
|
+
id: string | null;
|
|
18
|
+
source: string | null;
|
|
19
|
+
/** Its title. */
|
|
20
|
+
title: string;
|
|
21
|
+
/** The authors, as written. */
|
|
22
|
+
authors: string;
|
|
23
|
+
/** Where and when. */
|
|
24
|
+
journal: string | null;
|
|
25
|
+
year: number | null;
|
|
26
|
+
/** Where to read it, if it has an ID to be read by. */
|
|
27
|
+
lookAt: string | null;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** One page of a trail. */
|
|
31
|
+
export interface Trail {
|
|
32
|
+
/** How many there are in all. */
|
|
33
|
+
count: number;
|
|
34
|
+
/** The ones on this page. */
|
|
35
|
+
papers: Linked[];
|
|
36
|
+
/** Which page this was, counting from 1, and whether there are more. */
|
|
37
|
+
page: number;
|
|
38
|
+
more: boolean;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const words = (value: unknown): string | null => (typeof value === "string" && value.trim() !== "" ? value.trim() : null);
|
|
42
|
+
|
|
43
|
+
/** One entry, read into something steady. */
|
|
44
|
+
function oneLinked(raw: Record<string, unknown>): Linked {
|
|
45
|
+
const id = words(raw["id"]);
|
|
46
|
+
const source = words(raw["source"]);
|
|
47
|
+
return {
|
|
48
|
+
id, source,
|
|
49
|
+
title: (words(typeof raw["title"] === "string" ? raw["title"].replace(/<[^>]{0,80}>/g, "") : raw["title"]) ?? "Untitled").replace(/\.$/, ""),
|
|
50
|
+
authors: words(raw["authorString"]) ?? "",
|
|
51
|
+
journal: words(raw["journalAbbreviation"]) ?? words(raw["journalTitle"]) ?? null,
|
|
52
|
+
year: typeof raw["pubYear"] === "number" ? raw["pubYear"]
|
|
53
|
+
: typeof raw["pubYear"] === "string" && /^\d{4}$/.test(raw["pubYear"]) ? Number(raw["pubYear"]) : null,
|
|
54
|
+
lookAt: id === null || source === null ? null : `https://europepmc.org/article/${source}/${id}`,
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** Ask for one page of a list hanging off an article. */
|
|
59
|
+
async function page(which: "references" | "citations", source: string, id: string, options: { page?: number; limit?: number }): Promise<Trail> {
|
|
60
|
+
const index = source.trim().toUpperCase();
|
|
61
|
+
if (!/^[A-Z]{3,4}$/.test(index)) throw new EuropePmcError(`${JSON.stringify(source)} is not an index. It is MED for PubMed, PMC, or PPR for a preprint.`, which);
|
|
62
|
+
if (!/^[A-Za-z0-9.]{1,20}$/.test(id.trim())) throw new EuropePmcError(`${JSON.stringify(id)} is not an article ID.`, which);
|
|
63
|
+
const size = Math.max(1, Math.min(MOST_ON_A_PAGE, options.limit ?? 25));
|
|
64
|
+
const wanted = Math.max(1, options.page ?? 1);
|
|
65
|
+
const body = await ask(`${index}/${id.trim()}/${which}`, { format: "json", pageSize: size, page: wanted });
|
|
66
|
+
let answer: { hitCount?: number; referenceList?: { reference?: Record<string, unknown>[] }; citationList?: { citation?: Record<string, unknown>[] } };
|
|
67
|
+
try { answer = JSON.parse(body); } catch { throw new EuropePmcError(`Europe PMC sent back something that is not a list of ${which}.`, which); }
|
|
68
|
+
const papers = (answer.referenceList?.reference ?? answer.citationList?.citation ?? []).map(oneLinked);
|
|
69
|
+
const count = typeof answer.hitCount === "number" ? answer.hitCount : papers.length;
|
|
70
|
+
return { count, papers, page: wanted, more: wanted * size < count };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* What a paper cited.
|
|
75
|
+
*
|
|
76
|
+
* @param source - Which index it is in: `MED`, `PMC` or `PPR`.
|
|
77
|
+
* @param id - Its ID in that index.
|
|
78
|
+
* @param options - `page` counts from 1; `limit` is how many on a page.
|
|
79
|
+
* @returns One page of its reference list.
|
|
80
|
+
* @throws {@link EuropePmcError} if it could not be asked for.
|
|
81
|
+
*
|
|
82
|
+
* @example
|
|
83
|
+
* ```ts
|
|
84
|
+
* import { referencesOf } from "@biolibs/europepmc";
|
|
85
|
+
*
|
|
86
|
+
* const back = await referencesOf("MED", "40723902");
|
|
87
|
+
* back.papers.filter((one) => /casein/i.test(one.title));
|
|
88
|
+
* ```
|
|
89
|
+
*/
|
|
90
|
+
export const referencesOf = (source: string, id: string, options: { page?: number; limit?: number } = {}): Promise<Trail> =>
|
|
91
|
+
page("references", source, id, options);
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Who has cited a paper since.
|
|
95
|
+
*
|
|
96
|
+
* @param source - Which index it is in.
|
|
97
|
+
* @param id - Its ID in that index.
|
|
98
|
+
* @param options - `page` counts from 1; `limit` is how many on a page.
|
|
99
|
+
* @returns One page of the papers citing it, the most recent first as the service gives them.
|
|
100
|
+
* @throws {@link EuropePmcError} if it could not be asked for.
|
|
101
|
+
*/
|
|
102
|
+
export const citationsOf = (source: string, id: string, options: { page?: number; limit?: number } = {}): Promise<Trail> =>
|
|
103
|
+
page("citations", source, id, options);
|