@grest-ts/metrics 0.0.5 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grest-ts/metrics",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "type": "module",
   "license": "MIT",
   "description": "Metrics library for Grest Framework",
@@ -48,11 +48,11 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@grest-ts/common": "0.0.5",
-    "@grest-ts/locator": "0.0.5"
+    "@grest-ts/common": "0.0.7",
+    "@grest-ts/locator": "0.0.7"
   },
   "devDependencies": {
-    "@grest-ts/testkit": "0.0.5",
-    "@grest-ts/x-packager": "0.0.5"
+    "@grest-ts/testkit": "0.0.7",
+    "@grest-ts/x-packager": "0.0.7"
   }
 }

package/src/GGMetric.ts

@@ -1,124 +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];
+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

@@ -1,38 +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;
-}
+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

@@ -1,34 +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);
-            }
-        }
-    }
-}
+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

@@ -1,8 +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;
-}
+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

@@ -1,21 +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 () => {
-            }
-        })
-    }
-}
+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

@@ -1,26 +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();
-        }
-    }
-}
+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();
+        }
+    }
+}