Move files

sync_lib/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "sync_lib"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+base64 = "0.22.1"
+reconcile = { path = "../reconcile" }
+wasm-bindgen = "0.2.99"
+thiserror = { workspace = true }
+
+# The `console_error_panic_hook` crate provides better debugging of panics by
+# logging them with `console.error`. This is great for development, but requires
+# all the `std::fmt` and `std::panicking` infrastructure, so isn't great for
+# code size when deploying.
+console_error_panic_hook = { version = "0.1.7", optional = true }
+
+[dev-dependencies]
+wasm-bindgen-test = "0.3.49"
+insta = "1.42.2"
+
+[features]
+default = ["console_error_panic_hook"]
+
+[lints]
+workspace = true

sync_lib/src/cursor.rs

@@ -0,0 +1,88 @@
+use wasm_bindgen::prelude::*;
+
+/// Wrapper type to expose `TextWithCursors` to JS.
+#[wasm_bindgen]
+#[derive(Debug, Clone, PartialEq)]
+pub struct TextWithCursors {
+    text: String,
+    cursors: Vec<CursorPosition>,
+}
+
+#[wasm_bindgen]
+impl TextWithCursors {
+    #[wasm_bindgen(constructor)]
+    #[must_use]
+    pub fn new(text: String, cursors: Vec<CursorPosition>) -> Self { Self { text, cursors } }
+
+    #[must_use]
+    pub fn text(&self) -> String { self.text.clone() }
+
+    #[must_use]
+    pub fn cursors(&self) -> Vec<CursorPosition> { self.cursors.clone() }
+}
+
+impl From<TextWithCursors> for reconcile::TextWithCursors<'_> {
+    fn from(owned: TextWithCursors) -> Self {
+        reconcile::TextWithCursors::new_owned(
+            owned.text.to_string(),
+            owned
+                .cursors
+                .into_iter()
+                .map(std::convert::Into::into)
+                .collect(),
+        )
+    }
+}
+
+impl From<reconcile::TextWithCursors<'_>> for TextWithCursors {
+    fn from(text_with_cursors: reconcile::TextWithCursors<'_>) -> Self {
+        TextWithCursors {
+            text: text_with_cursors.text.into_owned(),
+            cursors: text_with_cursors
+                .cursors
+                .into_iter()
+                .map(std::convert::Into::into)
+                .collect(),
+        }
+    }
+}
+
+/// Wrapper type to expose `CursorPosition` to JS.
+#[wasm_bindgen]
+#[derive(Debug, Clone, PartialEq)]
+pub struct CursorPosition {
+    id: usize,
+    char_index: usize,
+}
+
+#[wasm_bindgen]
+impl CursorPosition {
+    #[wasm_bindgen(constructor)]
+    #[must_use]
+    pub fn new(id: usize, char_index: usize) -> Self { Self { id, char_index } }
+
+    #[must_use]
+    pub fn id(&self) -> usize { self.id }
+
+    #[wasm_bindgen(js_name = characterPosition)]
+    #[must_use]
+    pub fn char_index(&self) -> usize { self.char_index }
+}
+
+impl From<CursorPosition> for reconcile::CursorPosition {
+    fn from(owned: CursorPosition) -> Self {
+        reconcile::CursorPosition {
+            id: owned.id,
+            char_index: owned.char_index,
+        }
+    }
+}
+
+impl From<reconcile::CursorPosition> for CursorPosition {
+    fn from(cursor: reconcile::CursorPosition) -> Self {
+        CursorPosition {
+            id: cursor.id,
+            char_index: cursor.char_index,
+        }
+    }
+}

sync_lib/src/errors.rs

@@ -0,0 +1,29 @@
+use base64::DecodeError;
+use thiserror::Error;
+use wasm_bindgen::JsValue;
+
+#[derive(Error, Debug)]
+pub enum SyncLibError {
+    #[error("Base64 decoding error because of {}", .reason)]
+    Base64DecodingError { reason: String },
+}
+
+impl From<DecodeError> for SyncLibError {
+    fn from(e: DecodeError) -> Self {
+        SyncLibError::Base64DecodingError {
+            reason: e.to_string(),
+        }
+    }
+}
+
+impl From<std::string::FromUtf8Error> for SyncLibError {
+    fn from(e: std::string::FromUtf8Error) -> Self {
+        SyncLibError::Base64DecodingError {
+            reason: e.to_string(),
+        }
+    }
+}
+
+impl From<SyncLibError> for JsValue {
+    fn from(val: SyncLibError) -> Self { JsValue::from_str(&val.to_string()) }
+}

sync_lib/src/lib.rs

@@ -0,0 +1,152 @@
+//! This crate provides utilities for easily communicating between backend &
+//! frontend and ensuring the same logic for encoding and decoding binary data,
+//! and 3-way-merging documents in Rust and JavaScript.
+//!
+//! The crate is designed to be used as a Rust library and as a
+//! TypeScript/JavaScript package through WebAssembly (WASM).
+//!
+//! # Modules
+//!
+//! - `errors`: Contains error types used in this crate.
+
+use core::str;
+
+use base64::{Engine as _, engine::general_purpose::STANDARD};
+use cursor::TextWithCursors;
+use errors::SyncLibError;
+use wasm_bindgen::prelude::*;
+
+pub mod cursor;
+pub mod errors;
+
+/// Encode binary data for easy transport over HTTP. Inverse of
+/// `base64_to_bytes`.
+///
+/// # Arguments
+///
+/// - `input`: The binary data to encode.
+///
+/// # Returns
+///
+/// The base64-encoded string.
+///
+/// # Panics
+///
+/// If the input is not valid UTF-8.
+#[wasm_bindgen(js_name = bytesToBase64)]
+#[must_use]
+pub fn bytes_to_base64(input: &[u8]) -> String {
+    set_panic_hook();
+
+    STANDARD.encode(input)
+}
+
+/// Inverse of `bytes_to_base64`.
+/// Decode base64-encoded data into binary data.
+///
+/// # Arguments
+///
+/// - `input`: The base64-encoded string.
+///
+/// # Returns
+///
+/// The decoded binary data.
+///
+/// # Errors
+///
+/// If the input is not valid base64.
+#[wasm_bindgen(js_name = base64ToBytes)]
+pub fn base64_to_bytes(input: &str) -> Result<Vec<u8>, SyncLibError> {
+    set_panic_hook();
+
+    STANDARD.decode(input).map_err(SyncLibError::from)
+}
+
+/// Merge two documents with a common parent. Relies on `reconcile::reconcile`
+/// for texts and returns the right document as-is if either of the updated
+/// documents is binary.
+///
+/// # Arguments
+///
+/// - `parent`: The common parent document.
+/// - `left`: The left document updated by one user.
+/// - `right`: The right document updated by another user.
+///
+/// # Returns
+///
+/// The merged document.
+///
+/// # Panics
+///
+/// If any of the input documents are not valid UTF-8 strings.
+#[wasm_bindgen]
+#[must_use]
+pub fn merge(parent: &[u8], left: &[u8], right: &[u8]) -> Vec<u8> {
+    set_panic_hook();
+
+    if is_binary(parent) || is_binary(left) || is_binary(right) {
+        right.to_vec()
+    } else {
+        reconcile::reconcile(
+            str::from_utf8(parent).expect("parent must be valid UTF-8 because it's not binary"),
+            str::from_utf8(left).expect("left must be valid UTF-8 because it's not binary"),
+            str::from_utf8(right).expect("right must be valid UTF-8 because it's not binary"),
+        )
+        .into_bytes()
+    }
+}
+
+/// WASM wrapper around `reconcile::reconcile` for merging text.
+#[wasm_bindgen(js_name = mergeText)]
+#[must_use]
+pub fn merge_text(parent: &str, left: &str, right: &str) -> String {
+    set_panic_hook();
+
+    reconcile::reconcile(parent, left, right)
+}
+
+/// WASM wrapper around `reconcile::reconcile_with_cursors` for merging text.
+#[wasm_bindgen(js_name = mergeTextWithCursors)]
+#[must_use]
+pub fn merge_text_with_cursors(
+    parent: &str,
+    left: TextWithCursors,
+    right: TextWithCursors,
+) -> TextWithCursors {
+    set_panic_hook();
+
+    reconcile::reconcile_with_cursors(parent, left.into(), right.into()).into()
+}
+
+/// Heuristically determine if the given data is a binary or a text file's
+/// content.
+#[wasm_bindgen(js_name = isBinary)]
+#[must_use]
+pub fn is_binary(data: &[u8]) -> bool {
+    set_panic_hook();
+
+    if data.contains(&0) {
+        // Even though the NUL character is valid in UTF-8, it's highly suspicious in
+        // human-readable text.
+        return true;
+    }
+
+    std::str::from_utf8(data).is_err()
+}
+
+/// We don't want to support merging structured data like JSON, YAML, etc.
+#[wasm_bindgen(js_name = isFileTypeMergable)]
+#[must_use]
+pub fn is_file_type_mergable(path_or_file_name: &str) -> bool {
+    set_panic_hook();
+
+    let file_extension = path_or_file_name.split('.').next_back().unwrap_or_default();
+
+    matches!(file_extension.to_lowercase().as_str(), "md" | "txt")
+}
+
+fn set_panic_hook() {
+    // https://github.com/rustwasm/console_error_panic_hook#readme
+    #[cfg(feature = "console_error_panic_hook")]
+    console_error_panic_hook::set_once();
+}

sync_lib/tests/snapshots/web__base64_to_bytes_error.snap

@@ -0,0 +1,10 @@
+---
+source: sync_lib/tests/web.rs
+expression: base64_to_bytes(input)
+snapshot_kind: text
+---
+Err(
+    Base64DecodingError {
+        reason: "Invalid symbol 61, offset 0.",
+    },
+)

sync_lib/tests/web.rs

@@ -0,0 +1,99 @@
+use insta::assert_debug_snapshot;
+use sync_lib::{
+    cursor::{CursorPosition, TextWithCursors},
+    *,
+};
+use wasm_bindgen_test::*;
+
+#[wasm_bindgen_test(unsupported = test)]
+fn test_bytes_to_base64() {
+    let input = b"hello";
+    let expected = "aGVsbG8=";
+    assert_eq!(bytes_to_base64(input), expected);
+}
+
+#[wasm_bindgen_test(unsupported = test)]
+fn test_base64_to_bytes() {
+    let input = "aGVsbG8=";
+    let expected = b"hello".to_vec();
+    assert_eq!(base64_to_bytes(input).unwrap(), expected);
+}
+
+#[test] // insta doesn't support wasm-bindgen-test
+fn test_base64_to_bytes_error() {
+    let input = "===";
+    assert_debug_snapshot!(base64_to_bytes(input));
+}
+
+#[wasm_bindgen_test(unsupported = test)]
+fn test_merge() {
+    let left = b"hello ";
+    let right = b"world";
+    let result = merge(b"", left, right);
+    assert_eq!(result, b"hello world");
+
+    let left = b"\0binary";
+    let right = b"other";
+    let result = merge(b"", left, right);
+    assert_eq!(result, right);
+}
+
+#[wasm_bindgen_test(unsupported = test)]
+fn test_merge_text() {
+    let left = "hello ";
+    let right = "world";
+    let result = merge_text("", left, right);
+    assert_eq!(result, "hello world");
+}
+
+#[wasm_bindgen_test(unsupported = test)]
+fn test_merge_text_with_cursors() {
+    let result = merge_text_with_cursors(
+        "hi",
+        TextWithCursors::new("hi world".to_owned(), vec![]),
+        TextWithCursors::new(
+            "hi".to_owned(),
+            vec![CursorPosition::new(0, 1), CursorPosition::new(1, 2)],
+        ),
+    );
+
+    assert_eq!(
+        result,
+        TextWithCursors::new(
+            "hi world".to_owned(),
+            vec![CursorPosition::new(0, 1), CursorPosition::new(1, 2)]
+        ),
+    );
+}
+
+#[wasm_bindgen_test(unsupported = test)]
+fn merge_binary() {
+    let left = [0, 1, 2];
+    let right = [3, 4, 5];
+    assert_eq!(merge(b"", &left, &right), right);
+}
+
+#[wasm_bindgen_test(unsupported = test)]
+fn test_is_binary() {
+    assert!(is_binary(&[0, 159, 146, 150]));
+    assert!(is_binary(&[0, 12]));
+    assert!(!is_binary(b"hello"));
+}
+
+#[wasm_bindgen_test(unsupported = test)]
+fn test_is_binary_empty() {
+    assert!(!is_binary(b""));
+}
+
+#[wasm_bindgen_test(unsupported = test)]
+fn test_is_file_type_mergable() {
+    assert!(is_file_type_mergable(".md"));
+    assert!(is_file_type_mergable("hi.md"));
+    assert!(is_file_type_mergable("my/path/to/my/document.md"));
+    assert!(is_file_type_mergable("hi.MD"));
+    assert!(is_file_type_mergable("my/path/to/my/DOCUMENT.MD"));
+
+    assert!(!is_file_type_mergable(".json"));
+    assert!(!is_file_type_mergable("HELLO.JSON"));
+    assert!(!is_file_type_mergable("my/config.yml"));
+}