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, minimum 18.0.0 is required, and this is an ESM only package, read more here and maybe here.

Example

// Node.js
import { OAIPMH, OAIPMHError, ParsedOAIPMHError } from "oai_pmh_v2";
// Deno
import {
  OAIPMH,
  OAIPMHError,
  ParsedOAIPMHError,
} from "https://deno.land/x/oai_pmh_v2/src/mod.ts";

// 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",
});

try {
  for await (
    const values of oaiPMH.listIdentifiers(
      { metadataPrefix: "marc21", from: "2015-08-03", until: "2016-05-30" },
      { signal: AbortSignal.timeout(20_000) },
    )
  ) {
    console.log(JSON.stringify(values));
  }

  const info = await oaiPMH.identify();

  console.log(info);
} catch (error: unknown) {
  console.error(error);

  if (
    error instanceof OAIPMHError && error.cause instanceof ParsedOAIPMHError
  ) {
    // this means there are specific errors returned by the OAI-PMH provider
    for (const returnedError of error.cause.cause) {
      console.error(returnedError);
    }
  }
}

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.