lemon-core 5.0.0 → 5.0.2

package/dist/lib/perf.d.ts

@@ -9,6 +9,7 @@
  *
  * @author      Steve Jung <steve@lemoncloud.io>
  * @date        2026-10-27 v5 B2-c (D40)
+ * @date        2026-10-28 v5 B7: `PerfTrace` for the per-request `PERF` lines.
  *
  * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
  */
@@ -33,3 +34,31 @@ export declare const measure: <T>(log: PerfLogger, ns: string, label: string, fn
  * - a rejection is passed through, and no line is printed.
  */
 export declare const measureAsync: <T>(log: PerfLogger, ns: string, label: string, fn: () => Promise<T>) => Promise<T>;
+/** a value of `PerfTrace.line()`: `undefined`, `null` and `''` drop the key. */
+export type PerfValue = string | number | boolean | null | undefined;
+/**
+ * class: `PerfTrace`
+ * - step marks of one request (v5 B7): each `mark(name)` keeps the ms since the previous mark (or the start).
+ * - holds numbers only; the caller prints the line with its own logger.
+ */
+export declare class PerfTrace {
+    private readonly t0;
+    private cursor;
+    private readonly $marks;
+    constructor();
+    /**
+     * keep the ms since the previous mark (or t0) as `name`, then move the cursor.
+     * @returns the ms of this mark.
+     */
+    mark(name: string): number;
+    /** the ms since t0. */
+    elapsed(): number;
+    /** a copy of the marks. */
+    marks(): Record<string, number>;
+    /**
+     * build the `key=value` tail in the given key order.
+     * - `undefined`, `null` and `''` drop the key; a boolean is `1`/`0`; a number (ms) has one decimal.
+     * - pass a number that is not ms (ex: an HTTP status) as a string.
+     */
+    line(extra: Record<string, PerfValue>): string;
+}

package/dist/lib/perf.js

@@ -10,11 +10,12 @@
  *
  * @author      Steve Jung <steve@lemoncloud.io>
  * @date        2026-10-27 v5 B2-c (D40)
+ * @date        2026-10-28 v5 B7: `PerfTrace` for the per-request `PERF` lines.
  *
  * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.measureAsync = exports.measure = exports.nowMs = void 0;
+exports.PerfTrace = exports.measureAsync = exports.measure = exports.nowMs = void 0;
 /**
  * current monotonic time in ms (from `process.hrtime.bigint()`).
  */
@@ -49,4 +50,63 @@ const measureAsync = async (log, ns, label, fn) => {
     return res;
 };
 exports.measureAsync = measureAsync;
+/**
+ * class: `PerfTrace`
+ * - step marks of one request (v5 B7): each `mark(name)` keeps the ms since the previous mark (or the start).
+ * - holds numbers only; the caller prints the line with its own logger.
+ */
+class PerfTrace {
+    //* start time (t0), and the cursor of the last mark.
+    t0;
+    cursor;
+    //* marks by name (the insertion order is kept).
+    $marks = {};
+    //* start the trace now.
+    constructor() {
+        this.t0 = (0, exports.nowMs)();
+        this.cursor = this.t0;
+    }
+    /**
+     * keep the ms since the previous mark (or t0) as `name`, then move the cursor.
+     * @returns the ms of this mark.
+     */
+    mark(name) {
+        const now = (0, exports.nowMs)();
+        const ms = now - this.cursor;
+        this.$marks[name] = ms;
+        this.cursor = now;
+        return ms;
+    }
+    /** the ms since t0. */
+    elapsed() {
+        return (0, exports.nowMs)() - this.t0;
+    }
+    /** a copy of the marks. */
+    marks() {
+        return { ...this.$marks };
+    }
+    /**
+     * build the `key=value` tail in the given key order.
+     * - `undefined`, `null` and `''` drop the key; a boolean is `1`/`0`; a number (ms) has one decimal.
+     * - pass a number that is not ms (ex: an HTTP status) as a string.
+     */
+    line(extra) {
+        //* format one value (or `null` to drop the key).
+        const asText = (v) => {
+            if (v === undefined || v === null || v === '')
+                return null;
+            if (typeof v === 'boolean')
+                return v ? '1' : '0';
+            if (typeof v === 'number')
+                return v.toFixed(1);
+            return `${v}`;
+        };
+        return Object.entries(extra || {})
+            .map(([k, v]) => [k, asText(v)])
+            .filter(([, v]) => v !== null)
+            .map(([k, v]) => `${k}=${v}`)
+            .join(' ');
+    }
+}
+exports.PerfTrace = PerfTrace;
 //# sourceMappingURL=perf.js.map

package/dist/lib/perf.js.map

@@ -1 +1 @@
-{"version":3,"file":"perf.js","sourceRoot":"","sources":["../../src/lib/perf.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAKH;;GAEG;AACI,MAAM,KAAK,GAAG,GAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,GAAG,CAAC;AAA5D,QAAA,KAAK,SAAuD;AAEzE,0CAA0C;AAC1C,MAAM,IAAI,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,GAAG,CAAC,IAAA,aAAK,GAAE,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;AAEvE;;;;;;;;GAQG;AACI,MAAM,OAAO,GAAG,CAAI,GAAe,EAAE,EAAU,EAAE,KAAa,EAAE,EAAW,EAAK,EAAE;IACrF,MAAM,EAAE,GAAG,IAAA,aAAK,GAAE,CAAC;IACnB,MAAM,GAAG,GAAG,EAAE,EAAE,CAAC;IACjB,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9B,OAAO,GAAG,CAAC;AACf,CAAC,CAAC;AALW,QAAA,OAAO,WAKlB;AAEF;;;GAGG;AACI,MAAM,YAAY,GAAG,KAAK,EAAK,GAAe,EAAE,EAAU,EAAE,KAAa,EAAE,EAAoB,EAAc,EAAE;IAClH,MAAM,EAAE,GAAG,IAAA,aAAK,GAAE,CAAC;IACnB,MAAM,GAAG,GAAG,MAAM,EAAE,EAAE,CAAC;IACvB,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9B,OAAO,GAAG,CAAC;AACf,CAAC,CAAC;AALW,QAAA,YAAY,gBAKvB"}
+{"version":3,"file":"perf.js","sourceRoot":"","sources":["../../src/lib/perf.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemon-core",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Lemon Serverless Micro-Service Platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",