operations 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37feed93ae3f90b8e08f2ab960faf4195c8891e6bc4d60a78d03666c5c035de3
-  data.tar.gz: 29b2bad869d32e4bf22f188eb4c57a199300a315431f373d5cf988f15f63ab8b
+  metadata.gz: affb68a66ecbc1ee0e687ab13efb202037d10054adb114e684e775224957b65e
+  data.tar.gz: 255180d0be3704a73c0bf6e148658df8b662e33a4508dff3ae3fee819e73caba
 SHA512:
-  metadata.gz: 186e9327e813bbf7ddd5d5aea52b5bf00cc7a62a9c8b235b7fd25f36585a2468192922df3ff9435d7320b164807e31acf73523eaf9b106c67de6f2f27da19400
-  data.tar.gz: 43d61db8dbe71a4f9269755a6fc73c46214ba3baddeed80e650a7ae2ced43c08fb361dd19cef005954504970c06bfa573a1a55f760e7ac711c68c19f4e34601b
+  metadata.gz: 9f639386ccb6d003909737a4606b44f21cf49dc90b36fe0c854ea1e8c824049b2de7a70c480b44b2f4713558f21417c755361b6fccad4ed2f2af1068bc7cd135
+  data.tar.gz: a24d378627511c1198728a9aebe38c7f39cb057756e957906df29bf059804eef94d1188146b845842be42d94c559ebccd84b3d4d6a613b95a2a31d427771fe09

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2024-05-05 08:51:48 UTC using RuboCop version 1.59.0.
+# on 2024-08-07 02:24:58 UTC using RuboCop version 1.65.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -22,14 +22,14 @@ Metrics/AbcSize:
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 145
+  Max: 149
 
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ModuleLength:
-  Max: 142
+  Max: 141
 
-# Offense count: 2
+# Offense count: 3
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 7

data/CHANGELOG.md

@@ -1,10 +1,27 @@
 # Changelog
 
-## [0.7.0](https://github.com/BookingSync/operations/tree/main)
+## [0.7.2](https://github.com/BookingSync/operations/tree/v0.7.2)
 
 ### Added
 
-- Implement new forms system detaching it from operations [\#47](https://github.com/BookingSync/operations/pull/47) ([pyromaniac](https://github.com/pyromaniac))
+- Allow referencing and arbitrary model attrbiute from form object attribute with `model_name: "Post#title"` [\#50](https://github.com/BookingSync/operations/pull/50) ([pyromaniac](https://github.com/pyromaniac))
+- Allow passing multiple `hydrators:` to Operations::Form [\#49](https://github.com/BookingSync/operations/pull/49) ([pyromaniac](https://github.com/pyromaniac))
+
+### Improvements
+
+- Change default form hydration behavior - it is now deep merging params after hydration, so no need to do it in the hydrator. Controlled with `hydration_merge_params:` option. [\#49](https://github.com/BookingSync/operations/pull/49) ([pyromaniac](https://github.com/pyromaniac))
+
+## [0.7.1](https://github.com/BookingSync/operations/tree/v0.7.1)
+
+### Added
+
+- Added `persisted:` option to the new forms definition. [\#48](https://github.com/BookingSync/operations/pull/48) ([pyromaniac](https://github.com/pyromaniac))
+
+## [0.7.0](https://github.com/BookingSync/operations/tree/v0.7.0)
+
+### Added
+
+- Implement new forms system detaching it from operations. Please check [UPGRADING_FORMS.md](UPGRADING_FORMS.md) for more details. [\#47](https://github.com/BookingSync/operations/pull/47) ([pyromaniac](https://github.com/pyromaniac))
 
 ### Improvements
 
@@ -15,7 +32,7 @@
 
 - In some cases, `Operation::Command#form_class` was evaluated before `form_base` was evaluated [\#41](https://github.com/BookingSync/operations/pull/41) ([pyromaniac](https://github.com/pyromaniac))
 
-## [0.6.2]
+## [0.6.3](https://github.com/BookingSync/operations/tree/v0.6.3)
 
 ### Added
 

data/README.md

@@ -312,7 +312,7 @@ class ActiveRecordRepository
   include Dry::Monads[:result]
   extend Dry::Initializer
 
-  param :model, type: Types.Instance(Class).constrained(lt: ActiveRecord::Base)
+  param :model, type: Types::Class.constrained(lt: ActiveRecord::Base)
 
   def create(**attributes)
     record = model.new(**attributes)
@@ -853,6 +853,8 @@ In this case, `Order::MarkAsCompleted.system.call(...)` will be used in, say, co
 
 ### Form objects
 
+Form objects were refactored to be separate from Command. Please check [UPGRADING_FORMS.md](UPGRADING_FORMS.md) for more details.
+
 While we normally recommend using frontend-backend separation, it is still possible to use this framework with Rails view helpers:
 
 ```ruby
@@ -885,7 +887,7 @@ class Post::Update
 end
 ```
 
-Then, the form can be used as any other form object:
+Then, the form can be used as any other form object. Unfortunately, there is no way to figure out the correct route for the operation form object, so it have to be provided manually:
 
 ```erb
 # views/posts/edit.html.erb
@@ -902,7 +904,7 @@ class Post::Update
   def self.default_form
     @default_form ||= Operations::Form.new(
       default,
-      hydrator: Post::Update::Hydrator.new
+      hydrators: [Post::Update::Hydrator.new]
     )
   end
 end
@@ -910,9 +912,7 @@ end
 class Post::Update::Hydrator
   def call(form_class, params, post:, **_context)
     value_attributes = form_class.attributes.keys - %i[post_id]
-    data = value_attributes.index_with { |name| post.public_send(name) }
-
-    data.merge!(params)
+    value_attributes.index_with { |name| post.public_send(name) }
   end
 end
 ```
@@ -927,19 +927,36 @@ class Post::Update
     @default_form ||= Operations::Form.new(
       default,
       model_map: Post::Update::ModelMap.new,
-      hydrator: Post::Update::Hydrator.new
+      hydrators: [Post::Update::Hydrator.new]
     )
   end
 end
 
 class Post::Update::ModelMap
-  def call(_path)
-    Post
+  MAPPING = {
+    %w[published_at] => Post, # a model can be passed but beware of circular dependencies, better use strings
+    %w[title] => "Post", # or a model name - safer option
+    %w[content] => "Post#body" # referencing different attribute is possible, useful for naming migration or translations
+  }.freeze
+
+  def call(path)
+    MAPPING[path] # returns the mapping for a single path
   end
 end
 ```
 
-In forms, params input is already transformed to extract the nested data with the form name. `form_for @post_update_form` will generate the form that send params nested under the `params[:post_update_form]` key. By default operation forms extract this form data and send it to the operation at the top level, so `{ id: 42, post_update_form: { title: "Post Title" } }` params will be sent to the operation as `{ id: 42, title: "Post Title" }`. Strong params are also accepted by the form, though they are being converted with `to_unsafe_hash`.
+In forms, params input is already transformed to extract the nested data with the form name. `form_for @post_update_form` will generate the form that send params nested under the `params[:post_update_form]` key. By default operation forms extract this form data and send it to the operation at the top level, so `{ id: 42, post_update_form: { title: "Post Title" } }` params will be sent to the operation as `{ id: 42, title: "Post Title" }`. Strong params are also accepted by the form, though they are being converted with `to_unsafe_hash`. Though the form name can be customized if necessary:
+
+```ruby
+class Post::Update
+  def self.default_form
+    @default_form ||= Operations::Form.new(
+      default,
+      model_name: "custom_post_update_form", # form name can be customized
+    )
+  end
+end
+```
 
 It is possible to add more params transfomations to the form in cases when operation contract is different from the params structure:
 
@@ -948,7 +965,6 @@ class Post::Update
   def self.default_form
     @default_form ||= Operations::Form.new(
       default,
-      model_name: "post_update_form", # form name can be customized
       params_transformations: [
         ParamsMap.new(id: :post_id),
         NestedAttributes.new(:sections)
@@ -994,6 +1010,21 @@ class NestedAttributes
 end
 ```
 
+By default, the top-level form objects instantiated from the form will have `persisted?` flag set to `true`. This will result the form to use the `PATCH` werb like for any persisted AR object. If it is required to generate a form with the `POST` verb in case of operation, say, creating some objects, this default behavior can be customised:
+
+```ruby
+class Post::Create
+  def self.default_form
+    @default_form ||= Operations::Form.new(
+      default,
+      persisted: false
+    )
+  end
+end
+```
+
+Note that operation itself is agnostic to the persistence layer, so there is no way for it to figure out this semanticsa automatically.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/UPGRADING_FORMS.md

@@ -0,0 +1,101 @@
+# New form objects
+
+In version 0.7.0, a new form objects system were introduced. The old way of using form objects is deprecated and will be removed in 1.0.0. In order to upgrade your code to start using the new way please follow the guide:
+
+## Replace `Operations::Form` with `Operations::Form::Base`
+
+If you have any classes that were inherited from `Operations::Form`, please change them to inherit from `Operations::Form::Base`
+
+## Define forms as separate objects on top of the existing operations:
+
+```ruby
+# Before
+class Post::Update
+  def self.default
+    @default ||= Operations::Command.new(
+      ...,
+      form_hydrator: Post::Update::Hydrator.new,
+      form_model_map: {
+        [%r{.+}] => "Post"
+      }
+    )
+  end
+end
+
+# After
+class Post::Update
+  def self.default
+    @default ||= Operations::Command.new(...)
+  end
+
+  def self.default_form
+    @default_form ||= Operations::Form.new(
+      default,
+      hydrators: [Post::Update::Hydrator.new],
+      model_map: Post::Update::ModelMap.new,
+      params_transformations: [
+        ParamsMap.new(id: :post_id)
+      ]
+    )
+  end
+end
+```
+
+Where `Post::Update::ModelMap` can be a copy of [Operations::Form::DeprecatedLegacyModelMapImplementation](https://github.com/BookingSync/operations/blob/main/lib/operations/form/deprecated_legacy_model_map_implementation.rb) or your own implementation.
+
+And `ParamsMap` can be as simple as:
+
+```ruby
+class ParamsMap
+  extend Dry::Initializer
+
+  param :params_map
+
+  def call(_form_class, params, **_context)
+    params.transform_keys { |key| params_map[key] || key }
+  end
+end
+```
+
+## Change the way you use forms in you controllers and views:
+
+```ruby
+# Before
+class PostsController < ApplicationController
+  def edit
+    @post_update = Post::Update.default.callable(
+      { post_id: params[:id] },
+      current_user: current_user
+    )
+
+    respond_with @post_update
+  end
+
+  def update
+    # With operations we don't need strong parameters as the operation contract takes care of this.
+    @post_update = Post::Update.default.call(
+      { **params[:post_update_default_form], post_id: params[:id] },
+      current_user: current_user
+    )
+
+    respond_with @post_update, location: edit_post_url(@post_update.context[:post])
+  end
+end
+
+# After
+class PostsController < ApplicationController
+  def edit
+    @post_update_form = Post::Update.default_form.build(params, current_user: current_user)
+
+    respond_with @post_update_form
+  end
+
+  def update
+    @post_update_form = Post::Update.default_form.persist(params, current_user: current_user)
+
+    respond_with @post_update_form, location: edit_post_url(@post_update_form.operation_result.context[:post])
+  end
+end
+```
+
+Notice that `callable` and `call` methond are replaced with `build` and `persist` respectively.

data/lib/operations/command.rb

@@ -197,6 +197,11 @@ class Operations::Command
     result_policies = policies_sum - [Undefined] unless policies_sum == [Undefined, Undefined]
     options[:policies] = result_policies if result_policies
 
+    if after.present?
+      ActiveSupport::Deprecation.new.warn("Operations::Command `after:` option is deprecated and will be " \
+        "removed in 1.0.0. Please use `on_success:` instead")
+    end
+
     preconditions.push(precondition) if precondition.present?
     super(operation, preconditions: preconditions, on_success: after, **options)
   end
@@ -387,7 +392,8 @@ class Operations::Command
         key_map: contract.class.schema.key_map,
         model_map: Operations::Form::DeprecatedLegacyModelMapImplementation.new(form_model_map),
         namespace: operation.class,
-        class_name: form_class_name
+        class_name: form_class_name,
+        persisted: true
       )
   end
 

data/lib/operations/form/attribute.rb

@@ -5,39 +5,35 @@
 # legacy UI.
 class Operations::Form::Attribute
   extend Dry::Initializer
-  include Dry::Equalizer(:name, :collection, :model_name, :form)
-  include Operations::Inspect.new(:name, :collection, :model_name, :form)
+  include Dry::Equalizer(:name, :collection, :model_class, :model_attribute, :form)
+  include Operations::Inspect.new(:name, :collection, :model_class, :model_attribute, :form)
 
   param :name, type: Operations::Types::Coercible::Symbol
   option :collection, type: Operations::Types::Bool, default: proc { false }
-  option :model_name,
-    type: (Operations::Types::String | Operations::Types.Instance(Class).constrained(lt: ActiveRecord::Base)).optional,
-    default: proc {}
+  option :model_name, type: (Operations::Types::String | Operations::Types::Class).optional, default: proc {}
   option :form, type: Operations::Types::Class.optional, default: proc {}
 
-  def model_type
-    @model_type ||= owning_model.type_for_attribute(string_name) if model_name
-  end
+  def model_class
+    return @model_class if defined?(@model_class)
 
-  def model_human_name(options = {})
-    owning_model.human_attribute_name(string_name, options) if model_name
+    @model_class = model_name.is_a?(String) ? model_name.split("#").first.constantize : model_name
   end
 
-  def model_validators
-    @model_validators ||= model_name ? owning_model.validators_on(string_name) : []
-  end
+  def model_attribute
+    return @model_attribute if defined?(@model_attribute)
 
-  def model_localized_attr_name(locale)
-    owning_model.localized_attr_name_for(string_name, locale) if model_name
+    @model_attribute = model_class && (model_name.to_s.split("#").second.presence || name.to_s)
   end
 
-  private
+  def model_type
+    model_class.type_for_attribute(model_attribute) if model_name
+  end
 
-  def owning_model
-    @owning_model ||= model_name.is_a?(String) ? model_name.constantize : model_name
+  def model_human_name(options = {})
+    model_class.human_attribute_name(model_attribute, options) if model_name
   end
 
-  def string_name
-    @string_name ||= name.to_s
+  def model_validators
+    model_name ? model_class.validators_on(model_attribute) : []
   end
 end

data/lib/operations/form/base.rb

@@ -47,9 +47,16 @@ class Operations::Form::Base
 
       base.class_attribute :attributes, instance_accessor: false, default: {}
       base.class_attribute :primary_key, instance_accessor: false, default: :id
+      base.class_attribute :persisted, instance_accessor: false, default: nil
 
       base.define_method :initialize do |*args, **kwargs|
-        args.empty? && kwargs.present? ? super(kwargs, **{}) : super(*args, **kwargs)
+        if args.empty?
+          # Initializing Operations::Form::Base instance
+          super(kwargs, **{})
+        else
+          # Initializing Operations::Form instance as form object (deprecated)
+          super(*args, **kwargs)
+        end
       end
     end
 
@@ -82,12 +89,13 @@ class Operations::Form::Base
 
   # :nodoc:
   module InstanceMethods
-    def type_for_attribute(name)
-      self.class.attributes[name.to_sym].model_type
+    # Copied from globalize-accessors, should be deprecated and removed as it is not a core method
+    def localized_attr_name_for(attr_name, locale)
+      "#{attr_name}_#{locale.to_s.underscore}"
     end
 
-    def localized_attr_name_for(name, locale)
-      self.class.attributes[name.to_sym].model_localized_attr_name(locale)
+    def type_for_attribute(name)
+      self.class.attributes[name.to_sym].model_type
     end
 
     def has_attribute?(name) # rubocop:disable Naming/PredicateName
@@ -132,7 +140,7 @@ class Operations::Form::Base
     end
 
     def persisted?
-      !has_attribute?(self.class.primary_key) || read_attribute(self.class.primary_key).present?
+      self.class.persisted.nil? ? read_attribute(self.class.primary_key).present? : self.class.persisted
     end
 
     def new_record?

data/lib/operations/form/builder.rb

@@ -11,18 +11,19 @@ class Operations::Form::Builder
 
   option :base_class, Operations::Types::Instance(Class)
 
-  def build(key_map:, model_map:, namespace: nil, class_name: nil, model_name: nil)
+  def build(key_map:, model_map:, namespace: nil, class_name: nil, model_name: nil, persisted: nil)
     return namespace.const_get(class_name) if namespace && class_name && namespace.const_defined?(class_name)
 
-    traverse(key_map, model_map, namespace, class_name, model_name, [])
+    traverse(key_map, model_map, namespace, class_name, model_name, [], persisted: persisted)
   end
 
   private
 
-  def traverse(key_map, model_map, namespace, class_name, model_name, path)
+  def traverse(key_map, model_map, namespace, class_name, model_name, path, persisted: nil)
     form = Class.new(base_class)
     namespace.const_set(class_name, form) if namespace&.name && class_name
     define_model_name(form, model_name) if model_name && !form.name
+    form.persisted = persisted
 
     key_map.each { |key| define_attribute(form, model_map, key, path) }
     form

data/lib/operations/form.rb

@@ -21,8 +21,10 @@
 #
 class Operations::Form
   include Dry::Core::Constants
-  include Dry::Equalizer(:command, :model_map, :params_transformations, :hydrator, :form_class)
-  include Operations::Inspect.new(:model_name, :model_map, :params_transformations, :hydrator, :form_class)
+  include Dry::Equalizer(:command, :model_map, :persisted,
+    :params_transformations, :hydrators, :hydration_merge_params, :form_class)
+  include Operations::Inspect.new(:model_name, :model_map, :persisted,
+    :params_transformations, :hydrators, :hydration_merge_params, :form_class)
 
   # We need to make deprecated inheritance from Operations::Form act exactly the
   # same way as from Operations::Form::Base. In order to do this, we are encapsulating all the
@@ -48,12 +50,20 @@ class Operations::Form
     param :command, type: Operations::Types.Interface(:operation, :contract, :call)
     option :model_name, type: Operations::Types::String.optional, default: proc {}, reader: false
     option :model_map, type: Operations::Types.Interface(:call).optional, default: proc {}
+    option :persisted, type: Operations::Types::Bool, default: proc { true }
     option :params_transformations, type: Operations::Types::Coercible::Array.of(Operations::Types.Interface(:call)),
       default: proc { [] }
-    option :hydrator, type: Operations::Types.Interface(:call).optional, default: proc {}
+    option :hydrators, type: Operations::Types::Array.of(Operations::Types.Interface(:call)), default: proc { [] }
+    option :hydration_merge_params, type: Operations::Types::Bool, default: proc { true }
     option :base_class, type: Operations::Types::Class, default: proc { ::Operations::Form::Base }
   end)
 
+  def initialize(command, hydrator: nil, hydrators: [], **options)
+    hydrators.push(hydrator) if hydrator.present?
+
+    super(command, hydrators: hydrators, **options)
+  end
+
   def build(params = EMPTY_HASH, **context)
     instantiate_form(command.callable(transform_params(params, **context), **context))
   end
@@ -64,7 +74,7 @@ class Operations::Form
 
   def form_class
     @form_class ||= Operations::Form::Builder.new(base_class: base_class)
-      .build(key_map: key_map, model_map: model_map, model_name: model_name)
+      .build(key_map: key_map, model_map: model_map, model_name: model_name, persisted: persisted)
   end
 
   private
@@ -80,12 +90,20 @@ class Operations::Form
 
   def instantiate_form(operation_result)
     form_class.new(
-      hydrator&.call(form_class, operation_result.params, **operation_result.context) || {},
+      hydrate_params(form_class, operation_result.params, **operation_result.context),
       messages: operation_result.errors.to_h,
       operation_result: operation_result
     )
   end
 
+  def hydrate_params(form_class, params, **context)
+    hydrated_params = hydrators.inject({}) do |value, hydrator|
+      value.merge(hydrator.call(form_class, params, **context).deep_symbolize_keys)
+    end
+    hydrated_params.deep_merge!(params) if hydration_merge_params
+    hydrated_params
+  end
+
   def key_map
     @key_map ||= command.contract.schema.key_map
   end

data/lib/operations/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Operations
-  VERSION = "0.7.0"
+  VERSION = "0.7.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: operations
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.2
 platform: ruby
 authors:
 - Arkadiy Zabazhanov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-28 00:00:00.000000000 Z
+date: 2024-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: appraisal
@@ -154,6 +154,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- UPGRADING_FORMS.md
 - bin/console
 - bin/setup
 - gemfiles/rails.5.2.gemfile