@warlock.js/logger 4.0.171 → 4.1.1

package/skills/write-custom-log-channel/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: write-custom-log-channel
+description: 'Extend the abstract LogChannel class for custom sinks — Slack, database, HTTP endpoint, in-memory buffer. Triggers: `LogChannel`, `LogContract`, `LoggingData`, `shouldBeLogged`, `init`, `flushSync`, `terminal`; "log to slack", "log to a database", "send logs to datadog / loki HTTP api", "in-memory test capture channel", "build a custom log sink"; typical import `import { LogChannel, type LoggingData, type LogContract } from "@warlock.js/logger"`. Skip: built-in channels — `@warlock.js/logger/pick-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing libs `winston-transport`, `pino-transport`.'
+---
+
+# Custom channels — extending `LogChannel`
+
+Build a sink for any destination — Slack, a database, an HTTP endpoint — by extending the abstract `LogChannel` class.
+
+## The 5-line minimum
+
+```ts
+import { LogChannel, type LoggingData } from "@warlock.js/logger";
+
+export class NullChannel extends LogChannel {
+  public name = "null";
+  public log(_data: LoggingData) {}
+}
+```
+
+Then:
+```ts
+log.addChannel(new NullChannel());
+```
+
+That's a working channel. `LogChannel` provides the scaffolding; you only need to supply `name` and `log()`.
+
+## What `LogChannel` gives you
+
+| Thing | Who provides it |
+|---|---|
+| `name`, `description`, `terminal` | You (fields on your subclass) |
+| `log(data)` | **You must implement** — abstract |
+| `flushSync()` | You (optional — only if you buffer) |
+| `init()` | You (optional async hook — see below) |
+| `shouldBeLogged(data)` | `LogChannel` — combines `levels` + `filter` |
+| `config<K>(key)` | `LogChannel` — merges user config with `defaultConfigurations` |
+| `getDateAndTimeFormat()` | `LogChannel` — returns resolved `dateFormat` |
+
+## Complete example — SlackLog
+
+```ts title="src/channels/slack-log.ts"
+import { LogChannel, type BasicLogConfigurations, type LoggingData } from "@warlock.js/logger";
+
+// `LogChannel<Options>` constrains `Options extends BasicLogConfigurations`,
+// so extend the base to keep the inherited levels / filter / redact options.
+type SlackConfig = BasicLogConfigurations & {
+  webhookUrl: string;
+};
+
+export class SlackLog extends LogChannel<SlackConfig> {
+  public name = "slack";
+  public description = "Posts errors + warnings to a Slack webhook";
+
+  public async log(data: LoggingData) {
+    if (!this.shouldBeLogged(data)) return;   // ← inherit levels + filter
+
+    await fetch(this.config("webhookUrl"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `[${data.type.toUpperCase()}] [${data.module}][${data.action}]: ${data.message}`,
+      }),
+    });
+  }
+}
+```
+
+Register it alongside built-ins:
+
+```ts
+log.setChannels([
+  new ConsoleLog(),
+  new FileLog({ chunk: "daily" }),
+  new SlackLog({
+    webhookUrl: process.env.SLACK_WEBHOOK_URL!,
+    levels: ["error", "warn"],
+  }),
+]);
+```
+
+## The `init()` hook
+
+Override `protected async init()` for one-time setup — open a socket, connect to a DB, prepare a write stream. Runs automatically after construction (inside a `setTimeout(0)`); `isInitialized` flips to `true` once resolved.
+
+```ts
+export class DatabaseLog extends LogChannel<
+  BasicLogConfigurations & { connectionString: string }
+> {
+  public name = "database";
+  private client!: SomeDbClient;
+
+  protected async init() {
+    this.client = await SomeDbClient.connect(this.config("connectionString"));
+  }
+
+  public async log(data: LoggingData) {
+    if (!this.shouldBeLogged(data)) return;
+    await this.client.insert("logs", data);
+  }
+}
+```
+
+## Implementing `flushSync()`
+
+Only if your channel buffers. Signature: `flushSync?(): void`. Synchronous — no `await`, no promises.
+
+```ts
+export class BatchHttpLog extends LogChannel<BasicLogConfigurations & { url: string }> {
+  public name = "batch-http";
+  private buffer: LoggingData[] = [];
+
+  public log(data: LoggingData) {
+    if (!this.shouldBeLogged(data)) return;
+    this.buffer.push(data);
+    if (this.buffer.length >= 100) void this.drain();
+  }
+
+  public flushSync() {
+    // Synchronous HTTP — use `node:http` or `XMLHttpRequest` polyfill.
+    // If sync HTTP isn't possible, at least dump the buffer to disk here
+    // so a follow-up async drain can recover it next boot.
+  }
+
+  private async drain() { /* async post to this.config("url") */ }
+}
+```
+
+## The `terminal` property
+
+- `terminal = true` (ConsoleLog default) → the logger passes the **original** message, ANSI codes intact.
+- `terminal = false` (base default, all file channels) → the logger passes a shallow-cloned copy whose `message` has ANSI codes stripped.
+
+Set `terminal = true` on a channel only if its output is a TTY that should render colors.
+
+## `LogContract` — the minimal interface
+
+If you don't want anything `LogChannel` provides (level filtering, config merging), implement `LogContract` directly:
+
+```ts
+import type { LogContract, LoggingData } from "@warlock.js/logger";
+
+class MinimalSlack implements LogContract {
+  public name = "slack";
+
+  public async log(data: LoggingData) {
+    if (data.type !== "error") return;
+    await fetch(process.env.SLACK_WEBHOOK!, { /* ... */ });
+  }
+}
+```
+
+Prefer extending `LogChannel` unless you have a concrete reason not to — the level/filter plumbing is worth keeping.
+
+## Don't do
+
+- Don't mutate `data` inside `log()`. Later channels see the mutation if the logger passes the same reference.
+- Don't throw synchronously from `log()`. The logger fires it without awaiting; an unhandled rejection takes down the process (unless `captureAnyUnhandledRejection` is wired up — and then it's embarrassing to be the cause).
+- Don't block the event loop. `log()` may be sync or async; if your work takes >100ms, make it async and return the promise.
+- Don't forget `shouldBeLogged(data)` at the top of `log()` — or your channel silently ignores `levels` / `filter` config.

package/cjs/channels/console-log.d.ts

@@ -1,17 +0,0 @@
-import { LogChannel } from "../log-channel";
-import type { BasicLogConfigurations, LoggingData } from "../types";
-export declare class ConsoleLog extends LogChannel<BasicLogConfigurations> {
-    /**
-     * {@inheritdoc}
-     */
-    name: string;
-    /**
-     * Determine if channel is logging in terminal
-     */
-    terminal: boolean;
-    /**
-     * {@inheritdoc}
-     */
-    log(data: LoggingData): void;
-}
-//# sourceMappingURL=console-log.d.ts.map

package/cjs/channels/console-log.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"console-log.d.ts","sourceRoot":"","sources":["../../src/channels/console-log.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEpE,qBAAa,UAAW,SAAQ,UAAU,CAAC,sBAAsB,CAAC;IAChE;;OAEG;IACI,IAAI,SAAa;IAExB;;OAEG;IACI,QAAQ,UAAQ;IAEvB;;OAEG;IACI,GAAG,CAAC,IAAI,EAAE,WAAW;CA0E7B"}

package/cjs/channels/console-log.js

@@ -1,47 +0,0 @@
-'use strict';var copper=require('@mongez/copper'),logChannel=require('../log-channel.js');class ConsoleLog extends logChannel.LogChannel {
-    /**
-     * {@inheritdoc}
-     */
-    name = "console";
-    /**
-     * Determine if channel is logging in terminal
-     */
-    terminal = true;
-    /**
-     * {@inheritdoc}
-     */
-    log(data) {
-        const { module, action, message, type: level } = data;
-        if (!this.shouldBeLogged(data))
-            return;
-        // display date and time with milliseconds
-        const date = new Date().toISOString(); // i.e 2021-01-01T00:00:00.000Z
-        switch (level) {
-            case "debug":
-                // add a debug icon
-                console.log(copper.colors.magentaBright("⚙"), copper.colors.yellow(`(${date})`), copper.colors.cyan(`[${module}]`), copper.colors.magenta(`[${action}]`), copper.colors.magentaBright(message));
-                break;
-            case "info":
-                // add an info icon
-                console.log(copper.colors.blueBright("ℹ"), copper.colors.yellow(`(${date})`), copper.colors.cyan(`[${module}]`), copper.colors.magenta(`[${action}]`), copper.colors.blueBright(message));
-                break;
-            case "warn":
-                // add a warning icon
-                console.log(copper.colors.yellow("⚠"), copper.colors.yellow(`(${date})`), copper.colors.cyan(`[${module}]`), copper.colors.magenta(`[${action}]`), copper.colors.yellowBright(message));
-                break;
-            case "error":
-                // add an error icon
-                console.log(copper.colors.red("✗"), copper.colors.yellow(`(${date})`), copper.colors.cyan(`[${module}]`), copper.colors.magenta(`[${action}]`), copper.colors.redBright(message));
-                break;
-            case "success":
-                // add a success icon
-                console.log(copper.colors.green("✓"), copper.colors.yellow(`(${date})`), copper.colors.cyan(`[${module}]`), copper.colors.magenta(`[${action}]`), copper.colors.greenBright(message));
-                break;
-            default:
-                console.log("[log]", copper.colors.yellow(`(${date})`), copper.colors.cyan(`[${module}]`), copper.colors.magenta(`[${action}]`), message);
-        }
-        if (typeof message === "object") {
-            console.log(message);
-        }
-    }
-}exports.ConsoleLog=ConsoleLog;//# sourceMappingURL=console-log.js.map

package/cjs/channels/console-log.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"console-log.js","sources":["../../src/channels/console-log.ts"],"sourcesContent":[null],"names":["LogChannel","colors"],"mappings":"0FAIM,MAAO,UAAW,SAAQA,qBAAkC,CAAA;AAChE;;AAEG;IACI,IAAI,GAAG,SAAS,CAAC;AAExB;;AAEG;IACI,QAAQ,GAAG,IAAI,CAAC;AAEvB;;AAEG;AACI,IAAA,GAAG,CAAC,IAAiB,EAAA;AAC1B,QAAA,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;AAEtD,QAAA,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;YAAE,OAAO;;QAGvC,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACtC,QAAA,QAAQ,KAAK;AACX,YAAA,KAAK,OAAO;;gBAEV,OAAO,CAAC,GAAG,CACTC,aAAM,CAAC,aAAa,CAAC,GAAG,CAAC,EACzBA,aAAM,CAAC,MAAM,CAAC,CAAI,CAAA,EAAA,IAAI,GAAG,CAAC,EAC1BA,aAAM,CAAC,IAAI,CAAC,CAAI,CAAA,EAAA,MAAM,GAAG,CAAC,EAC1BA,aAAM,CAAC,OAAO,CAAC,CAAI,CAAA,EAAA,MAAM,GAAG,CAAC,EAC7BA,aAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAC9B,CAAC;gBACF,MAAM;AACR,YAAA,KAAK,MAAM;;gBAET,OAAO,CAAC,GAAG,CACTA,aAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EACtBA,aAAM,CAAC,MAAM,CAAC,CAAI,CAAA,EAAA,IAAI,GAAG,CAAC,EAC1BA,aAAM,CAAC,IAAI,CAAC,CAAI,CAAA,EAAA,MAAM,GAAG,CAAC,EAC1BA,aAAM,CAAC,OAAO,CAAC,CAAI,CAAA,EAAA,MAAM,GAAG,CAAC,EAC7BA,aAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAC3B,CAAC;gBACF,MAAM;AACR,YAAA,KAAK,MAAM;;gBAET,OAAO,CAAC,GAAG,CACTA,aAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAClBA,aAAM,CAAC,MAAM,CAAC,CAAI,CAAA,EAAA,IAAI,GAAG,CAAC,EAC1BA,aAAM,CAAC,IAAI,CAAC,CAAI,CAAA,EAAA,MAAM,GAAG,CAAC,EAC1BA,aAAM,CAAC,OAAO,CAAC,CAAI,CAAA,EAAA,MAAM,GAAG,CAAC,EAC7BA,aAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAC7B,CAAC;gBACF,MAAM;AACR,YAAA,KAAK,OAAO;;gBAEV,OAAO,CAAC,GAAG,CACTA,aAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EACfA,aAAM,CAAC,MAAM,CAAC,CAAI,CAAA,EAAA,IAAI,GAAG,CAAC,EAC1BA,aAAM,CAAC,IAAI,CAAC,CAAI,CAAA,EAAA,MAAM,GAAG,CAAC,EAC1BA,aAAM,CAAC,OAAO,CAAC,CAAI,CAAA,EAAA,MAAM,GAAG,CAAC,EAC7BA,aAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAC1B,CAAC;gBACF,MAAM;AAER,YAAA,KAAK,SAAS;;gBAEZ,OAAO,CAAC,GAAG,CACTA,aAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EACjBA,aAAM,CAAC,MAAM,CAAC,CAAI,CAAA,EAAA,IAAI,GAAG,CAAC,EAC1BA,aAAM,CAAC,IAAI,CAAC,CAAI,CAAA,EAAA,MAAM,GAAG,CAAC,EAC1BA,aAAM,CAAC,OAAO,CAAC,CAAI,CAAA,EAAA,MAAM,GAAG,CAAC,EAC7BA,aAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAC5B,CAAC;gBACF,MAAM;AAER,YAAA;AACE,gBAAA,OAAO,CAAC,GAAG,CACT,OAAO,EACPA,aAAM,CAAC,MAAM,CAAC,IAAI,IAAI,CAAA,CAAA,CAAG,CAAC,EAC1BA,aAAM,CAAC,IAAI,CAAC,CAAA,CAAA,EAAI,MAAM,CAAA,CAAA,CAAG,CAAC,EAC1BA,aAAM,CAAC,OAAO,CAAC,CAAA,CAAA,EAAI,MAAM,CAAG,CAAA,CAAA,CAAC,EAC7B,OAAO,CACR,CAAC;AACL,SAAA;AAED,QAAA,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE;AAC/B,YAAA,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACtB,SAAA;KACF;AACF"}

package/cjs/channels/file-log.d.ts

@@ -1,171 +0,0 @@
-import { LogChannel } from "../log-channel";
-import type { BasicLogConfigurations, LogContract, LoggingData, LogLevel, LogMessage } from "../types";
-export type FileLogConfig = BasicLogConfigurations & {
-    storagePath?: string;
-    /**
-     * File name, without extension
-     */
-    name?: string;
-    /**
-     * chunk mode
-     * If set to `single`, the logs will be created in a single file, unless the rotate is set to true
-     * If set to `daily`, the logs will be created in a daily file, unless the rotate is set to true
-     * If set to `hourly`, the logs will be created in an hourly file, unless the rotate is set to true
-     * @default single
-     */
-    chunk?: "single" | "daily" | "hourly";
-    /**
-     * Whether to rotate the file
-     *
-     * @default true
-     */
-    rotate?: boolean;
-    /**
-     * File Extension
-     *
-     * @default log
-     */
-    extension?: string;
-    /**
-     * If rotate is set, the rotate name will be added to the file name suffixed with `-`
-     *
-     * @default DD-MM-YYYY
-     */
-    rotateFileName?: string;
-    /**
-     * Max file size before rotating the file
-     *
-     * @default 10MB
-     */
-    maxFileSize?: number;
-    /**
-     * Set the max messages that needs to be added before writing to the file
-     *
-     * @default 100
-     */
-    maxMessagesToWrite?: number;
-    /**
-     * Group logs by
-     * Please note that the order matters here
-     * For example, if you set `groupBy: ['level', 'module']`, the logs will be added in level name first, then by module
-     *
-     * @default none
-     */
-    groupBy?: ("level" | "module" | "action")[];
-    /**
-     * Define what levels should be logged
-     *
-     * @default all
-     */
-    levels?: LogLevel[];
-    /**
-     * Date and time format
-     */
-    dateFormat?: {
-        date?: string;
-        time?: string;
-    };
-};
-export declare class FileLog extends LogChannel<FileLogConfig> implements LogContract {
-    /**
-     * {@inheritdoc}
-     */
-    name: string;
-    /**
-     * Messages buffer
-     */
-    protected messages: LogMessage[];
-    /**
-     * Grouped messages
-     */
-    protected groupedMessages: Record<string, LogMessage[]>;
-    /**
-     * Default channel configurations
-     */
-    protected defaultConfigurations: FileLogConfig;
-    /**
-     * Last write time
-     */
-    protected lastWriteTime: number;
-    /**
-     * A flag to determine if the file is being written
-     */
-    protected isWriting: boolean;
-    /**
-     * Check file size for file rotation
-     */
-    protected checkAndRotateFile(filePath?: string): Promise<void>;
-    /**
-     * Rotate log file
-     */
-    protected rotateLogFile(): Promise<void>;
-    /**
-     * Flush messages
-     */
-    protected initMessageFlush(): void;
-    /**
-     * Get file path
-     */
-    get filePath(): string;
-    /**
-     * Get max messages
-     */
-    protected get maxMessagesToWrite(): number;
-    /**
-     * Get file name
-     */
-    get fileName(): string;
-    /**
-     * Get file extension
-     */
-    get extension(): string;
-    /**
-     * Get content
-     */
-    protected get content(): string;
-    /**
-     * Get storage path
-     */
-    get storagePath(): string;
-    /**
-     * {@inheritdoc}
-     */
-    protected init(): Promise<void>;
-    /**
-     * Synchronously flush messages
-     */
-    flushSync(): void;
-    /**
-     * {@inheritdoc}
-     */
-    log(data: LoggingData): Promise<void>;
-    /**
-     * Check if messages should be written
-     */
-    protected checkIfMessagesShouldBeWritten(): Promise<void>;
-    /**
-     * Should be called after messages are saved
-     */
-    protected onSave(): void;
-    /**
-     * Check if messages should be grouped
-     */
-    protected get messagedShouldBeGrouped(): boolean;
-    /**
-     * Write messages to the file
-     */
-    protected writeMessagesToFile(): Promise<void>;
-    /**
-     * Write grouped messages to the file
-     */
-    protected writeGroupedMessagesToFile(): Promise<void>;
-    /**
-     * Prepare grouped messages
-     */
-    protected prepareGroupedMessages(): void;
-    /**
-     * Start writing to the file
-     */
-    protected write(filePath: string, content: string): Promise<unknown>;
-}
-//# sourceMappingURL=file-log.d.ts.map

package/cjs/channels/file-log.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"file-log.d.ts","sourceRoot":"","sources":["../../src/channels/file-log.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EACV,sBAAsB,EACtB,WAAW,EACX,WAAW,EACX,QAAQ,EACR,UAAU,EACX,MAAM,UAAU,CAAC;AAIlB,MAAM,MAAM,aAAa,GAAG,sBAAsB,GAAG;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IACtC;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAC;IAC5C;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB;;OAEG;IACH,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH,CAAC;AAEF,qBAAa,OAAQ,SAAQ,UAAU,CAAC,aAAa,CAAE,YAAW,WAAW;IAC3E;;OAEG;IACI,IAAI,SAAU;IAErB;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,CAAM;IAEtC;;OAEG;IACH,SAAS,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAM;IAE7D;;OAEG;IACH,SAAS,CAAC,qBAAqB,EAAE,aAAa,CAgB5C;IAEF;;OAEG;IACH,SAAS,CAAC,aAAa,SAAc;IAErC;;OAEG;IACH,SAAS,CAAC,SAAS,UAAS;IAE5B;;OAEG;cACa,kBAAkB,CAAC,QAAQ,SAAgB;IAkB3D;;OAEG;cACa,aAAa;IAY7B;;OAEG;IACH,SAAS,CAAC,gBAAgB;IAW1B;;OAEG;IACH,IAAW,QAAQ,WAMlB;IAED;;OAEG;IACH,SAAS,KAAK,kBAAkB,IAAI,MAAM,CAEzC;IAED;;OAEG;IACH,IAAW,QAAQ,IAAI,MAAM,CAY5B;IAED;;OAEG;IACH,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED;;OAEG;IACH,SAAS,KAAK,OAAO,WAEpB;IAED;;OAEG;IACH,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED;;OAEG;cACa,IAAI;IAQpB;;OAEG;IACI,SAAS,IAAI,IAAI;IAoBxB;;OAEG;IACU,GAAG,CAAC,IAAI,EAAE,WAAW;IAsClC;;OAEG;cACa,8BAA8B;IAM9C;;OAEG;IACH,SAAS,CAAC,MAAM;IAOhB;;OAEG;IACH,SAAS,KAAK,uBAAuB,IAAI,OAAO,CAE/C;IAED;;OAEG;cACa,mBAAmB;IAqBnC;;OAEG;cACa,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B3D;;OAEG;IACH,SAAS,CAAC,sBAAsB,IAAI,IAAI;IAWxC;;OAEG;cACa,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAcxD"}