@procedures/fs 0.27.3 → 0.27.5

package/dist/files/ndjson-tail.js

@@ -1,39 +1,165 @@
 /**
- * The repair of the end of an append-only NDJSON file after a crash (roadmap O51).
+ * The repair of the end of an append-only NDJSON file after a crash (roadmap O51 and O52).
  *
  * 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.
+ * `healNdjsonTail()` and `healNdjsonTailSync()` repair the end before the next append.
  */
+import { closeSync, fstatSync, fsyncSync, ftruncateSync, openSync, readSync, writeSync } from "node:fs";
 import { open } from "node:fs/promises";
+import { perform, runAsync, runSync } from "./steps.js";
+/** The code of the error of a last line that is longer than `maxLineBytes`. */
+export const NDJSON_LINE_TOO_LONG = "ERR_NDJSON_LINE_TOO_LONG";
 const NEWLINE = 0x0a;
-const NEWLINE_BYTES = Uint8Array.of(NEWLINE);
+const CARRIAGE_RETURN = 0x0d;
 const CHUNK_BYTES = 64 * 1024;
 const DEFAULT_MAX_LINE_BYTES = 16 * 1024 * 1024;
 const BOM = [0xef, 0xbb, 0xbf];
+/** The bytes of the file from `position`, `length` bytes or fewer. */
+function read(position, length) {
+    return perform({ op: "read", position, length });
+}
+/**
+ * The `RangeError` of a last line that is longer than `maxLineBytes`. It tells the length, the
+ * limit and the option. It has the fields `code`, `path`, `lineBytes` and `maxLineBytes`.
+ */
+function lineTooLong(path, lineBytes, maxLineBytes) {
+    const error = new RangeError(`A line at the end of ${path} has ${lineBytes} bytes, more than the limit maxLineBytes (${maxLineBytes} bytes). ` +
+        `Set the option maxLineBytes to ${lineBytes} or more, or to Infinity for no limit. The file did not change.`);
+    return Object.assign(error, { code: NDJSON_LINE_TOO_LONG, path, lineBytes, maxLineBytes });
+}
 /**
- * The bytes of the file from `position`, `length` bytes or fewer. A read of a local file gives all
- * the bytes up to the end of the file.
+ * The position after the last newline of the bytes from `lowest` to `end`, or -1 without a newline.
+ * The function reads back from `end`, one chunk at a time. It adds each chunk after the newline to
+ * the start of `keep`, when `keep` is set.
  */
-async function readAt(handle, position, length) {
-    const buffer = Buffer.alloc(length);
-    const { bytesRead } = await handle.read(buffer, 0, length, position);
-    return buffer.subarray(0, bytesRead);
+function* lineStartBack(end, lowest, keep) {
+    for (let to = end; to > lowest;) {
+        const from = Math.max(lowest, to - CHUNK_BYTES);
+        const chunk = yield* read(from, to - from);
+        const at = chunk.lastIndexOf(NEWLINE);
+        keep?.unshift(at === -1 ? chunk : chunk.subarray(at + 1));
+        if (at !== -1)
+            return from + at + 1;
+        to = from;
+    }
+    return -1;
 }
 /**
- * True when the bytes hold one complete JSON value. No part of an object or of an array is valid
+ * The line that ends at `end`, from the newline before it. The function reads no more than
+ * `maxLineBytes` and one byte back from `end`. A longer line is an error.
+ */
+function* lineBefore(path, end, maxLineBytes) {
+    const lowest = Math.max(0, end - maxLineBytes - 1);
+    const parts = [];
+    const start = yield* lineStartBack(end, lowest, parts);
+    if (start !== -1 || lowest === 0)
+        return { start: Math.max(start, 0), bytes: Buffer.concat(parts) };
+    // Only to give the length in the error: the bytes before the window, without a copy in memory
+    const found = yield* lineStartBack(lowest, 0, undefined);
+    throw lineTooLong(path, end - Math.max(found, 0), maxLineBytes);
+}
+/** The bytes of a line without the byte order mark at the start of the file. */
+function withoutBom(line) {
+    const { bytes } = line;
+    return line.start === 0 && BOM.every((byte, index) => bytes[index] === byte) ? bytes.subarray(BOM.length) : bytes;
+}
+/**
+ * True when the line holds one complete JSON value. No part of an object or of an array is valid
  * JSON, so the function cannot keep a part of such a record.
  */
-function isCompleteJson(bytes, atStart) {
-    const text = atStart && BOM.every((byte, index) => bytes[index] === byte) ? bytes.subarray(BOM.length) : bytes;
+function isCompleteJson(line) {
     try {
-        JSON.parse(text.toString("utf8"));
+        JSON.parse(withoutBom(line).toString("utf8"));
         return true;
     }
     catch {
         return false;
     }
 }
+/** The text of a complete line for `lastLine`: without the byte order mark and without a `\r` at the end. */
+function textOf(line) {
+    const bytes = withoutBom(line);
+    return (bytes.at(-1) === CARRIAGE_RETURN ? bytes.subarray(0, -1) : bytes).toString("utf8");
+}
+/** The steps of `healNdjsonTail()` and `healNdjsonTailSync()` on the open file. */
+function* healSteps(path, options) {
+    const maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+    const flush = options.fsync ?? true;
+    const wantLast = options.lastLine === true;
+    // The text of the complete line that ends at the newline at `newline`
+    const completeLine = function* (newline) {
+        return wantLast ? { lastLine: textOf(yield* lineBefore(path, newline, maxLineBytes)) } : {};
+    };
+    const noLine = wantLast ? { lastLine: undefined } : {};
+    const size = yield* perform({ op: "size" });
+    if (size === 0)
+        return { action: "none", bytes: 0, size, ...noLine };
+    const [last] = yield* read(size - 1, 1);
+    if (last === NEWLINE)
+        return { action: "none", bytes: 0, size, ...(yield* completeLine(size - 1)) };
+    const line = yield* lineBefore(path, size, maxLineBytes);
+    if (isCompleteJson(line)) {
+        yield { op: "newline", position: size };
+        if (flush)
+            yield { op: "sync" };
+        return { action: "newline", bytes: 1, size: size + 1, ...(wantLast ? { lastLine: textOf(line) } : {}) };
+    }
+    // The line before the cut is the last line after it. The function reads it first, so an error changes nothing.
+    const before = line.start === 0 ? noLine : yield* completeLine(line.start - 1);
+    yield { op: "truncate", length: line.start };
+    if (flush)
+        yield { op: "sync" };
+    return { action: "truncated", bytes: size - line.start, size: line.start, ...before };
+}
+/** The result for a file that does not exist. */
+function missing(options) {
+    return { action: "none", bytes: 0, size: 0, ...(options.lastLine === true ? { lastLine: undefined } : {}) };
+}
+/** True for the error of a file that does not exist. */
+function isMissing(error) {
+    return error.code === "ENOENT";
+}
+const NEWLINE_BYTES = Uint8Array.of(NEWLINE);
+/** The async operations on the open file, with a `FileHandle`. */
+function asyncOn(handle) {
+    return async (op) => {
+        switch (op.op) {
+            case "size":
+                return (await handle.stat()).size;
+            case "read": {
+                const buffer = Buffer.alloc(op.length);
+                const { bytesRead } = await handle.read(buffer, 0, op.length, op.position);
+                return buffer.subarray(0, bytesRead);
+            }
+            case "newline":
+                return handle.write(NEWLINE_BYTES, 0, 1, op.position);
+            case "truncate":
+                return handle.truncate(op.length);
+            case "sync":
+                return handle.sync();
+        }
+    };
+}
+/** The sync operations on the open file, with a file descriptor. */
+function syncOn(fd) {
+    return (op) => {
+        switch (op.op) {
+            case "size":
+                return fstatSync(fd).size;
+            case "read": {
+                const buffer = Buffer.alloc(op.length);
+                return buffer.subarray(0, readSync(fd, buffer, 0, op.length, op.position));
+            }
+            case "newline":
+                return writeSync(fd, NEWLINE_BYTES, 0, 1, op.position);
+            case "truncate":
+                return ftruncateSync(fd, op.length);
+            case "sync":
+                return fsyncSync(fd);
+        }
+    };
+}
 /**
  * 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.
  *
@@ -41,64 +167,50 @@ function isCompleteJson(bytes, atStart) {
  * - 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.
+ * - With `options.lastLine`, the result also gives the last complete line after the repair.
+ *
+ * A last line that is longer than `maxLineBytes` (16 MiB by default) is a `RangeError` with the code
+ * `ERR_NDJSON_LINE_TOO_LONG`. The file then does not change. Set `maxLineBytes: Infinity` for files with very long records.
  *
  * 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 async function healNdjsonTail(path, options = {}) {
-    const maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
     let handle;
     try {
         handle = await open(path, "r+");
     }
     catch (error) {
-        if (error.code === "ENOENT")
-            return { action: "none", bytes: 0, size: 0 };
+        if (isMissing(error))
+            return missing(options);
         throw error;
     }
     try {
-        const { size } = await handle.stat();
-        if (size === 0)
-            return { action: "none", bytes: 0, size };
-        const [last] = await readAt(handle, size - 1, 1);
-        if (last === NEWLINE)
-            return { action: "none", bytes: 0, size };
-        // Back from the end, one chunk at a time, to the newline before the last line
-        const lowest = Math.max(0, size - maxLineBytes - 1);
-        const parts = [];
-        let lineStart = -1;
-        for (let end = size; end > lowest && lineStart === -1;) {
-            const start = Math.max(lowest, end - CHUNK_BYTES);
-            const chunk = await readAt(handle, start, end - start);
-            const at = chunk.lastIndexOf(NEWLINE);
-            if (at === -1) {
-                parts.unshift(chunk);
-            }
-            else {
-                parts.unshift(chunk.subarray(at + 1));
-                lineStart = start + at + 1;
-            }
-            end = start;
-        }
-        if (lineStart === -1) {
-            if (lowest > 0)
-                throw new RangeError(`The last line of ${path} is longer than ${maxLineBytes} bytes (maxLineBytes)`);
-            lineStart = 0;
-        }
-        const flush = options.fsync ?? true;
-        if (isCompleteJson(Buffer.concat(parts), lineStart === 0)) {
-            await handle.write(NEWLINE_BYTES, 0, 1, size);
-            if (flush)
-                await handle.sync();
-            return { action: "newline", bytes: 1, size: size + 1 };
-        }
-        await handle.truncate(lineStart);
-        if (flush)
-            await handle.sync();
-        return { action: "truncated", bytes: size - lineStart, size: lineStart };
+        return await runAsync(healSteps(path, options), asyncOn(handle));
     }
     finally {
         await handle.close();
     }
 }
+/**
+ * This function is the sync form of `healNdjsonTail()`. It makes the same repairs, with the same
+ * options, the same result and the same errors. It blocks the thread until the repair is complete.
+ */
+export function healNdjsonTailSync(path, options = {}) {
+    let fd;
+    try {
+        fd = openSync(path, "r+");
+    }
+    catch (error) {
+        if (isMissing(error))
+            return missing(options);
+        throw error;
+    }
+    try {
+        return runSync(healSteps(path, options), syncOn(fd));
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 //# sourceMappingURL=ndjson-tail.js.map

package/dist/files/ndjson-tail.js.map

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

package/dist/files/steps.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The runners of the steps of a file helper (roadmap O52). A helper is one generator that yields
+ * each operation of the file system. `runSync()` and `runAsync()` do the operations, so the sync
+ * form and the async form of a helper share all their decisions.
+ */
+/**
+ * The step that gives the result of `op`. The cast is safe because each runner gives the value
+ * that the operation of the step gives.
+ */
+export declare function perform<Op, T>(op: Op): Generator<Op, T, unknown>;
+/**
+ * This function does the steps with a sync `does`. An error of an operation goes back into the
+ * steps, so their `try` and `finally` blocks apply.
+ */
+export declare function runSync<Op, T>(steps: Generator<Op, T, unknown>, does: (op: Op) => unknown): T;
+/** This function does the steps with an async `does`, in the same way as `runSync()`. */
+export declare function runAsync<Op, T>(steps: Generator<Op, T, unknown>, does: (op: Op) => Promise<unknown>): Promise<T>;
+//# sourceMappingURL=steps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../src/files/steps.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,wBAAiB,OAAO,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAEjE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,GAAG,CAAC,CAa7F;AAED,yFAAyF;AACzF,wBAAsB,QAAQ,CAAC,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAatH"}

package/dist/files/steps.js

@@ -0,0 +1,48 @@
+/**
+ * The runners of the steps of a file helper (roadmap O52). A helper is one generator that yields
+ * each operation of the file system. `runSync()` and `runAsync()` do the operations, so the sync
+ * form and the async form of a helper share all their decisions.
+ */
+/**
+ * The step that gives the result of `op`. The cast is safe because each runner gives the value
+ * that the operation of the step gives.
+ */
+export function* perform(op) {
+    return (yield op);
+}
+/**
+ * This function does the steps with a sync `does`. An error of an operation goes back into the
+ * steps, so their `try` and `finally` blocks apply.
+ */
+export function runSync(steps, does) {
+    let step = steps.next();
+    while (!step.done) {
+        let value;
+        try {
+            value = does(step.value);
+        }
+        catch (error) {
+            step = steps.throw(error);
+            continue;
+        }
+        step = steps.next(value);
+    }
+    return step.value;
+}
+/** This function does the steps with an async `does`, in the same way as `runSync()`. */
+export async function runAsync(steps, does) {
+    let step = steps.next();
+    while (!step.done) {
+        let value;
+        try {
+            value = await does(step.value);
+        }
+        catch (error) {
+            step = steps.throw(error);
+            continue;
+        }
+        step = steps.next(value);
+    }
+    return step.value;
+}
+//# sourceMappingURL=steps.js.map

package/dist/files/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../src/files/steps.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,SAAS,CAAC,CAAC,OAAO,CAAQ,EAAM;IACpC,OAAO,CAAC,MAAM,EAAE,CAAM,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAQ,KAAgC,EAAE,IAAyB;IACxF,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACxB,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,IAAI,KAAc,CAAC;QACnB,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,SAAS;QACX,CAAC;QACD,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC;AACpB,CAAC;AAED,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAQ,KAAgC,EAAE,IAAkC;IACxG,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACxB,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,IAAI,KAAc,CAAC;QACnB,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,SAAS;QACX,CAAC;QACD,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC;AACpB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/fs",
-  "version": "0.27.3",
+  "version": "0.27.5",
   "description": "File system procedures: read, write, copy, move, glob, exists, mkdir and JSON read and write, callable in process, over RPC or from Claude through MCP.",
   "keywords": [
     "filesystem",
@@ -69,7 +69,7 @@
     "procedures": "./dist/register.js"
   },
   "dependencies": {
-    "@procedures/client": "0.27.3",
+    "@procedures/client": "0.27.5",
     "zod": "^4.6.5"
   },
   "devDependencies": {