@jayf0x/npm-exists 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonatan
+
+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,121 @@
+# npm-exists
+
+> Check if an npm package name is taken. Zero dependencies, uses native `fetch`.
+
+[![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)
+
+## 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
+
+## Install
+
+```sh
+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!')
+}
+```
+
+```js
+// With a custom registry
+const details = 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)
+```
+
+### Exports
+
+| Export | Description |
+|---|---|
+| `npmExists(pkg, registry?)` | Returns package metadata (`object`) or `false` |
+| `getNpmUrl(pkg, registry?)` | Returns the registry URL for a package |
+
+### CLI
+
+```sh
+# Global install
+npm install -g npm-exists
+
+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
+
+```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 |
+
+**Returns:** `Promise<object \| false>`
+- `object` — full registry metadata (includes `name`, `dist-tags`, `versions`, `description`, …)
+- `false` — package does not exist
+
+**Throws** if the registry returns an unexpected non-404 error (network issue, auth failure, etc.).
+
+---
+
+### `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`).
+
+## License
+
+MIT

package/bin/npm-exists.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { npmExists } from '../dist/index.js'
+
+const [pkg, registry] = process.argv.slice(2)
+
+if (!pkg) {
+  console.error('Usage: npm-exists <package-name> [registry-url]')
+  process.exit(2)
+}
+
+const result = await npmExists(pkg, registry)
+
+if (result) {
+  const version = result['dist-tags']?.latest ?? '?'
+  console.log(`✓ ${pkg}@${version} exists on npm`)
+  process.exit(0)
+} else {
+  console.log(`✗ ${pkg} is not registered on npm`)
+  process.exit(1)
+}

package/dist/index.cjs

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+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();
+}
+exports.default = npmExists;
+exports.getNpmUrl = getNpmUrl;
+exports.npmExists = npmExists;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export declare function getNpmUrl(pkg: string, registry?: string): string
+
+export declare function npmExists(pkg: string, registry?: string): Promise<Record<string, unknown> | false>
+
+export default npmExists

package/dist/index.js

@@ -0,0 +1,16 @@
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+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();
+}
+export {
+  npmExists as default,
+  getNpmUrl,
+  npmExists
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@jayf0x/npm-exists",
+  "version": "2.0.1",
+  "description": "Check if an npm package name is taken. Zero dependencies, uses native fetch.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "npm-exists": "bin/npm-exists.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "vite build && node scripts/generate-types.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release": "bash publish-npm.sh",
+    "prepublishOnly": "bun run build && bun test"
+  },
+  "keywords": [
+    "npm",
+    "package",
+    "exists",
+    "check",
+    "registry",
+    "available",
+    "taken",
+    "name",
+    "lookup",
+    "cli",
+    "zero-deps",
+    "fetch",
+    "esm",
+    "typescript"
+  ],
+  "author": {
+    "name": "Jay Verstraete",
+    "email": "jonatanverstraete@outlook.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayverstraete/npm-exists.git"
+  },
+  "homepage": "https://github.com/jayverstraete/npm-exists#readme",
+  "bugs": {
+    "url": "https://github.com/jayverstraete/npm-exists/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "vite": "^6.0.0",
+    "vitest": "^2.0.0"
+  }
+}