2.0

[jacob-alford]

Thank you for supporting schemata-ts! Feel welcome to open PRs, submit issues, or discussions; get yourself on the contributor's list!

Feature Upgrades

No longer depends on io-ts

Schemata 2.0 is built from the ground up with its own extensible version of Schemable hand-crafted for all supported derivations.

(New) Transcoder and TranscoderPar

Schemata-ts 1.0 was built on top of io-ts 'experimental' and had derivations for Decoder, and Encoder. Later, schemata added its own version of Codec which for io-ts meant a combined decoder and encoder, but for schemata meant encoding, decoding, and serialization. Though novel, this prevented serializers from being composable with other schemas. This is because encoding was infallible and thus prevented instances that permitted fallible operations such as serialization and deserialization. Furthermore, io-ts experimental errors used a binary tree FreeSemigroup as its error grouping which made working with decode errors cumbersome.

Schemata-ts 2.0 comes with its own iteration of Codec: Transcoder. Transcoder has two methods: encode and decode. Both methods are fallible and come with the requirement that encoding and decoding are idempotent, which means that for all inner transcoder types, two consecutive encodes/decodes will round trip up to an isomorphism.

Because Transcoder is now circularly fallible, parser schemas are now possible. Schemata-ts comes with two printer/parser schemas out of the box: ParseJsonString which refocuses the input type to valid json-strings, and ParseBase64Json which is the same as ParseJsonString but has an extra step of encoding / decoding the string to and from URI-encoded/decoded base 64.

Schemata-ts 2.0 also comes with its own TranscodeError which is more ergonomic using ReadonlyNonEmptyArray as its concatenating structure and comes with helpers to reduce its tree structure into common semigroups. 

TranscoderPar is the same as Transcoder and the successor to TaskDecoder. The difference is that both methods return TaskEithers, and operate in parallel for operations where that applies, such as traversing arrays, records, or structs.

Json Schema

Now JsonSchema can now be projected into specific versions: Draft-07, 2019-09, and 2020-12. Additionally, JsonSchemas can now be annotated with reference for lazy schemas, readOnly, and deprecated. Additionally, the Optional schema can be supplied a fallback parameter which will lend its JsonSchema a default value.

(New) Type String

Schemata-ts has consolidated the expected error for transcoders largely in part due to the new Type String derivation. Type String is just a tuple of two strings: one input, the other output. Both describe the input/output types for a schema providing pseudo-TypeScript for debugging and typing information. In a pinch, it can be used in documentation or error messages as a quick overview of what's expected.

(New) MergeSemigroup

MergeSemigroup is a data type with a method semigroup which accepts an argument of either: "first," "last," or an object with semigroups that apply to particular primitives. Calling this method will return a semigroup that merges mergeable data types (like arrays, or records) and uses the supplied parameter for others.  

And more

• Optional schema will display a ? for input struct properties in type signatures
• Optional now accepts a fallback input value
• Struct now accepts an optional index signature as an additional way to handle unexpected properties
• (New) Strict schema for raising errors on unexpected keys
• (New) CamelCaseString for converting strings into a camelcase 
• (New) CamelCaseRecord for converting the keys of a record to all be camelcase
• (New) Union - a proper union type that first sorts elements by complexity to mitigate non-mutually exclusive union elements
• (New) Parse build your own string parser schemas
• (New) ParseEncodedJson apply a fallible string mapping function to serialized JSON
• Parser schemas pass their inner schema type to the string JSON schema
• Greatly improved architecture/repository organization
• Greatly improved documentation
• Stronger number types Float and Int branded with their configured min/max values
• String is now configurable with min/max length
• Date and DateString are now configurable with beforeDate and afterDate
• Array is now configurable with minLength and maxLength
• String validation schemas now use Kuvio under the hood
• newtype is now simpler with its own NewtypeIso data type
• brand now uses type-fest > Opaque for compatibility with other systems
• Schema now has stronger type-checking with two new methods: input/output which can be used as constructor functions 
• Schemata now has a stronger uniform testing suite
• Schemata now has a dedicated Eq module and instances
• Arbitrary construction is now memoized alongside MergeSemigroup

Breaking Changes

• getFoo interpreters are now called deriveFoo in the spirit of Haskell and Purescript
• Intersect is now binary instead of curried
• brand now uses type-fest's Opaque technique for branding which is incompatible with io-ts's branding
• String now has optional parameters
• Sum is replaced by Union
• Printer, JsonSerializer, and JsonDeserializer, are now replaced by parser schemas
• make, interpret, memoize are no longer exported from a primary module, use pre-constructed schemas instead
• Schemable instances are no longer exported
• Type has been removed
• iso has been removed
• struct has now been incorporated into the primary Struct schema
• Struct key remapping has been removed due to a high likelihood of overlapping keys that result in unlawful instances
• JsonFromString has been removed in favor of parsing schemas
• UUID is now a Newtype

2.0 Roadmap

Error Collation

Transcoders now produce a Left which is tagged with the type that produced that particular failure. This means that error reporters can be constructed for specific types. In a future release expect error reporters such as:

declare const collateFieldErrors: <T extends Record<string, Primitive>>(errs: Const<TranscodeErrors, T>) => ReadonlyMap<keyof T, string>

More Validators

Schemata-ts already has a ton of validators, but expect more in the near future!

Something else?

Schemata-ts welcomes all contributions and ideas, don’t be afraid to open up a ticket, PR, or start a discussion!

---

This discussion was created from the release 2.0.