Components

Features:FsCodec

Features:FsCodec.(Newtonsoft|SystemText)Json

Common API

Codec

Converters:Newtonsoft.Json.Converters /System.Text.Json.Serialization.JsonConverters

Explicit vs Implicit

This set might be all you need ...

... but don't forgetFSharp.SystemTextJson

Core converters

Custom converter base classes

Newtonsoft.Json-specific low level converters

System.Text.Json-specific low level converters

FsCodec.NewtonsoftJson.Options

FsCodec.SystemTextJson.Options

Serdes

Usage of Converters with ASP.NET Core

ASP.NET Core withNewtonsoft.Json

/// Define a Serdes instance with a given policy somewhere (globally if you need to do explicit JSON generation) let serdes = FsCodec.NewtonsoftJson.Serdes.Defaultservices.AddMvc(fun options -> ...).AddNewtonsoftJson(fun options ->    // Borrow the Converters from the Options the Serdes is holding    serdes.Options.Converters |> Seq.iter options.SerializerSettings.Converters.Add    // OR, in the trivial case: Options.Default.Converters |> Seq.iter options.SerializerSettings.Converters.Add) |> ignore

ASP.NET Core withSystem.Text.Json

// Default behavior throws an exception if you attempt to serialize a DU or TypeSafeEnum without an explicit JsonConverterAttribute// let serdes = FsCodec.SystemTextJson.Serdes.Default// If you use autoTypeSafeEnumToJsonString = true or autoUnionToJsonObject = true, serdes.Serialize / Deserialize applies the relevant converterslet options = FsCodec.SystemTextJson.Options.Create(autoTypeSafeEnumToJsonString = true, autoUnionToJsonObject = true, rejectNullString = true)let serdes = FsCodec.SystemTextJson.Serdes optionsservices.AddMvc(fun options -> ...).AddJsonOptions(fun options ->    // Register the converters from the Options passed to the `serdes` above    serdes.Options.Converters |> Seq.iter options.JsonSerializerOptions.Converters.Add) |> ignore

Examples:FsCodec.(Newtonsoft|SystemText)Json

Examples of usingSerdes to define a contract

Simple contracts that tag all types or fields necessitatingConverters directly and only records andoptions

openFsCodec.SystemTextJson// or FsCodec.NewtonsoftJson if you prefer and/or have legacy converters etcmoduleContract=typeItem={ value:string option}// No special policies required as we are using standard typesletprivateserdes= Serdes Options.Default// implies default settings from Options.Create(), i.e., includes UnsafeRelaxedJsonEscapingletserialize(x:Item):string= serdes.Serialize x// implies default settings from Options.Create()letdeserialize(json:string)= serdes.Deserialize json

More advanced case necessitating a custom converter

moduleContract=typeItem={ value:string option; other:TypeThatRequiresMyCustomConverter}/// Options to be used within this contract - note the Pascal Cased Value property compared to the previous record definitionletprivateoptions= Options.Create(converters=[| MyCustomConverter()|], camelCase=true)letprivateserdes= Serdes optionsletserialize(x:Item)= serdes.Serialize xletdeserialize(json:string):Item= serdes.Deserialize json

Encoding and conversion of F# types

Recommended round-trippable constructs

Unsupported types and/or constructs

TypeSafeEnumConverter

Out of the box behavior:Newtonsoft.Json

typeStatus= Initial| ActivetypeStatusMessage={ name:string option; status:Status}letstatus={ name= None; status= Initial}// The problems here are:// 1. the value has lots of noise, which consumes storage space, and makes parsing harder// 2. other languages which would naturally operate on the string value if it was presented as such will have problems parsing// 3. it's also simply unnecessarily hard to read as a humanserdes.Serialize status// "{"name":null,"status":{"Case":"Initial"}}"// If we pretty-print it, things get worse, not better:letserdesFormatted= Serdes(Options.Create(indent=true))serdesFormatted.Serialize(status)// "{//   "name": null,//   "status": {//     "Case": "Initial"//   }// }

Out of the box behavior:System.Text.Json

// Without any converters in force, Serdes exposes System.Text.Json's internal behavior, which throws:typeStatus= Initial| ActivetypeStatusMessage={ name:string option; status:Status}letstatus={ name= None; status= Initial}serdes.Serialize status// System.NotSupportedException: F# discriminated union serialization is not supported. Consider authoring a custom converter for the type.//    at System.Text.Json.Serialization.Converters.FSharpTypeConverterFactory.CreateConverter(Type typeToConvert, JsonSerializerOptions options)

TypeSafeEnumConverter behavior

FsCodec.NewtonsoftJson.TypeSafeEnumConverter

letserdes2= Serdes.Default[<Newtonsoft.Json.JsonConverter(typeof<TypeSafeEnumConverter>)>]typeStatus2= Initial| ActivetypeStatusMessage2={ name:string option; status:Status2}letstatus2={ name= None; status= Initial}serdes2.Serialize status2// "{"name":null,"status":"Initial"}"

// A single registered converter supplied when creating the Serdes can automatically map all Nullary Unions to strings:openFsCodec.NewtonsoftJsonletserdesWithConverter= Serdes(Options.Create(TypeSafeEnumConverter()))// NOTE: no JsonConverter attributetypeStatus3= Initial| ActivetypeStatusMessage3={ name:string option; status:Status3}letstatus3={ name= None; status= Initial}serdesWithConverter.Serialize status3// "{"name":null,"status":"Initial"}"

FsCodec.SystemTextJson.TypeSafeEnumConverter<'T>

typeStatus= Initial| ActivetypeStatusMessage={ name:string option; status:Status}letstatus={ name= None; status= Initial}

openFsCodec.SystemTextJsonletserdesWithConverter= Serdes<| Options.Create(TypeSafeEnumConverter<Status>())serdesWithConverter.Serialize status// "{"name":null,"status":"Initial"}"Rather than havingto supply lotsofsuchconverterisntances,therecommendationistotageachtype:```fsharpletserdes= Fscodec.SystemTextJson.Serdes.Default// NOTE in System.Text.Json, the converter is generic, and must reference the actual type (here: Status2)[<System.Text.Json.Serialization.JsonConverter(typeof<TypeSafeEnumConverter<Status2>>)>]typeStatus2= Initial| ActivetypeStatusMessage2={ name:string option; status:Status2}letstatus2={ name= None; status= Initial}serdes.Serialize status2

openFsCodec.SystemTextJson// NOTE: Every Nullary Union Type needs a specific instantiation of the generic converter registered:letserdesWithConverter= Serdes<| Options.Create(TypeSafeEnumConverter<Status>())serdesWithConverter.Serialize status// "{"name":null,"status":"Initial"}"

openFsCodec.SystemTextJsonletoptions= Options.Create(autoTypeSafeEnumToJsonString=true, rejectNullStrings=true)letserdes3= Serdes optionstypeStatus3= Initial| ActivetypeStatusMessage3={ name:string option; status:Status3}letstatus3={ name= None; status= Initial} serdes3.Serialize status3// "{"name":null,"status":"Initial"}"

Custom converters usingJsonIsomorphism

typeGuidConverter()=inherit JsonIsomorphism<Guid, string>()override_.Pickle g= g.ToString"N"override_.UnPickle g= Guid.Parse g

[<JsonConverter(typeof<TypeSafeEnumConverter>)>]typeOutcome= Joy| Pain| MiserytypeMessage={ name:string option; outcome:Outcome}letvalue={ name= Somenull; outcome= Joy}serdes.Serialize value// {"name":null,"outcome":"Joy"}serdes.Deserialize<Message>"""{"name":null,"outcome":"Joy"}"""// val it : Message = {name = None; outcome = Joy;}

serdes.Deserialize<Message>"""{"name":null,"outcome":"Discomfort"}"""// throws System.Collections.Generic.KeyNotFoundException: Could not find case 'Discomfort' for type 'FSI_0012+Outcome'

TypeSafeEnum fallback converters usingJsonIsomorphism

[<JsonConverter(typeof<OutcomeWithCatchAllConverter>)>]typeOutcomeWithOther= Joy| Pain| Misery| OtherandOutcomeWithCatchAllConverter()=inherit JsonIsomorphism<OutcomeWithOther, string>()override_.Pickle v=        FsCodec.TypeSafeEnum.toString voverride_.UnPickle json=        json|> FsCodec.TypeSafeEnum.tryParse<OutcomeWithOther>|> Option.defaultValue OthertypeMessage2={ name:string option; outcome:OutcomeWithOther}

letvalue2={ name= Somenull; outcome= Joy}serdes.Serialize value2// {"name":null,"outcome":"Joy"}serdes.Deserialize<Message2>"""{"name":null,"outcome":"Joy"}"""// val it : Message = {name = None; outcome = Joy;}

serdes.Deserialize<Message2>"""{"name":null,"outcome":"Discomfort"}"""// val it : Message = {name = None; outcome = Other;}

Features:IEventCodec

FsCodec.IEventCodec

/// Defines a contract interpreter that encodes and/or decodes events representing the known set of events borne by a stream categorytypeIEventCodec<'Event,'Format,'Context>=/// Encodes a 'Event instance into a 'Format representationabstractEncode: context:'Context* value:'Event->IEventData<'Format>/// Decodes a formatted representation into a 'Event instance. Does not throw exception on undefined EventTypesabstractDecode: encoded:ITimelineEvent<'Format>->'Eventvoption

FsCodec.IEventData

/// Common form for either a Domain Event or an Unfolded Event, without any context regarding its place in the timeline of eventstypeIEventData<'Format>=/// The Event Type, used to drive deserializationabstractmemberEventType:string/// Event body, as UTF-8 encoded JSON ready to be injected into the StoreabstractmemberData:'Format/// Optional metadata (null, or same as Data, not written if missing)abstractmemberMeta:'Format/// Application-generated identifier used to drive idempotent writes based on deterministic Ids and/or Request IdabstractmemberEventId:System.Guid/// The Correlation Id associated with the flow that generated this event. Can be `null`abstractmemberCorrelationId:string/// The Causation Id associated with the flow that generated this event. Can be `null`abstractmemberCausationId:string/// The Event's Creation Time (as defined by the writer, i.e. in a mirror, this is intended to reflect the original time)/// - For EventStore, this value is not honored when writing; the server applies an authoritative timestamp when accepting the write.abstractmemberTimestamp:System.DateTimeOffset

FsCodec.ITimelineEvent

/// Represents a Domain Event or Unfold, together with it's 0-based Index in the event sequencetypeITimelineEvent<'Format>=inherit IEventData<'Format>/// The 0-based index into the event sequence of this EventabstractmemberIndex:int64/// Application-supplied context related to the origin of this eventabstractmemberContext:obj/// Indicates this is not a true Domain Event, but actually an Unfolded Event based on the State inferred from the Events up to and including that at IndexabstractmemberIsUnfold:bool

Contracts for parsing / routing event records

moduleEvents=typeAdded={ item:string}typeRemoved={ name:string}typeEvent=| AddedofAdded| RemovedofRemovedinterface TypeShape.UnionContract.IUnionContractletcodec= Store.codec<Event>

namespace globalopenFsCodec.SystemTextJsonmoduleStore=typeEvent= FsCodec.ITimelineEvent<EventBody>// Many stores use a ReadOnlyMemory<byte> to represent a UTF-8 encoded JSON event body// System.Text.Json.JsonElement can be a useful alternative where the store is JSON basedandEventBody= ReadOnlyMemory<byte>andCodec<'Ewhen'E:>TypeShape.UnionContract.IUnionContract>= FsCodec.IEventCodec<'E, EventBody, unit>// Opt in to:// - mapping Type Safe Enums (F# Unions where the cases have no bodies) to/from Strings// - mapping other F# Unions using the UnionConverter with default settoings// TOCONSIDER avoid using this automatic behavior, and instead let the exception that System.Text.Json//            produces trigger adding a JsonConverterAttribute for each type as Documentationletprivateoptions= Options.Create(autoTypeSafeEnumToJsonString=true, autoUnionToJsonObject=true)letserdes= Serdes optionsletcodec<'Ewhen'E:>TypeShape.UnionContract.IUnionContract>:Codec<'E>=        Codec.Create(serdes= serdes)// OR, if your Store uses JsonElement bodies// CodecJsonElement.Create(serdes = serdes)

Strongly typed stream ids usingFSharp.UMX

openFSharp.UMXtype[<Measure>]clientIdtypeClientId= string<clientId>moduleClientId=letparse(str:string):ClientId=% strlettoString(value:ClientId):string=% valuelet(|Parse|)= ClientId.parse

Stream naming conventions

{Category}-{StreamId}

// Type aliases for a type-tagged `string`type[<Measure>]streamNametypeStreamName= string<streamName>moduleStreamName=lettoString(streamName:StreamName):string= UMX.untag streamName// Validates and maps a trusted Stream Name consisting of a Category and an Id separated by a '-` (dash)// Throws InvalidArgumentException if it does not adhere to that formletparse(rawStreamName:string):StreamName=...// Recommended way to specify a stream identifier; a category identifier and a streamId representing the aggregate's identity// category is separated from id by `-`letcreate(category:string)streamId:StreamName=...// Composes a StreamName from a category and > 1 name elements.// category is separated from the streamId by '-'; elements are separated from each other by '_'letcompose(category:string)(streamIdElements:string[]):StreamName=.../// Extracts the category portion of the StreamNameletcategory(x:StreamName):string=...let(|Category|)= category/// Splits a well-formed Stream Name of the form <c>{category}-{streamId}</c> into its two elements./// Throws InvalidArgumentException if it does not adhere to the well known format (i.e. if it was not produced by `parse`)./// Inverse of <c>create</c>letsplit(streamName:StreamName):struct(string* StreamId)=.../// Splits a well-formed Stream Name of the form <c>{category}-{streamId}</c> into its two elements./// Throws InvalidArgumentException if the stream name is not well-formed./// Inverse of <c>create</c>let(|Split|):StreamName->struct(string* StreamId)= split/// Yields the StreamId, if the Category matches the specified onelettryFind categoryName(x:StreamName):StreamId voption=...

/// Represents the second half of a canonical StreamName, i.e., the streamId in "{categoryName}-{streamId}"typeStreamId= string<streamId>and [<Measure>]streamId/// Helpers for composing and rendering StreamId valuesmodule StreamId=/// Any string can be a StreamId; parse/dec/Elements.split will judge whether it adheres to a valid formletcreate:string->StreamId= UMX.tag/// Render as a string for external uselettoString:StreamId->string= UMX.untag/// Generate a StreamId from a single application-level id, given a rendering function that maps to a non empty fragment without embedded `_` charsletgen(f:'a->string):'a->StreamId=.../// Generate a StreamId from a tuple of application-level ids, given two rendering functions that map to a non empty fragment without embedded `_` charsletgen2 f1 f2:'a* 'b-> StreamId=.../// Generate a StreamId from a triple of application-level ids, given three rendering functions that map to a non empty fragment without embedded `_` charsletgen3 f1 f2 f3:'a* 'b* 'c-> StreamId=.../// Generate a StreamId from a 4-tuple of application-level ids, given four rendering functions that map to a non empty fragment without embedded `_` charsletgen4 f1 f2 f3 f4:'a* 'b* 'c* 'd-> StreamId=.../// Validates and extracts the StreamId into a single fragment value/// Throws if the item embeds a `_`, is `null`, or is emptyletparseExactlyOne(x:StreamId):string=.../// Validates and extracts the StreamId into a single fragment value/// Throws if the item embeds a `_`, is `null`, or is emptylet(|Parse1|)(x:StreamId):string=.../// Splits a StreamId into the specified number of fragments./// Throws if the value does not adhere to the expected fragment count.letparse count(x:StreamId):string[]=letxs= Elements.split xif xs.Length<> countthen            invalidArg"x"(sprintf"StreamId '{%s}' must have {%d} elements, but had {%d}."(toString x) count xs.Length)        xs/// Splits a StreamId into an expected number of fragments./// Throws if the value does not adhere to the expected fragment count.let(|Parse|)count:StreamId->string[]= parse count/// Extracts a single fragment from the StreamId. Throws if the value is composed of more than one item.letdec f(x:StreamId)=                   parseExactlyOne x|> f/// Extracts 2 fragments from the StreamId. Throws if the value does not adhere to that expected form.letdec2 f1 f2(x:StreamId)=letxs= parse2 xinstruct(f1 xs[0], f2 xs[1])/// Extracts 3 fragments from the StreamId. Throws if the value does not adhere to that expected form.letdec3 f1 f2 f3(x:StreamId)=letxs= parse3 xinstruct(f1 xs[0], f2 xs[1], f3 xs[2])/// Extracts 4 fragments from the StreamId. Throws if the value does not adhere to that expected form.letdec4 f1 f2 f3 f4(x:StreamId)=letxs= parse4 xinstruct(f1 xs[0], f2 xs[1], f3 xs[2], f4 xs[3])

module Stream / module Reactions: Contracts for parsing / routing event records

(* Stream id generation/parsing logic. Normally kept private; Reactions module exposes relevant parsers to the wider application*)moduleprivateStream=// By convention, each contract defines a 'category' used as the first part of the stream name (e.g. `"Favorites-ClientA"`)let [<Literal>]Category="Favorites"/// Generates a strongly typed StreamId from the supplied Idletid:ClientId->FsCodec.StreamId= FsCodec.StreamId.gen ClientId.toString/// Maps from an app level identifier to a stream name as used when storing events in that stream/// Not normally necessary - typically you generate StreamIds, and you'll load from something that knows the Categoryletname:ClientId->FsCodec.StreamName= id>> FsCodec.StreamName.create Category/// Inverse of `id`; decodes a StreamId into its constituent parts; throws if the presented StreamId does not adhere to the expected formatletdecodeId:FsCodec.StreamId->ClientId= FsCodec.StreamId.dec ClientId.parse/// Inspects a stream name; if for this Category, decodes the elements into application level ids. Throws if it's malformed.letdecode:FsCodec.StreamName->ClientId voption= FsCodec.StreamName.tryFind Category>> ValueOption.map decodeIdmoduleReactions=/// Active Pattern to determine whether a given {category}-{streamId} StreamName represents the stream associated with this Aggregate/// Yields a strongly typed id from the streamId if the Category matcheslet [<return: Struct>](|For|_|)= Stream.decodeletprivatedec= Streams.codec<Events.Event>/// Yields decoded events and relevant strongly typed ids if the Category of the Stream Name matcheslet [<return: Struct>](|Decode|_|)=function|struct(For clientId,_)& Streams.Decode dec events-> ValueSomestruct(clientId, events)|_-> ValueNone

Decoding events

letutf8(s:string)= System.Text.Encoding.UTF8.GetBytes(s)letstreamForClient c= Stream.name(ClientId.parse c)letevents=[    Stream.name(ClientId.parse"ClientA"),                 FsCodec.Core.TimelineEvent.Create(0L,"Added",     utf8"""{ "item": "a" }""")    streamForClient"ClientB",                              FsCodec.Core.TimelineEvent.Create(0L,"Added",     utf8"""{ "item": "b" }""")    FsCodec.StreamName.parse"Favorites-ClientA",           FsCodec.Core.TimelineEvent.Create(1L,"Added",     utf8"""{ "item": "b" }""")    streamForClient"ClientB",                              FsCodec.Core.TimelineEvent.Create(1L,"Added",     utf8"""{ "item": "a" }""")    streamForClient"ClientB",                              FsCodec.Core.TimelineEvent.Create(2L,"Removed",   utf8"""{ "item": "a" }""")    FsCodec.StreamName.compose"Favorites"[|"ClientB"|], FsCodec.Core.TimelineEvent.Create(3L,"Exported",  utf8"""{ "count": 2 }""")    FsCodec.StreamName.parse"Misc-x",                      FsCodec.Core.TimelineEvent.Create(0L,"Dummy",     utf8"""{ "item": "z" }""")]andthe helpers defined above,we can route and/or filter them as follows:```fsharp// When we obtain events from an event store via streaming notifications, we typically receive them as ReadOnlyMemory<byte> bodiestype Event= FsCodec.ITimelineEvent<EventBody>andEventBody= ReadOnlyMemory<byte>andCodec<'E>= FsCodec.IEventCodec<'E, EventBody, unit>letstreamCodec<'Ewhen'E:>TypeShape.UnionContract.IUnionContract>:Codec<'E>=    Codec.Create<'E>(serdes= Store.serdes)letdec= streamCodec<Events.Event>let [<return:Struct>](|DecodeEvent|_|)(codec:Codec<'E>)event= codec.Decode eventletrunCodecExplicit()=for stream, eventin eventsdomatch stream, eventwith| Reactions.For clientId, DecodeEvent dec e->            printfn $"Client%s{ClientId.toString clientId}, event%A{e}"| FsCodec.StreamName.Splitstruct(cat, sid), e->            printfn $"Unhandled Event: Category%s{cat}, Ids%s{FsCodec.StreamId.toString sid}, Index%d{e.Index}, Event:%A{e.EventType}"

Client ClientA, event Added {item = "a";}Client ClientB, event Added {item = "b";}Client ClientA, event Added {item = "b";}Client ClientB, event Added {item = "a";}Client ClientB, event Removed {name = null;}Unhandled Event: Category Favorites, Id ClientB, Index 3, Event: "Exported"Unhandled Event: Category Misc, Id x, Index 0, Event: "Dummy"

Adding Matchers to the Event Contract

moduleReactionsBasic=letdec= streamCodec<Events.Event>let(|DecodeSingle|_|):FsCodec.StreamName* Event->(ClientId* Events.Event) option=function| Reactions.For clientId, DecodeEvent dec event-> Some(clientId, event)|_-> None

letreactSingle(clientId:ClientId)(event:Events.Event)=    printfn $"Client%s{ClientId.toString clientId}, event%A{event}"letrunCodecMatch()=for streamName, eventin eventsdomatch streamName, eventwith| ReactionsBasic.DecodeSingle(clientId, event)->            reactSingle clientId event| FsCodec.StreamName.Split(cat, sid), e->            printfn $"Unhandled Event: Category%s{cat}, Ids {FsCodec.StreamId.toString sid}, Index%d{e.Index}, Event:%s{e.EventType}"

Processing Reactions, Logging unmatched events

moduleStreams=// Events coming from streams are carried as a TimelineEvent; the body type is configurabletypeEvent= FsCodec.ITimelineEvent<EventBody>// Propulsion's Sinks by default use ReadOnlyMemory<byte> as the storage formatandEventBody= ReadOnlyMemory<byte>// the above Events can be decoded by a Codec implementing this interfaceandCodec<'E>= FsCodec.IEventCodec<'E, EventBody, unit>/// Generates a Codec for the specified Event Union typeletcodec<'Ewhen'E:>TypeShape.UnionContract.IUnionContract>:Codec<'E>=// Borrowing the Store serdes; frequently the events you parse can use less complex options...        Codec.Create<'E>(serdes= Store.serdes)// as we know our event bodies are all UTF8 encoded JSON, we can render the string as a log event property// alternately, you can render the EventBody directly and ensure you have appropriate type destructuring configuredletprivaterender(x:EventBody):string=        FsCodec.Encoding.GetStringUtf8 x/// Uses the supplied codec to decode the supplied event record `x`/// (iff at LogEventLevel.Debug, detail fails to `log` citing the `streamName` and body)letdecode<'E>(log:Serilog.ILogger)(codec:Codec<'E>)(streamName:FsCodec.StreamName)(x:Event)=match codec.Decode xwith| ValueNone->if log.IsEnabled Serilog.Events.LogEventLevel.Debugthen                log.ForContext("event", render x.Data,true)                    .Debug("Codec {type} Could not decode {eventType} in {stream}", codec.GetType().FullName, x.EventType, streamName)            ValueNone| ValueSome x-> ValueSome x/// Attempts to decode the supplied Event using the supplied Codeclet [<return: Struct>](|Decode|_|)(codec:Codec<'E>)struct(streamName,event)=        decode Serilog.Log.Logger codec streamName eventmoduleArray=let inlinechooseV f xs=[|for itemin xsdomatch f itemwith ValueSome v->yield v| ValueNone->()|]/// Yields the subset of events that successfully decoded (could be Array.empty)letdecode<'E>(codec:Codec<'E>)struct(streamName,events:Event[]):'E[]=        events|> Array.chooseV(decode<'E> Serilog.Log.Logger codec streamName)let(|Decode|)= decode

module Reactions =       let private dec = Streams.codec<Events.Event>    /// Yields decoded events and relevant strongly typed ids if the Category of the Stream Name matches    let [<return: Struct>] (|Decode|_|) = function        | struct (For clientId, _) & Streams.Decode dec events -> ValueSome struct (clientId, events)        | _ -> ValueNone    let react (clientId: ClientId) (event: Events.Event[]) =    printfn "Client %s, events %A" (ClientId.toString clientId) event    let runCodec () =    for streamName, xs in events |> Seq.groupBy fst do        let events = xs |> Seq.map snd |> Array.ofSeq        match struct (streamName, events) with        | Reactions.Decode (clientId, events) ->            react clientId events        | FsCodec.StreamName.Split (cat, sid), events ->            for e in events do                printfn "Unhandled Event: Category %s, Id %A, Index %d, Event: %A " cat sid e.Index e.EventTyperunCodec ()

// Switch on debug logging to get detailed information about events that don't match (which has no singificant perf cost when not switched on)openSerilogopenSerilog.EventsletoutputTemplate="{Message} {Properties}{NewLine}"Serilog.Log.Logger<-    LoggerConfiguration()        .MinimumLevel.Debug()        .WriteTo.Console(LogEventLevel.Debug, outputTemplate=outputTemplate)        .CreateLogger()runCodec()

Codec "<Snipped>" Could not decode "Exported" in "Favorites-ClientB" {event="{ \"count\": 2 }"}

Handling versioning of events in F# with FsCodec

Avoiding versioning by optional or nullable fields

moduleCartV1=typeCreateCart={ name:string}moduleCartV2Null=typeCreateCart={ name:string; cartId:CartId}moduleCartV2Option=typeCreateCart={ name:string; cartId:CartId option}moduleCartV2Nullable=typeCreateCart={ name:string; count:Nullable<int>}

Upconversion by mapping Event Types

moduleEventsV0=typeProperties={ a:string}typePropertiesV2={ a:string; b:int}typeEvent=| PropertiesUpdatedof{| properties: Properties|}| PropertiesUpdatedV2of{| properties: PropertiesV2|}

moduleEventsUpDown=typeProperties={ a:string}typePropertiesV2={ a:string; b:int}modulePropertiesV2=letdefaultB=2/// The possible representations within the store[<RequireQualifiedAccess>]typeContract=| PropertiesUpdatedof{| properties: Properties|}| PropertiesUpdatedV2of{| properties: PropertiesV2|}interface TypeShape.UnionContract.IUnionContract/// Used in the model - all decisions and folds are in terms of thistypeEvent=| PropertiesUpdatedof{| properties: PropertiesV2|}letup:Contract->Event=function| Contract.PropertiesUpdated e-> PropertiesUpdated{| properties={ a= e.properties.a; b= PropertiesV2.defaultB}|}| Contract.PropertiesUpdatedV2 e-> PropertiesUpdated eletdown:Event->Contract=function| Event.PropertiesUpdated e-> Contract.PropertiesUpdatedV2 eletcodec= Codec.Create<Event, Contract,_>(up=(fun _e c-> up c),                                                     down=fun e->struct(down e, ValueNone, ValueNone))moduleFold=typeState= unit// evolve functionsletevolve state=function| EventsUpDown.Event.PropertiesUpdated e-> state

Upconversion via Active Patterns

moduleEvents=typeProperties={ a:string}typePropertiesV2={ a:string; b:int}modulePropertiesV2=letdefaultB=2typeEvent=| PropertiesUpdatedof{| properties: Properties|}| PropertiesUpdatedV2of{| properties: PropertiesV2|}let(|Updated|)=function| PropertiesUpdated e->{| properties={ a= e.properties.a; b= PropertiesV2.defaultB}|}| PropertiesUpdatedV2 e-> emoduleFold=typeState={ b:int}letevolve state:Events.Event->State=function| Events.Updated e->{ statewith b= e.properties.b}

Adding metadata to events based on Domain-intrinsic information

moduleStoreWithMeta=typeEvent<'E>= int64* Metadata* 'EandMetadata={ principal:string}andCodec<'Ewhen'E:>TypeShape.UnionContract.IUnionContract>= FsCodec.IEventCodec<Event<'E>, Store.EventBody, unit>// no special requirements for deserializing Metadata, so use Default Serdesletprivateserdes= Serdes.Defaultletcodec<'Ewhen'E:>TypeShape.UnionContract.IUnionContract>:Codec<'E>=// here we surface the metadata from the raw event as part of the application level event based on the stored formletup(raw:Store.Event)(contract:'E):Event<'E>=            raw.Index, serdes.Deserialize<Metadata> raw.Meta, contract// _index: up and down are expected to encode/decode symmetrically - when encoding, the app supplies a dummy, and the store assigns it on appending// the metadata is encoded as the normal bodies areletdown((_index,meta:Metadata,event:'E):Event<'E>)=struct(event, ValueSome meta, ValueNone)        Codec.Create<Event<'E>, 'E, Metadata>(up, down, serdes= Store.serdes)

Adding Metadata to Events based on extrinsic Context

moduleStoreWithContext=typeContext={ correlationId:string; causationId:string; principal:string}andCodec<'Ewhen'E:>TypeShape.UnionContract.IUnionContract>= FsCodec.IEventCodec<'E, Store.EventBody, Context voption>andMetadata={ principal:string}letcodec<'Ewhen'E:>TypeShape.UnionContract.IUnionContract>:Codec<'E>=letup(_raw:Store.Event)(contract:'E)= contractletdown(event:'E)=// Not producing any Metadata based on the application-level event in this instanceletmeta= ValueNone: Metadata voptionletts= ValueNonestruct(event, meta, ts)letmapCausation(context:Context voption)(_downConvertedMeta:Metadata voption)=leteventId= Guid.NewGuid()letmetadata,corrId,causeId=match contextwith| ValueNone->// In some parts of this system, we don't have a Context to pass - hence we use `Context voption`// as the context type in this instance. Generally, it's recommended for this mapping function// to throw in order to have each path in the system that wishes to generate events be required// to supply the relevant attribution information. But, here we illustrate how to do it loosey goosey!                    ValueNone,null,null| ValueSome v->// We map the correlation/causation identifiers into the designated fields// the remaining information, we save into the Event's Meta field// In this instance, we don't have any metadata arising from the application level events,//   but, if we did, we could merge it into the final rendered `ValueSome` we are passing downletfinalMeta={ principal= v.principal}                    ValueSome finalMeta, v.correlationId, v.causationIdstruct(metadata, eventId, corrId, causeId)        Codec.Create<'E, 'E, Metadata, Context voption>(up, down, mapCausation, serdes= Store.serdes)

typeExternalContext(applicationRelevantThing,correlationId,causationId,principal)=member_.ApplicationRelevantThing= applicationRelevantThingmember_.StoreContext:StoreWithContext.Context={   correlationId= correlationId            causationId= causationId            principal= principal}

moduleFavoritesmoduleEvents=typeEvent=| Add| Removeinterface TypeShape.UnionContract.IUnionContractletcodec= StoreWithContext.codec<Event>moduleFold=typeState=...letdecide appRelevantThing command:Event list=...typeService(resolve: StoreWithContext.Context*ClientId->Decider<Events.Event, Fold.State>)=member_.Handle(context:ExternalContext,clientId,request)=letdecider= resolve(context.StoreContext, clientId)        decider.Transact(decide context.ApplicationRelevantThing command)moduleFactory=letcreate store=letcategory:Equinox.Category<..>=Cosmos.createcodec...letresolve=Store.createDecidercontextcategoryService(resolve)

letstore= Store.connect...letservice= Favorites.Factory.create store...letctx= ExternalContext(...)letclientId,request=...service.Handle(ctx, clientId, request)

Parsing Metadata from Events arriving via Streams

leteventsWithMeta=seq{for sn, ein events->letmeta= utf8"""{"principal": "me"}"""    sn, FsCodec.Core.TimelineEvent.Create(e.Index, e.EventType, e.Data, meta)}

moduleStreamsWithMeta=typeEvent<'E>=(struct(int64* Metadata* 'E))andMetadata={ principal:string}andCodec<'E>= FsCodec.IEventCodec<Event<'E>, Streams.EventBody, unit>// no special requirements for deserializing metadata, so use Default Serdesletprivateserdes= Serdes.Defaultletcodec<'Ewhen'E:>TypeShape.UnionContract.IUnionContract>:Codec<'E>=// here we surface some metadata from the raw event as part of the application level typeletup(raw:Streams.Event)(contract:'E):Event<'E>=struct(raw.Index, serdes.Deserialize<Metadata> raw.Meta, contract)// We are not using this codec to encode events, so we let the encoding side fail very fastletdown _= failwith"N/A"        Codec.Create<Event<'E>, 'E, Metadata>(up, down, options= Store.options)|> FsCodec.Encoder.Uncompressed

module ReactionsWithMeta =         let dec = StreamsWithMeta.codec<Events.Event>    let [<return: Struct>] (|Decode|_|) = function        | struct (Reactions.For clientId, _) & Streams.Decode dec events -> ValueSome struct (clientId, events)        | _ -> ValueNone

letreactStreamWithMeta(clientId:ClientId)(events:StreamsWithMeta.Event<Events.Event>[])=for index, meta, eventin eventsdo        printfn $"Client%s{ClientId.toString clientId}, event%i{index} meta%A{meta} event%A{event}"lethandleWithMeta streamName events=matchstruct(streamName, events)with| ReactionsWithMeta.Decode(clientId, events)->        reactStreamWithMeta clientId events| FsCodec.StreamName.Split(cat, sid),_->for ein eventsdo        printfn $"Unhandled Event: Category%s{cat}, Id%A{sid}, Index%d{e.Index}, Event:%s{e.EventType}"

letrunStreamsWithMeta()=for streamName, xsin eventsWithMeta|> Seq.groupBy fstdoletevents= xs|> Seq.map snd|> Array.ofSeq        handleWithMeta streamName events        runStreamsWithMeta()

Client ClientA index 0 time 2020-01-13 09:44:37Z event Added {item = "a";}Client ClientB index 0 time 2020-01-13 09:44:37Z event Added {item = "b";}Client ClientA index 1 time 2020-01-13 09:44:37Z event Added {item = "b";}Client ClientB index 1 time 2020-01-13 09:44:37Z event Added {item = "a";}Client ClientB index 2 time 2020-01-13 09:44:37Z event Removed {name = null;}Codec "<Snipped>" Could not decode "Exported" in "Favorites-ClientB" {event="{ \"count\": 2 }"}Unhandled Event: Category Favorites, Id ClientB, Index 3, Event: "Exported"Unhandled Event: Category Misc, Id x, Index 0, Event: "Dummy"

Features:FsCodec.Box.Codec

RELATED ARTICLES / BLOG POSTS etc

CONTRIBUTING

Building

# verify the integrity of the repo wrt being able to build/pack/test./dotnet build build.proj