Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/PaulBraetz/Unions
https://github.com/PaulBraetz/Unions
Last synced: 29 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/PaulBraetz/Unions
- Owner: PaulBraetz
- License: gpl-3.0
- Created: 2023-11-10T20:19:29.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-05-06T17:42:09.000Z (7 months ago)
- Last Synced: 2024-08-04T02:07:36.608Z (4 months ago)
- Language: C#
- Size: 343 KB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
- csharp-source-generators - Unions -   for generating meaningful, efficient union types. (Source Generators / Functional Programming)
README
# This Repo Is Obsoleted By: https://github.com/PaulBraetz/RhoMicro.CodeAnalysis/tree/release/UnionsGenerator
# Unions
Read about union types here: https://en.wikipedia.org/wiki/Union_type
## Table of Contents
1. [Features](#Features)
2. [Alternative Union Type Implementations](#Alternative-Union-Type-Implementations)
3. [Installation](#Installation)
4. [How To Use](#How-To-Use)
5. [Contrived Example](#Contrived-Example)
6. [Why Not OneOf?](#Why-Not-OneOf?)
## Features
- generate rich examination and conversion api
- automatic relation type detection (congruency, superset, subset, intersection)
- generate conversion operators
- generate meaningful api names like `myUnion.IsResult` or `MyUnion.CreateFromResult(result)`
- generate the most efficient impementation for your usecase and optimize against boxing or size constraints
## Alternative Union Type Implementations
- [OneOf](https://github.com/mcintyre321/OneOf)
- [ValueVariant](https://github.com/hikarin522/ValueVariant)
- [DiscriminatedUnion](https://github.com/sdedalus/DiscriminatedUnion)
- [CSharpDiscriminatedUnion](https://github.com/Galad/CSharpDiscriminatedUnion)
- [UnionType](https://github.com/Cricle/UnionType)
- [Funcky Discriminated Union](https://github.com/polyadic/funcky-discriminated-union)
- [N.SourceGenerators.UnionTypes](https://github.com/Ne4to/N.SourceGenerators.UnionTypes) <- This one is really similar to mine
## Installation
Requirements: `net7` (due to `static abstract` members)
Package Reference:
```
runtime; build; native; contentfiles; analyzers; buildtransitive
all
```
CLI:
```
dotnet add package RhoMicro.Unions.Attributes
dotnet add package RhoMicro.Unions
```
## How To Use
Annotate your union type with the `UnionType` attribute:
```cs
[UnionType(typeof(String))]
[UnionType(typeof(Double))]
readonly partial struct Union;
```
Use your union type:
```cs
Union u = "Hello, World!"; //implicitly converted
u = 32; //implicitly converted
u = false; //CS0029 Cannot implicitly convert type 'bool' to 'Union'
```
### Available attributes and instructions:
#### `UnionTypeAttribute`
- `representableType`: Instruct the generator on the kind of representable type:
```cs
[UnionType(representableType: typeof(String))]
[UnionType(representableType: typeof(Double))]
readonly partial struct Union;
```
- `genericRepresentableTypeName`: use `nameof(T)` to use generic parameters as representable types (this will likely change in the future):
```cs
[UnionType(genericRepresentableTypeName:nameof(T))]
readonly partial struct Result;
```
- `Alias`: define aliae for generated members, e.g.:
```cs
Names n = "John";
if(n.IsSingleName)
{
//...
} else if(n.IsMultipleNames)
{
//...
}
[UnionType(typeof(List), Alias = "MultipleNames")]
[UnionType(typeof(String), Alias = "SingleName")]
readonly partial struct Names;
```
- `Options`: define miscellaneous behaviour for the represented type:
```cs
/*
Instructs the generator to emit a superset conversion operator implementation even
the representable type is a generic type parameter. By default, it is omitted because of possible
unification for certain generic arguments.
*/
[UnionType(genericRepresentableTypeName:nameof(T), Alias = "Result", Options = UnionTypeOptions.SupersetOfParameter)]
readonly partial struct Result;
```
```cs
/*
Instructs the generator to emit a superset conversion operator implementation even
the representable type is a generic type parameter. By default, it is omitted because of possible
unification for certain generic arguments.
*/
[UnionType(typeof(Int32), Options = UnionTypeOptions.ImplicitConversionIfSolitary)]
readonly partial struct Union;
```
- `Storage`: optimize the generated storage implementation for the representable type against boxing or size constraints:
Available Storage Options: Auto, Reference, Value, Field
```cs
public enum StorageOption
{
// The generator will automatically decide on a storage strategy.
// If the representable type is known to be a value type,
// this will store values of that type inside a shared value type container.
// Boxing will not occur.
// If the representable type is known to be a reference type,
// this will store values of that type inside a shared reference type container.
// If the representable type is neither known to be a reference type
// nor a value type, this option will cause values of that type to
// be stored inside a shared reference type container.
// If the representable type is a generic type parameter,
// boxing will occur for value type arguments to that parameter.
Auto,
// The generator will always store values of the representable type
// inside a shared reference type container.
// If the representable type is known to be a value type,
// boxing will occur.
// If the representable type is a generic type parameter,
// boxing will occur for value type arguments to that parameter.
Reference,
// The generator will attempt to store values of the representable type
// inside a value type container.
// If the representable type is known to be a value type,
// this will store values of that type inside a shared value type container.
// Boxing will not occur.
// If the representable type is known to be a reference type,
// this will store values of that type inside a shared reference type container.
// Boxing will not occur.
// If the representable type is neither known to be a reference type
// nor a value type, this option will cause values of that type to
// be stored inside a shared value type container.
// If the representable type is a generic type parameter,
// an exception of type TypeLoadException will occur for
// reference type arguments to that parameter.
Value,
// The generator will attempt to store values of the representable type
// inside a dedicated container for that type.
// If the representable type is known to be a value type,
// this will store values of that type inside a dedicated
// value type container.
// Boxing will not occur.
// If the representable type is known to be a reference type,
// this will store values of that type inside a
// dedicated reference type container.
// If the representable type is neither known to be a reference type
// nor a value type, this option will cause values of that type to
// be stored inside a dedicated strongly typed container.
// Boxing will not occur.
Field
}
```
#### `UnionTypeSettingsAttribute`
This attribute may target either a union type or an assembly. When targeting a union type, it defines settings specific to that type. If, however, the attribute is annotating an assembly, it supplies the default settings for every union type in that assembly.
- `ConstructorAccessibility`: define the accessibility of generated constructors:
```cs
public enum ConstructorAccessibilitySetting
{
// Generated constructors should always be private, unless
// no conversion operators are generated for the type they
// accept. This would be the case for interface types or
// supertypes of the target union.
PublicIfInconvertible,
// Generated constructors should always be private.
Private,
// Generated constructors should always be public
Public
}
```
- `DiagnosticsLevel`: define the reporting of diagnostics:
```cs
[Flags]
public enum DiagnosticsLevelSettings
{
// Instructs the analyzer to report info diagnostics.
Info = 0x01,
// Instructs the analyzer to report warning diagnostics.
Warning = 0x02,
// Instructs the analyzer to report error diagnostics.
Error = 0x04,
// Instructs the analyzer to report all diagnostics.
All = Info + Warning + Error
}
```
- `ToStringSetting`: define how implementations of `ToString` should be generated:
```cs
public enum ToStringSetting
{
// The generator will emit an implementation that returns detailed information, including:
// - the name of the union type
// - a list of types representable by the union type
// - an indication of which type is being represented by the instance
// - the value currently being represented by the instance
Detailed,
// The generator will not generate an implementation of ToString.
None,
// The generator will generate an implementation that returns the result of
// calling ToString on the currently represented value.
Simple
}
```
- `Layout`: generate a layout attribute for size optimization
```cs
public enum LayoutSetting
{
// Generate an annotation optimized for size.
Small,
// Do not generate any annotations.
Auto
}
```
- Generic Names: define how generic type parameter names should be generated:
```cs
// Gets or sets the name of the generic parameter for generic Is, As and factory methods.
// Set this property in order to avoid name collisions with generic union type parameters
public String GenericTValueName { get; set; }
// Gets or sets the name of the generic parameter for the DownCast method.
// Set this property in order to avoid name collisions with generic union type parameters
public String DowncastTypeName { get; set; }
// Gets or sets the name of the generic parameter for the Match method.
// Set this property in order to avoid name collisions with generic union type parameters
public String MatchTypeName { get; set; }
```
#### `RelationAttribute`
This attribute defines a relation between the targeted union type the supplied type. The following relations are available:
- `None`
- `Congruent`
- `Superset`
- `Subset`
- `Intersection`
The generator will automatically detect the relation between two union types. The only requirement is for one of the two types to be annotated with the `RelationAttribute`:
```cs
[UnionType(typeof(DateTime))]
[UnionType(typeof(String))]
[UnionType(typeof(Double))]
[Relation(typeof(CongruentUnion))]
[Relation(typeof(SubsetUnion))]
[Relation(typeof(SupersetUnion))]
[Relation(typeof(IntersectionUnion))]
readonly partial struct Union;
[UnionType(typeof(Double))]
[UnionType(typeof(DateTime))]
[UnionType(typeof(String))]
sealed partial class CongruentUnion;
[UnionType(typeof(DateTime))]
[UnionType(typeof(String))]
partial class SubsetUnion;
[UnionType(typeof(DateTime))]
[UnionType(typeof(String))]
[UnionType(typeof(Double))]
[UnionType(typeof(Int32))]
partial struct SupersetUnion;
[UnionType(typeof(Int16))]
[UnionType(typeof(String))]
[UnionType(typeof(Double))]
[UnionType(typeof(List))]
partial class IntersectionUnion;
```
## Contrived Example
In our imaginary usecase, a user shall be retrieved from the infrastructure via a name query. The following types will be found throughout the example:
```cs
sealed record User(String Name);
enum ErrorCode
{
NotFound,
Unauthorized
}
readonly record struct MultipleUsersError(Int32 Count);
```
The `User` type represents a user. The `ErrorCode` represents an error that does not contain additional information, like `MultipleUsersError` does. It represents multiple users having been found while only one was requested.
We define a union type to represent our imaginary query:
```cs
[UnionType(typeof(ErrorCode))]
[UnionType(typeof(MultipleUsersError))]
[UnionType(typeof(User))]
readonly partial struct GetUserResult;
```
Instances of `GetUserResult` can represent *either* an instance of `ErrorCode`, `MultipleUsersError` or `User`.
It will be used in a service façade like so:
```cs
interface IUserService
{
GetUserResult GetUserByName(String name);
}
```
A repository abstracts over the underlying infrastructure:
```cs
interface IUserRepository
{
IQueryable UsersByName(String name);
}
```
Access violations would be communicated through the repository using the following exception type:
```cs
sealed class UnauthorizedDatabaseAccessException : Exception;
```
An implementation of the `IUserService` is provided as follows:
```cs
sealed class UserService : IUserService
{
public UserService(IUserRepository repository) => _repository = repository;
private readonly IUserRepository _repository;
public GetUserResult GetUserByName(String name)
{
IQueryable users;
try
{
users = _repository.UsersByName(name);
} catch(UnauthorizedDatabaseAccessException)
{
return ErrorCode.Unauthorized;
}
var reifiedUsers = users.ToArray();
if(reifiedUsers.Length == 0)
{
return ErrorCode.NotFound;
} else if(reifiedUsers.Length > 1)
{
return new MultipleUsersError(reifiedUsers.Length);
}
return reifiedUsers[0];
}
}
```
As you can see, possible representations of `GetUserResult` are implicitly converted and returned by the service. Users of `OneOf` will be familiar with this.
On the consumer side of this api, a generated `Match` function helps with transforming the union instance to another type:
```cs
sealed class UserModel
{
public UserModel(IUserService service) => _service = service;
private readonly IUserService _service;
public String ErrorMessage { get; private set; } = String.Empty;
public User? User { get; private set; }
public void SetUser(String name)
{
var getUserResult = _service.GetUserByName(name);
User = getUserResult.Match(
HandleErrorCode,
HandleMultipleResult,
user => user);
}
private User? HandleErrorCode(ErrorCode code)
{
ErrorMessage = code switch
{
ErrorCode.NotFound => "The user could not be located.",
ErrorCode.Unauthorized => "You are not authorized to access users.",
_ => throw new NotImplementedException()
};
return null;
}
private User? HandleMultipleResult(MultipleUsersError result)
{
ErrorMessage = $"{result.Count} users have been located. The name was not precise enough.";
return null;
}
}
```
Here is a list of some generated members on the `GetUserResult` union type (implementations have been elided):
```cs
/*Factories*/
public static GetUserResult Create(ErrorCode value);
public static GetUserResult Create(MultipleUsersResult value);
public static GetUserResult Create(User value);
public static Boolean TryCreate(TValue value, out GetUserResult instance);
public static GetUserResult Create(TValue value);
/*Handling Methods*/
public void Switch(
Action onErrorCode,
Action onMultipleUsersResult,
Action onUser);
public TResult Match(
Func onErrorCode,
Func onMultipleUsersResult,
Func onUser);
/*Casting & Conversion*/
public TResult DownCast();
public Boolean Is();
public Boolean Is(Type type);
public TValue As();
public Boolean IsErrorCode;
public ErrorCode AsErrorCode;
public Boolean IsMultipleUsersResult;
public MultipleUsersResult AsMultipleUsersResult;
public Boolean IsUser;
public User AsUser;
public Type GetRepresentedType();
public static implicit operator GetUserResult(ErrorCode value);
public static explicit operator ErrorCode(GetUserResult union);
public static implicit operator GetUserResult(MultipleUsersResult value);
public static explicit operator MultipleUsersResult(GetUserResult union);
public static implicit operator GetUserResult(User value);
public static explicit operator User(GetUserResult union);
```
## Why Not OneOf?
Here are some issues that I have with `OneOf` that this generator aims to solve:
- the internal tag field is a byte instead of an int
- by default, not every representable type has a dedicated field generated for it
- generic value type unions are possible:
```cs
[UnionType(typeof(String))]
[UnionType(nameof(T), Alias = "Result")]
readonly partial struct Result;
```
with helpful members like `IsResult` being generated for you.
- type order does not matter; convert to equivalent unions with ease:
```cs
Union u = DateTime.Now;
//Output: Union( | Double | String){23/11/2023 17:58:58}
Console.WriteLine(u);
EquivalentUnion eu = u.DownCast();
//Output: EquivalentUnion( | Double | String){23/11/2023 17:58:58}
Console.WriteLine(eu);
[UnionType(typeof(DateTime))]
[UnionType(typeof(String))]
[UnionType(typeof(Double))]
readonly partial struct Union;
[UnionType(typeof(Double))]
[UnionType(typeof(DateTime))]
[UnionType(typeof(String))]
sealed partial class EquivalentUnion;
```
- avoid `OneOf` invading your apis, instead rely on dedicated domain names for your union types
- use custom generated members with meaningful names for access to union data:
```cs
var r = Result.CreateFromResult("Hello, World!");
if(r.IsErrorMessage)
{
//handle error
} else if(r.IsResult)
{
//handle result
}
//alternatively:
r.Switch(
onErrorMessage: m =>/*handle error*/,
onResult: r =>/*handle result*/);
[UnionType(typeof(String), Alias = "ErrorMessage")]
[UnionType(nameof(T), Alias = "Result")]
readonly partial struct Result;
```
*Note that for generic union types, there will be no conversion operators generated for representable parameter types. That is why we are using the generated `CreateFromResult` factory method here.*