Serde Performance: Borrowing, Zero-Copy, Streaming, and Buffer Reuse

24 min read

In JavaScript, JSON.parse is a black box: it always builds a brand-new tree of objects and strings, copying every byte of input into the heap, and you have no levers to pull. Serde gives you those levers. By choosing the right field types and APIs you can parse JSON that borrows directly from the input buffer (zero string copies), stream millions of records without ever holding them all in memory, and reuse a single allocation across an entire workload. This page is about spending Serde’s flexibility where it pays off.

Quick Overview

Serde’s default path — derive Deserialize, parse into a struct full of Strings and Vecs — is already fast and is the right default for almost everything. The performance toolkit on top of that is: borrowed deserialization (&str / #[serde(borrow)] so string fields point into the input instead of being copied), streaming (from_reader and StreamDeserializer so you process one value at a time), avoiding serde_json::Value (parse straight into typed structs instead of building a dynamic tree), and buffer reuse (clear() + to_writer into a kept-capacity buffer). For a TypeScript developer the mental shift is that the shape of your types is itself a performance decision — there is no single fixed parse like JSON.parse.

Note: Reach for these techniques only when a profiler points here. Borrowing and streaming add lifetime and structural constraints; the typed String-field path is the correct starting point. Optimize the hot loop, not the config-file load that runs once at startup.

TypeScript/JavaScript Example

Here is a typical Node.js hot path: reading a large newline-delimited JSON (NDJSON) log file and summing a numeric field per category. This is the kind of code where, at scale, allocation pressure starts to dominate.

1
import { createReadStream } from "node:fs";
2
import { createInterface } from "node:readline";
3

4
interface Sample {
5
  metric: string;
6
  value: number;
7
}
8

9
async function aggregate(path: string): Promise<Map<string, number>> {
10
  const totals = new Map<string, number>();
11
  const rl = createInterface({ input: createReadStream(path) });
12

13
  for await (const line of rl) {
14
    if (line.trim() === "") continue;
15
    // JSON.parse builds a fresh object AND a fresh copy of the
16
    // "metric" string for every single line — no way to avoid it.
17
    const sample = JSON.parse(line) as Sample;
18
    totals.set(sample.metric, (totals.get(sample.metric) ?? 0) + sample.value);
19
  }
20
  return totals;
21
}

Two costs are unavoidable in this JavaScript version. First, JSON.parse allocates a new object plus a fresh string for metric on every line, even though we only need it briefly to look up a map key. Second, the as Sample cast is a compile-time fiction — a malformed line is not caught here, it surfaces as NaN or undefined somewhere downstream. Rust lets you eliminate the first cost and closes the second by construction.

Rust Equivalent

The Rust version borrows the metric string straight out of the line buffer (no per-record string allocation), reuses one String for reading lines, and never builds an intermediate dynamic tree. The current stable toolchain is Rust 1.96.0 on the 2024 edition; cargo new selects it automatically.

1
cargo new ndjson_agg
2
cd ndjson_agg
3
cargo add serde --features derive
4
cargo add serde_json

1
use serde::Deserialize;
2
use std::collections::HashMap;
3
use std::io::{BufRead, BufReader, Cursor};
4

5
// Borrowed: `metric` points INTO the line buffer. No per-record String
6
// allocation for the metric name — Serde hands back a slice of the input.
7
#[derive(Debug, Deserialize)]
8
struct Sample<'a> {
9
    metric: &'a str,
10
    value: f64,
11
}
12

13
// Process a JSON Lines stream, reusing a single line buffer across all
14
// records and never building a serde_json::Value.
15
fn aggregate<R: BufRead>(mut reader: R) -> std::io::Result<HashMap<String, f64>> {
16
    let mut totals: HashMap<String, f64> = HashMap::new();
17
    let mut line = String::new();
18

19
    loop {
20
        line.clear(); // reuse the allocation; keeps capacity
21
        let n = reader.read_line(&mut line)?;
22
        if n == 0 {
23
            break; // EOF
24
        }
25
        let trimmed = line.trim();
26
        if trimmed.is_empty() {
27
            continue;
28
        }
29
        // Borrowed deserialize straight out of `line`.
30
        let sample: Sample = match serde_json::from_str(trimmed) {
31
            Ok(s) => s,
32
            Err(e) => {
33
                eprintln!("skipping bad line: {e}");
34
                continue;
35
            }
36
        };
37
        // We only need an owned key when inserting a NEW entry into the map.
38
        *totals.entry(sample.metric.to_owned()).or_insert(0.0) += sample.value;
39
    }
40

41
    Ok(totals)
42
}
43

44
fn main() -> std::io::Result<()> {
45
    let input = "\
46
{\"metric\":\"requests\",\"value\":12.0}
47
{\"metric\":\"errors\",\"value\":1.0}
48
{\"metric\":\"requests\",\"value\":8.0}
49
{\"metric\":\"errors\",\"value\":2.0}
50
";
51
    let reader = BufReader::new(Cursor::new(input));
52
    let mut totals = aggregate(reader)?;
53

54
    // Sort for deterministic output.
55
    let mut sorted: Vec<_> = totals.drain().collect();
56
    sorted.sort_by(|a, b| a.0.cmp(&b.0));
57
    for (metric, total) in sorted {
58
        println!("{metric}: {total}");
59
    }
60
    Ok(())
61
}

Real output from cargo run:

1
errors: 3
2
requests: 20

The Sample<'a> struct’s metric: &'a str is the key move: during parsing, Serde points that field at the bytes already sitting in line, instead of allocating and copying a new String. The only allocation per record happens when a new category appears in the map. Everything else — the line buffer, the parse — reuses memory you already have.

Detailed Explanation

Let’s unpack each performance lever in the Rust version and contrast it with what JavaScript forces on you.

Borrowed deserialization (`&str`)

When you declare a field as &'a str instead of String, you are telling Serde: do not copy this string; hand me a slice that points into the input. This is zero-copy deserialization. Compare the two struct definitions:

1
use serde::Deserialize;
2

3
// Owning: every string field is a fresh heap allocation + memcpy.
4
#[derive(Deserialize)]
5
struct Owned {
6
    level: String,
7
    message: String,
8
}
9

10
// Borrowing: string fields are slices into the parsed input. No copies.
11
#[derive(Deserialize)]
12
struct Borrowed<'a> {
13
    level: &'a str,
14
    message: &'a str,
15
}
16

17
fn main() {
18
    let data = r#"{"level":"error","message":"disk full"}"#;
19
    let owned: Owned = serde_json::from_str(data).unwrap();
20
    let borrowed: Borrowed = serde_json::from_str(data).unwrap();
21
    println!("{} / {}", owned.message, borrowed.message);
22
}

The lifetime 'a ties Borrowed to the buffer it was parsed from. The compiler enforces that the struct cannot outlive the input — there is no such thing as a dangling slice in safe Rust. JavaScript has no equivalent: JSON.parse always materializes fresh, fully-owned strings, and the GC cleans them up later. Rust’s borrow is the price-free option when the input outlives the parsed value, and a compile error otherwise (we hit that error in Common Pitfalls).

This is the deserialization counterpart of the broader ownership story; if &str versus String is still fuzzy, see Section 05: Ownership.

When a borrow can’t happen: escapes and `Cow`

A &str field can only borrow if the string appears verbatim in the input. JSON allows escapes (\n, \", \uXXXX), and the unescaped bytes do not exist contiguously in the source — Serde would have to allocate to produce them. A plain &str field therefore fails at runtime on an escaped string. The escape-tolerant choice is Cow<'a, str> (“clone on write”): it borrows when it can and allocates only when it must.

1
use serde::Deserialize;
2
use std::borrow::Cow;
3

4
// `#[serde(borrow)]` tells the derive to generate a BORROWING impl for Cow.
5
// Without it, Cow always allocates (owns) — see Common Pitfalls.
6
#[derive(Debug, Deserialize)]
7
struct Message<'a> {
8
    #[serde(borrow)]
9
    text: Cow<'a, str>,
10
}
11

12
fn main() {
13
    // No escapes: Cow borrows (zero-copy).
14
    let plain = r#"{"text":"hello world"}"#;
15
    let m1: Message = serde_json::from_str(plain).unwrap();
16
    println!("{:?} -> borrowed = {}", m1.text, matches!(m1.text, Cow::Borrowed(_)));
17

18
    // Contains an escape: Cow must own a freshly-unescaped String.
19
    let escaped = r#"{"text":"line1\nline2"}"#;
20
    let m2: Message = serde_json::from_str(escaped).unwrap();
21
    println!("{:?} -> borrowed = {}", m2.text, matches!(m2.text, Cow::Borrowed(_)));
22
}

Real output from cargo run:

1
"hello world" -> borrowed = true
2
"line1\nline2" -> borrowed = false

Cow<'a, str> is the pragmatic default for borrowed string fields when you cannot guarantee escape-free input: the common (no-escape) case stays zero-copy, and the rare escaped case still works correctly.

`#[serde(borrow)]`

The derive macro auto-detects the borrow for a plain &'a str field. For Cow<'a, str>, it does not — it defaults to the owning implementation unless you opt in with #[serde(borrow)]. That single attribute switches the generated code to the borrowing variant. The other place you need it explicitly is when a borrowed lifetime is buried inside your own generic wrapper types where the derive cannot infer the intent.

Streaming with `from_reader` and `StreamDeserializer`

serde_json::from_str parses one value from a fully-loaded string. For a multi-gigabyte file or a network socket you do not want the whole thing in memory. Deserializer::from_reader(...).into_iter::<T>() gives you a StreamDeserializer: an iterator that pulls one JSON value at a time from any Read source.

1
use serde::Deserialize;
2
use std::io::Cursor;
3

4
#[derive(Debug, Deserialize)]
5
struct Event {
6
    id: u32,
7
    kind: String,
8
}
9

10
fn main() {
11
    // Whitespace-separated JSON values (JSON Lines style). The stream
12
    // reader processes them one at a time — no Vec<Event>, no big String.
13
    let ndjson = r#"
14
        {"id":1,"kind":"click"}
15
        {"id":2,"kind":"scroll"}
16
        {"id":3,"kind":"close"}
17
    "#;
18

19
    let reader = Cursor::new(ndjson);
20
    let stream = serde_json::Deserializer::from_reader(reader).into_iter::<Event>();
21

22
    let mut count = 0u32;
23
    for event in stream {
24
        let event = event.unwrap();
25
        count += 1;
26
        println!("event #{count}: id={} kind={}", event.id, event.kind);
27
    }
28
    println!("processed {count} events");
29
}

Real output from cargo run:

1
event #1: id=1 kind=click
2
event #2: id=2 kind=scroll
3
event #3: id=3 kind=close

Memory use stays flat regardless of input size, because only one Event exists at a time. The catch — which trips up newcomers — is that from_reader cannot borrow from its input (the reader owns its buffer transiently), so streamed types must be fully owned (String, not &str). We show that exact compiler error in Common Pitfalls.

Avoiding `serde_json::Value`

serde_json::Value is the dynamic, JavaScript-object-like representation: an enum tree where every object key is a heap String, every nested array/object is its own allocation, and numbers are stored generically. It is the right tool when the shape is genuinely unknown (json-manipulation.md), but on a hot path it is the slow option because you pay to build the entire tree even if you read one field.

1
use serde::Deserialize;
2
use serde_json::Value;
3

4
#[derive(Debug, Deserialize)]
5
struct User {
6
    id: u64,
7
    name: String,
8
}
9

10
fn main() {
11
    let data = r#"{"id":42,"name":"Ada","extra":{"nested":[1,2,3]},"flag":true}"#;
12

13
    // Approach A: parse into Value (dynamic). Builds the WHOLE tree —
14
    // including `extra` and `flag` — allocating a String for every key.
15
    let v: Value = serde_json::from_str(data).unwrap();
16
    println!("via Value: id={}, name={}", v["id"], v["name"].as_str().unwrap());
17

18
    // Approach B: parse into a typed struct. Serde skips `extra` and
19
    // `flag` entirely and builds only the two fields you declared.
20
    let user: User = serde_json::from_str(data).unwrap();
21
    println!("via struct: id={} name={}", user.id, user.name);
22
}

Real output from cargo run:

1
via Value: id=42, name=Ada
2
via struct: id=42 name=Ada

Both print the same two values, but they do very different amounts of work. The typed parse ignores extra and flag and allocates nothing for them, while the Value parse builds and allocates the full nested tree — a String for every key, a boxed variant for every value. If you only need a couple of fields, a minimal struct with just those fields (unknown fields are ignored by default) is dramatically cheaper than Value.

Buffer reuse on the serialize side

serde_json::to_string allocates a fresh String every call. In a loop that serializes many values, reuse one buffer instead: to_writer appends into any Write target, and Vec::clear() drops the contents while keeping the capacity.

1
use serde::Serialize;
2

3
#[derive(Serialize)]
4
struct Metric {
5
    name: &'static str,
6
    value: f64,
7
}
8

9
fn main() {
10
    let metrics = vec![
11
        Metric { name: "cpu", value: 0.42 },
12
        Metric { name: "mem", value: 0.71 },
13
        Metric { name: "disk", value: 0.13 },
14
    ];
15

16
    // ONE byte buffer reused for every record. After the first iteration
17
    // no further allocation happens — clear() keeps the capacity.
18
    let mut buf: Vec<u8> = Vec::new();
19

20
    for m in &metrics {
21
        buf.clear();
22
        serde_json::to_writer(&mut buf, m).unwrap();
23
        // The buffer holds UTF-8 JSON bytes; view them as &str to print.
24
        println!("{}", std::str::from_utf8(&buf).unwrap());
25
    }
26

27
    println!("final buffer capacity = {}", buf.capacity());
28
}

Real output from cargo run:

1
{"name":"cpu","value":0.42}
2
{"name":"mem","value":0.71}
3
{"name":"disk","value":0.13}
4
final buffer capacity = 32

The buffer was allocated once and held its 32-byte capacity through all three serializations. JavaScript gives you no control here: JSON.stringify always returns a brand-new string and the GC reclaims the old ones.

Key Differences

Concern	TypeScript / JavaScript	Rust + Serde
String fields on parse	Always copied into new `string`s	`&str` borrows from input (zero-copy); `String` copies; `Cow` does both
Who owns parsed strings	The GC; always heap, always owned	You choose: borrow the buffer or own a copy
Streaming a huge file	Manual `readline` + per-line `JSON.parse`	`StreamDeserializer` iterates values lazily
Dynamic vs typed	Always dynamic objects (`any`)	`Value` (dynamic, allocates tree) vs typed struct (skips unwanted fields)
Reusing a serialize buffer	Impossible — `JSON.stringify` returns a fresh string	`to_writer` + `clear()` reuses one allocation
Unwanted fields on parse	Materialized anyway, then ignored by you	Skipped by the parser; never allocated
Safety of borrowing	N/A (everything copied)	Borrow checker guarantees no dangling slice, at compile time

Three points deserve emphasis for a TypeScript developer:

There is no one “parse”. JSON.parse is a single fixed operation. In Rust the type you parse into decides how much work happens. A struct with three &str fields and one with three String fields parse the same JSON very differently.
Borrowing is checked, not hoped. A borrowed parse result is tied by lifetime to its input buffer. If you try to keep it after the buffer is gone, the program does not compile. This is the opposite of the “use-after-free” class of bug — it is impossible by construction.
Cheap-by-default skipping. A typed struct ignores fields it does not declare during parsing, so a 50-field JSON payload from which you need two fields costs roughly two fields’ worth of work. The dynamic-everything JSON.parse model cannot do this.

Common Pitfalls

Trying to borrow an escaped string into `&str`

A &str field cannot hold an escaped string, because the unescaped bytes are not contiguous in the source. Serde reports this at runtime as a deserialization error:

1
use serde::Deserialize;
2

3
#[derive(Debug, Deserialize)]
4
struct Message<'a> {
5
    text: &'a str,
6
}
7

8
fn main() {
9
    let escaped = r#"{"text":"line1\nline2"}"#; // contains an escape
10
    match serde_json::from_str::<Message>(escaped) {
11
        Ok(m) => println!("ok: {}", m.text),
12
        Err(e) => println!("error: {e}"),
13
    }
14
}

Real output from cargo run:

1
error: invalid type: string "line1\nline2", expected a borrowed string at line 1 column 22

The fix is to use Cow<'a, str> with #[serde(borrow)] (borrows when possible, allocates on escapes) or fall back to an owned String if borrowing buys you nothing here.

Returning a borrowed struct that outlives its buffer

This is the classic lifetime error. A borrowed struct points into a buffer; if that buffer is a local that gets dropped, you cannot return the struct:

1
use serde::Deserialize;
2

3
#[derive(Debug, Deserialize)]
4
struct LogEntry<'a> {
5
    level: &'a str,
6
    message: &'a str,
7
}
8

9
fn parse_owned() -> LogEntry<'static> {
10
    let data = String::from(r#"{"level":"info","message":"started"}"#);
11
    let entry: LogEntry = serde_json::from_str(&data).unwrap();
12
    entry // does not compile (error[E0515]): returns a value referencing `data`, dropped here
13
}
14

15
fn main() {
16
    let e = parse_owned();
17
    println!("{e:?}");
18
}

The real compiler error:

1
error[E0515]: cannot return value referencing local variable `data`
2
  --> src/main.rs:12:5
3
   |
4
11 |     let entry: LogEntry = serde_json::from_str(&data).unwrap();
5
   |                                                ----- `data` is borrowed here
6
12 |     entry // does not compile (error[E0515]): returns a value referencing `data`, dropped here
7
   |     ^^^^^ returns a value referencing data owned by the current function
8

9
For more information about this error, try `rustc --explain E0515`.

The fix is to either keep the buffer alive in the caller and parse there, or use an owning struct (String fields) so the result does not depend on the buffer’s lifetime. Borrowing is for when the input genuinely outlives the parsed value (as in a request handler that holds the body for the duration of the handler).

Expecting `from_reader` to borrow

from_reader and StreamDeserializer work over a transient internal buffer, so they can only produce owned types. Asking for a borrowed type is a compile error:

1
use serde::Deserialize;
2
use std::io::Cursor;
3

4
#[derive(Debug, Deserialize)]
5
struct Borrowed<'a> {
6
    name: &'a str,
7
}
8

9
fn main() {
10
    let reader = Cursor::new(r#"{"name":"x"}"#);
11
    // does not compile: from_reader cannot produce borrowed data.
12
    let b: Borrowed = serde_json::from_reader(reader).unwrap();
13
    println!("{b:?}");
14
}

The real compiler error:

1
error: implementation of `Deserialize` is not general enough
2
  --> src/main.rs:12:23
3
   |
4
12 |     let b: Borrowed = serde_json::from_reader(reader).unwrap();
5
   |                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ implementation of `Deserialize` is not general enough
6
   |
7
   = note: `Borrowed<'_>` must implement `Deserialize<'0>`, for any lifetime `'0`...
8
   = note: ...but `Borrowed<'_>` actually implements `Deserialize<'1>`, for some specific lifetime `'1`

The cryptic “not general enough” message is Serde’s way of saying the type only implements the borrowing Deserialize<'de>, but from_reader needs the owning DeserializeOwned. The fix: use String fields for streamed types, or, if you must borrow, read the whole input into a String first and use from_str.

Forgetting `#[serde(borrow)]` on `Cow`

Without the attribute, the derive generates the owning implementation for a Cow<'a, str> field — it always allocates, silently defeating the point:

1
use serde::Deserialize;
2
use std::borrow::Cow;
3

4
#[derive(Debug, Deserialize)]
5
struct Doc<'a> {
6
    body: Cow<'a, str>, // no #[serde(borrow)] -> always owns/allocates
7
}
8

9
fn main() {
10
    let data = r#"{"body":"plain text no escapes"}"#;
11
    let d: Doc = serde_json::from_str(data).unwrap();
12
    println!("borrowed = {}", matches!(d.body, Cow::Borrowed(_)));
13
}

Real output from cargo run:

1
borrowed = false

It compiles and runs — it is just quietly slower than you intended (borrowed = false means it allocated). Adding #[serde(borrow)] flips that to true for escape-free input. This one bites because it is not an error; it is a silent missed optimization. (A plain &'a str field, by contrast, auto-borrows without the attribute.)

Reaching for `Value` when a typed struct would do

If you find yourself writing let v: Value = from_str(...)?; and then v["a"]["b"].as_str(), you are paying to build and allocate the whole tree, then indexing it dynamically (which also loses the compile-time type checks). A small typed struct with just the fields you need is faster and safer. Save Value for genuinely schema-less input — see json-manipulation.md for when that is the right call.

Best Practices

Start with owned String fields; borrow only when profiling says so. The owning path is simpler, has no lifetime constraints, and is plenty fast for the vast majority of code. Borrowing is a hot-loop optimization, not a default.
Prefer &str for borrowed fields you control, Cow<'a, str> when escapes are possible. Use &str when you can guarantee escape-free input (or are happy to error on escapes); use Cow<'a, str> with #[serde(borrow)] for the safe, escape-tolerant zero-copy path.
Parse from &[u8] with from_slice to skip a String step. When you already hold bytes (an HTTP body, a memory-mapped file), serde_json::from_slice(&bytes) borrows directly and avoids constructing an intermediate String. Borrowed &str fields can point straight into those bytes.
Stream large or unbounded inputs. Use Deserializer::from_reader(BufReader::new(file)).into_iter::<T>() for files or sockets so memory stays flat. Remember streamed types must be owned.
Reuse buffers in serialize loops. to_writer(&mut buf, &value) plus buf.clear() reuses one allocation across many records. For files and sockets, to_writer(BufWriter::new(...), &value) avoids an intermediate String entirely.
Parse into the narrowest typed struct, not Value. Declare only the fields you need; Serde skips the rest during parsing for free. Reserve serde_json::Value for dynamic, schema-unknown data.
Pre-size buffers when the count is known. Vec::with_capacity(n) / String::with_capacity(n) avoid reallocation churn when you can estimate the output size up front.
Benchmark with criterion, do not guess. Before and after any of these changes, measure. Serde’s defaults are well-tuned; confirm the optimization is real on your data and workload. See Section 13: Testing for the testing and benchmarking toolchain.

Real-World Example

A production-flavored task: a metrics ingestion service receives a request body containing many NDJSON samples, parses each with a borrowed struct (zero string copies for the metric label), aggregates per-label totals, and serializes a compact summary back out — reusing a single output buffer. This is a complete, runnable src/main.rs using only serde (with derive) and serde_json.

1
use serde::{Deserialize, Serialize};
2
use std::collections::BTreeMap;
3
use std::io::{BufRead, BufReader, Read};
4

5
// Borrowed input: `label` is a slice into the line buffer, not a copy.
6
#[derive(Debug, Deserialize)]
7
struct Sample<'a> {
8
    label: &'a str,
9
    value: f64,
10
}
11

12
// Owned output: a summary we build and hand back. BTreeMap keeps keys
13
// sorted, which makes the serialized output deterministic.
14
#[derive(Debug, Serialize)]
15
struct Summary {
16
    total_samples: u64,
17
    sums: BTreeMap<String, f64>,
18
}
19

20
// Ingest a JSON Lines stream from any reader, reusing one line buffer and
21
// borrowing each record's label. Returns a typed Summary.
22
fn ingest<R: Read>(reader: R) -> std::io::Result<Summary> {
23
    let mut reader = BufReader::new(reader);
24
    let mut line = String::new();
25
    let mut sums: BTreeMap<String, f64> = BTreeMap::new();
26
    let mut total_samples = 0u64;
27

28
    loop {
29
        line.clear(); // reuse the allocation across all lines
30
        if reader.read_line(&mut line)? == 0 {
31
            break; // EOF
32
        }
33
        let trimmed = line.trim();
34
        if trimmed.is_empty() {
35
            continue;
36
        }
37
        match serde_json::from_str::<Sample>(trimmed) {
38
            Ok(sample) => {
39
                total_samples += 1;
40
                // Allocate an owned key only for a new label.
41
                *sums.entry(sample.label.to_owned()).or_insert(0.0) += sample.value;
42
            }
43
            Err(e) => eprintln!("dropping malformed sample: {e}"),
44
        }
45
    }
46

47
    Ok(Summary { total_samples, sums })
48
}
49

50
fn main() -> Result<(), Box<dyn std::error::Error>> {
51
    // Stand-in for an HTTP request body: raw bytes of NDJSON.
52
    let body: &[u8] = b"\
53
{\"label\":\"http_2xx\",\"value\":120.0}
54
{\"label\":\"http_5xx\",\"value\":3.0}
55
{\"label\":\"http_2xx\",\"value\":80.0}
56
{\"label\":\"bogus line, not json\"}
57
{\"label\":\"http_4xx\",\"value\":12.0}
58
";
59

60
    let summary = ingest(body)?;
61

62
    // Serialize the response by reusing a single output buffer.
63
    let mut out: Vec<u8> = Vec::with_capacity(256);
64
    serde_json::to_writer(&mut out, &summary)?;
65

66
    println!("response body: {}", std::str::from_utf8(&out)?);
67
    println!("accepted {} valid samples", summary.total_samples);
68
    Ok(())
69
}

Real output from cargo run:

1
dropping malformed sample: missing field `value` at line 1 column 32
2
response body: {"total_samples":4,"sums":{"http_2xx":200.0,"http_4xx":12.0,"http_5xx":3.0}}
3
accepted 4 valid samples

Notice the pipeline’s properties: input is read line-by-line into one reused buffer; each valid sample’s label is borrowed (no string copy) and only promoted to an owned String when it first appears as a map key; the malformed line is rejected at the parse boundary with a precise message rather than poisoning the totals; and the response is written into a pre-sized, reused byte buffer. None of these optimizations changed the readability of the code, and every one of them is checked by the compiler. In a real service this ingest function would sit behind an HTTP handler — see Section 16: Web APIs for wiring serialized structs to request and response bodies.

Exercises

Exercise 1: Convert an owning struct to a borrowing one

Difficulty: Easy

Objective: Turn a String-based struct into a zero-copy borrowed struct and prove the borrow works.

Instructions: Start from the owning Token below. Rewrite it to borrow its two string fields from the input (&'a str with a lifetime parameter), then write a function first_token(src: &str) -> Token<'_> that parses it. Parse the literal {"kind":"ident","lexeme":"user_count"} and print both fields. Confirm it compiles and runs.

1
use serde::Deserialize;
2

3
// TODO: make this borrow from the input instead of allocating two Strings.
4
#[derive(Debug, Deserialize)]
5
struct Token {
6
    kind: String,
7
    lexeme: String,
8
}
9

10
fn main() {
11
    let src = r#"{"kind":"ident","lexeme":"user_count"}"#;
12
    // TODO: parse `src` into a borrowing Token and print kind + lexeme.
13
}

Solution

1
use serde::Deserialize;
2

3
#[derive(Debug, Deserialize)]
4
struct Token<'a> {
5
    kind: &'a str,
6
    lexeme: &'a str,
7
}
8

9
fn first_token(src: &str) -> Token<'_> {
10
    serde_json::from_str(src).unwrap()
11
}
12

13
fn main() {
14
    let src = r#"{"kind":"ident","lexeme":"user_count"}"#;
15
    let tok = first_token(src);
16
    println!("{} = {:?}", tok.kind, tok.lexeme);
17
}

Real output from cargo run:

1
ident = "user_count"

The Token<'a> lifetime ties the parsed struct to src. The -> Token<'_> return type lets the compiler infer that the returned token borrows from the src argument. No String is allocated; both fields are slices into src.

Exercise 2: Stream-sum NDJSON without holding it all in memory

Difficulty: Medium

Objective: Use StreamDeserializer to sum a field across many JSON values without collecting them into a Vec.

Instructions: Write sum_totals<R: std::io::Read>(reader: R) -> Result<f64, serde_json::Error> that reads a stream of {"total": <number>} objects and returns the sum of all total fields. Use serde_json::Deserializer::from_reader(...).into_iter::<Order>() and accumulate as you iterate — never build a Vec<Order>. Test it on {"total":19.99}{"total":4.50}{"total":100.00} (note: no separators needed, JSON values are self-delimiting). Remember that streamed types must be owned.

1
use serde::Deserialize;
2
use std::io::Cursor;
3

4
#[derive(Deserialize)]
5
struct Order {
6
    total: f64,
7
}
8

9
// TODO: stream-sum the `total` fields without collecting into a Vec.
10
fn sum_totals<R: std::io::Read>(reader: R) -> Result<f64, serde_json::Error> {
11
    todo!()
12
}
13

14
fn main() -> Result<(), serde_json::Error> {
15
    let ndjson = r#"{"total":19.99}{"total":4.50}{"total":100.00}"#;
16
    let sum = sum_totals(Cursor::new(ndjson))?;
17
    println!("sum = {sum:.2}");
18
    Ok(())
19
}

Solution

1
use serde::Deserialize;
2
use std::io::Cursor;
3

4
#[derive(Deserialize)]
5
struct Order {
6
    total: f64,
7
}
8

9
fn sum_totals<R: std::io::Read>(reader: R) -> Result<f64, serde_json::Error> {
10
    let stream = serde_json::Deserializer::from_reader(reader).into_iter::<Order>();
11
    let mut sum = 0.0;
12
    for order in stream {
13
        sum += order?.total; // `order` is Result<Order, _>; `?` propagates errors
14
    }
15
    Ok(sum)
16
}
17

18
fn main() -> Result<(), serde_json::Error> {
19
    let ndjson = r#"{"total":19.99}{"total":4.50}{"total":100.00}"#;
20
    let sum = sum_totals(Cursor::new(ndjson))?;
21
    println!("sum = {sum:.2}");
22
    Ok(())
23
}

Real output from cargo run:

1
sum = 124.49

The StreamDeserializer yields Result<Order, _> items, so order? both unwraps the value and propagates any parse error. Only one Order exists at a time — memory stays constant no matter how many records the reader holds. The fields are f64 (owned), satisfying from_reader’s requirement that streamed types be owned.

Exercise 3: Extract one field without building a `Value` tree

Difficulty: Medium

Objective: Pull a single field out of a large JSON payload using a minimal typed struct instead of serde_json::Value, relying on the fact that unknown fields are skipped during parsing.

Instructions: Given a large JSON payload with many fields, you only need the top-level version number. Write payload_version(json: &str) -> Result<u32, serde_json::Error> that parses into a struct declaring only version (Serde ignores the rest at parse time — no full tree is built). Test it on the multi-field literal below and print the version.

1
use serde::Deserialize;
2

3
// TODO: declare a struct with ONLY the field you need.
4

5
fn payload_version(json: &str) -> Result<u32, serde_json::Error> {
6
    todo!()
7
}
8

9
fn main() -> Result<(), serde_json::Error> {
10
    let big = r#"{
11
        "version": 3,
12
        "data": {"a": [1,2,3,4,5], "b": "lots of text here"},
13
        "signature": "deadbeef",
14
        "nested": {"deep": {"deeper": {"x": true}}}
15
    }"#;
16
    println!("version = {}", payload_version(big)?);
17
    Ok(())
18
}

Solution

1
use serde::Deserialize;
2

3
// Only `version` is declared; `data`, `signature`, and `nested` are
4
// skipped by the parser — they are never allocated into a Value tree.
5
#[derive(Deserialize)]
6
struct VersionOnly {
7
    version: u32,
8
}
9

10
fn payload_version(json: &str) -> Result<u32, serde_json::Error> {
11
    let parsed: VersionOnly = serde_json::from_str(json)?;
12
    Ok(parsed.version)
13
}
14

15
fn main() -> Result<(), serde_json::Error> {
16
    let big = r#"{
17
        "version": 3,
18
        "data": {"a": [1,2,3,4,5], "b": "lots of text here"},
19
        "signature": "deadbeef",
20
        "nested": {"deep": {"deeper": {"x": true}}}
21
    }"#;
22
    println!("version = {}", payload_version(big)?);
23
    Ok(())
24
}

Real output from cargo run:

1
version = 3

Because Serde ignores fields the struct does not declare, the data, signature, and nested subtrees are parsed past but never materialized into owned values. Compared with let v: Value = from_str(big)?; v["version"].as_u64(), this allocates nothing for the unused fields and gives you a checked u32 directly instead of an Option<u64> you have to unwrap.

Serde Performance: Borrowing, Zero-Copy, Streaming, and Buffer Reuse

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Borrowed deserialization (&str)

When a borrow can’t happen: escapes and Cow

#[serde(borrow)]

Streaming with from_reader and StreamDeserializer

Avoiding serde_json::Value

Buffer reuse on the serialize side

Key Differences

Common Pitfalls

Trying to borrow an escaped string into &str

Returning a borrowed struct that outlives its buffer

Expecting from_reader to borrow

Forgetting #[serde(borrow)] on Cow

Reaching for Value when a typed struct would do

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Convert an owning struct to a borrowing one

Exercise 2: Stream-sum NDJSON without holding it all in memory

Exercise 3: Extract one field without building a Value tree

Borrowed deserialization (`&str`)

When a borrow can’t happen: escapes and `Cow`

`#[serde(borrow)]`

Streaming with `from_reader` and `StreamDeserializer`

Avoiding `serde_json::Value`

Trying to borrow an escaped string into `&str`

Expecting `from_reader` to borrow

Forgetting `#[serde(borrow)]` on `Cow`

Reaching for `Value` when a typed struct would do

Exercise 3: Extract one field without building a `Value` tree