Object-Graph-Mapping neo4j framework, fully-typed with TypeScript, for easy and flexible node and relationship operations

linkOverview

Neogma uses Model definitions to simplify and automate lots of operations. Alternatively, a flexible and fully-fletched query builder and a query runner is also provided for running operations directly with Javascript objects, without a Model definition.

By using Typescript, a user can also benefit from Neogma's type safety in all its parts. The types are built-in and used in neogma's core, so no external typings are needed.

linkExamples

You can try the following to see it in action!

First install neogma: npm i neogma

Then, run this:

1linkconst { Neogma, ModelFactory } = require('neogma');

2link

3link/* --> create a neogma instance and database connection */

4linkconst neogma = new Neogma(

5link    {

6link        /* --> use your connection details */

7link        url: 'bolt://localhost',

8link        username: 'neo4j',

9link        password: 'password',

10link    },

11link    {

12link        logger: console.log,

13link    }

14link);

15link

16link/* --> create a Users model */

17linkconst Users = ModelFactory({

18link    label: 'User',

19link    schema: {

20link        name: {

21link            type: 'string',

22link            minLength: 3,

23link            required: true

24link        },

25link        age: {

26link            type: 'number',

27link            minimum: 0,

28link        },

29link        id: {

30link            type: 'string',

31link            required: true,

32link        }

33link    },

34link    primaryKeyField: 'id',

35link    relationshipCreationKeys: {},

36link}, neogma);

37link

38linkconst createAndUpdateUser = async () => {

39link    /* --> creates a new Users node */

40link    const user = await Users.createOne({

41link        id: '1',

42link        name: 'John',

43link        age: 38

44link    });

45link

46link    console.log(user.name); // 'John'

47link

48link    user.name = 'Alex';

49link    /* --> updates the node's name in the database */

50link    await user.save();

51link    console.log(user.name); // 'Alex'

52link

53link    await neogma.getDriver().close();

54link}

55link

56linkcreateAndUpdateUser();

The Cypher which runs in createAndUpdateUser is the following:

1linkStatement: UNWIND {bulkCreateOptions} as bulkCreateData CREATE (bulkCreateNodes:`User`) SET bulkCreateNodes += bulkCreateData

2linkParameters: { bulkCreateOptions: [ { name: 'John', age: 38, id: '1' } ] }

3link

4linkStatement: MATCH (node:`User`) WHERE node.id = $id SET node.name = $name

5linkParameters: { id: '1', name: 'Jack' }

Another feature is to associate the created nodes with other nodes, which will either be created now or by matched by a where clause. This supports infinite nesting for maximum flexibility.

1link/* --> create a User node, an Order node and a relationship between them */

2linkawait Users.createMany([

3link    {

4link        id: '1',

5link        name: 'John',

6link        age: 38,

7link        /* --> assuming we're created an Orders Model and alias */

8link        Orders: {

9link            properties: [{

10link                /* --> creates a new Order node with the following properties, and associates it with John */

11link                id: '1',

12link                status: 'confirmed'

13link            }],

14link            where: {

15link                params: {

16link                    /* --> matches an Order node with the following id and associates it with John */

17link                    id: '2'

18link                }

19link            }

20link        }

21link    }

22link]);

23link

24link// find the Order node which is created in the above operation

25linkconst order = await Orders.findOne({

26link    where: {

27link        id: '1'

28link    }

29link});

30link

31linkconsole.log(order.status); // confirmed

The cypher which runs in Users.createMany is the following:

1linkStatement: CREATE (node:`User`) SET node += $data CREATE (node__aaaa:`Order`) SET node__aaaa += $data__aaaa CREATE (node)-[:CREATES]->(node__aaaa) WITH DISTINCT node MATCH (targetNode:`Order`) WHERE targetNode.id = $id CREATE (node)-[r:CREATES]->(targetNode)

2link

3linkParameters: {

4link  data: { name: 'John', age: 38, id: '1' },

5link  data__aaaa: { id: '1', status: 'confirmed' },

6link  id: '2'

7link}

All of the above run in a single statement for max performance. The association alias (here Orders) is defined in the Model along with the relationship name, direction and properties.

All the user-specified values are automatically used in the query with bind parameters. Neogma also offers helpers to easily create your own queries with generated where clauses and bind parameters.