@procedures/fs 0.27.2 → 0.27.4

package/dist/files/atomic.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The atomic write of a file (roadmap O51).
+ *
+ * `writeFileAtomic()` writes the data to a new temporary file in the folder of the target. Then it
+ * renames the temporary file over the target. Thus a reader sees the old file or the whole new
+ * file, also after a crash.
+ */
+/** The options of `writeFileAtomic()`. */
+export interface WriteFileAtomicOptions {
+    /** The encoding of a string `data`. The default is `utf8`. */
+    encoding?: BufferEncoding | undefined;
+    /**
+     * The permissions of the file. Without it, the file keeps the permissions of the target. A new
+     * file gets `0o666` less the umask.
+     */
+    mode?: number | undefined;
+    /** With `false`, the function does not flush the file and its folder to the disk. The default is `true`. */
+    fsync?: boolean | undefined;
+    /**
+     * The time in milliseconds to try a rename again after `EPERM`, `EACCES` or `EBUSY`. The default
+     * is 2000 on Windows and 0 on the other platforms.
+     */
+    renameRetryMs?: number | undefined;
+}
+/**
+ * This function writes `data` to `path` in one step for each reader. A reader sees the old file or
+ * the whole new file. It does not see a part of a file at any time.
+ *
+ * - The function writes a new temporary file in the folder of the target and flushes it to the disk.
+ * - Then it renames the temporary file over the target and flushes the folder. Windows gets no flush of the folder.
+ * - On Windows, an open handle of the target blocks the rename. Then the function tries the rename again for `renameRetryMs`.
+ * - After a failure, the function removes the temporary file and throws the error.
+ * - The file keeps the permissions of the target, unless `options.mode` is set. It does not keep the owner.
+ * - When `path` is a symlink, the function replaces the target of the link.
+ *
+ * Two writes at the same time do not mix: the file gets the data of one of them. The folder must exist.
+ */
+export declare function writeFileAtomic(path: string, data: string | Uint8Array, options?: WriteFileAtomicOptions): Promise<void>;
+//# sourceMappingURL=atomic.d.ts.map

package/dist/files/atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../../src/files/atomic.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,0CAA0C;AAC1C,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,4GAA4G;IAC5G,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAuGD;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CA6Bf"}

package/dist/files/atomic.js

@@ -0,0 +1,164 @@
+/**
+ * The atomic write of a file (roadmap O51).
+ *
+ * `writeFileAtomic()` writes the data to a new temporary file in the folder of the target. Then it
+ * renames the temporary file over the target. Thus a reader sees the old file or the whole new
+ * file, also after a crash.
+ */
+import { randomBytes } from "node:crypto";
+import { chmod, open, realpath, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+/** On Windows, an antivirus or an indexer that holds the target open gives these errors for a short time. */
+const LOCKED = new Set(["EPERM", "EACCES", "EBUSY"]);
+/** A file system that cannot flush a folder gives these errors. The write is complete without the flush. */
+const NO_FOLDER_SYNC = new Set(["EINVAL", "ENOTSUP", "EISDIR", "EBADF", "EPERM", "EACCES"]);
+/** True on Windows. The function reads the platform at each call, so a test can change it. */
+function isWindows() {
+    return process.platform === "win32";
+}
+/** The code of a Node.js error, or an empty string. */
+function codeOf(error) {
+    return error?.code ?? "";
+}
+/** True for the error of a path that does not exist. */
+function isMissing(error) {
+    const code = codeOf(error);
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/** The absolute path of the file to replace. The function follows a symlink, so the link stays a link. */
+async function targetOf(path) {
+    const absolute = resolve(path);
+    try {
+        return await realpath(absolute);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return absolute;
+        throw error;
+    }
+}
+/** The permission bits of the target, or undefined when the target does not exist. */
+async function modeOf(target) {
+    try {
+        return (await stat(target)).mode & 0o7777;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * A new path next to the target. The name starts with a dot and ends in `.tmp`, so a reader that
+ * looks for the extension of the target does not see it. The name keeps 32 characters of the
+ * target, so it does not become too long.
+ */
+function tempPathOf(target) {
+    const name = [...basename(target)].slice(0, 32).join("");
+    return join(dirname(target), `.${name}.${randomBytes(8).toString("hex")}.tmp`);
+}
+/**
+ * The rename, tried again with a longer wait each time until `retryMs` is over. A random part of
+ * each wait keeps two writers of one target out of step.
+ */
+async function renameWithRetry(from, to, retryMs) {
+    const deadline = Date.now() + retryMs;
+    for (let step = 10;; step = Math.min(step * 2, 100)) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (error) {
+            const delay = Math.round(step * (0.5 + Math.random()));
+            if (!LOCKED.has(codeOf(error)) || Date.now() + delay > deadline)
+                throw error;
+            await sleep(delay);
+        }
+    }
+}
+/** The removal of the temporary file after a failure. The original error is more important than an error here. */
+async function removeTemp(temp) {
+    try {
+        await unlink(temp);
+    }
+    catch (error) {
+        if (codeOf(error) !== "EPERM")
+            return;
+        // Windows does not remove a read-only file, so the function clears the flag and tries again
+        try {
+            await chmod(temp, 0o666);
+            await unlink(temp);
+        }
+        catch {
+            // The temporary file stays. The error of the write is the error that the caller gets.
+        }
+    }
+}
+/** The flush of the folder, so that the rename is on the disk. Windows cannot open a folder for it. */
+async function syncFolder(folder) {
+    if (isWindows())
+        return;
+    let handle;
+    try {
+        handle = await open(folder, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        if (!NO_FOLDER_SYNC.has(codeOf(error)))
+            throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/**
+ * This function writes `data` to `path` in one step for each reader. A reader sees the old file or
+ * the whole new file. It does not see a part of a file at any time.
+ *
+ * - The function writes a new temporary file in the folder of the target and flushes it to the disk.
+ * - Then it renames the temporary file over the target and flushes the folder. Windows gets no flush of the folder.
+ * - On Windows, an open handle of the target blocks the rename. Then the function tries the rename again for `renameRetryMs`.
+ * - After a failure, the function removes the temporary file and throws the error.
+ * - The file keeps the permissions of the target, unless `options.mode` is set. It does not keep the owner.
+ * - When `path` is a symlink, the function replaces the target of the link.
+ *
+ * Two writes at the same time do not mix: the file gets the data of one of them. The folder must exist.
+ */
+export async function writeFileAtomic(path, data, options = {}) {
+    const target = await targetOf(path);
+    const mode = options.mode ?? (await modeOf(target));
+    const flush = options.fsync ?? true;
+    const temp = tempPathOf(target);
+    let created = false;
+    let handle;
+    try {
+        handle = await open(temp, "wx", mode ?? 0o666);
+        created = true;
+        await handle.writeFile(data, { encoding: options.encoding ?? "utf8" });
+        // The umask changes the mode of open(), so the function sets the mode again
+        if (mode !== undefined)
+            await handle.chmod(mode);
+        if (flush)
+            await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await renameWithRetry(temp, target, options.renameRetryMs ?? (isWindows() ? 2000 : 0));
+    }
+    catch (error) {
+        if (handle) {
+            try {
+                await handle.close();
+            }
+            catch {
+                // The error of the write is the error that the caller gets
+            }
+        }
+        if (created)
+            await removeTemp(temp);
+        throw error;
+    }
+    if (flush)
+        await syncFolder(dirname(target));
+}
+//# sourceMappingURL=atomic.js.map

package/dist/files/atomic.js.map

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

package/dist/files/edit.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The edit of a file, one at a time for each path (roadmap O51). An edit reads the file, changes
+ * the text and writes it with `writeFileAtomic()`, while it holds the lock of the path.
+ */
+import { type WriteFileAtomicOptions } from "./atomic.js";
+/** The options of `editFile()`. */
+export interface EditFileOptions extends WriteFileAtomicOptions {
+    /** The text that the transform gets when the file does not exist. Without it, the transform gets `undefined`. */
+    initial?: string | undefined;
+    /** The abort of this signal stops the wait for the lock of the path. */
+    signal?: AbortSignal | undefined;
+}
+/** The result of `editFile()`. */
+export interface EditFileResult {
+    /** True when the function wrote the file. */
+    readonly changed: boolean;
+    /** The text of the file after the edit, or `undefined` when the file does not exist. */
+    readonly content: string | undefined;
+}
+/** The function that changes the text. It gives the new text, or `undefined` to write nothing. */
+export type EditTransform<Current> = (current: Current) => string | undefined | PromiseLike<string | undefined>;
+/**
+ * This function changes a file with `transform`, one edit at a time for each path in the process.
+ *
+ * - The function reads the file. A missing file gives `options.initial`, or `undefined`.
+ * - Then it waits for `transform` and writes its text with `writeFileAtomic()`.
+ * - A transform that gives the same text, or `undefined`, writes nothing.
+ * - Two paths of the same file share the lock, also when the case of the letters is not the same on Windows.
+ *
+ * The lock is in the process. It does not stop another process. The options of `writeFileAtomic()` apply to the write.
+ */
+export declare function editFile(path: string, transform: EditTransform<string>, options: EditFileOptions & {
+    initial: string;
+}): Promise<EditFileResult>;
+export declare function editFile(path: string, transform: EditTransform<string | undefined>, options?: EditFileOptions): Promise<EditFileResult>;
+//# sourceMappingURL=edit.d.ts.map

package/dist/files/edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/files/edit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAmB,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG3E,mCAAmC;AACnC,MAAM,WAAW,eAAgB,SAAQ,sBAAsB;IAC7D,iHAAiH;IACjH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAClC;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,kGAAkG;AAClG,MAAM,MAAM,aAAa,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AA6BhH;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,EAChC,OAAO,EAAE,eAAe,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC,cAAc,CAAC,CAAC;AAC3B,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,EAC5C,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CAAC"}

package/dist/files/edit.js

@@ -0,0 +1,56 @@
+/**
+ * The edit of a file, one at a time for each path (roadmap O51). An edit reads the file, changes
+ * the text and writes it with `writeFileAtomic()`, while it holds the lock of the path.
+ */
+import { readFile, realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { writeFileAtomic } from "./atomic.js";
+import { KeyedLock } from "./lock.js";
+let pathLock;
+/**
+ * The key of the lock of a path. The key is absolute, with the real path of the folder. On Windows,
+ * the case of the letters is not significant. The function does not follow a symlink of the file.
+ */
+async function lockKeyOf(absolute) {
+    let folder = dirname(absolute);
+    try {
+        folder = await realpath(folder);
+    }
+    catch {
+        // A folder that does not exist keeps its path. The write then fails.
+    }
+    const key = join(folder, basename(absolute));
+    return process.platform === "win32" ? key.toLowerCase() : key;
+}
+/** The text of the file, or `undefined` when the file does not exist. Another error is an error. */
+async function readOrUndefined(path, encoding) {
+    try {
+        return await readFile(path, { encoding });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function editFile(path, transform, options = {}) {
+    // The overloads give a transform of `string` only with `initial`, so the current text is a string then
+    const change = transform;
+    const { initial, signal, ...write } = options;
+    const target = resolve(path);
+    pathLock ??= new KeyedLock();
+    const release = await pathLock.acquire(await lockKeyOf(target), { signal });
+    try {
+        const encoding = write.encoding ?? "utf8";
+        const current = await readOrUndefined(target, encoding);
+        const next = await change(current ?? initial);
+        if (next === undefined || next === current)
+            return { changed: false, content: current };
+        await writeFileAtomic(target, next, { ...write, encoding });
+        return { changed: true, content: next };
+    }
+    finally {
+        release();
+    }
+}
+//# sourceMappingURL=edit.js.map

package/dist/files/edit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.js","sourceRoot":"","sources":["../../src/files/edit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,eAAe,EAA+B,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAqBtC,IAAI,QAA+B,CAAC;AAEpC;;;GAGG;AACH,KAAK,UAAU,SAAS,CAAC,QAAgB;IACvC,IAAI,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;IACvE,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC7C,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;AAChE,CAAC;AAED,oGAAoG;AACpG,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,QAAwB;IACnE,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACzE,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAsBD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAY,EACZ,SAAoE,EACpE,OAAO,GAAoB,EAAE;IAE7B,uGAAuG;IACvG,MAAM,MAAM,GAAG,SAA8C,CAAC;IAC9D,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,QAAQ,KAAK,IAAI,SAAS,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,MAAM,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5E,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,MAAM,CAAC;QAC1C,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,CAAC;QAC9C,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QACxF,MAAM,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC5D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1C,CAAC;YAAS,CAAC;QACT,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/files/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The file helpers of the package (roadmap O51): the `./files` entry. They are functions, not
+ * procedures, and an import of this entry registers nothing.
+ *
+ * - `writeFileAtomic()` writes a file in one step for each reader.
+ * - `healNdjsonTail()` repairs the end of an append-only NDJSON file after a crash.
+ * - `KeyedLock` and `withLock()` let one caller at a time hold a key.
+ * - `editFile()` changes a file, one edit at a time for each path.
+ */
+export { writeFileAtomic, type WriteFileAtomicOptions } from "./atomic.js";
+export { healNdjsonTail, type HealNdjsonTailOptions, type NdjsonTailAction, type NdjsonTailResult } from "./ndjson-tail.js";
+export { KeyedLock, withLock, type LockOutcome, type LockRelease, type LockSkipOptions, type LockWaitOptions, } from "./lock.js";
+export { editFile, type EditFileOptions, type EditFileResult, type EditTransform } from "./edit.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/files/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC5H,OAAO,EACL,SAAS,EACT,QAAQ,EACR,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/files/index.js

@@ -0,0 +1,14 @@
+/**
+ * The file helpers of the package (roadmap O51): the `./files` entry. They are functions, not
+ * procedures, and an import of this entry registers nothing.
+ *
+ * - `writeFileAtomic()` writes a file in one step for each reader.
+ * - `healNdjsonTail()` repairs the end of an append-only NDJSON file after a crash.
+ * - `KeyedLock` and `withLock()` let one caller at a time hold a key.
+ * - `editFile()` changes a file, one edit at a time for each path.
+ */
+export { writeFileAtomic } from "./atomic.js";
+export { healNdjsonTail } from "./ndjson-tail.js";
+export { KeyedLock, withLock, } from "./lock.js";
+export { editFile } from "./edit.js";
+//# sourceMappingURL=index.js.map

package/dist/files/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAA+B,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,cAAc,EAA4E,MAAM,kBAAkB,CAAC;AAC5H,OAAO,EACL,SAAS,EACT,QAAQ,GAKT,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAiE,MAAM,WAAW,CAAC"}

package/dist/files/lock.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A lock in the process for each key (roadmap O51). One holder at a time has a key. The other
+ * callers wait in the order of their calls, or they skip their work.
+ */
+/** The function that gives the lock back. A second call does nothing. */
+export type LockRelease = () => void;
+/** The options of a call that waits when the lock has a holder. */
+export interface LockWaitOptions {
+    /** With `wait` (the default), the call waits for the lock. */
+    ifHeld?: "wait" | undefined;
+    /** The abort of this signal stops the wait. The call then rejects with the reason of the signal. */
+    signal?: AbortSignal | undefined;
+}
+/** The options of a call that skips its work when the lock has a holder. */
+export interface LockSkipOptions {
+    /** With `skip`, the call does not start the function when the lock has a holder. */
+    ifHeld: "skip";
+}
+/** The result of a call with `ifHeld: "skip"`: the value of the function, or `ran: false` when the lock had a holder. */
+export type LockOutcome<T> = {
+    readonly ran: true;
+    readonly value: T;
+} | {
+    readonly ran: false;
+};
+/**
+ * A set of locks, one for each key, in one process. Each instance has its own keys.
+ *
+ * - One holder at a time has a key. The waiters get the key in the order of their calls.
+ * - The lock is not reentrant. A holder that asks for its own key again waits for ever.
+ * - A key without a holder uses no memory.
+ */
+export declare class KeyedLock {
+    /** The waiters of each key that has a holder. A key without a holder is not in the map. */
+    private readonly queues;
+    /** The number of keys that have a holder. */
+    get size(): number;
+    /** This method tells if the key has a holder. */
+    isHeld(key: string): boolean;
+    /** This method takes the key when it has no holder. Otherwise it gives `undefined` and does not wait. */
+    tryAcquire(key: string): LockRelease | undefined;
+    /**
+     * This method gives the key to the caller. When the key has a holder, the caller waits after the
+     * other waiters. The abort of `options.signal` stops the wait.
+     */
+    acquire(key: string, options?: {
+        signal?: AbortSignal | undefined;
+    }): Promise<LockRelease>;
+    /**
+     * This method starts `fn` with the key, and gives the key back when `fn` ends or throws.
+     * With `ifHeld: "skip"`, it does not start `fn` when the key has a holder.
+     */
+    run<T>(key: string, fn: () => T | PromiseLike<T>, options?: LockWaitOptions): Promise<T>;
+    run<T>(key: string, fn: () => T | PromiseLike<T>, options: LockSkipOptions): Promise<LockOutcome<T>>;
+    /** The start of a turn of a key without a holder: an empty queue in the map. */
+    private take;
+    /**
+     * The release of one turn of the key. It gives the key to the first waiter of `queue`, or removes
+     * the key. The queue stays in the map while the key has a holder.
+     */
+    private releaseOf;
+}
+/**
+ * This function starts `fn` with the key of the lock of the process, and gives the key back when
+ * `fn` ends or throws. The callers of one key run one at a time, in the order of their calls.
+ *
+ * - With `ifHeld: "skip"`, the function does not start `fn` when the key has a holder. It gives `{ ran: false }`.
+ * - All the callers in the process share the keys. For keys of your own, make a `KeyedLock`.
+ */
+export declare function withLock<T>(key: string, fn: () => T | PromiseLike<T>, options?: LockWaitOptions): Promise<T>;
+export declare function withLock<T>(key: string, fn: () => T | PromiseLike<T>, options: LockSkipOptions): Promise<LockOutcome<T>>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/files/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/files/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,yEAAyE;AACzE,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,oGAAoG;IACpG,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAClC;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yHAAyH;AACzH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAA;CAAE,CAAC;AAYjG;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IAEtD,6CAA6C;IAC7C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,iDAAiD;IACjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3B;IAED,yGAAyG;IACzG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAE/C;IAED;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAkB7F;IAED;;;OAGG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzF,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAuBrG,gFAAgF;IAChF,OAAO,CAAC,IAAI;IAMZ;;;OAGG;IACH,OAAO,CAAC,SAAS;CAclB;AAID;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAC9G,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/files/lock.js

@@ -0,0 +1,106 @@
+/**
+ * A lock in the process for each key (roadmap O51). One holder at a time has a key. The other
+ * callers wait in the order of their calls, or they skip their work.
+ */
+/** The function that does nothing: the `detach` of a waiter without a signal. */
+function noop() { }
+/**
+ * A set of locks, one for each key, in one process. Each instance has its own keys.
+ *
+ * - One holder at a time has a key. The waiters get the key in the order of their calls.
+ * - The lock is not reentrant. A holder that asks for its own key again waits for ever.
+ * - A key without a holder uses no memory.
+ */
+export class KeyedLock {
+    /** The waiters of each key that has a holder. A key without a holder is not in the map. */
+    queues = new Map();
+    /** The number of keys that have a holder. */
+    get size() {
+        return this.queues.size;
+    }
+    /** This method tells if the key has a holder. */
+    isHeld(key) {
+        return this.queues.has(key);
+    }
+    /** This method takes the key when it has no holder. Otherwise it gives `undefined` and does not wait. */
+    tryAcquire(key) {
+        return this.queues.has(key) ? undefined : this.take(key);
+    }
+    /**
+     * This method gives the key to the caller. When the key has a holder, the caller waits after the
+     * other waiters. The abort of `options.signal` stops the wait.
+     */
+    acquire(key, options = {}) {
+        const { signal } = options;
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        const queue = this.queues.get(key);
+        if (!queue)
+            return Promise.resolve(this.take(key));
+        return new Promise((resolve, reject) => {
+            const waiter = { grant: resolve, detach: noop };
+            queue.push(waiter);
+            if (signal) {
+                const onAbort = () => {
+                    // The grant removes this listener, so the waiter is still in the queue here
+                    queue.splice(queue.indexOf(waiter), 1);
+                    reject(signal.reason);
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+                waiter.detach = () => signal.removeEventListener("abort", onAbort);
+            }
+        });
+    }
+    async run(key, fn, options = {}) {
+        if (options.ifHeld === "skip") {
+            const release = this.tryAcquire(key);
+            if (!release)
+                return { ran: false };
+            try {
+                return { ran: true, value: await fn() };
+            }
+            finally {
+                release();
+            }
+        }
+        const release = await this.acquire(key, { signal: options.signal });
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+    /** The start of a turn of a key without a holder: an empty queue in the map. */
+    take(key) {
+        const queue = [];
+        this.queues.set(key, queue);
+        return this.releaseOf(key, queue);
+    }
+    /**
+     * The release of one turn of the key. It gives the key to the first waiter of `queue`, or removes
+     * the key. The queue stays in the map while the key has a holder.
+     */
+    releaseOf(key, queue) {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const next = queue.shift();
+            if (next) {
+                next.detach();
+                next.grant(this.releaseOf(key, queue));
+            }
+            else {
+                this.queues.delete(key);
+            }
+        };
+    }
+}
+let shared;
+export function withLock(key, fn, options) {
+    shared ??= new KeyedLock();
+    return options?.ifHeld === "skip" ? shared.run(key, fn, options) : shared.run(key, fn, options);
+}
+//# sourceMappingURL=lock.js.map

package/dist/files/lock.js.map

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

package/dist/files/ndjson-tail.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The repair of the end of an append-only NDJSON file after a crash (roadmap O51).
+ *
+ * A crash during an append can leave a part of a line at the end of the file. The next append
+ * then puts its line after that part, and the file has a bad line in its middle.
+ * `healNdjsonTail()` repairs the end before the next append.
+ */
+/** What `healNdjsonTail()` did: nothing, a cut of a partial last line, or a newline after a complete last record. */
+export type NdjsonTailAction = "none" | "truncated" | "newline";
+/** The result of `healNdjsonTail()`. */
+export interface NdjsonTailResult {
+    /** The change to the file. */
+    readonly action: NdjsonTailAction;
+    /** The number of bytes that the function removed or added. It is 0 for `none`. */
+    readonly bytes: number;
+    /** The size of the file after the repair. It is 0 for a file that does not exist. */
+    readonly size: number;
+}
+/** The options of `healNdjsonTail()`. */
+export interface HealNdjsonTailOptions {
+    /**
+     * The maximum length in bytes of the last line. The function reads no more than this number of
+     * bytes from the end. A longer last line is an error. The default is 16 MiB.
+     */
+    maxLineBytes?: number | undefined;
+    /** With `false`, the function does not flush a change to the disk. The default is `true`. */
+    fsync?: boolean | undefined;
+}
+/**
+ * This function repairs the end of an append-only NDJSON file after a crash. Then the file ends in a newline, or it is empty.
+ *
+ * - A missing file, an empty file and a file that ends in a newline get no change.
+ * - A last line that is not valid JSON is a part of a record. The function cuts it off with `ftruncate`.
+ * - A last line that is valid JSON is a complete record without its newline. The function adds the newline.
+ * - The function reads only the last line, from the end of the file. It does not read the whole file.
+ *
+ * The records must be objects or arrays. A part of a number or of a literal can be valid JSON too.
+ * The function does not lock the file. Start it before an append, in the same lock as the append.
+ */
+export declare function healNdjsonTail(path: string, options?: HealNdjsonTailOptions): Promise<NdjsonTailResult>;
+//# sourceMappingURL=ndjson-tail.d.ts.map

package/dist/files/ndjson-tail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ndjson-tail.d.ts","sourceRoot":"","sources":["../../src/files/ndjson-tail.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,qHAAqH;AACrH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAEhE,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,6FAA6F;IAC7F,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC7B;AAgCD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgDjH"}