npm package: @fnet/neo4j
Description: A package that is used to interact with the Neo4j database.
Author: Gultekin Boyraz
Latest version: 0.1.28

# @fnet/neo4j

## Introduction

The `@fnet/neo4j` project provides a straightforward way to connect and interact with a Neo4j database using JavaScript. It simplifies the process of running single or multiple Cypher queries, both from memory and from the filesystem. Designed to work in both development and production environments, it supports efficient query management by optionally caching query results.

## How It Works

The project operates by creating a Neo4j database connection through a `Database` class, which wraps Neo4j session management. When initialized, it allows users to execute Cypher queries using a dynamic, proxy-based `Query` object. Queries can be provided directly in-memory or read from specified directories. The system handles session creation and closure, providing a clean API for running queries with optional caching.

## Key Features

- **Connection Initialization**: Establishes a connection to a Neo4j instance using configurable URI, username, and password.
- **Query Execution**: Supports execution of single and multiple Cypher statements with ease.
- **Dynamic Query Access**: Uses proxies for dynamic query references, enabling straightforward directory-based query organization.
- **Caching**: Optional caching mechanism to speed up repeated query executions.
- **In-memory and Filesystem Support**: Allows queries to be stored either in-memory or in .cypher files within the filesystem.

## Conclusion

This project is useful for developers looking for a simple and efficient way to manage Neo4j database queries in their Node.js applications. It abstracts the complexity of direct Neo4j driver interactions while providing flexible query management through both in-memory and filesystem options.


# @fnet/neo4j Developer Guide

## Overview

The `@fnet/neo4j` library provides an interface for interacting with a Neo4j database, allowing developers to manage database queries efficiently. Its core functionality revolves around executing Cypher queries, both simple and multi-statement, by fetching them from memory or file storage. It encapsulates handling sessions and transactions, ensuring smooth operations with optional caching for improved performance.

Key Features:
- Connects to a Neo4j database using predefined credentials.
- Manages Cypher query execution from in-memory or file-based sources.
- Supports both single and multiple statement execution.
- Offers caching mechanism to optimize query retrieval.
- Facilitates session management, ensuring proper connection handling.

## Installation

To install the `@fnet/neo4j` library, execute the following command using npm:

```bash
npm install @fnet/neo4j
```

Or, if you are using yarn:

```bash
yarn add @fnet/neo4j
```

## Usage

Below is a basic usage example demonstrating how to set up a connection to a Neo4j database and run a sample query:

```javascript
// Import the @fnet/neo4j library
import neo4jConnector from '@fnet/neo4j';

async function main() {
  // Initialize the database connection with parameters
  const db = await neo4jConnector({
    uri: "bolt://localhost:7687",
    username: "neo4j",
    password: "your_password",
    queries_dir: "./queries", // Directory containing .cypher files
    use_cache: true // Enable query caching
  });

  // Run a single query
  const session = db.getSession();
  try {
    const cypherResult = await db.query.run({ param1: 'value' }, session);
    console.log(cypherResult);
  } finally {
    session.close();
  }

  // Close the database connection
  await db.close();
}

main().catch(console.error);
```

## Examples

Here are practical examples showcasing the most common use cases:

### Running a Single Query

```javascript
const session = db.getSession();

try {
  const result = await db.query.users.run({ username: 'john_doe' }, session);
  console.log(result.records);
} finally {
  session.close();
}
```

### Running Multiple Queries

```javascript
const session = db.getSession();

try {
  const results = await db.query.statistics.mrun({ limit: 10 }, session);
  results.forEach((resultSet) => {
    console.log(resultSet.records);
  });
} finally {
  session.close();
}
```

### Using Caching

To enable caching for faster query lookups, initialize `@fnet/neo4j` with `use_cache: true`. This will store queries in memory after the first load.

```javascript
const db = await neo4jConnector({
  uri: "bolt://localhost:7687",
  username: "neo4j",
  password: "your_password",
  queries_dir: "./queries",
  use_cache: true // Enable caching
});
```

## Acknowledgement

The `@fnet/neo4j` library harnesses the official Neo4j JavaScript driver to interact with the database, ensuring reliable and performant database operations.



# Input Schema
```yaml
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  uri:
    type: string
    description: URI for the Neo4j database connection
    default: bolt://localhost:7687
  username:
    type: string
    description: Username for Neo4j authentication
    default: neo4j
  password:
    type: string
    description: Password for Neo4j authentication
  queries_dir:
    type: string
    description: Directory path for .cypher files
    default: ./queries
  use_cache:
    type: boolean
    description: Flag to enable or disable query caching
    default: false
required:
  - password

```