NEO4J_URL=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=neo4j   # optional, defaults to neo4j

4. Initialise Neogma once at application startup and export the instance:

// src/db.ts
import { Neogma } from './lib/neogma';

export const neogma = new Neogma({
  url: process.env.NEO4J_URL!,
  username: process.env.NEO4J_USERNAME!,
  password: process.env.NEO4J_PASSWORD!,
});

5. Import models wherever needed, passing the shared neogma instance to ModelFactory.

Public API

Neogma

import { Neogma } from './lib/neogma';

const neogma = new Neogma(connectionConfig: {
  url: string;
  username: string;
  password: string;
  database?: string;
});

The root connection object. Instantiate once per process and share across models. It wraps the neo4j-driver Driver and exposes it for QueryRunner and session management.

ModelFactory

import { ModelFactory } from './lib/neogma';

const Model = ModelFactory<Properties, RelatedNodes>(
  config: {
    label: string | string[];
    schema: Record<keyof Properties, SchemaField>;
    primaryKeyField: keyof Properties;
    relationships?: RelationshipsI<RelatedNodes>;
    statics?: Record<string, Function>;
    methods?: Record<string, Function>;
  },
  neogma: Neogma
);

Creates a typed model class with static methods (createOne, createMany, findOne, findMany, updateMany, deleteMany, createRelationship, findRelationships) and instance methods (save, delete, findRelationships, getDataValues). Use this as the primary entry point for all node operations.

BindParam

import { BindParam } from './lib/neogma';

const bp = new BindParam({ key: 'value' });
bp.add({ anotherKey: 123 });
const params = bp.get(); // { key: 'value', anotherKey: 123 }

Accumulates Cypher parameters across composed query fragments, deduplicated and safe. Pass the same BindParam instance to QueryBuilder and Where to share parameters across clauses.

ModelRelatedNodesI / NeogmaInstance

import type { ModelRelatedNodesI, NeogmaInstance } from './lib/neogma';

NeogmaInstance<Properties, RelatedNodes> is the type of hydrated model instances returned from findOne/createOne. ModelRelatedNodesI types the relationship configuration inside model definitions. Import these for type annotations without runtime cost.

RESERVED_INSTANCE_PROPERTIES / RESERVED_RELATIONSHIP_ALIASES

import { RESERVED_INSTANCE_PROPERTIES, RESERVED_RELATIONSHIP_ALIASES } from './lib/neogma';

Constants enumerating property names that Neogma reserves internally. Reference these when validating user-supplied schemas to avoid collisions.

Working examples

Scenario - Define and create a model with nodes

Define a typed User model with schema validation and persist a node to Neo4j.

import { Neogma, ModelFactory } from './lib/neogma';

const neogma = new Neogma({
  url: process.env.NEO4J_URL!,
  username: process.env.NEO4J_USERNAME!,
  password: process.env.NEO4J_PASSWORD!,
});

type UserProps = { id: string; name: string; email: string };

const Users = ModelFactory<UserProps, {}>({
  label: 'User',
  schema: {
    id: { type: 'string', required: true },
    name: { type: 'string', required: true },
    email: { type: 'string', required: true },
  },
  primaryKeyField: 'id',
}, neogma);

async function run() {
  const user = await Users.createOne({
    id: crypto.randomUUID(),
    name: 'Alice',
    email: 'alice@example.com',
  });
  console.log(user.id, user.name);

  user.name = 'Alicia';
  await user.save(); // persists the change
}

run();

Scenario - Find nodes and handle not-found gracefully

Use findOne and findMany with typed WHERE conditions and handle the nullable result.

import { Neogma, ModelFactory, NeogmaNotFoundError } from './lib/neogma';

// reuse Users model from previous scenario

async function findUser(email: string) {
  const user = await Users.findOne({ where: { email } });

  if (!user) {
    throw new NeogmaNotFoundError(`No user with email ${email}`);
  }

  return user.getDataValues(); // plain object, no OGM metadata
}

async function listUsers() {
  const users = await Users.findMany({ limit: 20 });
  return users.map(u => u.getDataValues());
}

Scenario - Model with relationships and eager loading

Define two models linked by a relationship, create them together, and load them with eager relationships.

import {
  Neogma,
  ModelFactory,
  ModelRelatedNodesI,
  NeogmaInstance,
} from './lib/neogma';

type OrderProps = { id: string; status: string };
const Orders = ModelFactory<OrderProps, {}>({
  label: 'Order',
  schema: {
    id: { type: 'string', required: true },
    status: { type: 'string', required: true },
  },
  primaryKeyField: 'id',
}, neogma);

type UserProps = { id: string; name: string };
type UserRelated = { Orders: ModelRelatedNodesI<typeof Orders, {}, 'PLACES'> };

const Users = ModelFactory<UserProps, UserRelated>({
  label: 'User',
  schema: {
    id: { type: 'string', required: true },
    name: { type: 'string', required: true },
  },
  primaryKeyField: 'id',
  relationships: {
    Orders: {
      model: Orders,
      direction: 'out',
      name: 'PLACES',
    },
  },
}, neogma);

async function createUserWithOrder() {
  await Users.createMany([
    {
      id: 'u1',
      name: 'Bob',
      Orders: {
        attributes: [{ id: 'o1', status: 'pending' }],
      },
    },
  ]);

  const usersWithOrders = await Users.findMany({
    where: { id: 'u1' },
    relationships: [{ alias: 'Orders', include: 'all' }],
  });

  console.log(usersWithOrders[0].Orders); // typed eager-loaded relationship data
}

Scenario - Catch typed errors

Handle specific Neogma error types to return appropriate HTTP responses.

import {
  NeogmaError,
  NeogmaConstraintError,
  NeogmaConnectivityError,
  NeogmaInstanceValidationError,
} from './lib/neogma';

async function createSafe(data: unknown) {
  try {
    await Users.createOne(data as any);
  } catch (err) {
    if (err instanceof NeogmaConstraintError) {
      return { status: 409, message: 'Duplicate key constraint violated' };
    }
    if (err instanceof NeogmaInstanceValidationError) {
      return { status: 422, message: 'Schema validation failed' };
    }
    if (err instanceof NeogmaConnectivityError) {
      return { status: 503, message: 'Database unreachable' };
    }
    if (err instanceof NeogmaError) {
      return { status: 500, message: err.message };
    }
    throw err;
  }
}

File walkthrough

• index.ts - Master barrel; re-exports every sub-module including neo4jDriver as a named namespace.
• Neogma.ts - Connection bootstrapper; wraps neo4j-driver Driver creation and exposes it.
• BindParam/BindParam.ts - Parameter accumulator for safe Cypher parameterisation.
• Errors/NeogmaError.ts - Base error class all Neogma errors extend.
• Errors/NeogmaConnectivityError.ts - Thrown when the driver cannot reach Neo4j.
• Errors/NeogmaConstraintError.ts - Thrown on unique-constraint violations from Neo4j.
• Errors/NeogmaNotFoundError.ts - Utility error for missing node results.
• Errors/NeogmaInstanceValidationError.ts - Thrown when a model instance fails revalidator schema checks.
• Literal/Literal.ts - Wraps a raw Cypher string that must not be escaped or parameterised.
• ModelFactory/ModelFactory.ts - Assembles the full model class with statics, methods, and relationship config.
• ModelFactory/model.types.ts - Core public types: NeogmaModel, NeogmaInstance, RelationshipsI, etc.
• ModelFactory/relationship.types.ts - Types for relationship configuration objects.
• ModelFactory/shared.types.ts - Shared utility types used across ModelFactory sub-modules.
• ModelFactory/findMany/ - findMany static, eager loading query builder, and hydration logic.
• ModelFactory/findOne/ - Thin wrapper around findMany returning first result.
• ModelFactory/createOne/ - Single-node creation with relationship creation support.
• ModelFactory/createMany/ - Batch node creation using a single Cypher statement.
• ModelFactory/createRelationship/ - Static to create a relationship between two existing nodes.
• ModelFactory/delete/ - Instance and static deletion methods.
• ModelFactory/deleteRelationships/ - Static to delete specific relationships between nodes.
• ModelFactory/findRelationships/ - Static and instance methods to query relationships.
• ModelFactory/update/ - Bulk property update static.
• ModelFactory/updateRelationship/ - Updates properties on relationship records.
• ModelFactory/save/ - Instance save() method: upserts dirty properties.
• ModelFactory/getDataValues/ - Strips OGM metadata, returns plain property object.
• ModelFactory/validate/ - Triggers revalidator schema validation on an instance.
• ModelFactory/validation/ - Schema validation helpers and reserved-name constants.
• ModelFactory/labelConfig/ - Normalises single/multi-label configuration.
• ModelFactory/relationshipConfig/ - Parses and validates relationship definition objects.
• ModelFactory/utils/ - Internal helpers shared by ModelFactory sub-modules.
• ModelFactory/testHelpers.ts - Exported test utilities for integration test setup.
• QueryBuilder/ - Chainable builder that emits { query, parameters } pairs.
• QueryRunner/ - Executes queries against a driver session; handles result mapping.
• Sessions/ - Helpers for obtaining sessions and running transactions.
• Where/ - Builds typed Cypher WHERE clauses from plain JS filter objects.
• utils/ - Generic utilities (object helpers, type guards) used internally.

Common pitfalls and fixes

• NeogmaConnectivityError on startup: Neo4j may not be ready before Node.js connects; wrap new Neogma(...) in a retry loop or wait for the healthcheck endpoint.
• Schema mismatch silent failures: revalidator only throws when you call instance.validate() explicitly or when saving; always define required: true for mandatory fields so creation fails fast.
• Relationship alias not found on eager load: The string passed to relationships[].alias in findMany must exactly match the key used in the model's relationships config object.
• neo4j-driver version mismatch: Neogma 1.16.x pins to a specific neo4j-driver major; installing a mismatched version causes session API errors at runtime. Pin to the version in source/ peer requirements.
• ESM/CJS interop: If your project uses "type": "module" in package.json, import neo4j-driver via the neo4jDriver namespace re-exported from index.ts or configure esModuleInterop: true in tsconfig.json.
• Reserved property names: Properties named _fields, labels, or anything in RESERVED_INSTANCE_PROPERTIES will conflict with internal OGM properties; rename them in your schema and use Cypher aliases if needed.

Vibe-coding prompt template

I have copied the Neogma OGM source into `src/lib/neogma/` in my Node.js
TypeScript project. The integration guide is in `USAGE.md`. The upstream
package is `user@example.com`.

Please help me integrate Neogma step by step:

1. Read `USAGE.md` for the full API, imports, and working examples.
2. All imports must come from `./lib/neogma` (or a relative path to
   `src/lib/neogma/index.ts`). Do not import from the npm package directly.
3. Create a `src/db.ts` that initialises `Neogma` using environment variables
   NEO4J_URL, NEO4J_USERNAME, NEO4J_PASSWORD.
4. Define a `ModelFactory` model for [DESCRIBE YOUR NODE TYPE AND PROPERTIES].
5. Add relationships to [DESCRIBE RELATED MODELS] with direction [in/out] and
   relationship name [REL_NAME].
6. Wire the model into [my Express router / service class / wherever].
7. Add typed error handling using `NeogmaConstraintError`,
   `NeogmaNotFoundError`, and `NeogmaInstanceValidationError`.
8. Show me `findMany` with eager relationship loading for [ALIAS].

Only use symbols and method signatures documented in `USAGE.md`. Do not invent
new APIs.

License and credit

Neogma is released under the MIT License. See the upstream repository for the full license text. Source: neogma on npm / themetalfleece/neogma on GitHub. This AVCP block vendors user@example.com unmodified for use as a local source dependency.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.