logroller 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# 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.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: ESLint 9 flat config + typescript-eslint, Prettier,
+  EditorConfig, `npm run verify` gate (lint + 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,49 @@
-# logroller
 
-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.
+## README.md
+
+<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 +57,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 +69,126 @@ log.on("rotated", (r) => console.log("rotated:", r));
 const { createStream } = require("logroller");
 ```
 
-### Pipe anything into it
-
-```js
-source.pipe(createStream({ filename: "logs/data-%DATE%.log" }));
-```
-
-### With pino
+### pino destination
 
 ```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 },
+  { level: "info", stream: createStream({ filename: "logs/general-%DATE%.log" }) },
+  { level: "error", stream: createStream({ filename: "logs/error-%DATE%.log" }) },
 ]));
 ```
-
-## 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
+A killed process resumes without gaps or duplicates:
 
-| Disk at crash | Resumes into |
+| 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` (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 |
+| `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 |
 
-## Events
+## API
 
-| 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, …) |
+### `createStream(options)` → `RotateFileStream`
 
-Always attach an `error` handler — this is a real Writable stream.
+### Options
 
-## Audit manifest
+| 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 |
 
-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.
+### Events (typed)
 
-## Testing rotation without waiting
+| 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 |
 
-```js
+Errors must be handled — attach a listener on every instance.
+
+## Testing rotation without waiting a week
+
+```ts
 const s = createStream({
-  filename: "logs/test-%DATE%.log",
+  filename: "logs/demo-%DATE%.log",
   zippedArchive: true,
-  addHoursEveryMin: "24h",   // a day passes every minute
-  clockStepIntervalMs: 1000, // optional: step every second instead
-  tz: "UTC",
+  addHoursEveryMin: "24h",     // one day per real minute
+  clockStepIntervalMs: 1000,   // or faster
 });
-await s.advanceClock();      // or trigger one step manually
+await s.advanceClock();         // jump instantly when useful
 ```
 
-## Retention
+## FAQ
+
+**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.).
+
+**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.
+
+**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.
+
+**Windows / macOS / Linux?**
+Pure Node APIs; path handling via `node:path`. All three supported
+(Node `>=16.14`).
+
+## 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 |
+
+## 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 (lint + 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>;