# @hattip/walk

> Create a file manifest from a directory

Latest version **0.0.49** (published 2024-11-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install @hattip/walk
pnpm add @hattip/walk
yarn add @hattip/walk
bun add @hattip/walk
```

Provides the command `hattip-walk`.

## Health

**Score 40/100 (D)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.0.49 |
| Published | 2024-11-02 |
| First published | 2023-08-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 3 |
| Unpacked size | 15.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1379 |
| Author | Fatih Aygün |
| Maintainers | cyco130 |

## Links

- npm: https://www.npmjs.com/package/@hattip/walk
- Repository: https://github.com/hattipjs/hattip
- Homepage: https://github.com/hattipjs/hattip#readme
- Issues: https://github.com/hattipjs/hattip/issues
- npm.io page: https://npm.io/package/@hattip/walk

## Dependencies (3)

- [cac](https://npm.io/package/cac.md) ^6.7.14
- [mime-types](https://npm.io/package/mime-types.md) ^2.1.35
- [@hattip/headers](https://npm.io/package/@hattip/headers.md) 0.0.49

## Recent versions

- 0.0.49 (latest) — 2024-11-02
- 0.0.35-canary.7 (canary) — 2023-08-27
- 0.0.48 — 2024-09-08
- 0.0.47 — 2024-08-11
- 0.0.46 — 2024-06-18
- 0.0.45 — 2024-03-27
- 0.0.44 — 2024-03-09
- 0.0.43 — 2024-02-17
- 0.0.42 — 2024-02-07
- 0.0.41 — 2024-01-22
- 0.0.40 — 2024-01-17
- 0.0.39 — 2024-01-15
- 0.0.38 — 2024-01-03
- 0.0.37 — 2023-12-29
- 0.0.36 — 2023-12-29
- … 1 more at https://npm.io/package/@hattip/walk/versions

## README

# `@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:

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

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

```js
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:

```ts
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:

```ts
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:

```ts
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:

```js
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):

```ts
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:

```ts
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.

---
_Source: https://npm.io/package/@hattip/walk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._