Skip to content

Latest commit

 

History

History
781 lines (603 loc) · 23.1 KB

README.md

File metadata and controls

781 lines (603 loc) · 23.1 KB
Raw

With and Without State-Shift:

state-shift let's you convert your structs and methods into type-state version, without the ugly code.

If type-state-pattern didn't sound familiar, scroll to What the hell is even Type-State-Pattern?

Say, you want to build a player, and some fields need to be set before the others. In short, a classic type-state-pattern example...

Warning

Below are the comparison codes with and without state-shift. If you don't like reading huge chunks of code like me, scroll a bit down to see the chunk by chunk comparison

Full Code Comparison:

Caution

A simple Type-State PlayerBuilder example WITHOUT state-shift:

use core::marker::PhantomData;

struct PlayerBuilder<State1 = Initial> {
    race: Option<Race>,
    level: Option<u8>,
    skill_slots: Option<u8>,
    _state: PhantomData<fn() -> State1>,
}

mod sealed {
    pub trait Sealed {}
}

pub trait TypeStateProtector: sealed::Sealed {}

struct Initial;
struct RaceSet;
struct LevelSet;
struct SkillSlotsSet;

impl sealed::Sealed for Initial {}
impl sealed::Sealed for RaceSet {}
impl sealed::Sealed for LevelSet {}
impl sealed::Sealed for SkillSlotsSet {}

impl TypeStateProtector for Initial {}
impl TypeStateProtector for RaceSet {}
impl TypeStateProtector for LevelSet {}
impl TypeStateProtector for SkillSlotsSet {}


impl PlayerBuilder<Initial> {
    fn new() -> Self {
        PlayerBuilder {
            race: None,
            level: None,
            skill_slots: None,
            _state: (PhantomData),
        }
    }


    fn set_race(self, race: Race) -> PlayerBuilder<RaceSet> {
        PlayerBuilder {
            race: Some(race),
            level: self.level,
            skill_slots: self.skill_slots,
            _state: (PhantomData),
        }
    }
}

impl PlayerBuilder<RaceSet> {
    fn set_level(self, level_modifier: u8) -> PlayerBuilder<LevelSet> {
        let level = match self.race {
            Some(Race::Orc) => level_modifier + 2, // Orc's have +2 level advantage
            Some(Race::Human) => level_modifier,   // humans are weak
            None => unreachable!("type safety ensures that `race` is initialized"),
        };

        PlayerBuilder {
            race: self.race,
            level: Some(level),
            skill_slots: self.skill_slots,
            _state: (PhantomData),
        }
    }
}

impl PlayerBuilder<LevelSet> {
    fn set_skill_slots(self, skill_slot_modifier: u8) -> PlayerBuilder<SkillSlotsSet> {
        let skill_slots = match self.race {
            Some(Race::Orc) => skill_slot_modifier,
            Some(Race::Human) => skill_slot_modifier + 1, // Human's have +1 skill slot advantage
            None => unreachable!("type safety ensures that `race` should be initialized"),
        };

        PlayerBuilder {
            race: self.race,
            level: self.level,
            skill_slots: Some(skill_slots),
            _state: (PhantomData),
        }
    }
}

impl<A> PlayerBuilder<A>
where
    A: TypeStateProtector,
{
    fn say_hi(self) -> Self {
        println!("Hi!");
        self
    }
}

impl PlayerBuilder<SkillSlotsSet> {
    fn build(self) -> Player {
        Player {
            race: self.race.expect("type safety ensures this is set"),
            level: self.level.expect("type safety ensures this is set"),
            skill_slots: self.skill_slots.expect("type safety ensures this is set"),
        }
    }
}

#[derive(Debug)]
struct Player {
    race: Race,
    level: u8,
    skill_slots: u8,
}

#[derive(Debug, PartialEq)]
enum Race {
    Orc,
    #[allow(unused)]
    Human,
}

fn main() {
    let player = PlayerBuilder::new()
        .set_race(Race::Orc)
        .set_level(1)
        .set_skill_slots(1)
        .say_hi()
        .build();
    println!("Race: {:?}", player.race);
    println!("Level: {}", player.level);
    println!("Skill slots: {}", player.skill_slots);
}




Tip

A simple Type-State PlayerBuilder example WITH state-shift:

use state_shift::{impl_state, type_state};

#[type_state(
    states = (Initial, RaceSet, LevelSet, SkillSlotsSet), // defines the available states
    slots = (Initial) // defines how many concurrent states will be there, and the initial values for these states
)]
struct PlayerBuilder {
    race: Option<Race>,
    level: Option<u8>,
    skill_slots: Option<u8>,
}

#[impl_state]
impl PlayerBuilder {
    #[require(Initial)] // require the default state for the constructor
    fn new() -> PlayerBuilder {
        PlayerBuilder {
            race: None,
            level: None,
            skill_slots: None,
        }
    }

    #[require(Initial)] // can be called only at `Initial` state.
    #[switch_to(RaceSet)] // Transitions to `RaceSet` state
    fn set_race(self, race: Race) -> PlayerBuilder {
        PlayerBuilder {
            race: Some(race),
            level: self.level,
            skill_slots: self.skill_slots,
        }
    }

    #[require(RaceSet)]
    #[switch_to(LevelSet)]
    fn set_level(self, level_modifier: u8) -> PlayerBuilder {
        let level = match self.race {
            Some(Race::Orc) => level_modifier + 2, // Orc's have +2 level advantage
            Some(Race::Human) => level_modifier,   // humans are weak
            None => unreachable!("type safety ensures that `race` is initialized"),
        };

        PlayerBuilder {
            race: self.race,
            level: Some(level),
            skill_slots: self.skill_slots,
        }
    }

    #[require(LevelSet)]
    #[switch_to(SkillSlotsSet)]
    fn set_skill_slots(self, skill_slot_modifier: u8) -> PlayerBuilder {
        let skill_slots = match self.race {
            Some(Race::Orc) => skill_slot_modifier,
            Some(Race::Human) => skill_slot_modifier + 1, // Human's have +1 skill slot advantage
            None => unreachable!("type safety ensures that `race` should be initialized"),
        };

        PlayerBuilder {
            race: self.race,
            level: self.level,
            skill_slots: Some(skill_slots),
        }
    }

    /// doesn't require any state, so this is available at any state
    #[require(A)]
    fn say_hi(self) -> Self {
        println!("Hi!");
        self
    }

    #[require(SkillSlotsSet)]
    fn build(self) -> Player {
        Player {
            race: self.race.expect("type safety ensures this is set"),
            level: self.level.expect("type safety ensures this is set"),
            skill_slots: self.skill_slots.expect("type safety ensures this is set"),
        }
    }
}

#[derive(Debug)]
struct Player {
    race: Race,
    level: u8,
    skill_slots: u8,
}

#[derive(Debug, PartialEq)]
enum Race {
    #[allow(unused)]
    Orc,
    Human,
}

fn main() {
    let player = PlayerBuilder::new()
        .set_race(Race::Orc)
        .set_level(1)
        .set_skill_slots(1)
        .say_hi()
        .build();
    println!("Race: {:?}", player.race);
    println!("Level: {}", player.level);
    println!("Skill slots: {}", player.skill_slots);
}

Let's break it down:

Consuming huge chunks of code may be overwhelming, so let's break it down.

Note

Also, let's assume that you want to track multiple states simultaneously for your struct

1. Hiding the ugly and unreadable boilerplate code required for your structs:


  • without this library, you probably have to write something like this (BAD): 
    struct PlayerBuilder<State1 = Initial, State2 = Initial, State3 = Initial>
where
    State1: TypeStateProtector,
    State2: TypeStateProtector,
    State3: TypeStateProtector,
{
    race: Option<Race>,
    level: Option<u8>,
    skill_slots: Option<u8>,
    spell_slots: Option<u8>,
    _state: (
        PhantomData<State1>,
        PhantomData<State2>,
        PhantomData<State3>,
    ),
}

Caution

The above code might suck the enjoyment out of writing Rust code.



  • with this library, you can write this (GOOD): 
    #[type_state(
    states = (Initial, RaceSet, LevelSet, SkillSlotsSet),
    slots = (Initial, Initial, Initial)
)]
struct PlayerBuilder {
    race: Option<Race>,
    level: Option<u8>,
    skill_slots: Option<u8>,
    spell_slots: Option<u8>,
}

Tip

Mmmhh! Much better, right?


2. Hiding the ugly and unreadable boilerplate code required for your impl blocks:


  • without this library, you probably have to write something like this (BAD):

    impl<B, C> PlayerBuilder<Initial, B, C>
where
    B: TypeStateProtector,
    C: TypeStateProtector,
{
    fn set_race(self, race: Race) -> PlayerBuilder<RaceSet, B, C> {
        {
            {
                PlayerBuilder {
                    race: Some(race),
                    level: self.level,
                    skill_slots: self.skill_slots,
                    spell_slots: self.spell_slots,
                    _state: (PhantomData, PhantomData, PhantomData),
                }
            }
        }
    }
}

Caution

It's not immediately obvious what's going on here, which state is required, to which state it's transitioning into, etc.



  • with this library, you can write this (GOOD): 
    #[require(Initial, B, C)]
#[switch_to(RaceSet, B, C)]
fn set_race(self, race: Race) -> PlayerBuilder {
    PlayerBuilder {
        race: Some(race),
        level: self.level,
        skill_slots: self.skill_slots,
        spell_slots: self.spell_slots,
    }
}

Tip

Immediately signals:

  • which state is required.

  • to which state it's transitioning into.

No weird generics and intermediate unit structs that hurting your brain.



3. Hiding the ugly and unreadable boilerplate code required for intermediate traits and structs:


  • without this library, in order to ensure the type-safety, you have to write traits and unit structs (BAD): 
    mod sealed {
    pub trait Sealed {}
}

pub trait TypeStateProtector: sealed::Sealed {}

pub struct Initial;
pub struct RaceSet;
pub struct LevelSet;
pub struct SkillSlotsSet;
pub struct SpellSlotsSet;

impl sealed::Sealed for Initial {}
impl sealed::Sealed for RaceSet {}
impl sealed::Sealed for LevelSet {}
impl sealed::Sealed for SkillSlotsSet {}
impl sealed::Sealed for SpellSlotsSet {}

impl TypeStateProtector for Initial {}
impl TypeStateProtector for RaceSet {}
impl TypeStateProtector for LevelSet {}
impl TypeStateProtector for SkillSlotsSet {}
impl TypeStateProtector for SpellSlotsSet {}

Caution

EWWWW



  • with this library, you can write this (GOOD): 
    #[type_state(states = (Initial, RaceSet, LevelSet, SkillSlotsSet), slots = (Initial, Initial, Initial))]
struct PlayerBuilder {
    race: Option<Race>,
    level: Option<u8>,
    skill_slots: Option<u8>,
    spell_slots: Option<u8>,
}

Tip

The necessary states that we want to use, cannot be more clear!


Tell me more

I love type-state pattern's promises:

  • compile time checks

  • better/safer auto completion suggestions by your IDE

  • no additional runtime costs

However, I agree that in order to utilize type-state pattern, the code has to become quite ugly. We are talking about less readable and maintainable code, just because of this.

Although I'm a fan, I agree usually it's not a good idea to use type-state pattern.

And THAT, my friends, bothered me...

So I wrote state-shift.

TL;DR -> it lets you convert your structs and methods into type-state version, without the ugly code. So, best of both worlds!

If you don't appreciate all the boilerplate code required by Type-State-Pattern that makes the DevX worse, but you still like the idea of type-safety provided by it, this library is for you. state-shift lets you write your code as if type-state-pattern was not there, yet grants you the benefits of type-safety.

What the hell is even Type-State-Pattern?

Here is a great blog post that explains it, I heard that the author is a good person: https://cryptical.xyz/rust/type-state-pattern

TL;DR -> instead of relying on runtime checks, Type-State-Pattern uses type-safety to enforce specific methods are only callable at specific states at compile time.

For example, you cannot call fight() method on a Player struct when it is in Dead state. You normally accomplish this by introducing boolean flags and runtime checks. With Type-State-Pattern, you achieve this without any runtime checks, purely by the type-safety provided by Rust primitives.

This is good, due to:

  • better DevX (users of the library won't be even able to call this invalid methods)
  • less runtime bugs
  • less runtime checks -> more performant code
  • zero-cost abstractions for this type checks (no additional performance cost of doing this)

Why you should care about type-state?

1. State-Focused Methods

Let’s say you have a Player struct with methods like:

  • die()
  • resurrect()

As a reasonable person, you probably don’t want someone to call die() on a player who’s already Dead.

Tip

People cannot die twice!

With this library, you can ensure that your methods respect the logical state transitions, preventing awkward situations like trying to player.die().die();

This library lets you have above mentioned type-safe methods, WITHOUT:

  • duplicating your structs (one for Dead state and one for Alive state)
  • writing runtime checks
  • hurting the performance of your code
  • making your code horrible to look at due to infamous Type-State-Pattern

In short, the users of this library won't be able to call:

Caution

let player = PlayerBuilder::new().die().die(); // ❌ Invalid!

The good thing is, after calling the first die() method, the second die() won't be even suggested by your IDE via autocomplete.

And even if you insist to type it anyway, it will be a compile-time error!

2. Field/Method Order & Dependencies

Imagine you have a PlayerBuilder struct designed to construct a Player. Some fields need to be set before others because of logical dependencies. For instance, the race field must be specified before the level field, as the race affects how we calculate the player's starting level.

Caution

So, we don't want the below code:

let player = PlayerBuilder::new().level(10) // ❌ Invalid!

Tip

We want the below code:

let player = PlayerBuilder::new().race(Race::Human).level(10) // ✅

The gist of it is, some fields of the PlayerBuilder are depending on other fields. So we want to force the users of this library to set these fields in order by making invalid orders completely unrepresentable at compile time. Even rust-analyzer won't suggest the invalid methods as auto-completion! How wonderful is that!



Additional benefits of using this Library

1. You get type-safety for your methods, with concise and clear syntax.

The macros do all the heavy lifting for you. You just need to write your code as if type-state-pattern was not there, yet grants you the benefits of type-safety.


2. Sealed-traits

this library also uses sealed-traits to ensure even more safety! And again, you don't need to worry about anything. Sealed-traits basically ensure that the user cannot implement these trait themselves. So, your structs are super-safe!


3. Clear documentation

I tried to document nearly everything. If you are curios on what the macros do under the hood, even those macros are documented! Just check the inline documentation and I'm sure you will understand what's going on in a blink of an eye!


4. Suggestions and contributions are welcome!

I'm a quite friendly guy. Don't hesitate to open an issue or a pull request if you have any suggestions or if you want to contribute! Just keep in mind that everyone contributing to here (including myself) are doing it voluntarily. So, always be respectful and appreciate other's time and effort.



Advanced & Helpful Tips

Remember, this library is just hiding the ugly type-state-pattern boilerplate code under the hood. This means, your code still have to obey some rules.

Most of the issues arise from when we are returning the Self type. The compiler doesn't like the Self keyword in type-state-pattern, because we are actually not returning the Self, but a different type. For example, it could be that our method is accepting Player<Alive> but we are returning Player<Dead>.

And you know how Rust compiler is. It is very strict about types!

Rules

1. If your method is switching states (most probably it does), avoid using Self in the return position of the method's signature:

Caution

fn my_method(self) -> Self { // `-> Self` ❌
   // redacted body
}

Tip

fn my_method(self) -> PlayerBuilder { // `-> ConcreteName` ✅
   // redacted body
}

2. Similarly, also avoid using Self in the method's body:

Caution

fn my_method(self) -> PlayerBuilder {

   Self {  // `Self {}` ❌
      race: Race::human
      level: self.level
   }
}

Tip

fn my_method(self) -> PlayerBuilder {

   PlayerBuilder {  // `PlayerBuilder {}` ✅
      race: Race::human
      level: self.level
   }
}

3. self is ok to use, but there is one exception:

Caution

fn my_method(self) -> PlayerBuilder {

   PlayerBuilder {
      race: Race::human
      ..self  // `..self` ❌
   }
}

Note

actually having ..self is not supported by the Rust compiler in this context, YET.

So hoping it will become stable in the future and we won't have to worry about it.

4. These macros appends a hidden _state field to your struct to make it compatible with type-state-pattern. If you want to opt-out of the macros for god knows why, keep in mind that you need to provide the hidden _state field for your methods.

Warning

impl PlayerBuilder {
    fn my_weird_method(&self) -> Self {
        Self {
            race: Some(Race::Human),
            level: self.level,
            skill_slots: self.skill_slots,
           _state: (::core::marker::PhantomData), // Don't forget this!
        }
    }
}

Important

You only need to worry about _state field if you want to opt-out of the macros! So, keep using the macros, and keep yourself stress free 🥂

5. Don't use the same state names across different structs

Caution

#[type_state(states = (Initial, RaceSet, LevelSet), slots = (Initial))]
struct PlayerBuilder {
    race: Option<Race>,
    level: Option<u8>,
}

#[type_state(states = (Initial, RaceSet, LevelSet), slots = (Initial))]
struct AnotherBuilder {
    race: Option<Race>,
    level: Option<u8>,
}

Tip

#[type_state(states = (Initial, RaceSet, LevelSet), slots = (Initial))]
struct PlayerBuilder {
    race: Option<Race>,
    level: Option<u8>,
}

#[type_state(states = (OpInitial, OpRaceSet, OpLevelSet), slots = (OpInitial))]
struct OpponentBuilder {
    race: Option<Race>,
    level: Option<u8>,
}

It's up to you how to do the namings, but don't use the same state names across different structs.

#[type_state] macro generates marker structs for each state. If you use the same state names, the macro will try to generate multiple marker structs with the same name, causing compile-time errors.

Tips

1. Tracking multiple states

This feature was both my favorite to implement and the most brain-melting (design-wise and implementation-wise).

The problem:

Imagine you have three fields for your struct: a, b, and c. You want c to be set only after both a and b are set. Not just one of them—both.

How do you accomplish this with type-state-pattern? This is a problem because the default design pattern allows you to have a single state to track.

One workaround is to have multiple states for the combinations of a and b. For example, you can have the following states:

  • a_set_but_b_not_set
  • b_set_but_a_not_set
  • a_set_and_b_set.

This is not a good solution due to 2 reasons:

  • it is fucking ugly
  • you need to duplicate your methods and give them different names, because you cannot have multiple methods with the same name. If this didn't make sense, take a look at the expanded codes, and you will see why we need to have the same method on different impl blocks. The compiler of course doesn't like that. The only workaround to have the same function body on different impl blocks, is to have different names for these methods. Same methods, but different names? No more explanation needed on why this is bad.

The Solution:

Multiple state slots. By allowing multiple state slots, you can track each state separately, and they won't override each other. You can see this in action in the tests/complex_example.rs. It showcases how this is done, and when can it be useful. Now, the macro for our struct should make more sense:

#[type_state(
    states = (Initial, RaceSet, LevelSet, SkillSlotsSet), // defines the available states
    slots = (Initial) // defines how many concurrent states will be there, and the initial values for these states
)]
struct PlayerBuilder {
    race: Option<Race>,
    level: Option<u8>,
    skill_slots: Option<u8>,
    spell_slots: Option<u8>,
}

2. How do I pass the player to a function (no method), does it require extra type annotations to specify the state?

Say you have this:

fn player_builder_logger(player_builder: PlayerBuilder) {
    println!("PlayerBuilder's level: {:?}", player_builder.level);
}

You can pass the player_builder without any type-annotation, but then it would expect the states to be equal to the default ones, in this case: PlayerBuilder<Initial>.

If you want to pass another state, I think you have to explicitly tell the code:

fn player_builder_logger(player_builder: PlayerBuilder<LevelSet>) {
    println!("PlayerBuilder's level: {:?}", player_builder.level);
}

Then you can call it like this:

fn main() {
        let player = PlayerBuilder::new().set_race(Race::Human).set_level(4);
        player_builder_logger(player);
}

3. Will the generics, lifetimes, and visibility of my methods and structs be preserved?

  • yes
  • yes
  • yes
  • yes
  • yes

4. Can I use async or const methods?

  • YES!

5. Can I use Result<MyStruct> or Option<MyStruct> or similar complex types in my methods?

  • you can use them in the return type!
  • you can use them in the body!
  • basically, yes!

6. I don't see require and switch_to imported in the examples. What's up with that?

require and switch_to are consumed by the impl_state macro. I don't want to dive into technical details, but basically require and switch_to need some extra info from the impl block, so impl_state macro handles all that communication. If you are curious, check out the inline docs in lib.rs.

In short, you don't need to import require and switch_to in your code.

Happy coding!