📝 README.md, varo: Fix documentation errors and add new README

- Corrected `Data::<ty()` to `Data::ty()` and added quotes around the example string in main README.
- Changed "derivation" to "derive macro" in the main README explanation.
- Updated all Nix run commands to use full `git+https` URLs with `.git` extension.
- Created a new README for the `varo` crate describing its planned purpose.

2025-08-11 13:23:16 +03:00

2.6 KiB

Raw Blame History

Vanth

Vanth is a content-addressed database as a library designed for entity-component-system (ECS) applications.

It is currently experimental and should not be used for anything.

Library usage

Any type that implements serde::Serialize can be hashed using vanth::hash to produce a vanth::ContentHash.

let x = "hello";
assert_eq!(vanth::hash(&x).hex(), "ea8f163db38682925e4491c5e58d4bb3506ef8c14eb78a86e908c5624a67200f");

Derive or implement the vanth::Vanth trait for types you want to store in the database.

use serde::{Deserialize, Serialize};
use vanth::Vanth;

#[derive(Deserialize, Serialize, Vanth)]
struct Data {
    value: u32,
}

This generates a method Vanth::ty() which returns a vanth::Ty. This should represent the type's fully qualified name - its module path followed by the type itself and any generics it has. E.g. Data::ty().to_string() could return "my::crate::module::Data".

The derive macro only works for basic types right now and is not implemented for std types. Moving or renaming types or modules will change the type name, necessitating a database migration. This is not supported yet.

This should be used with caution. There are good reasons why std::any::TypeId is opaque.

Database storage

use vanth::store::{Store, StoreParams};

// Or use `Store::in_memory`.
let mut store = Store::sqlite_from_path(
    "path/to/my_database.sqlite".into(),
    StoreParams { create_if_not_exists: true, ..Default::default() },
);
let hash = store.write(Data { value: 5 }).unwrap();
let my_data: Data = store.get_from_hash(hash).unwrap();

CLI usage

You can run the Vanth CLI with Nix using nix run git+https://git.mascully.com/mascully/vanth.git.

Use -- to pass arguments, e.g. nix run git+https://git.mascully.com/mascully/vanth.git -- --help.

Syntax

Write a component to the database:

$ vanth write --db /path/to/db.sqlite --ty my::type::Name --value '{ "field": "value" }'
a1cf81d8afe4e72604ea5c13bbd9b6cce14bd98c3a2f036f7156c4464a88ec09

Get a component from the database:

$ vanth get --db /path/to/db.sqlite --ty my::type::Name a1cf81d8afe4e72604ea5c13bbd9b6cce14bd98c3a2f036f7156c4464a88ec09
{"field":"value"}

Get all components of a type from the database:

$ vanth get-all --db /path/to/db.sqlite --ty my::type::Name
{"field":"value1"}
{"field":"value2"}
{"field":"value3"}

Delete a component by its content hash:

$ vanth delete --db /path/to/db.sqlite ea8f163db38682925e4491c5e58d4bb3506ef8c14eb78a86e908c5624a67200f

Delete all components of a type:

$ vanth delete-all --db /path/to/db.sqlite --ty my::type::Name