Nervously Proposing Marriage

    neo4j-request
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.2 • Public • Published

    neo4j-request

    A wrapper for the official neo4j-driver that simplifies the execution of cypher queries by encapsulating session opening and closing as well as transaction handling in respective methods. The queried records are extracted to a simplified format, non-standard properties (e.g. dates) are converted.

    Currently, this package only makes use of the Promise API of neo4j-driver. Features like the Streaming API or bookmarks are not yet implemented.

    Installation

    Via npm:

    npm install neo4j-request
    

    Usage

    Import:

    const neo4j = require('neo4j-request');
    // or
    import * as neo4j from 'neo4j-request';

    init

    Before doing any transaction, the neo4j-driver needs to be initialized once. The driver instance is set globally, such that you can import neo4j-request in any other module without the need to initialize again. If the node application closes, the driver gets closed as well.

    If the Neo4j instance is unavailable, connection is not possible. Driver instantiation will be re-invoked a few times before throwing an error (useful in cases like server startup when node application is live earlier than the Neo4j database instance).

    For detailed options refer to neo4j-driver.

    neo4j.init(url, user, password, database = 'neo4j', options = {disableLosslessIntegers: true});
    Param Details
    url Type: string
    Usually something like neo4j://localhost.
    user Type: string
    password Type: string
    database
    (optional)
    Type: string
    Default: neo4j
    If using Neo4j 3.x, this information gets ignored.
    options
    (optional)
    Type: Object
    For details refer to neo4j-driver.

    Returns Promise<ServerInfo>.

    readTransaction

    A very simple read transaction that expects a cypher statement and (optionally) query parameters.

    Param Details
    query Type: string
    params
    (optional)
    Type: Object<string, any>

    Returns Promise<Object[]>: an array of objects, where the object's property names correlate with identifiers within the RETURN clause.

    const query = `
      MATCH (p:Person {name: $name})-[:HAS_ADDRESS]->(add:Address)
      RETURN p.name AS name, add AS address
    `;
    
    const params = {
      name: 'Alex'
    };
    
    try {
      
      const results = await neo4j.readTransaction(query, params);
      console.log(results);
      
    } catch (e) {
      
      // handle error
      
    }
    
    // console.log(results)
    // [
    //   {
    //     name: 'Alex',
    //     address: {
    //       ZIP: '10178',
    //       number: '1',
    //       town: 'Berlin',
    //       street: 'Alexanderplatz'
    //     }
    //   }
    // ]

    writeTransaction

    Very similar to readTransaction (see for details) except that it expects a cypher statement that modifies the database.

    multipleStatements

    Execute multiple cypher queries within one transaction. A fail of one statement will lead to the rollback of the whole transaction.

    Param Details
    statements Type: Array<{statement: string, parameters: Object<string, any>}>

    Returns Promise<Object[][]>: an array of arrays similar to readTransaction.

    const statements = [{
      statement: `CREATE ...`,
      parameters: {}
    }, {
      statement: `MATCH ... CREATE (n:Node $map) ...`,
      parameters: { map: { value: 'foo' } }
    }];
    
    try {
      
      const results = await neo4j.multipleStatements(statements);
      // handle results
      
    } catch (e) {
      
      // handle error
      
    }

    getDriver

    Get the driver instance to access full API of neo4j-driver.

    const driver = neo4j.getDriver();

    session

    Acquire a session to execute, e.g., explicit transactions.

    const session = neo4j.session();
    const txc = session.beginTransaction();
    
    // ...
    
    await session.close();

    extractRecords

    Used internally to extract and convert the returned records by neo4j-driver to a more simplified format. It converts non-standard values, like date, time, etc., to strings as well as Neo4j integers, if they are outside of the safe range.

    Takes an array of records Record[] and returns an array of objects Object[].

    const query = `
      MATCH (p:Person {name: "Alex"})-[:HAS_ADDRESS]->(add:Address)
      RETURN p.name AS name, add AS address
    `;
    
    // query results returned by neo4j-driver
    // {
    //   records: [
    //     Record {
    //       keys: [ 'name', 'address' ],
    //       length: 2,
    //       _fields: [
    //         'Alex',
    //         Node {
    //           identity: 1,
    //           labels: [ 'Address' ],
    //           properties: {
    //             ZIP: '10178',
    //             number: '1',
    //             town: 'Berlin',
    //             street: 'Alexanderplatz'
    //           }
    //         }
    //       ]
    //       _fieldLookup: { name: 0, address: 1 }
    //     }
    //   ],
    //   summary: ResultSummary {...}
    // }
    
    extractRecords(queryResults.records);
    
    // simplified records returned by neo4j-request
    // {
    //   name: 'Alex',
    //   address: {
    //     ZIP: '10178',
    //     number: '1',
    //     town: 'Berlin',
    //     street: 'Alexanderplatz'
    //   }
    // }

    removeEmptyArrays

    Look for empty arrays returned by Neo4j and clean them, if there is null inside.

    Sometimes, if the cypher query contains OPTIONAL MATCH node in combination with collect({key: node.value}) AS values, the resulting array may be filled with one object with null values: [{key: null}]. This method reduces the array to [] by calling removeEmptyArrays(data, 'values', 'key').

    Param Details
    data Type: any[]
    arrayKey Type: string
    Property key of the array to check.
    checkKey Type: string
    Property key of first array element to check against null.

    Returns cleaned data array.

    const query = `
      MATCH (p:Person {name: "Alex"})-[:HAS_ADDRESS]->(add:Address)
      OPTIONAL MATCH (p)-[:HAS_FRIEND]->(f:Person)-[:HAS_ADDRESS]->(fAddr:Address)
      RETURN p.name AS name,
             add AS address,
             collect({name: f.name, address: fAddr}) AS friends
    `;
    
    const results = await neo4j.readTransaction(query);
    console.log(results);
    
    // [
    //   {
    //     name: 'Alex',
    //     address: {
    //       ZIP: '10178',
    //       number: '1',
    //       town: 'Berlin',
    //       street: 'Alexanderplatz'
    //     },
    //     friends: [ { address: null, name: null } ]
    //   }
    // ]
    
    const resultsCleaned = neo4j.removeEmptyArrays(results, 'friends', 'name');
    console.log(resultsCleaned);
    
    // [
    //   {
    //     name: 'Alex',
    //     address: {
    //       ZIP: '10178',
    //       number: '1',
    //       town: 'Berlin',
    //       street: 'Alexanderplatz'
    //     },
    //     friends: []
    //   }
    // ]

    Testing

    Copy test/config-sample.js to test/config.js and change the values according to the settings of your Neo4j instance. Then, run test command:

    npm test
    

    Install

    npm i neo4j-request

    DownloadsWeekly Downloads

    3

    Version

    1.3.2

    License

    MIT

    Unpacked Size

    23.6 kB

    Total Files

    6

    Last publish

    Collaborators

    • brakebein