logroller 1.0.0 → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,101 @@
+# 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.1] — 2026-09-0X
+
+### 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.

package/README.md

@@ -1,19 +1,48 @@
-# logroller
+## README.md
 
-Zero-dependency rotating file stream for Node.js. Daily or interval rotation,
-size limits, gzip archives, retention policies, timezone-aware naming and a
-crash-safe resume — in one small Writable stream you can `pipe()` into or hand
-to pino.
+<p align="center"><strong>logroller</strong></p>
+<h3 align="center">Zero-dependency rotating file streams for Node.js</h3>
+
+<div align="center">
+
+![npm](https://img.shields.io/npm/v/logroller)
+![node](https://img.shields.io/node/v/logroller)
+![license](https://img.shields.io/npm/l/logroller)
+![types](https://shields.io/badge/types-included-blue)
+
+</div>
+
+---
+
+`logroller` turns a plain append destination into a resilient, observable
+log sink: **it is a Writable**, so `readable.pipe(log)` works, pino multistreams
+work, anything that consumes streams works.
 
 ```bash
 npm install logroller
 ```
 
+## Features
+
+- **Daily & interval rotation** — exact local midnight in any IANA zone,
+  or epoch-aligned intervals (`30s`, `5m`, `2h`)
+- **Size caps** — `"20m"`-style limits roll numbered segments
+- **Gzip archives** — sealed segments compressed atomically
+- **Retention** — by age or count; unset means files live forever
+- **Timezone-correct** — `Asia/Kolkata` means IST filenames, on a UTC box
+- **Crash-safe** — restarts resume mid-series byte-exactly;
+  gzips interrupted by a kill are completed on boot
+- **Observability** — `<stem>_audit.json` manifest with a uuid-tagged
+  event journal for every file's lifecycle
+- **Testable time** — virtual clocks (`addHours`, `addHoursEveryMin`,
+  `advanceClock()`) let a day pass per minute, or instantly
+- **Types first** — tuple-typed events, strict mode, dual ESM/CJS build
+
 ## Quick start
 
 ### ESM
 
-```js
+```ts
 import { createStream } from "logroller";
 
 const log = createStream({
@@ -27,7 +56,10 @@ const log = createStream({
 });
 
 log.write("hello\n");
-log.on("rotated", (r) => console.log("rotated:", r));
+log.on("rotated", ({ reason, archive, newFile }) =>
+  console.log(`${reason}: ${archive ?? "-"} → ${newFile}`),
+);
+process.on("exit", () => log.end());
 ```
 
 ### CommonJS
@@ -36,112 +68,129 @@ log.on("rotated", (r) => console.log("rotated:", r));
 const { createStream } = require("logroller");
 ```
 
-### Pipe anything into it
+### pino destination
 
 ```js
-source.pipe(createStream({ filename: "logs/data-%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" }) },
+  ]),
+);
 ```
 
-### With pino
-
-```js
-import pino from "pino";
-import { createStream } from "logroller";
-
-const stream = createStream({
-  filename: "logs/general-%DATE%.log",
-  zippedArchive: true,
-  maxSize: "20m",
-  maxFiles: "90d",
-  tz: "Asia/Kolkata",
-});
-
-const logger = pino(pino.multistream([
-  { level: "info", stream: pino.transport({ target: "./pretty.js" }) },
-  { level: "info", stream },
-]));
-```
-
-## Options
-
-| Option | Values | Default |
-|---|---|---|
-| `filename` | must contain `%DATE%` | required |
-| `datePattern` | `YYYY YY MM DD HH mm ss` | `YYYY-MM-DD` |
-| `zippedArchive` | boolean | `false` |
-| `maxSize` | `20m`, `1k`, `5g`, number of bytes, `0` = off | off |
-| `maxFiles` | `"90d"` (age), `500` (count), unset = never delete | off |
-| `frequency` | `"daily"`, `"1s"`, `"5m"`, `"2h"`, ms number | `"daily"` |
-| `tz` | any IANA zone (`Intl`-based) | `"UTC"` |
-| `audit` | write `<stem>_audit.json` manifest | `true` |
-| `auditFile` | custom manifest name | `<stem>_audit.json` |
-| `unrefTimers` | don't hold the process open | `false` |
-| `addHours` | static clock shift (`"-6h"`) — **test only** | off |
-| `addHoursEveryMin` | hours added per step (`"24h"`) — **test only** | off |
-| `clockStepIntervalMs` | step interval for `addHoursEveryMin` | `60000` |
-
-## File naming
+## What lands on disk
 
 ```
 app-2026-08-27.log          ← active
-app-2026-08-27.log.gz       ← hit maxSize → gzipped
-app-2026-08-27.1.log        ← next segment, writing…
-app-2026-08-27.1.log.gz     ← that one sealed too
-app-2026-08-28.log          ← new day (in tz), fresh series
+app-2026-08-27.log.gz       ← sealed (hit 20 MB)
+app-2026-08-27.1.log        ← next segment mid-day
+app-2026-08-27.1.log.gz     ← sealed too
+app-2026-08-28.log          ← fresh day (in your tz), clean series
+app_audit.json              ← library-owned manifest
 ```
 
-## Restart behaviour
-
-| Disk at crash | Resumes into |
-|---|---|
-| `app-D.log` | `app-D.log` (append) |
-| `app-D.log.gz` + `app-D.1.log` | `app-D.1.log` (append) |
-| `app-D.1.log.gz` only | `app-D.2.log` |
-| crossed midnight while down | new day base file on first write |
-| killed mid-gzip | boot finishes the interrupted gzip |
+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 |
+
+## API
+
+### `createStream(options)` → `RotateFileStream`
+
+### 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`            |
+
+### 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 |
+
+### 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         |
+
+Errors must be handled — attach a listener on every instance.
+
+## Testing rotation without waiting a week
+
+```ts
+const s = createStream({
+  filename: "logs/demo-%DATE%.log",
+  zippedArchive: true,
+  addHoursEveryMin: "24h", // one day per real minute
+  clockStepIntervalMs: 1000, // or faster
+});
+await s.advanceClock(); // jump instantly when useful
+```
 
-## Events
+## FAQ
 
-| Event | Payload |
-|---|---|
-| `open` | `(file: string)` |
-| `rotated` | `({ reason, oldFile, archive, newFile })` |
-| `archive` | `(gzFile: string)` |
-| `deleted` | `(file: string)` — retention |
-| `period` | `(stamp: string)` — new period, nothing to archive |
-| `clock` | `({ addHours, addHoursEveryMin, offsetMs })` — test clock active |
-| `warn` | `(err: Error)` — non-fatal (gzip failure, concurrent writer, …) |
+**Why is `%DATE%` mandatory?**
+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.).
 
-Always attach an `error` handler — this is a real Writable stream.
+**Can two processes share one directory?**
+Different prefixes/families: yes. The _same_ family: no — the audit
+manifest detects a live second writer (`writer.heartbeat`) and warns loudly.
 
-## Audit manifest
+**Is the audit JSON required?**
+No — `audit: false` reduces behaviour to pure disk-scan recovery. Recommended
+to leave on: it repairs interrupted gzips and demotes zombies automatically.
 
-Each stream family keeps a `*_audit.json` beside the logs (library-owned —
-treat it as read-only). It records every file's lifecycle with a capped,
-uuid-tagged event journal, restores the series index across restarts, repairs
-gzip interrupted by a crash, and demotes records left behind by dead
-processes. Writes are atomic (tmp + rename); a corrupt/foreign file is
-quarantined as `*.corrupt` and logging continues via disk scan.
+**Windows / macOS / Linux?**
+Pure Node APIs; path handling via `node:path`. All three supported
+(Node `>=16.14`).
 
-## Testing rotation without waiting
+## Compare
 
-```js
-const s = createStream({
-  filename: "logs/test-%DATE%.log",
-  zippedArchive: true,
-  addHoursEveryMin: "24h",   // a day passes every minute
-  clockStepIntervalMs: 1000, // optional: step every second instead
-  tz: "UTC",
-});
-await s.advanceClock();      // or trigger one step manually
-```
+|                           | 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                       |
 
-## Retention
+## Contributing
 
-- `maxFiles: "90d"` — delete family files older than 90 days (mtime)
-- `maxFiles: 500` — keep newest 500 archives
-- unset — never auto-delete; remove manually
+PRs welcome. `npm run verify` gates every change (typecheck + tests).
+Please file issues before large refactors.
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/dist/fsio.d.ts

@@ -0,0 +1,11 @@
+import fs from "node:fs";
+/** `stat().size` guarded to 0; string paths only. */
+export declare const statSizeSafe: (p: string | null | undefined) => number;
+export declare const existsSafe: (p: string) => boolean;
+/**
+ * Compress `src` → `dst`, deleting `src` ONLY on verified success.
+ * On failure removes the partial `dst` and reports via callback —
+ * logs degrade to uncompressed rather than losing data.
+ */
+export declare function gzipMove(src: string, dst: string, onWarn?: (err: Error) => void): Promise<boolean>;
+export declare const endStream: (ws: fs.WriteStream | null) => Promise<void>;