DEV Community: Isa Levine

How To Build an Event Sourcing Pattern in Rails from Scratch

Isa Levine — Sun, 03 May 2020 17:11:42 +0000

All code from this demo can be found in this GitHub repo:
https://github.com/isalevine/event-sourcing-user-app

To Recap: What is Event Sourcing?

Event Sourcing is a system design pattern that emphasizes recording changes to data via immutable events.

In other words: every time your data changes, you save an event to your database with the details.

Those events never change or go away. That way, you have a permanent, unchanging history of how your data reached its current state!

What this article covers

We will primarily be working off of Kickstarter's event sourcing example.

To create our Event pattern, we’ll take the following steps:

Get our Rails app up and running
- User model and controller
- PostgreSQL for our database
Set up our environment to test our Events
- Postico to inspect our database
- Insomnia for REST client
Add our Events pattern
- What is an Event, and what Event data will we store in the database?
- The BaseEvent that other Event classes will inherit from
- Events::User::Created
- Events::User::Destroyed

Getting our Rails app up and running

Let’s go ahead and create our new Rails app

We’ll set the database to PostgreSQL with --database=postgresql and skip tests with --skip-test, as we will be adding RSpec manually later.



rails new event-sourcing-user-app --database=postgresql --skip-test

Let’s add our `User` model

Our User model will have several fields:

name String,
email String,
password_digest String (for bcrypt)
deleted Boolean (remember, part of event sourcing is that we never delete data—instead, we will flag certain Users as being deleted, and scope our queries appropriately)
- this field also needs to be null: false, and be set to default: false

We’ll start this with Rails one-liner:



rails g model User name email password_digest deleted:boolean

And inside the new migration, tweak the t.boolean :deleted to be null: false and default: false:



# db/migrate/20200502025357_create_users.rb

class CreateUsers < ActiveRecord::Migration[6.0]
  def change
    create_table :users do |t|
      t.string :name
      t.string :email
      t.string :password_digest
      t.boolean :deleted, null: false, default: false

      t.timestamps
    end
  end
end

Add a `User` controller and routes

Our User controller needs to have two actions, a create and destroy action, to handle the Events we want to make.

Let’s create our controller manually, since we don’t need any views to be generated. In app/controllers, create a users_controller and add def create and def destroy actions:



# app/controllers/users_controller.rb

class UsersController < ApplicationController
  def create
  end

  def destroy
  end
end

Since we are not implementing auth yet, we’ll also add a skip_before_action hook to make testing our code easier:



# app/controllers/users_controller.rb

class UsersController < ApplicationController
  skip_before_action :verify_authenticity_token, only: [:create, :destroy]

  def create
  end

  def destroy
  end
end

Next, let’s manually add a POST and DELETE route that will go to the create and destroy actions in our controller:



# config/routes.rb

Rails.application.routes.draw do
  post 'users/create', to: 'users#create'
  delete 'users/destroy', to: 'users#destroy'
end

Run rails routes in your console to see that the routes are set up correctly:



[13:29:44] (master) event-sourcing-user-app
// ♥ rails routes 

Prefix           Verb     URI Pattern                 Controller#Action
users_create     POST     /users/create(.:format)     users#create
users_destroy    DELETE   /users/destroy(.:format)    users#destroy

Run database migrations

Now, let’s create our databases and run our migrations in the usual two-step:



rails db:create
rails db:migrate

Setting up our environment to test our Events

Set up Postico to view our PostgreSQL database

If you’re not familiar with Postico, it’s a a database management tool and viewer for PostgreSQL with a great free trial.

Download and install from their website, and open it up. Go ahead and hit Connect to in the localhost using its default settings:

From here, click the localhost button at the top to go to a list of available databases:

And now, we should be able to select our development database:

Select our users table:

And, hurray—there’s our User model, with its four fields:

Set up Insomnia to send HTTP requests

Likewise, if you’re not familiar with Insomnia, it’s a tool for sending HTTP requests to test RESTful APIs. We’ll be using Insomnia Core.

Download, install, and open it up:

Create a folder for our project, event-sourcing-user-app:

Let’s create our first request. We’ll make it a POST request, which we’ll user for a create User route:

And lastly, we’ll set the target URL to localhost:3000/users/create for testing later:

Yay, now Insomnia’s ready to go! We’ll just need to fill out the body of our request with a hash once we have our Events created.

Testing the `create` action with `byebug` and Insomnia

You can test out the routes by adding a byebug to the controller action:



# app/controllers/users_controller.rb

def create
  byebug
end

Fire up rails s, and send a POST request to localhost:3000/users/create in Insomnia. In your console, you will see byebug session:

Great, we can see our route working as expected!

Now, we’re ready to build our event pattern!

What is an Event?

In our event sourcing system, each Event will be a Rails model that stores information about changes to our data.

Our goal is to build two events:

Events::User::Created — this will record:
- payload: a hash containing the name, email, and password params to create the User
- user_id: the created User’s id, used in its belongs_to relationship
- event_type: a String to show that this user_event is the ”Created” type
- timestamps
Events::User::Destroyed — this will record:
- payload: a hash containing the id for the User to be flagged as deleted
- user_id: the target User’s id, used in its belongs_to relationship
- event_type: a String to show that this user_event is the ”Destroyed” type
- timestamps

When our Rails app creates or destroys a User, this will also trigger creating a new Event.

These events will be saved to our database, and will be immutable to serve as a permanent log of changes.

Since we might end up having a lot of User-related events, we’re also including the event_type field on our User events so we can store them all in one user_events table—and easily add more later!

The `Events::BaseEvent`

Our events will be built through inheritance. At the top of the chain, we will define Events::BaseEvent where a lot of the event functionality will live.

Since all of our events will be Rails models, go ahead and create a new /events directory inside app/models.

Now, we can create our BaseEvent:



# app/models/events/base_event.rb

class Events::BaseEvent < ActiveRecord::Base
end

`abstract_class`

Since the BaseEvent only exists for inheritance, we can make it an abstract_class so Rails knows not to try to load any records for it:



# app/models/events/base_event.rb

class Events::BaseEvent < ActiveRecord::Base
  self.abstract_class = true
end

`apply(aggregate)` and `apply_and_persist`

Each event will have to define its own apply method. This method will accept an aggregate—another model, in our case a User—and update its attributes.
(The term aggregate comes from the Kickstarter event sourcing system, and you can read more about it here. Basically, aggregates are models that receive changes via events.)

On BaseEvent, we’ll simply raise a NotImplementedError. This will enforce us having to define it explicitly on each event, thus overriding the error via inheritance.

The BaseEvent will also have a before_create hook that calls apply_and_persist. This will call apply, then save! the update to the database.
(It will also set the event’s aggregate_id, specifically for Created events where the id doesn’t exist until after save! is called.)

Let’s look at the code we’ll add:



# app/models/events/base_event.rb

before_create :apply_and_persist

def apply(aggregate)
  raise NotImplementedError
end

private def apply_and_persist
  # Lock the database row! (OK because we're in an ActiveRecord callback chain transaction)
  aggregate.lock! if aggregate.persisted?

  # Apply!
  self.aggregate = apply(aggregate)

  #Persist!
  aggregate.save!

  # Update aggregate_id with id from newly created User
  self.aggregate_id = aggregate.id if aggregate_id.nil?
end

`after_initialize` and `event_type`

No matter what kind of event we instantiate, there are a couple attributes we want to set right away:

event_type — every Event needs to be explicitly categorized for when it’s stored in the user_events table as a BaseEvent record
payload — since we always expect payload to be accessible as a hash (and stored in our PostgreSQL database as JSON), we’ll add a ||= operator to set it to {} if the event accepts no params

So, we’ll add an after_initialize hook to set those attributes:



# app/models/events/base_event.rb

after_initialize do
  self.event_type = event_type
  self.payload ||= {}
end

def event_type
  self.attributes["event_type"] || self.class.to_s.split("::").last
end

Above, we define event_type to quickly access its own type via attributes if loaded from our database—or upon first creation, deducing its type from the Event class’s name.

`self.payload_attributes(*attributes)`

In each Event class we create, we want the option to define possible payload_attributes we want to record.

On BaseEvent, self.payload_attributes will create the getters and setters for our payload fields:



# app/models/events/base_event.rb

def self.payload_attributes(*attributes)
  @payload_attributes ||= []

  attributes.map(&:to_s).each do |attribute|
    @payload_attributes << attribute unless @payload_attributes.include?(attribute)

    define_method attribute do
      self.payload ||= {}
      self.payload[attribute]
    end

    define_method "#{attribute}=" do |argument|
      self.payload ||= {}
      self.payload[attribute] = argument
    end
  end

  @payload_attributes
end

Ultimately, this will let us define attributes like this at the top of each new Event class: payload_attributes :name, :email, :password

`find_or_build_aggregate`

We want our events to be aware of their aggregates—in our case, the target User—and be able to either look it up, or create a new one.

We’ll add a before_validation hook (which gets called really early in the .create lifecycle) which will either look up or create the aggregate, based on whether a user_id is supplied in the event’s initializing arguments:



# app/models/events/base_event.rb

before_validation :find_or_build_aggregate

private def find_or_build_aggregate
  self.aggregate = find_aggregate if aggregate_id.present?
  self.aggregate = build_aggregate if self.aggregate.nil?
end

def find_aggregate
  klass = aggregate_name.to_s.classify.constantize
  klass.find(aggregate_id)
end

def build_aggregate
  public_send "build_#{aggregate_name}"
end

`aggregate` setters, getters, and get-its-namers

To round out our events’ functionality, we’ll want some setters and getters—as well as methods to easily return its type or class name:

aggregate=(model) and aggregate will set and get the User our event targets
aggregate_id=(id) and aggregate_id will map to the user_id field on our user_events table
self.aggregate_name gives the Event class awareness of its belongs_to relationship’s target class (#=> User)
delegate :aggregate_name, to: :class will return a Symbol of the aggregate’s class name (#=> :user)
def event_klass will convert our Event class’s ::BaseEvent namespace into its appropriate event type (#=> Events::User::Created)



# app/models/events/base_event.rb

def aggregate=(model)
  public_send "#{aggregate_name}=", model
end

def aggregate
  public_send aggregate_name
end

def aggregate_id=(id)
  public_send "#{aggregate_name}_id=", id
end

def aggregate_id
  public_send "#{aggregate_name}_id"
end

def self.aggregate_name
  inferred_aggregate = reflect_on_all_associations(:belongs_to).first
  raise "Events must belong to an aggregate" if inferred_aggregate.nil?
  inferred_aggregate.name
end

delegate :aggregate_name, to: :class

def event_klass
  klass = self.class.to_s.split("::")
  klass[-1] = event_type
  klass.join('::').constantize
end

Okay, let’s see the whole `Events::BaseEvent`!



# app/models/events/base_event.rb

# Kickstarter code reference:
# https://github.com/pcreux/event-sourcing-rails-todo-app-demo/blob/master/app/models/lib/base_event.rb

class Events::BaseEvent < ActiveRecord::Base
  before_validation :find_or_build_aggregate
  before_create :apply_and_persist

  self.abstract_class = true

  def apply(aggregate)
    raise NotImplementedError
  end

  after_initialize do
    self.event_type = event_type
    self.payload ||= {}
  end

  def self.payload_attributes(*attributes)
    @payload_attributes ||= []

    attributes.map(&:to_s).each do |attribute|
      @payload_attributes << attribute unless @payload_attributes.include?(attribute)

      define_method attribute do
        self.payload ||= {}
        self.payload[attribute]
      end

      define_method "#{attribute}=" do |argument|
        self.payload ||= {}
        self.payload[attribute] = argument
      end
    end

    @payload_attributes
  end

  private def find_or_build_aggregate
    self.aggregate = find_aggregate if aggregate_id.present?
    self.aggregate = build_aggregate if self.aggregate.nil?
  end

  def find_aggregate
    klass = aggregate_name.to_s.classify.constantize
    klass.find(aggregate_id)
  end

  def build_aggregate
    public_send "build_#{aggregate_name}"
  end

  private def apply_and_persist
    # Lock the database row! (OK because we're in an ActiveRecord callback chain transaction)
    aggregate.lock! if aggregate.persisted?

    # Apply!
    self.aggregate = apply(aggregate)

    #Persist!
    aggregate.save!
    self.aggregate_id = aggregate.id if aggregate_id.nil?
  end

  def aggregate=(model)
    public_send "#{aggregate_name}=", model
  end

  def aggregate
    public_send aggregate_name
  end

  def aggregate_id=(id)
    public_send "#{aggregate_name}_id=", id
  end

  def aggregate_id
    public_send "#{aggregate_name}_id"
  end

  def self.aggregate_name
    inferred_aggregate = reflect_on_all_associations(:belongs_to).first
    raise "Events must belong to an aggregate" if inferred_aggregate.nil?
    inferred_aggregate.name
  end

  delegate :aggregate_name, to: :class

  def event_type
    self.attributes["event_type"] || self.class.to_s.split("::").last
  end

  def event_klass
    klass = self.class.to_s.split("::")
    klass[-1] = event_type
    klass.join('::').constantize
  end

end

The `user_events` table, and the `Events::User::BaseEvent`

We previously mentioned that we will be storing multiple types of User-related events in a single user_events table.

To accomplish this and allow us to easily add more events later, we will create an Events::User::BaseEvent which will tell all events in the Events::User:: namespace to save to the user_events table. We will also define a belongs_to relationship with a User here.

`user_events` table

Let’s go ahead and create our user_events table in our database.

Kickstarter’s event sourcing example describes that each aggregate (User) has an event table (user_events). These event tables will have a similar schema—we will tweak them slightly to match our verbiage:

Each Aggregate (ex: subscriptions) has an Event table associated to it (ex: subscription_events).
…
All events related to an aggregate are stored in the same table. All events tables have a similar schema:
id, aggregate_id, type, data (json), metadata (json), created_at

A few things we’ll tweak for our code:

aggregate_id will be replaced by user_id
type will be replaced by event_type (just to be more explicit)
data will be replaced by payload, and will still be type JSON
metadata will not be included at this time, since our events are relatively simple
created_at will not be included, since we will simply rely on ActiveRecord’s default timestamps

We will create our user_events table with a Rails migration:



rails g migration CreateUserEvents

This will create our migration with a create_table block set up for us:



# db/migrate/20200502192018_create_user_events.rb

class CreateUserEvents < ActiveRecord::Migration[6.0]
  def change
    create_table :user_events do |t|
    end
  end
end

We want to add four fields:

a belongs_to relationship to a :user
an event_type String
a payload JSON
timestamps



# db/migrate/20200502192018_create_user_events.rb

class CreateUserEvents < ActiveRecord::Migration[6.0]
  def change
    create_table :user_events do |t|
      t.belongs_to :user, null: false, foreign_key: true
      t.string :event_type
      t.json :payload

      t.timestamps
    end
  end
end

Run the migration:



rails db:migrate

And open up Postico to check out the new user_events table:

Our table and fields are ready to go!

`Events::User::BaseEvent`

Inside our app/models/events directory, create a new user directory.

Inside that directory, create a new file base_event.rb. This gives us the namespacing to create this class:



# app/models/events/user/base_event.rb

class Events::User::BaseEvent < Events::BaseEvent
  self.table_name = "user_events"
end

With self.table_name = “user_events”, any new Event class we create that inherits from Events::User::BaseEvent will automatically be saved and retrieved from the user_events table!

`belongs_to :user` and `has_many :events`

Since all our User-related events target a User, it makes sense to create a has_many / belongs_to relationship between Users and Events in the Events::User:: namespace.

Since we’re deep in a namespace that uses the name User, to tell Rails to look for the regular top-level User model, we need to add :: before our classnames. This tells our has_many and belongs_to relationships to look outside the current namespace.

Let’s update our Events::User::BaseEvent and User classes with the relationships:



# app/models/events/user/base_event.rb

class Events::User::BaseEvent < Events::BaseEvent
  self.table_name = "user_events"

  belongs_to :user, class_name: "::User"
end


# app/models/user.rb

class User < ApplicationRecord
  has_many :events, class_name: "Events::User::BaseEvent" 
end

Great! Now, when we load a User into a user variable, we can call user.events to load all related events from the user_events table.

We’re now ready to create some real, usable Events!

Creating a new User with `Events::User::Created`

With our BaseEvent pattern in place, we can now build our first event!

Events::User::Created will record the params used to create a User, as well as the new User’s id, and the event’s timestamp.

Build the `Events::User::Created` class

In app/models/events/user, make a new created.rb file. Our class will inherit from Events::User::BaseEvent in the same directory:



# app/models/events/user/created.rb

class Events::User::Created < Events::User::BaseEvent
end

As we defined in the top-level Events::BaseEvent, we must define an apply method that will take a User instance as its aggregate argument:



# app/models/events/user/created.rb

class Events::User::Created < Events::User::BaseEvent
  def apply(user)
  end
end

Since we know creating a User requires params with a name, email, and password, we can also add them as a list of symbols to payload_attributes to create our getters and setters:



# app/models/events/user/created.rb

class Events::User::Created < Events::User::BaseEvent
  payload_attributes :name, :email, :password

  def apply(user)
  end
end

Add logic to the `apply` method

The logic in the event’s apply method is where the event’s power lies. It:

takes in a User instance
applies the changes to the User instance, supplied by payload_attributes
returns the mutated User instance => this is where the top-level BaseEvent receives back the User instance, and calls save! to persist the changes in the database!

Thanks to the list of attributes passed to payload_attributes, we can simply call the attributes inside our apply method to update the User instance:



# app/models/events/user/created.rb

payload_attributes :name, :email, :password

def apply(user)
  user.name = name
  user.email = email
  user.password_digest = password

  user
end

Perfect! Now, all we need to do is tell Insomnia to pass params that contain name, email, and password Strings, and our event will map them to the User model’s name, email, and password_digest fields.
(Remember: password_digest is related to bcrypt functionality, which we will explore in another article.)

Update our controller to create an Event and use strong params

Back in our users_controller, we need to update two things:

the create action needs to call Events::User::Created.create(payload: user_params)
add strong params to protect the user_params we will pass to .create(payload: user_params)

For the strong params, we will require the user_params to have name, email, and password nested inside a user key:



# app/controllers/users_controller.rb

private def user_params
  params.require(:user).permit(:name, :email, :password)
end

Now, we can safely pass user_params to Events::User::Created.create(payload: user_params) in the create action:



# app/controllers/users_controller.rb

def create
  Events::User::Created.create(payload: user_params)
end

private def user_params
  params.require(:user).permit(:name, :email, :password)
end

Let’s test our event with Insomnia and Postico!

If we send the correct params via a POST request to localhost:3000/users/create, we expect several behaviors:

a new record in the user_events table, with:
- event_type “Created”
- payload with the user_params
  - note that the password will be stored as plaintext => this is UNSAFE BEHAVIOR, and is because we have not implemented bcrypt encryption yet!
- user_id with the newly-created User’s id
a new record in the user table, with:
- correct name
- correct email
- password_digest that is the plaintext password => this is UNSAFE BEHAVIOR, and is because we have not implemented bcrypt encryption yet!

Let’s test it out!

Fire up rails s, and open up Insomnia.

In our Create User request, set the Body to JSON:

Then, create a JSON hash with a ”user” key, which points to a hash containing a ”name”, ”email”, and ”password”:

Now hit Send, and let’s check out our database tables!

First, let’s see if we have an event in our user_events table:

So far, so good!
(Remember: storing passwords as plaintext is UNSAFE BEHAVIOR, and is because we have not implemented bcrypt encryption yet!)

Now, let’s check out the users table:

Terrific! We now have our new User, ongo_gablogian, and a record of the Event and params that created him!

There you have it! Our event sourcing system is now capturing changes to our data!

As long as we never alter the data in the user_events table, we have a reliable log of how our data got to its current state!

Destroying a User with `Events::User::Destroyed`

Now that we have our pattern in place, it’s very straightforward to create a new Event and record it to our user_events table!

Since we never want to destroy our data, we implemented a boolean deleted field on the User model. When a new User is created, it defaults to false.

Let’s create a new event, Events::User::Destroyed, that will set the deleted field to true!

Create an `app/models/events/user/destroyed.rb` file

In the same directory as our Events::User::Created class, create an equivalent Events::User::Destroyed class:



# app/models/events/user/destroyed.rb

class Events::User::Destroyed < Events::User::BaseEvent
  def apply(user)
    user
  end
end

Above, we start with an apply method that simply returns the passed-in User instance.

To delete a User, we’ll simply require an id. Let’s add the payload_attributes for it:



# app/models/events/user/destroyed.rb

class Events::User::Destroyed < Events::User::BaseEvent
  payload_attributes :id
end

And we’ll make our apply method update the passed-in User’s deleted field to true:



# app/models/events/user/destroyed.rb

class Events::User::Destroyed < Events::User::BaseEvent
  payload_attributes :id

  def apply(user)
    user.deleted = true

    user
  end
end

That’s it—our new Event is done!

Update the `destroy` action in `users_controller`

In our users_controller, we’ll make our destroy action simply create our new Events::User::Destroyed event.

Thanks to the find_or_build_aggregate and aggregate_id methods defined in our top-level BaseEvent, this ”Destroyed” event will look up a User automatically if a user_id argument is supplied.

First, let’s add id to the list of strong params in user_params:



# app/controllers/users_controller.rb

private def user_params
  params.require(:user).permit(:name, :email, :password, :id)
end

Now, our controller’s destroy action can accept a user_params that has the necessary id. We’ll also use user_params[:id] so the event can look up our target User’s record:



# app/controllers/users_controller.rb

def destroy
  Events::User::Destroyed.create(user_id: user_params[:id], payload: user_params)
end

We’re ready to go ahead and test with Insomnia!

Test a DELETE request in Insomnia

Let’s fire up rails s.

Over in Insomnia, create a new request called Destroy User and make it a DELETE:

Set its target URL to localhost:3000/users/destroy:

Set the Body type to JSON, and add a hash with a ”user” key pointing to a hash containing the ”id”:

Hit Send, and check the database to see if the Event was created:

And finally, let’s check the database to see if our User has deleted set to true:

Perfect! We get to keep our User record, but also have it be deleted—we’re having our cake, and eating it too!

And that's no lie!

That’s all it takes to add a new event to our event sourcing system!

Conclusion

Wow, we covered a lot of ground! Let’s recap the steps we took to implement our event sourcing system:

Create a new Rails app, with a User model and controller, and PostgreSQL for the database
Create an Events::BaseEvent class in app/models/events to handle Event logic:
- Looking up or creating aggregates (Users)
- Creating getters and setters for payload_attributes
- Inferring its own event_type
- Hooks for automatically applying changes and saving to the database
Create a user_events table migration
Create an Events::User::BaseEvent to save all Events in its Events::User:: namespace to the user_events table
Create an Events::User::Created event that will apply user_params to a new User instance
Create an Events::User::Destroyed event that will look up at User by id and set its deleted field to true

This minimal system allows us to do the following:

Have a record of events that create and destroy Users
Keep all User data permanently, and still have the ability to scope the deleted ones as needed
A pattern that allows us to easily add new Events that will be saved to the same user_events table

All code from this demo can be found in this GitHub repo:
https://github.com/isalevine/event-sourcing-user-app

Next Up

We have a lot more we can do to improve our event sourcing system, especially around security and data validations! In the next article, we will cover:

Storing sensitive information safely in Event payloads, such as passwords
Wrapping creating Events in Commands, per Kickstarter’s example
Adding validations to Commands

References

Special thanks to Philippe Creux and Kickstarter for sharing their Event Sourcing example.

Thanks to Martin Fowler for his important writings on Event Sourcing.

Thanks to Arkency for their great work with the RailsEventStore library.

And finally, thanks to fellow Dev.to user Alfredo Motta for sharing about this years ago (and keeping it up for me to catch up on!).

Building an Event Sourcing System in Rails, Part 1: What is Event Sourcing?

Isa Levine — Mon, 20 Apr 2020 00:54:35 +0000

What is Event Sourcing?

Event Sourcing is a system design pattern that emphasizes recording changes to data via immutable events.

In other words: every time your data changes, you save an event to your database with the details.

Those events never change or go away. That way, you have a permanent, unchanging history of how your data reached its current state!

Martin Fowler’s important 2005 essay describes Event Sourcing this way (emphasis mine):

Event Sourcing ensures that all changes to application state are stored as a sequence of events. Not just can we query these events, we can also use the event log to reconstruct past states, and as a foundation to automatically adjust the state to cope with retroactive changes.
…
The fundamental idea of Event Sourcing is that of ensuring every change to the state of an application is captured in an event object, and that these event objects are themselves stored in the sequence they were applied for the same lifetime as the application state itself.

Cool! From this, we get a few key points about Event Sourcing systems that we’ll explore:

Changes to data are stored as Event objects
The Events have a fixed chronological order that can be “replayed”
The Events cannot be changed or deleted (for as long as they might be needed)

Examples of Event Sourcing

The example app we will be building in these articles will focus on events related to creating and destroying a User model. Consider this situation:

Client sends a request to create a User
Server receives the request
Server creates and saves a User
Server creates and saves an Event, which records the details of the request and the created User

Obviously, the implementation (and order of operations) will be more complex--but at its core, that's the basic Event Sourcing system we'll be creating!

In a 2017 essay, Martin Fowler points out that version-control systems (like Git) are probably the most common example of Event Sourcing that programmers encounter (emphasis mine):

The core idea of event sourcing is that whenever we make a change to the state of a system, we record that state change as an event, and we can confidently rebuild the system state by reprocessing the events at any time in the future. The event store becomes the principal source of truth, and the system state is purely derived from it. For programmers, the best example of this is a version-control system. The log of all the commits is the event store and the working copy of the source tree is the system state.

For Rails-specific Event Sourcing, two resources/examples are often cited:

The focus of these articles will be on following Kickstarter’s example as I create a personal project with event sourcing architecture. Thanks Kickstarter, you folks are amazing!

Some implications of using an Event Sourcing system

Since working on an event sourcing system at my previous job, I’ve been building a personal project using one too. The key difference is that, at work, I was expanding on an already-existing system (and one that wasn’t initially designed for event sourcing).

Now that I’m building one from scratch, I’ve encountered some important considerations:

Data is truly immutable—forget about using ActiveRecord.destroy! Instead, it’s important to design data for permanence, such as including a deleted field on User models.
Recording payload dumps of event data can include potentially storing sensitive data in an unsafe format if the event is saved outside of auth features like has_secure_password—you must be extra cautious about when sensitive data might be exposed, and be ready to manually implement encryption where needed!
Since events become “the principal source of truth” (in Martin Fowler’s words), tons of logic ends up being wrapped in Event objects—naming and organizing code (and making sure it’s future-proof) is more essential than ever! As Philippe Creux at Kickstarter described (emphasis not mine):

Naming is hard. And there are so many immutable events and attributes to name. The names you choose now will be the ones stored forever. So take a good dictionary and make sure that you nail down names that are explicit and future-proof.

I hope to explore and share these implications (and future ones that will surely arise!) in these articles, as we walk through how to implement an Event Sourcing system from scratch.

Next Up

The next article will go through the basics of creating a Rails app, centered around creating and destroying a User model, that uses basic Event Sourcing architecture. We will cover:

Setting up the Rails app with a User model and controller
Building the BaseEvent class architecture (per Kickstarter’s example)
Implementing Events::User::Created and Events::User::Destroyed event classes

References

Special thanks to Philippe Creux and Kickstarter for sharing their Event Sourcing example.

Thanks to Martin Fowler for his important writings on Event Sourcing.

Thanks to Arkency for their great work with the RailsEventStore library.

And finally, thanks to fellow Dev.to user Alfredo Motta for sharing about this years ago (and keeping it up for me to catch up on!).

Hi Folks, Good to be Back!

Isa Levine — Sun, 12 Apr 2020 21:26:06 +0000

Hi, Dev.to folks! Hope you’ve all been well and are staying safe!

I wanted to do an update/retrospective after my first few months of working at my first software engineering job…but a little while ago, it was part of the big wave of COVID-related layoffs.

Luckily, I learned a HUGE amount during my 2 1/2 months there, so I’m here to share and explore those lessons!

There are three things I plan to write about:

I learned a lot of patterns and techniques for working with Rails and Vue—and I’m currently starting a project, QueerHub, to re-implement them on my own, entirely from scratch!
Both last year and this year, I’ve accumulated some jobhunting advice, much of which comes from answering questions from other coding bootcamp graduates—I want to share my strategies, especially with respect to navigating mental health issues, queerness, and the current US quarantine
One of the reasons I love Dev.to is that it’s a place to be my whole-ass queer self—I’m here to share my perspective as a queer trans woman, and ways to be a better ally to people like me while at work, while networking, and in general!

Good to be back, everyone—glad you’re all here, and looking forward to catching up! (And picking up some new video game and/or trashy TV recommendations to keep me sane!)

Accurate representation of how much I want to hug right now. <3

What Happened to Video Games Having In-Game CLI Consoles?

Isa Levine — Sun, 15 Dec 2019 23:34:02 +0000

Console command cheats being used in Skyrim

Okay, sorry for the clickbait-y title...I know in-game consoles were never really common per se, and I'm writing this because of I've been relying on the console to fix bugs in Skyrim...

But still, the question stands: why don't we see in-game consoles more frequently in video games today?

My PC version of Skyrim has always been broken and buggy. Having played the same installed version on the same machine since college, it's become more and more unstable as time has gone on, hardware's been upgraded or replaced, and the computer itself has been (less than carefully) moved across the country.

Recently, I booted it up again to (finally) do a playthrough as a mage. Upon killing the first dragon, I uncovered a new and amazing bug: I can no longer absorb dragon souls.

Luckily, this is a rather common bug, and the easiest solution is to simply enter the game's console and use the command setstage MQ104 90 to mark the quest as complete. As I defeat other dragons, I have to artificially increase my dragon soul count by 1 using player.modav dragonsouls 1.

Let's learn a bit about what these consoles are, and where they originate!

To save you some time with trying to google "video game console" without the interference of console machines (PS4, Xbox One, Switch, etc.), here's the Wikipedia article on console (video game CLI).

Popular drop-down console box started with Quake (1996), for logs and cheats

The most recognizable in-game console is likely traceable to Quake (1996), the popular first-person shooter and successor to Doom.

Activated by either ~ (tilde) or ` (grave), the console was a box that dropped down from the top of the screen.

It displayed both logs for engine events (sound, joysticks, etc.), as well as in-game events (picking up items):

Console event log in Quake

In addition, the Quake console also included codes you could enter for both regular in-game commands, and cheats--here's a list of Quake console commands.

I personally first encountered Quake's console with noclip, a command to allow walking through walls and flying, and god, the god-mode (invincibility) cheat. These still commonly appear in games that have their own in-game consoles!

Why aren't consoles like Quake's more common in video games today?

One important thing to know about in-game consoles (like Quake's above) is that they are NOT windows into the engine's processes, nor the game's source code. It's easy to look at a console like this and assume that you're pausing the game's engine and directly accessing/modifying the code that's currently running. Nope.

You are not hacking the game's source code by using the in-game console--and this is why not every game has its own console.

Instead, an in-game console is an additional CLI built into the game that offers a specific set of commands for that game's console alone. While some game engines may have a set of common commands, their effects are game-specific, and they must be created by developers.

So, long-story short: most video games don't have an in-game console because they're a lot of extra effort for developers to make!

Modern example

Luckily, the in-game console lives on in some modern (and very popular) game engines.

Each of the games in these series/with these engines will usually have an in-game console, with varying numbers of commands:

Bethesda's Creation engine (Skyrim, Fallout) - list of Skyrim console commands
Valve's Source/GoldSrc engine (Counter-Strike, Half-Life) - list of console commands common to all Source engine games
Epic's Unreal engine (BioShock, Borderlands) - list of console commands for Unreal Engine 3 games and editor

Lots of articles are popping up lately about replaying some of these games using console commands/cheats, so now is a great time to dive in and explore the possibilities!

Note: Depending on the game, you may have to enable use of the in-game console (for example, with Steam games, running them with the -console flag), or by otherwise making it available. Just be prepared to do some Googling on the specific game!

Note (also): Some console (non-PC/Mac) versions of video games do NOT have an in-game console, usually due to complications of accessing it without a keyboard.

Cheats being activated in Half-Life via the Steam in-game console

Links and sources

Image sources:

Skyrim - found via Google images, direct link currently not working
Quake
Half-Life

Got any pieces of in-game console history (or favorite cheats) to share? Please comment below! <3

Intro to RSpec in Rails (part 2): Improving Tests with `let` and `context`

Isa Levine — Sun, 08 Dec 2019 19:40:22 +0000

In our last post, we started to write some RSpec tests for our character-generator API, and its RandomCharacterGenerator service class.

Dev.to community member Andrew Brown pointed out that several aspects of our code were not written optimally, so let's take a look at a few of his recommendations!

Use `let` to wrap your testing variables

In our original test code, we simply created our testing variables inside our describe block. This is not correct--instead, we are expected to wrap this code in either a before or let block. Both of these will help RSpec understand when to create the variables, and help our tests run correctly.

Here's the original test code we wrote (with a few omissions for readability):

# /spec/services/random_character_generator_spec.rb

require 'rails_helper'

RSpec.describe RandomCharacterGenerator do

    describe "#new_character" do
        # NOTE: Do NOT create your test variables this way!!
        rcg = RandomCharacterGenerator.new
        player = Player.create(user_name: "Ronald McDonald", display_name: "Mac")
        character = rcg.new_character("Ronnie the Rat", player)


        it "creates a new Character instance" do
            expect(character).to be_an_instance_of Character
        end

        # For now, we'll ignore the other tests we wrote...
    end
end

So, we need to do something about where we create those starting_database_count, rcg, player, and character variables!

`before` or `let`

We have two options for wrapping our variable-creation: before or let blocks.

before is a hook that will run before each test (by default), and thus may be run multiple times when we don't need it to.
let is only called when a test needs the variable it creates.

So, we could rewrite our code two different ways:

# /spec/services/random_character_generator_spec.rb

    describe "#new_character" do

        # OPTION 1 (run before each test):
        before do
            rcg = RandomCharacterGenerator.new
            player = Player.create(user_name: "Ronald McDonald", display_name: "Mac")
            character = rcg.new_character("Ronnie the Rat", player)
        end

        # OPTION 2 (run only when variables are called in a test):
        let(:player)    { Player.create(user_name: "Ronald McDonald", display_name: "Mac") }
        let(:character) {
            rcg = RandomCharacterGenerator.new
            rcg.new_character("Ronnie the Rat", player)
        }

    end

One resource Andrew pointed me to is BetterSpecs, an excellent list of guidelines for writing more standardized/readable/maintainable/side-effect-less RSpec tests. Here's what BetterSpecs says about the let block:

When you have to assign a variable instead of using a before block to create an instance variable, use let. Using let the variable lazy loads only when it is used the first time in the test and get cached until that specific test is finished. A really good and deep description of what let does can be found in this stackoverflow answer.

So, let is the preferred alternative to a before block. Both of these are methods we can wrap around creating our testing variables. But let is preferred because it runs more efficiently (and, as Andrew pointed out, has fewer side effects).

Sidenote from BetterSpecs -- this is how they describe `let` working under-the-hood:

# this:
let(:foo) { Foo.new }

# is very nearly equivalent to this:
def foo
  @foo ||= Foo.new
end

So, let prevents us from re-instantiating classes over and over! Definitely more efficient.

Let's go ahead and update our code with `let`, and run the test:

# /spec/services/random_character_generator_spec.rb

require 'rails_helper'

RSpec.describe RandomCharacterGenerator do

    describe "#new_character" do
        let(:player)    { Player.create(user_name: "Ronald McDonald", display_name: "Mac") }
        let(:character) {
            rcg = RandomCharacterGenerator.new
            rcg.new_character("Ronnie the Rat", player)
        }

        it "creates a new Character instance" do
            expect(character).to be_an_instance_of Character
        end  
    end
end

And run bundle exec rspec:

$ bundle exec rspec
.

Finished in 0.04259 seconds (files took 0.78975 seconds to load)
1 example, 0 failures

Awesome! Our test is still working (and passing) as expected.

Using `context` for different cases

Both Andrew and BetterSpecs recommend using context to organize tests.

context is an alias for describe, so there is no under-the-hood different. context exists solely to make tests more understandable to developers.

One common way to implement context is to use them for different cases, such as "success" and "failure".

Use case: `context "success"` and `context "failure"`

Let's add some contexts to our tests to reflect when the new_character method succeeds or fails, based on the uniqueness of our character's name (a validation which is NOT implemented on the Character model yet):

# /spec/services/random_character_generator_spec.rb

describe "#new_character" do
            let(:rcg)       { RandomCharacterGenerator.new }
            let(:player)    { Player.create(user_name: "Ronald McDonald", display_name: "Mac") }
            let(:character) { rcg.new_character("Ronnie the Rat", player) }

        context "success" do    
            it "creates a new Character instance" do
                expect(character).to be_an_instance_of Character
            end
        end

        context "failure (non-unique name)" do
            # test code here
        end
    end

Now, let's make a duplicate variable by trying to create a new Character with the same name as our first character. In our test, we'll also expect that duplicate is equal to an error message string:

# /spec/services/random_character_generator_spec.rb

    describe "#new_character" do
            let(:rcg)       { RandomCharacterGenerator.new }
            let(:player)    { Player.create(user_name: "Ronald McDonald", display_name: "Mac") }
            let(:character) { rcg.new_character("Ronnie the Rat", player) }
            let(:duplicate) { rcg.new_character("Ronnie the Rat", player) }

        context "success" do    
            it "creates a new Character instance" do
                expect(character).to be_an_instance_of Character
            end
        end

        context "failure (non-unique name)" do
            it "returns a message that Character is not created" do
                expect(character).to be_an_instance_of Character
                expect(duplicate).to eq "Character not created -- name already exists!"
            end
        end
    end

Now, our context "failure (non-unique name)" has an it block that instantiates character again (remember, the let variables don't exist until we call them in a test!), and tries to create duplicate with the same name. Instead of being a Character, duplicate should equal a string containing our error message.

Let's run our tests to make sure they work, and are not passing:

$ bundle exec rspec
.F

Failures:

  1) RandomCharacterGenerator#new_character failure does not create a new Character instance
     Failure/Error: expect(duplicate).to eq "Character not created -- name already exists!"

       expected: "Character not created -- name already exists!"
            got: #<Character id: 2, name: "Ronnie the Rat", strength: 2, dexterity: 3, intelligence: 3, charisma: 1, created_at: "2019-12-08 19:05:55", updated_at: "2019-12-08 19:05:55", player_id: 1>

       (compared using ==)

       Diff:
       @@ -1,2 +1,11 @@
       -"Character not created -- name already exists!"
       +#<Character:0x00007f9e56d37880
       + id: 2,
       + name: "Ronnie the Rat",
       + strength: 2,
       + dexterity: 3,
       + intelligence: 3,
       + charisma: 1,
       + created_at: Sun, 08 Dec 2019 19:05:55 UTC +00:00,
       + updated_at: Sun, 08 Dec 2019 19:05:55 UTC +00:00,
       + player_id: 1>

     # ./spec/services/random_character_generator_spec.rb:63:in `block (4 levels) in <top (required)>'

Finished in 0.1283 seconds (files took 1.76 seconds to load)
2 examples, 1 failure

Failed examples:

rspec ./spec/services/random_character_generator_spec.rb:61 # RandomCharacterGenerator#new_character failure does not create a new Character instance

Perfect--our test works, and is failing because duplicate is being created as a Character instance, instead of the error-message string we were expecting.

Let's add a uniqueness validation for `:name` to our Character model:

# /app/models/character.rb

class Character < ApplicationRecord
    belongs_to :player

    validates :name, uniqueness: true
end

And in `RandomCharacterGenerator.new_character()`, let's add a `rescue` that returns our error-message string:

# /app/services/random_character_generator.rb

class RandomCharacterGenerator

    def new_character(name, player)
        Character.new(name: name, player: player).tap do |character|
            roll_stats(character, @stats_array, @points_pool, @max_roll)
            character.save!
        end
    rescue ActiveRecord::RecordInvalid
        return "Character not created -- name already exists!"
    end

end

Running our tests now:

$ bundle exec rspec
..

Finished in 0.07993 seconds (files took 1.86 seconds to load)
2 examples, 0 failures

Awesome, now our new_character method has some better error-handling built in, and it's backed up by test coverage!

Using `it { expect }` syntax with `context`

One final suggestion from both Andrew and the BetterSpecs section on keeping descrptions short is to simplify the it block's syntax with curly brackets {} around the expect statement.

When used inside a context block, it can make the test much more expressive and readable:

# /spec/services/random_character_generator_spec.rb

    describe "#new_character" do
        let(:rcg)       { RandomCharacterGenerator.new }
        let(:player)    { Player.create(user_name: "Ronald McDonald", display_name: "Mac") }
        let(:character) { rcg.new_character("Ronnie the Rat", player) }
        let(:duplicate) { rcg.new_character("Ronnie the Rat", player) }

        # BEFORE:
        context "success" do    
            it "creates a new Character instance" do
                expect(character).to be_an_instance_of Character
            end
        end

        # AFTER:
        context "success" do    
            it { expect(character).to be_an_instance_of Character }
        end
    end

The second version reduces our it block from three lines to one, and completely eliminates the descriptive (and possibly redundant) text "creates a new Character instance". Instead, we can read the test as "the 'success' context expects variable character to be an instance of Character". Pretty self-descriptive code!

However, this strategy is best used for one-expectation tests. Our "failure (non-unique name)" test currently relies on two `expect` lines inside the same `it` block, so this would NOT work:

# /spec/services/random_character_generator_spec.rb

    describe "#new_character" do
        let(:rcg)       { RandomCharacterGenerator.new }
        let(:player)    { Player.create(user_name: "Ronald McDonald", display_name: "Mac") }
        let(:character) { rcg.new_character("Ronnie the Rat", player) }
        let(:duplicate) { rcg.new_character("Ronnie the Rat", player) }

        # this works:
        context "failure (non-unique name)" do
            it "returns a message that Character is not created" do
                expect(character).to be_an_instance_of Character
                expect(duplicate).to eq "Character not created -- name already exists!"
            end
        end

        # this does NOT work:
        context "failure (non-unique name)" do
            it { expect(character).to be_an_instance_of Character }
            it { expect(duplicate).to eq "Character not created -- name already exists!"}
        end
    end

The second option does not work because each it line creates its own scope, so duplicate is created as a Character successfully because the previous character is not instantiated in duplicate's scope.

So, our final successful test code looks like this:

# /spec/services/random_character_generator_spec.rb

require 'rails_helper'

RSpec.describe RandomCharacterGenerator do

    describe "#new_character" do
        let(:rcg)       { RandomCharacterGenerator.new }
        let(:player)    { Player.create(user_name: "Ronald McDonald", display_name: "Mac") }
        let(:character) { rcg.new_character("Ronnie the Rat", player) }
        let(:duplicate) { rcg.new_character("Ronnie the Rat", player) }

        context "success" do    
            it { expect(character).to be_an_instance_of Character}
        end

        context "failure (non-unique name)" do
            it "returns a message that Character is not created" do
                expect(character).to be_an_instance_of Character
                expect(duplicate).to eq "Character not created -- name already exists!"
            end
        end 
    end
end

Conclusion

As we've covered, using let to create your testing variables and context to wrap your test cases can improve both the readability and the efficiency of your RSpec tests. We've also seen one way to simplify it blocks down to a single line if there's a single expectation!

Thanks to Andrew Brown for his incredibly helpful comment on my previous post!

Additional thanks to Masaki Matsuo and Amy Pivo for helping me practice writing better RSpec tests this week!

Intro to RSpec in Rails (part 1): Basic Syntax and Strategy for Testing

Isa Levine — Sun, 01 Dec 2019 17:00:46 +0000

While working on the character-generator API from my last post, I found myself writing most of my code in the RandomCharacterGenerator service object. As the class got more complicated, I realized that I had a very clear idea of the expected behavior--so this was a perfect opportunity to practice writing RSpec tests for those behaviors!

RSpec is a behavior-driven development (BDD) testing tool for Ruby, and is widely used for testing both plain ol' Ruby and full-on Rails applications. I'm writing this as an intro to some basic patterns and syntax used in RSpec Rails testing, as well as some basic BDD strategy for breaking down code into testable units.

Behavior-Driven Development (BDD)

It's hard to understand RSpec without having some idea about behavior-driven development (BDD), so let's start there!

BDD is a testing philosophy that grew out of test-driven development (TDD). Essentially, the goal of both is: write tests first, then write code to make the tests pass!

The idea behind this is that being able to identify and articulate the behaviors you want to test should help guide you when writing the code itself:

If you know what behavior you need to see, you can write tests for it
If you write tests for it, you will know when your code is doing that behavior correctly
If you know when your code is doing that behavior correctly, you can:
- write as little code as possible (to get the test to pass)
- refactor with the confidence that the tests will tell you if the behavior is not working anymore

Applying this to Rails (or Ruby more broadly, or object-oriented programming languages in general), these are the main steps we will use:
1. Decide on the class/method/behavior to test
2. Write tests for that class/method/behavior
3. Write code to make the tests pass
4. When refactoring your code, make sure the tests still pass

RSpec

Adding RSpec to a new or existing Rails app

This is an excellent StackOverflow discussion for both starting a new Rails app with RSpec, and migrating an existing Rails app to RSpec (from test-unit, the default Rails test tool). The following instructions are pulled from the thread's answers.

Starting a new Rails app with no test tool, and adding RSpec

Per user Zabba:

at command line:

rails new MYAPP -T # The -T option tells rails not to include Test::Unit

in Gemfile:

gem 'rspec-rails'

at command line:

bundle install
rails g rspec:install

Migrate an existing Rails app with default `test-unit` to RSpec

Per user Sayuj:
NOTE: This does include deleting all existing files in test-unit's directory! Make sure to back up or migrate any existing tests before following these steps!!

Create your new rails application as:

rails new <app_name> -T

Or remove your test directory from your existing application:

rm -rf test/

Make an entry in your Gemfile:

gem 'rspec-rails'

From the command line install the gem

$ bundle install

From the command line install rspec into your application:

$ rails g rspec:install

Now your rails application uses RSpec instead of test-unit.

Running RSpec tests

To run all RSpec tests in your Rails project, use this console command:

bundle exec rspec

Per StackOverflow user apneadiving, you can also run individual tests by specifying the filepath and line number:

bundle exec rspec ./spec/controllers/groups_controller_spec.rb:42

RSpec building blocks: `describe` and `it`

In RSpec, the main building blocks for test suites are describe (for grouping) and it (for tests). We write both of them as do...end blocks, where we do things like instantiate classes, set variables, and write individual tests.

Here's the first test from random_character_generator_spec.rb:

# /spec/services/random_character_generator_spec.rb

RSpec.describe RandomCharacterGenerator do
    describe "#new_character" do
        # NOTE: Do NOT create your test variables this way!! (See comments for why.) This is just an example for readability...
        rcg = RandomCharacterGenerator.new
        player = Player.create(user_name: "Ronald McDonald", display_name: "Mac")
        character = rcg.new_character("Ronnie the Rat", player)

        it "creates a new Character instance" do
            expect(character).to be_an_instance_of Character
        end

    end
end

Let's walk through this:

At the top, we have RSpec.describe <ClassName> do. This encapsulates our tests for the RandomCharacterGenerator service object class.
Underneath, we have describe "#method_name" do. This encapsulates our tests for the new_character method. It is a Rails convention to add # before this--that way, the test output will read RandomCharacterGenerator#new_character, which helps us know what we're testing.
Inside that describe block for our method, we instantiate a couple objects to test, and run the new_character method so we can assign its output to the variable character. This will give us all the objects we need to test the method's behavior. (NOTE: This is NOT the right way to instantiate variables in an RSpec test! It is here only for an introductory example. See this excellent comment from Andrew Brown [and the next post in this series] to see why and learn the proper alternatives!)
Finally, we have an it "description of expected behavior" do block. This is where we write the test code logic! In a very expressive style, we see that the test itself expects the variable character to be an instance of the class Character. If this line evaluates to True, our test will pass--otherwise, it will fail!

Setting clear `expect`ations

As we saw above, RSpec provides an expressive domain-specific language (DSL) to write our tests with. The idea here is that methods can be chained together in a way that sounds very close to plain English. The code expect(character).to be_an_instance_of Character almost reads like a real sentence!

The most important syntax is expect(foo).to, because this creates the test itself! It's also important because we must know what one specific thing we're testing (foo) in order to write the test.

Here are some common syntax options, all sourced from the excellent resource RSpec Cheatsheet by @rstacruz:

Equal value (or not)

expect(target).to eq 1
expect(target).not_to eq 1

Math comparisons

expect(5).to be < 6
expect(5).to == 5
expect(5).to equal value
expect(5).to be_between(1, 10)
expect(5).to be_within(0.05).of value

Type-specific

expect(x).to be_zero    # FixNum#zero?
expect(x).to be_empty   # Array#empty?
expect(x).to have_key   # Hash#has_key?

Objects

expect(obj).to be_an_instance_of MyClass
expect(obj).to be_a_kind_of MyClass

Errors

expect { user.save! }.to raise_error
expect { user.save! }.to raise_error(ExceptionName, /msg/)

Enumerables

expect(list).to include(<object>)

expect(list).to have(1).things
expect(list).to have_at_least(2).things
expect(list).to have_at_most(3).things

Common RSpec strategy: (1) pick a class, (2) pick a method, (3) outline expected behaviors, (4) write one `it` block per behavior

In the example test above, our three layers of describe/describe/it blocks correspond to increasingly specific things we're testing:

At the highest level, we have the class RandomCharacterGenerator
Within that class, we have the method new_character
Within that method, we have the expected behavior "creates a new Character instance"

This maps well to the overall BDD strategy we outlined earlier. With RSpec specifically, we can translate this into four steps:
1. Pick a class to test
2. Pick a method on the class to test
3. Outline expected behaviors from that method (input/output, object/state mutations, errors, etc.)
4. Write one it block per behavior. This block can contain ONE or MANY expect(foo).to tests (to cover specific values, test/edge cases, etc.)

Rails makes picking classes straightforward--choose a model, a controller, a service object, anything defined as a class!

Ideally, you'll want to test the functionality of individual methods, as well as an overall input/output from a chain of methods. Doing both will help give you confidence that you know what each step of your code is doing (and provide a safety net for catching errors when refactoring).

In BDD, it is very important to think of expected behaviors AHEAD OF TIME! This is good practice to reinforce approaching your code with a deliberate plan. Be able to break down your methods (and overall functionality) into individual behaviors, as well as test cases (both expected and edge cases).

Use case: character-generator API

Here's a review of the character-generator API from my last post (with some recent refactors):

Our schema includes a Character model, which belongs to a Player model. Characters have a name string and four stats as integers (strength, dexterity, intelligence, charisma), and a foreign key for their Player. Players have a user name and a display name, both strings.

# /db/schema.rb

ActiveRecord::Schema.define(version: 2019_11_24_071655) do

  create_table "characters", force: :cascade do |t|
    t.string "name"
    t.integer "strength"
    t.integer "dexterity"
    t.integer "intelligence"
    t.integer "charisma"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
    t.integer "player_id", null: false
    t.index ["player_id"], name: "index_characters_on_player_id"
  end

  create_table "players", force: :cascade do |t|
    t.string "user_name"
    t.string "display_name"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
  end

  add_foreign_key "characters", "players"
end

The RandomCharacterGenerator service object is a class that handles all of the logic to generate a new Character, and assign their stats points randomly based on the available @points_pool and @max_roll attributes. There's also an attribute for @stats_array that contains strings for the four Character attributes. (Yes, I know that was lazy of me...)

The public method new_character returns a new Character instance with its stats filled in. There is also a private method, roll_stats, that handles the stat-randomizing:

# /app/services/random_character_generator.rb

class RandomCharacterGenerator
    attr_accessor :stats_array, :points_pool, :max_roll

    def initialize
        @stats_array = ["strength", "dexterity", "intelligence", "charisma"]
        @points_pool = 9
        @max_roll = 6
    end


    def new_character(name, player)
        # more code needed here to make tests pass
    end


    private

    def roll_stats(character, stats_array, points_pool, max_roll)
        # more code needed here to make tests pass
    end

end

For this article, we'll group all our tests together by the method new_character, as we're concerned with the output Character it returns. Because this method relies on the private method roll_stats, we are indirectly testing that too. However, some of these tests could be rewritten to be directly attached to roll_stats as well.

Let's go through the RSpec strategy steps above:

1. Pick a class:

RandomCharacterGenerator service object

2. Pick a method on the class:

new_character

3. Outline expected behaviors:

It creates a new Character instance
It randomly allocates all stat points (9) between four Character stats (strength, dexterity, intelligence, charisma)
It allocates stat points so stat values are between 1 and max roll (6)
It saves the Character to the database

4. Write one it block per behavior:

# /spec/services/random_character_generator_spec.rb

RSpec.describe RandomCharacterGenerator do

    describe "#new_character" do
        # NOTE: Do NOT create your test variables this way!! (See comments for why.) This is just an example for readability...
        rcg = RandomCharacterGenerator.new
        player = Player.create(user_name: "Ronald McDonald", display_name: "Mac")
        character = rcg.new_character("Ronnie the Rat", player)

        it "creates a new Character instance" do
            # expect(x).to
        end

        it "randomly allocates all #{rcg.points_pool} stat points between #{rcg.stats_array.to_s}" do
            # expect(x).to
        end

        it "allocates stat points so stat values are between 1 and max roll (#{rcg.max_roll})" do
            # expect(x).to
        end

        it "saves the Character to the database" do
            # expect(x).to
        end
    end
end

Creating our tests

Let's see our tests by running bundle exec rspec. This will execute all the tests available, and return the results to our console:

$ bundle exec rspec
....

Finished in 0.01019 seconds (files took 0.8859 seconds to load)
4 examples, 0 failures

Our tests are technically passing, because we haven't filled them in yet! Let's build them one-by-one.

1. `it "creates a new Character instance"`

We can test whether a variable is an instance of a particular class with be_an_instance_of:

# /spec/services/random_character_generator_spec.rb

    it "creates a new Character instance" do
        expect(character).to be_an_instance_of Character
    end

Run bundle exec rspec:

Failures:

  1) RandomCharacterGenerator#new_character creates a new Character instance
     Failure/Error: expect(character).to be_an_instance_of Character
       expected nil to be an instance of Character
     # ./spec/services/random_character_generator_spec.rb:70:in `block (3 levels) in <top (required)>'

Finished in 0.03433 seconds (files took 0.91909 seconds to load)
4 examples, 1 failure

Failed examples:

rspec ./spec/services/random_character_generator_spec.rb:69 # RandomCharacterGenerator#new_character creates a new Character instance

Great! Now we're ready to fill in the code in new_character to make this test pass. This is the heart of BDD (and TDD): write the tests first, then write the code!

# /app/services/random_character_generator.rb

    def new_character(name, player)
        Character.new(name: name, player: player).tap do |character|
            # roll_stats() will be called here
            # we will save! the character here
        end
    end

This will make our tests pass (even though roll_stats doesn't do anything yet). 1 of 4 complete!

2. `it "randomly allocates all 9 stat points between (strength, dexterity, intelligence, charisma)"`

Since we have the stats we want to check stored in @stats_array, we can use reduce to iterate through it, access character[stat] to check its value, and add up the integers for each stat. We can then use that with expect(x).to eq value to check for equality:

# /spec/services/random_character_generator_spec.rb

    it "randomly allocates all #{rcg.points_pool} stat points between #{rcg.stats_array.to_s}" do
        expect(rcg.stats_array.reduce(0) { |points, stat| points += character[stat] }).to eq rcg.points_pool 
    end

Let's run bundle exec rspec to see what the failing test outputs:

Failures:

  1) RandomCharacterGenerator#new_character randomly allocates all 9 stat points between ["strength", "dexterity", "intelligence", "charisma"]
     Failure/Error: expect(rcg.stats_array.reduce(0) { |points, stat| points += character[stat] }).to eq rcg.points_pool

     TypeError:
       nil can't be coerced into Integer
     # ./spec/services/random_character_generator_spec.rb:74:in `+'
     # ./spec/services/random_character_generator_spec.rb:74:in `block (4 levels) in <top (required)>'
     # ./spec/services/random_character_generator_spec.rb:74:in `each'
     # ./spec/services/random_character_generator_spec.rb:74:in `reduce'
     # ./spec/services/random_character_generator_spec.rb:74:in `block (3 levels) in <top (required)>'

Finished in 0.01359 seconds (files took 0.86408 seconds to load)
4 examples, 1 failure

Failed examples:

rspec ./spec/services/random_character_generator_spec.rb:73 # RandomCharacterGenerator#new_character randomly allocates all 9 stat points between ["strength", "dexterity", "intelligence", "charisma"]

Since nothing is assigned to each character[stat] yet, we're getting an error saying nil cannot be coerced into an integer for addition. Let's add some code to the roll_stats method, and call it inside new_character:

# /app/services/random_character_generator.rb

    def new_character(name, player)
        Character.new(name: name, player: player).tap do |character|
            roll_stats(character, @stats_array, @points_pool, @max_roll)
            # we will save! the character here
        end
    end


    private

    def roll_stats(character, stats_array, points_pool, max_roll)
        stats_array.each do |stat|
            roll = rand(1..10)
            character[stat] = roll
            points_pool -= roll
        end
    end

Run bundle exec rspec:

Failures:

  1) RandomCharacterGenerator#new_character randomly allocates all 9 stat points between ["strength", "dexterity", "intelligence", "charisma"]
     Failure/Error: expect(rcg.stats_array.reduce(0) { |points, stat| points += character[stat] }).to eq rcg.points_pool

       expected: 9
            got: 20

       (compared using ==)
     # ./spec/services/random_character_generator_spec.rb:74:in `block (3 levels) in <top (required)>'

Finished in 0.02692 seconds (files took 0.84623 seconds to load)
4 examples, 1 failure

Failed examples:

rspec ./spec/services/random_character_generator_spec.rb:73 # RandomCharacterGenerator#new_character randomly allocates all 9 stat points between ["strength", "dexterity", "intelligence", "charisma"]

Great, we've got a new error! The value we're adding up with reduce isn't matching the expected value (9). Let's add a bit more code to ensure that @points_pool isn't exceeded by each rand(1..max_roll):

# /app/services/random_character_generator.rb

    def roll_stats(character, stats_array, points_pool, max_roll)
        stats_array.each do |stat|
            roll = rand(1..10)

            if roll > points_pool
                roll = points_pool
            end

            character[stat] = roll
            points_pool -= roll
        end
    end

Awesome, our test will now pass!

3. `it "allocates stat points so they do not exceed max roll 6"`

For this, let's write four separate expect tests in the same it block. Each one will test an individual character[stat], and the test will only pass if all four expects are true:

# /spec/services/random_character_generator_spec.rb

        it "allocates stat points so stat values are between 1 and max roll (#{rcg.max_roll})" do
            expect(character.strength).to be_between(1, rcg.max_roll)
            expect(character.dexterity).to be_between(1, rcg.max_roll)
            expect(character.intelligence).to be_between(1, rcg.max_roll)
            expect(character.charisma).to be_between(1, rcg.max_roll)
        end

Let's check out our result with bundle exec rspec:

Failures:

  1) RandomCharacterGenerator#new_character allocates stat points so stat values are between 1 and max roll (6)
     Failure/Error: expect(character.strength).to be_between(1, rcg.max_roll)
       expected 8 to be between 1 and 6 (inclusive)
     # ./spec/services/random_character_generator_spec.rb:78:in `block (3 levels) in <top (required)>'

Finished in 0.04061 seconds (files took 0.91006 seconds to load)
4 examples, 1 failure

Failed examples:

rspec ./spec/services/random_character_generator_spec.rb:77 # RandomCharacterGenerator#new_character allocates stat points so stat values are between 1 and max roll (6)

Okay, so our rolls are going too high! (However, it IS possible for the stats to randomly all be in the correct range--beware of false positives!)

Change roll_stats so that our rand() call cannot exceed @max_roll:

# /app/services/random_character_generator.rb

    def roll_stats(character, stats_array, points_pool, max_roll)
        stats_array.each do |stat|
            roll = rand(1..max_roll)

            if roll > points_pool
                roll = points_pool
            end

            character[stat] = roll
            points_pool -= roll
        end
    end

Perfect!

Sidenote: the final code to allocate points across an arbitrary number of possible stats has roll_stats written to be this (and debugged using .tap!), which is recognizable from the previous article:

# /app/services/random_character_generator.rb

    def roll_stats(character, stats_array, points_pool, max_roll)
        stats_array.each_with_index do |stat, index|
            roll = rand(1..max_roll)                                    .tap {|r| puts "roll: #{r}"}
            remaining_stats = ((stats_array.length - 1) - index)        .tap {|r| puts "remaining_stats: #{r}"}
                                                                        .tap {|r| puts "points_pool (before): #{points_pool}"}
            if remaining_stats == 0
                character[stat] = points_pool
                points_pool = 0
            elsif points_pool - roll < remaining_stats
                max_points = points_pool - remaining_stats
                character[stat] = max_points
                points_pool -= max_points
            else
                character[stat] = roll
                points_pool -= roll
            end                                                         .tap {|r| puts "character[#{stat}]: #{character[stat]}"}
                                                                        .tap {|r| puts "points_pool (after): #{points_pool}\n\n"}
        end
    end

Run the tests again, and they will still pass!

4. `it "saves the Character to the database"`

We'll check if our Character is successfully saved to the database by checking if the number of Character records stored in the database has increased by 1.

To start, let's get a starting_database_count variable set up in our describe "#new_character block. We'll use the ActiveRecord .count method on the Character model to get this number:

# /spec/services/random_character_generator_spec.rb

RSpec.describe RandomCharacterGenerator do

    describe "#new_character" do
        # NOTE: Do NOT create your test variables this way!! (See comments for why.) This is just an example for readability...
        starting_database_count = Character.count

        rcg = RandomCharacterGenerator.new
        player = Player.create(user_name: "Ronald McDonald", display_name: "Mac")
        character = rcg.new_character("Ronnie the Rat", player)

        ...

        it "saves the Character to the database" do
            # expect(x).to
        end
    end
end

Now, we can use expect(x).to eq value to check if the Character.count value after calling new_character has increased by 1:

# /spec/services/random_character_generator_spec.rb

    it "saves the Character to the database" do
        expect(Character.count).to eq (starting_database_count + 1)
    end

Let's see what the failing test outputs with bundle exec rspec:

Failures:

  1) RandomCharacterGenerator#new_character saves the Character to the database
     Failure/Error: expect(Character.count).to eq (starting_database_count + 1)

       expected: 1736
            got: 1735

       (compared using ==)
     # ./spec/services/random_character_generator_spec.rb:87:in `block (3 levels) in <top (required)>'

Finished in 0.02612 seconds (files took 0.88349 seconds to load)
4 examples, 1 failure

Failed examples:

rspec ./spec/services/random_character_generator_spec.rb:86 # RandomCharacterGenerator#new_character saves the Character to the database

Okay, so our Character isn't being saved. Let's toss a save! call in the .tap block called on Character.new:

# /app/services/random_character_generator.rb

    def new_character(name, player)
        Character.new(name: name, player: player).tap do |character|
            roll_stats(character, @stats_array, @points_pool, @max_roll)
            character.save!
        end
    end

And our final test output:

$ bundle exec rspec
....

Finished in 0.01343 seconds (files took 0.86781 seconds to load)
4 examples, 0 failures

Hooray! We now have test coverage for our RandomCharacterGenerator#new_character method!

Conclusion

RSpec is a great tool to help you familiarize yourself with behavior-driven development and testing in Rails.

I highly recommend reading through the resources below, especially the top few (including the RubyGuides tutorial, an excellent intro tutorial by fellow Flatiron alum Aliya Lewis, and the Devhints RSpec cheatsheet!).

Pros and Cons of Ruby's .tap Method

Isa Levine — Mon, 25 Nov 2019 02:26:29 +0000

During a recent technical challenge, I got the chance to learn about and use Ruby's .tap method. This method allows you to "tap" into the result of a method call, usually to perform additional operations on that result, or to debug that result (i.e. by printing to the console).

A quick Google search for ruby tap method will return a lot of articles and StackOverflow discussions about when to use .tap. There's a pretty clear divide between folks who think it's useful for communicating intent and thus improving readability, and others who think it is overly-used / rarely-useful syntactic sugar that harms readability.

In this post, I'll explore some of the pros and cons of the .tap method.

What is the .tap method?

From the Ruby documentation for Object:

tap{|x|...} → obj

Yields self to the block, and then returns self. The primary purpose of this method is to “tap into” a method chain, in order to perform operations on intermediate results within the chain.

So, when we call .tap on an Object, we can insert extra operations before any other code executes. This is especially useful with things like ActiveRecord creation/lookups, where we may immediately want to do something to a new/found record.

For example, if we have a library app with Book and Checkout models, we could check for an existing Checkout record with Checkout.find_by(book: book), then use .tap to create a block to manipulate the found Checkout (and the Book we used to find it!):

Checkout.find_by(book: book).tap do |checkout|
  checkout.update!(check_in_date: date)
  book.update!(checked_out: false)
end

Pros

wrap ActiveRecord creation/lookup patterns in a block that communicates intent

per this StackOverflow example, this:

user = User.new.tap do |u|
  u.build_profile
  u.process_credit_card
  u.ship_out_item
  u.send_email_confirmation
  u.blahblahyougetmypoint
end

could be easier to understand at a glance than seeing this:

user = User.new
user.build_profile
user.process_credit_card
user.ship_out_item
user.send_email_confirmation
user.blahblahyougetmypoint

provide a way to debug code step-by-step (as an alternative to pry)

Again from the Ruby documentation for .tap, this example is designed to write step-by-step outputs to the console to help us debug:

(1..10)                .tap {|x| puts "original: #{x.inspect}"}
  .to_a                .tap {|x| puts "array: #{x.inspect}"}
  .select {|x| x%2==0} .tap {|x| puts "evens: #{x.inspect}"}
  .map {|x| x*x}       .tap {|x| puts "squares: #{x.inspect}"}

Cons

limited use because sometimes ActiveRecord patterns are more recognizable/readable than the .tap syntax
- per this soapbox rant, the "traditional" pattern may be more recognizable to people familiar with Rails, despite (or perhaps because of) the redundant return of self at the end:
```
obj = SomeClass.new
obj.blah = true
obj
```
when debugging, must carefully format to be readable without disrupting the rest of the code (as intended)
- per the same article as the previous con, using .tap to debug chains of ActiveRecord methods is very useful, and doesn't get in the way of reading the code it's testing--but writing this code, and keeping it tidy and readable while maintaining/changing it, is extra effort:
```
User
  .active                      .tap { |users| puts "Users so far: #{users.size}" }
  .non_admin                   .tap { |users| puts "Users so far: #{users.size}" }
  .at_least_years_old(25)      .tap { |users| puts "Users so far: #{users.size}" }
  .residing_in('USA')
```

Use case: character-generator API

In this use case, I build a character-generator API where Players can create randomly-generated Characters. Here, we will see two places to (potentially) use .tap:

When creating a new Character instance, to more clearly communicate our intent behind several variables, and to reduce some redundant code
When using a set number of points to assign to a Character's stats, while keeping track of (a) the random "6-sided die roll", (b) the remaining number of points, and (c) the Character's current and remaining stats.

API overview: models and relationships

Our two main models will be Players and Characters.

Players simply have a user_name and a display_name:

# /db/schema.rb

  create_table "players", force: :cascade do |t|
    t.string "user_name"
    t.string "display_name"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
  end

Characters have a name, 4 stats, and a Player they belong to:

# /db/schema.rb

  create_table "characters", force: :cascade do |t|
    t.string "name"
    t.integer "strength"
    t.integer "dexterity"
    t.integer "intelligence"
    t.integer "charisma"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
    t.integer "player_id", null: false
    t.index ["player_id"], name: "index_characters_on_player_id"
  end

RandomCharacterGenerator service object

We will be using .tap inside a service object, RandomCharacterGenerator, which will provide a .new_character() method that takes in a name and player, and automatically creates and saves a Character in the database:

# /app/services/random_character_generator.rb

class RandomCharacterGenerator

    def new_character(name, player)
        character = Character.new(name: name, player: player)
        stats_array = ["strength", "dexterity", "intelligence", "charisma"]
        points_pool = 9
        max_roll = 6
        roll_stats(character, stats_array, points_pool, max_roll)
        character.save!
        character
    end


    private

    def roll_stats(character, stats_array, points_pool, max_roll)
        stats_array.each_with_index do |stat, index|
            roll = rand(1..max_roll)
            remaining_stats = (stats_array.length - 1) - index
            if remaining_stats == 0
                character[stat] = points_pool
                points_pool = 0
            elsif points_pool - roll < remaining_stats
                max_points = points_pool - remaining_stats
                character[stat] = max_points
                points_pool -= max_points
            else
                character[stat] = roll
                points_pool -= roll
            end
        end
    end

end

Now let's look at some places where we can use .tap to (potentially) tie our code together more clearly!

Case 1: communicating intent and context of variables during `Character.new()`

In .new_character(), we're performing several operations as soon as we create a new Character instance. Right after Character.new(), we:

define 3 variables (stats_array, points_pool, max_roll)
call the private method roll_stats() with those 3 variables
call save! on our new Character
return the Character

However, it's a little unclear whether those 3 new variables need to be used anywhere else. Plus, you may be the kind of person who hates that redundant hanging line that just returns character!

So, let's use .tap to wrap those variables, the roll_stats() call that uses them, and the save! call in a block--and eliminate that final character line while we're at it:

# /app/services/random_character_generator.rb

    def new_character(name, player)
        Character.new.tap do |character|
            stats_array = ["strength", "dexterity", "intelligence", "charisma"]
            points_pool = 9
            max_roll = 6
            roll_stats(character, stats_array, points_pool, max_roll)
            save!
        end
    end

Now, we have several potential advantages:

Our intent with stats_array, points_pool, and max_roll is clearer, because the variables only exist in the .tap block's scope, and are immediately passed into roll_stats(). We can be more confident that those variables won't be needed anywhere else in our code.
We know that .tap always returns the object it's called on, so we don't have to worry about forgetting to explicitly return character at the end of new_character(). We can be more confident that our new Character will be returned as expected.

However...

We saved...0 lines of code.

Pro or con: do you think the ORIGINAL or NEW version is more readable? (Feel free to comment below!)

Case 2: debugging values step-by-step during iteration in `roll_stats()`

In the private method roll_stats(), we have several values that need to be tracked as each Character stat is randomly assigned a number 1 through 6:

how many points are left to allocate
how many stats are left to assign points to (so no stat ends up with 0)
what number 1 through 6 is randomly "rolled"
is the stat being correctly assigned the "rolled" value
is the number of points left to spend decreasing by the "rolled" value

Faced with the option to insert a puts "value: #{value}" or pry line in-between each step, I realized that using .tap instead would let me add debugging messages to the console without breaking up the code I'm testing.

So, after each step (and in a few extra places), I tabbed way over to the side and added a .tap call with a puts "value: #{value}" message to check the values step-by-step: (scroll to the right)

# /app/services/random_character_generator.rb

    def roll_stats(character, stats_array, points_pool, max_roll)
        stats_array.each_with_index do |stat, index|
            roll = rand(1..max_roll)                                    .tap {|r| puts "roll: #{r}"}
            remaining_stats = ((stats_array.length - 1) - index)        .tap {|r| puts "remaining_stats: #{r}"}
                                                                        .tap {|r| puts "points_pool (before): #{points_pool}"}
            if remaining_stats == 0
                character[stat] = points_pool
                points_pool = 0
            elsif points_pool - roll < remaining_stats
                max_points = points_pool - remaining_stats
                character[stat] = max_points
                points_pool -= max_points
            else
                character[stat] = roll
                points_pool -= roll
            end                                                         .tap {|r| puts "character[#{stat}]: #{character[stat]}"}
                                                                        .tap {|r| puts "points_pool (after): #{points_pool}\n\n"}
        end
    end

Now, when I'm running tests with RSpec, I can get this console output to help me debug:

[18:36:52] (master) tap-example-character-creator-api
// ♥ bundle exec rspec
roll: 3
remaining_stats: 3
points_pool (before): 9
character[strength]: 3
points_pool (after): 6

roll: 2
remaining_stats: 2
points_pool (before): 6
character[dexterity]: 2
points_pool (after): 4

roll: 1
remaining_stats: 1
points_pool (before): 4
character[intelligence]: 1
points_pool (after): 3

roll: 2
remaining_stats: 0
points_pool (before): 3
character[charisma]: 3
points_pool (after): 0

....

Finished in 0.02678 seconds (files took 3.61 seconds to load)
4 examples, 0 failures

The main advantage here is that the readability of the original code is not changed--in fact, it's easy to ignore that those .tap calls are even there!

However, it took time to format those .tap calls to be out of the way but still formatted in a readable way--and any changes to those lines of code will inevitably change the indentation that keeps them lined up. Maintaining that readability, or wanting to comment out/delete those .tap calls, costs extra time and effort.

Pro or con: do you think it takes MORE or LESS time to write and maintain this syntax for debugging? (Feel free to comment below!)

Conclusion

Honestly, I can't sum up the .tap method any better than Kartik Jagdale does in this article, so I'll simply quote him:

Just like any other ruby syntactic sugar , I would say tap is a pretty cool ruby method which can not just be used for readability but also to debug chained methods. Give it a shot.

Special thanks to Anthony Hernandez for introducing me to the .tap method! :)

Using Service Objects to Make your Rails Controllers (and Models) Skinny

Isa Levine — Mon, 18 Nov 2019 00:54:35 +0000

DISCLAIMER: I really dislike the anthropomorphic descriptors "fat" and "skinny" being used in this context, and I find it fatphobic that "skinny" is implicitly the "good" way to write your code. Surely there is a better alternative to these terms, and I welcome suggestions in the comments! (I will be happy to update the language in this post.)

When studying Rails design patterns, you may have heard the axiom "fat model, skinny controller" (or the inverse, "fat controller, skinny model"). Both of these describe a pattern of where to put business logic, which tends to take up a lot of lines of code.

Neither case is ideal--we want our controllers and our models to be "skinny", with as little code as possible, so that they are easy to understand and maintain. If only we had another place in our Rails app to put this logic...

Service Objects: Another place to put your business logic

...oh wait, there totally is: Service Objects! Service objects live in the /app/services/ directory, and any classes defined therein will be autoloaded (along with the rest of the /app/ directory).

So, we can define a service object class, move our business logic to it, and thus keep our controllers and models "skinny" by keeping only controller- or model-related code in them. All that extra business logic can be invoked by instantiating a service object only when needed.

Thus, we achieve the trifecta:

our controllers are "skinny", and can focus on controller-logic
our models are also "skinny", and can focus on model-logic
our business logic is wrapped in a service object (with the bonus that service objects are easily testable...but I'll save that for a future post!)

Example: Refactoring our Magic: the Gathering art-displaying app

A perfect example of a "fat controller" we could refactor with service objects is my previous post's app to render Magic: the Gathering card art.

Here, we defined a bunch of business logic in our pages_controller.rb to query the Scryfall API:

# /app/controller/pages_controller.rb

class PagesController < ApplicationController
  def index
    session[:img_array] ||= []  # refactor with ||= pointed out by Andrew Brown

    if session[:img_array].empty? || params["button_action"] == "refresh"
      session[:img_array] = get_scryfall_images
    end
  end


  private

  def get_json(url)
    response = RestClient.get(url)
    json = JSON.parse(response)
  end

  def parse_cards(json, img_array)
    data_array = json["data"]
    data_array.each do |card_hash|
      if card_hash["image_uris"]
        img_hash = {
          "image" => card_hash["image_uris"]["art_crop"],
          "name" => card_hash["name"],
          "artist" => card_hash["artist"]
        }
        img_array << img_hash
      end
    end

    if json["next_page"]
      json = get_json(json["next_page"])
      parse_cards(json, img_array)
    end
  end

  def get_scryfall_images
    api_url = "https://api.scryfall.com/cards/search?q="
    img_array = []
    creature_search_array = ["merfolk", "goblin", "angel", "sliver"]

    creature_search_array.each do |creature_str|
      search_url = api_url + "t%3Alegend+t%3A" + creature_str
      json = get_json(search_url)
      parse_cards(json, img_array)

      sleep(0.1)  # per the API documentation: https://scryfall.com/docs/api
    end

    img_array.sample(9)
  end
end

But pretty much everything below the private keyword is NOT related to the controller--it's just logic to query a specific API.

What if we wanted to query a different card game's API, and wrote a bunch of new functions to fetch and parse its data? Our controller could get out of control (and hard to understand/maintain) VERY quickly!

So, let's create a new /app/services/ directory, and a dedicated service object to handle the Scryfall API-querying logic--let's call it scryfall_query_service.rb:

# /app/services/scryfall_query_service.rb
class ScryfallQueryService
    def get_json(url)
        response = RestClient.get(url)
        json = JSON.parse(response)
    end

    def parse_cards(json, img_array)
        data_array = json["data"]
        data_array.each do |card_hash|
            if card_hash["image_uris"]
                img_hash = {
                    "image" => card_hash["image_uris"]["art_crop"],
                    "name" => card_hash["name"],
                    "artist" => card_hash["artist"]
                }
                img_array << img_hash
            end
        end

        if json["next_page"]
        json = self.get_json(json["next_page"])
        self.parse_cards(json, img_array)
        end
    end

    def get_scryfall_images 
        api_url = "https://api.scryfall.com/cards/search?q="
        img_array = []
        creature_search_array = ["merfolk", "goblin", "angel", "sliver"]

        creature_search_array.each do |creature_str|
            search_url = api_url + "t%3Alegend+t%3A" + creature_str
            json = self.get_json(search_url)
            self.parse_cards(json, img_array)

            sleep(0.1)  # per the API documentation: https://scryfall.com/docs/api
        end

        img_array.sample(9)
    end
end

Note that we need to add self. before our calls to these instance methods! (self.get_json and self.parse_cards)

And now, we can make our pages_controller.rb much "skinnier" by completely removing those same methods:

# /app/controllers/pages_controller.rb

class PagesController < ApplicationController
  def index
    session[:img_array] ||= []

    if session[:img_array].empty? || params["button_action"] == "refresh"
      scryfall_query_service = ScryfallQueryService.new
      session[:img_array] = scryfall_query_service.get_scryfall_images
    end


    session[:refresh_counter] ||= 0

    if params["button_action"] == "refresh"
      session[:refresh_counter] += 1
    end

    @refresh_counter = session[:refresh_counter]
  end
end

Now, we can instantiate a ScryfallQueryService object, and all its get_scryfall_images method to handle all of the API-querying and data-parsing outside of the controller. This makes our controller a lot easier to read and understand!

Note: Although the examples here are exclusively related to making "skinny" controllers, the same types of logic/methods can be moved from models to service objects as well!

Service Objects and Modular Design: Adding a new API-querying service object

One of the benefits of having this API-querying business logic wrapped in the ScryfallQueryService object is that we can now expand our app to include other service objects that query other APIs, without interrupting the functionality of our ScryfallQueryService or adding more logic to our pages_controller.rb.

Let's say we want to add a route to our app that will render card art from the Star Wars CCG instead. This will require us to query a different API altogether, and thus parse the JSON we get back in a different way than ScryfallQueryService.

The API we'll be using for card art from the Star Wars CCG is SWCCGDB, a fan-maintained database for the now-fan-maintained game that was "officially" discontinued in 2001.

Since the JSON we get back from the API is structured differently, both our parse_cards and get_swccgdb_images methods will be different from ScryfallQueryService. Here's the code:

# /app/services/swccgdb_query_service.rb

class SWCCGDBQueryService
    def get_json(url)
        response = RestClient.get(url)
        json = JSON.parse(response)
    end

    def parse_cards(json, img_array)
        data_array = json   # api returns all cards in a single array at top level of json
        data_array.each do |card_hash|
            if card_hash["type_code"] == "character"
                img_hash = {
                    "image" => card_hash["image_url"],
                    "name" => card_hash["name"],
                    "artist" => "Lucasfilm / Decipher / Wizards of the Coast / SWCCG Player's Committee"
                }
                img_array << img_hash
            end
        end
    end

    def get_swccgdb_images
        api_url = "https://swccgdb.com/api/public/cards/"
        img_array = []
        set_search_array = ["pr", "hoth", "cc"]     # premiere, hoth, and cloud city sets

        set_search_array.each do |set_str|
            search_url = api_url + set_str + ".json?_format=json"
            json = self.get_json(search_url)
            self.parse_cards(json, img_array)
        end

        img_array.sample(9)
    end 
end

Most of our code can be copied directly from scryfall_query_service.rb, but note several differences:

in get_swccgdb_images, we are now searching through different game sets ("Premiere", "Hoth", and "Cloud City") instead of creature types
also in get_swccgdb_images, the API URL is different (obviously), and our search_url string is constructed differently
in parse_cards, we assign the JSON directly to the data_array variable due to the structure of the API's JSON response
also in parse_cards, we are now filtering cards for card_hash["type_code"] == "creature"

Now, we can build another route in our pages_controller.rb and routes.rb files to use the ScryfallQueryService at localhost:3000/mtg, and SWCCGDBQueryService at localhost:3000/swccg.

Let's update pages_controller.rb first. Instead of one index method, let's define one for mtg (Magic: the Gathering) and one for swccg (Star Wars CCG):

class PagesController < ApplicationController
  # def index
  #   session[:img_array] ||= []

  #   if session[:img_array].empty? || params["button_action"] == "refresh"
  #     scryfall_query_service = ScryfallQueryService.new
  #     session[:img_array] = scryfall_query_service.get_scryfall_images
  #   end


  #   session[:refresh_counter] ||= 0

  #   if params["button_action"] == "refresh"
  #     session[:refresh_counter] += 1
  #   end

  #   @refresh_counter = session[:refresh_counter]
  # end


  def mtg
    # use ScryfallQueryService here
  end


  def swccg
    # use SWCCGDBQueryService here
  end

end

Now, let's copy the logic from index into our two new methods. Under swccg, we'll also change our service object to be an instance of SWCCGDBQueryService:

# /app/controller/pages_controller.rb

class PagesController < ApplicationController
  def mtg
    session[:img_array] ||= []

    if session[:img_array].empty? || params["button_action"] == "refresh"
      scryfall_query_service = ScryfallQueryService.new
      session[:img_array] = scryfall_query_service.get_scryfall_images
    end


    session[:refresh_counter] ||= 0

    if params["button_action"] == "refresh"
      session[:refresh_counter] += 1
    end

    @refresh_counter = session[:refresh_counter]
  end


  def swccg
    session[:img_array] ||= []

    if session[:img_array].empty? || params["button_action"] == "refresh"
      swccgdb_query_service = SWCCGDBQueryService.new
      session[:img_array] = swccgdb_query_service.get_swccgdb_images
    end


    session[:refresh_counter] ||= 0

    if params["button_action"] == "refresh"
      session[:refresh_counter] += 1
    end

    @refresh_counter = session[:refresh_counter]
  end

end

Next, let's add an if block to the top of both methods so our session can keep track of which game its storing card art for--that way, if we switch from localhost:3000/mtg to localhost:3000/swccg, the API will know to empty out our session[:img_array] and fetch new cards from the correct game:

# /app/controller/pages_controller.rb

class PagesController < ApplicationController
  def mtg
    if session[:game] == "swccg" || !session[:game]   # empty img_array if switching games
      session[:img_array] = []
      session[:game] = "mtg"
    end

    session[:img_array] ||= []

    if session[:img_array].empty? || params["button_action"] == "refresh"
      scryfall_query_service = ScryfallQueryService.new
      session[:img_array] = scryfall_query_service.get_scryfall_images
    end


    session[:refresh_counter] ||= 0

    if params["button_action"] == "refresh"
      session[:refresh_counter] += 1
    end

    @refresh_counter = session[:refresh_counter]
  end


  def swccg
    if session[:game] == "mtg" || !session[:game]   # empty img_array if switching games
      session[:img_array] = []
      session[:game] = "swccg"
    end

    session[:img_array] ||= []

    if session[:img_array].empty? || params["button_action"] == "refresh"
      swccgdb_query_service = SWCCGDBQueryService.new
      session[:img_array] = swccgdb_query_service.get_swccgdb_images
    end


    session[:refresh_counter] ||= 0

    if params["button_action"] == "refresh"
      session[:refresh_counter] += 1
    end

    @refresh_counter = session[:refresh_counter]
  end

end

This is great, but our controller isn't very "skinny" now, which is why we're creating service objects in the first place! The problem is that our code is not DRY--we have mostly duplicated the code from index, and it now appears twice in our controller.

Let's refactor the session-checking-and-setting logic into its own private method update_session, where we can pass the parameter "mtg" or "swccg" to set the session[:game] variable and use the correct service object:

# /app/controllers/pages_controller.rb

class PagesController < ApplicationController
  def mtg
    update_session("mtg")
    @refresh_counter = session[:refresh_counter]
  end

  def swccg
    update_session("swccg")
    @refresh_counter = session[:refresh_counter]
  end


  private

  def update_session(current_game)
    if session[:game] != current_game || !session[:game]   # empty img_array if switching games
      session[:img_array] = []
      session[:game] = current_game
    end

    session[:img_array] ||= []

    if session[:img_array].empty? || params["button_action"] == "refresh"
      if current_game == "mtg"
        scryfall_query_service = ScryfallQueryService.new
        session[:img_array] = scryfall_query_service.get_scryfall_images

      elsif current_game == "swccg"
        swccgdb_query_service = SWCCGDBQueryService.new
        session[:img_array] = swccgdb_query_service.get_swccgdb_images

      # add additional games here
      end
    end

    session[:refresh_counter] ||= 0

    if params["button_action"] == "refresh"
      session[:refresh_counter] += 1
    end
  end

end

Perfect! We can now add additional games into our app by adding another elsif current_game == String branch inside our update_session method, and adding another public method (with only two lines of code inside it!) to pages_controller.rb.

Now, let's update our routes.rb with a Get and Post route to both localhost:3000/mtg and localhost:3000/swccg:

# /config/routes.rb

Rails.application.routes.draw do
  get "/mtg", to: "pages#mtg"
  post "/mtg", to: "pages#mtg"

  get "/swccg", to: "pages#swccg"
  post "/swccg", to: "pages#swccg"
end

And, let's go ahead and make a set of mtg.html.erb and swccg.html.erb views (in the same /app/views/pages/ directory where index.html.erb currently lives). These will automatically render at the end of the mtg and swccg controller methods respectively, and we can customize them with the name of each game:

<%# /app/views/pages/mtg.html.erb %>

<h1>Pages#mtg</h1>
<p>Find me in app/views/pages/mtg.html.erb</p>

<h2>Let's add some Magic: the Gathering card art!</h2>

<div class="card_container">
    <%= render partial: '/pages/cards/card', collection: session[:img_array], as: :img_hash %>
</div>

<div class="refresh_form">
    <%= render partial: '/pages/forms/refresh_button' %>
    <%= render partial: '/pages/forms/refresh_counter', locals: {counter: @refresh_counter} %>
</div>

<%# /app/views/pages/swccg.html.erb %>

<h1>Pages#swccg</h1>
<p>Find me in app/views/pages/swccg.html.erb</p>

<h2>Let's add some Star Wars CCG card art!</h2>

<div class="card_container">
    <%= render partial: '/pages/cards/card', collection: session[:img_array], as: :img_hash %>
</div>

<div class="refresh_form">
    <%= render partial: '/pages/forms/refresh_button' %>
    <%= render partial: '/pages/forms/refresh_counter', locals: {counter: @refresh_counter} %>
</div>

Great! Let's test out our new routes. In your console, run rails s. Navigate to localhost:3000 and you will see the default Rails index page (since we got rid of our index method in pages_controller.rb).

Now let's check out localhost:3000/mtg to see our Magic: the Gathering card art...

And now, let's go to localhost:3000/swccg to see our Star Wars CCG card art...

Perfect! As you can see, creating individual service objects to handle each API allows us to separate our concerns, so that the controller can focus on handling controller logic and our API-querying business logic is handled within its own API-specific service object.

Conclusion

Rails service objects allow us to move business logic from controllers (or models) to a separate class, which helps us keep our controllers (and models) "skinny" and focused on their own logic. They also allow us to make our codebase more modular, as we can build our individual service objects instead of cramming more logic into our controllers indefinitely.

Next time you see a lot of logic in your controllers (or models), think about moving some of it to a service object!

Special thanks to Anthony Hernandez for introducing me to service objects! :)

And additional thanks to Andrew Brown for feedback/refactor suggestions on my previous post!

HELP NEEDED: Understanding Rails ActionController::Live Module (and Async Limitations)

Isa Levine — Mon, 11 Nov 2019 06:38:52 +0000

The Situation: Practicing Data Ingestion in Rails (and Trying to be Async)

So, for reasons that (ahem) may or may not be job-interview-related, I'm practicing building a Rails server for ingesting, parsing, and storing data in a database.

My goal was to make two Rails apps, and have them talk to each other:

A server that broadcasts hashes containing randomly-generated characters (ideally repeating every 1 second, indefinitely)
A server that listens for and receives the hashes, and parses them as they're received to store in a database

I intended to implement this behavior asynchronously with the ActionController::Live module. The intended behavior is for the Broadcast server to emit a hash (as a string) every 1 second, and for the Receiver server to parse and store each hash as they come in. (For my tests, I have this looping 5 times.)

My problem is that the character-hashes are rendered 1-by-1 when testing in my browser and in the Broadcast server's console...

working fine in Chrome...

working fine in console...

...but in the Receiver server's console, all the character-hashes come at once in the HTTP response!

all the JSON is received as one response body!

So why is the async behavior (apparently) working in some places, and not in others?

Broadcaster server

The Broadcaster server is a simple Rails app that uses a BroadcasterController with ActionController::Live and its server-side event (SSE) module.

The index method generates a random character_hash, writes it to the current SSE response.stream in the variable sse, and pauses for 1 second to illustrate async behavior.

# Broadcaster app
# /app/controllers/broadcaster_controller.rb

class BroadcasterController < ApplicationController
    include ActionController::Live

    def index
        name_array = ["Ryu", "Peco", "Rei", "Momo", "Garr", "Nina"]
        hp_array = [132, 71, 15, 1, 0, 325]
        magic_array = ["Frost", "Typhoon", "Magic Ball", "Ascension", "Rejuvinate", "Weretiger"]

        response.headers['Content-Type'] = "text/event-stream"
        sse = SSE.new(response.stream)

        begin
            5.times do      
                character_hash = {
                    "uuid": SecureRandom.uuid,
                    "name": name_array.sample,
                    "hp": hp_array.sample,
                    "magic": magic_array.sample
                }
                sse.write({ character: character_hash })
                sleep 1
            end
        rescue IOError
            # client disconnected
        ensure
            sse.close
        end
    end
end

# Broadcaster app
# /config/routes.rb

Rails.application.routes.draw do
  get 'broadcaster' => 'broadcaster#index'
end

Once we start the server with rails s, we can use curl -i http://localhost:3000/broadcaster in the command line to send a Get request to the index method. The response will return each character with a 1 second delay in-between:

Since navigating to http://localhost:3000/broadcaster in the browser will also send a Get request, we see the same behavior here in Chrome:

So far, so good...

Receiver server

The other Rails app is a Receiver server that sends a Get request to the Broadcaster at http://localhost:3000/broadcaster, and parses its response to store the received characters in the database.

We also have it puts a readout to show us the res.body characters arriving all at once, instead of asynchronously as we saw above.

# Receiver app
# /app/controllers/listener_controller.rb

require 'net/http'

class ListenerController < ApplicationController
    def index
        url = URI.parse('http://localhost:3000/broadcaster')
        req = Net::HTTP::Get.new(url.to_s)
        res = Net::HTTP.start(url.host, url.port) { |http| http.request(req) }

        puts <<-READOUT

    res.body:
    ==============================
    #{res.body}

        READOUT

        char_array = res.body.split("\n\n")
        char_array.each do |data_str|
            data_hash = eval(data_str.slice!(6..-1))    # slice to remove leading "data: " substring
            char_hash = data_hash[:character]
            Character.create("uuid": char_hash[:uuid], "name": char_hash[:name], "hp": char_hash[:hp], "magic": char_hash[:magic])
        end
    end
end

# Receiver app
# /config/routes.rb

Rails.application.routes.draw do
  get 'listener' => 'listener#index'
end

Thus, when we start the server with rails server -p 3001 and send a Get request with curl -i http://localhost:3001/listener, we call the ListenerController's index method.

Here, index sends a Get request to our Broadcaster server at localhost:3000/broadcaster. But instead of seeing the asynchronous behavior we saw before, it all arrives at once:

So, instead of parsing each character as they come in as separate objects, we have to split the res.body into separate strings. And of course, we have to wait until all 5 characters are finished generating before we receive them. So much for scaling it up to send an unlimited number of characters!

Where I'm At

From the research I've done, I think the async behavior is being limited by Rails' use of the standard HTTP request/response cycle as the basis for ActionController::Live. As such, each request only gets one response, and that's why all the characters have to come back as one res.body string!

Per this excellent article by Eric Bidelman covering SSEs in HTML5, I thought I was moving toward implementing long polling...but apparently not.

Further, the tutorials I'm following usually expect us to build a JavaScript event listener to catch the async data from the Broadcaster server. So, is it just browser-magic that's making the ActionController::Live async behavior work in Chrome?

But then, why do the characters still appear to be coming in asynchronously when we use curl directly on localhost:3000/broadcaster...

...and NOT when using curl indirectly through localhost:3001/listener?

Any help, advice, or insight is greatly appreciated! <3

Links/Tutorials used:

BONUS: A Quick Intro to Ruby's SortedSet

Isa Levine — Sun, 03 Nov 2019 19:13:32 +0000

To build on our coverage of Ruby's Set, let's look at another Ruby data structure that implements set: a SortedSet!

The key difference between a Set and SortedSet is that, well, SortedSets are sorted, meaning their contents must respond to being sorted by the <=> operator (or a custom-defined sort method).

To review, some key details about sets:

All objects in a Set are guaranteed unique
~~Objects in a Set are not ordered~~
Sets are built on top of Hashes for super-fast object lookup

And SortedSets add to this:

Objects in a SortedSet are ordered by index, and can be accessed with the at or [] methods, and negative indices count backwards from the end (same as Arrays)
All objects in a SortedSet must be mutually comparable, meaning that <=> or its custom sort must not return nil for all objects in the SortedSet (otherwise, an ArgumentError will be thrown)
SortedSets are built on top of Sets, and have access to most Set methods, including subset? and superset?

Let's see them in action!

Overview

In this article, we'll introduce this basic functionality for SortedSets:

Creating new SortedSets, and seeing their default sorting behavior

New SortedSets and default sorts

require 'set'

Because SortedSets are built on top of sets, we must start by requiring the set module:

require 'set'

Now we're ready to build some SortedSets!

SortedSets with Strings and Integers

We instantiate a new SortedSet with SortedSet.new(), and pass it a collection object. For our examples, we'll create some SortedSets out of arrays and sets.

Let's start by building some arrays to test:

str_array = ["i", "am", "watching", "the", "office", "right", "now", "now", "now"]
int_array = [2, 6, 1, 4, 7, 2, 3, 3, 3, 1, 0, 5]

Now, let's use SortedSet.new() to create SortedSets:

str_sorted_set = SortedSet.new(str_array)
int_sorted_set = SortedSet.new(int_array)

#<SortedSet: {"am", "i", "now", "office", "right", "the", "watching"}>
#<SortedSet: {0, 1, 2, 3, 4, 5, 6, 7}>

As expected, creating a SortedSet both 1) filters out duplicates and 2) sorts contents using default <=> behavior, here meaning alphabetically and lowest-to-highest value. (Also, we get some refrigerator-magnet-style poetry out of the string sorting!)

Now, let's create regular ol' Sets out of the Arrays, and pass the Sets to SortedSet.new():

str_set = Set.new(str_array)
int_set = Set.new(int_array)

str_sorted_set = SortedSet.new(str_set)
int_sorted_set = SortedSet.new(int_set)

#<SortedSet: {"am", "i", "now", "office", "right", "the", "watching"}>
#<SortedSet: {0, 1, 2, 3, 4, 5, 6, 7}>

Same behavior!

And for good measure, let's use the Vector collection too:

require 'matrix'

str_vector = Vector["i", "am", "watching", "the", "office", "right", "now", "now", "now"]
int_vector = Vector[2, 6, 1, 4, 7, 2, 3, 3, 3, 1, 0, 5]

str_sorted_set = SortedSet.new(str_vector)
int_sorted_set = SortedSet.new(int_vector)

#<SortedSet: {"am", "i", "now", "office", "right", "the", "watching"}>
#<SortedSet: {0, 1, 2, 3, 4, 5, 6, 7}>

And same behavior again! So, we can expect the same result from SortedSet.new() regardless of the type of collection!

ArgumentError with Mixed Types

If we try to create a SortedSet containing objects that cannot be compared with <=>, we will get an ArgumentError. If we try to print the following mixed_sorted_set:

mixed_array = [2, "i", 6, "am", 1, "watching", 4, "the", 7, "office", 2]

mixed_sorted_set = SortedSet.new(mixed_array)

# /Users/isalevine/.rvm/rubies/ruby-2.6.1/lib/ruby/2.6.0/set.rb:782:
# in `sort!': comparison of Integer with String failed (ArgumentError)

We see that SortedSet is trying to call a sort!, but throws an Argument error when trying to compare an Integer with a String.

Check out this RubyDoc.info guide for more information in implementing custom sort behavior on SortedSets.

And here's the RubyDoc.info regarding Set methods available (and not available) for SortedSets:

SortedSet supports the same basic set-theoretic operations as Set, including #union, #intersection, #difference, and #exclusion, as well as #subset?, #superset?, and so on. Unlike Set, it does not define comparison operators like #> or #< as aliases for the superset/subset predicates. Instead, these comparison operators do a item-by-item comparison between the SortedSet and another sequential collection. (See Array#<=> for details.)

Conclusion

Now you're equipped with two versions of sets in Ruby: Sets and SortedSets! Between them, you have the ability to guarantee unique collections of objects, in both an unordered and ordered/indexed form as needed. Think about using them the next time you have arrays of unique objects!

Links and Sources

Ruby-Doc - SortedSet

RubyDoc.info - SortedSet

StackOverflow - options for implementing custom sorts (not specific to SortedSet)

GitHub with code snippets used

Got any tips, tricks, or instances where you like to use sets? Please feel free to share in the comments below!

Let's Use Rails Partials To Render Art from Magic: the Gathering!

Isa Levine — Sun, 27 Oct 2019 20:52:42 +0000

When I was first learning Rails in bootcamp, I spent most of my time learning routing with regular views--and they were, uh, simple. At that point, I wasn't familiar with making reusable frontend components, rendering them in a dynamic and nested way.

But all that was before I learned React! Now that I'm returning to frontend Rails work, I've been spending much more time with partial views, or simply partials.

Rails Guides describes partials this way:

Partial templates - usually just called "partials" - are another device for breaking the rendering process into more manageable chunks. With a partial, you can move the code for rendering a particular piece of a response to its own file.

Overview

In this article, we'll create some partials to render art from Magic: the Gathering , queried from the Scryfall API. We'll cover these topics along the way:

Rails naming conventions for views and partials
Using session to store data from external APIs (not specific to partials, but part of the use case)
Using render partial: within views and other partials
Passing variables to partials with locals:
Rendering partials repeatedly by iterating through a collection with collection:

Views and Partials

Rails' convention-over-configuration gives us a lazy option for rendering views: if a controller's method has a view with a matching name, and there's no other render or redirect_to invoked, Rails will automatically render the view when that method is called. Or, more eloquently put from Rails Guides with the following code example:

class BooksController < ApplicationController
  def index
    @books = Book.all
  end
end

Note that we don't have explicit render at the end of the index action in accordance with "convention over configuration" principle. The rule is that if you do not explicitly render something at the end of a controller action, Rails will automatically look for the action_name.html.erb template in the controller's view path and render it. So in this case, Rails will render the app/views/books/index.html.erb file.

Partials Love Underscores

Partials, however, are named with underscores at the beginning. This convention gives two advantages: we can differentiate partials from regular views, and it also allows us to drop the underscore when invoking render partial: in ERB.

We'll explore this more once we have some examples in front of us. :)

Use Case: Querying the Scryfall API for Magic: the Gathering Card Art

I'm a sucker for art from Magic: the Gathering. So, our Rails app will query the Scryfall API for card art (along with identifying names and artists), and render a sampling of 9 images--with a button to refresh and re-query the API.

Rails App Setup

Let's get started by using rails new to create our app:

$ rails new partial-view-demo

After that, let's add a Pages controller, along with an empty index method:

$ rails g controller pages index

By default, this will populate our routes.rb file with a get 'pages/index and get page/index route. For our use case, we'll want both Get and Post requests to / to go to the index method on our Pages controller:

# /config/routes.rb

Rails.application.routes.draw do
  get '/', to: 'pages#index'
  post '/', to: 'pages#index'
end

And, because we'll be using RestClient in our API query, go ahead and add gem 'rest-client to the Gemfile, and update with Bundler:

$ bundle install

Now, let's test our /pages/index.html.erb view with our routes to make sure everything's working:

<%# /app/views/pages/index.html.erb %>

<h1>Pages#index</h1>
<p>Find me in app/views/pages/index.html.erb</p>

<h2>Let's add some Magic: the Gathering card art!</h2>

Run rails s and open up localhost:3000 in your browser:

Perfect! Now let's create some partials as components.

Card Components: _card, _card_image, _card_name, _card_artist

First, we'll add components to render each piece of art on its own card component. These cards will simply have an image, a name, and the artist.

To keep our components organized, create a new /views/pages/cards directory.

We name partials with underscores at the beginning, so we'll create 4 new files in our new directory: _card.html.erb, _card_image.html.erb, _card_name.html.erb, and _card_artist.html.erb.

Heres how our views are looking:

We'll fill out these partials with HTML and ERB like any other view once we have some API data to render.

Form Components: _refresh_button, _refresh_counter

We'll also add a /views/pages/forms directory, where we'll stash a button to refresh our 9 pieces of art, as well as a counter to keep track of how many times we've hit the button. (This will help illustrate how we can pass variables through render partial:.)

Add two files to our new directory: _refresh_button.html.erb, and _refresh_counter.html.erb:

We'll fill these out with our card components shortly.

Controller Methods to Query the API

Before we dive into rendering, here's a quick snapshot of the code used to query the Scryfall API and return 9 random pieces of art:

# /app/controller/pages_controller.rb

class PagesController < ApplicationController
  def index
    session[:img_array] = session[:img_array] || []

    if session[:img_array].empty? || params["button_action"] == "refresh"
      session[:img_array] = get_scryfall_images
    end
  end


  private

  def get_json(url)
    response = RestClient.get(url)
    json = JSON.parse(response)
  end

  def parse_cards(json, img_array)
    data_array = json["data"]
    data_array.each do |card_hash|
      if card_hash["image_uris"]
        img_hash = {
          "image" => card_hash["image_uris"]["art_crop"],
          "name" => card_hash["name"],
          "artist" => card_hash["artist"]
        }
        img_array << img_hash
      end
    end

    if json["next_page"]
      json = get_json(json["next_page"])
      parse_cards(json, img_array)
    end
  end

  def get_scryfall_images
    api_url = "https://api.scryfall.com/cards/search?q="
    img_array = []
    creature_search_array = ["merfolk", "goblin", "angel", "sliver"]

    creature_search_array.each do |creature_str|
      search_url = api_url + "t%3Alegend+t%3A" + creature_str
      json = get_json(search_url)
      parse_cards(json, img_array)

      sleep(0.1)  # per the API documentation: https://scryfall.com/docs/api
    end

    img_array.sample(9)
  end
end

Here, we're using the session variable to store an array of img_hash objects containing the "image" URL, the card's "name", and the "artist" (all as strings).

The API query is set up to look for "legend" card that are also creatures of the type "merfolk", "goblin", "angel", or "sliver"--my favorite creature types! (Sorry, my old beloved elf deck...) Also note that, per the API documentation, a 0.1 second delay is built in-between any searches, for good citizenship.

If we print the contents of session[:img_array] at the end of the index method, here's what we have when we re-navigate to localhost:3000:

# session[:img_array]

    [
     {"image"=>"https://img.scryfall.com/cards/art_crop/front/b/c/bc4c0d5b-6424-44bd-8445-833e01bb6af4.jpg?1562275603", "name"=>"Tuktuk the Explorer", "artist"=>"Volkan Baǵa"}, 
     {"image"=>"https://img.scryfall.com/cards/art_crop/front/9/a/9a8aea2f-1e1d-4e0d-8370-207b6cae76e3.jpg?1562740084", "name"=>"Tiana, Ship's Caretaker", "artist"=>"Eric Deschamps"}, 
     {"image"=>"https://img.scryfall.com/cards/art_crop/front/3/7/37ed04d3-cfa1-4778-aea6-b4c2c29e6e0a.jpg?1559959382", "name"=>"Krenko, Tin Street Kingpin", "artist"=>"Mark Behm"}, 
     {"image"=>"https://img.scryfall.com/cards/art_crop/front/4/2/4256dcc1-0eee-4385-9a5c-70abb212bf49.jpg?1562397424", "name"=>"Slobad, Goblin Tinkerer", "artist"=>"Kev Walker"}, 
     {"image"=>"https://img.scryfall.com/cards/art_crop/front/2/7/27907985-b5f6-4098-ab43-15a0c2bf94d5.jpg?1562728142", "name"=>"Bruna, the Fading Light", "artist"=>"Clint Cearley"}, 
     {"image"=>"https://img.scryfall.com/cards/art_crop/front/7/2/722b1e02-2268-4e02-8d09-9b337da2a844.jpg?1562405249", "name"=>"Vial Smasher the Fierce", "artist"=>"Deruchenko Alexander"}, 
     {"image"=>"https://img.scryfall.com/cards/art_crop/front/8/b/8bd37a04-87b1-42ad-b3e2-f17cd8998f9d.jpg?1562923246", "name"=>"Sliver Legion", "artist"=>"Ron Spears"}, 
     {"image"=>"https://img.scryfall.com/cards/art_crop/front/d/d/dd199a48-5ac8-4ab9-a33c-bbce6f7c9d1b.jpg?1559959197", "name"=>"Zegana, Utopian Speaker", "artist"=>"Slawomir Maniak"}, 
     {"image"=>"https://img.scryfall.com/cards/art_crop/front/d/d/ddb92ef6-0ef8-4b1d-8a45-3064fea23926.jpg?1562854687", "name"=>"Avacyn, Angel of Hope", "artist"=>"Jason Chan"}
    ]

Cool! We have our array of 9 img_hash objects, each with a URL, name, and artist. Now let's render them!

Rendering Partials Inside Views and Other Partials

Render a partial inside a view

Back in our /views/pages/index.html.erb view, we can now use render partial: to access the partials we created.

Let's start by simply rendering a _card_image partial with session[:img_array][0]["image"] supplying the URL:

_card_image.html.erb

<%# /app/views/pages/cards/_card_image.html.erb %>

<%= image_tag(session[:img_array][0]["image"]) %>

index.html.erb

<%# /app/views/pages/index.html.erb %>

<h1>Pages#index</h1>
<p>Find me in app/views/pages/index.html.erb</p>

<h2>Let's add some Magic: the Gathering card art!</h2>

<%= render partial: '/pages/cards/card_image' %>

Note that in render partial:, we drop the underscore from the beginning of _card_image.html.erb and simply call it as card_image (plus its path relative to the views directory).

Cool! Our partial is rendering with the URL from our img_hash.

Render a partial inside another partial

Let's make use of our _card.html.erb partial, and render the _card_image.html.erb partial inside it. We'll also wrap each partial's contents in a <div> so we can see the DOM tree more clearly in our inspector:

index.html.erb

<%# /app/views/pages/index.html.erb %>

<div class="card_container">
    <%= render partial: '/pages/cards/card' %>
</div>

_card.html.erb

<%# /app/views/pages/cards/_card.html.erb %>

<div class="card">
    <h3>This is the _card partial</h3>

    <%= render partial: '/pages/cards/card_image' %>
</div>

_card_image.html.erb

<%# /app/views/pages/cards/_card_image.html.erb %>

<div class="card_image">
    <h4>This is the _card_image partial</h4>

    <%= image_tag(session[:img_array][0]["image"]) %>
</div>

In our browser, with inspector open, we can see that the _card_image partial is its own <div> within the _card partial's <div>:

This is exactly the nested behavior we expected!

Rendering partials multiple times

We can also use render partial: to render the same partial multiple times:

index.html.erb

<%# /app/views/pages/index.html.erb %>

<div class="card_container">
    <%= render partial: '/pages/cards/card' %>
    <%= render partial: '/pages/cards/card' %>
    <%= render partial: '/pages/cards/card' %>
</div>

This results in three cards being created as sibling DOM elements:

Passing Variables to Partials with `locals:`

Instead of accessing our long-winded session[:img_array] variable repeatedly, we can pass variables directly to partials with the locals: option inside render partial:.

In our index.html.erb, let's change our three render partial: lines to include a different img_hash from sessions[:img_array] in each card:

index.html.erb

<%# /app/views/pages/index.html.erb %>

<div class="card_container">
    <%= render partial: '/pages/cards/card', locals: {img_hash: session[:img_array][0]} %>
    <%= render partial: '/pages/cards/card', locals: {img_hash: session[:img_array][1]} %>
    <%= render partial: '/pages/cards/card', locals: {img_hash: session[:img_array][2]} %>
</div>

Now, each _card partial now has a different piece of art to render!

Let's go back and build out our _card partial to render the _card_image, _card_name, and _card_artist partials. Each _card will also use locals: to pass the contents of its img_hash to those partials. (Note that, for ease of reading, we are nesting all these partials inside one <div class="card> tag.)

_card.html.erb

<%# /app/views/pages/cards/_card.html.erb %>

<div class="card">
    <h3>This is the _card partial</h3>

    <%= render partial: '/pages/cards/card_image', locals: {image: img_hash["image"]} %>
    <%= render partial: '/pages/cards/card_name', locals: {name: img_hash["name"]} %>
    <%= render partial: '/pages/cards/card_artist', locals: {artist: img_hash["artist"]} %>
</div>

_card_image.html.erb

<%# /app/views/pages/cards/_card_image.html.erb %>

<%= image_tag(image) %>

_card_name.html.erb

<%# /app/views/pages/cards/_card_name.html.erb %>

<p> Name: <%= name %> </p>

_card_artist.html.erb

<%# /app/views/pages/cards/_card_artist.html.erb %>

<p> Artist: <%= artist %> </p>

Let's check back on localhost:3000 to see if we've got some different cards now:

Perfect! Now, let's try iterating through our whole sessions[:img_array] to display all 9 cards!

Rendering Partials Repeatedly by Iterating with `collection:`

We can refactor our card-rendering code in index.html.erb by adding collection: session[:img_array], as: :img_hash. This will tell Rails to use the array stored in session[:img_array] and pass each object aliased as img_hash to its partial:

index.html.erb

<%# /app/views/pages/index.html.erb %>

<div class="card_container">
    <%= render partial: '/pages/cards/card', collection: session[:img_array], as: :img_hash %>
</div>

Now, we should expect 9 different cards to be rendered at localhost:3000. Since we previously used locals: to pass our hashes with the alias img_hash, our other partials should need no changes:

Success!!

Finishing Up: Adding a Form with a Refresh Button and Counter

Okay, you're probably bored of looking at Tuktuk by now--I know I am! So, let's go ahead and add our _refresh_button and _refresh_counter partials to our index.html.erb:

index.html.erb

<%# /app/views/pages/index.html.erb %>

<div class="refresh_form">
    <%= render partial: '/pages/forms/refresh_button' %>
    <%= render partial: '/pages/forms/refresh_counter', locals: {counter: @refresh_counter} %>
</div>

Since we are passing a @refresh_counter variable through locals:, lets go ahead and define that in our Pages controller:

pages_controller.rb

# /app/controllers/pages/page_controller.rb

  def index
    ...

    session[:refresh_counter] = session[:refresh_counter] || 0

    if params["button_action"] == "refresh"
      session[:refresh_counter] += 1
    end

    @refresh_counter = session[:refresh_counter]
  end

Great! Now our session will keep track of the number of times we've hit the refresh button.

And in our form partials:

_refresh_button.html.erb

<%# /app/views/pages/forms/_refresh_button.html.erb %>

<%= form_for :form_data do |f| %>
    <%= f.button "Refresh", name: "button_action", value: "refresh" %>
<% end %>

_refresh_counter.html.erb

<%# /app/views/pages/forms/_refresh_counter.html.erb %>

<p>Refresh counter: <%= counter %> </p>

Now, our page on displays a Refresh button along with the counter's value:

And hitting refresh will update our cards (and increment the counter by one)!

Conclusion

We've covered how to:

create partial views in Rails
render them with render partial:
pass variables to them with locals:
iterate through collections to repeatedly render a partial with collection:.

(Hopefully, you've seen some good Magic: the Gathering art along the way too!)

Here's the GitHub repo if you're interested in seeing the code or playing around with it yourself: https://github.com/isalevine/devto-rails-partial-view-demo

Got any tips or tricks for using Rails partial views? Please feel free to comment and share below! :)

A Quick Intro to Ruby's Set, Part 2: Object Lookups and Efficiency

Isa Levine — Sun, 20 Oct 2019 05:13:27 +0000

Continuing from the previous article, we will now explore some of Set's methods, and compare their benchmarks with equivalent operations on arrays.

To review, some key details about sets:

All objects in a Set are guaranteed unique (arrays can have duplicates)
Objects in a Set are not ordered (arrays are ordered by index)
Sets are built on top of Hashes for super-fast object lookup (arrays are just dynamic arrays under-the-hood)

Or, summarized by RubyGuides' article on the Set class:

A set is a class that stores items like an array…

But with some special attributes that make it 10x faster in specific situations!

On top of that:

All the items in a set are guaranteed to be unique.

As we will see, my particular benchmarks don't quite reach 10x faster efficiency--but we'll explore situations where sets are certainly more efficient than an array!

Overview

In this second article, we'll compare the following operations between Ruby sets and arrays:

Operations where sets are faster than arrays:

set.include?() vs. array.include?()
set.add() vs. array.push()
set.delete() vs. array.delete()
set.subset?() vs. (array1 & array2) == array2

Operations where sets are slower than arrays:

set.replace() vs. array.replace()
set1 == set2 vs. array1 == array2

Operations where sets are faster than arrays

Let's start with methods where sets are more efficient than arrays.

Note: If you're coding along at home, remember to include require 'benchmark' to avoid an error with the Benchmark class!

`set.include?()` vs. `array.include?()`

Since sets are built on top of Ruby's hash, the .include() method is where they really shine. It simply checks if an element is present, returning a boolean.

The RubyGuides article above reports these benchmarks:

set   include: 8381985.2 i/s
array include: 703305.5  i/s - 11.92x  slower

And goes on to explain:

The reason for this difference is that an array has to check every single element...

...if you have a 1 million element array it's going to be checking 1 million elements every time you call include?.

A set doesn't have to do that.

Here's how we'll be testing it, using the same sets and arrays from our previous article. Each operation will be performed within Benchmark.bm 5 million times, and will be reported with .report. (The large spacing is for pretty-printing in the console!)

n = 5000000

filter_set = Set["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
"them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
filter_array = ["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
    "them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]

Benchmark.bm(34) do |x|
    x.report("Set   .include? (beginning)       :")     { n.times do; filter_set.include?("a")   ; end}
    x.report("Array .include? (beginning)       :")     { n.times do; filter_array.include?("a")   ; end}
    x.report("Set   .include? (middle)          :")     { n.times do; filter_set.include?("they"); end}
    x.report("Array .include? (middle)          :")     { n.times do; filter_array.include?("they"); end}
    x.report("Set   .include? (end)             :")     { n.times do; filter_set.include?("at")  ; end}
    x.report("Array .include? (end)             :")     { n.times do; filter_array.include?("at")  ; end}
end

Above, we have the array checking for an element at the beginning, middle, and end of the array. For kicks, we have the set looking up elements that are hard-coded in the same order--but, because sets are built on top of hashes, there is no object order in a set!

Here's our output:

                                         user     system      total        real
Set   .include? (beginning)       :  0.796039   0.001551   0.797590 (  0.799956)
Array .include? (beginning)       :  0.632907   0.000869   0.633776 (  0.637059)
Set   .include? (middle)          :  0.786981   0.000610   0.787591 (  0.788172)
Array .include? (middle)          :  1.294061   0.001416   1.295477 (  1.298378)
Set   .include? (end)             :  0.792309   0.000866   0.793175 (  0.795283)
Array .include? (end)             :  2.476954   0.002786   2.479740 (  2.484839)

As expected, the array takes longer to find the closer the element is to the end. Meanwhile, the set's lookup time is essentially constant.

In the worst-case scenario, set.include?() will perform over 3x faster than array.include?().

`set.add()` vs. `array.push()`

Next, let's compare the set.add() method introduced in the previous article to array.push().

The array push method will add an element to the end of an array--this is the most efficient way to add elements (assuming you don't have to increase the array's capacity under-the-hood).

set.add(), on the other hand, simply adds a key-value pair to its under-the-hood hash, with the key being the added element, and its value being a boolean true.

Note: In this and several following tests, you'll notice that these operations include a first step of duplicating the original set/array. This is to ensure that the same operation is being performed--as opposed to the set adding an element only once and then rejecting it the other 4999999 times!

n = 5000000

filter_set = Set["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
"them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
filter_array = ["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
    "them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]

Benchmark.bm(34) do |x|
    x.report("Set   .add  (successful)          :") { 
        n.times do
            set = filter_set
            set.add("big")
        end
    }
    x.report("Array .push (successful)          :") { 
        n.times do
            array = filter_array
            array.push("big")                                     
        end
    }
    x.report("Set   .add  (failed)              :") { 
        n.times do
            set = filter_set
            set.add("they")
        end
    }
    x.report("Array .push (if not present)      :") { 
        n.times do
            array = filter_array
            if !array.include?("they")
                array.push("they")
            end   
        end
    }
end

Here's our output:

                                         user     system      total        real
Set   .add  (successful)          :  0.929103   0.000749   0.929852 (  0.931718)
Array .push (successful)          :  0.909708   0.094546   1.004254 (  1.005897)
Set   .add  (failed)              :  0.979433   0.029193   1.008626 (  1.011531)
Array .push (if not present)      :  1.327389   0.001286   1.328675 (  1.330673)

At best, our set adds elements approximately as fast as an array's push. In situations where we need to check an array for an element before adding it, we see sets outperforming arrays by about 36%.

`set.delete()` vs. `array.delete()`

Both set.delete() and array.delete() require a lookup for an element before removing it, so this is a great comparison of their equivalent abilities!

Here's our code:

n = 5000000

filter_set = Set["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
"them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
filter_array = ["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
    "them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]

Benchmark.bm(34) do |x|
    x.report("Set   .delete (beginning)         :") { 
        n.times do 
            set = filter_set
            set.delete("a")           
        end
    }
    x.report("Array .delete (beginning)         :") { 
        n.times do
            array = filter_array
            array.delete("a")
        end
    }
    x.report("Set   .delete (middle)            :") { 
        n.times do 
            set = filter_set
            set.delete("they")        
        end
    }
    x.report("Array .delete (middle)            :") { 
        n.times do
            array = filter_array
            array.delete("they")  
        end
    }
    x.report("Set   .delete (end)               :") { 
        n.times do 
            set = filter_set
            set.delete("at")          
        end
    }
    x.report("Array .delete (end)               :") { 
        n.times do
            array = filter_array
            array.delete("at")    
        end
    }
end

Once again, we're measuring an array's ability to delete elements at their beginning, middle, and end (and illustrating that sets have no such order).

Here's our output:

                                         user     system      total        real
Set   .delete (beginning)         :  0.812703   0.000889   0.813592 (  0.816582)
Array .delete (beginning)         :  1.932468   0.001862   1.934330 (  1.938841)
Set   .delete (middle)            :  0.811337   0.000912   0.812249 (  0.814055)
Array .delete (middle)            :  2.053270   0.001698   2.054968 (  2.059913)
Set   .delete (end)               :  0.813986   0.000986   0.814972 (  0.816330)
Array .delete (end)               :  2.203437   0.002076   2.205513 (  2.210077)

As expected, sets can delete elements in constant time. Interestingly, arrays are able to delete elements at the end almost as fast as ones at their beginning!

`set.subset?()` vs. `(array1 & array2) == array2`

One of sets' most useful features is the subset? method. A subset is a set where all of its elements are also elements of its superset.

While arrays don't have an exactly equivalent method, this excellent StackOverflow answer illustrates how the array & method can be used for the same effect.

Here's our code:

n = 5000000

filter_set = Set["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
"them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
filter_array = ["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
    "them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
sub_set = Set["a", "they", "at"]
sub_array = ["a", "they", "at"]
replace_set = Set["big", "sword", "knight"]
replace_array = ["big", "sword", "knight"]

Benchmark.bm(34) do |x|
    x.report("Set   .subset?          (true)    :")     { n.times do; sub_set.subset?(filter_set)                       ; end}
    x.report("Array (a1 & a2) == a2   (true)    :")     { n.times do; (filter_array & sub_array) == sub_array           ; end}
    x.report("Set   .subset?          (false)   :")     { n.times do; replace_set.subset?(filter_set)                   ; end}
    x.report("Array (a1 & a2) == a2   (false)   :")     { n.times do; (filter_array & replace_array) == replace_array   ; end}    
end

Our code compares sets and arrays in situations where subset? and (a1 & a2) == a2 return both true and false.

Here's our output:

                                         user     system      total        real
Set   .subset?          (true)    :  2.076477   0.001450   2.077927 (  2.080519)
Array (a1 & a2) == a2   (true)    :  7.961141   0.180642   8.141783 (  8.158982)
Set   .subset?          (false)   :  1.554540   0.001360   1.555900 (  1.558715)
Array (a1 & a2) == a2   (false)   :  5.280627   0.006986   5.287613 (  5.297066)

Wow! In both situations, we see sets performing subset? over 3x as fast as the array's equivalent!

Operations where sets are slower than arrays

Now, let's turn our attention to some situations where sets do not perform as well as arrays.

Unfortunately, I cannot offer under-the-hood explanations for these results at this time. Please feel free to comment below and share your wisdom of why arrays outperform sets in the following operations! :)

`set.replace()` vs. `array.replace()`

In both structures, the replace method completely replaces the contents of the given structure with the elements from a supplied enumerable. In our code, we will be replacing a set with a set, and an array with an array.

Here's our code:

n = 5000000

filter_set = Set["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
"them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
filter_array = ["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
    "them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
replace_set = Set["big", "sword", "knight"]
replace_array = ["big", "sword", "knight"]

Benchmark.bm(34) do |x|
    x.report("Set   .replace                    :")     { n.times do; filter_set.replace(replace_set)       ; end}
    x.report("Array .replace                    :")     { n.times do; filter_array.replace(replace_array)   ; end}
end

Here's our output:

                                         user     system      total        real
Set   .replace                    :  2.318287   0.001841   2.320128 (  2.327267)
Array .replace                    :  0.441079   0.000528   0.441607 (  0.442994)

Ouch! Arrays implement replace 5x faster than sets! As stated above, I'd love to have someone fill me in on why!

`set1 == set2` vs. `array1 == array2`

Finally, let's look at ==, where each pair of structures is checked for having the same elements--and for arrays, the same order. Once again, we will benchmark both true and false situations for each.

Here's our code:

n = 5000000

filter_set = Set["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
"them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
filter_array = ["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
    "them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
match_set = Set["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
"them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
match_array = ["a", "an", "the", "and", "is", "of", "to", "be", "in", "they", "their", 
    "them", "or", "if", "this", "like", "had", "but", "what", "with", "at",
]
replace_set = Set["big", "sword", "knight"]
replace_array = ["big", "sword", "knight"]

Benchmark.bm(34) do |x|
    x.report("Set   ==  (true)                  :")     { n.times do; filter_set == match_set       ; end}
    x.report("Array ==  (true)                  :")     { n.times do; filter_array == match_array   ; end}
    x.report("Set   ==  (false)                 :")     { n.times do; filter_set == replace_set     ; end}
    x.report("Array ==  (false)                 :")     { n.times do; filter_array == replace_array ; end}
end

Here's our output:

                                         user     system      total        real
Set   ==  (true)                  :  7.219614   0.004376   7.223990 (  7.234709)
Array ==  (true)                  :  4.119128   0.003112   4.122240 (  4.128884)
Set   ==  (false)                 :  1.097661   0.000751   1.098412 (  1.099235)
Array ==  (false)                 :  0.391299   0.000482   0.391781 (  0.393029)

In the best case, array's perform better than sets by about 75% when checking for true cases--and at worst, for false situations, arrays check about 275% faster than sets! Equality is definitely a situation to prefer arrays over sets. (Anyone care to explain why? <3)

Conclusion

Now you're more familiar with Set's methods and cases where they may be advantageous to arrays! The two key situations to look for are:

Needing to check via include? in a collection of unique elements
Needing to check for subsets of elements

Thanks for reading!

Links and Sources

Excellent introduction to Ruby Sets by Al Scott

Ruby docs - Sets

RubyGuides intro to Sets

DotNetPerls - Ruby Set examples

DEV Community: Isa Levine

How To Build an Event Sourcing Pattern in Rails from Scratch

To Recap: What is Event Sourcing?

What this article covers

Getting our Rails app up and running

Let’s go ahead and create our new Rails app

Let’s add our User model

Add a User controller and routes

Run database migrations

Setting up our environment to test our Events

Set up Postico to view our PostgreSQL database

Set up Insomnia to send HTTP requests

Testing the create action with byebug and Insomnia

What is an Event?

The Events::BaseEvent

abstract_class

apply(aggregate) and apply_and_persist

after_initialize and event_type

self.payload_attributes(*attributes)

find_or_build_aggregate

aggregate setters, getters, and get-its-namers

Okay, let’s see the whole Events::BaseEvent!

The user_events table, and the Events::User::BaseEvent

user_events table

Events::User::BaseEvent

belongs_to :user and has_many :events

Creating a new User with Events::User::Created

Build the Events::User::Created class

Add logic to the apply method

Update our controller to create an Event and use strong params

Let’s test our event with Insomnia and Postico!

Destroying a User with Events::User::Destroyed

Create an app/models/events/user/destroyed.rb file

Update the destroy action in users_controller

Test a DELETE request in Insomnia

Conclusion

Next Up

References

Building an Event Sourcing System in Rails, Part 1: What is Event Sourcing?

What is Event Sourcing?

Examples of Event Sourcing

Some implications of using an Event Sourcing system

Next Up

References

Hi Folks, Good to be Back!

Hi, Dev.to folks! Hope you’ve all been well and are staying safe!

There are three things I plan to write about:

What Happened to Video Games Having In-Game CLI Consoles?

Okay, sorry for the clickbait-y title...I know in-game consoles were never really common per se, and I'm writing this because of I've been relying on the console to fix bugs in Skyrim...

But still, the question stands: why don't we see in-game consoles more frequently in video games today?

Popular drop-down console box started with Quake (1996), for logs and cheats

Why aren't consoles like Quake's more common in video games today?

Modern example

Links and sources

Got any pieces of in-game console history (or favorite cheats) to share? Please comment below! <3

Intro to RSpec in Rails (part 2): Improving Tests with `let` and `context`

Use let to wrap your testing variables

before or let

Sidenote from BetterSpecs -- this is how they describe let working under-the-hood:

Let's go ahead and update our code with let, and run the test:

Using context for different cases

Use case: context "success" and context "failure"

Let's add a uniqueness validation for :name to our Character model:

And in RandomCharacterGenerator.new_character(), let's add a rescue that returns our error-message string:

Running our tests now:

Using it { expect } syntax with context

However, this strategy is best used for one-expectation tests. Our "failure (non-unique name)" test currently relies on two expect lines inside the same it block, so this would NOT work:

So, our final successful test code looks like this:

Conclusion

Thanks to Andrew Brown for his incredibly helpful comment on my previous post!

Additional thanks to Masaki Matsuo and Amy Pivo for helping me practice writing better RSpec tests this week!

Further reading/links/resources about RSpec testing:

Got any tips, tricks, or instances for testing with RSpec? Please feel free to comment and share below! <3

Intro to RSpec in Rails (part 1): Basic Syntax and Strategy for Testing

Behavior-Driven Development (BDD)

RSpec

Adding RSpec to a new or existing Rails app

Starting a new Rails app with no test tool, and adding RSpec

Migrate an existing Rails app with default test-unit to RSpec

Running RSpec tests

Let’s add our `User` model

Add a `User` controller and routes

Testing the `create` action with `byebug` and Insomnia

The `Events::BaseEvent`

`abstract_class`

`apply(aggregate)` and `apply_and_persist`

`after_initialize` and `event_type`

`self.payload_attributes(*attributes)`

`find_or_build_aggregate`

`aggregate` setters, getters, and get-its-namers

Okay, let’s see the whole `Events::BaseEvent`!

The `user_events` table, and the `Events::User::BaseEvent`

`user_events` table

`Events::User::BaseEvent`

`belongs_to :user` and `has_many :events`

Creating a new User with `Events::User::Created`

Build the `Events::User::Created` class

Add logic to the `apply` method

Destroying a User with `Events::User::Destroyed`

Create an `app/models/events/user/destroyed.rb` file

Update the `destroy` action in `users_controller`

Use `let` to wrap your testing variables

`before` or `let`

Sidenote from BetterSpecs -- this is how they describe `let` working under-the-hood:

Let's go ahead and update our code with `let`, and run the test:

Using `context` for different cases

Use case: `context "success"` and `context "failure"`

Let's add a uniqueness validation for `:name` to our Character model:

And in `RandomCharacterGenerator.new_character()`, let's add a `rescue` that returns our error-message string:

Using `it { expect }` syntax with `context`

However, this strategy is best used for one-expectation tests. Our "failure (non-unique name)" test currently relies on two `expect` lines inside the same `it` block, so this would NOT work:

Migrate an existing Rails app with default `test-unit` to RSpec

RSpec building blocks: `describe` and `it`

Setting clear `expect`ations

Common RSpec strategy: (1) pick a class, (2) pick a method, (3) outline expected behaviors, (4) write one `it` block per behavior

1. `it "creates a new Character instance"`

2. `it "randomly allocates all 9 stat points between (strength, dexterity, intelligence, charisma)"`

3. `it "allocates stat points so they do not exceed max roll 6"`

4. `it "saves the Character to the database"`

Case 1: communicating intent and context of variables during `Character.new()`

Case 2: debugging values step-by-step during iteration in `roll_stats()`

Passing Variables to Partials with `locals:`