zero_client/lib.rs
1//! A native Rust client for [Zero](https://zero.rocicorp.dev).
2//!
3//! A port of the JS client (`packages/zero-client`),
4//! checked against the JS implementation by the conformance vectors in
5//! `packages/zero-conformance`. See `rust/PARITY.md` for what is ported so
6//! far and what is planned.
7//!
8//! # Features
9//!
10//! The default build has no dependencies. It has the whole client,
11//! [`client::Zero`], which an app drives with its own
12//! [`Scheduler`](client::Scheduler) and
13//! [`SocketFactory`](client::SocketFactory). Opt-in features add:
14//!
15//! - `tokio-transport`: the `tokio_transport` module, a scheduler and a
16//! WebSocket transport on tokio and `tokio-tungstenite`.
17//! - `tls`: `wss://` for that transport, with rustls on `ring`.
18//! - `sqlite`: SQLite storage, `ZeroStorage::Sqlite`, on the system
19//! `libsqlite3`; `sqlite-bundled` compiles SQLite in.
20//!
21//! # Storage
22//!
23//! **A default build persists nothing across restarts**: its storage is
24//! [`ZeroStorage::Memory`](client::ZeroStorage::Memory), kept for the life
25//! of the thread by database name, like JS `kvStore: 'mem'`. SQLite storage,
26//! which keeps synced rows and pending mutations across restarts, is behind
27//! the `sqlite` feature, and an app can bring its own store with
28//! [`ZeroStorage::Custom`](client::ZeroStorage::Custom).
29//!
30//! # Modules
31//!
32//! An app uses [`client`], [`typed`] (through generated code), [`query`],
33//! [`ttl`], and [`testing`]; their items are all documented. The others
34//! (`ast`, `ivm`, `protocol`, and the primitives) are the engine's parts,
35//! public so the conformance runner can check each against JS.
36//!
37//! # Getting started
38//!
39//! A client is made from the app's schema (generated from its TypeScript
40//! schema by `zero-rust codegen`), its mutators, and a scheduler and socket
41//! factory for its event loop. Views stay current: when `mutate` returns,
42//! they show its writes. This one runs without a server, on the manual
43//! clock tests use; an app passes a `cache_url` and the
44//! [`tokio_transport`](crate#features) types instead.
45//!
46//! ```
47//! use zero_client::ast::System;
48//! use zero_client::client::{Mutator, Zero, ZeroOptions};
49//! use zero_client::json::{self, Object, Value};
50//! use zero_client::query::AnyQuery;
51//! use zero_client::schema::Schema;
52//! use zero_client::testing::ManualScheduler;
53//! use zero_client::ttl::Ttl;
54//! use std::sync::Arc;
55//!
56//! let schema = Arc::new(Schema::from_json(&json::parse(
57//! r#"{"tables": {"issue": {"name": "issue", "primaryKey": ["id"],
58//! "columns": {"id": {"type": "string"}, "title": {"type": "string"}}}}}"#,
59//! )?)?);
60//!
61//! // Runs on the client now, and on the server's API when it syncs.
62//! let create = Mutator::new("issue.create", |tx, args, _ctx: &()| {
63//! let mut row = Object::new();
64//! row.insert("id", args.and_then(|a| a.get("id")).cloned().unwrap_or_default());
65//! row.insert("title", Value::from("Hello"));
66//! tx.table("issue").insert(&row)?;
67//! Ok(None)
68//! });
69//!
70//! let scheduler = ManualScheduler::new(1_700_000_000_000.0);
71//! let zero = Zero::new(schema.clone(), (), vec![create], ZeroOptions::default(), scheduler, None)?;
72//!
73//! let issues = AnyQuery::new(schema, "issue", System::Client);
74//! let view = zero.materialize(&issues, &Ttl::default())?;
75//! let mut args = Object::new();
76//! args.insert("id", Value::from("i1"));
77//! zero.mutate("issue.create", Some(Value::from(args)));
78//!
79//! let rows = view.data();
80//! assert_eq!(rows.entries().len(), 1);
81//! assert_eq!(rows.entries()[0].row.get("title"), Some(&Value::from("Hello")));
82//! # Ok::<(), Box<dyn std::error::Error>>(())
83//! ```
84//!
85//! With generated types, the query is `zql::issue()`, and a view's data
86//! reads as row structs with `query.read(&view.data())`; see the
87//! [README](https://github.com/wevm/zero/blob/main/rust/README.md#generated-types).
88
89pub mod ast;
90pub mod builder;
91#[warn(missing_docs)]
92pub mod client;
93pub mod compare;
94pub mod decode;
95pub mod format;
96pub mod hash;
97pub mod ivm;
98pub mod json;
99pub mod keys;
100pub mod like;
101pub mod map;
102pub mod protocol;
103#[warn(missing_docs)]
104pub mod query;
105pub mod schema;
106pub mod sort;
107pub mod strings;
108#[warn(missing_docs)]
109pub mod testing;
110#[cfg(feature = "tokio-transport")]
111#[warn(missing_docs)]
112pub mod tokio_transport;
113#[warn(missing_docs)]
114pub mod ttl;
115#[warn(missing_docs)]
116pub mod typed;