logroller 2.0.2 → 2.1.1

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

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.2",
+  "version": "2.1.1",
   "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",
@@ -48,8 +48,7 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
+    "LICENSE"
   ],
   "engines": {
     "node": ">=16.14"
@@ -59,12 +58,13 @@
     "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"
   },
   "devDependencies": {
+    "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-typescript": "^11.1.6",
     "@types/node": "^26.4.0",
     "prettier": "^3.4.2",

package/CHANGELOG.md

@@ -1,133 +0,0 @@
-# Changelog
-
-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
-modular **TypeScript** codebase with strict typings, first-class DX tooling,
-and CI-gated releases. The public runtime API (`createStream`,
-`RotateFileStream`, all options and events) remains compatible with 1.x;
-TypeScript consumers gain full type coverage.
-
-> ⚠️ Consumers on 1.x should re-run their smoke/integration tests after
-> 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`, …).
-- **Tuple-typed events** via `RotateFileStreamEventMap` — `on("rotated", …)`
-  autocompletes and payload types are checked (`RotatedInfo`, `ClockInfo`),
-  while Node-core fallback overloads keep `.pipe()` structurally valid.
-- `advanceClock()` — apply one virtual-clock tick immediately (previously the
-  step timer fired only every minute); makes day-crossing tests fully
-  deterministic.
-- `clockStepIntervalMs` option — control how often `addHoursEveryMin` ticks.
-- 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: 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`,
-  so a rapid first `write()` can no longer race a boot-time reopen or skip
-  zombie cleanup.
-- 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
-  `./package.json` export, `files` whitelist (`dist`, docs, license,
-  changelog).
-- Test suite runs against the built bundle and covers: base writing +
-  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.
-
-## [1.0.0] — 2026-08-26
-
-Initial release. Single-file zero-dependency JavaScript SDK
-(`file-rotation-sdk.js`) providing a Writable stream with scheduled file
-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
-  numbered segments — `app-D.log`, `app-D.1.log`, … — inserted between the
-  date stamp and the extension.
-- Optional gzip archiving of sealed segments (`zippedArchive`), atomic tmp+
-  rename writes, source deleted only after verified compression success.
-- Retention via `maxFiles`: age policy (`"90d"`) or count policy (`500`);
-  unset means files are never auto-deleted.
-- Crash-safe restart resume from disk scan: raw tails are appended to,
-  sealed chains continue at the next free index; lazy period-roll catches
-  boundaries missed while suspended or shut down.
-- Audit manifest (`<stem>_audit.json`): lifecycle records per file, capped
-  uuid-tagged event journal, `gzipPending` intent markers enabling automatic
-  repair of gzips interrupted by a crash, zombie active-record demotion,
-  disk-divergence healing (`archive-regressed`, `vanished`),
-  concurrent-writer detection via pid/bootId heartbeat.
-- Virtual test clock: static shift (`addHours`) and per-minute stepping
-  (`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.