@graphium/nestjs

English · 한국어

Graph-native OGM with multiple graph DB backends

Explicit persistence model — no Proxy magic, no N+1 footguns

@graphium/nestjs groups the NestJS entrypoints for the graph-native OGM track and the MikroORM + AGE adapter track.

The root package is a namespace facade. Use the family subpaths directly in application code.

What's new in 0.4

• Read-only repository inject — @InjectRepository(User, { mode: 'read-only' }) returns a ReadOnlyRepository<User>. Calls to persist/remove/flush throw ConfigurationError (Phase 6.1 / 6.2).
• GraphError-baseclass exception filter — GraphQueryErrorFilter uses @Catch(GraphError) and now catches every GraphError subclass (MetadataError, ValidationError, CapabilityError, MigrationError, OptimisticLockError, PartialPersistError).
• OTel metrics auto wire-up — GraphModule.forRoot({ metrics: { provider } }) automatically wires GraphiumMetricsAdapter into the OGM hook chain (Phase 6.6).

Entry Points

| Entry | Role | Status | | ---------------------------- | ------------------------------------ | -------------- | | @graphium/nestjs/ogm | graph-native Nest module and tokens | usable | | @graphium/nestjs/mikro-orm | Mikro adapter Nest module and tokens | experimental |

OGM Quickstart

import { Injectable, Module } from '@nestjs/common'
import { GraphModule, InjectGraphManager } from '@graphium/nestjs/ogm'
import { Neo4jDriver, Node, PrimaryKey, Property } from '@graphium/neo4j'
import type { GraphManager } from '@graphium/neo4j'

@Node({ label: 'User' })
class User {
  @PrimaryKey({ type: 'uuid', generated: true })
  id!: string

  @Property({ type: 'string' })
  email!: string
}

@Injectable()
class UsersService {
  constructor(@InjectGraphManager() private readonly gm: GraphManager) {}

  public list() {
    return this.gm.find(User)
  }
}

@Module({
  imports: [
    GraphModule.forRoot({
      backend: 'neo4j',
      driver: Neo4jDriver.create({
        uri: 'bolt://127.0.0.1:7687',
        username: 'neo4j',
        password: 'password',
      }),
      entities: [User],
      autoRequestContext: true,
    }),
    GraphModule.forFeature([User]),
  ],
  providers: [UsersService],
})
export class AppModule {}

autoDriver auto-discovers only @graphium/neo4j and @graphium/memgraph. For Neptune, pass backend and driver explicitly. The private Cosmos boundary remains opt-in and is not part of auto discovery.

Named Connections

connectionName is part of the public OGM contract.

imports: [
  GraphModule.forRoot({
    backend: 'neo4j',
    driver: primaryDriver,
    entities: [User],
  }),
  GraphModule.forRoot({
    connectionName: 'analytics',
    backend: 'neo4j',
    driver: analyticsDriver,
    entities: [User],
  }),
  GraphModule.forFeature([User]),
  GraphModule.forFeature([User], 'analytics'),
]

constructor(
  @InjectGraphManager() private readonly primary: GraphManager,
  @InjectRepository(User, 'analytics')
  private readonly analyticsUsers: Repository<User>
) {}

Repository, graph, and manager tokens are all scoped by entity + connectionName. Application shutdown closes every registered graph connection automatically.

ORM Quickstart

Use the ORM family modules when the host ORM remains the source of truth.

• @graphium/nestjs/mikro-orm

Those entrypoints attach the package-owned graph facade and expose it through InjectGraph().

Public Surface

@graphium/nestjs/ogm exports:

• GraphModule
• GraphModuleOptions
• GraphModuleAsyncOptions
• GraphAutoDriverOptions
• InjectGraph
• InjectGraphManager
• InjectRepository
• getGraphToken
• getGraphManagerToken
• getRepositoryToken

@graphium/nestjs/mikro-orm exports:

• GraphModule (canonical docs name)
• GraphMikroModule (explicit alias)
• GraphMikroOrmModule (deprecated compatibility alias)
• GraphModuleOptions
• GraphModuleAsyncOptions
• InjectGraph
• getGraphToken

Related Docs

• Root README
• NeOGM migration guide
• Example blog app