instrumentality 0.0.7 → 0.0.9

package/README.md

@@ -1,9 +1,7 @@
-![white title](./assets/titleLight.webp)
-
-
 ## The INSTRUMENTALITY project (concept)
 A utility library for TypeScript/Node.js
 
+![white title](./assets/titleLight.webp)
 
 #
 ### What is this?
@@ -13,13 +11,13 @@ A combination of files to handle TS/JS by itself, Node and DOM (for web) that pr
 #
 ### How to use
 ```sh
-npm install git+https://github.com/clerkburk/ts-instrumentality.git
+npm install instrumentality
 ```
 then
 ```ts
 import * as ins from "instrumentality" // Base
 import * as ind from "instrumentality/dom" // Browser (if available)
-import * as inr from "instrumentality/road" // Filesystem using Node.js (if available)
+import * as inr from "instrumentality/road" // Filesystem using Node.js (if available, deno 2 support is experimental)
 ```
 thats literally it
 

package/dist/base.d.ts

@@ -1,27 +1,27 @@
 /** Subclass of {@link Error} that represents an error thrown from this library, providing a specific name for easier identification. */
-export declare class InsErr extends Error {
+export declare class Err extends Error {
     name: string;
 }
+export { Err as InsErr };
 /**
- * Retries a function multiple times with optional error handling and abort signal.
+ * Retries a function multiple times until it succeeds or the maximum number of attempts is reached, or the error callback indicates to stop.
  *
  * @param fn_ - The function to be retried.
  * @param maxAttempts_ - The maximum number of attempts to execute the function.
- * @param cbErr_ - An optional callback function to be executed after each failed attempt.
- * @param abs_ - An optional AbortSignal to abort the retry process.
+ * @param cbErr_ - An optional callback function that is invoked when an error occurs. It receives the error and the remaining number of attempts as arguments and should return `true` to continue retrying or `false` to stop.
  * @returns The result of {@link fn_} if it succeeds within the allowed attempts.
- * @throws {unknown} If {@link fn_} fails after the maximum attempts, the last error thrown by {@link fn_} is re-thrown.
- * @throws {InsErr} If the maximum attempts is less than 1 or if the operation is aborted.
+ * @throws the last error thrown by {@link fn_} if it fails after the maximum attempts or if the error callback indicates to stop.
+ * @throws If {@link cbErr_} throws or returns a rejected promise, the error is propagated immediately.
+ * @throws {InsErr} If {@link maxAttempts_} isn't a positive integer.
  */
-export declare function retry<T>(fn_: () => T, maxAttempts_: number, cbErr_?: () => unknown, abs_?: AbortSignal): Promise<T>;
+export declare function retry<T>(fn_: () => T | PromiseLike<T>, maxAttempts_: number, cbErr_?: (err: unknown, remainingAttempts: number) => boolean | PromiseLike<boolean>): Promise<T>;
 /**
- * Asynchronously sleep.
+ * Alias for `setTimeout`.
  *
  * @param ms_ - The number of milliseconds to sleep.
- * @param abs_ - An optional AbortSignal to abort the sleep.
- * @throws {InsErr} If the sleep is aborted before or during the wait.
+ * @remarks The delay is a minimum, not an exact duration. The actual elapsed time also includes timer scheduling, event-loop latency, and promise-continuation overhead, so it may exceed {@link ms_}, especially for short delays.
  */
-export declare function sleep(ms_: number, abs_?: AbortSignal): Promise<void>;
+export declare function sleep(ms_: number): Promise<void>;
 /**
  * Build a tuple of a specified length.
  *
@@ -115,7 +115,6 @@ export declare const BASE122_SHORT: 7;
  *
  * @param data_ - An array-like object containing the data to be encoded.
  * @returns A string representing the base-122 encoded data.
- * @throws If somehow malformed UTF-8 data is generated, the {@link TextDecoder} will throw an error (shouldn't happen if the input is valid).
  * @remarks The high density might not be suitable for all use cases, especially if the medium used to transmit the data has limitations on character sets or encoding.
  * @see {@link TextDecoder} how the output string is generated from the byte array (this step is necessary for accurate translation to a string).
  */

package/dist/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA,wIAAwI;AACxI,qBAAa,GAAI,SAAQ,KAAK;IAAY,IAAI,SAA0B;CAAE;AAC1E,OAAO,EAAE,GAAG,IAAI,MAAM,EAAE,CAAA;AAIxB;;;;;;;;;;GAUG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAUpL;AAID;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAsD;AAIvG;;;;;GAKG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,IACvD,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;AAGhE;;;;;GAKG;AACH,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAChD;IAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAAE,GAAG,UAAU,CAAC,CAAC,CAAC;CAAC,CAAC,QAAQ,CAAC,CAAA;AAGhD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,IAC/D,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;AAIrE;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,SAAS;IACpB,kGAAkG;IAClG,MAAM,EAAE,MAAM,EAAE,CAAK;IACrB,0EAA0E;IAC1E,KAAK,SAAoB;IACzB,+DAA+D;IAC/D,KAAK,SAAgE;IACrE,iFAAiF;IACjF,KAAK,SAAuD;IAC5D,wFAAwF;IACxF,IAAI,KAAK,WAA8D;IACvE,iEAAiE;IACjE,IAAI,CAAC,WAA0B;IAC/B,+DAA+D;IAC/D,IAAI,EAAE,WAAwB;IAC9B,6BAA6B;IAC7B,IAAI,CAAC,WAAwB;IAC7B,4BAA4B;IAC5B,IAAI,CAAC,WAAyB;IAC9B,6BAA6B;IAC7B,IAAI,CAAC,WAAyB;IAC9B,+BAA+B;IAC/B,IAAI,CAAC,WAAyB;IAC9B,+BAA+B;IAC/B,IAAI,CAAC,WAA4B;IACjC,oCAAoC;IACpC,IAAI,EAAE,WAA4C;IAClD,oCAAoC;IACpC,IAAI,EAAE,WAA2B;IACjC,mCAAmC;IACnC,IAAI,EAAE,WAA2B;IACjC,mCAAmC;IACnC,IAAI,EAAE,WAA2B;CAClC;AACD,OAAO,EAAE,SAAS,IAAI,KAAK,EAAE,SAAS,IAAI,KAAK,EAAE,SAAS,IAAI,SAAS,EAAE,CAAA;AAIzE,uGAAuG;AACvG,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,EACxC,IAAI,GACJ,UAAU,GACV,SAAS,GACT,aAAa,GACb,MAAM,GACN,WAAW,GACX,UAAU,GACV,eAAe,GACf,OAAO,GACP,MAAM,GACN,SAAS,GACT,SAAS,GACT,MAAM,GACN,QAAQ,GACR,OAAO,MAAM,CAAC,QAAQ,GACtB,QAAQ,GACR,aAAa,GACb,MAAM,GACN,gBAAgB,GAChB,UAAU,GACV,KAAK,GACL,QAAQ,GACR,OAAO,GACP,YAAY,GACZ,UAAU,GACV,MAAM,GACN,QAAQ,GACR,YAAY,GACZ,YAAY,CACf,GAAG;IAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AAIpC,yJAAyJ;AACzJ,eAAO,MAAM,eAAe,YAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAU,CAAA;AAC/D,iHAAiH;AACjH,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOzD,CAAA;AACV,8JAA8J;AAC9J,eAAO,MAAM,aAAa,EAAG,CAAc,CAAA;AAG3C;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAmC1D;AAGD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,2BAgCzC"}

package/dist/base.js

@@ -1,56 +1,38 @@
 /** Subclass of {@link Error} that represents an error thrown from this library, providing a specific name for easier identification. */
-export class InsErr extends Error {
+export class Err extends Error {
     name = "Instrumentality-Error";
 }
+export { Err as InsErr };
 /**
- * Retries a function multiple times with optional error handling and abort signal.
+ * Retries a function multiple times until it succeeds or the maximum number of attempts is reached, or the error callback indicates to stop.
  *
  * @param fn_ - The function to be retried.
  * @param maxAttempts_ - The maximum number of attempts to execute the function.
- * @param cbErr_ - An optional callback function to be executed after each failed attempt.
- * @param abs_ - An optional AbortSignal to abort the retry process.
+ * @param cbErr_ - An optional callback function that is invoked when an error occurs. It receives the error and the remaining number of attempts as arguments and should return `true` to continue retrying or `false` to stop.
  * @returns The result of {@link fn_} if it succeeds within the allowed attempts.
- * @throws {unknown} If {@link fn_} fails after the maximum attempts, the last error thrown by {@link fn_} is re-thrown.
- * @throws {InsErr} If the maximum attempts is less than 1 or if the operation is aborted.
+ * @throws the last error thrown by {@link fn_} if it fails after the maximum attempts or if the error callback indicates to stop.
+ * @throws If {@link cbErr_} throws or returns a rejected promise, the error is propagated immediately.
+ * @throws {InsErr} If {@link maxAttempts_} isn't a positive integer.
  */
-export async function retry(fn_, maxAttempts_, cbErr_, abs_) {
-    while (--maxAttempts_ >= 0 && !(abs_?.aborted ?? false))
+export async function retry(fn_, maxAttempts_, cbErr_) {
+    if (!Number.isInteger(maxAttempts_) || maxAttempts_ < 1)
+        throw new Err("Max attempts isn't a positive integer");
+    while (true)
         try {
             return await fn_();
         }
         catch (err) {
-            if (maxAttempts_ <= 0)
+            if (--maxAttempts_ <= 0 || (cbErr_ && !(await cbErr_(err, maxAttempts_))))
                 throw err;
-            await cbErr_?.();
         }
-    if (maxAttempts_ < 0)
-        throw new InsErr("Max attempts must be at least 1");
-    else
-        throw new InsErr("Operation aborted");
 }
 /**
- * Asynchronously sleep.
+ * Alias for `setTimeout`.
  *
  * @param ms_ - The number of milliseconds to sleep.
- * @param abs_ - An optional AbortSignal to abort the sleep.
- * @throws {InsErr} If the sleep is aborted before or during the wait.
+ * @remarks The delay is a minimum, not an exact duration. The actual elapsed time also includes timer scheduling, event-loop latency, and promise-continuation overhead, so it may exceed {@link ms_}, especially for short delays.
  */
-export async function sleep(ms_, abs_) {
-    if (abs_?.aborted)
-        return Promise.reject(new InsErr("Sleep aborted before start"));
-    return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-            abs_?.removeEventListener("abort", onAbort);
-            resolve();
-        }, ms_);
-        function onAbort() {
-            clearTimeout(timeout);
-            abs_?.removeEventListener("abort", onAbort);
-            reject(new InsErr("Sleep aborted during wait"));
-        }
-        abs_?.addEventListener("abort", onAbort, { once: true });
-    });
-}
+export function sleep(ms_) { return new Promise(r => setTimeout(r, ms_)); }
 /**
  * Wrapper around {@link performance.now}
  *
@@ -123,12 +105,12 @@ export const BASE122_SHORT = 0b111;
  *
  * @param data_ - An array-like object containing the data to be encoded.
  * @returns A string representing the base-122 encoded data.
- * @throws If somehow malformed UTF-8 data is generated, the {@link TextDecoder} will throw an error (shouldn't happen if the input is valid).
  * @remarks The high density might not be suitable for all use cases, especially if the medium used to transmit the data has limitations on character sets or encoding.
  * @see {@link TextDecoder} how the output string is generated from the byte array (this step is necessary for accurate translation to a string).
  */
 export function encode122(data_) {
-    const out = [];
+    const out = new Uint8Array(2 * Math.ceil(data_.length * 8 / 7));
+    let outIndex = 0;
     let byteIndex = 0;
     let bitIndex = 0;
     function next7() {
@@ -149,14 +131,16 @@ export function encode122(data_) {
     for (let value = next7(); value !== undefined; value = next7()) {
         const illegalIndex = BASE122_ILLEGAL_INDEX[value];
         if (illegalIndex === undefined)
-            out.push(value);
+            out[outIndex++] = value;
         else {
             const next = next7();
             const payload = next ?? value;
-            out.push(0b11000010 | ((next === undefined ? BASE122_SHORT : illegalIndex) << 2) | (payload >>> 6), 0b10000000 | (payload & 0b00111111));
+            out[outIndex++] =
+                0b11000010 | ((next === undefined ? BASE122_SHORT : illegalIndex) << 2) | (payload >>> 6),
+                out[outIndex++] = 0b10000000 | (payload & 0b00111111);
         }
     }
-    return new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(out));
+    return new TextDecoder("utf-8", { fatal: true }).decode(out.subarray(0, outIndex));
 }
 /**
  * Decodes a base-122 encoded string back into its original byte representation.
@@ -190,7 +174,7 @@ export function decode122(base122_) {
         if (illegalIndex < BASE122_ILLEGAL.length)
             push7(BASE122_ILLEGAL[illegalIndex]);
         else if (illegalIndex !== BASE122_SHORT)
-            throw new InsErr(`Invalid base-122 illegal index ${illegalIndex} at position ${i}`);
+            throw new Err(`Invalid base-122 illegal index ${illegalIndex} at position ${i}`);
         push7(code & 0b01111111);
     }
     return Uint8Array.from(out);

package/dist/dom.d.ts

@@ -1,8 +1,3 @@
-import * as bs from "./base.ts";
-/** Subclass of {@link bs.InsErr} that represents an error thrown from this specific module of the library */
-export declare class DomErr extends bs.InsErr {
-    name: string;
-}
 /**
  * Resolves on `DOMContentLoaded` or immediately if the document is already ready.
  */
@@ -19,7 +14,7 @@ export declare function byId<T extends HTMLElement>(id_: string, type_: new () =
  * Typed accessor for {@link document.getElementsByClassName}
  *
  * @param className_ - The class name of the elements to retrieve.
- * @param type_ - An optional constructor function for the expected element type.
+ * @param type_ - The constructor function for the expected element type.
  * @returns All elements with the specified class name and type.
  */
 export declare function byClass<T extends HTMLElement>(className_: string, type_: new () => T): T[];

package/dist/dom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,WAAW,CAAA;AAI/B,6GAA6G;AAC7G,qBAAa,MAAO,SAAQ,EAAE,CAAC,MAAM;IAAY,IAAI,SAA8B;CAAE;AAIrF;;GAEG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAI/C;AAID;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI,CAKrF;AAGD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAE1F;AAGD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAAE,IAAI,EAAE,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAEhG;AAID;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;IAC9C,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;CACrC,EAAE,KAAK,SAAM,GAAG,IAAI,CASpB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,IAAI,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMjD"}
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAI/C;AAID;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI,CAKrF;AAGD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAE1F;AAGD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAAE,IAAI,EAAE,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAEhG;AAID;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;IAC9C,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;CACrC,EAAE,KAAK,SAAM,GAAG,IAAI,CASpB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,IAAI,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMjD"}

package/dist/dom.js

@@ -1,8 +1,3 @@
-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 DomErr extends bs.InsErr {
-    name = "Instrumentality-DOM-Error";
-}
 /**
  * Resolves on `DOMContentLoaded` or immediately if the document is already ready.
  */
@@ -28,7 +23,7 @@ export function byId(id_, type_) {
  * Typed accessor for {@link document.getElementsByClassName}
  *
  * @param className_ - The class name of the elements to retrieve.
- * @param type_ - An optional constructor function for the expected element type.
+ * @param type_ - The constructor function for the expected element type.
  * @returns All elements with the specified class name and type.
  */
 export function byClass(className_, type_) {

package/dist/road.d.ts

@@ -1,19 +1,30 @@
-import * as fs from "node:fs";
 import * as cr from "node:crypto";
-import * as bs from "./base.ts";
-/** Subclass of {@link bs.InsErr} that represents an error thrown from this specific module of the library */
-export declare class RdErr extends bs.InsErr {
+import * as fs from "node:fs";
+import * as fp from "node:fs/promises";
+import { InsErr } from "./base.ts";
+/** Subclass of {@link InsErr} that represents an error thrown from this specific module of the library */
+export declare class Err extends InsErr {
     name: string;
 }
-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 Err}.
+ */
+export declare function resolveStat(statmode_: number): typeof File | typeof Folder | typeof BlockDevice | typeof CharacterDevice | typeof SymbolicLink | typeof Fifo | typeof Socket;
+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 file mode is unknown, throws a {@link RdErr}.
+ * @throws If the directory entry type is unknown, throws a {@link Err}.
  */
-export declare function resolveMode(statmode_: number): typeof File | typeof Folder | typeof BlockDevice | typeof CharacterDevice | typeof SymbolicLink | typeof Fifo | typeof Socket;
+export declare function resolveDirent(dirent: fs.Dirent): typeof File | typeof Folder | typeof BlockDevice | typeof CharacterDevice | typeof SymbolicLink | typeof Fifo | typeof Socket;
+export { resolveDirent as resDirent };
 /**
  * Creates the appropriate subclass of {@link Road} based on the file mode of the specified path.
  *
@@ -22,12 +33,14 @@ export declare function resolveMode(statmode_: number): typeof File | typeof Fol
  * @throws If {@link fp.lstat}/{@link fs.lstatSync} fails to retrieved the status of {@link path_}.
  */
 export declare function factory(path_: string): Promise<BlockDevice | CharacterDevice | Fifo | File | Folder | Socket | SymbolicLink>;
+export { factory as fac, factory as mk };
 /** Sync version of {@link factory}. */
 export declare function factorySync(path_: string): BlockDevice | CharacterDevice | Fifo | File | Folder | Socket | SymbolicLink;
+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.
@@ -62,25 +75,9 @@ export declare abstract 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.
-     */
-    constructor(path_: string, typeCheck_: boolean | 1 | 0);
-    /**
-     * 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).
+     * @throws If {@link typeCheck_} is true and the path does not correspond to the expected type of road, a {@link Err} will be thrown.
      */
-    protected lock(cb_?: () => void): Promise<AsyncDisposable & Disposable>;
-    /**
-     * 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.
-     */
-    protected lockSync(cb_?: () => void): Disposable & AsyncDisposable;
+    constructor(path_: string, typeCheck_: boolean);
     /** @returns An instance of {@link Folder} representing the parent directory of the current road. */
     parent(): Folder;
     /**
@@ -91,6 +88,11 @@ export declare abstract class Road {
     ancestorsIt(): Generator<Folder, void, unknown>;
     /** @returns An array of {@link Folder} instances representing the ancestors of the current road. */
     ancestors(): Folder[];
+    protected reserveLock(allowConcurrent: boolean): Disposable & {
+        previous: Promise<void> | undefined;
+    };
+    lock(): Promise<Disposable>;
+    lockSync(): Disposable;
     /**
      * Watches the current entry for changes and resolves when the entry becomes accessible (i.e., exists and can be accessed).
      *
@@ -114,18 +116,19 @@ export declare abstract class Road {
     lstat(): Promise<fs.Stats>;
     /** @returns The result of {@link fs.lstatSync} for the current entry. */
     lstatSync(): fs.Stats;
-    /** @returns The result of {@link fp.stat} for the current entry. */
-    stat(): Promise<fs.Stats>;
-    /** @returns The result of {@link fs.statSync} for the current entry. */
-    statSync(): fs.Stats;
-    abstract delete(): Promise<void>;
-    abstract deleteSync(): void;
-    abstract moveSync(into_: Folder): void;
-    abstract move(into_: Folder): Promise<void>;
-    abstract copySync(into_: Folder): this;
-    abstract copy(into_: Folder): Promise<this>;
-    abstract renameSync(to_: string): void;
-    abstract rename(to_: string): Promise<void>;
+    /** Get the size of the this entry in bytes. */
+    abstract size(): Promise<number>;
+    abstract sizeSync(): number;
+    /** Wrapper around {@link fp.rm} with locking. */
+    delete(): Promise<void>;
+    /** Wrapper around {@link fs.rmSync} with locking. */
+    deleteSync(): void;
+    copy(into_: Folder): Promise<this>;
+    copySync(into_: Folder): this;
+    move(into_: Folder): Promise<void>;
+    moveSync(into_: Folder): void;
+    rename(newName_: string): Promise<void>;
+    renameSync(newName_: string): void;
     abstract check(): Promise<boolean>;
     abstract checkSync(): boolean;
     /** Type narrowing for {@link File} (similar to `instanceof` without unnecessary runtime checks). */
@@ -136,10 +139,6 @@ export declare abstract class Road {
     isFolder(): this is Folder;
     /** Type narrowing for {@link Folder} (similar to `instanceof` without unnecessary runtime checks). */
     isDirectory(): this is Folder;
-    /** Type narrowing for {@link Folder} (similar to `instanceof` without unnecessary runtime checks). */
-    isDict(): this is Folder;
-    /** Type narrowing for {@link Folder} (similar to `instanceof` without unnecessary runtime checks). */
-    isDictionary(): this is Folder;
     /** Type narrowing for {@link SymbolicLink} (similar to `instanceof` without unnecessary runtime checks). */
     isSymlink(): this is SymbolicLink;
     /** Type narrowing for {@link SymbolicLink} (similar to `instanceof` without unnecessary runtime checks). */
@@ -155,48 +154,60 @@ export declare abstract class Road {
     /** Type narrowing for {@link Socket} (similar to `instanceof` without unnecessary runtime checks). */
     isSocket(): this is Socket;
 }
-export type road_t = ConstructorParameters<typeof Road>;
+/** Constructor type for a subclass of {@link Road}. */
+export type road_t<T extends Road> = new (...args_: ConstructorParameters<typeof Road>) => T;
 /** Subclass of {@link Road} that represents a file. */
 export declare class File extends Road {
-    static create(at_: string): Promise<File>;
+    /**
+     * 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 create(at_: string, data?: string | Buffer): Promise<File>;
+    /** Alias for {@link File.create}. */
     static readonly mk: typeof File.create;
-    static createSync(at_: string): File;
+    /** Synchronous version of {@link File.create}. */
+    static createSync(at_: string, data?: string | Buffer): File;
+    /** Alias for {@link File.createSync}. */
     static readonly mkSync: typeof File.createSync;
+    /** The file extension of this file, including the leading dot. */
     get ext(): string;
+    /** The file name without its extension. */
     get noExt(): string;
+    /**
+     * Reads the contents of the file.
+     *
+     * @returns A promise that resolves to the contents of the file as a `Buffer` or `string`, depending on the specified encoding.
+     * @throws If the file can't be read due to permission issues or other filesystem errors.
+     */
     read(): Promise<Buffer>;
-    read(encoding_: BufferEncoding, flag_?: string): Promise<string>;
+    read(options_: Parameters<typeof fp.readFile>[1]): Promise<string>;
     readSync(): Buffer;
-    readSync(encoding_: BufferEncoding, flag_?: string): string;
-    itBuff(chunkSize_?: number, flags_?: string | number, mode_?: fs.Mode): AsyncGenerator<Buffer<ArrayBuffer>, void, unknown>;
-    itBuffSync(chunkSize_?: number, flags_?: string | number, mode_?: fs.Mode): Generator<Buffer<ArrayBuffer>, void, unknown>;
+    readSync(options_: Parameters<typeof fs.readFileSync>[1]): string;
+    itBuff(options_?: fs.ReadStreamOptions): AsyncGenerator<Buffer>;
+    itBuffSync(chunkSize_?: number, flags_?: string | number, mode_?: fs.Mode): Generator<Buffer>;
+    sameAs(other_: File): Promise<boolean>;
+    sameAsSync(other_: File): boolean;
+    hash(algorithm_?: string, options_?: cr.HashOptions): Promise<Buffer>;
+    hash(algorithm_?: string, options_?: cr.HashOptions, encoding_?: BufferEncoding): Promise<string>;
+    hashSync(algorithm_?: string, options_?: cr.HashOptions): Buffer;
+    hashSync(algorithm_?: string, options_?: cr.HashOptions, encoding_?: BufferEncoding): string;
+    size(): Promise<number>;
+    sizeSync(): number;
+    writeAtomic(data_: Buffer | string, options_?: fs.WriteFileOptions): Promise<void>;
+    writeAtomicSync(data_: Buffer | string, options_?: fs.WriteFileOptions): void;
     write(data_: Buffer | string, options_?: fs.WriteFileOptions): Promise<void>;
     writeSync(data_: Buffer | string, options_?: fs.WriteFileOptions): void;
     append(data_: Buffer | string, options_?: fs.WriteFileOptions): Promise<void>;
     appendSync(data_: Buffer | string, options_?: fs.WriteFileOptions): void;
-    delete(): Promise<void>;
-    deleteSync(): void;
-    move(into_: Folder): Promise<void>;
-    moveSync(into_: Folder): void;
-    copy(into_: Folder): Promise<this>;
-    copySync(into_: Folder): this;
-    rename(to_: string): Promise<void>;
-    renameSync(to_: string): void;
     check(): Promise<boolean>;
     checkSync(): boolean;
     isFile(): this is File;
 }
-export declare function hash(f_: File, algorithm_?: string, options_?: cr.HashOptions): Promise<Buffer>;
-export declare function hash(f_: File, algorithm_?: string, options_?: cr.HashOptions, encoding_?: BufferEncoding): Promise<string>;
-export declare function hashSync(f_: File, algorithm_?: string, options_?: cr.HashOptions): Buffer;
-export declare function hashSync(f_: File, algorithm_?: string, options_?: cr.HashOptions, encoding_?: BufferEncoding): string;
-export declare function streamHash(f_: File, algorithm_?: string, options_?: cr.HashOptions): Promise<Buffer>;
-export declare function streamHash(f_: File, algorithm_?: string, options_?: cr.HashOptions, encoding_?: BufferEncoding): Promise<string>;
-export declare function streamHashSync(f_: File, algorithm_?: string, options_?: cr.HashOptions): Buffer;
-export declare function streamHashSync(f_: File, algorithm_?: string, options_?: cr.HashOptions, encoding_?: BufferEncoding): string;
-export declare function itLines(f_: File, options_?: fs.ReadStreamOptions): AsyncGenerator<string, void, unknown>;
-export declare function fileSameAs(f1_: File, f2_: File): Promise<boolean>;
-export declare function fileSameAsSync(f1_: File, f2_: File): boolean;
+/** Helper type for filtering {@link Road} instances. */
+export type filter_t<T extends Road> = ((road: Road) => road is T);
 export declare class Folder extends Road {
     static create(at_: string): Promise<Folder>;
     static readonly mk: typeof Folder.create;
@@ -204,38 +215,42 @@ export declare class Folder extends Road {
     static readonly mkSync: typeof Folder.createSync;
     join(...paths_: string[]): string;
     it(): AsyncIterable<Road>;
-    it<T extends Road>(expectedType_: new (..._: any[]) => T): AsyncIterable<T>;
+    it<T extends Road>(filter_: filter_t<T>): AsyncIterable<T>;
     itSync(): Iterable<Road>;
-    itSync<T extends Road>(expectedType_: new (..._: any[]) => T): Iterable<T>;
+    itSync<T extends Road>(filter_: filter_t<T>): Iterable<T>;
     list(): Promise<Road[]>;
-    list<T extends Road>(expectedType_: new (..._: any[]) => T): Promise<T[]>;
+    list<T extends Road>(filter_: filter_t<T>): Promise<T[]>;
     listSync(): Road[];
-    listSync<T extends Road>(expectedType_: new (..._: any[]) => T): T[];
+    listSync<T extends Road>(filter_: filter_t<T>): T[];
+    walk(): AsyncIterable<Road>;
+    walk<T extends Road>(filter_: filter_t<T>): AsyncIterable<T>;
+    walk(filter_: (r: Road) => boolean): AsyncIterable<Road>;
+    walkSync(): Iterable<Road>;
+    walkSync<T extends Road>(filter_: filter_t<T>): Iterable<T>;
+    walkSync(filter_: (r: Road) => boolean): Iterable<Road>;
     find(name_: string): Promise<Road | null>;
-    find<T extends Road>(name_: string, expectedType_: new (..._: any[]) => T): Promise<T | null>;
+    find<T extends Road>(name_: string, expect_: road_t<T>): Promise<T | null>;
     findSync(name_: string): Road | null;
-    findSync<T extends Road>(name_: string, expectedType_: new (..._: any[]) => T): T | null;
+    findSync<T extends Road>(name_: string, expect_: road_t<T>): T | null;
     add<T extends Road>(name_: string, createable_: {
-        create: (at: string) => Promise<T>;
+        mk: (at: string) => Promise<T>;
     }): Promise<T>;
     addSync<T extends Road>(name_: string, createable_: {
-        createSync: (at: string) => T;
+        mkSync: (at: string) => T;
     }): T;
-    delete(options_?: fs.RmOptions): Promise<void>;
-    deleteSync(options_?: fs.RmOptions): void;
-    move(into_: Folder): Promise<void>;
-    moveSync(into_: Folder): void;
-    copy(into_: Folder): Promise<this>;
-    copySync(into_: Folder): this;
-    rename(to_: string): Promise<void>;
-    renameSync(to_: string): void;
+    borrow<T extends Road>(createable_: {
+        mk: (at: string) => Promise<T>;
+    }, cb_: (r: T) => Promise<void> | void): Promise<void>;
+    borrowSync<T extends Road>(createable_: {
+        mkSync: (at: string) => T;
+    }, cb_: (r: T) => void): void;
+    size(): Promise<number>;
+    sizeSync(): number;
     check(): Promise<boolean>;
     checkSync(): boolean;
     isFolder(): this is Folder;
     isDir(): this is Folder;
     isDirectory(): this is Folder;
-    isDict(): this is Folder;
-    isDictionary(): this is Folder;
 }
 export declare function sysRoot(): Folder;
 export declare function home(): Folder;
@@ -251,14 +266,10 @@ export declare class SymbolicLink extends Road {
     targetSync(): BlockDevice | CharacterDevice | Fifo | File | Folder | Socket | SymbolicLink;
     retarget(to_: Road): Promise<void>;
     retargetSync(to_: Road): void;
+    size(): Promise<number>;
+    sizeSync(): number;
     delete(): Promise<void>;
     deleteSync(): void;
-    move(into_: Folder): Promise<void>;
-    moveSync(into_: Folder): void;
-    copy(into_: Folder): Promise<this>;
-    copySync(into_: Folder): this;
-    rename(to_: string): Promise<void>;
-    renameSync(to_: string): void;
     check(): Promise<boolean>;
     checkSync(): boolean;
     isSymlink(): this is SymbolicLink;
@@ -267,17 +278,28 @@ export declare class SymbolicLink extends Road {
 export { SymbolicLink as Symlink };
 export declare abstract class UnusableRoad extends Road {
     readonly mutable: boolean;
-    constructor(...args_: ConstructorParameters<typeof Road>);
+    size(): Promise<0>;
+    sizeSync(): 0;
     error(): never;
-    lock(): Promise<never>;
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be locked */
+    lock(): never;
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be locked */
     lockSync(): never;
-    delete(): Promise<never>;
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be deleted */
+    delete(): never;
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be deleted */
     deleteSync(): never;
-    move(): Promise<never>;
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be moved */
+    move(): never;
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be moved */
     moveSync(): never;
-    copy(): Promise<never>;
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be copied */
+    copy(): never;
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be copied */
     copySync(): never;
-    rename(): Promise<never>;
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be renamed */
+    rename(): never;
+    /** @deprecated System-level resources (UnusableRoad) can't/shouldn't be renamed */
     renameSync(): never;
     isUnusable(): this is UnusableRoad;
 }
@@ -301,8 +323,4 @@ export declare class Socket extends UnusableRoad {
     checkSync(): boolean;
     isSocket(): this is Socket;
 }
-export declare function registerToCleanup(self_: Road): void;
-export declare function Temp<T extends Road>(createable_: {
-    createSync: (at: string) => T;
-}, autoCleanup_: boolean): T & Disposable & AsyncDisposable;
 //# sourceMappingURL=road.d.ts.map