Crate atomic_lib

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_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_shortname("shortname", "age", &store).unwrap()
  .set_shortname("datatype", atomic_lib::urls::INTEGER, &store).unwrap()
  .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

• agents
  Logic for Agents Agents are actors (such as users) that can edit content. https://docs.atomicdata.dev/commits/concepts.html
• atoms
  The smallest units of data, consisting of a Subject, a Property and a Value
• authentication
  Check signatures in authentication headers, find the correct agent. Authorization is done in Hierarchies
• client
  Client
• collections
  Collections are dynamic resources that refer to multiple resources. They are constructed using a Query
• commit
  Describe changes / mutations to data
• datatype
  DataTypes constrain values of Atoms
• errors
  Mostly contains implementations for Error types.
• hierarchy
  The Hierarchy model describes how Resources are structured in a tree-like shape. It deals with authorization (read / write permissions, rights, grants) See
• mapping
  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.
• parse
  Parsing / deserialization / decoding
• populate
  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.
• resources
  A Resource is a set of Atoms that share a URL. Has methods for saving resources and getting properties inside them.
• schema
  Structs and models at the core of Atomic Schema (Class, Property, Datatype).
• serialize
  Serialization / formatting / encoding (JSON, RDF, N-Triples)
• store
  In-memory store of Atomic data. This provides many methods for finding, changing, serializing and parsing Atomic Data.
• storelike
  The Storelike Trait contains many useful methods for maniupulting / retrieving data.
• urls
  Contains some of the most important Atomic Data URLs.
• utils
  Helper functions for dealing with URLs
• validate
  Validate the Store and create a ValidationReport. Might be deprecated soon, as Validation hasn’t been necessary since parsing has built-in data validation.
• values
  A value is the part of an Atom that contains the actual information.