an error is thrown if the directory does not exist, or if it is a file/symbolic-link.
each directory entry's name is stripped off of any trailing slash, and any leading dot-slash.
this means, you will not be able to distinguish files from folders and symbolic links based on their
name alone, and instead, you will have to rely on the isXYZ flags.
TODO: what about symbolic links? should I follow them until I hit a "real" entry?
TODO: should I also give an option for recursive traversal? I think it might lead to more complexity,
but at the same time, it'll be faster since we won't have to double check the any subdir dir_path's existence via statEntry.
import { assertEquals, assertObjectMatch } from "jsr:@std/assert"
const
runtime_id = identifyCurrentRuntime(),
base_dir = new URL(import.meta.resolve("../temp/a/")),
my_dir = new URL(import.meta.resolve("../temp/a/b/c/")),
my_file1 = new URL(import.meta.resolve("../temp/a/b/x.txt")),
my_file2 = new URL(import.meta.resolve("../temp/a/y.txt")),
my_file3 = new URL(import.meta.resolve("../temp/a/z.txt"))
await ensureDir(runtime_id, my_dir)
await ensureFile(runtime_id, my_file1)
await ensureFile(runtime_id, my_file2)
await ensureFile(runtime_id, my_file3)
// the directories and files should now exist.
// so now, we'll iterate over them.
const entries: Record<string, FsEntryRecord> = {}
for await (const entry of readDir(runtime_id, base_dir)) {
entries[entry.name] = entry
}
assertEquals(Object.keys(entries).length, 3)
assertObjectMatch(entries["b"], {
name: "b",
isFile: false,
isDirectory: true,
isSymlink: false,
})
assertObjectMatch(entries["y.txt"], {
name: "y.txt",
isFile: true,
isDirectory: false,
isSymlink: false,
})
assertObjectMatch(entries["z.txt"], {
name: "z.txt",
isFile: true,
isDirectory: false,
isSymlink: false,
})
// deleting the base directory (recursively)
assertEquals(await removeEntry(runtime_id, base_dir, { recursive: true }), true)
// the directory no longer exists
assertEquals(await statEntry(runtime_id, base_dir), undefined)
read a directory's immediate child entries (files, folders, and symbolic links). this operation is not recursive, and so, subdirectories will not be traversed.