fast-npm-meta 1.0.0 → 1.2.0

package/dist/index.d.mts

@@ -1,125 +1,182 @@
+//#region ../shared/types.d.ts
 interface PackageManifest {
-    name: string;
-    distTags: Record<string, string> & {
-        latest: string;
-    };
-    versionsMeta: Record<string, PackageVersionMeta>;
-    timeCreated: string;
-    timeModified: string;
-    lastSynced: number;
+  name: string;
+  distTags: Record<string, string> & {
+    latest: string;
+  };
+  versionsMeta: Record<string, PackageVersionMeta>;
+  timeCreated: string;
+  timeModified: string;
+  lastSynced: number;
 }
 type Engines = Partial<Record<string, string>>;
 interface PackageVersionMeta {
-    time?: string;
-    engines?: Engines;
-    deprecated?: string;
-    provenance?: 'trustedPublisher' | boolean;
-    integrity?: string;
+  time?: string;
+  engines?: Engines;
+  deprecated?: string;
+  provenance?: 'trustedPublisher' | boolean;
+  integrity?: string;
 }
 interface PackageVersionsInfo extends Pick<PackageManifest, 'name' | 'distTags' | 'lastSynced'> {
-    versions: string[];
-    specifier: string;
-    time: {
-        created: string;
-        modified: string;
-    } & Record<string, string>;
+  versions: string[];
+  specifier: string;
+  time: {
+    created: string;
+    modified: string;
+  } & Record<string, string>;
 }
 interface PackageVersionsInfoWithMetadata extends PackageManifest {
-    specifier: string;
+  specifier: string;
 }
 interface PackageError {
-    name: string;
-    error: string;
+  status: number;
+  name: string;
+  error: string;
 }
 type MaybeError<T> = T | PackageError;
 interface PackageManifestError extends PackageError {
-    lastSynced: number;
+  lastSynced: number;
 }
 interface ResolvedPackageVersion {
-    name: string;
-    version: string | null;
-    specifier: string;
-    publishedAt: string | null;
-    lastSynced: number;
+  name: string;
+  version: string | null;
+  specifier: string;
+  publishedAt: string | null;
+  lastSynced: number;
 }
-interface ResolvedPackageVersionWithMetadata extends ResolvedPackageVersion, PackageVersionMeta {
+interface ResolvedPackageVersionWithMetadata extends ResolvedPackageVersion, PackageVersionMeta {}
+//#endregion
+//#region src/types.d.ts
+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
-     *
-     * @default 'https://npm.antfu.dev/'
-     */
-    apiEndpoint?: string;
-    /**
-     * Fetch function
-     *
-     * @default [globalThis.fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
-     */
-    fetch?: typeof fetch;
-    /**
-     * Should throw error or return error object
-     *
-     * @default true
-     */
-    throw?: Throw;
+  /**
+   * API endpoint for fetching package versions
+   *
+   * @default 'https://npm.antfu.dev/'
+   */
+  apiEndpoint?: string;
+  /**
+   * Fetch function
+   *
+   * @default [globalThis.fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+   */
+  fetch?: typeof fetch;
+  /**
+   * Should throw error or return error object
+   *
+   * @default true
+   */
+  throw?: Throw;
 }
 interface GetVersionsOptions<Metadata extends boolean = false, Throw extends boolean = true> extends FetchOptions<Throw> {
-    /**
-     * By pass cache and get the latest data
-     *
-     * @default false
-     */
-    force?: boolean;
-    /**
-     * Include all versions that are newer than the specified version
-     *
-     * @default false
-     */
-    loose?: boolean;
-    /**
-     * Includes metadata, this will change the return type
-     *
-     * @default false
-     */
-    metadata?: Metadata;
-    /**
-     * Only return versions published after this ISO date-time
-     *
-     * @default undefined
-     */
-    after?: string;
+  /**
+   * By pass cache and get the latest data
+   *
+   * @default false
+   */
+  force?: boolean;
+  /**
+   * Include all versions that are newer than the specified version
+   *
+   * @default false
+   */
+  loose?: boolean;
+  /**
+   * Includes metadata, this will change the return type
+   *
+   * @default false
+   */
+  metadata?: Metadata;
+  /**
+   * Only return versions published after this ISO date-time
+   *
+   * @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> {
-    /**
-     * By pass cache and get the latest data
-     *
-     * @default false
-     */
-    force?: boolean;
-    /**
-     * Includes metadata
-     *
-     * @default false
-     */
-    metadata?: Metadata;
+  /**
+   * By pass cache and get the latest data
+   *
+   * @default false
+   */
+  force?: boolean;
+  /**
+   * Includes metadata
+   *
+   * @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>;
+//#endregion
+//#region src/api.d.ts
 declare const defaultOptions: {
-    /**
-     * API endpoint for fetching package versions
-     *
-     * @default 'https://npm.antfu.dev/'
-     */
-    apiEndpoint: string;
+  /**
+   * API endpoint for fetching package versions
+   *
+   * @default 'https://npm.antfu.dev/'
+   */
+  apiEndpoint: string;
 };
 declare function getLatestVersionBatch<Metadata extends boolean = false, Throw extends boolean = true>(packages: string[], options?: GetLatestVersionOptions<Metadata, Throw>): Promise<InferGetLatestVersionResult<Metadata, Throw>[]>;
 declare function getLatestVersion<Metadata extends boolean = false, Throw extends boolean = true>(name: string, options?: GetLatestVersionOptions<Metadata, Throw>): Promise<InferGetLatestVersionResult<Metadata, Throw>>;
 declare function getVersionsBatch<Metadata extends boolean = false, Throw extends boolean = true>(packages: string[], options?: GetVersionsOptions<Metadata, Throw>): Promise<InferGetVersionsResult<Metadata, Throw>[]>;
 declare function getVersions<Metadata extends boolean = false, Throw extends boolean = true>(name: string, options?: GetVersionsOptions<Metadata, Throw>): Promise<InferGetVersionsResult<Metadata, Throw>>;
-
+//#endregion
+//#region src/helpers.d.ts
 declare const NPM_REGISTRY = "https://registry.npmjs.org/";
 /**
  * Lightweight replacement of `npm-registry-fetch` function `pickRegistry`'
@@ -129,6 +186,5 @@ declare const NPM_REGISTRY = "https://registry.npmjs.org/";
  * @param defaultRegistry - default registry, default to '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 };
+//#endregion
+export { Engines, FetchOptions, GetLatestVersionOptions, GetVersionsOptions, InferGetLatestVersionResult, InferGetVersionsResult, MaybeError, NPM_REGISTRY, PackageError, PackageManifest, PackageManifestError, PackageVersionMeta, PackageVersionsInfo, PackageVersionsInfoWithMetadata, ResolvedPackageVersion, ResolvedPackageVersionWithMetadata, RetryOptions, defaultOptions, getLatestVersion, getLatestVersionBatch, getVersions, getVersionsBatch, pickRegistry };

package/dist/index.mjs

@@ -1,78 +1,239 @@
-const defaultOptions = {
-  /**
-   * API endpoint for fetching package versions
-   *
-   * @default 'https://npm.antfu.dev/'
-   */
-  apiEndpoint: "https://npm.antfu.dev/"
+//#region ../node_modules/.pnpm/is-network-error@1.3.0/node_modules/is-network-error/index.js
+const objectToString = Object.prototype.toString;
+const isError = (value) => objectToString.call(value) === "[object Error]";
+const errorMessages = new Set([
+	"network error",
+	"Failed to fetch",
+	"NetworkError when attempting to fetch resource.",
+	"The Internet connection appears to be offline.",
+	"Network request failed",
+	"fetch failed",
+	"terminated",
+	" A network error occurred.",
+	"Network connection lost"
+]);
+function isNetworkError(error) {
+	if (!(error && isError(error) && error.name === "TypeError" && typeof error.message === "string")) return false;
+	const { message, stack } = error;
+	if (message === "Load failed") return stack === void 0 || "__sentry_captured__" in error;
+	if (message.startsWith("error sending request for url")) return true;
+	return errorMessages.has(message);
+}
+
+//#endregion
+//#region ../node_modules/.pnpm/p-retry@7.1.1/node_modules/p-retry/index.js
+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 !== void 0) throw new TypeError("Expected `retries` to be a number or Infinity.");
+}
+function validateNumberOption(name, value, { min = 0, allowInfinity = false } = {}) {
+	if (value === void 0) 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}.`);
+}
+var AbortError = class 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 : /* @__PURE__ */ 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);
+	options.signal?.throwIfAborted();
+	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 ??= 1e3;
+	options.maxTimeout ??= Number.POSITIVE_INFINITY;
+	options.maxRetryTime ??= Number.POSITIVE_INFINITY;
+	options.randomize ??= false;
+	options.onFailedAttempt ??= () => {};
+	options.shouldRetry ??= () => true;
+	options.shouldConsumeRetry ??= () => true;
+	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
+	});
+	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++;
+		}
+	}
+	throw new Error("Retry attempts exhausted without throwing an error.");
+}
+
+//#endregion
+//#region src/api.ts
+const defaultRetryOptions = {
+	retries: 5,
+	factor: 2,
+	minTimeout: 1e3,
+	maxTimeout: Infinity,
+	randomize: false
 };
+const defaultOptions = { apiEndpoint: "https://npm.antfu.dev/" };
 async function getLatestVersionBatch(packages, options = {}) {
-  const {
-    apiEndpoint = defaultOptions.apiEndpoint,
-    fetch: fetchApi = fetch,
-    throw: throwError = true
-  } = options;
-  let query = [
-    options.force ? "force=true" : "",
-    options.metadata ? "metadata=true" : "",
-    throwError ? "" : "throw=false"
-  ].filter(Boolean).join("&");
-  if (query)
-    query = `?${query}`;
-  const data = await fetchApi(new URL(packages.join("+") + query, apiEndpoint)).then((r) => r.json());
-  const list = toArray(data);
-  return throwError ? throwErrorObject(list) : list;
+	const { apiEndpoint = defaultOptions.apiEndpoint, fetch: fetchApi = fetch, throw: throwError = true, retry = defaultRetryOptions } = options;
+	let query = [
+		options.force ? "force=true" : "",
+		options.metadata ? "metadata=true" : "",
+		throwError ? "" : "throw=false"
+	].filter(Boolean).join("&");
+	if (query) query = `?${query}`;
+	const fetchFn = () => fetchApi(new URL(packages.join("+") + query, apiEndpoint)).then((r) => r.json());
+	const retryOptions = typeof retry === "number" ? {
+		...defaultRetryOptions,
+		retries: retry
+	} : retry;
+	const list = toArray(await (retryOptions === false ? fetchFn() : pRetry(fetchFn, retryOptions)));
+	return throwError ? throwErrorObject(list) : list;
 }
 async function getLatestVersion(name, options = {}) {
-  const [data] = await getLatestVersionBatch([name], options);
-  return data;
+	const [data] = await getLatestVersionBatch([name], options);
+	return data;
 }
 async function getVersionsBatch(packages, options = {}) {
-  const {
-    apiEndpoint = defaultOptions.apiEndpoint,
-    fetch: fetchApi = fetch,
-    throw: throwError = true
-  } = options;
-  let query = [
-    options.force ? "force=true" : "",
-    options.loose ? "loose=true" : "",
-    options.metadata ? "metadata=true" : "",
-    options.after ? `after=${encodeURIComponent(options.after)}` : "",
-    throwError ? "" : "throw=false"
-  ].filter(Boolean).join("&");
-  if (query)
-    query = `?${query}`;
-  const data = await fetchApi(new URL(`/versions/${packages.join("+")}${query}`, apiEndpoint)).then((r) => r.json());
-  const list = toArray(data);
-  return throwError ? throwErrorObject(list) : list;
+	const { apiEndpoint = defaultOptions.apiEndpoint, fetch: fetchApi = fetch, throw: throwError = true, retry = defaultRetryOptions } = options;
+	let query = [
+		options.force ? "force=true" : "",
+		options.loose ? "loose=true" : "",
+		options.metadata ? "metadata=true" : "",
+		options.after ? `after=${encodeURIComponent(options.after)}` : "",
+		throwError ? "" : "throw=false"
+	].filter(Boolean).join("&");
+	if (query) query = `?${query}`;
+	const fetchFn = () => fetchApi(new URL(`/versions/${packages.join("+")}${query}`, apiEndpoint)).then((r) => r.json());
+	const list = toArray(await (retry === false ? fetchFn() : pRetry(fetchFn, typeof retry === "number" ? {
+		...defaultRetryOptions,
+		retries: retry
+	} : retry)));
+	return throwError ? throwErrorObject(list) : list;
 }
 async function getVersions(name, options = {}) {
-  const [data] = await getVersionsBatch([name], options);
-  return data;
+	const [data] = await getVersionsBatch([name], options);
+	return data;
 }
 function throwErrorObject(data) {
-  for (const item of toArray(data)) {
-    if (item && "error" in item)
-      throw new Error(item.message || item.error);
-  }
-  return data;
+	for (const item of toArray(data)) if (item && "error" in item) throw new Error(item.message || item.error);
+	return data;
 }
 function toArray(data) {
-  if (Array.isArray(data))
-    return data;
-  return [data];
+	if (Array.isArray(data)) return data;
+	return [data];
 }
 
+//#endregion
+//#region src/helpers.ts
 const NPM_REGISTRY = "https://registry.npmjs.org/";
+/**
+* Lightweight replacement of `npm-registry-fetch` function `pickRegistry`'
+*
+* @param scope - scope of package, get from 'npm-package-arg'
+* @param npmConfigs - npm configs, read from `.npmrc` file
+* @param defaultRegistry - default registry, default to 'https://registry.npmjs.org/'
+*/
 function pickRegistry(scope, npmConfigs, defaultRegistry = NPM_REGISTRY) {
-  let registry = scope ? npmConfigs[`${scope.replace(/^@?/, "@")}:registry`] : void 0;
-  if (!registry && typeof npmConfigs.scope === "string") {
-    registry = npmConfigs[`${npmConfigs.scope.replace(/^@?/, "@")}:registry`];
-  }
-  if (!registry) {
-    registry = npmConfigs.registry || defaultRegistry;
-  }
-  return registry;
+	let registry = scope ? npmConfigs[`${scope.replace(/^@?/, "@")}:registry`] : void 0;
+	if (!registry && typeof npmConfigs.scope === "string") registry = npmConfigs[`${npmConfigs.scope.replace(/^@?/, "@")}:registry`];
+	if (!registry) registry = npmConfigs.registry || defaultRegistry;
+	return registry;
 }
 
-export { NPM_REGISTRY, defaultOptions, getLatestVersion, getLatestVersionBatch, getVersions, getVersionsBatch, pickRegistry };
+//#endregion
+export { NPM_REGISTRY, defaultOptions, getLatestVersion, getLatestVersionBatch, getVersions, getVersionsBatch, pickRegistry };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fast-npm-meta",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Get npm package metadata",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -15,16 +15,19 @@
   "keywords": [],
   "sideEffects": false,
   "exports": {
-    ".": "./dist/index.mjs"
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
   },
-  "main": "./dist/index.mjs",
-  "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "files": [
     "dist"
   ],
+  "devDependencies": {
+    "p-retry": "^7.1.1",
+    "tsdown": "^0.20.1"
+  },
   "scripts": {
-    "build": "unbuild",
-    "dev": "unbuild --stub"
+    "build": "tsdown",
+    "dev": "tsdown --watch"
   }
 }