walk

import { walk } from "jsr:@ende/fs";

function

async function* walk(root: string | URL, options?: WalkOptions): AsyncIterableIterator<WalkEntry>

Recursively walks through a directory and yields information about each file and directory encountered.

The root path determines whether the file paths are relative or absolute. The root directory is included in the yielded entries.

Requires --allow-read permission.

root: string | URL

The root directory to start the walk from, as a string or URL.

options?: WalkOptions

The options for the walk.

Returns

An async iterable iterator that yields the walk entry objects.

Example: Basic usage

File structure:

folder
├── script.ts
└── foo.ts

import { walk } from "@ende/fs/walk";

await Array.fromAsync(walk("."));
// [
//   {
//     path: ".",
//     name: ".",
//     isFile: false,
//     isDirectory: true,
//     isSymlink: false
//   },
//   {
//     path: "script.ts",
//     name: "script.ts",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: false
//   },
//   {
//     path: "foo.ts",
//     name: "foo.ts",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: false
//   },
// ]

Example: Maximum file depth

Setting the maxDepth option to 1 will only include the root directory and its immediate children.

File structure:

folder
├── script.ts
└── foo
    └── bar.ts

import { walk } from "@ende/fs/walk";

await Array.fromAsync(walk(".", { maxDepth: 1 }));
// [
//   {
//     path: ".",
//     name: ".",
//     isFile: false,
//     isDirectory: true,
//     isSymlink: false
//   },
//   {
//     path: "script.ts",
//     name: "script.ts",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: false
//   },
//   {
//     path: "foo",
//     name: "foo",
//     isFile: false,
//     isDirectory: true,
//     isSymlink: false
//   },
// ]

Example: Exclude files

Setting the includeFiles option to false will exclude files.

File structure:

folder
├── script.ts
└── foo

import { walk } from "@ende/fs/walk";

await Array.fromAsync(walk(".", { includeFiles: false }));
// [
//   {
//     path: ".",
//     name: ".",
//     isFile: false,
//     isDirectory: true,
//     isSymlink: false
//   },
//   {
//     path: "foo",
//     name: "foo",
//     isFile: false,
//     isDirectory: true,
//     isSymlink: false,
//   },
// ]

Example: Exclude directories

Setting the includeDirs option to false will exclude directories.

File structure:

folder
├── script.ts
└── foo

import { walk } from "@ende/fs/walk";

await Array.fromAsync(walk(".", { includeDirs: false }));
// [
//   {
//     path: "script.ts",
//     name: "script.ts",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: false
//   },
// ]

Example: Exclude symbolic links

Setting the includeSymlinks option to false will exclude symbolic links.

File structure:

folder
├── script.ts
├── foo
└── link -> script.ts (symbolic link)

import { walk } from "@ende/fs/walk";

await Array.fromAsync(walk(".", { includeSymlinks: false }));
// [
//   {
//     path: ".",
//     name: ".",
//     isFile: false,
//     isDirectory: true,
//     isSymlink: false
//   },
//   {
//     path: "script.ts",
//     name: "script.ts",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: false
//   },
// ]

Example: Follow symbolic links

Setting the followSymlinks option to true will follow symbolic links, affecting the path property of the walk entry.

File structure:

folder
├── script.ts
└── link -> script.ts (symbolic link)

import { walk } from "@ende/fs/walk";

await Array.fromAsync(walk(".", { followSymlinks: true }));
// [
//   {
//     path: ".",
//     name: ".",
//     isFile: false,
//     isDirectory: true,
//     isSymlink: false
//   },
//   {
//     path: "script.ts",
//     name: "script.ts",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: false
//   },
//   {
//     path: "script.ts",
//     name: "link",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: true
//   },
// ]

Example: Canonicalize symbolic links

Setting the canonicalize option to false will canonicalize the path of the followed symbolic link. Meaning, the path property of the walk entry will be the path of the symbolic link itself.

File structure:

folder
├── script.ts
└── link -> script.ts (symbolic link)

import { walk } from "@ende/fs/walk";

await Array.fromAsync(walk(".", { followSymlinks: true, canonicalize: true }));
// [
//   {
//     path: ".",
//     name: ".",
//     isFile: false,
//     isDirectory: true,
//     isSymlink: false
//   },
//   {
//     path: "script.ts",
//     name: "script.ts",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: false
//   },
//   {
//     path: "link",
//     name: "link",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: true
//   },
// ]

Example: Filter by file extensions

Setting the exts option to [".ts"] or ["ts"] will only include entries with the .ts file extension.

File structure:

folder
├── script.ts
└── foo.js

import { walk } from "@ende/fs/walk";

await Array.fromAsync(walk(".", { exts: [".ts"] }));
// [
//   {
//     path: "script.ts",
//     name: "script.ts",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: false
//   },
// ]

Example: Filter by regular expressions

Setting the match option to [/s/] will only include entries with the letter s in their name.

File structure:

folder
├── script.ts
└── README.md

import { walk } from "@ende/fs/walk";

await Array.fromAsync(walk(".", { match: [/s/] }));
// [
//   {
//     path: "script.ts",
//     name: "script.ts",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: false
//   },
// ]

Example: Exclude by regular expressions

Setting the skip option to [/s/] will exclude entries with the letter s in their name.

File structure:

folder
├── script.ts
└── README.md

import { walk } from "@ende/fs/walk";

await Array.fromAsync(walk(".", { skip: [/s/] }));
// [
//   {
//     path: "README.md",
//     name: "README.md",
//     isFile: true,
//     isDirectory: false,
//     isSymlink: false
//   },
// ]

See also

Source