purescript-record-optional-fields

Type-safe manipulation of optional fields for PureScript record types.

What's this?

purescript-record-optional-fields is a library that offers a flexible, yet type-safe way of handling records with optional fields.

How to use?

Suppose you have following type:

type T =
  { foo :: Int
  , bar :: String
  , baz ::
    { quz :: Number
    , qux :: Array Boolean
    }
  }

Using the optional function provided by this library, you can convert a record with some missing fields for the target type T into a record that includes all the fields from T, but the types of the fields are modified with the Maybe type constructor.

-- Example 1
optional @T {}
  == Just { foo: Nothing, bar: Nothing, baz: Nothing }

-- Example 2
optional @T { foo: 42 }
  == Just
    { foo: Just 42
    , bar: Nothing
    , baz: Nothing
    }

If the target type T has nested record fields, all of its nested fields will be recursively transformed into their Maybe counterparts, as illustrated in the following example.

-- Example 3
optional @T { foo: 42, baz: { quz: 3.14 } }
  == Just
    { foo: Just 42
    , bar: Nothing
    , baz: Just
      { quz: Just 3.14
      , qux: Nothing
      }
    }

Sometimes, you may want to include a certain field only if a specific conditional check is met. In this case, you can provide a value with an explicit Maybe modification.

-- Example 4
optional @T
  { foo: if (some conditional check)
         then Just 42 else Nothing
  }
  == Just
    { foo: Just 42  -- or Nothing, if condition does not hold
    , bar: Nothing
    , baz: Nothing
    }

Custom compiler error

When you attempt to convert a record with fields not belonging to the target type, the compiler will indicate the issue with a user-friendly custom error.

optional @T { foo: "abc" }

will result in following error:

Error found:

Custom error:

  An error occurred while checking input option type:

  - At field `foo`:
    Unexpected value type: `String`

  💡 You must specify a value of type `Int`.

And this case

optional @T { baz: { qux: [true] , quux: [3.14, 2.718] } }

will result in:

Custom error:

  An error occurred while checking input option type:

  - At field `baz`:
    Unsupported field name: `quux`.

  💡 Supported fields include: `qux` `quz`