Crate atomic_lib
source · [−]Expand description
atomic_lib
helps you to get, store, serialize, parse and validate Atomic Data.
See the Atomic Data Docs for more information.
Features
- Two stores for Atomic Data:
- In-memory Store for getting / setting data. Useful for client applications.
- On disk [Db], powered by Sled. Useful for applications that persist Atomic Data, such as
atomic-server
.
- serialize and parse tools for JSON-AD, plain JSON, RDF, Turtle, N-Triples and JSON-LD.
- Resource with getters, setters and a
.save
function that creates Commits. - Value converts Atomic Data to Rust native types
- Validate Atomic Schema
- Commits (transactions / delta’s / changes / updates / versioning / history).
- [plugins] system (although not very mature)
- collections (pagination, sorting, filtering)
- Querying (using triple pattern fragments) (see storelike::Query)
- [plugins::invite] for sharing
- hierarchy for authorization
- [crate::endpoints::Endpoint] for custom API endpoints
- [config::Config] files.
Getting started
// Import the `Storelike` trait to get access to most functions
use atomic_lib::Storelike;
// Start with initializing the in-memory store
let store = atomic_lib::Store::init().unwrap();
// Pre-load the default Atomic Data Atoms (from atomicdata.dev),
// this is not necessary, but will probably make your project a bit faster
store.populate().unwrap();
// We can create a new Resource, linked to the store.
// Note that since this store only exists in memory, it's data cannot be accessed from the internet.
// Let's make a new Property instance! Let's create "age".
let mut new_property = atomic_lib::Resource::new_instance("https://atomicdata.dev/classes/Property", &store).unwrap();
// And add a description for that Property
new_property.set_propval_shortname("description", "the age of a person", &store).unwrap();
// A subject URL for the new resource has been created automatically.
let subject = new_property.get_subject().clone();
// Now we need to make sure these changes are also applied to the store.
// In order to change things in the store, we should use Commits,
// which are signed pieces of data that contain state changes.
// Because these are signed, we need an Agent, which has a private key to sign Commits.
let agent = store.create_agent(Some("my_agent")).unwrap();
store.set_default_agent(agent);
let _fails = new_property.save_locally(&store);
// But.. when we commit, we get an error!
// Because we haven't set all the properties required for the Property class.
// We still need to set `shortname` and `datatype`.
new_property.set_propval_shortname("shortname", "age", &store).unwrap();
new_property.set_propval_shortname("datatype", atomic_lib::urls::INTEGER, &store).unwrap();
new_property.save_locally(&store).unwrap();
// Now the changes to the resource applied to the store, and we can fetch the newly created resource!
let fetched_new_resource = store.get_resource(&subject).unwrap();
assert!(fetched_new_resource.get_shortname("description", &store).unwrap().to_string() == "the age of a person");
Re-exports
pub use atoms::Atom;
pub use commit::Commit;
pub use errors::AtomicError;
pub use errors::AtomicErrorType;
pub use resources::Resource;
pub use store::Store;
pub use storelike::Storelike;
pub use values::Value;
Modules
Logic for Agents Agents are actors (such as users) that can edit content. https://docs.atomicdata.dev/commits/concepts.html
The smallest units of data, consiting of a Subject, a Property and a Value
Check signatures in authentication headers, find the correct agent. Authorization is done in Hierarchies
Functions for interacting with an Atomic Server
Collections are dynamic resources that refer to multiple resources. They are constructed using a TPF query
Describe changes / mutations to data
Datatypes constrain values of Atoms
The Error type that you can expect when using this library
The Hierarchy model describes how Resources are structed in a tree-like shape. It deals with authorization (read / write permissions, rights, grants) See
Because writing full URLs is error prone and time consuming, we map URLs to shortnames. These are often user-specific. This section provides tools to store, share and resolve these Mappings.
Parsing / deserialization / decoding
Populating a Store means adding resources to it. Some of these are the core Atomic Data resources, such as the Property class. These base models are required for having a functioning store. Other populate methods help to set up an Atomic Server, by creating a basic file hierarcy and creating default collections.
A resource is a set of Atoms that share a URL
Structs and models at the core of Atomic Schema (Class, Property, Datatype).
Serialization / formatting / encoding (JSON, RDF, N-Triples)
In-memory store of Atomic data. This provides many methods for finding, changing, serializing and parsing Atomic Data.
The Storelike Trait contains many useful methods for maniupulting / retrieving data.
Contains some of the most important Atomic Data URLs.
Helper functions for dealing with URLs
Validate the Store and create a ValidationReport. Might be deprecated soon, as Validation hasn’t been necessary since parsing has built-in data validation.
A value is the part of an Atom that contains the actual information.