logroller 2.1.0 → 3.0.0

package/dist/pino.cjs

@@ -0,0 +1,2 @@
+/*! logroller v3.0.0 | MIT License */
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("./rotate-file-stream.cjs");require("node:crypto"),require("node:fs"),require("node:path"),require("node:stream"),require("node:zlib"),require("node:stream/promises"),exports.default=function(r){return e.createStream(r)};

package/dist/pino.d.cts

@@ -0,0 +1,6 @@
+import { RotateFileStreamOptions, RotateFileStream } from './index.cjs';
+import 'node:stream';
+
+declare function pinoTransport(options: RotateFileStreamOptions): RotateFileStream;
+
+export { pinoTransport as default };

package/dist/pino.d.ts

@@ -0,0 +1,6 @@
+import { RotateFileStreamOptions, RotateFileStream } from './index.js';
+import 'node:stream';
+
+declare function pinoTransport(options: RotateFileStreamOptions): RotateFileStream;
+
+export { pinoTransport as default };

package/dist/pino.esm.js

@@ -0,0 +1,2 @@
+/*! logroller v3.0.0 | MIT License */
+import{c as o}from"./rotate-file-stream.esm.js";import"node:crypto";import"node:fs";import"node:path";import"node:stream";import"node:zlib";import"node:stream/promises";function t(t){return o(t)}export{t as default};

package/dist/rotate-file-stream.cjs

@@ -0,0 +1,2 @@
+/*! logroller v3.0.0 | MIT License */
+"use strict";var t=require("node:crypto"),e=require("node:fs"),i=require("node:path"),s=require("node:stream"),a=require("node:zlib"),n=require("node:stream/promises");const r=t=>{try{return"string"==typeof t?e.statSync(t).size:0}catch{return 0}},h=t=>{try{return e.existsSync(t)}catch{return!1}};async function o(t,i,s,r=6){try{return await n.pipeline(e.createReadStream(t),a.createGzip({level:r}),e.createWriteStream(i)),await e.promises.unlink(t),!0}catch(t){return await e.promises.unlink(i).catch(()=>{}),s?.(t),!1}}const d=t=>t?new Promise(e=>t.end(()=>e())):Promise.resolve(),c={b:1,k:1024,kb:1024,m:1048576,mb:1048576,g:1073741824,gb:1073741824},u={ms:1,s:1e3,m:6e4,h:36e5,hour:36e5,hours:36e5};function l(t,e,i){if("number"==typeof t)return Math.round(t*u[e]);const s=/^\s*(-?\d+(?:\.\d+)?)\s*(h(?:our)?s?|ms|s|m)?\s*$/i.exec(t);if(!s)throw new Error(`Invalid ${i} "${t}"`);const a=(s[2]??e).toLowerCase(),n=u[a];if(void 0===n)throw new Error(`Invalid ${i} unit "${s[2]}" in "${t}"`);return Math.round(Number.parseFloat(s[1])*n)}function _(t){if(null==t||0===t)return 0;if("number"==typeof t)return t;const e=/^\s*(\d+(?:\.\d+)?)\s*(b|kb|k|mb|m|gb|g)?\s*$/i.exec(t);if(!e)throw new Error(`Invalid maxSize "${t}"`);return Math.round(Number.parseFloat(e[1])*(c[e[2]?.toLowerCase()]??1))}const m={ms:1,s:1e3,m:6e4,h:36e5};const p=new Map;function f(t){let e=p.get(t);if(!e){try{e=new Intl.DateTimeFormat("en-US",{timeZone:t,hourCycle:"h23",year:"numeric",month:"2-digit",day:"2-digit",hour:"2-digit",minute:"2-digit",second:"2-digit"})}catch{throw new Error(`Invalid timeZone "${t}"`)}p.set(t,e)}return e}function w(t,e){const i={};for(const s of f(t).formatToParts(e))i[s.type]=s.value;return i}const v=t=>t.padStart(2,"0");function y(t){return t.replace(/[.*+?^${}()|[\]\\]/g,String.raw`\$&`)}function b(t,e){const i=w(t,e);return Date.UTC(+i.year,+i.month-1,+i.day,+i.hour,+i.minute,+i.second)-(e.getTime()-e.getTime()%1e3)}class S extends s.Writable{tz;template;dir;datePattern;zippedArchive;maxSize;maxFiles;freq;unrefTimers;maxTotalSize;_tL;_tMid;_tExt;_rxFor;_rxActive;_auditEnabled;_auditPath;_bootId=t.randomUUID();_onSeal;_sealHookTimeoutMs;_compressionLevel;_symlinkPath=null;_offsetMs;_stepMs;_bumpEvery;_curStamp;_index;_ws=null;_path=null;_bytes=0;_timer=null;_bumpTimer=null;_beatTimer;_ended=!1;_tail=Promise.resolve();_warnedBackward=!1;_stampSec=Number.NaN;_stampVal="";_audit;constructor(t={}){super(t.highWaterMark?{highWaterMark:t.highWaterMark}:{});const s=t.filename;if("string"!=typeof s||!s.includes("%DATE%"))throw new Error("opts.filename must contain '%DATE%' (e.g. 'logs/app-%DATE%.log')");var a;this.tz=t.tz||"UTC",f(this.tz),this.template=i.basename(s),this.dir=i.dirname(s),this.datePattern=t.datePattern||"YYYY-MM-DD",this.zippedArchive=!!t.zippedArchive,this.maxSize=_(t.maxSize??0),this.maxFiles=function(t){if(null==t||""===t||0===t)return null;if("number"==typeof t){if(t<0)throw new Error(`Invalid maxFiles "${t}"`);return{count:t}}const e=/^\s*(\d+)\s*d\s*$/i.exec(t);if(e)return 0===Number(e[1])?null:{days:Number.parseInt(e[1],10)};const i=/^\s*(\d+)\s*$/.exec(t);if(i)return 0===Number(i[1])?null:{count:Number.parseInt(i[1],10)};throw new Error(`Invalid maxFiles "${t}"`)}(t.maxFiles),this.maxTotalSize=_(t.maxTotalSize??0),this.freq=function(t){if(null==t)return{type:"daily"};if("daily"===t)return{type:"daily"};if("number"==typeof t){if(t<=0)throw new Error(`Invalid frequency "${t}"`);return{type:"interval",ms:t}}const e=/^\s*(\d+)\s*(ms|s|m|h)\s*$/i.exec(t);if(!e)throw new Error(`Invalid frequency "${t}"`);return{type:"interval",ms:Number.parseInt(e[1],10)*m[e[2].toLowerCase()]}}(t.frequency),this.unrefTimers=!!t.unrefTimers,this._offsetMs=null==(a=t.addHours)||""===a?0:l(a,"h","addHours"),this._stepMs=function(t){return null==t||""===t?0:l(t,"h","addHoursEveryMin")}(t.addHoursEveryMin),this._bumpEvery=Math.max(50,t.clockStepIntervalMs??6e4),this._compressionLevel=Math.min(9,Math.max(0,t.compressionLevel??6)),this._onSeal=t.onSeal,this._sealHookTimeoutMs=Math.max(0,t.sealHookTimeoutMs??3e4);const n=this.template.indexOf("%DATE%"),r=this.template.slice(n+6),h=r.lastIndexOf(".");this._tL=this.template.slice(0,n),this._tMid=h>=0?r.slice(0,h):"",this._tExt=h>=0?r.slice(h):"",this._rxFor=t=>new RegExp("^"+y(this._tL)+t+y(this._tMid)+"(?:\\.(\\d+))?"+y(this._tExt)+"(?:\\.gz)?$"),this._rxActive=this._rxFor("("+this.datePattern.split(/(YYYY|YY|MM|DD|HH|mm|ss)/).map((t,e)=>e%2?"YYYY"===t?"\\d{4}":"\\d{2}":y(t)).join("")+")"),this._auditEnabled=!1!==t.audit;const o=(this._tL.replace(/[^\w.-]+/g,"")||"log").replace(/^[-.]+|[-.]+$/g,"");var d,c,u,p;this._auditPath=i.join(this.dir,t.auditFile||`${o}_audit.json`),this._symlinkPath=t.symlink?i.join(this.dir,"string"==typeof t.symlink?t.symlink:`${o}-current.log`):null,e.mkdirSync(this.dir,{recursive:!0}),this._curStamp=this._stampNow(),this._audit=(d=this._tL,c=this._tExt,u=this.datePattern,p=this.tz,{version:1,prefix:d,ext:c,datePattern:u,tz:p,createdAt:null,updatedAt:null,activeStamp:null,activeIndex:null,writer:null,files:{},events:[]});const w=this._auditEnabled&&this._loadAudit();this._index=this._recoverIndexFor(this._curStamp);const v=this._audit.activeIndex;w&&null!==v&&this._audit.activeStamp===this._curStamp&&(this._index=Math.max(this._index,v)),0===this._offsetMs&&0===this._stepMs||process.nextTick(()=>this.emit("clock",{addHours:t.addHours??void 0,addHoursEveryMin:t.addHoursEveryMin??void 0,offsetMs:this._offsetMs})),process.nextTick(()=>{const e=t=>this.emit("warn",new Error(t));"interval"===this.freq.type?(this.freq.ms<864e5&&!this.datePattern.includes("HH")&&e(`frequency "${t.frequency}" needs HH in datePattern — segments would collapse onto one filename`),this.freq.ms<6e4&&!this.datePattern.includes("mm")&&e(`frequency "${t.frequency}" needs mm in datePattern`)):this.datePattern.includes("DD")||e("daily frequency needs DD in datePattern")}),this._job(async()=>{await this._sealOrphanedPastStamps(),this._auditEnabled&&(this._demoteZombieActives(),this._reconcileWithDisk(),await this._repairInterruptedGzips(),this._aevent("boot",{stamp:this._curStamp,index:this._index}),this._saveAudit()),await this._retire()}).catch(()=>{}),this._armTimer(),this._armBump(),this._auditEnabled&&(this._beatTimer=setInterval(()=>this._job(()=>this._saveAudit()).catch(()=>{}),1e4),this._beatTimer.unref()),this.once("close",()=>{this._stopTimer(),this._stopBump(),clearInterval(this._beatTimer)})}on(t,e){return super.on(t,e)}once(t,e){return super.once(t,e)}emit(t,...e){return super.emit(t,...e)}get filename(){return this._path}get currentIndex(){return this._index}rotateNow(){return this._job(()=>this._rotate("manual"))}advanceClock(){return this._job(()=>this._applyBump())}listSegments(){const t=this._rxActive,s=this._symlinkPath&&i.basename(this._symlinkPath),a=[];let n=[];try{n=e.readdirSync(this.dir)}catch{return a}for(const e of n){if(e===s)continue;const n=t.exec(e);if(!n)continue;const h=this._audit.files[e];a.push({file:i.join(this.dir,e),stamp:n[1],index:n[2]?Number.parseInt(n[2],10):0,gzipped:e.endsWith(".gz"),bytes:r(i.join(this.dir,e)),state:h?.state??"untracked",openedAt:h?.openedAt,archivedAt:h?.archivedAt})}return a.sort((t,e)=>t.stamp.localeCompare(e.stamp)||t.index-e.index),a}stats(){const t=this.listSegments();return{dir:this.dir,currentStamp:this._curStamp,activeFile:this._path,activeIndex:this._index,segments:t.length,archived:t.filter(t=>t.gzipped).length,totalBytes:t.reduce((t,e)=>t+e.bytes,0),clockOffsetMs:this._offsetMs,symlink:this._symlinkPath}}_write(t,e,i){this._writeBatch([t],i)}_writev(t,e){this._writeBatch(t.map(t=>t.chunk),e)}_writeBatch(t,e){this._ended?process.nextTick(e,new Error("write after end")):this._job(async()=>{try{this._stampAdvanced(this._stampNow())&&await this._rotate("time"),await this._ensureOpen();let i=[],s=0;for(const e of t){const t=this._bytes+s;this.maxSize>0&&t>0&&t+e.length>this.maxSize&&(await this._flush(i,s),i=[],s=0,await this._rotate("size"),await this._ensureOpen()),i.push(e),s+=e.length}await this._flush(i,s),e()}catch(t){e(t)}}).catch(()=>{})}async _flush(t,e){if(!e)return;const i=this._ws;if(!i)throw new Error("segment write stream not open");const s=1===t.length?t[0]:Buffer.concat(t,e);await new Promise((t,e)=>i.write(s,i=>i?e(i):t())),this._bytes+=e}_final(t){this._ended=!0,this._stopTimer(),this._stopBump(),clearInterval(this._beatTimer),this._job(async()=>{await d(this._ws);const t=this._path&&i.basename(this._path);if(t&&this._audit.files[t]){const e=this._audit.files[t];e.state="closed",e.closedAt=(new Date).toISOString(),e.bytes=r(this._path),this._aevent("close",{file:t}),this._saveAudit()}this._ws=null,this._path=null}).catch(()=>{}).finally(()=>t())}_destroy(t,e){this._ended=!0,this._stopTimer(),this._stopBump(),clearInterval(this._beatTimer),this._ws?.destroy(),this._ws=null,e(t)}async[Symbol.asyncDispose](){this.destroyed||this.writableFinished||await new Promise(t=>this.end(()=>t()))}_job(t){const e=this._tail.then(t,t);return this._tail=e.catch(()=>{}),e}_now(){return Date.now()+this._offsetMs}_stampNow(){const t=Math.floor(this._now()/1e3);var e,i;return t!==this._stampSec&&(this._stampSec=t,this._stampVal=(e=this.datePattern,i=w(this.tz,new Date(1e3*t)),e.replace(/YYYY|YY|MM|DD|HH|mm|ss/g,t=>{switch(t){case"YYYY":return i.year;case"YY":return i.year.slice(-2);case"MM":return v(i.month);case"DD":return v(i.day);case"HH":return v(i.hour);case"mm":return v(i.minute);case"ss":return v(i.second);default:return t}}))),this._stampVal}_resolveName(t,e){return i.join(this.dir,this._tL+t+this._tMid+(e?`.${e}`:"")+this._tExt)}_stampAdvanced(t){return t>this._curStamp||(t<this._curStamp&&!this._warnedBackward&&(this._warnedBackward=!0,this.emit("warn",new Error(`clock moved backward (stamp ${t} < ${this._curStamp}); keeping current segment until the clock catches up`))),!1)}_recoverIndexFor(t){const i=this._rxFor(y(t));let s=-1,a=-1,n=[];try{n=e.readdirSync(this.dir)}catch{}for(const t of n){const e=i.exec(t);if(!e)continue;const n=e[1]?Number.parseInt(e[1],10):0;n>s&&(s=n),!t.endsWith(".gz")&&n>a&&(a=n)}let r=a>=0?a:s>=0?s+1:0;const h=this._audit.activeIndex;return this._auditEnabled&&null!==h&&this._audit.activeStamp===t&&(r=Math.max(r,h)),r}_updateSymlink(){const t=this._symlinkPath;if(!t||!this._path)return;const s=`${t}.tmp`;try{try{e.unlinkSync(s)}catch{}e.symlinkSync(i.basename(this._path),s,"file"),e.renameSync(s,t)}catch(e){this._symlinkPath=null,this.emit("warn",new Error(`symlink unavailable ("${t}"): ${e.message} — continuing without it`))}}async _runSealHook(t,e){const s=this._onSeal;if(!s)return;let a;try{await Promise.race([Promise.resolve().then(()=>s({raw:t,gz:e})),new Promise((s,n)=>{a=setTimeout(()=>n(new Error(`onSeal hook timed out after ${this._sealHookTimeoutMs}ms (${i.basename(e??t)})`)),this._sealHookTimeoutMs)})])}catch(t){this.emit("warn",t)}finally{a&&clearTimeout(a)}}async _ensureOpen(){if(this._ws)return;const t=this._resolveName(this._curStamp,this._index);this._bytes=r(t);const s=e.createWriteStream(t,{flags:"a"});if(s.on("error",t=>this.destroy(t)),this._ws=s,this._path=t,this._updateSymlink(),this._auditEnabled){const e=i.basename(t);this._audit.files[e]={index:this._index,state:"active",gzipPending:!1,openedAt:(new Date).toISOString()},this._setActivePointer(this._index),this._aevent("open",{file:e,index:this._index,resumedBytes:this._bytes}),this._saveAudit()}this.emit("open",t)}async _rotate(t){const s=this._path,a=this._ws;this._ws=null,this._path=null,this._bytes=0;let n=null;if(a&&s){await d(a);const t=r(s),c=i.basename(s),u=this._auditEnabled?this._audit.files[c]:void 0;if(this.zippedArchive&&t>0){n=`${s}.gz`,u&&(u.gzipPending=!0,u.bytes=t,this._saveAudit());await o(s,n,t=>this.emit("warn",t),this._compressionLevel)?(this._finishArchivedRecord(c),await this._runSealHook(s,n)):(u&&(u.gzipPending=!1,u.state="kept-raw"),this._aevent("gzip-failed",{file:c}),n=null,await this._runSealHook(s,null))}else if(0===t){const t=`${s}.gz`;if(h(t))this._finishArchivedRecord(c),n=t,await this._runSealHook(s,t);else{try{e.unlinkSync(s)}catch{}u&&delete this._audit.files[c],this._aevent("drop-empty",{file:c})}}else t>0&&(u&&(u.state="sealed",u.bytes=t),await this._runSealHook(s,null))}let c=this._stampNow();c<this._curStamp&&(this._warnedBackward||(this._warnedBackward=!0,this.emit("warn",new Error(`clock moved backward (stamp ${c} < ${this._curStamp}); rotation clamped to the current period`))),c=this._curStamp);const u=c!==this._curStamp;this._curStamp=c,this._index=u||"time"===t?this._recoverIndexFor(c):this._index+1,this._bytes=0,this._auditEnabled&&(this._setActivePointer(this._index),this._aevent("rotate",{reason:t,nextIndex:this._index,stamp:c}),this._saveAudit()),"time"!==t&&"manual"!==t||this._armTimer(),s&&this.emit("rotated",{reason:t,oldFile:s,archive:n,newFile:this._resolveName(c,this._index)}),await this._retire()}_hasContent(){return this._ws?this._bytes>0||r(this._path)>0:!!(this._path&&r(this._path)>0)}_armTimer(){if(this._stopTimer(),this._ended)return;const t=this._now();var e,i;const s=("daily"===this.freq.type?function(t,e){const i=w(t,new Date(e)),s=Date.UTC(+i.year,+i.month-1,+i.day+1);let a=s-b(t,new Date(s));for(let e=0;e<3;e++){const e=s-b(t,new Date(a));if(e===a)break;a=e}return a<=e&&(a+=864e5),a}(this.tz,t):(e=t,i=this.freq.ms,Math.floor(e/i)*i+i))-this._now(),a=s<0?1e3:Math.max(100,s);this._timer=setTimeout(()=>{this._job(async()=>{const t=this._stampNow();"daily"!==this.freq.type?this._hasContent()&&await this._rotate("time"):await this._crossPeriod(t),this._armTimer()}).catch(()=>{})},a),this.unrefTimers&&this._timer.unref()}async _crossPeriod(t,e=!1){this._stampAdvanced(t)&&(this._hasContent()?await this._rotate("time"):(this._curStamp=t,this._index=this._recoverIndexFor(t),this._auditEnabled&&(this._setActivePointer(this._index),this._aevent("period",e?{stamp:t,virtual:e}:{stamp:t}),this._saveAudit()),this.emit("period",t)))}_armBump(){this._stopBump(),this._stepMs&&!this._ended&&(this._bumpTimer=setInterval(()=>this._job(()=>this._applyBump()).catch(()=>{}),this._bumpEvery),this.unrefTimers&&this._bumpTimer.unref())}_stopBump(){this._bumpTimer&&(clearInterval(this._bumpTimer),this._bumpTimer=null)}async _applyBump(){if(this._ended)return;this._offsetMs+=this._stepMs,this._armTimer();const t=this._stampNow();await this._crossPeriod(t,!0),this._auditEnabled&&(this._aevent("clock-step",{addedMsPerMin:this._stepMs,offsetMs:this._offsetMs,stamp:t}),this._saveAudit())}_stopTimer(){this._timer&&(clearTimeout(this._timer),this._timer=null)}_loadAudit(){let i;try{i=JSON.parse(e.readFileSync(this._auditPath,"utf8"))}catch{try{e.renameSync(this._auditPath,`${this._auditPath}.corrupt`)}catch{}return!1}const s=i;if(!s||1!==s.version||s.prefix!==this._tL||s.ext!==this._tExt){try{e.renameSync(this._auditPath,`${this._auditPath}.corrupt`)}catch{}return!1}this._audit.createdAt=s.createdAt??(new Date).toISOString(),this._audit.activeStamp="string"==typeof s.activeStamp?s.activeStamp:null,this._audit.activeIndex=Number.isInteger(s.activeIndex)?s.activeIndex:null,this._audit.files=s.files&&"object"==typeof s.files?s.files:{},this._audit.events=Array.isArray(s.events)?s.events.slice(-200):[];const a=s.writer;if(a&&"string"==typeof a.bootId&&a.bootId!==this._bootId&&"number"==typeof a.heartbeat&&Date.now()-a.heartbeat<3e4){const e=new Error(`concurrent writer detected (pid ${a.pid}, boot ${a.bootId}); two processes share this log family and will race. If running 'node --watch', exclude the logs dir via --watch-path.`);this.emit("warn",e),this._audit.events.push({id:t.randomUUID(),t:(new Date).toISOString(),type:"concurrent-writer",otherPid:a.pid,otherBoot:a.bootId})}return!0}_saveAudit(){if(this._auditEnabled)try{this._pruneAuditFiles(),this._audit.updatedAt=(new Date).toISOString(),this._audit.writer={pid:process.pid,bootId:this._bootId,heartbeat:Date.now()};const t=`${this._auditPath}.tmp`;e.writeFileSync(t,JSON.stringify(this._audit,null,1)),e.renameSync(t,this._auditPath)}catch(t){this.emit("warn",t)}}_pruneAuditFiles(){const t=this._audit.files,e=Object.keys(t);if(e.length<=600)return;const s=this._path&&i.basename(this._path),a=t=>t.archivedAt??t.closedAt??t.abandonedAt??t.openedAt??"",n=e.filter(e=>e!==s&&"active"!==t[e].state).sort((e,i)=>a(t[e]).localeCompare(a(t[i]))),r=e.length-600+50;for(const e of n.slice(0,r))delete t[e]}_aevent(e,i={}){if(!this._auditEnabled)return;const s=this._audit.events;s.push({id:t.randomUUID(),t:(new Date).toISOString(),type:e,...i}),s.length>200&&s.splice(0,s.length-200)}_setActivePointer(t){this._audit.activeStamp=this._curStamp,this._audit.activeIndex=t}_demoteZombieActives(){const t=this._path&&i.basename(this._path);for(const[e,i]of Object.entries(this._audit.files))"active"===i.state&&e!==t&&(i.state="abandoned",i.abandonedAt=(new Date).toISOString(),this._aevent("abandon",{file:e}))}_reconcileWithDisk(){for(const t of Object.keys(this._audit.files)){const e=this._audit.files[t];if(e.gzipPending)continue;if(t.endsWith(".gz")){const s=h(i.join(this.dir,t)),a=t.slice(0,-3),n=h(i.join(this.dir,a));if(s)continue;if(n){delete this._audit.files[t],this._audit.files[a]={...e,state:"sealed"},this._aevent("archive-regressed",{file:t,backTo:a}),this.emit("warn",new Error(`archive ${t} missing but raw ${a} exists`));continue}this._aevent("vanished",{file:t}),delete this._audit.files[t];continue}const s=h(i.join(this.dir,t)),a=h(i.join(this.dir,`${t}.gz`));s||(a?this._finishArchivedRecord(t,!0):(this._aevent("vanished",{file:t}),delete this._audit.files[t]))}}async _sealOrphanedPastStamps(){if(!this.zippedArchive)return;const t=this._rxActive;let s=[];try{s=e.readdirSync(this.dir)}catch{return}for(const e of s){if(e.endsWith(".gz"))continue;if(e===(this._path&&i.basename(this._path)))continue;const s=t.exec(e)?.[1];if(!s||s>=this._curStamp)continue;const a=i.join(this.dir,e);if(!h(a)||0===r(a))continue;const n=`${a}.gz`;await o(a,n,t=>this.emit("warn",t),this._compressionLevel)&&(this._auditEnabled&&this._audit.files[e]?this._finishArchivedRecord(e,!0):(this._auditEnabled&&(this._audit.files[n]={state:"archived",gzipPending:!1,archivedAt:(new Date).toISOString()},this._aevent("seal-past",{file:n})),this.emit("archive",n)),await this._runSealHook(a,n))}}async _repairInterruptedGzips(){for(const[t,s]of Object.entries(this._audit.files)){if(!s.gzipPending)continue;const a=i.join(this.dir,t),n=`${a}.gz`;if(!h(a)){s.gzipPending=!1,s.state="lost",this._aevent("gzip-lost",{file:t});continue}if(h(n)){try{e.unlinkSync(a)}catch{}this._finishArchivedRecord(t,!0),await this._runSealHook(a,n);continue}await o(a,n,t=>this.emit("warn",t),this._compressionLevel)?(this._finishArchivedRecord(t,!0),await this._runSealHook(a,n)):(s.gzipPending=!1,s.state="kept-raw",this._aevent("gzip-failed",{file:t}))}}_finishArchivedRecord(t,e=!1){const s=this._audit.files[t];if(!s)return;if(s.gzipPending=!1,s.state="archived",s.archivedAt=(new Date).toISOString(),t.endsWith(".gz"))return this.emit("archive",i.join(this.dir,t)),void this._aevent("archive",{file:t,...e&&{repaired:e}});const a=`${t}.gz`;delete this._audit.files[t],this._audit.files[a]=s,this.emit("archive",i.join(this.dir,a)),this._aevent("archive",{file:a,...e&&{repaired:e}})}async _retire(){const t=this.maxFiles;if(!t&&this.maxTotalSize<=0)return;const s=i.basename(this._resolveName(this._curStamp,this._index)),a=[i.basename(this._auditPath),`${i.basename(this._auditPath)}.tmp`,`${i.basename(this._auditPath)}.corrupt`,...this._symlinkPath?[i.basename(this._symlinkPath),`${i.basename(this._symlinkPath)}.tmp`]:[]];try{const n=(await e.promises.readdir(this.dir)).filter(t=>this._rxActive.test(t)&&t!==s&&!a.includes(t)),r=[];for(const t of n){const s=i.join(this.dir,t);try{const t=await e.promises.stat(s);r.push({full:s,mtimeMs:t.mtimeMs,size:t.size})}catch{}}r.sort((t,e)=>t.mtimeMs-e.mtimeMs);const h=new Set;if(null!=t?.days){const e=this._now()-864e5*t.days;for(const t of r)t.mtimeMs<e&&h.add(t.full)}if(null!=t?.count){const e=r.filter(t=>!h.has(t.full)),i=e.length-t.count;for(let t=0;t<i;t++)h.add(e[t].full)}if(this.maxTotalSize>0){const t=r.filter(t=>!h.has(t.full));let e=t.reduce((t,e)=>t+e.size,0),i=0;for(;e>this.maxTotalSize&&i<t.length;)h.add(t[i].full),e-=t[i].size,i++}if(0===h.size)return;for(const t of h)await e.promises.unlink(t).catch(()=>{}),this._auditEnabled&&(delete this._audit.files[i.basename(t)],this._aevent("deleted",{file:i.basename(t)})),this.emit("deleted",t);this._saveAudit()}catch(t){this.emit("warn",t)}}}exports.RotateFileStream=S,exports.createStream=function(t){return new S(t)};

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

@@ -0,0 +1,350 @@
+import { Writable } from 'node:stream';
+
+/**
+ * logroller — public types.
+ *
+ * Everything exported here is part of the stable API surface.
+ */
+type RotationReason = "time" | "size" | "manual";
+/** Options accepted by {@linkcode RotateFileStream} and `createStream`. */
+interface RotateFileStreamOptions {
+    /**
+     * Destination filename pattern. REQUIRED and must contain the `%DATE%`
+     * token.
+     * @example "logs/app-%DATE%.log"
+     */
+    filename: string;
+    /** 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 */
+    zippedArchive?: boolean;
+    /**
+     * 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 by age or count:
+     * - `"90d"` — delete archived files older than 90 days (mtime)
+     * - `500`   — keep at most the newest 500 archived files
+     * Unset, `0`, `"0"` or `"0d"` means never auto-delete.
+     */
+    maxFiles?: number | string;
+    /**
+     * 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;
+    /** `"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. `"-6h"`, `"24h"`,
+     * plain/fractional number, or `"30m"`/`"90s"`.
+     */
+    addHours?: number | string;
+    /**
+     * 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.
+     * @default 60_000 */
+    clockStepIntervalMs?: number;
+    /**
+     * 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. */
+    auditFile?: string;
+    /** Passed through to the underlying `Writable`. */
+    highWaterMark?: number;
+}
+/** Payload delivered to `onSeal` when a segment completes its lifecycle. */
+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()`. */
+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()`. */
+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. */
+interface RotatedInfo {
+    reason: RotationReason;
+    oldFile: string | null;
+    archive: string | null;
+    newFile: string;
+}
+/** Payload for the `clock` event. */
+interface ClockInfo {
+    addHours?: number | string;
+    addHoursEveryMin?: number | string;
+    offsetMs: number;
+}
+/** Tuple-style event map typing `on` / `once` / `emit`. */
+interface RotateFileStreamEventMap {
+    open: [file: string];
+    rotated: [info: RotatedInfo];
+    archive: [gzFile: string];
+    deleted: [file: string];
+    period: [stamp: string];
+    clock: [info: ClockInfo];
+    warn: [err: Error];
+    error: [err: Error];
+    close: [];
+}
+
+interface ParsedMaxFiles {
+    days?: number;
+    count?: number;
+}
+type ParsedFrequency = {
+    readonly type: "daily";
+} | {
+    readonly type: "interval";
+    ms: number;
+};
+
+/**
+ * A `Writable` that appends to dated log files, rolling segments on time
+ * 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)
+ * ```
+ */
+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;
+    readonly maxTotalSize: number;
+    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 readonly _onSeal?;
+    private readonly _sealHookTimeoutMs;
+    private readonly _compressionLevel;
+    private _symlinkPath;
+    private _offsetMs;
+    private _stepMs;
+    private _bumpEvery;
+    private _curStamp;
+    private _index;
+    private _ws;
+    private _path;
+    private _bytes;
+    private _timer;
+    private _bumpTimer;
+    private _beatTimer;
+    private _ended;
+    private _tail;
+    private _warnedBackward;
+    private _stampSec;
+    private _stampVal;
+    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>;
+    /**
+     * 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;
+    /** Lines buffered while the previous write was in flight arrive here as one batch. */
+    _writev(chunks: {
+        chunk: Buffer;
+        encoding: BufferEncoding;
+    }[], callback: (error?: Error | null) => void): void;
+    private _writeBatch;
+    private _flush;
+    _final(callback: (error?: Error | null) => void): void;
+    _destroy(err: Error | null, callback: (error?: Error | null) => void): void;
+    /**
+     * `await using log = createStream(...)` — ends (flushes) the stream on scope exit.
+     * Node's default destroys instead, dropping buffered lines.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    private _job;
+    private _now;
+    /** Stamps change at most once per second (ss is the finest token), so cache per second. */
+    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;
+    private _armTimer;
+    /** Guarded period crossing: rotate if the segment has data, else slide with no file. */
+    private _crossPeriod;
+    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;
+    /**
+     * 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;
+    private _retire;
+}
+/**
+ * Convenience factory mirroring common rotator APIs.
+ *
+ * @example
+ * const log = createStream({ filename: "logs/app-%DATE%.log" });
+ */
+declare function createStream(options: RotateFileStreamOptions): RotateFileStream;
+
+export { RotateFileStream as R, createStream as g };
+export type { ClockInfo as C, SealInfo as S, RotateFileStreamEventMap as a, RotateFileStreamOptions as b, RotatedInfo as c, RotationReason as d, SegmentInfo as e, StreamStats as f };

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

@@ -1,6 +1,176 @@
-import { Writable } from "node:stream";
-import { type ParsedFrequency, type ParsedMaxFiles } from "./parsers.js";
-import type { RotateFileStreamEventMap, RotateFileStreamOptions, SegmentInfo, StreamStats } from "./types.js";
+import { Writable } from 'node:stream';
+
+/**
+ * logroller — public types.
+ *
+ * Everything exported here is part of the stable API surface.
+ */
+type RotationReason = "time" | "size" | "manual";
+/** Options accepted by {@linkcode RotateFileStream} and `createStream`. */
+interface RotateFileStreamOptions {
+    /**
+     * Destination filename pattern. REQUIRED and must contain the `%DATE%`
+     * token.
+     * @example "logs/app-%DATE%.log"
+     */
+    filename: string;
+    /** 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 */
+    zippedArchive?: boolean;
+    /**
+     * 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 by age or count:
+     * - `"90d"` — delete archived files older than 90 days (mtime)
+     * - `500`   — keep at most the newest 500 archived files
+     * Unset, `0`, `"0"` or `"0d"` means never auto-delete.
+     */
+    maxFiles?: number | string;
+    /**
+     * 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;
+    /** `"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. `"-6h"`, `"24h"`,
+     * plain/fractional number, or `"30m"`/`"90s"`.
+     */
+    addHours?: number | string;
+    /**
+     * 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.
+     * @default 60_000 */
+    clockStepIntervalMs?: number;
+    /**
+     * 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. */
+    auditFile?: string;
+    /** Passed through to the underlying `Writable`. */
+    highWaterMark?: number;
+}
+/** Payload delivered to `onSeal` when a segment completes its lifecycle. */
+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()`. */
+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()`. */
+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. */
+interface RotatedInfo {
+    reason: RotationReason;
+    oldFile: string | null;
+    archive: string | null;
+    newFile: string;
+}
+/** Payload for the `clock` event. */
+interface ClockInfo {
+    addHours?: number | string;
+    addHoursEveryMin?: number | string;
+    offsetMs: number;
+}
+/** Tuple-style event map typing `on` / `once` / `emit`. */
+interface RotateFileStreamEventMap {
+    open: [file: string];
+    rotated: [info: RotatedInfo];
+    archive: [gzFile: string];
+    deleted: [file: string];
+    period: [stamp: string];
+    clock: [info: ClockInfo];
+    warn: [err: Error];
+    error: [err: Error];
+    close: [];
+}
+
+interface ParsedMaxFiles {
+    days?: number;
+    count?: number;
+}
+type ParsedFrequency = {
+    readonly type: "daily";
+} | {
+    readonly type: "interval";
+    ms: number;
+};
+
 /**
  * A `Writable` that appends to dated log files, rolling segments on time
  * and/or size, optionally gzipping sealed segments, enforcing retention
@@ -23,7 +193,7 @@ import type { RotateFileStreamEventMap, RotateFileStreamOptions, SegmentInfo, St
  * log.write("hello\n");          // or: readable.pipe(log)
  * ```
  */
-export declare class RotateFileStream extends Writable {
+declare class RotateFileStream extends Writable {
     readonly tz: string;
     readonly template: string;
     readonly dir: string;
@@ -56,9 +226,12 @@ export declare class RotateFileStream extends Writable {
     private _bytes;
     private _timer;
     private _bumpTimer;
+    private _beatTimer;
     private _ended;
     private _tail;
     private _warnedBackward;
+    private _stampSec;
+    private _stampVal;
     private _audit;
     constructor(opts?: Partial<RotateFileStreamOptions>);
     on<E extends keyof RotateFileStreamEventMap>(event: E, listener: (...args: RotateFileStreamEventMap[E]) => void): this;
@@ -88,11 +261,24 @@ export declare class RotateFileStream extends Writable {
      * Health-check snapshot for dashboards and support triage.
      */
     stats(): StreamStats;
-    _write(chunk: Buffer, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    /** Lines buffered while the previous write was in flight arrive here as one batch. */
+    _writev(chunks: {
+        chunk: Buffer;
+        encoding: BufferEncoding;
+    }[], callback: (error?: Error | null) => void): void;
+    private _writeBatch;
+    private _flush;
     _final(callback: (error?: Error | null) => void): void;
-    destroy(...args: Parameters<Writable["destroy"]>): this;
+    _destroy(err: Error | null, callback: (error?: Error | null) => void): void;
+    /**
+     * `await using log = createStream(...)` — ends (flushes) the stream on scope exit.
+     * Node's default destroys instead, dropping buffered lines.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
     private _job;
     private _now;
+    /** Stamps change at most once per second (ss is the finest token), so cache per second. */
     private _stampNow;
     private _resolveName;
     /**
@@ -125,6 +311,8 @@ export declare class RotateFileStream extends Writable {
     private _rotate;
     private _hasContent;
     private _armTimer;
+    /** Guarded period crossing: rotate if the segment has data, else slide with no file. */
+    private _crossPeriod;
     private _armBump;
     private _stopBump;
     private _applyBump;
@@ -156,4 +344,7 @@ export declare class RotateFileStream extends Writable {
  * @example
  * const log = createStream({ filename: "logs/app-%DATE%.log" });
  */
-export declare function createStream(options: RotateFileStreamOptions): RotateFileStream;
+declare function createStream(options: RotateFileStreamOptions): RotateFileStream;
+
+export { RotateFileStream as R, createStream as g };
+export type { ClockInfo as C, SealInfo as S, RotateFileStreamEventMap as a, RotateFileStreamOptions as b, RotatedInfo as c, RotationReason as d, SegmentInfo as e, StreamStats as f };