@tmlmobilidade/go-utils-telemetry 20260922.1130.21

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './logger/index.js';
+export * from './timer/index.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './logger/index.js';
+export * from './timer/index.js';

package/dist/logger/create-logger.d.ts

@@ -0,0 +1,8 @@
+import { type Logger, type LogRenderer } from './types/logger.js';
+/**
+ * Builds the public logger around one renderer.
+ *
+ * Every level method goes through the same `log` path, so their signatures cannot drift.
+ * Presentation helpers are plain console output and behave the same in every environment.
+ */
+export declare function createLogger(render: LogRenderer): Logger;

package/dist/logger/create-logger.js

@@ -0,0 +1,30 @@
+import { divider } from './presentation/divider.js';
+import { init } from './presentation/init.js';
+import { spacer } from './presentation/spacer.js';
+import { terminate } from './presentation/terminate.js';
+import { title } from './presentation/title.js';
+import { toRecord } from './to-record.js';
+/**
+ * Builds the public logger around one renderer.
+ *
+ * Every level method goes through the same `log` path, so their signatures cannot drift.
+ * Presentation helpers are plain console output and behave the same in every environment.
+ */
+export function createLogger(render) {
+    const log = (level, input) => render(toRecord(level, input));
+    return {
+        critical: input => log('critical', input),
+        debug: input => log('debug', input),
+        divider,
+        error: input => log('error', input),
+        info: input => log('info', input),
+        init,
+        log,
+        progress: input => log('progress', input),
+        spacer,
+        success: input => log('success', input),
+        terminate,
+        title,
+        warning: input => log('warning', input),
+    };
+}

package/dist/logger/index.d.ts

@@ -0,0 +1,10 @@
+import { type Logger as LoggerApi } from './types/logger.js';
+/**
+ * Shared application logger.
+ * Human-readable console output in development, OpenTelemetry JSON lines otherwise.
+ */
+export declare const Logger: LoggerApi;
+export type { LogLevel } from './levels.js';
+export type { OtelLogRecord } from './render/structured.js';
+export type { LogEntry, LogInput, LogRecord } from './types/entry.js';
+export type { Logger as LoggerApi, LogRenderer } from './types/logger.js';

package/dist/logger/index.js

@@ -0,0 +1,12 @@
+/* * */
+import { createLogger } from './create-logger.js';
+import { renderDev } from './render/dev.js';
+import { renderStructured } from './render/structured.js';
+/* * */
+const IS_DEV = process.env.ENVIRONMENT === 'dev';
+/* * */
+/**
+ * Shared application logger.
+ * Human-readable console output in development, OpenTelemetry JSON lines otherwise.
+ */
+export const Logger = createLogger(IS_DEV ? renderDev : renderStructured);

package/dist/logger/levels.d.ts

@@ -0,0 +1,38 @@
+/** Semantic kind of a log line. Each level maps to exactly one OpenTelemetry severity. */
+export type LogLevel = 'critical' | 'debug' | 'error' | 'info' | 'progress' | 'success' | 'warning';
+/**
+ * OpenTelemetry severity for each level.
+ *
+ * `success` and `progress` are INFO: they exist so the development renderer can
+ * draw them differently, not because they carry a different severity.
+ */
+export declare const SEVERITY: {
+    readonly critical: {
+        readonly number: 21;
+        readonly text: "FATAL";
+    };
+    readonly debug: {
+        readonly number: 5;
+        readonly text: "DEBUG";
+    };
+    readonly error: {
+        readonly number: 17;
+        readonly text: "ERROR";
+    };
+    readonly info: {
+        readonly number: 9;
+        readonly text: "INFO";
+    };
+    readonly progress: {
+        readonly number: 9;
+        readonly text: "INFO";
+    };
+    readonly success: {
+        readonly number: 9;
+        readonly text: "INFO";
+    };
+    readonly warning: {
+        readonly number: 13;
+        readonly text: "WARN";
+    };
+};

package/dist/logger/levels.js

@@ -0,0 +1,15 @@
+/**
+ * OpenTelemetry severity for each level.
+ *
+ * `success` and `progress` are INFO: they exist so the development renderer can
+ * draw them differently, not because they carry a different severity.
+ */
+export const SEVERITY = {
+    critical: { number: 21, text: 'FATAL' },
+    debug: { number: 5, text: 'DEBUG' },
+    error: { number: 17, text: 'ERROR' },
+    info: { number: 9, text: 'INFO' },
+    progress: { number: 9, text: 'INFO' },
+    success: { number: 9, text: 'INFO' },
+    warning: { number: 13, text: 'WARN' },
+};

package/dist/logger/presentation/divider.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Logs a divider line to visually separate sections in the console output.
+ *
+ * If a message is provided, it will be placed after an initial hyphen and padded with additional hyphens up to `size`.
+ * For example: divider("Section", 20) will print something like:
+ *
+ *
+ * - Section -----------
+ *
+ * @param message Optional message to display within the divider.
+ * @param size Total length of the divider line. Defaults to 75.
+ */
+export declare function divider(message?: string, size?: number): void;

package/dist/logger/presentation/divider.js

@@ -0,0 +1,24 @@
+/**
+ * Logs a divider line to visually separate sections in the console output.
+ *
+ * If a message is provided, it will be placed after an initial hyphen and padded with additional hyphens up to `size`.
+ * For example: divider("Section", 20) will print something like:
+ *
+ *
+ * - Section -----------
+ *
+ * @param message Optional message to display within the divider.
+ * @param size Total length of the divider line. Defaults to 75.
+ */
+export function divider(message, size = 75) {
+    console.log();
+    if (message) {
+        // Calculate the available space for hyphens after the message and account for hyphens and spaces
+        const hyphenCount = size - 2 - message.length;
+        console.log(`- ${message} ${'-'.repeat(hyphenCount < 1 ? 1 : hyphenCount)}`);
+    }
+    else {
+        console.log('-'.repeat(size));
+    }
+    console.log();
+}

package/dist/logger/presentation/init.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Logs an initialization block with the current ISO timestamp.
+ *
+ * Output format:
+ *   (blank line)
+ *   --------------------... (matches timestamp width)
+ *   2023-01-01T12:34:56.789Z
+ *   --------------------... (matches timestamp width)
+ *   (blank line)
+ */
+export declare function init(): void;

package/dist/logger/presentation/init.js

@@ -0,0 +1,18 @@
+/**
+ * Logs an initialization block with the current ISO timestamp.
+ *
+ * Output format:
+ *   (blank line)
+ *   --------------------... (matches timestamp width)
+ *   2023-01-01T12:34:56.789Z
+ *   --------------------... (matches timestamp width)
+ *   (blank line)
+ */
+export function init() {
+    const timestamp = new Date().toISOString();
+    console.log();
+    console.log('-'.repeat(timestamp.length));
+    console.log(timestamp);
+    console.log('-'.repeat(timestamp.length));
+    console.log();
+}

package/dist/logger/presentation/spacer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Prints the specified number of blank lines to stdout.
+ *
+ * This helper inserts padding in logs for readability, by emitting `lines`
+ * empty lines (default 1) using console.log().
+ *
+ * @param lines - Number of blank lines to print (default: 1)
+ *
+ * Example:
+ *   spacer();      // prints 1 blank line
+ *   spacer(3);     // prints 3 blank lines
+ */
+export declare function spacer(lines?: number): void;

package/dist/logger/presentation/spacer.js

@@ -0,0 +1,17 @@
+/**
+ * Prints the specified number of blank lines to stdout.
+ *
+ * This helper inserts padding in logs for readability, by emitting `lines`
+ * empty lines (default 1) using console.log().
+ *
+ * @param lines - Number of blank lines to print (default: 1)
+ *
+ * Example:
+ *   spacer();      // prints 1 blank line
+ *   spacer(3);     // prints 3 blank lines
+ */
+export function spacer(lines = 1) {
+    for (let i = 0; i < lines; i++) {
+        console.log();
+    }
+}

package/dist/logger/presentation/terminate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Logs a termination/done message surrounded by separator lines for emphasis.
+ *
+ * @param message - The message to highlight as terminated/completed.
+ */
+export declare function terminate(message: string): void;

package/dist/logger/presentation/terminate.js

@@ -0,0 +1,12 @@
+/**
+ * Logs a termination/done message surrounded by separator lines for emphasis.
+ *
+ * @param message - The message to highlight as terminated/completed.
+ */
+export function terminate(message) {
+    console.log();
+    console.log('-'.repeat(message.length));
+    console.log(message);
+    console.log('-'.repeat(message.length));
+    console.log();
+}

package/dist/logger/presentation/title.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Logs a visually prominent title message to stdout, wrapped with spacing.
+ *
+ * @param message - The title or label to display.
+ */
+export declare function title(message: string): void;

package/dist/logger/presentation/title.js

@@ -0,0 +1,10 @@
+/**
+ * Logs a visually prominent title message to stdout, wrapped with spacing.
+ *
+ * @param message - The title or label to display.
+ */
+export function title(message) {
+    console.log();
+    console.log(`▶︎ ${message}`);
+    console.log();
+}

package/dist/logger/render/dev.d.ts

@@ -0,0 +1,8 @@
+import { type LogRenderer } from '../types/logger.js';
+/**
+ * Human-readable console line for local development.
+ *
+ * Prints optional spacing, `glyph message`, and the error stack when an error is attached.
+ * Attributes are not rendered.
+ */
+export declare const renderDev: LogRenderer;

package/dist/logger/render/dev.js

@@ -0,0 +1,30 @@
+import { spacer } from '../presentation/spacer.js';
+/**
+ * Glyph and console method per level. `satisfies` makes a missing level a compile error.
+ * The method is stored by name and resolved on each call so patched consoles are honoured.
+ */
+const STYLE = {
+    critical: { glyph: '‼', method: 'error' },
+    debug: { glyph: '·', method: 'debug' },
+    error: { glyph: '✘', method: 'error' },
+    info: { glyph: '→', method: 'log' },
+    progress: { glyph: '•', method: 'log' },
+    success: { glyph: '✓', method: 'log' },
+    warning: { glyph: '⚠', method: 'warn' },
+};
+/**
+ * Human-readable console line for local development.
+ *
+ * Prints optional spacing, `glyph message`, and the error stack when an error is attached.
+ * Attributes are not rendered.
+ */
+export const renderDev = (record) => {
+    const { glyph, method } = STYLE[record.level];
+    if (record.spacesBefore)
+        spacer(record.spacesBefore);
+    console[method](`${glyph} ${record.message}`);
+    if (record.error?.stack)
+        console[method](record.error.stack);
+    if (record.spacesAfter)
+        spacer(record.spacesAfter);
+};

package/dist/logger/render/structured.d.ts

@@ -0,0 +1,21 @@
+import { type LogRenderer } from '../types/logger.js';
+/** OpenTelemetry-compatible JSON log record emitted in production. */
+export interface OtelLogRecord {
+    /** Structured event attributes, including `exception.*` when an error is attached. */
+    attributes?: Record<string, unknown>;
+    /** Human-readable event message. */
+    body: string;
+    /** OpenTelemetry severity number. */
+    severity_number: number;
+    /** OpenTelemetry severity name. */
+    severity_text: string;
+    /** ISO 8601 event timestamp. */
+    timestamp: string;
+}
+/**
+ * One JSON line per record, for Grafana Alloy/Loki.
+ *
+ * Records at `error` severity and above go to stderr, everything else to stdout.
+ * `spacesBefore`/`spacesAfter` are development hints and are ignored here.
+ */
+export declare const renderStructured: LogRenderer;

package/dist/logger/render/structured.js

@@ -0,0 +1,29 @@
+import { SEVERITY } from '../levels.js';
+/** OpenTelemetry semantic-convention attributes for an attached error. */
+function exceptionAttributes(error) {
+    if (!error)
+        return {};
+    return {
+        'exception.message': error.message,
+        'exception.stacktrace': error.stack,
+        'exception.type': error.constructor.name,
+    };
+}
+/**
+ * One JSON line per record, for Grafana Alloy/Loki.
+ *
+ * Records at `error` severity and above go to stderr, everything else to stdout.
+ * `spacesBefore`/`spacesAfter` are development hints and are ignored here.
+ */
+export const renderStructured = (record) => {
+    const { number, text } = SEVERITY[record.level];
+    const attributes = { ...record.attributes, ...exceptionAttributes(record.error) };
+    const line = {
+        attributes: Object.keys(attributes).length ? attributes : undefined,
+        body: record.message,
+        severity_number: number,
+        severity_text: text,
+        timestamp: new Date().toISOString(),
+    };
+    (number >= SEVERITY.error.number ? console.error : console.log)(JSON.stringify(line));
+};

package/dist/logger/to-record.d.ts

@@ -0,0 +1,9 @@
+import { type LogLevel } from './levels.js';
+import { type LogInput, type LogRecord } from './types/entry.js';
+/**
+ * Normalises any accepted input into a record.
+ *
+ * `Error` is checked before the object form: an Error also satisfies the entry shape
+ * structurally, and treating it as one would drop its stack.
+ */
+export declare function toRecord(level: LogLevel, input: LogInput): LogRecord;

package/dist/logger/to-record.js

@@ -0,0 +1,13 @@
+/**
+ * Normalises any accepted input into a record.
+ *
+ * `Error` is checked before the object form: an Error also satisfies the entry shape
+ * structurally, and treating it as one would drop its stack.
+ */
+export function toRecord(level, input) {
+    if (typeof input === 'string')
+        return { level, message: input };
+    if (input instanceof Error)
+        return { error: input, level, message: input.message };
+    return { ...input, level, message: input.message ?? input.error?.message ?? '' };
+}

package/dist/logger/types/entry.d.ts

@@ -0,0 +1,33 @@
+import { type LogLevel } from '../levels.js';
+interface LogEntryFields {
+    /** Structured fields. Emitted as OpenTelemetry `attributes` in production; not rendered in development. */
+    attributes?: Record<string, unknown>;
+    /** Error to attach. Development prints its stack; production emits `exception.*` attributes. */
+    error?: Error;
+    /** Human-readable text. Defaults to `error.message` when omitted. */
+    message?: string;
+    /** Development only: blank lines printed after the entry. Ignored in production. */
+    spacesAfter?: number;
+    /** Development only: blank lines printed before the entry. Ignored in production. */
+    spacesBefore?: number;
+}
+/** Object form accepted by every level method. Requires a message or an error. */
+export type LogEntry = LogEntryFields & ({
+    error: Error;
+} | {
+    message: string;
+});
+/**
+ * Anything a level method accepts.
+ *
+ * `Error` is listed explicitly on purpose: an Error is structurally a `{ message: string }`,
+ * so without this member (and the `instanceof` check in `toRecord`) a bare Error would be
+ * treated as an entry with no error attached and its stack would be lost.
+ */
+export type LogInput = Error | LogEntry | string;
+/** Fully resolved entry handed to a renderer. */
+export interface LogRecord extends Omit<LogEntryFields, 'message'> {
+    level: LogLevel;
+    message: string;
+}
+export {};

package/dist/logger/types/entry.js

@@ -0,0 +1 @@
+export {};

package/dist/logger/types/logger.d.ts

@@ -0,0 +1,21 @@
+import { type LogLevel } from '../levels.js';
+import { type LogInput, type LogRecord } from './entry.js';
+/** Renders one resolved record. This is the only thing that differs between development and production. */
+export type LogRenderer = (record: LogRecord) => void;
+type LevelMethod = (input: LogInput) => void;
+/**
+ * Public logger API. Identical in every environment; only rendering differs.
+ *
+ * Extending `Record<LogLevel, LevelMethod>` means adding a value to `LogLevel`
+ * without a matching method is a compile error.
+ */
+export interface Logger extends Record<LogLevel, LevelMethod> {
+    divider(message?: string, size?: number): void;
+    init(): void;
+    /** Generic entry point. Every level method is shorthand for `log(level, input)`. */
+    log(level: LogLevel, input: LogInput): void;
+    spacer(lines?: number): void;
+    terminate(message: string): void;
+    title(message: string): void;
+}
+export {};

package/dist/logger/types/logger.js

@@ -0,0 +1 @@
+export {};

package/dist/timer/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Timer class for tracking elapsed time.
+ * Provides methods to get formatted time strings and raw time values.
+ */
+export declare class Timer {
+    private startTime;
+    constructor();
+    /**
+     * Gets the elapsed time as a formatted string.
+     * @param reset - If true, resets the timer after getting the elapsed time
+     * @returns Formatted string (e.g., "1h 2m 3s 456ms" or "0ms")
+     */
+    get(reset?: boolean): string;
+    /**
+     * Gets the elapsed time in milliseconds.
+     * @param reset - If true, resets the timer after getting the elapsed time
+     * @returns Elapsed time in milliseconds
+     */
+    getMs(reset?: boolean): number;
+    /**
+     * Gets the elapsed time in seconds.
+     * @param reset - If true, resets the timer after getting the elapsed time
+     * @returns Elapsed time in seconds (with decimal precision)
+     */
+    getSeconds(reset?: boolean): number;
+    /**
+     * Resets the timer to the current time.
+     */
+    reset(): void;
+    /**
+     * Formats elapsed time in milliseconds to a human-readable string.
+     * @param elapsedTime - Time in milliseconds
+     * @returns Formatted string (e.g., "1h 2m 3s 456ms" or "0ms")
+     */
+    private formatElapsedTime;
+}

package/dist/timer/index.js

@@ -0,0 +1,78 @@
+/**
+ * Timer class for tracking elapsed time.
+ * Provides methods to get formatted time strings and raw time values.
+ */
+export class Timer {
+    startTime;
+    constructor() {
+        this.startTime = Date.now();
+    }
+    /**
+     * Gets the elapsed time as a formatted string.
+     * @param reset - If true, resets the timer after getting the elapsed time
+     * @returns Formatted string (e.g., "1h 2m 3s 456ms" or "0ms")
+     */
+    get(reset = false) {
+        const elapsedTime = Date.now() - this.startTime;
+        const result = this.formatElapsedTime(elapsedTime);
+        if (reset) {
+            this.reset();
+        }
+        return result;
+    }
+    /**
+     * Gets the elapsed time in milliseconds.
+     * @param reset - If true, resets the timer after getting the elapsed time
+     * @returns Elapsed time in milliseconds
+     */
+    getMs(reset = false) {
+        const elapsedTime = Date.now() - this.startTime;
+        if (reset) {
+            this.reset();
+        }
+        return elapsedTime;
+    }
+    /**
+     * Gets the elapsed time in seconds.
+     * @param reset - If true, resets the timer after getting the elapsed time
+     * @returns Elapsed time in seconds (with decimal precision)
+     */
+    getSeconds(reset = false) {
+        const elapsedTime = Date.now() - this.startTime;
+        const seconds = elapsedTime / 1000;
+        if (reset) {
+            this.reset();
+        }
+        return seconds;
+    }
+    /**
+     * Resets the timer to the current time.
+     */
+    reset() {
+        this.startTime = Date.now();
+    }
+    /**
+     * Formats elapsed time in milliseconds to a human-readable string.
+     * @param elapsedTime - Time in milliseconds
+     * @returns Formatted string (e.g., "1h 2m 3s 456ms" or "0ms")
+     */
+    formatElapsedTime(elapsedTime) {
+        // Ensure non-negative time
+        const time = Math.max(0, elapsedTime);
+        const hours = Math.floor(time / (1000 * 60 * 60));
+        const minutes = Math.floor(time / (1000 * 60)) % 60;
+        const seconds = Math.floor(time / 1000) % 60;
+        const milliseconds = time % 1000;
+        const parts = [];
+        if (hours > 0)
+            parts.push(`${hours}h`);
+        if (minutes > 0)
+            parts.push(`${minutes}m`);
+        if (seconds > 0)
+            parts.push(`${seconds}s`);
+        if (milliseconds > 0 || parts.length === 0) {
+            parts.push(`${milliseconds}ms`);
+        }
+        return parts.join(' ');
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@tmlmobilidade/go-utils-telemetry",
+	"version": "20260922.1130.21",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"test": "tsx --test tests/*.test.ts",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/go-utils-tsconfig": "*",
+		"@types/node": "26.4.0",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"tsx": "4.23.12",
+		"typescript": "6.0.3"
+	}
+}