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//! - `serde`: the `define` module, typed named queries and mutators
21//! (`define_query`, `define_mutator`) over serde argument types, and
22//! serde for `json::Value`.
23//!
24//! # Storage
25//!
26//! **A default build persists nothing across restarts**: its storage is
27//! [`ZeroStorage::Memory`](client::ZeroStorage::Memory), kept for the life
28//! of the thread by database name, like JS `kvStore: 'mem'`. SQLite storage,
29//! which keeps synced rows and pending mutations across restarts, is behind
30//! the `sqlite` feature, and an app can bring its own store with
31//! [`ZeroStorage::Custom`](client::ZeroStorage::Custom).
32//!
33//! # Modules
34//!
35//! An app uses [`client`], [`typed`] (through generated code), [`query`],
36//! [`ttl`], and [`testing`]; their items are all documented. The others
37//! (`ast`, `ivm`, `protocol`, and the primitives) are the engine's parts,
38//! public so the conformance runner can check each against JS.
39//!
40//! # Getting started
41//!
42//! A client is made from the app's schema (generated from its TypeScript
43//! schema by `zero-rust codegen`), its mutators, and a scheduler and socket
44//! factory for its event loop. Views stay current: when `mutate` returns,
45//! they show its writes. This one runs without a server, on the manual
46//! clock tests use; an app passes a `cache_url` and the
47//! [`tokio_transport`](crate#features) types instead.
48//!
49//! ```
50//! use zero_client::ast::System;
51//! use zero_client::client::{Mutator, Zero, ZeroOptions};
52//! use zero_client::json::{self, Object, Value};
53//! use zero_client::query::AnyQuery;
54//! use zero_client::schema::Schema;
55//! use zero_client::testing::ManualScheduler;
56//! use zero_client::ttl::Ttl;
57//! use std::sync::Arc;
58//!
59//! let schema = Arc::new(Schema::from_json(&json::parse(
60//! r#"{"tables": {"issue": {"name": "issue", "primaryKey": ["id"],
61//! "columns": {"id": {"type": "string"}, "title": {"type": "string"}}}}}"#,
62//! )?)?);
63//!
64//! // Runs on the client now, and on the server's API when it syncs.
65//! let create = Mutator::new("issue.create", |tx, args, _ctx: &()| {
66//! let mut row = Object::new();
67//! row.insert("id", args.and_then(|a| a.get("id")).cloned().unwrap_or_default());
68//! row.insert("title", Value::from("Hello"));
69//! tx.table("issue").insert(&row)?;
70//! Ok(None)
71//! });
72//!
73//! let scheduler = ManualScheduler::new(1_700_000_000_000.0);
74//! let zero = Zero::new(schema.clone(), (), vec![create], ZeroOptions::default(), scheduler, None)?;
75//!
76//! let issues = AnyQuery::new(schema, "issue", System::Client);
77//! let view = zero.materialize(&issues, &Ttl::default())?;
78//! let mut args = Object::new();
79//! args.insert("id", Value::from("i1"));
80//! zero.mutate("issue.create", Some(Value::from(args)));
81//!
82//! let rows = view.data();
83//! assert_eq!(rows.entries().len(), 1);
84//! assert_eq!(rows.entries()[0].row.get("title"), Some(&Value::from("Hello")));
85//! # Ok::<(), Box<dyn std::error::Error>>(())
86//! ```
87//!
88//! With generated types, the query is `zql::issue()`, and
89//! [`Zero::live`](client::Zero::live) keeps its rows read as row structs;
90//! see the [README](https://github.com/wevm/zero-rust#quick-start).
91
92pub mod ast;
93pub mod builder;
94#[warn(missing_docs)]
95pub mod client;
96pub mod compare;
97pub mod decode;
98#[cfg(feature = "serde")]
99#[warn(missing_docs)]
100pub mod define;
101pub mod format;
102pub mod hash;
103pub mod ivm;
104pub mod json;
105pub mod keys;
106pub mod like;
107pub mod map;
108pub mod protocol;
109#[warn(missing_docs)]
110pub mod query;
111pub mod schema;
112pub mod sort;
113pub mod strings;
114#[warn(missing_docs)]
115pub mod tdigest;
116#[warn(missing_docs)]
117pub mod testing;
118#[cfg(feature = "tokio-transport")]
119#[warn(missing_docs)]
120pub mod tokio_transport;
121#[warn(missing_docs)]
122pub mod ttl;
123#[warn(missing_docs)]
124pub mod typed;