grafio-mongo 1.2.0 → 3.0.0

package/README.md

@@ -17,10 +17,7 @@ This package provides the MongoDB storage provider for grafio, extracted from th
 ## Installation
 
 ```bash
-npm install grafio-mongo mongodb
-
-# peer dependencies
-npm install grafio
+npm install grafio-mongo
 ```
 
 ## Quick Start
@@ -155,6 +152,213 @@ try {
 - `isFailed()` — returns true if a storage operation failed within the transaction
 - `isActive()` — returns true if transaction is active and not failed
 
+## Cypher Query Language
+
+MongoDB-backed graphs support read-only openCypher-compatible queries via the `CypherEngine`:
+
+```typescript
+import { Graph } from 'grafio';
+import { CypherEngine } from 'grafio/cypher';
+
+const graph = factory.forGraph('my-graph');
+
+// Build your graph
+const alice = await graph.addNode('Person', { name: 'Alice', age: 30 });
+const bob   = await graph.addNode('Person', { name: 'Bob', age: 25 });
+await graph.addEdge(alice.id, bob.id, 'KNOWS', { since: 2020 });
+
+const engine = new CypherEngine(graph);
+
+// Scan nodes by type
+const result = await engine.query('MATCH (p:Person) RETURN p.name, p.age');
+
+// Filter with WHERE
+const adults = await engine.query(
+  'MATCH (p:Person) WHERE p.age > 25 RETURN p.name'
+);
+
+// Follow relationships
+const friends = await engine.query(
+  'MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name'
+);
+
+// Multi-hop traversal
+const network = await engine.query(
+  'MATCH (a:Person)-[:KNOWS*1..2]->(b:Person) RETURN DISTINCT a.name, b.name'
+);
+
+// Parameterized queries
+const byName = await engine.query(
+  'MATCH (p:Person {name: $name}) RETURN p',
+  { name: 'Alice' }
+);
+
+// Pagination
+const page = await engine.query(
+  'MATCH (p:Person) RETURN p ORDER BY p.age DESC SKIP 0 LIMIT 10'
+);
+```
+
+### Supported Clauses
+
+| Clause | Support | Notes |
+|--------|---------|-------|
+| `MATCH` | ✅ Read-only patterns | Typed/untyped nodes, directed edges, multi-label `(n:A\|B)`, inline property maps |
+| `WHERE` | ✅ Full expressions | `AND`/`OR`/`NOT`, comparisons, `IN`, `NOT IN`, `IS NULL`, `IS NOT NULL` |
+| `RETURN` | ✅ With `DISTINCT` | Property access, aliases with `AS` |
+| `ORDER BY` | ✅ ASC/DESC | Default ASC when omitted |
+| `SKIP` | ✅ Literal + `$param` | Evaluated at runtime |
+| `LIMIT` | ✅ Literal + `$param` | Evaluated at runtime |
+| `CREATE` / `DELETE` / `SET` / `REMOVE` / `MERGE` | ❌ Rejected | Validation gate prevents execution |
+
+#### Aggregation Functions
+
+```typescript
+// Basic count
+const total = await engine.query('MATCH (p:Person) RETURN COUNT(p) AS total');
+
+// Group by with aggregation
+const byCity = await engine.query(
+  'MATCH (p:Person) RETURN p.city, COUNT(*) AS cnt ORDER BY cnt DESC'
+);
+
+// HAVING clause
+const popular = await engine.query(
+  'MATCH (p:Person) RETURN p.city, COUNT(*) AS cnt HAVING cnt > 1'
+);
+
+// Multiple aggregates
+const stats = await engine.query(
+  'MATCH (p:Person) RETURN MIN(p.age), MAX(p.age), AVG(p.age)'
+);
+
+// Named path variable
+const paths = await engine.query(
+  'MATCH p = (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person) RETURN p'
+);
+```
+
+#### Query Plan — Inspect Execution Steps
+
+Use `getQueryPlan()` to inspect the logical execution plan for a query without running it:
+
+```typescript
+// Get query plan in JSON format (default)
+const planJson = await engine.getQueryPlan('MATCH (p:Person) RETURN p.name');
+// Returns: { plan: { steps: [...] } }
+
+// Get in Text tree format
+const planText = await engine.getQueryPlan('MATCH (p:Person)-[:KNOWS]->(b) RETURN p.name, b.name', undefined, 'text');
+/*
+NodeScanStep (Person)
+  EdgeExpandStep (KNOWS, outgoing)
+    ProjectStep [p.name, b.name]
+*/
+
+// Get in Mermaid flowchart format
+const planMermaid = await engine.getQueryPlan('MATCH (p:Person)-[:KNOWS*1..2]->(b) RETURN p.name', undefined, 'mermaid');
+/*
+flowchart TD
+    Step1[NodeScanStep Person]
+    Step2[EdgeExpandStep KNOWS, 1..2 hops, outgoing]
+    Step3[ProjectStep [p.name]]
+    Step1 --> Step2
+    Step2 --> Step3
+*/
+```
+
+#### Execution Plan — Query Plan with Runtime Statistics
+
+Use `execute()` with the `executionPlan` option to get the query plan enriched with per-step timing and row counts:
+
+```typescript
+const result = await engine.execute(
+  'MATCH (p:Person)-[:KNOWS]->(b:Person) RETURN p.name, b.name',
+  {},
+  { executionPlan: { format: 'json' } }
+);
+
+// result.executionPlan contains the formatted plan with stats
+// result.summary contains timing metadata
+// result.summary.planExecutionStats contains per-step timing data
+
+// Get execution plan in Text format with timing
+const execText = await engine.execute(
+  'MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person) RETURN a.name',
+  {},
+  { executionPlan: { format: 'text' } }
+);
+console.log(execText.executionPlan);
+/*
+NodeScanStep Person (1ms, 33.3%, 2 rows)
+  EdgeExpandStep KNOWS, outgoing (1ms, 33.3%, 5 rows)
+    EdgeExpandStep KNOWS, outgoing (1ms, 33.3%, 3 rows)
+      ProjectStep [a.name]
+*/
+```
+
+Supported formats: `'json'`, `'text'`, `'mermaid'`
+
+The execution plan includes:
+- **timeMs**: Time spent in each step
+- **percentageOfTotal**: Percentage of total query time
+- **rowsOut**: Number of rows output by each step
+
+### Variable-length Edge Syntax
+
+| Syntax | Meaning |
+|--------|---------|
+| `[*]` | Unbounded (up to 100 hops) |
+| `[*1..3]` | 1 to 3 hops (BFS by default) |
+| `[*2]` | Exactly 2 hops |
+| `[*..5]` | Up to 5 hops |
+
+> **Strategy selection**: BFS is used by default for multi-hop expansion. When `LIMIT` is present, DFS is selected automatically for better early-result performance.
+
+#### Property Filter Operators
+
+The `filter.properties` option supports various comparison operators:
+
+| Operator | Syntax | Description |
+|----------|--------|-------------|
+| `=` | `{ key: 'age', value: 30 }` | Equality (default) |
+| `<>` | `{ key: 'age', value: 30, op: '<>' }` | Not equal |
+| `>` | `{ key: 'age', value: 25, op: '>' }` | Greater than |
+| `<` | `{ key: 'age', value: 25, op: '<' }` | Less than |
+| `>=` | `{ key: 'age', value: 25, op: '>=' }` | Greater than or equal |
+| `<=` | `{ key: 'age', value: 25, op: '<=' }` | Less than or equal |
+| `CONTAINS` | `{ key: 'name', value: 'John', op: 'CONTAINS' }` | String contains |
+| `STARTS_WITH` | `{ key: 'name', value: 'J', op: 'STARTS_WITH' }` | String prefix |
+| `ENDS_WITH` | `{ key: 'name', value: 'n', op: 'ENDS_WITH' }` | String suffix |
+| `IN` | `{ key: 'city', value: ['NYC', 'LA'], op: 'IN' }` | In array |
+| `NOT_IN` | `{ key: 'city', value: ['SF', 'CHI'], op: 'NOT_IN' }` | Not in array |
+| `IS_NULL` | `{ key: 'age', op: 'IS_NULL' }` | Is null |
+| `IS_NOT_NULL` | `{ key: 'age', op: 'IS_NOT_NULL' }` | Is not null |
+
+**AND/OR Chaining:**
+
+```typescript
+// AND chaining
+const result = await graph.getNodes({
+  filter: {
+    AND: [
+      { key: 'age', value: 25, op: '>' },
+      { key: 'city', value: 'NYC' }
+    ]
+  }
+});
+
+// OR chaining
+const result = await graph.getNodes({
+  filter: {
+    OR: [
+      { key: 'city', value: 'NYC' },
+      { key: 'city', value: 'LA' }
+    ]
+  }
+});
+```
+
 ## Graph Operations
 
 All graph operations from grafio are available when using MongoDB storage. See the [grafio documentation](https://github.com/satyajugran/grafio) for the complete API reference.
@@ -179,8 +383,8 @@ const path = await graph.traverse(alice.id, bob.id, { method: 'bfs' });
 // Type filtering
 const allPersons = await graph.getNodesByType('Person');
 
-// Property queries
-const adults = await graph.getNodesByProperty('age', 30);
+// Property queries with operators
+const adults = await graph.getNodes({ filter: { properties: [{ key: 'age', value: 25, op: '>' }] } });
 
 // DAG check and topological sort
 const isDag = await graph.isDAG();

package/dist/MongoStorageProvider.d.ts

@@ -1,5 +1,12 @@
 import type { Db } from 'mongodb';
-import { IStorageProvider, IOrderBy, NodeData, ITransactionHandle, EdgeData, GraphData } from 'grafio';
+import { IStorageProvider, NodeData, ITransactionHandle, EdgeData, GraphData, StorageQueryOptions } from 'grafio';
+export interface QueryOptionsFilterProperty {
+    key?: string;
+    value?: unknown;
+    op?: '=' | '<>' | '>' | '<' | '>=' | '<=' | 'CONTAINS' | 'STARTS_WITH' | 'ENDS_WITH' | 'IN' | 'NOT_IN' | 'IS_NULL' | 'IS_NOT_NULL';
+    AND?: QueryOptionsFilterProperty[];
+    OR?: QueryOptionsFilterProperty[];
+}
 export interface MongoStorageProviderOptions {
     graphId?: string;
     nodesCollection?: string;
@@ -19,23 +26,34 @@ export declare class MongoStorageProvider implements IStorageProvider {
     deleteNode(id: string, transaction?: ITransactionHandle): Promise<void>;
     hasNode(id: string, transaction?: ITransactionHandle): Promise<boolean>;
     getNode(id: string, transaction?: ITransactionHandle): Promise<NodeData | undefined>;
-    getAllNodes(limit?: number, orderBy?: IOrderBy, transaction?: ITransactionHandle): Promise<NodeData[]>;
-    getNodesByType(type: string, transaction?: ITransactionHandle): Promise<NodeData[]>;
-    getNodesByProperty(key: string, value: unknown, nodeType?: string, transaction?: ITransactionHandle): Promise<NodeData[]>;
-    getTotalNodeCount(transaction?: ITransactionHandle): Promise<number>;
-    getEdgesByProperty(key: string, value: unknown, edgeType?: string, transaction?: ITransactionHandle): Promise<EdgeData[]>;
-    getTotalEdgeCount(transaction?: ITransactionHandle): Promise<number>;
-    insertEdge(edge: EdgeData, transaction?: ITransactionHandle): Promise<void>;
-    deleteEdge(id: string, transaction?: ITransactionHandle): Promise<void>;
+    getNodeCount(options?: StorageQueryOptions): Promise<number>;
+    aggregateNodeProperty(key: string, options?: StorageQueryOptions): Promise<{
+        count: number;
+        sum?: number;
+        avg?: number;
+        min?: number;
+        max?: number;
+    }>;
+    getNodes(options?: StorageQueryOptions): Promise<NodeData[]>;
     hasEdge(id: string, transaction?: ITransactionHandle): Promise<boolean>;
     getEdge(id: string, transaction?: ITransactionHandle): Promise<EdgeData | undefined>;
-    getAllEdges(limit?: number, orderBy?: IOrderBy, transaction?: ITransactionHandle): Promise<EdgeData[]>;
-    getEdgesByType(type: string, transaction?: ITransactionHandle): Promise<EdgeData[]>;
-    getEdgesBySource(nodeId: string, type?: string, transaction?: ITransactionHandle): Promise<EdgeData[]>;
-    getEdgesByTarget(nodeId: string, type?: string, transaction?: ITransactionHandle): Promise<EdgeData[]>;
+    getEdgeCount(options?: StorageQueryOptions): Promise<number>;
+    aggregateEdgeProperty(key: string, options?: StorageQueryOptions): Promise<{
+        count: number;
+        sum?: number;
+        avg?: number;
+        min?: number;
+        max?: number;
+    }>;
+    getEdges(options?: StorageQueryOptions): Promise<EdgeData[]>;
+    getEdgesBySource(nodeId: string, options?: StorageQueryOptions): Promise<EdgeData[]>;
+    getEdgesByTarget(nodeId: string, options?: StorageQueryOptions): Promise<EdgeData[]>;
+    insertEdge(edge: EdgeData, transaction?: ITransactionHandle): Promise<void>;
+    deleteEdge(id: string, transaction?: ITransactionHandle): Promise<void>;
     exportJSON(): Promise<GraphData>;
     importJSON(data: GraphData): Promise<void>;
-    createIndex(target: 'node' | 'edge', propertyKey: string, type?: string): Promise<void>;
+    createIndex(target: 'node' | 'edge', propertyKey: string): Promise<void>;
+    hasIndex(target: 'node' | 'edge', propertyKey: string): Promise<boolean>;
     addProperty(target: 'node' | 'edge', id: string, key: string, value: unknown, transaction?: ITransactionHandle): Promise<void>;
     updateProperty(target: 'node' | 'edge', id: string, key: string, value: unknown, transaction?: ITransactionHandle): Promise<void>;
     deleteProperty(target: 'node' | 'edge', id: string, key: string, transaction?: ITransactionHandle): Promise<void>;
@@ -44,6 +62,11 @@ export declare class MongoStorageProvider implements IStorageProvider {
     beginTransaction(): Promise<ITransactionHandle>;
     commitTransaction(handle: ITransactionHandle): Promise<void>;
     rollbackTransaction(handle: ITransactionHandle): Promise<void>;
+    private _buildNodeFilter;
+    private _buildEdgeFilter;
+    private _buildPropertyFilter;
+    private _buildSimplePropertyFilter;
+    private _escapeRegex;
     private _docToNode;
     private _docToEdge;
     private _isDuplicateKeyError;

package/dist/MongoStorageProvider.js

@@ -11,8 +11,8 @@ class MongoStorageProvider {
     _batchSize;
     _client = null;
     constructor(db, opts = {}) {
-        const nodesColl = opts.nodesCollection ?? 'sgdb_nodes';
-        const edgesColl = opts.edgesCollection ?? 'sgdb_edges';
+        const nodesColl = opts.nodesCollection ?? 'grafiodb_nodes';
+        const edgesColl = opts.edgesCollection ?? 'grafiodb_edges';
         this._nodes = db.collection(nodesColl);
         this._edges = db.collection(edgesColl);
         this._graphId = opts.graphId ?? 'default';
@@ -79,55 +79,169 @@ class MongoStorageProvider {
         const doc = await this._nodes.findOne({ graphId: this._graphId, id }, { session });
         return doc ? this._docToNode(doc) : undefined;
     }
-    async getAllNodes(limit, orderBy, transaction) {
-        const session = transaction?.context;
+    async getNodeCount(options) {
+        const session = options?.transaction?.context;
+        const filter = this._buildNodeFilter(options);
+        return this._nodes.countDocuments(filter, { session });
+    }
+    async aggregateNodeProperty(key, options) {
+        const session = options?.transaction?.context;
+        const matchFilter = this._buildNodeFilter(options);
+        const propFilter = { $exists: true, $type: 'number' };
+        if (matchFilter.$and) {
+            matchFilter.$and.push({ [`properties.${key}`]: propFilter });
+        }
+        else {
+            matchFilter[`properties.${key}`] = propFilter;
+        }
+        const pipeline = [
+            { $match: matchFilter },
+            {
+                $group: {
+                    _id: null,
+                    count: { $sum: 1 },
+                    sum: { $sum: `$properties.${key}` },
+                    avg: { $avg: `$properties.${key}` },
+                    min: { $min: `$properties.${key}` },
+                    max: { $max: `$properties.${key}` },
+                },
+            },
+        ];
+        const result = await this._nodes.aggregate(pipeline, { session }).next();
+        if (!result) {
+            return { count: 0 };
+        }
+        return {
+            count: result.count,
+            sum: result.sum,
+            avg: result.avg,
+            min: result.min,
+            max: result.max,
+        };
+    }
+    async getNodes(options) {
+        const session = options?.transaction?.context;
+        const filter = this._buildNodeFilter(options);
         const nodes = [];
-        const cursor = this._nodes.find({ graphId: this._graphId }, { session }).batchSize(this._batchSize);
-        if (orderBy)
-            cursor.sort(orderBy.field, orderBy.direction);
-        if (limit)
-            cursor.limit(limit);
+        const cursor = this._nodes.find(filter, { session }).batchSize(this._batchSize);
+        if (options?.orderBy) {
+            const { field, direction } = options.orderBy;
+            const sortField = field === 'createdOn' || field === 'updatedOn' ? field : `properties.${field}`;
+            cursor.sort(sortField, direction);
+        }
+        if (options?.limit) {
+            cursor.limit(options.limit);
+        }
         for await (const doc of cursor) {
             nodes.push(this._docToNode(doc));
         }
         return nodes;
     }
-    async getNodesByType(type, transaction) {
+    async hasEdge(id, transaction) {
         const session = transaction?.context;
-        const docs = await this._nodes.find({ graphId: this._graphId, type }, { session }).toArray();
-        return docs.map(d => this._docToNode(d));
+        const doc = await this._edges.findOne({ graphId: this._graphId, id }, { projection: { _id: 1 }, session });
+        return doc !== null;
     }
-    async getNodesByProperty(key, value, nodeType, transaction) {
+    async getEdge(id, transaction) {
         const session = transaction?.context;
-        const filter = {
-            graphId: this._graphId,
-            [`properties.${key}`]: value,
-        };
-        if (nodeType !== undefined) {
-            filter.type = nodeType;
-        }
-        const docs = await this._nodes.find(filter, { session }).toArray();
-        return docs.map(d => this._docToNode(d));
+        const doc = await this._edges.findOne({ graphId: this._graphId, id }, { session });
+        return doc ? this._docToEdge(doc) : undefined;
     }
-    async getTotalNodeCount(transaction) {
-        const session = transaction?.context;
-        return this._nodes.countDocuments({ graphId: this._graphId }, { session });
+    async getEdgeCount(options) {
+        const session = options?.transaction?.context;
+        const filter = this._buildEdgeFilter(options);
+        return this._edges.countDocuments(filter, { session });
     }
-    async getEdgesByProperty(key, value, edgeType, transaction) {
-        const session = transaction?.context;
-        const filter = {
-            graphId: this._graphId,
-            [`properties.${key}`]: value,
+    async aggregateEdgeProperty(key, options) {
+        const session = options?.transaction?.context;
+        const matchFilter = this._buildEdgeFilter(options);
+        const propFilter = { $exists: true, $type: 'number' };
+        if (matchFilter.$and) {
+            matchFilter.$and.push({ [`properties.${key}`]: propFilter });
+        }
+        else {
+            matchFilter[`properties.${key}`] = propFilter;
+        }
+        const pipeline = [
+            { $match: matchFilter },
+            {
+                $group: {
+                    _id: null,
+                    count: { $sum: 1 },
+                    sum: { $sum: `$properties.${key}` },
+                    avg: { $avg: `$properties.${key}` },
+                    min: { $min: `$properties.${key}` },
+                    max: { $max: `$properties.${key}` },
+                },
+            },
+        ];
+        const result = await this._edges.aggregate(pipeline, { session }).next();
+        if (!result) {
+            return { count: 0 };
+        }
+        return {
+            count: result.count,
+            sum: result.sum,
+            avg: result.avg,
+            min: result.min,
+            max: result.max,
         };
-        if (edgeType !== undefined) {
-            filter.type = edgeType;
+    }
+    async getEdges(options) {
+        const session = options?.transaction?.context;
+        const filter = this._buildEdgeFilter(options);
+        const edges = [];
+        const cursor = this._edges.find(filter, { session }).batchSize(this._batchSize);
+        if (options?.orderBy) {
+            const { field, direction } = options.orderBy;
+            const sortField = field === 'createdOn' || field === 'updatedOn' ? field : `properties.${field}`;
+            cursor.sort(sortField, direction);
+        }
+        if (options?.limit) {
+            cursor.limit(options.limit);
+        }
+        for await (const doc of cursor) {
+            edges.push(this._docToEdge(doc));
         }
-        const docs = await this._edges.find(filter, { session }).toArray();
-        return docs.map(d => this._docToEdge(d));
+        return edges;
     }
-    async getTotalEdgeCount(transaction) {
-        const session = transaction?.context;
-        return this._edges.countDocuments({ graphId: this._graphId }, { session });
+    async getEdgesBySource(nodeId, options) {
+        const session = options?.transaction?.context;
+        const baseFilter = { graphId: this._graphId, sourceId: nodeId };
+        const filter = this._buildEdgeFilter(options, baseFilter);
+        const edges = [];
+        const cursor = this._edges.find(filter, { session }).batchSize(this._batchSize);
+        if (options?.orderBy) {
+            const { field, direction } = options.orderBy;
+            const sortField = field === 'createdOn' || field === 'updatedOn' ? field : `properties.${field}`;
+            cursor.sort(sortField, direction);
+        }
+        if (options?.limit) {
+            cursor.limit(options.limit);
+        }
+        for await (const doc of cursor) {
+            edges.push(this._docToEdge(doc));
+        }
+        return edges;
+    }
+    async getEdgesByTarget(nodeId, options) {
+        const session = options?.transaction?.context;
+        const baseFilter = { graphId: this._graphId, targetId: nodeId };
+        const filter = this._buildEdgeFilter(options, baseFilter);
+        const edges = [];
+        const cursor = this._edges.find(filter, { session }).batchSize(this._batchSize);
+        if (options?.orderBy) {
+            const { field, direction } = options.orderBy;
+            const sortField = field === 'createdOn' || field === 'updatedOn' ? field : `properties.${field}`;
+            cursor.sort(sortField, direction);
+        }
+        if (options?.limit) {
+            cursor.limit(options.limit);
+        }
+        for await (const doc of cursor) {
+            edges.push(this._docToEdge(doc));
+        }
+        return edges;
     }
     async insertEdge(edge, transaction) {
         const now = Date.now();
@@ -160,50 +274,6 @@ class MongoStorageProvider {
         const session = transaction?.context;
         await this._edges.deleteOne({ graphId: this._graphId, id }, { session });
     }
-    async hasEdge(id, transaction) {
-        const session = transaction?.context;
-        const doc = await this._edges.findOne({ graphId: this._graphId, id }, { projection: { _id: 1 }, session });
-        return doc !== null;
-    }
-    async getEdge(id, transaction) {
-        const session = transaction?.context;
-        const doc = await this._edges.findOne({ graphId: this._graphId, id }, { session });
-        return doc ? this._docToEdge(doc) : undefined;
-    }
-    async getAllEdges(limit, orderBy, transaction) {
-        const session = transaction?.context;
-        const edges = [];
-        const cursor = this._edges.find({ graphId: this._graphId }, { session }).batchSize(this._batchSize);
-        if (orderBy)
-            cursor.sort(orderBy.field, orderBy.direction);
-        if (limit)
-            cursor.limit(limit);
-        for await (const doc of cursor) {
-            edges.push(this._docToEdge(doc));
-        }
-        return edges;
-    }
-    async getEdgesByType(type, transaction) {
-        const session = transaction?.context;
-        const docs = await this._edges.find({ graphId: this._graphId, type }, { session }).toArray();
-        return docs.map(d => this._docToEdge(d));
-    }
-    async getEdgesBySource(nodeId, type, transaction) {
-        const session = transaction?.context;
-        const filter = { graphId: this._graphId, sourceId: nodeId };
-        if (type)
-            filter.type = type;
-        const docs = await this._edges.find(filter, { session }).toArray();
-        return docs.map(d => this._docToEdge(d));
-    }
-    async getEdgesByTarget(nodeId, type, transaction) {
-        const session = transaction?.context;
-        const filter = { graphId: this._graphId, targetId: nodeId };
-        if (type)
-            filter.type = type;
-        const docs = await this._edges.find(filter, { session }).toArray();
-        return docs.map(d => this._docToEdge(d));
-    }
     async exportJSON() {
         const nodes = [];
         const edges = [];
@@ -294,39 +364,41 @@ class MongoStorageProvider {
             }
         }
     }
-    async createIndex(target, propertyKey, type) {
+    async createIndex(target, propertyKey) {
         if (target === 'node') {
             const indexFields = { graphId: 1, [`properties.${propertyKey}`]: 1 };
-            if (type && type !== '*') {
-                indexFields['type'] = 1;
-                await this._nodes.createIndex(indexFields, {
-                    name: `node_graphId_type_${propertyKey}`,
-                    background: true
-                });
-            }
-            else {
-                await this._nodes.createIndex(indexFields, {
-                    name: `node_graphId_${propertyKey}`,
-                    background: true
-                });
-            }
+            await this._nodes.createIndex(indexFields, {
+                name: `node_graphId_${propertyKey}`,
+                background: true
+            });
+            await this._nodes.createIndex({ ...indexFields, type: 1 }, {
+                name: `node_graphId_type_${propertyKey}`,
+                background: true
+            });
         }
         else {
             const indexFields = { graphId: 1, [`properties.${propertyKey}`]: 1 };
-            if (type && type !== '*') {
-                indexFields['type'] = 1;
-                await this._edges.createIndex(indexFields, {
-                    name: `edge_graphId_type_${propertyKey}`,
-                    background: true
-                });
-            }
-            else {
-                await this._edges.createIndex(indexFields, {
-                    name: `edge_graphId_${propertyKey}`,
-                    background: true
-                });
+            await this._edges.createIndex(indexFields, {
+                name: `edge_graphId_${propertyKey}`,
+                background: true
+            });
+            await this._edges.createIndex({ ...indexFields, type: 1 }, {
+                name: `edge_graphId_type_${propertyKey}`,
+                background: true
+            });
+        }
+    }
+    async hasIndex(target, propertyKey) {
+        const collection = target === 'node' ? this._nodes : this._edges;
+        const indexNameWithoutType = `${target === 'node' ? 'node' : 'edge'}_graphId_${propertyKey}`;
+        const indexNameWithType = `${target === 'node' ? 'node' : 'edge'}_graphId_type_${propertyKey}`;
+        for await (const index of collection.listIndexes()) {
+            const name = index.name;
+            if (name === indexNameWithoutType || name === indexNameWithType) {
+                return true;
             }
         }
+        return false;
     }
     async addProperty(target, id, key, value, transaction) {
         if (!(0, grafio_1.isPrimitive)(value)) {
@@ -432,6 +504,150 @@ class MongoStorageProvider {
             session.endSession();
         }
     }
+    _buildNodeFilter(options, baseFilter = {}) {
+        const filter = { graphId: this._graphId, ...baseFilter };
+        const andConditions = [];
+        if (options?.filter) {
+            if (options.filter.types && options.filter.types.length > 0) {
+                filter.type = { $in: options.filter.types };
+            }
+            if (options.filter.properties && options.filter.properties.length > 0) {
+                for (const prop of options.filter.properties) {
+                    const propFilter = this._buildPropertyFilter(prop);
+                    if (propFilter) {
+                        andConditions.push(propFilter);
+                    }
+                }
+            }
+        }
+        if (andConditions.length > 0) {
+            filter.$and = andConditions;
+        }
+        return filter;
+    }
+    _buildEdgeFilter(options, baseFilter = {}) {
+        const filter = { graphId: this._graphId, ...baseFilter };
+        const andConditions = [];
+        if (options?.filter) {
+            if (options.filter.types && options.filter.types.length > 0) {
+                filter.type = { $in: options.filter.types };
+            }
+            if (options.filter.properties && options.filter.properties.length > 0) {
+                for (const prop of options.filter.properties) {
+                    const propFilter = this._buildPropertyFilter(prop);
+                    if (propFilter) {
+                        andConditions.push(propFilter);
+                    }
+                }
+            }
+        }
+        if (andConditions.length > 0) {
+            filter.$and = andConditions;
+        }
+        return filter;
+    }
+    _buildPropertyFilter(prop) {
+        if (prop.AND && prop.AND.length > 0) {
+            const andFilters = [];
+            for (const subProp of prop.AND) {
+                const subFilter = this._buildPropertyFilter(subProp);
+                if (subFilter) {
+                    andFilters.push(subFilter);
+                }
+            }
+            if (andFilters.length > 0) {
+                return { $and: andFilters };
+            }
+            return undefined;
+        }
+        if (prop.OR && prop.OR.length > 0) {
+            const orFilters = [];
+            for (const subProp of prop.OR) {
+                const subFilter = this._buildPropertyFilter(subProp);
+                if (subFilter) {
+                    orFilters.push(subFilter);
+                }
+            }
+            if (orFilters.length > 0) {
+                return { $or: orFilters };
+            }
+            return undefined;
+        }
+        if (prop.key === undefined) {
+            return undefined;
+        }
+        const op = prop.op ?? '=';
+        const propPath = `properties.${prop.key}`;
+        switch (op) {
+            case '=':
+                return { [propPath]: prop.value };
+            case '<>':
+                return { [propPath]: { $ne: prop.value } };
+            case '>':
+                return { [propPath]: { $gt: prop.value } };
+            case '<':
+                return { [propPath]: { $lt: prop.value } };
+            case '>=':
+                return { [propPath]: { $gte: prop.value } };
+            case '<=':
+                return { [propPath]: { $lte: prop.value } };
+            case 'CONTAINS':
+                return { [propPath]: { $regex: String(prop.value), $options: 'i' } };
+            case 'STARTS_WITH':
+                return { [propPath]: { $regex: `^${this._escapeRegex(String(prop.value))}`, $options: 'i' } };
+            case 'ENDS_WITH':
+                return { [propPath]: { $regex: `${this._escapeRegex(String(prop.value))}$`, $options: 'i' } };
+            case 'IN':
+                return { [propPath]: { $in: Array.isArray(prop.value) ? prop.value : [prop.value] } };
+            case 'NOT_IN':
+                return { [propPath]: { $nin: Array.isArray(prop.value) ? prop.value : [prop.value] } };
+            case 'IS_NULL':
+                return { $or: [{ [propPath]: null }, { [propPath]: { $exists: false } }] };
+            case 'IS_NOT_NULL':
+                return { $and: [{ [propPath]: { $exists: true } }, { [propPath]: { $ne: null } }] };
+            default:
+                return { [propPath]: prop.value };
+        }
+    }
+    _buildSimplePropertyFilter(prop) {
+        if (prop.key === undefined) {
+            return undefined;
+        }
+        const op = prop.op ?? '=';
+        switch (op) {
+            case '=':
+                return prop.value;
+            case '<>':
+                return { $ne: prop.value };
+            case '>':
+                return { $gt: prop.value };
+            case '<':
+                return { $lt: prop.value };
+            case '>=':
+                return { $gte: prop.value };
+            case '<=':
+                return { $lte: prop.value };
+            case 'CONTAINS':
+                return { $regex: String(prop.value), $options: 'i' };
+            case 'STARTS_WITH':
+                return { $regex: `^${this._escapeRegex(String(prop.value))}`, $options: 'i' };
+            case 'ENDS_WITH':
+                return { $regex: `${this._escapeRegex(String(prop.value))}$`, $options: 'i' };
+            case 'IN':
+                return { $in: Array.isArray(prop.value) ? prop.value : [prop.value] };
+            case 'NOT_IN':
+                return { $nin: Array.isArray(prop.value) ? prop.value : [prop.value] };
+            case 'IS_NULL':
+                return { $or: [{ [prop.key]: null }, { [prop.key]: { $exists: false } }] };
+            case 'IS_NOT_NULL':
+                return { $and: [{ [prop.key]: { $exists: true } }, { [prop.key]: { $ne: null } }] };
+            default:
+                return prop.value;
+        }
+    }
+    _escapeRegex(str) {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
     _docToNode(doc) {
         return {
             id: doc.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grafio-mongo",
-  "version": "1.2.0",
+  "version": "3.0.0",
   "description": "MongoDB storage backend for grafio",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,14 +14,14 @@
     "perf:gc": "cross-env TS_NODE_PROJECT=tsconfig.perf.json node --expose-gc -r ts-node/register tests/perf/entryPoint.ts"
   
   },
-  "peerDependencies": {
-    "grafio": ">=6.2.0",
+  "peerDependencies": {},
+  "dependencies": {
+    "grafio": ">=7.0.0",
     "mongodb": ">=5.0.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",
     "@types/node": "^25.6.0",
-    "grafio": "^6.2.0",
     "cross-env": "^10.1.0",
     "jest": "^29.5.0",
     "rimraf": "^5.0.0",