Skip to content

Native iCloud apps for Windows and Linux, built in Rust. Notes, Reminders, Calendar, Contacts, Drive and Photos, offline and in sync with your iPhone.

Sync: a pass names the items it changed, and a rewrite that changed nothing is quiet

Yashwanth Kamireddi2bb762d6a0ec
diff --git a/.uiverify/stub.mjs b/.uiverify/stub.mjs
index 6837770..246a0a5 100644
--- a/.uiverify/stub.mjs
+++ b/.uiverify/stub.mjs
@@ -91,6 +91,9 @@ export function installStub({ screen, services, twoFactor, calendarFixture, note
birthday: null, notes: null, etag: null,
methods: [{ kind: "phone", label: null, value: "+91 90000 11111" }] },
].concat(contactsFixture ? (window.__contactsExtra ?? []) : []);
+ // The book as the library holds it, for a test to change "on the phone" before playing a
+ // pass in with __emit.
+ window.__contactList = contactList;
const driveItems = !driveFixture ? [] : [
{ drivewsid: "FOLDER::a", parentId: null, name: "Downloads", extension: null,
kind: "FOLDER", size: null, childCount: 3, createdAt: 1785000000,
@@ -856,6 +859,12 @@ export function installStub({ screen, services, twoFactor, calendarFixture, note
const q = window.__contactsSearch && args?.search ? String(args.search).toLowerCase() : "";
return q ? contactList.filter((c) => [c.firstName, c.lastName, c.company, ...c.methods.map((m) => m.value)].join(" ").toLowerCase().includes(q)) : contactList.slice();
}
+ // These cards alone, those still here: what a pass that named them has read.
+ case "contacts_get": {
+ if (!contactsFixture) return [];
+ const want = new Set(args?.guids ?? []);
+ return contactList.filter((c) => want.has(c.guid));
+ }
// Duplicates as contacts_merge.rs finds them, on the fixture: a shared number (its
// last ten digits), a shared email, or the same name.
case "contacts_duplicates": {
diff --git a/crates/quince-core/Cargo.toml b/crates/quince-core/Cargo.toml
index bf8dca2..3f21cef 100644
--- a/crates/quince-core/Cargo.toml
+++ b/crates/quince-core/Cargo.toml
@@ -6,7 +6,7 @@ rust-version.workspace = true
license.workspace = true
[dependencies]
-rusqlite = { version = "0.32", features = ["bundled", "hooks"] }
+rusqlite = { version = "0.32", features = ["bundled", "functions", "hooks"] }
jiff = "0.2.37"
serde.workspace = true
thiserror = "2"
diff --git a/crates/quince-core/src/changes.rs b/crates/quince-core/src/changes.rs
new file mode 100644
index 0000000..20117c0
--- /dev/null
+++ b/crates/quince-core/src/changes.rs
@@ -0,0 +1,412 @@
+//! Which of each app's items a change to the library touched: the reminders, notes, cards and
+//! photos added, changed and removed — so a screen can redraw those rows rather than read its
+//! whole list again.
+//!
+//! Watched with triggers rather than read off the records a pass brought: a pass writes
+//! through many paths (a whole address book stored again, changes still on their way laid back
+//! over it, a tombstone), and the rows themselves are the one place they all meet. Each row
+//! written is counted by a digest of what it holds — out once as it was, in once as it is — so
+//! a row stored again just as it was cancels out, and what is left is what really changed.
+//! A card whose numbers were all rewritten unchanged is not a changed card.
+
+use std::collections::{BTreeMap, BTreeSet, HashMap};
+use std::hash::{Hash, Hasher};
+use std::sync::{Arc, Mutex, PoisonError};
+
+use rusqlite::functions::FunctionFlags;
+use rusqlite::types::ValueRef;
+use rusqlite::Connection;
+use serde::Serialize;
+
+/// Where each table's rows belong: the app that shows them, the column naming the item a row
+/// is part of, and whether it is the item's own row (rather than one of its parts — a number on
+/// a card, a tag on a reminder). No column: the table holds how the app is arranged — its
+/// lists, folders, albums — and a change there is read whole.
+const PLACES: &[(&str, &str, Option<&str>, bool)] = &[
+ ("events", "calendar", Some("guid"), true),
+ ("calendars", "calendar", None, false),
+ ("reminders", "reminders", Some("guid"), true),
+ ("reminder_alarms", "reminders", Some("reminder_guid"), false),
+ (
+ "reminder_attachments",
+ "reminders",
+ Some("reminder_guid"),
+ false,
+ ),
+ (
+ "reminder_early_alerts",
+ "reminders",
+ Some("reminder_guid"),
+ false,
+ ),
+ (
+ "reminder_hashtags",
+ "reminders",
+ Some("reminder_guid"),
+ false,
+ ),
+ ("reminder_parts", "reminders", Some("reminder_guid"), false),
+ ("reminder_lists", "reminders", None, false),
+ ("reminder_sections", "reminders", None, false),
+ ("reminder_groups", "reminders", None, false),
+ ("reminder_smart_lists", "reminders", None, false),
+ ("alarm_triggers", "reminders", None, false),
+ ("alarm_fired", "reminders", None, false),
+ ("alarm_snoozes", "reminders", None, false),
+ ("notes", "notes", Some("guid"), true),
+ ("note_folders", "notes", None, false),
+ ("contacts", "contacts", Some("guid"), true),
+ ("contact_methods", "contacts", Some("contact_guid"), false),
+ ("contact_addresses", "contacts", Some("contact_guid"), false),
+ ("drive_items", "drive", Some("drivewsid"), true),
+ ("photos", "photos", Some("id"), true),
+ ("photo_albums", "photos", None, false),
+ ("photo_album_items", "photos", None, false),
+];
+
+/// Tables no screen reads a pass's change in: where each service got to, the search index
+/// kept from the rows themselves, and the queues that say their own changes.
+const UNSEEN: &[&str] = &[
+ "sync_state",
+ "search_docs",
+ "outbox",
+ "photo_uploads",
+ "photo_walk",
+ "photo_walk_held",
+];
+
+/// When to stop counting and say only "a lot": a first pass of a large photo library, which
+/// every screen reads whole anyway.
+const MOST_ROWS: usize = 200_000;
+
+/// What a change did to one app's items, by their ids.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Items {
+ pub added: Vec<String>,
+ pub changed: Vec<String>,
+ pub removed: Vec<String>,
+}
+
+impl Items {
+ #[must_use]
+ pub fn is_empty(&self) -> bool {
+ self.added.is_empty() && self.changed.is_empty() && self.removed.is_empty()
+ }
+
+ #[must_use]
+ pub fn len(&self) -> usize {
+ self.added.len() + self.changed.len() + self.removed.len()
+ }
+}
+
+/// What one change to the library did, as [`crate::Library::changing_items`] saw it.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Changed {
+ /// Rows beyond the bookkeeping were written (`Library::changing`'s answer).
+ pub written: bool,
+ /// Each app's items it really changed, once rows stored again as they were cancel out.
+ /// `None` when not all of it could be placed: a table no app's items live in, or more
+ /// rows than are worth counting. Read whole, then.
+ pub items: Option<BTreeMap<&'static str, Items>>,
+ /// The apps whose arrangement — lists, folders, albums — it changed: read whole.
+ pub arranged: BTreeSet<&'static str>,
+}
+
+impl Changed {
+ /// What it did to `service`, for that app's screen: `None` to read it whole, `Some` with
+ /// the ids otherwise — empty when nothing it shows changed.
+ #[must_use]
+ pub fn for_service(&self, service: &str) -> Option<Items> {
+ let items = self.items.as_ref()?;
+ if self.arranged.contains(service) {
+ return None;
+ }
+ // Another app's items changed by this one's pass: nothing the ids could say for sure.
+ if items.iter().any(|(s, i)| *s != service && !i.is_empty()) {
+ return None;
+ }
+ Some(items.get(service).cloned().unwrap_or_default())
+ }
+}
+
+/// Rows seen while watching: each row's digest, counted in (+1) and out (−1), by table and item.
+#[derive(Default)]
+pub(crate) struct Tally {
+ rows: HashMap<(usize, Option<String>, u64), i64>,
+ /// Too many rows to be worth placing, or a write the watch could not read.
+ lost: bool,
+}
+
+/// The watch shared between the library and the functions its triggers call.
+pub(crate) type Watch = Arc<Mutex<Option<Tally>>>;
+
+/// The two functions the triggers call: whether anything is being watched, and "this row, in
+/// or out". Registered once per writing connection.
+pub(crate) fn register(conn: &Connection, watch: &Watch) -> rusqlite::Result<()> {
+ let on = Arc::clone(watch);
+ conn.create_scalar_function(
+ "quince_watching",
+ 0,
+ FunctionFlags::SQLITE_UTF8,
+ move |_| Ok(on.lock().unwrap_or_else(PoisonError::into_inner).is_some()),
+ )?;
+ let tally = Arc::clone(watch);
+ conn.create_scalar_function("quince_seen", -1, FunctionFlags::SQLITE_UTF8, move |ctx| {
+ let mut guard = tally.lock().unwrap_or_else(PoisonError::into_inner);
+ let Some(tally) = guard.as_mut() else {
+ return Ok(rusqlite::types::Null);
+ };
+ if tally.lost {
+ return Ok(rusqlite::types::Null);
+ }
+ let table = usize::try_from(ctx.get::<i64>(0)?).unwrap_or(usize::MAX);
+ let key = match ctx.get_raw(1) {
+ ValueRef::Null => None,
+ ValueRef::Text(t) => Some(String::from_utf8_lossy(t).into_owned()),
+ ValueRef::Integer(n) => Some(n.to_string()),
+ ValueRef::Real(n) => Some(n.to_string()),
+ ValueRef::Blob(b) => Some(String::from_utf8_lossy(b).into_owned()),
+ };
+ let sign = ctx.get::<i64>(2)?;
+ // DefaultHasher::new() is keyed the same every time: digests compare within a change.
+ let mut hasher = std::collections::hash_map::DefaultHasher::new();
+ for i in 3..ctx.len() {
+ match ctx.get_raw(i) {
+ ValueRef::Null => 0u8.hash(&mut hasher),
+ ValueRef::Integer(n) => (1u8, n).hash(&mut hasher),
+ ValueRef::Real(n) => (2u8, n.to_bits()).hash(&mut hasher),
+ ValueRef::Text(t) => (3u8, t).hash(&mut hasher),
+ ValueRef::Blob(b) => (4u8, b).hash(&mut hasher),
+ }
+ }
+ *tally.rows.entry((table, key, hasher.finish())).or_insert(0) += sign;
+ if tally.rows.len() > MOST_ROWS {
+ tally.lost = true;
+ tally.rows = HashMap::new();
+ }
+ Ok(rusqlite::types::Null)
+ })?;
+ Ok(())
+}
+
+/// Every table a write can land in, with its place: (index into [`PLACES`], or `None`).
+fn tables(conn: &Connection) -> rusqlite::Result<Vec<(String, Option<usize>)>> {
+ let mut stmt = conn.prepare(
+ "SELECT name FROM main.sqlite_master
+ WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+ AND sql NOT LIKE 'CREATE VIRTUAL%'
+ AND name NOT LIKE 'search_text%'",
+ )?;
+ let names = stmt.query_map([], |r| r.get::<_, String>(0))?;
+ let mut out = Vec::new();
+ for name in names {
+ let name = name?;
+ if UNSEEN.contains(&name.as_str()) {
+ continue;
+ }
+ let place = PLACES.iter().position(|(t, ..)| *t == name);
+ out.push((name, place));
+ }
+ Ok(out)
+}
+
+/// The triggers that tell [`register`]'s function of each row written, made where missing.
+/// Temporary: they belong to this connection alone, are never stored in the library, and do
+/// nothing unless a change is being watched.
+pub(crate) fn install(conn: &Connection) -> rusqlite::Result<()> {
+ for (n, (table, place)) in tables(conn)?.into_iter().enumerate() {
+ // Placed tables are numbered by their place; the rest after them, by the order read.
+ let at = place.unwrap_or(PLACES.len() + n);
+ let mut columns = Vec::new();
+ {
+ let mut stmt = conn.prepare(&format!("PRAGMA main.table_info(\"{table}\")"))?;
+ let names = stmt.query_map([], |r| r.get::<_, String>(1))?;
+ for name in names {
+ let name = name?;
+ // When a row was last stored is not what it holds.
+ if name != "updated_at" {
+ columns.push(name);
+ }
+ }
+ }
+ let key = place.and_then(|p| PLACES[p].2);
+ let row = |side: &str, sign: i64| {
+ let key = key.map_or_else(|| "NULL".to_string(), |k| format!("{side}.\"{k}\""));
+ let values: Vec<String> = columns.iter().map(|c| format!("{side}.\"{c}\"")).collect();
+ format!(
+ "SELECT quince_seen({at}, {key}, {sign}, {});",
+ values.join(", ")
+ )
+ };
+ conn.execute_batch(&format!(
+ "CREATE TEMP TRIGGER IF NOT EXISTS \"quince_seen_{table}_in\" AFTER INSERT ON \"{table}\"
+ WHEN quince_watching() BEGIN {} END;
+ CREATE TEMP TRIGGER IF NOT EXISTS \"quince_seen_{table}_set\" AFTER UPDATE ON \"{table}\"
+ WHEN quince_watching() BEGIN {} {} END;
+ CREATE TEMP TRIGGER IF NOT EXISTS \"quince_seen_{table}_out\" AFTER DELETE ON \"{table}\"
+ WHEN quince_watching() BEGIN {} END;",
+ row("NEW", 1),
+ row("OLD", -1),
+ row("NEW", 1),
+ row("OLD", -1),
+ ))?;
+ }
+ Ok(())
+}
+
+/// What a watch saw, placed: each app's items in, changed and out, and whose arrangement moved.
+pub(crate) fn place(tally: Tally, written: bool) -> Changed {
+ if tally.lost {
+ return Changed {
+ written,
+ items: None,
+ arranged: BTreeSet::new(),
+ };
+ }
+ // Per item: what its own row did (in, out, or both) and whether any part of it moved.
+ #[derive(Default)]
+ struct Seen {
+ own_in: bool,
+ own_out: bool,
+ parts: bool,
+ }
+ let mut seen: BTreeMap<(&'static str, String), Seen> = BTreeMap::new();
+ let mut arranged = BTreeSet::new();
+ for ((at, key, _), n) in tally.rows {
+ if n == 0 {
+ continue;
+ }
+ let Some(&(_, service, column, own)) = PLACES.get(at) else {
+ // A table no app's items live in: nothing about this change can be placed.
+ return Changed {
+ written,
+ items: None,
+ arranged: BTreeSet::new(),
+ };
+ };
+ match (column, key) {
+ (Some(_), Some(key)) => {
+ let s = seen.entry((service, key)).or_default();
+ if !own {
+ s.parts = true;
+ } else if n > 0 {
+ s.own_in = true;
+ } else {
+ s.own_out = true;
+ }
+ }
+ // An arrangement's row, or a part belonging to no item.
+ _ => {
+ arranged.insert(service);
+ }
+ }
+ }
+ let mut items: BTreeMap<&'static str, Items> = BTreeMap::new();
+ for ((service, key), s) in seen {
+ let mine = items.entry(service).or_default();
+ match (s.own_in, s.own_out) {
+ (true, false) => mine.added.push(key),
+ (false, true) => mine.removed.push(key),
+ _ => mine.changed.push(key),
+ }
+ }
+ Changed {
+ written,
+ items: Some(items),
+ arranged,
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use crate::contacts::{Contact, ContactMethod};
+ use crate::Library;
+
+ fn card(guid: &str, last: &str, phone: &str) -> Contact {
+ Contact {
+ guid: guid.into(),
+ first_name: Some("Alex".into()),
+ middle_name: None,
+ last_name: Some(last.into()),
+ company: None,
+ is_company: false,
+ birthday: None,
+ notes: None,
+ photo_url: None,
+ photo_signature: None,
+ photo_crop: None,
+ etag: Some("1".into()),
+ methods: vec![ContactMethod {
+ kind: "phone".into(),
+ label: Some("mobile".into()),
+ value: phone.into(),
+ }],
+ }
+ }
+
+ /// A whole address book stored again names only the cards that differ: the one renamed,
+ /// the one whose number moved, the one new and the one gone — not every card rewritten.
+ #[test]
+ fn a_book_stored_again_names_only_the_cards_that_changed() {
+ let mut library = Library::in_memory().unwrap();
+ library
+ .put_contacts(&[
+ card("A", "Rivera", "1"),
+ card("B", "Chen", "2"),
+ card("C", "Diaz", "3"),
+ card("D", "Evans", "4"),
+ ])
+ .unwrap();
+ let ((), changed) = library.changing_items(&["sync_state"], |l| {
+ l.put_contacts(&[
+ card("A", "Rivera", "1"),
+ card("B", "Chen-Park", "2"),
+ card("C", "Diaz", "33"),
+ card("E", "Fischer", "5"),
+ ])
+ .unwrap();
+ l.mark_synced("contacts", Some("t")).unwrap();
+ });
+ assert!(changed.written);
+ let items = changed.for_service("contacts").expect("placed");
+ assert_eq!(items.added, ["E"]);
+ assert_eq!(items.changed, ["B", "C"]);
+ assert_eq!(items.removed, ["D"]);
+ }
+
+ /// Stored again exactly as it was, nothing is named — and a screen has nothing to read.
+ #[test]
+ fn rows_stored_again_as_they_were_cancel_out() {
+ let mut library = Library::in_memory().unwrap();
+ library.put_contacts(&[card("A", "Rivera", "1")]).unwrap();
+ library.set_state("contacts.me", "A").unwrap();
+ let ((), changed) = library.changing_items(&["sync_state"], |l| {
+ l.put_contacts(&[card("A", "Rivera", "1")]).unwrap();
+ l.set_state("contacts.me", "A").unwrap();
+ });
+ assert!(changed.written, "rows were written");
+ assert_eq!(
+ changed.for_service("contacts"),
+ Some(super::Items::default())
+ );
+ }
+
+ /// A row in a table no app's items live in can't be placed: the screen reads whole. Nor is
+ /// anything watched outside a change, or left watched after one.
+ #[test]
+ fn what_cannot_be_placed_is_read_whole() {
+ let mut library = Library::in_memory().unwrap();
+ let ((), changed) = library.changing_items(&["sync_state"], |l| {
+ l.set_state("contacts.lists", "[1]").unwrap();
+ });
+ assert_eq!(changed.for_service("contacts"), None);
+ library.put_contacts(&[card("A", "Rivera", "1")]).unwrap();
+ let ((), changed) = library.changing_items(&["sync_state"], |_| {});
+ assert!(!changed.written);
+ assert_eq!(
+ changed.for_service("contacts"),
+ Some(super::Items::default())
+ );
+ }
+}
diff --git a/crates/quince-core/src/contacts.rs b/crates/quince-core/src/contacts.rs
index 7ae3433..59b9a35 100644
--- a/crates/quince-core/src/contacts.rs
+++ b/crates/quince-core/src/contacts.rs
@@ -808,14 +808,27 @@ impl Library {
/// [`Library::contacts`], each card whole: with the rest of its name and work, which a
/// search matches too — a nickname or a job title finds the person.
pub fn cards(&self, search: Option<&str>) -> Result<Vec<Card>> {
+ self.cards_among(search, None)
+ }
+
+ /// The cards with these ids, whole, in the same order — those still here. What a screen
+ /// reads when a pass names the cards it changed, rather than the whole book again.
+ pub fn cards_by_guid(&self, guids: &[String]) -> Result<Vec<Card>> {
+ self.cards_among(None, Some(guids))
+ }
+
+ fn cards_among(&self, search: Option<&str>, only: Option<&[String]>) -> Result<Vec<Card>> {
let words = crate::fold::words(search.unwrap_or(""));
+ // The ids as one JSON array, matched in SQL: no statement built per count of them.
+ let only = only.map(|ids| serde_json::to_string(ids).unwrap_or_else(|_| "[]".into()));
let mut stmt = self.conn.prepare(
"SELECT c.guid, c.first_name, c.middle_name, c.last_name, c.company, c.is_company,
c.birthday, c.notes, c.photo_url, c.photo_signature, c.photo_crop, c.etag
- FROM contacts c",
+ FROM contacts c
+ WHERE ?1 IS NULL OR c.guid IN (SELECT value FROM json_each(?1))",
)?;
- let rows = stmt.query_map([], |row| {
+ let rows = stmt.query_map(params![only], |row| {
Ok(Contact {
guid: row.get(0)?,
first_name: row.get(1)?,
@@ -840,9 +853,10 @@ impl Library {
std::collections::HashMap::new();
let mut stmt = self.conn.prepare(
"SELECT contact_guid, kind, label, value FROM contact_methods
+ WHERE ?1 IS NULL OR contact_guid IN (SELECT value FROM json_each(?1))
ORDER BY contact_guid, position",
)?;
- let rows = stmt.query_map([], |row| {
+ let rows = stmt.query_map(params![only], |row| {
Ok((
row.get::<_, String>(0)?,
ContactMethod {
@@ -859,7 +873,15 @@ impl Library {
for contact in &mut contacts {
contact.methods = methods.remove(&contact.guid).unwrap_or_default();
}
- let mut details = self.details_by_guid(None)?;
+ let mut details = if only.is_some() {
+ let mut some = std::collections::HashMap::new();
+ for c in &contacts {
+ some.extend(self.details_by_guid(Some(&c.guid))?);
+ }
+ some
+ } else {
+ self.details_by_guid(None)?
+ };
let mut cards: Vec<Card> = contacts
.into_iter()
.map(|contact| Card {
@@ -1003,6 +1025,41 @@ mod tests {
}
}
+ /// Cards asked for by id come whole — numbers and the rest of the name — and only those
+ /// still here, the same as the whole book has them.
+ #[test]
+ fn cards_by_id_are_the_cards_the_book_has() {
+ let mut lib = Library::in_memory().unwrap();
+ lib.put_contacts(&[
+ contact("1", Some("Sam"), Some("Rivera")),
+ contact("2", Some("Maya"), Some("Chen")),
+ contact("3", Some("Jamie"), None),
+ ])
+ .unwrap();
+ lib.put_contact_details(
+ &[(
+ "2".into(),
+ ContactDetails {
+ nickname: Some("May".into()),
+ ..ContactDetails::default()
+ },
+ )],
+ false,
+ )
+ .unwrap();
+ let some = lib
+ .cards_by_guid(&["2".into(), "3".into(), "gone".into()])
+ .unwrap();
+ let whole = lib.cards(None).unwrap();
+ assert_eq!(some.len(), 2);
+ for card in &some {
+ let same = whole.iter().find(|c| c.contact.guid == card.contact.guid);
+ assert_eq!(Some(card), same);
+ }
+ assert_eq!(some[0].details.nickname.as_deref(), Some("May"));
+ assert!(lib.cards_by_guid(&[]).unwrap().is_empty());
+ }
+
/// A company's card goes by the company, whoever is named on it — as Contacts lists it,
/// and as an export names it.
#[test]
diff --git a/crates/quince-core/src/lib.rs b/crates/quince-core/src/lib.rs
index 890ca5d..82c2bdd 100644
--- a/crates/quince-core/src/lib.rs
+++ b/crates/quince-core/src/lib.rs
@@ -6,6 +6,7 @@
pub mod alarms;
pub mod calendar;
+pub mod changes;
pub mod contacts;
pub mod drive;
pub mod export;
@@ -205,6 +206,8 @@ pub struct Library {
/// The zone all-day and floating events are read and stored in: this computer's, asked
/// each time (`None`), so a change of zone is seen at once — or one given, for tests.
zone: Option<jiff::tz::TimeZone>,
+ /// What a change being watched has written so far, row by row (`changing_items`).
+ watch: changes::Watch,
}
impl Library {
@@ -322,7 +325,11 @@ impl Library {
)?;
conn.pragma_update(None, "query_only", true)?;
conn.busy_timeout(std::time::Duration::from_millis(250))?;
- Ok(Self { conn, zone: None })
+ Ok(Self {
+ conn,
+ zone: None,
+ watch: changes::Watch::default(),
+ })
}
/// An in-memory library. Tests, and nothing else.
@@ -343,8 +350,13 @@ impl Library {
conn.pragma_update(None, "journal_mode", "WAL")?;
conn.pragma_update(None, "synchronous", "FULL")?;
conn.pragma_update(None, "foreign_keys", "ON")?;
- let mut library = Self { conn, zone: None };
+ let mut library = Self {
+ conn,
+ zone: None,
+ watch: changes::Watch::default(),
+ };
library.migrate()?;
+ changes::register(&library.conn, &library.watch)?;
Ok(library)
}
@@ -441,6 +453,52 @@ impl Library {
(out, written > aside.load(Ordering::Relaxed))
}
+ /// [`Library::changing`], saying besides which of each app's items the change really
+ /// touched — added, changed, removed — once rows stored again as they were cancel out
+ /// (`changes`). A screen redraws those rows rather than reading its whole list again.
+ pub fn changing_items<T>(
+ &mut self,
+ besides: &'static [&'static str],
+ apply: impl FnOnce(&mut Self) -> T,
+ ) -> (T, changes::Changed) {
+ /// The watch ended however `apply` ends, a panic included.
+ struct Unwatch(changes::Watch);
+ impl Drop for Unwatch {
+ fn drop(&mut self) {
+ self.0
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .take();
+ }
+ }
+ // Made where missing on each change, so a table made since (a walk's own) is watched
+ // too. A library whose triggers cannot be made places nothing, and is read whole.
+ let watching = changes::install(&self.conn).is_ok();
+ if watching {
+ *self
+ .watch
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner) =
+ Some(changes::Tally::default());
+ }
+ let unwatch = Unwatch(std::sync::Arc::clone(&self.watch));
+ let (out, written) = self.changing(besides, apply);
+ let tally = unwatch
+ .0
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .take();
+ let changed = match tally {
+ Some(tally) => changes::place(tally, written),
+ None => changes::Changed {
+ written,
+ items: None,
+ arranged: std::collections::BTreeSet::new(),
+ },
+ };
+ (out, changed)
+ }
+
pub fn schema_version(&self) -> Result<u32> {
Ok(self
.conn
diff --git a/crates/quince-icloud/src/contacts.rs b/crates/quince-icloud/src/contacts.rs
index 3bc48f6..f8efd0f 100644
--- a/crates/quince-icloud/src/contacts.rs
+++ b/crates/quince-icloud/src/contacts.rs
@@ -1958,6 +1958,71 @@ fn apply_whole(library: &mut quince_core::Library, book: AddressBook) -> Result<
#[cfg(test)]
mod list_tests {
+ /// The whole book read again after one card's address moved on the phone: the pass names
+ /// that card alone, and a book read again unchanged names none — so Contacts redraws one
+ /// row, or nothing, rather than reading every card again.
+ #[test]
+ fn a_whole_book_read_again_names_only_the_card_that_moved() {
+ use quince_core::contacts::{Contact, ContactDetails, ContactMethod, PostalAddress};
+ let person = |guid: &str, last: &str| Contact {
+ guid: guid.into(),
+ first_name: Some("Sam".into()),
+ middle_name: None,
+ last_name: Some(last.into()),
+ company: None,
+ is_company: false,
+ birthday: None,
+ notes: None,
+ photo_url: None,
+ photo_signature: None,
+ photo_crop: None,
+ etag: Some("e1".into()),
+ methods: vec![ContactMethod {
+ kind: "email".into(),
+ label: Some("home".into()),
+ value: format!("{guid}@example.com"),
+ }],
+ };
+ let book = |city: &str| super::AddressBook {
+ contacts: vec![person("A", "Rivera"), person("B", "Turner")],
+ lists: Vec::new(),
+ me: Some("A".into()),
+ addresses: vec![(
+ "B".into(),
+ vec![PostalAddress {
+ label: Some("HOME".into()),
+ city: Some(city.into()),
+ ..PostalAddress::default()
+ }],
+ )],
+ details: vec![(
+ "A".into(),
+ ContactDetails {
+ nickname: Some("Al".into()),
+ ..ContactDetails::default()
+ },
+ )],
+ };
+ let mut library = quince_core::Library::in_memory().unwrap();
+ super::apply(&mut library, book("Lisbon")).unwrap();
+
+ let (_, same) = library.changing_items(&["sync_state"], |l| {
+ super::apply(l, book("Lisbon")).unwrap();
+ });
+ assert_eq!(
+ same.for_service("contacts"),
+ Some(quince_core::changes::Items::default()),
+ "the same book read again changes no card"
+ );
+
+ let (_, moved) = library.changing_items(&["sync_state"], |l| {
+ super::apply(l, book("Porto")).unwrap();
+ });
+ let items = moved.for_service("contacts").expect("placed");
+ assert_eq!(items.changed, ["B"]);
+ assert!(items.added.is_empty() && items.removed.is_empty());
+ }
+
/// The tokens a pass keeps come back as they went in; anything else kept there (a library
/// from before) reads as none, so the book is read whole rather than trusted.
#[test]
diff --git a/src-tauri/src/main.rs b/src-tauri/src/main.rs
index c33152a..05e43f2 100644
--- a/src-tauri/src/main.rs
+++ b/src-tauri/src/main.rs
@@ -3847,12 +3847,15 @@ async fn contact_save(
async fn contact_delete(guid: String, data: State<'_, Data>) -> UiResult<()> {
{
let mut library = data.0.lock().await;
+ // The one card, not the whole book: deleting fifty people read every card fifty times,
+ // each under the library's lock.
let contact = library
- .contacts(None)
+ .cards_by_guid(std::slice::from_ref(&guid))
.map_err(|e| e.to_string())?
.into_iter()
- .find(|c| c.guid == guid)
- .ok_or("That contact is no longer in the local library.")?;
+ .next()
+ .ok_or("That contact is no longer in the local library.")?
+ .contact;
outbox::record_contact_delete(&mut library, &contact).map_err(|e| e.to_string())?;
}
outbox::kick();
@@ -4038,6 +4041,18 @@ async fn contacts_list(
.map_err(|e| e.to_string())
}
+/// These cards alone, whole: what Contacts reads when a pass names the cards it changed.
+#[tauri::command]
+async fn contacts_get(
+ guids: Vec<String>,
+ data: State<'_, Data>,
+) -> UiResult<Vec<quince_core::contacts::Card>> {
+ data.0
+ .read(move |library| library.cards_by_guid(&guids))
+ .await
+ .map_err(|e| e.to_string())
+}
+
#[tauri::command]
async fn drive_sync_folder(
folder_id: String,
@@ -5217,6 +5232,7 @@ fn spawn_auto_sync(app: tauri::AppHandle, client: Arc<Mutex<Client>>) {
fn told(result: &refresh::Refresh) -> refresh::Refresh {
refresh::Refresh {
changed: Some(Vec::new()),
+ items: None,
..result.clone()
}
}
@@ -6471,13 +6487,14 @@ fn main() {
spawn_auto_sync(app.handle().clone(), client);
// Each service's part of a pass, told to the open screens as it is stored.
let landing = app.handle().clone();
- refresh::on_landed(move |service, changed| {
+ refresh::on_landed(move |service, changed, items| {
let app = landing.clone();
tauri::async_runtime::spawn(async move {
- let mut status = refresh::status(&app.state::<Data>().0).await;
- // Its freshness for every screen; a read again only for its own, and only
- // when it stored something.
- status.changed = Some(if changed { vec![service] } else { Vec::new() });
+ // Its freshness for every screen; a read again only for its own, only when
+ // it stored something — and of only the items it changed, when known.
+ let status =
+ refresh::status_landed(&app.state::<Data>().0, service, changed, items)
+ .await;
app.emit(SYNCED, status).ok();
});
});
@@ -6675,6 +6692,7 @@ fn main() {
notes_search,
note_counts,
contacts_list,
+ contacts_get,
contact_save,
contact_lists,
contacts_export,
diff --git a/src-tauri/src/refresh.rs b/src-tauri/src/refresh.rs
index cc4e9db..9457d32 100644
--- a/src-tauri/src/refresh.rs
+++ b/src-tauri/src/refresh.rs
@@ -16,8 +16,10 @@
use crate::library_lock::LibraryLock;
use quince_auth::Client;
+use quince_core::changes::Items;
use quince_core::Library;
use serde::Serialize;
+use std::collections::BTreeMap;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
use tokio::sync::Mutex;
@@ -48,6 +50,10 @@ pub struct ServiceReport {
/// the pass, never sent with the report itself.
#[serde(skip)]
pub changed: bool,
+ /// Which of the app's items it changed, when that could be placed: its screen redraws those
+ /// rows alone. `None`, it reads its list whole.
+ #[serde(skip)]
+ pub items: Option<Items>,
}
/// Everything one refresh pass did.
@@ -64,8 +70,16 @@ pub struct Refresh {
/// only for its own. Absent, every screen reads again, as it always did.
#[serde(skip_serializing_if = "Option::is_none")]
pub changed: Option<Vec<&'static str>>,
+ /// For services in `changed` whose items could be placed, which ones: added, changed and
+ /// removed, by id. A service in `changed` and not here is read whole.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub items: Option<BTreeMap<&'static str, Items>>,
}
+/// More items than this changed in one go and the screen reads its list whole: one read of
+/// everything is quicker than asking after each.
+const MOST_ITEMS: usize = 500;
+
/// How often a service reconciles against everything Apple has, rather than the changes
/// since last time.
///
@@ -134,18 +148,18 @@ async fn context(client: &Arc<Mutex<Client>>) -> Context {
}
/// Told each time one service's part of a pass has been stored, before the rest are done,
-/// with whether it changed anything a screen shows.
-type Landed = Box<dyn Fn(&'static str, bool) + Send + Sync>;
+/// with whether it changed anything a screen shows, and which items when that is known.
+type Landed = Box<dyn Fn(&'static str, bool, Option<Items>) + Send + Sync>;
static LANDED: std::sync::OnceLock<Landed> = std::sync::OnceLock::new();
/// What to do when a service lands: set once, by the app, to tell the open screens.
-pub fn on_landed(f: impl Fn(&'static str, bool) + Send + Sync + 'static) {
+pub fn on_landed(f: impl Fn(&'static str, bool, Option<Items>) + Send + Sync + 'static) {
let _ = LANDED.set(Box::new(f));
}
fn landed(report: &ServiceReport) {
if let Some(f) = LANDED.get() {
- f(report.service, report.changed);
+ f(report.service, report.changed, report.items.clone());
}
}
@@ -226,6 +240,7 @@ fn arrived((mut report, ran): (ServiceReport, bool)) -> ServiceReport {
landed(&report);
} else {
report.changed = false;
+ report.items = None;
}
report
}
@@ -511,6 +526,8 @@ async fn run(client: &Arc<Mutex<Client>>, data: &LibraryLock, services: &[&str])
// is asked for: the walk holds no more of it in memory than those pages, and
// goes as far in one pass as it did when it held all of them at once.
let mut changed = false;
+ // What every round changed, put together; read whole once any round can't say.
+ let mut items = Some(Items::default());
let mut rounds = 0;
loop {
rounds += 1;
@@ -550,11 +567,18 @@ async fn run(client: &Arc<Mutex<Client>>, data: &LibraryLock, services: &[&str])
)
.await;
changed |= report.changed;
+ if report.changed {
+ items = match (items, report.items.take()) {
+ (Some(all), Some(round)) => joined(all, round),
+ _ => None,
+ };
+ }
if report.outcome != Outcome::Ok
|| !more
|| rounds >= quince_icloud::photos::PASS_ROUNDS
{
report.changed = changed;
+ report.items = if changed { items } else { None };
break report;
}
}
@@ -594,12 +618,18 @@ async fn run(client: &Arc<Mutex<Client>>, data: &LibraryLock, services: &[&str])
.filter(|r| r.changed)
.map(|r| r.service)
.collect();
+ let items = reports
+ .iter()
+ .filter(|r| r.changed)
+ .filter_map(|r| Some((r.service, r.items.clone()?)))
+ .collect();
Refresh {
services: reports,
as_of,
took_ms: u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX),
changed: Some(changed),
+ items: Some(items),
}
}
@@ -614,6 +644,24 @@ pub async fn status_changed(data: &LibraryLock, changed: &[&'static str]) -> Ref
}
}
+/// [`status`], for one service that has just landed: whose rows changed and, when known, which
+/// of its items — so its screen redraws those rows and every other screen stays as it is.
+pub async fn status_landed(
+ data: &LibraryLock,
+ service: &'static str,
+ changed: bool,
+ items: Option<Items>,
+) -> Refresh {
+ Refresh {
+ changed: Some(if changed { vec![service] } else { Vec::new() }),
+ items: Some(match items {
+ Some(items) if changed => BTreeMap::from([(service, items)]),
+ _ => BTreeMap::new(),
+ }),
+ ..status(data).await
+ }
+}
+
/// What the library already knows, without asking Apple anything.
///
/// The window renders from this the instant it opens, so freshness is on screen before the
@@ -647,6 +695,7 @@ pub async fn status(data: &LibraryLock) -> Refresh {
detail: error,
last_synced_at: found.and_then(|h| h.last_synced_at),
changed: false,
+ items: None,
}
})
.collect();
@@ -655,7 +704,40 @@ pub async fn status(data: &LibraryLock) -> Refresh {
as_of,
took_ms: 0,
changed: None,
+ items: None,
+ }
+}
+
+/// Two rounds' items as one: an item two rounds touched is counted once, as changed — its
+/// screen reads it again either way. More than are worth placing, and it is read whole.
+fn joined(mut all: Items, round: Items) -> Option<Items> {
+ let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
+ for id in all.added.iter().chain(&all.changed).chain(&all.removed) {
+ seen.insert(id.clone());
+ }
+ for (id, list) in round
+ .added
+ .into_iter()
+ .map(|id| (id, 0))
+ .chain(round.changed.into_iter().map(|id| (id, 1)))
+ .chain(round.removed.into_iter().map(|id| (id, 2)))
+ {
+ if seen.contains(&id) {
+ all.added.retain(|x| *x != id);
+ all.removed.retain(|x| *x != id);
+ if !all.changed.contains(&id) {
+ all.changed.push(id);
+ }
+ continue;
+ }
+ seen.insert(id.clone());
+ match list {
+ 0 => all.added.push(id),
+ 1 => all.changed.push(id),
+ _ => all.removed.push(id),
+ }
}
+ (all.len() <= MOST_ITEMS).then_some(all)
}
fn plural(n: usize) -> &'static str {
@@ -674,6 +756,7 @@ fn unavailable(service: &'static str, label: &'static str) -> ServiceReport {
detail: None,
last_synced_at: None,
changed: false,
+ items: None,
}
}
@@ -726,6 +809,7 @@ where
detail: Some("Signed out while this was being read.".into()),
last_synced_at: None,
changed: false,
+ items: None,
};
}
// SQLite is synchronous: a full pass's apply (a whole photo library, every reminder and its
@@ -737,11 +821,18 @@ where
// position land together, or — failing, or the app dying part way — none of them do.
// Whether it stored anything beyond its position is noted on the way, so a pass that found
// nothing new does not have every screen read its whole list again.
- let (result, changed) = tokio::task::block_in_place(|| {
- library.changing(BOOKKEEPING, |library| {
+ //
+ // Which items it changed is noted too — rows stored again just as they were cancel out —
+ // so the screen redraws those rows alone, and a pass that rewrote everything as it was
+ // (a whole address book read again for one card's sake) leaves the rest untouched.
+ let (result, seen) = tokio::task::block_in_place(|| {
+ library.changing_items(BOOKKEEPING, |library| {
fetched.and_then(|value| library.atomically(|library| apply(library, value)))
})
});
+ let items = seen.for_service(service).filter(|i| i.len() <= MOST_ITEMS);
+ // Written, but nothing it shows is different: no screen has anything to read.
+ let changed = seen.written && items.as_ref().is_none_or(|i| !i.is_empty());
let took = started.elapsed();
if took > std::time::Duration::from_millis(50) {
quiet!("{service}: stored in {} ms", took.as_millis());
@@ -754,6 +845,7 @@ where
detail: Some(detail),
last_synced_at: library.last_synced(service).ok().flatten(),
changed,
+ items: if changed { items } else { None },
},
Err(e) => {
let message = e.to_string();
@@ -765,6 +857,7 @@ where
detail: Some(message),
last_synced_at: library.last_synced(service).ok().flatten(),
changed: false,
+ items: None,
}
}
}
@@ -792,6 +885,63 @@ mod tests {
assert_eq!(quiet.services.len(), status(&data).await.services.len());
}
+ /// A service landing names its items with it — for its own screen alone — and one that
+ /// stored nothing new names none.
+ #[tokio::test]
+ async fn a_landing_names_the_items_it_changed() {
+ let data = LibraryLock::new(quince_core::Library::in_memory().unwrap(), None);
+ let items = Items {
+ added: vec!["A".into()],
+ changed: vec!["B".into()],
+ removed: vec![],
+ };
+ let told = status_landed(&data, "contacts", true, Some(items)).await;
+ let json = serde_json::to_value(&told).unwrap();
+ assert_eq!(json["changed"], serde_json::json!(["contacts"]));
+ assert_eq!(
+ json["items"],
+ serde_json::json!({"contacts": {"added": ["A"], "changed": ["B"], "removed": []}})
+ );
+ let whole = status_landed(&data, "contacts", true, None).await;
+ assert_eq!(
+ serde_json::to_value(&whole).unwrap()["items"],
+ serde_json::json!({}),
+ "changed, with no items named: read whole"
+ );
+ let quiet = status_landed(&data, "contacts", false, None).await;
+ assert_eq!(
+ serde_json::to_value(&quiet).unwrap()["changed"],
+ serde_json::json!([])
+ );
+ }
+
+ /// Photos' rounds put together: an item two rounds touched is one change, and too many
+ /// are read whole.
+ #[test]
+ fn rounds_join_into_one_set_of_items() {
+ let ids = |v: &[&str]| v.iter().map(|s| (*s).to_string()).collect::<Vec<_>>();
+ let first = Items {
+ added: ids(&["a"]),
+ changed: ids(&["b"]),
+ removed: vec![],
+ };
+ let second = Items {
+ added: ids(&["c"]),
+ changed: ids(&["a"]),
+ removed: ids(&["d"]),
+ };
+ let all = joined(first, second).unwrap();
+ assert_eq!(all.added, ids(&["c"]));
+ assert_eq!(all.changed, ids(&["b", "a"]));
+ assert_eq!(all.removed, ids(&["d"]));
+ let many = Items {
+ added: (0..=MOST_ITEMS).map(|n| n.to_string()).collect(),
+ changed: vec![],
+ removed: vec![],
+ };
+ assert_eq!(joined(Items::default(), many), None);
+ }
+
#[test]
fn the_default_window_reaches_back_a_month_and_forward_a_quarter() {
let (from, to, _zone) = default_window();
diff --git a/src/lib/ipc.ts b/src/lib/ipc.ts
index 5631c3c..0a3de63 100644
--- a/src/lib/ipc.ts
+++ b/src/lib/ipc.ts
@@ -54,8 +54,16 @@ export type Refresh = {
* only for its own. Absent, every screen reads again.
*/
changed?: string[];
+ /**
+ * For services in `changed` whose items the backend could place, which ones: a screen that
+ * takes them redraws those rows alone. A service in `changed` and not here is read whole.
+ */
+ items?: Record<string, ItemChanges>;
};
+/** What a pass did to one app's items, by their ids. */
+export type ItemChanges = { added: string[]; changed: string[]; removed: string[] };
+
/** Emitted by the backend whenever a refresh finishes, background ones included. */
/** Where each uploading file's progress is announced. */
export const UPLOAD = "quince://upload";
@@ -1112,6 +1120,8 @@ export type AddressEdit =
| { op: "remove"; index: number };
export const contactsApi = {
+ /** These cards alone, whole — those still here. */
+ get: (guids: string[]) => invoke<Contact[]>("contacts_get", { guids }),
/** One card's addresses, part by part. */
addresses: (guid: string) => invoke<PostalAddress[]>("contact_addresses", { guid }),
/** Edits laid over the card's addresses at Apple; answers the list as written. */
diff --git a/src/lib/sync.tsx b/src/lib/sync.tsx
index b5fb808..9366eb0 100644
--- a/src/lib/sync.tsx
+++ b/src/lib/sync.tsx
@@ -9,7 +9,7 @@ import {
type ReactNode,
} from "react";
import { listen } from "@tauri-apps/api/event";
-import { api, messageOf, SYNCED, type Refresh } from "./ipc";
+import { api, messageOf, SYNCED, type ItemChanges, type Refresh } from "./ipc";
import { useScreenActive } from "./screen";
/**
@@ -41,6 +41,10 @@ type Sync = {
serviceErrors: Readonly<Record<string, string>>;
/** When the whole-account pass in flight began (unix seconds), or null. */
passStartedAt: number | null;
+ /** Like `revisions`, but only for changes whose items could not be named (`useItemChanges`). */
+ wholeRevisions: Readonly<Record<string, number>>;
+ /** Be told the items each pass changes in a service, when they are known. */
+ subscribe: (service: string, told: (items: ItemChanges) => void) => () => void;
};
const Context = createContext<Sync | null>(null);
@@ -53,20 +57,47 @@ export function SyncProvider({ children }: { children: ReactNode }) {
const [syncing, setSyncing] = useState(false);
const [revision, setRevision] = useState(0);
const [revisions, setRevisions] = useState<Record<string, number>>({});
+ const [wholeRevisions, setWholeRevisions] = useState<Record<string, number>>({});
const [error, setError] = useState<string | null>(null);
+ /** Who is told of each service's items, as `useItemChanges` asks. */
+ const listeners = useRef(new Map<string, Set<(items: ItemChanges) => void>>());
+ const subscribe = useCallback((service: string, told: (items: ItemChanges) => void) => {
+ const mine = listeners.current.get(service) ?? new Set();
+ listeners.current.set(service, mine);
+ mine.add(told);
+ return () => {
+ mine.delete(told);
+ };
+ }, []);
/**
* A pass landed. With the services it changed named, only their screens read again — and
* none, when it stored nothing new: a clean pass landing every service told every open
* screen to read its whole list seven times. Unnamed, every screen reads again.
*/
- const bump = useCallback((changed?: readonly string[]) => {
+ const bump = useCallback((changed?: readonly string[], items?: Readonly<Record<string, ItemChanges>>) => {
if (Array.isArray(changed) && changed.length === 0) return;
+ const services = Array.isArray(changed) ? changed : ["all"];
setRevision((n) => n + 1);
setRevisions((was) => {
const next = { ...was };
- for (const s of Array.isArray(changed) ? changed : ["all"]) next[s] = (next[s] ?? 0) + 1;
+ for (const s of services) next[s] = (next[s] ?? 0) + 1;
return next;
});
+ // A service whose items are named: those who take them redraw just those rows. The rest —
+ // and every screen that reads by `revisions` — read whole, as before.
+ const whole: string[] = [];
+ for (const s of services) {
+ const named = items?.[s];
+ const told = listeners.current.get(s);
+ if (named && told?.size) for (const tell of told) tell(named);
+ else if (!named) whole.push(s);
+ }
+ if (whole.length)
+ setWholeRevisions((was) => {
+ const next = { ...was };
+ for (const s of whole) next[s] = (next[s] ?? 0) + 1;
+ return next;
+ });
}, []);
// A second click while a pass is running would mean two walks of the same zones.
const inFlight = useRef(false);
@@ -153,7 +184,7 @@ export function SyncProvider({ children }: { children: ReactNode }) {
const stop = listen<Refresh>(SYNCED, (event) => {
if (cancelled) return;
setReport(event.payload);
- bump(event.payload?.changed);
+ bump(event.payload?.changed, event.payload?.items);
});
/*
@@ -182,8 +213,8 @@ export function SyncProvider({ children }: { children: ReactNode }) {
}, [refresh, bump]);
const value = useMemo(
- () => ({ report, syncing, revision, revisions, refresh, error, refreshService, updating, serviceErrors, passStartedAt }),
- [report, syncing, revision, revisions, refresh, error, refreshService, updating, serviceErrors, passStartedAt]
+ () => ({ report, syncing, revision, revisions, refresh, error, refreshService, updating, serviceErrors, passStartedAt, wholeRevisions, subscribe }),
+ [report, syncing, revision, revisions, refresh, error, refreshService, updating, serviceErrors, passStartedAt, wholeRevisions, subscribe]
);
return <Context.Provider value={value}>{children}</Context.Provider>;
}
@@ -217,6 +248,53 @@ export function useShownRevision(...services: string[]): number {
return seen.current;
}
+/**
+ * For a screen that redraws only what a pass changed. `apply` is handed the ids of the items a
+ * pass added, changed and removed in `service`, as each lands; the revision returned moves only
+ * for a change whose items could not be named, which the screen reads whole. A screen kept out
+ * of sight holds both until it comes back, then takes them once — the items put together.
+ *
+ * Every other screen keeps reading by `useRevision`, which moves for both.
+ */
+export function useItemChanges(service: string, apply: (items: ItemChanges) => void): number {
+ const { wholeRevisions, subscribe } = useSync();
+ const whole = (wholeRevisions[service] ?? 0) + (wholeRevisions.all ?? 0);
+ const active = useScreenActive();
+ const seen = useRef(whole);
+ if (active) seen.current = whole;
+ const latest = useRef({ apply, active });
+ latest.current = { apply, active };
+ const waiting = useRef<ItemChanges | null>(null);
+ useEffect(
+ () =>
+ subscribe(service, (items) => {
+ if (latest.current.active) latest.current.apply(items);
+ else waiting.current = joinItems(waiting.current, items);
+ }),
+ [service, subscribe],
+ );
+ useEffect(() => {
+ if (!active || !waiting.current) return;
+ const items = waiting.current;
+ waiting.current = null;
+ latest.current.apply(items);
+ }, [active]);
+ return seen.current;
+}
+
+/** Two passes' items as one: an id named twice is read again once, as changed. */
+export function joinItems(a: ItemChanges | null, b: ItemChanges): ItemChanges {
+ if (!a) return b;
+ const named = new Set([...a.added, ...a.changed, ...a.removed]);
+ const twice = new Set([...b.added, ...b.changed, ...b.removed].filter((id) => named.has(id)));
+ const keep = (ids: string[]) => ids.filter((id) => !twice.has(id));
+ return {
+ added: [...keep(a.added), ...keep(b.added)],
+ changed: [...new Set([...a.changed, ...b.changed, ...twice])],
+ removed: [...keep(a.removed), ...keep(b.removed)],
+ };
+}
+
/** "just now", "4 min ago", "yesterday" — how old the library is, in words. */
export function freshness(asOf: number | null): string {
if (asOf === null) return "Not synced yet";