windmill-cli 1.476.0 → 1.477.1

package/esm/deps/jsr.io/@std/log/{0.224.7 → 0.224.14}/file_handler.js

@@ -4,70 +4,110 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _FileHandler_instances, _FileHandler_unloadCallback, _FileHandler_resetBuffer, _a, _b, _c, _d, _e, _f, _g;
-// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// Copyright 2018-2025 the Deno authors. MIT license.
 import * as dntShim from "../../../../../_dnt.shims.js";
 import { LogLevels } from "./levels.js";
 import { BaseHandler } from "./base_handler.js";
-import { writeAllSync } from "../../io/0.224.8/write_all.js";
+import { writeAllSync } from "../../io/0.225.2/write_all.js";
 import { bufSymbol, encoderSymbol, filenameSymbol, fileSymbol, modeSymbol, openOptionsSymbol, pointerSymbol, } from "./_file_handler_symbols.js";
 /**
- * This handler will output to a file using an optional mode (default is `a`,
- * e.g. append). The file will grow indefinitely. It uses a buffer for writing
- * to file. Logs can be manually flushed with `fileHandler.flush()`. Log
- * messages with a log level greater than error are immediately flushed. Logs
- * are also flushed on process completion.
+ * A file-based log handler that writes log messages to a specified file with buffering and optional modes.
+ * The logs are buffered for optimized performance, writing to the file only
+ * when the buffer is full, on manual .flush() call, during logging of a critical message or when process ends.
+ * It is important to note that the file can grow indefinitely.
  *
- * Behavior of the log modes is as follows:
+ * This handler requires `--allow-write` permission on the log file.
  *
- * - `'a'` - Default mode. Appends new log messages to the end of an existing log
- *   file, or create a new log file if none exists.
- * - `'w'` - Upon creation of the handler, any existing log file will be removed
- *   and a new one created.
- * - `'x'` - This will create a new log file and throw an error if one already
- *   exists.
+ * @example Usage
+ * ```ts no-assert
+ * import { FileHandler } from "@std/log/file-handler";
  *
- * This handler requires `--allow-write` permission on the log file.
+ * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
+ * handler.setup();
+ * handler.log('Hello, world!'); // Buffers the message, or writes it to the file depending on buffer state
+ * handler.flush(); // Manually flushes the buffer
+ * handler.destroy(); // Closes the file and removes listeners
+ * ```
  */
 export class FileHandler extends BaseHandler {
+    /**
+     * Constructs a new FileHandler instance.
+     *
+     * @param levelName The level name to log messages at.
+     * @param options Options for the handler.
+     */
     constructor(levelName, options) {
         super(levelName, options);
         _FileHandler_instances.add(this);
+        /** Opened file to append logs to.
+         *
+         * @private
+         */
         Object.defineProperty(this, _a, {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Buffer used to write to file.
+         *
+         * @private
+         */
         Object.defineProperty(this, _b, {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Current position for pointer.
+         *
+         * @private
+         */
         Object.defineProperty(this, _c, {
             enumerable: true,
             configurable: true,
             writable: true,
             value: 0
         });
+        /**
+         * Filename associated with the file being logged.
+         *
+         * @private
+         */
         Object.defineProperty(this, _d, {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Current log mode.
+         *
+         * @private
+         */
         Object.defineProperty(this, _e, {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * File open options.
+         *
+         * @private
+         */
         Object.defineProperty(this, _f, {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Text encoder.
+         *
+         * @private
+         */
         Object.defineProperty(this, _g, {
             enumerable: true,
             configurable: true,
@@ -89,11 +129,52 @@ export class FileHandler extends BaseHandler {
         };
         this[bufSymbol] = new Uint8Array(options.bufferSize ?? 4096);
     }
+    /**
+     * Sets up the file handler by opening the specified file and initializing resources.
+     *
+     * @example Usage
+     * ```ts no-assert
+     * import { FileHandler } from "@std/log/file-handler";
+     *
+     * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
+     * handler.setup(); // Opens the file and prepares the handler for logging.
+     * handler.destroy();
+     * ```
+     */
     setup() {
         this[fileSymbol] = dntShim.Deno.openSync(this[filenameSymbol], this[openOptionsSymbol]);
         __classPrivateFieldGet(this, _FileHandler_instances, "m", _FileHandler_resetBuffer).call(this);
         addEventListener("unload", __classPrivateFieldGet(this, _FileHandler_unloadCallback, "f"));
     }
+    /**
+     * Handles a log record and flushes the buffer if the log level is higher than error.
+     *
+     * @param logRecord Log record to handle.
+     *
+     * @example Usage
+     * ```ts
+     * import { FileHandler } from "@std/log/file-handler";
+     * import { assertInstanceOf } from "@std/assert/instance-of";
+     * import { LogLevels } from "./levels.ts";
+     * import { LogRecord } from "./logger.ts";
+     *
+     * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
+     * handler.setup();
+     *
+     * // Flushes the buffer immediately and logs "CRITICAL This log is very critical indeed." into the file.
+     * handler.handle(
+     *   new LogRecord({
+     *     msg: "This log is very critical indeed.",
+     *     args: [],
+     *     level: LogLevels.CRITICAL,
+     *     loggerName: "INFO",
+     *   }),
+     * );
+     * handler.destroy();
+     *
+     * assertInstanceOf(handler, FileHandler);
+     * ```
+     */
     handle(logRecord) {
         super.handle(logRecord);
         // Immediately flush if log level is higher than ERROR
@@ -101,6 +182,25 @@ export class FileHandler extends BaseHandler {
             this.flush();
         }
     }
+    /**
+     * Logs a message by adding it to the buffer, with flushing as needed.
+     *
+     * @param msg The message to log.
+     *
+     * @example Usage
+     * ```ts
+     * import { FileHandler } from "@std/log/file-handler";
+     * import { assertInstanceOf } from "@std/assert/instance-of";
+     *
+     * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
+     * handler.setup();
+     * handler.log('Hello, world!');
+     * handler.flush();
+     * handler.destroy();
+     *
+     * assertInstanceOf(handler, FileHandler);
+     * ```
+     */
     log(msg) {
         const bytes = this[encoderSymbol].encode(msg + "\n");
         if (bytes.byteLength > this[bufSymbol].byteLength - this[pointerSymbol]) {
@@ -114,6 +214,23 @@ export class FileHandler extends BaseHandler {
             this[pointerSymbol] += bytes.byteLength;
         }
     }
+    /**
+     * Immediately writes the contents of the buffer to the previously opened file.
+     *
+     * @example Usage
+     * ```ts
+     * import { FileHandler } from "@std/log/file-handler";
+     * import { assertInstanceOf } from "@std/assert/instance-of";
+     *
+     * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
+     * handler.setup();
+     * handler.log('Hello, world!');
+     * handler.flush(); // Writes buffered log messages to the file immediately.
+     * handler.destroy();
+     *
+     * assertInstanceOf(handler, FileHandler);
+     * ```
+     */
     flush() {
         if (this[pointerSymbol] > 0 && this[fileSymbol]) {
             let written = 0;
@@ -123,6 +240,21 @@ export class FileHandler extends BaseHandler {
             __classPrivateFieldGet(this, _FileHandler_instances, "m", _FileHandler_resetBuffer).call(this);
         }
     }
+    /**
+     * Destroys the handler, performing any cleanup that is required and closes the file handler.
+     *
+     * @example Usage
+     * ```ts
+     * import { FileHandler } from "@std/log/file-handler";
+     * import { assertInstanceOf } from "@std/assert/instance-of";
+     *
+     * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" });
+     * handler.setup();
+     * handler.destroy();
+     *
+     * assertInstanceOf(handler, FileHandler);
+     * ```
+     */
     destroy() {
         this.flush();
         this[fileSymbol]?.close();

package/esm/deps/jsr.io/@std/log/0.224.14/formatters.js

@@ -0,0 +1,45 @@
+/**
+ * JSON log formatter.
+ *
+ * @example Usage
+ * ```ts
+ * import { LogRecord } from "@std/log/logger";
+ * import { jsonFormatter } from "@std/log/formatters";
+ * import { LogLevels } from "@std/log/levels";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const record = new LogRecord({
+ *   msg: "Hello, world!",
+ *   args: ["foo", "bar"],
+ *   level: LogLevels.INFO,
+ *   loggerName: "example",
+ * });
+ * const formatted = jsonFormatter(record);
+ *
+ * assertEquals(
+ *   formatted,
+ *   `{"level":"INFO","datetime":${record.datetime.getTime()},"message":"Hello, world!","args":["foo","bar"]}`,
+ * );
+ * ```
+ *
+ * @param logRecord Log record to format.
+ * @returns JSON string representation of the log record.
+ */
+export function jsonFormatter(logRecord) {
+    return JSON.stringify({
+        level: logRecord.levelName,
+        datetime: logRecord.datetime.getTime(),
+        message: logRecord.msg,
+        args: flattenArgs(logRecord.args),
+    });
+}
+function flattenArgs(args) {
+    if (args.length === 1) {
+        return args[0];
+    }
+    else if (args.length > 1) {
+        return args;
+    }
+}
+/** Formatters for log records. */
+export const formatters = { jsonFormatter };

package/esm/deps/jsr.io/@std/log/0.224.14/get_logger.js

@@ -0,0 +1,75 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+// This module is browser compatible.
+import { Logger } from "./logger.js";
+import { state } from "./_state.js";
+/**
+ * Get a logger instance. If not specified `name`, get the default logger.
+ *
+ * @param name The name of the logger.
+ * @returns The logger instance.
+ *
+ * @example Usage (without defined name and minimal setup)
+ * ```ts
+ * import { getLogger } from "@std/log/get-logger";
+ * import "@std/log/setup";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const logger = getLogger();
+ * const result = logger.info("Hello world!"); // Prints "INFO Hello world!" in blue
+ *
+ * assertEquals(result, "Hello world!");
+ * ```
+ *
+ * @example Usage (without defined name and custom setup)
+ * ```ts
+ * import { getLogger } from "@std/log/get-logger";
+ * import { ConsoleHandler } from "@std/log/console-handler";
+ * import { setup } from "@std/log/setup";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * setup({
+ *   handlers: {
+ *     console: new ConsoleHandler("DEBUG"),
+ *   },
+ *   loggers: {
+ *     default: {
+ *       level: "DEBUG",
+ *       handlers: ["console"],
+ *     },
+ *   },
+ * });
+ *
+ * const logger = getLogger();
+ *
+ * const result = logger.info("Hello world!"); // Prints "INFO Hello world!" in blue
+ *
+ * assertEquals(result, "Hello world!");
+ * ```
+ *
+ * @example Usage (with defined name)
+ * ```ts
+ * import { getLogger } from "@std/log/get-logger";
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * const logger = getLogger("my-logger");
+ * const result = logger.info("Hello world!");
+ *
+ * assertEquals(result, "Hello world!");
+ * ```
+ */
+export function getLogger(name) {
+    if (!name) {
+        const d = state.loggers.get("default");
+        if (d === undefined) {
+            throw new Error(`"default" logger must be set for getting logger without name`);
+        }
+        return d;
+    }
+    const result = state.loggers.get(name);
+    if (!result) {
+        const logger = new Logger(name, "NOTSET", { handlers: [] });
+        state.loggers.set(name, logger);
+        return logger;
+    }
+    return result;
+}

package/esm/deps/jsr.io/@std/log/{0.224.7 → 0.224.14}/info.js

@@ -1,6 +1,7 @@
-// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// Copyright 2018-2025 the Deno authors. MIT license.
 // This module is browser compatible.
 import { getLogger } from "./get_logger.js";
+import "./setup.js";
 export function info(msg, ...args) {
     // Assist TS compiler with pass-through generic type
     if (msg instanceof Function) {

package/esm/deps/jsr.io/@std/log/{0.224.7 → 0.224.14}/levels.js

@@ -1,8 +1,10 @@
-// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// Copyright 2018-2025 the Deno authors. MIT license.
 // This module is browser compatible.
 /**
  * Use this to retrieve the numeric log level by it's associated name.
  * Defaults to INFO.
+ *
+ * @internal
  */
 export const LogLevels = {
     NOTSET: 0,