PubMed Client - Node.js Native Bindings

Native Node.js bindings for the PubMed and PMC (PubMed Central) API client, built with napi-rs.

Overview

This package provides high-performance native Node.js bindings to the Rust-based PubMed client library. Unlike WASM bindings, native bindings offer better performance and seamless integration with the Node.js ecosystem.

Features

• PubMed Search: Search and retrieve article metadata from PubMed
• PMC Full-Text: Access full-text articles from PubMed Central
• Markdown Conversion: Convert PMC articles to well-formatted Markdown
• SearchQuery Builder: Build complex queries programmatically with filters
• High Performance: Native Rust bindings via napi-rs
• TypeScript Support: Full type definitions included
• Cross-Platform: Pre-built binaries for Windows, macOS, and Linux (x64/ARM64)

Installation

npm install pubmed-client
# or
pnpm add pubmed-client
# or
yarn add pubmed-client

Quick Start

Basic Search

import { PubMedClient } from 'pubmed-client';

const client = new PubMedClient();

// Search for articles
const articles = await client.search('COVID-19 vaccine', 10);

for (const article of articles) {
  console.log(`[${article.pmid}] ${article.title}`);
  console.log(`  Journal: ${article.journal}`);
  console.log(`  Authors: ${article.authors.map(a => a.fullName).join(', ')}`);
}

With Configuration

import { PubMedClient, type Config } from 'pubmed-client';

const config: Config = {
  apiKey: process.env.NCBI_API_KEY,     // Optional: increases rate limit to 10 req/s
  email: '[email protected]',       // Recommended by NCBI
  tool: 'my-app',                        // Your application name
  timeoutSeconds: 30,                    // Request timeout
};

const client = PubMedClient.withConfig(config);

Fetch Single Article

const article = await client.fetchArticle('31978945');

console.log(`Title: ${article.title}`);
console.log(`Abstract: ${article.abstractText}`);
console.log(`DOI: ${article.doi}`);
console.log(`Keywords: ${article.keywords.join(', ')}`);

Fetch PMC Full-Text

// Check if PMC full-text is available
const pmcId = await client.checkPmcAvailability('31978945');

if (pmcId) {
  // Fetch full-text article
  const fullText = await client.fetchPmcArticle(pmcId);

  console.log(`Title: ${fullText.title}`);
  console.log(`Sections: ${fullText.sections.length}`);
  console.log(`References: ${fullText.references.length}`);

  // Access sections
  for (const section of fullText.sections) {
    console.log(`Section: ${section.title}`);
    console.log(`Content: ${section.content.substring(0, 200)}...`);
  }
}

Convert to Markdown

import { type MarkdownOptions } from 'pubmed-client';

const options: MarkdownOptions = {
  includeMetadata: true,
  includeToc: true,
  useYamlFrontmatter: true,
  includeOrcidLinks: true,
  includeFigureCaptions: true,
};

const markdown = await client.fetchPmcAsMarkdown('PMC7906746', options);
console.log(markdown);

Using SearchQuery Builder

The SearchQuery builder provides a fluent API for constructing complex PubMed queries:

import { PubMedClient, SearchQuery } from 'pubmed-client';

const client = new PubMedClient();

// Build a complex query
const query = new SearchQuery()
  .query('cancer')
  .publishedBetween(2020, 2024)
  .articleType('Clinical Trial')
  .freeFullTextOnly()
  .setLimit(50);

// Execute the query
const articles = await client.executeQuery(query);

Date Filtering

// Published in a specific year
const query = new SearchQuery()
  .query('diabetes')
  .publishedInYear(2024);

// Published between years
const query2 = new SearchQuery()
  .query('treatment')
  .publishedBetween(2020, 2024);

// Published after a year
const query3 = new SearchQuery()
  .query('CRISPR')
  .publishedAfter(2020);

Article Type Filtering

// Supported types: "Clinical Trial", "Review", "Systematic Review",
// "Meta-Analysis", "Case Reports", "RCT", "Observational Study"

const query = new SearchQuery()
  .query('cancer')
  .articleTypes(['RCT', 'Meta-Analysis']);

MeSH Terms and Advanced Filters

const query = new SearchQuery()
  .meshTerm('Neoplasms')
  .meshMajorTopic('Diabetes Mellitus, Type 2')
  .meshSubheading('drug therapy')
  .author('Smith J')
  .firstAuthor('Williams K')
  .affiliation('Harvard Medical School')
  .journal('Nature')
  .language('English')
  .humanStudiesOnly()
  .hasAbstract();

Boolean Logic

// AND combination
const q1 = new SearchQuery().query('covid-19');
const q2 = new SearchQuery().query('vaccine');
const combined = q1.and(q2);
combined.build(); // "(covid-19) AND (vaccine)"

// OR combination
const either = q1.or(q2);
either.build(); // "(covid-19) OR (vaccine)"

// Exclusion
const base = new SearchQuery().query('cancer treatment');
const exclude = new SearchQuery().query('animal studies');
const filtered = base.exclude(exclude);
filtered.build(); // "(cancer treatment) NOT (animal studies)"

API Reference

PubMedClient

| Method | Description | | ------------------------------------- | ----------------------------------------- | | new PubMedClient() | Create client with default configuration | | PubMedClient.withConfig(config) | Create client with custom configuration | | search(query, limit?) | Search PubMed and return articles | | fetchArticle(pmid) | Fetch single article by PMID | | fetchPmcArticle(pmcid) | Fetch full-text article from PMC | | fetchPmcAsMarkdown(pmcid, options?) | Fetch PMC article as Markdown | | checkPmcAvailability(pmid) | Check if PMC full-text is available | | executeQuery(searchQuery) | Execute a SearchQuery and return articles |

SearchQuery Builder

| Method | Description | | ------------------------------- | --------------------------------- | | query(term) | Add search term | | terms(terms[]) | Add multiple search terms | | setLimit(n) | Set maximum results | | build() | Build final query string | | publishedInYear(year) | Filter by publication year | | publishedBetween(start, end?) | Filter by date range | | publishedAfter(year) | Filter to articles after year | | publishedBefore(year) | Filter to articles before year | | articleType(type) | Filter by article type | | articleTypes(types[]) | Filter by multiple article types | | language(lang) | Filter by language | | freeFullTextOnly() | Filter to open access articles | | fullTextOnly() | Filter to articles with full text | | pmcOnly() | Filter to PMC articles | | hasAbstract() | Filter to articles with abstracts | | titleContains(text) | Search in titles | | abstractContains(text) | Search in abstracts | | titleOrAbstract(text) | Search in title or abstract | | journal(name) | Filter by journal | | meshTerm(term) | Filter by MeSH term | | meshMajorTopic(term) | Filter by MeSH major topic | | meshTerms(terms[]) | Filter by multiple MeSH terms | | author(name) | Filter by author | | firstAuthor(name) | Filter by first author | | lastAuthor(name) | Filter by last author | | affiliation(institution) | Filter by affiliation | | orcid(id) | Filter by ORCID | | humanStudiesOnly() | Filter to human studies | | animalStudiesOnly() | Filter to animal studies | | and(other) | Combine with AND logic | | or(other) | Combine with OR logic | | exclude(other) | Exclude matching articles | | negate() | Negate the query | | group() | Add parentheses for grouping |

Data Types

Article

interface Article {
  pmid: string;
  title: string;
  authors: Author[];
  journal: string;
  pubDate: string;
  doi?: string;
  pmcId?: string;
  abstractText?: string;
  articleTypes: string[];
  keywords: string[];
}

FullTextArticle

interface FullTextArticle {
  pmcid: string;
  pmid?: string;
  title: string;
  authors: Author[];
  journal: string;
  pubDate: string;
  doi?: string;
  sections: Section[];
  references: Reference[];
  keywords: string[];
}

Author

interface Author {
  fullName: string;
  orcid?: string;
  affiliation?: string;
}

Platform Support

Pre-built binaries are available for:

| Platform | Architecture | | ------------- | -------------------------- | | Windows | x64 | | macOS | x64, ARM64 (Apple Silicon) | | Linux (glibc) | x64, ARM64 | | Linux (musl) | x64, ARM64 |

Development

Prerequisites

• Node.js >= 16
• Rust toolchain
• pnpm

Setup

cd pubmed-client-napi
pnpm install

Build

# Development build
pnpm run build:debug

# Release build
pnpm run build

Test

pnpm test

Code Quality

pnpm run lint       # Run linter
pnpm run format     # Format code
pnpm run typecheck  # TypeScript check

License

MIT

Links

• Repository
• npm Package
• Core Rust Library
• WebAssembly Bindings
• Python Bindings
• NCBI E-utilities Documentation