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

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,51 @@ 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
+
+### 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 writes 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")

package/package.json

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

package/script/sink.js

@@ -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")

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,28 @@ 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;
 //# 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"}