planter 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe6195656eb33a7e774e6f5fb37e6f1dbcf6d7be33230c97605f291201d04de0
+  data.tar.gz: 68e04cc88dde75734fd06b69e0fd783f8f1849cb9d7f6e73fd33c18814cb1c61
+SHA512:
+  metadata.gz: dbcea200bc37aa0d691cc001a918bcafea73a6c37754f83dea3f56867c4cb0773f474d276477c71081c03a5cc83d592b5ff511e745005e3bb17919436943b33a
+  data.tar.gz: 26f4beb0e5613aedbb6308bcad145a5cd39c20f328fbfa6fb7db0f6bb588128c6c031c014ef00a61d519f246e89eea9e14b05d4126a990fca7235349a9615c9f

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2021 Evan Gray
+
+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,201 @@
+# Planter
+> Pre-release version! Anything is subject to change in the near future!
+
+Seeds for Rails applications can get complicated fast, and Rails doesn't provide
+much for assisting with this process. This plugin seeks to rectify that by
+providing easy ways to seed specific tables by hooking into the existing `rails
+db:seed` task.
+
+Features include:
+
+- Seed tables from CSV files, an array of hashes, or custom methods.
+- Seed specific tables with `rails db:seed TABLES=users,addresses`.
+- Control the number of records being created.
+- Seed associations.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'planter'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install planter
+```
+
+## Usage
+Let's assume you'd like to seed your `users` table.
+
+To get started, simply add the following to your `db/seeds.rb` file. Note that
+the `config.tables` should be an array of the tables to seed. They should be in
+the correct order to successfully seed the tables when considering associations.
+
+```ruby
+require 'planter'
+
+Planter.configure do |config|
+  config.tables = %i[ users ]
+end
+
+Planter.seed
+```
+
+Then, create a directory called `db/seeds`, and create a file called
+`db/seeds/users_seeder.rb`. In that file, create the following class. Note the
+name of the seeder is the name of the table, plus `Seeder`, and it inherits from
+`Planter::Seeder`.
+
+```ruby
+class UsersSeeder < Planter::Seeder
+end
+```
+
+You then need to choose a seeding method, of which there are currently three.
+
+### Seeding from CSV
+To seed from CSV, you simply need to add the following to your seeder class.
+
+```ruby
+class UsersSeeder < Planter::Seeder
+  seeding_method :standard_csv
+end
+```
+
+Then, create a directory called `db/seed_files`, and create a csv file called
+`db/seed_files/users.csv`. In this file, the header should be the field names,
+and the rest of the rows should be the corresponding data.
+
+```
+email,username
+test1@example.com,test1
+test2@example.com,test2
+```
+
+If the CSV files are not located in the project, you can specify a `:csv_file`
+option. Note that the value must be a full path.
+
+```ruby
+class UsersSeeder < Planter::Seeder
+  seeding_method :standard_csv, csv_file: '/home/me/users.csv'
+end
+```
+
+Running `rails db:seed` will now seed your `users` table.
+
+## Seeding from a data array
+If you need dynamic seeds, you can add something similar to the following to
+your seeder class. In this example, we'll use
+[faker](https://github.com/faker-ruby/faker).
+
+```ruby
+require 'faker' # You should really just require this in `db/seeds.rb`.
+
+class UsersSeeder < Planter::Seeder
+  seeding_method :data_array, number_of_records: 10
+
+  def data
+    [{
+      email: Faker::Internet.email,
+      username: Faker::Name.name
+    }]
+  end
+end
+```
+
+The `number_of_records` option allows you to only create one array element, but
+create ten records. If you leave this option off, you'll need your array to have
+ten elements to create ten records. It's also worth noting that setting an
+instance variable called `@data` from an `initialize` method would also work, as
+the `Planter::Seeder` parent class automatically provides `attr_reader :data`.
+
+Running `rails db:seed` should now seed your `users` table.
+
+You can also seed children records for every existing record of a parent model.
+For example, to seed an address for every user, you'd need to create an
+`AddressesSeeder` that uses the `parent_model` option, as seen below.
+
+```ruby
+require 'faker'
+
+class AddressesSeeder < Planter::Seeder
+  seeding_method :data_array, parent_model: 'User'
+
+  def data
+    [{
+      street: Faker::Address.street_address,
+      city: Faker::Address.city,
+      state: Faker::Address.state_abbr,
+      zip: Faker::Address.zip
+    }]
+  end
+end
+```
+
+Note that specifying `number_of_records` in this instance will create that many
+records *for each record of the parent model*. You can also specify the
+association if it's different from the table name, using the `assocation:`
+option. Currently, associations are assumed to be as `has_many`, so the
+association is plural by default. Any help with making this more heuristically
+complete would be welcome.
+
+### Custom seeds
+To write your own custom seeds, just overload the `seed` method and do whatever
+you need to do.
+
+```ruby
+class UsersSeeder < Planter::Seeder
+  USERS = {
+    'test1@example.com' => { username: 'John Smith' }
+    'test2@example.com' => { username: 'Jane Smith' }
+  }
+
+  def seed
+    USERS.each { |email, attrs| User.where(email).first_or_create!(attrs) }
+  end
+end
+```
+
+## Customization
+You can change the directories of both the seeder files and the csv files. In
+your `configure` block in `db/seeds.rb`, you can add the following. Note that,
+in both instances, the path should be relative to `Rails.root`.
+
+```ruby
+require 'planter'
+
+Planter.configure do |config|
+  config.seeders_directory = 'db/seeder_classes'
+  config.csv_files_directory = 'db/csvs'
+  config.tables = %i[
+    users
+    addresses
+  ]
+end
+
+Planter.seed
+```
+
+## License
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).
+
+## Reporting Bugs and Requesting Features
+If you have an idea or find a bug, please [create an
+issue](https://github.com/evanthegrayt/planter/issues/new). Just make sure
+the topic doesn't already exist. Better yet, you can always submit a Pull
+Request.
+
+## Self-Promotion
+I do these projects for fun, and I enjoy knowing that they're helpful to people.
+Consider starring [the repository](https://github.com/evanthegrayt/planter)
+if you like it! If you love it, follow me [on
+Github](https://github.com/evanthegrayt)!

data/Rakefile

@@ -0,0 +1,18 @@
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rdoc/task'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.md'
+  rdoc.rdoc_dir = 'doc'
+  rdoc.rdoc_files.include('README.md', 'lib/**/*.rb')
+end
+
+task default: :test

data/lib/planter.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'planter/version'
+require 'planter/railtie'
+require 'planter/config'
+require 'planter/seeder'
+
+##
+# Class that seeders should inherit from. Seeder files should be in +db/seeds+,
+# and named +TABLE_seeder.rb+, where +TABLE+ is the name of the table being
+# seeded (I.E. +users_seeder.rb+). The seeder's class name should be the same
+# as the file name, but camelized. So, +UsersSeeder+. The directory where the
+# seeder files are located can be changed via an initializer.
+#
+# The most basic way to seed is to have a CSV file with the same name as the
+# table in +db/seed_files/+. So, +users.csv+. This CSV should have the table's
+# column names as header. To seed using this method, your class should look
+# like the following. Note that +:csv_file+ is not required; it defaults to the
+# table name with a +csv+ file extension. The directory where the seed files
+# are kept can be changed via an initializer.
+#   # db/seeds/users_seeder.rb
+#   require 'planter'
+#   class UsersSeeder < Planter::Seeder
+#     seeding_method :standard_csv, csv_file: '/home/me/users.csv'
+#   end
+#
+# Another way to seed is to create records from a data array. To do this, your
+# class must implement a +data+ attribute or method, which is an array of
+# hashes. Note that this class already provides the +attr_reader+ for this
+# attribute, so the most you have to do it create instance variables in your
+# constructor. If if you want your data to be different for each new record
+# (via Faker, +Array#sample+, etc.), you'll probably want to supply a method
+# called data that returns an array of new data each time.
+#   require 'planter'
+#   class UsersSeeder < Planter::Seeder
+#     seeding_method :data_array
+#     def data
+#       [{foo: 'bar', baz: 'bar'}]
+#     end
+#   end
+#
+# In both of the above methods, you can specify +parent_model+ and
+# +association+. If specified, records will be created via that parent model's
+# association. If +association+ is not provided, it will be assumed to be the
+# model name, pluralized and snake-cased (implying a +has_many+ relationship).
+# For example, if we're seeding the users table, and the model is +User+, the
+# association will default to +users+.
+#   require 'planter'
+#   class UsersSeeder < Planter::Seeder
+#     seeding_method :data_array, parent_model: 'Person', association: :users
+#     def data
+#       [{foo: 'bar', baz: 'bar'}]
+#     end
+#   end
+#
+# You can also set +number_of_records+ to determine how many times each record
+# in the +data+ array will get created. The default is 1. Note that if this
+# attribute is set alongside +parent_model+ and +association+,
+# +number_of_records+ will be how many records will be created for each record
+# in the parent table.
+#   require 'planter'
+#   class UsersSeeder < Planter::Seeder
+#     seeding_method :data_array, number_of_records: 5
+#     def data
+#       [{foo: 'bar', baz: 'bar'}]
+#     end
+#   end
+#
+# If you need to seed a different way, put your own custom +seed+ method in
+# your seeder class and do whatever needs to be done.
+module Planter
+  ##
+  # The seeder configuration.
+  #
+  # @return [Planter::Config]
+  def self.config
+    @config ||= Planter::Config.new
+  end
+
+  ##
+  # Resets the config back to its initial state.
+  #
+  # @return [Planter::Config]
+  def self.reset_config
+    @config = Planter::Config.new
+  end
+
+  ##
+  # Quick way of configuring the directories via an initializer.
+  #
+  # @return [self]
+  #
+  # @example
+  #   Planter.configure do |app_seeder|
+  #     app_seeder.tables = %i[users]
+  #     app_seeder.seeders_directory = 'db/seeds'
+  #     app_seeder.csv_files_directory = 'db/seed_files'
+  #   end
+  def self.configure
+    config.tap { |c| yield c }
+  end
+
+  ##
+  # This is the method to call from your +db/seeds.rb+. It seeds the tables
+  # listed in +Planter.config.tables+. To seed specific tables at
+  # runtime, you can set the +TABLES+ environmental variable to a
+  # comma-separated list of tables.
+  #
+  # @example
+  #   rails db:seed TABLES=users,accounts
+  def self.seed
+    tables = ENV['TABLES']&.split(',') || config.tables&.map(&:to_s)
+    raise RuntimeError, 'No tables specified; nothing to do' unless tables&.any?
+
+    tables.each do |table|
+      require Rails.root.join(config.seeders_directory, "#{table}_seeder.rb").to_s
+      puts "Seeding #{table}" unless config.quiet
+      "#{table.camelize}Seeder".constantize.new.seed
+    end
+  end
+end

data/lib/planter/config.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Planter
+  ##
+  # Configure the application seeder.
+  #
+  # @example
+  #   Planter.configure { |seeder| seeder.tables = %i[users] }
+  class Config
+    ##
+    # Tell the application where the seeder classes are kept. Must be a path
+    # relative to +Rails.root+.
+    #
+    # @param [String] directory
+    #
+    # @return [String]
+    attr_accessor :seeders_directory
+
+    ##
+    # Tell the application where the CSV seed files are kept. Must be a path
+    # relative to +Rails.root+.
+    #
+    # @param [String] directory
+    #
+    # @return [String]
+    attr_accessor :csv_files_directory
+
+    ##
+    # Tell the application what tables to seed. Elements should be in the correct
+    # order, and can be strings or symbols.
+    #
+    # @param [Array] tables
+    #
+    # @return [Array]
+    attr_accessor :tables
+
+    ##
+    # When true, don't print output when seeding.
+    #
+    # @param [Boolean] quiet
+    #
+    # @return [Boolean]
+    attr_accessor :quiet
+
+    ##
+    # Create a new instance of the config.
+    def initialize
+      @quiet = false
+      @seeders_directory = ::File.join('db', 'seeds')
+      @csv_files_directory = ::File.join('db', 'seed_files')
+    end
+  end
+end

data/lib/planter/railtie.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Planter
+  class Railtie < ::Rails::Railtie # :nodoc:
+  end
+end

data/lib/planter/seeder.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Planter
+  ##
+  # The class your seeder files should inherit from.
+  class Seeder
+    ##
+    # The allowed seeding methods.
+    #
+    # @return [Array]
+    SEEDING_METHODS = %i[standard_csv data_array].freeze
+
+    ##
+    # Array of hashes used to create records. Your class must set this
+    # attribute when using +data_hash+ seeding method, although it's probably
+    # more likely that you'll want to define a method that returns a new set of
+    # data each time (via +Faker+, +Array#sample+, etc.). When using
+    # +standard_csv+, +data+ will be set to the data within the csv. You can
+    # override this.
+    #
+    # @return [Array]
+    attr_reader :data
+
+    ##
+    # If your class is going to use the inherited +seed+ method, you must tell
+    # it which +seeding_method+ to use. The argument to this method must be
+    # included in the +SEEDING_METHODS+ array.
+    #
+    # @param [Symbol] seeding_method
+    #
+    # @param [Hash] options
+    #
+    # @example
+    #   require 'planter'
+    #   class UsersSeeder < Planter::Seeder
+    #     seeding_method :data_array,
+    #       model: 'User'
+    #       parent_model: 'Person',
+    #       association: :users,
+    #       number_of_records: 2
+    #   end
+    def self.seeding_method(method, **options)
+      if !SEEDING_METHODS.include?(method.intern)
+        raise ArgumentError, "Method must be one of #{SEEDING_METHODS.join(', ')}"
+      elsif options[:association] && !options[:parent_model]
+        raise ArgumentError, "Must specify :parent_model with :association"
+      end
+
+      @seeding_method = method
+      @number_of_records = options.fetch(:number_of_records, 1)
+      @model = options.fetch(:model, to_s.delete_suffix('Seeder').singularize)
+      @parent_model = options[:parent_model]
+      @association = @parent_model && options.fetch(:association) do
+        determine_association(options)
+      end
+      return unless @seeding_method == :standard_csv
+
+      @csv_file = options.fetch(:csv_file, Rails.root.join(
+        Planter.config.csv_files_directory,
+        "#{to_s.delete_suffix('Seeder').underscore}.csv"
+      ).to_s)
+    end
+
+    def self.determine_association(options) # :nodoc:
+      associations =
+        @parent_model.constantize.reflect_on_all_associations.map(&:name)
+      table = to_s.delete_suffix('Seeder').underscore.split('/').last
+
+      [table, table.singularize].map(&:intern).each do |t|
+        return t if associations.include?(t)
+      end
+
+      raise ArgumentError, 'Could not determine association name'
+    end
+    private_class_method :determine_association
+
+    ##
+    # The default seed method. To use this method, your class must provide a
+    # valid +seeding_method+, and not implement its own +seed+ method.
+    def seed
+      validate_attributes
+
+      parent_model ? create_records_from_parent : create_records
+    end
+
+    protected
+
+    ##
+    # The seeding method specified.
+    #
+    # @return [Symbol]
+    def seeding_method
+      @seeding_method ||= self.class.instance_variable_get('@seeding_method')
+    end
+
+    ##
+    # The model for the table being seeded. If the model name you need is
+    # different, change via +seeding_method+.
+    #
+    # @return [String]
+    def model
+      @model ||= self.class.instance_variable_get('@model')
+    end
+
+    ##
+    # The model of the parent. When provided with +association+, records in the
+    # +data+ array, will be created for each record in the parent table. Your
+    # class must set this attribute via +seeding_method+.
+    #
+    # @return [String]
+    def parent_model
+      @parent_model ||= self.class.instance_variable_get('@parent_model')
+    end
+
+    ##
+    # When using +parent_model+, the association name. Your class can set this
+    # attribute via +seeding_method+.
+    #
+    # @return [Symbol]
+    def association
+      @association ||= self.class.instance_variable_get('@association')
+    end
+
+    ##
+    # The number of records to create from each record in the +data+ array. If
+    # nil, defaults to 1, but you can override this in your class via
+    # +seeding_method+.
+    #
+    # @return [Integer]
+    def number_of_records
+      @number_of_records ||=
+        self.class.instance_variable_get('@number_of_records')
+    end
+
+    ##
+    # The csv file corresponding to the model.
+    #
+    # @return [String]
+    def csv_file
+      @csv_file ||= self.class.instance_variable_get('@csv_file')
+    end
+
+    ##
+    # Creates records from the +data+ attribute.
+    def create_records
+      data.each do |rec|
+        number_of_records.times do
+          model.constantize.where(
+            rec.transform_values { |value| value == 'NULL' ? nil : value }
+          ).first_or_create!
+        end
+      end
+    end
+
+    ##
+    # Create records from the +data+ attribute for each record in the
+    # +parent_table+, via the specified +association+.
+    def create_records_from_parent
+      parent_model.constantize.all.each do |assoc_rec|
+        number_of_records.times do
+          data.each { |rec| send(create_method, assoc_rec, association, rec) }
+        end
+      end
+    end
+
+    private
+
+    def create_method
+      parent_model.constantize.reflect_on_association(
+        association
+      ).macro.to_s.include?('many') ? :create_has_many : :create_has_one
+    end
+
+    def create_has_many(assoc_rec, association, rec)
+      assoc_rec.public_send(association).where(rec).first_or_create!
+    end
+
+    def create_has_one(assoc_rec, association, rec)
+      assoc_rec.public_send("create_#{association}", rec)
+    end
+
+    def validate_attributes # :nodoc:
+      case seeding_method.intern
+      when :standard_csv
+        raise "#{csv_file} does not exist" unless ::File.file?(csv_file)
+
+        @data ||= ::CSV.table(csv_file).map(&:to_hash)
+      when :data_array
+        raise "Must define '@data'" if public_send(:data).nil?
+      else
+        raise("Must set 'seeding_method'")
+      end
+    end
+  end
+end

data/lib/planter/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Planter
+  ##
+  # Gem version, semantic.
+  VERSION = '0.0.2'.freeze
+end

data/lib/tasks/planter_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :planter do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: planter
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Evan Gray
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-05-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.1.3
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.1.3
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.3.1
+description: Create a seeder for each table in your database, and easily seed from
+  CSV or custom methods
+email:
+- evanthegrayt@vivaldi.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/planter.rb
+- lib/planter/config.rb
+- lib/planter/railtie.rb
+- lib/planter/seeder.rb
+- lib/planter/version.rb
+- lib/tasks/planter_tasks.rake
+homepage: https://github.com/evanthegrayt/planter
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/evanthegrayt/planter
+  source_code_uri: https://github.com/evanthegrayt/planter
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key: 
+specification_version: 4
+summary: Framework for seeding rails applications.
+test_files: []