OAI-PMH TypeScript client

It's an OAI-PMH Version 2.0 API client package/module for Node.js and Deno.

Installing (Node.js)

npm i oai_pmh_v2

Important

For Node.js users a fetch compatible version of the runtime is required, or a polyfill otherwise (like node-fetch).

Example

Note

It is possible to iterate through the generator with a for...of loop, but this way we can only acquire the yield -ed values of the generator, the return -ed value would be lost, and the return -ed value contains the potential error.

// `... from "npm:oai_pmh_v2"` for Deno
import { OAIPMH, STATUS } from "oai_pmh_v2";

// you can find OAI-PMH providers here (although a lot of them might not work):
// https://www.openarchives.org/Register/BrowseSites
const oaiPMH = new OAIPMH({
  baseURL:
    "http://bibliotecavirtual.asturias.es/i18n/oai/oai_bibliotecavirtual.asturias.es.cmd",
});

const g = oaiPMH.listIdentifiers(
  { metadataPrefix: "marc21", from: "2015-04-10", until: "2015-10-28" },
  { signal: AbortSignal.timeout(30_000) },
);

for (;;) {
  const { done, value: gVal } = await g.next();

  if (done) {
    // there are no more values yielded by the generator
    const { status, value } = gVal;

    if (status !== STATUS.OK) {
      // handle error, we can narrow error type by checking
      // against specific values of `STATUS` enum
      console.error(value);
    }

    // break out of loop as there are no more yielded values
    break;
  }

  console.log(JSON.stringify(gVal));
}

Warning

When using an AbortSignal with any list method (listIdentifiers, listRecords, listSets), there will be some minuscule memory leak until the loop exits. This is because for each request there is an additional listener registered for the signal. Specifically in Node.js this will cause a lot of warnings (after 100 or so loops). This is a fetch API spec limitation, see issue.

General shape of parsed data

type ParsedXMLRecordValue = {
  // index in XML tree branch, for preserving order of elements
  i: number;
  // XML attributes
  attr?: Record<string, string>;
  // either a text value, another branch of the XML tree,
  // or undefined in case of an empty XML element
  val?: string | ParsedXML;
};

type ParsedXML = Record<string, ParsedXMLRecordValue[]>;

Find examples for all methods in examples directory. Documentation via types.