Merge pull request #5 from codemix/map-filter-chaining

Add FilterPredicateStep and related methods to ValueTraversal

Author: phpnode

.changeset/value-traversal-map-filter.md

@@ -0,0 +1,5 @@
+---
+"@codemix/graph": minor
+---
+
+Add support for `.map()` and `.filter()` on `ValueTraversal`, so value pipelines can transform and filter extracted values after steps like `values()` and `unfold()`.

README.md

@@ -10,11 +10,11 @@ This is the knowledge graph database for the [codemix](https://codemix.com/) pro
 
 ## Packages
 
-| Package                                                  | Version | Description                                                                                 |
-| -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
-| [`@codemix/graph`](./packages/graph)                     | 0.0.1   | Core graph database: Cypher queries + type-safe Gremlin-style traversals (`GraphTraversal`) |
-| [`@codemix/text-search`](./packages/text-search)         | 0.0.1   | BM25-based full-text search with English stemming                                           |
-| [`@codemix/y-graph-storage`](./packages/y-graph-storage) | 0.0.1   | [Yjs](https://yjs.dev/) CRDT storage adapter for collaborative/offline-first use            |
+| Package                                                  | Description                                                                                 |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [`@codemix/graph`](./packages/graph)                     | Core graph database: Cypher queries + type-safe Gremlin-style traversals (`GraphTraversal`) |
+| [`@codemix/text-search`](./packages/text-search)         | BM25-based full-text search with English stemming                                           |
+| [`@codemix/y-graph-storage`](./packages/y-graph-storage) | [Yjs](https://yjs.dev/) CRDT storage adapter for collaborative/offline-first use            |
 
 ---
 

packages/graph/src/Steps.ts

@@ -2876,6 +2876,46 @@ export class MapElementsStep<TInput> extends Step<MapElementsStepConfig<TInput>>
   }
 }
 
+export interface FilterPredicateStepConfig<TInput> extends StepConfig {
+  /**
+   * The predicate used to decide whether to keep each element.
+   */
+  predicate: (value: TInput) => boolean;
+}
+
+export class FilterPredicateStep<TInput> extends Step<FilterPredicateStepConfig<TInput>> {
+  public get name() {
+    return "FilterPredicate";
+  }
+
+  public *traverse(
+    _source: GraphSource<any>,
+    input: Iterable<TInput>,
+    _context?: QueryContext,
+  ): IterableIterator<unknown> {
+    const { predicate } = this.config;
+    for (const value of input) {
+      this.traversed++;
+      if (predicate(value as TInput)) {
+        this.emitted++;
+        yield value;
+      }
+    }
+  }
+
+  public override clone(partial?: Partial<FilterPredicateStepConfig<TInput>>) {
+    const { config } = this;
+    return new FilterPredicateStep({
+      predicate: partial?.predicate ?? config.predicate,
+      stepLabels: partial?.stepLabels ?? (config.stepLabels ? [...config.stepLabels] : undefined),
+    });
+  }
+
+  public override toJSON(): [string, FilterPredicateStepConfig<TInput>, unknown?] {
+    throw new Error("Cannot convert FilterPredicateStep to JSON.");
+  }
+}
+
 export interface GroupByStepConfig extends StepConfig {
   /**
    * The items to group by (variable, property, function like labels/type).
@@ -7360,6 +7400,7 @@ const KnownSteps = {
   Unwind: UnwindStep,
   Call: CallStep,
   MapElements: MapElementsStep,
+  FilterPredicate: FilterPredicateStep,
   Range: RangeStep,
   Order: OrderStep,
   FilterElements: FilterElementsStep,
@@ -7394,6 +7435,7 @@ export type KnownSteps =
   | RepeatStep<any>
   | DedupStep
   | MapElementsStep<any>
+  | FilterPredicateStep<any>
   | RangeStep
   | OrderStep
   | SumStep

packages/graph/src/Traversals.ts

@@ -18,6 +18,7 @@ import {
   FetchEdgesStep,
   FetchVerticesStep,
   FilterElementsStep,
+  FilterPredicateStep,
   IntersectStep,
   MapElementsStep,
   OrderDirection,
@@ -1105,6 +1106,32 @@ export class ValueTraversal<const TSchema extends GraphSchema, const TValue> ext
   TSchema,
   TValue
 > {
+  /**
+   * Map each value in the traversal to a new value.
+   * @param mapper A function that maps the current value to a new value.
+   */
+  public map<const TNextValue>(mapper: (value: TValue) => TNextValue) {
+    return new ValueTraversal<TSchema, TNextValue>(this.graph, [
+      ...this.steps,
+      new MapElementsStep<TValue>({
+        mapper,
+      }),
+    ]);
+  }
+
+  /**
+   * Filter the values in the traversal using a predicate.
+   * @param predicate A function that returns true for values to keep.
+   */
+  public filter(predicate: (value: TValue) => boolean) {
+    return new ValueTraversal<TSchema, TValue>(this.graph, [
+      ...this.steps,
+      new FilterPredicateStep<TValue>({
+        predicate,
+      }),
+    ]);
+  }
+
   /**
    * Unfold each value in the traversal.
    */

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

@@ -55,6 +55,36 @@ test("ValueTraversal Operations - values() extraction - values() after map extra
   expect(names.includes("Alice")).toBe(true);
 });
 
+test("ValueTraversal Operations - map() operation - map() after values() transforms extracted vertices", () => {
+  const names = Array.from(
+    g
+      .V()
+      .hasLabel("Person")
+      .limit(3)
+      .values()
+      .map((vertex) => vertex.get("name"))
+      .order()
+      .by(),
+  );
+
+  expect(names).toEqual(["Alice", "Bob", "Charlie"]);
+});
+
+test("ValueTraversal Operations - filter() operation - filter() after values() keeps matching vertices", () => {
+  const names = Array.from(
+    g
+      .V()
+      .hasLabel("Person")
+      .values()
+      .filter((vertex) => vertex.get("age") >= 50)
+      .map((vertex) => vertex.get("name"))
+      .order()
+      .by(),
+  );
+
+  expect(names).toEqual(["Fiona", "George"]);
+});
+
 test("ValueTraversal Operations - order() operation - order().by() sorts primitive values", () => {
   const names = Array.from(
     g
@@ -243,10 +273,12 @@ test("ValueTraversal Operations - unfold() operation - unfold() with subsequent
       .V(alice.id)
       .map(() => [10, 20, 30, 40])
       .unfold()
+      .filter((value) => value >= 20)
+      .map((value) => value / 10)
       .values(),
   );
 
-  expect(results).toEqual([10, 20, 30, 40]);
+  expect(results).toEqual([2, 3, 4]);
 });
 
 test("ValueTraversal Operations - Combined values() and unfold() operations - Select multiple labels, unfold, and extract values", () => {