Data.Codec.JSON.Common

nonEmptyString :: Codec NonEmptyString

A codec for NonEmptyString values.

Encodes as the standard type in JSON, but will fail to decode if the string is empty.

nonEmptyArray :: forall a. Codec a -> Codec (NonEmptyArray a)

A codec for NonEmptyArray values.

Encodes as the standard type in JSON, but will fail to decode if the array is empty.

maybe :: forall a. Codec a -> Codec (Maybe a)

A codec for Maybe values.

tuple :: forall a b. Codec a -> Codec b -> Codec (Tuple a b)

A codec for Tuple values.

Encodes as a two-element array in JSON.

either :: forall a b. Codec a -> Codec b -> Codec (Either a b)

A codec for Either values.

list :: forall a. Codec a -> Codec (List a)

A codec for List values.

Encodes as an array in JSON.

nonEmptyList :: forall a. Codec a -> Codec (NonEmptyList a)

A codec for NonEmptyList values.

Encodes as an array in JSON.

map :: forall a b. Ord a => Codec a -> Codec b -> Codec (Map a b)

A codec for Map values.

Encodes as an array of two-element key/value arrays in JSON.

strMap :: forall a. Codec a -> Codec (Map String a)

A codec for Map values which have string keys.

Encodes as an object in JSON.

set :: forall a. Ord a => Codec a -> Codec (Set a)

A codec for Set values.

Encodes as an array in JSON.

nonEmptySet :: forall a. Ord a => Codec a -> Codec (NonEmptySet a)

A codec for NonEmptySet values.

Encodes as an array in JSON.

foreignObject :: forall a. Codec a -> Codec (Object a)

A codec for Object values.

Encodes as an array of two-element key/value arrays in JSON.

type PropCodec a = Codec (Except DecodeError) JObject (List (Tuple String JSON)) a a

Codec type for JObject prop/value pairs.

type IndexedCodec a = Codec (Except DecodeError) JArray (List JSON) a a

Codec type for specifically indexed JArray elements.

newtype DecodeError

Type for failures while decoding, a path to the point in the JSON that failure occurred, a message describing the problem, and a list of further causes for the failure.

Constructors

• DecodeError DecodeErrorDetails

Instances

• Eq DecodeError
• Ord DecodeError
• Generic DecodeError _
• Newtype DecodeError _
• Show DecodeError
• Semigroup DecodeError

type Codec a = Codec' (Except DecodeError) JSON a

Codec type for Json values.

void :: Codec Void

A codec for Void values.

string :: Codec String

A codec for String values in Json.

recordPropOptional :: forall p a r r'. IsSymbol p => Cons p (Maybe a) r r' => Proxy p -> Codec a -> PropCodec (Record r) -> PropCodec (Record r')

Used with record to define an optional field.

This will only decode the property as Nothing if the field does not exist in the object - having a values such as null assigned will need handling separately.

The property will be omitted when encoding and the value is Nothing.

recordProp :: forall p a r r'. IsSymbol p => Cons p a r r' => Proxy p -> Codec a -> PropCodec (Record r) -> PropCodec (Record r')

Used with record to define codecs for record types that encode into JSON objects of the same shape. See the comment on record for an example.

record :: PropCodec (Record ())

The starting value for a object-record codec. Used with recordProp it provides a convenient method for defining codecs for record types that encode into JSON objects of the same shape.

For example, to encode a record as the JSON object { "name": "Karl", "age": 25 } we would define a codec like this:

import Data.Codec.JSON as CJ
import Type.Proxy (Proxy(..))

type Person = { name ∷ String, age ∷ Int }

codecPerson ∷ CJ.Codec Person
codecPerson =
  CJ.object $ CJ.record
    # CJ.recordProp (Proxy :: _ "name") CJ.string
    # CJ.recordProp (Proxy :: _ "age") CJ.int

See also Data.Codec.JSON.Record.object for a more commonly useful version of this function.

prop :: forall a. String -> Codec a -> PropCodec a

A codec for a property of an object.

prismaticCodec :: forall a b. String -> (a -> Maybe b) -> (b -> a) -> Codec a -> Codec b

Adapts an existing codec with a pair of functions to allow a value to be further refined. If the inner decoder fails an UnexpectedValue error will be raised for JSON input.

This function is named as such as the pair of functions it accepts correspond with the preview and review functions of a Prism-style lens.

An example of this would be a codec for Data.String.NonEmpty.NonEmptyString:

nonEmptyString ∷ CJ.Codec NES.NonEmptyString
nonEmptyString = CJ.prismaticCodec "NonEmptyString" NES.fromString NES.toString CJ.string

Another example might be to handle a mapping from a small sum type to strings:

data Direction = North | South | West | East

directionCodec :: Codec Direction
directionCodec = CJ.prismaticCodec "Direction" dec enc string
  where
    dec = case _ of
      "N" -> Just North
      "S" -> Just South
      "W" -> Just West
      "E" -> Just East
      _ -> Nothing

    enc = case _ of
      North -> "N"
      South -> "S"
      West -> "W"
      East -> "E"

Although for this latter case there are some other options too, in the form of Data.Codec.JSON.Generic.nullarySum and Data.Codec.JSON.Sum.enumSum.

object :: forall a. PropCodec a -> Codec a

A codec for objects that are encoded with specific properties.

See also Data.Codec.JSON.Record.object for a more commonly useful version of this function.

number :: Codec Number

A codec for Number values in Json.

nullable :: forall a. Codec a -> Codec (Maybe a)

A codec for JSON values that can be null or some other value.

This should not be used if an accurate representation of nested Maybe values is required, as values like Just Nothing cannot be encoded. For nested Maybes consider using Data.Codec.JSON.Common.maybe instead.

null :: Codec Unit

A codec for null values in Json.

named :: forall a. String -> Codec a -> Codec a

A codec for introducing names into error messages - useful when definiting a codec for a type synonym for a record, for instance.

json :: Codec JSON

The "identity codec" for Json values.

jobject :: Codec JObject

A codec for JObject values in Json.

jarray :: Codec JArray

A codec for JArray values in Json. This does not decode the values of the array, for that use array for a general array decoder, or indexedArray with index to decode fixed length array encodings.

int :: Codec Int

A codec for Int values in Json.

indexedArray :: forall a. IndexedCodec a -> Codec a

A codec for types that are encoded as an array with a specific layout.

For example, if we'd like to encode a Person as a 2-element array, like ["Rashida", 37], we could write the following codec:

import Data.Codec.JSON ((~))
import Data.Codec.JSON as CJ

type Person = { name ∷ String, age ∷ Int }

codecPerson ∷ CJ.Codec Person
codecPerson = CJ.indexedArray $
  { name: _, age: _ }
    <$> _.name ~ CJ.index 0 CJ.string
    <*> _.age ~ CJ.index 1 CJ.int

index :: forall a. Int -> Codec a -> IndexedCodec a

A codec for an item in an indexedArray.

identity :: forall m a. Applicative m => Codec m a a a a

hoist :: forall m m' a b c d. (m ~> m') -> Codec m a b c d -> Codec m' a b c d

fix :: forall m a b. (Codec' m a b -> Codec' m a b) -> Codec' m a b

encode :: forall a b c d. Codec (Except DecodeError) a b c d -> c -> b

Encodes a value as JSON using the specified code.

decode :: forall a b c d. Codec (Except DecodeError) a b c d -> a -> Either DecodeError d

Tries to decode JSON to a value using the specified code.

coercible :: forall a b. Coercible a b => String -> Codec a -> Codec b

A codec for types that can be safely coerced.

Accepts the name of the target type as an argument to improve error messaging when the inner codec fails.

codePoint :: Codec CodePoint

A codec for Codepoint values in Json.

char :: Codec Char

A codec for Char values in Json.

boolean :: Codec Boolean

A codec for Boolean values in Json.

array :: forall a. Codec a -> Codec (Array a)

A codec for arbitrary length Arrays where every item in the array shares the same type.

import Data.Codec.JSON as CJ

codecIntArray ∷ CJ.Codec (Array Int)
codecIntArray = CJ.array CJ.int

Operator alias for Data.Profunctor.lcmap (left-associative / precedence 5)

Codec is defined as a Profunctor so that lcmap can be used to target specific fields when defining a codec for a product type. This operator is a convenience for that:

tupleCodec =
  Tuple
    <$> fst ~ fstCodec
    <*> snd ~ sndCodec

Operator alias for Data.Codec.composeFlipped (right-associative / precedence 8)

Operator alias for Data.Codec.compose (right-associative / precedence 8)

taggedSum :: forall tag a. String -> (tag -> String) -> (String -> Maybe tag) -> (tag -> Either a (JSON -> Either DecodeError a)) -> (a -> Tuple tag (Maybe JSON)) -> Codec a

A helper for defining JSON codecs for sum types. To ensure exhaustivity there needs to be a mapping to and from a tag type for the type to be encoded.

• The first argument is the name of the type being decoded, for error message purposes.
• The second argument maps a tag value to a string to use in the encoding.
• The third argument maps a string back to a tag value during decoding.
• The fourth argument returns either a constant value or a decoder function based on a tag value.
• The fifth argument returns a tag value and optional encoded value to store for a constructor of the sum.