lograil 0.1.0

package/dist/esm/transport/file.d.ts

@@ -0,0 +1,190 @@
+import type { LogEntry } from '../types.js';
+import type { Formatter } from '../pipeline/formatter.js';
+import type { Transport } from './transport.js';
+/** Fields every file mode shares. `appName` is required so the log file name
+ * always embeds the application identity. */
+export interface FileBaseOptions {
+    /** Application name; embedded in every generated log file name. */
+    appName: string;
+    /** Directory for the log file(s). Defaults to `os.tmpdir()`. */
+    dir?: string;
+    formatter?: Formatter;
+    /** Drop entries for which this returns `false`. */
+    filter?: (entry: LogEntry) => boolean;
+    /** Transport name for diagnostics and `removeTransport()`. Defaults to
+     * `file:<appName>`. Unlike `appName`, it never appears in generated file
+     * names — it only identifies this transport instance in memory. */
+    name?: string;
+    /** File extension without the dot. Defaults to `'log'`. */
+    ext?: string;
+    /**
+     * Global cap on the **total** bytes of every file this transport owns in
+     * `dir` (matched by the `${appName}.*.${ext}` shape). When exceeded, the
+     * oldest files are deleted until back under the cap. Defaults to `Infinity`
+     * (no limit). Works alongside, and independently of, `maxFiles` — whichever
+     * limit is hit first trims from the oldest.
+     */
+    maxTotalSize?: number;
+    /**
+     * Global cap on file age. Any owned file (matched by `${appName}.*.${ext}`,
+     * excluding the active file) whose modification time is older than
+     * `maxAge` milliseconds is deleted.
+     * - `undefined` or `-1` (default): no limit.
+     * - `0`: delete all history files immediately.
+     * - `>0`: threshold in milliseconds.
+     */
+    maxAge?: number;
+}
+/** 1.1 — write to one fixed file, appending forever until the disk is full. */
+export interface SingleAppendOptions extends FileBaseOptions {
+    mode: 'single';
+}
+/** 1.2 — single file; when it would exceed `maxSize`, copy it to a backup and
+ * truncate the original so writing resumes from the top (a 2-file ring). */
+export interface SingleTruncateOptions extends FileBaseOptions {
+    mode: 'single-truncate';
+    /** Size in bytes that triggers the backup+truncate cycle. */
+    maxSize: number;
+    /** Backup file name. Defaults to `${appName}.bak`. */
+    backupName?: string;
+}
+/** 2.1 — roll by size, keeping up to `maxFiles` generations. */
+export interface RotateSizeOptions extends FileBaseOptions {
+    mode: 'rotate-size';
+    /** Size in bytes that triggers a rotation. */
+    maxSize: number;
+    /** Number of generations to keep (active file + N-1 backups). */
+    maxFiles: number;
+}
+/** 2.2 — roll by time (hour or day), naming each file with a timestamp. */
+export interface RotateTimeOptions extends FileBaseOptions {
+    mode: 'rotate-time';
+    /** Time granularity of a new file. */
+    unit: 'hour' | 'day';
+    /** Number of time buckets (stamps) to keep. When a bucket contains
+     *  multiple seq files (via `maxSize`), the entire bucket is kept or
+     *  deleted as a unit. Omit = unbounded. */
+    maxFiles?: number;
+    /**
+     * Max bytes per time bucket. When the active file within the same time
+     * bucket would exceed this limit, a new numbered part is created
+     * (e.g. `app.2026-08-31-14.0.log`, `app.2026-08-31-14.1.log`).
+     * Omit = no size cap (time-only rotation).
+     */
+    maxSize?: number;
+    /** Max number of seq files kept **within a single time bucket**. When a
+     * bucket would exceed this count, the oldest seq files inside that bucket
+     * are deleted (the bucket forms an inner ring). Combined with `maxFiles`
+     * and `maxSize`, this bounds total disk usage at roughly
+     * `maxFiles × maxFilesPerBucket × maxSize` bytes. Omit = unbounded.
+     */
+    maxFilesPerBucket?: number;
+    /** Override the clock (mainly for testing). Defaults to `new Date()`. */
+    now?: () => Date;
+}
+/** Context handed to a custom rotation predicate. */
+export interface RotateContext {
+    entry: LogEntry;
+    /** Bytes already written to the current active file. */
+    size: number;
+    /** ISO timestamp of the entry, for time-based decisions. */
+    time: string;
+}
+/** 2.3 — fully custom rotation driven by a user predicate. */
+export interface RotateCustomOptions extends FileBaseOptions {
+    mode: 'rotate-custom';
+    /** Return `true` to close the current file and open a new one. */
+    shouldRotate: (entry: LogEntry, ctx: RotateContext) => boolean;
+    /** Name the seq-th file. Required (no sensible default for custom). */
+    fileName: (app: string, seq: number, ext: string) => string;
+    /** Max number of files to keep. Omit = unbounded. */
+    maxFiles?: number;
+}
+export type FileTransportOptions = SingleAppendOptions | SingleTruncateOptions | RotateSizeOptions | RotateTimeOptions | RotateCustomOptions;
+/** Metadata for a single log file managed by a {@link FileTransport}. */
+export interface FileMeta {
+    /** File name (e.g. `app.2026-09-01.0.log`). */
+    name: string;
+    /** Absolute path to the file. */
+    path: string;
+    /** File size in bytes. */
+    size: number;
+    /** Last modification timestamp (milliseconds since epoch). */
+    mtime: number;
+    /** Whether this is the file currently being written to. */
+    active: boolean;
+}
+/** Options for {@link FileTransport.getFiles}. */
+export interface GetFilesOptions {
+    /** When `true`, only return files created by the current transport instance
+     *  (files that existed on disk before this instance started are excluded).
+     *  Default `false`. */
+    currentSessionOnly?: boolean;
+}
+/**
+ * Single file transport covering every file-output strategy. Each strategy is
+ * an isolated `Rotator` (see above); this class only performs the shared
+ * filesystem plumbing on a serialized queue.
+ *
+ * Modes:
+ *  - `single` (1.1): one fixed file, append forever.
+ *  - `single-truncate` (1.2): back up + truncate when `maxSize` would be exceeded.
+ *  - `rotate-size` (2.1): roll by size into N generations.
+ *  - `rotate-time` (2.2): roll by hour/day into timestamped files.
+ *  - `rotate-custom` (2.3): roll whenever a user predicate says so.
+ *
+ * `appName` is required and is embedded in every file name.
+ */
+export declare class FileTransport implements Transport {
+    readonly name: string;
+    readonly formatter: Formatter;
+    readonly filter?: (entry: LogEntry) => boolean;
+    /** Effective capacity limits, for diagnostics (e.g. "why was my log file
+     * deleted?"). `maxSize`/`maxFiles` reflect the active rotation mode;
+     * `maxTotalSize`/`maxAge` are the global caps (`Infinity`/`-1` = unset). */
+    get caps(): {
+        maxSize?: number;
+        maxFiles?: number;
+        maxFilesPerBucket?: number;
+        maxTotalSize: number;
+        maxAge: number;
+    };
+    private readonly options;
+    private readonly dir;
+    private readonly ext;
+    private readonly io;
+    private readonly rotator;
+    private readonly clock;
+    private readonly maxTotalSize;
+    private readonly maxAge;
+    private readonly owned;
+    private readonly createdAt;
+    private closed;
+    private reportedFirstError;
+    private handle;
+    private queue;
+    private ownedScanned;
+    private static readonly PERIODIC_EVERY;
+    private static readonly PERIODIC_INTERVAL_MS;
+    private writeCount;
+    private lastCheckMs;
+    constructor(options: FileTransportOptions);
+    /** Absolute path of the log directory. */
+    getDir(): string;
+    /** Absolute path of the file currently being written to. */
+    getActiveFile(): string;
+    /** List all log files managed by this transport.
+     *
+     *  By default returns every file the transport knows about, including
+     *  files left over from previous runs (discovered via `scanOwned`). Pass
+     *  `{ currentSessionOnly: true }` to restrict the result to files created
+     *  by the current transport instance. */
+    getFiles(options?: GetFilesOptions): Promise<FileMeta[]>;
+    private ensureHandle;
+    private scanOwned;
+    private closeHandle;
+    write(entry: LogEntry, formatted: string): void | Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=file.d.ts.map

package/dist/esm/transport/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../../src/transport/file.ts"],"names":[],"mappings":"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"}