Implexus

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

# 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:

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:

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

Then connect from a client:

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:

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:

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:

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:

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:

// 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:

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

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

By Expression

// 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/ directory:

• Overview - High-level description and design principles
• Namespaces - Namespace organization
• Core Interfaces - Entity, Engine, Storage interfaces
• Class Hierarchy - Inheritance relationships
• Path System - Path parsing and resolution
• Entity Types - Container, Document, Category, Index
• Storage Layer - DBM abstraction and serialization
• Set Operations - Entity children manipulation
• Client-Server Protocol - TCP protocol design
• File Organization - 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

# 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

# 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 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:

# 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:

# 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 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.