@hattip/walk

中文文档
0.0.49发布于 2024/11/02MITES Module近 30 天下载 2.9万

Create a file manifest from a directory

原始使用文档
文档目录6 节
  1. File name normalization
  2. Manifest types
  3. File set manifest
  4. File map manifest
  5. File list manifest
  6. The prune option

@hattip/walk

A utility package that walks a directory and generates a manifest of files for implementing static file servers.

There are two ways to use this package:

  • You can either use one of the walk, createFileSet, createFileMap, or createFileList functions at runtime during server startup and use the result to implement a static file server,
  • Or you can use the CLI or one of the createFileSetModule, createFileListModule, or createCompressedFileListModule functions to generate a manifest module at build time to improve cold start times in serverless environments.

File name normalization

@hattip/walk normalizes file names to make them safe to use in the path portion of a URL.

Manifest types

This tool can generate three types of manifests:

  • A file set manifest is a simple set of file names.
  • A file map manifest is a map of URL-normalized file names to file paths.
  • A file list manifest is an array of tuples consisting of URL-normalized file names, paths, sizes, hashes, and optionally ETags.

File set manifest

A file set manifest is generated using the --set flag or the createFileSetModule function. This is a module with the following interface:

const files: Set<string>;
export default files;

The exported set is a set of file paths similar to this:

export default new Set([
  "/LICENSE",
  "/cli.js",
  "/package.json",
  "/readme.md",
  "/%D83D%DE42.txt", // 🙂.txt percent-encoded
]);

This type of manifest is useful when the platform offers a static file server but a quick check is needed to see if a file exists before calling the static file handler.

File map manifest

A file map manifest is generated using the --map flag or the createFileMapModule function. This is a module with the following interface:

const files: Map<string, string | undefined>;
export default files;

Names that map to undefined are names that don't require normalization. Example output is like the following:

export default new Map([
  ["/LICENSE"],
  ["/cli.js"],
  ["/package.json"],
  ["/readme.md"],
  ["/%D83D%DE42.txt", "/🙂.txt"],
]);

File list manifest

A file list manifest is generated when neither the --set nor the --map flag is used or by calling the createFileListModule function. This is a module with the following interface:

const files: Array<
  [
    name: string,
    path: string | undefined, // undefined for names that don't require normalization
    size: number,
    hash: string,
    etag?: string,
  ]
>;
export default files;

ETag generation can be disabled by passing --no-etag to the CLI or passing false for the relevant option in the createFileListModule function.

The exported list is an array of tuples similar to this:

export default [
  [
    "/LICENSE",
    ,
    "application/octet-stream",
    1069,
    "10094a766eba8c1f9e9377874ad0832b12a9af93ec9ff08bee0d95e1fef9ae40",
  ],
  [
    "/cli.js",
    ,
    "application/javascript",
    44,
    "0779d059d458628cb4ab06c3e7d2a7e5b5e40698fce230c5aa0908bbb844f40b",
  ],
  [
    "/package.json",
    ,
    "application/json",
    1208,
    "e28324f872c5805cc5f36f261ecdba122b80df060d200edd4d2dc1a54af6217d",
  ],
  [
    "/readme.md",
    ,
    "text/markdown",
    5746,
    "3644ce0612c829bff249628b1f6dd23b4de62c5b3d1230ebceaccd6db8f9f69a",
  ],
  [
    "/%D83D%DE42.txt",
    "/🙂.txt",
    "text/plain",
    14,
    "df7a1ec45c1f8f13aa902a819a1d19d8707e6e8b5398803853d0489bf6d603c0",
  ],
];

By using the --compress CLI flag or by calling the createCompressedFileListModule function, you can generate a slightly compressed version of the manifest that doesn't repeat the content type for each file. This might be useful on platforms with size limits for the deployed code. Assuming ETag generation is disabled, the output looks like this (the second element is the index of the content type in the types array):

export default {
  types: [
    "application/octet-stream",
    "application/javascript",
    "application/json",
    "text/markdown",
    "text/plain",
  ],
  files: [
    ["/LICENSE", , 0, 1069],
    ["/cli.js", , 1, 44],
    ["/package.json", , 2, 1208],
    ["/readme.md", , 3, 5028],
    ["/%D83D%DE42.txt", "/🙂.txt", 4, 14],
  ],
};

The interface is like the following:

const manifest: {
  types: string[];
  files: Array<
    [
      name: string,
      path: string | undefined, // undefined for names that don't require normalization
      type: number,
      size: number,
      hash: string,
      etag?: string,
    ]
  >;
};

export default manifest;

The prune option

By default, @hattip/walk skips node_modules, dist, and any file that starts with a dot except .well-known. You can override this with the prune option which accepts an array of strings or regular expressions. Regular expressions have to start and end with / when using the CLI.

版本与发布记录

@hattip/walk 共发布 16 个版本,首次发布于 2023/08/27;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.0.49latest2024/11/022 年前
0.0.482024/09/082 年前
0.0.472024/08/112 年前
0.0.462024/06/192 年前
0.0.452024/03/272 年前
0.0.442024/03/092 年前

其他发布通道:canary → 0.0.35-canary.7。

关于 @hattip/walk 的常见问题

@hattip/walk 是什么?

Create a file manifest from a directory

如何安装 @hattip/walk?

在项目目录运行 npm install @hattip/walk,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hattip-walk,可以用 npx hattip-walk 直接运行。

@hattip/walk 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/hattip__walk 是否存在。

@hattip/walk 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hattip/walk 可以商用吗?

@hattip/walk 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hattip/walk 的下载量有多少?

根据 npm 官方下载统计,@hattip/walk 在 2026/10/18 – 2026/11/16 这 30 天内被下载 28,543 次,日均约 951 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hattip/walk 还在维护吗?

最新版本 0.0.49 发布于 2024/11/02(2 年前);至今共发布 16 个版本,其中过去 12 个月发布了 0 个;首次发布于 2023/08/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。