# Implexus

A path-based document database library and engine for Vala.

## Features

- **Path-based identification**: Access entities using intuitive paths like `/users/john`
- **Four entity types**: Container, Document, Category, and Index
- **Dual operation modes**: Embedded (in-process) and client/server (remote TCP)
- **Transaction support**: ACID transactions with commit/rollback
- **Expression-based queries**: Filter entities using Invercargill.Expressions
- **Binary serialization**: Efficient storage format
- **No Libgee dependency**: Uses Invercargill.DataStructures for collections

## Dependencies

- GLib 2.0
- GObject 2.0
- GIO 2.0
- Invercargill-1 (collections, expressions, Element types, JSON)

## Installation

### From Source

```bash
# Configure build
meson setup build

# Compile
meson compile -C build

# Install (requires root privileges)
meson install -C build
```

### Dependencies

Ensure `invercargill-1` is installed and available in your system's package configuration.

## Quick Start

### Embedded Mode

Embedded mode runs the database in-process, ideal for single-application use:

```vala
using Implexus;
using Implexus.Core;
using Implexus.Engine;

public static int main(string[] args) {
    try {
        // Create embedded engine configuration
        var config = EngineConfiguration.embedded("./my_database");
        
        // Create engine
        Core.Engine engine = EngineFactory.create(config);
        
        // Get root container and create entities
        var root = engine.get_root();
        var users = root.create_container("users");
        
        // Create a document with type label
        var john = users.create_document("john", "User");
        john.set_entity_property("email", new Invercargill.NativeElement<string>("john@example.com"));
        john.set_entity_property("age", new Invercargill.NativeElement<int>(30));
        
        // Query by type
        foreach (var entity in engine.query_by_type("User")) {
            stdout.printf("User: %s\n", entity.name);
        }
        
        return 0;
    } catch (Error e) {
        stderr.printf("Error: %s\n", e.message);
        return 1;
    }
}
```

### Client/Server Mode

For multi-client access, run the server daemon:

```bash
# Start server
implexusd --port 9876 --storage /path/to/database
```

Then connect from a client:

```vala
using Implexus;
using Implexus.Core;
using Implexus.Engine;

public static int main(string[] args) {
    try {
        // Create remote engine configuration
        var config = EngineConfiguration.remote("localhost", 9876);
        
        // Create engine - same API as embedded mode!
        Core.Engine engine = EngineFactory.create(config);
        
        // Use the identical API
        var root = engine.get_root();
        var users = root.create_container("users");
        
        // ... rest of code is identical to embedded mode
        
        return 0;
    } catch (Error e) {
        stderr.printf("Error: %s\n", e.message);
        return 1;
    }
}
```

## Entity Types

### Container

A container for child entities, similar to a filesystem folder:

```vala
var root = engine.get_root();
var users = root.create_container("users");
var projects = root.create_container("projects");
```

### Document

An object with properties and a type label for querying:

```vala
var doc = users.create_document("john", "User");
doc.set_entity_property("email", new Invercargill.NativeElement<string>("john@example.com"));
doc.set_entity_property("active", new Invercargill.NativeElement<bool?>(true));

// Retrieve properties
var email = doc.get_entity_property("email");
if (email != null) {
    stdout.printf("Email: %s\n", ((!) email).to_string());
}
```

### Category

Auto-generated categories based on expression evaluation:

```vala
var category = root.create_category("active_users", "User", "active==true");
// category.children() returns all User documents where active==true
```

### Index

Text search results organized as a container:

```vala
var index = root.create_index("search_results", "search terms");
// index contains documents matching the search terms
```

## Path-Based Access

Access any entity using its path:

```vala
// Get entity by path
var path = new EntityPath("/users/john");
var entity = engine.get_entity(path);

// Check existence
bool exists = engine.entity_exists(new EntityPath("/users/john"));
```

## Transactions

Group multiple operations in a transaction:

```vala
var tx = engine.begin_transaction();

try {
    var jane = users.create_document("jane", "User");
    jane.set_entity_property("email", new Invercargill.NativeElement<string>("jane@example.com"));
    
    var bob = users.create_document("bob", "User");
    bob.set_entity_property("email", new Invercargill.NativeElement<string>("bob@example.com"));
    
    tx.commit();
} catch (Error e) {
    tx.rollback();
    stderr.printf("Transaction failed: %s\n", e.message);
}
```

## Querying

### By Type

```vala
foreach (var entity in engine.query_by_type("User")) {
    stdout.printf("Found user: %s\n", entity.name);
}
```

### By Expression

```vala
// Find active users over 25
foreach (var entity in engine.query_by_expression("User", "active==true && age>25")) {
    stdout.printf("Active user over 25: %s\n", entity.name);
}
```

## Architecture

Implexus is organized into the following namespaces:

| Namespace | Description |
|-----------|-------------|
| `Implexus.Core` | Core interfaces: Engine, Entity, EntityPath, Transaction |
| `Implexus.Entities` | Entity implementations: Container, Document, Category, Index |
| `Implexus.Storage` | Storage layer: Storage, DBM interfaces, binary serialization |
| `Implexus.Engine` | Engine implementations: EmbeddedEngine, RemoteEngine |
| `Implexus.Protocol` | Client-server protocol: Message, Request, Response |
| `Implexus.Server` | Server implementation: Server, ClientHandler |

For detailed design documentation, see the [Architecture/](Architecture/) directory:

- [Overview](Architecture/01-Overview.md) - High-level description and design principles
- [Namespaces](Architecture/02-Namespaces.md) - Namespace organization
- [Core Interfaces](Architecture/03-Core-Interfaces.md) - Entity, Engine, Storage interfaces
- [Class Hierarchy](Architecture/04-Class-Hierarchy.md) - Inheritance relationships
- [Path System](Architecture/05-Path-System.md) - Path parsing and resolution
- [Entity Types](Architecture/06-Entity-Types.md) - Container, Document, Category, Index
- [Storage Layer](Architecture/07-Storage-Layer.md) - DBM abstraction and serialization
- [Set Operations](Architecture/08-Set-Operations.md) - Entity children manipulation
- [Client-Server Protocol](Architecture/09-Client-Server-Protocol.md) - TCP protocol design
- [File Organization](Architecture/10-File-Organization.md) - Project structure

## Project Structure

```
implexus/
├── src/                    # Source files
│   ├── Core/               # Implexus.Core namespace
│   ├── Entities/           # Implexus.Entities namespace
│   ├── Storage/            # Implexus.Storage namespace
│   ├── Engine/             # Implexus.Engine namespace
│   ├── Protocol/           # Implexus.Protocol namespace
│   └── Server/             # Implexus.Server namespace
├── examples/               # Example programs
│   └── BasicUsage.vala     # Comprehensive usage example
├── tools/                  # CLI tools
│   └── implexusd/          # Server daemon
├── tests/                  # Test suite
├── vapi/                   # Custom VAPI files
├── Architecture/           # Architecture documentation
├── meson.build             # Build configuration
└── README.md               # This file
```

## Building from Source

### Requirements

- Meson build system
- Vala compiler
- C compiler (gcc or clang)
- Invercargill-1 library

### Build Steps

```bash
# Setup build directory
meson setup build

# Compile
meson compile -C build

# Run tests
meson test -C build

# Install (optional)
meson install -C build
```

## Running Tests

```bash
# Run all tests
meson test -C build

# Run with verbose output
meson test -C build -v

# Run specific test
meson test -C build implexus_test
```

## Examples

See [examples/BasicUsage.vala](examples/BasicUsage.vala) for a comprehensive example demonstrating:

- Mode selection (embedded vs remote)
- Entity creation and deletion
- Property management
- Path-based access
- Transactions
- Querying by type and expression

Build and run the example:

```bash
# Build
meson compile -C build

# Run in embedded mode
./build/examples/basicusage

# Run in remote mode (requires running server)
./build/examples/basicusage --remote --host localhost --port 9876
```

## Server Daemon

The `implexusd` daemon provides TCP access to the database:

```bash
# Basic usage
implexusd --port 9876 --storage /path/to/database

# Options
# --port PORT       TCP port to listen on (default: 9876)
# --storage PATH    Path to database storage
# --host HOST       Host to bind to (default: 0.0.0.0)
```

## License

MIT License - see [LICENSE](LICENSE) for details.

```
Copyright (c) 2026 Implexus Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
```