Home

Awesome

PolyType Build & Tests NuGet Badge codecov

PolyType is a practical generic programming library for .NET. It facilitates the rapid development of feature-complete, high-performance libraries that interact with user-defined types. This includes serializers, structured loggers, mappers, validators, parsers, random generators, and equality comparers. Its built-in source generator ensures that any library built on top of PolyType gets Native AOT support for free.

The project is a port of the TypeShape library for F#, adapted to patterns and idioms available in C#. The name PolyType is a reference to polytypic programming, another term for generic programming.

See the project website for additional background and API documentation.

Quick Start

You can try the library by installing the PolyType NuGet package:

$ dotnet add package PolyType

which includes the core types and source generator for generating type shapes:

using PolyType;

[GenerateShape]
public partial record Person(string name, int age);

Doing this will augment Person with an implementation of the IShapeable<Person> interface. This suffices to make Person usable with any library that targets the PolyType core abstractions. You can try this out by installing the built-in example libraries:

$ dotnet add package PolyType.Examples

Here's how the same value can be serialized to three separate formats.

using PolyType.Examples.JsonSerializer;
using PolyType.Examples.CborSerializer;
using PolyType.Examples.XmlSerializer;

Person person = new("Pete", 70);
JsonSerializerTS.Serialize(person); // {"Name":"Pete","Age":70}
XmlSerializer.Serialize(person);    // <value><Name>Pete</Name><Age>70</Age></value>
CborSerializer.EncodeToHex(person); // A2644E616D656450657465634167651846

Since the application uses a source generator to produce the shape for Person, it is fully compatible with Native AOT. See the shape providers article for more details on how to use the library with your types.

Authoring PolyType Libraries

As a library author, PolyType makes it easy to write high-performance, feature-complete components by targeting its core abstractions. For example, a parser API using PolyType might look as follows:

public static class MyFancyParser
{
    public static T? Parse<T>(string myFancyFormat) where T : IShapeable<T>;
}

The IShapeable<T> constraint indicates that the parser only works with types augmented with PolyType metadata. This metadata can be provided using the PolyType source generator:

Person? person = MyFancyParser.Parse<Person>(format); // Compiles

[GenerateShape] // Generate an IShapeable<TPerson> implementation
partial record Person(string name, int age, List<Person> children);

For more information see:

Case Study: Writing a JSON serializer

The repo includes a JSON serializer built on top of the Utf8JsonWriter/Utf8JsonReader primitives provided by System.Text.Json. At the time of writing, the full implementation is just under 1200 lines of code but exceeds STJ's built-in JsonSerializer both in terms of supported types and performance.

Performance

Here's a benchmark comparing System.Text.Json with the included PolyType implementation:

Serialization

MethodMeanRatioAllocatedAlloc Ratio
Serialize_StjReflection491.9 ns1.00312 B1.00
Serialize_StjSourceGen467.0 ns0.95312 B1.00
Serialize_StjSourceGen_FastPath227.2 ns0.46-0.00
Serialize_PolyTypeReflection277.9 ns0.57-0.00
Serialize_PolyTypeSourceGen273.6 ns0.56-0.00

Deserialization

MethodMeanRatioAllocatedAlloc Ratio
Deserialize_StjReflection1,593.0 ns1.001024 B1.00
Deserialize_StjSourceGen1,530.3 ns0.961000 B0.98
Deserialize_PolyTypeReflection773.1 ns0.49440 B0.43
Deserialize_PolyTypeSourceGen746.7 ns0.47440 B0.43

Even though both serializers target the same underlying reader and writer types, the PolyType implementation is ~75% faster for serialization and ~100% faster for deserialization, when compared with System.Text.Json's metadata serializer. As expected, fast-path serialization is still fastest since its implementation is fully inlined.

Known libraries based on PolyType

The following code bases are based upon PolyType and may be worth checking out.

Project structure

The repo consists of the following projects: