facet_format_json/
serializer.rs

1extern crate alloc;
2
3use alloc::{string::String, vec::Vec};
4
5use facet_core::Facet;
6use facet_format::{FormatSerializer, ScalarValue, SerializeError, serialize_root};
7use facet_reflect::Peek;
8
9/// Options for JSON serialization.
10#[derive(Debug, Clone)]
11pub struct SerializeOptions {
12    /// Whether to pretty-print with indentation (default: false)
13    pub pretty: bool,
14    /// Indentation string for pretty-printing (default: "  ")
15    pub indent: &'static str,
16}
17
18impl Default for SerializeOptions {
19    fn default() -> Self {
20        Self {
21            pretty: false,
22            indent: "  ",
23        }
24    }
25}
26
27impl SerializeOptions {
28    /// Create new default options (compact output).
29    pub fn new() -> Self {
30        Self::default()
31    }
32
33    /// Enable pretty-printing with default indentation.
34    pub fn pretty(mut self) -> Self {
35        self.pretty = true;
36        self
37    }
38
39    /// Set a custom indentation string (implies pretty-printing).
40    pub fn indent(mut self, indent: &'static str) -> Self {
41        self.indent = indent;
42        self.pretty = true;
43        self
44    }
45}
46
47#[derive(Debug)]
48pub struct JsonSerializeError {
49    msg: &'static str,
50}
51
52impl core::fmt::Display for JsonSerializeError {
53    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
54        f.write_str(self.msg)
55    }
56}
57
58impl std::error::Error for JsonSerializeError {}
59
60#[derive(Debug, Clone, Copy)]
61enum Ctx {
62    Struct { first: bool },
63    Seq { first: bool },
64}
65
66/// JSON serializer with configurable formatting options.
67pub struct JsonSerializer {
68    out: Vec<u8>,
69    stack: Vec<Ctx>,
70    options: SerializeOptions,
71}
72
73impl JsonSerializer {
74    /// Create a new JSON serializer with default (compact) options.
75    pub fn new() -> Self {
76        Self::with_options(SerializeOptions::default())
77    }
78
79    /// Create a new JSON serializer with the given options.
80    pub fn with_options(options: SerializeOptions) -> Self {
81        Self {
82            out: Vec::new(),
83            stack: Vec::new(),
84            options,
85        }
86    }
87
88    /// Consume the serializer and return the output bytes.
89    pub fn finish(self) -> Vec<u8> {
90        self.out
91    }
92
93    /// Current nesting depth (for indentation).
94    fn depth(&self) -> usize {
95        self.stack.len()
96    }
97
98    /// Write a newline and indentation if in pretty mode.
99    fn write_indent(&mut self) {
100        if self.options.pretty {
101            self.out.push(b'\n');
102            for _ in 0..self.depth() {
103                self.out.extend_from_slice(self.options.indent.as_bytes());
104            }
105        }
106    }
107
108    fn before_value(&mut self) -> Result<(), JsonSerializeError> {
109        match self.stack.last_mut() {
110            Some(Ctx::Seq { first }) => {
111                if !*first {
112                    self.out.push(b',');
113                }
114                *first = false;
115                self.write_indent();
116            }
117            Some(Ctx::Struct { .. }) => {
118                // struct values are separated by `field_key`
119            }
120            None => {}
121        }
122        Ok(())
123    }
124
125    /// Optimized JSON string writing with SIMD-like 16-byte fast path.
126    ///
127    /// For ASCII strings without special characters, processes 16 bytes at a time.
128    /// Falls back to character-by-character escaping when needed.
129    fn write_json_string(&mut self, s: &str) {
130        const STEP_SIZE: usize = 16; // u128 = 16 bytes
131        type Chunk = [u8; STEP_SIZE];
132
133        self.out.push(b'"');
134
135        let mut s = s;
136        while let Some(Ok(chunk)) = s.as_bytes().get(..STEP_SIZE).map(Chunk::try_from) {
137            let window = u128::from_ne_bytes(chunk);
138            // Check all 16 bytes at once:
139            // 1. All ASCII (high bit clear): window & 0x80...80 == 0
140            // 2. No quotes (0x22): !contains_byte(window, 0x22)
141            // 3. No backslashes (0x5c): !contains_byte(window, 0x5c)
142            // 4. No control chars (< 0x20): top 3 bits set for all bytes
143            let completely_ascii = window & 0x80808080808080808080808080808080 == 0;
144            let quote_free = !contains_byte(window, 0x22);
145            let backslash_free = !contains_byte(window, 0x5c);
146            let control_char_free = no_control_chars(window);
147
148            if completely_ascii && quote_free && backslash_free && control_char_free {
149                // Fast path: copy 16 bytes directly
150                self.out.extend_from_slice(&chunk);
151                s = &s[STEP_SIZE..];
152            } else {
153                // Slow path: escape character by character for this chunk
154                let mut chars = s.chars();
155                let mut count = STEP_SIZE;
156                for c in &mut chars {
157                    self.write_json_escaped_char(c);
158                    count = count.saturating_sub(c.len_utf8());
159                    if count == 0 {
160                        break;
161                    }
162                }
163                s = chars.as_str();
164            }
165        }
166
167        // Handle remaining bytes (< 16)
168        for c in s.chars() {
169            self.write_json_escaped_char(c);
170        }
171
172        self.out.push(b'"');
173    }
174
175    #[inline]
176    fn write_json_escaped_char(&mut self, c: char) {
177        match c {
178            '"' => self.out.extend_from_slice(b"\\\""),
179            '\\' => self.out.extend_from_slice(b"\\\\"),
180            '\n' => self.out.extend_from_slice(b"\\n"),
181            '\r' => self.out.extend_from_slice(b"\\r"),
182            '\t' => self.out.extend_from_slice(b"\\t"),
183            '\u{08}' => self.out.extend_from_slice(b"\\b"),
184            '\u{0C}' => self.out.extend_from_slice(b"\\f"),
185            c if c.is_ascii_control() => {
186                let code_point = c as u32;
187                let to_hex = |d: u32| {
188                    if d < 10 {
189                        b'0' + d as u8
190                    } else {
191                        b'a' + (d - 10) as u8
192                    }
193                };
194                let buf = [
195                    b'\\',
196                    b'u',
197                    to_hex((code_point >> 12) & 0xF),
198                    to_hex((code_point >> 8) & 0xF),
199                    to_hex((code_point >> 4) & 0xF),
200                    to_hex(code_point & 0xF),
201                ];
202                self.out.extend_from_slice(&buf);
203            }
204            c if c.is_ascii() => {
205                self.out.push(c as u8);
206            }
207            c => {
208                let mut buf = [0u8; 4];
209                let len = c.encode_utf8(&mut buf).len();
210                self.out.extend_from_slice(&buf[..len]);
211            }
212        }
213    }
214}
215
216/// Check if any byte in the u128 equals the target byte.
217/// Uses the SWAR (SIMD Within A Register) technique.
218#[inline]
219fn contains_byte(val: u128, byte: u8) -> bool {
220    let mask = 0x01010101010101010101010101010101u128 * (byte as u128);
221    let xor_result = val ^ mask;
222    let has_zero = (xor_result.wrapping_sub(0x01010101010101010101010101010101))
223        & !xor_result
224        & 0x80808080808080808080808080808080;
225    has_zero != 0
226}
227
228/// Check that all bytes have at least one of the top 3 bits set (i.e., >= 0x20).
229/// This means no control characters (0x00-0x1F).
230#[inline]
231fn no_control_chars(value: u128) -> bool {
232    let masked = value & 0xe0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0;
233    let has_zero = (masked.wrapping_sub(0x01010101010101010101010101010101))
234        & !masked
235        & 0x80808080808080808080808080808080;
236    has_zero == 0
237}
238
239impl Default for JsonSerializer {
240    fn default() -> Self {
241        Self::new()
242    }
243}
244
245impl FormatSerializer for JsonSerializer {
246    type Error = JsonSerializeError;
247
248    fn begin_struct(&mut self) -> Result<(), Self::Error> {
249        self.before_value()?;
250        self.out.push(b'{');
251        self.stack.push(Ctx::Struct { first: true });
252        Ok(())
253    }
254
255    fn field_key(&mut self, key: &str) -> Result<(), Self::Error> {
256        match self.stack.last_mut() {
257            Some(Ctx::Struct { first }) => {
258                if !*first {
259                    self.out.push(b',');
260                }
261                *first = false;
262                self.write_indent();
263                self.write_json_string(key);
264                self.out.push(b':');
265                if self.options.pretty {
266                    self.out.push(b' ');
267                }
268                Ok(())
269            }
270            _ => Err(JsonSerializeError {
271                msg: "field_key called outside of a struct",
272            }),
273        }
274    }
275
276    fn end_struct(&mut self) -> Result<(), Self::Error> {
277        match self.stack.pop() {
278            Some(Ctx::Struct { first }) => {
279                // Only add newline/indent before closing brace if struct was non-empty
280                if !first {
281                    self.write_indent();
282                }
283                self.out.push(b'}');
284                Ok(())
285            }
286            _ => Err(JsonSerializeError {
287                msg: "end_struct called without matching begin_struct",
288            }),
289        }
290    }
291
292    fn begin_seq(&mut self) -> Result<(), Self::Error> {
293        self.before_value()?;
294        self.out.push(b'[');
295        self.stack.push(Ctx::Seq { first: true });
296        Ok(())
297    }
298
299    fn end_seq(&mut self) -> Result<(), Self::Error> {
300        match self.stack.pop() {
301            Some(Ctx::Seq { first }) => {
302                // Only add newline/indent before closing bracket if seq was non-empty
303                if !first {
304                    self.write_indent();
305                }
306                self.out.push(b']');
307                Ok(())
308            }
309            _ => Err(JsonSerializeError {
310                msg: "end_seq called without matching begin_seq",
311            }),
312        }
313    }
314
315    fn scalar(&mut self, scalar: ScalarValue<'_>) -> Result<(), Self::Error> {
316        self.before_value()?;
317        match scalar {
318            ScalarValue::Null => self.out.extend_from_slice(b"null"),
319            ScalarValue::Bool(v) => {
320                if v {
321                    self.out.extend_from_slice(b"true")
322                } else {
323                    self.out.extend_from_slice(b"false")
324                }
325            }
326            ScalarValue::I64(v) => {
327                #[cfg(feature = "fast")]
328                self.out
329                    .extend_from_slice(itoa::Buffer::new().format(v).as_bytes());
330                #[cfg(not(feature = "fast"))]
331                self.out.extend_from_slice(v.to_string().as_bytes());
332            }
333            ScalarValue::U64(v) => {
334                #[cfg(feature = "fast")]
335                self.out
336                    .extend_from_slice(itoa::Buffer::new().format(v).as_bytes());
337                #[cfg(not(feature = "fast"))]
338                self.out.extend_from_slice(v.to_string().as_bytes());
339            }
340            ScalarValue::F64(v) => {
341                #[cfg(feature = "fast")]
342                self.out
343                    .extend_from_slice(ryu::Buffer::new().format(v).as_bytes());
344                #[cfg(not(feature = "fast"))]
345                self.out.extend_from_slice(v.to_string().as_bytes());
346            }
347            ScalarValue::Str(s) => self.write_json_string(&s),
348            ScalarValue::Bytes(_) => {
349                return Err(JsonSerializeError {
350                    msg: "bytes serialization unsupported for json",
351                });
352            }
353        }
354        Ok(())
355    }
356
357    fn raw_serialize_shape(&self) -> Option<&'static facet_core::Shape> {
358        Some(crate::RawJson::SHAPE)
359    }
360
361    fn raw_scalar(&mut self, content: &str) -> Result<(), Self::Error> {
362        // For RawJson, output the content directly without escaping
363        self.before_value()?;
364        self.out.extend_from_slice(content.as_bytes());
365        Ok(())
366    }
367}
368
369/// Serialize a value to JSON bytes.
370///
371/// # Example
372///
373/// ```
374/// use facet::Facet;
375/// use facet_format_json::to_vec;
376///
377/// #[derive(Facet)]
378/// struct Point { x: i32, y: i32 }
379///
380/// let point = Point { x: 10, y: 20 };
381/// let bytes = to_vec(&point).unwrap();
382/// assert_eq!(bytes, br#"{"x":10,"y":20}"#);
383/// ```
384pub fn to_vec<'facet, T>(value: &'_ T) -> Result<Vec<u8>, SerializeError<JsonSerializeError>>
385where
386    T: Facet<'facet> + ?Sized,
387{
388    to_vec_with_options(value, &SerializeOptions::default())
389}
390
391/// Serialize a value to pretty-printed JSON bytes.
392///
393/// # Example
394///
395/// ```
396/// use facet::Facet;
397/// use facet_format_json::to_vec_pretty;
398///
399/// #[derive(Facet)]
400/// struct Point { x: i32, y: i32 }
401///
402/// let point = Point { x: 10, y: 20 };
403/// let bytes = to_vec_pretty(&point).unwrap();
404/// assert!(bytes.contains(&b'\n'));
405/// ```
406pub fn to_vec_pretty<'facet, T>(value: &'_ T) -> Result<Vec<u8>, SerializeError<JsonSerializeError>>
407where
408    T: Facet<'facet> + ?Sized,
409{
410    to_vec_with_options(value, &SerializeOptions::default().pretty())
411}
412
413/// Serialize a value to JSON bytes with custom options.
414///
415/// # Example
416///
417/// ```
418/// use facet::Facet;
419/// use facet_format_json::{to_vec_with_options, SerializeOptions};
420///
421/// #[derive(Facet)]
422/// struct Point { x: i32, y: i32 }
423///
424/// let point = Point { x: 10, y: 20 };
425///
426/// // Compact output
427/// let bytes = to_vec_with_options(&point, &SerializeOptions::default()).unwrap();
428/// assert_eq!(bytes, br#"{"x":10,"y":20}"#);
429///
430/// // Pretty output with tabs
431/// let bytes = to_vec_with_options(&point, &SerializeOptions::default().indent("\t")).unwrap();
432/// assert!(bytes.contains(&b'\n'));
433/// ```
434pub fn to_vec_with_options<'facet, T>(
435    value: &'_ T,
436    options: &SerializeOptions,
437) -> Result<Vec<u8>, SerializeError<JsonSerializeError>>
438where
439    T: Facet<'facet> + ?Sized,
440{
441    let mut serializer = JsonSerializer::with_options(options.clone());
442    serialize_root(&mut serializer, Peek::new(value))?;
443    Ok(serializer.finish())
444}
445
446/// Serialize a value to a JSON string.
447///
448/// # Example
449///
450/// ```
451/// use facet::Facet;
452/// use facet_format_json::to_string;
453///
454/// #[derive(Facet)]
455/// struct Person { name: String, age: u32 }
456///
457/// let person = Person { name: "Alice".into(), age: 30 };
458/// let json = to_string(&person).unwrap();
459/// assert_eq!(json, r#"{"name":"Alice","age":30}"#);
460/// ```
461pub fn to_string<'facet, T>(value: &'_ T) -> Result<String, SerializeError<JsonSerializeError>>
462where
463    T: Facet<'facet> + ?Sized,
464{
465    let bytes = to_vec(value)?;
466    // JSON output is always valid UTF-8, so this unwrap is safe
467    Ok(String::from_utf8(bytes).expect("JSON output should always be valid UTF-8"))
468}
469
470/// Serialize a value to a pretty-printed JSON string.
471///
472/// # Example
473///
474/// ```
475/// use facet::Facet;
476/// use facet_format_json::to_string_pretty;
477///
478/// #[derive(Facet)]
479/// struct Person { name: String, age: u32 }
480///
481/// let person = Person { name: "Alice".into(), age: 30 };
482/// let json = to_string_pretty(&person).unwrap();
483/// assert!(json.contains('\n'));
484/// ```
485pub fn to_string_pretty<'facet, T>(
486    value: &'_ T,
487) -> Result<String, SerializeError<JsonSerializeError>>
488where
489    T: Facet<'facet> + ?Sized,
490{
491    let bytes = to_vec_pretty(value)?;
492    Ok(String::from_utf8(bytes).expect("JSON output should always be valid UTF-8"))
493}
494
495/// Serialize a value to a JSON string with custom options.
496///
497/// # Example
498///
499/// ```
500/// use facet::Facet;
501/// use facet_format_json::{to_string_with_options, SerializeOptions};
502///
503/// #[derive(Facet)]
504/// struct Person { name: String, age: u32 }
505///
506/// let person = Person { name: "Alice".into(), age: 30 };
507///
508/// // Compact output
509/// let json = to_string_with_options(&person, &SerializeOptions::default()).unwrap();
510/// assert_eq!(json, r#"{"name":"Alice","age":30}"#);
511///
512/// // Pretty output with tabs
513/// let json = to_string_with_options(&person, &SerializeOptions::default().indent("\t")).unwrap();
514/// assert!(json.contains('\n'));
515/// ```
516pub fn to_string_with_options<'facet, T>(
517    value: &'_ T,
518    options: &SerializeOptions,
519) -> Result<String, SerializeError<JsonSerializeError>>
520where
521    T: Facet<'facet> + ?Sized,
522{
523    let bytes = to_vec_with_options(value, options)?;
524    Ok(String::from_utf8(bytes).expect("JSON output should always be valid UTF-8"))
525}
526
527// ── Peek-based serialization ──
528
529/// Serialize a `Peek` instance to a JSON string.
530///
531/// This allows serializing values without requiring ownership, useful when
532/// you already have a `Peek` from reflection operations.
533///
534/// # Example
535///
536/// ```
537/// use facet::Facet;
538/// use facet_reflect::Peek;
539/// use facet_format_json::peek_to_string;
540///
541/// #[derive(Facet)]
542/// struct Point { x: i32, y: i32 }
543///
544/// let point = Point { x: 10, y: 20 };
545/// let json = peek_to_string(Peek::new(&point)).unwrap();
546/// assert_eq!(json, r#"{"x":10,"y":20}"#);
547/// ```
548pub fn peek_to_string<'input, 'facet>(
549    peek: Peek<'input, 'facet>,
550) -> Result<String, SerializeError<JsonSerializeError>> {
551    peek_to_string_with_options(peek, &SerializeOptions::default())
552}
553
554/// Serialize a `Peek` instance to a pretty-printed JSON string.
555///
556/// # Example
557///
558/// ```
559/// use facet::Facet;
560/// use facet_reflect::Peek;
561/// use facet_format_json::peek_to_string_pretty;
562///
563/// #[derive(Facet)]
564/// struct Point { x: i32, y: i32 }
565///
566/// let point = Point { x: 10, y: 20 };
567/// let json = peek_to_string_pretty(Peek::new(&point)).unwrap();
568/// assert!(json.contains('\n'));
569/// ```
570pub fn peek_to_string_pretty<'input, 'facet>(
571    peek: Peek<'input, 'facet>,
572) -> Result<String, SerializeError<JsonSerializeError>> {
573    peek_to_string_with_options(peek, &SerializeOptions::default().pretty())
574}
575
576/// Serialize a `Peek` instance to a JSON string with custom options.
577///
578/// # Example
579///
580/// ```
581/// use facet::Facet;
582/// use facet_reflect::Peek;
583/// use facet_format_json::{peek_to_string_with_options, SerializeOptions};
584///
585/// #[derive(Facet)]
586/// struct Point { x: i32, y: i32 }
587///
588/// let point = Point { x: 10, y: 20 };
589/// let json = peek_to_string_with_options(
590///     Peek::new(&point),
591///     &SerializeOptions::default().indent("\t"),
592/// ).unwrap();
593/// assert!(json.contains('\n'));
594/// ```
595pub fn peek_to_string_with_options<'input, 'facet>(
596    peek: Peek<'input, 'facet>,
597    options: &SerializeOptions,
598) -> Result<String, SerializeError<JsonSerializeError>> {
599    let mut serializer = JsonSerializer::with_options(options.clone());
600    serialize_root(&mut serializer, peek)?;
601    let bytes = serializer.finish();
602    Ok(String::from_utf8(bytes).expect("JSON output should always be valid UTF-8"))
603}
604
605// ── Writer-based serialization (std::io::Write) ──
606
607/// Serialize a value to JSON and write it to a `std::io::Write` writer.
608///
609/// # Example
610///
611/// ```
612/// use facet::Facet;
613/// use facet_format_json::to_writer_std;
614///
615/// #[derive(Facet)]
616/// struct Person {
617///     name: String,
618///     age: u32,
619/// }
620///
621/// let person = Person { name: "Alice".into(), age: 30 };
622/// let mut buffer = Vec::new();
623/// to_writer_std(&mut buffer, &person).unwrap();
624/// assert_eq!(buffer, br#"{"name":"Alice","age":30}"#);
625/// ```
626pub fn to_writer_std<'facet, W, T>(writer: W, value: &T) -> std::io::Result<()>
627where
628    W: std::io::Write,
629    T: Facet<'facet> + ?Sized,
630{
631    peek_to_writer_std(writer, Peek::new(value))
632}
633
634/// Serialize a value to pretty-printed JSON and write it to a `std::io::Write` writer.
635///
636/// # Example
637///
638/// ```
639/// use facet::Facet;
640/// use facet_format_json::to_writer_std_pretty;
641///
642/// #[derive(Facet)]
643/// struct Person {
644///     name: String,
645///     age: u32,
646/// }
647///
648/// let person = Person { name: "Alice".into(), age: 30 };
649/// let mut buffer = Vec::new();
650/// to_writer_std_pretty(&mut buffer, &person).unwrap();
651/// assert!(String::from_utf8_lossy(&buffer).contains('\n'));
652/// ```
653pub fn to_writer_std_pretty<'facet, W, T>(writer: W, value: &T) -> std::io::Result<()>
654where
655    W: std::io::Write,
656    T: Facet<'facet> + ?Sized,
657{
658    peek_to_writer_std_pretty(writer, Peek::new(value))
659}
660
661/// Serialize a value to JSON with custom options and write it to a `std::io::Write` writer.
662///
663/// # Example
664///
665/// ```
666/// use facet::Facet;
667/// use facet_format_json::{to_writer_std_with_options, SerializeOptions};
668///
669/// #[derive(Facet)]
670/// struct Person {
671///     name: String,
672///     age: u32,
673/// }
674///
675/// let person = Person { name: "Alice".into(), age: 30 };
676///
677/// // Compact output
678/// let mut buffer = Vec::new();
679/// to_writer_std_with_options(&mut buffer, &person, &SerializeOptions::default()).unwrap();
680/// assert_eq!(buffer, br#"{"name":"Alice","age":30}"#);
681///
682/// // Pretty output with tabs
683/// let mut buffer = Vec::new();
684/// to_writer_std_with_options(&mut buffer, &person, &SerializeOptions::default().indent("\t")).unwrap();
685/// assert!(String::from_utf8_lossy(&buffer).contains('\n'));
686/// ```
687pub fn to_writer_std_with_options<'facet, W, T>(
688    writer: W,
689    value: &T,
690    options: &SerializeOptions,
691) -> std::io::Result<()>
692where
693    W: std::io::Write,
694    T: Facet<'facet> + ?Sized,
695{
696    peek_to_writer_std_with_options(writer, Peek::new(value), options)
697}
698
699/// Serialize a `Peek` instance to JSON and write it to a `std::io::Write` writer.
700pub fn peek_to_writer_std<'input, 'facet, W>(
701    writer: W,
702    peek: Peek<'input, 'facet>,
703) -> std::io::Result<()>
704where
705    W: std::io::Write,
706{
707    peek_to_writer_std_with_options(writer, peek, &SerializeOptions::default())
708}
709
710/// Serialize a `Peek` instance to pretty-printed JSON and write it to a `std::io::Write` writer.
711pub fn peek_to_writer_std_pretty<'input, 'facet, W>(
712    writer: W,
713    peek: Peek<'input, 'facet>,
714) -> std::io::Result<()>
715where
716    W: std::io::Write,
717{
718    peek_to_writer_std_with_options(writer, peek, &SerializeOptions::default().pretty())
719}
720
721/// Serialize a `Peek` instance to JSON with custom options and write it to a `std::io::Write` writer.
722pub fn peek_to_writer_std_with_options<'input, 'facet, W>(
723    mut writer: W,
724    peek: Peek<'input, 'facet>,
725    options: &SerializeOptions,
726) -> std::io::Result<()>
727where
728    W: std::io::Write,
729{
730    // Serialize to bytes first, then write
731    // This is simpler and avoids the complexity of incremental writes
732    let mut serializer = JsonSerializer::with_options(options.clone());
733    serialize_root(&mut serializer, peek)
734        .map_err(|e| std::io::Error::other(alloc::format!("{:?}", e)))?;
735    writer.write_all(&serializer.finish())
736}
facet_format_json/serializer.rs

facet_format_json/
serializer.rs
