instrumentality 0.0.13 → 0.0.15

package/dist/road.js

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import * as cr from "node:crypto";
 import * as fs from "node:fs";
 import { constants as fsc } from "node:fs";
@@ -57,22 +58,6 @@ export function resolveDirent(dirent) {
     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.
- *
- * @param path_ The path to follow.
- * @returns A new instance of {@link Road}.
- * @throws If {@link fp.lstat}/{@link fs.lstatSync} fails to retrieved the status of {@link path_}.
- */
-export async function factory(path_) {
-    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 (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.
  *
@@ -91,18 +76,32 @@ export let lockedRoads = null;
  * It is more like a memory representation, similar to a pointer in low-level programming languages; other processes might mess with the underlying entry. There are methods to check for consistency, but they are not guaranteed to be foolproof.
  */
 export class Road {
-    /** The absolute path to the file or directory that this Road instance represents.
+    /** The absolute path to the entry that this Road instance represents.
      * @remarks Intentionally made protected to prevent external modification, as changing this value could lead to inconsistencies and unexpected behavior. */
     pointsTo;
-    /** Indicates whether the file or directory represented by this Road instance can be modified.
+    /** Indicates which operations are allowed on the entry represented by this Road instance.
      * Changing this value does not affect the actual file system permissions, but rather serves as a safeguard within the application to prevent accidental modifications. */
-    mutable = true;
+    writable = true;
+    moveable = true;
+    deletable = true;
+    copyable = true;
+    renameable = true;
+    assertWrite() { if (!this.writable)
+        throw new Err(`Road to '${this.isAt}' isn't writable.`); }
+    assertMove() { if (!this.moveable)
+        throw new Err(`Road to '${this.isAt}' isn't moveable.`); }
+    assertDelete() { if (!this.deletable)
+        throw new Err(`Road to '${this.isAt}' isn't deletable.`); }
+    assertCopy() { if (!this.copyable)
+        throw new Err(`Road to '${this.isAt}' isn't copyable.`); }
+    assertRename() { if (!this.renameable)
+        throw new Err(`Road to '${this.isAt}' isn't renameable.`); }
     // Quick accessors
     /** Copy of the absolute path. */
     get isAt() { return this.pointsTo; }
     /** Name of the road without the path (including extensions). */
     get name() { return this.isAt.slice(this.isAt.lastIndexOf(ph.sep) + 1); }
-    /** The amount of path segments in the absolute path to the file or directory represented by this Road instance, minus one (i.e., the depth of the path in the file system hierarchy). */
+    /** The amount of path segments in the absolute path to the entry represented by this Road instance, minus one (i.e., the depth of the path in the file system hierarchy). */
     get depth() { return this.isAt.split(ph.sep).length - 1; }
     /** Same as {@link isAt} but for compatibility with external APIs. */
     toString() { return this.isAt; }
@@ -116,7 +115,7 @@ export class Road {
      */
     constructor(path_, typeCheck_) {
         this.pointsTo = ph.resolve(path_);
-        if (typeCheck_ && !this.checkSync())
+        if (typeCheck_ && !this.checkSync(true))
             throw new Err(`Type mismatch: '${this.isAt}'`);
     }
     /** @returns An instance of {@link Folder} representing the parent directory of the current road. */
@@ -138,8 +137,6 @@ 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;
@@ -161,7 +158,9 @@ export class Road {
         try {
             await l.previous;
         }
-        catch { }
+        catch {
+            null;
+        }
         return l;
     }
     lockSync() {
@@ -180,7 +179,7 @@ export class Road {
     async untilAccessible(abs, expectMode = fsc.F_OK, cb_) {
         const watcher = fs.watch(this.isAt);
         try {
-            for await (let _ of on(watcher, 'change', { signal: abs })) {
+            for await (const _ of on(watcher, 'change', { signal: abs })) {
                 try {
                     await fp.access(this.isAt, expectMode);
                     return;
@@ -207,7 +206,7 @@ export class Road {
     async onChange(abs_, cb_) {
         const watcher = fs.watch(this.isAt);
         try {
-            for await (let _ of on(watcher, 'change', { signal: abs_ }))
+            for await (const _ of on(watcher, 'change', { signal: abs_ }))
                 return await cb_?.() ?? null;
             return null;
         }
@@ -224,43 +223,51 @@ export class Road {
     lstatSync() { return fs.lstatSync(this.isAt); }
     /** Wrapper around {@link fp.rm} with locking. */
     async delete() {
+        this.assertDelete();
         using _ = await this.lock();
         await fp.rm(this.isAt, { recursive: true, force: true });
     }
     /** Wrapper around {@link fs.rmSync} with locking. */
     deleteSync() {
+        this.assertDelete();
         using _ = this.lockSync();
         fs.rmSync(this.isAt, { recursive: true, force: true });
     }
     async copy(into_) {
+        this.assertCopy();
         const newPath = into_.join(this.name);
         await fp.cp(this.isAt, newPath, { recursive: true, force: true });
         return new this.constructor(newPath, false);
     }
     copySync(into_) {
+        this.assertCopy();
         const newPath = into_.join(this.name);
         fs.cpSync(this.isAt, newPath, { recursive: true, force: true });
         return new this.constructor(newPath, false);
     }
     async move(into_) {
+        this.assertMove();
         using _ = await this.lock();
         const newPath = into_.join(this.name);
         await fp.rename(this.isAt, newPath);
         this.pointsTo = newPath;
     }
     moveSync(into_) {
+        this.assertMove();
         using _ = this.lockSync();
         const newPath = into_.join(this.name);
         fs.renameSync(this.isAt, newPath);
         this.pointsTo = newPath;
     }
     async rename(newName_) {
+        this.assertRename();
         using _ = await this.lock();
         const newPath = this.parent().join(newName_);
         await fp.rename(this.isAt, newPath);
         this.pointsTo = newPath;
     }
     renameSync(newName_) {
+        this.assertRename();
         using _ = this.lockSync();
         const newPath = this.parent().join(newName_);
         fs.renameSync(this.isAt, newPath);
@@ -289,6 +296,18 @@ export class Road {
     /** Type narrowing for {@link Socket} (similar to `instanceof` without unnecessary runtime checks). */
     isSocket() { return false; }
 }
+/**
+ * Creates the appropriate subclass of {@link Road} based on the file mode of the specified path.
+ *
+ * @param path_ The path to follow.
+ * @returns A new instance of {@link Road}.
+ * @throws If {@link fp.lstat}/{@link fs.lstatSync} fails to retrieved the status of {@link path_}.
+ */
+export async function road(path_) { return new (resolveStat((await fp.lstat(path_)).mode))(path_, false); }
+export { road as fac, road as mk, road as factory };
+/** Sync version of {@link road}. */
+export function roadSync(path_) { return new (resolveStat((fs.lstatSync(path_).mode)))(path_, false); }
+export { roadSync as facSync, roadSync as mkSync, roadSync as factorySync };
 /** Subclass of {@link Road} that represents a file. */
 export class File extends Road {
     /**
@@ -326,7 +345,7 @@ export class File extends Road {
     /** The file name without its extension. */
     get noExt() { return ph.basename(this.isAt, this.ext); }
     async read(options_) {
-        return fp.readFile(this.isAt, options_);
+        return await fp.readFile(this.isAt, options_);
     }
     readSync(options_) {
         return fs.readFileSync(this.isAt, options_);
@@ -408,11 +427,15 @@ export class File extends Road {
             try {
                 iter1.return?.(undefined);
             }
-            catch { }
+            catch {
+                null;
+            }
             try {
                 iter2.return?.(undefined);
             }
-            catch { }
+            catch {
+                null;
+            }
         }
     }
     async hash(algorithm_ = "sha256", options_, encoding_) {
@@ -430,30 +453,37 @@ export class File extends Road {
     async size() { return (await this.lstat()).size; }
     sizeSync() { return this.lstatSync().size; }
     async writeAtomic(data_, options_) {
+        this.assertWrite();
         using _ = await this.lock();
         await this.parent().borrow(File, async (tmp) => {
+            tmp.assertWrite();
             using _ = await tmp.lock();
             await fp.writeFile(tmp.isAt, data_, options_);
             await fp.rename(tmp.isAt, this.isAt);
         });
     }
     writeAtomicSync(data_, options_) {
+        this.assertWrite();
         using _ = this.lockSync();
         this.parent().borrowSync(File, tmp => {
+            tmp.assertWrite();
             using _ = tmp.lockSync();
             fs.writeFileSync(tmp.isAt, data_, options_);
             fs.renameSync(tmp.isAt, this.isAt);
         });
     }
     async write(data_, options_) {
+        this.assertWrite();
         using _ = await this.lock();
         await fp.writeFile(this.isAt, data_, options_);
     }
     writeSync(data_, options_) {
+        this.assertWrite();
         using _ = this.lockSync();
         fs.writeFileSync(this.isAt, data_, options_);
     }
     async writePast(offset_, data_) {
+        this.assertWrite();
         using _ = await this.lock();
         const fd = await fp.open(this.isAt, 'r+');
         try {
@@ -465,6 +495,7 @@ export class File extends Road {
         }
     }
     writePastSync(offset_, data_) {
+        this.assertWrite();
         using _ = this.lockSync();
         const fd = fs.openSync(this.isAt, 'r+');
         try {
@@ -476,6 +507,7 @@ export class File extends Road {
         }
     }
     async truncWritePast(offset_, data_) {
+        this.assertWrite();
         using _ = await this.lock();
         const fd = await fp.open(this.isAt, 'r+');
         try {
@@ -488,6 +520,7 @@ export class File extends Road {
         }
     }
     truncWritePastSync(offset_, data_) {
+        this.assertWrite();
         using _ = this.lockSync();
         const fd = fs.openSync(this.isAt, 'r+');
         try {
@@ -500,23 +533,29 @@ export class File extends Road {
         }
     }
     async append(data_, options_) {
+        this.assertWrite();
         using _ = await this.lock();
         await fp.appendFile(this.isAt, data_, options_);
     }
     appendSync(data_, options_) {
+        this.assertWrite();
         using _ = this.lockSync();
         fs.appendFileSync(this.isAt, data_, options_);
     }
-    async check() { try {
+    async check(throwOnError_) { try {
         return (await fp.lstat(this.isAt)).isFile();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
-    checkSync() { try {
+    checkSync(throwOnError_) { try {
         return fs.lstatSync(this.isAt).isFile();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
     isFile() { return true; }
@@ -584,12 +623,10 @@ export class Folder extends Road {
                 yield* entry.walkSync(filter_);
         }
     }
-    async find(name_, expect_) {
+    async find(name_, filter_) {
         try {
-            const found = await factory(this.join(name_));
-            if (!expect_)
-                return found;
-            if (found instanceof expect_)
+            const found = await road(this.join(name_));
+            if (!filter_ || filter_(found))
                 return found;
             return null;
         }
@@ -597,45 +634,45 @@ export class Folder extends Road {
             return null;
         }
     }
-    findSync(name_, expect_) {
+    findSync(name_, filter_) {
         try {
-            const found = factorySync(this.join(name_));
-            if (!expect_)
-                return found;
-            if (found instanceof expect_)
+            const found = roadSync(this.join(name_));
+            if (!filter_ || filter_(found))
                 return found;
             return null;
         }
-        catch (e) {
+        catch {
             return null;
         }
     }
     async add(name_, createable_) {
+        this.assertWrite();
         const newPath = this.join(name_);
         await createable_.mk(newPath);
-        return (await factory(newPath));
+        return (await road(newPath));
     }
     addSync(name_, createable_) {
+        this.assertWrite();
         const newPath = this.join(name_);
         createable_.mkSync(newPath);
-        return factorySync(newPath);
+        return roadSync(newPath);
     }
     async borrow(createable_, cb_) {
-        const path = this.join(`instrumentality@${crypto.randomUUID()}`);
+        const created = await createable_.mk(this.join(`instrumentality@${crypto.randomUUID()}`));
         try {
-            await cb_(await createable_.mk(path));
+            await cb_(created);
         }
         finally {
-            await fp.rm(path, { recursive: true, force: true });
+            await fp.rm(created.isAt, { recursive: true, force: true });
         }
     }
     borrowSync(createable_, cb_) {
-        const path = this.join(`instrumentality@${crypto.randomUUID()}`);
+        const created = createable_.mkSync(this.join(`instrumentality@${crypto.randomUUID()}`));
         try {
-            cb_(createable_.mkSync(path));
+            cb_(created);
         }
         finally {
-            fs.rmSync(path, { recursive: true, force: true });
+            fs.rmSync(created.isAt, { recursive: true, force: true });
         }
     }
     async size() {
@@ -650,16 +687,20 @@ export class Folder extends Road {
             size += entry.sizeSync();
         return size;
     }
-    async check() { try {
+    async check(throwOnError_) { try {
         return (await fp.lstat(this.isAt)).isDirectory();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
-    checkSync() { try {
+    checkSync(throwOnError_) { try {
         return fs.lstatSync(this.isAt).isDirectory();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
     isFolder() { return true; }
@@ -668,11 +709,12 @@ export class Folder extends Road {
 }
 export function folder(...args) { return new Folder(...args); }
 export function dir(...args) { return new Folder(...args); }
+export function directory(...args) { return new Folder(...args); }
 export function sysRoot() { return new Folder(ph.parse(process.cwd()).root, false); }
 export function home() { return new Folder(os.homedir(), false); }
 export function tmp() { return new Folder(os.tmpdir(), false); }
 export function here() { return new Folder(process.cwd(), false); }
-export { Folder as Dir, Folder as Directory, Folder as Dict, Folder as Dictionary };
+export { Folder as Dir, Folder as Directory };
 export class SymbolicLink extends Road {
     static async create(at_, target_) {
         try {
@@ -695,17 +737,21 @@ export class SymbolicLink extends Road {
     }
     static mkSync = SymbolicLink.createSync;
     async target() {
-        return factory(ph.resolve(ph.dirname(this.isAt), await fp.readlink(this.isAt)));
+        return await road(ph.resolve(ph.dirname(this.isAt), await fp.readlink(this.isAt)));
     }
     targetSync() {
-        return factorySync(ph.resolve(ph.dirname(this.isAt), fs.readlinkSync(this.isAt)));
+        return roadSync(ph.resolve(ph.dirname(this.isAt), fs.readlinkSync(this.isAt)));
     }
     async retarget(to_) {
+        this.assertDelete();
+        this.assertWrite();
         using _ = await this.lock();
         await fp.unlink(this.isAt);
         await fp.symlink(to_.isAt, this.isAt);
     }
     retargetSync(to_) {
+        this.assertDelete();
+        this.assertWrite();
         using _ = this.lockSync();
         fs.unlinkSync(this.isAt);
         fs.symlinkSync(to_.isAt, this.isAt);
@@ -713,23 +759,29 @@ export class SymbolicLink extends Road {
     async size() { return (await this.lstat()).size; }
     sizeSync() { return this.lstatSync().size; }
     async delete() {
+        this.assertDelete();
         using _ = await this.lock();
         await fp.unlink(this.isAt);
     }
     deleteSync() {
+        this.assertDelete();
         using _ = this.lockSync();
         fs.unlinkSync(this.isAt);
     }
-    async check() { try {
+    async check(throwOnError_) { try {
         return (await fp.lstat(this.isAt)).isSymbolicLink();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
-    checkSync() { try {
+    checkSync(throwOnError_) { try {
         return fs.lstatSync(this.isAt).isSymbolicLink();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
     isSymlink() { return true; }
@@ -737,92 +789,118 @@ export class SymbolicLink extends Road {
 }
 export { SymbolicLink as Symlink };
 export function symlink(...args) { return new SymbolicLink(...args); }
+/**
+ * Represents a system-level resource that is not subject to modification.
+ * All modification operations will throw an error.
+ *
+ * One could say 'this road truly is *unusable*.' hehe
+ */
 export class UnusableRoad extends Road {
-    mutable = false; // Modification will cause system issues (e.g. deleting a device file)
-    async size() { return 0; }
+    // Modification will cause system issues (e.g. deleting a device file)
+    writable = false;
+    moveable = false;
+    deletable = false;
+    copyable = false;
+    size() { return Promise.resolve(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 */
+    /** @deprecated System-level resources ({@link UnusableRoad}) can't/shouldn't be locked */
     lock() { return this.error(); }
-    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be locked */
+    /** @deprecated System-level resources ({@link UnusableRoad}) can't/shouldn't be locked */
     lockSync() { return this.error(); }
-    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be deleted */
+    /** @deprecated System-level resources ({@link UnusableRoad}) can't/shouldn't be deleted */
     delete() { return this.error(); }
-    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be deleted */
+    /** @deprecated System-level resources ({@link UnusableRoad}) can't/shouldn't be deleted */
     deleteSync() { return this.error(); }
-    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be moved */
+    /** @deprecated System-level resources ({@link UnusableRoad}) can't/shouldn't be moved */
     move() { return this.error(); }
-    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be moved */
+    /** @deprecated System-level resources ({@link UnusableRoad}) can't/shouldn't be moved */
     moveSync() { return this.error(); }
-    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be copied */
+    /** @deprecated System-level resources ({@link UnusableRoad}) can't/shouldn't be copied */
     copy() { return this.error(); }
-    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be copied */
+    /** @deprecated System-level resources ({@link UnusableRoad}) can't/shouldn't be copied */
     copySync() { return this.error(); }
-    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be renamed */
+    /** @deprecated System-level resources ({@link UnusableRoad}) can't/shouldn't be renamed */
     rename() { return this.error(); }
-    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be renamed */
+    /** @deprecated System-level resources ({@link UnusableRoad}) can't/shouldn't be renamed */
     renameSync() { return this.error(); }
     isUnusable() { return true; }
 }
 export class BlockDevice extends UnusableRoad {
-    async check() { try {
+    async check(throwOnError_) { try {
         return (await fp.lstat(this.isAt)).isBlockDevice();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
-    checkSync() { try {
+    checkSync(throwOnError_) { try {
         return fs.lstatSync(this.isAt).isBlockDevice();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
     isBlockDevice() { return true; }
 }
 export function blockDevice(...args) { return new BlockDevice(...args); }
 export class CharacterDevice extends UnusableRoad {
-    async check() { try {
+    async check(throwOnError_) { try {
         return (await fp.lstat(this.isAt)).isCharacterDevice();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
-    checkSync() { try {
+    checkSync(throwOnError_) { try {
         return fs.lstatSync(this.isAt).isCharacterDevice();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
     isCharacterDevice() { return true; }
 }
 export function characterDevice(...args) { return new CharacterDevice(...args); }
 export class Fifo extends UnusableRoad {
-    async check() { try {
+    async check(throwOnError_) { try {
         return (await fp.lstat(this.isAt)).isFIFO();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
-    checkSync() { try {
+    checkSync(throwOnError_) { try {
         return fs.lstatSync(this.isAt).isFIFO();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
     isFifo() { return true; }
 }
 export function fifo(...args) { return new Fifo(...args); }
 export class Socket extends UnusableRoad {
-    async check() { try {
+    async check(throwOnError_) { try {
         return (await fp.lstat(this.isAt)).isSocket();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
-    checkSync() { try {
+    checkSync(throwOnError_) { try {
         return fs.lstatSync(this.isAt).isSocket();
     }
-    catch {
+    catch (e) {
+        if (throwOnError_)
+            throw e;
         return false;
     } }
     isSocket() { return true; }

package/package.json

@@ -5,7 +5,7 @@
     "url": "https://github.com/clerkburk/instrumentality.git"
   },
   "type": "module",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "main": "./dist/base.js",
   "types": "./dist/base.d.ts",
   "devDependencies": {

package/src/dom.ts

@@ -1,9 +1,9 @@
 /**
  * Resolves on `DOMContentLoaded` or immediately if the document is already ready.
  */
-export async function onceReady(): Promise<void> {
+export function onceReady(): Promise<void> {
   if (document.readyState === "complete" || document.readyState === "interactive")
-    return
+    return Promise.resolve()
   return new Promise(r => document.addEventListener("DOMContentLoaded", () => r(), { once: true }))
 }