rindle_replica/

wire_json.rs

//! The replica's JSON wire surface: the shared write-plane codec re-exported wholesale,
//! plus the two renderings that read the ENGINE's own types and therefore cannot live in
//! the write plane — the **flat-change / wire-schema** dialect every native host ships to
//! its client ([`flat_changes_to_json`], [`wire_schema_to_json`]) and the SSR **assembled
//! snapshot** ([`assembled_snapshot_to_json`]).
//!
//! Both read the engine's change model (`FlatChange`/`WireSchema`, `CaughtChange`/
//! `CaughtNode`) — the IVM types a `Graph` produces. `rindle-writeplane` is engine-free
//! by construction (it depends on `rindle-value`, not `rindle`), so this is the lowest
//! crate that can host them. Everything else in the wire codec still lives in the write
//! plane and is re-exported below, so every downstream `rindle_replica::wire_json::…`
//! import site is unchanged.
//!
//! ## One dialect, every native home
//!
//! The flat-change rendering is **byte-for-byte the wasm `Db`'s** (`rindle/src/wasm/
//! marshal.rs`): bare cells (`number | string | boolean | null`), camelCase keys,
//! `{ tag }`-tagged ops — so the SAME `@rindle/client` `ArrayView` folds either backend's
//! stream. It used to live in the napi addon (`rindle-replica-node/src/marshal.rs`); it
//! was lifted here (design 410 PR 0) when a SECOND native home — `rindle-mobile`'s Swift
//! binding — needed the same bytes. Two copies of a wire dialect drift; one function
//! cannot. The addon's `marshal` now re-exports these, and `rindle-mobile`'s
//! `tests/json_shape.rs` pins the output against literal strings.

pub use rindle_writeplane::wire_json::*;

use rindle::value::{RelId, Schema};
use rindle::{CaughtChange, CaughtNode, FlatChange, FlatOp, WireNode, WireRel, WireSchema};
use serde_json::{json, Map, Value};

fn wire_node_to_json(node: &WireNode) -> Value {
    let rels: Vec<Value> = node
        .rels
        .iter()
        .map(|(rel, children)| {
            json!({
                "rel": rel.0 as f64,
                "children": children.iter().map(wire_node_to_json).collect::<Vec<_>>(),
            })
        })
        .collect();
    json!({ "row": wire_row_to_json(&node.row), "rels": rels })
}

fn flat_change_to_json(c: &FlatChange) -> Value {
    let path: Vec<Value> = c
        .path
        .iter()
        .map(|seg| json!({ "rel": seg.rel.0 as f64, "parentRow": wire_row_to_json(&seg.parent_row) }))
        .collect();
    let op = match &c.op {
        FlatOp::Add(node) => json!({ "tag": "add", "node": wire_node_to_json(node) }),
        FlatOp::Remove { row } => json!({ "tag": "remove", "row": wire_row_to_json(row) }),
        FlatOp::Edit { old, new } => {
            json!({ "tag": "edit", "old": wire_row_to_json(old), "new": wire_row_to_json(new) })
        }
    };
    json!({ "path": path, "op": op })
}

/// A batch of flat changes → the JS/Swift-shaped array (the hydrate snapshot, or one
/// commit's events).
pub fn flat_changes_to_json(changes: &[FlatChange]) -> Value {
    Value::Array(changes.iter().map(flat_change_to_json).collect())
}

fn wire_rel_to_json(r: &WireRel) -> Value {
    let child = match &r.child {
        Some(cs) => wire_schema_to_json(cs),
        None => Value::Null,
    };
    // A scalar-projected relationship aggregate (`REDUCE-DESIGN.md` §9) carries
    // `project: { col, identity }` (identity as a bare cell); `null` otherwise.
    let project = match &r.project {
        Some(p) => json!({ "col": p.col as f64, "identity": owned_to_json(&p.identity) }),
        None => Value::Null,
    };
    json!({ "name": r.name.to_string(), "slot": r.slot as f64, "child": child, "project": project })
}

/// A `WireSchema` → the camelCase object the `ArrayView` builds from (handed once in
/// `hello`): `{ columns, primaryKey, sort: [col, asc][], singular, relationships }`.
pub fn wire_schema_to_json(ws: &WireSchema) -> Value {
    let sort: Vec<Value> = ws
        .sort
        .iter()
        .map(|&(c, asc)| json!([c as f64, asc]))
        .collect();
    let mut obj = Map::new();
    obj.insert(
        "columns".into(),
        Value::Array(
            ws.columns
                .iter()
                .map(|c| Value::String(c.to_string()))
                .collect(),
        ),
    );
    obj.insert(
        "primaryKey".into(),
        Value::Array(ws.primary_key.iter().map(|&c| json!(c as f64)).collect()),
    );
    obj.insert("sort".into(), Value::Array(sort));
    obj.insert("singular".into(), Value::Bool(ws.singular));
    obj.insert(
        "relationships".into(),
        Value::Array(ws.relationships.iter().map(wire_rel_to_json).collect()),
    );
    Value::Object(obj)
}

/// [`owned_to_json`] over a flat row's borrowed cell (`rindle::value::Value`).
fn cell_to_json(v: rindle::value::Value<'_>) -> Value {
    owned_to_json(&v.to_owned())
}

/// Render a query's **assembled** view snapshot — the `Add` hydration changes
/// ([`Graph::hydrate_change_sink`](rindle::graph::Graph)) read for the SSR one-shot — to the flat,
/// already-joined wire shape (`SSR-DESIGN.md` §3.3). Unlike the normalized per-table ops, the
/// view is handed back **constructed**: each result node is `{ cols, <rel>: [..] }`, with
/// relationships nested inline by name, so a stateless API server (which runs no IVM engine)
/// can use it directly. Cells are keyed by column name and honor the query's projection;
/// `.one()` levels surface as a single object (or `null`); scalar-projected relationship
/// aggregates (`countAs`) surface as a single scalar field.
pub fn assembled_snapshot_to_json(changes: &[CaughtChange], schema: &Schema) -> Value {
    let rows: Vec<Value> = changes
        .iter()
        .filter_map(|ch| match ch {
            // A hydrate snapshot is `Add`s only; ignore anything else defensively.
            CaughtChange::Add(node) => Some(assembled_node_to_json(node, schema)),
            _ => None,
        })
        .collect();
    Value::Array(rows)
}

fn assembled_node_to_json(node: &CaughtNode, schema: &Schema) -> Value {
    let mut obj = serde_json::Map::new();

    // Cells: keyed by column name, narrowed to the projection when the query has one
    // (rows stay full-width internally — read `columns[col]`/`row[col]` per projected col).
    let mut cols = serde_json::Map::new();
    let col_ids: Vec<usize> = match &schema.projection {
        Some(p) => p.clone(),
        None => (0..schema.columns.len()).collect(),
    };
    for col in col_ids {
        if let (Some(name), Some(val)) = (schema.columns.get(col), node.row.get(col)) {
            cols.insert(name.to_string(), cell_to_json(val));
        }
    }
    obj.insert("cols".to_string(), Value::Object(cols));

    // In-view relationships, nested inline by name (slot = index into `relationships`).
    for (slot, rel) in schema.relationships.iter().enumerate() {
        let children = node.relationships.get(&RelId(slot as u32));
        let Some(child_schema) = rel.child.as_deref() else {
            continue; // join-only relationship (no child schema): not in-view, skip
        };
        if let Some(proj) = &rel.project {
            // Scalar-projected aggregate (REDUCE `countAs`): unwrap the one-row child to a
            // scalar, substituting the identity (e.g. 0) when the parent has no children.
            let val = children
                .and_then(|c| c.first())
                .and_then(|n| n.row.get(proj.col))
                .map(cell_to_json)
                .unwrap_or_else(|| owned_to_json(&proj.identity));
            obj.insert(rel.name.to_string(), val);
            continue;
        }
        let list: Vec<Value> = children
            .map(|c| {
                c.iter()
                    .map(|n| assembled_node_to_json(n, child_schema))
                    .collect()
            })
            .unwrap_or_default();
        let value = if child_schema.singular {
            list.into_iter().next().unwrap_or(Value::Null)
        } else {
            Value::Array(list)
        };
        obj.insert(rel.name.to_string(), value);
    }

    Value::Object(obj)
}