instrumentality 0.0.8 → 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?

package/dist/road.d.ts

@@ -1,5 +1,6 @@
 import * as cr from "node:crypto";
 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 {
@@ -87,23 +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[];
-    /**
-     * 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.
-     *
-     * @returns An object with a dispose method that releases the lock when called.
-     * @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 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.
-     */
-    protected lock(): Promise<Disposable & AsyncDisposable>;
-    /**
-     * Sync version of {@link lock}.
-     * @throws 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(): Disposable & AsyncDisposable;
+    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).
      *
@@ -134,8 +123,8 @@ export declare abstract class Road {
     delete(): Promise<void>;
     /** Wrapper around {@link fs.rmSync} with locking. */
     deleteSync(): void;
-    copy(into_: Folder, options_?: fs.CopyOptions): Promise<this>;
-    copySync(into_: Folder, options_?: fs.CopySyncOptions): this;
+    copy(into_: Folder): Promise<this>;
+    copySync(into_: Folder): this;
     move(into_: Folder): Promise<void>;
     moveSync(into_: Folder): void;
     rename(newName_: string): Promise<void>;
@@ -176,11 +165,11 @@ export declare class File extends Road {
      * @returns A promise that resolves to the newly created `File` instance.
      * @throws if {@link fp.writeFile} throws.
      */
-    static create(at_: string): Promise<File>;
+    static create(at_: string, data?: string | Buffer): Promise<File>;
     /** Alias for {@link File.create}. */
     static readonly mk: typeof File.create;
     /** Synchronous version of {@link File.create}. */
-    static createSync(at_: string): File;
+    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. */
@@ -194,15 +183,13 @@ export declare class File extends Road {
      * @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;
+    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;
-    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>;
-    itLines(chunkSize_?: number, flags_?: string | number, mode_?: fs.Mode): AsyncGenerator<string, void, unknown>;
-    itLinesSync(chunkSize_?: number, flags_?: string | number, mode_?: fs.Mode): Generator<string, void, unknown>;
     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;
@@ -246,11 +233,17 @@ export declare class Folder extends Road {
     findSync(name_: string): Road | 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;
+    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>;
@@ -330,17 +323,4 @@ export declare class Socket extends UnusableRoad {
     checkSync(): boolean;
     isSocket(): this is Socket;
 }
-export declare function Temp<T extends Road>(createable_: {
-    create: (at: string) => Promise<T>;
-}): Promise<T & Disposable & AsyncDisposable>;
-export declare function TempSync<T extends Road>(createable_: {
-    createSync: (at: string) => T;
-}): T & Disposable & AsyncDisposable;
-export declare function registerToCleanup(self_: Road): void;
-export declare function AutoTemp<T extends Road>(createable_: {
-    mk: (at: string) => Promise<T>;
-}): Promise<T & Disposable & AsyncDisposable>;
-export declare function AutoTempSync<T extends Road>(createable_: {
-    mk: (at: string) => T;
-}, autoCleanup_: boolean): T & Disposable & AsyncDisposable;
 //# sourceMappingURL=road.d.ts.map

package/dist/road.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"road.d.ts","sourceRoot":"","sources":["../src/road.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"road.d.ts","sourceRoot":"","sources":["../src/road.ts"],"names":[],"mappings":"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"}

package/dist/road.js

@@ -137,52 +137,35 @@ export class Road {
     }
     /** @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.
-     *
-     * @returns An object with a dispose method that releases the lock when called.
-     * @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 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() {
+    reserveLock(allowConcurrent) {
         if (!this.mutable)
             throw new Err(`Road to '${this.isAt}' is immutable.`);
         lockedRoads ??= new Map();
         const { promise, resolve } = Promise.withResolvers();
+        const isAt = this.isAt;
         const previous = lockedRoads.get(this.isAt);
+        if (!allowConcurrent && previous)
+            throw new Err(`Road to '${this.isAt}' is already locked.`);
         lockedRoads.set(this.isAt, promise);
-        const isAt = this.isAt;
-        const dispose = () => {
-            resolve();
-            if (lockedRoads.get(isAt) === promise)
-                lockedRoads.delete(isAt);
+        return {
+            [Symbol.dispose]: () => {
+                resolve();
+                if (lockedRoads.get(isAt) === promise)
+                    lockedRoads.delete(isAt);
+            },
+            previous,
         };
-        await previous;
-        return { [Symbol.dispose]: dispose, [Symbol.asyncDispose]: dispose };
     }
-    /**
-     * Sync version of {@link lock}.
-     * @throws If the road is currently locked by another operation as it cannot wait for the lock to be released in a synchronous context.
-     */
+    async lock() {
+        const l = this.reserveLock(true);
+        try {
+            await l.previous;
+        }
+        catch { }
+        return l;
+    }
     lockSync() {
-        if (!this.mutable)
-            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;
-        const dispose = () => {
-            resolve();
-            if (lockedRoads.get(isAt) === promise)
-                lockedRoads.delete(isAt);
-        };
-        return { [Symbol.dispose]: dispose, [Symbol.asyncDispose]: dispose };
+        return this.reserveLock(false);
     }
     /**
      * Watches the current entry for changes and resolves when the entry becomes accessible (i.e., exists and can be accessed).
@@ -249,14 +232,14 @@ export class Road {
         using _ = this.lockSync();
         fs.rmSync(this.isAt, { recursive: true, force: true });
     }
-    async copy(into_, options_) {
+    async copy(into_) {
         const newPath = into_.join(this.name);
-        await fp.cp(this.isAt, newPath, { recursive: true, ...options_ });
+        await fp.cp(this.isAt, newPath, { recursive: true, force: true });
         return new this.constructor(newPath, false);
     }
-    copySync(into_, options_) {
+    copySync(into_) {
         const newPath = into_.join(this.name);
-        fs.cpSync(this.isAt, newPath, { recursive: true, ...options_ });
+        fs.cpSync(this.isAt, newPath, { recursive: true, force: true });
         return new this.constructor(newPath, false);
     }
     async move(into_) {
@@ -315,24 +298,24 @@ export class File extends Road {
      * @returns A promise that resolves to the newly created `File` instance.
      * @throws if {@link fp.writeFile} throws.
      */
-    static async create(at_) {
+    static async create(at_, data = "") {
         try {
             await fp.access(at_, fsc.W_OK);
         }
         catch {
-            await fp.writeFile(at_, "");
+            await fp.writeFile(at_, data);
         }
         return new File(at_, true);
     }
     /** Alias for {@link File.create}. */
     static mk = File.create;
     /** Synchronous version of {@link File.create}. */
-    static createSync(at_) {
+    static createSync(at_, data = "") {
         try {
             fs.accessSync(at_, fs.constants.W_OK);
         }
         catch {
-            fs.writeFileSync(at_, "");
+            fs.writeFileSync(at_, data);
         }
         return new File(at_, true);
     }
@@ -342,66 +325,21 @@ export class File extends Road {
     get ext() { return ph.extname(this.isAt); }
     /** The file name without its extension. */
     get noExt() { return ph.basename(this.isAt, this.ext); }
-    async read(encoding_, flag_) {
-        if (encoding_)
-            return fp.readFile(this.isAt, { encoding: encoding_, flag: flag_ });
-        else
-            return fp.readFile(this.isAt);
-    }
-    readSync(encoding_, flag_) {
-        if (encoding_)
-            return fs.readFileSync(this.isAt, { encoding: encoding_, flag: flag_ });
-        else
-            return fs.readFileSync(this.isAt);
+    async read(options_) {
+        return fp.readFile(this.isAt, options_);
     }
-    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;
-        }
+    readSync(options_) {
+        return fs.readFileSync(this.isAt, options_);
     }
-    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_);
+    async *itBuff(options_) {
+        const stream = fs.createReadStream(this.isAt, { ...options_, encoding: undefined });
         try {
-            const buffer = Buffer.alloc(chunkSize_);
-            let bytesRead;
-            do {
-                bytesRead = (await fd.read(buffer, 0, chunkSize_, null)).bytesRead;
-                if (bytesRead > 0)
-                    yield Buffer.from(buffer.subarray(0, bytesRead));
-            } while (bytesRead === chunkSize_);
+            for await (const chunk of stream)
+                yield chunk;
         }
         finally {
-            await fd.close();
+            if (!stream.destroyed)
+                stream.destroy();
         }
     }
     *itBuffSync(chunkSize_ = 64 * 1024, flags_ = 'r', mode_) {
@@ -419,37 +357,63 @@ export class File extends Road {
             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);
+    async sameAs(other_) {
+        if (this.isAt === other_.isAt)
+            return true;
+        const [s1, s2] = await Promise.all([this.size(), other_.size()]);
+        if (s1 !== s2)
+            return false;
+        if (s1 === 0)
+            return true;
+        const iter1 = this.itBuff();
+        const iter2 = other_.itBuff();
+        try {
+            while (true) {
+                const [a, b] = await Promise.all([iter1.next(), iter2.next()]);
+                if (a.done && b.done)
+                    return true;
+                if (a.done !== b.done)
+                    return false;
+                if (!a.value.equals(b.value))
+                    return false;
+            }
+        }
+        finally {
+            await Promise.all([iter1.return?.(undefined), iter2.return?.(undefined)]);
+        }
+    }
+    sameAsSync(other_) {
+        if (this.isAt === other_.isAt)
+            return true;
+        const [s1, s2] = [this.sizeSync(), other_.sizeSync()];
+        if (s1 !== s2)
+            return false;
+        if (s1 === 0)
+            return true;
+        const iter1 = this.itBuffSync();
+        const iter2 = other_.itBuffSync();
+        try {
+            while (true) {
+                const a = iter1.next();
+                const b = iter2.next();
+                if (a.done && b.done)
+                    return true;
+                if (a.done !== b.done)
+                    return false;
+                if (!a.value.equals(b.value))
+                    return false;
             }
         }
-        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);
+        finally {
+            try {
+                iter1.return?.(undefined);
             }
+            catch { }
+            try {
+                iter2.return?.(undefined);
+            }
+            catch { }
         }
-        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_);
@@ -467,17 +431,19 @@ export class File extends Road {
     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
+        await this.parent().borrow(File, async (tmp) => {
+            using _ = await tmp.lock();
+            await fp.writeFile(tmp.isAt, data_, options_);
+            await fp.rename(tmp.isAt, this.isAt);
+        });
     }
     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
+        this.parent().borrowSync(File, tmp => {
+            using _ = tmp.lockSync();
+            fs.writeFileSync(tmp.isAt, data_, options_);
+            fs.renameSync(tmp.isAt, this.isAt);
+        });
     }
     async write(data_, options_) {
         using _ = await this.lock();
@@ -549,16 +515,11 @@ export class Folder extends Road {
     }
     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 (!filter_)
-            return resolvedEntries;
-        return resolvedEntries.filter(entry => filter_(entry));
+        return filter_ ? entries.filter(entry => filter_(entry)) : entries;
     }
     listSync(filter_) {
         const entries = fs.readdirSync(this.isAt, { withFileTypes: true }).map(e => new (resolveDirent(e))(this.join(e.name), false));
-        if (!filter_)
-            return entries;
-        return entries.filter(entry => filter_(entry));
+        return filter_ ? entries.filter(entry => filter_(entry)) : entries;
     }
     async *walk(filter_) {
         for await (const entry of this.it()) {
@@ -604,14 +565,32 @@ export class Folder extends Road {
     }
     async add(name_, createable_) {
         const newPath = this.join(name_);
-        await createable_.create(newPath);
+        await createable_.mk(newPath);
         return (await factory(newPath));
     }
     addSync(name_, createable_) {
         const newPath = this.join(name_);
-        createable_.createSync(newPath);
+        createable_.mkSync(newPath);
         return factorySync(newPath);
     }
+    async borrow(createable_, cb_) {
+        const path = this.join(`instrumentality@${crypto.randomUUID()}`);
+        try {
+            await cb_(await createable_.mk(path));
+        }
+        finally {
+            await fp.rm(path, { recursive: true, force: true });
+        }
+    }
+    borrowSync(createable_, cb_) {
+        const path = this.join(`instrumentality@${crypto.randomUUID()}`);
+        try {
+            cb_(createable_.mkSync(path));
+        }
+        finally {
+            fs.rmSync(path, { recursive: true, force: true });
+        }
+    }
     async size() {
         let size = 0;
         for await (const entry of this.it())
@@ -708,7 +687,6 @@ export class SymbolicLink extends Road {
     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)
     async size() { return 0; }
@@ -796,90 +774,3 @@ export class Socket extends UnusableRoad {
     } }
     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;
-/**
- * Forcefully cleans up all files and folders registered for cleanup on exit.
- */
-function forceCleanupToDelete() {
-    for (const path of toDelete ?? [])
-        try {
-            fs.rmSync(path, { force: true, recursive: true });
-        }
-        catch { }
-    toDelete?.clear();
-    toDelete = null;
-    finalizer = null;
-    if (exitHandlerRegistered)
-        process.off('exit', forceCleanupToDelete);
-    exitHandlerRegistered = false;
-}
-export function registerToCleanup(self_) {
-    finalizer ??= new FinalizationRegistry(p => { try {
-        fs.rmSync(p, { force: true, recursive: true });
-    }
-    catch { } ; toDelete?.delete(p); });
-    toDelete ??= new Set();
-    if (!exitHandlerRegistered) {
-        process.once('exit', forceCleanupToDelete);
-        exitHandlerRegistered = true;
-    }
-    toDelete.add(self_.isAt);
-    finalizer.register(self_, self_.isAt, self_);
-}
-export 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, {
-        [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); }
-    }));
-}

package/package.json

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

package/src/road.ts

@@ -112,7 +112,7 @@ export abstract class Road {
   /** 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). */
   get depth() { return this.isAt.split(ph.sep).length - 1 }
   /** Same as {@link isAt} but for compatibility with external APIs. */
-  toString() { return this.isAt }
+  toString(): string { return this.isAt }
 
   /**
    * Creates a new instance of the Road class.
@@ -147,52 +147,32 @@ export abstract class Road {
   /** @returns An array of {@link Folder} instances representing the ancestors of the current road. */
   ancestors(): Folder[] { 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.
-   * 
-   * @returns An object with a dispose method that releases the lock when called.
-   * @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 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.
-   */
-  protected async lock(): Promise<Disposable & AsyncDisposable> {
+  protected reserveLock(allowConcurrent: boolean): Disposable & { previous: Promise<void> | undefined } {
     if (!this.mutable)
       throw new Err(`Road to '${this.isAt}' is immutable.`)
     lockedRoads ??= new Map()
     const { promise, resolve } = Promise.withResolvers<void>()
-    const previous = lockedRoads.get(this.isAt)
-    lockedRoads.set(this.isAt, promise)
     const isAt = this.isAt
-    const dispose = () => {
-      resolve()
-      if (lockedRoads!.get(isAt) === promise)
-        lockedRoads!.delete(isAt)
-    }
-    await previous
-    return { [Symbol.dispose]: dispose, [Symbol.asyncDispose]: dispose as any }
-  }
-  /**
-   * Sync version of {@link lock}.
-   * @throws 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(): Disposable & AsyncDisposable {
-    if (!this.mutable)
-      throw new Err(`Road to '${this.isAt}' is immutable.`)
-    lockedRoads ??= new Map()
-    const { promise, resolve } = Promise.withResolvers<void>()
-    if (lockedRoads.has(this.isAt))
+    const previous = lockedRoads.get(this.isAt)
+    if (!allowConcurrent && previous)
       throw new Err(`Road to '${this.isAt}' is already locked.`)
     lockedRoads.set(this.isAt, promise)
-    const isAt = this.isAt
-    const dispose = () => {
-      resolve()
-      if (lockedRoads!.get(isAt) === promise)
-        lockedRoads!.delete(isAt)
+    return {
+      [Symbol.dispose]: () => {
+        resolve()
+        if (lockedRoads!.get(isAt) === promise)
+          lockedRoads!.delete(isAt)
+      },
+      previous,
     }
-    return { [Symbol.dispose]: dispose, [Symbol.asyncDispose]: dispose as any }
+  }
+  async lock(): Promise<Disposable> {
+    const l = this.reserveLock(true)
+    try { await l.previous } catch {}
+    return l
+  }
+  lockSync(): Disposable {
+    return this.reserveLock(false)
   }
 
   /**
@@ -256,14 +236,14 @@ export abstract class Road {
     using _ = this.lockSync()
     fs.rmSync(this.isAt, { recursive: true, force: true })
   }
-  async copy(into_: Folder, options_?: fs.CopyOptions): Promise<this> {
+  async copy(into_: Folder): Promise<this> {
     const newPath = into_.join(this.name)
-    await fp.cp(this.isAt, newPath, { recursive: true, ...options_ })
+    await fp.cp(this.isAt, newPath, { recursive: true, force: true })
     return new (this.constructor as new (path: string, typeCheck: boolean) => this)(newPath, false)
   }
-  copySync(into_: Folder, options_?: fs.CopySyncOptions): this {
+  copySync(into_: Folder): this {
     const newPath = into_.join(this.name)
-    fs.cpSync(this.isAt, newPath, { recursive: true, ...options_ })
+    fs.cpSync(this.isAt, newPath, { recursive: true, force: true })
     return new (this.constructor as new (path: string, typeCheck: boolean) => this)(newPath, false)
   }
   async move(into_: Folder): Promise<void> {
@@ -291,7 +271,6 @@ export abstract class Road {
     this.pointsTo = newPath
   }
 
-
   // jsdocs for the abstract methods are in the subclasses
   abstract check(): Promise<boolean>
   abstract checkSync(): boolean
@@ -333,17 +312,17 @@ export class File extends Road {
    * @returns A promise that resolves to the newly created `File` instance.
    * @throws if {@link fp.writeFile} throws.
    */
-  static async create(at_: string) {
+  static async create(at_: string, data: string | Buffer = "") {
     try { await fp.access(at_, fsc.W_OK) }
-    catch { await fp.writeFile(at_, "") }
+    catch { await fp.writeFile(at_, data) }
     return new File(at_, true)
   }
   /** Alias for {@link File.create}. */
   static readonly mk: typeof File.create = File.create
   /** Synchronous version of {@link File.create}. */
-  static createSync(at_: string) {
+  static createSync(at_: string, data: string | Buffer = "") {
     try { fs.accessSync(at_, fs.constants.W_OK) }
-    catch { fs.writeFileSync(at_, "") }
+    catch { fs.writeFileSync(at_, data) }
     return new File(at_, true)
   }
   /** Alias for {@link File.createSync}. */
@@ -361,67 +340,25 @@ export class File extends Road {
    * @throws If the file can't be read due to permission issues or other filesystem errors.
    */
   async read(): Promise<Buffer>
-  async read(encoding_: BufferEncoding, flag_?: string): Promise<string>
-  async read(encoding_?: BufferEncoding, flag_?: string): Promise<Buffer | string> {
-    if (encoding_)
-      return fp.readFile(this.isAt, { encoding: encoding_, flag: flag_ })
-    else
-      return fp.readFile(this.isAt)
+  async read(options_: Parameters<typeof fp.readFile>[1]): Promise<string>
+  async read(options_?: Parameters<typeof fp.readFile>[1]): Promise<Buffer | string> {
+    return fp.readFile(this.isAt, options_!)
   }
   readSync(): Buffer
-  readSync(encoding_: BufferEncoding, flag_?: string): string
-  readSync(encoding_?: BufferEncoding, flag_?: string): Buffer | string {
-    if (encoding_)
-      return fs.readFileSync(this.isAt, { encoding: encoding_, flag: flag_ })
-    else
-      return fs.readFileSync(this.isAt)
+  readSync(options_: Parameters<typeof fs.readFileSync>[1]): string
+  readSync(options_?: Parameters<typeof fs.readFileSync>[1]): Buffer | string {
+    return fs.readFileSync(this.isAt, options_!)
   }
 
-  async sameAs(other_: File): Promise<boolean> {
-    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_: File): boolean {
-    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_: number = 64 * 1024, flags_: string | number = 'r', mode_?: fs.Mode) {
-    const fd = await fp.open(this.isAt, flags_, mode_)
+  async *itBuff(options_?: fs.ReadStreamOptions): AsyncGenerator<Buffer> {
+    const stream = fs.createReadStream(this.isAt, { ...options_, encoding: undefined })
     try {
-      const buffer = Buffer.alloc(chunkSize_)
-      let bytesRead: number
-      do {
-        bytesRead = (await fd.read(buffer, 0, chunkSize_, null)).bytesRead
-        if (bytesRead > 0)
-          yield Buffer.from(buffer.subarray(0, bytesRead))
-      } while (bytesRead === chunkSize_)
-    } finally {
-      await fd.close()
+      for await (const chunk of stream)
+        yield chunk
     }
+    finally { if (!stream.destroyed) stream.destroy() }
   }
-  *itBuffSync(chunkSize_: number = 64 * 1024, flags_: string | number = 'r', mode_?: fs.Mode) {
+  *itBuffSync(chunkSize_: number = 64 * 1024, flags_: string | number = 'r', mode_?: fs.Mode): Generator<Buffer> {
     const fd = fs.openSync(this.isAt, flags_, mode_)
     try {
       const buffer = Buffer.alloc(chunkSize_)
@@ -431,43 +368,47 @@ export class File extends Road {
         if (bytesRead > 0)
           yield Buffer.from(buffer.subarray(0, bytesRead))
       } while (bytesRead === chunkSize_)
-    } finally {
-      fs.closeSync(fd)
     }
+    finally { fs.closeSync(fd) }
   }
-  async *itLines(chunkSize_: number = 64 * 1024, flags_: string | number = 'r', mode_?: fs.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: number
-      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)
+
+  async sameAs(other_: File): Promise<boolean> {
+    if (this.isAt === other_.isAt) return true
+    const [s1, s2] = await Promise.all([this.size(), other_.size()])
+    if (s1 !== s2) return false
+    if (s1 === 0) return true
+    const iter1 = this.itBuff()
+    const iter2 = other_.itBuff()
+    try {
+      while (true) {
+        const [a, b] = await Promise.all([iter1.next(), iter2.next()])
+        if (a.done && b.done) return true
+        if (a.done !== b.done) return false
+        if (!a.value.equals(b.value)) return false
       }
     }
-    carry += decoder.decode()
-    if (carry.length > 0)
-      yield carry.endsWith("\r") ? carry.slice(0, -1) : carry
-  }
-  *itLinesSync(chunkSize_: number = 64 * 1024, flags_: string | number = 'r', mode_?: fs.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: number
-      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)
+    finally { await Promise.all([iter1.return?.(undefined), iter2.return?.(undefined)]) }
+  }
+  sameAsSync(other_: File): boolean {
+    if (this.isAt === other_.isAt) return true
+    const [s1, s2] = [this.sizeSync(), other_.sizeSync()]
+    if (s1 !== s2) return false
+    if (s1 === 0) return true
+    const iter1 = this.itBuffSync()
+    const iter2 = other_.itBuffSync()
+    try {
+      while (true) {
+        const a = iter1.next()
+        const b = iter2.next()
+        if (a.done && b.done) return true
+        if (a.done !== b.done) return false
+        if (!a.value!.equals(b.value!)) return false
       }
     }
-    carry += decoder.decode()
-    if (carry.length > 0)
-      yield carry.endsWith("\r") ? carry.slice(0, -1) : carry
+    finally {
+      try { iter1.return?.(undefined) } catch {}
+      try { iter2.return?.(undefined) } catch {}
+    }
   }
 
   async hash(algorithm_?: string, options_?: cr.HashOptions): Promise<Buffer>
@@ -492,17 +433,19 @@ export class File extends Road {
 
   async writeAtomic(data_: Buffer | string, options_?: fs.WriteFileOptions) {
     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
+    await this.parent().borrow(File, async tmp => {
+      using _ = await tmp.lock()
+      await fp.writeFile(tmp.isAt, data_, options_)
+      await fp.rename(tmp.isAt, this.isAt)
+    })
   }
   writeAtomicSync(data_: Buffer | string, options_?: fs.WriteFileOptions) {
     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
+    this.parent().borrowSync(File, tmp => {
+      using _ = tmp.lockSync()
+      fs.writeFileSync(tmp.isAt, data_, options_)
+      fs.renameSync(tmp.isAt, this.isAt)
+    })
   }
 
   async write(data_: Buffer | string, options_?: fs.WriteFileOptions) {
@@ -574,18 +517,13 @@ export class Folder extends Road {
   async list<T extends Road>(filter_: filter_t<T>): Promise<T[]>
   async list<T extends Road>(filter_?: filter_t<T>): Promise<Road[] | T[]> {
     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 (!filter_)
-      return resolvedEntries
-    return resolvedEntries.filter(entry => filter_(entry))
+    return filter_ ? entries.filter(entry => filter_(entry)) : entries
   }
   listSync(): Road[]
   listSync<T extends Road>(filter_: filter_t<T>): T[]
   listSync<T extends Road>(filter_?: filter_t<T>): Road[] | T[] {
     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 => filter_(entry))
+    return filter_ ? entries.filter(entry => filter_(entry)) : entries
   }
 
   walk(): AsyncIterable<Road>
@@ -623,9 +561,8 @@ export class Folder extends Road {
       if (found instanceof expect_)
         return found as T
       return null
-    } catch {
-      return null
     }
+    catch { return null }
   }
   findSync(name_: string): Road | null
   findSync<T extends Road>(name_: string, expect_: road_t<T>): T | null
@@ -637,22 +574,32 @@ export class Folder extends Road {
       if (found instanceof expect_)
         return found as T
       return null
-    } catch(e: unknown) {
-      return null
     }
+    catch(e: unknown) { return null }
   }
 
-  async add<T extends Road>(name_: string, createable_: { create: (at: string) => Promise<T> }): Promise<T> {
+  async add<T extends Road>(name_: string, createable_: { mk: (at: string) => Promise<T> }): Promise<T> {
     const newPath = this.join(name_)
-    await createable_.create(newPath)
+    await createable_.mk(newPath)
     return (await factory(newPath)) as unknown as T
   }
-  addSync<T extends Road>(name_: string, createable_: { createSync: (at: string) => T }): T {
+  addSync<T extends Road>(name_: string, createable_: { mkSync: (at: string) => T }): T {
     const newPath = this.join(name_)
-    createable_.createSync(newPath)
+    createable_.mkSync(newPath)
     return factorySync(newPath) as unknown as T
   }
 
+  async borrow<T extends Road>(createable_: { mk: (at: string) => Promise<T> }, cb_: (r: T) => Promise<void> | void): Promise<void> {
+    const path = this.join(`instrumentality@${crypto.randomUUID()}`)
+    try { await cb_(await createable_.mk(path)) }
+    finally { await fp.rm(path, { recursive: true, force: true }) }
+  }
+  borrowSync<T extends Road>(createable_: { mkSync: (at: string) => T }, cb_: (r: T) => void): void {
+    const path = this.join(`instrumentality@${crypto.randomUUID()}`)
+    try { cb_(createable_.mkSync(path)) }
+    finally { fs.rmSync(path, { recursive: true, force: true }) }
+  }
+
   async size(): Promise<number> {
     let size = 0
     for await (const entry of this.it())
@@ -733,7 +680,6 @@ export class SymbolicLink extends Road {
   override isSymbolicLink(): this is SymbolicLink { return true as const }
 }
 export { SymbolicLink as Symlink }
-here().walk(r => !r.isSymlink())
 
 
 
@@ -784,68 +730,4 @@ export class Socket extends UnusableRoad {
   async check(): Promise<boolean> { try { return (await fp.lstat(this.isAt)).isSocket() } catch { return false } }
   checkSync(): boolean { try { return fs.lstatSync(this.isAt).isSocket() } catch { return false } }
   override isSocket(): this is Socket { return true as const }
-}
-
-
-
-export async function Temp<T extends Road>(createable_: { create: (at: string) => Promise<T> }): Promise<T & Disposable & AsyncDisposable> {
-  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<T extends Road>(createable_: { createSync: (at: string) => T }): T & Disposable & AsyncDisposable {
-  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: FinalizationRegistry<string> | null = null
-let toDelete: Set<string> | null = null
-let exitHandlerRegistered: boolean | null = null
-/**
- * Forcefully cleans up all files and folders registered for cleanup on exit.
- */
-function forceCleanupToDelete() {
-  for (const path of toDelete ?? [])
-    try { fs.rmSync(path, { force: true, recursive: true }) } catch {}
-  toDelete?.clear()
-  toDelete = null
-  finalizer = null
-  if (exitHandlerRegistered)
-    process.off('exit', forceCleanupToDelete)
-  exitHandlerRegistered = false
-}
-export function registerToCleanup(self_: Road) {
-  finalizer ??= new FinalizationRegistry<string>(p => { try { fs.rmSync(p, { force: true, recursive: true }) } catch {}; toDelete?.delete(p) })
-  toDelete ??= new Set()
-  if (!exitHandlerRegistered) {
-    process.once('exit', forceCleanupToDelete)
-    exitHandlerRegistered = true
-  }
-  toDelete.add(self_.isAt)
-  finalizer.register(self_, self_.isAt, self_)
-}
-
-
-export async function AutoTemp<T extends Road>(createable_: { mk: (at: string) => Promise<T> }): Promise<T & Disposable & AsyncDisposable> {
-  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<T extends Road>(createable_: { mk: (at: string) => T }, autoCleanup_: boolean): T & Disposable & AsyncDisposable {
-  let t = createable_.mk(tmp().join(`instrumentality@${cr.randomUUID()}`))
-  if (autoCleanup_)
-    registerToCleanup(t)
-  return Object.freeze(Object.assign(t, {
-    [Symbol.dispose]() { try { t.deleteSync() } catch {} toDelete?.delete(t.isAt); finalizer?.unregister(t) },
-    async [Symbol.asyncDispose]() { try { await t.delete() } catch {} toDelete?.delete(t.isAt); finalizer?.unregister(t) }
-  }))
 }