v1 design

[chris-pardy]

There are a number of design mistakes that exist in Type-Shift that should be addressed for V1:

1. Use of exceptions for errors - This was done because other libraries that don't do this are much harder to interact with. However the design of V1 should have the flow of data between converters be done using success or failure tagged objects.
2. Lack of symmetry between input and output. The primary advantage to this is the for most converters you simply transform and return the value. However by moving all the data into a single properties object that can be used both for input and output it will enable things like path transforms much cleaner. Additionally new input fields can be added with little to no issue.
3. Treating missing and undefined as equivalent. While this is generally true in javascript the fact that the in operator and the Object.keys / values / entries methods will treat a present but undefined key differently then a non-present key means that we should support handling that in our converters.
4. Core types separated from common higher level / coercive / opinionated types - Things like string / number / boolean should be very strict and act as building blocks for other types. Higher level types such as a coercive number type that allows strings that are valid numbers should be build from these low level types. This should also allow the inclusion of opinionated types that we would expect more usage of.
5. Fixes to optional / required - currently optionality happens at the beginning of a converter and "skips" a converter. This breaks when a converter has a default value which would substitute in a different input value. However to properly fix this in a generic way we need to know that a converter would have produced an empty value if that was allowed. Practically this needs to be done by embedding the idea of optionally deeply within the converters.

[pignatenko]

In regards to #4, I think creating a functional core (data last plz), while still allowing the declarative OO style would greatly improve usage and consistency.

e.g. t.number.or(t.boolean) can be written and internally is represented as t.or(t.number, t.boolean)

• 1 implementation but semantic aliases t.optional(t.boolean) is t.or(t.boolean) (obviously right now these exist separately because of speed and implementation issues you mentioned above)

• Implicity array processing or variadics. e.g. t.number.or(t.boolean) t.number.or([t.boolean, t.string]) t.number.or(t.boolean, t.string) I'm okay supporting just 1 type.

• Implicit literal converters everywhere e.g. t.or('abc', '123')

The above offers amazing lift you can do something like

import * as t from 'type-shift';
import * as SubWidgetConverters from './sub-widgets'

export widgetConverter() {
  return {
    ...
    type: t.or('cool', 'bad', 'good'),
    sub-widgets: t.array(t.or(...Object.values(SubWidgetConverters))),
    ...
  }
}

• In a similar vein function wrapping to allow literals most places e.g. t.number.default(3);

• A very nice to have but may not be aligned with our own goals/usage is serialization into a standardized format/extensions the most obvious would be Typescript typedef generation e.g. yarn generate-types validators/*, but OpenAPI/Swagger/JSON Schema, etc. would also be nice. The converter would have to verify that only literals are used at extension points obviously. This would make better errors as well!

• Lazy metadata generation for production.

• Adding a distinct separation between shaping and conversion.

e.g.

You could do

t.shape({
  ...
  myField: t.forPath('other.bigInt', t.number),
  ...
  });

But this is a limited construct of limited value despite actually defining 2 shapes and a mapping (and a shape and the mapping is lost in the definition)! If we move more functionally we can do;

const myPayloadValidator = t.shape({
  ...
  myField: t.number,
  ...
});

const otherPayloadValidator = t.shape({
  other: t.shape({
    bigInt: t.string
  })
});

const reducedFieldConverter = t.createConverter((value: OtherPayloadOther) =>  {
  // .... do complex math here ....
}, 'ReducedFieldConverter');

const payloadTransform : TransformDefinition<MyPayload, OtherPayload> = t.transform(
  ...
  t.transform(t.path('myField'), t.path('other', 'bigInt')),
  t.transform(t.path('enumField'), t.pipe(t.path('other', 'type'), t.or('abc', '123', 'etc'))),
  t.transform(t.path('reducedField'), t.pipe(t.path('other'), reducedFieldConverter)),
  ...
);

This allows us to import shapes and transformations from anywhere and reuse them for multiple purposes. Transforms /may/ become bidirectional cutting down on code maintenance.

[pignatenko]

Also baked in testing tools to verify shapes/transforms.

Generate fake data from shapes.

Shared behaviors for transform / conversion expections.