Sharpino 1.3.0-beta

Sharpino

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

A little F# event-sourcing library

What is it?

A library about a simple event-sourcing framework in F#. The example app I provided is more related to the Property-Sourcing (see here for a nice explanation of the difference between event-sourcing and property-sourcing). However, that is a limitation of my example, and not a limitation of the library (and more examples will come later) The events are stored in append mode and cannot be deleted or updated, so the solution at the moment it is not suitable for sensitive data (see GDPR).

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.

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

• LightCommandHandler.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 LightCommandHandler).

• 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 CommandHandler.

• 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 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>
  

More documentation (Sharpino gitbook)