MorseCode.StagedConstruction 0.2.0

• .NETFramework 4.7.2

  • No dependencies.

• .NETStandard 2.0

  • No dependencies.

• net6.0

  • No dependencies.

0.2.0

This package now targets net472, net6.0, and netstandard2.0, and not net10.0
only. The behavior is the same on every target.

Breaking change: the IConstruct and IStage interfaces are gone. The abstract
classes Constructor<TBaseValues> and Stage<TInput, TOutput, TNext> replace them.
.NET Framework and .NET Standard 2.0 do not support a default interface member,
so Select could not stay on the interface, and an interface cannot force an
implementer to check for a second call. Each class has a public Construct or
Advance method that checks for a second call, also when two threads call at the
same time, and also when the first call fails. Then it calls a method that a
derived class implements: ConstructCore or AdvanceCore. The static class that
made the usual handles, Construct, is now Constructor.

Select works the same way. It is not virtual: it refuses a null selector, uses
the handle, and then calls the virtual method SelectCore, which a derived class
can override.

Behavior change: Select now uses the handle that it is called on. In 0.1.0, a
Construct on the source after a Select succeeded, and the selected handle then
failed. Now the Construct on the source fails, with a message that says Select
used the handle. A second Select on the same handle also fails. Thus, the
values of a base reach one constructor only, also when a derived class
overrides SelectCore.

Construct and Advance now refuse a null constructor or continuation with an
ArgumentNullException, before they use the handle. In 0.1.0, the call used the
handle and then failed with a NullReferenceException.

MorseCode.Mvvm 0.1.0 does not work with this version, although the dependency
range that it was released with admits this version. Use MorseCode.Mvvm 0.2.0
or later.

You must change every signature that names the old types. For example,
StageContinuation<string, IConstruct<AnimalValues>, TResult> becomes
StageContinuation<string, Constructor<AnimalValues>, TResult>, and
Construct.From(values) becomes Constructor.From(values). Compile again any
assembly that you built against 0.1.0.

The classes are not variant, as the interfaces were. A Constructor<Dog> does not
convert to a Constructor<Animal>. A helper that must accept both is generic in
the values type, for example
Describe<T>(Constructor<T> handle) where T : AnimalValues. To change the values
type of a handle, call Select.

0.1.0

The first release. It contains the types for staged construction: the
StageContinuation callback, the IStage and IConstruct handles, and the Stage
and Construct helpers that make the usual handles.

A C# constructor that calls a base constructor has three problems. The order of
the two constructors is fixed. Each constructor can read this before the object
is complete. And a virtual member that the base constructor calls can read a
field of the subclass before the subclass sets it.

Staged construction removes all three. A static Create method builds each value
in a local variable and gives the finished values to a private constructor that
only assigns them. A base does its part in a static CreateBase method. It gives
its output to the subclass through a callback, together with a handle. The
handle is either the next stage, which takes more input from the subclass, or
an IConstruct, which gives the values of the base to the constructor of the
subclass:

 public static TResult CreateBase<TResult>(
     string name,
     StageContinuation<string, IConstruct<AnimalValues>, TResult> continuation) =>
     continuation(name.ToUpperInvariant(), Construct.From(new AnimalValues(name)));

 public static Dog Create(string name) =>
     Animal.CreateBase(name, (output, construct) =>
         construct.Construct(animal => new Dog(animal, bark: output + "!")));

The compiler infers TResult from the lambdas, thus a Create method writes no
type arguments. A base with more than one stage names every stage in the type
of its callback, in order, for example
StageContinuation<TOutput1, IStage<TInput2, TOutput2, IConstruct<TValues>>, TResult>.
The subclass cannot reach the constructor before the base finishes, when the
base keeps the constructor of its values private.

Construct.From(values) makes the usual final handle. Select on an IConstruct
lets a base that has a base of its own extend the values of that base. The
selector runs when the subclass constructs, and not before. Stage.From(body)
makes a stage from a function that takes the input of the subclass and returns
the output and the next handle. A null selector or body fails when Select or
Stage.From is called, and not later.

A subclass must use each handle one time only, and the handles that
Construct.From, Select, and Stage.From make check this: a second Construct or
Advance throws an InvalidOperationException, also when two threads call at the
same time. The first call uses the handle even if the constructor or stage
throws, so a failed construction cannot be run again. A base that implements
IConstruct or IStage by hand should make the same check.

This package is pre-1.0. Its API can change in a minor version until 1.0.0.

---

About this package

Construction of immutable objects in ordered stages, with no access to a partly
built object. It is part of the MorseCode toolkit, which holds the conventions
that MorseCode Software builds its own applications with.

Targets net472, net6.0, and netstandard2.0. No dependencies.

Source: https://github.com/MorseCode-Software/MorseCode.Toolkit