refactor: extract event sourcing contract into dedicated app

ccamel · ccamel · commit 33241eea4119 · 2025-10-30T20:22:11.000+01:00
diff --git a/README.md b/README.md
@@ -340,16 +340,21 @@ The manager can be configured with options such as:
 
 ```plaintext
 apps/
+├── event_sourcing_contract
+│   ├── include/event_sourcing.hrl                  % Shared types and records
+│   └── src                                         % Public behaviours (the contract)
+│       ├── event_sourcing_contract.app.src
+│       ├── event_sourcing_aggregate_behaviour.erl
+│       ├── event_sourcing_event_store_behaviour.erl
+│       └── event_sourcing_snapshot_store_behaviour.erl
 ├── event_sourcing_core
-│   ├── include/event_sourcing_core.hrl             % Shared types and macros
-│   ├── src                                         % Core behaviours + processes
+│   ├── src                                         % Core processes built on the contract
 │   │   ├── event_sourcing_core.app.src
 │   │   ├── event_sourcing_core_aggregate.erl
-│   │   ├── event_sourcing_core_aggregate_behaviour.erl
 │   │   ├── event_sourcing_core_mgr_aggregate.erl
 │   │   ├── event_sourcing_core_mgr_behaviour.erl
 │   │   └── event_sourcing_core_store.erl
-│   └── test                                        % Aggregate + behaviour suites
+│   └── test                                        % Aggregate + store suites
 ├── event_sourcing_store_ets
 │   ├── src/event_sourcing_store_ets.erl            % ETS-backed store implementation
 │   └── test                                        % ETS-focused tests (planned)
diff --git a/apps/event_sourcing_contract/include/event_sourcing.hrl b/apps/event_sourcing_contract/include/event_sourcing.hrl
@@ -77,3 +77,11 @@ Fields:
 - `state`: The serialized aggregate state at the snapshot point.
 """.
 -type snapshot() :: #snapshot{}.
+
+%%% Options for folding events
+-type fold_events_opts() ::
+    #{
+        from => non_neg_integer(),
+        to => non_neg_integer() | infinity,
+        limit => pos_integer() | infinity
+    }.
diff --git a/apps/event_sourcing_contract/src/event_sourcing_aggregate_behaviour.erl b/apps/event_sourcing_contract/src/event_sourcing_aggregate_behaviour.erl
@@ -1,4 +1,4 @@
--module(event_sourcing_core_aggregate_behaviour).
+-module(event_sourcing_aggregate_behaviour).
 -moduledoc """
 Defines the aggregate behaviour for event-sourced domain modules.
 
@@ -15,7 +15,7 @@ Implementers are responsible for:
 - Identifying the event type for a payload (`event_type/1`)
 """.
 
--include_lib("event_sourcing_core.hrl").
+-include("event_sourcing.hrl").
 
 -export_type([aggregate_state/0]).
 
diff --git a/apps/event_sourcing_contract/src/event_sourcing_contract.app.src b/apps/event_sourcing_contract/src/event_sourcing_contract.app.src
@@ -0,0 +1,14 @@
+{application, event_sourcing_contract, [
+    {description, "Contracts (behaviours and types) for event sourcing components"},
+    {vsn, "0.1.0"},
+    {registered, []},
+    {applications, [kernel, stdlib]},
+    {env, []},
+    {modules, [
+        event_sourcing_aggregate_behaviour,
+        event_sourcing_event_store_behaviour,
+        event_sourcing_snapshot_store_behaviour
+    ]},
+    {licenses, ["BSD 3-Clause"]},
+    {links, []}
+]}.
diff --git a/apps/event_sourcing_contract/src/event_sourcing_event_store_behaviour.erl b/apps/event_sourcing_contract/src/event_sourcing_event_store_behaviour.erl
@@ -1,4 +1,4 @@
--module(event_sourcing_core_event_store).
+-module(event_sourcing_event_store_behaviour).
 -moduledoc """
 Behaviour for **event store backends**.
 
@@ -20,7 +20,7 @@ Implementations must guarantee:
 Typical implementations include in-memory stores (ETS) and relational databases.
 """.
 
--include_lib("event_sourcing_core/include/event_sourcing_core.hrl").
+-include("event_sourcing.hrl").
 
 -doc """
 Starts the event store, performing any necessary initialization.
@@ -77,7 +77,7 @@ Returns `{ok, Acc}` where `Acc` is the result of folding all events.
 """.
 -callback retrieve_and_fold_events(StreamId, Options, Fun, Acc0) -> Acc1 when
     StreamId :: stream_id(),
-    Options :: event_sourcing_core_store:fold_events_opts(),
+    Options :: fold_events_opts(),
     Fun :: fun((Event :: event(), AccIn) -> AccOut),
     Acc0 :: term(),
     Acc1 :: term(),
diff --git a/apps/event_sourcing_contract/src/event_sourcing_snapshot_store_behaviour.erl b/apps/event_sourcing_contract/src/event_sourcing_snapshot_store_behaviour.erl
@@ -1,4 +1,4 @@
--module(event_sourcing_core_snapshot_store).
+-module(event_sourcing_snapshot_store_behaviour).
 -moduledoc """
 Behaviour for **snapshot store backends**.
 
@@ -20,7 +20,7 @@ Common implementations include key–value stores, databases, or object storage
 systems (e.g., S3).
 """.
 
--include_lib("event_sourcing_core/include/event_sourcing_core.hrl").
+-include("event_sourcing.hrl").
 
 -doc """
 Save a snapshot for a stream.
diff --git a/apps/event_sourcing_core/src/event_sourcing_core.app.src b/apps/event_sourcing_core/src/event_sourcing_core.app.src
@@ -2,10 +2,9 @@
     {description, "Core library for event sourcing implementation in Erlang"},
     {vsn, "0.1.0"},
     {registered, []},
-    {applications, [kernel, stdlib]},
+    {applications, [kernel, stdlib, event_sourcing_contract]},
     {env, []},
     {modules, [
-        event_sourcing_core_aggregate_behaviour,
         event_sourcing_core_store,
         event_sourcing_core_mgr_aggregate,
         event_sourcing_core_aggregate,
diff --git a/apps/event_sourcing_core/src/event_sourcing_core_aggregate.erl b/apps/event_sourcing_core/src/event_sourcing_core_aggregate.erl
@@ -1,6 +1,6 @@
 -module(event_sourcing_core_aggregate).
 
--include_lib("event_sourcing_core/include/event_sourcing_core.hrl").
+-include_lib("event_sourcing_contract/include/event_sourcing.hrl").
 -include_lib("kernel/include/logger.hrl").
 
 -behaviour(gen_server).
@@ -28,7 +28,7 @@
 -define(SEQUENCE_ZERO, 0).
 -define(INACTIVITY_TIMEOUT, 5000).
 
--type aggregate_state() :: event_sourcing_core_aggregate_behaviour:aggregate_state().
+-type aggregate_state() :: event_sourcing_aggregate_behaviour:aggregate_state().
 
 -doc """
 Starts an aggregate process with a given timeout.
diff --git a/apps/event_sourcing_core/src/event_sourcing_core_mgr_aggregate.erl b/apps/event_sourcing_core/src/event_sourcing_core_mgr_aggregate.erl
@@ -10,7 +10,7 @@ monitoring them for crashes.
 
 -behaviour(gen_server).
 
--include_lib("event_sourcing_core/include/event_sourcing_core.hrl").
+-include_lib("event_sourcing_contract/include/event_sourcing.hrl").
 
 -export([
     init/1,
diff --git a/apps/event_sourcing_core/src/event_sourcing_core_mgr_behaviour.erl b/apps/event_sourcing_core/src/event_sourcing_core_mgr_behaviour.erl
@@ -9,7 +9,7 @@ for commands.
 Implementations of this behaviour are responsible for extracting routing information,
 enabling the aggregate manager to dispatch commands to the correct aggregate instance.
 """.
--include_lib("event_sourcing_core/include/event_sourcing_core.hrl").
+-include_lib("event_sourcing_contract/include/event_sourcing.hrl").
 
 -doc """
 Extracts the routing information from the command.
diff --git a/apps/event_sourcing_core/src/event_sourcing_core_store.erl b/apps/event_sourcing_core/src/event_sourcing_core_store.erl
@@ -12,7 +12,7 @@ A `store_context()` is represented as `{EventStore, SnapshotStore}`.
 Both modules may be the same if one backend implements both roles.
 """.
 
--include_lib("event_sourcing_core/include/event_sourcing_core.hrl").
+-include_lib("event_sourcing_contract/include/event_sourcing.hrl").
 
 -export([
     start/1,
@@ -41,7 +41,6 @@ Both modules may be the same if one backend implements both roles.
 ]).
 
 -export_type([
-    fold_events_opts/0,
     domain/0,
     event/0,
     event_id/0,
@@ -55,6 +54,7 @@ Both modules may be the same if one backend implements both roles.
     snapshot/0,
     snapshot_id/0,
     snapshot_data/0,
+    fold_events_opts/0,
     store_context/0
 ]).
 
@@ -145,13 +145,6 @@ retrieve_events(StoreContext, StreamId, Options) ->
         []
     ).
 
--type fold_events_opts() ::
-    #{
-        from => non_neg_integer(),
-        to => non_neg_integer() | infinity,
-        limit => pos_integer() | infinity
-    }.
-
 -doc """
 Creates a new event.
 
diff --git a/apps/event_sourcing_core/test/event_sourcing_core_store_snapshot_stub.erl b/apps/event_sourcing_core/test/event_sourcing_core_store_snapshot_stub.erl
@@ -1,6 +1,6 @@
 -module(event_sourcing_core_store_snapshot_stub).
 
--include_lib("event_sourcing_core/include/event_sourcing_core.hrl").
+-include_lib("event_sourcing_contract/include/event_sourcing.hrl").
 
 -export([start/0, stop/0, save_snapshot/1, retrieve_latest_snapshot/1]).
 
diff --git a/apps/event_sourcing_store_ets/src/event_sourcing_store_ets.erl b/apps/event_sourcing_store_ets/src/event_sourcing_store_ets.erl
@@ -3,10 +3,10 @@
 The ETS-based implementation of the event store.
 """.
 
--behaviour(event_sourcing_core_event_store).
--behaviour(event_sourcing_core_snapshot_store).
+-behaviour(event_sourcing_event_store_behaviour).
+-behaviour(event_sourcing_snapshot_store_behaviour).
 
--include_lib("event_sourcing_core/include/event_sourcing_core.hrl").
+-include_lib("event_sourcing_contract/include/event_sourcing.hrl").
 
 -export([
     start/0,
@@ -17,7 +17,9 @@ The ETS-based implementation of the event store.
     retrieve_latest_snapshot/1
 ]).
 
--export_type([event/0, stream_id/0, sequence/0, timestamp/0, snapshot/0, snapshot_data/0]).
+-export_type([
+    event/0, stream_id/0, sequence/0, timestamp/0, snapshot/0, snapshot_data/0, fold_events_opts/0
+]).
 
 -record(event_record, {
     key :: event_id(), stream_id :: stream_id(), sequence :: sequence(), event :: event()
@@ -79,7 +81,7 @@ persist_events(_, Events) ->
 
 -spec retrieve_and_fold_events(StreamId, Options, Fun, Acc0) -> Acc1 when
     StreamId :: stream_id(),
-    Options :: event_sourcing_core_store:fold_events_opts(),
+    Options :: fold_events_opts(),
     Fun :: fun((Event :: event(), AccIn) -> AccOut),
     Acc0 :: term(),
     Acc1 :: term(),
diff --git a/apps/event_sourcing_store_mnesia/src/event_sourcing_store_mnesia.erl b/apps/event_sourcing_store_mnesia/src/event_sourcing_store_mnesia.erl
@@ -3,11 +3,11 @@
 The Mnesia-based implementation of the event store.
 """.
 
--behaviour(event_sourcing_core_event_store).
--behaviour(event_sourcing_core_snapshot_store).
+-behaviour(event_sourcing_event_store_behaviour).
+-behaviour(event_sourcing_snapshot_store_behaviour).
 
 -include_lib("stdlib/include/qlc.hrl").
--include_lib("event_sourcing_core/include/event_sourcing_core.hrl").
+-include_lib("event_sourcing_contract/include/event_sourcing.hrl").
 
 -export([
     start/0,
@@ -18,7 +18,9 @@ The Mnesia-based implementation of the event store.
     retrieve_latest_snapshot/1
 ]).
 
--export_type([event/0, stream_id/0, sequence/0, timestamp/0, snapshot/0, snapshot_data/0]).
+-export_type([
+    event/0, stream_id/0, sequence/0, timestamp/0, snapshot/0, snapshot_data/0, fold_events_opts/0
+]).
 
 -record(event_record, {
     key :: event_id(), stream_id :: stream_id(), sequence :: sequence(), event :: event()
@@ -119,7 +121,7 @@ persist_events_in_tx(StreamId, [Event | Rest]) ->
 
 -spec retrieve_and_fold_events(StreamId, Options, Fun, Acc0) -> Acc1 when
     StreamId :: stream_id(),
-    Options :: event_sourcing_core_store:fold_events_opts(),
+    Options :: fold_events_opts(),
     Fun :: fun((Event :: event(), AccIn) -> AccOut),
     Acc0 :: term(),
     Acc1 :: term(),
diff --git a/apps/event_sourcing_xp/src/bank_account_aggregate.erl b/apps/event_sourcing_xp/src/bank_account_aggregate.erl
@@ -1,6 +1,6 @@
 -module(bank_account_aggregate).
 
--behaviour(event_sourcing_core_aggregate_behaviour).
+-behaviour(event_sourcing_aggregate_behaviour).
 -behaviour(event_sourcing_core_mgr_behaviour).
 
 %% Callbacks implementation
diff --git a/rebar.config b/rebar.config
@@ -3,6 +3,7 @@
 {erl_opts, [debug_info]}.
 
 {apps, [
+    event_sourcing_contract,
     event_sourcing_store_ets,
     event_sourcing_store_mnesia,
     event_sourcing_core,
@@ -17,6 +18,7 @@
 
 {relx, [
     {release, {event_sourcing_xp, "1.1.0"}, [
+        event_sourcing_contract,
         event_sourcing_core,
         event_sourcing_store_ets,
         event_sourcing_store_mnesia,
