logroller 2.0.2 → 2.1.0

package/dist/index.esm.js

@@ -1,4 +1,4 @@
-/*! logroller v2.0.1 | MIT License */
+/*! logroller v2.1.0 | MIT License */
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -24,13 +24,13 @@ const existsSafe = (p) => {
     }
 };
 /**
- * Compress `src` → `dst`, deleting `src` ONLY on verified success.
- * On failure removes the partial `dst` and reports via callback —
+ * Compress `src` → `dst` at gzip `level`, deleting `src` ONLY on verified
+ * success. On failure removes the partial `dst` and reports via callback —
  * logs degrade to uncompressed rather than losing data.
  */
-async function gzipMove(src, dst, onWarn) {
+async function gzipMove(src, dst, onWarn, level = 6) {
     try {
-        await pipeline(fs.createReadStream(src), zlib.createGzip({ level: 6 }), fs.createWriteStream(dst));
+        await pipeline(fs.createReadStream(src), zlib.createGzip({ level }), fs.createWriteStream(dst));
         await fs.promises.unlink(src);
         return true;
     }
@@ -43,21 +43,47 @@ async function gzipMove(src, dst, onWarn) {
 const endStream = (ws) => ws ? new Promise((resolve) => ws.end(() => resolve())) : Promise.resolve();
 
 const UNITS = {
-    b: 1, k: 1024, kb: 1024,
-    m: 1048576, mb: 1048576,
-    g: 1073741824, gb: 1073741824,
+    b: 1,
+    k: 1024,
+    kb: 1024,
+    m: 1048576,
+    mb: 1048576,
+    g: 1073741824,
+    gb: 1073741824,
 };
-const FREQ_MULT = {
-    ms: 1, s: 1000, m: 60_000, h: 3_600_000,
+/**
+ * Every unit token the duration regex can capture MUST have an entry here —
+ * a captured-but-unmapped unit would otherwise surface as a NaN that
+ * detonates later (e.g. `RangeError: Invalid time value` from Intl),
+ * far away from the actual misconfiguration.
+ */
+const DURATION_ALIASES = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    hour: 3_600_000,
+    hours: 3_600_000,
 };
+/**
+ * Parse `"<n><unit?>"` or a bare number into milliseconds.
+ * Bare numbers are interpreted in `defaultUnit`.
+ *
+ * Accepted unit spellings: ms, s, m, h, hour, hours (case-insensitive).
+ */
 function parseDuration(value, defaultUnit, fieldName) {
     if (typeof value === "number") {
-        return Math.round(value * FREQ_MULT[defaultUnit]);
+        return Math.round(value * DURATION_ALIASES[defaultUnit]);
     }
-    const m = /^\s*(-?\d+(?:\.\d+)?)\s*(ms|s|m|h)?\s*$/i.exec(value);
+    const m = /^\s*(-?\d+(?:\.\d+)?)\s*(h(?:our)?s?|ms|s|m)?\s*$/i.exec(value);
     if (!m)
         throw new Error(`Invalid ${fieldName} "${value}"`);
-    return Math.round(Number.parseFloat(m[1]) * FREQ_MULT[(m[2] ?? defaultUnit).toLowerCase()]);
+    const unit = (m[2] ?? defaultUnit).toLowerCase();
+    const mult = DURATION_ALIASES[unit];
+    if (mult === undefined) {
+        throw new Error(`Invalid ${fieldName} unit "${m[2]}" in "${value}"`);
+    }
+    return Math.round(Number.parseFloat(m[1]) * mult);
 }
 function parseSize(v) {
     if (v === undefined || v === null || v === 0)
@@ -72,8 +98,11 @@ function parseSize(v) {
 function parseMaxFiles(v) {
     if (v === undefined || v === null || v === "" || v === 0)
         return null;
-    if (typeof v === "number")
+    if (typeof v === "number") {
+        if (v < 0)
+            throw new Error(`Invalid maxFiles "${v}"`);
         return { count: v };
+    }
     const m = /^\s*(\d+)\s*d\s*$/i.exec(v);
     if (m)
         return { days: Number.parseInt(m[1], 10) };
@@ -97,15 +126,23 @@ function parseFrequency(v) {
         throw new Error(`Invalid frequency "${v}"`);
     return { type: "interval", ms: Number.parseInt(m[1], 10) * FREQ_MULT[m[2].toLowerCase()] };
 }
+const FREQ_MULT = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+};
+/** Static virtual-clock shift. Accepts hours by default; h/hours/m/s/ms. */
 function parseClockOffset(v) {
     if (v === undefined || v === null || v === "")
         return 0;
     return parseDuration(v, "h", "addHours");
 }
+/** Per-tick virtual-clock step. Accepts hours by default; h/hours/m/s/ms. */
 function parseClockStep(v) {
     if (v === undefined || v === null || v === "")
         return 0;
-    return parseDuration(v, "h", "addHours");
+    return parseDuration(v, "h", "addHoursEveryMin");
 }
 
 /* Timezone-aware helpers built exclusively on Intl (zero deps). */
@@ -212,17 +249,22 @@ const emptyAudit = (prefix, ext, datePattern, tz) => ({
 });
 /**
  * A `Writable` that appends to dated log files, rolling segments on time
- * and/or size, optionally gzipping sealed segments, enforcing retention,
- * and resuming an unbroken series across restarts via disk scan + audit
- * manifest.
+ * and/or size, optionally gzipping sealed segments, enforcing retention
+ * (count, age, and total-byte budget), maintaining a stable "current"
+ * symlink for log collectors, running an awaited seal hook (upload
+ * pipeline), and resuming an unbroken series across restarts via disk
+ * scan + audit manifest.
  *
  * @example
  * ```ts
  * const log = createStream({
  *   filename: "logs/app-%DATE%.log",
  *   maxSize: "20m",
+ *   maxTotalSize: "5g",
  *   maxFiles: "90d",
  *   zippedArchive: true,
+ *   symlink: true,
+ *   onSeal: async ({ gz }) => uploadToS3(gz),
  * });
  * log.write("hello\n");          // or: readable.pipe(log)
  * ```
@@ -237,6 +279,7 @@ class RotateFileStream extends Writable {
     maxFiles;
     freq;
     unrefTimers;
+    maxTotalSize;
     /* ---- filename-template pieces ---- */
     _tL;
     _tMid;
@@ -247,6 +290,10 @@ class RotateFileStream extends Writable {
     _auditEnabled;
     _auditPath;
     _bootId = randomUUID();
+    _onSeal;
+    _sealHookTimeoutMs;
+    _compressionLevel;
+    _symlinkPath = null;
     /* ---- virtual test clock ---- */
     _offsetMs;
     _stepMs;
@@ -277,11 +324,16 @@ class RotateFileStream extends Writable {
         this.zippedArchive = !!opts.zippedArchive;
         this.maxSize = parseSize(opts.maxSize ?? 0);
         this.maxFiles = parseMaxFiles(opts.maxFiles);
+        this.maxTotalSize = parseSize(opts.maxTotalSize ?? 0);
         this.freq = parseFrequency(opts.frequency);
         this.unrefTimers = !!opts.unrefTimers;
         this._offsetMs = parseClockOffset(opts.addHours);
         this._stepMs = parseClockStep(opts.addHoursEveryMin);
         this._bumpEvery = Math.max(50, opts.clockStepIntervalMs ?? BUMP_DEFAULT_MS);
+        // compression + seal hook
+        this._compressionLevel = Math.min(9, Math.max(0, opts.compressionLevel ?? 6));
+        this._onSeal = opts.onSeal;
+        this._sealHookTimeoutMs = Math.max(0, opts.sealHookTimeoutMs ?? 30_000);
         /* Split "prefix-%DATE%mid.ext" → pieces so indices land BETWEEN the
            stamp and the extension: prefix-STAMP.N.ext                       */
         const li = this.template.indexOf("%DATE%");
@@ -298,6 +350,12 @@ class RotateFileStream extends Writable {
         const stem = (this._tL.replace(/[^\w.-]+/g, "") || "log")
             .replace(/^[-.]+|[-.]+$/g, "");
         this._auditPath = path.join(this.dir, opts.auditFile || `${stem}_audit.json`);
+        // stable "current" pointer target
+        this._symlinkPath = opts.symlink
+            ? path.join(this.dir, typeof opts.symlink === "string"
+                ? opts.symlink
+                : `${stem}-current.log`)
+            : null;
         fs.mkdirSync(this.dir, { recursive: true });
         this._curStamp = this._stampNow();
         this._audit = emptyAudit(this._tL, this._tExt, this.datePattern, this.tz);
@@ -314,6 +372,7 @@ class RotateFileStream extends Writable {
                 offsetMs: this._offsetMs,
             }));
         }
+        // warn when frequency is finer than the datePattern tokens
         process.nextTick(() => {
             const warn = (m) => this.emit("warn", new Error(m));
             if (this.freq.type === "interval") {
@@ -333,6 +392,7 @@ class RotateFileStream extends Writable {
            constructor so it deterministically precedes any write job: zombie
            demotion sees `_path === null`, gzip repair cannot race a reopen.  */
         this._job(async () => {
+            // disk-driven, audit-independent (runs even with audit:false)
             await this._sealOrphanedPastStamps();
             if (this._auditEnabled) {
                 this._demoteZombieActives();
@@ -341,8 +401,8 @@ class RotateFileStream extends Writable {
                 this._aevent("boot", { stamp: this._curStamp, index: this._index });
                 this._saveAudit();
             }
-            if (this.maxFiles)
-                this._retire();
+            if (this.maxFiles || this.maxTotalSize > 0)
+                this._retire(); // budget policy also gates
         }).catch(() => { });
         this._armTimer();
         this._armBump();
@@ -383,6 +443,60 @@ class RotateFileStream extends Writable {
     advanceClock() {
         return this._job(() => this._applyBump());
     }
+    /**
+     * Every family file on disk, oldest stamp first.
+     * Disk is truth: untracked files are reported with state "untracked".
+     */
+    listSegments() {
+        const rx = new RegExp("^" + escRe(this._tL) + "(.+?)" + escRe(this._tMid) +
+            "(?:\\.(\\d+))?" + escRe(this._tExt) + "(?:\\.gz)?$");
+        const skip = this._symlinkPath && path.basename(this._symlinkPath);
+        const out = [];
+        let names = [];
+        try {
+            names = fs.readdirSync(this.dir);
+        }
+        catch {
+            return out;
+        }
+        for (const n of names) {
+            if (n === skip)
+                continue;
+            const m = rx.exec(n);
+            if (!m)
+                continue;
+            const rec = this._audit.files[n];
+            out.push({
+                file: path.join(this.dir, n),
+                stamp: m[1],
+                index: m[2] ? Number.parseInt(m[2], 10) : 0,
+                gzipped: n.endsWith(".gz"),
+                bytes: statSizeSafe(path.join(this.dir, n)),
+                state: rec?.state ?? "untracked",
+                openedAt: rec?.openedAt,
+                archivedAt: rec?.archivedAt,
+            });
+        }
+        out.sort((a, b) => a.stamp.localeCompare(b.stamp) || a.index - b.index);
+        return out;
+    }
+    /**
+     * Health-check snapshot for dashboards and support triage.
+     */
+    stats() {
+        const segs = this.listSegments();
+        return {
+            dir: this.dir,
+            currentStamp: this._curStamp,
+            activeFile: this._path,
+            activeIndex: this._index,
+            segments: segs.length,
+            archived: segs.filter((s) => s.gzipped).length,
+            totalBytes: segs.reduce((sum, s) => sum + s.bytes, 0),
+            clockOffsetMs: this._offsetMs,
+            symlink: this._symlinkPath,
+        };
+    }
     /* ==================================================================
      * Writable contract
      * ================================================================ */
@@ -515,6 +629,57 @@ class RotateFileStream extends Writable {
         }
         return idx;
     }
+    /**
+     * Atomically flip the "current" symlink to the active segment.
+     * tmp + rename so followers (`tail -f`, Filebeat) never observe a gap.
+     * Relative target keeps the link portable. Best-effort: filesystems
+     * denying symlinks warn once and disable the feature permanently.
+     */
+    _updateSymlink() {
+        const link = this._symlinkPath;
+        if (!link || !this._path)
+            return;
+        const tmp = `${link}.tmp`;
+        try {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* absent */ }
+            fs.symlinkSync(path.basename(this._path), tmp, "file");
+            fs.renameSync(tmp, link);
+        }
+        catch (e) {
+            this._symlinkPath = null;
+            this.emit("warn", new Error(`symlink unavailable ("${link}"): ${e.message} — continuing without it`));
+        }
+    }
+    /**
+     * Await the user's onSeal hook with a hard timeout. Result or
+     * failure degrades to `warn` — a wedged upload must never stall rotation.
+     * Called BEFORE retention so uploads finish before deletion.
+     */
+    async _runSealHook(raw, gz) {
+        const hook = this._onSeal;
+        if (!hook)
+            return;
+        let timer;
+        try {
+            await Promise.race([
+                Promise.resolve().then(() => hook({ raw, gz })),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`onSeal hook timed out after ${this._sealHookTimeoutMs}ms ` +
+                        `(${path.basename(gz ?? raw)})`)), this._sealHookTimeoutMs);
+                }),
+            ]);
+        }
+        catch (err) {
+            this.emit("warn", err);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     async _ensureOpen() {
         if (this._ws)
             return;
@@ -524,6 +689,7 @@ class RotateFileStream extends Writable {
         ws.on("error", (e) => this.emit("error", e));
         this._ws = ws;
         this._path = p;
+        this._updateSymlink(); // flip pointer on every open
         if (this._auditEnabled) {
             const base = path.basename(p);
             // reopen = NEW incarnation. Never inherit lifecycle
@@ -566,9 +732,10 @@ class RotateFileStream extends Writable {
                     rec.bytes = realBytes;
                     this._saveAudit();
                 }
-                const ok = await gzipMove(oldPath, archive, (e) => this.emit("warn", e));
+                const ok = await gzipMove(oldPath, archive, (e) => this.emit("warn", e), this._compressionLevel);
                 if (ok) {
                     this._finishArchivedRecord(oldBase);
+                    await this._runSealHook(oldPath, archive);
                 }
                 else {
                     if (rec) {
@@ -577,6 +744,7 @@ class RotateFileStream extends Writable {
                     }
                     this._aevent("gzip-failed", { file: oldBase });
                     archive = null;
+                    await this._runSealHook(oldPath, null);
                 }
             }
             else if (realBytes === 0) {
@@ -587,6 +755,7 @@ class RotateFileStream extends Writable {
                 if (existsSafe(adoptedGz)) {
                     this._finishArchivedRecord(oldBase);
                     archive = adoptedGz;
+                    await this._runSealHook(oldPath, adoptedGz);
                 }
                 else {
                     try {
@@ -600,9 +769,13 @@ class RotateFileStream extends Writable {
                     this._aevent("drop-empty", { file: oldBase });
                 }
             }
-            else if (rec) {
-                rec.state = "sealed";
-                rec.bytes = realBytes;
+            else if (realBytes > 0) {
+                // uncompressed seal (zippedArchive off): still notify sealers
+                if (rec) {
+                    rec.state = "sealed";
+                    rec.bytes = realBytes;
+                }
+                await this._runSealHook(oldPath, null);
             }
         }
         let stamp = this._stampNow();
@@ -929,7 +1102,8 @@ class RotateFileStream extends Writable {
             const full = path.join(this.dir, name);
             if (!existsSafe(full) || statSizeSafe(full) === 0)
                 continue;
-            const ok = await gzipMove(full, `${full}.gz`, (e) => this.emit("warn", e));
+            const gzName = `${full}.gz`;
+            const ok = await gzipMove(full, gzName, (e) => this.emit("warn", e), this._compressionLevel);
             if (!ok)
                 continue;
             if (this._auditEnabled && this._audit.files[name]) {
@@ -938,7 +1112,6 @@ class RotateFileStream extends Writable {
             }
             else {
                 // untracked → record it fresh so future reconciles see truth
-                const gzName = `${name}.gz`;
                 if (this._auditEnabled) {
                     this._audit.files[gzName] = {
                         state: "archived",
@@ -947,8 +1120,9 @@ class RotateFileStream extends Writable {
                     };
                     this._aevent("seal-past", { file: gzName });
                 }
-                this.emit("archive", path.join(this.dir, gzName));
+                this.emit("archive", gzName);
             }
+            await this._runSealHook(full, gzName);
         }
     }
     async _repairInterruptedGzips() {
@@ -971,11 +1145,13 @@ class RotateFileStream extends Writable {
                     /* ignore */
                 }
                 this._finishArchivedRecord(name, true);
+                await this._runSealHook(src, dst);
                 continue;
             }
-            const ok = await gzipMove(src, dst, (e) => this.emit("warn", e));
+            const ok = await gzipMove(src, dst, (e) => this.emit("warn", e), this._compressionLevel);
             if (ok) {
                 this._finishArchivedRecord(name, true);
+                await this._runSealHook(src, dst);
             }
             else {
                 rec.gzipPending = false;
@@ -1008,14 +1184,19 @@ class RotateFileStream extends Writable {
      * ================================================================ */
     async _retire() {
         const policy = this.maxFiles;
-        if (!policy)
-            return;
+        if (!policy && this.maxTotalSize <= 0)
+            return; // budget gates too
         const activeBase = this._path && path.basename(this._path);
         const activeStem = activeBase?.replace(/(?:\.\d+)?(?:\.log|)(?:\.gz)?$/, "");
         const reserved = [
             path.basename(this._auditPath),
             `${path.basename(this._auditPath)}.tmp`,
             `${path.basename(this._auditPath)}.corrupt`,
+            // never eat the "current" pointer (or its tmp)
+            ...(this._symlinkPath
+                ? [path.basename(this._symlinkPath),
+                    `${path.basename(this._symlinkPath)}.tmp`]
+                : []),
         ];
         try {
             const dirEntries = await fs.promises.readdir(this.dir);
@@ -1027,7 +1208,8 @@ class RotateFileStream extends Writable {
             for (const name of candidates) {
                 const full = path.join(this.dir, name);
                 try {
-                    stats.push({ full, mtimeMs: (await fs.promises.stat(full)).mtimeMs });
+                    const st = await fs.promises.stat(full);
+                    stats.push({ full, mtimeMs: st.mtimeMs, size: st.size }); // size
                 }
                 catch {
                     /* raced deletion */
@@ -1035,18 +1217,30 @@ class RotateFileStream extends Writable {
             }
             stats.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
             const kill = new Set();
-            if (policy.days != null) {
+            if (policy?.days != null) {
                 const cutoff = this._now() - policy.days * 86_400_000;
                 for (const f of stats)
                     if (f.mtimeMs < cutoff)
                         kill.add(f.full);
             }
-            if (policy.count != null) {
+            if (policy?.count != null) {
                 const survivors = stats.filter((f) => !kill.has(f.full));
                 const excessCount = survivors.length - policy.count;
                 for (let i = 0; i < excessCount; i++)
                     kill.add(survivors[i].full);
             }
+            // byte budget — delete OLDEST until under budget.
+            // The active segment is never a candidate, so only archives count.
+            if (this.maxTotalSize > 0) {
+                const survivors = stats.filter((f) => !kill.has(f.full)); // oldest→newest
+                let total = survivors.reduce((sum, f) => sum + f.size, 0);
+                let i = 0;
+                while (total > this.maxTotalSize && i < survivors.length) {
+                    kill.add(survivors[i].full);
+                    total -= survivors[i].size;
+                    i++;
+                }
+            }
             if (kill.size === 0)
                 return;
             for (const file of kill) {
@@ -1074,4 +1268,64 @@ function createStream(options) {
     return new RotateFileStream(options);
 }
 
-export { RotateFileStream, createStream };
+const registry = new Set();
+let installed = false;
+let inProgress = false;
+/**
+ * Register streams for graceful shutdown: on SIGINT/SIGTERM every
+ * registered stream is ended — flushing buffered writes and finishing the
+ * audit manifest — before the process exits, with a hard deadline.
+ *
+ * Safe to call multiple times: process listeners install once, streams
+ * accumulate in the registry.
+ *
+ * Returns `flush()`, the same graceful end WITHOUT exiting — for tests
+ * and custom signal handling.
+ *
+ * @example
+ * const flush = installShutdown(logStream);
+ * process.on("exit", () => { void flush(); });
+ */
+function installShutdown(streams, opts = {}) {
+    const list = Array.isArray(streams) ? streams : [streams];
+    for (const s of list)
+        registry.add(s);
+    if (!installed) {
+        installed = true;
+        const timeoutMs = opts.timeoutMs ?? 5_000;
+        const code = opts.code ?? 0;
+        for (const sig of opts.signals ?? ["SIGINT", "SIGTERM"]) {
+            process.on(sig, () => {
+                void flushAll(timeoutMs).finally(() => process.exit(code));
+            });
+        }
+    }
+    return async () => {
+        // flush FIRST — flushAll() drains the registry, so unregistering
+        // before flushing would flush nothing (caught by the shutdown test)
+        await flushAll(opts.timeoutMs ?? 5_000);
+        for (const s of list)
+            registry.delete(s);
+    };
+}
+/**
+ * End every registered stream (flush buffered writes) with a deadline.
+ * Does NOT exit the process. Double-ending an already-ended stream is
+ * harmless — the error lands in the ignored callback.
+ */
+async function flushAll(timeoutMs = 5_000) {
+    if (inProgress)
+        return;
+    inProgress = true;
+    const deadline = setTimeout(() => process.exit(1), timeoutMs);
+    deadline.unref();
+    try {
+        await Promise.allSettled([...registry].map((s) => new Promise((res) => s.end(() => res()))));
+    }
+    finally {
+        clearTimeout(deadline);
+        inProgress = false;
+    }
+}
+
+export { RotateFileStream, createStream, flushAll, installShutdown };

package/dist/parsers.d.ts

@@ -12,5 +12,7 @@ export type ParsedFrequency = {
 export declare function parseSize(v: RotateFileStreamOptions["maxSize"]): number;
 export declare function parseMaxFiles(v: RotateFileStreamOptions["maxFiles"]): ParsedMaxFiles | null;
 export declare function parseFrequency(v: RotateFileStreamOptions["frequency"]): ParsedFrequency;
+/** Static virtual-clock shift. Accepts hours by default; h/hours/m/s/ms. */
 export declare function parseClockOffset(v: RotateFileStreamOptions["addHours"]): number;
+/** Per-tick virtual-clock step. Accepts hours by default; h/hours/m/s/ms. */
 export declare function parseClockStep(v: RotateFileStreamOptions["addHoursEveryMin"]): number;

package/dist/rotate-file-stream.d.ts

@@ -1,19 +1,24 @@
 import { Writable } from "node:stream";
 import { type ParsedFrequency, type ParsedMaxFiles } from "./parsers.js";
-import type { RotateFileStreamEventMap, RotateFileStreamOptions } from "./types.js";
+import type { RotateFileStreamEventMap, RotateFileStreamOptions, SegmentInfo, StreamStats } from "./types.js";
 /**
  * A `Writable` that appends to dated log files, rolling segments on time
- * and/or size, optionally gzipping sealed segments, enforcing retention,
- * and resuming an unbroken series across restarts via disk scan + audit
- * manifest.
+ * and/or size, optionally gzipping sealed segments, enforcing retention
+ * (count, age, and total-byte budget), maintaining a stable "current"
+ * symlink for log collectors, running an awaited seal hook (upload
+ * pipeline), and resuming an unbroken series across restarts via disk
+ * scan + audit manifest.
  *
  * @example
  * ```ts
  * const log = createStream({
  *   filename: "logs/app-%DATE%.log",
  *   maxSize: "20m",
+ *   maxTotalSize: "5g",
  *   maxFiles: "90d",
  *   zippedArchive: true,
+ *   symlink: true,
+ *   onSeal: async ({ gz }) => uploadToS3(gz),
  * });
  * log.write("hello\n");          // or: readable.pipe(log)
  * ```
@@ -28,6 +33,7 @@ export declare class RotateFileStream extends Writable {
     readonly maxFiles: Readonly<ParsedMaxFiles> | null;
     readonly freq: ParsedFrequency;
     readonly unrefTimers: boolean;
+    readonly maxTotalSize: number;
     private readonly _tL;
     private readonly _tMid;
     private readonly _tExt;
@@ -36,6 +42,10 @@ export declare class RotateFileStream extends Writable {
     private readonly _auditEnabled;
     private readonly _auditPath;
     private readonly _bootId;
+    private readonly _onSeal?;
+    private readonly _sealHookTimeoutMs;
+    private readonly _compressionLevel;
+    private _symlinkPath;
     private _offsetMs;
     private _stepMs;
     private _bumpEvery;
@@ -69,6 +79,15 @@ export declare class RotateFileStream extends Writable {
      * archive flow as a real midnight roll.
      */
     advanceClock(): Promise<void>;
+    /**
+     * Every family file on disk, oldest stamp first.
+     * Disk is truth: untracked files are reported with state "untracked".
+     */
+    listSegments(): SegmentInfo[];
+    /**
+     * Health-check snapshot for dashboards and support triage.
+     */
+    stats(): StreamStats;
     _write(chunk: Buffer, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
     _final(callback: (error?: Error | null) => void): void;
     destroy(...args: Parameters<Writable["destroy"]>): this;
@@ -89,6 +108,19 @@ export declare class RotateFileStream extends Writable {
      * The audit pointer (same stamp only) may only RAISE the result.
      */
     private _recoverIndexFor;
+    /**
+     * Atomically flip the "current" symlink to the active segment.
+     * tmp + rename so followers (`tail -f`, Filebeat) never observe a gap.
+     * Relative target keeps the link portable. Best-effort: filesystems
+     * denying symlinks warn once and disable the feature permanently.
+     */
+    private _updateSymlink;
+    /**
+     * Await the user's onSeal hook with a hard timeout. Result or
+     * failure degrades to `warn` — a wedged upload must never stall rotation.
+     * Called BEFORE retention so uploads finish before deletion.
+     */
+    private _runSealHook;
     private _ensureOpen;
     private _rotate;
     private _hasContent;

package/dist/shutdown.d.ts

@@ -0,0 +1,32 @@
+import type { RotateFileStream } from "./rotate-file-stream.js";
+export interface ShutdownOptions {
+    /** Signals to listen on. @default ["SIGINT", "SIGTERM"] */
+    signals?: NodeJS.Signals[];
+    /** Hard-exit deadline (ms) if a stream refuses to end.
+     * @default 5000 */
+    timeoutMs?: number;
+    /** Process exit code. @default 0 */
+    code?: number;
+}
+/**
+ * Register streams for graceful shutdown: on SIGINT/SIGTERM every
+ * registered stream is ended — flushing buffered writes and finishing the
+ * audit manifest — before the process exits, with a hard deadline.
+ *
+ * Safe to call multiple times: process listeners install once, streams
+ * accumulate in the registry.
+ *
+ * Returns `flush()`, the same graceful end WITHOUT exiting — for tests
+ * and custom signal handling.
+ *
+ * @example
+ * const flush = installShutdown(logStream);
+ * process.on("exit", () => { void flush(); });
+ */
+export declare function installShutdown(streams: RotateFileStream | RotateFileStream[], opts?: ShutdownOptions): () => Promise<void>;
+/**
+ * End every registered stream (flush buffered writes) with a deadline.
+ * Does NOT exit the process. Double-ending an already-ended stream is
+ * harmless — the error lands in the ignored callback.
+ */
+export declare function flushAll(timeoutMs?: number): Promise<void>;