@logtape/logtape 0.1.0-dev.9 → 0.1.0

package/README.md

@@ -3,16 +3,357 @@
 LogTape
 =======
 
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
 [![GitHub Actions][GitHub Actions badge]][GitHub Actions]
 [![Codecov][Codecov badge]][Codecov]
 
+> [!NOTE]
+> LogTape is still in the early stage of development.  The API is not stable
+> yet.  Please be careful when using it in production.
+
 LogTape is a simple logging library for Deno/Node.js/Bun/browsers.  It is
 designed to be used for both applications and libraries.
 
 Currently, LogTape provides only few sinks, but you can easily add your own
 sinks.
 
+![](./screenshots/web-console.png)
+![](./screenshots/terminal-console.png)
+
+[JSR]: https://jsr.io/@logtape/logtape
+[JSR badge]: https://jsr.io/badges/@logtape/logtape
+[npm]: https://www.npmjs.com/package/@logtape/logtape
+[npm badge]: https://img.shields.io/npm/v/@logtape/logtape?logo=npm
 [GitHub Actions]: https://github.com/dahlia/logtape/actions/workflows/main.yaml
 [GitHub Actions badge]: https://github.com/dahlia/logtape/actions/workflows/main.yaml/badge.svg
 [Codecov]: https://codecov.io/gh/dahlia/logtape
 [Codecov badge]: https://codecov.io/gh/dahlia/logtape/graph/badge.svg?token=yOejfcuX7r
+
+
+Installation
+------------
+
+### Deno
+
+~~~~ sh
+deno add @logtape/logtape
+~~~~
+
+### Node.js
+
+~~~~ sh
+npm add @logtape/logtape
+~~~~
+
+### Bun
+
+~~~~ sh
+bun add @logtape/logtape
+~~~~
+
+
+Quick start
+-----------
+
+Set up LogTape in the entry point of your application (if you are composing
+a library, you should not set up LogTape in the library itself; it is up to
+the application to set up LogTape):
+
+~~~~ typescript
+import { configure, getConsoleSink } from "@logtape/logtape";
+
+configure({
+  sinks: { console: getConsoleSink() },
+  filters: {},
+  loggers: [
+    { category: "my-app", level: "debug", sinks: ["console"] }
+  ]
+});
+~~~~
+
+And then you can use LogTape in your application or library:
+
+~~~~ typescript
+import { getLogger } from "@logtape/logtape";
+
+const logger = getLogger(["my-app", "my-module"]);
+
+export function myFunc(value: number): void {
+  logger.debug `Hello, ${value}!`;
+}
+~~~~
+
+
+How to log
+----------
+
+There are total 5 log levels: `debug`, `info`, `warning`, `error`, `fatal` (in
+the order of verbosity).  You can log messages with the following syntax:
+
+~~~~ typescript
+logger.debug `This is a debug message with ${value}.`;
+logger.info  `This is an info message with ${value}.`;
+logger.warn  `This is a warning message with ${value}.`;
+logger.error `This is an error message with ${value}.`;
+logger.fatal `This is a fatal message with ${value}.`;
+~~~~
+
+You can also log messages with a function call:
+
+~~~~ typescript
+logger.debug("This is a debug message with {value}.", { value });
+logger.info("This is an info message with {value}.", { value });
+logger.warn("This is a warning message with {value}.", { value });
+logger.error("This is an error message with {value}.", { value });
+logger.fatal("This is a fatal message with {value}.", { value });
+~~~~
+
+Sometimes, values to be logged are expensive to compute.  In such cases, you
+can use a function to defer the computation so that it is only computed when
+the log message is actually logged:
+
+~~~~ typescript
+logger.debug(l => l`This is a debug message with ${computeValue()}.`);
+logger.debug("Or you can use a function call: {value}.", () => {
+  return { value: computeValue() };
+});
+~~~~
+
+
+Categories
+----------
+
+LogTape uses a hierarchical category system to manage loggers.  A category is
+a list of strings.  For example, `["my-app", "my-module"]` is a category.
+
+When you log a message, it is dispatched to all loggers whose categories are
+prefixes of the category of the logger.  For example, if you log a message
+with the category `["my-app", "my-module", "my-submodule"]`, it is dispatched
+to loggers whose categories are `["my-app", "my-module"]` and `["my-app"]`.
+
+This behavior allows you to control the verbosity of log messages by setting
+the log level of loggers at different levels of the category hierarchy.
+
+Here's an example of setting log levels for different categories:
+
+~~~~ typescript
+import { configure, getConsoleSink } from "@logtape/logtape";
+
+configure({
+  sinks: {
+    console: getConsoleSink(),
+  },
+  filters: {},
+  loggers: [
+    { category: ["my-app"], level: "info", sinks: ["console"] },
+    { category: ["my-app", "my-module"], level: "debug", sinks: ["console"] },
+  ],
+})
+~~~~
+
+
+Sinks
+-----
+
+A sink is a destination of log messages.  LogTape currently provides a few
+sinks: console and stream.  However, you can easily add your own sinks.
+The signature of a sink is:
+
+~~~~ typescript
+export type Sink = (record: LogRecord) => void;
+~~~~
+
+Here's a simple example of a sink that writes log messages to console:
+
+~~~~ typescript
+import { configure } from "@logtape/logtape";
+
+configure({
+  sinks: {
+    console(record) {
+      console.log(record.message);
+    }
+  },
+  // Omitted for brevity
+});
+~~~~
+
+### Console sink
+
+Of course, you don't have to implement your own console sink because LogTape
+provides a console sink:
+
+~~~~ typescript
+import { configure, getConsoleSink } from "@logtape/logtape";
+
+configure({
+  sinks: {
+    console: getConsoleSink(),
+  },
+  // Omitted for brevity
+});
+~~~~
+
+See also [`getConsoleSink()`] function and [`ConsoleSinkOptions`] interface
+in the API reference for more details.
+
+[`getConsoleSink()`]: https://jsr.io/@logtape/logtape/doc/~/getConsoleSink
+[`ConsoleSinkOptions`]: https://jsr.io/@logtape/logtape/doc/~/ConsoleSinkOptions
+
+### Stream sink
+
+Another built-in sink is a stream sink.  It writes log messages to
+a [`WritableStream`].  Here's an example of a stream sink that writes log
+messages to the standard error:
+
+~~~~ typescript
+// Deno:
+configure({
+  sinks: {
+    stream: getStreamSink(Deno.stderr.writable),
+  },
+  // Omitted for brevity
+});
+~~~~
+
+~~~~ typescript
+// Node.js:
+import stream from "node:stream";
+
+configure({
+  sinks: {
+    stream: getStreamSink(stream.Writable.toWeb(process.stderr)),
+  },
+  // Omitted for brevity
+});
+~~~~
+
+> [!NOTE]
+> Here we use `WritableStream` from the Web Streams API.  If you are using
+> Node.js, you cannot directly pass `process.stderr` to `getStreamSink` because
+> `process.stderr` is not a `WritableStream` but a [`Writable`], which is a
+> Node.js stream.  You can use [`Writable.toWeb()`] method to convert a Node.js
+> stream to a `WritableStream`.
+
+See also [`getStreamSink()`] function and [`StreamSinkOptions`] interface
+in the API reference for more details.
+
+[`WritableStream`]: https://developer.mozilla.org/en-US/docs/Web/API/WritableStream
+[`Writable`]: https://nodejs.org/api/stream.html#class-streamwritable
+[`Writable.toWeb()`]: https://nodejs.org/api/stream.html#streamwritabletowebstreamwritable
+[`getStreamSink()`]: https://jsr.io/@logtape/logtape/doc/~/getStreamSink
+[`StreamSinkOptions`]: https://jsr.io/@logtape/logtape/doc/~/StreamSinkOptions
+
+### File sink
+
+> [!NOTE]
+> File sink is unavailable in the browser environment.
+
+LogTape provides a file sink as well.  Here's an example of a file sink that
+writes log messages to a file:
+
+~~~~ typescript
+import { getFileSink } from "@logtape/logtape";
+
+configure({
+  sinks: {
+    file: getFileSink("my-app.log"),
+  },
+  // Omitted for brevity
+});
+~~~~
+
+See also [`getFileSink()`] function and [`FileSinkOptions`] interface
+in the API reference for more details.
+
+[`getFileSink()`]: https://jsr.io/@logtape/logtape/doc/~/getFileSink
+[`FileSinkOptions`]: https://jsr.io/@logtape/logtape/doc/~/FileSinkOptions
+
+### Text formatter
+
+A stream sink and a file sink write log messages in a plain text format.
+You can customize the format by providing a text formatter.  The type of a
+text formatter is:
+
+~~~~ typescript
+export type TextFormatter = (record: LogRecord) => string;
+~~~~
+
+Here's an example of a text formatter that writes log messages in a JSON format:
+
+~~~~ typescript
+configure({
+  sinks: {
+    stream: getStreamSink(Deno.stderr.writable, {
+      formatter: JSON.stringify,
+    }),
+  },
+  // Omitted for brevity
+})
+~~~~
+
+### Disposable sink
+
+A disposable sink is a sink that can be disposed of.  They are automatically
+disposed of when the configuration is reset or the program exits.  The type
+of a disposable sink is: `Sink & Disposable`.  You can create a disposable
+sink by defining a `[Symbol.dispose]` method:
+
+~~~~ typescript
+const disposableSink: Sink & Disposable = (record: LogRecord) => {
+  console.log(record.message);
+};
+disposableSink[Symbol.dispose] = () => {
+  console.log("Disposed!");
+};
+~~~~
+
+
+Testing
+-------
+
+Here are some tips for testing your application or library with LogTape.
+
+### Reset configuration
+
+You can reset the configuration of LogTape to its initial state.  This is
+useful when you want to reset the configuration between tests.  For example,
+the following code shows how to reset the configuration after a test
+(regardless of whether the test passes or fails) in Deno:
+
+~~~~ typescript
+import { configure, reset } from "@logtape/logtape";
+
+Deno.test("my test", async (t) => {
+  await t.step("set up", () => {
+    configure({ /* ... */ });
+  });
+
+  await t.step("run test", () => {
+    // Run the test
+  });
+
+  await t.step("tear down", () => {
+    reset();
+  });
+});
+~~~~
+
+### Buffer sink
+
+For testing purposes, you may want to collect log messages in memory.  Although
+LogTape does not provide a built-in buffer sink, you can easily implement it:
+
+~~~~ typescript
+import { type LogRecord, configure } from "@logtape/logtape";
+
+const buffer: LogRecord[] = [];
+
+configure({
+  sinks: {
+    buffer: buffer.push.bind(buffer),
+  },
+  // Omitted for brevity
+});
+~~~~

package/esm/config.js

@@ -1,10 +1,21 @@
+import * as dntShim from "./_dnt.shims.js";
 import { toFilter } from "./filter.js";
 import { LoggerImpl } from "./logger.js";
 import { getConsoleSink } from "./sink.js";
+/**
+ * Whether the loggers are configured.
+ */
 let configured = false;
+/**
+ * Disposables to dispose when resetting the configuration.
+ */
+const disposables = new Set();
 /**
  * Configure the loggers with the specified configuration.
  *
+ * Note that if the given sinks or filters are disposable, they will be
+ * disposed when the configuration is reset, or when the process exits.
+ *
  * @example
  * ```typescript
  * configure({
@@ -42,8 +53,8 @@ export function configure(config) {
     if (configured && !config.reset) {
         throw new ConfigError("Already configured; if you want to reset, turn on the reset flag.");
     }
+    reset();
     configured = true;
-    LoggerImpl.getLogger([]).resetDescendants();
     let metaConfigured = false;
     for (const cfg of config.loggers) {
         if (cfg.category.length === 0 ||
@@ -73,6 +84,20 @@ export function configure(config) {
             logger.filters.push(toFilter(filter));
         }
     }
+    for (const sink of Object.values(config.sinks)) {
+        if (Symbol.dispose in sink)
+            disposables.add(sink);
+    }
+    for (const filter of Object.values(config.filters)) {
+        if (filter != null && typeof filter !== "string" && Symbol.dispose in filter)
+            disposables.add(filter);
+    }
+    if ("process" in dntShim.dntGlobalThis) { // @ts-ignore: It's fine to use process in Node
+        process.on("exit", dispose);
+    }
+    else { // @ts-ignore: It's fine to addEventListener() on the browser/Deno
+        addEventListener("unload", dispose);
+    }
     const meta = LoggerImpl.getLogger(["logtape", "meta"]);
     if (!metaConfigured) {
         meta.sinks.push(getConsoleSink());
@@ -90,9 +115,18 @@ export function configure(config) {
  * Reset the configuration.  Mostly for testing purposes.
  */
 export function reset() {
+    dispose();
     LoggerImpl.getLogger([]).resetDescendants();
     configured = false;
 }
+/**
+ * Dispose of the disposables.
+ */
+export function dispose() {
+    for (const disposable of disposables)
+        disposable[Symbol.dispose]();
+    disposables.clear();
+}
 /**
  * A configuration error.
  */

package/esm/filesink.node.js

@@ -0,0 +1,32 @@
+import * as dntShim from "./_dnt.shims.js";
+import fs from "node:fs";
+import { webDriver } from "./filesink.web.js";
+import { getFileSink as getBaseFileSink, } from "./sink.js";
+/**
+ * A Node.js-specific file sink driver.
+ */
+export const nodeDriver = {
+    openSync(path) {
+        return fs.openSync(path, "a");
+    },
+    writeSync: fs.writeSync,
+    flushSync: fs.fsyncSync,
+    closeSync: fs.closeSync,
+};
+/**
+ * Get a file sink.
+ *
+ * Note that this function is unavailable in the browser.
+ *
+ * @param path A path to the file to write to.
+ * @param options The options for the sink.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed.
+ */
+export function getFileSink(path, options = {}) {
+    if ("document" in dntShim.dntGlobalThis) {
+        return getBaseFileSink(path, { ...options, ...webDriver });
+    }
+    return getBaseFileSink(path, { ...options, ...nodeDriver });
+}
+// cSpell: ignore filesink

package/esm/filesink.web.js

@@ -0,0 +1,12 @@
+function notImplemented() {
+    throw new Error("File sink is not available in the browser.");
+}
+/**
+ * A browser-specific file sink driver.  All methods throw an error.
+ */
+export const webDriver = {
+    openSync: notImplemented,
+    writeSync: notImplemented,
+    flushSync: notImplemented,
+    closeSync: notImplemented,
+};

package/esm/formatter.js

@@ -29,7 +29,7 @@ const inspect = eval(`(
  * The default text formatter.  This formatter formats log records as follows:
  *
  * ```
- * 2023-11-14 22:13:20.000 +00:00 [INF] Hello, world!
+ * 2023-11-14 22:13:20.000 +00:00 [INF] category·subcategory: Hello, world!
  * ```
  *
  * @param record The log record to format.
@@ -44,7 +44,8 @@ export function defaultTextFormatter(record) {
         else
             msg += inspect(record.message[i]);
     }
-    return `${ts.toISOString().replace("T", " ").replace("Z", " +00:00")} [${levelAbbreviations[record.level]}] ${msg}\n`;
+    const category = record.category.join("\xb7");
+    return `${ts.toISOString().replace("T", " ").replace("Z", " +00:00")} [${levelAbbreviations[record.level]}] ${category}: ${msg}\n`;
 }
 /**
  * The styles for the log level in the console.
@@ -52,9 +53,9 @@ export function defaultTextFormatter(record) {
 const logLevelStyles = {
     "debug": "background-color: gray; color: white;",
     "info": "background-color: white; color: black;",
-    "warning": "background-color: orange;",
-    "error": "background-color: red;",
-    "fatal": "background-color: maroon;",
+    "warning": "background-color: orange; color: black;",
+    "error": "background-color: red; color: white;",
+    "fatal": "background-color: maroon; color: white;",
 };
 /**
  * The default console formatter.
@@ -74,8 +75,11 @@ export function defaultConsoleFormatter(record) {
             values.push(record.message[i]);
         }
     }
+    const date = new Date(record.timestamp);
+    const time = `${date.getUTCHours().toString().padStart(2, "0")}:${date.getUTCMinutes().toString().padStart(2, "0")}:${date.getUTCSeconds().toString().padStart(2, "0")}.${date.getUTCMilliseconds().toString().padStart(3, "0")}`;
     return [
-        `%c${record.level.toUpperCase()}%c %c${record.category.join("\xb7")} %c${msg}`,
+        `%c${time} %c${levelAbbreviations[record.level]}%c %c${record.category.join("\xb7")} %c${msg}`,
+        "color: gray;",
         logLevelStyles[record.level],
         "background-color: default;",
         "color: gray;",

package/esm/mod.js

@@ -1,5 +1,7 @@
-export { ConfigError, configure, } from "./config.js";
+export { ConfigError, configure, reset, } from "./config.js";
+export { getFileSink } from "./filesink.node.js";
 export { getLevelFilter, toFilter, } from "./filter.js";
-export { defaultConsoleFormatter, } from "./formatter.js";
+export { defaultConsoleFormatter, defaultTextFormatter, } from "./formatter.js";
 export { getLogger } from "./logger.js";
-export { getConsoleSink } from "./sink.js";
+export { getConsoleSink, getStreamSink, } from "./sink.js";
+// cSpell: ignore filesink

package/esm/sink.js

@@ -20,28 +20,29 @@ import { defaultConsoleFormatter, defaultTextFormatter, } from "./formatter.js";
  * ```
  *
  * @param stream The stream to write to.
- * @param formatter The text formatter to use.  Defaults to
- *                  {@link defaultTextFormatter}.
- * @param encoder The text encoder to use.  Defaults to an instance of
- *                {@link TextEncoder}.
+ * @param options The options for the sink.
  * @returns A sink that writes to the stream.
  */
-export function getStreamSink(stream, formatter = defaultTextFormatter, encoder = new TextEncoder()) {
+export function getStreamSink(stream, options = {}) {
+    const formatter = options.formatter ?? defaultTextFormatter;
+    const encoder = options.encoder ?? new TextEncoder();
     const writer = stream.getWriter();
-    return (record) => {
+    const sink = (record) => {
         const bytes = encoder.encode(formatter(record));
         writer.ready.then(() => writer.write(bytes));
     };
+    sink[Symbol.dispose] = () => writer.close();
+    return sink;
 }
 /**
  * A console sink factory that returns a sink that logs to the console.
  *
- * @param formatter A console formatter.  Defaults to
- *                  {@link defaultConsoleFormatter}.
- * @param console The console to log to.  Defaults to {@link console}.
+ * @param options The options for the sink.
  * @returns A sink that logs to the console.
  */
-export function getConsoleSink(formatter = defaultConsoleFormatter, console = globalThis.console) {
+export function getConsoleSink(options = {}) {
+    const formatter = options.formatter ?? defaultConsoleFormatter;
+    const console = options.console ?? globalThis.console;
     return (record) => {
         const args = formatter(record);
         if (record.level === "debug")
@@ -57,3 +58,23 @@ export function getConsoleSink(formatter = defaultConsoleFormatter, console = gl
             throw new TypeError(`Invalid log level: ${record.level}.`);
     };
 }
+/**
+ * Get a platform-independent file sink.
+ *
+ * @typeParam TFile The type of the file descriptor.
+ * @param path A path to the file to write to.
+ * @param options The options for the sink and the file driver.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed.
+ */
+export function getFileSink(path, options) {
+    const formatter = options.formatter ?? defaultTextFormatter;
+    const encoder = options.encoder ?? new TextEncoder();
+    const fd = options.openSync(path);
+    const sink = (record) => {
+        options.writeSync(fd, encoder.encode(formatter(record)));
+        options.flushSync(fd);
+    };
+    sink[Symbol.dispose] = () => options.closeSync(fd);
+    return sink;
+}

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@logtape/logtape",
-  "version": "0.1.0-dev.9+dfa649b3",
+  "version": "0.1.0",
   "description": "Simple logging library for Deno/Node.js/Bun/browsers",
+  "keywords": [
+    "logging",
+    "log",
+    "logger"
+  ],
   "author": {
     "name": "Hong Minhee",
     "email": "hong@minhee.org",

package/script/config.js

@@ -1,13 +1,47 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConfigError = exports.reset = exports.configure = void 0;
+exports.ConfigError = exports.dispose = exports.reset = exports.configure = void 0;
+const dntShim = __importStar(require("./_dnt.shims.js"));
 const filter_js_1 = require("./filter.js");
 const logger_js_1 = require("./logger.js");
 const sink_js_1 = require("./sink.js");
+/**
+ * Whether the loggers are configured.
+ */
 let configured = false;
+/**
+ * Disposables to dispose when resetting the configuration.
+ */
+const disposables = new Set();
 /**
  * Configure the loggers with the specified configuration.
  *
+ * Note that if the given sinks or filters are disposable, they will be
+ * disposed when the configuration is reset, or when the process exits.
+ *
  * @example
  * ```typescript
  * configure({
@@ -45,8 +79,8 @@ function configure(config) {
     if (configured && !config.reset) {
         throw new ConfigError("Already configured; if you want to reset, turn on the reset flag.");
     }
+    reset();
     configured = true;
-    logger_js_1.LoggerImpl.getLogger([]).resetDescendants();
     let metaConfigured = false;
     for (const cfg of config.loggers) {
         if (cfg.category.length === 0 ||
@@ -76,6 +110,20 @@ function configure(config) {
             logger.filters.push((0, filter_js_1.toFilter)(filter));
         }
     }
+    for (const sink of Object.values(config.sinks)) {
+        if (Symbol.dispose in sink)
+            disposables.add(sink);
+    }
+    for (const filter of Object.values(config.filters)) {
+        if (filter != null && typeof filter !== "string" && Symbol.dispose in filter)
+            disposables.add(filter);
+    }
+    if ("process" in dntShim.dntGlobalThis) { // @ts-ignore: It's fine to use process in Node
+        process.on("exit", dispose);
+    }
+    else { // @ts-ignore: It's fine to addEventListener() on the browser/Deno
+        addEventListener("unload", dispose);
+    }
     const meta = logger_js_1.LoggerImpl.getLogger(["logtape", "meta"]);
     if (!metaConfigured) {
         meta.sinks.push((0, sink_js_1.getConsoleSink)());
@@ -94,10 +142,20 @@ exports.configure = configure;
  * Reset the configuration.  Mostly for testing purposes.
  */
 function reset() {
+    dispose();
     logger_js_1.LoggerImpl.getLogger([]).resetDescendants();
     configured = false;
 }
 exports.reset = reset;
+/**
+ * Dispose of the disposables.
+ */
+function dispose() {
+    for (const disposable of disposables)
+        disposable[Symbol.dispose]();
+    disposables.clear();
+}
+exports.dispose = dispose;
 /**
  * A configuration error.
  */

package/script/filesink.node.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFileSink = exports.nodeDriver = void 0;
+const dntShim = __importStar(require("./_dnt.shims.js"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const filesink_web_js_1 = require("./filesink.web.js");
+const sink_js_1 = require("./sink.js");
+/**
+ * A Node.js-specific file sink driver.
+ */
+exports.nodeDriver = {
+    openSync(path) {
+        return node_fs_1.default.openSync(path, "a");
+    },
+    writeSync: node_fs_1.default.writeSync,
+    flushSync: node_fs_1.default.fsyncSync,
+    closeSync: node_fs_1.default.closeSync,
+};
+/**
+ * Get a file sink.
+ *
+ * Note that this function is unavailable in the browser.
+ *
+ * @param path A path to the file to write to.
+ * @param options The options for the sink.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed.
+ */
+function getFileSink(path, options = {}) {
+    if ("document" in dntShim.dntGlobalThis) {
+        return (0, sink_js_1.getFileSink)(path, { ...options, ...filesink_web_js_1.webDriver });
+    }
+    return (0, sink_js_1.getFileSink)(path, { ...options, ...exports.nodeDriver });
+}
+exports.getFileSink = getFileSink;
+// cSpell: ignore filesink

package/script/filesink.web.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webDriver = void 0;
+function notImplemented() {
+    throw new Error("File sink is not available in the browser.");
+}
+/**
+ * A browser-specific file sink driver.  All methods throw an error.
+ */
+exports.webDriver = {
+    openSync: notImplemented,
+    writeSync: notImplemented,
+    flushSync: notImplemented,
+    closeSync: notImplemented,
+};

package/script/formatter.js

@@ -32,7 +32,7 @@ const inspect = eval(`(
  * The default text formatter.  This formatter formats log records as follows:
  *
  * ```
- * 2023-11-14 22:13:20.000 +00:00 [INF] Hello, world!
+ * 2023-11-14 22:13:20.000 +00:00 [INF] category·subcategory: Hello, world!
  * ```
  *
  * @param record The log record to format.
@@ -47,7 +47,8 @@ function defaultTextFormatter(record) {
         else
             msg += inspect(record.message[i]);
     }
-    return `${ts.toISOString().replace("T", " ").replace("Z", " +00:00")} [${levelAbbreviations[record.level]}] ${msg}\n`;
+    const category = record.category.join("\xb7");
+    return `${ts.toISOString().replace("T", " ").replace("Z", " +00:00")} [${levelAbbreviations[record.level]}] ${category}: ${msg}\n`;
 }
 exports.defaultTextFormatter = defaultTextFormatter;
 /**
@@ -56,9 +57,9 @@ exports.defaultTextFormatter = defaultTextFormatter;
 const logLevelStyles = {
     "debug": "background-color: gray; color: white;",
     "info": "background-color: white; color: black;",
-    "warning": "background-color: orange;",
-    "error": "background-color: red;",
-    "fatal": "background-color: maroon;",
+    "warning": "background-color: orange; color: black;",
+    "error": "background-color: red; color: white;",
+    "fatal": "background-color: maroon; color: white;",
 };
 /**
  * The default console formatter.
@@ -78,8 +79,11 @@ function defaultConsoleFormatter(record) {
             values.push(record.message[i]);
         }
     }
+    const date = new Date(record.timestamp);
+    const time = `${date.getUTCHours().toString().padStart(2, "0")}:${date.getUTCMinutes().toString().padStart(2, "0")}:${date.getUTCSeconds().toString().padStart(2, "0")}.${date.getUTCMilliseconds().toString().padStart(3, "0")}`;
     return [
-        `%c${record.level.toUpperCase()}%c %c${record.category.join("\xb7")} %c${msg}`,
+        `%c${time} %c${levelAbbreviations[record.level]}%c %c${record.category.join("\xb7")} %c${msg}`,
+        "color: gray;",
         logLevelStyles[record.level],
         "background-color: default;",
         "color: gray;",

package/script/mod.js

@@ -1,15 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getConsoleSink = exports.getLogger = exports.defaultConsoleFormatter = exports.toFilter = exports.getLevelFilter = exports.configure = exports.ConfigError = void 0;
+exports.getStreamSink = exports.getConsoleSink = exports.getLogger = exports.defaultTextFormatter = exports.defaultConsoleFormatter = exports.toFilter = exports.getLevelFilter = exports.getFileSink = exports.reset = exports.configure = exports.ConfigError = void 0;
 var config_js_1 = require("./config.js");
 Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return config_js_1.ConfigError; } });
 Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return config_js_1.configure; } });
+Object.defineProperty(exports, "reset", { enumerable: true, get: function () { return config_js_1.reset; } });
+var filesink_node_js_1 = require("./filesink.node.js");
+Object.defineProperty(exports, "getFileSink", { enumerable: true, get: function () { return filesink_node_js_1.getFileSink; } });
 var filter_js_1 = require("./filter.js");
 Object.defineProperty(exports, "getLevelFilter", { enumerable: true, get: function () { return filter_js_1.getLevelFilter; } });
 Object.defineProperty(exports, "toFilter", { enumerable: true, get: function () { return filter_js_1.toFilter; } });
 var formatter_js_1 = require("./formatter.js");
 Object.defineProperty(exports, "defaultConsoleFormatter", { enumerable: true, get: function () { return formatter_js_1.defaultConsoleFormatter; } });
+Object.defineProperty(exports, "defaultTextFormatter", { enumerable: true, get: function () { return formatter_js_1.defaultTextFormatter; } });
 var logger_js_1 = require("./logger.js");
 Object.defineProperty(exports, "getLogger", { enumerable: true, get: function () { return logger_js_1.getLogger; } });
 var sink_js_1 = require("./sink.js");
 Object.defineProperty(exports, "getConsoleSink", { enumerable: true, get: function () { return sink_js_1.getConsoleSink; } });
+Object.defineProperty(exports, "getStreamSink", { enumerable: true, get: function () { return sink_js_1.getStreamSink; } });
+// cSpell: ignore filesink

package/script/sink.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getConsoleSink = exports.getStreamSink = void 0;
+exports.getFileSink = exports.getConsoleSink = exports.getStreamSink = void 0;
 const formatter_js_1 = require("./formatter.js");
 /**
  * A factory that returns a sink that writes to a {@link WritableStream}.
@@ -23,29 +23,30 @@ const formatter_js_1 = require("./formatter.js");
  * ```
  *
  * @param stream The stream to write to.
- * @param formatter The text formatter to use.  Defaults to
- *                  {@link defaultTextFormatter}.
- * @param encoder The text encoder to use.  Defaults to an instance of
- *                {@link TextEncoder}.
+ * @param options The options for the sink.
  * @returns A sink that writes to the stream.
  */
-function getStreamSink(stream, formatter = formatter_js_1.defaultTextFormatter, encoder = new TextEncoder()) {
+function getStreamSink(stream, options = {}) {
+    const formatter = options.formatter ?? formatter_js_1.defaultTextFormatter;
+    const encoder = options.encoder ?? new TextEncoder();
     const writer = stream.getWriter();
-    return (record) => {
+    const sink = (record) => {
         const bytes = encoder.encode(formatter(record));
         writer.ready.then(() => writer.write(bytes));
     };
+    sink[Symbol.dispose] = () => writer.close();
+    return sink;
 }
 exports.getStreamSink = getStreamSink;
 /**
  * A console sink factory that returns a sink that logs to the console.
  *
- * @param formatter A console formatter.  Defaults to
- *                  {@link defaultConsoleFormatter}.
- * @param console The console to log to.  Defaults to {@link console}.
+ * @param options The options for the sink.
  * @returns A sink that logs to the console.
  */
-function getConsoleSink(formatter = formatter_js_1.defaultConsoleFormatter, console = globalThis.console) {
+function getConsoleSink(options = {}) {
+    const formatter = options.formatter ?? formatter_js_1.defaultConsoleFormatter;
+    const console = options.console ?? globalThis.console;
     return (record) => {
         const args = formatter(record);
         if (record.level === "debug")
@@ -62,3 +63,24 @@ function getConsoleSink(formatter = formatter_js_1.defaultConsoleFormatter, cons
     };
 }
 exports.getConsoleSink = getConsoleSink;
+/**
+ * Get a platform-independent file sink.
+ *
+ * @typeParam TFile The type of the file descriptor.
+ * @param path A path to the file to write to.
+ * @param options The options for the sink and the file driver.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed.
+ */
+function getFileSink(path, options) {
+    const formatter = options.formatter ?? formatter_js_1.defaultTextFormatter;
+    const encoder = options.encoder ?? new TextEncoder();
+    const fd = options.openSync(path);
+    const sink = (record) => {
+        options.writeSync(fd, encoder.encode(formatter(record)));
+        options.flushSync(fd);
+    };
+    sink[Symbol.dispose] = () => options.closeSync(fd);
+    return sink;
+}
+exports.getFileSink = getFileSink;

package/types/config.d.ts

@@ -50,6 +50,9 @@ export interface LoggerConfig<TSinkId extends string, TFilterId extends string>
 /**
  * Configure the loggers with the specified configuration.
  *
+ * Note that if the given sinks or filters are disposable, they will be
+ * disposed when the configuration is reset, or when the process exits.
+ *
  * @example
  * ```typescript
  * configure({
@@ -88,6 +91,10 @@ export declare function configure<TSinkId extends string, TFilterId extends stri
  * Reset the configuration.  Mostly for testing purposes.
  */
 export declare function reset(): void;
+/**
+ * Dispose of the disposables.
+ */
+export declare function dispose(): void;
 /**
  * A configuration error.
  */

package/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAY,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAkB,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,MAAM,CAAC,OAAO,SAAS,MAAM,EAAE,SAAS,SAAS,MAAM;IACtE;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAEvC;;OAEG;IACH,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IAE5C;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAC3B,OAAO,SAAS,MAAM,EACtB,SAAS,SAAS,MAAM;IAExB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAE5B;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IAEtB;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CACzB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,SAAS,CAAC,OAAO,SAAS,MAAM,EAAE,SAAS,SAAS,MAAM,EACxE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,QA0DnC;AAED;;GAEG;AACH,wBAAgB,KAAK,SAGpB;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC;;;OAGG;gBACS,OAAO,EAAE,MAAM;CAI5B"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAY,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAkB,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,MAAM,CAAC,OAAO,SAAS,MAAM,EAAE,SAAS,SAAS,MAAM;IACtE;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAEvC;;OAEG;IACH,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IAE5C;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAC3B,OAAO,SAAS,MAAM,EACtB,SAAS,SAAS,MAAM;IAExB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAE5B;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IAEtB;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CACzB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,SAAS,CAAC,OAAO,SAAS,MAAM,EAAE,SAAS,SAAS,MAAM,EACxE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,QA0EnC;AAED;;GAEG;AACH,wBAAgB,KAAK,SAIpB;AAED;;GAEG;AACH,wBAAgB,OAAO,SAGtB;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC;;;OAGG;gBACS,OAAO,EAAE,MAAM;CAI5B"}

package/types/deps/deno.land/x/which_runtime@0.2.0/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../../src/deps/deno.land/x/which_runtime@0.2.0/mod.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,MAAM,SAAgC,CAAC;AACpD,eAAO,MAAM,MAAM,SAA0B,CAAC"}

package/types/filesink.node.d.ts

@@ -0,0 +1,18 @@
+/// <reference types="node" />
+import { type FileSinkDriver, type FileSinkOptions, type Sink } from "./sink.js";
+/**
+ * A Node.js-specific file sink driver.
+ */
+export declare const nodeDriver: FileSinkDriver<number>;
+/**
+ * Get a file sink.
+ *
+ * Note that this function is unavailable in the browser.
+ *
+ * @param path A path to the file to write to.
+ * @param options The options for the sink.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed.
+ */
+export declare function getFileSink(path: string, options?: FileSinkOptions): Sink & Disposable;
+//# sourceMappingURL=filesink.node.d.ts.map

package/types/filesink.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesink.node.d.ts","sourceRoot":"","sources":["../src/filesink.node.ts"],"names":[],"mappings":";AAGA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,eAAe,EAEpB,KAAK,IAAI,EACV,MAAM,WAAW,CAAC;AAEnB;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,MAAM,CAO7C,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,GAC5B,IAAI,GAAG,UAAU,CAKnB"}

package/types/filesink.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesink.test.d.ts","sourceRoot":"","sources":["../src/filesink.test.ts"],"names":[],"mappings":""}

package/types/filesink.web.d.ts

@@ -0,0 +1,6 @@
+import type { FileSinkDriver } from "./sink.js";
+/**
+ * A browser-specific file sink driver.  All methods throw an error.
+ */
+export declare const webDriver: FileSinkDriver<void>;
+//# sourceMappingURL=filesink.web.d.ts.map

package/types/filesink.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesink.web.d.ts","sourceRoot":"","sources":["../src/filesink.web.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMhD;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,IAAI,CAK1C,CAAC"}

package/types/formatter.d.ts

@@ -11,7 +11,7 @@ export type TextFormatter = (record: LogRecord) => string;
  * The default text formatter.  This formatter formats log records as follows:
  *
  * ```
- * 2023-11-14 22:13:20.000 +00:00 [INF] Hello, world!
+ * 2023-11-14 22:13:20.000 +00:00 [INF] category·subcategory: Hello, world!
  * ```
  *
  * @param record The log record to format.

package/types/formatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAY,SAAS,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,MAAM,CAAC;AA+B1D;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAU9D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,SAAS,OAAO,EAAE,CAAC;AAazE;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,OAAO,EAAE,CAoB7E"}
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAY,SAAS,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,MAAM,CAAC;AA+B1D;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAW9D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,SAAS,OAAO,EAAE,CAAC;AAazE;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,OAAO,EAAE,CA2B7E"}

package/types/mod.d.ts

@@ -1,7 +1,8 @@
-export { type Config, ConfigError, configure, type LoggerConfig, } from "./config.js";
+export { type Config, ConfigError, configure, type LoggerConfig, reset, } from "./config.js";
+export { getFileSink } from "./filesink.node.js";
 export { type Filter, type FilterLike, getLevelFilter, toFilter, } from "./filter.js";
-export { type ConsoleFormatter, defaultConsoleFormatter, type TextFormatter, } from "./formatter.js";
+export { type ConsoleFormatter, defaultConsoleFormatter, defaultTextFormatter, type TextFormatter, } from "./formatter.js";
 export { getLogger, type Logger } from "./logger.js";
 export type { LogLevel, LogRecord } from "./record.js";
-export { getConsoleSink, type Sink } from "./sink.js";
+export { type ConsoleSinkOptions, type FileSinkDriver, type FileSinkOptions, getConsoleSink, getStreamSink, type Sink, type StreamSinkOptions, } from "./sink.js";
 //# sourceMappingURL=mod.d.ts.map

package/types/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EACX,WAAW,EACX,SAAS,EACT,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,MAAM,EACX,KAAK,UAAU,EACf,cAAc,EACd,QAAQ,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,gBAAgB,EACrB,uBAAuB,EACvB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EACX,WAAW,EACX,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EACL,KAAK,MAAM,EACX,KAAK,UAAU,EACf,cAAc,EACd,QAAQ,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,gBAAgB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,cAAc,EACd,aAAa,EACb,KAAK,IAAI,EACT,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAC"}

package/types/sink.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 /// <reference types="node" />
+/// <reference types="node" />
 import * as dntShim from "./_dnt.shims.js";
 import { type ConsoleFormatter, type TextFormatter } from "./formatter.js";
 import type { LogRecord } from "./record.js";
@@ -13,6 +14,21 @@ import type { LogRecord } from "./record.js";
  * @param record The log record to sink.
  */
 export type Sink = (record: LogRecord) => void;
+/**
+ * Options for the {@link getStreamSink} function.
+ */
+export interface StreamSinkOptions {
+    /**
+     * The text formatter to use.  Defaults to {@link defaultTextFormatter}.
+     */
+    formatter?: TextFormatter;
+    /**
+     * The text encoder to use.  Defaults to an instance of {@link TextEncoder}.
+     */
+    encoder?: {
+        encode(text: string): Uint8Array;
+    };
+}
 /**
  * A factory that returns a sink that writes to a {@link WritableStream}.
  *
@@ -34,22 +50,69 @@ export type Sink = (record: LogRecord) => void;
  * ```
  *
  * @param stream The stream to write to.
- * @param formatter The text formatter to use.  Defaults to
- *                  {@link defaultTextFormatter}.
- * @param encoder The text encoder to use.  Defaults to an instance of
- *                {@link TextEncoder}.
+ * @param options The options for the sink.
  * @returns A sink that writes to the stream.
  */
-export declare function getStreamSink(stream: dntShim.WritableStream, formatter?: TextFormatter, encoder?: {
-    encode(text: string): Uint8Array;
-}): Sink;
+export declare function getStreamSink(stream: dntShim.WritableStream, options?: StreamSinkOptions): Sink & Disposable;
+/**
+ * Options for the {@link getConsoleSink} function.
+ */
+export interface ConsoleSinkOptions {
+    /**
+     * The console formatter to use.  Defaults to {@link defaultConsoleFormatter}.
+     */
+    formatter?: ConsoleFormatter;
+    /**
+     * The console to log to.  Defaults to {@link console}.
+     */
+    console?: Console;
+}
 /**
  * A console sink factory that returns a sink that logs to the console.
  *
- * @param formatter A console formatter.  Defaults to
- *                  {@link defaultConsoleFormatter}.
- * @param console The console to log to.  Defaults to {@link console}.
+ * @param options The options for the sink.
  * @returns A sink that logs to the console.
  */
-export declare function getConsoleSink(formatter?: ConsoleFormatter, console?: Console): Sink;
+export declare function getConsoleSink(options?: ConsoleSinkOptions): Sink;
+/**
+ * Options for the {@link getFileSink} function.
+ */
+export type FileSinkOptions = StreamSinkOptions;
+/**
+ * A platform-specific file sink driver.
+ * @typeParam TFile The type of the file descriptor.
+ */
+export interface FileSinkDriver<TFile> {
+    /**
+     * Open a file for appending and return a file descriptor.
+     * @param path A path to the file to open.
+     */
+    openSync(path: string): TFile;
+    /**
+     * Write a chunk of data to the file.
+     * @param fd The file descriptor.
+     * @param chunk The data to write.
+     */
+    writeSync(fd: TFile, chunk: Uint8Array): void;
+    /**
+     * Flush the file to ensure that all data is written to the disk.
+     * @param fd The file descriptor.
+     */
+    flushSync(fd: TFile): void;
+    /**
+     * Close the file.
+     * @param fd The file descriptor.
+     */
+    closeSync(fd: TFile): void;
+}
+/**
+ * Get a platform-independent file sink.
+ *
+ * @typeParam TFile The type of the file descriptor.
+ * @param path A path to the file to write to.
+ * @param options The options for the sink and the file driver.
+ * @returns A sink that writes to the file.  The sink is also a disposable
+ *          object that closes the file when disposed.
+ */
+export declare function getFileSink<TFile>(path: string, options: FileSinkOptions & FileSinkDriver<TFile>): Sink & Disposable;
 //# sourceMappingURL=sink.d.ts.map

package/types/sink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../src/sink.ts"],"names":[],"mappings":";;AAAA,OAAO,KAAK,OAAO,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EACL,KAAK,gBAAgB,EAGrB,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,OAAO,CAAC,cAAc,EAC9B,SAAS,GAAE,aAAoC,EAC/C,OAAO,GAAE;IAAE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;CAAsB,GAChE,IAAI,CAMN;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,SAAS,GAAE,gBAA0C,EACrD,OAAO,GAAE,OAA4B,GACpC,IAAI,CAUN"}
+{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../src/sink.ts"],"names":[],"mappings":";;;AAAA,OAAO,KAAK,OAAO,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EACL,KAAK,gBAAgB,EAGrB,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,OAAO,CAAC,cAAc,EAC9B,OAAO,GAAE,iBAAsB,GAC9B,IAAI,GAAG,UAAU,CAUnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAE7B;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,kBAAuB,GAAG,IAAI,CAYrE;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK;IACnC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAE9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAE9C;;;OAGG;IACH,SAAS,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,GAAG,cAAc,CAAC,KAAK,CAAC,GAC/C,IAAI,GAAG,UAAU,CAUnB"}