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_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§

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, consisting of a Subject, a Property and a Value
  • Check signatures in authentication headers, find the correct agent. Authorization is done in Hierarchies
  • Client
  • Collections are dynamic resources that refer to multiple resources. They are constructed using a Query
  • Describe changes / mutations to data
  • DataTypes constrain values of Atoms
  • Mostly contains implementations for Error types.
  • The Hierarchy model describes how Resources are structured 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. Has methods for saving resources and getting properties inside them.
  • 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.