npm package: @rodbe/check-updates
Description: Configurable update checker
Author: KevinRodbe
Latest version: 1.4.0

# @rodbe/check-updates

> TypeScript utility that checks your local npm packages against the registry and prompts users to update — with smart caching to avoid unnecessary network requests.

## ✨ Features

- 🔍 **Version detection** — fetches the latest version of any npm package from the registry
- ⚡ **Smart caching** — avoids repeated network calls using configurable TTL intervals
- 💬 **Interactive prompt** — asks the user before installing anything
- 📦 **Auto install** — runs the install command automatically when the user accepts
- 🔔 **Lifecycle callbacks** — hooks for success and error after the install attempt

## 📦 Installation

```sh
npm install @rodbe/check-updates --save
```

## 🚀 Usage

```ts
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { checkUpdates } from '@rodbe/check-updates';

// → ./dist/ (compiled output directory)
const distPath = join(dirname(fileURLToPath(import.meta.url)));

const updateChecker = checkUpdates({
  packageJsonPath: join(distPath, '..', 'package.json'), // → ./package.json
  isGlobal: true,
});

// Checks the registry, prompts the user, and installs if accepted
await updateChecker.checkNewVersion();
```

## ⚙️ Configuration Options

| Option | Type | Default | Description |
|---|---|---|---|
| `packageJsonPath` | `string` | **Required** | Path to the `package.json` of the package to check |
| `askToUpdate` | `boolean` | `true` | Whether to prompt the user before installing |
| `isGlobal` | `boolean` | `true` | Install the package globally (`npm install -g`) |
| `updateCheckInterval` | `number` | `604800000` (1 week) | How often to check the registry for a new version, in ms |
| `dontAskCheckInterval` | `number` | `86400000` (1 day) | How long to suppress the prompt after the user declines, in ms |
| `updateQuestion` | `string` | `'Heey! Before, do you want to get the latest version? 🔥'` | Custom message shown in the update prompt |
| `cbOnSuccess` | `() => void` | `undefined` | Callback invoked after a successful installation |
| `cbOnError` | `() => void` | `undefined` | Callback invoked when the installation fails |
| `debug` | `boolean` | `false` | Runs `npm -v` instead of the real install command — useful during local development |

## 📖 API

### `checkNewVersion(): Promise<void>`

Checks the npm registry for a newer version. If one is found (and the cache TTL has expired), it prompts the user. The user can accept to install or decline — if declined, the prompt is suppressed until `dontAskCheckInterval` elapses.

### `update(): void`

Runs the install command immediately without any prompt. Calls `cbOnSuccess` on success or `cbOnError` on failure.

## 🔧 Advanced usage

```ts
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { checkUpdates } from '@rodbe/check-updates';

const distPath = join(dirname(fileURLToPath(import.meta.url)));

const updateChecker = checkUpdates({
  packageJsonPath: join(distPath, '..', 'package.json'),
  isGlobal: true,
  askToUpdate: true,
  updateCheckInterval: 7 * 24 * 60 * 60 * 1000, // check once a week
  dontAskCheckInterval: 24 * 60 * 60 * 1000,    // suppress prompt for 1 day after decline
  updateQuestion: 'Do you want to upgrade to the latest version now?',
  cbOnSuccess: () => console.log('Package updated successfully!'),
  cbOnError: () => console.error('Something went wrong during the update.'),
});

// Check and prompt automatically
await updateChecker.checkNewVersion();

// Or trigger the update directly, skipping the prompt
updateChecker.update();
```

## 📄 License

MIT