Class FileHandler

A file-based log handler that writes log messages to a specified file with buffering and optional modes. The logs are buffered for optimized performance, writing to the file only when the buffer is full, on manual .flush() call, during logging of a critical message or when process ends. It is important to note that the file can grow indefinitely.

This handler requires --allow-write permission on the log file.

Example: Usage

import { FileHandler } from "@std/log/file-handler";

const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
handler.setup();
handler.log('Hello, world!'); // Buffers the message, or writes it to the file depending on buffer state
handler.flush(); // Manually flushes the buffer
handler.destroy(); // Closes the file and removes listeners
Hierarchy

Constructors

constructor

Properties

formatter

Accessors

level levelName

Methods

[dispose] destroy flush format handle log setup

Constructors

constructor

Properties

formatter

formatter: FormatterFunction

The function that formats log records.

Example: Usage

import { BaseHandler } from "@std/log/base-handler";
import { LogRecord } from "@std/log/logger";
import { LogLevels } from "@std/log/levels";
import { assertEquals } from "@std/assert/equals";

class MyHandler extends BaseHandler {
 log(msg: string) {
  console.log(msg);
}
}

const handler = new MyHandler("INFO");
const record = new LogRecord({
  msg: "Hello, world!",
  args: ["foo", "bar"],
  level: LogLevels.INFO,
  loggerName: "example",
});
const formatted = handler.formatter(record);
assertEquals(formatted, "INFO Hello, world!");

Accessors

level

  • get level(): LogLevel

  • Getter for the log level that this handler will handle.

    Returns LogLevel

    The log level to handle.

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { LogLevels } from "@std/log/levels";
    import { assertEquals } from "@std/assert/equals";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    const handler = new MyHandler("INFO");
    assertEquals(handler.level, LogLevels.INFO);
  • set level(level): void

  • Setter for the log level that this handler will handle.

    Parameters

    • level: LogLevel

      The log level to handle.

    Returns void

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { LogLevels } from "@std/log/levels";
    import { assertEquals } from "@std/assert/equals";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    const handler = new MyHandler("INFO");
    handler.level = LogLevels.DEBUG;
    assertEquals(handler.level, LogLevels.DEBUG);

levelName

  • get levelName(): LevelName

  • Getter for the name of the log level that this handler will handle.

    Returns LevelName

    The name of the log level to handle.

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { assertEquals } from "@std/assert/equals";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    const handler = new MyHandler("INFO");
    assertEquals(handler.levelName, "INFO");
  • set levelName(levelName): void

  • Setter for the name of the log level that this handler will handle.

    Parameters

    • levelName: LevelName

      The name of the log level to handle.

    Returns void

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { assertEquals } from "@std/assert/equals";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    const handler = new MyHandler("INFO");
    handler.levelName = "DEBUG";
    assertEquals(handler.levelName, "DEBUG");

Methods

[dispose]

  • [dispose](): void

  • Automatically disposes of the handler when instantiated with the using keyword by calling the BaseHandler.destroy method.

    Returns void

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { LogRecord } from "@std/log/logger";
    import { assertInstanceOf } from "@std/assert/instance-of";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    using handler = new MyHandler("INFO");
    assertInstanceOf(handler, BaseHandler);

destroy

  • destroy(): void

  • Destroys the handler, performing any cleanup that is required and closes the file handler.

    Returns void

    Example: Usage

    import { FileHandler } from "@std/log/file-handler";
    import { assertInstanceOf } from "@std/assert/instance-of";

    const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
    handler.setup();
    handler.destroy();

    assertInstanceOf(handler, FileHandler);

flush

  • flush(): void

  • Immediately writes the contents of the buffer to the previously opened file.

    Returns void

    Example: Usage

    import { FileHandler } from "@std/log/file-handler";
    import { assertInstanceOf } from "@std/assert/instance-of";

    const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
    handler.setup();
    handler.log('Hello, world!');
    handler.flush(); // Writes buffered log messages to the file immediately.
    handler.destroy();

    assertInstanceOf(handler, FileHandler);

format

  • format(logRecord): string

  • Formats a log record.

    Parameters

    • logRecord: LogRecord

      The log record to format.

    Returns string

    A string representation of the log record.

    Example: Usage

    import { BaseHandler } from "@std/log/base-handler";
    import { LogRecord } from "@std/log/logger";
    import { LogLevels } from "@std/log/levels";
    import { assertEquals } from "@std/assert/equals";

    class MyHandler extends BaseHandler {
      log(msg: string) {
        console.log(msg);
      }
    }

    const handler = new MyHandler("INFO");
    const record = new LogRecord({
      msg: "Hello, world!",
      args: ["foo", "bar"],
      level: LogLevels.INFO,
      loggerName: "example",
    });
    const formatted = handler.format(record);
    assertEquals(formatted, "INFO Hello, world!");

handle

  • handle(logRecord): void

  • Handles a log record and flushes the buffer if the log level is higher than error.

    Parameters

    Returns void

    Example: Usage

    import { FileHandler } from "@std/log/file-handler";
    import { assertInstanceOf } from "@std/assert/instance-of";
    import { LogLevels } from "./levels.ts";
    import { LogRecord } from "./logger.ts";

    const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
    handler.setup();

    // Flushes the buffer immediately and logs "CRITICAL This log is very critical indeed." into the file.
    handler.handle(
      new LogRecord({
        msg: "This log is very critical indeed.",
        args: [],
        level: LogLevels.CRITICAL,
        loggerName: "INFO",
      }),
    );
    handler.destroy();

    assertInstanceOf(handler, FileHandler);

log

  • log(msg): void

  • Logs a message by adding it to the buffer, with flushing as needed.

    Parameters

    • msg: string

      The message to log.

    Returns void

    Example: Usage

    import { FileHandler } from "@std/log/file-handler";
    import { assertInstanceOf } from "@std/assert/instance-of";

    const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
    handler.setup();
    handler.log('Hello, world!');
    handler.flush();
    handler.destroy();

    assertInstanceOf(handler, FileHandler);

setup

  • setup(): void

  • Sets up the file handler by opening the specified file and initializing resources.

    Returns void

    Example: Usage

    import { FileHandler } from "@std/log/file-handler";

    const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
    handler.setup(); // Opens the file and prepares the handler for logging.
    handler.destroy();

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods