aur-rpc-wrapper

A robust, fully-typed Node.js wrapper for Arch-based systems: parses pacman -Qi output and queries the Arch User Repository (AUR) RPC API, returning clean, strictly-typed JSON.

This package talks to the system's own pacman/vercmp binaries and the official AUR RPC endpoint — no bundled binary, no Python dependency. It only runs on Arch-based systems (Arch Linux, CachyOS, Manjaro, EndeavourOS, ...).

Installation

npm install aur-rpc-wrapper

Usage Guide

The API is fully Promise-based and returns strictly typed objects.

1. Fetching Installed Package Info

The pacman.getInstalledPackage method parses pacman -Qi for one package into a clean object.

import aur from 'aur-rpc-wrapper';

async function fetchInfo() {
  const pkg = await aur.pacman.getInstalledPackage('linux');

  console.log(pkg.version);     // 6.11.6.arch1-1
  console.log(pkg.dependsOn);   // ['coreutils', 'kmod', 'initramfs']
}

JSON Output Structure Example:

{
  "name": "yay",
  "version": "12.3.5-1",
  "description": "Yet another yogurt. Pacman wrapper and AUR helper written in go.",
  "architecture": "x86_64",
  "url": "https://github.com/Jguer/yay",
  "licenses": ["GPL3"],
  "dependsOn": ["pacman", "git"],
  "optionalDeps": [],
  "requiredBy": [],
  "installedSize": "9.85 MiB",
  "installReason": "Explicitly installed"
}

2. Listing Every Installed Package

import aur from 'aur-rpc-wrapper';

const packages = await aur.pacman.getInstalledPackages();
console.log(packages.length);

3. Listing Installed AUR/Foreign Packages

pacman -Qm lists packages not found in any sync database — i.e. AUR packages and other manually built ones.

import aur from 'aur-rpc-wrapper';

const foreign = await aur.pacman.getForeignPackages();
foreign.forEach(pkg => console.log(pkg.name, pkg.version));

4. Querying the AUR RPC for Package Info

import aur from 'aur-rpc-wrapper';

async function fetchAurInfo() {
  const pkg = await aur.rpc.getPackage('yay');

  console.log(pkg.Version);      // 12.3.5-1
  console.log(pkg.NumVotes);     // 1234
  console.log(pkg.Maintainer);   // Jguer
}

5. Batch Lookups

rpc.info looks up many packages in as few requests as possible, splitting large lists into multiple RPC calls automatically.

import aur from 'aur-rpc-wrapper';

const packages = await aur.rpc.info(['yay', 'paru', 'visual-studio-code-bin']);

6. Searching the AUR

import aur from 'aur-rpc-wrapper';

const results = await aur.rpc.search('spotify', { by: 'name-desc' });
results.forEach(pkg => console.log(pkg.Name, pkg.Description));

7. Fetching Dependencies

Both a local (installed) view and a remote (AUR, pre-install) view are available.

import aur from 'aur-rpc-wrapper';

const installedDeps = await aur.pacman.getDependencies('yay');       // from pacman -Qi
const buildDeps = await aur.rpc.getDependencies('yay-bin');          // Depends + MakeDepends + CheckDepends

8. Checking for AUR Updates

Compares every installed AUR/foreign package against its current AUR version using vercmp, without needing a full AUR helper like yay or paru.

import aur from 'aur-rpc-wrapper';

const updates = await aur.checkUpdates();
updates.forEach(u => console.log(`${u.name}: ${u.installedVersion} -> ${u.aurVersion}`));

const single = await aur.checkUpdate('yay');
if (single) console.log('Update available:', single.aurVersion);

9. Watching for New Updates

Polls installed AUR packages and calls onUpdate for each newly detected update; already-notified (package, version) pairs aren't repeated on later polls.

import aur from 'aur-rpc-wrapper';

const stop = aur.watchUpdates(
  (update) => console.log(`Update available: ${update.name} ${update.aurVersion}`),
  { intervalMs: 30 * 60_000 }
);

// later, to stop polling:
stop();

10. Batch Package Lookups with Bounded Concurrency

import aur from 'aur-rpc-wrapper';

const results = await aur.batchGetPackages(['yay', 'paru', 'not-a-real-package'], { concurrency: 5 });

for (const r of results) {
  if (r.status === 'fulfilled') console.log(r.key, r.value.Version);
  else console.warn(r.key, r.reason.message);
}

11. Cancelling In-Flight Requests

Every method accepts an AbortSignal via options.signal.

import aur from 'aur-rpc-wrapper';

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

await aur.rpc.search('firefox', { signal: controller.signal });

12. Global RPC Options (custom endpoint, timeout, batch size)

Pass options to the Aur constructor to configure the underlying AurRpc client.

import { Aur } from 'aur-rpc-wrapper';

const aur = new Aur({
  timeoutMs: 10_000,
  maxBatchSize: 100,
});

13. Typed Errors

Failures are classified into specific error subclasses so callers can branch on why a call failed.

import aur, { PackageNotFoundError, PacmanNotFoundError, RateLimitedError } from 'aur-rpc-wrapper';

try {
  await aur.pacman.getInstalledPackage('not-installed-package');
} catch (err) {
  if (err instanceof PackageNotFoundError) {
    // not installed
  } else if (err instanceof PacmanNotFoundError) {
    // not an Arch-based system
  }
  throw err;
}

14. Raw Pacman Access

import aur from 'aur-rpc-wrapper';

const out = await aur.pacman.exec(['-Qi', 'yay']);

API Reference

• new Aur(globalOptions?: GlobalOptions) Creates a wrapper instance combining pacman and rpc. globalOptions (baseUrl, timeoutMs, maxBatchSize, userAgent) apply to every AUR RPC call.

• aur.pacman: Pacman Local pacman query client. See methods below.

• aur.rpc: AurRpc Remote AUR RPC client. See methods below.

• aur.checkUpdates(options?: AurRpcOptions): Promise<UpdateInfo[]> Compares every installed AUR/foreign package against its AUR version and returns those with an update available.

• aur.checkUpdate(name: string, options?: AurRpcOptions): Promise<UpdateInfo | null> Checks a single installed package for an available AUR update.

• aur.batchGetPackages(names: string[], options?: BatchOptions): Promise<BatchResult<AurPackage>[]> Fetches many AUR package records with bounded concurrency; each name resolves independently.

• aur.watchUpdates(onUpdate: (update: UpdateInfo) => void, options?: WatchUpdatesOptions): () => void Polls for AUR updates and invokes onUpdate for each newly detected one. Returns a stop function.

Pacman

• pacman.version(): Promise<string>
• pacman.getInstalledPackage(name: string, options?: PacmanOptions): Promise<PacmanPackage>
• pacman.getInstalledPackages(options?: PacmanOptions): Promise<PacmanPackage[]>
• pacman.getForeignPackages(options?: PacmanOptions): Promise<ForeignPackage[]>
• pacman.getDependencies(name: string, options?: PacmanOptions): Promise<string[]>
• pacman.exec(args: string[], signal?: AbortSignal): Promise<string>

AurRpc

• rpc.info(names: string[], options?: AurRpcOptions): Promise<AurPackage[]>
• rpc.getPackage(name: string, options?: AurRpcOptions): Promise<AurPackage>
• rpc.search(query: string, options?: AurSearchOptions): Promise<AurPackage[]>
• rpc.getDependencies(name: string, options?: AurRpcOptions): Promise<string[]>

License

MIT