Architecture for 2.0

[jacob-alford]

This is a discussion for all the changes related to the library's architecture for version 2.0.

fp-ts/schema

The original intention for 2.0 was to replace the Schemable system with the Provider system in fp-ts/schema. The Schemable system is isomorphic to the Provider system in that they contain the same amount of functionality / information. The difference between the two is that the Provider system relies on symbolic keys existing in a Map, which means that all instances must be generated unsafely. Unlike this, the Schemable system is type safe and all errors are captured in the type system.

All Schemable instances (Decoder, etc) will match in structure to that of fp-ts/schema, and not rely on Schemable in io-ts. For example, Decoder will return a These with DecodeErrors compatible with fp-ts/schema DecodeErrors.

Additionally it might be possible to write a zero'th order schemable typeclass for fp-ts/schema's AST, which would make complete interop possible.

Schemables

• Schema is changing into a simple Reader, where the reader environment is the smallest necessary environment to produce a Schemable typeclass.
• The Reader environment of a Schema will be a struct with symbolic keys i.e. Symbol("string"), which is a typesafe alternative to fp-ts/schema's Symbol.for inside a nested Map.
• Schemable Extensions (Withs) will be renamed to lowercase without the With, and will be classified as Schemables.
• Schemables will contain a Reader environment definition, a Schema which consumes that definition, and instances for all (or some) of the Schemable Typeclasses.
• The Schemable modules will also export constructors that take the internal methods as arguments and arranges them in an appropriate manner. The schemable instances will consume this constructor in ./instances/InstanceName.ts.
• SchemableBase will be split up into their own Schemable modules like src/schemables/primitive
• Schemata will be defined in terms of which reader environments they require, and schema combinators will handle intersections of reader environments.

Schemata API

• The schemata from src/schemata will largely not change, and will still be exported from src/schemata.ts.
• Schemable Schemas in src/schemata.ts will be exported as flat Schamata from their respective files. I.e. Date.dateString() will turn into DateString().
• Other single definition Schemable Schemas will not change. I.e. Int() will stay Int().
• Under the hood, Schemable Schemas will be exported using export * from.

Peer Dependencies

Schemata-ts version 2.0 will list fp-ts/core, fp-ts/data, and fp-ts/schema as peer dependencies, and the library will be reworked to use the new APIs from the fp-ts organization.

[skeate]

Schema is changing into a simple Reader, where the reader environment is the smallest necessary environment to produce a Schemable typeclass.

It's kind of a Reader but not really (and it already is this; it's not changing). The main difference is that currently a Schema is a <S>(S: Schemable<S>) => HKT<S, A> where A is determined by the schema combinators; with the change it will be something like <R, S>(S: RequiredSchemables<R, S>) => HKT<S, A> very roughly.

/nitpick

[jacob-alford]

This wasn't my original plan, but after experimenting with generic requirements, it made things much more complicated. Now I'm heavily leaning toward an architecture that isn't so different than it is now, with the key difference being Schemable extensions namespaced by symbol.

Check out the 2.0 branch for an example: https://github.com/jacob-alford/schemata-ts/blob/2.0/src/schemables/primitives/index.ts

And arguably this is similarly extensible, because any consumer of the library could do module augmentation to expand Schemable, even though it's a bit cumbersome to spread the existing Schemable into a hand-rolled Schemable Ext.

[skeate]

this is functionally identical to the 1.x setup and doesn't seem to permit instances supporting only some schemables

... actually with augmentation it might be a little worse because you can't splice in WithFoo schemables as needed; everything is augmented into one big module so every instance has to support all of it

[jacob-alford]

I've gone back and forth on whether to have partial schema interpretation. It'd be frustrating to write a schema only to find out that the instance you need to make can't be made without digging into deeply nested type errors. For this reason I think we should lean heavily toward complete schema support.

IMO this is a killer arch if we intend to have complete schema support.

That said, if you can find a way to do it, and it's extensible and user friendly, I'm inclined to do it if we ever were to find need for something with only partial support.

[jacob-alford]

Possible hybrid option:

Keep the module augmentation but have empty Schemables defined for every typeclass i.e. DecoderSchemable, EncoderSchemable.

We can then write a SchemableLambda to abstract over all the FooSchemables and use a single interpreter / schema definition

[jacob-alford]

Amendment: base type declarations like Printer will live in src/Printer, and the generated Derivation will live in src/derivations/printer and will be a collection of every PrinterSupport interface (referenced by symbol) for all src/schemables/* that contain an instances/printer file.

And if we're able to write that dynamic requirements schema, it should pair quite nicely.

This will allow us to add derivation specific combinators / helpers