push.rocks/smartupdate
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(smartupdate): improve update check caching, validation, and error handling

Browse Source
This commit is contained in:
Jürgen Kunz
2026-05-10 15:05:00 +00:00
parent d049d1a1e9
commit 3d1a73cf9e
12 changed files with 376 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ts/index.ts
+3
View File
@@ -13,6 +13,9 @@ export type {
ICacheStatus,
ICacheOptions,
INotificationOptions,
TCacheStrategy,
TCacheStoreType,
TCachedUpdateStatus,
} from './smartupdate.interfaces.js';
// Error classes
ts/smartupdate.classes.cachemanager.ts
+47 -12
View File
@@ -1,18 +1,21 @@
import * as plugins from './smartupdate.plugins.js';
import type { ICacheStatus, ICacheOptions } from './smartupdate.interfaces.js';
import type { ICacheStatus, ICacheOptions, TCacheStrategy, TCachedUpdateStatus } from './smartupdate.interfaces.js';
type TCacheStoreData = Record<string, ICacheStatus>;
/**
* Manages caching of update check results
*/
export class UpdateCacheManager {
public readonly kvStore: plugins.npmextra.KeyValueStore;
public readonly kvStore: plugins.npmextra.KeyValueStore<TCacheStoreData>;
private cacheDurationMs: number;
constructor(options: ICacheOptions) {
this.cacheDurationMs = options.durationMs;
this.kvStore = new plugins.npmextra.KeyValueStore({
typeArg: 'userHomeDir',
this.kvStore = new plugins.npmextra.KeyValueStore<TCacheStoreData>({
typeArg: options.storeType || 'userHomeDir',
identityArg: options.storeIdentifier || 'global_smartupdate',
customPath: options.customPath,
});
}
@@ -27,7 +30,7 @@ export class UpdateCacheManager {
* Get cached status for a package
*/
public async getCached(packageName: string): Promise<ICacheStatus | null> {
return await this.kvStore.readKey(packageName);
return (await this.kvStore.readKey(packageName)) || null;
}
/**
@@ -42,11 +45,12 @@ export class UpdateCacheManager {
*/
public async clearCache(packageName?: string): Promise<void> {
if (packageName) {
await this.kvStore.deleteKey(packageName);
const cacheData = await this.kvStore.readAll();
delete cacheData[packageName];
await this.kvStore.wipe();
await this.kvStore.writeAll(cacheData);
} else {
// Clear all keys - this requires reading all keys first
// For now, we'll skip implementing full cache clear as it requires more kvStore API
throw new Error('Clearing all cache entries is not yet implemented');
await this.kvStore.wipe();
}
}
@@ -56,7 +60,11 @@ export class UpdateCacheManager {
*/
public async shouldCheckRegistry(
packageName: string,
strategy: 'always' | 'never' | 'time-based' = 'time-based'
strategy: TCacheStrategy = 'time-based',
cacheContext: {
currentVersion?: string;
registryUrl?: string;
} = {}
): Promise<{
shouldCheck: boolean;
cacheStatus?: ICacheStatus;
@@ -72,7 +80,7 @@ export class UpdateCacheManager {
const cacheStatus = await this.getCached(packageName);
// No cache exists
if (!cacheStatus) {
if (!cacheStatus || !this.cacheMatchesContext(cacheStatus, cacheContext)) {
return { shouldCheck: true };
}
@@ -106,11 +114,38 @@ export class UpdateCacheManager {
/**
* Create a new cache status object
*/
public createCacheStatus(latestVersion: string, performedUpgrade: boolean = false): ICacheStatus {
public createCacheStatus(
latestVersion: string,
performedUpgrade: boolean = false,
metadata: {
currentVersion?: string;
registryUrl?: string;
status?: TCachedUpdateStatus;
} = {}
): ICacheStatus {
return {
lastCheck: Date.now(),
latestVersion,
currentVersion: metadata.currentVersion,
registryUrl: metadata.registryUrl,
status: metadata.status,
performedUpgrade,
};
}
private cacheMatchesContext(
cacheStatus: ICacheStatus,
cacheContext: {
currentVersion?: string;
registryUrl?: string;
}
): boolean {
if (cacheContext.currentVersion && cacheStatus.currentVersion !== cacheContext.currentVersion) {
return false;
}
if (cacheContext.registryUrl && cacheStatus.registryUrl !== cacheContext.registryUrl) {
return false;
}
return true;
}
}
ts/smartupdate.classes.smartupdate.ts
+97 -25
View File
@@ -3,13 +3,18 @@ import { UpdateCacheManager } from './smartupdate.classes.cachemanager.js';
import { UpdateNotifier } from './smartupdate.classes.notifier.js';
import { DEFAULT_CACHE_DURATION_HOURS, MILLISECONDS_PER_MINUTE, MINUTES_PER_HOUR } from './smartupdate.constants.js';
import type {
ICacheStatus,
ISmartUpdateOptions,
IUpdateCheckOptions,
IUpdateCheckResult,
TCachedUpdateStatus,
} from './smartupdate.interfaces.js';
import {
SmartUpdateError,
RegistryUnavailableError,
PackageNotFoundError,
InvalidPackageNameError,
InvalidVersionError,
} from './smartupdate.errors.js';
/**
@@ -38,7 +43,7 @@ export class SmartUpdate {
/**
* @deprecated Use the options parameter instead of kvStore property
*/
public kvStore: plugins.npmextra.KeyValueStore;
public kvStore: plugins.npmextra.KeyValueStore<Record<string, ICacheStatus>>;
constructor(options: ISmartUpdateOptions = {}) {
this.options = options;
@@ -56,6 +61,9 @@ export class SmartUpdate {
// Initialize cache manager
this.cacheManager = new UpdateCacheManager({
durationMs: cacheDurationMs || DEFAULT_CACHE_DURATION_HOURS * MINUTES_PER_HOUR * MILLISECONDS_PER_MINUTE,
storeIdentifier: options.cacheStore?.storeIdentifier,
storeType: options.cacheStore?.storeType,
customPath: options.cacheStore?.customPath,
});
// Initialize notifier
@@ -72,7 +80,7 @@ export class SmartUpdate {
/**
* Check for updates with caching (primarily for CLI use)
*
* @deprecated Use checkForUpdate with cacheStrategy: 'always' instead
* @deprecated Use checkForUpdate with cacheStrategy: 'time-based' instead
* @param packageName - The npm package name to check
* @param currentVersion - The current version to compare against
* @param changelogUrl - Optional URL to open if update is available
@@ -92,10 +100,15 @@ export class SmartUpdate {
packageName,
currentVersion,
changelogUrl,
cacheStrategy: 'always',
cacheStrategy: 'time-based',
});
return result.status === 'update-available';
return (
result.status === 'update-available' ||
(result.status === 'check-skipped' &&
!!result.latestVersion &&
this.safeIsUpdateAvailable(result.latestVersion, currentVersion))
);
}
/**
@@ -129,12 +142,19 @@ export class SmartUpdate {
const checkTime = new Date();
try {
this.validatePackageName(packageName);
const versionLocal = this.createSmartVersion(currentVersion);
const registryUrl = this.getRegistryUrl();
// Check if we should use cache or check registry
const cacheCheck = await this.cacheManager.shouldCheckRegistry(packageName, cacheStrategy);
const cacheCheck = await this.cacheManager.shouldCheckRegistry(packageName, cacheStrategy, {
currentVersion,
registryUrl,
});
// If we should skip the check due to cache
if (!cacheCheck.shouldCheck) {
return {
const skippedResult: IUpdateCheckResult = {
status: 'check-skipped',
packageName,
currentVersion,
@@ -142,23 +162,26 @@ export class SmartUpdate {
checkTime,
cacheHit: true,
nextCheckTime: cacheCheck.nextCheckTime,
reason: 'Rate limited - checked recently',
reason:
cacheStrategy === 'always'
? 'Cached result reused'
: 'Rate limited - checked recently',
};
this.notifier.notifyUpdateCheckResult(skippedResult);
return skippedResult;
}
// Fetch package info from registry
const npmPackage = await this.getNpmPackageFromRegistry(packageName);
if (!npmPackage) {
throw new RegistryUnavailableError();
}
// Compare versions
const versionNpm = new plugins.smartversion.SmartVersion(npmPackage.version);
const versionLocal = new plugins.smartversion.SmartVersion(currentVersion);
const versionNpm = this.createSmartVersion(npmPackage.version);
const status: TCachedUpdateStatus = versionNpm.greaterThan(versionLocal)
? 'update-available'
: 'up-to-date';
const result: IUpdateCheckResult = {
status: versionNpm.greaterThan(versionLocal) ? 'update-available' : 'up-to-date',
status,
packageName: npmPackage.name,
currentVersion,
latestVersion: npmPackage.version,
@@ -172,14 +195,20 @@ export class SmartUpdate {
// If update is available, handle changelog
if (result.status === 'update-available' && changelogUrl && openChangelog && !process.env.CI) {
this.notifier.notifyOpeningChangelog();
plugins.smartopen.openUrl(changelogUrl);
await plugins.smartopen.openUrl(changelogUrl).catch((error) => {
this.notifier.warn(
`Could not open changelog: ${error instanceof Error ? error.message : String(error)}`
);
});
}
// Update cache if there's an update
if (result.status === 'update-available') {
const cacheStatus = this.cacheManager.createCacheStatus(npmPackage.version, false);
await this.cacheManager.setCached(packageName, cacheStatus);
}
// Cache both positive and negative checks to avoid repeated registry hits.
const cacheStatus = this.cacheManager.createCacheStatus(npmPackage.version, false, {
currentVersion,
registryUrl,
status,
});
await this.cacheManager.setCached(packageName, cacheStatus);
return result;
} catch (error) {
@@ -242,10 +271,8 @@ export class SmartUpdate {
* ```
*/
public async getLatestVersion(packageName: string): Promise<string> {
this.validatePackageName(packageName);
const npmPackage = await this.getNpmPackageFromRegistry(packageName);
if (!npmPackage) {
throw new PackageNotFoundError(packageName);
}
return npmPackage.version;
}
@@ -267,13 +294,58 @@ export class SmartUpdate {
* Fetch package information from the npm registry
* @private
*/
private async getNpmPackageFromRegistry(packageName: string): Promise<plugins.smartnpm.NpmPackage | null> {
private async getNpmPackageFromRegistry(packageName: string): Promise<plugins.smartnpm.NpmPackage> {
this.notifier.notifyCheckingForUpdate(packageName);
try {
const npmPackage = await this.npmRegistry.getPackageInfo(packageName);
if (!npmPackage?.version) {
throw new PackageNotFoundError(packageName);
}
return npmPackage;
} catch (error) {
return null;
if (error instanceof SmartUpdateError) {
throw error;
}
const message = error instanceof Error ? error.message : String(error);
const lowerMessage = message.toLowerCase();
if (lowerMessage.includes('not found') || lowerMessage.includes('404')) {
throw new PackageNotFoundError(packageName);
}
throw new RegistryUnavailableError(message);
}
}
private validatePackageName(packageName: string): void {
if (!packageName || packageName.trim() !== packageName || /\s/.test(packageName)) {
throw new InvalidPackageNameError(packageName);
}
}
private createSmartVersion(version: string): plugins.smartversion.SmartVersion {
try {
return new plugins.smartversion.SmartVersion(version);
} catch (error) {
throw new InvalidVersionError(version, error instanceof Error ? error.message : String(error));
}
}
private isUpdateAvailable(latestVersion: string, currentVersion: string): boolean {
const versionNpm = this.createSmartVersion(latestVersion);
const versionLocal = this.createSmartVersion(currentVersion);
return versionNpm.greaterThan(versionLocal);
}
private safeIsUpdateAvailable(latestVersion: string, currentVersion: string): boolean {
try {
return this.isUpdateAvailable(latestVersion, currentVersion);
} catch {
return false;
}
}
private getRegistryUrl(): string {
return this.npmRegistry.options.npmRegistryUrl || 'https://registry.npmjs.org';
}
}
ts/smartupdate.interfaces.ts
+29 -2
View File
@@ -1,12 +1,19 @@
import type { TLogLevel } from './smartupdate.constants.js';
import type * as smartnpm from '@push.rocks/smartnpm';
export type TCacheStrategy = 'always' | 'never' | 'time-based';
export type TCacheStoreType = 'custom' | 'userHomeDir' | 'ephemeral';
export type TCachedUpdateStatus = 'up-to-date' | 'update-available';
/**
* Cache status stored for each package
*/
export interface ICacheStatus {
lastCheck: number;
latestVersion: string;
currentVersion?: string;
registryUrl?: string;
status?: TCachedUpdateStatus;
performedUpgrade: boolean;
}
@@ -46,6 +53,16 @@ export interface ISmartUpdateOptions {
* @default false
*/
noColor?: boolean;
/**
* Cache storage configuration
* @default { storeType: 'userHomeDir', storeIdentifier: 'global_smartupdate' }
*/
cacheStore?: {
storeType?: TCacheStoreType;
storeIdentifier?: string;
customPath?: string;
};
}
/**
@@ -77,12 +94,12 @@ export interface IUpdateCheckOptions {
/**
* Cache strategy for this check
* - 'always': Always check cache first (default for CLI)
* - 'always': Always use an existing matching cache entry
* - 'never': Always check registry, bypass cache
* - 'time-based': Check based on cache duration
* @default 'time-based'
*/
cacheStrategy?: 'always' | 'never' | 'time-based';
cacheStrategy?: TCacheStrategy;
}
/**
@@ -148,6 +165,16 @@ export interface ICacheOptions {
* Identifier for the key-value store
*/
storeIdentifier?: string;
/**
* Key-value store backend
*/
storeType?: TCacheStoreType;
/**
* Custom path for custom key-value stores
*/
customPath?: string;
}
/**
ts/smartupdate.plugins.ts
+1 -2
View File
@@ -2,7 +2,6 @@ import * as consolecolor from '@push.rocks/consolecolor';
import * as npmextra from '@push.rocks/npmextra';
import * as smartnpm from '@push.rocks/smartnpm';
import * as smartopen from '@push.rocks/smartopen';
import * as smarttime from '@push.rocks/smarttime';
import * as smartversion from '@push.rocks/smartversion';
export { consolecolor, npmextra, smartnpm, smartopen, smarttime, smartversion };
export { consolecolor, npmextra, smartnpm, smartopen, smartversion };