fast-npm-meta 0.4.8 → 1.1.0

package/dist/index.d.mts

@@ -28,6 +28,7 @@ interface PackageVersionsInfoWithMetadata extends PackageManifest {
     specifier: string;
 }
 interface PackageError {
+    status: number;
     name: string;
     error: string;
 }
@@ -45,6 +46,40 @@ interface ResolvedPackageVersion {
 interface ResolvedPackageVersionWithMetadata extends ResolvedPackageVersion, PackageVersionMeta {
 }
 
+interface RetryOptions {
+    /**
+     * The number of times to retry the operation.
+     *
+     * @default 5
+     */
+    retries?: number;
+    /**
+     * The exponential factor to use.
+     *
+     * @default 2
+     */
+    factor?: number;
+    /**
+     * The number of milliseconds before starting the first retry.
+     *
+     * Set this to `0` to retry immediately with no delay.
+     *
+     * @default 1000
+     */
+    minTimeout?: number;
+    /**
+     * The maximum number of milliseconds between two retries.
+     *
+     * @default Infinity
+     */
+    maxTimeout?: number;
+    /**
+     * Randomizes the timeouts by multiplying with a factor between 1 and 2.
+     *
+     * @default false
+     */
+    randomize?: boolean;
+}
 interface FetchOptions<Throw extends boolean = true> {
     /**
      * API endpoint for fetching package versions
@@ -90,6 +125,15 @@ interface GetVersionsOptions<Metadata extends boolean = false, Throw extends boo
      * @default undefined
      */
     after?: string;
+    /**
+     * Retry options for the built-in retry mechanism
+     *
+     * Can be:
+     * - `RetryOptions` object for fine-grained control
+     * - `number` for simple retry count (uses defaults for other options)
+     * - `false` to disable retries
+     */
+    retry?: RetryOptions | number | false;
 }
 interface GetLatestVersionOptions<Metadata extends boolean = false, Throw extends boolean = true> extends FetchOptions<Throw> {
     /**
@@ -104,6 +148,15 @@ interface GetLatestVersionOptions<Metadata extends boolean = false, Throw extend
      * @default false
      */
     metadata?: Metadata;
+    /**
+     * Retry options for the built-in retry mechanism
+     *
+     * Can be:
+     * - `RetryOptions` object for fine-grained control
+     * - `number` for simple retry count (uses defaults for other options)
+     * - `false` to disable retries
+     */
+    retry?: RetryOptions | number | false;
 }
 type InferGetVersionsResult<Metadata, Throw> = Metadata extends true ? Throw extends true ? PackageVersionsInfoWithMetadata : MaybeError<PackageVersionsInfoWithMetadata> : Throw extends true ? PackageVersionsInfo : MaybeError<PackageVersionsInfo>;
 type InferGetLatestVersionResult<Metadata, Throw> = Metadata extends true ? Throw extends true ? ResolvedPackageVersionWithMetadata : MaybeError<ResolvedPackageVersionWithMetadata> : Throw extends true ? ResolvedPackageVersion : MaybeError<ResolvedPackageVersion>;
@@ -131,4 +184,4 @@ declare const NPM_REGISTRY = "https://registry.npmjs.org/";
 declare function pickRegistry(scope: string | null | undefined, npmConfigs: Record<string, unknown>, defaultRegistry?: string): string;
 
 export { NPM_REGISTRY, defaultOptions, getLatestVersion, getLatestVersionBatch, getVersions, getVersionsBatch, pickRegistry };
-export type { Engines, FetchOptions, GetLatestVersionOptions, GetVersionsOptions, InferGetLatestVersionResult, InferGetVersionsResult, MaybeError, PackageError, PackageManifest, PackageManifestError, PackageVersionMeta, PackageVersionsInfo, PackageVersionsInfoWithMetadata, ResolvedPackageVersion, ResolvedPackageVersionWithMetadata };
+export type { Engines, FetchOptions, GetLatestVersionOptions, GetVersionsOptions, InferGetLatestVersionResult, InferGetVersionsResult, MaybeError, PackageError, PackageManifest, PackageManifestError, PackageVersionMeta, PackageVersionsInfo, PackageVersionsInfoWithMetadata, ResolvedPackageVersion, ResolvedPackageVersionWithMetadata, RetryOptions };

package/dist/index.mjs

@@ -1,3 +1,268 @@
+const objectToString = Object.prototype.toString;
+
+const isError = value => objectToString.call(value) === '[object Error]';
+
+const errorMessages = new Set([
+	'network error', // Chrome
+	'Failed to fetch', // Chrome
+	'NetworkError when attempting to fetch resource.', // Firefox
+	'The Internet connection appears to be offline.', // Safari 16
+	'Network request failed', // `cross-fetch`
+	'fetch failed', // Undici (Node.js)
+	'terminated', // Undici (Node.js)
+	' A network error occurred.', // Bun (WebKit)
+	'Network connection lost', // Cloudflare Workers (fetch)
+]);
+
+function isNetworkError(error) {
+	const isValid = error
+		&& isError(error)
+		&& error.name === 'TypeError'
+		&& typeof error.message === 'string';
+
+	if (!isValid) {
+		return false;
+	}
+
+	const {message, stack} = error;
+
+	// Safari 17+ has generic message but no stack for network errors
+	if (message === 'Load failed') {
+		return stack === undefined
+			// Sentry adds its own stack trace to the fetch error, so also check for that
+			|| '__sentry_captured__' in error;
+	}
+
+	// Deno network errors start with specific text
+	if (message.startsWith('error sending request for url')) {
+		return true;
+	}
+
+	// Standard network error messages
+	return errorMessages.has(message);
+}
+
+function validateRetries(retries) {
+	if (typeof retries === 'number') {
+		if (retries < 0) {
+			throw new TypeError('Expected `retries` to be a non-negative number.');
+		}
+
+		if (Number.isNaN(retries)) {
+			throw new TypeError('Expected `retries` to be a valid number or Infinity, got NaN.');
+		}
+	} else if (retries !== undefined) {
+		throw new TypeError('Expected `retries` to be a number or Infinity.');
+	}
+}
+
+function validateNumberOption(name, value, {min = 0, allowInfinity = false} = {}) {
+	if (value === undefined) {
+		return;
+	}
+
+	if (typeof value !== 'number' || Number.isNaN(value)) {
+		throw new TypeError(`Expected \`${name}\` to be a number${allowInfinity ? ' or Infinity' : ''}.`);
+	}
+
+	if (!allowInfinity && !Number.isFinite(value)) {
+		throw new TypeError(`Expected \`${name}\` to be a finite number.`);
+	}
+
+	if (value < min) {
+		throw new TypeError(`Expected \`${name}\` to be \u2265 ${min}.`);
+	}
+}
+
+class AbortError extends Error {
+	constructor(message) {
+		super();
+
+		if (message instanceof Error) {
+			this.originalError = message;
+			({message} = message);
+		} else {
+			this.originalError = new Error(message);
+			this.originalError.stack = this.stack;
+		}
+
+		this.name = 'AbortError';
+		this.message = message;
+	}
+}
+
+function calculateDelay(retriesConsumed, options) {
+	const attempt = Math.max(1, retriesConsumed + 1);
+	const random = options.randomize ? (Math.random() + 1) : 1;
+
+	let timeout = Math.round(random * options.minTimeout * (options.factor ** (attempt - 1)));
+	timeout = Math.min(timeout, options.maxTimeout);
+
+	return timeout;
+}
+
+function calculateRemainingTime(start, max) {
+	if (!Number.isFinite(max)) {
+		return max;
+	}
+
+	return max - (performance.now() - start);
+}
+
+async function onAttemptFailure({error, attemptNumber, retriesConsumed, startTime, options}) {
+	const normalizedError = error instanceof Error
+		? error
+		: new TypeError(`Non-error was thrown: "${error}". You should only throw errors.`);
+
+	if (normalizedError instanceof AbortError) {
+		throw normalizedError.originalError;
+	}
+
+	const retriesLeft = Number.isFinite(options.retries)
+		? Math.max(0, options.retries - retriesConsumed)
+		: options.retries;
+
+	const maxRetryTime = options.maxRetryTime ?? Number.POSITIVE_INFINITY;
+
+	const context = Object.freeze({
+		error: normalizedError,
+		attemptNumber,
+		retriesLeft,
+		retriesConsumed,
+	});
+
+	await options.onFailedAttempt(context);
+
+	if (calculateRemainingTime(startTime, maxRetryTime) <= 0) {
+		throw normalizedError;
+	}
+
+	const consumeRetry = await options.shouldConsumeRetry(context);
+
+	const remainingTime = calculateRemainingTime(startTime, maxRetryTime);
+
+	if (remainingTime <= 0 || retriesLeft <= 0) {
+		throw normalizedError;
+	}
+
+	if (normalizedError instanceof TypeError && !isNetworkError(normalizedError)) {
+		if (consumeRetry) {
+			throw normalizedError;
+		}
+
+		options.signal?.throwIfAborted();
+		return false;
+	}
+
+	if (!await options.shouldRetry(context)) {
+		throw normalizedError;
+	}
+
+	if (!consumeRetry) {
+		options.signal?.throwIfAborted();
+		return false;
+	}
+
+	const delayTime = calculateDelay(retriesConsumed, options);
+	const finalDelay = Math.min(delayTime, remainingTime);
+
+	if (finalDelay > 0) {
+		await new Promise((resolve, reject) => {
+			const onAbort = () => {
+				clearTimeout(timeoutToken);
+				options.signal?.removeEventListener('abort', onAbort);
+				reject(options.signal.reason);
+			};
+
+			const timeoutToken = setTimeout(() => {
+				options.signal?.removeEventListener('abort', onAbort);
+				resolve();
+			}, finalDelay);
+
+			if (options.unref) {
+				timeoutToken.unref?.();
+			}
+
+			options.signal?.addEventListener('abort', onAbort, {once: true});
+		});
+	}
+
+	options.signal?.throwIfAborted();
+
+	return true;
+}
+
+async function pRetry(input, options = {}) {
+	options = {...options};
+
+	validateRetries(options.retries);
+
+	if (Object.hasOwn(options, 'forever')) {
+		throw new Error('The `forever` option is no longer supported. For many use-cases, you can set `retries: Infinity` instead.');
+	}
+
+	options.retries ??= 10;
+	options.factor ??= 2;
+	options.minTimeout ??= 1000;
+	options.maxTimeout ??= Number.POSITIVE_INFINITY;
+	options.maxRetryTime ??= Number.POSITIVE_INFINITY;
+	options.randomize ??= false;
+	options.onFailedAttempt ??= () => {};
+	options.shouldRetry ??= () => true;
+	options.shouldConsumeRetry ??= () => true;
+
+	// Validate numeric options and normalize edge cases
+	validateNumberOption('factor', options.factor, {min: 0, allowInfinity: false});
+	validateNumberOption('minTimeout', options.minTimeout, {min: 0, allowInfinity: false});
+	validateNumberOption('maxTimeout', options.maxTimeout, {min: 0, allowInfinity: true});
+	validateNumberOption('maxRetryTime', options.maxRetryTime, {min: 0, allowInfinity: true});
+
+	// Treat non-positive factor as 1 to avoid zero backoff or negative behavior
+	if (!(options.factor > 0)) {
+		options.factor = 1;
+	}
+
+	options.signal?.throwIfAborted();
+
+	let attemptNumber = 0;
+	let retriesConsumed = 0;
+	const startTime = performance.now();
+
+	while (Number.isFinite(options.retries) ? retriesConsumed <= options.retries : true) {
+		attemptNumber++;
+
+		try {
+			options.signal?.throwIfAborted();
+
+			const result = await input(attemptNumber);
+
+			options.signal?.throwIfAborted();
+
+			return result;
+		} catch (error) {
+			if (await onAttemptFailure({
+				error,
+				attemptNumber,
+				retriesConsumed,
+				startTime,
+				options,
+			})) {
+				retriesConsumed++;
+			}
+		}
+	}
+
+	// Should not reach here, but in case it does, throw an error
+	throw new Error('Retry attempts exhausted without throwing an error.');
+}
+
+const defaultRetryOptions = {
+  retries: 5,
+  factor: 2,
+  minTimeout: 1e3,
+  maxTimeout: Infinity,
+  randomize: false
+};
 const defaultOptions = {
   /**
    * API endpoint for fetching package versions
@@ -10,7 +275,8 @@ async function getLatestVersionBatch(packages, options = {}) {
   const {
     apiEndpoint = defaultOptions.apiEndpoint,
     fetch: fetchApi = fetch,
-    throw: throwError = true
+    throw: throwError = true,
+    retry = defaultRetryOptions
   } = options;
   let query = [
     options.force ? "force=true" : "",
@@ -19,7 +285,9 @@ async function getLatestVersionBatch(packages, options = {}) {
   ].filter(Boolean).join("&");
   if (query)
     query = `?${query}`;
-  const data = await fetchApi(new URL(packages.join("+") + query, apiEndpoint)).then((r) => r.json());
+  const fetchFn = () => fetchApi(new URL(packages.join("+") + query, apiEndpoint)).then((r) => r.json());
+  const retryOptions = typeof retry === "number" ? { ...defaultRetryOptions, retries: retry } : retry;
+  const data = await (retryOptions === false ? fetchFn() : pRetry(fetchFn, retryOptions));
   const list = toArray(data);
   return throwError ? throwErrorObject(list) : list;
 }
@@ -31,7 +299,8 @@ async function getVersionsBatch(packages, options = {}) {
   const {
     apiEndpoint = defaultOptions.apiEndpoint,
     fetch: fetchApi = fetch,
-    throw: throwError = true
+    throw: throwError = true,
+    retry = defaultRetryOptions
   } = options;
   let query = [
     options.force ? "force=true" : "",
@@ -42,7 +311,11 @@ async function getVersionsBatch(packages, options = {}) {
   ].filter(Boolean).join("&");
   if (query)
     query = `?${query}`;
-  const data = await fetchApi(new URL(`/versions/${packages.join("+")}${query}`, apiEndpoint)).then((r) => r.json());
+  const fetchFn = () => fetchApi(new URL(`/versions/${packages.join("+")}${query}`, apiEndpoint)).then((r) => r.json());
+  const data = await (retry === false ? fetchFn() : pRetry(
+    fetchFn,
+    typeof retry === "number" ? { ...defaultRetryOptions, retries: retry } : retry
+  ));
   const list = toArray(data);
   return throwError ? throwErrorObject(list) : list;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fast-npm-meta",
   "type": "module",
-  "version": "0.4.8",
+  "version": "1.1.0",
   "description": "Get npm package metadata",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -23,6 +23,9 @@
   "files": [
     "dist"
   ],
+  "devDependencies": {
+    "p-retry": "^7.1.0"
+  },
   "scripts": {
     "build": "unbuild",
     "dev": "unbuild --stub"