Add property and properties methods to ValueTraversal for enhanced value selection

- Introduced property() method to select a single property from graph elements and plain objects.
- Added properties() method to select multiple properties, supporting both graph elements and plain objects.
- Implemented tests to validate the functionality of the new methods, ensuring correct extraction of properties from elements and objects.

Author: phpnode

packages/graph/src/Traversals.ts

@@ -1196,6 +1196,93 @@ export class ValueTraversal<const TSchema extends GraphSchema, const TValue> ext
     ]);
   }
 
+  /**
+   * Select a single property of the values in the traversal.
+   * Supports both graph elements and plain object values.
+   * @param propertyName The name of the property to select.
+   */
+  public property<const TPropertyName extends keyof GetValueTraversalProperties<TValue>>(
+    propertyName: TPropertyName,
+  ) {
+    return new ValueTraversal<TSchema, GetValueTraversalProperties<TValue>[TPropertyName]>(
+      this.graph,
+      [
+        ...this.steps,
+        new MapElementsStep<TValue>({
+          mapper: (value) => {
+            if (value instanceof Element) {
+              return value.get(propertyName as never);
+            }
+            if (typeof value === "object" && value !== null) {
+              return value[propertyName as keyof typeof value];
+            }
+            return undefined as GetValueTraversalProperties<TValue>[TPropertyName];
+          },
+        }),
+      ],
+    );
+  }
+
+  /**
+   * Select specific properties of the values in the traversal.
+   * Supports both graph elements and plain object values.
+   * @param propertyNames The names of the properties to select.
+   */
+  public properties(): ValueTraversal<TSchema, GetValueTraversalProperties<TValue>>;
+  public properties<
+    const TPropertyNames extends readonly (keyof GetValueTraversalProperties<TValue>)[],
+  >(
+    ...propertyNames: TPropertyNames
+  ): ValueTraversal<TSchema, Pick<GetValueTraversalProperties<TValue>, TPropertyNames[number]>>;
+  public properties<
+    const TPropertyNames extends readonly (keyof GetValueTraversalProperties<TValue>)[],
+  >(...propertyNames: TPropertyNames): ValueTraversal<TSchema, any> {
+    return new ValueTraversal<
+      TSchema,
+      Pick<GetValueTraversalProperties<TValue>, TPropertyNames[number]>
+    >(this.graph, [
+      ...this.steps,
+      new MapElementsStep<TValue>({
+        mapper: (value) => {
+          if (value instanceof Element) {
+            const storedProps = value[$StoredElement].properties;
+            if (propertyNames.length === 0) {
+              return storedProps as Pick<
+                GetValueTraversalProperties<TValue>,
+                TPropertyNames[number]
+              >;
+            }
+            const properties = {} as Pick<
+              GetValueTraversalProperties<TValue>,
+              TPropertyNames[number]
+            >;
+            for (const propertyName of propertyNames) {
+              properties[propertyName] = value.get(propertyName as never);
+            }
+            return properties;
+          }
+          if (typeof value === "object" && value !== null) {
+            if (propertyNames.length === 0) {
+              return value as Pick<GetValueTraversalProperties<TValue>, TPropertyNames[number]>;
+            }
+            const properties = {} as Pick<
+              GetValueTraversalProperties<TValue>,
+              TPropertyNames[number]
+            >;
+            for (const propertyName of propertyNames) {
+              properties[propertyName] = value[propertyName as keyof typeof value] as Pick<
+                GetValueTraversalProperties<TValue>,
+                TPropertyNames[number]
+              >[typeof propertyName];
+            }
+            return properties;
+          }
+          return {} as Pick<GetValueTraversalProperties<TValue>, TPropertyNames[number]>;
+        },
+      }),
+    ]);
+  }
+
   /**
    * Order the values in the traversal.
    */

packages/graph/src/test/ValueTraversal.test.ts

@@ -194,6 +194,61 @@ test("ValueTraversal Operations - order() operation - order().by(property) sorts
   expect(keys).toEqual([...keys].sort());
 });
 
+test("ValueTraversal Operations - property() operation - property() after values() extracts element properties", () => {
+  const names = Array.from(
+    g
+      .V()
+      .hasLabel("Person")
+      .order()
+      .by("name")
+      .values()
+      .property("name"),
+  );
+
+  expect(names).toEqual(["Alice", "Bob", "Charlie", "Dave", "Erin", "Fiona", "George"]);
+});
+
+test("ValueTraversal Operations - property() operation - property() extracts object properties", () => {
+  const names = Array.from(
+    g
+      .V(alice.id)
+      .map((path) => ({
+        name: path.value.get("name"),
+        age: path.value.get("age"),
+      }))
+      .property("name"),
+  );
+
+  expect(names).toEqual(["Alice"]);
+});
+
+test("ValueTraversal Operations - properties() operation - properties() after values() extracts all element properties", () => {
+  const results = Array.from(g.V(alice.id).values().properties());
+
+  expect(results).toHaveLength(1);
+  expect(results[0]).toMatchObject({ name: "Alice", age: 30 });
+});
+
+test("ValueTraversal Operations - properties() operation - properties() extracts selected object properties", () => {
+  const results = Array.from(
+    g
+      .V()
+      .hasLabel("Person")
+      .limit(2)
+      .map((path) => ({
+        bucket: path.value.get("age") >= 30 ? "older" : "younger",
+        name: path.value.get("name"),
+        age: path.value.get("age"),
+      }))
+      .properties("bucket", "name"),
+  );
+
+  expect(results).toEqual([
+    { bucket: "older", name: "Alice" },
+    { bucket: "younger", name: "Bob" },
+  ]);
+});
+
 test("ValueTraversal Operations - values() extraction - values() on edge traversal", () => {
   const edges = Array.from(g.E().values());