@logtape/logtape 0.1.0-dev.12 → 0.1.0-dev.14

package/README.md

@@ -16,6 +16,9 @@ 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)
+
 [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
@@ -126,6 +129,23 @@ 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
 -----
@@ -153,6 +173,8 @@ configure({
 });
 ~~~~
 
+### Console sink
+
 Of course, you don't have to implement your own console sink because LogTape
 provides a console sink:
 
@@ -167,19 +189,38 @@ configure({
 });
 ~~~~
 
+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:
-const stderrSink = getStreamSink(Deno.stderr.writable);
+configure({
+  sinks: {
+    stream: getStreamSink(Deno.stderr.writable),
+  },
+  // Omitted for brevity
+});
 ~~~~
 
 ~~~~ typescript
 // Node.js:
 import stream from "node:stream";
-const stderrSink = getStreamSink(stream.Writable.toWeb(process.stderr));
+
+configure({
+  sinks: {
+    stream: getStreamSink(stream.Writable.toWeb(process.stderr)),
+  },
+  // Omitted for brevity
+});
 ~~~~
 
 > [!NOTE]
@@ -189,6 +230,114 @@ const stderrSink = getStreamSink(stream.Writable.toWeb(process.stderr));
 > 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
+
+LogTape provides a platform-independent file sink.  You can use it by providing
+a platform-specific file driver for Deno or Node.js.  Here's an example of
+a file sink that writes log messages to a file:
+
+~~~~ typescript
+// Deno
+import { type FileSinkDriver, getFileSink } from "@logtape/logtape";
+
+const driver: FileSinkDriver<Deno.FsFile> = {
+  openSync(path: string) {
+    return Deno.openSync(path, { create: true, append: true });
+  },
+  writeSync(fd, chunk) {
+    fd.writeSync(chunk);
+  },
+  flushSync(fd) {
+    fd.syncSync();
+  },
+  closeSync(fd) {
+    fd.close();
+  },
+};
+
+configure({
+  sinks: {
+    file: getFileSink("my-app.log", driver),
+  },
+  // Omitted for brevity
+});
+~~~~
+
+~~~~ typescript
+// Node.js or Bun
+import fs from "node:fs";
+import { type FileSinkDriver, getFileSink } from "@logtape/logtape";
+
+const driver: FileSinkDriver<number> = {
+  openSync(path: string) {
+    return fs.openSync(path, "a");
+  },
+  writeSync: fs.writeSync,
+  flushSync: fs.fsyncSync,
+  closeSync: fs.closeSync,
+};
+
+configure({
+  sinks: {
+    file: getFileSink("my-app.log", driver),
+  },
+  // Omitted for brevity
+});
+~~~~
+
+See also [`getFileSink()`] function, [`FileSinkOptions`] interface, and
+[`FileSinkDriver`] interface in the API reference for more details.
+
+[`getFileSink()`]: https://jsr.io/@logtape/logtape/doc/~/getFileSink
+[`FileSinkOptions`]: https://jsr.io/@logtape/logtape/doc/~/FileSinkOptions
+[`FileSinkDriver`]: https://jsr.io/@logtape/logtape/doc/~/FileSinkDriver
+
+### 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
+});
+~~~~
+
+### 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
+})
+~~~~

package/esm/sink.js

@@ -20,13 +20,12 @@ 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 bytes = encoder.encode(formatter(record));
@@ -36,12 +35,12 @@ export function getStreamSink(stream, formatter = defaultTextFormatter, encoder
 /**
  * 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 +56,21 @@ 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.
+ */
+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.close = () => options.closeSync(fd);
+    return sink;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/logtape",
-  "version": "0.1.0-dev.12+e99600b7",
+  "version": "0.1.0-dev.14+777b0238",
   "description": "Simple logging library for Deno/Node.js/Bun/browsers",
   "keywords": [
     "logging",

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,13 +23,12 @@ 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 bytes = encoder.encode(formatter(record));
@@ -40,12 +39,12 @@ 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 +61,22 @@ 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.
+ */
+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.close = () => options.closeSync(fd);
+    return sink;
+}
+exports.getFileSink = getFileSink;

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/sink.d.ts

@@ -13,6 +13,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 +49,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;
+/**
+ * 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.
+ */
+export declare function getFileSink<TFile>(path: string, options: FileSinkOptions & FileSinkDriver<TFile>): Sink & {
+    close: () => void;
+};
 //# 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,CAQN;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;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,GAAG,cAAc,CAAC,KAAK,CAAC,GAC/C,IAAI,GAAG;IAAE,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAU9B"}