@grest-ts/metrics 0.0.5

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@grest-ts/metrics",
+  "version": "0.0.5",
+  "type": "module",
+  "license": "MIT",
+  "description": "Metrics library for Grest Framework",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index-node.d.ts",
+      "import": "./dist/src/index-node.js"
+    },
+    "./testkit": {
+      "types": "./dist/testkit/index-testkit.d.ts",
+      "import": "./dist/testkit/index-testkit.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p src"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grest-ts/grest-ts.git",
+    "directory": "packages/metrics"
+  },
+  "homepage": "https://github.com/grest-ts/grest-ts/tree/master/packages/metrics",
+  "bugs": {
+    "url": "https://github.com/grest-ts/grest-ts/issues"
+  },
+  "keywords": [
+    "typescript",
+    "framework",
+    "contract",
+    "api",
+    "microservices",
+    "testing",
+    "metrics",
+    "monitoring",
+    "observability"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@grest-ts/common": "0.0.5",
+    "@grest-ts/locator": "0.0.5"
+  },
+  "devDependencies": {
+    "@grest-ts/testkit": "0.0.5",
+    "@grest-ts/x-packager": "0.0.5"
+  }
+}

package/src/GGMetric.ts

@@ -0,0 +1,124 @@
+import {GGMetricKey} from "./GGMetricKey";
+
+/**
+ * Configuration for grouping metrics in nested exporters.
+ * - labels: Which labels to use for grouping (must be subset of labelNames)
+ * - template: Optional template string for the group key. Use {labelName} for placeholders.
+ *             Missing values become empty strings. Defaults to values.join(',')
+ *             Example: "{api}.{method}" produces "MyApi.myMethod"
+ */
+export interface GroupByConfig<TLabels extends GGMetricLabels = {}> {
+    labels: readonly (keyof TLabels & string)[];
+    template?: string;
+}
+
+export interface GGMetricOptionsBase {
+    help: string;
+    maxLabelCombinations?: number;
+}
+
+export interface GGMetricOptionsWithLabels<TLabels extends GGMetricLabels> {
+    help: string;
+    maxLabelCombinations?: number;
+    labelNames: readonly (keyof TLabels & string)[];
+    groupBy?: GroupByConfig<TLabels>;
+}
+
+/**
+ * Options for metrics. When TLabels has keys, labelNames is required and must match those keys.
+ * Uses {} as "no labels" because keyof {} = never, while keyof Record<string, never> = string.
+ */
+export type GGMetricOptions<TLabels extends GGMetricLabels = {}> =
+    keyof TLabels extends never
+        ? GGMetricOptionsBase
+        : GGMetricOptionsWithLabels<TLabels>;
+
+export abstract class GGMetric<
+    TLabels extends GGMetricLabels = {},
+    TValue = unknown,
+    TKey extends GGMetricKey<TLabels> = GGMetricKey<TLabels>
+> {
+
+    public readonly key: TKey;
+    private readonly values = new Map<string, TValue>();
+    private readonly compiledGetKey: (labels: TLabels) => tMetricKey;
+
+    public constructor(key: TKey) {
+        this.key = key;
+        this.compiledGetKey = this.compileGetKey();
+    }
+
+    private compileGetKey(): (labels: TLabels) => tMetricKey {
+        const labelNames = this.key.labelNames;
+        if (labelNames.length === 0) {
+            return () => '' as tMetricKey;
+        }
+        // Build the function body: "name1=" + (l?.name1 ?? "") + ",name2=" + (l?.name2 ?? "")
+        let body = 'return ';
+        for (let i = 0; i < labelNames.length; i++) {
+            const name = labelNames[i];
+            if (i > 0) body += '+","+';
+            body += `"${name}="+(l?.${name}??"")`;
+        }
+        return new Function('l', body) as (labels: TLabels) => tMetricKey;
+    }
+
+    public get name(): string {
+        return this.key.name;
+    }
+
+    public reset(): void {
+        this.values.clear();
+    }
+
+    protected abstract getDefaultValue(): TValue;
+
+    /**
+     * Can't throw.
+     * Uses AOT-compiled function for fast key generation.
+     */
+    protected getKey(labels: TLabels): tMetricKey {
+        return this.compiledGetKey(labels);
+    }
+
+    /**
+     * Can't throw.
+     */
+    protected getByKey(key: tMetricKey): TValue | undefined {
+        const value = this.values.get(key);
+        if (value === undefined) {
+            if (this.values.size >= this.key.maxLabelCombinations) {
+                return undefined;
+            }
+            const defaultValue = this.getDefaultValue();
+            this.setByKey(key, defaultValue);
+            return defaultValue;
+        } else {
+            return value;
+        }
+    }
+
+    protected setByKey(key: tMetricKey, value: TValue): void {
+        this.values.set(key, value);
+    }
+
+    public getValue(...args: LabelsArgs<TLabels>): TValue {
+        return this.getByKey(this.getKey(args[0] as TLabels));
+    }
+
+    public getValues(): Map<string, TValue> {
+        return this.values;
+    }
+}
+
+export type tMetricKey = string & { tMetricKey: never };
+
+export type GGMetricLabels = Record<string, string | number | boolean>;
+
+/**
+ * Helper type for labels parameter. Makes labels required when TLabels has keys.
+ * - When TLabels = {}, no argument needed
+ * - When TLabels has keys, labels argument is required
+ */
+export type LabelsArgs<TLabels extends GGMetricLabels> =
+    keyof TLabels extends never ? [] : [labels: TLabels];

package/src/GGMetricKey.ts

@@ -0,0 +1,38 @@
+import {GGMetrics} from "./GGMetrics.js";
+import {GG_METRICS} from "./GGMetricsLoader.js";
+import {GGMetric, GGMetricLabels, GGMetricOptions, GroupByConfig} from "./GGMetric.js";
+
+export abstract class GGMetricKey<
+    TLabels extends GGMetricLabels = {},
+    TMetric extends GGMetric<TLabels, any, any> = GGMetric<TLabels, any, any>
+> {
+
+    public readonly root: string;
+    public readonly name: string;
+    public readonly help: string;
+    public readonly labelNames: readonly string[];
+    public readonly maxLabelCombinations?: number;
+    public readonly groupBy?: GroupByConfig<TLabels>;
+
+    protected constructor(name: string, options: GGMetricOptions<TLabels>) {
+        this.root = GGMetrics.getDefinitionContext();
+        if (!this.root) {
+            throw new Error("Metric key must be created inside GGMetrics.define()");
+        }
+        this.name = this.root + name;
+        this.help = options.help;
+        this.labelNames = ('labelNames' in options ? options.labelNames : []) as readonly (keyof TLabels & string)[];
+        this.maxLabelCombinations = options.maxLabelCombinations;
+        this.groupBy = ('groupBy' in options ? options.groupBy : undefined) as GroupByConfig<TLabels> | undefined;
+        Object.freeze(this.labelNames);
+        if (this.groupBy) {
+            Object.freeze(this.groupBy.labels);
+        }
+    }
+
+    protected getMetric(): TMetric {
+        return GG_METRICS.get().get(this) as TMetric;
+    }
+
+    public abstract create(): TMetric;
+}

package/src/GGMetrics.ts

@@ -0,0 +1,34 @@
+import {GGMetricKey} from "./GGMetricKey";
+import {METRICS_DEFINE_CONTEXT} from "./GGMetricsDefineStorage";
+
+export type GGMetricsDefinition<T> = T & { __isGGMetricsDefinition: never };
+
+export class GGMetrics {
+
+    public static define<T>(name: string, define: () => T): GGMetricsDefinition<T> {
+        return METRICS_DEFINE_CONTEXT.run(name, define) as GGMetricsDefinition<T>
+    }
+
+    public static getDefinitionContext(): string {
+        return METRICS_DEFINE_CONTEXT.getStore()!
+    }
+
+    public static toJSON(metrics: GGMetricsDefinition<any>): Record<string, unknown> {
+        const result: Record<string, unknown> = {};
+        this.collectKeys(metrics, result);
+        return result;
+    }
+
+    private static collectKeys(obj: unknown, result: Record<string, unknown>): void {
+        if (obj instanceof GGMetricKey) {
+            result[obj.name] = {
+                type: obj.constructor.name,
+                help: obj.help
+            };
+        } else if (obj && typeof obj === 'object') {
+            for (const value of Object.values(obj)) {
+                this.collectKeys(value, result);
+            }
+        }
+    }
+}

package/src/GGMetricsDefineStorage.ts

@@ -0,0 +1,8 @@
+import {BrowserAsyncStorage, type IAsyncStorage} from "@grest-ts/common";
+
+// Browser-safe by default. Node.js entry replaces with real AsyncLocalStorage.
+export let METRICS_DEFINE_CONTEXT: IAsyncStorage<string> = new BrowserAsyncStorage();
+
+export function _initMetricsStorage(storage: IAsyncStorage<string>): void {
+    METRICS_DEFINE_CONTEXT = storage;
+}

package/src/GGMetricsLoader.ts

@@ -0,0 +1,21 @@
+import {GGMetricsStore} from "./GGMetricsStore";
+import {GGLocator, GGLocatorKey, GGLocatorServiceType} from "@grest-ts/locator";
+
+export const GG_METRICS = new GGLocatorKey<GGMetricsStore>("GGMetrics");
+
+export class GGMetricsLoader {
+
+    private readonly store: GGMetricsStore;
+
+    constructor(store?: GGMetricsStore) {
+        this.store = store ?? new GGMetricsStore();
+
+        GGLocator.getScope().setWithLifecycle(GG_METRICS, this.store, {
+            type: GGLocatorServiceType.CONFIG + 1,
+            start: async () => {
+            },
+            teardown: async () => {
+            }
+        })
+    }
+}

package/src/GGMetricsStore.ts

@@ -0,0 +1,26 @@
+import {GGMetric, GGMetricLabels} from "./GGMetric.js";
+import {GGMetricKey} from "./GGMetricKey.js";
+
+export class GGMetricsStore {
+
+    private readonly metrics = new Map<string, GGMetric<any>>();
+
+    public get<TLabel extends GGMetricLabels>(key: GGMetricKey<TLabel>): GGMetric<TLabel> {
+        let metric = this.metrics.get(key.name);
+        if (!metric) {
+            metric = key.create();
+            this.metrics.set(key.name, metric);
+        }
+        return metric;
+    }
+
+    public getAllMetrics(): IterableIterator<GGMetric<any>> {
+        return this.metrics.values();
+    }
+
+    public reset(): void {
+        for (const metric of this.metrics.values()) {
+            metric.reset();
+        }
+    }
+}

package/src/exporters/GGJsonMetricsExporter.ts

@@ -0,0 +1,176 @@
+import {GGMetric} from "../GGMetric.js";
+import {GGCounter} from "../metric/GGCounter.js";
+import {GGGauge} from "../metric/GGGauge.js";
+import {GGLazyGauge} from "../metric/GGLazyGauge.js";
+import {GGHistogram, HistogramData} from "../metric/GGHistogram.js";
+import {GGMetricsExporter, ExporterConfig} from "./GGMetricsExporter.js";
+
+export type JsonMetricConverter = (metric: GGMetric<any>, exporter: GGJsonMetricsExporter) => JsonMetric;
+
+export class GGJsonMetricsExporter extends GGMetricsExporter<JsonMetricsOutput> {
+
+    // Static map for extensibility - register converters for new metric types
+    private static converters = new Map<Function, JsonMetricConverter>();
+
+    static {
+        GGJsonMetricsExporter.registerConverter(GGCounter, convertCounter);
+        GGJsonMetricsExporter.registerConverter(GGGauge, convertGauge);
+        GGJsonMetricsExporter.registerConverter(GGLazyGauge, convertLazyGauge);
+        GGJsonMetricsExporter.registerConverter(GGHistogram, convertHistogram);
+    }
+
+    /**
+     * Register a converter for a custom metric type.
+     */
+    static registerConverter(metricClass: Function, converter: JsonMetricConverter): void {
+        GGJsonMetricsExporter.converters.set(metricClass, converter);
+    }
+
+    constructor(config: ExporterConfig = {}) {
+        super(config);
+    }
+
+    getMetrics(): JsonMetricsOutput {
+        const output: JsonMetricsOutput = {
+            timestamp: Date.now(),
+            metrics: {}
+        };
+
+        for (const metric of this.getFilteredMetrics()) {
+            output.metrics[metric.name] = this.convertMetric(metric);
+        }
+
+        return output;
+    }
+
+    private convertMetric(metric: GGMetric<any>): JsonMetric {
+        const converter = GGJsonMetricsExporter.converters.get(metric.constructor);
+        if (!converter) {
+            throw new Error(`No converter registered for metric type: ${metric.constructor.name}`);
+        }
+        return converter(metric, this);
+    }
+
+    /**
+     * Parse a label key string into a labels object.
+     * Exposed for use by converters.
+     */
+    parseLabels(labelKey: string): Record<string, string> {
+        if (!labelKey) return {};
+        const labels: Record<string, string> = {};
+        const parts = labelKey.split(',');
+        for (const part of parts) {
+            const [key, val] = part.split('=');
+            if (key && val !== undefined) {
+                labels[key] = val;
+            }
+        }
+        return labels;
+    }
+}
+
+// Built-in converters
+
+function convertCounter(metric: GGCounter<any>, exporter: GGJsonMetricsExporter): JsonMetric {
+    const values: JsonMetricValue[] = [];
+    for (const [labelKey, value] of metric.getValues()) {
+        values.push({
+            labels: exporter.parseLabels(labelKey),
+            value
+        });
+    }
+    return {
+        name: metric.name,
+        type: 'counter',
+        help: metric.key.help,
+        values
+    };
+}
+
+function convertGauge(metric: GGGauge<any>, exporter: GGJsonMetricsExporter): JsonMetric {
+    const values: JsonMetricValue[] = [];
+    for (const [labelKey, value] of metric.getValues()) {
+        values.push({
+            labels: exporter.parseLabels(labelKey),
+            value
+        });
+    }
+    return {
+        name: metric.name,
+        type: 'gauge',
+        help: metric.key.help,
+        values
+    };
+}
+
+function convertLazyGauge(metric: GGLazyGauge, exporter: GGJsonMetricsExporter): JsonMetric {
+    // Lazy gauge computes value on read - no labels
+    return {
+        name: metric.name,
+        type: 'gauge',
+        help: metric.key.help,
+        values: [{
+            labels: {},
+            value: metric.getValue()
+        }]
+    };
+}
+
+function convertHistogram(metric: GGHistogram<any>, exporter: GGJsonMetricsExporter): JsonMetric {
+    const values: JsonMetricValue[] = [];
+    const buckets = metric.getBuckets();
+
+    for (const [labelKey, data] of metric.getValues() as Map<string, HistogramData>) {
+        const bucketObj: Record<string, number> = {};
+        for (let i = 0; i < buckets.length; i++) {
+            bucketObj[String(buckets[i])] = data.values[i] ?? 0;
+        }
+
+        values.push({
+            labels: exporter.parseLabels(labelKey),
+            value: {
+                count: data.count,
+                sum: data.sum,
+                avg: data.count > 0 ? data.sum / data.count : 0,
+                min: data.min === Infinity ? 0 : data.min,
+                max: data.max === -Infinity ? 0 : data.max,
+                buckets: bucketObj
+            }
+        });
+    }
+
+    return {
+        name: metric.name,
+        type: 'histogram',
+        help: metric.key.help,
+        values
+    };
+}
+
+// Types
+
+export interface JsonMetricValue {
+    labels: Record<string, string>;
+    value: number | JsonHistogramValue;
+}
+
+export interface JsonHistogramValue {
+    count: number;
+    sum: number;
+    avg: number;
+    min: number;
+    max: number;
+    buckets: Record<string, number>;
+}
+
+export interface JsonMetric {
+    name: string;
+    type: string;
+    help: string;
+    values: JsonMetricValue[];
+}
+
+export interface JsonMetricsOutput {
+    timestamp: number;
+    metrics: Record<string, JsonMetric>;
+}

package/src/exporters/GGMetricsExporter.ts

@@ -0,0 +1,88 @@
+import {GGMetricsStore} from "../GGMetricsStore.js";
+import {GG_METRICS} from "../GGMetricsLoader.js";
+import {GGMetric} from "../GGMetric.js";
+import {GGMetricKey} from "../GGMetricKey.js";
+
+export interface ExporterConfig {
+    store?: GGMetricsStore;
+    include?: unknown[];
+    exclude?: unknown[];
+}
+
+/**
+ * Abstract base class for metrics exporters.
+ * Handles config parsing, metric filtering, and key discovery.
+ */
+export abstract class GGMetricsExporter<TOutput> {
+    protected readonly store: GGMetricsStore;
+    private readonly includeKeys?: Set<GGMetricKey<any>>;
+    private readonly excludeKeys?: Set<GGMetricKey<any>>;
+
+    constructor(config: ExporterConfig = {}) {
+        this.store = config.store ?? GG_METRICS.get();
+        this.includeKeys = config.include ? this.discoverKeys(config.include) : undefined;
+        this.excludeKeys = config.exclude ? this.discoverKeys(config.exclude) : undefined;
+    }
+
+    /**
+     * Discover all GGMetricKey instances from an array of objects.
+     * Objects can be individual keys, or nested structures containing keys.
+     */
+    private discoverKeys(objects: unknown[]): Set<GGMetricKey<any>> {
+        const keys = new Set<GGMetricKey<any>>();
+        for (const obj of objects) {
+            this.discoverKeysRecursive(obj, keys);
+        }
+        return keys;
+    }
+
+    private discoverKeysRecursive(obj: unknown, keys: Set<GGMetricKey<any>>): void {
+        if (obj instanceof GGMetricKey) {
+            keys.add(obj);
+        } else if (obj && typeof obj === 'object') {
+            for (const value of Object.values(obj)) {
+                this.discoverKeysRecursive(value, keys);
+            }
+        }
+    }
+
+    /**
+     * Check if a metric should be included in the export.
+     * Exclude takes precedence over include.
+     */
+    protected shouldIncludeMetric(metric: GGMetric<any>): boolean {
+        // Exclude takes precedence
+        if (this.excludeKeys?.has(metric.key)) {
+            return false;
+        }
+        // If include is set, only include those
+        if (this.includeKeys) {
+            return this.includeKeys.has(metric.key);
+        }
+        // Default: include all
+        return true;
+    }
+
+    /**
+     * Get all metrics that pass the include/exclude filters.
+     */
+    protected* getFilteredMetrics(): Iterable<GGMetric<any>> {
+        for (const metric of this.store.getAllMetrics()) {
+            if (this.shouldIncludeMetric(metric)) {
+                yield metric;
+            }
+        }
+    }
+
+    /**
+     * Export metrics to the output format.
+     */
+    abstract getMetrics(): TOutput;
+
+    /**
+     * Export metrics as a JSON string.
+     */
+    getMetricsString(): string {
+        return JSON.stringify(this.getMetrics(), null, 2);
+    }
+}