nexus_seed 0.2.15 → 0.2.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f65a6d127fd04cdc7ea6444e24e463edaa62769ebe68e127a870ad1e8eabd19
-  data.tar.gz: 9ea8b12324c1dff3b61c1cbadec1804fb183122586abe9ec037ff7263f0f2fe0
+  metadata.gz: c56d4582669b8742a96cb06df56efda328b62f4916a49f4a9adb32521facff49
+  data.tar.gz: dc6146a31126777419cec6b29f5acf677ba0119b93e4905c6575465243f67c22
 SHA512:
-  metadata.gz: fb4b7145f7e763e470669b7c8b7a0eb93a3e33fa3c9c0326c8f9a3c81ac0e5c52e1ac68989061ac9314647ce564c054f87605c11e52a302a4a9a05a66565f81e
-  data.tar.gz: 0514dc2375a5fd73eecf2e7708865e32dcdd742b0ccc871d3a1ec77cebb85829609ae61914e4a3dae8868db45f8fddb4f4932ef7d892bbf3a55de04d825a9949
+  metadata.gz: aedd5115dc4ca6a71c1b6ae574e41da3045ea8644ccd654bb0fed9f16baba4b6626cfb280d6380cfe292027de537a2f9566546b2df6715bbb86583e51c4575c6
+  data.tar.gz: 2c5f568773a14fbd9de9c8c8fc33c683387b0e610c129524ee16ec0418ab52851193a6d9476d2b732899420efbcfbd1f9d5b9cee5d776d763e930f468dcd3498

data/README.md

@@ -2,6 +2,10 @@
 
 Common rails application seeding logic.
 
+# Seed development
+
+See [SEED_BUILDER](SEED_BUILDER.md) documentation.
+
 # Running
 
 ## Running tasks on deploy
@@ -41,6 +45,14 @@ E.g. to retry 100 times every 3 seconds:
 
 `bundle exec rake seed_common:run[100,3]`
 
+## Removing seeded data
+
+Use `NEXUS_SEED_DESTROY` env var to locate seeded data and remove it.
+
+Especially useful when developing seeds, run with destroy and then run again without.
+
+`NEXUS_SEED_DESTROY=true bundle exec rake seed_common:run`
+
 # Local gem development
 
 Steps to run this gem from local sources in one the nexus 'staged build' rails components:

data/SEED_BUILDER.md

@@ -0,0 +1,254 @@
+# Seed builder
+
+The new seeding method proposes the following syntax:
+
+```
+NexusSeed::Builder.build(:collection_schema)
+NexusSeed::Builder.build(:category)
+
+game = NexusSeed::Builder.build(:game,
+  game_genre: NexusSeed::Builder.build(:game_genre, name: 'Some Game Genre'),
+  name: 'Some Random Game'
+)
+
+NexusSeed::Builder.build(:forum, { id: ENV['FORUM_COLLECTIONS_ID'] }, { find_by_params: :id })
+```
+
+`NexusSeed::Base.transaction` wraps the existing AR transaction and provides some QOL methods such as destroying
+previously generated seeds and generating seed reports.
+
+`NexusSeed::Builder.build(:collection_schema)` can be viewed as something
+mimicking `FactoryBot.create(:collection_schema)`. There are a few key differences, however:
+
+- `NexusSeed::Builder` ensures that the record generation is always idempotent
+- It does not currently support traits, but it does provide `before_save` and `after_save` callbacks which have to be
+  defined in the corresponding builder class (think of builder classes as factory definitions in `FactoryBot`)
+- it takes special parameters that can be passed as options
+
+Each model that we are intending to build needs to have a corresponding builder class in `db/nexus_seed/builders`
+directory. For example, if we want to create a builder class for a `Category` model, we will call it `CategoryBuilder`
+and place it in that directory. Here's a simple example of a builder class:
+
+```
+# frozen_string_literal: true
+module NexusSeed
+  module Builders
+    class CategoryBuilder < NexusSeed::Builder::Base
+      def defaults(params = {})
+        {
+          name: 'Default Category',
+          description: 'Category description',
+          approved: true,
+          suggested_by: 1,
+          parent_id: 0,
+        }
+      end
+
+      def find_by_params(instance, params)
+        :name
+      end
+    end
+  end
+end
+```
+
+There are 2 things that are defined here:
+
+- `defaults` is optional and can be used to provide default values for a model so that we don't need to specify them
+  each time. It takes `params` as an argument which is there simply to provide access to whatever is being passed into
+  an actual instance, e.g.:
+
+```
+NexusSeed::Builder.build(:category, name: 'some category', approved: false)
+```
+
+The `defaults` method will be able to see the `name` and `approved` params provided and if required, use them to resolve
+the rest of the parameters, i.e. we could have a conditional statement such as:
+
+```
+def defaults(params)
+  defaults = {}  
+
+  if params[:approved]
+    defaults[:approved_by] = 1337
+  end
+
+  ...
+  defaults
+end
+```
+
+To sum up, `defaults` is a method with access to current parameters used for the record generation and can accept any
+arbitrary code, as long as it returns a hash that matches the available columns and relationships of the corresponding
+model.
+
+That said, you can use relationships when building your seed data, just as you would if you were using factory bot, or
+the models directly e.g.:
+
+```
+genre = NexusSeed::Builder.build(:game_genre, name: 'Some Game Genre')
+
+game = NexusSeed::Builder.build(:game, game_genre: genre)
+```
+
+This is equivalent to:
+
+```
+game = Game.create(game_genre: genre, ...rest of params)
+# or
+game = FactoryBot.create(:game, game_genre: genre)
+```
+
+**Idempotence:**
+
+As you can see in the `CategoryBuilder` example, each builder class must have a `find_by_params` defined, which is used
+to ensure that the records generated by the builder are idempotent. In the case of the category builder, that field is
+set to `:name`, which means that the builder will never build two records with identical names.
+
+`find_by_params` can also accept an array or a hash with a specific query, or it can be a method. Some examples:
+
+```
+# make this builder ensure the records are unique by name and parent_id
+def find_by_params(instance, params)
+  [:name, :parent_id]
+end
+
+# make sure only one record with this parent_id can be created:
+def find_by_params(instance, params)
+  { parent_id: 1337 }
+end
+
+# do something with the params before returning the final `find_by_params`
+def find_by_params(instance, params)
+  final_params = {}        
+
+  if instance.foo? and params.bar?
+    final_params = ... run some code
+  end
+
+  final_params
+end
+```
+
+You can do similar things in the `defaults` method, the difference is the `defaults` can only access your parameters,
+whereas `find_by_params` can access the instance of a new model before it's saved. Here's the actual code from the base
+builder class:
+
+```
+# /nexus_seed/builders/base.rb
+module NexusSeed
+  module Builder
+    class Base   
+
+        ...
+
+        instance = klass.new(merged_params)
+
+        # set the custom find_by_params if provided
+        @find_by_params = if @options.key?(:find_by_params)
+          @options[:find_by_params]
+        else
+          find_by_params(instance, params)
+        end
+
+        raise StandardError, "Error: find_by_params must not be nil" if @find_by_params.nil?
+
+        before_save(instance, params)
+
+        find_by_query = if @find_by_params.is_a?(Hash)
+          @find_by_params
+        else
+          @find_by_params = @find_by_params.is_a?(Array) ? @find_by_params : [@find_by_params]
+
+          query_hash = {}
+
+          @find_by_params.each do |e|
+            query_hash[e] = instance[e]
+          end
+
+          query_hash
+        end
+```
+
+You can also override the default definition of `find_by_params` in your builder, by passing the `find_by_params` in
+your options when generating new data:
+
+```
+NexusSeed::Builder.build(:category, {approved: true}, {find_by_params: [:name, :parent_id]})
+```
+
+Ensure that the `find_by_params` override goes into the **second** hash in the build method, which is intended to accept
+optional stuff such as the above.
+
+Finally, each builder can have `before_save` and `after_save` methods, which work in the same way and can access both
+the instance and the params.
+
+If a corresponding model is nested in a module, e.g. `Collections::BugReports::CollectionBugReport`, the builder will
+not know how to resolve a call such as
+
+```
+NexusSeed::Builder.build(:collection_bug_report)
+```
+
+We need to therefore define the full modulized class inside the `CollectionBugReportBuilder.rb` like so:
+
+```
+def find_by_params ...
+def defaults ...
+def before_save...
+
+# define modulized class here:
+def model_class
+  Collections::BugReports::CollectionBugReport
+end
+```
+
+Now you can simply run `NexusSeed::Builder.build(:collection_bug_report)` and the builder will know which active record
+model is being used internally.
+
+# Development assistance
+
+It's often difficult to clear the seeds, especially if a project uses more than one database, so the seed builder
+provides a handy interface to do just that. Simply pass `NEXUS_SEED_DESTROY=true` as your env variable when running seeds
+manually, and it will destroy all of the previously generated seeds:
+
+```
+$ rake db:seeds NEXUS_SEED_DESTROY=true
+1337 seeds destroyed.
+Finished.
+
+$ rake db:seeds
+1337 created.
+Finished
+```
+
+You can also request a detailed report of what's been generated:
+
+```
+$ rake db:seeds NEXUS_SEED_REPORT=true
+Created 1000 Mods.
+Created 2000 ModFiles.
+... etc
+35000 new seeds were created in total.
+
+```
+
+Reporting and idempotency play together nicely. Say you've added a couple more things to your seeds, a collection image
+perhaps. When run again, you should see something along these lines:
+
+```
+$ rake db:seeds NEXUS_SEED_REPORT=true
+Created 1 CollectionImage
+1 new seed was created in total.
+```
+
+Running the seeds again after not changing anything should always result in:
+
+```
+$ rake db:seeds NEXUS_SEED_REPORT=true
+0 new seed was created in total.
+```
+
+If that is NOT the case, then your `find_by_params` might be incorrectly defined. There is no hard and fast rule of how
+you should declare your find_by_params to ensure idempotency, nor there is a one size fits all default go-to method to
+use.

data/lib/nexus_seed/builder/base.rb

@@ -60,7 +60,7 @@ module NexusSeed
           existing
         end
 
-        NexusSeed::Builder.add_seed(result) if ENV['destroy_seeds']
+        NexusSeed::Builder.add_seed(result) if ENV['NEXUS_SEED_DESTROY'] == 'true'
 
         after_save(result, params)
       end

data/lib/nexus_seed/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module NexusSeed
-  # Leave this as 0.2.15 in order for CI process to replace with the tagged version.
-  VERSION = '0.2.15'
+  # Leave this as 0.2.16 in order for CI process to replace with the tagged version.
+  VERSION = '0.2.16'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexus_seed
 version: !ruby/object:Gem::Version
-  version: 0.2.15
+  version: 0.2.16
 platform: ruby
 authors:
 - Johnathon Harris
@@ -35,6 +35,7 @@ files:
 - ".rubocop.yml"
 - Gemfile
 - README.md
+- SEED_BUILDER.md
 - lib/nexus_seed.rb
 - lib/nexus_seed/base.rb
 - lib/nexus_seed/builder.rb