fix(js): store execution order number in dotted order (#654)

Closes LS-1663

js/src/run_trees.ts

@@ -16,10 +16,18 @@ function stripNonAlphanumeric(input: string) {
   return input.replace(/[-:.]/g, "");
 }
 
-export function convertToDottedOrderFormat(epoch: number, runId: string) {
+export function convertToDottedOrderFormat(
+  epoch: number,
+  runId: string,
+  executionOrder = 1
+) {
+  // Date only has millisecond precision, so we use the microseconds to break
+  // possible ties, avoiding incorrect run order
+  const paddedOrder = executionOrder.toFixed(0).slice(0, 3).padStart(3, "0");
   return (
-    stripNonAlphanumeric(`${new Date(epoch).toISOString().slice(0, -1)}000Z`) +
-    runId
+    stripNonAlphanumeric(
+      `${new Date(epoch).toISOString().slice(0, -1)}${paddedOrder}Z`
+    ) + runId
   );
 }
 
@@ -44,6 +52,8 @@ export interface RunTreeConfig {
   client?: Client;
   tracingEnabled?: boolean;
   on_end?: (runTree: RunTree) => void;
+  execution_order?: number;
+  child_execution_order?: number;
 }
 
 export interface RunnableConfigLike {
@@ -86,7 +96,7 @@ export class RunTree implements BaseRun {
   name: RunTreeConfig["name"];
   run_type: string;
   project_name: string;
-  parent_run?: BaseRun;
+  parent_run?: RunTree;
   child_runs: RunTree[];
   start_time: number;
   end_time?: number;
@@ -103,6 +113,8 @@ export class RunTree implements BaseRun {
   dotted_order: string;
 
   tracingEnabled?: boolean;
+  execution_order: number;
+  child_execution_order: number;
 
   constructor(originalConfig: RunTreeConfig) {
     const defaultConfig = RunTree.getDefaultConfig();
@@ -121,10 +133,15 @@ export class RunTree implements BaseRun {
         this.trace_id = this.id;
       }
     }
+
+    this.execution_order ??= 1;
+    this.child_execution_order ??= 1;
+
     if (!this.dotted_order) {
       const currentDottedOrder = convertToDottedOrderFormat(
         this.start_time,
-        this.id
+        this.id,
+        this.execution_order
       );
       if (this.parent_run) {
         this.dotted_order =
@@ -197,14 +214,31 @@ export class RunTree implements BaseRun {
   }
 
   public createChild(config: RunTreeConfig): RunTree {
+    const child_execution_order = this.child_execution_order + 1;
+
     const child = new RunTree({
       ...config,
       parent_run: this,
       project_name: this.project_name,
       client: this.client,
       tracingEnabled: this.tracingEnabled,
+      execution_order: child_execution_order,
+      child_execution_order: child_execution_order,
     });
 
+    // propagate child_execution_order upwards
+    const visited = new Set<string>();
+    let current: RunTree | undefined = this as RunTree;
+    while (current != null && !visited.has(current.id)) {
+      visited.add(current.id);
+      current.child_execution_order = Math.max(
+        current.child_execution_order,
+        child_execution_order
+      );
+
+      current = current.parent_run;
+    }
+
     this.child_runs.push(child);
     return child;
   }

js/src/tests/run_trees.int.test.ts

@@ -46,7 +46,11 @@ test.concurrent(
     expect(child_llm_run.dotted_order).toEqual(
       parent_run.dotted_order +
         "." +
-        convertToDottedOrderFormat(child_llm_run.start_time, child_llm_run.id)
+        convertToDottedOrderFormat(
+          child_llm_run.start_time,
+          child_llm_run.id,
+          2
+        )
     );
     expect(child_llm_run.trace_id).toEqual(parent_run.trace_id);
     await child_llm_run.postRun();

js/src/tests/run_trees.test.ts

@@ -3,6 +3,10 @@
 import { jest } from "@jest/globals";
 import { Client } from "../client.js";
 import { RunTree } from "../run_trees.js";
+import { mockClient } from "./utils/mock_client.js";
+
+const _DATE = 1620000000000;
+Date.now = jest.fn(() => _DATE);
 
 test("Should work with manually set API key", async () => {
   const key = process.env.LANGCHAIN_API_KEY;
@@ -34,3 +38,32 @@ test("Should work with manually set API key", async () => {
     process.env.LANGCHAIN_API_KEY = key;
   }
 }, 180_000);
+
+test("nested", () => {
+  const id = "00000000-0000-0000-0000-00000000000";
+  const date = "20210503T00000000000";
+
+  const parent = new RunTree({ name: "parent_1", id: `${id}0` });
+  const child1 = parent.createChild({ name: "child_1", id: `${id}1` });
+  const child2 = parent.createChild({ name: "child_2", id: `${id}2` });
+  const grandchild1 = child1.createChild({
+    name: "grandchild_1",
+    id: `${id}3`,
+  });
+  const grandchild2 = child1.createChild({
+    name: "grandchild_2",
+    id: `${id}4`,
+  });
+  const child3 = parent.createChild({ name: "child_3", id: `${id}5` });
+
+  expect(parent.dotted_order).toBe(`${date}1Z${id}0`);
+  expect(child1.dotted_order).toBe(`${date}1Z${id}0.${date}2Z${id}1`);
+  expect(child2.dotted_order).toBe(`${date}1Z${id}0.${date}3Z${id}2`);
+  expect(grandchild1.dotted_order).toBe(
+    `${date}1Z${id}0.${date}2Z${id}1.${date}3Z${id}3`
+  );
+  expect(grandchild2.dotted_order).toBe(
+    `${date}1Z${id}0.${date}2Z${id}1.${date}4Z${id}4`
+  );
+  expect(child3.dotted_order).toBe(`${date}1Z${id}0.${date}5Z${id}5`);
+});