npm package: @nenco/nendb-native
Description: NenDB Native version - High-performance graph database with static memory allocation
Author: NenCo
Latest version: 0.2.2-beta

# 🚀 NenDB - AI-Native Graph Database

> **Lightning-fast graph database built with Data-Oriented Design (DOD) for AI workloads** ⚡

[![Zig](https://img.shields.io/badge/Zig-0.15.1-F7A41D)](https://ziglang.org/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/Version-v0.2.0--beta-green.svg)](https://github.com/Nen-Co/nen-db/releases)
[![Docker](https://img.shields.io/badge/Docker-GHCR-blue.svg)](https://ghcr.io/nen-co/nendb)
[![DOD](https://img.shields.io/badge/Architecture-Data--Oriented--Design-FF6B6B)](docs/DATA_ORIENTED_DESIGN.md)

## 📦 Package Structure

NenDB is available as focused packages so you can install only what you need.

### 🌐 `@nenco/nendb-wasm` - WebAssembly (browser / Node / Bun)
```bash
# NPM
npm install @nenco/nendb-wasm
# shorthand
npm i @nenco/nendb-wasm

# Bun (recommended)
bun add @nenco/nendb-wasm
```
- **CLI**: `npx nendb-wasm help` or `bunx nendb-wasm help`

### 🖥️ `@nenco/nendb-native` - Native (server)
```bash
# NPM
npm install @nenco/nendb-native
# shorthand
npm i @nenco/nendb-native

# Bun (recommended)
bun add @nenco/nendb-native
```
- **CLI**: `npx nendb-create help` or `bunx nendb-create help`

Use the WASM package for browser/edge environments and the native package for high-performance server deployments.

## 🎯 What is NenDB?

NenDB is a **Data-Oriented Design (DOD) graph database** built specifically for AI applications. Using Struct of Arrays (SoA) layout, component-based architecture, and SIMD optimization, it delivers:

- 🧠 **AI-Native Design**: Optimized for graph reasoning and AI workloads
- ⚡ **Data-Oriented Design**: SoA layout for maximum cache efficiency
- 🚀 **SIMD Optimization**: Vectorized operations for peak performance
- 🧩 **Component System**: Flexible entity-component architecture
- 🛡️ **Crash Safe**: WAL-based durability with point-in-time recovery
- 🔧 **Zero Dependencies**: Self-contained with minimal external requirements

## ✨ Key Features

### 🎨 **Core Capabilities**
- **Data-Oriented Design**: Struct of Arrays (SoA) layout for maximum performance
- **Component System**: Entity-component architecture for flexible data modeling
- **SIMD Operations**: Vectorized processing for peak throughput
- **Static Memory Pools**: Predictable performance with configurable memory limits
- **Write-Ahead Logging**: Crash-safe persistence with point-in-time recovery
- **Graph Algorithms**: BFS, Dijkstra, PageRank, and Community Detection
- **HTTP API**: RESTful interface using nen-net networking framework
- **CLI Interface**: Command-line tool for database management

### 🚀 **Performance Features**
- **Cache Locality**: SoA layout optimizes memory access patterns
- **SIMD Optimization**: Vectorized operations on aligned data structures
- **Hot/Cold Separation**: Frequently accessed data separated from cold data
- **Memory Pools**: Static allocation for zero GC overhead
- **Predictable Latency**: Consistent response times under load
- **Efficient Storage**: DOD-optimized data structures for graph operations
- **Cross-Platform**: Linux, macOS, and Windows support

### 🔌 **API Endpoints**
- `GET /health` - Server health check
- `GET /graph/stats` - Graph statistics
- `POST /graph/algorithms/bfs` - Breadth-first search
- `POST /graph/algorithms/dijkstra` - Shortest path
- `POST /graph/algorithms/pagerank` - PageRank centrality
- `POST /graph/algorithms/community` - Community detection

## 🚀 Quick Start

### 🎯 **DOD Demo**
Experience the power of Data-Oriented Design:

```bash
# Run the DOD performance demo
zig build dod-demo
```

This demo showcases:
- **SoA Performance**: Struct of Arrays vs Array of Structs
- **SIMD Filtering**: Vectorized node and edge filtering
- **Component System**: Entity-component architecture
- **Memory Statistics**: Cache efficiency and utilization

### 📦 **Installation**

**Linux (x86_64)**
```bash
curl -fsSL https://github.com/Nen-Co/nen-db/releases/latest/download/nen-linux-x86_64.tar.gz | tar -xz
```

**macOS (Intel)**
```bash
curl -fsSL https://github.com/Nen-Co/nen-db/releases/latest/download/nen-macos-x86_64.tar.gz | tar -xz
```

**macOS (Apple Silicon - M1/M2)**
```bash
curl -fsSL https://github.com/Nen-Co/nen-db/releases/latest/download/nen-macos-aarch64.tar.gz | tar -xz
```

**Windows PowerShell**
```powershell
Invoke-WebRequest -Uri "https://github.com/Nen-Co/nen-db/releases/latest/download/nen-windows-x86_64.zip" -OutFile "nen-windows.zip"
Expand-Archive -Path "nen-windows.zip" -DestinationPath "."
```

**🐳 Docker (Recommended)**
```bash
# Pull and run with HTTP server on port 8080
docker run --rm -p 8080:8080 --name nendb \
  -v $(pwd)/data:/data \
  ghcr.io/nen-co/nendb:latest
```

**📦 Generated Binaries**
After building with specific targets, you'll find:
- `zig-out/bin/nendb` - Executable for the current platform
- `zig-out/bin/nendb-server` - HTTP server for the current platform

**For cross-compilation, use:**
- `zig build -Dtarget=x86_64-linux-gnu` → Linux x86_64 binary
- `zig build -Dtarget=x86_64-macos-none` → macOS Intel binary (no libc)  
- `zig build -Dtarget=aarch64-macos-none` → macOS Apple Silicon binary (no libc)
- `zig build -Dtarget=x86_64-windows-gnu` → Windows x86_64 binary

**💡 Note:** The installation URLs in the Quick Start section will be updated when releases are published with the correct binary names for each platform.

### 🏃 **Running NenDB**

**Start HTTP Server**
```bash
./zig-out/bin/nendb-server
# Server will be available at http://localhost:8080
```

**CLI Commands**
```bash
# Check version
./zig-out/bin/nendb --version

# Start TCP server
./zig-out/bin/nendb serve
```

### 🧪 **Test the Server**

```bash
# Health check
curl http://localhost:8080/health

# Graph statistics
curl http://localhost:8080/graph/stats
```

## � WebAssembly (WASM) Build

NenDB compiles to a lightweight **37KB WASM module** for embedded usage in browsers and JavaScript environments:

### 📦 **Quick Start**
```html
<script type="module">
    import NenDB from 'https://github.com/Nen-Co/nen-db/releases/latest/download/nendb-wasm.js';
    
    const db = await NenDB.loadFromURL('https://github.com/Nen-Co/nen-db/releases/latest/download/nendb-wasm.wasm');
    
    // Add graph data
    const node1 = db.addNode(100);
    const node2 = db.addNode(200);
    const edge = db.addEdge(100, 200, 1.5);
    
    console.log('Memory usage:', db.getMemoryUsage(), 'bytes');
    db.destroy();
</script>
```

### 🏗️ **Build WASM**
```bash
# Build WASM module
zig build wasm

# Output: zig-out/bin/nendb-wasm.wasm (~37KB)
```

### ✨ **Features**
- **🪶 Lightweight**: Only ~37KB WASM file
- **⚡ Embedded**: SQLite-like simplicity for graph data
- **🔧 Zero Dependencies**: Pure Zig compiled to clean WASM
- **🌐 Universal**: Browser, Node.js, Deno, Bun support
- **🛡️ Static Memory**: Predictable performance in constrained environments

For detailed usage examples, see [wasm/README.md](wasm/README.md).

## �🏗️ Building from Source

### 📋 **Prerequisites**
- [Zig 0.15.1](https://ziglang.org/download/) or later
- Git

### 🔨 **Build Steps**
```bash
# Clone the repository
git clone https://github.com/Nen-Co/nen-db.git
cd nen-db

# Build the project
zig build

# Run tests
zig build test

# Build optimized release
zig build -Doptimize=ReleaseSafe

# Build WASM module (~37KB)
zig build wasm

# Build for all target platforms (Linux, macOS Intel/ARM, Windows)
zig build cross-compile

# Or build for specific targets:
zig build -Dtarget=x86_64-linux-gnu    # Linux x86_64
zig build -Dtarget=x86_64-macos-none   # macOS Intel (no libc)
zig build -Dtarget=aarch64-macos-none  # macOS Apple Silicon (no libc)
zig build -Dtarget=x86_64-windows-gnu  # Windows x86_64
```

## 🐳 Docker Support

NenDB provides official Docker images via GitHub Container Registry (GHCR):

- **Latest**: `ghcr.io/nen-co/nendb:latest`
- **Versioned**: `ghcr.io/nen-co/nendb:v0.1.0-beta`
- **Simple variant**: `ghcr.io/nen-co/nendb:simple-latest`

See [DOCKER.md](DOCKER.md) for comprehensive Docker usage instructions.

## 📚 Documentation

- 🌐 **Website**: [https://nen-co.github.io/docs/nendb/](https://nen-co.github.io/docs/nendb/)
- 📖 **API Reference**: [https://nen-co.github.io/docs/nendb/api/](https://nen-co.github.io/docs/nendb/api/)
- 🐍 **Python Client**: [https://nen-co.github.io/docs/nendb-python-driver/](https://nen-co.github.io/docs/nendb-python-driver/)
- 🐳 **Docker Guide**: [DOCKER.md](DOCKER.md)

## 🧪 Testing

```bash
# Run all tests
zig build test

# Run specific test categories
zig build test-unit
zig build test-integration
zig build test-performance

# Run with coverage
zig build test --summary all
```

## 🚀 Performance

NenDB is designed for high-performance graph operations:

- **Static Memory**: No dynamic allocations during runtime
- **Predictable Latency**: Consistent response times under load
- **Efficient Algorithms**: Optimized implementations of graph algorithms
- **Zero GC Overhead**: Static memory pools eliminate garbage collection

## 🔮 Roadmap

### 🎯 **v0.1.0-beta (Current)**
- ✅ Static memory graph database
- ✅ HTTP API server
- ✅ Basic graph algorithms
- ✅ WAL persistence
- ✅ CLI interface

### 🚀 **Future Releases**
- 🔄 Enhanced graph algorithms
- 🔍 Cypher-like query language
- 🧠 Vector similarity search
- 📊 GraphRAG support
- ⚡ Performance optimizations
- 🌐 Distributed clustering

## 🤝 Contributing

We welcome contributions! 🎉

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (`git checkout -b feature/amazing-feature`)
3. 💾 Commit your changes (`git commit -m 'Add amazing feature'`)
4. 📤 Push to the branch (`git push origin feature/amazing-feature`)
5. 🔄 Open a Pull Request

See our [Contributing Guide](https://github.com/Nen-Co/nen-db/blob/main/docs/deployment/CONTRIBUTING.md) for detailed information.

## 📄 License

This project is licensed under the APACHE 2.0 License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- 🐛 **Issues**: [GitHub Issues](https://github.com/Nen-Co/nen-db/issues)
- 📖 **Documentation**: [https://nen-co.github.io/docs/nendb/](https://nen-co.github.io/docs/nendb/)
- 💬 **Community**: [Discord](https://discord.gg/nen-co)

## 🙏 Acknowledgments

- Built with [Zig](https://ziglang.org/) for maximum performance
- Networking powered by [nen-net](https://github.com/Nen-Co/nen-net)
- I/O operations using [nen-io](https://github.com/Nen-Co/nen-io)
- JSON handling via [nen-json](https://github.com/Nen-Co/nen-json)

---

**Ready to build AI-native graph applications?** 🚀 [Get started now!](https://www.nenco.co/docs)