Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zishanneno/cypher-vault
A utility for sourcing and managing Neo4j cypher queries from the file system.
https://github.com/zishanneno/cypher-vault
cypher cypher-query cypher-query-language neo4j neo4j-driver npm-package typescript
Last synced: 22 days ago
JSON representation
A utility for sourcing and managing Neo4j cypher queries from the file system.
- Host: GitHub
- URL: https://github.com/zishanneno/cypher-vault
- Owner: zishanneno
- License: mit
- Created: 2023-11-06T20:10:11.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2023-11-08T03:45:43.000Z (about 1 year ago)
- Last Synced: 2024-12-08T18:39:05.199Z (about 1 month ago)
- Topics: cypher, cypher-query, cypher-query-language, neo4j, neo4j-driver, npm-package, typescript
- Language: TypeScript
- Homepage:
- Size: 10.7 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# CypherVault
CypherVault is a Node.js library designed to simplify the management and loading of Cypher query files for Neo4j graph database applications. With support for multiple file extensions, CypherVault streamlines the process of reading Cypher queries from a directory structure and providing them as a record object for easy access within your application.
## Updates in Version 2.0.0
- **Asynchronous Loading**: The `loadQueries` function is now fully asynchronous, using `Promise.all` to handle concurrent file reading. This update brings improved performance and better integration with modern Node.js applications.
## Features
- Supports `.cypher`, `.cql`, and `.cyp` file extensions for Cypher queries.
- Recursively reads a given directory path to asynchronously load all supported query files.
- Organizes queries in a `Record` structure, using the file path (minus the root path and extension) as the key.
## Installation
To install CypherVault, use npm:
```bash
npm install cypher-vault
```
Or, if you prefer using yarn:
```bash
yarn add cypher-vault
```
## Usage
To use CypherVault in your project, follow these steps:
1. Import the `CypherVault` class from the library.
2. Instantiate the class with a path to the directory containing your Cypher query files.
3. Call `loadQueries` async function to load the queries.
Here's an example:
```javascript
import { CypherVault } from "cypher-vault";
// Path to the directory where Cypher queries are stored
const queryPath = "src/path/to/cypher/queries";
// Create a new instance of CypherVault
const cypherVault = new CypherVault(queryPath);
// Load queries
const queries = cypherVault.loadQueries();
// Access a query by its key
const updateUser = await queries["user/update"];
```
## Motivation
In the journey through the realms of Neo4j, it quickly becomes apparent that Cypher queries evolve. They grow from the simplicity of `MATCH (p:Person) RETURN p` into intricate statements capable of unveiling deep insights within connected data. However, when these queries are nestled within JavaScript or TypeScript code, their complexity can become overwhelming. They're not just code; they're the cartographers of our data landscape, and they deserve their own space.
The clarity of thought and organization often reflects in the structure of our work. I envisioned my queries residing not just anywhere but in a place they could call home — a dedicated directory where each could be accessed without clutter, yet with the efficiency I demanded. No longer would the queries be mixed with code, obscured within template literals. Instead, they would stand in their own files, clear and distinct, ready to be called upon like well-organized tomes in a library.
The structure I had in mind was simple yet intuitive:
```
- src/
- cypher/
- user/
- insert.cypher
- update.cypher
```
With such an arrangement, accessing my Cypher queries needed to be as straightforward as referencing `queries["user/insert"]` or `queries["user/update"]` (see example section below).
This would not only streamline the development experience but also pave the way for easier maintenance and scalability of the codebase. Thus, the creation of CypherVault — a means to encapsulate the complexity of Neo4j queries and harness their power with elegance and efficiency.
## API Reference
### CypherVault(queryPath: string)
Constructor to create a new instance of CypherVault.
- `queryPath`: A string representing the path to the directory containing the Cypher query files, relative to your current working directory.
### async loadQueries(): Promise>
Asynchronously loads all the Cypher queries from the directory path provided when the instance was created. The function returns a promise that resolves to a record. The record's keys are derived from the relative file paths, excluding the root path and file extension. The record's values are the contents of the query files. This function must be awaited or used with `.then()` to handle the returned promise.
## Contributing
Contributions are welcome! If you have suggestions for how CypherVault could be improved, or if you encounter any issues, please open an issue or submit a pull request.
## License
CypherVault is [MIT licensed](./LICENSE.md).
Before contributing or using the library, please review the full license details to ensure it is suitable for your use case.