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.