Enhance TraversalPath with new helper methods and improve ORDER BY support

- Added `nodes()`, `relationships()`, `length()`, and `sum()` methods to `TraversalPath` for better path manipulation.
- Improved runtime support for `ORDER BY` expressions, allowing references to projected aliases before `RETURN`/`WITH`.
- Updated tests to validate the new functionalities and ensure correct behavior in various scenarios.

Author: phpnode

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

packages/graph/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Minor Changes
 
+- Improve path ergonomics with `TraversalPath.nodes()`, `relationships()`, `length()`, and `sum()`, and add runtime support for `ORDER BY` expressions that reference projected aliases before `RETURN`/`WITH`.
 - 848690d: Add support for `.map()` and `.filter()` on `ValueTraversal`, so value pipelines can transform and filter extracted values after steps like `values()` and `unfold()`.
 
 ## 0.0.2

packages/graph/README.md

@@ -404,13 +404,7 @@ g.V()
 ### Shortest Path
 
 ```ts
-g.V()
-  .hasLabel("Person")
-  .shortestPath(
-    (t) => t.out("knows"), // expansion
-    targetVertex, // destination vertex or id
-    { maxDepth: 10 },
-  );
+g.V(alice.id).shortestPath().to(george.id).through("knows").direction("out");
 ```
 
 ### Union and Intersection

packages/graph/src/Steps.ts

@@ -3931,6 +3931,7 @@ export interface OrderStepConfig extends StepConfig {
    */
   directions: readonly {
     key?: string;
+    expression?: ConditionValue;
     direction: OrderDirection;
     nulls?: NullsOrdering;
   }[];
@@ -3944,13 +3945,13 @@ export class OrderStep extends Step<OrderStepConfig> {
   public *traverse(
     source: GraphSource<any>,
     input: Iterable<unknown>,
-    _context?: QueryContext,
+    context?: QueryContext,
   ): IterableIterator<unknown> {
     const { directions } = this.config;
     const sorted = [...input].sort((a, b) => {
-      for (const { key, direction, nulls } of directions) {
-        const aValue = resolveOrderValue(a, key);
-        const bValue = resolveOrderValue(b, key);
+      for (const { key, expression, direction, nulls } of directions) {
+        const aValue = resolveOrderValue(a, key, expression, context);
+        const bValue = resolveOrderValue(b, key, expression, context);
 
         // Handle null values according to nulls ordering
         const aIsNull = aValue === null || aValue === undefined;
@@ -3991,7 +3992,19 @@ export class OrderStep extends Step<OrderStepConfig> {
   }
 }
 
-function resolveOrderValue(item: unknown, key: string | undefined): unknown {
+function resolveOrderValue(
+  item: unknown,
+  key: string | undefined,
+  expression?: ConditionValue,
+  context?: QueryContext,
+): unknown {
+  if (expression !== undefined) {
+    if (item instanceof TraversalPath) {
+      return resolveConditionValue(item, expression, context);
+    }
+    return undefined;
+  }
+
   if (key === undefined) {
     return item instanceof TraversalPath ? item.value : item;
   }
@@ -6639,7 +6652,8 @@ export interface WithStepConfig extends StepConfig {
    * Optional ORDER BY within the WITH clause.
    */
   orderBy?: readonly {
-    key: string;
+    key?: string;
+    expression?: ConditionValue;
     direction: OrderDirection;
     nulls?: NullsOrdering;
   }[];
@@ -6791,13 +6805,15 @@ export class WithStep extends Step<WithStepConfig> {
     // Apply ORDER BY if present
     if (orderBy && orderBy.length > 0) {
       results.sort((a, b) => {
-        for (const { key, direction, nulls } of orderBy) {
-          // First try to get the value as a bound variable (for aliases like `WITH a.num AS val`)
-          // then fall back to property access (for expressions like `ORDER BY a.num`)
-          const aNode = a.get(key);
-          const bNode = b.get(key);
-          const aValue = aNode !== undefined ? aNode.value : a.property(key as never);
-          const bValue = bNode !== undefined ? bNode.value : b.property(key as never);
+        for (const { key, expression, direction, nulls } of orderBy) {
+          const aValue =
+            expression !== undefined
+              ? resolveConditionValue(a, expression, context)
+              : resolveProjectedOrderValue(a, key);
+          const bValue =
+            expression !== undefined
+              ? resolveConditionValue(b, expression, context)
+              : resolveProjectedOrderValue(b, key);
 
           const aIsNull = aValue === null || aValue === undefined;
           const bIsNull = bValue === null || bValue === undefined;
@@ -7088,6 +7104,20 @@ export class WithStep extends Step<WithStepConfig> {
   }
 }
 
+function resolveProjectedOrderValue(
+  path: TraversalPath<any, any, any>,
+  key: string | undefined,
+): unknown {
+  if (key === undefined) {
+    return path.value;
+  }
+
+  // First try to get the value as a bound variable (for aliases like `WITH a.num AS val`)
+  // then fall back to property access (for expressions like `ORDER BY a.num`)
+  const pathNode = path.get(key);
+  return pathNode !== undefined ? pathNode.value : path.property(key as never);
+}
+
 /**
  * Expression type for UNWIND - can be a literal list, null, property access, variable reference, parameter, function call, or general expression.
  */

packages/graph/src/Traversals.ts

@@ -6,6 +6,7 @@ import {
   VertexProperties,
   EdgeProperties,
   AnyEdgePropertyName,
+  AnyVertexPropertyName,
 } from "./GraphSchema.js";
 import { ElementId } from "./GraphStorage.js";
 import {
@@ -108,7 +109,11 @@ export class TraversalPath<
   public with<const TValue, const TLabels extends readonly string[] = []>(
     value: TValue,
     labels: TLabels = [] as unknown as TLabels,
-  ): this extends TraversalPath<any, unknown, any> ? TraversalPath<this, TValue, TLabels> : never {
+  ): this extends TraversalPath<any, unknown, any>
+    ? TLabels extends readonly []
+      ? this
+      : TraversalPath<this, TValue, TLabels>
+    : this {
     return new TraversalPath(this as any, value, labels) as any;
   }
 
@@ -129,20 +134,96 @@ export class TraversalPath<
     return undefined as PropertyOf<TValue>[TPropertyName];
   }
 
+  /**
+   * Return the vertices in this path, in traversal order.
+   * Optionally extract a property from each vertex instead of returning the vertices themselves.
+   */
+  public nodes(): GetTraversalPathVertices<TraversalPath<TParent, TValue, TLabels>>;
+  public nodes<
+    const TPropertyName extends AnyVertexPropertyNameOrString<
+      GetTraversalPathSchema<TraversalPath<TParent, TValue, TLabels>>
+    >,
+  >(
+    propertyName: TPropertyName,
+  ): GetTraversalPathVertexPropertyValues<TraversalPath<TParent, TValue, TLabels>, TPropertyName>;
+  public nodes(propertyName?: string) {
+    const nodes: unknown[] = [];
+    for (const step of this) {
+      if (!(step.value instanceof Vertex)) {
+        continue;
+      }
+      nodes.push(propertyName ? step.property(propertyName as never) : step.value);
+    }
+    return nodes;
+  }
+
+  /**
+   * Return the edges/relationships in this path, in traversal order.
+   * Optionally extract a property from each edge instead of returning the edges themselves.
+   */
+  public relationships(): GetTraversalPathEdges<TraversalPath<TParent, TValue, TLabels>>;
+  public relationships<
+    const TPropertyName extends AnyEdgePropertyNameOrString<
+      GetTraversalPathSchema<TraversalPath<TParent, TValue, TLabels>>
+    >,
+  >(
+    propertyName: TPropertyName,
+  ): GetTraversalPathEdgePropertyValues<TraversalPath<TParent, TValue, TLabels>, TPropertyName>;
+  public relationships(propertyName?: string) {
+    const relationships: unknown[] = [];
+    for (const step of this) {
+      if (!(step.value instanceof Edge)) {
+        continue;
+      }
+      relationships.push(propertyName ? step.property(propertyName as never) : step.value);
+    }
+    return relationships;
+  }
+
+  /**
+   * Return the number of edges/relationships in this path.
+   * Mirrors Cypher's `length(path)`.
+   */
+  public length(): number {
+    let edgeCount = 0;
+    for (const step of this) {
+      if (step.value instanceof Edge) {
+        edgeCount++;
+      }
+    }
+    return edgeCount;
+  }
+
+  /**
+   * Sum a numeric property across all items in the path.
+   * Non-numeric or missing values are ignored.
+   */
+  public sum(propertyName: string): number {
+    let total = 0;
+    for (const step of this) {
+      const value = step.property(propertyName as never);
+      if (typeof value === "number") {
+        total += value;
+      }
+    }
+    return total;
+  }
+
   /**
    * Get a node in the path by label.
    * @param label The label to get the node by.
    */
-  public get<const TLabel extends string>(label: TLabel): GetTraversalPathByLabel<this, TLabel> {
-    // eslint-disable-next-line @typescript-eslint/no-this-alias
-    let node: TraversalPath<any, unknown, any> = this;
+  public get<const TLabel extends string>(
+    label: TLabel,
+  ): GetTraversalPathByLabel<TraversalPath<TParent, TValue, TLabels>, TLabel> {
+    let node: TraversalPath<any, any, any> = this;
     while (node !== undefined) {
       if (node.labels.includes(label)) {
-        return node as GetTraversalPathByLabel<this, TLabel>;
+        return node as GetTraversalPathByLabel<TraversalPath<TParent, TValue, TLabels>, TLabel>;
       }
       node = node.parent;
     }
-    return undefined as GetTraversalPathByLabel<this, TLabel>;
+    return undefined as GetTraversalPathByLabel<TraversalPath<TParent, TValue, TLabels>, TLabel>;
   }
 
   /**
@@ -151,17 +232,16 @@ export class TraversalPath<
    */
   public getAll<const TLabel extends string>(
     label: TLabel,
-  ): GetAllTraversalPathsByLabel<this, TLabel> {
-    const nodes = [] as TraversalPath<any, unknown, any>[];
-    // eslint-disable-next-line @typescript-eslint/no-this-alias
-    let node: TraversalPath<any, unknown, any> = this;
+  ): GetAllTraversalPathsByLabel<TraversalPath<TParent, TValue, TLabels>, TLabel> {
+    const nodes = [] as TraversalPath<any, any, any>[];
+    let node: TraversalPath<any, any, any> = this;
     while (node !== undefined) {
       if (node.labels.includes(label)) {
         nodes.unshift(node);
       }
       node = node.parent;
     }
-    return nodes as GetAllTraversalPathsByLabel<this, TLabel>;
+    return nodes as GetAllTraversalPathsByLabel<TraversalPath<TParent, TValue, TLabels>, TLabel>;
   }
 
   public toJSON(): TraversalPathJSON {
@@ -224,6 +304,62 @@ export class TraversalPath<
 
 type PropertyOf<T> = T extends Element<any, any, infer TProperties, any> ? TProperties : keyof T;
 
+type GetTraversalPathItems<TPath> =
+  TPath extends TraversalPath<infer TParent, infer TValue, any>
+    ? [...GetTraversalPathItems<TParent>, TValue]
+    : [];
+
+type GetTraversalPathSchema<TPath> =
+  Extract<GetTraversalPathItems<TPath>[number], Element<any, any, any, any>> extends Element<
+    infer TSchema,
+    any,
+    any,
+    any
+  >
+    ? TSchema
+    : GraphSchema;
+
+type AnyVertexPropertyNameOrString<TSchema extends GraphSchema> =
+  AnyVertexPropertyName<TSchema> extends never ? string : AnyVertexPropertyName<TSchema>;
+
+type AnyEdgePropertyNameOrString<TSchema extends GraphSchema> =
+  AnyEdgePropertyName<TSchema> extends never ? string : AnyEdgePropertyName<TSchema>;
+
+type AnyVertexPropertyValue<TSchema extends GraphSchema, TPropertyName extends string> = {
+  [TVertexLabel in VertexLabel<TSchema>]: TPropertyName extends keyof VertexProperties<
+    TSchema,
+    TVertexLabel
+  >
+    ? VertexProperties<TSchema, TVertexLabel>[TPropertyName]
+    : never;
+}[VertexLabel<TSchema>];
+
+type AnyEdgePropertyValue<TSchema extends GraphSchema, TPropertyName extends string> = {
+  [TEdgeLabel in EdgeLabel<TSchema>]: TPropertyName extends keyof EdgeProperties<
+    TSchema,
+    TEdgeLabel
+  >
+    ? EdgeProperties<TSchema, TEdgeLabel>[TPropertyName]
+    : never;
+}[EdgeLabel<TSchema>];
+
+type GetTraversalPathVertices<TPath> = Extract<
+  GetTraversalPathItems<TPath>[number],
+  Vertex<any, any>
+>[];
+
+type GetTraversalPathEdges<TPath> = Extract<GetTraversalPathItems<TPath>[number], Edge<any, any>>[];
+
+type GetTraversalPathVertexPropertyValues<
+  TPath,
+  TPropertyName extends string,
+> = AnyVertexPropertyValue<GetTraversalPathSchema<TPath>, TPropertyName>[];
+
+type GetTraversalPathEdgePropertyValues<TPath, TPropertyName extends string> = AnyEdgePropertyValue<
+  GetTraversalPathSchema<TPath>,
+  TPropertyName
+>[];
+
 type GetTraversalPathValue<TPath> =
   TPath extends TraversalPath<any, infer TValue, any>
     ? TValue