Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.1.9] - 2026-04-01

Added

  • Algorithm Streaming API - Stream processing support for graph algorithms
  • Real-time result streaming for large-scale graph computations
  • Memory-efficient processing for graph analytics
  • WRITE clause support - Direct write operations within queries
  • Combine reads and writes in single Cypher statements
  • Simplified update and insert patterns
  • Parallel Spectral Clustering - Enhanced community detection
  • Multi-core optimized spectral clustering algorithm
  • Improved performance on large graphs
  • Infomap algorithm - Information-theoretic community detection
  • Optimizes for minimum description length of network flows
  • Effective for hierarchical community structures
  • SLPA algorithm - Speaker-Listener Label Propagation Algorithm
  • Overlapping community detection
  • Suitable for social network analysis
  • Comprehensive Graph Algorithm API with CALL syntax
  • Unified interface for all graph algorithms
  • Consistent parameter passing and result handling
  • Support for algorithm chaining and composition

Changed

  • Reorganized N-API modules - Improved code organization
  • Enhanced algorithm test coverage - More comprehensive testing

[0.1.8] - 2026-03-29

Added

  • Optimistic Concurrency Control (OCC) - Full support for serializable snapshot isolation
  • Version tracking for all rows (nodes and relationships) with _version column
  • Read set and write set tracking per transaction
  • Commit-time validation to detect conflicts before applying changes
  • Automatic retry mechanism with exponential backoff on conflicts
  • New ConcurrencyConflict error type for conflict detection
  • Configurable OCC retry attempts via max_occ_retries in DatabaseConfig
  • Adaptive OCC Retry System - Production-ready features for high-concurrency workloads
  • Configurable adaptive retry based on conflict rate
  • Automatic retry count adjustment (3x multiplier under high contention)
  • Exponential backoff with jitter to reduce thundering herd
  • Statistics tracking for retry patterns
  • OCC Version Cache - LRU cache for version lookups (default 1000 entries)
  • Reduces table access overhead during validation
  • Automatic invalidation on writes
  • Configurable cache size
  • Lock-Free Version Reads - Atomic version storage with Acquire/Release ordering
  • Separate atomic arrays for node and relationship tables
  • Get version without any locks for high-concurrency scenarios
  • Fallback to column storage for persistence
  • JavaScript Schema API - Native interfaces for managing database schema from Node.js
  • createNodeTable() and createRelTable() for schema creation
  • dropTable() for removing tables
  • createIndex() and dropIndex() for index management
  • ensureSchema() for idempotent schema creation
  • getTables() for schema introspection
  • PropertyTypes constant for type-safe property definitions
  • OCC JavaScript API methods
  • commitWithOccSync(maxRetries) - commit with automatic retry
  • executeWithRetrySync(operationName, maxRetries) - retry wrapper
  • getOccStatistics() - retrieve conflict metrics
  • resetOccStatistics() - reset counters
  • getVersionCacheSize() / clearVersionCache() - cache management
  • OCC Statistics & Monitoring
  • Track total validations, successes, conflicts, and retries
  • Conflict rate calculation (0-100%)
  • Max retry count tracking
  • Snapshot API for monitoring with reset functionality

Changed

  • Node/edge matching - Now supports both id and _id fields
  • Error handling - Improved error messages throughout the API
  • QueryResult - Added toString() method for better console output
  • Developer infrastructure - Added Prettier and ESLint configuration
  • .prettierrc with project code style settings
  • eslint.config.mjs with recommended rules and Prettier integration
  • Added lint, lint:fix, format, and format:check scripts

Performance Improvements

  • No locks on version reads in common paths
  • Reduced validation overhead via caching
  • Better throughput under high contention with graceful degradation

Test Coverage

  • Added OCC unit tests for read/write set tracking
  • Added OCC integration tests for concurrent scenarios
  • Added SchemaAPI tests in npm/test/schema.test.js
  • Added JavaScript schema API tests in test/javascript/17-schema-api.test.js

[0.1.7] - 2026-03-28

Added

  • Query result modifiers - ORDER BY, SKIP, LIMIT clauses
  • ORDER BY with ASC/DESC modifiers for sorting results
  • SKIP clause for offsetting results
  • LIMIT clause for restricting result count
  • UnionOperator - Combines results from multiple pattern combinations
  • Variable-length path traversal operator - Supports [*..n] path patterns
  • Comprehensive TypeScript type definitions - Complete index.d.ts for CongraphDB API
  • JavaScript API CRUD test suite - Comprehensive API testing (500+ lines of tests)
  • Serialization tests - Large integers and special float values validation

Fixed

  • Relationship RETURN bug - RETURN r was returning source node instead of relationship
  • Fixed CSR structure usage for directional relationship traversal
  • Multi-node-table pattern matching - Patterns with different node types now work correctly
  • User->Project queries now properly use Project table for target nodes
  • Case-insensitive keyword parsing - All Cypher keywords now case-insensitive
  • Prevents identifier conflicts like "order" or "match"
  • Edge query compatibility - Edge queries now match both 'id' and '_id' properties
  • TypeScript definition patching - Multi-line comments now properly handled
  • Resolves "missing exported member" errors in consumers
  • WHERE clause auto-prefixing - Bare property references automatically prefixed
  • Relationship type checking - Now excludes 'REL' alongside 'Relationship'

Changed

  • Major codebase refactoring - Improved code organization and maintainability
  • Query binder split into modular structure (clause, expression, pattern, statement)
  • Query operators reorganized into subdirectories (core, non_streaming, streaming, write)
  • N-API bindings separated into dedicated module (src/napi/)
  • Value types unified and duplicates eliminated
  • Column operations split into read/write modules
  • Pattern operator split into focused modules (pattern_match, optional_match, var_length_path)
  • Query executor optimizations
  • Lazy synchronization via ensure_synced()
  • Removed redundant sync_tables_with_catalog calls
  • Added architecture documentation - docs/architecture.md for maintainability guide

Test Coverage

  • Added comprehensive JavaScript API test suite (15 test files)
  • Added serialization tests for edge cases
  • Added relationship property query tests

[0.1.6] - 2026-03-21

Fixed

  • JavaScript API exports - Fixed missing exports for CongraphDBAPI and related classes
  • CongraphDBAPI, NodeAPI, EdgeAPI, Navigator, Variable, Pattern, and CypherBuilder are now properly exported from the main package
  • TypeScript definitions now include all JavaScript API types
  • Build script automatically patches generated files to include JavaScript API exports

Changed

  • Updated build process to run patch-exports.js script after NAPI build
  • This ensures JavaScript API exports are included in all builds

[0.1.5] - 2026-03-17

Added

  • Dual Query Interface - Choose between Cypher Query Language OR JavaScript-Native API
  • Cypher: Industry-standard graph query language for complex operations
  • JavaScript API: Native methods for simple CRUD with fluent Navigator API
  • Both interfaces share the same underlying database engine
  • CongraphDBAPI class - Main API with NodeAPI, EdgeAPI, Pattern, and Navigator
    • createNode(), getNode(), getNodesByLabel(), updateNode(), deleteNode()
    • createEdge(), getEdge(), getEdges(), updateEdge(), deleteEdge()
    • find() - Pattern matching with variables
    • nav() - Fluent traversal API compatible with LevelGraph
    • v() - Variable creation for pattern matching
  • Navigator API - Fluent graph traversal
    • .out(), .in(), .both() - Relationship traversal
    • .where(), .limit() - Filtering
    • .values(), .paths(), .count() - Result methods
    • Async iteration support with for await...of
  • TypeScript definitions - Complete type definitions for all API classes
  • Complete DML operations support - CREATE, SET, DELETE, REMOVE, MERGE with ON MATCH/ON CREATE
  • CREATE nodes and relationships with properties
  • SET operations for updating existing properties and dynamically creating new ones
  • DELETE and DETACH DELETE for removing nodes and relationships
  • REMOVE operations for properties and labels
  • MERGE with conditional ON CREATE and ON MATCH clauses
  • Query execution statistics - Track query performance metrics
  • execution_time_ms - Query execution time in milliseconds
  • row_count - Number of rows returned
  • query_type - Type of query (MATCH, CREATE, SET, DELETE, etc.)
  • Property filter handling in MATCH patterns - Property filters now correctly filter results
  • MATCH (u:User {name: "Alice"}) now returns only matching nodes
  • Automatic conversion to WHERE clauses during query binding
  • Dynamic property creation - SET operations on non-existent properties auto-create columns
  • Type inference from values being set
  • Seamless schema evolution
  • CASE expressions - Full conditional logic support in queries
  • Simple CASE: CASE expression WHEN value THEN result
  • Generic CASE: CASE WHEN condition THEN result ELSE default END
  • Query result benchmark badge - Link to performance benchmark website

Fixed

  • Critical SET/DELETE timeout bug - Resolved infinite loop in SetOperator
  • Added persistent row_buffer to prevent re-scanning source on every next() call
  • Fix reduces SET operations from >60s timeout to <100ms
  • NodeTable update deadlock - Fixed complex write→read→write locking pattern
  • Implemented phase-based locking (read→create→update)
  • Eliminates deadlock conditions during dynamic property creation
  • Windows memory-mapped file issues - Fixed mmap deadlocks on Windows
  • Clone file handles before mapping operations
  • Explicitly drop old mappings before creating new ones
  • In-memory WAL file conflicts - Unique IDs prevent concurrent test conflicts
  • Parser PRIMARY KEY detection - Fixed CREATE NODE TABLE parsing
  • Parser now correctly detects PRIMARY KEY clause before closing paren
  • DELETE/DETACH performance - Optimized from O(N×M×R) to O(N+R) complexity
  • Direct CSR structure access instead of nested lookups
  • NodeScanOperator recursion - Converted to iteration to prevent stack overflow
  • Column bounds checking - Uses actual data length from lock guard

Changed

  • Enhanced table instance management for proper state sharing across queries
  • QueryExecutor now checks db registry before local cache
  • Ensures authoritative table state is always used
  • MERGE operations now properly check relationship existence before creating
  • Property filters in MATCH patterns automatically converted to BoundFilter clauses
  • QueryResult now includes statistics field for performance tracking
  • Removed test ignore flags from parser tests (PRIMARY KEY parsing now works)

Test Coverage

  • 172+ tests passing (up from 131 in v0.1.4)
  • All previously timeout-prone SET/DELETE tests now pass
  • New comprehensive DML test suite with 18 tests
  • New SET operator timeout fix tests (7 tests)
  • Property filter test suite (3 tests)
  • DML integration tests (15 tests)
  • JavaScript API test suite (28 integration tests written)

Query Interface Coverage

  • Cypher Query Language - ✅ 100% (all operators, expressions, functions)
  • JavaScript API - ✅ 100% (NodeAPI, EdgeAPI, Pattern, Navigator)
  • Node operations: create, get, getByLabel, update, delete, createMany, stream
  • Edge operations: create, get, getEdges, update, delete, createMany, getOutgoing, getIncoming, stream
  • Pattern matching: find() with variables
  • Navigator API: fluent traversal (out/in/both), filtering, path finding
  • TypeScript definitions: Complete type coverage

Cypher Feature Coverage

  • CREATE with properties - ✅ 100%
  • SET operations - ✅ 100%
  • DELETE/DETACH DELETE - ✅ 100%
  • REMOVE operations - ✅ 100%
  • MERGE with ON MATCH/ON CREATE - ✅ 100%
  • Property filters in patterns - ✅ 100%
  • Dynamic property creation - ✅ 100%
  • CASE expressions - ✅ 100%
  • Query statistics - ✅ 100%

Breaking Changes

  • None - All changes are backwards compatible

[0.1.4] - 2026-03-15

Fixed

  • Fixed GitHub Actions artifact naming conflict in release workflow
  • Changed artifact names to use full target identifier instead of os-architecture pattern
  • Resolves duplicate artifact name issue for linux-gnu and linux-musl builds

Changed

  • Version synchronization across all CongraphDB packages

[0.1.3] - 2026-03-15

Added

  • Path finding functions with BFS-based algorithms
  • shortestPath() - Find the shortest path between two nodes
  • allShortestPaths() - Find all shortest paths at minimum length
  • Configurable max path length with [*..n] syntax
  • Support for all relationship directions (Outgoing, Incoming, Undirected)
  • Pattern comprehensions with full relationship pattern support
  • Single-node patterns: [(n:Label) | n.prop]
  • Relationship patterns: [(a)-[:REL]->(b) | b.prop]
  • Multi-hop patterns: [(a)-[:KNOWS]->(b)-[:FOLLOWS]->(c) | c]
  • WHERE clause support within comprehensions
  • Outer variable scope - reference variables from outer query context
  • Temporal types and functions
  • Date type for calendar dates (year, month, day)
  • DateTime type for timestamps (milliseconds since epoch)
  • Duration type for time spans
  • date() function - Parse or create date values
  • datetime() function - Get current datetime or parse datetime strings
  • timestamp() function - Get current Unix timestamp in milliseconds
  • duration() function - Parse ISO 8601 duration strings
  • Multi-label nodes support
  • Nodes can have multiple labels: (u:User:Admin:Premium)
  • labels() function returns all labels as a list
  • has_label(), add_label(), remove_label() methods on NodeValue
  • Regex matching with =~ operator
  • Pattern matching using regular expressions
  • Returns boolean for match success/failure
  • Map literals in Cypher queries
  • Create maps with {key: value, ...} syntax
  • Support for arbitrary key-value pairs
  • PathValue type for representing graph paths
  • Contains ordered nodes and relationships
  • length(), node_count(), start_node(), end_node() methods
  • Support for single-node paths (path from node to itself)

Changed

  • Enhanced Labels function to return all labels for multi-label nodes
  • ExpressionEvaluator now supports table access for graph-aware evaluation
  • Path finding functions now use physical operators instead of placeholders
  • Pattern comprehensions now preserve outer variable scope properly

Dependencies

  • Added regex = "1.11" for regex pattern matching support

Test Coverage

  • Added 30+ new tests covering all new features
  • Total: 131 tests passing (108 unit + 17 integration + 6 end-to-end)

Cypher Feature Coverage

  • Path finding (shortestPath, allShortestPaths) - ✅ 100%
  • Pattern comprehensions - ✅ 100% (single-node + relationship patterns)
  • Variable scope - ✅ 100% (outer variable reference)
  • Temporal types - ✅ 100%
  • Multi-label nodes - ✅ 100%
  • Regex matching - ✅ 100%
  • Map literals - ✅ 100%

[0.1.2] - 2026-03-14

Changed

  • Version bump to 0.1.2

[0.1.1] - 2025-03-14

Fixed

  • Fixed CI/CD pipeline issues for cross-platform builds
  • Fixed release workflow binary stripping command
  • Updated Node.js version requirement to 20.12.0+
  • Fixed flaky HNSW graph index test
  • Resolved all Clippy linting warnings
  • Added JavaScript test files for CI

Changed

  • Applied cargo fmt to all Rust source files for consistent code style
  • Updated CI to test only Node.js 20 (dependencies require 20.12.0+)

[0.1.0] - 2025-03-14

Added

  • Initial release of CongraphDB - A high-performance, embedded graph database for Node.js
  • Native Node.js bindings via napi-rs for maximum performance
  • Support for Cypher query language for graph operations
  • HNSW (Hierarchical Navigable Small World) index for vector similarity search
  • ACID transactions with write-ahead logging (WAL) for data durability
  • Memory-mapped I/O for efficient file-based storage
  • Columnar storage architecture optimized for analytical workloads
  • Single-file database format (.cgraph) similar to SQLite
  • In-memory database mode using :memory: path
  • Configurable buffer manager size for memory optimization
  • Compression support for stored data
  • Read-only database mode
  • Checkpoint API for manual WAL flushing
  • Version information APIs (getVersion(), getStorageVersion())
  • TypeScript type definitions for full IDE support

Features

  • Embedded & Serverless - No separate database process required
  • Cross-platform - Prebuilt binaries for Windows, macOS, and Linux
  • Memory Safe - Built with Rust for guaranteed memory safety
  • AI-Ready - Built-in vector similarity search for embeddings and AI workloads

Supported Platforms

  • Windows (x64, arm64)
  • macOS (x64, arm64, universal)
  • Linux (x64, arm64) - GNU and MUSL variants

Documentation

  • Comprehensive README with usage examples
  • API reference for Database, Connection, and QueryResult classes
  • Cypher query language examples
  • Building from source instructions

Installation

npm install congraphdb

Quick Start

const { Database } = require('congraphdb');

const db = new Database('./my-graph.db');
await db.init();

const conn = db.createConnection();
await conn.query('CREATE (u:User {name: "Alice"})');
  • Repository: https://github.com/congraph-ai/congraphdb
  • NPM Package: https://www.npmjs.com/package/congraphdb
  • Documentation: https://congraph-ai.github.io/congraphdb-docs/

[Unreleased]

Planned Features

  • Complete DML operations (MERGE, SET, DELETE, REMOVE execution)
  • OPTIONAL MATCH with variable-length paths
  • Graph analytics algorithms (PageRank, community detection, etc.)
  • Distributed query execution
  • GraphQL endpoint
  • WebAssembly support for browser environments
  • Additional index types (B-tree, hash, etc.)
  • Query optimization and execution plan visualization
  • Backup and restore utilities
  • Database migration tools