Type-safe Java helper annotation for ArcadeDB - feedback welcome

[ivan-velikanov]

@lvca and ArcadeData team

Been working on a small annotation-based library for ArcadeDB. Repo: https://github.com/xyz-jphil/datahelper

Motivation: I like static typing, IDE autocomplete, refactor-rename, find-usages. Wanted field references as first-class objects rather than strings.

What it looks like:

@ArcadeData
public final class Person extends Person_A {
    String name;
    String email;
    Address homeAddress;  // embedded type
    List<PhoneNumber> phones;

    public static final TypeDef<Person> TYPEDEF =
        schemaBuilder().unique($email).lsmIndex($name).__();
}

@ArcadeData
public final class Address extends Address_A {
    String city;
    String zip;
    // No TYPEDEF needed - auto-registered when Person registers
}

One annotation. Generates $email, $name, $homeAddress as static field objects. Class definition becomes single source of truth for schema, accessors, and field metadata.

Field symbols - use either way:

// Type-safe field objects
.whereEq($email, value)
.__($age, 29)

// Or as strings via .__ suffix (both work, pick your preference)  
.property($email.__)      // equivalent to .property("email")
.orderBy($createdAt.__)   // equivalent to .orderBy("createdAt")

Chained access for embedded types:

// Type-safe path traversal
.property($homeAddress.__($city).__)   // "homeAddress.city"

// Or just use the string directly - both work
.property("homeAddress.city")

// Deeper nesting (3 levels): address → location → country
.property($address.___($location).__($country).__)
//                 ^^^ chain       ^^ terminal

---

CRUD Examples

Create (fluent builder + upsert):

var person = new Person()
    .name("Alice")
    .email("[email protected]")
    .age(28)
    .createdAt(System.currentTimeMillis());

db.transaction(() -> {
    person.in(db).whereEq($email, person.email()).upsert();
});

Read (query + load):

var docs = db.select()
    .fromType(Person.__)
    .where().property($email.__).eq().value("[email protected]")
    .documents();

if (docs.hasNext()) {
    var person = Person.fromDoc(docs.next());
    System.out.println(person.name());  // fluent getter
}

Update (specific fields only):

db.transaction(() -> {
    Update.use(db)
        .select(Person.__)
        .whereEq($email, "[email protected]")
        .upsert()
        .__($age, 29)
        .__($name, "Alice Updated")
        .saveDocument();
});

Update (from partial object):

var partial = new Person().age(30).name("New Name");

db.transaction(() -> {
    partial.in(db)
        .whereEq($email, "[email protected]")
        .from($age, $name)  // only these fields
        .upsert();
});

Update nested field:

db.transaction(() -> {
    Update.use(db)
        .select(Person.__)
        .whereEq($email, "[email protected]")
        .upsert()
        .__($homeAddress.__($city).__, "Seattle")
        .saveDocument();
});

Query with ordering:

var docs = db.select()
    .fromType(Person.__)
    .orderBy($createdAt.__, false)  // descending
    .limit(10)
    .documents();

Query nested field:

// Type-safe
var docs = db.select()
    .fromType(Person.__)
    .where().property($homeAddress.__($city).__).eq().value("Seattle")
    .documents();

// Or string-based - same result
var docs = db.select()
    .fromType(Person.__)
    .where().property("homeAddress.city").eq().value("Seattle")
    .documents();

---

Schema registration:

// Just pass top-level types - dependencies auto-detected
InitDoc.initDocTypes(db,
    Person.TYPEDEF,
    Order.TYPEDEF
);
// Address, PhoneNumber auto-registered first (dependency order)

---

Schema definition is intentionally explicit rather than annotation-based. TypeDef in code is more transparent - you see exactly what indexes exist. May add annotation sugar later.

Accessors: Generates both classic POJO getters/setters (Jackson-compatible) and fluent chainable methods. No Lombok dependency.

Zero-reflection nested types: Embedded objects and List<NestedType> work automatically. Schema registration detects dependencies and registers in correct order.

Graph support: @ArcadeData(type = VERTEX) and @ArcadeData(type = EDGE) for schema definition. Runtime graph ops use ArcadeDB's native API.

Would appreciate feedback on the API design or rough edges.