hotstepper 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b07ab5ad5f621350aee538dc060af2fc9d979834b5c2d9fc39ff5bb7f710194
+  data.tar.gz: 5c05a8274192ab24505ab8f5e2badf3a87c04876d7d2694152747640c25b722f
+SHA512:
+  metadata.gz: b8ff6783c1f8d2055281bf584ee022b86556637bab39e8dd354526e12fa3f8f1c7cff83e63a1009c4438c183aa1396255fc68cde8fdcc626bea2adf735ae98f4
+  data.tar.gz: 9f3dea435adb87f761e4f6a00e807b1568248eae2a990e6359c06457a4ebbdc3b3623e445fa1fd484964faf8d42bd5e5492706bb67a9108f160201b26cf78108

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Alexa Grey
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,36 @@
+# Hotstepper
+
+Hotstepper is a slightly opinionated framework that is built atop Rails and
+combines several [dry-rb](https://dry-rb.org/) libraries in order to simplify
+certain service-oriented design patterns. These are patterns I've developed
+over years and like Rails itself, hotstepper been extracted from use in
+real-world applications.
+
+## Usage
+
+While the code in here is stable and tested, this is not really intended for public consumption yet.
+
+Documentation will come at a later date.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "hotstepper"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install hotstepper
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/validators/unique_items_validator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# A validator for ensuring that a given array has only unique items.
+#
+# It relies on [`Array#uniq`](https://ruby-doc.org/core-3.0.2/Array.html#method-i-uniq),
+# so if checking an array of POROs, ensure that their `#eql?` methods are implemented
+# correctly. (`Dry::Core::Equalizer` provides this out-of-the-box for most use cases).
+class UniqueItemsValidator < ActiveModel::EachValidator
+  # @param [ActiveModel::Validations, #errors] record
+  # @param [Symbol] attribute
+  # @param [Array, #to_a] value
+  # @return [void]
+  def validate_each(record, attribute, value)
+    # :nocov:
+    return if value.blank?
+    # :nocov:
+
+    arr = Array(value)
+
+    unique_count = arr.uniq.size
+
+    total_count = arr.size
+
+    diff = total_count - unique_count
+
+    record.errors.add attribute, :duplicate_items, count: diff unless diff.zero?
+  end
+
+  # @api private
+  # @note Used in tests.
+  class TestModel
+    include ActiveModel::Model
+    include ActiveModel::Validations
+
+    # @return [Array]
+    attr_accessor :items
+
+    validates :items, unique_items: true
+  end
+end

data/config/locales/custom-predicates.en.yml

@@ -0,0 +1,70 @@
+# custom predicates implemented for dry-logic
+# we can't use YAML aliases because psych requires it to be turned on somewhere else
+# than the Rails engine.
+en:
+  dry_schema:
+    errors:
+      any_uuid?: "must be a UUID"
+
+      email?: "must be an email"
+
+      global_id?: "must be a GlobalID"
+
+      global_id_uri?: "must be a GlobalID URI"
+
+      has_model_name?: "must be a named ActiveModel object"
+
+      http_uri?: "must be a valid HTTP or HTTPS url"
+
+      https_uri?: "must be a valid HTTPS url"
+
+      instance_named?: "must be an instance of %{instance_name}"
+
+      model?: "must be a model"
+
+      model_class?: "must be a model class"
+
+      model_class_list?: "must be an array of model classes"
+
+      model_list?: "must be an array of models"
+
+      model_named?: "must be a model of type %{model_name}"
+
+      rails_blank?: "must be blank"
+
+      rails_present?: "cannot be blank"
+
+      uri?: "must be a valid URI"
+  dry_validation:
+    errors:
+      any_uuid?: "must be a UUID"
+
+      email?: "must be an email"
+
+      global_id?: "must be a GlobalID"
+
+      global_id_uri?: "must be a GlobalID URI"
+
+      has_model_name?: "must be a named ActiveModel object"
+
+      http_uri?: "must be a valid HTTP or HTTPS url"
+
+      https_uri?: "must be a valid HTTPS url"
+
+      instance_named?: "must be an instance of %{instance_name}"
+
+      model?: "must be a model"
+
+      model_class?: "must be a model class"
+
+      model_class_list?: "must be an array of model classes"
+
+      model_list?: "must be an array of models"
+
+      model_named?: "must be a model of type %{model_name}"
+
+      rails_blank?: "must be blank"
+
+      rails_present?: "cannot be blank"
+
+      uri?: "must be a valid URI"

data/config/locales/dry-validation-errors.en.yml

@@ -0,0 +1,113 @@
+en:
+  dry_validation:
+    or: "or"
+
+    errors:
+      acceptance: "must accept %{key}"
+
+      unexpected_key: "is not allowed"
+
+      array?: "must be an array"
+
+      empty?: "must be empty"
+
+      excludes?: "must not include %{value}"
+
+      excluded_from?:
+        arg:
+          default: "must not be one of: %{list}"
+          range: "must not be one of: %{list_left} - %{list_right}"
+
+      exclusion?: "must not be one of: %{list}"
+
+      eql?: "must be equal to %{left}"
+
+      not_eql?: "must not be equal to %{left}"
+
+      filled?: "must be filled"
+
+      format?: "is in invalid format"
+
+      number?: "must be a number"
+
+      odd?: "must be odd"
+
+      even?: "must be even"
+
+      gt?: "must be greater than %{num}"
+
+      gteq?: "must be greater than or equal to %{num}"
+
+      hash?: "must be a hash"
+
+      included_in?:
+        arg:
+          default: "must be one of: %{list}"
+          range: "must be one of: %{list_left} - %{list_right}"
+
+      inclusion?: "must be one of: %{list}"
+
+      includes?: "must include %{value}"
+
+      bool?: "must be boolean"
+
+      true?: "must be true"
+
+      false?: "must be false"
+
+      int?: "must be an integer"
+
+      float?: "must be a float"
+
+      decimal?: "must be a decimal"
+
+      date?: "must be a date"
+
+      date_time?: "must be a date time"
+
+      time?: "must be a time"
+
+      key?: "is missing"
+
+      attr?: "is missing"
+
+      lt?: "must be less than %{num}"
+
+      lteq?: "must be less than or equal to %{num}"
+
+      max_size?: "size cannot be greater than %{num}"
+
+      max_bytesize?: "bytesize cannot be greater than %{num}"
+
+      min_size?: "size cannot be less than %{num}"
+
+      min_bytesize?: "bytesize cannot be less than %{num}"
+
+      nil?: "cannot be defined"
+
+      str?: "must be a string"
+
+      type?: "must be %{type}"
+
+      respond_to?: "must respond to %{method}"
+
+      size?:
+        arg:
+          default: "size must be %{size}"
+          range: "size must be within %{size_left} - %{size_right}"
+
+        value:
+          string:
+            arg:
+              default: "length must be %{size}"
+              range: "length must be within %{size_left} - %{size_right}"
+
+      bytesize?:
+        arg:
+          default: "must be %{size} bytes long"
+          range: "must be within %{size_left} - %{size_right} bytes long"
+
+      uuid_v4?: "is not a valid UUID"
+
+      not:
+        empty?: "cannot be empty"

data/config/locales/en.yml

@@ -0,0 +1,14 @@
+---
+en:
+  activemodel:
+    errors:
+      models:
+        hotstepper/support/generators/step_definition:
+          attributes:
+            name:
+              invalid: "must be all lowercase, starts with a letter, and can only contain letters, numbers, and underscores"
+  errors:
+    messages:
+      duplicate_items:
+        one: "has a duplicate item"
+        other: "has %{count} duplicate items"

data/config/routes.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+end

data/lib/boot/setup.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "active_support/all"
+require "active_model"
+require "active_model/callbacks"
+require "active_model/model"
+require "active_model/naming"
+require "active_model/validations"
+require "active_record"
+
+require "dry/auto_inject"
+require "dry/configurable"
+require "dry/container"
+require "dry/core/class_attributes"
+require "dry/core/constants"
+require "dry/initializer"
+require "dry/matcher/result_matcher"
+require "dry/monads/all"
+require "dry/schema"
+require "dry/struct"
+require "dry/types"
+require "dry/validation"
+
+require "pathname"
+
+require "rails/engine"
+
+require "uri"
+
+require "zeitwerk"
+
+Dry::Schema.load_extensions :hints
+Dry::Schema.load_extensions :info
+Dry::Schema.load_extensions :monads
+Dry::Types.load_extensions :monads
+Dry::Validation.load_extensions :monads
+Dry::Validation.load_extensions :predicates_as_macros
+
+Dry::Logic::Predicates.predicate :any_uuid? do |input|
+  str?(input) && (
+    uuid_v1?(input) ||
+      uuid_v2?(input) ||
+      uuid_v3?(input) ||
+      uuid_v4?(input) ||
+      uuid_v5?(input) ||
+      uuid_v6?(input) ||
+      uuid_v7?(input) ||
+      uuid_v8?(input)
+  )
+end
+
+# A constraint for dry types to be able to match dry types,
+# for when you need to type types typingly.
+Dry::Logic::Predicates.predicate :dry_type? do |input|
+  type?(Dry::Types::Type, input)
+end
+
+# `#blank?` in constraints.
+Dry::Logic::Predicates.predicate :rails_blank? do |input|
+  input.blank?
+end
+
+# `#present?` in constraints.
+Dry::Logic::Predicates.predicate :rails_present? do |input|
+  input.present?
+end
+
+# Override the built-in `filled?` predicate to use Rails' definition of presence,
+# which is more strict than Dry's default.
+Dry::Logic::Predicates.predicate :filled? do |input|
+  rails_present?(input)
+end
+
+# This is pretty loose, since it allows things like `foo@bar`,
+# but it catches most things.
+Dry::Logic::Predicates.predicate :email? do |input|
+  str?(input) && format?(Hotstepper::Patterns::EMAIL, input)
+end
+
+# A matcher for a GlobalID URI string, like `gid://app/User/1`.
+Dry::Logic::Predicates.predicate :global_id_uri? do |input|
+  str?(input) && format?(Hotstepper::Patterns::GlobalID, input)
+end
+
+# A matcher for a GlobalID string or instance.
+Dry::Logic::Predicates.predicate :global_id? do |input|
+  return false if rails_blank?(input) || !(global_id_uri?(input) || type?(::GlobalID, input))
+
+  gid = GlobalID.parse input
+
+  return false if gid.blank?
+
+  begin
+    gid.model_class.present?
+  rescue NameError
+    false
+  end
+end
+
+# A matcher for an HTTP (or HTTPS) URI string, like `http://example.com`.
+Dry::Logic::Predicates.predicate :http_uri? do |input|
+  str?(input) && format?(Hotstepper::Patterns::HTTP, input)
+end
+
+# A matcher for an HTTPS URI string, like `https://example.com`.
+Dry::Logic::Predicates.predicate :https_uri? do |input|
+  str?(input) && format?(Hotstepper::Patterns::HTTPS, input)
+end
+
+Dry::Logic::Predicates.predicate :inherits? do |parent, input|
+  type?(Class, input) && input < parent
+end
+
+Dry::Logic::Predicates.predicate :model? do |input|
+  type?(ActiveRecord::Base, input)
+end
+
+Dry::Logic::Predicates.predicate :model_list? do |input|
+  array?(input) && input.all? { |elm| model? elm }
+end
+
+Dry::Logic::Predicates.predicate :model_class? do |input|
+  inherits?(ActiveRecord::Base, input)
+end
+
+Dry::Logic::Predicates.predicate :model_class_list? do |input|
+  array?(input) && input.all? { |elm| model_class?(input) }
+end
+
+Dry::Logic::Predicates.predicate :has_model_name? do |input|
+  attr?(:model_name, input) && !none?(input.model_name) && type?(ActiveModel::Name, input.model_name)
+end
+
+Dry::Logic::Predicates.predicate :relation? do |input|
+  type?(ActiveRecord::Relation, input)
+end
+
+Dry::Logic::Predicates.predicate :relation_for? do |model_klass, input|
+  relation?(input) && (
+    (model_class?(model_klass) && input.model <= model_klass) ||
+      (dry_type?(model_klass) && model_klass.valid?(input.model))
+  )
+end
+
+Dry::Logic::Predicates.predicate :instance_named? do |name, input|
+  input.class.name == name
+end
+
+Dry::Logic::Predicates.predicate :model_named? do |model_name, input|
+  has_model_name?(input) && input.model_name == model_name
+end

data/lib/generators/hotstepper/service/USAGE

@@ -0,0 +1,17 @@
+Description:
+    Create a service and operation pair using Hotstepper conventions.
+
+    The operation class will be a Hotstepper::Operation that
+    forwards all arguments passed to `#call` on to the wrapped
+    service, and then calls the service instance's own `#call` method.
+
+    The service will inherit from `Hotstepper::Service` by default,
+    and execute its defined steps with the ability to halt execution
+    based on the monadic result of each step.
+
+Example:
+    bin/rails generate hotstepper:service Some::Namespace Create Creator
+
+    This will create:
+        app/operations/some/namespace/create.rb
+        app/services/some/namespace/creator.rb

data/lib/generators/hotstepper/service/service_generator.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  # Generate a service and operation pair using Hotstepper conventions.
+  class ServiceGenerator < Rails::Generators::Base
+    include Hotstepper::Support::Generators::Common
+    include Hotstepper::Support::Generators::Namespaced
+
+    source_root File.expand_path("templates", __dir__)
+
+    DEFAULT_PARENT = "Hotstepper::Service"
+
+    DEFAULT_STEPS = ["prepare"].freeze
+
+    argument :operation_name, type: :string, required: true,
+      desc: "a verb, e.g. Create"
+
+    argument :service_name, type: :string, required: true,
+      desc: "a noun, e.g. Creator"
+
+    class_option :abstract, type: :boolean, default: false,
+      desc: <<~TEXT.strip.squish
+      Whether to generate an abstract service and skip generating the operation. Implies --skip-operation and --skip-service-implementation.
+      TEXT
+
+    class_option :parent, type: :string, required: true,
+      default: DEFAULT_PARENT,
+      desc: "The abstract class to inherit from."
+
+    class_option :operation, type: :boolean,
+      desc: "Whether to generate the operation."
+
+    class_option :service_implementation, type: :boolean,
+      desc: "Whether to generate the service implementation. Defaults to false if --abstract or if --parent is not the default."
+
+    class_option :steps, type: :array,
+      desc: %{The steps to define on the service. Defaults to `["prepare"]` unless --abstract.}
+
+    class_option :matcher, type: :boolean, default: false,
+      desc: "Whether to activate dry-matcher on the operation."
+
+    def prepare!
+      set_up_namespace!
+
+      @parent_service_class = options[:parent].presence || DEFAULT_PARENT
+
+      @skip_operation = determine_whether_to_skip_operation
+
+      @skip_service_implementation = determine_whether_to_skip_service_implementation
+
+      @steps = parse_steps(options[:steps].presence || default_steps)
+
+      @operation = namespaced_file(operation_name)
+
+      @service = namespaced_file(service_name)
+    end
+
+    def generate_files!
+      validate_steps!
+    rescue StepsInvalid => e
+      say_status :error, e.message
+    else
+      unless skip_operation?
+        template "operation.rb", operation.to_operation_path
+      end
+
+      template "service.rb", service.to_service_path
+    end
+
+    private
+
+    def abstract? = options[:abstract]
+
+    def default_steps = inheriting_from_other_parent? ? [] : DEFAULT_STEPS
+
+    # @param [<String>] raw_steps
+    # @return [<Hotstepper::Support::Generators::StepDefinition>]
+    def parse_steps(raw_steps) = Hotstepper::Support::Generators::StepDefinition.parse_many(raw_steps)
+
+    # @return [Boolean]
+    def determine_whether_to_skip_operation
+      return options[:operation].blank? if options.key?(:operation)
+
+      abstract?
+    end
+
+    # @return [Boolean]
+    def determine_whether_to_skip_service_implementation
+      return options[:service_implementation].blank? if options.key?(:service_implementation)
+
+      inheriting_from_other_parent?
+    end
+
+    def inheriting_from_other_parent? = parent_service_class != DEFAULT_PARENT
+
+    # @return [String]
+    attr_reader :parent_service_class
+
+    # @return [Hotstepper::Support::FileWrapper]
+    attr_reader :operation
+
+    # @return [Hotstepper::Support::FileWrapper]
+    attr_reader :service
+
+    # @return [Boolean]
+    attr_reader :skip_operation
+
+    alias skip_operation? skip_operation
+
+    # @return [Boolean]
+    attr_reader :skip_service_implementation
+
+    alias skip_service_implementation? skip_service_implementation
+
+    # @return [<Hotstepper::Support::Generators::StepDefinition>]
+    attr_reader :steps
+
+    def use_dry_matcher? = options[:matcher]
+
+    def validate_steps!
+      _, invalid = steps.partition(&:valid?)
+
+      return if invalid.empty?
+
+      invalid.each do |step|
+        say_status :error, "Invalid step: #{step.name.inspect}"
+        step.errors.full_messages.each do |message|
+          say_status :error, "  #{message}"
+        end
+      end
+
+      raise StepsInvalid, "One or more step definitions were invalid. See above for details."
+    end
+
+    class StepsInvalid < StandardError; end
+  end
+end

data/lib/generators/hotstepper/service/templates/operation.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+<%- nest_under_namespace do -%>
+# @see <%= service.full_name %>
+# @!method call
+#   @return [Dry::Monads::Result]
+class <%= operation.name %> < Hotstepper::Operation
+  wraps_service! ::<%= service.full_name %><%- if use_dry_matcher? -%>, with_matcher: true<%- end %>
+end
+<%- end -%>

data/lib/generators/hotstepper/service/templates/service.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+<%- nest_under_namespace do -%>
+<%- if abstract? -%>
+# @abstract
+<%- end -%>
+<%- unless skip_operation? -%>
+# @see <%= operation.full_name %>
+<%- end -%>
+class <%= service.name %> < <%= parent_service_class %>
+<%- unless skip_service_implementation? -%>
+  include Dry::Initializer[undefined: false].define -> do
+  end
+
+  # @return [Dry::Monads::Result]
+  def call
+    run_callbacks :execute do
+    <%- steps.each do |step| -%>
+      yield <%= step.name! %>
+    <%- end -%>
+    end
+
+    Success()
+  end
+<%- end -%>
+<%- steps.each do |step| -%>
+<%- unless skip_service_implementation? && step.index == 0 -%>
+
+<%- end -%>
+<%- if step.abstract? -%>
+  step! <%= step.name.inspect %>
+<%- else -%>
+  step! def <%= step.name %>
+    Success()
+  end
+<%- end -%>
+<%- end -%>
+end
+<%- end -%>

data/lib/generators/hotstepper/typespace/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Generate a typespace within a namespace for a subdivision of the application.
+
+Example:
+    bin/rails generate typespace Things
+
+    This will create:
+        app/services/things/types.rb

data/lib/generators/hotstepper/typespace/templates/types.rb.tt

@@ -0,0 +1,5 @@
+<%- nest_under_namespace do -%>
+module <%= types.name %>
+  extend Hotstepper::Typespace
+end
+<%- end -%>