instrumentality 0.0.7 → 0.0.9

package/dist/road.js

@@ -1,25 +1,24 @@
-import * as rl from "node:readline";
+import * as cr from "node:crypto";
 import * as fs from "node:fs";
 import { constants as fsc } from "node:fs";
 import * as fp from "node:fs/promises";
 import * as ph from "node:path";
 import * as os from "node:os";
-import * as cr from "node:crypto";
 import { on } from "node:events";
-import * as bs from "./base.js";
-/** Subclass of {@link bs.InsErr} that represents an error thrown from this specific module of the library */
-export class RdErr extends bs.InsErr {
+import { InsErr } from "./base.js";
+/** Subclass of {@link InsErr} that represents an error thrown from this specific module of the library */
+export class Err extends InsErr {
     name = "Instrumentality-Road-Error";
 }
-export { RdErr as RoadError };
+export { Err as RoadError, Err as RdErr };
 /**
  * Returns the constructor function corresponding to the file mode (statmode).
  *
- * @param statmode_ The file mode to check.
+ * @param statmode_ The file mode or {@link fs.Dirent} to check.
  * @returns The constructor function corresponding to the road type (e.g., {@link File}, {@link Folder}, etc.).
- * @throws If the file mode is unknown, throws a {@link RdErr}.
+ * @throws If the file mode is unknown, throws a {@link Err}.
  */
-export function resolveMode(statmode_) {
+export function resolveStat(statmode_) {
     switch (statmode_ & fsc.S_IFMT) {
         case fsc.S_IFREG: return File;
         case fsc.S_IFDIR: return Folder;
@@ -28,9 +27,36 @@ export function resolveMode(statmode_) {
         case fsc.S_IFLNK: return SymbolicLink;
         case fsc.S_IFIFO: return Fifo;
         case fsc.S_IFSOCK: return Socket;
-        default: throw new RdErr(`Unknown mode type ${statmode_} (statmode is most likely corrupted)`);
+        default: throw new Err(`Unknown mode type ${statmode_} (statmode is most likely corrupted)`);
     }
 }
+export { resolveStat as resStat };
+/**
+ * Returns the constructor function corresponding to the type of the given {@link fs.Dirent}.
+ *
+ * @param dirent The directory entry to check.
+ * @returns The constructor function corresponding to the road type (e.g., {@link File}, {@link Folder}, etc.).
+ * @throws If the directory entry type is unknown, throws a {@link Err}.
+ */
+export function resolveDirent(dirent) {
+    // Order by likelihood: files/dicts are most common, followed by symbolic links
+    if (dirent.isFile())
+        return File;
+    if (dirent.isDirectory())
+        return Folder;
+    if (dirent.isSymbolicLink())
+        return SymbolicLink;
+    if (dirent.isBlockDevice())
+        return BlockDevice;
+    if (dirent.isCharacterDevice())
+        return CharacterDevice;
+    if (dirent.isFIFO())
+        return Fifo;
+    if (dirent.isSocket())
+        return Socket;
+    throw new Err(`Unknown dirent type for ${dirent.name}`);
+}
+export { resolveDirent as resDirent };
 /**
  * Creates the appropriate subclass of {@link Road} based on the file mode of the specified path.
  *
@@ -39,16 +65,18 @@ export function resolveMode(statmode_) {
  * @throws If {@link fp.lstat}/{@link fs.lstatSync} fails to retrieved the status of {@link path_}.
  */
 export async function factory(path_) {
-    return new (resolveMode((await fp.lstat(path_)).mode))(path_, false);
+    return new (resolveStat((await fp.lstat(path_)).mode))(path_, false);
 }
+export { factory as fac, factory as mk };
 /** Sync version of {@link factory}. */
 export function factorySync(path_) {
-    return new (resolveMode(fs.lstatSync(path_).mode))(path_, false);
+    return new (resolveStat(fs.lstatSync(path_).mode))(path_, false);
 }
+export { factorySync as facSync, factorySync as mkSync };
 /**
  * A map that keeps track of locked roads to prevent concurrent modifications.
  *
- * @key The absolute path of the road that is currently locked.
+ * @key The **absolute** and **normalized** (**resolved**) path of the road that is currently locked.
  * @value A promise that resolves when the lock on the road is released.
  *
  * @remarks The map is initialized lazily when the first lock is created to minimize import-time side effects.
@@ -84,63 +112,12 @@ export class Road {
      * @param path_ Any path-like string that can be resolved to an absolute path. It will be resolved to an absolute path using {@link ph.resolve}.
      * @param typeCheck_ If true, the constructor will check if the path corresponds to the expected type of road (e.g., file, folder, etc.) and throw an error if it doesn't. If false, no type checking will be performed.
      *
-     * @throws If {@link typeCheck_} is true and the path does not correspond to the expected type of road, a {@link RdErr} will be thrown.
+     * @throws If {@link typeCheck_} is true and the path does not correspond to the expected type of road, a {@link Err} will be thrown.
      */
     constructor(path_, typeCheck_) {
         this.pointsTo = ph.resolve(path_);
         if (typeCheck_ && !this.checkSync())
-            throw new RdErr(`Type mismatch: '${this.isAt}'`);
-    }
-    /**
-     * Aquires a lock for the path represented by this Road instance, preventing concurrent modifications from this and other Road instances pointing to the same path.
-     *
-     * @param cb_ A callback function that will be called when the lock is released. This is used internally to manage the lock state.
-     * @returns An object with a dispose method that releases the lock when called.
-     * @throws If the road is immutable, a {@link RdErr} will be thrown.
-     *
-     * @remarks This method MUST be used with a `using` statement to ensure that the lock is released properly. Failing to do so may result in deadlocks or other concurrency issues.
-     * Non-deterministic release is unfortunately not possible due to the nature of JavaScript's garbage collection, thus the lock must be released deterministically by the user (to which the `using` statement is a convenient way to do so).
-     */
-    async lock(cb_ = () => { }) {
-        if (!this.mutable)
-            throw new RdErr(`Road to '${this.isAt}' is immutable.`);
-        lockedRoads ??= new Map();
-        const isAt = this.isAt;
-        await lockedRoads.get(isAt); // will skip if `undefined` (no lock)
-        lockedRoads.set(isAt, new Promise(res => cb_ = res));
-        return {
-            [Symbol.dispose]() {
-                cb_();
-                lockedRoads.delete(isAt);
-            },
-            async [Symbol.asyncDispose]() {
-                cb_();
-                lockedRoads.delete(isAt);
-            }
-        };
-    }
-    /**
-     * Sync version of {@link lock}.
-     * @throws Also throws a {@link RdErr} if the road is currently locked by another operation as it cannot wait for the lock to be released in a synchronous context.
-     */
-    lockSync(cb_ = () => { }) {
-        if (!this.mutable)
-            throw new RdErr(`Road to '${this.isAt}' is immutable.`);
-        lockedRoads ??= new Map();
-        const isAt = this.isAt;
-        if (lockedRoads.has(isAt))
-            throw new RdErr(`Road to '${this.isAt}' is currently locked by another operation.`);
-        lockedRoads.set(isAt, new Promise(res => cb_ = res));
-        return {
-            [Symbol.dispose]() {
-                lockedRoads.delete(isAt);
-                cb_();
-            },
-            async [Symbol.asyncDispose]() {
-                lockedRoads.delete(isAt);
-                cb_();
-            }
-        };
+            throw new Err(`Type mismatch: '${this.isAt}'`);
     }
     /** @returns An instance of {@link Folder} representing the parent directory of the current road. */
     parent() { return new Folder(ph.dirname(this.isAt), false); }
@@ -160,6 +137,36 @@ export class Road {
     }
     /** @returns An array of {@link Folder} instances representing the ancestors of the current road. */
     ancestors() { return [...this.ancestorsIt()]; }
+    reserveLock(allowConcurrent) {
+        if (!this.mutable)
+            throw new Err(`Road to '${this.isAt}' is immutable.`);
+        lockedRoads ??= new Map();
+        const { promise, resolve } = Promise.withResolvers();
+        const isAt = this.isAt;
+        const previous = lockedRoads.get(this.isAt);
+        if (!allowConcurrent && previous)
+            throw new Err(`Road to '${this.isAt}' is already locked.`);
+        lockedRoads.set(this.isAt, promise);
+        return {
+            [Symbol.dispose]: () => {
+                resolve();
+                if (lockedRoads.get(isAt) === promise)
+                    lockedRoads.delete(isAt);
+            },
+            previous,
+        };
+    }
+    async lock() {
+        const l = this.reserveLock(true);
+        try {
+            await l.previous;
+        }
+        catch { }
+        return l;
+    }
+    lockSync() {
+        return this.reserveLock(false);
+    }
     /**
      * Watches the current entry for changes and resolves when the entry becomes accessible (i.e., exists and can be accessed).
      *
@@ -215,10 +222,50 @@ export class Road {
     lstat() { return fp.lstat(this.isAt); }
     /** @returns The result of {@link fs.lstatSync} for the current entry. */
     lstatSync() { return fs.lstatSync(this.isAt); }
-    /** @returns The result of {@link fp.stat} for the current entry. */
-    stat() { return fp.stat(this.isAt); }
-    /** @returns The result of {@link fs.statSync} for the current entry. */
-    statSync() { return fs.statSync(this.isAt); }
+    /** Wrapper around {@link fp.rm} with locking. */
+    async delete() {
+        using _ = await this.lock();
+        await fp.rm(this.isAt, { recursive: true, force: true });
+    }
+    /** Wrapper around {@link fs.rmSync} with locking. */
+    deleteSync() {
+        using _ = this.lockSync();
+        fs.rmSync(this.isAt, { recursive: true, force: true });
+    }
+    async copy(into_) {
+        const newPath = into_.join(this.name);
+        await fp.cp(this.isAt, newPath, { recursive: true, force: true });
+        return new this.constructor(newPath, false);
+    }
+    copySync(into_) {
+        const newPath = into_.join(this.name);
+        fs.cpSync(this.isAt, newPath, { recursive: true, force: true });
+        return new this.constructor(newPath, false);
+    }
+    async move(into_) {
+        using _ = await this.lock();
+        const newPath = into_.join(this.name);
+        await fp.rename(this.isAt, newPath);
+        this.pointsTo = newPath;
+    }
+    moveSync(into_) {
+        using _ = this.lockSync();
+        const newPath = into_.join(this.name);
+        fs.renameSync(this.isAt, newPath);
+        this.pointsTo = newPath;
+    }
+    async rename(newName_) {
+        using _ = await this.lock();
+        const newPath = this.parent().join(newName_);
+        await fp.rename(this.isAt, newPath);
+        this.pointsTo = newPath;
+    }
+    renameSync(newName_) {
+        using _ = this.lockSync();
+        const newPath = this.parent().join(newName_);
+        fs.renameSync(this.isAt, newPath);
+        this.pointsTo = newPath;
+    }
     /** Type narrowing for {@link File} (similar to `instanceof` without unnecessary runtime checks). */
     isFile() { return false; }
     /** Type narrowing for {@link Folder} (similar to `instanceof` without unnecessary runtime checks). */
@@ -227,10 +274,6 @@ export class Road {
     isFolder() { return false; }
     /** Type narrowing for {@link Folder} (similar to `instanceof` without unnecessary runtime checks). */
     isDirectory() { return false; }
-    /** Type narrowing for {@link Folder} (similar to `instanceof` without unnecessary runtime checks). */
-    isDict() { return false; }
-    /** Type narrowing for {@link Folder} (similar to `instanceof` without unnecessary runtime checks). */
-    isDictionary() { return false; }
     /** Type narrowing for {@link SymbolicLink} (similar to `instanceof` without unnecessary runtime checks). */
     isSymlink() { return false; }
     /** Type narrowing for {@link SymbolicLink} (similar to `instanceof` without unnecessary runtime checks). */
@@ -248,54 +291,55 @@ export class Road {
 }
 /** Subclass of {@link Road} that represents a file. */
 export class File extends Road {
-    static async create(at_) {
+    /**
+     * Creates a new file at the specified path if it does not already exist.
+     *
+     * @param at_ The path at which to create the file.
+     * @returns A promise that resolves to the newly created `File` instance.
+     * @throws if {@link fp.writeFile} throws.
+     */
+    static async create(at_, data = "") {
         try {
             await fp.access(at_, fsc.W_OK);
         }
         catch {
-            await fp.writeFile(at_, "");
+            await fp.writeFile(at_, data);
         }
         return new File(at_, true);
     }
+    /** Alias for {@link File.create}. */
     static mk = File.create;
-    static createSync(at_) {
+    /** Synchronous version of {@link File.create}. */
+    static createSync(at_, data = "") {
         try {
             fs.accessSync(at_, fs.constants.W_OK);
         }
         catch {
-            fs.writeFileSync(at_, "");
+            fs.writeFileSync(at_, data);
         }
         return new File(at_, true);
     }
+    /** Alias for {@link File.createSync}. */
     static mkSync = File.createSync;
+    /** The file extension of this file, including the leading dot. */
     get ext() { return ph.extname(this.isAt); }
+    /** The file name without its extension. */
     get noExt() { return ph.basename(this.isAt, this.ext); }
-    async read(encoding_, flag_) {
-        if (encoding_)
-            return fp.readFile(this.isAt, { encoding: encoding_, flag: flag_ });
-        else
-            return fp.readFile(this.isAt);
-    }
-    readSync(encoding_, flag_) {
-        if (encoding_)
-            return fs.readFileSync(this.isAt, { encoding: encoding_, flag: flag_ });
-        else
-            return fs.readFileSync(this.isAt);
-    }
-    async *itBuff(chunkSize_ = 64 * 1024, flags_ = 'r', mode_) {
-        const fd = await fp.open(this.isAt, flags_, mode_);
+    async read(options_) {
+        return fp.readFile(this.isAt, options_);
+    }
+    readSync(options_) {
+        return fs.readFileSync(this.isAt, options_);
+    }
+    async *itBuff(options_) {
+        const stream = fs.createReadStream(this.isAt, { ...options_, encoding: undefined });
         try {
-            const buffer = Buffer.alloc(chunkSize_);
-            let bytesRead;
-            do {
-                const readResult = await fd.read(buffer, 0, chunkSize_, null);
-                bytesRead = readResult.bytesRead;
-                if (bytesRead > 0)
-                    yield buffer.subarray(0, bytesRead);
-            } while (bytesRead === chunkSize_);
+            for await (const chunk of stream)
+                yield chunk;
         }
         finally {
-            await fd.close();
+            if (!stream.destroyed)
+                stream.destroy();
         }
     }
     *itBuffSync(chunkSize_ = 64 * 1024, flags_ = 'r', mode_) {
@@ -306,145 +350,130 @@ export class File extends Road {
             do {
                 bytesRead = fs.readSync(fd, buffer, 0, chunkSize_, null);
                 if (bytesRead > 0)
-                    yield buffer.subarray(0, bytesRead);
+                    yield Buffer.from(buffer.subarray(0, bytesRead));
             } while (bytesRead === chunkSize_);
         }
         finally {
             fs.closeSync(fd);
         }
     }
-    async write(data_, options_) {
-        using _ = await this.lock();
-        await fp.writeFile(this.isAt, data_, options_);
+    async sameAs(other_) {
+        if (this.isAt === other_.isAt)
+            return true;
+        const [s1, s2] = await Promise.all([this.size(), other_.size()]);
+        if (s1 !== s2)
+            return false;
+        if (s1 === 0)
+            return true;
+        const iter1 = this.itBuff();
+        const iter2 = other_.itBuff();
+        try {
+            while (true) {
+                const [a, b] = await Promise.all([iter1.next(), iter2.next()]);
+                if (a.done && b.done)
+                    return true;
+                if (a.done !== b.done)
+                    return false;
+                if (!a.value.equals(b.value))
+                    return false;
+            }
+        }
+        finally {
+            await Promise.all([iter1.return?.(undefined), iter2.return?.(undefined)]);
+        }
     }
-    writeSync(data_, options_) {
-        using _ = this.lockSync();
-        fs.writeFileSync(this.isAt, data_, options_);
+    sameAsSync(other_) {
+        if (this.isAt === other_.isAt)
+            return true;
+        const [s1, s2] = [this.sizeSync(), other_.sizeSync()];
+        if (s1 !== s2)
+            return false;
+        if (s1 === 0)
+            return true;
+        const iter1 = this.itBuffSync();
+        const iter2 = other_.itBuffSync();
+        try {
+            while (true) {
+                const a = iter1.next();
+                const b = iter2.next();
+                if (a.done && b.done)
+                    return true;
+                if (a.done !== b.done)
+                    return false;
+                if (!a.value.equals(b.value))
+                    return false;
+            }
+        }
+        finally {
+            try {
+                iter1.return?.(undefined);
+            }
+            catch { }
+            try {
+                iter2.return?.(undefined);
+            }
+            catch { }
+        }
     }
-    async append(data_, options_) {
-        using _ = await this.lock();
-        await fp.appendFile(this.isAt, data_, options_);
+    async hash(algorithm_ = "sha256", options_, encoding_) {
+        const hash = cr.createHash(algorithm_, options_);
+        for await (const chunk of this.itBuff())
+            hash.update(chunk);
+        return encoding_ ? hash.digest(encoding_) : hash.digest();
     }
-    appendSync(data_, options_) {
-        using _ = this.lockSync();
-        fs.appendFileSync(this.isAt, data_, options_);
+    hashSync(algorithm_ = "sha256", options_, encoding_) {
+        const hash = cr.createHash(algorithm_, options_);
+        for (const chunk of this.itBuffSync())
+            hash.update(chunk);
+        return encoding_ ? hash.digest(encoding_) : hash.digest();
     }
-    async delete() {
+    async size() { return (await this.lstat()).size; }
+    sizeSync() { return this.lstatSync().size; }
+    async writeAtomic(data_, options_) {
         using _ = await this.lock();
-        await fp.rm(this.isAt, { force: true });
+        await this.parent().borrow(File, async (tmp) => {
+            using _ = await tmp.lock();
+            await fp.writeFile(tmp.isAt, data_, options_);
+            await fp.rename(tmp.isAt, this.isAt);
+        });
     }
-    deleteSync() {
+    writeAtomicSync(data_, options_) {
         using _ = this.lockSync();
-        fs.rmSync(this.isAt, { force: true });
+        this.parent().borrowSync(File, tmp => {
+            using _ = tmp.lockSync();
+            fs.writeFileSync(tmp.isAt, data_, options_);
+            fs.renameSync(tmp.isAt, this.isAt);
+        });
     }
-    async move(into_) {
+    async write(data_, options_) {
         using _ = await this.lock();
-        const newPath = into_.join(this.name);
-        await fp.rename(this.isAt, newPath);
-        this.pointsTo = newPath;
+        await fp.writeFile(this.isAt, data_, options_);
     }
-    moveSync(into_) {
+    writeSync(data_, options_) {
         using _ = this.lockSync();
-        const newPath = into_.join(this.name);
-        fs.renameSync(this.isAt, newPath);
-        this.pointsTo = newPath;
-    }
-    async copy(into_) {
-        const newPath = into_.join(this.name);
-        await fp.copyFile(this.isAt, newPath);
-        return new File(newPath, false);
-    }
-    copySync(into_) {
-        const newPath = into_.join(this.name);
-        fs.copyFileSync(this.isAt, newPath);
-        return new File(newPath, false);
+        fs.writeFileSync(this.isAt, data_, options_);
     }
-    async rename(to_) {
+    async append(data_, options_) {
         using _ = await this.lock();
-        const newPath = this.parent().join(to_);
-        await fp.rename(this.isAt, newPath);
-        this.pointsTo = newPath;
+        await fp.appendFile(this.isAt, data_, options_);
     }
-    renameSync(to_) {
+    appendSync(data_, options_) {
         using _ = this.lockSync();
-        const newPath = this.parent().join(to_);
-        fs.renameSync(this.isAt, newPath);
-        this.pointsTo = newPath;
-    }
-    async check() { return (await fp.lstat(this.isAt)).isFile(); }
-    checkSync() { return fs.lstatSync(this.isAt).isFile(); }
-    isFile() { return true; }
-}
-export async function hash(f_, algorithm_ = "sha256", options_, encoding_) {
-    const hash = cr.createHash(algorithm_, options_);
-    for await (const chunk of f_.itBuff())
-        hash.update(chunk);
-    return encoding_ ? hash.digest(encoding_) : hash.digest();
-}
-export function hashSync(f_, algorithm_ = "sha256", options_, encoding_) {
-    const hash = cr.createHash(algorithm_, options_);
-    for (const chunk of f_.itBuffSync())
-        hash.update(chunk);
-    return encoding_ ? hash.digest(encoding_) : hash.digest();
-}
-export async function streamHash(f_, algorithm_ = "sha256", options_, encoding_) {
-    const hash = cr.createHash(algorithm_, options_);
-    for await (const chunk of f_.itBuff())
-        hash.update(chunk);
-    return encoding_ ? hash.digest(encoding_) : hash.digest();
-}
-export function streamHashSync(f_, algorithm_ = "sha256", options_, encoding_) {
-    const hash = cr.createHash(algorithm_, options_);
-    for (const chunk of f_.itBuffSync())
-        hash.update(chunk);
-    return encoding_ ? hash.digest(encoding_) : hash.digest();
-}
-export async function* itLines(f_, options_ = { encoding: 'utf-8' }) {
-    const readStream = fs.createReadStream(f_.isAt, options_);
-    const rlInterface = rl.createInterface({ input: readStream, crlfDelay: Infinity });
-    try {
-        for await (const line of rlInterface)
-            yield line;
+        fs.appendFileSync(this.isAt, data_, options_);
     }
-    finally {
-        rlInterface.close();
-        readStream.destroy();
+    async check() { try {
+        return (await fp.lstat(this.isAt)).isFile();
     }
-}
-export async function fileSameAs(f1_, f2_) {
-    if (f1_.isAt === f2_.isAt)
-        return true;
-    else if ((await fp.lstat(f1_.isAt)).size !== (await fp.lstat(f2_.isAt)).size)
+    catch {
         return false;
-    const iter1 = f1_.itBuff();
-    const iter2 = f2_.itBuff();
-    while (true) {
-        const [a, b] = await Promise.all([iter1.next(), iter2.next()]);
-        if (a.done && b.done)
-            return true;
-        if (a.done !== b.done)
-            return false;
-        if (!a.value.equals(b.value))
-            return false;
+    } }
+    checkSync() { try {
+        return fs.lstatSync(this.isAt).isFile();
     }
-}
-export function fileSameAsSync(f1_, f2_) {
-    if (f1_.isAt === f2_.isAt)
-        return true;
-    else if (fs.statSync(f1_.isAt).size !== fs.statSync(f2_.isAt).size)
+    catch {
         return false;
-    const iter1 = f1_.itBuffSync();
-    const iter2 = f2_.itBuffSync();
-    while (true) {
-        const a = iter1.next();
-        const b = iter2.next();
-        if (a.done && b.done)
-            return true;
-        if (a.done !== b.done)
-            return false;
-        if (!a.value.equals(b.value))
-            return false;
-    }
+    } }
+    isFile() { return true; }
 }
 export class Folder extends Road {
     static async create(at_) {
@@ -470,40 +499,50 @@ export class Folder extends Road {
     join(...paths_) {
         return ph.join(this.isAt, ...paths_);
     }
-    async *it(expectedType_) {
-        for (const entryName of await fp.readdir(this.isAt)) {
-            const road = await factory(this.join(entryName));
-            if (!expectedType_ || road instanceof expectedType_)
+    async *it(filter_) {
+        for (const entry of await fp.readdir(this.isAt, { withFileTypes: true })) {
+            const road = new (resolveDirent(entry))(this.join(entry.name), false);
+            if (!filter_ || filter_(road))
                 yield road;
         }
     }
-    *itSync(expectedType_) {
-        for (const entry of fs.readdirSync(this.isAt)) {
-            const road = factorySync(this.join(entry));
-            if (!expectedType_ || road instanceof expectedType_)
+    *itSync(filter_) {
+        for (const entry of fs.readdirSync(this.isAt, { withFileTypes: true })) {
+            const road = new (resolveDirent(entry))(this.join(entry.name), false);
+            if (!filter_ || filter_(road))
                 yield road;
         }
     }
-    async list(expectedType_) {
-        const entries = (await fp.readdir(this.isAt)).map(async (entry) => factory(this.join(entry)));
-        const resolvedEntries = await Promise.all(entries);
-        if (!expectedType_)
-            return resolvedEntries;
-        return resolvedEntries.filter(entry => entry instanceof expectedType_);
+    async list(filter_) {
+        const entries = (await fp.readdir(this.isAt, { withFileTypes: true })).map(e => new (resolveDirent(e))(this.join(e.name), false));
+        return filter_ ? entries.filter(entry => filter_(entry)) : entries;
+    }
+    listSync(filter_) {
+        const entries = fs.readdirSync(this.isAt, { withFileTypes: true }).map(e => new (resolveDirent(e))(this.join(e.name), false));
+        return filter_ ? entries.filter(entry => filter_(entry)) : entries;
+    }
+    async *walk(filter_) {
+        for await (const entry of this.it()) {
+            if (!filter_ || filter_(entry))
+                yield entry;
+            if (entry.isDir())
+                yield* entry.walk(filter_);
+        }
     }
-    listSync(expectedType_) {
-        const entries = fs.readdirSync(this.isAt).map(entry => factorySync(this.join(entry)));
-        if (!expectedType_)
-            return entries;
-        return entries.filter(entry => entry instanceof expectedType_);
+    *walkSync(filter_) {
+        for (const entry of this.itSync()) {
+            if (!filter_ || filter_(entry))
+                yield entry;
+            if (entry.isDir())
+                yield* entry.walkSync(filter_);
+        }
     }
-    async find(name_, expectedType_) {
+    async find(name_, expect_) {
         try {
-            await fp.access(this.join(name_), fs.constants.F_OK);
             const found = await factory(this.join(name_));
-            if (!expectedType_)
+            if (!expect_)
                 return found;
-            if (found instanceof expectedType_)
+            if (found instanceof expect_)
                 return found;
             return null;
         }
@@ -511,78 +550,74 @@ export class Folder extends Road {
             return null;
         }
     }
-    findSync(name_, expectedType_) {
+    findSync(name_, expect_) {
         try {
             const found = factorySync(this.join(name_));
-            if (!expectedType_)
+            if (!expect_)
                 return found;
-            if (found instanceof expectedType_)
+            if (found instanceof expect_)
                 return found;
             return null;
         }
-        catch {
+        catch (e) {
             return null;
         }
     }
     async add(name_, createable_) {
         const newPath = this.join(name_);
-        await createable_.create(newPath);
+        await createable_.mk(newPath);
         return (await factory(newPath));
     }
     addSync(name_, createable_) {
         const newPath = this.join(name_);
-        createable_.createSync(newPath);
+        createable_.mkSync(newPath);
         return factorySync(newPath);
     }
-    async delete(options_ = { recursive: true }) {
-        using _ = await this.lock();
-        await fp.rm(this.isAt, options_);
-    }
-    deleteSync(options_ = { recursive: true }) {
-        using _ = this.lockSync();
-        fs.rmSync(this.isAt, options_);
-    }
-    async move(into_) {
-        using _ = await this.lock();
-        const newPath = into_.join(this.name);
-        await fp.rename(this.isAt, newPath);
-        this.pointsTo = newPath;
+    async borrow(createable_, cb_) {
+        const path = this.join(`instrumentality@${crypto.randomUUID()}`);
+        try {
+            await cb_(await createable_.mk(path));
+        }
+        finally {
+            await fp.rm(path, { recursive: true, force: true });
+        }
     }
-    moveSync(into_) {
-        using _ = this.lockSync();
-        const newPath = into_.join(this.name);
-        fs.renameSync(this.isAt, newPath);
-        this.pointsTo = newPath;
+    borrowSync(createable_, cb_) {
+        const path = this.join(`instrumentality@${crypto.randomUUID()}`);
+        try {
+            cb_(createable_.mkSync(path));
+        }
+        finally {
+            fs.rmSync(path, { recursive: true, force: true });
+        }
     }
-    async copy(into_) {
-        const newPath = into_.join(this.name);
-        await fp.cp(this.isAt, newPath, { recursive: true });
-        return new Folder(newPath, false);
+    async size() {
+        let size = 0;
+        for await (const entry of this.it())
+            size += await entry.size();
+        return size;
     }
-    copySync(into_) {
-        const newPath = into_.join(this.name);
-        fs.cpSync(this.isAt, newPath, { recursive: true });
-        return new Folder(newPath, false);
+    sizeSync() {
+        let size = 0;
+        for (const entry of this.itSync())
+            size += entry.sizeSync();
+        return size;
     }
-    async rename(to_) {
-        using _ = await this.lock();
-        const newPath = this.parent().join(to_);
-        await fp.rename(this.isAt, newPath);
-        this.pointsTo = newPath;
+    async check() { try {
+        return (await fp.lstat(this.isAt)).isDirectory();
     }
-    renameSync(to_) {
-        using _ = this.lockSync();
-        const newPath = this.parent().join(to_);
-        fs.renameSync(this.isAt, newPath);
-        this.pointsTo = newPath;
+    catch {
+        return false;
+    } }
+    checkSync() { try {
+        return fs.lstatSync(this.isAt).isDirectory();
     }
-    async check() { return (await fp.lstat(this.isAt)).isDirectory(); }
-    checkSync() { return fs.lstatSync(this.isAt).isDirectory(); }
+    catch {
+        return false;
+    } }
     isFolder() { return true; }
     isDir() { return true; }
     isDirectory() { return true; }
-    isDict() { return true; }
-    isDictionary() { return true; }
 }
 export function sysRoot() { return new Folder(ph.parse(process.cwd()).root, false); }
 export function home() { return new Folder(os.homedir(), false); }
@@ -617,13 +652,17 @@ export class SymbolicLink extends Road {
         return factorySync(ph.resolve(ph.dirname(this.isAt), fs.readlinkSync(this.isAt)));
     }
     async retarget(to_) {
-        await this.delete();
-        return fp.symlink(to_.isAt, this.isAt);
+        using _ = await this.lock();
+        await fp.unlink(this.isAt);
+        await fp.symlink(to_.isAt, this.isAt);
     }
     retargetSync(to_) {
-        this.deleteSync();
+        using _ = this.lockSync();
+        fs.unlinkSync(this.isAt);
         fs.symlinkSync(to_.isAt, this.isAt);
     }
+    async size() { return (await this.lstat()).size; }
+    sizeSync() { return this.lstatSync().size; }
     async delete() {
         using _ = await this.lock();
         await fp.unlink(this.isAt);
@@ -632,132 +671,106 @@ export class SymbolicLink extends Road {
         using _ = this.lockSync();
         fs.unlinkSync(this.isAt);
     }
-    async move(into_) {
-        using _ = await this.lock();
-        const newPath = into_.join(this.name);
-        await fp.rename(this.isAt, newPath);
-        this.pointsTo = newPath;
-    }
-    moveSync(into_) {
-        using _ = this.lockSync();
-        const newPath = into_.join(this.name);
-        fs.renameSync(this.isAt, newPath);
-        this.pointsTo = newPath;
-    }
-    async copy(into_) {
-        const newPath = into_.join(this.name);
-        const target = await this.target();
-        await fp.symlink(target.isAt, newPath);
-        return new SymbolicLink(newPath, false);
-    }
-    copySync(into_) {
-        const newPath = into_.join(this.name);
-        const target = this.targetSync();
-        fs.symlinkSync(target.isAt, newPath);
-        return new SymbolicLink(newPath, false);
-    }
-    async rename(to_) {
-        using _ = await this.lock();
-        const newPath = this.parent().join(to_);
-        await fp.rename(this.isAt, newPath);
-        this.pointsTo = newPath;
+    async check() { try {
+        return (await fp.lstat(this.isAt)).isSymbolicLink();
     }
-    renameSync(to_) {
-        using _ = this.lockSync();
-        const newPath = this.parent().join(to_);
-        fs.renameSync(this.isAt, newPath);
-        this.pointsTo = newPath;
+    catch {
+        return false;
+    } }
+    checkSync() { try {
+        return fs.lstatSync(this.isAt).isSymbolicLink();
     }
-    async check() { return (await fp.lstat(this.isAt)).isSymbolicLink(); }
-    checkSync() { return fs.lstatSync(this.isAt).isSymbolicLink(); }
+    catch {
+        return false;
+    } }
     isSymlink() { return true; }
     isSymbolicLink() { return true; }
 }
 export { SymbolicLink as Symlink };
 export class UnusableRoad extends Road {
     mutable = false; // Modification will cause system issues (e.g. deleting a device file)
-    constructor(...args_) {
-        super(...args_);
-        Object.freeze(this);
-    }
-    error() { throw new RdErr(`${this.constructor.name} at '${this.isAt}' is a system-level resource thus not subject to modification.`); }
-    async lock() { return this.error(); }
+    async size() { return 0; }
+    sizeSync() { return 0; }
+    error() { throw new Err(`${this.constructor.name} at '${this.isAt}' is a system-level resource thus not subject to modification.`); }
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be locked */
+    lock() { return this.error(); }
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be locked */
     lockSync() { return this.error(); }
-    async delete() { return this.error(); }
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be deleted */
+    delete() { return this.error(); }
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be deleted */
     deleteSync() { return this.error(); }
-    async move() { return this.error(); }
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be moved */
+    move() { return this.error(); }
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be moved */
     moveSync() { return this.error(); }
-    async copy() { return this.error(); }
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be copied */
+    copy() { return this.error(); }
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be copied */
     copySync() { return this.error(); }
-    async rename() { return this.error(); }
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be renamed */
+    rename() { return this.error(); }
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be renamed */
     renameSync() { return this.error(); }
     isUnusable() { return true; }
 }
 export class BlockDevice extends UnusableRoad {
-    async check() { return (await fp.lstat(this.isAt)).isBlockDevice(); }
-    checkSync() { return fs.lstatSync(this.isAt).isBlockDevice(); }
+    async check() { try {
+        return (await fp.lstat(this.isAt)).isBlockDevice();
+    }
+    catch {
+        return false;
+    } }
+    checkSync() { try {
+        return fs.lstatSync(this.isAt).isBlockDevice();
+    }
+    catch {
+        return false;
+    } }
     isBlockDevice() { return true; }
 }
 export class CharacterDevice extends UnusableRoad {
-    async check() { return (await fp.lstat(this.isAt)).isCharacterDevice(); }
-    checkSync() { return fs.lstatSync(this.isAt).isCharacterDevice(); }
+    async check() { try {
+        return (await fp.lstat(this.isAt)).isCharacterDevice();
+    }
+    catch {
+        return false;
+    } }
+    checkSync() { try {
+        return fs.lstatSync(this.isAt).isCharacterDevice();
+    }
+    catch {
+        return false;
+    } }
     isCharacterDevice() { return true; }
 }
 export class Fifo extends UnusableRoad {
-    async check() { return (await fp.lstat(this.isAt)).isFIFO(); }
-    checkSync() { return fs.lstatSync(this.isAt).isFIFO(); }
+    async check() { try {
+        return (await fp.lstat(this.isAt)).isFIFO();
+    }
+    catch {
+        return false;
+    } }
+    checkSync() { try {
+        return fs.lstatSync(this.isAt).isFIFO();
+    }
+    catch {
+        return false;
+    } }
     isFifo() { return true; }
 }
 export class Socket extends UnusableRoad {
-    async check() { return (await fp.lstat(this.isAt)).isSocket(); }
-    checkSync() { return fs.lstatSync(this.isAt).isSocket(); }
+    async check() { try {
+        return (await fp.lstat(this.isAt)).isSocket();
+    }
+    catch {
+        return false;
+    } }
+    checkSync() { try {
+        return fs.lstatSync(this.isAt).isSocket();
+    }
+    catch {
+        return false;
+    } }
     isSocket() { return true; }
 }
-let finalizer = null;
-let toDelete = null;
-let exitHandlerRegistered = null;
-/**
- * Forcefully cleans up all files and folders registered for cleanup on exit.
- */
-function forceCleanupToDelete() {
-    for (const path of toDelete ?? [])
-        try {
-            fs.rmSync(path, { force: true, recursive: true });
-        }
-        catch { }
-    toDelete?.clear();
-    toDelete = null;
-    finalizer = null;
-    if (exitHandlerRegistered)
-        process.off('exit', forceCleanupToDelete);
-    exitHandlerRegistered = false;
-}
-export function registerToCleanup(self_) {
-    finalizer ??= new FinalizationRegistry(p => { try {
-        fs.rmSync(p, { force: true, recursive: true });
-    }
-    catch { } ; toDelete?.delete(p); });
-    toDelete ??= new Set();
-    if (!exitHandlerRegistered) {
-        process.once('exit', forceCleanupToDelete);
-        exitHandlerRegistered = true;
-    }
-    toDelete.add(self_.isAt);
-    finalizer.register(self_, self_.isAt, self_);
-}
-export function Temp(createable_, autoCleanup_) {
-    let t = createable_.createSync(tmp().join(`instrumentality@${cr.randomUUID()}`));
-    if (autoCleanup_)
-        registerToCleanup(t);
-    return Object.freeze(Object.assign(t, {
-        [Symbol.dispose]() { try {
-            t.deleteSync();
-        }
-        catch { } toDelete?.delete(t.isAt); finalizer?.unregister(t); },
-        async [Symbol.asyncDispose]() { try {
-            await t.delete();
-        }
-        catch { } toDelete?.delete(t.isAt); finalizer?.unregister(t); }
-    }));
-}
-11;