# whatver

> A modern CLI tool and Node.js library for checking npm package versions against semver ranges

Latest version **2.0.1** (published 2025-09-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install whatver
pnpm add whatver
yarn add whatver
bun add whatver
```

Provides the command `whatver`.

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2025-09-18 |
| First published | 2020-01-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 407.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Chris Green |
| Maintainers | chrisgreen1993 |
| Keywords | npm, semver, version, cli, package, registry, typescript, bun |

## Links

- npm: https://www.npmjs.com/package/whatver
- Repository: https://github.com/chrisgreen1993/whatver
- Homepage: https://github.com/chrisgreen1993/whatver#readme
- Issues: https://github.com/chrisgreen1993/whatver/issues
- npm.io page: https://npm.io/package/whatver

## Dependencies (4)

- [chalk](https://npm.io/package/chalk.md) ^5.6.2
- [yargs](https://npm.io/package/yargs.md) ^18.0.0
- [semver](https://npm.io/package/semver.md) ^7.7.2
- [cli-columns](https://npm.io/package/cli-columns.md) ^4.0.0

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 2.0.1 (latest) — 2025-09-18
- 2.0.0-alpha.1 (alpha) — 2025-09-17
- 2.0.0 — 2025-09-17
- 2.0.0-alpha.0 — 2025-09-12
- 1.0.0 — 2020-01-02

## README

# whatver

A simple Node.js cli tool for checking semver ranges of npm packages, similar to [https://semver.npmjs.com/](https://semver.npmjs.com/), but in the comfort of your terminal. 

As well as checking package versions on the registry, it will also display the currently installed package version in your `node_modules` and the semver range from `package.json`.

![screenshot](screenshot.png)

## Installation

```bash
# For CLI usage
npm install -g whatver
# or
npx whatver

# For library usage  
npm install whatver
```

## CLI Usage

### Basic Usage
```bash
# Show all stable versions of a package (excludes prerelease by default)
npx whatver lodash

# Show versions matching a specific range
npx whatver lodash "^4.14"

# Include prerelease versions (alpha, beta, rc, etc.)
npx whatver lodash --show-prerelease
```

### Local Package Detection

When run in a directory with a package.json, whatver automatically detects local packages:

```bash
# In a project with lodash in package.json
npx whatver lodash
# Automatically uses the semver range from your package.json
# Shows installed version with visual indicators

# Override with specific range
npx whatver lodash "^4.0.0"

# Show all versions with local range highlighted
npx whatver lodash --all

# Include prerelease versions in local package analysis
npx whatver lodash --show-prerelease
```

### Version Filtering

By default, whatver excludes prerelease versions (alpha, beta, rc, etc.) to show only stable releases. Use `--show-prerelease` to include prerelease versions when needed.

## Library Usage

### List all versions and whether the semver range is satisfied for that version.

```typescript
import { allPackageVersions, type PackageVersionInfo, type PackageVersionOptions } from "whatver";

// Get stable versions only (default behavior)
const versionInfo: PackageVersionInfo[] = await allPackageVersions("lodash", "^4.14");
// Returns: [
//   { version: "4.14.0", satisfied: true },
//   { version: "4.15.0", satisfied: true },
//   { version: "3.10.1", satisfied: false },
//   ...
// ]
console.log(versionInfo);

// Include prerelease versions
const options: PackageVersionOptions = { showPrerelease: true };
const allVersions = await allPackageVersions("lodash", "^4.14", options);
// Also includes versions like "4.15.0-beta.1", "4.16.0-alpha.1", etc.
```

### List only versions that satisfy the semver range

```typescript
import { satisfiedPackageVersions, type PackageVersionOptions } from "whatver";

// Get satisfied stable versions only (default)
const satisfied: string[] = await satisfiedPackageVersions("lodash", "^4.14");
// Returns: ["4.14.0", "4.14.1", "4.15.0", "4.16.0", ...]
console.log(satisfied);

// Include prerelease versions that satisfy the range
const options: PackageVersionOptions = { showPrerelease: true };
const withPrerelease = await satisfiedPackageVersions("lodash", "^4.14", options);
// Also includes "4.15.0-beta.1", "4.16.0-alpha.1", etc. if they satisfy ^4.14
```

### TypeScript Types

```typescript
import type { PackageVersionInfo, PackageVersionOptions } from "whatver";

// Interface for version results
interface PackageVersionInfo {
  version: string;
  satisfied: boolean;
}

// Interface for options
interface PackageVersionOptions {
  showPrerelease?: boolean;
}
```

### Error Handling

```typescript
import { allPackageVersions } from "whatver";

try {
  const versions = await allPackageVersions("nonexistent-package", "^1.0.0");
} catch (error) {
  console.error(error.message);
  // "Failed to fetch package versions: Package 'nonexistent-package' not found in npm registry"
}

try {
  const versions = await allPackageVersions("lodash", "invalid-semver");
} catch (error) {
  console.error(error.message);
  // "Invalid semver range: invalid-semver"
}
```

## Development

This project uses [Bun](https://bun.com/) and [devbox](https://www.jetify.com/docs/devbox/) (optional) for development:


```bash
# Installs bun to isolated env & enters it (optional)
devbox install
devbox shell

# install dependenices
bun install

# run cli
bun run src/cli.ts

# run tests
bun test

# type checking
bun type-check

# check linting and formatting
bun check
```

## Releasing

```bash
# Test release process (dry run)
bun run release:dry

# Interactive release (choose version)
bun run release
```

The release process will:
- Run tests and linting checks
- Build the project
- Update the version in package.json
- Create a git tag
- Push to GitHub
- Create a GitHub release with changelog
- Publish to npm

---
_Source: https://npm.io/package/whatver · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._