Purescript module for converting options records defined in Purescript into objects used for options in foreign Javascript libraries.
Many Javascript libraries use anonymous objects to specify "options" for configuring various
operations. Often, the option fields can take one of a couple types (such as either
String
or Number
) or can be absent from the object entirely, in which case
a reasonable default is assumed.
In Purescript, this kind of behavior can be modeled with the Either
type in
the first case and the Maybe
type in the second. However, because the
Javascript library does not understand these types, a conversion must be made
before the options can be used in the foreign library. This module provides functionality for
handling this conversion in a type safe way.
The module defines a type Options a
to represent a foreign anonymous options
object. Also defined is a function toOptions
that converts a purescript record
of type {|a}
to Options {|a}
. In this way, foreign functions that consume the
options can be declared using Options MyOptionsRecordType
in the function signature,
so passing any incomplete or incorrect set of options to that function is a
compile time error.
Additionally, since records are used to respresent the set of options in Purescript,
options can be easily updated using the record { myfield = 7 }
syntax.
Fields can be protected from conversion by wrapping them in the Opaque
type.
This would be used, for example, to protect a constructed object instance.
The conversion is one-way; there is no provided functionality to marshal the
Options
type back to a Purescript record.
Example usage is provided in the examples
directory.
This function converts an arbitrary record in the following ways, with example cases listed in italics:
- Fields wrapped in the
Opaque
type are unchanged. Use to protect a foreign JS object from coversion. Left
andRight
are converted to the conversion of their inner values. Use to choose from either of two types for an options field.Just
is converted to the conversion of its inner value. Fields withNothing
are not included in the resulting options object. Use when an options field can be present or absent from the options object.- Fields with functions returning pure values are converted to an uncurried form.
Use to pass purescript functions as callbacks without converting to
FnX
types. - Fields with functions returning effectful values are converted to an uncurried form and run immediately when called. Use to pass purescript effectful functions as callbacks that are run when invoked.
- Fields with any other object values are converted to object literals with each field converted according to these rules. Use to represent options with nested structure.
- Anything else is left unchanged. If a conversion is needed and is not covered by the above rules, it must be performed manually before invoking
toOptions
. Use for types consistent between PS and JS, likeString
,Number
, etc.