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

package/README.md

@@ -239,6 +239,68 @@ in the API reference for more details.
 [`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
@@ -259,8 +321,9 @@ configure({
 
 ### 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:
+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;

package/esm/sink.js

@@ -56,3 +56,21 @@ export function getConsoleSink(options = {}) {
             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.13+11d80a56",
+  "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}.
@@ -61,3 +61,22 @@ function getConsoleSink(options = {}) {
     };
 }
 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

@@ -73,4 +73,45 @@ export interface ConsoleSinkOptions {
  * @returns A sink that logs to the console.
  */
 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;;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"}
+{"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"}