@agntn/registries 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present oritwoen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# @agntn/registries
+
+[![npm version](https://img.shields.io/npm/v/%40agntn%2Fregistries?style=flat&colorA=130f40&colorB=474787)](https://npmjs.com/package/@agntn/registries)
+[![npm downloads](https://img.shields.io/npm/dm/%40agntn%2Fregistries?style=flat&colorA=130f40&colorB=474787)](https://npm.chart.dev/@agntn/registries)
+[![license](https://img.shields.io/github/license/agntn/registries?style=flat&colorA=130f40&colorB=474787)](https://github.com/agntn/registries/blob/main/LICENSE)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/agntn/registries)
+
+> Query npm, PyPI, crates.io, RubyGems, Packagist, and Arch Linux with one API. PURL-native, typed, cached.
+
+## Why?
+
+If you need package metadata from multiple registries, you currently have two options: call each registry's REST API yourself (they all work differently), or depend on a third-party aggregation service.
+
+There is no embeddable TypeScript library that normalizes across registries. The closest thing is [git-pkgs/registries](https://github.com/git-pkgs/registries) in Go, which covers 25 ecosystems but is Go-only. Aggregation APIs like [ecosyste.ms](https://ecosyste.ms/) and [deps.dev](https://deps.dev/) exist, but they are external services you can't bundle into your own tool.
+
+@agntn/registries fills that gap. One `fetchPackage` call, same response shape, regardless of whether the package lives on npm or Packagist. Uses [PURL (ECMA-427)](https://github.com/package-url/purl-spec) for addressing, so `pkg:npm/lodash` and `pkg:cargo/serde` resolve through the same code path. Storage-backed caching with a lockfile keeps things fast on repeated lookups.
+
+## Features
+
+- 🔍 **Single API, six registries** - npm, PyPI, crates.io, RubyGems, Packagist, Arch Linux (official + AUR)
+- 📦 **PURL-native** - [ECMA-427](https://github.com/package-url/purl-spec) identifiers as first-class input
+- 🏷️ **Normalized data model** - same `Package`, `Version`, `Dependency`, `Maintainer` types everywhere
+- 💾 **Storage-backed cache + lockfile** - unstorage-native, sha256 integrity checks, configurable TTL
+- ⌨️ **CLI included** - `registries info npm/lodash`, `registries versions cargo/serde`, `registries deps pypi/flask@3.1.1`
+- 🔁 **Retry + backoff** - exponential backoff with jitter, rate limiter interface
+- 🪶 **ESM-only, zero CJS** - built with [obuild](https://github.com/unjs/obuild)
+
+## Install
+
+```bash
+pnpm add @agntn/registries
+```
+
+For the AI SDK tool (`@agntn/registries/ai` subpath), also install `ai` and `zod`:
+
+```bash
+pnpm add ai zod
+```
+
+## Quick start
+
+### API
+
+```ts
+import { fetchPackageFromPURL } from "@agntn/registries";
+
+const pkg = await fetchPackageFromPURL("pkg:npm/lodash");
+
+console.log(pkg.name); // "lodash"
+console.log(pkg.latestVersion); // "4.17.23"
+console.log(pkg.licenses); // "MIT"
+console.log(pkg.repository); // "https://github.com/lodash/lodash"
+```
+
+Works the same for any supported registry:
+
+```ts
+await fetchPackageFromPURL("pkg:cargo/serde");
+await fetchPackageFromPURL("pkg:pypi/flask");
+await fetchPackageFromPURL("pkg:gem/rails");
+await fetchPackageFromPURL("pkg:composer/laravel/framework");
+await fetchPackageFromPURL("pkg:alpm/arch/pacman");
+```
+
+### CLI
+
+The `pkg:` prefix is optional in the CLI. `npm/lodash` works just as well:
+
+```bash
+registries info npm/lodash
+registries versions cargo/serde
+registries deps pypi/flask@3.1.1
+registries maintainers gem/rails
+registries deps alpm/aur/paru
+```
+
+Add `--json` for machine-readable output, `--no-cache` to skip the cache.
+
+### AI SDK tool
+
+`@agntn/registries/ai` exports a ready-made tool for AI SDK apps:
+
+```ts
+import { generateText } from "ai";
+import { packageTool } from "@agntn/registries/ai";
+
+const { text } = await generateText({
+  model: yourModel,
+  tools: { packageRegistry: packageTool },
+  prompt: "Show me the latest metadata for pkg:npm/lodash and then list its maintainers.",
+});
+```
+
+The tool supports these operations through one input schema:
+
+```ts
+// { operation: 'package', purl: 'pkg:npm/lodash' }
+// { operation: 'versions', purl: 'pkg:cargo/serde' }
+// { operation: 'dependencies', purl: 'pkg:pypi/flask@3.1.1' }
+// { operation: 'maintainers', purl: 'pkg:gem/rails' }
+// { operation: 'bulk-packages', purls: ['pkg:npm/lodash', 'pkg:cargo/serde'], concurrency?: number }
+```
+
+## Registries
+
+| Ecosystem  | PURL type          | Registry                         |
+| ---------- | ------------------ | -------------------------------- |
+| npm        | `pkg:npm/...`      | registry.npmjs.org               |
+| Cargo      | `pkg:cargo/...`    | crates.io                        |
+| PyPI       | `pkg:pypi/...`     | pypi.org                         |
+| RubyGems   | `pkg:gem/...`      | rubygems.org                     |
+| Packagist  | `pkg:composer/...` | packagist.org                    |
+| Arch Linux | `pkg:alpm/...`     | archlinux.org, aur.archlinux.org |
+
+Scoped packages work as expected: `pkg:npm/%40vue/core` or `npm/@vue/core` in the CLI.
+
+Arch Linux packages use a namespace: `pkg:alpm/arch/pacman` (or just `pkg:alpm/pacman`) for official repos, `pkg:alpm/aur/paru` for AUR. Official packages default to `arch` when the namespace is omitted; AUR requires the explicit `aur` namespace.
+
+## API reference
+
+### PURL helpers
+
+```ts
+import {
+  fetchPackageFromPURL,
+  fetchVersionsFromPURL,
+  fetchDependenciesFromPURL,
+  fetchMaintainersFromPURL,
+  bulkFetchPackages,
+} from "@agntn/registries";
+
+// Single lookups
+const pkg = await fetchPackageFromPURL("pkg:npm/lodash");
+const versions = await fetchVersionsFromPURL("pkg:cargo/serde");
+const deps = await fetchDependenciesFromPURL("pkg:pypi/flask@3.1.1");
+const maintainers = await fetchMaintainersFromPURL("pkg:gem/rails");
+
+// Bulk - fetches up to 15 packages concurrently
+const packages = await bulkFetchPackages(["pkg:npm/lodash", "pkg:cargo/serde", "pkg:pypi/flask"]);
+```
+
+### Direct registry access
+
+For more control, instantiate a concrete registry class:
+
+```ts
+import { Client } from "@agntn/registries";
+import { NpmRegistry } from "@agntn/registries";
+
+const npm = new NpmRegistry("https://registry.npmjs.org", new Client());
+const pkg = await npm.fetchPackage("lodash");
+const versions = await npm.fetchVersions("lodash");
+const deps = await npm.fetchDependencies("lodash", "4.17.21");
+```
+
+Use `create("npm")` when you prefer lookup through the registered ecosystem classes.
+
+### Cached registry
+
+Wrap any registry with caching:
+
+```ts
+import { createCached } from "@agntn/registries";
+
+const npm = createCached("npm");
+
+// First call hits the network and writes to cache
+const pkg = await npm.fetchPackage("lodash");
+
+// Second call reads from cache (if TTL hasn't expired)
+const same = await npm.fetchPackage("lodash");
+```
+
+By default, @agntn/registries uses filesystem storage and follows platform cache conventions: `~/.cache/registries` on Linux (XDG), `~/Library/Caches/registries` on macOS, `%LOCALAPPDATA%\registries\cache` on Windows. Override with `REGISTRIES_CACHE_DIR` env var.
+
+For edge/serverless runtimes, configure a custom unstorage driver (example: Cloudflare KV binding):
+
+```ts
+import { configureStorage, createCached } from "@agntn/registries";
+import { createStorage } from "unstorage";
+import cloudflareKVBindingDriver from "unstorage/drivers/cloudflare-kv-binding";
+
+configureStorage(
+  createStorage({
+    driver: cloudflareKVBindingDriver({ binding: "REGISTRIES_CACHE" }),
+  }),
+);
+
+const npm = createCached("npm");
+const pkg = await npm.fetchPackage("lodash");
+```
+
+### PURL parsing
+
+```ts
+import { parsePURL, buildPURL, fullName } from "@agntn/registries";
+
+const parsed = parsePURL("pkg:npm/%40vue/core@3.5.0");
+// { type: 'npm', namespace: '@vue', name: 'core', version: '3.5.0', qualifiers: {}, subpath: '' }
+
+fullName(parsed); // "@vue/core"
+
+buildPURL({ type: "cargo", name: "serde", version: "1.0.0" });
+// "pkg:cargo/serde@1.0.0"
+```
+
+### Types
+
+```ts
+import type {
+  Package,
+  Version,
+  Dependency,
+  Maintainer,
+  Registry,
+  ParsedPURL,
+} from "@agntn/registries";
+```
+
+## CLI
+
+```bash
+registries <command> [options]
+```
+
+| Command                         | Description                                            |
+| ------------------------------- | ------------------------------------------------------ |
+| `registries info <purl>`        | Package metadata (name, license, repo, latest version) |
+| `registries versions <purl>`    | List all published versions                            |
+| `registries deps <purl>`        | Dependencies for a specific version                    |
+| `registries maintainers <purl>` | Package maintainers / authors                          |
+| `registries cache status`       | Show cache stats (entries, freshness)                  |
+| `registries cache path`         | Print cache directory path                             |
+| `registries cache clear`        | Remove all cached data                                 |
+| `registries cache prune`        | Remove stale entries                                   |
+
+### Options
+
+| Flag         | Description                              |
+| ------------ | ---------------------------------------- |
+| `--json`     | Output as JSON                           |
+| `--no-cache` | Bypass cache, always fetch from registry |
+
+## Caching
+
+@agntn/registries stores fetched data and freshness metadata in unstorage. Default TTLs:
+
+| Data type        | TTL        |
+| ---------------- | ---------- |
+| Package metadata | 1 hour     |
+| Version list     | 30 minutes |
+| Dependencies     | 24 hours   |
+| Maintainers      | 24 hours   |
+
+Each cached entry has a sha256 integrity hash. If the stored data doesn't match the hash, @agntn/registries refetches automatically.
+
+## Data model
+
+Every registry returns the same normalized types:
+
+```ts
+interface Package {
+  name: string;
+  description: string;
+  homepage: string;
+  documentation: string; // docs URL (docs.rs, readthedocs, rubydoc, etc.)
+  repository: string;
+  licenses: string; // SPDX-normalized
+  keywords: string[];
+  namespace: string; // e.g. "@vue" for npm scoped packages
+  latestVersion: string;
+  metadata: Record<string, unknown>;
+}
+
+interface Version {
+  number: string;
+  publishedAt: Date | null;
+  licenses: string;
+  integrity: string;
+  status: "" | "yanked" | "deprecated" | "retracted";
+  metadata: Record<string, unknown>;
+}
+
+interface Dependency {
+  name: string;
+  requirements: string; // version constraint
+  scope: "runtime" | "development" | "test" | "build" | "optional";
+  optional: boolean;
+}
+
+interface Maintainer {
+  uuid: string;
+  login: string;
+  name: string;
+  email: string;
+  url: string;
+  role: string;
+}
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/_chunks/cached-registry.d.mts

@@ -0,0 +1,35 @@
+import { c as URLBuilder, i as Package, l as Version, n as Dependency, r as Maintainer } from "./types.mjs";
+import { t as Registry } from "./registry.mjs";
+import { Storage } from "unstorage";
+
+//#region src/cache/cached-registry.d.ts
+/**
+ * CachedRegistry wraps any Registry and adds caching backed by unstorage
+ * with a lockfile for freshness tracking.
+ *
+ * Pass a custom `storage` to use a non-default driver (e.g. Cloudflare KV).
+ * If omitted, uses the globally configured storage (see `configureStorage()`).
+ */
+declare class CachedRegistry extends Registry {
+  readonly inner: Registry;
+  readonly storage: Storage;
+  private readonly lockfileStorage;
+  private readonly inflight;
+  constructor(inner: Registry, storage?: Storage);
+  ecosystem(): string;
+  urls(): URLBuilder;
+  fetchPackage(name: string, signal?: AbortSignal): Promise<Package>;
+  fetchVersions(name: string, signal?: AbortSignal): Promise<Version[]>;
+  fetchDependencies(name: string, version: string, signal?: AbortSignal): Promise<Dependency[]>;
+  fetchMaintainers(name: string, signal?: AbortSignal): Promise<Maintainer[]>;
+  /**
+   * Generic cache-through method:
+   * 1. Check lockfile for fresh entry
+   * 2. If fresh -> read from storage
+   * 3. If stale/missing -> fetch, store, update lockfile
+   */
+  private cached;
+}
+//#endregion
+export { CachedRegistry as t };
+//# sourceMappingURL=cached-registry.d.mts.map

package/dist/_chunks/cached-registry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-registry.d.mts","names":[],"sources":["../../src/cache/cached-registry.ts"],"mappings":";;;;;;;AAqBA;;;;;cAAa,cAAA,SAAuB,QAAA;EAAA,SACzB,KAAA,EAAO,QAAA;EAAA,SACP,OAAA,EAAS,OAAA;EAAA,iBACD,eAAA;EAAA,iBACA,QAAA;cAEL,KAAA,EAAO,QAAA,EAAU,OAAA,GAAU,OAAA;EAOvC,SAAA,CAAA;EAIA,IAAA,CAAA,GAAQ,UAAA;EAIF,YAAA,CAAa,IAAA,UAAc,MAAA,GAAS,WAAA,GAAc,OAAA,CAAQ,OAAA;EAW1D,aAAA,CAAc,IAAA,UAAc,MAAA,GAAS,WAAA,GAAc,OAAA,CAAQ,OAAA;EAgB3D,iBAAA,CACJ,IAAA,UACA,OAAA,UACA,MAAA,GAAS,WAAA,GACR,OAAA,CAAQ,UAAA;EAUL,gBAAA,CAAiB,IAAA,UAAc,MAAA,GAAS,WAAA,GAAc,OAAA,CAAQ,UAAA;EAAtB;;;;;;EAAA,QAgBhC,MAAA;AAAA"}

package/dist/_chunks/errors.d.mts

@@ -0,0 +1,90 @@
+import { a as ParsedPURL } from "./types.mjs";
+import { o as Client, t as Registry } from "./registry.mjs";
+
+//#region src/core/purl.d.ts
+/**
+ * Parse a PURL string into its components.
+ *
+ * Format: `pkg:<type>/<namespace>/<name>@<version>?<qualifiers>#<subpath>`
+ *
+ * @see https://github.com/package-url/purl-spec (ECMA-427)
+ */
+declare function parsePURL(purlStr: string): ParsedPURL;
+/** Build the full name from namespace + name (e.g., "@scope/pkg" for npm). */
+declare function fullName(parsed: ParsedPURL): string;
+/** Create a registry instance from a PURL, returning [registry, name, version]. */
+declare function createFromPURL(purlStr: string, client?: Client): [Registry, string, string];
+/** Build a PURL string from components. Inverse of `parsePURL`. */
+declare function buildPURL(parts: {
+  type: string;
+  name: string;
+  version?: string;
+  namespace?: string;
+  qualifiers?: Record<string, string>;
+  subpath?: string;
+}): string;
+//#endregion
+//#region src/core/license.d.ts
+/**
+ * Normalize a license string to SPDX expression.
+ *
+ * Handles common variations: "MIT License" → "MIT", "Apache 2.0" → "Apache-2.0".
+ * Passes through already-valid SPDX identifiers unchanged.
+ */
+declare function normalizeLicense(raw: string | null | undefined): string;
+/**
+ * Combine multiple license strings into a single SPDX expression.
+ *
+ * Default operator is OR (disjunctive, user picks one).
+ * Pass "AND" for ecosystems where multiple licenses mean all apply (e.g. Arch Linux).
+ */
+declare function combineLicenses(licenses: (string | null | undefined)[], operator?: "OR" | "AND"): string;
+//#endregion
+//#region src/core/repository.d.ts
+/**
+ * Normalize a repository URL to a clean HTTPS git URL.
+ *
+ * Handles various formats:
+ * - "git+https://github.com/foo/bar.git" → "https://github.com/foo/bar"
+ * - "git://github.com/foo/bar" → "https://github.com/foo/bar"
+ * - "ssh://git@github.com/foo/bar.git" → "https://github.com/foo/bar"
+ * - "github:foo/bar" → "https://github.com/foo/bar"
+ * - { url: "..." } → extracted and normalized
+ */
+declare function normalizeRepositoryURL(raw: unknown): string;
+//#endregion
+//#region src/core/errors.d.ts
+/** Custom error types for registry operations. */
+declare class PkioError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+declare class HTTPError extends PkioError {
+  readonly statusCode: number;
+  readonly url: string;
+  readonly body: string;
+  constructor(statusCode: number, url: string, body: string);
+  isNotFound(): boolean;
+  isRateLimit(): boolean;
+  isServerError(): boolean;
+}
+declare class NotFoundError extends PkioError {
+  readonly ecosystem: string;
+  readonly packageName: string;
+  readonly version: string;
+  constructor(ecosystem: string, packageName: string, version?: string);
+}
+declare class RateLimitError extends PkioError {
+  readonly retryAfter: number;
+  constructor(retryAfter: number);
+}
+declare class UnknownEcosystemError extends PkioError {
+  readonly ecosystem: string;
+  constructor(ecosystem: string);
+}
+declare class InvalidPURLError extends PkioError {
+  readonly purl: string;
+  constructor(purl: string, reason: string);
+}
+//#endregion
+export { RateLimitError as a, combineLicenses as c, createFromPURL as d, fullName as f, PkioError as i, normalizeLicense as l, InvalidPURLError as n, UnknownEcosystemError as o, parsePURL as p, NotFoundError as r, normalizeRepositoryURL as s, HTTPError as t, buildPURL as u };
+//# sourceMappingURL=errors.d.mts.map

package/dist/_chunks/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../src/core/purl.ts","../../src/core/license.ts","../../src/core/repository.ts","../../src/core/errors.ts"],"mappings":";;;;;AAqBA;;;;;AA4FA;iBA5FgB,SAAA,CAAU,OAAA,WAAkB,UAAA;;iBA4F5B,QAAA,CAAS,MAAA,EAAQ,UAAA;;iBAQjB,cAAA,CAAe,OAAA,UAAiB,MAAA,GAAS,MAAA,IAAU,QAAA;;iBAQnD,SAAA,CAAU,KAAA;EACxB,IAAA;EACA,IAAA;EACA,OAAA;EACA,SAAA;EACA,UAAA,GAAa,MAAA;EACb,OAAA;AAAA;;;;;;;AAlHF;;iBCfgB,gBAAA,CAAiB,GAAA;;;AD2GjC;;;;iBClDgB,eAAA,CACd,QAAA,iCACA,QAAA;;;;;;;AD5CF;;;;;AA4FA;iBEvGgB,sBAAA,CAAuB,GAAA;;;;cCR1B,SAAA,SAAkB,KAAA;cACjB,OAAA,UAAiB,OAAA,GAAU,YAAA;AAAA;AAAA,cAM5B,SAAA,SAAkB,SAAA;EAAA,SACpB,UAAA;EAAA,SACA,GAAA;EAAA,SACA,IAAA;cAEG,UAAA,UAAoB,GAAA,UAAa,IAAA;EAQ7C,UAAA,CAAA;EAIA,WAAA,CAAA;EAIA,aAAA,CAAA;AAAA;AAAA,cAKW,aAAA,SAAsB,SAAA;EAAA,SACxB,SAAA;EAAA,SACA,WAAA;EAAA,SACA,OAAA;cAEG,SAAA,UAAmB,WAAA,UAAqB,OAAA;AAAA;AAAA,cAUzC,cAAA,SAAuB,SAAA;EAAA,SACzB,UAAA;cAEG,UAAA;AAAA;AAAA,cAOD,qBAAA,SAA8B,SAAA;EAAA,SAChC,SAAA;cAEG,SAAA;AAAA;AAAA,cAOD,gBAAA,SAAyB,SAAA;EAAA,SAC3B,IAAA;cAEG,IAAA,UAAc,MAAA;AAAA"}

package/dist/_chunks/helpers.mjs

@@ -0,0 +1,95 @@
+import { l as InvalidPURLError } from "./registry.mjs";
+import { n as createFromPURL } from "./purl.mjs";
+/** Fetch normalized package metadata from a PURL. */
+async function fetchPackageFromPURL(purl, signal, client) {
+	const [reg, name] = createFromPURL(purl, client);
+	return reg.fetchPackage(name, signal);
+}
+/** Fetch all versions from a PURL. */
+async function fetchVersionsFromPURL(purl, signal, client) {
+	const [reg, name] = createFromPURL(purl, client);
+	return reg.fetchVersions(name, signal);
+}
+/** Fetch dependencies for a specific version from a PURL. */
+async function fetchDependenciesFromPURL(purl, signal, client) {
+	const [reg, name, version] = createFromPURL(purl, client);
+	if (!version) throw new InvalidPURLError(purl, "must include a version for dependency lookup");
+	return reg.fetchDependencies(name, version, signal);
+}
+/** Fetch maintainers from a PURL. */
+async function fetchMaintainersFromPURL(purl, signal, client) {
+	const [reg, name] = createFromPURL(purl, client);
+	return reg.fetchMaintainers(name, signal);
+}
+const DEFAULT_CONCURRENCY = 15;
+/** Bulk fetch packages from multiple PURLs, with concurrency limit. */
+async function bulkFetchPackages(purls, options) {
+	const concurrency = options?.concurrency ?? DEFAULT_CONCURRENCY;
+	const results = /* @__PURE__ */ new Map();
+	const queue = [...purls];
+	const signal = options?.signal;
+	const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+		while (queue.length > 0) {
+			if (signal?.aborted) break;
+			const purl = queue.shift();
+			try {
+				const pkg = await fetchPackageFromPURL(purl, signal, options?.client);
+				results.set(purl, pkg);
+			} catch {
+				if (signal?.aborted) break;
+			}
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}
+/**
+* Select the best matching version from a list.
+*
+* Resolution order:
+* 1. Exact match for `requested` (non-yanked/deprecated/retracted)
+* 2. Exact match for `latest` (non-yanked/deprecated/retracted)
+* 3. Newest available version with no negative status (by publishedAt)
+*
+* Returns `null` when no usable version exists.
+*/
+function selectVersion(versions, options) {
+	const { requested, latest } = options ?? {};
+	if (requested) {
+		const exact = versions.find((v) => v.number === requested && v.status === "");
+		if (exact) return exact;
+	}
+	if (latest) {
+		const latestV = versions.find((v) => v.number === latest && v.status === "");
+		if (latestV) return latestV;
+	}
+	const usable = versions.filter((v) => v.status === "");
+	if (usable.length === 0) return null;
+	usable.sort((a, b) => {
+		const at = a.publishedAt?.getTime() ?? 0;
+		return (b.publishedAt?.getTime() ?? 0) - at;
+	});
+	return usable[0] ?? null;
+}
+/**
+* Resolve the best documentation URL for a package.
+*
+* Fallback chain:
+* 1. `package.documentation` (explicit docs URL from registry)
+* 2. `package.homepage` (project homepage)
+* 3. `urls.documentation()` (ecosystem default, e.g. docs.rs, rubydoc.info)
+*/
+function resolveDocsUrl(pkg, urls, version) {
+	return pkg.documentation || pkg.homepage || urls.documentation(pkg.name, version);
+}
+/**
+* Resolve the best README URL for a package.
+*
+* Returns the ecosystem-specific URL where the package README can be fetched.
+*/
+function resolveReadmeUrl(pkg, urls, version) {
+	return urls.readme(pkg.name, version);
+}
+export { fetchVersionsFromPURL as a, selectVersion as c, fetchPackageFromPURL as i, fetchDependenciesFromPURL as n, resolveDocsUrl as o, fetchMaintainersFromPURL as r, resolveReadmeUrl as s, bulkFetchPackages as t };
+
+//# sourceMappingURL=helpers.mjs.map

package/dist/_chunks/helpers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.mjs","names":[],"sources":["../../src/helpers.ts"],"sourcesContent":["import type { Package, Version, Dependency, Maintainer, URLBuilder } from \"./core/types.ts\";\nimport type { Client } from \"./core/client.ts\";\nimport { createFromPURL } from \"./core/purl.ts\";\nimport { InvalidPURLError } from \"./core/errors.ts\";\n\n/** Fetch normalized package metadata from a PURL. */\nexport async function fetchPackageFromPURL(\n  purl: string,\n  signal?: AbortSignal,\n  client?: Client,\n): Promise<Package> {\n  const [reg, name] = createFromPURL(purl, client);\n  return reg.fetchPackage(name, signal);\n}\n\n/** Fetch all versions from a PURL. */\nexport async function fetchVersionsFromPURL(\n  purl: string,\n  signal?: AbortSignal,\n  client?: Client,\n): Promise<Version[]> {\n  const [reg, name] = createFromPURL(purl, client);\n  return reg.fetchVersions(name, signal);\n}\n\n/** Fetch dependencies for a specific version from a PURL. */\nexport async function fetchDependenciesFromPURL(\n  purl: string,\n  signal?: AbortSignal,\n  client?: Client,\n): Promise<Dependency[]> {\n  const [reg, name, version] = createFromPURL(purl, client);\n  if (!version) {\n    throw new InvalidPURLError(purl, \"must include a version for dependency lookup\");\n  }\n  return reg.fetchDependencies(name, version, signal);\n}\n\n/** Fetch maintainers from a PURL. */\nexport async function fetchMaintainersFromPURL(\n  purl: string,\n  signal?: AbortSignal,\n  client?: Client,\n): Promise<Maintainer[]> {\n  const [reg, name] = createFromPURL(purl, client);\n  return reg.fetchMaintainers(name, signal);\n}\n\nconst DEFAULT_CONCURRENCY = 15;\n\n/** Bulk fetch packages from multiple PURLs, with concurrency limit. */\nexport async function bulkFetchPackages(\n  purls: string[],\n  options?: { concurrency?: number; signal?: AbortSignal; client?: Client },\n): Promise<Map<string, Package>> {\n  const concurrency = options?.concurrency ?? DEFAULT_CONCURRENCY;\n  const results = new Map<string, Package>();\n  const queue = [...purls];\n\n  const signal = options?.signal;\n\n  const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {\n    while (queue.length > 0) {\n      if (signal?.aborted) break;\n\n      const purl = queue.shift()!;\n      try {\n        const pkg = await fetchPackageFromPURL(purl, signal, options?.client);\n        results.set(purl, pkg);\n      } catch {\n        if (signal?.aborted) break;\n        // Silently skip failed lookups — absent from results map\n      }\n    }\n  });\n\n  await Promise.all(workers);\n  return results;\n}\n\n/**\n * Select the best matching version from a list.\n *\n * Resolution order:\n * 1. Exact match for `requested` (non-yanked/deprecated/retracted)\n * 2. Exact match for `latest` (non-yanked/deprecated/retracted)\n * 3. Newest available version with no negative status (by publishedAt)\n *\n * Returns `null` when no usable version exists.\n */\nexport function selectVersion(\n  versions: Version[],\n  options?: {\n    requested?: string;\n    latest?: string;\n  },\n): Version | null {\n  const { requested, latest } = options ?? {};\n\n  if (requested) {\n    const exact = versions.find((v) => v.number === requested && v.status === \"\");\n    if (exact) return exact;\n  }\n\n  if (latest) {\n    const latestV = versions.find((v) => v.number === latest && v.status === \"\");\n    if (latestV) return latestV;\n  }\n\n  const usable = versions.filter((v) => v.status === \"\");\n  if (usable.length === 0) return null;\n\n  usable.sort((a, b) => {\n    const at = a.publishedAt?.getTime() ?? 0;\n    const bt = b.publishedAt?.getTime() ?? 0;\n    return bt - at;\n  });\n\n  return usable[0] ?? null;\n}\n\n/**\n * Resolve the best documentation URL for a package.\n *\n * Fallback chain:\n * 1. `package.documentation` (explicit docs URL from registry)\n * 2. `package.homepage` (project homepage)\n * 3. `urls.documentation()` (ecosystem default, e.g. docs.rs, rubydoc.info)\n */\nexport function resolveDocsUrl(pkg: Package, urls: URLBuilder, version?: string): string {\n  return pkg.documentation || pkg.homepage || urls.documentation(pkg.name, version);\n}\n\n/**\n * Resolve the best README URL for a package.\n *\n * Returns the ecosystem-specific URL where the package README can be fetched.\n */\nexport function resolveReadmeUrl(pkg: Package, urls: URLBuilder, version?: string): string {\n  return urls.readme(pkg.name, version);\n}\n"],"mappings":";;;AAMA,eAAsB,qBACpB,MACA,QACA,QACkB;CAClB,MAAM,CAAC,KAAK,QAAQ,eAAe,MAAM,OAAO;AAChD,QAAO,IAAI,aAAa,MAAM,OAAO;;;AAIvC,eAAsB,sBACpB,MACA,QACA,QACoB;CACpB,MAAM,CAAC,KAAK,QAAQ,eAAe,MAAM,OAAO;AAChD,QAAO,IAAI,cAAc,MAAM,OAAO;;;AAIxC,eAAsB,0BACpB,MACA,QACA,QACuB;CACvB,MAAM,CAAC,KAAK,MAAM,WAAW,eAAe,MAAM,OAAO;AACzD,KAAI,CAAC,QACH,OAAM,IAAI,iBAAiB,MAAM,+CAA+C;AAElF,QAAO,IAAI,kBAAkB,MAAM,SAAS,OAAO;;;AAIrD,eAAsB,yBACpB,MACA,QACA,QACuB;CACvB,MAAM,CAAC,KAAK,QAAQ,eAAe,MAAM,OAAO;AAChD,QAAO,IAAI,iBAAiB,MAAM,OAAO;;AAG3C,MAAM,sBAAsB;;AAG5B,eAAsB,kBACpB,OACA,SAC+B;CAC/B,MAAM,cAAc,SAAS,eAAe;CAC5C,MAAM,0BAAU,IAAI,KAAsB;CAC1C,MAAM,QAAQ,CAAC,GAAG,MAAM;CAExB,MAAM,SAAS,SAAS;CAExB,MAAM,UAAU,MAAM,KAAK,EAAE,QAAQ,KAAK,IAAI,aAAa,MAAM,OAAO,EAAE,EAAE,YAAY;AACtF,SAAO,MAAM,SAAS,GAAG;AACvB,OAAI,QAAQ,QAAS;GAErB,MAAM,OAAO,MAAM,OAAO;AAC1B,OAAI;IACF,MAAM,MAAM,MAAM,qBAAqB,MAAM,QAAQ,SAAS,OAAO;AACrE,YAAQ,IAAI,MAAM,IAAI;WAChB;AACN,QAAI,QAAQ,QAAS;;;GAIzB;AAEF,OAAM,QAAQ,IAAI,QAAQ;AAC1B,QAAO;;;;;;;;;;;;AAaT,SAAgB,cACd,UACA,SAIgB;CAChB,MAAM,EAAE,WAAW,WAAW,WAAW,EAAE;AAE3C,KAAI,WAAW;EACb,MAAM,QAAQ,SAAS,MAAM,MAAM,EAAE,WAAW,aAAa,EAAE,WAAW,GAAG;AAC7E,MAAI,MAAO,QAAO;;AAGpB,KAAI,QAAQ;EACV,MAAM,UAAU,SAAS,MAAM,MAAM,EAAE,WAAW,UAAU,EAAE,WAAW,GAAG;AAC5E,MAAI,QAAS,QAAO;;CAGtB,MAAM,SAAS,SAAS,QAAQ,MAAM,EAAE,WAAW,GAAG;AACtD,KAAI,OAAO,WAAW,EAAG,QAAO;AAEhC,QAAO,MAAM,GAAG,MAAM;EACpB,MAAM,KAAK,EAAE,aAAa,SAAS,IAAI;AAEvC,UADW,EAAE,aAAa,SAAS,IAAI,KAC3B;GACZ;AAEF,QAAO,OAAO,MAAM;;;;;;;;;;AAWtB,SAAgB,eAAe,KAAc,MAAkB,SAA0B;AACvF,QAAO,IAAI,iBAAiB,IAAI,YAAY,KAAK,cAAc,IAAI,MAAM,QAAQ;;;;;;;AAQnF,SAAgB,iBAAiB,KAAc,MAAkB,SAA0B;AACzF,QAAO,KAAK,OAAO,IAAI,MAAM,QAAQ"}