@graphium/core

English · 한국어

Graph-native OGM with multiple graph DB backends

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

@graphium/core is the backend-neutral OGM runtime core used by graph-native backends such as @graphium/neo4j, and by future graph-native packages such as @graphium/neptune.

It is not the main getting-started package for application users.

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(). Enable: Graph.create({ autoFlush: true }).
• lazy relationship loading — opt-in lazy Promise<T[]> on first access (requires autoFlush).
• Observability detectors — slow-query, N+1, and Neo4j EXPLAIN cost detectors; enable all via Graph.create({ profile: 'production' }).
• ReadOnlyRepository / WritableRepository interface split — BaseRepository<T> implements both; find/findOne/count go through the read-only surface, mutations through the writable surface.
• PII redaction extended — SENSITIVE_KEY_PATTERN now matches cardNumber, ssn, cvv, email, phone, dob, and birth* in QueryError / log redaction.
• Schema diff engine — buildDesiredSchemaSpec + diffSchema (@graphium/core/migration) powering the new migrate:diff CLI subcommand (Phase 4).

Owns

• Graph lifecycle and configuration
• GraphManager core CRUD/orchestration behavior
• BaseRepository core behavior
• unit of work, identity map, transactions, request context
• seeding, logging, metrics, error handling
• backend-neutral driver/store runtime contracts
• graph decorators and metadata declarations (the schema layer)
• the Bolt transport, Cypher AST/query builder, and Gremlin DSL/renderer, exposed on enforced sub-paths: @graphium/core/bolt, @graphium/core/cypher, @graphium/core/cypher/ogm, @graphium/core/gremlin, @graphium/core/gremlin/ogm
• the unified BackendCapabilities capability model and the Capability Conformance Suite (src/__tests__/conformance/)

Does Not Own

• backend-specific raw query APIs
• backend-specific migrators

Those live in backend packages such as @graphium/neo4j.

Who Should Use It Directly

• backend package authors
• framework/integration package authors
• advanced users building on Graph internals

Most application code should start from a user-facing package such as @graphium/neo4j.

Related Docs

• Root README
• Neo4j package