https://github.com/themetalfleece/neogma
Object-Graph-Mapping neo4j framework, Fully-typed with TypeScript, for easy and flexible node and relationship operations
https://github.com/themetalfleece/neogma
cypher neo4j neo4j-driver neo4j-ogm nodejs typescript
Last synced: 8 months ago
JSON representation
Object-Graph-Mapping neo4j framework, Fully-typed with TypeScript, for easy and flexible node and relationship operations
- Host: GitHub
- URL: https://github.com/themetalfleece/neogma
- Owner: themetalfleece
- License: mit
- Created: 2019-07-16T19:14:59.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2025-10-12T16:14:48.000Z (8 months ago)
- Last Synced: 2025-10-12T20:27:31.276Z (8 months ago)
- Topics: cypher, neo4j, neo4j-driver, neo4j-ogm, nodejs, typescript
- Language: TypeScript
- Homepage: https://themetalfleece.github.io/neogma/
- Size: 1.42 MB
- Stars: 146
- Watchers: 5
- Forks: 14
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
A powerful Neo4j OGM for Node.js & TypeScript
Build graph applications with ease using type-safe models, flexible query builders, and automatic relationship management
---
## Why Neogma?
- 🔷 **Fully Type-Safe** - Built-in TypeScript support with complete type inference
- âš¡ **Flexible** - Use Models, Query Builders, or raw Cypher queries
- 🔗 **Automatic Relationships** - Create and manage complex graph structures effortlessly
- ✅ **Validation** - Built-in schema validation for your data models
- 🚀 **Production Ready** - Battle-tested with comprehensive test coverage
## Quick Start
### Installation
```bash
npm i neogma
# or
yarn add neogma
# or
pnpm i neogma
```
### Basic Example
```js
const { Neogma, ModelFactory } = require('neogma');
// Connect to Neo4j
const neogma = new Neogma({
url: 'bolt://localhost:7687',
username: 'neo4j',
password: 'password',
});
// Define a model
const User = ModelFactory({
label: 'User',
schema: {
name: { type: 'string', required: true },
email: { type: 'string', required: true },
},
}, neogma);
// Create and query
const user = await User.createOne({
name: 'Alice',
email: 'alice@example.com',
});
const found = await User.findOne({ where: { email: 'alice@example.com' } });
```
**[View full documentation →](https://themetalfleece.github.io/neogma)**
---
## Table of Contents
- [Quick Start](#quick-start)
- [Features](#features)
- [Examples](#examples)
- [Documentation](#documentation)
- [Development](#development)
- [Acknowledgements](#acknowledgements)
---
## Documentation
Full documentation is available at **[themetalfleece.github.io/neogma](https://themetalfleece.github.io/neogma)**
---
## Examples
### Creating and Updating Nodes
```js
const { Neogma, ModelFactory } = require('neogma');
// create a neogma instance and database connection
const neogma = new Neogma(
{
// use your connection details
url: 'bolt://localhost',
username: 'neo4j',
password: 'password',
},
{
logger: console.log,
},
);
// create a Users model
const Users = ModelFactory(
{
label: 'User',
schema: {
name: {
type: 'string',
minLength: 3,
required: true,
},
age: {
type: 'number',
minimum: 0,
},
id: {
type: 'string',
required: true,
},
},
primaryKeyField: 'id',
relationshipCreationKeys: {},
},
neogma,
);
const createAndUpdateUser = async () => {
// creates a new Users node
const user = await Users.createOne({
id: '1',
name: 'John',
age: 38,
});
console.log(user.name); // 'John'
user.name = 'Alex';
// updates the node's name in the database
await user.save();
console.log(user.name); // 'Alex'
await neogma.getDriver().close();
};
createAndUpdateUser();
```
The Cypher which runs in `createAndUpdateUser` is the following:
```sql
Statement: UNWIND {bulkCreateOptions} as bulkCreateData CREATE (bulkCreateNodes:`User`) SET bulkCreateNodes += bulkCreateData
Parameters: { bulkCreateOptions: [ { name: 'John', age: 38, id: '1' } ] }
Statement: MATCH (node:`User`) WHERE node.id = $id SET node.name = $name
Parameters: { 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.
```js
await Users.createMany([
{
id: '1',
name: 'John',
age: 38,
// assuming we're created an Orders Model and alias
Orders: {
attributes: [
{
// creates a new Order node with the following properties, and associates it with John
id: '1',
status: 'confirmed',
},
],
where: {
params: {
// matches an Order node with the following id and associates it with John
id: '2',
},
},
},
},
]);
// find the Order node which is created in the above operation
const order = await Orders.findOne({
where: {
id: '1',
},
});
console.log(order.status); // confirmed
```
The cypher which runs in `Users.createMany` is the following:
```sql
Statement: 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)
Parameters: {
data: { name: 'John', age: 38, id: '1' },
data__aaaa: { id: '1', status: 'confirmed' },
id: '2'
}
```
All of the above run in a single statement for max performance.
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.
---
## Development
### Prerequisites
- [nvm](https://github.com/nvm-sh/nvm), which will install node.js
- [Docker](https://www.docker.com/) and Docker Compose
### Setting up Node.js and Yarn
**Activate the project's Node.js version:**
```bash
nvm use
```
This will automatically use the Node.js version specified in `.nvmrc`.
**Enable Yarn via Corepack:**
```bash
corepack enable yarn
```
### Setting up Neo4j
Neogma requires a running Neo4j instance for unit tests. The easiest way to get started is using Docker Compose.
#### Using Docker Compose (Recommended)
**Start Neo4j:**
```bash
docker compose up -d
```
This will start a Neo4j 5.x Enterprise instance with:
- HTTP interface on http://localhost:7474
- Bolt protocol on bolt://localhost:7687
- Default credentials: `neo4j/password`
**Note:** Enterprise Edition is required for temporary database support used in tests.
**Verify Neo4j is running:**
Open http://localhost:7474 in your browser and login with username `neo4j` and password `password`.
**Configure environment variables:**
```bash
cp .env.example .env
```
The `.env` file contains the connection details. You can modify them if you changed the Docker Compose configuration.
**Stop Neo4j:**
```bash
docker compose down
```
To also remove the data volumes:
```bash
docker compose down -v
```
#### Manual Neo4j Installation
If you prefer not to use Docker:
1. Download and install [Neo4j Desktop](https://neo4j.com/download/) or [Neo4j Community Edition](https://neo4j.com/deployment-center/)
2. Create a new database with username `neo4j` and password `password`
3. Start the database
4. Copy `.env.example` to `.env` and update the connection details if needed
### Running Tests
1. **Install dependencies:**
```bash
yarn
```
2. **Ensure Neo4j is running** (see above)
3. **Configure environment variables:**
Make sure you have a `.env` file with the Neo4j connection details (see `.env.example`)
4. **Run the tests:**
```bash
yarn test
```
The tests will automatically create temporary databases for each test suite to avoid conflicts.
### Development Workflow
**Build TypeScript:**
```bash
yarn build
```
**Lint code:**
```bash
yarn lint
```
**Format code:**
```bash
yarn format
```
**Run tests in watch mode:**
```bash
yarn test --watch
```
---
## Acknowledgements
- Neogma logo created by [Greg Magkos](https://github.com/grigmag)
- Development was made possible thanks to the open source libraries which can be found in package.json.