@jayf0x/npm-exists 2.0.1 → 2.0.2

package/README.md

@@ -1,20 +1,14 @@
 # npm-exists
 
-> Check if an npm package name is taken. Zero dependencies, uses native `fetch`.
+> Check if an npm package name is taken.
 
-[![npm version](https://img.shields.io/npm/v/@jayf0x/npm-exists.svg)](https://npmjs.com/package/@jayf0x/npm-exists)
-[![npm downloads](https://img.shields.io/npm/dm/@jayf0x/npm-exists.svg)](https://npmjs.com/package/@jayf0x/npm-exists)
-[![license](https://img.shields.io/npm/l/@jayf0x/npm-exists.svg)](LICENSE)
-[![node](https://img.shields.io/node/v/@jayf0x/npm-exists.svg)](package.json)
+[![npm version](https://img.shields.io/npm/v/@jayf0x/npm-exists)](https://www.npmjs.com/package/@jayf0x/npm-exists)
+[![npm downloads](https://img.shields.io/npm/dm/@jayf0x/npm-exists)](https://www.npmjs.com/package/@jayf0x/npm-exists)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@jayf0x/npm-exists)](https://bundlephobia.com/package/@jayf0x/npm-exists)
+[![license](https://img.shields.io/npm/l/@jayf0x/npm-exists)](./LICENSE)
+[![CI](https://github.com/jayf0x/npm-exists/actions/workflows/release.yml/badge.svg)](https://github.com/jayf0x/npm-exists/actions/workflows/release.yml)
 
-## Features
-
-- **Zero dependencies** — uses native `fetch` (Node 18+)
-- **Returns full metadata** — not just a boolean; get version, description, author, etc.
-- **Custom registry** — point at any npm-compatible registry
-- **CLI included** — `npm-exists <package-name>`
-- **Dual ESM/CJS** — works in both module systems
-- **TypeScript types** included
+Zero dependencies. Returns the npm package URL or `false`.
 
 ## Install
 
@@ -24,97 +18,55 @@ npm install @jayf0x/npm-exists
 
 ## Usage
 
-### API
-
 ```js
 import npmExists from '@jayf0x/npm-exists'
 
-// Check if a package exists — returns metadata or false
-const details = await npmExists('react')
-if (details) {
-  console.log(`react@${details['dist-tags'].latest} exists`)
-} else {
-  console.log('Package name is free!')
-}
+const url = await npmExists('react')
+// 'https://www.npmjs.com/package/react' | false
 ```
 
 ```js
-// With a custom registry
-const details = await npmExists('my-pkg', 'https://my.private.registry.io')
+// Custom registry
+const url = await npmExists('my-pkg', 'https://my.private.registry.io')
 ```
 
 ```js
-// Build your own fetch — getNpmUrl lets you use axios, ky, etc.
-import { getNpmUrl } from '@jayf0x/npm-exists'
-import axios from 'axios'
-
-const url = getNpmUrl('react')
-const { data } = await axios.get(url)
+// Suppress errors (network failures return false instead of throwing)
+const url = await npmExists('react', { silent: true })
 ```
 
-### Exports
-
-| Export | Description |
-|---|---|
-| `npmExists(pkg, registry?)` | Returns package metadata (`object`) or `false` |
-| `getNpmUrl(pkg, registry?)` | Returns the registry URL for a package |
+```js
+// Build your own fetch
+import { getNpmUrl } from '@jayf0x/npm-exists'
+const url = getNpmUrl('react') // https://registry.npmjs.org/react
+```
 
-### CLI
+## CLI
 
 ```sh
-# Global install
-npm install -g npm-exists
-
-npm-exists react
+npx @jayf0x/npm-exists react
 # ✓ react@19.1.0 exists on npm
 
-npm-exists my-unique-package-name-xyz
-# ✗ my-unique-package-name-xyz is not registered on npm
-
-# Exit codes:  0 = exists,  1 = not found,  2 = bad usage
-
-# Custom registry
 npm-exists my-pkg https://my.private.registry.io
 ```
 
-### One-off via npx
+Exit codes: `0` exists · `1` not found · `2` bad usage
 
-```sh
-npx @jayf0x/npm-exists react
-```
-
-## API Reference
-
-### `npmExists(pkg, registry?)`
-
-| Param | Type | Default | Description |
-|---|---|---|---|
-| `pkg` | `string` | — | Package name (scoped names like `@scope/pkg` are supported) |
-| `registry` | `string` | `https://registry.npmjs.org` | Registry base URL |
+## API
 
-**Returns:** `Promise<object \| false>`
-- `object` — full registry metadata (includes `name`, `dist-tags`, `versions`, `description`, …)
-- `false` — package does not exist
+### `npmExists(pkg, registryOrOptions?, options?)`
 
-**Throws** if the registry returns an unexpected non-404 error (network issue, auth failure, etc.).
+| Param | Type | Description |
+|---|---|---|
+| `pkg` | `string` | Package name |
+| `registryOrOptions` | `string \| { registry?, silent? }` | Registry URL or options object |
+| `options` | `{ silent? }` | When `silent: true`, errors return `false` instead of throwing |
 
----
+Returns `Promise<string \| false>` — the npm page URL or `false` if not found.
 
 ### `getNpmUrl(pkg, registry?)`
 
-Returns the full URL used to query the registry. Useful when you want to make the request yourself.
-
-```js
-getNpmUrl('react')
-// → 'https://registry.npmjs.org/react'
-
-getNpmUrl('@scope/pkg')
-// → 'https://registry.npmjs.org/%40scope%2Fpkg'
-```
-
-## Requirements
-
-Node 18+ (uses native `fetch`).
+Returns the registry API URL. Useful with custom HTTP clients like axios or ky.
 
 ## License
 

package/dist/index.cjs

@@ -1,15 +1,33 @@
 "use strict";
 Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
 const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+const NPM_PAGE_BASE = "https://www.npmjs.com/package";
 function getNpmUrl(pkg, registry = DEFAULT_REGISTRY) {
   return `${registry.replace(/\/$/, "")}/${encodeURIComponent(pkg)}`;
 }
-async function npmExists(pkg, registry) {
-  const url = getNpmUrl(pkg, registry);
-  const res = await fetch(url);
-  if (res.status === 404) return false;
-  if (!res.ok) throw new Error(`npm registry error: HTTP ${res.status}`);
-  return res.json();
+function getPageUrl(pkg, registry) {
+  const base = !registry || registry === DEFAULT_REGISTRY ? NPM_PAGE_BASE : `${registry.replace(/\/$/, "")}/package`;
+  return `${base}/${pkg}`;
+}
+async function npmExists(pkg, registryOrOptions, options) {
+  let registry = DEFAULT_REGISTRY;
+  let silent = false;
+  if (typeof registryOrOptions === "string") {
+    registry = registryOrOptions;
+    silent = options?.silent ?? false;
+  } else if (registryOrOptions != null) {
+    registry = registryOrOptions.registry ?? DEFAULT_REGISTRY;
+    silent = registryOrOptions.silent ?? false;
+  }
+  try {
+    const res = await fetch(getNpmUrl(pkg, registry));
+    if (res.status === 404) return false;
+    if (!res.ok) throw new Error(`npm registry error: HTTP ${res.status}`);
+    return getPageUrl(pkg, registry);
+  } catch (err) {
+    if (silent) return false;
+    throw err;
+  }
 }
 exports.default = npmExists;
 exports.getNpmUrl = getNpmUrl;

package/dist/index.d.ts

@@ -1,5 +1,14 @@
 export declare function getNpmUrl(pkg: string, registry?: string): string
 
-export declare function npmExists(pkg: string, registry?: string): Promise<Record<string, unknown> | false>
+export interface NpmExistsOptions {
+  registry?: string
+  silent?: boolean
+}
+
+export declare function npmExists(
+  pkg: string,
+  registryOrOptions?: string | NpmExistsOptions,
+  options?: Pick<NpmExistsOptions, 'silent'>
+): Promise<string | false>
 
 export default npmExists

package/dist/index.js

@@ -1,13 +1,31 @@
 const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+const NPM_PAGE_BASE = "https://www.npmjs.com/package";
 function getNpmUrl(pkg, registry = DEFAULT_REGISTRY) {
   return `${registry.replace(/\/$/, "")}/${encodeURIComponent(pkg)}`;
 }
-async function npmExists(pkg, registry) {
-  const url = getNpmUrl(pkg, registry);
-  const res = await fetch(url);
-  if (res.status === 404) return false;
-  if (!res.ok) throw new Error(`npm registry error: HTTP ${res.status}`);
-  return res.json();
+function getPageUrl(pkg, registry) {
+  const base = !registry || registry === DEFAULT_REGISTRY ? NPM_PAGE_BASE : `${registry.replace(/\/$/, "")}/package`;
+  return `${base}/${pkg}`;
+}
+async function npmExists(pkg, registryOrOptions, options) {
+  let registry = DEFAULT_REGISTRY;
+  let silent = false;
+  if (typeof registryOrOptions === "string") {
+    registry = registryOrOptions;
+    silent = options?.silent ?? false;
+  } else if (registryOrOptions != null) {
+    registry = registryOrOptions.registry ?? DEFAULT_REGISTRY;
+    silent = registryOrOptions.silent ?? false;
+  }
+  try {
+    const res = await fetch(getNpmUrl(pkg, registry));
+    if (res.status === 404) return false;
+    if (!res.ok) throw new Error(`npm registry error: HTTP ${res.status}`);
+    return getPageUrl(pkg, registry);
+  } catch (err) {
+    if (silent) return false;
+    throw err;
+  }
 }
 export {
   npmExists as default,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jayf0x/npm-exists",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Check if an npm package name is taken. Zero dependencies, uses native fetch.",
   "type": "module",
   "main": "./dist/index.cjs",