@graphium/neptune

English · 한국어

Graph-native OGM with multiple graph DB backends

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

@graphium/neptune is the Amazon Neptune Gremlin backend for Graphium.

What's new in 0.4

• Unlimited find() by default — the 0.3 implicit 10 000-row cap is removed. Opt back in via Graph.create({ defaultMaxRows: 10_000 }).
• autoFlush dirty tracking — opt-in ES Proxy wrapper that flushes property mutations without explicit persist() (Graph.create({ autoFlush: true })).
• Read-only repositories — @InjectRepository(User, { mode: 'read-only' }) for NestJS (Phase 6.1).
• Raw Gremlin @security JSDoc — gremlinRaw() carries the uniform @security WARNING tag (Phase 5.4).

Status

experimental

Core functionality is working. CI runs against a generic Gremlin Server. Neptune-specific acceptance tests require a live Neptune endpoint.

Install

pnpm add @graphium/neptune reflect-metadata

Quickstart

import 'reflect-metadata'
import {
  Graph,
  NeptuneDriver,
  Node,
  PrimaryKey,
  Property,
} from '@graphium/neptune'

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

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

const graph = await Graph.create({
  driver: NeptuneDriver.create({
    endpoint:
      'wss://your-cluster.cluster-id.region.neptune.amazonaws.com:8182/gremlin',
  }),
  entities: [User],
})

const gm = graph.getManager()

await gm.save(User, { email: '[email protected]' })
const users = await gm.find(User, { where: { email: '[email protected]' } })

SigV4 IAM Authentication

import { createNeptuneSigV4HeadersFactory } from '@graphium/neptune'

NeptuneDriver.create({
  endpoint: 'wss://your-cluster...',
  headersFactory: createNeptuneSigV4HeadersFactory({
    region: 'us-east-1',
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    },
  }),
})

STS Credential Rotation (long-lived connections)

When using short-lived credentials from AWS STS AssumeRole, use createNeptuneSigV4HeadersFactoryWithRefresh together with credentialsFactory on the connection so that fresh credentials are fetched on every WebSocket handshake — including automatic re-handshakes triggered by auth failures (HTTP 401/403).

import { createNeptuneSigV4HeadersFactoryWithRefresh } from '@graphium/neptune'
import { STSClient, AssumeRoleCommand } from '@aws-sdk/client-sts'

const sts = new STSClient({ region: 'us-east-1' })

async function fetchCredentials() {
  const { Credentials } = await sts.send(
    new AssumeRoleCommand({
      RoleArn: 'arn:aws:iam::123456789012:role/NeptuneRole',
      RoleSessionName: 'graphium-session',
    })
  )
  return {
    accessKeyId: Credentials!.AccessKeyId!,
    secretAccessKey: Credentials!.SecretAccessKey!,
    sessionToken: Credentials!.SessionToken,
  }
}

NeptuneDriver.create({
  endpoint: 'wss://your-cluster...',
  // headersFactory: called on every WS connect — returns fresh SigV4 headers
  headersFactory: createNeptuneSigV4HeadersFactoryWithRefresh({
    region: 'us-east-1',
    endpoint: 'wss://your-cluster...',
    credentialsFactory: fetchCredentials,
  }),
  // credentialsFactory: called on auth-failure to trigger close + re-handshake
  credentialsFactory: fetchCredentials,
  sigV4Region: 'us-east-1',
})

When Neptune returns a 401/403 during an active connection, the connection automatically closes the WebSocket and reconnects with a new SigV4 signature produced by credentialsFactory. The caller receives the original auth error; the next operation will use the fresh connection.

Capabilities

• CRUD operations: create, save, find, findOne, delete
• Relationship persistence
• Transactions (NeptuneTransaction, TransactionManager, @Transactional)
• Find session (cursor-based pagination)
• Schema migration via Migrator and GremlinMigration
• Bytecode traversal submission mode
• Auto-driver from environment variables (createNeptuneDriverFromEnv)
• Error classification and retry support
• NestJS adapter via graphNestOgmAdapter

Auto-Driver (env-based)

NEPTUNE_ENDPOINT=wss://your-cluster.neptune.amazonaws.com:8182/gremlin
NEPTUNE_REGION=us-east-1

import { createNeptuneDriverFromEnv } from '@graphium/neptune/auto'

Public API

• Graph, GraphManager, Repository
• NeptuneDriver, NeptuneConnection, NeptuneTransaction
• NeptuneResultAdapter, NeptuneTypeConverter, NeptuneTransactionStrategy
• NEPTUNE_CAPABILITIES
• TransactionManager, Transactional, TransactionPropagation
• createNeptuneSigV4HeadersFactory, createNeptuneSigV4HeadersFactoryWithRefresh
• Migrator, GremlinMigration
• createNeptuneDriverFromEnv, resolveNeptuneConnectionOptionsFromEnv
• graphNestOgmAdapter

Related Docs

• Root README