instrumentality 0.0.6 → 0.0.8

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,82 +112,78 @@ 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}'`);
+            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); }
+    /**
+     * An async generator that yields the ancestors of the current road, starting from its parent and moving up the directory tree until it reaches the root.
+     *
+     * @yields Each ancestor folder as a {@link Folder} instance.
+     */
+    *ancestorsIt() {
+        let current = this.parent();
+        let parent = current.parent();
+        while (current.isAt !== parent.isAt) {
+            yield current;
+            current = parent;
+            parent = current.parent();
+        }
     }
+    /** @returns An array of {@link Folder} instances representing the ancestors of the current road. */
+    ancestors() { return [...this.ancestorsIt()]; }
     /**
      * 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.
+     * @throws If the road is immutable, a {@link Err} 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).
+     * @remarks This method MUST be used with a `using` statement to ensure that the lock is released properly. Failing to do so WILL result in deadlocks and 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 (for which the `using` statement is a convenient way to do so).
+     * @remarks Methods may call other methods that each acquire their own locks, and release them independently, meaning from the perspective of other instances, the lock may appear to be free even if the original method still has work to do.
+     * To fix this, it's recommeneded to aquire a lock at the beginning and use fs/fp operations within the locked context.
      */
-    async lock(cb_ = () => { }) {
+    async lock() {
         if (!this.mutable)
-            throw new RdErr(`Road to '${this.isAt}' is immutable.`);
+            throw new Err(`Road to '${this.isAt}' is immutable.`);
         lockedRoads ??= new Map();
+        const { promise, resolve } = Promise.withResolvers();
+        const previous = lockedRoads.get(this.isAt);
+        lockedRoads.set(this.isAt, promise);
         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_();
+        const dispose = () => {
+            resolve();
+            if (lockedRoads.get(isAt) === promise)
                 lockedRoads.delete(isAt);
-            }
         };
+        await previous;
+        return { [Symbol.dispose]: dispose, [Symbol.asyncDispose]: dispose };
     }
     /**
      * 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.
+     * @throws 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_ = () => { }) {
+    lockSync() {
         if (!this.mutable)
-            throw new RdErr(`Road to '${this.isAt}' is immutable.`);
+            throw new Err(`Road to '${this.isAt}' is immutable.`);
         lockedRoads ??= new Map();
+        const { promise, resolve } = Promise.withResolvers();
+        if (lockedRoads.has(this.isAt))
+            throw new Err(`Road to '${this.isAt}' is already locked.`);
+        lockedRoads.set(this.isAt, promise);
         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]() {
+        const dispose = () => {
+            resolve();
+            if (lockedRoads.get(isAt) === promise)
                 lockedRoads.delete(isAt);
-                cb_();
-            }
         };
+        return { [Symbol.dispose]: dispose, [Symbol.asyncDispose]: dispose };
     }
-    /** @returns An instance of {@link Folder} representing the parent directory of the current road. */
-    parent() { return new Folder(ph.dirname(this.isAt), false); }
-    /**
-     * An async generator that yields the ancestors of the current road, starting from its parent and moving up the directory tree until it reaches the root.
-     *
-     * @yields Each ancestor folder as a {@link Folder} instance.
-     */
-    *ancestorsIt() {
-        let current = this.parent();
-        let parent = current.parent();
-        while (current.isAt !== parent.isAt) {
-            yield current;
-            current = parent;
-            parent = current.parent();
-        }
-    }
-    /** @returns An array of {@link Folder} instances representing the ancestors of the current road. */
-    ancestors() { return [...this.ancestorsIt()]; }
     /**
      * Watches the current entry for changes and resolves when the entry becomes accessible (i.e., exists and can be accessed).
      *
@@ -215,10 +239,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_, options_) {
+        const newPath = into_.join(this.name);
+        await fp.cp(this.isAt, newPath, { recursive: true, ...options_ });
+        return new this.constructor(newPath, false);
+    }
+    copySync(into_, options_) {
+        const newPath = into_.join(this.name);
+        fs.cpSync(this.isAt, newPath, { recursive: true, ...options_ });
+        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 +291,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,6 +308,13 @@ export class Road {
 }
 /** Subclass of {@link Road} that represents a file. */
 export class File extends Road {
+    /**
+     * 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_) {
         try {
             await fp.access(at_, fsc.W_OK);
@@ -257,6 +324,9 @@ export class File extends Road {
         }
         return new File(at_, true);
     }
+    /** Alias for {@link File.create}. */
+    static mk = File.create;
+    /** Synchronous version of {@link File.create}. */
     static createSync(at_) {
         try {
             fs.accessSync(at_, fs.constants.W_OK);
@@ -266,7 +336,11 @@ export class File extends Road {
         }
         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_)
@@ -280,16 +354,50 @@ export class File extends Road {
         else
             return fs.readFileSync(this.isAt);
     }
+    async sameAs(other_) {
+        if (this.isAt === other_.isAt)
+            return true;
+        else if ((await fp.lstat(this.isAt)).size !== (await fp.lstat(other_.isAt)).size)
+            return false;
+        const iter1 = this.itBuff();
+        const iter2 = other_.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;
+        }
+    }
+    sameAsSync(other_) {
+        if (this.isAt === other_.isAt)
+            return true;
+        else if (fs.lstatSync(this.isAt).size !== fs.lstatSync(other_.isAt).size)
+            return false;
+        const iter1 = this.itBuffSync();
+        const iter2 = other_.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;
+        }
+    }
     async *itBuff(chunkSize_ = 64 * 1024, flags_ = 'r', mode_) {
         const fd = await fp.open(this.isAt, flags_, mode_);
         try {
             const buffer = Buffer.alloc(chunkSize_);
             let bytesRead;
             do {
-                const readResult = await fd.read(buffer, 0, chunkSize_, null);
-                bytesRead = readResult.bytesRead;
+                bytesRead = (await fd.read(buffer, 0, chunkSize_, null)).bytesRead;
                 if (bytesRead > 0)
-                    yield buffer.subarray(0, bytesRead);
+                    yield Buffer.from(buffer.subarray(0, bytesRead));
             } while (bytesRead === chunkSize_);
         }
         finally {
@@ -304,13 +412,73 @@ 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 *itLines(chunkSize_ = 64 * 1024, flags_ = 'r', mode_) {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        let carry = "";
+        for await (const chunk of this.itBuff(chunkSize_, flags_, mode_)) {
+            carry += decoder.decode(chunk, { stream: true });
+            let newlineINdex;
+            while ((newlineINdex = carry.indexOf("\n")) !== -1) {
+                const line = carry.slice(0, newlineINdex);
+                yield line.endsWith("\r") ? line.slice(0, -1) : line;
+                carry = carry.slice(newlineINdex + 1);
+            }
+        }
+        carry += decoder.decode();
+        if (carry.length > 0)
+            yield carry.endsWith("\r") ? carry.slice(0, -1) : carry;
+    }
+    *itLinesSync(chunkSize_ = 64 * 1024, flags_ = 'r', mode_) {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        let carry = "";
+        for (const chunk of this.itBuffSync(chunkSize_, flags_, mode_)) {
+            carry += decoder.decode(chunk, { stream: true });
+            let newlineINdex;
+            while ((newlineINdex = carry.indexOf("\n")) !== -1) {
+                const line = carry.slice(0, newlineINdex);
+                yield line.endsWith("\r") ? line.slice(0, -1) : line;
+                carry = carry.slice(newlineINdex + 1);
+            }
+        }
+        carry += decoder.decode();
+        if (carry.length > 0)
+            yield carry.endsWith("\r") ? carry.slice(0, -1) : carry;
+    }
+    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();
+    }
+    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 size() { return (await this.lstat()).size; }
+    sizeSync() { return this.lstatSync().size; }
+    async writeAtomic(data_, options_) {
+        using _ = await this.lock();
+        const temp = await Temp(File); // Don't use `using` as we won't clean it up
+        await fp.rename(temp.isAt, this.parent().join(temp.name)); // Move temp file to the same directory as the target
+        await fp.writeFile(temp.isAt, data_, options_); // Write data to the temp file
+        await fp.rename(temp.isAt, this.isAt); // Replace the target file with the temp file atomically
+    }
+    writeAtomicSync(data_, options_) {
+        using _ = this.lockSync();
+        const temp = TempSync(File); // Don't use `using` as we won't clean it up
+        fs.renameSync(temp.isAt, this.parent().join(temp.name)); // Move temp file to the same directory as the target
+        fs.writeFileSync(temp.isAt, data_, options_); // Write data to the temp file
+        fs.renameSync(temp.isAt, this.isAt); // Replace the target file with the temp file atomically
+    }
     async write(data_, options_) {
         using _ = await this.lock();
         await fp.writeFile(this.isAt, data_, options_);
@@ -327,122 +495,19 @@ export class File extends Road {
         using _ = this.lockSync();
         fs.appendFileSync(this.isAt, data_, options_);
     }
-    async delete() {
-        using _ = await this.lock();
-        await fp.rm(this.isAt, { force: true });
-    }
-    deleteSync() {
-        using _ = this.lockSync();
-        fs.rmSync(this.isAt, { force: true });
-    }
-    async move(into_) {
-        using _ = await this.lock();
-        const newPath = into_.join(this.name);
-        await fp.rename(this.isAt, newPath);
-        this.pointsTo = newPath;
+    async check() { try {
+        return (await fp.lstat(this.isAt)).isFile();
     }
-    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);
-        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);
-    }
-    async rename(to_) {
-        using _ = await this.lock();
-        const newPath = this.parent().join(to_);
-        await fp.rename(this.isAt, newPath);
-        this.pointsTo = newPath;
-    }
-    renameSync(to_) {
-        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;
-    }
-    finally {
-        rlInterface.close();
-        readStream.destroy();
-    }
-}
-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_) {
@@ -454,6 +519,7 @@ export class Folder extends Road {
         }
         return new Folder(at_, false);
     }
+    static mk = Folder.create;
     static createSync(at_) {
         try {
             fs.accessSync(at_, fsc.W_OK);
@@ -463,43 +529,59 @@ export class Folder extends Road {
         }
         return new Folder(at_, false);
     }
+    static mkSync = Folder.createSync;
     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)));
+    async list(filter_) {
+        const entries = (await fp.readdir(this.isAt, { withFileTypes: true })).map(e => new (resolveDirent(e))(this.join(e.name), false));
         const resolvedEntries = await Promise.all(entries);
-        if (!expectedType_)
+        if (!filter_)
             return resolvedEntries;
-        return resolvedEntries.filter(entry => entry instanceof expectedType_);
+        return resolvedEntries.filter(entry => filter_(entry));
     }
-    listSync(expectedType_) {
-        const entries = fs.readdirSync(this.isAt).map(entry => factorySync(this.join(entry)));
-        if (!expectedType_)
+    listSync(filter_) {
+        const entries = fs.readdirSync(this.isAt, { withFileTypes: true }).map(e => new (resolveDirent(e))(this.join(e.name), false));
+        if (!filter_)
             return entries;
-        return entries.filter(entry => entry instanceof expectedType_);
+        return entries.filter(entry => filter_(entry));
+    }
+    async *walk(filter_) {
+        for await (const entry of this.it()) {
+            if (!filter_ || filter_(entry))
+                yield entry;
+            if (entry.isDir())
+                yield* entry.walk(filter_);
+        }
+    }
+    *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;
         }
@@ -507,16 +589,16 @@ 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;
         }
     }
@@ -530,55 +612,33 @@ export class Folder extends Road {
         createable_.createSync(newPath);
         return factorySync(newPath);
     }
-    async delete(options_ = { recursive: true }) {
-        using _ = await this.lock();
-        await fp.rm(this.isAt, options_);
+    async size() {
+        let size = 0;
+        for await (const entry of this.it())
+            size += await entry.size();
+        return size;
     }
-    deleteSync(options_ = { recursive: true }) {
-        using _ = this.lockSync();
-        fs.rmSync(this.isAt, options_);
+    sizeSync() {
+        let size = 0;
+        for (const entry of this.itSync())
+            size += entry.sizeSync();
+        return size;
     }
-    async move(into_) {
-        using _ = await this.lock();
-        const newPath = into_.join(this.name);
-        await fp.rename(this.isAt, newPath);
-        this.pointsTo = newPath;
+    async check() { try {
+        return (await fp.lstat(this.isAt)).isDirectory();
     }
-    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);
-        await fp.cp(this.isAt, newPath, { recursive: true });
-        return new Folder(newPath, false);
-    }
-    copySync(into_) {
-        const newPath = into_.join(this.name);
-        fs.cpSync(this.isAt, newPath, { recursive: true });
-        return new Folder(newPath, false);
-    }
-    async rename(to_) {
-        using _ = await this.lock();
-        const newPath = this.parent().join(to_);
-        await fp.rename(this.isAt, newPath);
-        this.pointsTo = newPath;
-    }
-    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); }
@@ -595,6 +655,7 @@ export class SymbolicLink extends Road {
         }
         return new SymbolicLink(at_, false);
     }
+    static mk = SymbolicLink.create;
     static createSync(at_, target_) {
         try {
             fs.accessSync(at_, fs.constants.F_OK);
@@ -604,6 +665,7 @@ export class SymbolicLink extends Road {
         }
         return new SymbolicLink(at_, false);
     }
+    static mkSync = SymbolicLink.createSync;
     async target() {
         return factory(ph.resolve(ph.dirname(this.isAt), await fp.readlink(this.isAt)));
     }
@@ -611,13 +673,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);
@@ -626,87 +692,136 @@ 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;
+    async check() { try {
+        return (await fp.lstat(this.isAt)).isSymbolicLink();
     }
-    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;
-    }
-    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 };
+here().walk(r => !r.isSymlink());
 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; }
 }
+export async function Temp(createable_) {
+    let t = await createable_.create(tmp().join(`instrumentality@${cr.randomUUID()}`));
+    return 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); }
+    });
+}
+export function TempSync(createable_) {
+    let t = createable_.createSync(tmp().join(`instrumentality@${cr.randomUUID()}`));
+    return 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); }
+    });
+}
 let finalizer = null;
 let toDelete = null;
 let exitHandlerRegistered = null;
@@ -739,8 +854,22 @@ export function registerToCleanup(self_) {
     toDelete.add(self_.isAt);
     finalizer.register(self_, self_.isAt, self_);
 }
-export function Temp(createable_, autoCleanup_) {
-    let t = createable_.createSync(tmp().join(`instrumentality@${cr.randomUUID()}`));
+export async function AutoTemp(createable_) {
+    let t = await createable_.mk(tmp().join(`instrumentality@${cr.randomUUID()}`));
+    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); }
+    }));
+}
+export function AutoTempSync(createable_, autoCleanup_) {
+    let t = createable_.mk(tmp().join(`instrumentality@${cr.randomUUID()}`));
     if (autoCleanup_)
         registerToCleanup(t);
     return Object.freeze(Object.assign(t, {
@@ -754,4 +883,3 @@ export function Temp(createable_, autoCleanup_) {
         catch { } toDelete?.delete(t.isAt); finalizer?.unregister(t); }
     }));
 }
-11;