@esmx/fetch 3.0.0-rc.10

package/dist/fetch-pkg.d.ts

@@ -0,0 +1,7 @@
+import type { FetchPkgOptions, FetchResult } from './types';
+/**
+ * 获取文件，并缓存到本地。如果有缓存则使用缓存
+ */
+export declare function fetchPkg<Level extends number>({ cacheDir, outputDir, noCache, returnLevel, logger, axiosReqCfg, name, url, onFinally }: FetchPkgOptions & {
+    returnLevel?: Level;
+}): Promise<FetchResult<Level>>;

package/dist/fetch-pkg.mjs

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import path from "node:path";
+import genSysCacheDir from "cachedir";
+import { downloadFile, getHashText } from "./utils.mjs";
+const sysCacheDir = path.join(genSysCacheDir("npm-esmx"), "packages");
+export async function fetchPkg({
+  cacheDir = sysCacheDir,
+  outputDir,
+  noCache,
+  returnLevel = 2,
+  logger = console.log,
+  axiosReqCfg = {},
+  name,
+  url = "",
+  onFinally = () => {
+  }
+}) {
+  const returnWrapper = (ans) => {
+    onFinally(ans);
+    return returnLevel === 0 ? ans.hasError : ans;
+  };
+  const paramsChecker = () => {
+    url = axiosReqCfg.url || url;
+    if (axiosReqCfg.baseURL) {
+      url = new URL(url, axiosReqCfg.baseURL).href;
+    }
+    if (!name) {
+      return returnWrapper({
+        hasError: true,
+        name,
+        url,
+        error: new Error("name is empty")
+      });
+    }
+    if (!url) {
+      return returnWrapper({
+        hasError: true,
+        name,
+        url,
+        error: new Error("url is empty")
+      });
+    }
+    const urlInfo2 = new URL(url);
+    urlInfo2.searchParams.append(Date.now() + "_", Date.now() + "");
+    axiosReqCfg.headers = axiosReqCfg.headers || {};
+    axiosReqCfg.headers["Cache-Control"] = axiosReqCfg.headers["Cache-Control"] || "no-cache";
+    axiosReqCfg.headers.Pragma = axiosReqCfg.headers.Pragma || "no-cache";
+    axiosReqCfg.headers.Expires = axiosReqCfg.headers.Expires || "0";
+    url = urlInfo2.href;
+    if (noCache && !outputDir) {
+      return returnWrapper({
+        hasError: true,
+        name,
+        url,
+        error: new Error("outputFilePath is empty")
+      });
+    }
+    if (!noCache && cacheDir === "") {
+      return returnWrapper({
+        hasError: true,
+        name,
+        url,
+        error: new Error("cacheDir is empty")
+      });
+    }
+  };
+  const initDirs = async () => {
+    if (outputDir && !fs.existsSync(outputDir)) {
+      await fs.promises.mkdir(outputDir, { recursive: true });
+    }
+    if (!noCache) {
+      if (!fs.existsSync(cacheDir)) {
+        await fs.promises.mkdir(cacheDir, { recursive: true });
+      }
+    }
+  };
+  const t = paramsChecker();
+  logger?.(`[fetch] [${name}] From ${url}`);
+  if (t) {
+    return t;
+  }
+  await initDirs();
+  const urlInfo = new URL(url);
+  const fileExt = path.parse(urlInfo.pathname).ext;
+  urlInfo.pathname = urlInfo.pathname.replace(
+    new RegExp(fileExt + "$"),
+    ".txt"
+  );
+  const hashUrl = urlInfo.href;
+  let hash = "";
+  let hashAlg = "";
+  if (!noCache) {
+    const hashInfo = await getHashText(hashUrl, {
+      ...axiosReqCfg,
+      onDownloadProgress: void 0
+    });
+    if (hashInfo.error) {
+      logger?.(`[fetch] [${name}] Error: ${hashInfo.error}`);
+      return returnWrapper({
+        hasError: true,
+        name,
+        url,
+        error: hashInfo.error
+      });
+    }
+    ({ hash, hashAlg } = hashInfo);
+  }
+  const download2output = noCache || !hash;
+  if (download2output && !outputDir) {
+    logger?.(`[fetch] [${name}] Error: outputDir is empty`);
+    return returnWrapper({
+      hasError: true,
+      name,
+      url,
+      error: new Error("outputDir is empty")
+    });
+  }
+  const outputFilePath = outputDir ? path.join(outputDir, name + fileExt) : "";
+  const cacheFilePath = path.join(cacheDir, hash + fileExt);
+  const tmpFilePath = (download2output ? outputFilePath : path.join(cacheDir, hash + fileExt)) + ".tmp";
+  if (hash && fs.existsSync(cacheFilePath)) {
+    logger?.(`[fetch] [${name}] Hit cache`);
+    if (outputFilePath) {
+      await fs.promises.cp(cacheFilePath, outputFilePath, {
+        force: true
+      });
+    }
+    return returnWrapper({
+      hasError: false,
+      name,
+      url,
+      filePath: outputFilePath || cacheFilePath,
+      cacheFilePath,
+      hash,
+      hitCache: true
+    });
+  }
+  const error = await downloadFile(
+    url,
+    tmpFilePath,
+    hash,
+    hashAlg,
+    axiosReqCfg
+  );
+  if (error) {
+    const err = error.error;
+    switch (error.errType) {
+      case "axios":
+        logger?.(`[fetch] [${name}] Error: ${err.message}`);
+        break;
+      case "file":
+        logger?.(`[fetch] [${name}] Write file error: ${err.message}`);
+        break;
+      case "hash":
+        logger?.(`[fetch] [${name}] Hash not match`);
+        break;
+    }
+    return returnWrapper({ hasError: true, name, url, error: err });
+  }
+  if (download2output) {
+    await fs.promises.rename(tmpFilePath, outputFilePath);
+    logger?.(
+      `[fetch] [${name}] Downloaded without cache: ${outputFilePath}`
+    );
+    return returnWrapper({
+      hasError: false,
+      name,
+      url,
+      filePath: outputFilePath,
+      cacheFilePath: outputFilePath,
+      hash,
+      hitCache: true
+    });
+  } else {
+    await fs.promises.rename(tmpFilePath, cacheFilePath);
+    if (outputFilePath) {
+      await fs.promises.cp(cacheFilePath, outputFilePath, {
+        force: true
+      });
+    }
+    const filePath = outputFilePath || cacheFilePath;
+    logger?.(`[fetch] [${name}] Downloaded: ${filePath}`);
+    return returnWrapper({
+      hasError: false,
+      name,
+      url,
+      filePath,
+      cacheFilePath,
+      hash,
+      hitCache: false
+    });
+  }
+}

package/dist/fetch-pkgs.d.ts

@@ -0,0 +1,14 @@
+import type { FetchPkgsOptions, FetchPkgsWithBarOptions, FetchResults } from './types';
+/**
+ * 获取多个文件，并缓存到本地。如果有缓存则使用缓存。
+ */
+export declare function fetchPkgs<Level extends number>({ packs, returnLevel, onEachFinally, ...options }: FetchPkgsOptions & {
+    returnLevel?: Level;
+}): Promise<FetchResults<Level>>;
+/**
+ * 获取多个文件，并缓存到本地。如果有缓存则使用缓存。带有进度条
+ */
+export declare function fetchPkgsWithBar<Level extends number>({ packs, axiosReqCfg, multiBarCfg, logger, onEachFinally, ...options }: FetchPkgsWithBarOptions & {
+    returnLevel?: Level;
+}): Promise<FetchResults<Level>>;
+export { fetchPkgsWithBar as fetchPkgsWithProgress };

package/dist/fetch-pkgs.mjs

@@ -0,0 +1,102 @@
+import { styleText } from "node:util";
+import { MultiBar } from "cli-progress";
+import { fetchPkg } from "./fetch-pkg.mjs";
+export async function fetchPkgs({
+  packs,
+  returnLevel = 2,
+  onEachFinally = () => {
+  },
+  ...options
+}) {
+  if (new Set(packs.map((pack) => pack.name)).size !== packs.length) {
+    return returnLevel === 0 ? false : returnLevel === 1 ? packs.map(() => false) : packs.map(() => ({
+      hasError: true,
+      name: "",
+      url: "",
+      error: new Error("Duplicate name")
+    }));
+  }
+  const axiosReqCfg = options.axiosReqCfg || {};
+  const results = await Promise.all(
+    packs.map(
+      (pack) => fetchPkg({
+        ...options,
+        returnLevel,
+        ...pack,
+        axiosReqCfg: {
+          ...axiosReqCfg,
+          ...pack.axiosReqCfg || {}
+        },
+        onFinally: (result) => onEachFinally(result)
+      })
+    )
+  );
+  return returnLevel === 0 ? results.every((r) => !r) : returnLevel === 1 ? results.map((r) => !r.hasError) : results;
+}
+export async function fetchPkgsWithBar({
+  packs,
+  axiosReqCfg = {},
+  multiBarCfg = {},
+  logger = (barLogger, str) => barLogger(str),
+  onEachFinally = () => {
+  },
+  ...options
+}) {
+  const multiBar = new MultiBar({
+    stopOnComplete: true,
+    format: " [{bar}] {percentage}% | {status} | {name}",
+    forceRedraw: true,
+    barCompleteChar: "#",
+    barIncompleteChar: "_",
+    autopadding: true,
+    ...multiBarCfg
+  });
+  const multiBarLogger = (str = "") => {
+    multiBar.log(str.trimEnd() + "\n");
+    multiBar.update();
+  };
+  const bars = packs.reduce((obj, { name }) => {
+    obj[name] = multiBar.create(1, 0, { status: "WAT", name });
+    return obj;
+  }, {});
+  const timer = setInterval(() => multiBar.update(), 1e3);
+  const fetchPkgsPacks = packs.map((pack) => {
+    const ans = pack;
+    ans.axiosReqCfg = ans.axiosReqCfg || {};
+    const onDownloadProgress = ans.axiosReqCfg.onDownloadProgress || axiosReqCfg.onDownloadProgress;
+    ans.axiosReqCfg.onDownloadProgress = (progressEvent) => {
+      bars[ans.name].setTotal(
+        progressEvent?.total ?? progressEvent.loaded + 1
+      );
+      bars[ans.name].update(progressEvent.loaded, {
+        status: styleText("yellow", "DLD"),
+        name: ans.name
+      });
+      onDownloadProgress?.(progressEvent);
+    };
+    if (ans.logger) {
+      const orgLogger = ans.logger;
+      ans.logger = (str = "") => orgLogger(multiBarLogger, str);
+    }
+    return ans;
+  });
+  const results = await fetchPkgs({
+    packs: fetchPkgsPacks,
+    ...options,
+    axiosReqCfg,
+    logger: logger && ((str) => logger(multiBarLogger, str)),
+    onEachFinally: (result) => {
+      bars[result.name].update(Number.POSITIVE_INFINITY, {
+        status: result.hasError ? styleText("red", "ERR") : styleText("green", result.hitCache ? "HIT" : "SUC"),
+        name: result.name
+      });
+      multiBar.update();
+      onEachFinally(result);
+    }
+  });
+  clearInterval(timer);
+  multiBar.update();
+  multiBar.stop();
+  return results;
+}
+export { fetchPkgsWithBar as fetchPkgsWithProgress };

package/dist/fetch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fetch.test.mjs

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "vitest";
+import { fetchPkgsWithProgress } from "./index.mjs";
+test("base", async () => {
+  const urls = ["ssr-html/versions/latest.tgz", "ssr-html/versions/1.0.tgz"];
+  const outputDir = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "output"
+  );
+  await fetchPkgsWithProgress({
+    outputDir,
+    axiosReqCfg: {
+      baseURL: "https://www.esmnext.com",
+      timeout: 4500
+    },
+    packs: urls.map((url) => ({ url, name: url.split("/")[0] }))
+  }).then((...args) => {
+    console.log(...args);
+  });
+}, 5e3);

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './fetch-pkg';
+export * from './fetch-pkgs';

package/dist/index.mjs

@@ -0,0 +1,3 @@
+export * from "./types.mjs";
+export * from "./fetch-pkg.mjs";
+export * from "./fetch-pkgs.mjs";

package/dist/types.d.ts

@@ -0,0 +1,139 @@
+import type { AxiosRequestConfig } from 'axios';
+import type { Options as MultiBarOptions } from 'cli-progress';
+export interface FetchBaseOptions {
+    /**
+     * 是否不使用缓存 默认为 `false` (即默认使用缓存)
+     * 现在的逻辑是不使用缓存时，不校验 hash 值。
+     */
+    noCache?: boolean;
+    /**
+     * 缓存文件夹路径 默认为 `{system cache dir}/npm-esmx/packages`。
+     * 当 `noCache` 为 `true` 时，该参数无效。
+     * 当 `noCache` 为 `false` 时，省略该参数会导致报错 `cacheDir is empty`。
+     */
+    cacheDir?: string;
+    /**
+     * 输出的文件夹路径。
+     * 省略时不输出文件，如果使用缓存会下载到缓存。
+     * 不使用缓存时或无hash文件时，省略则会导致报错 `outputDir is empty`。
+     * 目前，如果不使用缓存，会直接下载到输出，且不进行 hash 校验。
+     */
+    outputDir?: string;
+    /**
+     * 返回结果的级别 默认为 `2` (即默认返回详细结果)
+     * - `0`: 如果没有发生任何错误，返回 `true`，否则返回 `false`；
+     * - `1`: 根据入参顺序，返回 `boolean[]`，表示是否成功；
+     * - `2`: 返回详细结果。
+     */
+    returnLevel?: number;
+    /**
+     * 日志输出函数 默认为 `console.log`
+     * @param str string 输出的字符串
+     * @returns void
+     */
+    logger?: (str?: string) => void;
+    /**
+     * axios 请求配置
+     */
+    axiosReqCfg?: AxiosRequestConfig;
+    /**
+     * 包下载结束时的回调函数
+     * @param pack 包信息
+     * @param result 结果
+     */
+    onFinally?: (result: FetchResultSuccess | FetchResultError) => void;
+}
+export interface FetchPkgOptions extends FetchBaseOptions {
+    /**
+     * 包名。用于输出和保存时的文件名。
+     */
+    name: string;
+    /**
+     * 下载地址。优先级低于 `axiosReqCfg?.url`
+     */
+    url?: string;
+}
+export interface FetchPkgsOptions extends FetchBaseOptions {
+    /**
+     * 请确保每个包的 `name` 不同，否则会报错 `Duplicate name`。文件将会被下载到 `{outputDir}/{name}.ext`。
+     */
+    packs: FetchPkgOptions[];
+    /**
+     * 每个包下载结束时的回调函数
+     * @param pack 包信息
+     * @param result 结果
+     */
+    onEachFinally?: (result: FetchResultSuccess | FetchResultError) => void;
+}
+export type FetchPkgWithBarLogger = (multiBarLogger: (data?: string) => void, str?: string) => void;
+export interface FetchPkgWithBarOptions extends Omit<FetchPkgOptions, 'logger'> {
+    /**
+     * 进度条日志输出函数，默认为空（不输出东西）。可以使用 `(barLogger, str) => barLogger(str)` 来输出日志。
+     * @param multiBarLogger `(data: string) => void` 进度条自带的日志输出函数，请通过该函数进行日志输出
+     * @param str string 输出的字符串
+     * @returns void
+     */
+    logger?: FetchPkgWithBarLogger;
+}
+export interface FetchPkgsWithBarOptions extends Omit<FetchBaseOptions, 'logger'> {
+    /**
+     * 进度条日志输出函数，默认为 `(barLogger, str) => barLogger(str)`
+     * @param multiBarLogger `(data: string) => void` 进度条自带的日志输出函数，请通过该函数进行日志输出
+     * @param str string 输出的字符串
+     * @returns void
+     */
+    logger?: FetchPkgWithBarLogger;
+    /**
+     * 进度条配置
+     */
+    multiBarCfg?: MultiBarOptions;
+    /**
+     * 每个包下载结束时的回调函数
+     * @param pack 包信息
+     * @param result 结果
+     */
+    onEachFinally?: (result: FetchResultSuccess | FetchResultError) => void;
+    packs: FetchPkgWithBarOptions[];
+}
+export interface FetchResultBase {
+    /**
+     * 资源是从哪个 URL 获取的
+     */
+    url: string;
+    /**
+     * 包名。用于输出和保存时的文件名。
+     */
+    name: string;
+}
+export interface FetchResultSuccess extends FetchResultBase {
+    hasError: false;
+    /**
+     * 输出的文件路径
+     * 如果无 outputPath，且使用缓存，则为缓存文件路径。
+     */
+    filePath: string;
+    /**
+     * 缓存文件路径 默认为 `{system cache dir}/npm-esmx/packages/hash.ext`
+     * 如果不使用缓存，则为空字符串。
+     */
+    cacheFilePath: string;
+    /**
+     * 文件 hash 值
+     * 如果不使用缓存/无校验文件时，则为空字符串。
+     */
+    hash: string;
+    /**
+     * 是否命中缓存
+     * 如果不使用缓存，则必定为 `false`。
+     */
+    hitCache: boolean;
+}
+export interface FetchResultError extends FetchResultBase {
+    hasError: true;
+    /**
+     * 错误信息
+     */
+    error: Error;
+}
+export type FetchResult<Level extends number> = Level extends 0 ? boolean : FetchResultSuccess | FetchResultError;
+export type FetchResults<Level extends number> = Level extends 0 ? FetchResult<0> : Level extends 1 ? boolean[] : FetchResult<2>[];

package/dist/utils.d.ts

@@ -0,0 +1,16 @@
+import { type AxiosRequestConfig } from 'axios';
+/**
+ * 获取 hash 文件的值
+ */
+export declare function getHashText(hashUrl: string, axiosOptions?: AxiosRequestConfig): Promise<{
+    hash: string;
+    hashAlg: string;
+    error?: Error;
+}>;
+/**
+ * 获取文件。如果有hash则校验hash
+ */
+export declare function downloadFile(url: string, filePath: string, hash: string, hashAlg: string, axiosOptions?: AxiosRequestConfig): Promise<null | {
+    errType?: 'axios' | 'file' | 'hash';
+    error?: Error;
+}>;

package/dist/utils.mjs

@@ -0,0 +1,58 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import axios from "axios";
+export async function getHashText(hashUrl, axiosOptions = {}) {
+  try {
+    let hash = (await axios.get(hashUrl, {
+      ...axiosOptions,
+      responseType: "text"
+    })).data;
+    let hashAlg = "sha256";
+    if (hash.includes("-")) {
+      const t = hash.split("-");
+      hash = t.pop();
+      hashAlg = t.join("-");
+    }
+    if (!crypto.getHashes().includes(hashAlg)) {
+      return {
+        hash: "",
+        hashAlg: "",
+        error: new Error(`Unsupported hash algorithm ${hashAlg}`)
+      };
+    }
+    return { hash, hashAlg };
+  } catch (error) {
+    return { hash: "", hashAlg: "", error };
+  }
+}
+export async function downloadFile(url, filePath, hash, hashAlg, axiosOptions = {}) {
+  let result;
+  try {
+    result = await axios.get(url, {
+      ...axiosOptions,
+      responseType: "stream"
+    });
+  } catch (error) {
+    return { errType: "axios", error };
+  }
+  const hashStream = hash ? crypto.createHash(hashAlg) : null;
+  const fileStream = fs.createWriteStream(filePath);
+  const streamPromise = new Promise((resolve, reject) => {
+    fileStream.on("finish", resolve);
+    fileStream.on("error", reject);
+  });
+  result.data.on("data", (chunk) => {
+    hashStream?.update(chunk);
+    fileStream.write(chunk);
+  });
+  result.data.on("end", () => fileStream.end());
+  try {
+    await streamPromise;
+  } catch (error) {
+    return { errType: "file", error };
+  }
+  if (hash && hashStream?.digest("hex") !== hash) {
+    return { errType: "hash", error: new Error("Hash not match") };
+  }
+  return null;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "@esmx/fetch",
+    "template": "library-node",
+    "scripts": {
+        "lint:css": "stylelint '**/*.{css,vue}' --fix --aei",
+        "lint:type": "tsc --noEmit",
+        "test": "vitest --pass-with-no-tests",
+        "coverage": "vitest run --coverage --pass-with-no-tests",
+        "lint:js": "biome check --write --no-errors-on-unmatched",
+        "build": "unbuild"
+    },
+    "dependencies": {
+        "axios": "^1.7.7",
+        "cachedir": "^2.4.0",
+        "cli-progress": "^3.12.0"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "1.9.4",
+        "@esmx/lint": "3.0.0-rc.10",
+        "@types/cli-progress": "^3.11.6",
+        "@types/node": "22.9.0",
+        "@vitest/coverage-v8": "2.1.5",
+        "stylelint": "16.10.0",
+        "typescript": "5.6.3",
+        "unbuild": "2.0.0",
+        "vitest": "2.1.5"
+    },
+    "version": "3.0.0-rc.10",
+    "type": "module",
+    "private": false,
+    "exports": {
+        ".": {
+            "import": "./dist/index.mjs",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "module": "dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "src",
+        "dist",
+        "*.mjs",
+        "template",
+        "public"
+    ],
+    "gitHead": "4a528ffecfdc6f2c6e7d97bc952427745f467691"
+}

package/src/fetch-pkg.ts

@@ -0,0 +1,219 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import genSysCacheDir from 'cachedir';
+
+import type { FetchPkgOptions, FetchResult } from './types';
+import { downloadFile, getHashText } from './utils';
+
+const sysCacheDir = path.join(genSysCacheDir('npm-esmx'), 'packages');
+
+/**
+ * 获取文件，并缓存到本地。如果有缓存则使用缓存
+ */
+export async function fetchPkg<Level extends number>({
+    cacheDir = sysCacheDir,
+    outputDir,
+    noCache,
+    returnLevel = 2 as Level,
+    logger = console.log,
+    axiosReqCfg = {},
+    name,
+    url = '',
+    onFinally = () => {}
+}: FetchPkgOptions & { returnLevel?: Level }): Promise<FetchResult<Level>> {
+    const returnWrapper = (ans: FetchResult<2>) => {
+        onFinally(ans);
+        return (returnLevel === 0 ? ans.hasError : ans) as FetchResult<Level>;
+    };
+
+    const paramsChecker = () => {
+        url = axiosReqCfg.url || url;
+        if (axiosReqCfg.baseURL) {
+            url = new URL(url, axiosReqCfg.baseURL).href;
+        }
+        if (!name) {
+            return returnWrapper({
+                hasError: true,
+                name,
+                url,
+                error: new Error('name is empty')
+            });
+        }
+        if (!url) {
+            return returnWrapper({
+                hasError: true,
+                name,
+                url,
+                error: new Error('url is empty')
+            });
+        }
+        const urlInfo = new URL(url);
+        urlInfo.searchParams.append(Date.now() + '_', Date.now() + '');
+        axiosReqCfg.headers = axiosReqCfg.headers || {};
+        axiosReqCfg.headers['Cache-Control'] =
+            axiosReqCfg.headers['Cache-Control'] || 'no-cache';
+        axiosReqCfg.headers.Pragma = axiosReqCfg.headers.Pragma || 'no-cache';
+        axiosReqCfg.headers.Expires = axiosReqCfg.headers.Expires || '0';
+        url = urlInfo.href;
+        if (noCache && !outputDir) {
+            return returnWrapper({
+                hasError: true,
+                name,
+                url,
+                error: new Error('outputFilePath is empty')
+            });
+        }
+        if (!noCache && cacheDir === '') {
+            return returnWrapper({
+                hasError: true,
+                name,
+                url,
+                error: new Error('cacheDir is empty')
+            });
+        }
+    };
+
+    const initDirs = async () => {
+        if (outputDir && !fs.existsSync(outputDir)) {
+            await fs.promises.mkdir(outputDir, { recursive: true });
+        }
+        if (!noCache) {
+            if (!fs.existsSync(cacheDir)) {
+                await fs.promises.mkdir(cacheDir, { recursive: true });
+            }
+        }
+    };
+
+    const t = paramsChecker();
+    logger?.(`[fetch] [${name}] From ${url}`);
+    if (t) {
+        return t;
+    }
+    await initDirs();
+
+    const urlInfo = new URL(url);
+    const fileExt = path.parse(urlInfo.pathname).ext;
+    urlInfo.pathname = urlInfo.pathname.replace(
+        new RegExp(fileExt + '$'),
+        '.txt'
+    );
+    const hashUrl = urlInfo.href;
+
+    /*
+        获取 hash。使用缓存时，一定要有 hash 值。
+        现在的逻辑是不使用缓存时，不校验 hash 值。
+        TODO: 理论上应该将《是否使用缓存》和《是否校验》分开，以后再说吧。
+    */
+    let hash = '';
+    let hashAlg = '';
+    if (!noCache) {
+        const hashInfo = await getHashText(hashUrl, {
+            ...axiosReqCfg,
+            onDownloadProgress: undefined
+        });
+        if (hashInfo.error) {
+            logger?.(`[fetch] [${name}] Error: ${hashInfo.error}`);
+            return returnWrapper({
+                hasError: true,
+                name,
+                url,
+                error: hashInfo.error
+            });
+        }
+        ({ hash, hashAlg } = hashInfo);
+    }
+    // 不使用缓存时 || 无hash文件时，直接下载到 outputPath，且不进行校验
+    const download2output = noCache || !hash;
+    if (download2output && !outputDir) {
+        logger?.(`[fetch] [${name}] Error: outputDir is empty`);
+        return returnWrapper({
+            hasError: true,
+            name,
+            url,
+            error: new Error('outputDir is empty')
+        });
+    }
+    const outputFilePath = outputDir
+        ? path.join(outputDir, name + fileExt)
+        : '';
+
+    const cacheFilePath = path.join(cacheDir, hash + fileExt);
+    const tmpFilePath =
+        (download2output
+            ? outputFilePath
+            : path.join(cacheDir, hash + fileExt)) + '.tmp';
+
+    if (hash && fs.existsSync(cacheFilePath)) {
+        logger?.(`[fetch] [${name}] Hit cache`);
+        if (outputFilePath) {
+            await fs.promises.cp(cacheFilePath, outputFilePath, {
+                force: true
+            });
+        }
+        return returnWrapper({
+            hasError: false,
+            name,
+            url,
+            filePath: outputFilePath || cacheFilePath,
+            cacheFilePath,
+            hash,
+            hitCache: true
+        });
+    }
+
+    const error = await downloadFile(
+        url,
+        tmpFilePath,
+        hash,
+        hashAlg,
+        axiosReqCfg
+    );
+    if (error) {
+        const err = error.error as Error;
+        switch (error.errType) {
+            case 'axios':
+                logger?.(`[fetch] [${name}] Error: ${err.message}`);
+                break;
+            case 'file':
+                logger?.(`[fetch] [${name}] Write file error: ${err.message}`);
+                break;
+            case 'hash':
+                logger?.(`[fetch] [${name}] Hash not match`);
+                break;
+        }
+        return returnWrapper({ hasError: true, name, url, error: err });
+    }
+    if (download2output) {
+        await fs.promises.rename(tmpFilePath, outputFilePath);
+        logger?.(
+            `[fetch] [${name}] Downloaded without cache: ${outputFilePath}`
+        );
+        return returnWrapper({
+            hasError: false,
+            name,
+            url,
+            filePath: outputFilePath,
+            cacheFilePath: outputFilePath,
+            hash,
+            hitCache: true
+        });
+    } else {
+        await fs.promises.rename(tmpFilePath, cacheFilePath);
+        if (outputFilePath) {
+            await fs.promises.cp(cacheFilePath, outputFilePath, {
+                force: true
+            });
+        }
+        const filePath = outputFilePath || cacheFilePath;
+        logger?.(`[fetch] [${name}] Downloaded: ${filePath}`);
+        return returnWrapper({
+            hasError: false,
+            name,
+            url,
+            filePath,
+            cacheFilePath,
+            hash,
+            hitCache: false
+        });
+    }
+}

package/src/fetch-pkgs.ts

@@ -0,0 +1,139 @@
+import { styleText } from 'node:util';
+import { MultiBar } from 'cli-progress';
+
+import { fetchPkg } from './fetch-pkg';
+import type {
+    FetchPkgOptions,
+    FetchPkgWithBarLogger,
+    FetchPkgWithBarOptions,
+    FetchPkgsOptions,
+    FetchPkgsWithBarOptions,
+    FetchResult,
+    FetchResults
+} from './types';
+
+/**
+ * 获取多个文件，并缓存到本地。如果有缓存则使用缓存。
+ */
+export async function fetchPkgs<Level extends number>({
+    packs,
+    returnLevel = 2 as Level,
+    onEachFinally = () => {},
+    ...options
+}: FetchPkgsOptions & { returnLevel?: Level }): Promise<FetchResults<Level>> {
+    if (new Set(packs.map((pack) => pack.name)).size !== packs.length) {
+        return (
+            returnLevel === 0
+                ? false
+                : returnLevel === 1
+                  ? packs.map(() => false)
+                  : packs.map(() => ({
+                        hasError: true,
+                        name: '',
+                        url: '',
+                        error: new Error('Duplicate name')
+                    }))
+        ) as FetchResults<Level>;
+    }
+    const axiosReqCfg = options.axiosReqCfg || {};
+    const results = await Promise.all(
+        packs.map((pack) =>
+            fetchPkg({
+                ...options,
+                returnLevel,
+                ...pack,
+                axiosReqCfg: {
+                    ...axiosReqCfg,
+                    ...(pack.axiosReqCfg || {})
+                },
+                onFinally: (result) => onEachFinally(result)
+            })
+        )
+    );
+    return (
+        returnLevel === 0
+            ? results.every((r) => !r)
+            : returnLevel === 1
+              ? (results as FetchResult<1>[]).map((r) => !r.hasError)
+              : results
+    ) as FetchResults<Level>;
+}
+
+/**
+ * 获取多个文件，并缓存到本地。如果有缓存则使用缓存。带有进度条
+ */
+export async function fetchPkgsWithBar<Level extends number>({
+    packs,
+    axiosReqCfg = {},
+    multiBarCfg = {},
+    logger = (barLogger, str) => barLogger(str),
+    onEachFinally = () => {},
+    ...options
+}: FetchPkgsWithBarOptions & { returnLevel?: Level }): Promise<
+    FetchResults<Level>
+> {
+    const multiBar = new MultiBar({
+        stopOnComplete: true,
+        format: ' [{bar}] {percentage}% | {status} | {name}',
+        forceRedraw: true,
+        barCompleteChar: '#',
+        barIncompleteChar: '_',
+        autopadding: true,
+        ...multiBarCfg
+    });
+    const multiBarLogger = (str = '') => {
+        // multiBar.log 最后一个字符需要是换行符
+        multiBar.log(str.trimEnd() + '\n');
+        multiBar.update(); // force redraw
+    };
+    const bars = packs.reduce((obj, { name }) => {
+        obj[name] = multiBar.create(1, 0, { status: 'WAT', name });
+        return obj;
+    }, {});
+    // 不知为何，有的时候不会更新，强制每秒重绘一次
+    const timer = setInterval(() => multiBar.update(), 1000);
+    const fetchPkgsPacks = packs.map((pack) => {
+        const ans = pack as FetchPkgWithBarOptions | FetchPkgOptions;
+        ans.axiosReqCfg = ans.axiosReqCfg || {};
+        const onDownloadProgress =
+            ans.axiosReqCfg.onDownloadProgress ||
+            axiosReqCfg.onDownloadProgress;
+        ans.axiosReqCfg.onDownloadProgress = (progressEvent) => {
+            bars[ans.name].setTotal(
+                progressEvent?.total ?? progressEvent.loaded + 1
+            );
+            bars[ans.name].update(progressEvent.loaded, {
+                status: styleText('yellow', 'DLD'),
+                name: ans.name
+            });
+            onDownloadProgress?.(progressEvent);
+        };
+        if (ans.logger) {
+            const orgLogger = ans.logger as FetchPkgWithBarLogger;
+            ans.logger = (str = '') => orgLogger(multiBarLogger, str);
+        }
+        return ans as FetchPkgOptions;
+    });
+    const results = await fetchPkgs({
+        packs: fetchPkgsPacks,
+        ...options,
+        axiosReqCfg,
+        logger: logger && ((str) => logger(multiBarLogger, str)),
+        onEachFinally: (result) => {
+            bars[result.name].update(Number.POSITIVE_INFINITY, {
+                status: result.hasError
+                    ? styleText('red', 'ERR')
+                    : styleText('green', result.hitCache ? 'HIT' : 'SUC'),
+                name: result.name
+            });
+            multiBar.update(); // force redraw
+            onEachFinally(result);
+        }
+    });
+    clearInterval(timer);
+    multiBar.update(); // force redraw
+    multiBar.stop();
+    return results;
+}
+
+export { fetchPkgsWithBar as fetchPkgsWithProgress };

package/src/fetch.test.ts

@@ -0,0 +1,22 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { test } from 'vitest';
+import { fetchPkgsWithProgress } from '.';
+
+test('base', async () => {
+    const urls = ['ssr-html/versions/latest.tgz', 'ssr-html/versions/1.0.tgz'];
+    const outputDir = path.join(
+        path.dirname(fileURLToPath(import.meta.url)),
+        'output'
+    );
+    await fetchPkgsWithProgress({
+        outputDir,
+        axiosReqCfg: {
+            baseURL: 'https://www.esmnext.com',
+            timeout: 4500
+        },
+        packs: urls.map((url) => ({ url, name: url.split('/')[0] }))
+    }).then((...args) => {
+        console.log(...args);
+    });
+}, 5000);

package/src/index.ts

@@ -0,0 +1,31 @@
+/*
+
+专门为 esmx 框架提供远程的下载库，具有缓存功能。
+
+例子：
+
+const urls = [
+    'ssr-html/versions/latest.tgz',
+    'ssr-html/versions/1.0.tgz',
+];
+
+const outputDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'output');
+
+fetchPkgsWithProgress({
+    outputDir,
+    axiosReqCfg: {
+        baseURL: 'https://js-esm.github.io/esmx/',
+        timeout: 10000,
+    },
+    packs: urls.map(url => ({ url, name: url.split('/')[0] })),
+    logger: (barLogger, str) => barLogger(str),
+    returnLevel: 0,
+}).then((...args) => {
+    console.log(...args);
+});
+
+ */
+
+export * from './types';
+export * from './fetch-pkg';
+export * from './fetch-pkgs';

package/src/types.ts

@@ -0,0 +1,153 @@
+import type { AxiosRequestConfig } from 'axios';
+import type { Options as MultiBarOptions } from 'cli-progress';
+
+export interface FetchBaseOptions {
+    /**
+     * 是否不使用缓存 默认为 `false` (即默认使用缓存)
+     * 现在的逻辑是不使用缓存时，不校验 hash 值。
+     */
+    noCache?: boolean;
+    /**
+     * 缓存文件夹路径 默认为 `{system cache dir}/npm-esmx/packages`。
+     * 当 `noCache` 为 `true` 时，该参数无效。
+     * 当 `noCache` 为 `false` 时，省略该参数会导致报错 `cacheDir is empty`。
+     */
+    cacheDir?: string;
+    /**
+     * 输出的文件夹路径。
+     * 省略时不输出文件，如果使用缓存会下载到缓存。
+     * 不使用缓存时或无hash文件时，省略则会导致报错 `outputDir is empty`。
+     * 目前，如果不使用缓存，会直接下载到输出，且不进行 hash 校验。
+     */
+    outputDir?: string;
+    /**
+     * 返回结果的级别 默认为 `2` (即默认返回详细结果)
+     * - `0`: 如果没有发生任何错误，返回 `true`，否则返回 `false`；
+     * - `1`: 根据入参顺序，返回 `boolean[]`，表示是否成功；
+     * - `2`: 返回详细结果。
+     */
+    returnLevel?: number;
+    /**
+     * 日志输出函数 默认为 `console.log`
+     * @param str string 输出的字符串
+     * @returns void
+     */
+    logger?: (str?: string) => void;
+    /**
+     * axios 请求配置
+     */
+    axiosReqCfg?: AxiosRequestConfig;
+    /**
+     * 包下载结束时的回调函数
+     * @param pack 包信息
+     * @param result 结果
+     */
+    onFinally?: (result: FetchResultSuccess | FetchResultError) => void;
+}
+export interface FetchPkgOptions extends FetchBaseOptions {
+    /**
+     * 包名。用于输出和保存时的文件名。
+     */
+    name: string;
+    /**
+     * 下载地址。优先级低于 `axiosReqCfg?.url`
+     */
+    url?: string;
+}
+export interface FetchPkgsOptions extends FetchBaseOptions {
+    /**
+     * 请确保每个包的 `name` 不同，否则会报错 `Duplicate name`。文件将会被下载到 `{outputDir}/{name}.ext`。
+     */
+    packs: FetchPkgOptions[];
+    /**
+     * 每个包下载结束时的回调函数
+     * @param pack 包信息
+     * @param result 结果
+     */
+    onEachFinally?: (result: FetchResultSuccess | FetchResultError) => void;
+}
+
+export type FetchPkgWithBarLogger = (
+    multiBarLogger: (data?: string) => void,
+    str?: string
+) => void;
+export interface FetchPkgWithBarOptions
+    extends Omit<FetchPkgOptions, 'logger'> {
+    /**
+     * 进度条日志输出函数，默认为空（不输出东西）。可以使用 `(barLogger, str) => barLogger(str)` 来输出日志。
+     * @param multiBarLogger `(data: string) => void` 进度条自带的日志输出函数，请通过该函数进行日志输出
+     * @param str string 输出的字符串
+     * @returns void
+     */
+    logger?: FetchPkgWithBarLogger;
+}
+export interface FetchPkgsWithBarOptions
+    extends Omit<FetchBaseOptions, 'logger'> {
+    /**
+     * 进度条日志输出函数，默认为 `(barLogger, str) => barLogger(str)`
+     * @param multiBarLogger `(data: string) => void` 进度条自带的日志输出函数，请通过该函数进行日志输出
+     * @param str string 输出的字符串
+     * @returns void
+     */
+    logger?: FetchPkgWithBarLogger;
+    /**
+     * 进度条配置
+     */
+    multiBarCfg?: MultiBarOptions;
+    /**
+     * 每个包下载结束时的回调函数
+     * @param pack 包信息
+     * @param result 结果
+     */
+    onEachFinally?: (result: FetchResultSuccess | FetchResultError) => void;
+    packs: FetchPkgWithBarOptions[];
+}
+
+export interface FetchResultBase {
+    /**
+     * 资源是从哪个 URL 获取的
+     */
+    url: string;
+    /**
+     * 包名。用于输出和保存时的文件名。
+     */
+    name: string;
+}
+export interface FetchResultSuccess extends FetchResultBase {
+    hasError: false;
+    /**
+     * 输出的文件路径
+     * 如果无 outputPath，且使用缓存，则为缓存文件路径。
+     */
+    filePath: string;
+    /**
+     * 缓存文件路径 默认为 `{system cache dir}/npm-esmx/packages/hash.ext`
+     * 如果不使用缓存，则为空字符串。
+     */
+    cacheFilePath: string;
+    /**
+     * 文件 hash 值
+     * 如果不使用缓存/无校验文件时，则为空字符串。
+     */
+    hash: string;
+    /**
+     * 是否命中缓存
+     * 如果不使用缓存，则必定为 `false`。
+     */
+    hitCache: boolean;
+}
+export interface FetchResultError extends FetchResultBase {
+    hasError: true;
+    /**
+     * 错误信息
+     */
+    error: Error;
+}
+export type FetchResult<Level extends number> = Level extends 0
+    ? boolean
+    : FetchResultSuccess | FetchResultError;
+export type FetchResults<Level extends number> = Level extends 0
+    ? FetchResult<0>
+    : Level extends 1
+      ? boolean[]
+      : FetchResult<2>[];

package/src/utils.ts

@@ -0,0 +1,83 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import axios, { type AxiosResponse, type AxiosRequestConfig } from 'axios';
+
+/**
+ * 获取 hash 文件的值
+ */
+export async function getHashText(
+    hashUrl: string,
+    axiosOptions: AxiosRequestConfig = {}
+): Promise<{ hash: string; hashAlg: string; error?: Error }> {
+    try {
+        let hash = (
+            await axios.get(hashUrl, {
+                ...axiosOptions,
+                responseType: 'text'
+            })
+        ).data;
+        let hashAlg = 'sha256';
+        if (hash.includes('-')) {
+            const t = hash.split('-');
+            hash = t.pop() as string;
+            hashAlg = t.join('-');
+        }
+        if (!crypto.getHashes().includes(hashAlg)) {
+            return {
+                hash: '',
+                hashAlg: '',
+                error: new Error(`Unsupported hash algorithm ${hashAlg}`)
+            };
+        }
+        return { hash, hashAlg };
+    } catch (error: any) {
+        return { hash: '', hashAlg: '', error };
+    }
+}
+
+/**
+ * 获取文件。如果有hash则校验hash
+ */
+export async function downloadFile(
+    url: string,
+    filePath: string,
+    hash: string,
+    hashAlg: string,
+    axiosOptions: AxiosRequestConfig = {}
+): Promise<null | { errType?: 'axios' | 'file' | 'hash'; error?: Error }> {
+    // TODO: 断点续传
+    let result: AxiosResponse;
+    try {
+        result = await axios.get(url, {
+            ...axiosOptions,
+            responseType: 'stream'
+        });
+    } catch (error: any) {
+        return { errType: 'axios', error };
+    }
+
+    const hashStream = hash ? crypto.createHash(hashAlg) : null;
+    const fileStream = fs.createWriteStream(filePath);
+
+    const streamPromise = new Promise((resolve, reject) => {
+        fileStream.on('finish', resolve);
+        fileStream.on('error', reject);
+    });
+    result.data.on('data', (chunk: crypto.BinaryLike) => {
+        hashStream?.update(chunk);
+        fileStream.write(chunk);
+    });
+    result.data.on('end', () => fileStream.end());
+
+    try {
+        await streamPromise;
+    } catch (error: any) {
+        return { errType: 'file', error };
+    }
+
+    if (hash && hashStream?.digest('hex') !== hash) {
+        return { errType: 'hash', error: new Error('Hash not match') };
+    }
+
+    return null;
+}