Simdjsont.Codec

Codecs used to decode and encode typed OCaml values.

This module is the foundation for Decode, Encode, Extract.at, and Cbor. Define a codec once and reuse it across JSON strings, bigstrings, NDJSON streams, and CBOR bytes.

Typed codecs for JSON and CBOR.

A codec 'a t describes how to decode a parsed value into an OCaml value, how to encode that OCaml value as JSON, and how to turn it into the dynamic JSON tree used by CBOR encoding. The same codec can be used with JSON entry points such as decode_string and CBOR entry points such as Simdjsont.Cbor.decode_string.

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.