From d234ab9e1069af8b2bf4f26f5f97f1e894f52868 Mon Sep 17 00:00:00 2001 From: diy0r Date: Sat, 21 Sep 2024 14:59:23 +0500 Subject: [PATCH] doc: improved documentation text and examples --- README.md | 312 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 304 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index f8d5769..ad70dee 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# File-Graph +# FileGraph- Graph Operations API [![version](https://img.shields.io/npm/v/file-graph.svg)](https://www.npmjs.com/package/file-graph) [![npm downloads](https://img.shields.io/npm/dt/file-graph.svg)](https://www.npmjs.com/package/file-graph) @@ -6,7 +6,7 @@ [![license](https://badgen.net/npm/license/file-graph)](https://www.npmjs.com/package/file-graph) [![Testing CI](https://github.com/DIY0R/file-graph/actions/workflows/checker.yaml/badge.svg?branch=main)](https://github.com/DIY0R/file-graph/actions/workflows/checker.yaml) -**file-graph** is a library for working with graphs using a file-based storage system. It provides functionality for creating, updating, deleting, and searching for graph vertices and edges, as well as for performing traversal and pathfinding operations within the graph. +The `file-graph` class provides an abstract implementation for graph operations. It supports graph manipulation, including creating, updating, and deleting vertices, creating arcs and edges, and traversing or querying the graph structure. --- @@ -28,7 +28,7 @@ npm install @diy0r/file-graph const graph = FileGraph('../graph.txt'); ``` -`FileGraph` accepts a path where the graph data will be stored. The `graph` object returned is an instance of the `FileGraphAbstract` class, which provides methods for manipulating the graph. You can refer to the [jsDoc documentation](https://www.jsdocs.io/package/file-graph) for more details. +`FileGraph` accepts a path where the graph data will be stored. The graph object returned is an instance of the `FileGraphAbstract` class, which provides methods for manipulating the graph. You can refer to the [jsDoc documentation](https://www.jsdocs.io/package/file-graph) documentation for more details. ## File Structure @@ -46,11 +46,307 @@ Example of a vertex record: ## Public API - Asynchronous Methods -### Creating a Vertex +Below is an overview of the methods, their parameters, return values, and examples of how to use them. -```ts -const data = { name: 'Diyor', city: 'New-York' }; -const createdVertex = await graph.createVertex(data); +### `createVertex(data: T): Promise>` + +Creates a vertex (node) in the graph with the provided data. + +- **Parameters**: + - `data: T` - An object representing the vertex data. +- **Returns**: + - A promise that resolves to the created vertex object `{ id, data, links }`. + +#### Example: + +```typescript +const data = { name: 'Alice', age: 30 }; +const createdVertex = await graph.createVertex(data); +console.log(createdVertex); +// Output: { id: 'some-unique-id', data: { name: 'Alice', age: 30 }, links: [] } +``` + +--- + +### `createVertices(data: T[]): Promise[]>` + +Creates multiple vertices at once. + +- **Parameters**: + - `data: T[]` - An array of objects representing the data for each vertex. +- **Returns**: + - A promise that resolves to an array of created vertex objects. + +#### Example: + +```typescript +const data = [{ name: 'Alice' }, { name: 'Bob' }]; +const createdVertices = await graph.createVertices(data); +console.log(createdVertices); +// Output: [{ id: 'id1', data: { name: 'Alice' }, links: [] }, { id: 'id2', data: { name: 'Bob' }, links: [] }] +``` + +--- + +### `updateVertex(updater: IUpdater): Promise` + +Updates a vertex that matches the given condition. The updater function defines the logic for finding and modifying the vertex. + +- **Parameters**: + - `updater: IUpdater` - A function that takes a vertex and returns an updated vertex if it matches the condition. +- **Returns**: + - A promise that resolves to `true` if the update was successful, otherwise `false`. + +#### Example: + +```typescript +const isUpdated = await graph.updateVertex( + vertex => + vertex.id === 'some-unique-id' && { data: { name: 'Alice Updated' } }, +); +console.log(isUpdated); // true +``` + +--- + +### `deleteVertex(predicate: IPredicate): Promise` + +Deletes a vertex that matches the given condition. + +- **Parameters**: + - `predicate: IPredicate` - A function that returns `true` if the vertex should be deleted. +- **Returns**: + - A promise that resolves to `true` if the deletion was successful, otherwise `false`. + +#### Example: + +```typescript +const isDeleted = await graph.deleteVertex( + vertex => vertex.id === 'some-unique-id', +); +console.log(isDeleted); // true +``` + +--- + +### `findOne(predicate: IPredicate): Promise | null>` + +Finds a single vertex that matches the given condition. + +- **Parameters**: + - `predicate: IPredicate` - A function that returns `true` if the vertex matches the search condition. +- **Returns**: + - A promise that resolves to the matching vertex object, or `null` if no match is found. + +#### Example: + +```typescript +const foundVertex = await graph.findOne(vertex => vertex.data.name === 'Alice'); +console.log(foundVertex); +// Output: { id: 'some-unique-id', data: { name: 'Alice', age: 30 }, links: [] } +``` + +--- + +### `findAll(predicate: IPredicate): Promise[]>` + +Finds all vertices that match the given condition. + +- **Parameters**: + - `predicate: IPredicate` - A function that returns `true` for each vertex that matches the search condition. +- **Returns**: + - A promise that resolves to an array of matching vertex objects. + +#### Example: + +```typescript +const foundVertices = await graph.findAll( + vertex => vertex.data.name === 'Alice', +); +console.log(foundVertices); +// Output: [{ id: 'id1', data: { name: 'Alice', age: 30 }, links: [] }, { id: 'id2', data: { name: 'Alice', age: 25 }, links: [] }] ``` -This method returns an instance of the created vertex. +--- + +### `forEachVertex(callbackVertex: ICallbackVertex): Promise` + +Iterates over each vertex in the graph and applies the provided callback function. + +- **Parameters**: + - `callbackVertex: ICallbackVertex` - A callback function that is invoked for each vertex. If it returns `true`, the iteration stops. +- **Returns**: + - A promise that resolves when the iteration is complete. + +#### Example: + +```typescript +await graph.forEachVertex(vertex => { + console.log(vertex); + // Stop iteration if the vertex's name is 'Alice' + return vertex.data.name === 'Alice'; +}); +``` + +--- + +### `createEdge(ids: IUuidArray): Promise` + +Creates edges (links) between the specified vertices. + +- **Parameters**: + - `ids: IUuidArray` - An array of vertex IDs between which to create edges. +- **Returns**: + - A promise that resolves to `true` if the edge creation was successful. + +#### Example: + +```typescript +const isEdgeCreated = await graph.createEdge(['id1', 'id2', 'id3']); +console.log(isEdgeCreated); // true +``` + +--- + +### `createArc(sourceVertexId: uuidType, targetVertexId: uuidType): Promise` + +Creates an arc (directed edge) between two vertices. + +- **Parameters**: + - `sourceVertexId: uuidType` - The ID of the source vertex. + - `targetVertexId: uuidType` - The ID of the target vertex. +- **Returns**: + - A promise that resolves to `true` if the arc creation was successful. + +#### Example: + +```typescript +const isArcCreated = await graph.createArc('id1', 'id2'); +console.log(isArcCreated); // true +``` + +--- + +### `createArcs(ids: IUuidArray): Promise` + +Creates arcs (directed edges) between multiple vertices in the specified order. + +- **Parameters**: + - `ids: IUuidArray` - An array of vertex IDs. +- **Returns**: + - A promise that resolves to `true` if the arcs creation was successful. + +#### Example: + +```typescript +const isArcsCreated = await graph.createArcs(['id1', 'id2', 'id3']); +console.log(isArcsCreated); // true +``` + +--- + +### `removeArc(sourceVertexId: uuidType, targetVertexId: uuidType): Promise` + +Removes an arc (edge) between two vertices. + +- **Parameters**: + - `sourceVertexId: uuidType` - The ID of the source vertex. + - `targetVertexId: uuidType` - The ID of the target vertex. +- **Returns**: + - A promise that resolves to `true` if the arc was successfully removed. + +#### Example: + +```typescript +const isArcRemoved = await graph.removeArc('id1', 'id2'); +console.log(isArcRemoved); // true +``` + +--- + +### `hasArc(sourceVertexId: uuidType, targetVertexId: uuidType): Promise` + +Checks if an arc exists between two vertices. + +- **Parameters**: + - `sourceVertexId: uuidType` - The ID of the source vertex. + - `targetVertexId: uuidType` - The ID of the target vertex. +- **Returns**: + - A promise that resolves to `true` if the arc exists, otherwise `false`. + +#### Example: + +```typescript +const hasArc = await graph.hasArc('id1', 'id2'); +console.log(hasArc); // true or false +``` + +--- + +### `findUpToLevel(vertexId: uuidType, maxLevel?: number): Promise[]>` + +Retrieves vertices up to a specified depth level from a starting vertex. + +- **Parameters**: + - `vertexId: uuidType` - The ID of the starting vertex. + - `maxLevel?: number` - (Optional) The depth level to limit the search. +- **Returns**: + - A promise that resolves to an array of vertices up to the specified level. + +#### Example: + +```typescript +const graphTree = await graph.findUpToLevel('id1', 2); +console.log(graphTree); +/* Output: [ +{ id: 'id1',data:{...},links:[...],level: 0 }, +{ id: 'id2',data:{...},links:[...], level: 1 }, +{ id: 'id3', data:{...},links:[...],level: 2 } + ]; */ +``` + +--- + +### `searchVerticesFrom(vertexId: uuidType, predicate: IPredicate): Promise[]>` + +Performs a search starting from the given vertex and returns vertices that match the predicate. + +- **Parameters**: + - `vertexId: uuidType` - The ID of the starting vertex. + - `predicate: IPredicate` - A function used to evaluate each vertex. Only vertices that satisfy the predicate will be returned. +- **Returns**: + - A promise that resolves to an array of matching vertices. + +#### Example: + +```typescript +const matchingVertices = await graph.searchVerticesFrom( + 'id1', + vertex => vertex.data.age > 25, +); +console.log(matchingVertices); +// Output: [{ id: 'id2', data: { name: 'Alice', age: 30 }, links: [] }] +``` + +--- + +### `hasPath(sourceVertexId: uuidType, targetVertexId: uuidType): Promise` + +Checks if a path exists between two vertices using Depth-First Search (DFS). + +- **Parameters**: + - `sourceVertexId: uuidType` - The ID of the source vertex. + - `targetVertexId: uuidType` - The ID of the target vertex. +- **Returns**: + - A promise that resolves to `true` if a path exists between the vertices, otherwise `false`. + +#### Example: + +```typescript +const pathExists = await graph.hasPath('id1', 'id3'); +console.log(pathExists); // true or false +``` + +--- + +This abstract class provides the blueprint for interacting with a graph structure, supporting both simple and complex operations for managing vertices and their relationships. Concrete implementations should define the behavior for storing and retrieving graph data.