Mutations Ruby Library

To create a new business logic operation, subclass Mutations::Command. You define your input schema using required and optional blocks, and implement the core logic in the execute method. The execute method is only called if all input validations pass.

class UserSignup < Mutations::Command

  # Required inputs
  required do
    string :email, matches: EMAIL_REGEX
    string :name
  end

  # Optional inputs
  optional do
    boolean :newsletter_subscribe
  end

  # Business logic
  def execute
    user = User.create!(inputs)
    NewsletterSubscriptions.create(email: email, user_id: user.id) if newsletter_subscribe
    UserMailer.async(:deliver_welcome, user.id)
    user
  end
end

You can install the mutations gem via the command line or by adding it to your Gemfile.

gem install mutations

Or add it to your Gemfile:

gem 'mutations'

When defining a HashFilter schema, you use blocks to specify the scope of the keys being defined:

• required(&block): Defines keys that must be present in the input data. If a required key is missing, the filter will return a :required error.
• optional(&block): Defines keys that may or may not be present. If an optional key is missing, it is simply ignored (unless it has a default value).

Switching between these blocks changes the internal @current_inputs pointer used by the DSL.

To implement a business action, create a class that inherits from Mutations::Command. You must define which inputs are required and which are optional using the class methods provided. You should also override the execute method to contain your business logic and optionally override the validate method for custom validation logic.

Inputs defined via required or optional are automatically accessible via getter and setter methods on the command instance.

Inside the execute method, you can access inputs via self.inputs (a hash with indifferent access) or via helper methods named after the input keys.

Input helpers:

• self.email: Returns the value of the email input.
• self.email=(val): Allows setting the value (rarely used).
• self.email_present?: Returns true if the input was provided (useful for optional inputs).

Adding errors: You can add errors manually inside the execute method or a validate method using add_error(key, symbolic_error, message).

# Inside execute
def execute
  if email =~ /aol.com/
    add_error(:email, :old_school, "Wow, you still use AOL?")
    return
  end
end

# Inside validate (prevents execute from running)
def validate
  if password != password_confirmation
    add_error(:password_confirmation, :doesnt_match, "Your passwords don't match")
  end
end

The .run and .run! methods accept hashes as arguments. You can pass multiple hashes, which will be merged together. Later hashes take precedence over earlier ones. This is useful for merging unsafe user input with safe server-side data.

# A user comments on an article
class CreateComment < Mutations::Command
  required do
    model :user
    model :article
    string :comment, max_length: 500
  end

  def execute; ...; end
end

def somewhere
  # params[:comment] might contain a 'user' key, but it will be overwritten by the second hash
  outcome = CreateComment.run(params[:comment], 
    user: current_user, 
    article: Article.find(params[:article_id])
  )
end

Inside a Mutations::Command subclass, use required and optional blocks to define the expected input types and validations. Supported types include string, symbol, integer, boolean, array, hash, model, and more.

Required inputs:

required do
  string :name, max_length: 10
  symbol :state, in: %i(AL AK AR ... WY)
  integer :age
  boolean :is_special, default: true
  model :account
end

Optional inputs:

optional do
  array :tags, class: String
  hash :prefs do
    boolean :smoking
    boolean :view
  end
end

The Mutations::TimeFilter is used to validate and sanitize time-related inputs. It can coerce strings, dates, or date-times into Time objects and enforce range constraints.

Available configuration options:

• :nils: Boolean. If true, an explicit nil input is considered valid. Defaults to false.
• :format: String. If provided, Time.strptime is used with this format for coercion. If nil, Time.parse is used. Defaults to nil.
• :after: Time object. Represents the minimum allowed time (inclusive). If the input is earlier than or equal to this value, validation fails.
• :before: Time object. Represents the maximum allowed time (inclusive). If the input is later than or equal to this value, validation fails.

The Mutations::DateFilter is used to validate and sanitize date inputs. It can be configured with several options to handle nil values, empty strings, specific date formats, and range constraints.

When filter(data) is called, it returns an array containing [processed_value, error_code]. If the input is valid, the error code is nil. If invalid, the error code indicates the reason (e.g., :nils, :empty, :date, :after, or :before).