Call on_change on Projection init (#14)

* Call on_change on Projection init

* Improve docs

lib/ecspanse/projection.ex

@@ -15,9 +15,16 @@ defmodule Ecspanse.Projection do
   `c:Ecspanse.Projection.project/1` callback. This is responsible for
   querying the state and building the projection struct.
 
+  > #### Info  {: .info}
+  > On server initialization, the `on_change/3` callback is called with the initial calculated projection as the new_projection,
+  > and the default projection struct as the previous_projection.
+  > This is executed even if the calculated projection is the same as the default one.
+  > As the `on_change/3` callback is generally used to send the projection to the client,
+  > this ensures that the client receives the initial projection.
+
   > #### Note  {: .warning}
   > The `project/2` callback runs every frame, after executing all systems.
-  > Many projections with complex queries can have a negative impact on performance.
+  > Many projections with complex queries may have a negative impact on performance.
 
   ## Options
   - `:fields` - a list with all the event struct keys and their initial values (if any)

lib/ecspanse/projection/server.ex

@@ -23,6 +23,11 @@ defmodule Ecspanse.Projection.Server do
 
     validate_projection(projection, projection_module)
 
+    # call the `on_change/3` callback upon initialization to handle the initial projection
+    if function_exported?(projection_module, :on_change, 3) do
+      apply(projection_module, :on_change, [attrs, projection, struct(projection_module)])
+    end
+
     {:ok, %{attrs: attrs, projection: projection, projection_module: projection_module}}
   end
 

test/ecspanse/projection_test.exs

@@ -78,6 +78,23 @@ defmodule Ecspanse.ProjectionTest do
   end
 
   describe "on_change/3" do
+    test "is called once when the projection server starts" do
+      entity =
+        Ecspanse.Command.spawn_entity!(
+          {Ecspanse.Entity, components: [TestComponent1, TestComponent2]}
+        )
+
+      assert_receive {:next_frame, _state}
+
+      projection_pid = TestProjection.start!(%{entity_id: entity.id, test_pid: self()})
+      assert %TestProjection{comp_1: 1, comp_2: 2} = TestProjection.get!(projection_pid)
+
+      assert_receive {:next_frame, _state}
+
+      assert_receive {:projection_updated, %TestProjection{comp_1: 1, comp_2: 2}}
+      TestProjection.stop(projection_pid)
+    end
+
     test "is called when the projection changes" do
       entity =
         Ecspanse.Command.spawn_entity!(