@astralarium/repo-telemetry 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astralarium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# `@astralarium/repo-telemetry`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenTelemetry compatible structured logging.
+Supports minimal ICU syntax.
+Strongly typed.
+
+```ts
+import { log } from "@astralarium/repo-telemetry";
+
+log.info("user.joined", "{user} joined", { user });
+log.info("cart.items", "{n, plural, one {# item} other {# items}}", { n });
+log.info("user.left", "{why, select, kick {kicked} other {left}}", { why });
+log.error("job.failed", "job failed", { exception });
+```
+
+`pnpm lint --fix` updates type annotations.
+
+Error logging exceptions also outputs a stack trace,
+unless thrown as `ExpectedError` (useful for CLIs).
+
+## Environment Variables
+
+- `LOG_FORMAT=json`: output JSON lines.
+- `LOG_STACKS=1`: always output stack trace.

package/dist/src/json.d.ts

@@ -0,0 +1,11 @@
+/** Arbitrary values as JSON or text, never throwing. */
+/** JSON replacer: bigints as decimal strings. */
+export declare const jsonReplacer: (_key: string, value: unknown) => unknown;
+/** `value` as JSON, bigints as strings; `[unserializable]` when cyclic or
+ *  otherwise rejected. */
+export declare function safeJson(value: unknown): string;
+/** `value`, or `[unserializable]` when JSON rejects it (cycles). */
+export declare function serializable(value: unknown): unknown;
+/** `String(value)`, or `[unprintable]` where that throws (null-prototype
+ *  objects). */
+export declare function safeString(value: unknown): string;

package/dist/src/json.js

@@ -0,0 +1,35 @@
+/** Arbitrary values as JSON or text, never throwing. */
+/** JSON replacer: bigints as decimal strings. */
+export const jsonReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
+/** Stand-in for a value JSON rejects. */
+const UNSERIALIZABLE = "[unserializable]";
+/** `value` as JSON, bigints as strings; `[unserializable]` when cyclic or
+ *  otherwise rejected. */
+export function safeJson(value) {
+    try {
+        return JSON.stringify(value, jsonReplacer) ?? String(value);
+    }
+    catch {
+        return UNSERIALIZABLE;
+    }
+}
+/** `value`, or `[unserializable]` when JSON rejects it (cycles). */
+export function serializable(value) {
+    try {
+        JSON.stringify(value, jsonReplacer);
+        return value;
+    }
+    catch {
+        return UNSERIALIZABLE;
+    }
+}
+/** `String(value)`, or `[unprintable]` where that throws (null-prototype
+ *  objects). */
+export function safeString(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return "[unprintable]";
+    }
+}

package/dist/src/logger.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Structured logging facade. Records follow the OpenTelemetry log data
+ * model (event names, severity numbers, exception.* attributes) without
+ * depending on the OTel SDK, so any sink stays OTLP-compatible.
+ * Templates are an ICU MessageFormat subset (`template.ts`).
+ *
+ * `log` picks its sink per runtime (`runtimeSink`).
+ */
+/** OTel severity numbers per level. */
+declare const SEVERITY: {
+    readonly debug: 5;
+    readonly info: 9;
+    readonly warn: 13;
+    readonly error: 17;
+};
+export type LogLevel = keyof typeof SEVERITY;
+export type LogAttributes = Record<string, unknown>;
+export interface LogRecord {
+    level: LogLevel;
+    severityNumber: number;
+    /** OTel event name: lowercase, dot-separated, globally unique, e.g.
+     *  "match.seed_failed". */
+    event: string;
+    /** ICU template whose arguments name attributes. */
+    template: string;
+    /** `template` filled in from `attributes`. */
+    message: string;
+    /** Caller attributes as given, `exception` lifted out. */
+    attributes: LogAttributes;
+    /** The `exception` attribute: the caught value. */
+    exception?: unknown;
+}
+export type LogSink = (record: LogRecord) => void;
+/** Emits `event` with `template` filled in from `attributes`. `V` is the
+ *  template's argument contract, written by `telemetry/template` lint;
+ *  attributes are required while it names any. The `exception` attribute
+ *  takes a caught value. */
+export type LogMethod = <V extends LogAttributes = Record<never, never>>(event: string, template: string, ...attributes: [keyof V] extends [never] ? [attributes?: LogAttributes] : [attributes: V & LogAttributes]) => void;
+export interface Logger {
+    debug: LogMethod;
+    info: LogMethod;
+    warn: LogMethod;
+    error: LogMethod;
+}
+/** A failure its message fully explains: input, environment, config or
+ *  state the user fixes. Terminal output shows its message and causes,
+ *  stack-free. */
+export declare class ExpectedError extends Error {
+    name: string;
+}
+/** Emits one JSON object per record to `console`, at its level; on
+ *  Workers, Workers Logs indexes and timestamps it. */
+export declare const consoleSink: LogSink;
+/** `consoleSink` with the caught error as a second argument: DevTools
+ *  expands it with source-mapped frames and causes. */
+export declare const browserSink: LogSink;
+/** Writes one JSON line per record to `console.error`, led by a
+ *  `timestamp`: stderr in Node. Bigints become strings; an attribute JSON
+ *  rejects becomes `[unserializable]`. */
+export declare const jsonLinesSink: LogSink;
+/** How `textSink` renders errors. */
+export interface TextOptions {
+    /** Every error's stack trace, error attributes included; otherwise only
+     *  an error record's unexpected exception shows one. */
+    stacks?: boolean;
+}
+/**
+ * Human-readable sink: one line per record,
+ * `[level: ]message[: exception message] key=value…` (pairs: attributes
+ * the template leaves unread; event and undefined values omitted).
+ * Indented below: the exception's stack on error records unless expected,
+ * else its causes; with `stacks`, every error's stack.
+ */
+export declare function textSink(write: (line: string) => void, { stacks }?: TextOptions): LogSink;
+/** Logger writing to `sink`. */
+export declare function createLogger(sink: LogSink): Logger;
+/** Runtime globals `runtimeSink` reads, each absent somewhere. */
+export interface RuntimeGlobals {
+    navigator?: {
+        userAgent?: string;
+    };
+    document?: unknown;
+    process?: {
+        versions?: {
+            node?: string;
+        };
+        env?: Record<string, string | undefined>;
+    };
+}
+/** The sink for `runtime`: Workers before Node (`nodejs_compat` reports a
+ *  Node version), browsers (jsdom too) before Node. Node: `textSink` onto
+ *  stderr, for CLIs; `LOG_FORMAT=json` writes JSON lines; `LOG_STACKS=1`
+ *  prints every stack. */
+export declare function runtimeSink(runtime?: RuntimeGlobals): LogSink;
+/** Logger onto the runtime's sink. */
+export declare const log: Logger;
+export {};

package/dist/src/logger.js

@@ -0,0 +1,282 @@
+/**
+ * Structured logging facade. Records follow the OpenTelemetry log data
+ * model (event names, severity numbers, exception.* attributes) without
+ * depending on the OTel SDK, so any sink stays OTLP-compatible.
+ * Templates are an ICU MessageFormat subset (`template.ts`).
+ *
+ * `log` picks its sink per runtime (`runtimeSink`).
+ */
+import { templateArguments } from "@astralarium/icu-template";
+import { jsonReplacer, safeJson, safeString, serializable } from "./json.js";
+import { formatTemplate } from "./template.js";
+/** OTel severity numbers per level. */
+const SEVERITY = {
+    debug: 5,
+    info: 9,
+    warn: 13,
+    error: 17,
+};
+/** Errors `error` consists of under their labels: a suppressed pair or
+ *  aggregate members. */
+function constituents(error) {
+    if (typeof SuppressedError !== "undefined" &&
+        error instanceof SuppressedError)
+        return [
+            ["Caused by", error.error],
+            ["Suppressed", error.suppressed],
+        ];
+    if (error instanceof AggregateError)
+        return error.errors.map((inner) => ["Caused by", inner]);
+    return [];
+}
+/** Errors nested in `error` under their labels: its cause, then its
+ *  constituents. */
+function nestedErrors(error) {
+    return [
+        ...(error.cause === undefined
+            ? []
+            : [["Caused by", error.cause]]),
+        ...constituents(error),
+    ];
+}
+/** A failure its message fully explains: input, environment, config or
+ *  state the user fixes. Terminal output shows its message and causes,
+ *  stack-free. */
+export class ExpectedError extends Error {
+    name = "ExpectedError";
+}
+/** `error` is an `ExpectedError`, or a `SuppressedError` or
+ *  `AggregateError` whose constituents are all expected. */
+function isExpected(error, ancestors = new Set()) {
+    if (error instanceof ExpectedError)
+        return true;
+    if (!(error instanceof Error) || ancestors.has(error))
+        return false;
+    const parts = constituents(error);
+    ancestors.add(error);
+    const expected = parts.length > 0 &&
+        parts.every(([, inner]) => isExpected(inner, ancestors));
+    ancestors.delete(error);
+    return expected;
+}
+/** `error`'s message; `String(error)` for other thrown values. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : safeString(error);
+}
+/** Lines naming `error`'s nested errors, each under its label and
+ *  indented by depth; an error nested in itself shows as circular. */
+function causeLines(error, indent = "  ", ancestors = new Set()) {
+    if (!(error instanceof Error))
+        return [];
+    ancestors.add(error);
+    const lines = nestedErrors(error).flatMap(([label, inner]) => inner instanceof Error && ancestors.has(inner)
+        ? [`${indent}${label}: [circular ${inner.name}]`]
+        : [
+            `${indent}${label}: ${errorMessage(inner)}`,
+            ...causeLines(inner, `${indent}  `, ancestors),
+        ]);
+    ancestors.delete(error);
+    return lines;
+}
+/** `error`'s stack, then each nested error's after its label; an error
+ *  nested in itself shows as circular. */
+function stackTrace(error, ancestors = new Set()) {
+    if (!(error instanceof Error))
+        return safeString(error);
+    if (ancestors.has(error))
+        return `[circular ${error.name}]`;
+    ancestors.add(error);
+    const trace = [
+        error.stack ?? `${error.name}: ${error.message}`,
+        ...nestedErrors(error).map(([label, inner]) => `${label}: ${stackTrace(inner, ancestors)}`),
+    ].join("\n");
+    ancestors.delete(error);
+    return trace;
+}
+/** OTel `exception.*` attributes for a caught value; the stacktrace
+ *  carries nested errors' stacks after `Caused by:` / `Suppressed:`. */
+function exceptionAttributes(error) {
+    if (error instanceof Error)
+        return {
+            "exception.type": error.name,
+            "exception.message": error.message,
+            "exception.stacktrace": stackTrace(error),
+        };
+    return { "exception.message": safeString(error) };
+}
+/** `value` with an `Error` made JSON-ready: `{ type, message,
+ *  stacktrace }`. */
+function serializeError(value) {
+    if (!(value instanceof Error))
+        return value;
+    return {
+        type: value.name,
+        message: value.message,
+        stacktrace: stackTrace(value),
+    };
+}
+/** `record`'s attributes in OTel form: the exception expanded to
+ *  `exception.*` (caller attributes win), other errors serialized. */
+function otelAttributes(record) {
+    return {
+        ...("exception" in record && exceptionAttributes(record.exception)),
+        ...Object.fromEntries(Object.entries(record.attributes).map(([k, v]) => [k, serializeError(v)])),
+    };
+}
+const CONSOLE_METHOD = {
+    debug: "debug",
+    info: "log",
+    warn: "warn",
+    error: "error",
+};
+/** A record as JSON: `event.name`, `message`, `level`, `severityNumber`,
+ *  and `attributes` nested. */
+const jsonRecord = (record) => ({
+    "event.name": record.event,
+    message: record.message,
+    level: record.level,
+    severityNumber: record.severityNumber,
+    attributes: otelAttributes(record),
+});
+/** Emits one JSON object per record to `console`, at its level; on
+ *  Workers, Workers Logs indexes and timestamps it. */
+export const consoleSink = (record) => {
+    console[CONSOLE_METHOD[record.level]](jsonRecord(record));
+};
+/** `consoleSink` with the caught error as a second argument: DevTools
+ *  expands it with source-mapped frames and causes. */
+export const browserSink = (record) => {
+    const write = console[CONSOLE_METHOD[record.level]].bind(console);
+    if (record.exception === undefined)
+        write(jsonRecord(record));
+    else
+        write(jsonRecord(record), record.exception);
+};
+/** Writes one JSON line per record to `console.error`, led by a
+ *  `timestamp`: stderr in Node. Bigints become strings; an attribute JSON
+ *  rejects becomes `[unserializable]`. */
+export const jsonLinesSink = (record) => {
+    const json = jsonRecord(record);
+    json.attributes = Object.fromEntries(Object.entries(json.attributes).map(([k, v]) => [k, serializable(v)]));
+    console.error(JSON.stringify({ timestamp: new Date().toISOString(), ...json }, jsonReplacer));
+};
+/** Line prefix per level; info lines carry none. */
+const TEXT_PREFIX = {
+    debug: "debug: ",
+    info: "",
+    warn: "warning: ",
+    error: "error: ",
+};
+/** Attribute value as text: `?` when null, an error's message, bare when
+ *  unambiguous, JSON otherwise. */
+function textValue(value) {
+    if (value === null)
+        return "?";
+    if (value instanceof Error)
+        return textValue(value.message);
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "string")
+        return value === "" || /[\s"=]/.test(value) ? JSON.stringify(value) : value;
+    return safeJson(value);
+}
+/** Argument names `template` reads; none when malformed, which
+ *  `formatTemplate` renders as text. */
+function shownArguments(template) {
+    try {
+        return templateArguments(template);
+    }
+    catch {
+        return new Map();
+    }
+}
+/**
+ * Human-readable sink: one line per record,
+ * `[level: ]message[: exception message] key=value…` (pairs: attributes
+ * the template leaves unread; event and undefined values omitted).
+ * Indented below: the exception's stack on error records unless expected,
+ * else its causes; with `stacks`, every error's stack.
+ */
+export function textSink(write, { stacks = false } = {}) {
+    return (record) => {
+        const { level, template, message, attributes } = record;
+        const caught = "exception" in record;
+        const shown = shownArguments(template);
+        const pairs = Object.entries(attributes)
+            .filter(([k, v]) => v !== undefined && !shown.has(k))
+            .map(([k, v]) => ` ${k}=${textValue(v)}`);
+        const indent = (text) => text.replace(/^/gm, "  ");
+        const exceptionStack = caught &&
+            (stacks || (level === "error" && !isExpected(record.exception)));
+        const below = [
+            ...(exceptionStack
+                ? [indent(stackTrace(record.exception))]
+                : caught
+                    ? causeLines(record.exception)
+                    : []),
+            ...(stacks
+                ? Object.entries(attributes)
+                    .filter(([, v]) => v instanceof Error)
+                    .map(([k, v]) => indent(`${k}: ${stackTrace(v)}`))
+                : []),
+        ];
+        write([
+            `${TEXT_PREFIX[level]}${message}${caught ? `: ${errorMessage(record.exception)}` : ""}${pairs.join("")}`,
+            ...below,
+        ].join("\n"));
+    };
+}
+/** Logger writing to `sink`. */
+export function createLogger(sink) {
+    const method = (level) => ((event, template, given = {}) => {
+        // Logging runs in callers' error paths; it never throws into them.
+        try {
+            const { exception, ...attributes } = given;
+            sink({
+                level,
+                severityNumber: SEVERITY[level],
+                event,
+                template,
+                message: formatTemplate(template, attributes),
+                attributes,
+                ...("exception" in given && { exception }),
+            });
+        }
+        catch (failure) {
+            try {
+                console.error("log dropped", event, failure);
+            }
+            catch {
+                // Console itself failed; nothing left to report to.
+            }
+        }
+    });
+    return {
+        debug: method("debug"),
+        info: method("info"),
+        warn: method("warn"),
+        error: method("error"),
+    };
+}
+/** The sink for `runtime`: Workers before Node (`nodejs_compat` reports a
+ *  Node version), browsers (jsdom too) before Node. Node: `textSink` onto
+ *  stderr, for CLIs; `LOG_FORMAT=json` writes JSON lines; `LOG_STACKS=1`
+ *  prints every stack. */
+export function runtimeSink(runtime = globalThis) {
+    if (runtime.navigator?.userAgent === "Cloudflare-Workers")
+        return consoleSink;
+    if (runtime.document !== undefined)
+        return browserSink;
+    const node = runtime.process;
+    if (node?.versions?.node)
+        return node.env?.LOG_FORMAT === "json"
+            ? jsonLinesSink
+            : textSink((line) => {
+                console.error(line);
+            }, { stacks: node.env?.LOG_STACKS === "1" });
+    return consoleSink;
+}
+/** Logger onto the runtime's sink. */
+export const log = createLogger(runtimeSink());

package/dist/src/template.d.ts

@@ -0,0 +1,2 @@
+/** `template` filled in from `values`. */
+export declare function formatTemplate(template: string, values: Record<string, unknown>): string;

package/dist/src/template.js

@@ -0,0 +1,22 @@
+/** Log templates: `@astralarium/icu-template` over log values. */
+import { renderText } from "@astralarium/icu-template";
+import { safeJson, safeString } from "./json.js";
+/** Argument value as message text: `?` when null or undefined, lists
+ *  comma-joined. */
+function messageValue(value) {
+    if (value === null || value === undefined)
+        return "?";
+    if (Array.isArray(value))
+        return value.map(messageValue).join(", ");
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Error)
+        return value.message;
+    if (typeof value === "object")
+        return safeJson(value);
+    return safeString(value);
+}
+/** `template` filled in from `values`. */
+export function formatTemplate(template, values) {
+    return renderText(template, values, messageValue);
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@astralarium/repo-telemetry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "homepage": "https://github.com/astralarium/repo/tree/main/packages/repo-telemetry#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astralarium/repo.git",
+    "directory": "packages/repo-telemetry"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/src/logger.js",
+    "./template": "./dist/src/template.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@astralarium/icu-template": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.0",
+    "@typescript-eslint/rule-tester": "^8.71.0",
+    "eslint": "^10.2.1",
+    "intl-messageformat": "^12.1.2",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.3",
+    "@astralarium/repo-config-typescript": "^0.1.0",
+    "@astralarium/repo-config-eslint": "^0.1.0",
+    "@astralarium/repo-package-files": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=24.2"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit && tsc -p tsconfig.build.json --noEmit",
+    "lint": "eslint",
+    "test": "vitest"
+  }
 }