@spec back() :: DevJoy.Session.entry() | nil

Handles the navigation back logic based on the current history entry.

It considers the following scenarios:

1. Returns nil If the history is empty.
2. Returns nil if the current history entry is the last entry in the history and its index is 1
3. Otherwise if the index of a current history entry is 1, increments the history index and returns the previous entry.
4. Otherwise it decrements the index of the current history entry and returns this updated entry

# :ok = DevJoy.API.Storage.set_history([…])
current_entry = DevJoy.Session.History.back()
is_nil(current_entry) or is_tuple(current_entry) and tuple_size(current_entry) == 3
# => true

@spec current_entry(true) :: DevJoy.Session.entry() | nil

@spec current_entry(false) :: DevJoy.API.Storage.history_entry() | nil

Returns the current history entry.

# :ok = DevJoy.API.Storage.set_history([…])
current_entry = DevJoy.Session.History.current_entry()
is_nil(current_entry) or is_tuple(current_entry) and tuple_size(current_entry) == 3
# => true

current_entry = DevJoy.Session.History.current_entry(false)
is_nil(current_entry) or is_tuple(current_entry) and tuple_size(current_entry) == 4
# => true

@spec drop(non_neg_integer()) :: DevJoy.Session.entry() | nil

Drops the forward history entries, the current history entry and amount - 1 number of previous history entries. It returns the current history entry after dropping the specified entries, or nil if the history is empty or all entries have been dropped.

# :ok = DevJoy.API.Storage.set_history([…])
current_entry = DevJoy.Session.History.drop()
is_nil(current_entry) or is_tuple(current_entry) and tuple_size(current_entry) == 3
# => true

# :ok = DevJoy.API.Storage.set_history([…])
current_entry = DevJoy.Session.History.drop(2)
is_nil(current_entry) or is_tuple(current_entry) and tuple_size(current_entry) == 3
# => true

@spec forward() :: DevJoy.Session.entry() | nil

The forward/0 function is used to handle the navigation forward logic based on the current history entry.

It considers the following scenarios:

1. Returns nil if the current history entry's is the first in the history and its index is equal to the maximum index.
2. Otherwise if the index of a current history entry is equal to its maximum index, it decrements the index and returns the updated entry.
3. Otherwise if the index of a current history entry is less than its maximum index, it increments the index and returns the updated entry.
4. In all other cases, it returns nil.

# :ok = DevJoy.API.Storage.set_history([…])
current_entry = DevJoy.Session.History.forward()
is_nil(current_entry) or is_tuple(current_entry) and tuple_size(current_entry) == 3
# => true

@spec forwardable?() :: boolean()

Determines whether it's possible to navigate forward in the session history.

Returns false if the session history is empty. Returns true if the index of the current entry is less than the max_index or the history index is greater than 0. Returns false otheriwse.

result = DevJoy.Session.History.forwardable?()
is_boolean(result)
# => true

@spec reversible?() :: boolean()

Determines whether it's possible to navigate back in the session history.

Returns false if the session history is empty. Returns true if the index of the current entry is greater than 1 or if the current element is not the last one in the ssions history. Returns false otheriwse.

result = DevJoy.Session.History.reversible?()
is_boolean(result)
# => true

@spec update(DevJoy.Session.entry()) :: DevJoy.Session.entry()

Updates the history based on the current history entry.

If the current history entry has the same scene and part name as an existing entry, the function replaces the index of the existing entry and updates its maximum index to the maximum of the current entry's maximum index and the updated index, finally returning the updated entry.

If the current history entry has a different scene or part name, the function inserts a new history entry before the current entry and returns the new entry.

# :ok = DevJoy.API.Storage.set_history([…])
current_entry = DevJoy.Session.History.update({MyApp.MyScene, :part_name, 1})
is_tuple(current_entry) and tuple_size(current_entry) == 3
# => true