Introduction

Neogma is a fully type-safe Object-Graph-Mapping (OGM) framework for Neo4j and TypeScript. Define graph models using decorators, build complex queries with a fluent API, and manage relationships automatically - all with complete type safety.

What's new in v2

Neogma v2 introduces a decorator-based model definition with simple, readable class decorators:

• @Node, @PrimaryKey, @Property, @Relationship decorators - define models with plain classes
• TypeBox validation - use TypeBox schemas for powerful, type-safe validation (supports complex validations like unions, patterns, and custom constraints)
• Less boilerplate - no need for separate type interfaces; types are inferred directly from your class
• Full backwards compatibility - the ModelFactory API still works; only the old revalidator validation schema is deprecated and will be removed in a future major release

See the migration guide for step-by-step instructions on upgrading from v1.

Key features

• 🔒 Fully type-safe - complete TypeScript support with automatic type inference
• 🎀 Decorator-based models - define nodes, properties, and relationships with @Node, @Property, @Relationship
• 🔍 Flexible queries - use models, the QueryBuilder, or raw Cypher
• 🔗 Automatic relationships - create and manage complex graph structures in a single operation
• 🚀 Eager loading - load nested relationships in one query to avoid N+1 problems
• ✅ TypeBox validation - powerful schema validation (included, no extra install)
• 🛡️ Parameterized queries - all user input is passed as query parameters, never interpolated into Cypher strings, preventing injection attacks
• 🔄 Session and transaction management - built-in helpers for sessions, transactions, and automatic rollback on errors
• 🏗️ NestJS integration - first-class support via the @neogma/nest module

Quick example

import {
  Neogma,
  Node,
  PrimaryKey,
  Property,
  Relationship,
  NodeEntity,
  Type,
} from 'neogma';
import type { Related } from 'neogma';

const neogma = new Neogma({
  url: 'bolt://localhost:7687',
  username: 'neo4j',
  password: 'password',
});

@Node({ label: 'Order' })
class OrderNode extends NodeEntity {
  @PrimaryKey(Type.String()) id!: string;
  @Property(Type.String()) status!: string;
}

@Node({ label: 'User' })
class UserNode extends NodeEntity {
  @PrimaryKey(Type.String()) id!: string;

  @Property(Type.String({ minLength: 1 }))
  name!: string;

  @Relationship({ name: 'PLACED', direction: 'out', model: () => OrderNode })
  Orders!: Related<typeof OrderNode>;
}

// Register models (referenced models first)
const Orders = neogma.model(OrderNode);
const Users = neogma.model(UserNode);

// Create a user with a related order - fully typed
const user = await Users.createOne({
  id: '1',
  name: 'Alice',
  Orders: {
    attributes: [{ id: 'order-1', status: 'confirmed' }],
  },
});

// Eager-load relationships in one query
const found = await Users.findOne({
  where: { name: 'Alice' },
  relationships: { Orders: { where: { target: { status: 'confirmed' } } } },
});
console.log(found?.name); // string
console.log(found?.Orders[0].node.status); // string
// console.log(found?.bogusValue);           // TypeScript error

Example applications

Check out the example applications in the repository's /examples directory:

For AI/LLM agents

This documentation is available in machine-readable formats:

• /llms.txt - page index with titles and URLs
• /llms-full.txt - complete documentation content as plaintext markdown

Next steps

• Installation - install neogma and set up your project
• Defining models - learn the decorator-based model API
• Query Builder - build complex Cypher queries
• Migration from v1 - upgrade from neogma v1