@logtape/file 1.3.2 → 1.3.4

package/dist/dist/filesink.base.d.cts

@@ -0,0 +1,74 @@
+import { StreamSinkOptions } from "@logtape/logtape";
+
+//#region dist/filesink.base.d.ts
+
+//#region src/filesink.base.d.ts
+/**
+ * Options for the {@link getBaseFileSink} function.
+ */
+type FileSinkOptions = StreamSinkOptions & {
+  /**
+   * If `true`, the file is not opened until the first write.  Defaults to `false`.
+   */
+  lazy?: boolean;
+  /**
+   * The size of the buffer to use when writing to the file.  If not specified,
+   * a default buffer size will be used.  If it is less or equal to 0,
+   * the file will be written directly without buffering.
+   * @default 8192
+   * @since 0.12.0
+   */
+  bufferSize?: number;
+  /**
+   * The maximum time interval in milliseconds between flushes.  If this time
+   * passes since the last flush, the buffer will be flushed regardless of size.
+   * This helps prevent log loss during unexpected process termination.
+   * @default 5000
+   * @since 0.12.0
+   */
+  flushInterval?: number;
+  /**
+   * Enable non-blocking mode with background flushing.
+   * When enabled, flush operations are performed asynchronously to prevent
+   * blocking the main thread during file I/O operations.
+   *
+   * @default `false`
+   * @since 1.0.0
+   */
+  nonBlocking?: boolean;
+};
+/**
+ * A platform-specific file sink driver.
+ * @template TFile The type of the file descriptor.
+ */
+
+/**
+ * Get a platform-independent file sink.
+ *
+ * @template 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. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
+ */
+
+/**
+ * Options for the {@link getBaseRotatingFileSink} function.
+ */
+interface RotatingFileSinkOptions extends Omit<FileSinkOptions, "lazy"> {
+  /**
+   * The maximum bytes of the file before it is rotated.  1 MiB by default.
+   */
+  maxSize?: number;
+  /**
+   * The maximum number of files to keep.  5 by default.
+   */
+  maxFiles?: number;
+}
+/**
+ * A platform-specific rotating file sink driver.
+ */
+//#endregion
+export { FileSinkOptions, RotatingFileSinkOptions };
+//# sourceMappingURL=filesink.base.d.cts.map

package/dist/dist/filesink.base.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesink.base.d.cts","names":["Sink","StreamSinkOptions","FileSinkOptions","FileSinkDriver","TFile","Uint8Array","AsyncFileSinkDriver","Promise","RotatingFileSinkOptions","Omit","RotatingFileSinkDriver","AsyncRotatingFileSinkDriver"],"sources":["../filesink.base.d.ts"],"sourcesContent":["import { Sink, StreamSinkOptions } from \"@logtape/logtape\";\n\n//#region src/filesink.base.d.ts\n\n/**\n * Options for the {@link getBaseFileSink} function.\n */\ntype FileSinkOptions = StreamSinkOptions & {\n  /**\n   * If `true`, the file is not opened until the first write.  Defaults to `false`.\n   */\n  lazy?: boolean;\n  /**\n   * The size of the buffer to use when writing to the file.  If not specified,\n   * a default buffer size will be used.  If it is less or equal to 0,\n   * the file will be written directly without buffering.\n   * @default 8192\n   * @since 0.12.0\n   */\n  bufferSize?: number;\n  /**\n   * The maximum time interval in milliseconds between flushes.  If this time\n   * passes since the last flush, the buffer will be flushed regardless of size.\n   * This helps prevent log loss during unexpected process termination.\n   * @default 5000\n   * @since 0.12.0\n   */\n  flushInterval?: number;\n  /**\n   * Enable non-blocking mode with background flushing.\n   * When enabled, flush operations are performed asynchronously to prevent\n   * blocking the main thread during file I/O operations.\n   *\n   * @default `false`\n   * @since 1.0.0\n   */\n  nonBlocking?: boolean;\n};\n/**\n * A platform-specific file sink driver.\n * @template TFile The type of the file descriptor.\n */\ninterface FileSinkDriver<TFile> {\n  /**\n   * Open a file for appending and return a file descriptor.\n   * @param path A path to the file to open.\n   */\n  openSync(path: string): TFile;\n  /**\n   * Write a chunk of data to the file.\n   * @param fd The file descriptor.\n   * @param chunk The data to write.\n   */\n  writeSync(fd: TFile, chunk: Uint8Array): void;\n  /**\n   * Write multiple chunks of data to the file in a single operation.\n   * This is optional - if not implemented, falls back to multiple writeSync calls.\n   * @param fd The file descriptor.\n   * @param chunks Array of data chunks to write.\n   */\n  writeManySync?(fd: TFile, chunks: Uint8Array[]): void;\n  /**\n   * Flush the file to ensure that all data is written to the disk.\n   * @param fd The file descriptor.\n   */\n  flushSync(fd: TFile): void;\n  /**\n   * Close the file.\n   * @param fd The file descriptor.\n   */\n  closeSync(fd: TFile): void;\n}\n/**\n * A platform-specific async file sink driver.\n * @template TFile The type of the file descriptor.\n * @since 1.0.0\n */\ninterface AsyncFileSinkDriver<TFile> extends FileSinkDriver<TFile> {\n  /**\n   * Asynchronously write multiple chunks of data to the file in a single operation.\n   * This is optional - if not implemented, falls back to multiple writeSync calls.\n   * @param fd The file descriptor.\n   * @param chunks Array of data chunks to write.\n   */\n  writeMany?(fd: TFile, chunks: Uint8Array[]): Promise<void>;\n  /**\n   * Asynchronously flush the file to ensure that all data is written to the disk.\n   * @param fd The file descriptor.\n   */\n  flush(fd: TFile): Promise<void>;\n  /**\n   * Asynchronously close the file.\n   * @param fd The file descriptor.\n   */\n  close(fd: TFile): Promise<void>;\n}\n/**\n * Get a platform-independent file sink.\n *\n * @template TFile The type of the file descriptor.\n * @param path A path to the file to write to.\n * @param options The options for the sink and the file driver.\n * @returns A sink that writes to the file.  The sink is also a disposable\n *          object that closes the file when disposed. If `nonBlocking` is enabled,\n *          returns a sink that also implements {@link AsyncDisposable}.\n */\n\n/**\n * Options for the {@link getBaseRotatingFileSink} function.\n */\ninterface RotatingFileSinkOptions extends Omit<FileSinkOptions, \"lazy\"> {\n  /**\n   * The maximum bytes of the file before it is rotated.  1 MiB by default.\n   */\n  maxSize?: number;\n  /**\n   * The maximum number of files to keep.  5 by default.\n   */\n  maxFiles?: number;\n}\n/**\n * A platform-specific rotating file sink driver.\n */\ninterface RotatingFileSinkDriver<TFile> extends FileSinkDriver<TFile> {\n  /**\n   * Get the size of the file.\n   * @param path A path to the file.\n   * @returns The `size` of the file in bytes, in an object.\n   */\n  statSync(path: string): {\n    size: number;\n  };\n  /**\n   * Rename a file.\n   * @param oldPath A path to the file to rename.\n   * @param newPath A path to be renamed to.\n   */\n  renameSync(oldPath: string, newPath: string): void;\n}\n/**\n * A platform-specific async rotating file sink driver.\n * @since 1.0.0\n */\ninterface AsyncRotatingFileSinkDriver<TFile> extends AsyncFileSinkDriver<TFile> {\n  /**\n   * Get the size of the file.\n   * @param path A path to the file.\n   * @returns The `size` of the file in bytes, in an object.\n   */\n  statSync(path: string): {\n    size: number;\n  };\n  /**\n   * Rename a file.\n   * @param oldPath A path to the file to rename.\n   * @param newPath A path to be renamed to.\n   */\n  renameSync(oldPath: string, newPath: string): void;\n}\n/**\n * Get a platform-independent rotating file sink.\n *\n * This sink writes log records to a file, and rotates the file when it reaches\n * the `maxSize`.  The rotated files are named with the original file name\n * followed by a dot and a number, starting from 1.  The number is incremented\n * for each rotation, and the maximum number of files to keep is `maxFiles`.\n *\n * @param path A path to the file to write to.\n * @param options The options for the sink and the file driver.\n * @returns A sink that writes to the file.  The sink is also a disposable\n *          object that closes the file when disposed. If `nonBlocking` is enabled,\n *          returns a sink that also implements {@link AsyncDisposable}.\n */\n//#endregion\nexport { AsyncRotatingFileSinkDriver, FileSinkDriver, FileSinkOptions, RotatingFileSinkDriver, RotatingFileSinkOptions };\n//# sourceMappingURL=filesink.base.d.ts.map"],"mappings":";;;;;AA6E2D;;;KAtEtDE,eAAAA,GAAkBD,iBAuGmBQ,GAAAA;EAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAApCD,uBAAAA,SAAgCC,KAAKP"}

package/dist/dist/filesink.node.d.cts

@@ -0,0 +1,45 @@
+import { FileSinkOptions, RotatingFileSinkOptions } from "./filesink.base.cjs";
+import { Sink } from "@logtape/logtape";
+
+//#region dist/filesink.node.d.ts
+
+/**
+ * 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. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
+ */
+declare function getFileSink(path: string, options?: FileSinkOptions): Sink & Disposable;
+declare function getFileSink(path: string, options: FileSinkOptions & {
+  nonBlocking: true;
+}): Sink & AsyncDisposable;
+/**
+ * Get a rotating file sink.
+ *
+ * This sink writes log records to a file, and rotates the file when it reaches
+ * the `maxSize`.  The rotated files are named with the original file name
+ * followed by a dot and a number, starting from 1.  The number is incremented
+ * for each rotation, and the maximum number of files to keep is `maxFiles`.
+ *
+ * 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 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. If `nonBlocking` is enabled,
+ *          returns a sink that also implements {@link AsyncDisposable}.
+ */
+declare function getRotatingFileSink(path: string, options?: RotatingFileSinkOptions): Sink & Disposable;
+declare function getRotatingFileSink(path: string, options: RotatingFileSinkOptions & {
+  nonBlocking: true;
+}): Sink & AsyncDisposable;
+//# sourceMappingURL=filesink.node.d.ts.map
+//#endregion
+//#endregion
+export { getFileSink, getRotatingFileSink };
+//# sourceMappingURL=filesink.node.d.cts.map

package/dist/dist/filesink.node.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesink.node.d.cts","names":["AsyncRotatingFileSinkDriver","FileSinkOptions","RotatingFileSinkDriver","RotatingFileSinkOptions","Sink","nodeDriver","nodeAsyncDriver","getFileSink","Disposable","AsyncDisposable","getRotatingFileSink"],"sources":["../filesink.node.d.ts"],"sourcesContent":["import { AsyncRotatingFileSinkDriver, FileSinkOptions, RotatingFileSinkDriver, RotatingFileSinkOptions } from \"./filesink.base.js\";\nimport { Sink } from \"@logtape/logtape\";\n\n//#region src/filesink.node.d.ts\n\n/**\n * A Node.js-specific file sink driver.\n */\ndeclare const nodeDriver: RotatingFileSinkDriver<number | void>;\n/**\n * A Node.js-specific async file sink driver.\n * @since 1.0.0\n */\ndeclare const nodeAsyncDriver: AsyncRotatingFileSinkDriver<number | void>;\n/**\n * Get a file sink.\n *\n * Note that this function is unavailable in the browser.\n *\n * @param path A path to the file to write to.\n * @param options The options for the sink.\n * @returns A sink that writes to the file.  The sink is also a disposable\n *          object that closes the file when disposed. If `nonBlocking` is enabled,\n *          returns a sink that also implements {@link AsyncDisposable}.\n */\ndeclare function getFileSink(path: string, options?: FileSinkOptions): Sink & Disposable;\ndeclare function getFileSink(path: string, options: FileSinkOptions & {\n  nonBlocking: true;\n}): Sink & AsyncDisposable;\n/**\n * Get a rotating file sink.\n *\n * This sink writes log records to a file, and rotates the file when it reaches\n * the `maxSize`.  The rotated files are named with the original file name\n * followed by a dot and a number, starting from 1.  The number is incremented\n * for each rotation, and the maximum number of files to keep is `maxFiles`.\n *\n * Note that this function is unavailable in the browser.\n *\n * @param path A path to the file to write to.\n * @param options The options for the sink and the file driver.\n * @returns A sink that writes to the file.  The sink is also a disposable\n *          object that closes the file when disposed. If `nonBlocking` is enabled,\n *          returns a sink that also implements {@link AsyncDisposable}.\n */\ndeclare function getRotatingFileSink(path: string, options?: RotatingFileSinkOptions): Sink & Disposable;\ndeclare function getRotatingFileSink(path: string, options: RotatingFileSinkOptions & {\n  nonBlocking: true;\n}): Sink & AsyncDisposable;\n//# sourceMappingURL=filesink.node.d.ts.map\n//#endregion\nexport { getFileSink, getRotatingFileSink, nodeAsyncDriver, nodeDriver };\n//# sourceMappingURL=filesink.node.d.ts.map"],"mappings":";;;;;;AA4B0B;AAAA;;;;;AAiB8E;AAAA;;;iBApBvFO,WAAAA,CAuBbH,IAAAA,EAAAA,MAAAA,EAAAA,OAAAA,CAAAA,EAvBiDH,eAuBjDG,CAAAA,EAvBmEA,IAuBnEA,GAvB0EI,UAuB1EJ;iBAtBaG,WAAAA,CAsBNE,IAAAA,EAAAA,MAAAA,EAAAA,OAAAA,EAtByCR,eAsBzCQ,GAAAA;EAAe,WAAA,EAAA,IAAA;IApBtBL,OAAOK;;;;;;;;;;;;;;;;;iBAiBMC,mBAAAA,yBAA4CP,0BAA0BC,OAAOI;iBAC7EE,mBAAAA,wBAA2CP;;IAExDC,OAAOK"}

package/dist/mod.d.cts

@@ -1,4 +1,4 @@
 import { FileSinkDriver, FileSinkOptions, RotatingFileSinkDriver, RotatingFileSinkOptions } from "./filesink.base.cjs";
 import { StreamFileSinkOptions, getStreamFileSink } from "./streamfilesink.cjs";
-import { getFileSink, getRotatingFileSink } from "#filesink";
+import { getFileSink, getRotatingFileSink } from "./dist/filesink.node.cjs";
 export { FileSinkDriver, FileSinkOptions, RotatingFileSinkDriver, RotatingFileSinkOptions, StreamFileSinkOptions, getFileSink, getRotatingFileSink, getStreamFileSink };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/file",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "File sink and rotating file sink for LogTape",
   "keywords": [
     "logging",
@@ -60,7 +60,7 @@
     "dist/"
   ],
   "peerDependencies": {
-    "@logtape/logtape": "^1.3.2"
+    "@logtape/logtape": "^1.3.4"
   },
   "devDependencies": {
     "@alinea/suite": "^0.6.3",