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