npm - logroller - Versions diffs - 2.0.0 → 2.0.2 - Mend

logroller 2.0.0 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md +50 -4
package/README.md +57 -55
package/dist/index.cjs +184 -40
package/dist/index.esm.js +184 -40
package/dist/rotate-file-stream.d.ts +19 -6
package/package.json +1 -1

package/CHANGELOG.md CHANGED Viewed

@@ -5,6 +5,49 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [2.0.2] — 2026-08-28
+### Fixed
+- **Corrupt audit manifest quarantine**: an unparseable `<stem>_audit.json`
+  (partial write, bad edit) is now renamed to `.corrupt` and preserved,
+  matching existing behaviour for version/family mismatches. Previously it
+  was silently overwritten by the first manifest save, destroying the
+  event journal.
+- **Backward-clock safety**: a clock moving backward (NTP correction,
+  manual change) no longer reopens a past log family or forks the segment
+  series. The stream keeps the current segment, warns once, and resumes
+  normal rotation when the clock catches up.
+- **Timer anti-spin**: with the rotation boundary in the past (backward
+  clock), the timer now polls at 1 s instead of firing every 100 ms,
+  which previously could keep processes from exiting cleanly.
+### Added
+- **Construction-time pattern warning**: warns when `frequency` is finer
+  than the `datePattern` tokens allow (`daily`→`DD`, sub-daily→`HH`,
+  sub-minute→`mm`), preventing silent filename collisions where many
+  rotations overwrite a single file.
+### Tests
+- Suite expanded to 23 tests: interrupted-gzip repair, manifest divergence
+  healing (`archive-regressed`, `vanished`), manifest quarantine,
+  concurrent-writer detection, IST-midnight boundary, idle `period` slide,
+  `rotateNow()`, over-max resume, backward-clock guard, and coarse-pattern
+  warning.
+## [2.0.1] — 2026-08-27
+### Fixed
+- Reactivated segments no longer inherit stale lifecycle timestamps
+  (`abandonedAt` could predate `openedAt`).
+- Raw tails of already-passed periods are now gzipped at boot
+  (crash-near-midnight no longer leaves yesterday's file uncompressed).
+- Rotation adopts a `.gz` produced by a (warned-about) concurrent writer
+  instead of recording a false `drop-empty` that orphaned the archive.
 ## [2.0.0] — 2026-08-28
 Architecture release: the library moved from a single-file JavaScript SDK to a
@@ -17,6 +60,7 @@ TypeScript consumers gain full type coverage.
 > upgrading — mostly due to the deterministic boot-order fix below.
 ### Added
 - **Full TypeScript source with shipped declarations** (`dist/index.d.ts`);
   strict-mode compile (`noImplicitOverride`, `noUnusedLocals`,
   `verbatimModuleSyntax`, …).
@@ -30,13 +74,13 @@ TypeScript consumers gain full type coverage.
 - Modular source layout (`src/types.ts`, `parsers.ts`, `time.ts`, `fsio.ts`,
   `rotate-file-stream.ts`) with `.js` extension imports so emitted
   declarations resolve under `nodenext` consumers.
-- Developer toolchain: ESLint 9 flat config + typescript-eslint, Prettier,
-  EditorConfig, `npm run verify` gate (lint + typecheck + build + tests).
+- Developer toolchain: Prettier, `npm run verify` gate (typecheck + build + tests).
 - GitHub Actions: CI matrix on Node 18/20/22, release-triggered publish with
   npm provenance (`id-token: write`, `--provenance`).
 - Expanded README: comparison table, FAQ, restart-resume matrix, pino recipe.
 ### Fixed
 - **Deterministic boot sequencing**: housekeeping (zombie demotion, disk
   reconciliation, interrupted-gzip repair) is chained as job #1 of the
   serial operation queue in the constructor instead of `process.nextTick`,
@@ -45,6 +89,7 @@ TypeScript consumers gain full type coverage.
 - Retention sweep skips `<audit>.corrupt` artifacts alongside `.tmp`.
 ### Changed
 - Internals restructured behind the same public exports; barrels re-export
   types explicitly (`import type { RotatedInfo } from "logroller"`).
 - Stricter package hygiene metadata: `sideEffects: false`, explicit
@@ -54,7 +99,7 @@ TypeScript consumers gain full type coverage.
   manifest creation, size rotation/gzip/indexing, restart resume,
   `addHours` naming, virtual midnight crossing, count-retention ordering
   (mtime-deterministic), zombie-record lifecycle (`abandon → active →
-  closed`), and CJS loadability through the exports map.
+closed`), and CJS loadability through the exports map.
 ## [1.0.0] — 2026-08-26
@@ -63,6 +108,7 @@ Initial release. Single-file zero-dependency JavaScript SDK
 rotation.
 ### Added
 - Time-based rotation: `frequency: "daily"` (local midnight in any IANA
   timezone via `Intl`) or epoch-aligned intervals (`"30s"`, `"5m"`, `"2h"`).
 - Size-based rotation: `maxSize` (`"20m"` / `"512k"` / raw bytes) producing
@@ -84,4 +130,4 @@ rotation.
   (`addHoursEveryMin`).
 - Dual-format distribution (ESM + CJS) bundled with Rollup; named exports
   `createStream` and `RotateFileStream`; factory options mirroring common
-  rotator APIs; streams pipe-ready for pino multistreams.
+  rotator APIs; streams pipe-ready for pino multistreams.

package/README.md CHANGED Viewed

@@ -1,4 +1,3 @@
 ## README.md
 <p align="center"><strong>logroller</strong></p>
@@ -72,11 +71,14 @@ const { createStream } = require("logroller");
 ### pino destination
 ```js
-const logger = pino(pino.multistream([
-  { level: "info", stream: createStream({ filename: "logs/general-%DATE%.log" }) },
-  { level: "error", stream: createStream({ filename: "logs/error-%DATE%.log" }) },
-]));
+const logger = pino(
+  pino.multistream([
+    { level: "info", stream: createStream({ filename: "logs/general-%DATE%.log" }) },
+    { level: "error", stream: createStream({ filename: "logs/error-%DATE%.log" }) },
+  ]),
+);
 ```
 ## What lands on disk
 ```
@@ -90,12 +92,12 @@ app_audit.json              ← library-owned manifest
 A killed process resumes without gaps or duplicates:
-| Disk at crash | Restart continues into |
-|---|---|
-| `app-D.log` | `app-D.log` (append) |
-| `app-D.log.gz` + `app-D.1.log` | `app-D.1.log` |
-| `app-D.1.log.gz` (chain sealed) | `app-D.2.log` |
-| died during a gzip | boot finishes the gzip, then proceeds |
+| Disk at crash                   | Restart continues into                |
+| ------------------------------- | ------------------------------------- |
+| `app-D.log`                     | `app-D.log` (append)                  |
+| `app-D.log.gz` + `app-D.1.log`  | `app-D.1.log`                         |
+| `app-D.1.log.gz` (chain sealed) | `app-D.2.log`                         |
+| died during a gzip              | boot finishes the gzip, then proceeds |
 ## API
@@ -103,41 +105,41 @@ A killed process resumes without gaps or duplicates:
 ### Options
-| Option | Values | Default |
-|---|---|---|
-| `filename` | **required**, must contain `%DATE%` | — |
-| `datePattern` | `YYYY YY MM DD HH mm ss` | `YYYY-MM-DD` |
-| `zippedArchive` | boolean | `false` |
-| `maxSize` | `20m`, `512k`, `2g`, bytes, `0`=off | off |
-| `maxFiles` | `"90d"` age, `500` count, unset=never | — |
-| `frequency` | `daily`, `30s`, `5m`, `2h`, ms | `daily` |
-| `tz` | any IANA zone | `UTC` |
-| `audit` / `auditFile` | manifest control | `true` / auto-name |
-| `unrefTimers` | detach from event loop | `false` |
-| `addHours` | ⚠️ static clock shift, test only | off |
-| `addHoursEveryMin` | ⚠️ virtual time per tick, test only | off |
-| `clockStepIntervalMs` | tick interval | `60000` |
+| Option                | Values                                | Default            |
+| --------------------- | ------------------------------------- | ------------------ |
+| `filename`            | **required**, must contain `%DATE%`   | —                  |
+| `datePattern`         | `YYYY YY MM DD HH mm ss`              | `YYYY-MM-DD`       |
+| `zippedArchive`       | boolean                               | `false`            |
+| `maxSize`             | `20m`, `512k`, `2g`, bytes, `0`=off   | off                |
+| `maxFiles`            | `"90d"` age, `500` count, unset=never | —                  |
+| `frequency`           | `daily`, `30s`, `5m`, `2h`, ms        | `daily`            |
+| `tz`                  | any IANA zone                         | `UTC`              |
+| `audit` / `auditFile` | manifest control                      | `true` / auto-name |
+| `unrefTimers`         | detach from event loop                | `false`            |
+| `addHours`            | ⚠️ static clock shift, test only      | off                |
+| `addHoursEveryMin`    | ⚠️ virtual time per tick, test only   | off                |
+| `clockStepIntervalMs` | tick interval                         | `60000`            |
 ### Methods
-| Method | Returns | Purpose |
-|---|---|---|
-| `write / end / destroy` | stream semantics | normal `Writable` |
-| `rotateNow()` | `Promise<void>` | force a rotation |
-| `advanceClock()` | `Promise<void>` | apply one virtual tick now |
+| Method                  | Returns          | Purpose                    |
+| ----------------------- | ---------------- | -------------------------- |
+| `write / end / destroy` | stream semantics | normal `Writable`          |
+| `rotateNow()`           | `Promise<void>`  | force a rotation           |
+| `advanceClock()`        | `Promise<void>`  | apply one virtual tick now |
 ### Events (typed)
-| Event | Payload | Meaning |
-|---|---|---|
-| `open` | `file` | segment opened for appending |
-| `rotated` | `{reason, oldFile, archive, newFile}` | segment closed |
-| `archive` | `gzFile` | gzip finished |
-| `deleted` | `file` | retention removed it |
-| `period` | `stamp` | boundary crossed while idle |
-| `clock` | `{offsetMs, …}` | virtual clock engaged |
-| `warn` | `Error` | non-fatal problems |
-| `error` | `Error` | fatal write problems |
+| Event     | Payload                               | Meaning                      |
+| --------- | ------------------------------------- | ---------------------------- |
+| `open`    | `file`                                | segment opened for appending |
+| `rotated` | `{reason, oldFile, archive, newFile}` | segment closed               |
+| `archive` | `gzFile`                              | gzip finished                |
+| `deleted` | `file`                                | retention removed it         |
+| `period`  | `stamp`                               | boundary crossed while idle  |
+| `clock`   | `{offsetMs, …}`                       | virtual clock engaged        |
+| `warn`    | `Error`                               | non-fatal problems           |
+| `error`   | `Error`                               | fatal write problems         |
 Errors must be handled — attach a listener on every instance.
@@ -147,21 +149,21 @@ Errors must be handled — attach a listener on every instance.
 const s = createStream({
   filename: "logs/demo-%DATE%.log",
   zippedArchive: true,
-  addHoursEveryMin: "24h",     // one day per real minute
-  clockStepIntervalMs: 1000,   // or faster
+  addHoursEveryMin: "24h", // one day per real minute
+  clockStepIntervalMs: 1000, // or faster
 });
-await s.advanceClock();         // jump instantly when useful
+await s.advanceClock(); // jump instantly when useful
 ```
 ## FAQ
 **Why is `%DATE%` mandatory?**
-It is the anchor that decouples *rotation scheduling* from *filenames*.
+It is the anchor that decouples _rotation scheduling_ from _filenames_.
 Coarser patterns than your frequency collapse distinct segments onto one
 name — match tokens to cadence (`HH` for hourly, etc.).
 **Can two processes share one directory?**
-Different prefixes/families: yes. The *same* family: no — the audit
+Different prefixes/families: yes. The _same_ family: no — the audit
 manifest detects a live second writer (`writer.heartbeat`) and warns loudly.
 **Is the audit JSON required?**
@@ -174,19 +176,19 @@ Pure Node APIs; path handling via `node:path`. All three supported
 ## Compare
-| | logroller | file-stream-rotator | rotating-file-stream | winston-daily-rotate-file |
-|---|---|---|---|---|
-| Dependencies | **0** | 4+ | 2+ | winston-bound |
-| Crash-safe resume | ✅ audit-assisted | partial | partial | ✖ |
-| Interrupted-gzip repair | ✅ | ✖ | ✖ | ✖ |
-| Event journal | ✅ | ✖ | ✖ | ✖ |
-| TZ-correct daily rollover | ✅ | partial | ✅ | ✅ |
-| Virtual test clock | ✅ | ✖ | ✖ | ✖ |
-| Winston required | no | no | no | yes |
+|                           | logroller         | file-stream-rotator | rotating-file-stream | winston-daily-rotate-file |
+| ------------------------- | ----------------- | ------------------- | -------------------- | ------------------------- |
+| Dependencies              | **0**             | 4+                  | 2+                   | winston-bound             |
+| Crash-safe resume         | ✅ audit-assisted | partial             | partial              | ✖                         |
+| Interrupted-gzip repair   | ✅                | ✖                   | ✖                    | ✖                         |
+| Event journal             | ✅                | ✖                   | ✖                    | ✖                         |
+| TZ-correct daily rollover | ✅                | partial             | ✅                   | ✅                        |
+| Virtual test clock        | ✅                | ✖                   | ✖                    | ✖                         |
+| Winston required          | no                | no                  | no                   | yes                       |
 ## Contributing
-PRs welcome. `npm run verify` gates every change (lint + typecheck + tests).
+PRs welcome. `npm run verify` gates every change (typecheck + tests).
 Please file issues before large refactors.
 ## License

package/dist/index.cjs CHANGED Viewed

@@ -1,4 +1,4 @@
-/*! logroller v1.0.0 | MIT License */
+/*! logroller v2.0.1 | MIT License */
 'use strict';
 var node_crypto = require('node:crypto');
@@ -52,12 +52,21 @@ const UNITS = {
 const FREQ_MULT = {
     ms: 1, s: 1000, m: 60_000, h: 3_600_000,
 };
+function parseDuration(value, defaultUnit, fieldName) {
+    if (typeof value === "number") {
+        return Math.round(value * FREQ_MULT[defaultUnit]);
+    }
+    const m = /^\s*(-?\d+(?:\.\d+)?)\s*(ms|s|m|h)?\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()]);
+}
 function parseSize(v) {
     if (v === undefined || v === null || v === 0)
         return 0;
     if (typeof v === "number")
         return v;
-    const m = /^\s*(\d+(?:\.\d+)?)\s*(b|k|kb|m|mb|g|gb)?\s*$/i.exec(v);
+    const m = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|k|mb|m|gb|g)?\s*$/i.exec(v);
     if (!m)
         throw new Error(`Invalid maxSize "${v}"`);
     return Math.round(Number.parseFloat(m[1]) * (UNITS[m[2]?.toLowerCase()] ?? 1));
@@ -81,7 +90,7 @@ function parseFrequency(v) {
     if (v === "daily")
         return { type: "daily" };
     if (typeof v === "number") {
-        if (!(v > 0))
+        if (v <= 0)
             throw new Error(`Invalid frequency "${v}"`);
         return { type: "interval", ms: v };
     }
@@ -93,22 +102,12 @@ function parseFrequency(v) {
 function parseClockOffset(v) {
     if (v === undefined || v === null || v === "")
         return 0;
-    if (typeof v === "number")
-        return Math.round(v * 3_600_000);
-    const m = /^\s*(-?\d+(?:\.\d+)?)\s*h(?:our)?s?\s*$/i.exec(v);
-    if (!m)
-        throw new Error(`Invalid addHours "${v}"`);
-    return Math.round(Number.parseFloat(m[1]) * 3_600_000);
+    return parseDuration(v, "h", "addHours");
 }
 function parseClockStep(v) {
-    if (v === undefined || v === null || v === "" || v === 0)
+    if (v === undefined || v === null || v === "")
         return 0;
-    if (typeof v === "number")
-        return Math.round(v * 3_600_000);
-    const m = /^\s*(-?\d+(?:\.\d+)?)\s*(ms|s|m|h)?\s*$/i.exec(v);
-    if (!m)
-        throw new Error(`Invalid addHoursEveryMin "${v}"`);
-    return Math.round(Number.parseFloat(m[1]) * FREQ_MULT[(m[2] ?? "h").toLowerCase()]);
+    return parseDuration(v, "h", "addHours");
 }
 /* Timezone-aware helpers built exclusively on Intl (zero deps). */
@@ -145,11 +144,30 @@ function partsIn(tz, date) {
 const pad2 = (n) => n.padStart(2, "0");
 /** Escape a literal string for embedding inside a RegExp. */
 function escRe(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return s.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
 }
 /** Substitute YYYY|YY|MM|DD|HH|mm|ss tokens in `pattern`. */
 function formatStamp(pattern, parts) {
-    return pattern.replace(/YYYY|YY|MM|DD|HH|mm|ss/g, (t) => t === "YYYY" ? parts.year : t === "YY" ? parts.year.slice(-2) : t === "MM" ? pad2(parts.month) : t === "DD" ? pad2(parts.day) : t === "HH" ? pad2(parts.hour) : t === "mm" ? pad2(parts.minute) : t === "ss" ? pad2(parts.second) : t);
+    return pattern.replace(/YYYY|YY|MM|DD|HH|mm|ss/g, (token) => {
+        switch (token) {
+            case "YYYY":
+                return parts.year;
+            case "YY":
+                return parts.year.slice(-2);
+            case "MM":
+                return pad2(parts.month);
+            case "DD":
+                return pad2(parts.day);
+            case "HH":
+                return pad2(parts.hour);
+            case "mm":
+                return pad2(parts.minute);
+            case "ss":
+                return pad2(parts.second);
+            default:
+                return token;
+        }
+    });
 }
 /** Offset of `tz` vs UTC at instant `date`, milliseconds. */
 function tzOffsetMs(tz, date) {
@@ -179,6 +197,7 @@ const BUMP_DEFAULT_MS = 60_000;
 const AUDIT_MAX_FILES = 600;
 const AUDIT_MAX_EVENTS = 200;
 const HEARTBEAT_STALE_MS = 30_000;
+const TIMER_POLL_MS = 1_000;
 const emptyAudit = (prefix, ext, datePattern, tz) => ({
     version: 1,
     prefix,
@@ -244,6 +263,7 @@ class RotateFileStream extends node_stream.Writable {
     _bumpTimer = null;
     _ended = false;
     _tail = Promise.resolve();
+    _warnedBackward = false;
     _audit;
     constructor(opts = {}) {
         super(opts.highWaterMark ? { highWaterMark: opts.highWaterMark } : {});
@@ -296,10 +316,26 @@ class RotateFileStream extends node_stream.Writable {
                 offsetMs: this._offsetMs,
             }));
         }
+        process.nextTick(() => {
+            const warn = (m) => this.emit("warn", new Error(m));
+            if (this.freq.type === "interval") {
+                if (this.freq.ms < 86_400_000 && !this.datePattern.includes("HH")) {
+                    warn(`frequency "${opts.frequency}" needs HH in datePattern — ` +
+                        "segments would collapse onto one filename");
+                }
+                if (this.freq.ms < 60_000 && !this.datePattern.includes("mm")) {
+                    warn(`frequency "${opts.frequency}" needs mm in datePattern`);
+                }
+            }
+            else if (!this.datePattern.includes("DD")) {
+                warn("daily frequency needs DD in datePattern");
+            }
+        });
         /* Boot housekeeping is job #1 of the serial queue — chained HERE in the
            constructor so it deterministically precedes any write job: zombie
            demotion sees `_path === null`, gzip repair cannot race a reopen.  */
         this._job(async () => {
+            await this._sealOrphanedPastStamps();
             if (this._auditEnabled) {
                 this._demoteZombieActives();
                 this._reconcileWithDisk();
@@ -337,9 +373,7 @@ class RotateFileStream extends node_stream.Writable {
     get currentIndex() {
         return this._index;
     }
-    /**
-     * Force an immediate rotation and resolve when the next slot is staged.
-     */
+    /** Force an immediate rotation and resolve when the next slot is staged. */
     rotateNow() {
         return this._job(() => this._rotate("manual"));
     }
@@ -362,8 +396,8 @@ class RotateFileStream extends node_stream.Writable {
         const len = chunk.length;
         this._job(async () => {
             try {
-                const stamp = this._stampNow();
-                if (stamp !== this._curStamp)
+                // guarded roll (never rotates into a regressed stamp)
+                if (this._stampAdvanced(this._stampNow()))
                     await this._rotate("time");
                 await this._ensureOpen();
                 if (this.maxSize > 0 &&
@@ -434,6 +468,22 @@ class RotateFileStream extends node_stream.Writable {
             ? base.replace(/\.[^.]+$/, `.${index}$&`)
             : `${base}.${index}`;
     }
+    /**
+     * true only when the period legally advanced. A regressed
+     * clock (NTP correction, manual change) never reopens a past family:
+     * writes continue in the current segment until real time catches up.
+     * Requires zero-padded datePattern tokens (documented assumption).
+     */
+    _stampAdvanced(stamp) {
+        if (stamp > this._curStamp)
+            return true;
+        if (stamp < this._curStamp && !this._warnedBackward) {
+            this._warnedBackward = true;
+            this.emit("warn", new Error(`clock moved backward (stamp ${stamp} < ${this._curStamp}); ` +
+                "keeping current segment until the clock catches up"));
+        }
+        return false;
+    }
     /**
      * Highest viable segment index for `stamp`.
      * Disk is truth: resume a raw tail; start after sealed ones.
@@ -478,9 +528,10 @@ class RotateFileStream extends node_stream.Writable {
         this._path = p;
         if (this._auditEnabled) {
             const base = path.basename(p);
-            const prev = this._audit.files[base];
+            // reopen = NEW incarnation. Never inherit lifecycle
+            // fields from the previous record (observed in the wild as
+            // abandonedAt < openedAt on reactivated segments).
             this._audit.files[base] = {
-                ...(prev && prev.state === "archived" ? {} : prev),
                 index: this._index,
                 state: "active",
                 gzipPending: false,
@@ -531,22 +582,42 @@ class RotateFileStream extends node_stream.Writable {
                 }
             }
             else if (realBytes === 0) {
-                try {
-                    fs.unlinkSync(oldPath);
+                // a concurrent writer may have archived this segment
+                // between our last stat and now — adopt its artifact instead of
+                // recording a false `drop-empty` that orphans the .gz.
+                const adoptedGz = `${oldPath}.gz`;
+                if (existsSafe(adoptedGz)) {
+                    this._finishArchivedRecord(oldBase);
+                    archive = adoptedGz;
                 }
-                catch {
-                    /* already gone */
+                else {
+                    try {
+                        fs.unlinkSync(oldPath);
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                    if (rec)
+                        delete this._audit.files[oldBase];
+                    this._aevent("drop-empty", { file: oldBase });
                 }
-                if (rec)
-                    delete this._audit.files[oldBase];
-                this._aevent("drop-empty", { file: oldBase });
             }
             else if (rec) {
                 rec.state = "sealed";
                 rec.bytes = realBytes;
             }
         }
-        const stamp = this._stampNow();
+        let stamp = this._stampNow();
+        // a rotation itself must never move the series backward
+        // (covers rotateNow()/interval/size paths the upstream guards miss)
+        if (stamp < this._curStamp) {
+            if (!this._warnedBackward) {
+                this._warnedBackward = true;
+                this.emit("warn", new Error(`clock moved backward (stamp ${stamp} < ${this._curStamp}); ` +
+                    "rotation clamped to the current period"));
+            }
+            stamp = this._curStamp;
+        }
         const newPeriod = stamp !== this._curStamp;
         this._curStamp = stamp;
         /* Never blind-reset to 0 — recover what THIS stamp already owns. */
@@ -588,16 +659,26 @@ class RotateFileStream extends node_stream.Writable {
         const next = this.freq.type === "daily"
             ? nextMidnight(this.tz, now)
             : nextAligned(now, this.freq.ms);
+        // anti-spin. A backward clock can put the computed
+        // boundary in the past; poll gently instead of firing every 100 ms.
+        const delta = next - this._now();
+        const delay = delta < 0 ? TIMER_POLL_MS : Math.max(100, delta);
         this._timer = setTimeout(() => {
             this._job(async () => {
                 const stamp = this._stampNow();
-                const dueDaily = this.freq.type === "daily" && stamp !== this._curStamp;
-                const dueInterval = this.freq.type !== "daily";
-                if (dueDaily || dueInterval) {
+                if (this.freq.type !== "daily") {
+                    /* interval rotation is schedule-based; runs regardless of
+                       stamp movement */
+                    if (this._hasContent())
+                        await this._rotate("time");
+                }
+                else if (this._stampAdvanced(stamp)) {
+                    // guarded daily branch
                     if (this._hasContent()) {
                         await this._rotate("time");
                     }
-                    else if (stamp !== this._curStamp) {
+                    else {
+                        /* idle boundary slide — no file created for empty days */
                         this._curStamp = stamp;
                         this._index = this._recoverIndexFor(stamp);
                         if (this._auditEnabled) {
@@ -608,9 +689,10 @@ class RotateFileStream extends node_stream.Writable {
                         this.emit("period", stamp);
                     }
                 }
+                /* stamp regressed or unchanged → keep current segment, re-arm */
                 this._armTimer();
             }).catch(() => { });
-        }, Math.max(100, next - this._now()));
+        }, delay);
         if (this.unrefTimers)
             this._timer.unref();
     }
@@ -634,7 +716,8 @@ class RotateFileStream extends node_stream.Writable {
         this._offsetMs += this._stepMs;
         this._armTimer();
         const stamp = this._stampNow();
-        if (stamp !== this._curStamp) {
+        // guarded crossing (virtual clock can't roll backward either)
+        if (this._stampAdvanced(stamp)) {
             if (this._hasContent()) {
                 await this._rotate("time");
             }
@@ -672,7 +755,15 @@ class RotateFileStream extends node_stream.Writable {
             parsed = JSON.parse(fs.readFileSync(this._auditPath, "utf8"));
         }
         catch {
-            return false; // missing/unreadable → fresh start
+            // unparseable manifest is quarantined too (was silently
+            // clobbered by the first save — caught by the quarantine test)
+            try {
+                fs.renameSync(this._auditPath, `${this._auditPath}.corrupt`);
+            }
+            catch {
+                /* ignore */
+            }
+            return false;
         }
         const j = parsed;
         if (!j || j.version !== 1 || j.prefix !== this._tL || j.ext !== this._tExt) {
@@ -809,6 +900,59 @@ class RotateFileStream extends node_stream.Writable {
             delete this._audit.files[name];
         }
     }
+    /**
+     * DISK-DRIVEN seal. Seal raw segments whose period has
+     * already passed (crash near midnight, virtual-clock leftovers,
+     * untracked/pruned files). Iterates the DIRECTORY, not the manifest:
+     * the filesystem is the source of truth; the manifest is an index.
+     */
+    async _sealOrphanedPastStamps() {
+        if (!this.zippedArchive)
+            return;
+        const stampRx = new RegExp("^" + escRe(this._tL) + "(.+?)" + escRe(this._tMid) +
+            "(?:\\.\\d+)?" + escRe(this._tExt) + "(?:\\.gz)?$");
+        let names = [];
+        try {
+            names = fs.readdirSync(this.dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name.endsWith(".gz"))
+                continue;
+            if (name === (this._path && path.basename(this._path)))
+                continue;
+            const stamp = stampRx.exec(name)?.[1];
+            // lexicographic compare is safe for zero-padded patterns (YYYY-MM-DD…);
+            // also guards the current stamp and anything future-dated
+            if (!stamp || stamp >= this._curStamp)
+                continue;
+            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));
+            if (!ok)
+                continue;
+            if (this._auditEnabled && this._audit.files[name]) {
+                // tracked → re-key record name → name.gz (emits archive + journal)
+                this._finishArchivedRecord(name, true);
+            }
+            else {
+                // untracked → record it fresh so future reconciles see truth
+                const gzName = `${name}.gz`;
+                if (this._auditEnabled) {
+                    this._audit.files[gzName] = {
+                        state: "archived",
+                        gzipPending: false,
+                        archivedAt: new Date().toISOString(),
+                    };
+                    this._aevent("seal-past", { file: gzName });
+                }
+                this.emit("archive", path.join(this.dir, gzName));
+            }
+        }
+    }
     async _repairInterruptedGzips() {
         for (const [name, rec] of Object.entries(this._audit.files)) {
             if (!rec.gzipPending)

package/dist/index.esm.js CHANGED Viewed

@@ -1,4 +1,4 @@
-/*! logroller v1.0.0 | MIT License */
+/*! logroller v2.0.1 | MIT License */
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -50,12 +50,21 @@ const UNITS = {
 const FREQ_MULT = {
     ms: 1, s: 1000, m: 60_000, h: 3_600_000,
 };
+function parseDuration(value, defaultUnit, fieldName) {
+    if (typeof value === "number") {
+        return Math.round(value * FREQ_MULT[defaultUnit]);
+    }
+    const m = /^\s*(-?\d+(?:\.\d+)?)\s*(ms|s|m|h)?\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()]);
+}
 function parseSize(v) {
     if (v === undefined || v === null || v === 0)
         return 0;
     if (typeof v === "number")
         return v;
-    const m = /^\s*(\d+(?:\.\d+)?)\s*(b|k|kb|m|mb|g|gb)?\s*$/i.exec(v);
+    const m = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|k|mb|m|gb|g)?\s*$/i.exec(v);
     if (!m)
         throw new Error(`Invalid maxSize "${v}"`);
     return Math.round(Number.parseFloat(m[1]) * (UNITS[m[2]?.toLowerCase()] ?? 1));
@@ -79,7 +88,7 @@ function parseFrequency(v) {
     if (v === "daily")
         return { type: "daily" };
     if (typeof v === "number") {
-        if (!(v > 0))
+        if (v <= 0)
             throw new Error(`Invalid frequency "${v}"`);
         return { type: "interval", ms: v };
     }
@@ -91,22 +100,12 @@ function parseFrequency(v) {
 function parseClockOffset(v) {
     if (v === undefined || v === null || v === "")
         return 0;
-    if (typeof v === "number")
-        return Math.round(v * 3_600_000);
-    const m = /^\s*(-?\d+(?:\.\d+)?)\s*h(?:our)?s?\s*$/i.exec(v);
-    if (!m)
-        throw new Error(`Invalid addHours "${v}"`);
-    return Math.round(Number.parseFloat(m[1]) * 3_600_000);
+    return parseDuration(v, "h", "addHours");
 }
 function parseClockStep(v) {
-    if (v === undefined || v === null || v === "" || v === 0)
+    if (v === undefined || v === null || v === "")
         return 0;
-    if (typeof v === "number")
-        return Math.round(v * 3_600_000);
-    const m = /^\s*(-?\d+(?:\.\d+)?)\s*(ms|s|m|h)?\s*$/i.exec(v);
-    if (!m)
-        throw new Error(`Invalid addHoursEveryMin "${v}"`);
-    return Math.round(Number.parseFloat(m[1]) * FREQ_MULT[(m[2] ?? "h").toLowerCase()]);
+    return parseDuration(v, "h", "addHours");
 }
 /* Timezone-aware helpers built exclusively on Intl (zero deps). */
@@ -143,11 +142,30 @@ function partsIn(tz, date) {
 const pad2 = (n) => n.padStart(2, "0");
 /** Escape a literal string for embedding inside a RegExp. */
 function escRe(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return s.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
 }
 /** Substitute YYYY|YY|MM|DD|HH|mm|ss tokens in `pattern`. */
 function formatStamp(pattern, parts) {
-    return pattern.replace(/YYYY|YY|MM|DD|HH|mm|ss/g, (t) => t === "YYYY" ? parts.year : t === "YY" ? parts.year.slice(-2) : t === "MM" ? pad2(parts.month) : t === "DD" ? pad2(parts.day) : t === "HH" ? pad2(parts.hour) : t === "mm" ? pad2(parts.minute) : t === "ss" ? pad2(parts.second) : t);
+    return pattern.replace(/YYYY|YY|MM|DD|HH|mm|ss/g, (token) => {
+        switch (token) {
+            case "YYYY":
+                return parts.year;
+            case "YY":
+                return parts.year.slice(-2);
+            case "MM":
+                return pad2(parts.month);
+            case "DD":
+                return pad2(parts.day);
+            case "HH":
+                return pad2(parts.hour);
+            case "mm":
+                return pad2(parts.minute);
+            case "ss":
+                return pad2(parts.second);
+            default:
+                return token;
+        }
+    });
 }
 /** Offset of `tz` vs UTC at instant `date`, milliseconds. */
 function tzOffsetMs(tz, date) {
@@ -177,6 +195,7 @@ const BUMP_DEFAULT_MS = 60_000;
 const AUDIT_MAX_FILES = 600;
 const AUDIT_MAX_EVENTS = 200;
 const HEARTBEAT_STALE_MS = 30_000;
+const TIMER_POLL_MS = 1_000;
 const emptyAudit = (prefix, ext, datePattern, tz) => ({
     version: 1,
     prefix,
@@ -242,6 +261,7 @@ class RotateFileStream extends Writable {
     _bumpTimer = null;
     _ended = false;
     _tail = Promise.resolve();
+    _warnedBackward = false;
     _audit;
     constructor(opts = {}) {
         super(opts.highWaterMark ? { highWaterMark: opts.highWaterMark } : {});
@@ -294,10 +314,26 @@ class RotateFileStream extends Writable {
                 offsetMs: this._offsetMs,
             }));
         }
+        process.nextTick(() => {
+            const warn = (m) => this.emit("warn", new Error(m));
+            if (this.freq.type === "interval") {
+                if (this.freq.ms < 86_400_000 && !this.datePattern.includes("HH")) {
+                    warn(`frequency "${opts.frequency}" needs HH in datePattern — ` +
+                        "segments would collapse onto one filename");
+                }
+                if (this.freq.ms < 60_000 && !this.datePattern.includes("mm")) {
+                    warn(`frequency "${opts.frequency}" needs mm in datePattern`);
+                }
+            }
+            else if (!this.datePattern.includes("DD")) {
+                warn("daily frequency needs DD in datePattern");
+            }
+        });
         /* Boot housekeeping is job #1 of the serial queue — chained HERE in the
            constructor so it deterministically precedes any write job: zombie
            demotion sees `_path === null`, gzip repair cannot race a reopen.  */
         this._job(async () => {
+            await this._sealOrphanedPastStamps();
             if (this._auditEnabled) {
                 this._demoteZombieActives();
                 this._reconcileWithDisk();
@@ -335,9 +371,7 @@ class RotateFileStream extends Writable {
     get currentIndex() {
         return this._index;
     }
-    /**
-     * Force an immediate rotation and resolve when the next slot is staged.
-     */
+    /** Force an immediate rotation and resolve when the next slot is staged. */
     rotateNow() {
         return this._job(() => this._rotate("manual"));
     }
@@ -360,8 +394,8 @@ class RotateFileStream extends Writable {
         const len = chunk.length;
         this._job(async () => {
             try {
-                const stamp = this._stampNow();
-                if (stamp !== this._curStamp)
+                // guarded roll (never rotates into a regressed stamp)
+                if (this._stampAdvanced(this._stampNow()))
                     await this._rotate("time");
                 await this._ensureOpen();
                 if (this.maxSize > 0 &&
@@ -432,6 +466,22 @@ class RotateFileStream extends Writable {
             ? base.replace(/\.[^.]+$/, `.${index}$&`)
             : `${base}.${index}`;
     }
+    /**
+     * true only when the period legally advanced. A regressed
+     * clock (NTP correction, manual change) never reopens a past family:
+     * writes continue in the current segment until real time catches up.
+     * Requires zero-padded datePattern tokens (documented assumption).
+     */
+    _stampAdvanced(stamp) {
+        if (stamp > this._curStamp)
+            return true;
+        if (stamp < this._curStamp && !this._warnedBackward) {
+            this._warnedBackward = true;
+            this.emit("warn", new Error(`clock moved backward (stamp ${stamp} < ${this._curStamp}); ` +
+                "keeping current segment until the clock catches up"));
+        }
+        return false;
+    }
     /**
      * Highest viable segment index for `stamp`.
      * Disk is truth: resume a raw tail; start after sealed ones.
@@ -476,9 +526,10 @@ class RotateFileStream extends Writable {
         this._path = p;
         if (this._auditEnabled) {
             const base = path.basename(p);
-            const prev = this._audit.files[base];
+            // reopen = NEW incarnation. Never inherit lifecycle
+            // fields from the previous record (observed in the wild as
+            // abandonedAt < openedAt on reactivated segments).
             this._audit.files[base] = {
-                ...(prev && prev.state === "archived" ? {} : prev),
                 index: this._index,
                 state: "active",
                 gzipPending: false,
@@ -529,22 +580,42 @@ class RotateFileStream extends Writable {
                 }
             }
             else if (realBytes === 0) {
-                try {
-                    fs.unlinkSync(oldPath);
+                // a concurrent writer may have archived this segment
+                // between our last stat and now — adopt its artifact instead of
+                // recording a false `drop-empty` that orphans the .gz.
+                const adoptedGz = `${oldPath}.gz`;
+                if (existsSafe(adoptedGz)) {
+                    this._finishArchivedRecord(oldBase);
+                    archive = adoptedGz;
                 }
-                catch {
-                    /* already gone */
+                else {
+                    try {
+                        fs.unlinkSync(oldPath);
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                    if (rec)
+                        delete this._audit.files[oldBase];
+                    this._aevent("drop-empty", { file: oldBase });
                 }
-                if (rec)
-                    delete this._audit.files[oldBase];
-                this._aevent("drop-empty", { file: oldBase });
             }
             else if (rec) {
                 rec.state = "sealed";
                 rec.bytes = realBytes;
             }
         }
-        const stamp = this._stampNow();
+        let stamp = this._stampNow();
+        // a rotation itself must never move the series backward
+        // (covers rotateNow()/interval/size paths the upstream guards miss)
+        if (stamp < this._curStamp) {
+            if (!this._warnedBackward) {
+                this._warnedBackward = true;
+                this.emit("warn", new Error(`clock moved backward (stamp ${stamp} < ${this._curStamp}); ` +
+                    "rotation clamped to the current period"));
+            }
+            stamp = this._curStamp;
+        }
         const newPeriod = stamp !== this._curStamp;
         this._curStamp = stamp;
         /* Never blind-reset to 0 — recover what THIS stamp already owns. */
@@ -586,16 +657,26 @@ class RotateFileStream extends Writable {
         const next = this.freq.type === "daily"
             ? nextMidnight(this.tz, now)
             : nextAligned(now, this.freq.ms);
+        // anti-spin. A backward clock can put the computed
+        // boundary in the past; poll gently instead of firing every 100 ms.
+        const delta = next - this._now();
+        const delay = delta < 0 ? TIMER_POLL_MS : Math.max(100, delta);
         this._timer = setTimeout(() => {
             this._job(async () => {
                 const stamp = this._stampNow();
-                const dueDaily = this.freq.type === "daily" && stamp !== this._curStamp;
-                const dueInterval = this.freq.type !== "daily";
-                if (dueDaily || dueInterval) {
+                if (this.freq.type !== "daily") {
+                    /* interval rotation is schedule-based; runs regardless of
+                       stamp movement */
+                    if (this._hasContent())
+                        await this._rotate("time");
+                }
+                else if (this._stampAdvanced(stamp)) {
+                    // guarded daily branch
                     if (this._hasContent()) {
                         await this._rotate("time");
                     }
-                    else if (stamp !== this._curStamp) {
+                    else {
+                        /* idle boundary slide — no file created for empty days */
                         this._curStamp = stamp;
                         this._index = this._recoverIndexFor(stamp);
                         if (this._auditEnabled) {
@@ -606,9 +687,10 @@ class RotateFileStream extends Writable {
                         this.emit("period", stamp);
                     }
                 }
+                /* stamp regressed or unchanged → keep current segment, re-arm */
                 this._armTimer();
             }).catch(() => { });
-        }, Math.max(100, next - this._now()));
+        }, delay);
         if (this.unrefTimers)
             this._timer.unref();
     }
@@ -632,7 +714,8 @@ class RotateFileStream extends Writable {
         this._offsetMs += this._stepMs;
         this._armTimer();
         const stamp = this._stampNow();
-        if (stamp !== this._curStamp) {
+        // guarded crossing (virtual clock can't roll backward either)
+        if (this._stampAdvanced(stamp)) {
             if (this._hasContent()) {
                 await this._rotate("time");
             }
@@ -670,7 +753,15 @@ class RotateFileStream extends Writable {
             parsed = JSON.parse(fs.readFileSync(this._auditPath, "utf8"));
         }
         catch {
-            return false; // missing/unreadable → fresh start
+            // unparseable manifest is quarantined too (was silently
+            // clobbered by the first save — caught by the quarantine test)
+            try {
+                fs.renameSync(this._auditPath, `${this._auditPath}.corrupt`);
+            }
+            catch {
+                /* ignore */
+            }
+            return false;
         }
         const j = parsed;
         if (!j || j.version !== 1 || j.prefix !== this._tL || j.ext !== this._tExt) {
@@ -807,6 +898,59 @@ class RotateFileStream extends Writable {
             delete this._audit.files[name];
         }
     }
+    /**
+     * DISK-DRIVEN seal. Seal raw segments whose period has
+     * already passed (crash near midnight, virtual-clock leftovers,
+     * untracked/pruned files). Iterates the DIRECTORY, not the manifest:
+     * the filesystem is the source of truth; the manifest is an index.
+     */
+    async _sealOrphanedPastStamps() {
+        if (!this.zippedArchive)
+            return;
+        const stampRx = new RegExp("^" + escRe(this._tL) + "(.+?)" + escRe(this._tMid) +
+            "(?:\\.\\d+)?" + escRe(this._tExt) + "(?:\\.gz)?$");
+        let names = [];
+        try {
+            names = fs.readdirSync(this.dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name.endsWith(".gz"))
+                continue;
+            if (name === (this._path && path.basename(this._path)))
+                continue;
+            const stamp = stampRx.exec(name)?.[1];
+            // lexicographic compare is safe for zero-padded patterns (YYYY-MM-DD…);
+            // also guards the current stamp and anything future-dated
+            if (!stamp || stamp >= this._curStamp)
+                continue;
+            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));
+            if (!ok)
+                continue;
+            if (this._auditEnabled && this._audit.files[name]) {
+                // tracked → re-key record name → name.gz (emits archive + journal)
+                this._finishArchivedRecord(name, true);
+            }
+            else {
+                // untracked → record it fresh so future reconciles see truth
+                const gzName = `${name}.gz`;
+                if (this._auditEnabled) {
+                    this._audit.files[gzName] = {
+                        state: "archived",
+                        gzipPending: false,
+                        archivedAt: new Date().toISOString(),
+                    };
+                    this._aevent("seal-past", { file: gzName });
+                }
+                this.emit("archive", path.join(this.dir, gzName));
+            }
+        }
+    }
     async _repairInterruptedGzips() {
         for (const [name, rec] of Object.entries(this._audit.files)) {
             if (!rec.gzipPending)

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

@@ -1,6 +1,6 @@
 import { Writable } from "node:stream";
 import { type ParsedFrequency, type ParsedMaxFiles } from "./parsers.js";
-import type { RotateFileStreamEventMap, RotateFileStreamOptions } from "./types";
+import type { RotateFileStreamEventMap, RotateFileStreamOptions } from "./types.js";
 /**
  * A `Writable` that appends to dated log files, rolling segments on time
  * and/or size, optionally gzipping sealed segments, enforcing retention,
@@ -37,8 +37,8 @@ export declare class RotateFileStream extends Writable {
     private readonly _auditPath;
     private readonly _bootId;
     private _offsetMs;
-    private readonly _stepMs;
-    private readonly _bumpEvery;
+    private _stepMs;
+    private _bumpEvery;
     private _curStamp;
     private _index;
     private _ws;
@@ -48,6 +48,7 @@ export declare class RotateFileStream extends Writable {
     private _bumpTimer;
     private _ended;
     private _tail;
+    private _warnedBackward;
     private _audit;
     constructor(opts?: Partial<RotateFileStreamOptions>);
     on<E extends keyof RotateFileStreamEventMap>(event: E, listener: (...args: RotateFileStreamEventMap[E]) => void): this;
@@ -60,9 +61,7 @@ export declare class RotateFileStream extends Writable {
     get filename(): string | null;
     /** Index of the active segment within the current period. */
     get currentIndex(): number;
-    /**
-     * Force an immediate rotation and resolve when the next slot is staged.
-     */
+    /** Force an immediate rotation and resolve when the next slot is staged. */
     rotateNow(): Promise<void>;
     /**
      * Apply ONE virtual-clock tick immediately (bypasses the interval timer
@@ -77,6 +76,13 @@ export declare class RotateFileStream extends Writable {
     private _now;
     private _stampNow;
     private _resolveName;
+    /**
+     * true only when the period legally advanced. A regressed
+     * clock (NTP correction, manual change) never reopens a past family:
+     * writes continue in the current segment until real time catches up.
+     * Requires zero-padded datePattern tokens (documented assumption).
+     */
+    private _stampAdvanced;
     /**
      * Highest viable segment index for `stamp`.
      * Disk is truth: resume a raw tail; start after sealed ones.
@@ -100,6 +106,13 @@ export declare class RotateFileStream extends Writable {
     private _demoteZombieActives;
     /** Heal audit-vs-disk divergence after crashes / external tampering. */
     private _reconcileWithDisk;
+    /**
+     * DISK-DRIVEN seal. Seal raw segments whose period has
+     * already passed (crash near midnight, virtual-clock leftovers,
+     * untracked/pruned files). Iterates the DIRECTORY, not the manifest:
+     * the filesystem is the source of truth; the manifest is an index.
+     */
+    private _sealOrphanedPastStamps;
     private _repairInterruptedGzips;
     /** Seal a record; re-key `name` → `name.gz` so scans stop ghosting. */
     private _finishArchivedRecord;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "logroller",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Zero-dependency rotating file stream for Node.js — daily/interval/size rotation, gzip archives, retention, timezone-aware, crash-safe resume",
   "license": "MIT",
   "author": "Vinau",