brace_comb 0.0.3 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8fe368a2abc127eb6eabb97dd00821f440d0e715
-  data.tar.gz: 31c9abbd499456fa9fa5a4d0c734166ead74d4cc
+  metadata.gz: 1bfd2a6dfe32328fd413215449ec8880f0a50cba
+  data.tar.gz: d3d8f3995d6695d34cfec43ac0e1fbfd2109d65c
 SHA512:
-  metadata.gz: 56f9d83c4244ba7d54317b750c0f25efb4615344cd4e855bd9fb461b426b64d78619d6ae799151bd32a7ea83720be202fd0a593e17771c7615ac9ec265944661
-  data.tar.gz: 8c3c00d2aa57ed9308a9d73f77da66f3f9234a6861ed9a172ca98504cf197b01390e8e0a8f642f8359e60e063f0319938c83d9bf0cfafca281c3f1fef58d0ead
+  metadata.gz: 8f4d959428312946a06ec5fc78da49a1b30b9ec9d3e08de0bf81c481e310caf64cec80db870dab19a4c1f1732cc1a761576d0e163107603f91991890764a0074
+  data.tar.gz: ce0b8b59c727609cafe7244d29e6e7020af6cbdda06a258767651f9dc5c1ba571381c23ddacc85ff5be2dc27c2de71682484e3877148b46edbf06fd73d0cf353

data/README.md

@@ -2,15 +2,36 @@
 
 Brace Comb is a small bit of wax built between two combs or frames to fasten them together. Brace comb is also built between a comb and adjacent wood, or between two wooden parts such as top bars.
 
-Allows setting dependency logic between entities, and declaring resolution methods and callbacks to resolve dependencies.
+This is akin to how workflows are connected to each other with dependencies.
 
-## Background
+## Description
 
-In workflow management systems, there is often a need to define that certain tasks should only begin when another task(s) is complete.
+In workflow management systems, there is often a need to define that certain tasks should only begin when another task(s) is complete. BraceComb can be used to define multiple types of workflows and handle each workflow consistently.
 
-Instead of having each workflow system define database entities to denote dependency relationships between tasks/dependents, this gem provides features that can create both the dependency and dependent model. These entity names are configurable based on the project needs. 
+## Example
+A factory production line sytem uses pre-defined workflows with strict dependencies between tasks. In a simplified scenario, let's say we need to define a workflow in which an item on the conveyor belt must be packed before it is dispatched. In this case:
 
-In addition, it accepts methods/procs to define the logic for dependency resolution via resolution callbacks. In the same vein as active record callbacks, dependency resolution callbacks can define actions that should be executed before a dependency is resolved and after a dependency is resolved. If any before callbacks fail, then dependency resolution will also fail.
+- Dependents/Tasks are the actions such as packing and dispatching
+- Dependencies are links that define that packing must finish before dispatching
+
+In this system we can create a dependent entity called `entity1` for `packing` and another dependent entity called `entity2` for `dispatching`. A new dependency between the two entities can be created using the following command:
+
+  ```
+    initialize_dependency! from: entity1.id, to: entity2.id, type: 'dispatch'
+  ```
+
+This will create a dependency in `pending` state. In this case `packing` is a strict prerequisite for `dispatching`, hence `entity2` should not start unless the dependency is in `resolved` state. This is also the case for any dependencies of type `dispatch`. This can be defined by declaring a dependency characteristics using:
+
+```
+  declare_dependency type: :dispatch,
+                     resolver: :send_packing_complete_confirmation,
+                     before_resolution: [:check_packing_complete?, :check_dispatcher_available?],
+                     after_resolution: [:send_dispatch_notification]
+```
+
+This declaration will ensure that for all dependencies of type `dispatch`, all `before_resolution` hooks are first run. If any `before_resolution` functions returns false, then the operation is aborted. If all `before_resolution` functions return true, then the resolver code inside `send_packing_complete_confirmation` will be executed, and then all functions inside `after_resolution` would be executed.
+
+To kick-off this flow just call `dependency.resolve` and the before and after hooks will be invoked in the manner as described above.
 
 ## Installation
 
@@ -18,21 +39,23 @@ In addition, it accepts methods/procs to define the logic for dependency resolut
 
     `gem 'brace_comb'`
 
-2. Create an initializer for `brace_comb` 
+2. Create an initializer for `brace_comb`
 
     a. `bundle exec rails generate brace_comb:initializer`
-    
+
     b. Modify the name of dependency and dependent tables in the initializer `config/initializers/brace_comb.rb`
-    
+
     c. Run `bundle exec rails generate brace_comb:migration` to create the migration
-    
+
     d. Create the dependency tables and associations using `bundle exec rake db:migrate`
-    
+
     e. Generate the basic dependency model by running:
        ```bundle exec rails generate brace_comb:model ''```
 
 ## Usage
-  
+
+Entity names for dependencies and dependents are configurable and can be set in `config/initializers/brace_comb.rb` before creating the migrations.
+
 1. Declare a dependency type by adding in the following to the dependency class:
    ```
      include BraceComb::Helper
@@ -44,39 +67,39 @@ In addition, it accepts methods/procs to define the logic for dependency resolut
    ```
      declare_dependency type: :shopping,
                         resolver: :shopping_complete
-                        before_resolved: [:completed_status?],
-                        after_resolved: [:complete_job]
+                        before_resolution: [:completed_status?],
+                        after_resolution: [:complete_job]
    ```
-   
-   or 
-   
+
+   or
+
    b. Using a proc in the resolver
-   
+
    ```
      declare_dependency type: :shopping,
                         resolver: ->(data) { data.condition },
-                        before_resolved: [:completed_status?],
-                        after_resolved: [:complete_job]
+                        before_resolution: [:completed_status?],
+                        after_resolution: [:complete_job]
    ```
 3. Create dependencies between the dependent class by using the following helper in any instance method of a model class:
 
    - When an exception needs to be raised:
-   `initialize_dependency! from: job1, to: job2, type: 'shopping'`
+   `initialize_dependency! from: entity1.id, to: entity2.id, type: 'shopping'`
 
    or
    - When a boolean needs to be returned:
-   `initialize_dependency from: job1, to: job2, type: 'shopping'`
+   `initialize_dependency from: entity1.id, to: entity2.id, type: 'shopping'`
 
 5. Resolve dependencies from any active record model by using:
-   
+
    - When an exception needs to be raised:
    ```
      dependency.resolve!(identifier: 123, status: :resolved)
    ```
-   
+
    or
-   - When a boolean needs to be returned: 
-   
+   - When a boolean needs to be returned:
+
    ```
      dependency.resolve(identifier: 123, status: :resolved)
    ```

data/lib/brace_comb/dependency_helper.rb

@@ -4,23 +4,23 @@ module BraceComb
       # declare_dependency
       #   type: :shopping
       #   resolver: :shopping_completed
-      #   before_resolved: [:completed_status?]
-      #   after_resolved: :complete_job, Proc.new {}
+      #   before_resolution: [:completed_status?]
+      #   after_resolution: :complete_job, Proc.new {}
       # Options:
       # resolver: Methods or procs that can mark the dependency as resolved
-      # before_resolved: Checks that can be performed before a dependency is resolved.
+      # before_resolution: Checks that can be performed before a dependency is resolved.
       # If any of these return false then the dependency resolution will result in a false
       # or exception.
-      # after_resolved: if the dependency resolution succeeds, each of these methods will be
-      # executed one by one. All the subsequent after_resolved hooks will not be executed if any
-      # of the predecessor after_resolved hook throws an exception. However, this will not make
+      # after_resolution: if the dependency resolution succeeds, each of these methods will be
+      # executed one by one. All the subsequent after_resolution hooks will not be executed if any
+      # of the predecessor after_resolution hook throws an exception. However, this will not make
       # a difference to the resolution status of the dependency itself
       def declare_dependency(options = {})
         dependency_mapping = dependency_mapping_value
         dependency_mapping[options[:type]] = options.slice(
           :resolver,
-          :before_resolved,
-          :after_resolved
+          :before_resolution,
+          :after_resolution
         )
         set_dependency_mapping(dependency_mapping)
       end
@@ -51,7 +51,8 @@ module BraceComb
         dependency_model.create(
           source_id: from,
           destination_id: to,
-          dependency_type: dependency_type
+          dependency_type: dependency_type,
+          status: :pending
         )
       end
 
@@ -60,7 +61,8 @@ module BraceComb
         dependency_model.create!(
           source_id: from,
           destination_id: to,
-          dependency_type: dependency_type
+          dependency_type: dependency_type,
+          status: :pending
         )
       end
 

data/lib/brace_comb/dependency_model.rb

@@ -10,9 +10,9 @@ module BraceComb
         dependency_mapping = self.class.
           instance_variable_get(:@dependency_mapping)[self.dependency_type.to_sym]
         ActiveRecord::Base.transaction do
-          execute_before_callbacks(dependency_mapping[:before_resolved])
+          execute_before_callbacks(dependency_mapping[:before_resolution])
           execute_resolver(dependency_mapping[:resolver], args)
-          execute_after_callbacks(dependency_mapping[:after_resolved])
+          execute_after_callbacks(dependency_mapping[:after_resolution])
         end
       end
 

data/lib/brace_comb/version.rb

@@ -1,3 +1,3 @@
 module BraceComb
-  VERSION = '0.0.3'
+  VERSION = '0.1.1'
 end

data/lib/generators/brace_comb/migration_generator.rb

@@ -10,7 +10,7 @@ module BraceComb
     def create_migration_file
       add_migrations(dependent_table_name, 'create_dependent')
       add_migrations(dependency_table_name, 'create_dependencies')
-      add_migrations(nil, 'add_associations')
+      add_migrations('associations', 'add_associations')
     end
 
     private
@@ -23,7 +23,7 @@ module BraceComb
       else
         migration_template(
           "#{template}.rb.erb",
-          "db/migrate/#{migration_name.pluralize}.rb",
+          "db/migrate/create_#{migration_name.pluralize}.rb",
           migration_version: migration_version
         )
       end

data/lib/generators/brace_comb/templates/add_associations.rb.erb

@@ -1,5 +1,5 @@
 # This migration adds associations between the dependency and dependent
-class AddAssociations < ActiveRecord::Migration<%= migration_version %>
+class CreateAssociations < ActiveRecord::Migration<%= migration_version %>
   def change
     add_foreign_key :<%= dependency_table_name%>, :<%= dependent_table_name %>, column: :source_id, dependent: :delete
     add_foreign_key :<%= dependency_table_name%>, :<%= dependent_table_name %>, column: :destination_id, dependent: :delete

data/spec/brace_comb/dependency_helper_spec.rb

@@ -30,8 +30,8 @@ describe BraceComb::Helper do
 
           declare_dependency type: :shopping,
                              resolver: :shopping_complete,
-                             before_resolved: [:completed_status?],
-                             after_resolved: [:complete_job]
+                             before_resolution: [:completed_status?],
+                             after_resolution: [:complete_job]
         end
       end
       it 'can declare dependency' do
@@ -39,8 +39,8 @@ describe BraceComb::Helper do
         expect(dependency_mapping).to match(
           shopping: {
             resolver: :shopping_complete,
-            before_resolved: [:completed_status?],
-            after_resolved: [:complete_job]
+            before_resolution: [:completed_status?],
+            after_resolution: [:complete_job]
           }
         )
       end
@@ -107,4 +107,4 @@ describe BraceComb::Helper do
       end
     end
   end
-end
+end

data/spec/brace_comb/dependency_model_spec.rb

@@ -30,8 +30,8 @@ describe BraceComb::Model do
 
       declare_dependency type: :shopping,
                          resolver: :mark_as_complete,
-                         before_resolved: [:before_resolve1?, :before_resolve2?],
-                         after_resolved: [:complete_job]
+                         before_resolution: [:before_resolve1?, :before_resolve2?],
+                         after_resolution: [:complete_job]
     end
   end
 
@@ -106,8 +106,8 @@ describe BraceComb::Model do
         dependency_class.constantize.class_eval do
           declare_dependency type: :shopping,
                              resolver: ->(data) { data.resolved! },
-                             before_resolved: [->(_) { true }, :before_resolve?],
-                             after_resolved: [:complete_job]
+                             before_resolution: [->(_) { true }, :before_resolve?],
+                             after_resolution: [:complete_job]
         end
 
         class JobDependency
@@ -153,4 +153,4 @@ describe BraceComb::Model do
       end
     end
   end
-end
+end

data/spec/generators/brace_comb/migration_generator_spec.rb

@@ -26,12 +26,12 @@ describe BraceComb::MigrationGenerator, type: :generator do
       expect(destination_root).to have_structure {
         directory 'db' do
           directory 'migrate' do
-            migration 'jobs' do
+            migration 'create_jobs' do
               contains('class CreateJobs < ' + parent_class)
               contains('create_table :jobs do |t|')
               contains('t.timestamps null: false')
             end
-            migration 'job_dependencies' do
+            migration 'create_job_dependencies' do
               contains('create_table :job_dependencies do |t|')
               contains('class CreateJobDependencies < ' + parent_class)
               contains('t.integer :dependency_type, null: false')
@@ -40,8 +40,8 @@ describe BraceComb::MigrationGenerator, type: :generator do
               contains('t.integer :destination_id, null: false')
               contains('t.timestamps null: false')
             end
-            migration 'add_associations' do
-              contains('class AddAssociations < ' + parent_class)
+            migration 'create_associations' do
+              contains('class CreateAssociations < ' + parent_class)
               contains('add_foreign_key :job_dependencies, :jobs, column: :source_id, dependent: :delete')
               contains('add_foreign_key :job_dependencies, :jobs, column: :destination_id, dependent: :delete')
             end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brace_comb
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.1
 platform: ruby
 authors:
 - Ankita Gupta
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-08-18 00:00:00.000000000 Z
+date: 2017-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord