@logtape/logtape 0.3.0-dev.27 → 0.3.0-dev.29

package/README.md

@@ -293,13 +293,17 @@ await configure({
 See also [`getFileSink()`] function and [`FileSinkOptions`] interface
 in the API reference for more details.
 
+> [!NOTE]
+> On Deno, you need to have the `--allow-write` flag and the `--unstable-fs`
+> flag to use the file sink.
+
 [`getFileSink()`]: https://jsr.io/@logtape/logtape/doc/~/getFileSink
 [`FileSinkOptions`]: https://jsr.io/@logtape/logtape/doc/~/FileSinkOptions
 
 ### Rotating file sink
 
 > [!NOTE]
-> File sink is unavailable in the browser environment.
+> Rotating file sink is unavailable in the browser environment.
 
 A rotating file sink is a file sink that rotates log files.  It creates a new
 log file when the current log file reaches a certain size.  Here's an example
@@ -324,6 +328,10 @@ Rotated log files are named with a suffix like *.1*, *.2*, *.3*, and so on.
 For more details, see [`getRotatingFileSink()`] function and
 [`RotatingFileSinkOptions`] interface in the API reference.
 
+> [!NOTE]
+> On Deno, you need to have the `--allow-write` flag and the `--unstable-fs`
+> flag to use the rotating file sink.
+
 [`getRotatingFileSink()`]: https://jsr.io/@logtape/logtape/doc/~/getRotatingFileSink
 [`RotatingFileSinkOptions`]: https://jsr.io/@logtape/logtape/doc/~/RotatingFileSinkOptions
 
@@ -343,7 +351,9 @@ Here's an example of a text formatter that writes log messages in a JSON format:
 await configure({
   sinks: {
     stream: getStreamSink(Deno.stderr.writable, {
-      formatter: JSON.stringify,
+      formatter(log) {
+        return JSON.stringify(log) + "\n",
+      }
     }),
   },
   // Omitted for brevity
@@ -408,6 +418,91 @@ export default {
 [`ctx.waitUntil()`]: https://developers.cloudflare.com/workers/runtime-apis/context/#waituntil
 
 
+Filters
+-------
+
+A filter is a function that filters log messages.  A filter takes a log record
+and returns a boolean value.  If the filter returns `true`, the log record is
+passed to the sinks; otherwise, the log record is discarded.  Its signature is:
+
+~~~~ typescript
+export type Filter = (record: LogRecord) => boolean;
+~~~~
+
+For example, the following filter discards log messages whose property `elapsed`
+is less than 100 milliseconds:
+
+~~~~ typescript
+import { configure, type LogRecord } from "@logtape/logtape";
+
+await configure({
+  // Omitted for brevity
+  filters: {
+    tooSlow(record: LogRecord) {
+      return "elapsed" in record.properties && record.properties.elapsed >= 100;
+    },
+  },
+  loggers: [
+    {
+      category: ["my-app", "database"],
+      level: "debug",
+      sinks: ["console"],
+      filters: ["tooSlow"],
+    }
+  ]
+});
+~~~~
+
+### Level filter
+
+LogTape provides a built-in level filter.  You can use the level filter to
+filter log messages by their log levels.  The level filter factory takes
+a [`LogLevel`] string and returns a level filter.  For example, the following
+level filter discards log messages whose log level is less than `info`:
+
+~~~~ typescript
+import { getLevelFilter } from "@logtape/logtape";
+
+await configure({
+  filters: {
+    infoOrHigher: getLevelFilter("info");
+  },
+  // Omitted for brevity
+});
+~~~~
+
+[`LogLevel`]: https://jsr.io/@logtape/logtape/doc/~/LogLevel
+
+### Sink filter
+
+A sink filter is a filter that is applied to a specific sink.  You can add a
+sink filter to a sink by decorating the sink with [`withFilter()`]:
+
+~~~~ typescript
+import { getConsoleSink, withFilter } from "@logtape/logtape";
+
+await configure({
+  sinks: {
+    filteredConsole: withFilter(
+      getConsoleSink(),
+      log => "elapsed" in log.properties && log.properties.elapsed >= 100,
+    ),
+  },
+  // Omitted for brevity
+});
+~~~~
+
+The `filteredConsoleSink` only logs messages whose property `elapsed` is greater
+than or equal to 100 milliseconds to the console.
+
+> [!TIP]
+> The `withFilter()` function can take a [`LogLevel`] string as the second
+> argument.  In this case, the log messages whose log level is less than
+> the specified log level are discarded.
+
+[`withFilter()`]: https://jsr.io/@logtape/logtape/doc/~/withFilter
+
+
 Testing
 -------
 

package/esm/mod.js

@@ -4,5 +4,5 @@ export { getLevelFilter, toFilter, } from "./filter.js";
 export { defaultConsoleFormatter, defaultTextFormatter, } from "./formatter.js";
 export { isLogLevel, parseLogLevel } from "./level.js";
 export { getLogger } from "./logger.js";
-export { getConsoleSink, getStreamSink, } from "./sink.js";
+export { getConsoleSink, getStreamSink, withFilter, } from "./sink.js";
 // cSpell: ignore filesink

package/esm/sink.js

@@ -1,4 +1,26 @@
+import { toFilter } from "./filter.js";
 import { defaultConsoleFormatter, defaultTextFormatter, } from "./formatter.js";
+/**
+ * Turns a sink into a filtered sink.  The returned sink only logs records that
+ * pass the filter.
+ *
+ * @example Filter a console sink to only log records with the info level
+ * ```typescript
+ * const sink = withFilter(getConsoleSink(), "info");
+ * ```
+ *
+ * @param sink A sink to be filtered.
+ * @param filter A filter to apply to the sink.  It can be either a filter
+ *               function or a {@link LogLevel} string.
+ * @returns A sink that only logs records that pass the filter.
+ */
+export function withFilter(sink, filter) {
+    const filterFunc = toFilter(filter);
+    return (record) => {
+        if (filterFunc(record))
+            sink(record);
+    };
+}
 /**
  * A factory that returns a sink that writes to a {@link WritableStream}.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/logtape",
-  "version": "0.3.0-dev.27+42b10385",
+  "version": "0.3.0-dev.29+5a800eb8",
   "description": "Simple logging library with zero dependencies for Deno/Node.js/Bun/browsers",
   "keywords": [
     "logging",

package/script/mod.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getStreamSink = exports.getConsoleSink = exports.getLogger = exports.parseLogLevel = exports.isLogLevel = exports.defaultTextFormatter = exports.defaultConsoleFormatter = exports.toFilter = exports.getLevelFilter = exports.getRotatingFileSink = exports.getFileSink = exports.reset = exports.getConfig = exports.dispose = exports.configure = exports.ConfigError = void 0;
+exports.withFilter = exports.getStreamSink = exports.getConsoleSink = exports.getLogger = exports.parseLogLevel = exports.isLogLevel = exports.defaultTextFormatter = exports.defaultConsoleFormatter = exports.toFilter = exports.getLevelFilter = exports.getRotatingFileSink = exports.getFileSink = exports.reset = exports.getConfig = exports.dispose = 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; } });
@@ -24,4 +24,5 @@ Object.defineProperty(exports, "getLogger", { enumerable: true, get: function ()
 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; } });
+Object.defineProperty(exports, "withFilter", { enumerable: true, get: function () { return sink_js_1.withFilter; } });
 // cSpell: ignore filesink

package/script/sink.js

@@ -1,7 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRotatingFileSink = exports.getFileSink = exports.getConsoleSink = exports.getStreamSink = void 0;
+exports.getRotatingFileSink = exports.getFileSink = exports.getConsoleSink = exports.getStreamSink = exports.withFilter = void 0;
+const filter_js_1 = require("./filter.js");
 const formatter_js_1 = require("./formatter.js");
+/**
+ * Turns a sink into a filtered sink.  The returned sink only logs records that
+ * pass the filter.
+ *
+ * @example Filter a console sink to only log records with the info level
+ * ```typescript
+ * const sink = withFilter(getConsoleSink(), "info");
+ * ```
+ *
+ * @param sink A sink to be filtered.
+ * @param filter A filter to apply to the sink.  It can be either a filter
+ *               function or a {@link LogLevel} string.
+ * @returns A sink that only logs records that pass the filter.
+ */
+function withFilter(sink, filter) {
+    const filterFunc = (0, filter_js_1.toFilter)(filter);
+    return (record) => {
+        if (filterFunc(record))
+            sink(record);
+    };
+}
+exports.withFilter = withFilter;
 /**
  * A factory that returns a sink that writes to a {@link WritableStream}.
  *

package/types/mod.d.ts

@@ -5,5 +5,5 @@ export { type ConsoleFormatter, defaultConsoleFormatter, defaultTextFormatter, t
 export { isLogLevel, type LogLevel, parseLogLevel } from "./level.js";
 export { getLogger, type Logger } from "./logger.js";
 export type { LogRecord } from "./record.js";
-export { type ConsoleSinkOptions, type FileSinkOptions, getConsoleSink, getStreamSink, type RotatingFileSinkOptions, type Sink, type StreamSinkOptions, } from "./sink.js";
+export { type ConsoleSinkOptions, type FileSinkOptions, getConsoleSink, getStreamSink, type RotatingFileSinkOptions, type Sink, type StreamSinkOptions, withFilter, } 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,OAAO,EACP,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACtE,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,UAAU,EAAE,KAAK,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,cAAc,EACd,aAAa,EACb,KAAK,uBAAuB,EAC5B,KAAK,IAAI,EACT,KAAK,iBAAiB,GACvB,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,OAAO,EACP,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACtE,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,UAAU,EAAE,KAAK,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,cAAc,EACd,aAAa,EACb,KAAK,uBAAuB,EAC5B,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,UAAU,GACX,MAAM,WAAW,CAAC"}

package/types/sink.d.ts

@@ -2,6 +2,7 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import * as dntShim from "./_dnt.shims.js";
+import { type FilterLike } from "./filter.js";
 import { type ConsoleFormatter, type TextFormatter } from "./formatter.js";
 import type { LogRecord } from "./record.js";
 /**
@@ -14,6 +15,21 @@ import type { LogRecord } from "./record.js";
  * @param record The log record to sink.
  */
 export type Sink = (record: LogRecord) => void;
+/**
+ * Turns a sink into a filtered sink.  The returned sink only logs records that
+ * pass the filter.
+ *
+ * @example Filter a console sink to only log records with the info level
+ * ```typescript
+ * const sink = withFilter(getConsoleSink(), "info");
+ * ```
+ *
+ * @param sink A sink to be filtered.
+ * @param filter A filter to apply to the sink.  It can be either a filter
+ *               function or a {@link LogLevel} string.
+ * @returns A sink that only logs records that pass the filter.
+ */
+export declare function withFilter(sink: Sink, filter: FilterLike): Sink;
 /**
  * Options for the {@link getStreamSink} function.
  */

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;;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,eAAe,CAgBxB;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;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK,CAAE,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC1E;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAEzC;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,uBAAuB,GAAG,sBAAsB,CAAC,KAAK,CAAC,GAC/D,IAAI,GAAG,UAAU,CAkCnB"}
+{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../src/sink.ts"],"names":[],"mappings":";;;AAAA,OAAO,KAAK,OAAO,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,KAAK,UAAU,EAAY,MAAM,aAAa,CAAC;AACxD,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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAK/D;AAED;;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,eAAe,CAgBxB;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;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK,CAAE,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC1E;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAEzC;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,uBAAuB,GAAG,sBAAsB,CAAC,KAAK,CAAC,GAC/D,IAAI,GAAG,UAAU,CAkCnB"}