logroller 1.0.0 → 2.0.1

package/dist/parsers.d.ts

@@ -0,0 +1,16 @@
+import type { RotateFileStreamOptions } from "./types.js";
+export interface ParsedMaxFiles {
+    days?: number;
+    count?: number;
+}
+export type ParsedFrequency = {
+    readonly type: "daily";
+} | {
+    readonly type: "interval";
+    ms: number;
+};
+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;
+export declare function parseClockOffset(v: RotateFileStreamOptions["addHours"]): number;
+export declare function parseClockStep(v: RotateFileStreamOptions["addHoursEveryMin"]): number;

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

@@ -0,0 +1,121 @@
+import { Writable } from "node:stream";
+import { type ParsedFrequency, type ParsedMaxFiles } from "./parsers.js";
+import type { RotateFileStreamEventMap, RotateFileStreamOptions } from "./types";
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const log = createStream({
+ *   filename: "logs/app-%DATE%.log",
+ *   maxSize: "20m",
+ *   maxFiles: "90d",
+ *   zippedArchive: true,
+ * });
+ * log.write("hello\n");          // or: readable.pipe(log)
+ * ```
+ */
+export declare class RotateFileStream extends Writable {
+    readonly tz: string;
+    readonly template: string;
+    readonly dir: string;
+    readonly datePattern: string;
+    readonly zippedArchive: boolean;
+    readonly maxSize: number;
+    readonly maxFiles: Readonly<ParsedMaxFiles> | null;
+    readonly freq: ParsedFrequency;
+    readonly unrefTimers: boolean;
+    private readonly _tL;
+    private readonly _tMid;
+    private readonly _tExt;
+    private readonly _rxFor;
+    private readonly _rxActive;
+    private readonly _auditEnabled;
+    private readonly _auditPath;
+    private readonly _bootId;
+    private _offsetMs;
+    private readonly _stepMs;
+    private readonly _bumpEvery;
+    private _curStamp;
+    private _index;
+    private _ws;
+    private _path;
+    private _bytes;
+    private _timer;
+    private _bumpTimer;
+    private _ended;
+    private _tail;
+    private _audit;
+    constructor(opts?: Partial<RotateFileStreamOptions>);
+    on<E extends keyof RotateFileStreamEventMap>(event: E, listener: (...args: RotateFileStreamEventMap[E]) => void): this;
+    on(event: string | symbol, listener: (...args: any[]) => void): this;
+    once<E extends keyof RotateFileStreamEventMap>(event: E, listener: (...args: RotateFileStreamEventMap[E]) => void): this;
+    once(event: string | symbol, listener: (...args: any[]) => void): this;
+    emit<E extends keyof RotateFileStreamEventMap>(event: E, ...args: RotateFileStreamEventMap[E]): boolean;
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+    /** Absolute path of the segment currently written; `null` until first write. */
+    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.
+     */
+    rotateNow(): Promise<void>;
+    /**
+     * Apply ONE virtual-clock tick immediately (bypasses the interval timer
+     * for deterministic tests). Crossing into a new period triggers the same
+     * archive flow as a real midnight roll.
+     */
+    advanceClock(): Promise<void>;
+    _write(chunk: Buffer, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    _final(callback: (error?: Error | null) => void): void;
+    destroy(...args: Parameters<Writable["destroy"]>): this;
+    private _job;
+    private _now;
+    private _stampNow;
+    private _resolveName;
+    /**
+     * 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;
+    private _ensureOpen;
+    private _rotate;
+    private _hasContent;
+    private _armTimer;
+    private _armBump;
+    private _stopBump;
+    private _applyBump;
+    private _stopTimer;
+    private _loadAudit;
+    private _saveAudit;
+    private _pruneAuditFiles;
+    private _aevent;
+    private _setActivePointer;
+    /** Records left `active` by dead processes → `abandoned`. */
+    private _demoteZombieActives;
+    /** Heal audit-vs-disk divergence after crashes / external tampering. */
+    private _reconcileWithDisk;
+    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;
+}
+/**
+ * Convenience factory mirroring common rotator APIs.
+ *
+ * @example
+ * const log = createStream({ filename: "logs/app-%DATE%.log" });
+ */
+export declare function createStream(options: RotateFileStreamOptions): RotateFileStream;

package/dist/time.d.ts

@@ -0,0 +1,13 @@
+/** Cached `Intl.DateTimeFormat`; throws synchronously for invalid zones. */
+export declare function getDtf(tz: string): Intl.DateTimeFormat;
+export declare function partsIn(tz: string, date: Date): Record<string, string>;
+/** Escape a literal string for embedding inside a RegExp. */
+export declare function escRe(s: string): string;
+/** Substitute YYYY|YY|MM|DD|HH|mm|ss tokens in `pattern`. */
+export declare function formatStamp(pattern: string, parts: Record<string, string>): string;
+/** Offset of `tz` vs UTC at instant `date`, milliseconds. */
+export declare function tzOffsetMs(tz: string, date: Date): number;
+/** Next local midnight in `tz`, DST-corrected by fixed-point iteration. */
+export declare function nextMidnight(tz: string, fromMs: number): number;
+/** Next epoch-aligned boundary (e.g. hh:00 for step = 1h). */
+export declare const nextAligned: (from: number, step: number) => number;

package/dist/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * logroller — public types.
+ *
+ * Everything exported here is part of the stable API surface.
+ */
+export type RotationReason = "time" | "size" | "manual";
+/** Options accepted by {@linkcode RotateFileStream} and `createStream`. */
+export interface RotateFileStreamOptions {
+    /**
+     * Destination filename pattern. REQUIRED and must contain the `%DATE%`
+     * token, which is replaced by the formatted current date/time.
+     *
+     * @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"
+     */
+    datePattern?: string;
+    /** 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.
+     * @default 0 (unlimited)
+     */
+    maxSize?: number | string;
+    /**
+     * Retention policy for this stream family.
+     * - `"90d"` — delete archived files older than 90 days (by mtime)
+     * - `500`   — keep at most the newest 500 archived files
+     * 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"
+     */
+    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"
+     */
+    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.
+     */
+    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.
+     */
+    addHoursEveryMin?: number | string;
+    /**
+     * Real interval between virtual-clock ticks (see `addHoursEveryMin`).
+     * Lower it to fast-forward faster in integration tests.
+     * @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
+     */
+    audit?: boolean;
+    /** Override the audit manifest filename. Default derives from the prefix. */
+    auditFile?: string;
+    /** Passed through to the underlying `Writable`. */
+    highWaterMark?: number;
+}
+/** 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). */
+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.
+ */
+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,9 +1,9 @@
 {
   "name": "logroller",
-  "version": "1.0.0",
+  "version": "2.0.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 <>",
+  "author": "Vinau",
   "homepage": "https://github.com/VinniWin/logroller#readme",
   "repository": {
     "type": "git",
@@ -13,47 +13,63 @@
   "keywords": [
     "log",
     "logger",
+    "logging",
     "rotate",
     "rotation",
     "rotating-file",
+    "rolling",
     "gzip",
+    "compress",
+    "retention",
     "stream",
+    "writable",
     "daily-rotate",
     "logrotate",
-    "writable"
+    "timezone",
+    "utc",
+    "pino",
+    "pipeline",
+    "crash-safe",
+    "resilient",
+    "zero-dependency"
   ],
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.esm.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=16.4"
+    "node": ">=16.14"
   },
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json && rollup -c",
-    "test": "npm run build && node --test --experimental-strip-types test/rotate.test.ts",
-    "prepublishOnly": "npm test && npm run build",
-    "prepare": "npm run build"
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.js\"",
+    "test": "node --test --experimental-strip-types test/rotate.test.ts",
+    "verify": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run verify",
+    "release": "npm run verify && npm pack --dry-run"
   },
   "devDependencies": {
     "@rollup/plugin-typescript": "^11.1.6",
-    "@types/node": "^22.10.0",
-    "rollup": "^4.27.0",
-    "typescript": "^5.6.3"
-  },
-  "dependencies": {
-    "tslib": "^2.8.1"
+    "@types/node": "^26.4.0",
+    "prettier": "^3.4.2",
+    "rollup": "^4.28.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.2"
   }
 }