@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:

npm install @fnet/neo4j

Or, if you are using yarn:

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:

// 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

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

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.

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

$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