formify 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bd463cb45e56a78846363c509874052ea0b0e172c8dfd4b7015f652dce998c7
-  data.tar.gz: ead9810fb43a0bdad43f919221ed2c964aef6e26fa032898b029ae4998b1e6aa
+  metadata.gz: '09b226440478b6b89edbee6d137934281da2c347fd48681e5b205eb4039e0582'
+  data.tar.gz: 85399692540ed00fe2f26f88273f300a9a7bdaa1a7c82c95102f3a59b89d8aa2
 SHA512:
-  metadata.gz: c8f31a0487e61fcc35ece263d92f90737b0e63e7defb194730a80fb1005695438378cf5b8c8b649715a819a94aa36b81c8fd31b5a552959c456cfc81f220505a
-  data.tar.gz: 7df77eb9274c738e10cc9301cc798a3a815656d18aee60887ea2feb538682f49227608e9e8a917db9e96e975fe7e87325d684f17aba705bd980a820539d90cf6
+  metadata.gz: 6646b9167f6ab241864284b64e88b3ec851e4fa7a4c00f08597e53e32bfbdc1a50a084ef65152bfa1ed9796c51f74f276652da618195f4189797fe92784de282
+  data.tar.gz: 3af2ea3e9492d8cd839b2198bb96153fa18b71ce4890e40407cfea4b1a07b3741d3a8d0130e4c94599db6868e502f433adc9350f93fdf4d9f95c0b626f28a626

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    formify (0.15.0)
+    formify (0.16.0)
       rails
       resonad
+      with_advisory_lock
 
 GEM
   remote: https://rubygems.org/
@@ -130,6 +131,8 @@ GEM
     websocket-driver (0.7.0)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.3)
+    with_advisory_lock (4.0.0)
+      activerecord (>= 4.2)
 
 PLATFORMS
   ruby

data/README.md

@@ -20,7 +20,181 @@ Or install it yourself as:
 
 ## Usage
 
-Once installed, use `include Formify::Form` into any class to give it the form structure.
+Once installed, use `include Formify::Form` into any class to give it the form structure.  In rspec tests, you can `require 'formify/spec_helpers` and then `include Formify::SpecHelpers`.  This gives you access to [a number of helper methods](lib/formify/spec_helpers.rb).
+
+## Generators
+
+Formify ships with a powerful generator, giving you some default scaffolding.  It's designed to generate everything for you, letting you know what's optional and can be removed.  You can generate forms and their respective spec files using the following:
+
+`rails generate form ATTRIBUTES`
+
+`ATTRIBUTES` is a list of form attributes and their delegates.  Formify takes advantage of existing objects (e.g. models and other forms) and their attribute reading and writing functionality.  For example, if you were to do the following:
+
+`rails generate form widgets/create foo:bar,baz owner:owner_attribute created_by`
+
+You would get the following files:
+
+- `app/lib/forms/widgets/create.rb`
+- `spec/lib/forms/widgets/create_spec.rb`
+
+### Generated Form
+
+```ruby
+# frozen_string_literal: true
+
+module Forms
+  module Widgets
+    class Create
+      include Formify::Form
+
+      attr_accessor :created_by,
+                    :foo,
+                    :owner
+
+      delegate_accessor :bar,
+                        :baz,
+                        to: :foo
+      delegate_accessor :owner_attribute,
+                        to: :owner
+
+      validates_presence_of :bar,
+                            :baz,
+                            :created_by,
+                            :foo,
+                            :owner,
+                            :owner_attribute
+
+      # validate :validate_something
+
+      initialize_with :created_by, :foo, :owner do |attributes|
+        puts attributes
+      end
+
+      def save
+        raise NotImplementedError
+
+        with_advisory_lock_transaction(:foo) do
+          validate_or_fail
+            .and_then { create_widget }
+            .and_then { success(created_by) }
+        end
+      end
+
+      private
+
+      def create_widget
+      end
+
+      # def validate_something
+      # end
+    end
+  end
+end
+```
+
+### Generated Spec
+
+```ruby
+# frozen_string_literal: true
+
+require 'rails_helper'
+require 'formify/spec_helpers'
+
+describe Forms::Widgets::Create, type: :form do
+  include Formify::SpecHelpers
+
+  # :attributes is used to initialize the form.
+  # These values should result in a valid form.
+  # You can override these in blocks or use let(:attributes_override) { { foo: bar } }
+  let(:attributes) do
+    {
+      bar: BAR_VALUE,
+      baz: BAZ_VALUE,
+      created_by: CREATED_BY_VALUE,
+      foo: FOO_VALUE,
+      owner: OWNER_VALUE,
+      owner_attribute: OWNER_ATTRIBUTE_VALUE
+    }
+  end
+
+  it { expect_valid } # Expect the form to be valid
+  it { expect(result).to be_success }
+  it { expect(value).to be_a(Widget) } # Model name inferred
+
+  context '#bar' do
+    # Attribute: :bar
+    it { expect_error_with_missing_attribute(:bar) }
+    xit { expect_error_with_attribute_value(:bar, BAR_BAD_VALUE, message: nil) } # :message is optional
+    xit { expect_valid_with_attribute_value(:bar, BAR_GOOD_VALUE) }
+  end
+
+  context '#baz' do
+    # Attribute: :baz
+    it { expect_error_with_missing_attribute(:baz) }
+    xit { expect_error_with_attribute_value(:baz, BAZ_BAD_VALUE, message: nil) } # :message is optional
+    xit { expect_valid_with_attribute_value(:baz, BAZ_GOOD_VALUE) }
+  end
+
+  context '#created_by' do
+    # Attribute: :created_by
+    it { expect_error_with_missing_attribute(:created_by) }
+    xit { expect_error_with_attribute_value(:created_by, CREATED_BY_BAD_VALUE, message: nil) } # :message is optional
+    xit { expect_valid_with_attribute_value(:created_by, CREATED_BY_GOOD_VALUE) }
+  end
+
+  context '#foo' do
+    # Attribute: :foo
+    it { expect_error_with_missing_attribute(:foo) }
+    xit { expect_error_with_attribute_value(:foo, FOO_BAD_VALUE, message: nil) } # :message is optional
+    xit { expect_valid_with_attribute_value(:foo, FOO_GOOD_VALUE) }
+  end
+
+  context '#owner' do
+    # Attribute: :owner
+    it { expect_error_with_missing_attribute(:owner) }
+    xit { expect_error_with_attribute_value(:owner, OWNER_BAD_VALUE, message: nil) } # :message is optional
+    xit { expect_valid_with_attribute_value(:owner, OWNER_GOOD_VALUE) }
+  end
+
+  context '#owner_attribute' do
+    # Attribute: :owner_attribute
+    it { expect_error_with_missing_attribute(:owner_attribute) }
+    xit { expect_error_with_attribute_value(:owner_attribute, OWNER_ATTRIBUTE_BAD_VALUE, message: nil) } # :message is optional
+    xit { expect_valid_with_attribute_value(:owner_attribute, OWNER_ATTRIBUTE_GOOD_VALUE) }
+  end
+
+  # Other Expectation Helpers
+  # xit { expect_error_message(message) }
+  # xit { expect_error_with_attribute(attribute) }
+  # xit { expect_not_valid(attribute: nil, message: nil) } # :attribute and :message are optional
+end
+
+```
+
+### Options
+
+- `pluralize_collection` (default: `true`) - Pluralize the collection as per naming conventions below.
+
+## Transactions
+
+Formify works with ClosureTree/with_advisory_lock to offer easy and intuitive locking, with or without transactions.
+
+## Naming Conventions
+
+### Form Name
+Formify assumes that every form is an action.  As such, it's best to use verbs like `create`, `update`, `destroy`, `upsert`, `find`, `process`, etc.
+
+### Form Collection
+The parent folder of a form should be the plural of the object it operates on.  For example, if you had a `User` model, you would have `users/create.rb`.  The collection does not need to be a model.  It can be any noun in the plural form, like `sessions/create.rb`
+
+### Collection Scopes
+
+Any folder before the collection is considered a scope and serves to help you group collections and forms.  Consider an application that has a end-user and an admin, and accounts need to be approved.  You would probably consider the following actions to need separate functionality:
+
+- `/forms/admin/accounts/create.rb` - This one may take an `approved_by` attribute.
+- `/forms/accounts/create.rb` - This one would result in account pending approval
+
+Scoping helps you keep your
 
 ## Development
 

data/formify.gemspec

@@ -27,4 +27,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_runtime_dependency 'rails'
   spec.add_runtime_dependency 'resonad'
+  spec.add_runtime_dependency 'with_advisory_lock'
 end

data/lib/formify/version.rb

@@ -1,3 +1,3 @@
 module Formify
-  VERSION = '0.15.0'.freeze
+  VERSION = '0.16.0'.freeze
 end

data/lib/generators/form/form_generator.rb

@@ -11,6 +11,20 @@ class FormGenerator < Rails::Generators::NamedBase
             required: true,
             description: 'A list of attributes and their delegates: foo:bar,baz'
 
+  class_option  :pluralize_collection,
+                default: true,
+                description: 'Disable naming convention transformations like forcing plural collections',
+                type: :boolean
+
+  def transform_naming
+    return unless pluralize_collection?
+
+    self.name = begin
+      names = name.split('/')
+      names[0..-3].append(names[-2].pluralize).append(names[-1]).join('/')
+    end
+  end
+
   def validate_fixed_attrs
     return unless duplicate_attributes.any?
 
@@ -18,11 +32,11 @@ class FormGenerator < Rails::Generators::NamedBase
   end
 
   def generate_form
-    template 'form.rb', File.join('app/lib/forms', class_path, "#{file_name}.rb")
+    template 'form.rb', File.join('app/lib/forms', transformed_class_path, "#{file_name}.rb")
   end
 
   def generate_form_spec
-    template 'form_spec.rb', File.join('spec/lib/forms', class_path, "#{file_name}_spec.rb")
+    template 'form_spec.rb', File.join('spec/lib/forms', transformed_class_path, "#{file_name}_spec.rb")
   end
 
   private
@@ -47,6 +61,14 @@ class FormGenerator < Rails::Generators::NamedBase
     ]
   end
 
+  def collection
+    @collection ||= split_name[-2].pluralize.underscore
+  end
+
+  def collection_name
+    @collection_name ||= collection.camelcase
+  end
+
   def delegated_attributes
     @delegated_attributes ||= attributes_and_delegates
       .select { |_k, v| v.sort!.present? }
@@ -59,8 +81,16 @@ class FormGenerator < Rails::Generators::NamedBase
                               .map(&:first)
   end
 
+  def form
+    @form ||= name.split('/').last.to_s.underscore
+  end
+
+  def form_name
+    @form_name ||= form.camelcase
+  end
+
   def inferred_model_name
-    @inferred_model_name ||= name.split('/')[-2].singularize.camelcase
+    @inferred_model_name ||= collection.singularize.camelcase
   end
 
   def module_namespacing(&block)
@@ -72,7 +102,33 @@ class FormGenerator < Rails::Generators::NamedBase
   end
 
   def modules
-    @modules ||= ['Forms'] + name.split('/')[0..-2].map(&:to_s).map(&:camelcase)
+    @modules ||= ['Forms'] + split_name[0..-2].map(&:to_s).map(&:camelcase)
+  end
+
+  def pluralize_collection?
+    @pluralize_collection ||= options[:pluralize_collection]
+  end
+
+  def scopes
+    @scopes ||= split_name[0..-3].map(&:underscore)
+  end
+
+  def scope_names
+    @scope_names ||= scopes.map(&:camelcase)
+  end
+
+  def split_name
+    @split_name ||= name.split('/')
+  end
+
+  def transformed_class_path
+    @transformed_class_path ||= begin
+      if pluralize_collection?
+        class_path[0..-2].append(class_path[-1].pluralize)
+      else
+        class_path
+      end
+    end
   end
 
   def variablefy(val)

data/lib/generators/form/templates/form.rb.tt

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 <% module_namespacing do -%>
-class <%= name.split('/').last.to_s.camelcase %>
+class <%= form_name %>
   include Formify::Form
 
   attr_accessor :<%= attributes.first %><%= ',' if attributes.count > 1 %>

data/lib/generators/form/templates/form_spec.rb.tt

@@ -21,17 +21,15 @@ describe Forms::<%= class_name %>, type: :form do
   it { expect(result).to be_success }
   it { expect(value).to be_a(<%= inferred_model_name %>) } # Model name inferred
 
-  ### START: Attribute Expectations
-
 <% all_attributes.each do |attr| -%>
-  # Attribute: :<%= attr %>
-  it { expect_error_with_missing_attribute(:<%= attr %>) }
-  xit { expect_error_with_attribute_value(:<%= attr %>, <%= attr.upcase %>_BAD_VALUE, message: nil) } # :message is optional
-  xit { expect_valid_with_attribute_value(:<%= attr %>, <%= attr.upcase %>_GOOD_VALUE) }
+  context '#<%= attr %>' do
+    # Attribute: :<%= attr %>
+    it { expect_error_with_missing_attribute(:<%= attr %>) }
+    xit { expect_error_with_attribute_value(:<%= attr %>, <%= attr.upcase %>_BAD_VALUE, message: nil) } # :message is optional
+    xit { expect_valid_with_attribute_value(:<%= attr %>, <%= attr.upcase %>_GOOD_VALUE) }
+  end
 
 <% end -%>
-  ### END: Attribute Expectations
-
   # Other Expectation Helpers
   # xit { expect_error_message(message) }
   # xit { expect_error_with_attribute(attribute) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: formify
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Ryan Jackson
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: with_advisory_lock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Formify acts as an abstract class, allowing you to easily create robust
   form objects and test them using rspec.
 email: