logroller 2.0.1 → 2.1.0

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";
+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,9 +42,13 @@ 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 readonly _stepMs;
-    private readonly _bumpEvery;
+    private _stepMs;
+    private _bumpEvery;
     private _curStamp;
     private _index;
     private _ws;
@@ -48,6 +58,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 +71,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
@@ -70,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;
@@ -77,12 +95,32 @@ 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.
      * 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;
@@ -100,16 +138,16 @@ 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;
-    /**
- * Seal raw segments whose period has already passed (crash near midnight,
- * virtual-clock leftovers, untracked files). Disk is the source of truth —
- * manifest-tracked or not, a raw tail nothing will ever write to again
- * must still honour zippedArchive.
- */
-    private _sealOrphanedPastStamps;
     private _retire;
 }
 /**

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>;

package/dist/types.d.ts

@@ -8,122 +8,152 @@ export type RotationReason = "time" | "size" | "manual";
 export interface RotateFileStreamOptions {
     /**
      * Destination filename pattern. REQUIRED and must contain the `%DATE%`
-     * token, which is replaced by the formatted current date/time.
-     *
+     * token.
      * @example "logs/app-%DATE%.log"
      */
     filename: string;
-    /**
-     * Date token pattern substituted for `%DATE%`.
-     *
-     * Supported tokens: `YYYY YY MM DD HH mm ss`.
-     * Use tokens coarser-or-equal to your rotation frequency — hourly
-     * rotation with a day-only pattern collapses multiple files onto one name.
-     *
-     * @default "YYYY-MM-DD"
-     */
+    /** Tokens: `YYYY YY MM DD HH mm ss`. Must be coarse-or-equal to your
+     *  rotation frequency, or segments collapse onto one name.
+     * @default "YYYY-MM-DD" */
     datePattern?: string;
-    /** Gzip closed segments (`name.log` → `name.log.gz`). */
-    /** @default false */
+    /** Gzip closed segments (`name.log` → `name.log.gz`).
+     * @default false */
     zippedArchive?: boolean;
     /**
-     * Maximum bytes per segment before rolling. Accepts raw numbers (bytes)
-     * or human strings: `"20m"`, `"512k"`, `"2g"`, `"100b"`.
-     * `0` disables size-based rotation.
+     * gzip level 0–9. 0 = stored (fastest, no ratio), 9 = best ratio,
+     * 6 = default library default. Ignored when `zippedArchive` is false.
+     * @default 6
+     */
+    compressionLevel?: number;
+    /**
+     * Roll when the next write would exceed this size per segment.
+     * `"20m"`, `"512k"`, `"2g"`, or raw bytes. `0` disables.
      * @default 0 (unlimited)
      */
     maxSize?: number | string;
     /**
-     * Retention policy for this stream family.
-     * - `"90d"` — delete archived files older than 90 days (by mtime)
+     * Retention by age or count:
+     * - `"90d"` — delete archived files older than 90 days (mtime)
      * - `500`   — keep at most the newest 500 archived files
-     * Unset means **never** auto-delete.
+     * Unset means never auto-delete.
      */
     maxFiles?: number | string;
     /**
-     * IANA timezone used for date stamps and the daily boundary.
-     * Resolved via `Intl.DateTimeFormat`; throws early if invalid.
-     * @default "UTC"
+     * Retention by total byte budget across archived files (the active
+     * segment is never counted). When archives exceed the budget, the
+     * OLDEST are deleted until under budget. Composes with `maxFiles`
+     * (either policy may delete). `"5g"`, `"500m"`, or raw bytes.
+     * Unset/0 = no byte budget.
      */
+    maxTotalSize?: number | string;
+    /** IANA timezone for stamps and the daily boundary.
+     * @default "UTC" */
     tz?: string;
-    /**
-     * Rotation cadence: `"daily"` (local midnight in `tz`) or an interval
-     * like `"30s"`, `"5m"`, `"2h"`, or a millisecond number.
-     * Interval boundaries align to epoch multiples (hh:00:00 for `"1h"`).
-     * @default "daily"
-     */
+    /** `"daily"` (local midnight in `tz`) or interval `"30s"`/`"5m"`/`"2h"`
+     *  /ms. Interval boundaries align to epoch multiples.
+     * @default "daily" */
     frequency?: number | string;
     /**
-     * TEST ONLY. Static shift of the internal clock, in hours.
-     * `"-6h"`, `"24h"`, or a plain number (fractional allowed).
-     * Affects naming, timers, and retention cutoffs — never production data.
+     * TEST ONLY. Static shift of the internal clock. `"-6h"`, `"24h"`,
+     * plain/fractional number, or `"30m"`/`"90s"`.
      */
     addHours?: number | string;
     /**
-     *  TEST ONLY. Amount of virtual time added to the internal clock at
-     * every tick ({@linkcode RotateFileStreamOptions.clockStepIntervalMs}),
-     * simulating passing days: crossing into a new period archives the old
-     * segment exactly like a real midnight roll.
+     * TEST ONLY. Virtual time added per tick (see `clockStepIntervalMs`).
+     * Negative values exercise the backward-clock guard (no rotations).
      */
     addHoursEveryMin?: number | string;
-    /**
-     * Real interval between virtual-clock ticks (see `addHoursEveryMin`).
-     * Lower it to fast-forward faster in integration tests.
-     * @default 60_000
-     */
+    /** Real interval between virtual-clock ticks.
+     * @default 60_000 */
     clockStepIntervalMs?: number;
-    /** Detach rotation timers from the event loop (`timer.unref()`). */
-    /** @default false */
-    unrefTimers?: boolean;
     /**
-     * Maintain `<stem>_audit.json` beside the logs: lifecycle manifest,
-     * uuid-tagged journal, restart recovery, interrupted-gzip repair,
-     * zombie-process detection. Library-owned; treat as read-only.
-     * @default true
-     */
+     * Maintain a stable "current" pointer for log collectors
+     * (`tail -f`, Filebeat, promtail). `true` derives the name from the
+     * prefix (`"app-"` → `app-current.log`); a string names it exactly.
+     * The link is updated atomically each time a segment opens. Best-effort:
+     * on filesystems denying symlinks (Windows without Developer Mode) it
+     * warns once and disables itself.
+     * @default false */
+    symlink?: boolean | string;
+    /**
+     * Awaited after a segment is sealed/archived and BEFORE retention can
+     * delete it — the extension point for uploading to S3/GCS. Errors and
+     * timeouts degrade to a `warn`; they never break rotation.
+     * @default undefined */
+    onSeal?: (info: SealInfo) => Promise<void> | void;
+    /** Hard deadline for one `onSeal` invocation.
+     * @default 30_000 */
+    sealHookTimeoutMs?: number;
+    /** Detach rotation timers from the event loop.
+     * @default false */
+    unrefTimers?: boolean;
+    /** Maintain `<stem>_audit.json` (library-owned; treat as read-only).
+     * @default true */
     audit?: boolean;
-    /** Override the audit manifest filename. Default derives from the prefix. */
+    /** Override the audit manifest filename. */
     auditFile?: string;
     /** Passed through to the underlying `Writable`. */
     highWaterMark?: number;
 }
+/** Payload delivered to `onSeal` when a segment completes its lifecycle. */
+export interface SealInfo {
+    /** Closed segment path. May already be unlinked when `gz` exists. */
+    raw: string;
+    /** Compressed artifact; `null` when compression is off or failed. */
+    gz: string | null;
+}
+/** One file of the stream family, as reported by `listSegments()`. */
+export interface SegmentInfo {
+    file: string;
+    /** Date stamp embedded in the filename. */
+    stamp: string;
+    /** Segment index within the stamp (0 = base file). */
+    index: number;
+    gzipped: boolean;
+    bytes: number;
+    /** Audit state, or `"untracked"` for files unknown to the manifest. */
+    state: string;
+    openedAt?: string;
+    archivedAt?: string;
+}
+/** Snapshot for dashboards/health checks — see `stats()`. */
+export interface StreamStats {
+    dir: string;
+    currentStamp: string;
+    activeFile: string | null;
+    activeIndex: number;
+    /** All family files on disk (active included). */
+    segments: number;
+    /** Of those, how many are compressed archives. */
+    archived: number;
+    totalBytes: number;
+    /** Active virtual-clock shift (non-zero only under test knobs). */
+    clockOffsetMs: number;
+    /** Active symlink path, or `null`. */
+    symlink: string | null;
+}
 /** Payload for the `rotated` event. */
 export interface RotatedInfo {
     reason: RotationReason;
-    /** Segment that was closed; `null` when nothing was open. */
     oldFile: string | null;
-    /** Gzip artifact created for it; `null` when unzipped, empty, or failed. */
     archive: string | null;
-    /** Segment subsequent writes go to (opened lazily). */
     newFile: string;
 }
-/** Payload for the `clock` event (emitted when a virtual clock is active). */
+/** Payload for the `clock` event. */
 export interface ClockInfo {
     addHours?: number | string;
     addHoursEveryMin?: number | string;
     offsetMs: number;
 }
-/**
- * Tuple-style event map used to type `on` / `once` / `emit`.
- * Keys mirror Node core lifecycle events where relevant.
- */
+/** Tuple-style event map typing `on` / `once` / `emit`. */
 export interface RotateFileStreamEventMap {
-    /** A segment file was opened for appending. */
     open: [file: string];
-    /** A segment completed its lifecycle; see {@linkcode RotatedInfo}. */
     rotated: [info: RotatedInfo];
-    /** A gzip archive finished successfully. */
     archive: [gzFile: string];
-    /** Retention removed a file. */
     deleted: [file: string];
-    /** Period changed with nothing to archive (idle boundary slide). */
     period: [stamp: string];
-    /** Virtual clock engaged (test knobs). */
     clock: [info: ClockInfo];
-    /** Non-fatal problem: gzip failure, divergent state, stray writer… */
     warn: [err: Error];
-    /** Fatal problem mid-write; mirrors `Writable#close` semantics. */
     error: [err: Error];
-    /** Stream fully closed. */
     close: [];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logroller",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "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",
@@ -59,7 +59,7 @@
     "build": "tsc -p tsconfig.json && rollup -c",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.js\"",
-    "test": "node --test --experimental-strip-types test/rotate.test.ts",
+    "test": "npm run build && node --test --experimental-strip-types test/rotate.test.ts test/features.test.ts",
     "verify": "npm run typecheck && npm test",
     "prepublishOnly": "npm run verify",
     "release": "npm run verify && npm pack --dry-run"