lograil 0.1.0

package/dist/cjs/transport/electron-ipc.d.ts

@@ -0,0 +1,69 @@
+import type { LogEntry } from '../types.js';
+import type { Transport } from './transport.js';
+import type { IpcRenderer } from 'electron';
+/** Minimal view of `IpcRenderer` the transport actually needs. */
+type IpcSender = Pick<IpcRenderer, 'send'>;
+/** Shape we probe for at runtime to enable the zero-copy transfer path. */
+type IpcZeroCopySender = IpcSender & {
+    postMessage?: (channel: string, message: unknown, transfer?: unknown[]) => void;
+};
+/**
+ * Serialize an entry to an `ArrayBuffer` (UTF-8 JSON). The returned buffer is
+ * transferable: hand it to `postMessage(channel, buffer, [buffer])` so the
+ * underlying memory is moved across the process boundary instead of being
+ * structured-cloned (copied) by Electron.
+ */
+export declare function encodeEntry(entry: LogEntry): ArrayBuffer;
+/** Inverse of {@link encodeEntry}. */
+export declare function decodeEntry(buffer: ArrayBuffer | Uint8Array): LogEntry;
+export declare const LOGRAIL_CHANNEL = "lograil:log";
+/**
+ * Metadata key (on `LogEntry.metadata`) used to mark entries that originated
+ * in a renderer process and arrived over IPC. The main runtime uses it to
+ * route those entries to a dedicated renderer log file.
+ */
+export declare const RENDERER_PROCESS_MARKER = "__lograilProcess";
+export interface ElectronIpcTransportOptions {
+    /** IPC channel used to reach the main process. */
+    channel?: string;
+    /** Transport name. */
+    name?: string;
+    /**
+     * Injected IPC sender. Use this when the renderer cannot reach
+     * `require('electron')` itself (e.g. `nodeIntegration: false` +
+     * `contextIsolation: true`): pass the `ipcRenderer` obtained from a preload
+     * bridge instead of letting the transport call `require('electron')`.
+     */
+    ipcRenderer?: IpcZeroCopySender;
+}
+/**
+ * Renderer-side transport. Forwards each log entry to the Electron main
+ * process over IPC, where it is persisted by the main logger (the renderer
+ * itself has no filesystem access). The `electron` module is required lazily
+ * so this file is safe to import in non-Electron environments.
+ */
+export declare class ElectronIpcTransport implements Transport {
+    readonly name: string;
+    readonly channel: string;
+    private injectedIpc?;
+    private resolvedIpc?;
+    constructor(options?: ElectronIpcTransportOptions);
+    private getIpc;
+    write(entry: LogEntry, _formatted: string): void;
+    /** Send a cross-process level command to the main process. */
+    sendLevelCommand(level: number): void;
+}
+export interface IpcReceiverOptions {
+    channel?: string;
+}
+/**
+ * Main-side helper: listen on the IPC channel and feed received renderer
+ * entries into the provided `ingest` callback (typically `logger.ingestEntry`).
+ * Level-change commands are forwarded to `onLevelCommand` when provided.
+ * Returns an unregister function.
+ */
+export declare function registerIpcReceiver(ingest: (entry: LogEntry) => void, options?: IpcReceiverOptions & {
+    onLevelCommand?: (level: number) => void;
+}): () => void;
+export {};
+//# sourceMappingURL=electron-ipc.d.ts.map

package/dist/cjs/transport/electron-ipc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electron-ipc.d.ts","sourceRoot":"","sources":["../../../src/transport/electron-ipc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAS5C,kEAAkE;AAClE,KAAK,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AAE3C,2EAA2E;AAC3E,KAAK,iBAAiB,GAAG,SAAS,GAAG;IACnC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACjF,CAAC;AAMF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,CAExD;AAED,sCAAsC;AACtC,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,QAAQ,CAGtE;AAED,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,MAAM,WAAW,2BAA2B;IAC1C,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,SAAS;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,OAAO,CAAC,WAAW,CAAC,CAAoB;IACxC,OAAO,CAAC,WAAW,CAAC,CAAY;gBAEpB,OAAO,GAAE,2BAAgC;IAMrD,OAAO,CAAC,MAAM;IAYd,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAoBhD,8DAA8D;IAC9D,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAgBtC;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,EACjC,OAAO,GAAE,kBAAkB,GAAG;IAAE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAC9E,MAAM,IAAI,CAsCZ"}

package/dist/cjs/transport/electron-ipc.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElectronIpcTransport = exports.RENDERER_PROCESS_MARKER = exports.LOGRAIL_CHANNEL = void 0;
+exports.encodeEntry = encodeEntry;
+exports.decodeEntry = decodeEntry;
+exports.registerIpcReceiver = registerIpcReceiver;
+const types_js_1 = require("../types.js");
+const electron_binding_js_1 = require("../runtime/electron-binding.js");
+// Captured at module load so error reporting never recurses into itself.
+const RAW_CONSOLE_ERROR = typeof console !== 'undefined' && typeof console.error === 'function'
+    ? console.error.bind(console)
+    : () => { };
+// Reused across calls so we don't allocate an encoder/decoder per log line.
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * Serialize an entry to an `ArrayBuffer` (UTF-8 JSON). The returned buffer is
+ * transferable: hand it to `postMessage(channel, buffer, [buffer])` so the
+ * underlying memory is moved across the process boundary instead of being
+ * structured-cloned (copied) by Electron.
+ */
+function encodeEntry(entry) {
+    return encoder.encode(JSON.stringify(entry)).buffer;
+}
+/** Inverse of {@link encodeEntry}. */
+function decodeEntry(buffer) {
+    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    return JSON.parse(decoder.decode(bytes));
+}
+exports.LOGRAIL_CHANNEL = 'lograil:log';
+/**
+ * Metadata key (on `LogEntry.metadata`) used to mark entries that originated
+ * in a renderer process and arrived over IPC. The main runtime uses it to
+ * route those entries to a dedicated renderer log file.
+ */
+exports.RENDERER_PROCESS_MARKER = '__lograilProcess';
+/**
+ * Renderer-side transport. Forwards each log entry to the Electron main
+ * process over IPC, where it is persisted by the main logger (the renderer
+ * itself has no filesystem access). The `electron` module is required lazily
+ * so this file is safe to import in non-Electron environments.
+ */
+class ElectronIpcTransport {
+    constructor(options = {}) {
+        this.channel = options.channel ?? exports.LOGRAIL_CHANNEL;
+        this.name = options.name ?? `ipc:${this.channel}`;
+        this.injectedIpc = options.ipcRenderer;
+    }
+    getIpc() {
+        if (this.injectedIpc)
+            return this.injectedIpc;
+        if (!this.resolvedIpc) {
+            try {
+                this.resolvedIpc = (0, electron_binding_js_1.getElectron)().ipcRenderer;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return this.resolvedIpc;
+    }
+    write(entry, _formatted) {
+        const ipc = this.getIpc();
+        if (!ipc)
+            return;
+        try {
+            const sender = ipc;
+            if (typeof sender.postMessage === 'function') {
+                // Zero-copy path: serialize once, then transfer the buffer's ownership
+                // across the process boundary (no structured-clone of the object graph).
+                const buf = encodeEntry(entry);
+                sender.postMessage(this.channel, buf, [buf]);
+            }
+            else {
+                // Fallback: Electron structured-clones the whole entry object.
+                ipc.send(this.channel, entry);
+            }
+        }
+        catch (err) {
+            // Report IPC failure so users can diagnose renderer → main delivery issues.
+            RAW_CONSOLE_ERROR(`[lograil] ipc transport (${this.name}) send failed:`, err);
+        }
+    }
+    /** Send a cross-process level command to the main process. */
+    sendLevelCommand(level) {
+        const ipc = this.getIpc();
+        if (!ipc)
+            return;
+        const cmd = { __lograilCmd: true, __lograilCmdType: 'setLevel', level };
+        try {
+            const sender = ipc;
+            if (typeof sender.postMessage === 'function') {
+                const buf = encoder.encode(JSON.stringify(cmd)).buffer;
+                sender.postMessage(this.channel, buf, [buf]);
+            }
+            else {
+                ipc.send(this.channel, cmd);
+            }
+        }
+        catch {
+            /* silently drop — command loss is not fatal */
+        }
+    }
+}
+exports.ElectronIpcTransport = ElectronIpcTransport;
+/**
+ * Main-side helper: listen on the IPC channel and feed received renderer
+ * entries into the provided `ingest` callback (typically `logger.ingestEntry`).
+ * Level-change commands are forwarded to `onLevelCommand` when provided.
+ * Returns an unregister function.
+ */
+function registerIpcReceiver(ingest, options = {}) {
+    const channel = options.channel ?? exports.LOGRAIL_CHANNEL;
+    const onLevelCommand = options.onLevelCommand;
+    // `electron` is only present in a main process; resolve it lazily.
+    const ipcMain = (0, electron_binding_js_1.getElectron)().ipcMain;
+    const handler = (_event, payload) => {
+        if (payload instanceof ArrayBuffer || payload instanceof Uint8Array) {
+            // Zero-copy transfer path
+            try {
+                const decoded = JSON.parse(decoder.decode(payload));
+                if ((0, types_js_1.isLogLevelCommand)(decoded)) {
+                    onLevelCommand?.((0, types_js_1.normalizeLevel)(decoded.level));
+                    return;
+                }
+                const entry = decoded;
+                ingest({
+                    ...entry,
+                    metadata: { ...entry.metadata, [exports.RENDERER_PROCESS_MARKER]: 'renderer' },
+                });
+            }
+            catch {
+                return;
+            }
+        }
+        else {
+            const data = payload;
+            if ((0, types_js_1.isLogLevelCommand)(data)) {
+                onLevelCommand?.((0, types_js_1.normalizeLevel)(data.level));
+                return;
+            }
+            const entry = data;
+            // Copy-on-write: mark renderer-origin without mutating a shared/frozen entry.
+            ingest({
+                ...entry,
+                metadata: { ...entry.metadata, [exports.RENDERER_PROCESS_MARKER]: 'renderer' },
+            });
+        }
+    };
+    ipcMain.on(channel, handler);
+    return () => ipcMain.removeListener(channel, handler);
+}
+//# sourceMappingURL=electron-ipc.js.map

package/dist/cjs/transport/electron-ipc.js.map

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

package/dist/cjs/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/cjs/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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"}