Sharpino 1.2.2

Sharpino

<img src="ico/sharpino.png" alt="drawing" width="50"/>

A little event-sourcing framework for F#

a library and an example of a simple event-sourcing framework in F#.

Projects:

Sharpino.Lib:

• Core.fs: Abstract definition of Events, Commands and Undoer (the reverse of a command to be used if storage lacks transaction between streams). Definition of EvolveUnForgivingErrors and "normal" Evolve. The former rise an error if there are some events that cannot be applied to the current state of the aggregate. The latter just skip those events. Note: in some strict setups, for instance in using Postgres or in-memory storage, and in making the command be processed by the Mailboxprocessor (which is how you will see in the examples ensuring single-threaded execution of command->event->store), the EvolveUnForgivingErrors would not be necessary. However, it is theoretically possible to have inconsistent events when the order of the events is not guaranteed (e.g. in a distributed system). To increase the throughput you may actually want to process commands not in single-thread anymore assuming the risk of storing conflicting/inconsistent events.

• Repository.fs: gets and stores snapshots, execute commands, produces and store events using the storage.

• LightRepository.fs: gets and stores snapshots, execute commands, produces and store events using a storage that supports pub/sub model (only Eventstoredb at the moment).

• DbStorage.fs and MemoryStorage.fs: Manages persistency in Postgres or in memory.

• Cache.fs. Cache events, snapshots and state

Sharpino.Sample: You need a user called 'safe' with password 'safe' in your postgres (if you want to use postgres as event store).

It is an example of a library for managing todos with tags and categories. There are two versions in the sense of two different configurations concerning the distribution of the models (collection of entities) between the aggregates. There is a strategy to test the migration between versions (aggregate refactoring) that is described in the code (See: AppVersions.fs and MultiVersionsTests.fs) .

• entities (e.g. Entities) manage entities.

• aggregates (e.g. TodoAggregate) own a partition of the models and provide members to handle them.

• aggregate members have corresponding events (e.g. TagsEvents) that are Discriminated Unions cases. Event types implement the Process interface.

• aggregates are related to Commands (e.g. TagCommand) that are Discriminated Unions cases that can return lists of events by implementing the Executable interface. Commands defines also undoers that are functions that can undo the commands to reverse action in a multiple-stream operation for storage that don't support multiple-stream transactions (see LightRepository).

• A Storage stores and retrieves aggregates, events and snapshots.

• The Repository can build and retrieve snapshots, run the commands and store the related events.

• The api layer functions provide business logic involving one or more aggregates by accessing their state, and by building one or more commands and sending them to the repository.

• An example of how to handle multiple versions of the application to help refactoring and migration between different versions: application versions.

Sharpino.Sample.tests

• tests for the sample application

How to use it

• Just use ordinary dotnet command line tools for building the solution. Particularly you can run tests of the sample application by using the following command:

dotnet test 

You can also run the tests by the following command from Sharpino.Sample.Tests folder:

dotnet run

In the latter case, you get the output from Expecto test runner (in this case the console shows eventual standard output/printf).

By default, the tests run only the in-memory implementation of the storage. You can set up the postgres tables and db by using dbmate. In the Sharpino.Sample folder you can run the following command to setup the Postgres database:

dbmate -e DATABASE_URL up

(see the .env to set up the DATABASE_URL environment variable to connect to the Postgres database with a connection string). If you have Eventstore the standard configuration should work. (I have tested it with Eventstore 20.10.2-alpha on M2 Apple Silicon chip under Docker).

Tests on eventstoredb

If eventstore is running on docker you may want to run tests on it as follow: by making the eventstore tests not pending (search for "eventstore tests" and change ptestList to ftestList) or by uncommenting the following line on the file MultiversionsTests.fs:

        // (AppVersions.evSApp,                    AppVersions.evSApp,                 fun () -> () |> Result.Ok)

Warning: on testing eventstoredb you may experience some random test falures: I added some force update and some little delays to avoid, even though they can arise sometimes anyway in a non reproducible way. The cure is adding more delay if needed.

Faq:

• Why "Sharpino"?
  • It's a mix of Sharp and fino (Italian for "thin"). "sciarpino" (same pronunciation) in Italian means also "little scarf".
• Why another event-sourcing library?
  • I wanted to study the subject and it ended up in a tiny little framework.
• Why F#?
  • Any functional language from the ML family language in my opinion is a good fit for the following reasons:
    • Events are immutable, building the state of the aggregates is a function of those events.
    • Discriminated Unions are suitable to represent events and commands.
    • The use of the lambda expression is a nice trick for the undoers (the under is returned as a lambda that retrieves the context for applying the undo and returns another lambda that actually can "undo" the command).
    • It is a .net language, so you can use everything in the .net ecosystem (including C# libraries).
• How to use it
  • add the nuget package Sharpino to your project (current version 1.0.1)
  • note: on my side, when I added Sharpino as a library into a web app then I had to add the following line to the web app project file to avoid a false error (the error was "A function labeled with the 'EntryPointAttribute' attribute must be the last declaration")

  <GenerateProgramFile>false</GenerateProgramFile>
  

A small gitbook on the subject is available (click to read)