@hydranium/protocol 1.0.0-next.353 → 1.0.0-next.356

package/lib/abstract-logger.d.ts

@@ -40,6 +40,12 @@ export declare abstract class AbstractLogger implements Logger {
      * with. The label is padded to the widest, so timestamps line up across sinks.
      */
     protected formatLinePrefix(label: string): string;
+    /**
+     * One log argument as the text a sink appends to its line; {@link formatLogArg}
+     * by default. `ConsoleLogger` hands its arguments to the console instead.
+     * Never throws, since a log call that throws loses the line.
+     */
+    protected formatArg(arg: unknown): string;
     error(message?: string, ...args: unknown[]): this;
     warn(message?: string, ...args: unknown[]): this;
     info(message?: string, ...args: unknown[]): this;

package/lib/abstract-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abstract-logger.d.ts","sourceRoot":"","sources":["../src/abstract-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,SAAS,CAAC;AAClD,OAAO,EAAwB,KAAK,QAAQ,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAK1F;;;;;;;;;;;;GAYG;AACH,8BAAsB,cAAe,YAAW,MAAM;IACvC,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM;IAAxC,YAAsB,SAAS,CAAC,EAAE,MAAM,YAAA,EAAI;IAE5C;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,IAAI,KAAK,CAEvB;IAED,2FAA2F;IAC3F,SAAS,CAAC,SAAS,IAAI,MAAM,CAE5B;IAED;;;OAGG;IACH,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;IAED,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAGhD;IACD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG/C;IACD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG/C;IACD,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAGhD;IACD,uFAAuF;IACvF,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAGhD;IACD,4EAA4E;IAC5E,GAAG,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG9C;IAED,+EAA+E;IAC/E,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAKpD;IAED,qDAAqD;IACrD,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE3B;IAED,uFAAuF;IACvF,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE3B;IAED,kFAAkF;IAClF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE5B;IAED;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzB;IAED,yFAAyF;IACzF,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,OAAO,EAAO,EAAE,KAAK,SAAsB,GAAG,IAAI,CAKlH;IAED,gGAAgG;IAChG,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAEzG,qFAAqF;IACrF,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACrD"}
+{"version":3,"file":"abstract-logger.d.ts","sourceRoot":"","sources":["../src/abstract-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,SAAS,CAAC;AAElD,OAAO,EAAwB,KAAK,QAAQ,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAK1F;;;;;;;;;;;;GAYG;AACH,8BAAsB,cAAe,YAAW,MAAM;IACvC,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM;IAAxC,YAAsB,SAAS,CAAC,EAAE,MAAM,YAAA,EAAI;IAE5C;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,IAAI,KAAK,CAEvB;IAED,2FAA2F;IAC3F,SAAS,CAAC,SAAS,IAAI,MAAM,CAE5B;IAED;;;OAGG;IACH,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;IAED;;;;OAIG;IACH,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAExC;IAED,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAGhD;IACD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG/C;IACD,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG/C;IACD,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAGhD;IACD,uFAAuF;IACvF,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAGhD;IACD,4EAA4E;IAC5E,GAAG,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG9C;IAED,+EAA+E;IAC/E,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAKpD;IAED,qDAAqD;IACrD,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE3B;IAED,uFAAuF;IACvF,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE3B;IAED,kFAAkF;IAClF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE5B;IAED;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzB;IAED,yFAAyF;IACzF,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,OAAO,EAAO,EAAE,KAAK,SAAsB,GAAG,IAAI,CAKlH;IAED,gGAAgG;IAChG,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAEzG,qFAAqF;IACrF,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACrD"}

package/lib/abstract-logger.js

@@ -10,6 +10,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AbstractLogger = void 0;
 const clock_1 = require("./clock");
+const format_log_arg_1 = require("./format-log-arg");
 const logger_1 = require("./logger");
 /** Default time source for every {@link AbstractLogger}; overridable per subclass via {@link AbstractLogger.clock}. */
 const systemClock = new clock_1.SystemClock();
@@ -53,6 +54,14 @@ class AbstractLogger {
     formatLinePrefix(label) {
         return `[${label.padEnd(5)} - ${this.timestamp()}]${this.component ? ` [${this.component}]` : ''}`;
     }
+    /**
+     * One log argument as the text a sink appends to its line; {@link formatLogArg}
+     * by default. `ConsoleLogger` hands its arguments to the console instead.
+     * Never throws, since a log call that throws loses the line.
+     */
+    formatArg(arg) {
+        return (0, format_log_arg_1.formatLogArg)(arg);
+    }
     error(message, ...args) {
         this.send('error', message, args);
         return this;

package/lib/abstract-logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"abstract-logger.js","sourceRoot":"","sources":["../src/abstract-logger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"abstract-logger.js","sourceRoot":"","sources":["../src/abstract-logger.ts"],"names":[],"mappings":"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"}

package/lib/format-log-arg.d.ts

@@ -0,0 +1,33 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/** Options of {@link formatLogArg}. An object, so that a `map` index cannot be passed as one. */
+export interface FormatLogArgOptions {
+    /** The `space` argument of `JSON.stringify`; compact where omitted. */
+    readonly indent?: number;
+}
+/**
+ * Render a log argument as text for a log line:
+ * - a string as it is;
+ * - an error by its stack and causes;
+ * - another object as JSON, cut to a bounded size;
+ * - anything else by its description, as is an object JSON renders as nothing
+ *   or cannot render.
+ *
+ * The cut is needed because the log call serialises synchronously and every
+ * Langium AST node is cyclic. The JSON stops at `LOG_ARG_DEPTH` levels,
+ * `LOG_ARG_ITEMS` items or keys and `LOG_ARG_STRING_LENGTH` characters per
+ * string or key, and at about `LOG_ARG_LENGTH` in all. A reference back to an
+ * object that contains it reads `[Circular]`, and a BigInt its digits; the
+ * markers are JSON strings. `util.inspect` would cut too, but is Node-only.
+ *
+ * Never throws, since a log call that throws loses the line and interrupts its
+ * caller. A `%s`-style specifier is not substituted.
+ */
+export declare function formatLogArg(value: unknown, options?: FormatLogArgOptions): string;
+//# sourceMappingURL=format-log-arg.d.ts.map

package/lib/format-log-arg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-log-arg.d.ts","sourceRoot":"","sources":["../src/format-log-arg.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAgBlF,iGAAiG;AACjG,MAAM,WAAW,mBAAmB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAiBtF"}

package/lib/format-log-arg.js

@@ -0,0 +1,158 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatLogArg = formatLogArg;
+const primitives_1 = require("./messages/primitives");
+/** How deep an object argument is rendered; a deeper object reads `[Object]` or `[Array]`. */
+const LOG_ARG_DEPTH = 2;
+/** How many items or keys of one array or object are rendered. */
+const LOG_ARG_ITEMS = 100;
+/** How many characters of one string or key inside an object argument are rendered. */
+const LOG_ARG_STRING_LENGTH = 10_000;
+/**
+ * About how many characters one argument renders, since the limits above
+ * multiply. The entry that would pass it reads `...`; later ones are left out.
+ */
+const LOG_ARG_LENGTH = 100_000;
+/**
+ * Render a log argument as text for a log line:
+ * - a string as it is;
+ * - an error by its stack and causes;
+ * - another object as JSON, cut to a bounded size;
+ * - anything else by its description, as is an object JSON renders as nothing
+ *   or cannot render.
+ *
+ * The cut is needed because the log call serialises synchronously and every
+ * Langium AST node is cyclic. The JSON stops at `LOG_ARG_DEPTH` levels,
+ * `LOG_ARG_ITEMS` items or keys and `LOG_ARG_STRING_LENGTH` characters per
+ * string or key, and at about `LOG_ARG_LENGTH` in all. A reference back to an
+ * object that contains it reads `[Circular]`, and a BigInt its digits; the
+ * markers are JSON strings. `util.inspect` would cut too, but is Node-only.
+ *
+ * Never throws, since a log call that throws loses the line and interrupts its
+ * caller. A `%s`-style specifier is not substituted.
+ */
+function formatLogArg(value, options = {}) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'object' && value !== null) {
+        try {
+            // `undefined` where `toJSON` returns nothing.
+            const json = value instanceof Error ? undefined : JSON.stringify(value, boundedReplacer(options.indent), options.indent);
+            if (json !== undefined) {
+                return json;
+            }
+        }
+        catch {
+            // A throwing getter or `toJSON`, or a revoked proxy; described below instead.
+        }
+    }
+    return (0, primitives_1.describeErrorWithStack)(value);
+}
+function boundedReplacer(indent) {
+    // Keyed by the object last entered; JSON is written depth first, so its entry is on the path being written.
+    const visits = new Map();
+    const isOnPath = (value, holder) => holder !== undefined && ((visits.get(holder)?.source ?? holder) === value || isOnPath(value, visits.get(holder)?.parent));
+    // As `JSON.stringify` clamps its `space`.
+    const space = Math.min(10, Math.max(0, Math.floor(indent ?? 0)));
+    let remaining = LOG_ARG_LENGTH;
+    let exhausted = false;
+    return function (key, raw) {
+        if (exhausted) {
+            // In an object the entry is left out; in an array it reads `null`.
+            return undefined;
+        }
+        // A boxed primitive is written as its value, so it is cut as one.
+        const value = raw instanceof String || raw instanceof Number || raw instanceof Boolean || raw instanceof BigInt ? raw.valueOf() : raw;
+        const depth = (visits.get(this)?.depth ?? -1) + 1;
+        const rendered = render(value, depth, this);
+        const isObject = typeof rendered === 'object' && rendered !== null;
+        // What this entry writes: its value, its key unless it is an item, and the punctuation and indent around them.
+        const written = isObject ? undefined : JSON.stringify(rendered);
+        // A value JSON cannot write is left out of an object, key and all, and written as `null` in an array.
+        const leftOut = !isObject && written === undefined && !Array.isArray(this);
+        const valueLength = isObject ? 2 : (written?.length ?? 4);
+        const keyLength = depth === 0 || Array.isArray(this) ? 0 : JSON.stringify(key).length + 1 + (space > 0 ? 1 : 0);
+        const layoutLength = 1 + (space > 0 ? (1 + space * depth) * (isObject ? 2 : 1) : 0);
+        const length = leftOut ? 0 : valueLength + keyLength + layoutLength;
+        if (length > remaining) {
+            exhausted = true;
+            return '...';
+        }
+        remaining -= length;
+        if (isObject) {
+            visits.set(rendered, { parent: this, depth, source: value });
+        }
+        return rendered;
+    };
+    function render(value, depth, holder) {
+        if (typeof value === 'string') {
+            return cutString(value);
+        }
+        if (typeof value === 'bigint') {
+            return String(value);
+        }
+        if (typeof value !== 'object' || value === null) {
+            return value;
+        }
+        if (isOnPath(value, holder)) {
+            return '[Circular]';
+        }
+        if (depth > LOG_ARG_DEPTH) {
+            return Array.isArray(value) || isTypedArray(value) ? '[Array]' : '[Object]';
+        }
+        return cut(value);
+    }
+}
+function cutString(value) {
+    const more = value.length - LOG_ARG_STRING_LENGTH;
+    return more > 0 ? `${value.slice(0, LOG_ARG_STRING_LENGTH)}... ${more} more characters` : value;
+}
+function isTypedArray(value) {
+    return ArrayBuffer.isView(value) && !(value instanceof DataView);
+}
+/**
+ * `value`, or a copy of its first {@link LOG_ARG_ITEMS} items or keys, keys cut
+ * as strings are, with a note of how many more there are. A typed array is
+ * copied to an array, which reads its items without listing its keys.
+ */
+function cut(value) {
+    if (Array.isArray(value) || isTypedArray(value)) {
+        const more = value.length - LOG_ARG_ITEMS;
+        const items = Array.from({ length: Math.min(value.length, LOG_ARG_ITEMS) }, (_, i) => value[i]);
+        return more > 0 ? [...items, `... ${more} more items`] : Array.isArray(value) ? value : items;
+    }
+    // Linear in the keys: no API lists the first few alone, and `JSON.stringify` would list them all too.
+    const keys = Object.keys(value);
+    const more = keys.length - LOG_ARG_ITEMS;
+    const kept = keys.slice(0, LOG_ARG_ITEMS);
+    if (more <= 0 && kept.every(key => key.length <= LOG_ARG_STRING_LENGTH)) {
+        return value;
+    }
+    // No prototype, so a `__proto__` key is an entry like any other.
+    const copy = Object.create(null);
+    // A cut key or the note can equal a key already written; numbered, so neither entry is lost.
+    const add = (key, entry) => {
+        let unique = key;
+        for (let i = 2; unique in copy; i++) {
+            unique = `${key} (${i})`;
+        }
+        copy[unique] = entry;
+    };
+    for (const key of kept) {
+        add(cutString(key), value[key]);
+    }
+    if (more > 0) {
+        add(`... ${more} more keys`, '...');
+    }
+    return copy;
+}
+//# sourceMappingURL=format-log-arg.js.map

package/lib/format-log-arg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-log-arg.js","sourceRoot":"","sources":["../src/format-log-arg.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -18,6 +18,7 @@ export * from './glsp-edits-settled-actions';
 export * from './glsp-request-model-args';
 export * from './glsp-save-model-actions';
 export * from './errors';
+export * from './format-log-arg';
 export * from './host-diagnostics';
 export * from './logger';
 export * from './latency-collector';

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AASlF,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AAIpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,OAAO,CAAC;AACtB,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AASlF,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AAIpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,OAAO,CAAC;AACtB,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC"}

package/lib/index.js

@@ -40,6 +40,7 @@ __exportStar(require("./glsp-edits-settled-actions"), exports);
 __exportStar(require("./glsp-request-model-args"), exports);
 __exportStar(require("./glsp-save-model-actions"), exports);
 __exportStar(require("./errors"), exports);
+__exportStar(require("./format-log-arg"), exports);
 __exportStar(require("./host-diagnostics"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./latency-collector"), exports);

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,kFAAkF;AAClF,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,4EAA4E;AAC5E,iDAAiD;AAEjD,oDAAkC;AAClC,mDAAiC;AACjC,2CAAyB;AACzB,+CAA6B;AAC7B,0CAAwB;AACxB,yCAAuB;AACvB,oDAAkC;AAClC,8CAA4B;AAC5B,+DAA6C;AAC7C,4DAA0C;AAC1C,4DAA0C;AAC1C,2CAAyB;AACzB,qDAAmC;AACnC,2CAAyB;AACzB,sDAAoC;AACpC,6EAA6E;AAC7E,+EAA+E;AAC/E,+BAA+B;AAC/B,wDAAsC;AACtC,gDAA8B;AAC9B,oDAAkC;AAClC,gDAA8B;AAC9B,qDAAmC;AACnC,yDAAuC;AACvC,oDAAkC;AAClC,8CAA4B;AAC5B,2CAAyB;AACzB,wDAAsC;AACtC,qDAAmC;AACnC,0CAAwB;AACxB,kDAAgC;AAChC,sDAAoC;AACpC,iDAA+B;AAC/B,4CAA0B;AAC1B,gDAA8B;AAC9B,uDAAqC;AACrC,wCAAsB;AACtB,wCAAsB;AACtB,yCAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,kFAAkF;AAClF,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,4EAA4E;AAC5E,iDAAiD;AAEjD,oDAAkC;AAClC,mDAAiC;AACjC,2CAAyB;AACzB,+CAA6B;AAC7B,0CAAwB;AACxB,yCAAuB;AACvB,oDAAkC;AAClC,8CAA4B;AAC5B,+DAA6C;AAC7C,4DAA0C;AAC1C,4DAA0C;AAC1C,2CAAyB;AACzB,mDAAiC;AACjC,qDAAmC;AACnC,2CAAyB;AACzB,sDAAoC;AACpC,6EAA6E;AAC7E,+EAA+E;AAC/E,+BAA+B;AAC/B,wDAAsC;AACtC,gDAA8B;AAC9B,oDAAkC;AAClC,gDAA8B;AAC9B,qDAAmC;AACnC,yDAAuC;AACvC,oDAAkC;AAClC,8CAA4B;AAC5B,2CAAyB;AACzB,wDAAsC;AACtC,qDAAmC;AACnC,0CAAwB;AACxB,kDAAgC;AAChC,sDAAoC;AACpC,iDAA+B;AAC/B,4CAA0B;AAC1B,gDAA8B;AAC9B,uDAAqC;AACrC,wCAAsB;AACtB,wCAAsB;AACtB,yCAAuB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/protocol",
-  "version": "1.0.0-next.353",
+  "version": "1.0.0-next.356",
   "description": "Generic, language-agnostic types, constants, and pure utilities for the hydranium framework.",
   "keywords": [
     "hydranium",

package/src/abstract-logger.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { type Clock, SystemClock } from './clock';
+import { formatLogArg } from './format-log-arg';
 import { Format, LEVEL_LABELS, type LogLevel, Logger, type LogThreshold } from './logger';
 
 /** Default time source for every {@link AbstractLogger}; overridable per subclass via {@link AbstractLogger.clock}. */
@@ -54,6 +55,15 @@ export abstract class AbstractLogger implements Logger {
       return `[${label.padEnd(5)} - ${this.timestamp()}]${this.component ? ` [${this.component}]` : ''}`;
    }
 
+   /**
+    * One log argument as the text a sink appends to its line; {@link formatLogArg}
+    * by default. `ConsoleLogger` hands its arguments to the console instead.
+    * Never throws, since a log call that throws loses the line.
+    */
+   protected formatArg(arg: unknown): string {
+      return formatLogArg(arg);
+   }
+
    error(message?: string, ...args: unknown[]): this {
       this.send('error', message, args);
       return this;

package/src/format-log-arg.ts

@@ -0,0 +1,176 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { describeErrorWithStack } from './messages/primitives';
+
+/** How deep an object argument is rendered; a deeper object reads `[Object]` or `[Array]`. */
+const LOG_ARG_DEPTH = 2;
+/** How many items or keys of one array or object are rendered. */
+const LOG_ARG_ITEMS = 100;
+/** How many characters of one string or key inside an object argument are rendered. */
+const LOG_ARG_STRING_LENGTH = 10_000;
+/**
+ * About how many characters one argument renders, since the limits above
+ * multiply. The entry that would pass it reads `...`; later ones are left out.
+ */
+const LOG_ARG_LENGTH = 100_000;
+
+/** Options of {@link formatLogArg}. An object, so that a `map` index cannot be passed as one. */
+export interface FormatLogArgOptions {
+   /** The `space` argument of `JSON.stringify`; compact where omitted. */
+   readonly indent?: number;
+}
+
+/**
+ * Render a log argument as text for a log line:
+ * - a string as it is;
+ * - an error by its stack and causes;
+ * - another object as JSON, cut to a bounded size;
+ * - anything else by its description, as is an object JSON renders as nothing
+ *   or cannot render.
+ *
+ * The cut is needed because the log call serialises synchronously and every
+ * Langium AST node is cyclic. The JSON stops at `LOG_ARG_DEPTH` levels,
+ * `LOG_ARG_ITEMS` items or keys and `LOG_ARG_STRING_LENGTH` characters per
+ * string or key, and at about `LOG_ARG_LENGTH` in all. A reference back to an
+ * object that contains it reads `[Circular]`, and a BigInt its digits; the
+ * markers are JSON strings. `util.inspect` would cut too, but is Node-only.
+ *
+ * Never throws, since a log call that throws loses the line and interrupts its
+ * caller. A `%s`-style specifier is not substituted.
+ */
+export function formatLogArg(value: unknown, options: FormatLogArgOptions = {}): string {
+   if (typeof value === 'string') {
+      return value;
+   }
+   if (typeof value === 'object' && value !== null) {
+      try {
+         // `undefined` where `toJSON` returns nothing.
+         const json: string | undefined =
+            value instanceof Error ? undefined : JSON.stringify(value, boundedReplacer(options.indent), options.indent);
+         if (json !== undefined) {
+            return json;
+         }
+      } catch {
+         // A throwing getter or `toJSON`, or a revoked proxy; described below instead.
+      }
+   }
+   return describeErrorWithStack(value);
+}
+
+interface Visit {
+   readonly parent: object;
+   readonly depth: number;
+   /** The object a cut copy stands in for, which a cycle refers back to. */
+   readonly source: object;
+}
+
+function boundedReplacer(indent: number | undefined): (this: object, key: string, value: unknown) => unknown {
+   // Keyed by the object last entered; JSON is written depth first, so its entry is on the path being written.
+   const visits = new Map<object, Visit>();
+   const isOnPath = (value: object, holder: object | undefined): boolean =>
+      holder !== undefined && ((visits.get(holder)?.source ?? holder) === value || isOnPath(value, visits.get(holder)?.parent));
+   // As `JSON.stringify` clamps its `space`.
+   const space = Math.min(10, Math.max(0, Math.floor(indent ?? 0)));
+   let remaining = LOG_ARG_LENGTH;
+   let exhausted = false;
+   return function (this: object, key: string, raw: unknown): unknown {
+      if (exhausted) {
+         // In an object the entry is left out; in an array it reads `null`.
+         return undefined;
+      }
+      // A boxed primitive is written as its value, so it is cut as one.
+      const value = raw instanceof String || raw instanceof Number || raw instanceof Boolean || raw instanceof BigInt ? raw.valueOf() : raw;
+      const depth = (visits.get(this)?.depth ?? -1) + 1;
+      const rendered = render(value, depth, this);
+      const isObject = typeof rendered === 'object' && rendered !== null;
+      // What this entry writes: its value, its key unless it is an item, and the punctuation and indent around them.
+      const written = isObject ? undefined : JSON.stringify(rendered);
+      // A value JSON cannot write is left out of an object, key and all, and written as `null` in an array.
+      const leftOut = !isObject && written === undefined && !Array.isArray(this);
+      const valueLength = isObject ? 2 : (written?.length ?? 4);
+      const keyLength = depth === 0 || Array.isArray(this) ? 0 : JSON.stringify(key).length + 1 + (space > 0 ? 1 : 0);
+      const layoutLength = 1 + (space > 0 ? (1 + space * depth) * (isObject ? 2 : 1) : 0);
+      const length = leftOut ? 0 : valueLength + keyLength + layoutLength;
+      if (length > remaining) {
+         exhausted = true;
+         return '...';
+      }
+      remaining -= length;
+      if (isObject) {
+         visits.set(rendered, { parent: this, depth, source: value as object });
+      }
+      return rendered;
+   };
+
+   function render(value: unknown, depth: number, holder: object): unknown {
+      if (typeof value === 'string') {
+         return cutString(value);
+      }
+      if (typeof value === 'bigint') {
+         return String(value);
+      }
+      if (typeof value !== 'object' || value === null) {
+         return value;
+      }
+      if (isOnPath(value, holder)) {
+         return '[Circular]';
+      }
+      if (depth > LOG_ARG_DEPTH) {
+         return Array.isArray(value) || isTypedArray(value) ? '[Array]' : '[Object]';
+      }
+      return cut(value);
+   }
+}
+
+function cutString(value: string): string {
+   const more = value.length - LOG_ARG_STRING_LENGTH;
+   return more > 0 ? `${value.slice(0, LOG_ARG_STRING_LENGTH)}... ${more} more characters` : value;
+}
+
+function isTypedArray(value: object): value is ArrayLike<unknown> {
+   return ArrayBuffer.isView(value) && !(value instanceof DataView);
+}
+
+/**
+ * `value`, or a copy of its first {@link LOG_ARG_ITEMS} items or keys, keys cut
+ * as strings are, with a note of how many more there are. A typed array is
+ * copied to an array, which reads its items without listing its keys.
+ */
+function cut(value: object): object {
+   if (Array.isArray(value) || isTypedArray(value)) {
+      const more = value.length - LOG_ARG_ITEMS;
+      const items = Array.from({ length: Math.min(value.length, LOG_ARG_ITEMS) }, (_, i) => value[i]);
+      return more > 0 ? [...items, `... ${more} more items`] : Array.isArray(value) ? value : items;
+   }
+   // Linear in the keys: no API lists the first few alone, and `JSON.stringify` would list them all too.
+   const keys = Object.keys(value);
+   const more = keys.length - LOG_ARG_ITEMS;
+   const kept = keys.slice(0, LOG_ARG_ITEMS);
+   if (more <= 0 && kept.every(key => key.length <= LOG_ARG_STRING_LENGTH)) {
+      return value;
+   }
+   // No prototype, so a `__proto__` key is an entry like any other.
+   const copy: Record<string, unknown> = Object.create(null);
+   // A cut key or the note can equal a key already written; numbered, so neither entry is lost.
+   const add = (key: string, entry: unknown): void => {
+      let unique = key;
+      for (let i = 2; unique in copy; i++) {
+         unique = `${key} (${i})`;
+      }
+      copy[unique] = entry;
+   };
+   for (const key of kept) {
+      add(cutString(key), (value as Record<string, unknown>)[key]);
+   }
+   if (more > 0) {
+      add(`... ${more} more keys`, '...');
+   }
+   return copy;
+}

package/src/index.ts

@@ -26,6 +26,7 @@ export * from './glsp-edits-settled-actions';
 export * from './glsp-request-model-args';
 export * from './glsp-save-model-actions';
 export * from './errors';
+export * from './format-log-arg';
 export * from './host-diagnostics';
 export * from './logger';
 export * from './latency-collector';