@contrail/util 1.1.15-alpha-6 → 1.1.15-alpha-8

package/lib/performance-util/example-usage.js

@@ -1,4 +1,13 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const performance_util_1 = require("./performance-util");
 function demonstrateStartEndSpan() {
@@ -71,5 +80,219 @@ function demonstrateWarningBehavior() {
     console.log('Attempted to end "Non-existent Span" (should see warning above)');
     (0, performance_util_1.displayTimingTree)();
 }
-demonstrateStartEndSpan();
-demonstrateWarningBehavior();
+function demonstrateParentNodeId() {
+    return __awaiter(this, void 0, void 0, function* () {
+        console.log('\n--- Demonstrating parentNodeId Functionality ---\n');
+        (0, performance_util_1.clearDefaultTimingProfile)();
+        console.log('Example 5: Concurrent async operations with explicit parent');
+        yield (0, performance_util_1.withTimingAsync)('Main Operation', () => __awaiter(this, void 0, void 0, function* () {
+            const mainOpId = (0, performance_util_1.getCurrentParentNodeId)();
+            console.log(`Main Operation ID: ${mainOpId}`);
+            console.log('Starting concurrent operations...');
+            const results = yield Promise.all([
+                (0, performance_util_1.withTimingAsync)('Fetch User Data', () => __awaiter(this, void 0, void 0, function* () {
+                    yield new Promise((resolve) => setTimeout(resolve, 80));
+                    console.log('  ✓ User data fetched');
+                    return 'user-data';
+                }), { parentNodeId: mainOpId }),
+                (0, performance_util_1.withTimingAsync)('Fetch Permissions', () => __awaiter(this, void 0, void 0, function* () {
+                    yield new Promise((resolve) => setTimeout(resolve, 60));
+                    console.log('  ✓ Permissions fetched');
+                    return 'permissions-data';
+                }), { parentNodeId: mainOpId }),
+                (0, performance_util_1.withTimingAsync)('Fetch Preferences', () => __awaiter(this, void 0, void 0, function* () {
+                    yield new Promise((resolve) => setTimeout(resolve, 100));
+                    console.log('  ✓ Preferences fetched');
+                    return 'preferences-data';
+                }), { parentNodeId: mainOpId }),
+            ]);
+            console.log('All concurrent operations completed:', results);
+            yield (0, performance_util_1.withTimingAsync)('Process Results', () => __awaiter(this, void 0, void 0, function* () {
+                yield new Promise((resolve) => setTimeout(resolve, 30));
+                console.log('  ✓ Results processed');
+            }));
+        }));
+        (0, performance_util_1.displayTimingTree)();
+    });
+}
+function demonstrateMixedNesting() {
+    return __awaiter(this, void 0, void 0, function* () {
+        console.log('\n--- Demonstrating Mixed Natural and Explicit Nesting ---\n');
+        (0, performance_util_1.clearDefaultTimingProfile)();
+        console.log('Example 6: Mixed natural and explicit nesting');
+        yield (0, performance_util_1.withTimingAsync)('Application Startup', () => __awaiter(this, void 0, void 0, function* () {
+            yield (0, performance_util_1.withTimingAsync)('Load Configuration', () => __awaiter(this, void 0, void 0, function* () {
+                yield new Promise((resolve) => setTimeout(resolve, 50));
+                console.log('  ✓ Configuration loaded');
+                yield (0, performance_util_1.withTimingAsync)('Validate Config', () => __awaiter(this, void 0, void 0, function* () {
+                    yield new Promise((resolve) => setTimeout(resolve, 20));
+                    console.log('    ✓ Configuration validated');
+                }));
+            }));
+            console.log('Starting parallel initialization...');
+            (0, performance_util_1.startSpan)('Initialization');
+            const ininitializeId = (0, performance_util_1.getCurrentParentNodeId)();
+            (0, performance_util_1.withTimingSync)('Do something before initialization', () => {
+                const start = performance.now();
+                while (performance.now() < start + 20) {
+                }
+                console.log('  ✓ Pre-initialization task completed');
+            });
+            yield Promise.all([
+                (0, performance_util_1.withTimingAsync)('Initialize Database', () => __awaiter(this, void 0, void 0, function* () {
+                    yield new Promise((resolve) => setTimeout(resolve, 120));
+                    console.log('  ✓ Database initialized');
+                }), { parentNodeId: ininitializeId }),
+                (0, performance_util_1.withTimingAsync)('Initialize Cache', () => __awaiter(this, void 0, void 0, function* () {
+                    yield new Promise((resolve) => setTimeout(resolve, 90));
+                    console.log('  ✓ Cache initialized');
+                }), { parentNodeId: ininitializeId }),
+                (0, performance_util_1.withTimingAsync)('Initialize Logging', () => __awaiter(this, void 0, void 0, function* () {
+                    yield new Promise((resolve) => setTimeout(resolve, 40));
+                    console.log('  ✓ Logging initialized');
+                }), { parentNodeId: ininitializeId }),
+            ]);
+            (0, performance_util_1.withTimingSync)('Do something after initialization', () => {
+                const start = performance.now();
+                while (performance.now() < start + 20) {
+                }
+                console.log('  ✓ Post-initialization task completed');
+            });
+            (0, performance_util_1.endSpan)('Initialization');
+            yield (0, performance_util_1.withTimingAsync)('Final Setup', () => __awaiter(this, void 0, void 0, function* () {
+                yield new Promise((resolve) => setTimeout(resolve, 30));
+                console.log('  ✓ Final setup completed');
+            }));
+        }));
+        (0, performance_util_1.displayTimingTree)();
+    });
+}
+function demonstrateSyncWithParentId() {
+    console.log('\n--- Demonstrating Sync Functions with parentNodeId ---\n');
+    (0, performance_util_1.clearDefaultTimingProfile)();
+    console.log('Example 7: Sync functions with explicit parent');
+    (0, performance_util_1.withTimingSync)('Data Processing Pipeline', () => {
+        const pipelineId = (0, performance_util_1.getCurrentParentNodeId)();
+        console.log(`Pipeline ID: ${pipelineId}`);
+        (0, performance_util_1.withTimingSync)('Load Input Data', () => {
+            const start = performance.now();
+            while (performance.now() < start + 50) {
+            }
+            console.log('  ✓ Input data loaded');
+        });
+        (0, performance_util_1.withTimingSync)('Process Batch 1', () => {
+            const start = performance.now();
+            while (performance.now() < start + 80) {
+            }
+            console.log('  ✓ Batch 1 processed');
+        }, { parentNodeId: pipelineId });
+        (0, performance_util_1.withTimingSync)('Process Batch 2', () => {
+            const start = performance.now();
+            while (performance.now() < start + 70) {
+            }
+            console.log('  ✓ Batch 2 processed');
+        }, { parentNodeId: pipelineId });
+        (0, performance_util_1.withTimingSync)('Process Batch 3', () => {
+            const start = performance.now();
+            while (performance.now() < start + 90) {
+            }
+            console.log('  ✓ Batch 3 processed');
+        }, { parentNodeId: pipelineId });
+        (0, performance_util_1.withTimingSync)('Save Results', () => {
+            const start = performance.now();
+            while (performance.now() < start + 40) {
+            }
+            console.log('  ✓ Results saved');
+        });
+    });
+    (0, performance_util_1.displayTimingTree)();
+}
+function demonstrateManualSpansWithParentId() {
+    console.log('\n--- Demonstrating Manual Spans with parentNodeId ---\n');
+    (0, performance_util_1.clearDefaultTimingProfile)();
+    console.log('Example 8: Manual spans with explicit parent');
+    (0, performance_util_1.startSpan)('Service Request');
+    const serviceId = (0, performance_util_1.getCurrentParentNodeId)();
+    console.log(`Service Request ID: ${serviceId}`);
+    (0, performance_util_1.startSpan)('Authenticate User');
+    const start1 = performance.now();
+    while (performance.now() < start1 + 30) {
+    }
+    (0, performance_util_1.endSpan)('Authenticate User');
+    console.log('  ✓ User authenticated');
+    (0, performance_util_1.startSpan)('Validate Input', { parentNodeId: serviceId });
+    const start2 = performance.now();
+    while (performance.now() < start2 + 20) {
+    }
+    (0, performance_util_1.endSpan)('Validate Input');
+    console.log('  ✓ Input validated');
+    (0, performance_util_1.startSpan)('Check Rate Limits', { parentNodeId: serviceId });
+    const start3 = performance.now();
+    while (performance.now() < start3 + 15) {
+    }
+    (0, performance_util_1.endSpan)('Check Rate Limits');
+    console.log('  ✓ Rate limits checked');
+    (0, performance_util_1.startSpan)('Log Request', { parentNodeId: serviceId });
+    const start4 = performance.now();
+    while (performance.now() < start4 + 10) {
+    }
+    (0, performance_util_1.endSpan)('Log Request');
+    console.log('  ✓ Request logged');
+    (0, performance_util_1.startSpan)('Process Request');
+    const start5 = performance.now();
+    while (performance.now() < start5 + 60) {
+    }
+    (0, performance_util_1.endSpan)('Process Request');
+    console.log('  ✓ Request processed');
+    (0, performance_util_1.endSpan)('Service Request');
+    (0, performance_util_1.displayTimingTree)();
+}
+function demonstrateNestingComparison() {
+    return __awaiter(this, void 0, void 0, function* () {
+        console.log('\n--- Demonstrating Natural vs Explicit Nesting ---\n');
+        console.log('Natural Nesting (call stack based):');
+        (0, performance_util_1.clearDefaultTimingProfile)();
+        yield (0, performance_util_1.withTimingAsync)('Sequential Operations', () => __awaiter(this, void 0, void 0, function* () {
+            yield (0, performance_util_1.withTimingAsync)('Operation 1', () => __awaiter(this, void 0, void 0, function* () {
+                yield new Promise((resolve) => setTimeout(resolve, 30));
+            }));
+            yield (0, performance_util_1.withTimingAsync)('Operation 2', () => __awaiter(this, void 0, void 0, function* () {
+                yield new Promise((resolve) => setTimeout(resolve, 40));
+            }));
+            yield (0, performance_util_1.withTimingAsync)('Operation 3', () => __awaiter(this, void 0, void 0, function* () {
+                yield new Promise((resolve) => setTimeout(resolve, 35));
+            }));
+        }));
+        (0, performance_util_1.displayTimingTree)();
+        console.log('\nExplicit Parent Assignment (logical grouping):');
+        (0, performance_util_1.clearDefaultTimingProfile)();
+        yield (0, performance_util_1.withTimingAsync)('Parallel Operations', () => __awaiter(this, void 0, void 0, function* () {
+            const parentId = (0, performance_util_1.getCurrentParentNodeId)();
+            yield Promise.all([
+                (0, performance_util_1.withTimingAsync)('Operation 1', () => __awaiter(this, void 0, void 0, function* () {
+                    yield new Promise((resolve) => setTimeout(resolve, 30));
+                }), { parentNodeId: parentId }),
+                (0, performance_util_1.withTimingAsync)('Operation 2', () => __awaiter(this, void 0, void 0, function* () {
+                    yield new Promise((resolve) => setTimeout(resolve, 40));
+                }), { parentNodeId: parentId }),
+                (0, performance_util_1.withTimingAsync)('Operation 3', () => __awaiter(this, void 0, void 0, function* () {
+                    yield new Promise((resolve) => setTimeout(resolve, 35));
+                }), { parentNodeId: parentId }),
+            ]);
+        }));
+        (0, performance_util_1.displayTimingTree)();
+    });
+}
+function runAllExamples() {
+    return __awaiter(this, void 0, void 0, function* () {
+        demonstrateStartEndSpan();
+        demonstrateWarningBehavior();
+        yield demonstrateParentNodeId();
+        yield demonstrateMixedNesting();
+        demonstrateSyncWithParentId();
+        demonstrateManualSpansWithParentId();
+        yield demonstrateNestingComparison();
+        console.log('\nAll examples completed. ');
+    });
+}
+runAllExamples().catch(console.error);

package/lib/performance-util/performance-util.d.ts

@@ -2,23 +2,34 @@ type TimingSpans = TimingNode[];
 type TimingStack = TimingNode[];
 type TimingNode = {
     label: string;
+    id: string;
     durationMs: number;
     children: TimingNode[];
+    startTime: number;
 };
 type ActiveSpan = {
     node: TimingNode;
     startTime: number;
+    wasAddedToStack: boolean;
 };
 type TimingProfile = {
+    activeSpans: Map<string, ActiveSpan>;
+    spansById: Map<string, TimingNode>;
     timingSpans: TimingSpans;
     timingStack: TimingStack;
-    activeSpans: Map<string, ActiveSpan>;
 };
 export declare function getDefaultTimingProfile(): TimingProfile;
 export declare function clearDefaultTimingProfile(): void;
-export declare function withTimingAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
-export declare function withTimingSync<T>(label: string, fn: () => T): T;
+export declare function getCurrentParentNodeId(): string | null;
+export declare function withTimingAsync<T>(label: string, fn: () => Promise<T>, options?: {
+    parentNodeId?: string | null;
+}): Promise<T>;
+export declare function withTimingSync<T>(label: string, fn: () => T, options?: {
+    parentNodeId?: string | null;
+}): T;
 export declare function displayTimingTree(nodes?: TimingSpans, depth?: number): string;
-export declare function startSpan(spanName: string): void;
+export declare function startSpan(spanName: string, options?: {
+    parentNodeId?: string | null;
+}): void;
 export declare function endSpan(spanName: string): void;
 export {};

package/lib/performance-util/performance-util.js

@@ -11,15 +11,18 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDefaultTimingProfile = getDefaultTimingProfile;
 exports.clearDefaultTimingProfile = clearDefaultTimingProfile;
+exports.getCurrentParentNodeId = getCurrentParentNodeId;
 exports.withTimingAsync = withTimingAsync;
 exports.withTimingSync = withTimingSync;
 exports.displayTimingTree = displayTimingTree;
 exports.startSpan = startSpan;
 exports.endSpan = endSpan;
+const crypto_1 = require("crypto");
 const DEFAULT_TIMING_PROFILE = {
+    activeSpans: new Map(),
+    spansById: new Map(),
     timingSpans: [],
     timingStack: [],
-    activeSpans: new Map(),
 };
 function getDefaultTimingProfile() {
     return DEFAULT_TIMING_PROFILE;
@@ -30,48 +33,91 @@ function getTimingStack() {
 function getTimingSpans() {
     return DEFAULT_TIMING_PROFILE.timingSpans;
 }
+function getNodeById(id) {
+    return DEFAULT_TIMING_PROFILE.spansById.get(id);
+}
+function setSpanId(id, node) {
+    DEFAULT_TIMING_PROFILE.spansById.set(id, node);
+}
 function clearDefaultTimingProfile() {
     DEFAULT_TIMING_PROFILE.timingSpans = [];
     DEFAULT_TIMING_PROFILE.timingStack = [];
     DEFAULT_TIMING_PROFILE.activeSpans.clear();
+    DEFAULT_TIMING_PROFILE.spansById.clear();
 }
-function withTimingAsync(label, fn) {
+function getParentNode() {
+    const stack = getTimingStack();
+    return stack.length > 0 ? stack[stack.length - 1] : null;
+}
+function getCurrentParentNodeId() {
+    const parentNode = getParentNode();
+    return parentNode ? parentNode.id : null;
+}
+function withTimingAsync(label, fn, options) {
     return __awaiter(this, void 0, void 0, function* () {
         const start = performance.now();
-        const timingNode = { label, durationMs: 0, children: [] };
-        const parent = getTimingStack().length > 0 ? getTimingStack()[getTimingStack().length - 1] : null;
+        const chosenId = options === null || options === void 0 ? void 0 : options.parentNodeId;
+        const uniqueId = (0, crypto_1.randomUUID)();
+        const timingNode = {
+            label,
+            durationMs: 0,
+            children: [],
+            id: uniqueId,
+            startTime: start,
+        };
+        setSpanId(uniqueId, timingNode);
+        const parent = chosenId ? getNodeById(chosenId) : getParentNode();
         if (parent) {
             parent.children.push(timingNode);
         }
         else {
             getTimingSpans().push(timingNode);
         }
-        getTimingStack().push(timingNode);
+        const isRunningConcurrently = !!chosenId;
+        if (!isRunningConcurrently) {
+            getTimingStack().push(timingNode);
+        }
         return fn().finally(() => {
             const end = performance.now();
             timingNode.durationMs = end - start;
-            getTimingStack().pop();
+            if (!isRunningConcurrently) {
+                getTimingStack().pop();
+            }
         });
     });
 }
-function withTimingSync(label, fn) {
+function withTimingSync(label, fn, options) {
     const start = performance.now();
-    const timingNode = { label, durationMs: 0, children: [] };
-    const parent = getTimingStack().length > 0 ? getTimingStack()[getTimingStack().length - 1] : null;
+    const chosenId = options === null || options === void 0 ? void 0 : options.parentNodeId;
+    const uniqueId = (0, crypto_1.randomUUID)();
+    const timingNode = {
+        label,
+        durationMs: 0,
+        children: [],
+        id: uniqueId,
+        startTime: start,
+    };
+    setSpanId(uniqueId, timingNode);
+    const parent = chosenId ? getNodeById(chosenId) : getParentNode();
     if (parent) {
         parent.children.push(timingNode);
     }
     else {
         getTimingSpans().push(timingNode);
     }
-    getTimingStack().push(timingNode);
+    const isRunningConcurrently = !!chosenId;
+    if (!isRunningConcurrently) {
+        getTimingStack().push(timingNode);
+    }
     try {
         return fn();
     }
     finally {
         const end = performance.now();
         timingNode.durationMs = end - start;
-        getTimingStack().pop();
+        if (!isRunningConcurrently) {
+            getTimingStack().pop();
+        }
     }
 }
 function displayTimingTree(nodes = DEFAULT_TIMING_PROFILE.timingSpans, depth = 0) {
@@ -79,14 +125,58 @@ function displayTimingTree(nodes = DEFAULT_TIMING_PROFILE.timingSpans, depth = 0
     const indent = '  '.repeat(depth);
     const totalWidth = 120;
     const timeWidth = 10;
-    nodes.forEach((node) => {
-        const timeStr = `${node.durationMs.toFixed(2)}ms`;
-        const labelWithIndent = `${indent}${node.label}`;
-        const availableWidth = totalWidth - timeWidth - labelWithIndent.length;
-        const dots = '.'.repeat(Math.max(2, availableWidth));
-        lines.push(`${labelWithIndent}${dots}${timeStr.padStart(timeWidth)}`);
-        if (node.children && node.children.length > 0) {
-            lines.push(displayTimingTree(node.children, depth + 1));
+    const sortedNodes = [...nodes].sort((a, b) => a.startTime - b.startTime);
+    const groups = [];
+    let currentGroup = [];
+    for (let i = 0; i < sortedNodes.length; i++) {
+        const node = sortedNodes[i];
+        if (currentGroup.length === 0) {
+            currentGroup = [node];
+        }
+        else {
+            const hasOverlap = currentGroup.some((groupNode) => {
+                const nodeEnd = node.startTime + node.durationMs;
+                const groupNodeEnd = groupNode.startTime + groupNode.durationMs;
+                return node.startTime < groupNodeEnd && nodeEnd > groupNode.startTime;
+            });
+            if (hasOverlap) {
+                currentGroup.push(node);
+            }
+            else {
+                groups.push(currentGroup);
+                currentGroup = [node];
+            }
+        }
+    }
+    if (currentGroup.length > 0) {
+        groups.push(currentGroup);
+    }
+    groups.forEach((group) => {
+        if (group.length === 1) {
+            const node = group[0];
+            const timeStr = `${node.durationMs.toFixed(2)}ms`;
+            const labelWithIndent = `${indent}${node.label}`;
+            const availableWidth = totalWidth - timeWidth - labelWithIndent.length;
+            const dots = '.'.repeat(Math.max(2, availableWidth));
+            lines.push(`${labelWithIndent}${dots}${timeStr.padStart(timeWidth)}`);
+            if (node.children && node.children.length > 0) {
+                lines.push(displayTimingTree(node.children, depth + 1));
+            }
+        }
+        else {
+            const parallelHeader = `${indent}∥ Parallel Operations (${group.length})`;
+            lines.push(parallelHeader);
+            group.forEach((node) => {
+                const timeStr = `${node.durationMs.toFixed(2)}ms`;
+                const parallelIndicator = '∥ ';
+                const labelWithIndent = `${indent}${parallelIndicator}${node.label}`;
+                const availableWidth = totalWidth - timeWidth - labelWithIndent.length;
+                const dots = '.'.repeat(Math.max(2, availableWidth));
+                lines.push(`${labelWithIndent}${dots}${timeStr.padStart(timeWidth)}`);
+                if (node.children && node.children.length > 0) {
+                    lines.push(displayTimingTree(node.children, depth + 1));
+                }
+            });
         }
     });
     const result = lines.join('\n');
@@ -97,24 +187,37 @@ function displayTimingTree(nodes = DEFAULT_TIMING_PROFILE.timingSpans, depth = 0
     }
     return result;
 }
-function startSpan(spanName) {
+function startSpan(spanName, options) {
     if (DEFAULT_TIMING_PROFILE.activeSpans.has(spanName)) {
         console.warn(`Span "${spanName}" is already active. Please end it before starting a new one with the same name.`);
         return;
     }
     const startTime = performance.now();
-    const timingNode = { label: spanName, durationMs: 0, children: [] };
-    const parent = getTimingStack().length > 0 ? getTimingStack()[getTimingStack().length - 1] : null;
+    const chosenId = options === null || options === void 0 ? void 0 : options.parentNodeId;
+    const uniqueId = (0, crypto_1.randomUUID)();
+    const timingNode = {
+        label: spanName,
+        durationMs: 0,
+        children: [],
+        id: uniqueId,
+        startTime: startTime,
+    };
+    setSpanId(uniqueId, timingNode);
+    const parent = chosenId ? getNodeById(chosenId) : getParentNode();
     if (parent) {
         parent.children.push(timingNode);
     }
     else {
         getTimingSpans().push(timingNode);
     }
-    getTimingStack().push(timingNode);
+    const isRunningConcurrently = !!chosenId;
+    if (!isRunningConcurrently) {
+        getTimingStack().push(timingNode);
+    }
     DEFAULT_TIMING_PROFILE.activeSpans.set(spanName, {
         node: timingNode,
         startTime: startTime,
+        wasAddedToStack: !isRunningConcurrently,
     });
 }
 function endSpan(spanName) {
@@ -125,14 +228,16 @@ function endSpan(spanName) {
     }
     const endTime = performance.now();
     activeSpan.node.durationMs = endTime - activeSpan.startTime;
-    const currentTop = getTimingStack()[getTimingStack().length - 1];
-    if (currentTop === activeSpan.node) {
-        getTimingStack().pop();
-    }
-    else {
-        const stackIndex = getTimingStack().findIndex((node) => node === activeSpan.node);
-        if (stackIndex !== -1) {
-            getTimingStack().splice(stackIndex, 1);
+    if (activeSpan.wasAddedToStack) {
+        const currentTop = getTimingStack()[getTimingStack().length - 1];
+        if (currentTop === activeSpan.node) {
+            getTimingStack().pop();
+        }
+        else {
+            const stackIndex = getTimingStack().findIndex((node) => node === activeSpan.node);
+            if (stackIndex !== -1) {
+                getTimingStack().splice(stackIndex, 1);
+            }
         }
     }
     DEFAULT_TIMING_PROFILE.activeSpans.delete(spanName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/util",
-  "version": "1.1.15-alpha-6",
+  "version": "1.1.15-alpha-8",
   "description": "General JavaScript utilities",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",