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

Note 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 be non functional):
// 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.returnedErrors) {
      console.error(returnedError);
    }
  }
}

Warning When using an AbortSignal with any list method (listIdentifiers, listRecords, listSets), there will be some 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. This is a fetch API limitation, issue.

General shape of parsed data

type TransformedParsedXMLValue = {
  // 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 | TransformedParsedXML;
};

type TransformedParsedXML = Record<string, TransformedParsedXMLValue[]>;

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