feat(formatter): Add YScope formatter for structured logs and remove Logback-style formatter.

src/components/modals/SettingsModal/SettingsDialog.tsx

@@ -33,8 +33,11 @@ import ThemeSwitchToggle from "./ThemeSwitchToggle";
 
 const CONFIG_FORM_FIELDS = [
     {
-        helperText: "[JSON] Log messages conversion pattern. The current syntax is similar to" +
-            " Logback conversion patterns but will change in a future release.",
+        helperText: `[JSON] Log messages conversion pattern. Add field-placeholders to insert
+        fields from JSON log events. A field-placeholder uses the following syntax:
+        \`{<field-name>[:<formatter-name>[:<formatter-options>]]}\`. \`field-name\` is required,
+        while \`formatter-name\` and \`formatter-options\` are optional. See the default pattern
+        for an example.`,
         initialValue: getConfig(CONFIG_KEY.DECODER_OPTIONS).formatString,
         label: "Decoder: Format string",
         name: LOCAL_STORAGE_KEY.DECODER_OPTIONS_FORMAT_STRING,

src/services/decoders/ClpIrDecoder.ts

@@ -12,7 +12,7 @@ import {
 import {Formatter} from "../../typings/formatters";
 import {JsonObject} from "../../typings/js";
 import {LogLevelFilter} from "../../typings/logs";
-import LogbackFormatter from "../formatters/LogbackFormatter";
+import YScopeFormatter from "../formatters/YScopeFormatter";
 import {
     convertToDayjsTimestamp,
     isJsonObject,
@@ -39,7 +39,7 @@ class ClpIrDecoder implements Decoder {
         this.#streamType = streamType;
         this.#streamReader = streamReader;
         this.#formatter = (streamType === CLP_IR_STREAM_TYPE.STRUCTURED) ?
-            new LogbackFormatter({formatString: decoderOptions.formatString}) :
+            new YScopeFormatter({formatString: decoderOptions.formatString}) :
             null;
     }
 
@@ -87,7 +87,7 @@ class ClpIrDecoder implements Decoder {
     }
 
     setFormatterOptions (options: DecoderOptions): boolean {
-        this.#formatter = new LogbackFormatter({formatString: options.formatString});
+        this.#formatter = new YScopeFormatter({formatString: options.formatString});
 
         return true;
     }

src/services/decoders/JsonlDecoder/index.ts

@@ -16,7 +16,7 @@ import {
     LogEvent,
     LogLevelFilter,
 } from "../../../typings/logs";
-import LogbackFormatter from "../../formatters/LogbackFormatter";
+import YscopeFormatter from "../../formatters/YScopeFormatter";
 import {
     convertToDayjsTimestamp,
     convertToLogLevelValue,
@@ -53,7 +53,7 @@ class JsonlDecoder implements Decoder {
         this.#dataArray = dataArray;
         this.#logLevelKey = decoderOptions.logLevelKey;
         this.#timestampKey = decoderOptions.timestampKey;
-        this.#formatter = new LogbackFormatter({formatString: decoderOptions.formatString});
+        this.#formatter = new YscopeFormatter({formatString: decoderOptions.formatString});
     }
 
     getEstimatedNumEvents (): number {
@@ -82,7 +82,7 @@ class JsonlDecoder implements Decoder {
     }
 
     setFormatterOptions (options: DecoderOptions): boolean {
-        this.#formatter = new LogbackFormatter({formatString: options.formatString});
+        this.#formatter = new YscopeFormatter({formatString: options.formatString});
 
         return true;
     }

src/services/formatters/LogbackFormatter.ts

@@ -7,26 +7,9 @@ import {
 } from "../../typings/formatters";
 import {JsonObject} from "../../typings/js";
 import {LogEvent} from "../../typings/logs";
+import {convertDateTimeFormatterPatternToDayJs} from "../../utils/formatters";
 
 
-/**
- * Converts a *simple* java.time.format.DateTimeFormatter pattern to a Day.js date format string.
- *
- * NOTE: This method doesn't handle all possible patterns. Check the implementation to determine
- * what's supported.
- *
- * @param pattern
- * @return The corresponding Day.js date format string.
- */
-const convertDateTimeFormatterPatternToDayJs = (pattern: string): string => {
-    pattern = pattern.replace("yyyy", "YYYY");
-    pattern = pattern.replace("yy", "YY");
-    pattern = pattern.replace("dd", "D");
-    pattern = pattern.replace("d", "D");
-
-    return pattern;
-};
-
 /**
  * A formatter that uses a Logback-like format string to format log events into a string. See
  * `LogbackFormatterOptionsType` for details about the format string.
@@ -51,12 +34,6 @@ class LogbackFormatter implements Formatter {
         this.#parseKeys();
     }
 
-    /**
-     * Formats the given log event.
-     *
-     * @param logEvent
-     * @return The formatted log event.
-     */
     formatLogEvent (logEvent: LogEvent): string {
         const {fields, timestamp} = logEvent;
         const formatStringWithTimestamp: string =

src/services/formatters/YScopeFormatter/FieldFormatters/RoundFormatter.ts

@@ -0,0 +1,29 @@
+import {Nullable} from "../../../../typings/common";
+import {YScopeFieldFormatter} from "../../../../typings/formatters";
+import {JsonValue} from "../../../../typings/js";
+import {jsonValueToString} from "../utils";
+
+
+/**
+ * A field formatter that rounds numerical values to the nearest integer.
+ * If the field value is not a number, it is returned as-is after being
+ * converted to a string. Does not currently support any options.
+ */
+class RoundFormatter implements YScopeFieldFormatter {
+    constructor (options: Nullable<string>) {
+        if (null !== options) {
+            throw Error(`Round formatter does not support option ${options}`);
+        }
+    }
+
+    // eslint-disable-next-line class-methods-use-this
+    formatField (field: JsonValue): string {
+        if ("number" === typeof field) {
+            field = Math.round(field);
+        }
+
+        return jsonValueToString(field);
+    }
+}
+
+export default RoundFormatter;

src/services/formatters/YScopeFormatter/FieldFormatters/TimestampFormatter.ts

@@ -0,0 +1,39 @@
+import {Dayjs} from "dayjs";
+
+import {Nullable} from "../../../../typings/common";
+import {YScopeFieldFormatter} from "../../../../typings/formatters";
+import {JsonValue} from "../../../../typings/js";
+import {convertDateTimeFormatterPatternToDayJs} from "../../../../utils/formatters";
+import {convertToDayjsTimestamp} from "../../../decoders/JsonlDecoder/utils";
+
+
+/**
+ * A formatter that formats timestamp values using a specified date-time pattern.
+ * If no pattern is provided as an option, the timestamp is formatted in the
+ * default ISO 8601 format.
+ */
+class TimestampFormatter implements YScopeFieldFormatter {
+    #dateFormat: Nullable<string> = null;
+
+    constructor (options: Nullable<string>) {
+        if (null !== options) {
+            this.#dateFormat = convertDateTimeFormatterPatternToDayJs(options);
+        }
+    }
+
+    formatField (field: JsonValue): string {
+        // eslint-disable-next-line no-warning-comments
+        // TODO: We already parsed the timestamp during deserialization so this is perhaps
+        // inefficient. However, this field formatter can be used for multiple keys, so using
+        // the single parsed timestamp by itself would not work. Perhaps in future we can check
+        // if the key is the same as timestamp key and avoid parsing again.
+        const timestamp: Dayjs = convertToDayjsTimestamp(field);
+        if (null === this.#dateFormat) {
+            return timestamp.format();
+        }
+
+        return timestamp.format(this.#dateFormat);
+    }
+}
+
+export default TimestampFormatter;

src/services/formatters/YScopeFormatter/index.ts

@@ -0,0 +1,127 @@
+import {
+    BACKSLASH_REGEX,
+    FIELD_PLACEHOLDER_REGEX,
+    Formatter,
+    FormatterOptionsType,
+    YScopeFieldFormatter,
+    YScopeFieldPlaceholder,
+} from "../../../typings/formatters";
+import {LogEvent} from "../../../typings/logs";
+import {getNestedJsonValue} from "../../../utils/js";
+import {
+    jsonValueToString,
+    splitFieldPlaceholder,
+    YSCOPE_FORMATTERS_MAP,
+} from "./utils";
+
+
+/**
+ * A formatter that uses a YScope format string to format log events into a string. See
+ * `YScopeFormatterOptionsType` for details about the format string.
+ */
+class YScopeFormatter implements Formatter {
+    #formatString: string;
+
+    #fieldPlaceholders: YScopeFieldPlaceholder[] = [];
+
+    constructor (options: FormatterOptionsType) {
+        this.#formatString = options.formatString;
+        this.#parseFieldPlaceholder();
+    }
+
+    formatLogEvent (logEvent: LogEvent): string {
+        let placeholderIndex = 0;
+
+        // Inline replacer function. Uses `placeholderIndex` indirectly via closure. Returns
+        // a formatted field. Function gets the `YScopeFieldPlaceholder` specified by
+        // `placeholderIndex` from array of placeholders parsed and validated in the class
+        // constructor. Next, retrieves a field from the log event using the placeholder's
+        // `fieldNameKeys`. The field is then formatted using the placeholder's `fieldFormatter`.
+        const replacePlaceholder = () => {
+            const fieldPlaceholder: YScopeFieldPlaceholder | undefined =
+                this.#fieldPlaceholders[placeholderIndex];
+
+            if ("undefined" === typeof fieldPlaceholder) {
+                throw new Error("Unexpected change in placeholder quantity in format string.");
+            }
+
+            // Increment `placeholderIndex` taking advantage of closure property. Subsequent
+            // calls to `replacePlaceholder()` will use the next index from array of placeholders.
+            placeholderIndex++;
+
+            const nestedValue = getNestedJsonValue(logEvent.fields, fieldPlaceholder.fieldNameKeys);
+            if ("undefined" === typeof nestedValue) {
+                return "";
+            }
+
+            return fieldPlaceholder.fieldFormatter ?
+                fieldPlaceholder.fieldFormatter.formatField(nestedValue) :
+                jsonValueToString(nestedValue);
+        };
+
+        const placeholderPattern = new RegExp(FIELD_PLACEHOLDER_REGEX, "g");
+
+        // Calls `replacePlaceholder()` for each pattern match in the format string. Effectively
+        // replaces each field placeholder in the format string with values from the current
+        // log event.
+        let formattedLog =
+            this.#formatString.replace(placeholderPattern, replacePlaceholder);
+
+
+        /* eslint-disable-next-line no-warning-comments */
+        // TODO: This is simply but lossy and will remove backlash from user fields. Working on a
+        // better way to avoid this issue.
+        const backslashPattern = new RegExp(BACKSLASH_REGEX, "g");
+        formattedLog = formattedLog.replace(backslashPattern, "");
+
+        return `${formattedLog}\n`;
+    }
+
+    /**
+     * Parses field name, formatter name, and formatter options from placeholders in the format
+     * string. For each placeholder, it creates a corresponding `YScopeFieldFormatter` and adds
+     * it to the class-level array.
+     *
+     * @throws Error if `FIELD_PLACEHOLDER_REGEX` does not contain a capture group.
+     * @throws Error if a specified formatter is not supported.
+     */
+    #parseFieldPlaceholder () {
+        const pattern = new RegExp(FIELD_PLACEHOLDER_REGEX, "g");
+        const it = this.#formatString.matchAll(pattern);
+        for (const execResult of it) {
+            // The 1-index of exec result is the capture group in `FIELD_PLACEHOLDER_REGEX`.
+            // (i.e. entire field-placeholder excluding braces).
+            const [, placeholderString]: (string | undefined) [] = execResult;
+
+            if ("undefined" === typeof placeholderString) {
+                throw Error("Field placeholder regex is invalid and does not have a capture group");
+            }
+
+            const {fieldNameKeys, formatterName, formatterOptions} =
+                splitFieldPlaceholder(placeholderString);
+
+            if (null === formatterName) {
+                this.#fieldPlaceholders.push({
+                    fieldNameKeys: fieldNameKeys,
+                    fieldFormatter: null,
+                });
+                continue;
+            }
+
+            const FieldFormatterConstructor = YSCOPE_FORMATTERS_MAP[formatterName];
+            if ("undefined" === typeof FieldFormatterConstructor) {
+                throw Error(`Formatter ${formatterName} is not currently supported`);
+            }
+
+            const fieldFormatter: YScopeFieldFormatter =
+                new FieldFormatterConstructor(formatterOptions);
+
+            this.#fieldPlaceholders.push({
+                fieldNameKeys: fieldNameKeys,
+                fieldFormatter: fieldFormatter,
+            });
+        }
+    }
+}
+
+export default YScopeFormatter;