https://github.com/captainsafia/gh-release-update-notifier
TypeScript library for checking GitHub releases to notify users of available updates.
https://github.com/captainsafia/gh-release-update-notifier
github github-releases typescript update-notifier
Last synced: 5 months ago
JSON representation
TypeScript library for checking GitHub releases to notify users of available updates.
- Host: GitHub
- URL: https://github.com/captainsafia/gh-release-update-notifier
- Owner: captainsafia
- License: mit
- Created: 2025-12-29T18:47:05.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-02T21:57:34.000Z (5 months ago)
- Last Synced: 2026-01-09T09:58:48.571Z (5 months ago)
- Topics: github, github-releases, typescript, update-notifier
- Language: TypeScript
- Homepage:
- Size: 64.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# gh-release-update-notifier
A lightweight TypeScript library for checking GitHub Releases to notify CLI users of available updates, with built-in caching and disk persistence.
## Installation
```bash
npm install gh-release-update-notifier
```
```bash
pnpm add gh-release-update-notifier
```
```bash
yarn add gh-release-update-notifier
```
## Usage
### Basic Usage
```typescript
import { ReleaseNotifier } from 'gh-release-update-notifier';
const notifier = new ReleaseNotifier({
repo: 'owner/repo',
});
// Check if an update is available
const result = await notifier.checkVersion('1.0.0');
if (result.updateAvailable) {
console.log(`Update available: ${result.latestVersion}`);
console.log(`Download: ${result.latestRelease?.htmlUrl}`);
}
```
### Get Latest Release
```typescript
const notifier = new ReleaseNotifier({ repo: 'owner/repo' });
// Get the latest stable release
const stable = await notifier.getLatestRelease();
console.log(`Latest stable: ${stable?.tagName}`);
// Include prereleases in the search
const latest = await notifier.getLatestRelease(true);
console.log(`Latest (including prereleases): ${latest?.tagName}`);
```
### Get Latest Prerelease
```typescript
const notifier = new ReleaseNotifier({ repo: 'owner/repo' });
const prerelease = await notifier.getLatestPrerelease();
if (prerelease) {
console.log(`Latest prerelease: ${prerelease.tagName}`);
}
```
### Check Version with Prereleases
```typescript
const notifier = new ReleaseNotifier({ repo: 'owner/repo' });
// Check against the latest prerelease
const result = await notifier.checkVersion('2.0.0-beta.1', true);
if (result.updateAvailable) {
console.log(`New prerelease available: ${result.latestVersion}`);
}
```
### Caching Configuration
```typescript
const notifier = new ReleaseNotifier({
repo: 'owner/repo',
// Check interval in milliseconds (default: 1 hour)
checkInterval: 3600000,
// Optional: persist cache to disk
cacheFilePath: '/path/to/cache.json',
});
// Clear the cache manually
notifier.clearCache();
```
## API Reference
### `ReleaseNotifier`
#### Constructor Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `repo` | `string` | **required** | GitHub repository in `owner/repo` format |
| `checkInterval` | `number` | `3600000` (1 hour) | Minimum time between API requests (in ms). Set to `0` to disable caching. |
| `cacheFilePath` | `string` | `undefined` | Path to persist cache on disk |
| `token` | `string` | `undefined` | GitHub token for authentication (increases rate limits and enables access to private repos) |
#### Methods
##### `getLatestRelease(includePrerelease?: boolean): Promise`
Fetches the most recent release from GitHub.
- `includePrerelease` - When `true`, includes prereleases in the search (default: `false`)
- Returns the latest release or `null` if no releases found
##### `getLatestPrerelease(): Promise`
Fetches the most recent prerelease from GitHub.
- Returns the latest prerelease or `null` if no prereleases found
##### `checkVersion(currentVersion: string, isPrerelease?: boolean): Promise`
Checks if the provided version is older than the latest available version.
- `currentVersion` - The version/tag to check (e.g., `"1.2.3"` or `"v1.2.3"`)
- `isPrerelease` - When `true`, checks against the latest prerelease (default: `false`)
- Returns version check result with update availability information
##### `clearCache(): void`
Clears the cached releases, forcing the next fetch to get fresh data. Also removes the cache file from disk if configured.
### Types
#### `Release`
```typescript
interface Release {
tagName: string;
name: string;
prerelease: boolean;
draft: boolean;
htmlUrl: string;
publishedAt: string;
}
```
#### `VersionCheckResult`
```typescript
interface VersionCheckResult {
updateAvailable: boolean;
currentVersion: string;
latestVersion: string | null;
latestRelease: Release | null;
}
```
#### `ReleaseNotifierConfig`
```typescript
interface ReleaseNotifierConfig {
repo: string;
checkInterval?: number;
cacheFilePath?: string;
token?: string;
}
```
## CLI Integration Example
```typescript
import { ReleaseNotifier } from 'gh-release-update-notifier';
import { readFileSync } from 'node:fs';
const pkg = JSON.parse(readFileSync('./package.json', 'utf-8'));
const notifier = new ReleaseNotifier({
repo: 'your-org/your-cli',
checkInterval: 86400000, // Check once per day
cacheFilePath: `${process.env.HOME}/.your-cli/update-cache.json`,
token: process.env.GITHUB_TOKEN, // Optional: for higher rate limits
});
async function checkForUpdates() {
try {
const result = await notifier.checkVersion(pkg.version);
if (result.updateAvailable) {
console.log(`\nš¦ Update available: ${pkg.version} ā ${result.latestVersion}`);
console.log(` Run: npm install -g your-cli`);
console.log(` Or visit: ${result.latestRelease?.htmlUrl}\n`);
}
} catch {
// Silently fail - don't block the CLI for update checks
}
}
// Run update check in the background
checkForUpdates();
```