Simdjsont.Decode

Codecs and decoding functions.

This module re-exports the Codec interface.

Example: a record codec

type user = { id : int; name : string; email : string option }

let user : user Simdjsont.Codec.t =
  let open Simdjsont.Codec in
  Obj.field (fun id name email -> { id; name; email })
  |> Obj.mem "id" int ~enc:(fun u -> u.id)
  |> Obj.mem "name" string ~enc:(fun u -> u.name)
  |> Obj.opt_mem "email" string ~enc:(fun u -> u.email)
  |> Obj.finish

How object decoding works

• a decoder from a low-level raw element to 'a
• an encoder from 'a to JSON written into a buffer
• a conversion from 'a to the dynamic JSON tree Required fields fail with a path-aware error when they are absent or have the wrong type. Optional object members accept both a missing field and a present null value as None. Unknown object members are ignored.

type error = {
  path : string list;
  message : string;
}

Error value used by Decode_error.

• path is a list of strings accumulated during decoding.
• message is a human-readable error message.

exception Decode_error of error

Exception raised by decoders.

val error_to_string : error -> string

Convert an error to a string.

type 'a t

A codec for values of type 'a.

val decode_string : 'a t -> string -> ('a, string) result

decode_string codec json parses json and decodes the root value using codec. The Error case contains either the simdjson parse message or a codec error such as "user.id: expected int".

val decode_string_exn : 'a t -> string -> 'a

Like decode_string, but raises Failure with the error message. Prefer decode_string at trust boundaries.

val decode_bigstring : 
  'a t ->
  (char, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t ->
  len:int ->
  ('a, string) result

decode_bigstring codec buf ~len decodes the first len bytes of the bigstring buf using codec. Parsing is zero-copy when buf already has the padding required by the parser; otherwise the data is copied into a padded buffer.

val decode_bigstring_exn : 
  'a t ->
  (char, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t ->
  len:int ->
  'a

Like decode_bigstring, but raises on error.

val decode_element : 
  'a t ->
  Simdjsont__.Simdjsont_raw.element ->
  ('a, string) result

Decode an already parsed low-level element. The caller must keep the parser that owns element alive for the duration of the call.

val encode_to_obuf : 'a t -> 'a -> Simdjsont__.Simdjsont_obuf.t

Encode a value into a fresh output buffer using the given codec.

val encode_string : 'a t -> 'a -> string

Encode a value to a JSON string using the given codec.

val encode_to_bigstring : 
  'a t ->
  'a ->
  (char, Bigarray.int8_unsigned_elt, Bigarray.c_layout) Bigarray.Array1.t * int

Encode a value directly into a parse-ready bigstring, returning it with the number of valid bytes. No intermediate string is allocated, and the result can be fed straight back into decode_bigstring.

val to_json : 'a t -> 'a -> Simdjsont__.Simdjsont_json.t

Convert a value to JSON AST using the given codec.

val null : unit t

Codec for the JSON null value, represented as ().

val bool : bool t

Codec for JSON booleans.

Simdjsont.Codec.decode_string Simdjsont.Codec.bool "true" = Ok true

val int : int t

Codec for JSON integers mapped to OCaml int. Use int64 when the input may exceed the platform int range.

val int64 : int64 t

Codec for JSON integers mapped to OCaml int64.

val float : float t

Codec for JSON numbers mapped to OCaml float. Integer JSON numbers are accepted and converted to floats. Non-finite OCaml floats encode as null because JSON has no NaN or infinity literals.

val string : string t

Codec for JSON strings. Encoding escapes control characters, quotes, and backslashes.

val list : 'a t -> 'a list t

list item maps JSON arrays to OCaml lists.

Simdjsont.Codec.decode_string Simdjsont.Codec.(list int) "[1,2,3]"
= Ok [ 1; 2; 3 ]

val array : 'a t -> 'a array t

array item maps JSON arrays to OCaml arrays. Prefer list when you do not need random access or mutable array operations.

val optional : 'a t -> 'a option t

optional codec maps null to None and any other value to Some decoded_value. When used with Obj.opt_mem, a missing object member also becomes None.

val map : ('a -> 'b) -> ('b -> 'a) -> 'a t -> 'b t

map decode encode codec adapts codec through conversion functions.

This is useful for small domain types:

type user_id = User_id of int

let user_id =
  Simdjsont.Codec.map
    (fun n -> User_id n)
    (fun (User_id n) -> n)
    Simdjsont.Codec.int

module Obj : sig ... end

Builder for JSON objects.

val value : Simdjsont__.Simdjsont_json.t t

Codec for dynamic JSON values.

Use this when the document shape is not known at compile time, or when you want to transform a JSON/CBOR value tree manually before re-encoding it.