Support arbitrary conversions with a Type#convert method

[skeggse]

This is a:

• Bug Report
• Feature Request
• Question
• Other

Which concerns:

• flow-runtime
• babel-plugin-flow-runtime
• flow-runtime-validators
• flow-runtime-mobx
• flow-config-parser
• The documentation website

---

No affordance for convert behavior:

type Request = {
  // Feature: convert strings to numbers.
  quantity: number,
  // Feature: convert datetime strings (v.dateTime) or numeric timestamps to Dates.
  sessionTime: Date,
};

const RequestType = (reify: Type<Request>);

// One possibility for a conversion decoration API. flow-runtime ingests the explicit
// type on the input parameter to determine how to widen the type.
RequestType.getProperty('quantity').addConversion((raw: string) => {
  const value = parseInt(raw, 10);
  if (isNaN(value)) {
    throw new TypeError('expected a base-10 integer');
  }
  return value;
});

// The convert method is a modified assert that expands the supported types to include
// types that can be casted.
const value = RequestType.convert({
  // value.quantity could become 12, or this behavior could be customized like in
  // the constraint model by mutating a PermissiveNumber type.
  quantity: '12.0',
  // value.sessionTime becomes Date(2019-11-19T01:53:00.000Z)
  sessionTime: '2019-11-19T01:53:00Z',
});

A v1 here might be to just decorate all Types with convert methods and conversion arrays that we can extend with addConversion. This would mostly be trying to solve the same use-cases as joi's convert option.

A v2 might be to support a conversion where the types in and the types out are entirely disjoint - e.g. convert(input: string | number): Date but via a declarative syntax

A v3 might be to include default conversion functionality like string -> number, but that'd require a bit more exploration.

I'm open to working on this; just curious if y'all have thoughts on the API/concerns about the implementation.

[skeggse]

I'm tempted to say that some of this functionality shouldn't be in the flow-runtime core; I think this pattern might be possible with type introspection/or a visitor pattern #5.