deno.land / std@0.224.0 / fs / walk.ts
walk.ts
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.// Documentation and interface for walk were adapted from Go// https://golang.org/pkg/path/filepath/#Walk// Copyright 2009 The Go Authors. All rights reserved. BSD license.import { join } from "../path/join.ts";import { normalize } from "../path/normalize.ts";import { toPathString } from "./_to_path_string.ts";import { createWalkEntry, createWalkEntrySync, type WalkEntry,} from "./_create_walk_entry.ts";
/** Error thrown in {@linkcode walk} or {@linkcode walkSync} during iteration. */export class WalkError extends Error { /** File path of the root that's being walked. */ root: string;
/** Constructs a new instance. */ constructor(cause: unknown, root: string) { super( `${cause instanceof Error ? cause.message : cause} for path "${root}"`, ); this.cause = cause; this.name = this.constructor.name; this.root = root; }}
function include( path: string, exts?: string[], match?: RegExp[], skip?: RegExp[],): boolean { if (exts && !exts.some((ext): boolean => path.endsWith(ext))) { return false; } if (match && !match.some((pattern): boolean => !!path.match(pattern))) { return false; } if (skip && skip.some((pattern): boolean => !!path.match(pattern))) { return false; } return true;}
function wrapErrorWithPath(err: unknown, root: string) { if (err instanceof WalkError) return err; return new WalkError(err, root);}
/** Options for {@linkcode walk} and {@linkcode walkSync}. */export interface WalkOptions { /** * The maximum depth of the file tree to be walked recursively. * * @default {Infinity} */ maxDepth?: number; /** * Indicates whether file entries should be included or not. * * @default {true} */ includeFiles?: boolean; /** * Indicates whether directory entries should be included or not. * * @default {true} */ includeDirs?: boolean; /** * Indicates whether symlink entries should be included or not. * This option is meaningful only if `followSymlinks` is set to `false`. * * @default {true} */ includeSymlinks?: boolean; /** * Indicates whether symlinks should be resolved or not. * * @default {false} */ followSymlinks?: boolean; /** * Indicates whether the followed symlink's path should be canonicalized. * This option works only if `followSymlinks` is not `false`. * * @default {true} */ canonicalize?: boolean; /** * List of file extensions used to filter entries. * If specified, entries without the file extension specified by this option * are excluded. * * @default {undefined} */ exts?: string[]; /** * List of regular expression patterns used to filter entries. * If specified, entries that do not match the patterns specified by this * option are excluded. * * @default {undefined} */ match?: RegExp[]; /** * List of regular expression patterns used to filter entries. * If specified, entries matching the patterns specified by this option are * excluded. * * @default {undefined} */ skip?: RegExp[];}export type { WalkEntry };
/** * Recursively walks through a directory and yields information about each file * and directory encountered. * * @param root The root directory to start the walk from, as a string or URL. * @param options The options for the walk. * @returns An async iterable iterator that yields `WalkEntry` objects. * * @example Basic usage * * File structure: * ``` * folder * ├── script.ts * └── foo.ts * ``` * * ```ts * import { walk } from "https://deno.land/std@$STD_VERSION/fs/walk.ts"; * * const entries = []; * for await (const entry of walk(".")) { * entries.push(entry); * } * * entries[0]!.path; // "folder" * entries[0]!.name; // "folder" * entries[0]!.isFile; // false * entries[0]!.isDirectory; // true * entries[0]!.isSymlink; // false * * entries[1]!.path; // "folder/script.ts" * entries[1]!.name; // "script.ts" * entries[1]!.isFile; // true * entries[1]!.isDirectory; // false * entries[1]!.isSymlink; // false * ``` */export async function* walk( root: string | URL, { maxDepth = Infinity, includeFiles = true, includeDirs = true, includeSymlinks = true, followSymlinks = false, canonicalize = true, exts = undefined, match = undefined, skip = undefined, }: WalkOptions = {},): AsyncIterableIterator<WalkEntry> { if (maxDepth < 0) { return; } root = toPathString(root); if (includeDirs && include(root, exts, match, skip)) { yield await createWalkEntry(root); } if (maxDepth < 1 || !include(root, undefined, undefined, skip)) { return; } try { for await (const entry of Deno.readDir(root)) { let path = join(root, entry.name);
let { isSymlink, isDirectory } = entry;
if (isSymlink) { if (!followSymlinks) { if (includeSymlinks && include(path, exts, match, skip)) { yield { path, ...entry }; } continue; } const realPath = await Deno.realPath(path); if (canonicalize) { path = realPath; } // Caveat emptor: don't assume |path| is not a symlink. realpath() // resolves symlinks but another process can replace the file system // entity with a different type of entity before we call lstat(). ({ isSymlink, isDirectory } = await Deno.lstat(realPath)); }
if (isSymlink || isDirectory) { yield* walk(path, { maxDepth: maxDepth - 1, includeFiles, includeDirs, includeSymlinks, followSymlinks, exts, match, skip, }); } else if (includeFiles && include(path, exts, match, skip)) { yield { path, ...entry }; } } } catch (err) { throw wrapErrorWithPath(err, normalize(root)); }}
/** Same as {@linkcode walk} but uses synchronous ops */export function* walkSync( root: string | URL, { maxDepth = Infinity, includeFiles = true, includeDirs = true, includeSymlinks = true, followSymlinks = false, canonicalize = true, exts = undefined, match = undefined, skip = undefined, }: WalkOptions = {},): IterableIterator<WalkEntry> { root = toPathString(root); if (maxDepth < 0) { return; } if (includeDirs && include(root, exts, match, skip)) { yield createWalkEntrySync(root); } if (maxDepth < 1 || !include(root, undefined, undefined, skip)) { return; } let entries; try { entries = Deno.readDirSync(root); } catch (err) { throw wrapErrorWithPath(err, normalize(root)); } for (const entry of entries) { let path = join(root, entry.name);
let { isSymlink, isDirectory } = entry;
if (isSymlink) { if (!followSymlinks) { if (includeSymlinks && include(path, exts, match, skip)) { yield { path, ...entry }; } continue; } const realPath = Deno.realPathSync(path); if (canonicalize) { path = realPath; } // Caveat emptor: don't assume |path| is not a symlink. realpath() // resolves symlinks but another process can replace the file system // entity with a different type of entity before we call lstat(). ({ isSymlink, isDirectory } = Deno.lstatSync(realPath)); }
if (isSymlink || isDirectory) { yield* walkSync(path, { maxDepth: maxDepth - 1, includeFiles, includeDirs, includeSymlinks, followSymlinks, exts, match, skip, }); } else if (includeFiles && include(path, exts, match, skip)) { yield { path, ...entry }; } }}
std
Version Info
6 months ago
