oaken 0.2.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 160e746d1605f0e227c7084ce39ee6e05837cfe4288de735b4407c39a45d4fbe
-  data.tar.gz: 9510c077a7f0f7bad0ebc56bfb6306cf2465253a04d6c19f28009a3552a47719
+  metadata.gz: 3d441d9ce6156b7fa0f30b188f1f1e09a065292fb520c8415e8eae3e3b3f6aef
+  data.tar.gz: b69bc4be147d5dca48ded82969b8abee63f10fd81b53015bf3c236d2abfcaadc
 SHA512:
-  metadata.gz: 393bd015fadfb6e806a49f43be92fbf764d89c15577f91963361cef6d8221ba8cbd2992c0edba6b38920831dbe3299482b12c3c46e1b2f5b593617ce8c697ccf
-  data.tar.gz: 3e6480a0ef119fa5929f44a6481359d7247ff4da4b4fcbc45225c90e98ad1c0897857f63d29c685b2a6af70f663724606360bb9487802fc9ac5995b8930ead9f
+  metadata.gz: 22c8eb550e6564429fed5302807d5586b77f8e19c2a5c097d168d23dec0bec25f8595db8a79ee654cdc24f67b7c1dbcb8c758c0dab38ffb03ccb823374e5ce94
+  data.tar.gz: 7dcd270301eb5994cdfac1c2630e9a0c27ba45df0bf851f54dc78e47273625e8500bf357649eab7f04481ae8bb4bc68144813eb831229bc66814df0196defe33

data/README.md

@@ -1,22 +1,119 @@
 # Oaken
 
-The gem we're building in the Open Source Retreat https://kaspthrb.gumroad.com/l/open-source-retreat
+Oaken is a new take on development and test data management for your Rails app. It blends the stability and storytelling from Fixtures with the dynamicness of FactoryBot/Fabricator.
 
-## Installation
+Fixtures are stable & help you build a story of how your app and its object graph exists along with edge cases, but the UX is unfortunately a nightmare.
+To trace N associations, you have to open and read N different files — there's no way to group by scenario.
+
+FactoryBot is spray & pray. You basically say “screw it, just give me the bare minimum I need to run this test”, which slows everything down because there’s no cohesion; and the Factories are always suspect in terms of completeness. Sure, I got the test to pass by wiring these 5 Factories together but did I miss something?
+
+Oaken instead upgrades seeds in `db/seeds.rb`, so that you can put together scenarios & also reuse the development data in tests. That way the data you see in your development browser, is the same data you work with in tests to tie it more together — especially for people who are new to your codebase.
+
+So you get the stability of named keys, a cohesive dataset, and a story like Fixtures. But the dynamics of FactoryBot as well. And unlike FactoryBot, you’re not making tons of one-off records to handle each case.
+
+While Fixtures and FactoryBot both load data & truncate in tests, the end result is you end up writing less data back & forth to the database because you aren’t cobbling stuff together.
+
+## Setup
+
+### Starting in development
+
+You can set it up in `db/seeds.rb`, like this:
+
+```ruby
+Oaken.prepare do
+  seed :accounts, :data
+end
+```
+
+This will look for deeply nested files to load in `db/seeds` and `db/seeds/#{Rails.env}` within the `accounts` and `data` directories.
+
+Here's what they could look like:
+
+```ruby
+# db/seeds/accounts/kaspers_donuts.rb
+donuts = accounts.create :kaspers_donuts, name: "Kasper's Donuts"
+
+kasper   = users.create :kasper,   name: "Kasper",   accounts: [donuts]
+coworker = users.create :coworker, name: "Coworker", accounts: [donuts]
+
+menu = menus.create account: donuts
+plain_donut     = menu_items.create menu: menu, name: "Plain",     price_cents: 10_00
+sprinkled_donut = menu_items.create menu: menu, name: "Sprinkled", price_cents: 10_10
+
+supporter = users.create name: "Super Supporter"
+orders.insert_all [user_id: supporter.id, item_id: plain_donut.id] * 10
+
+orders.insert_all \
+  10.times.map { { user_id: users.create(name: "Customer #{_1}").id, item_id: menu.items.sample.id } }
+```
+
+```ruby
+# db/seeds/data/plans.rb
+plans.upsert :basic, title: "Basic", price_cents: 10_00
+```
+
+Seed files will generally use `create` and/or `insert`. Passing a symbol to name the record is useful when reusing the data in tests.
+
+Now you can run `bin/rails db:seed` and `bin/rails db:seed:replant`.
+
+### Interlude: Directory Naming Conventions
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Oaken has some chosen directory conventions to help strengthen your understanding of your object graph:
+
+- Have a directory for your top-level model, like `Account`, `Team`, `Organization`, that's why we have `db/seeds/accounts` above.
+- `db/seeds/data` for any data tables, like the plans a SaaS app has.
+- `db/seeds/tests/cases` for any specific cases that are only used in some tests, like `pagination.rb`.
+
+### Reusing data in tests
+
+With the setup above, Oaken can reuse the same data in tests like this:
+
+```ruby
+# test/test_helper.rb
+class ActiveSupport::TestCase
+  include Oaken::TestSetup
+end
+```
+
+Now tests have access to `accounts.kaspers_donuts` and `users.kasper` etc. that were setup in the data scripts.
+
+You can also load a specific seed, like this:
+
+```ruby
+class PaginationTest < ActionDispatch::IntegrationTest
+  setup { seed "cases/pagination" }
+end
+```
+
+> [!NOTE]
+> We're recommending having one-off seeds on an individual unit of work to help reinforce test isolation. Having some seed files be isolated also helps:
+>
+> - Reduce amount of junk data generated for unrelated tests
+> - Make it easier to debug a particular test
+> - Reduce test flakiness
+> - Encourage writing seed files for specific edge-case scenarios
+
+### Fixtures Converter
+
+You can convert your Rails fixtures to Oaken's seeds by running:
+
+    $ bin/rails generate oaken:convert:fixtures
+
+This will convert anything in test/fixtures to db/seeds. E.g. `test/fixtures/users.yml` becomes `db/seeds/users.rb`.
+
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ bundle add oaken
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ gem install oaken
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `cd test/dummy` and `bin/rails test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
@@ -30,4 +127,21 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Oaken project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kaspth/oaken/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Oaken project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/kaspth/oaken/blob/main/CODE_OF_CONDUCT.md).
+
+## Support
+
+Initial development is supported in part by:
+
+<a href="https://arrows.to">
+ <img src="https://user-images.githubusercontent.com/56947/258236465-06c692a7-738e-44bd-914e-fecc697317ce.png" />
+</a>
+
+And by:
+
+- [Alexandre Ruban](https://github.com/alexandreruban)
+- [Lars Kronfält](https://github.com/larkro)
+- [Manuel Costa Reis](https://github.com/manuelfcreis)
+- [Thomas Cannon](https://github.com/tcannonfodder)
+
+As a sponsor you're welcome to submit a pull request to add your own name here.

data/lib/generators/oaken/convert/fixtures_generator.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "yaml"
+
+module Oaken::Convert; end
+class Oaken::Convert::Fixture
+  attr_reader :model_name, :name
+
+  def initialize(model_name, name, attributes)
+    @model_name, @name, @attributes = model_name.tr("/", "_"), name, attributes
+    @plural = @model_name
+    @singular = @model_name.singularize
+  end
+
+  def extract_dependents(fixtures)
+    @dependents = fixtures.select { _1.reference(plural, singular) == name }
+    fixtures.replace fixtures - dependents
+
+    dependents.each { _1.extract_dependents fixtures }
+  end
+
+  def reference(plural, singular)
+    @referenced = [plural, :plural]     if attributes[plural]
+    @referenced = [singular, :singular] if attributes[singular]
+    attributes[@referenced&.first]
+  end
+
+  def render(delimiter: "\n")
+    [render_self, dependents&.map { _1.render delimiter: nil }].join(delimiter)
+  end
+
+  private
+    attr_reader :attributes, :dependents
+    attr_reader :plural, :singular
+
+    def render_self
+      "#{model_name}.create :#{name}, #{convert_hash(attributes)}\n".tap do
+        _1.prepend "#{name} = " if dependents&.any?
+      end
+    end
+
+    def convert_hash(hash)
+      hash.map { |k, v| "#{k}: #{recursive_convert(v, key: k)}" }.join(", ")
+    end
+
+    def recursive_convert(input, key: nil)
+      case input
+      when Hash  then "{ #{convert_hash(input)} }"
+      when Array then input.map { recursive_convert _1 }.join(", ")
+      when Integer then input
+      else
+        if key == @referenced&.first
+          @referenced.last == :plural ? "[#{input}]" : input
+        else
+          "\"#{input}\""
+        end
+      end
+    end
+end
+
+class Oaken::Convert::FixturesGenerator < Rails::Generators::Base
+  desc "Converts fixtures to Oaken seeds in db/seeds/test"
+  source_root File.expand_path("templates", __dir__)
+
+  class_option :root_model, required: true
+  class_option :keeps, type: :boolean, default: true
+
+  def prepare
+    @root_model = ActiveModel::Name.new(options[:root_model].constantize)
+    empty_directory_with_keep_file "db/seeds/data"
+    empty_directory_with_keep_file "db/seeds/test/cases"
+  end
+
+  def parse
+    @fixtures = Dir.glob("test/fixtures/**/*.yml").to_h do |path|
+      model_name = path.delete_prefix("test/fixtures/").chomp(".yml")
+      [model_name, YAML.load_file(path).presence&.map { Oaken::Convert::Fixture.new(model_name, _1, _2) }]
+    rescue Psych::SyntaxError
+      say "Skipped #{path} due to ERB content or other YAML parsing issues.", :yellow
+    end.tap(&:compact_blank!)
+  end
+
+  def prepend_prepare_to_seeds
+    namespaces = @fixtures.keys.filter_map { _1.classify if _1.include?("/") }.uniq.sort
+
+    code  = +"Oaken.prepare do\n"
+    code << "  register #{namespaces.join(", ")}\n\n" if namespaces.any?
+    code << "  seed :#{@root_model.plural}, :data\n"
+    code << "end\n"
+
+    inject_into_file "db/seeds.rb", code, before: /\A/
+  end
+
+  def convert_all
+    roots = @fixtures.delete(@root_model.collection)
+    @fixtures = @fixtures.values.flatten
+
+    roots.each do |fixture|
+      fixture.extract_dependents @fixtures
+      create_file "db/seeds/test/#{@root_model.plural}/#{fixture.name}.rb", fixture.render.chomp
+    end
+
+    @fixtures.group_by(&:model_name).each do |model_name, fixtures|
+      create_file "db/seeds/test/data/#{model_name}.rb", fixtures.map(&:render).join.chomp
+    end
+  end
+
+  private
+    def empty_directory_with_keep_file(name)
+      empty_directory name
+      create_file "#{name}/.keep" if options[:keeps]
+    end
+end

data/lib/oaken/railtie.rb

@@ -0,0 +1,5 @@
+class Oaken::Railtie < Rails::Railtie
+  initializer "oaken.lookup_paths" do
+    Oaken.lookup_paths << "db/seeds/#{Rails.env}"
+  end
+end

data/lib/oaken/rspec_setup.rb

@@ -0,0 +1,11 @@
+RSpec.configure do |config|
+  config.include(Oaken::Seeds)
+
+  config.use_transactional_fixtures = true
+
+  config.before(:suite) do
+    # Mimic fixtures by truncating before inserting.
+    ActiveRecord::Tasks::DatabaseTasks.truncate_all
+    Oaken.load_seed
+  end
+end

data/lib/oaken/seeds.rb

@@ -0,0 +1,83 @@
+module Oaken::Seeds
+  extend self
+
+  def self.method_missing(name, ...)
+    if type = name.to_s.classify.safe_constantize
+      register type
+      public_send(name, ...)
+    else
+      super
+    end
+  end
+  def self.respond_to_missing?(name, ...) = name.to_s.classify.safe_constantize || super
+
+  def self.register(*types)
+    types.each do |type|
+      stored = provider.new(type) and define_method(stored.key) { stored }
+    end
+  end
+  def self.provider = Oaken::Stored::ActiveRecord
+
+  class << self
+    # Set up a general seed rule or perform a one-off seed for a test file.
+    #
+    # You can set up a general seed rule in `db/seeds.rb` like this:
+    #
+    #   Oaken.prepare do
+    #     seed :accounts # Seeds from `db/seeds/accounts/**/*.rb` and `db/seeds/<Rails.env>/accounts/**/*.rb`
+    #   end
+    #
+    # Then if you need a test specific scenario, we recommend putting them in `db/seeds/test/cases`.
+    #
+    # Say you have `db/seeds/test/cases/pagination.rb`, you can load it like this:
+    #
+    #   # test/integration/pagination_test.rb
+    #   class PaginationTest < ActionDispatch::IntegrationTest
+    #     setup { seed "cases/pagination" }
+    #   end
+    def seed(*directories)
+      Oaken.lookup_paths.product(directories).each do |path, directory|
+        load_from Pathname(path).join(directory.to_s)
+      end
+    end
+
+    private def load_from(path)
+      @loader = Oaken::Loader.new path
+      @loader.load_onto self
+    ensure
+      @loader = nil
+    end
+
+    # `section` is purely for decorative purposes to carve up `Oaken.prepare` and seed files.
+    #
+    #   Oaken.prepare do
+    #     section :roots # Just the very few top-level models like Accounts and Users.
+    #     users.defaults email_address: -> { Faker::Internet.email }, webauthn_id: -> { SecureRandom.hex }
+    #
+    #     section :stems # Models building on the roots.
+    #
+    #     section :leafs # Remaining models, bulk of them, hanging off root and stem models.
+    #
+    #     section do
+    #       seed :accounts, :data
+    #     end
+    #   end
+    #
+    # Since `section` is defined as `def section(*, **) = yield if block_given?`, you can use
+    # all of Ruby's method signature flexibility to help communicate structure better.
+    #
+    # Use positional and keyword arguments, or use blocks to indent them, or combine them all.
+    def section(*, **)
+      yield if block_given?
+    end
+  end
+
+  # Call `seed` in tests to load individual case files:
+  #
+  #   class PaginationTest < ActionDispatch::IntegrationTest
+  #     setup do
+  #       seed "cases/pagination" # Loads `db/seeds/{,test}/cases/pagination{,**/*}.rb`
+  #     end
+  #   end
+  delegate :seed, to: Oaken::Seeds
+end

data/lib/oaken/stored/active_record.rb

@@ -0,0 +1,45 @@
+class Oaken::Stored::ActiveRecord
+  def initialize(type)
+    @type, @key = type, type.table_name
+    @attributes = {}
+  end
+  attr_reader :type, :key
+  delegate :transaction, to: :type # For multi-db setups to help open a transaction on secondary connections.
+  delegate :find, :insert_all, :pluck, to: :type
+
+  def defaults(**attributes)
+    @attributes = @attributes.merge(attributes)
+    @attributes
+  end
+
+  def create(label = nil, unique_by: nil, **attributes)
+    attributes = @attributes.merge(attributes)
+    attributes.transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
+
+    finders  = attributes.slice(*unique_by)
+    record   = type.find_by(finders)&.tap { _1.update!(**attributes) } if finders.any?
+    record ||= type.create!(**attributes)
+
+    label label => record if label
+    record
+  end
+
+  def upsert(label = nil, unique_by: nil, **attributes)
+    attributes = @attributes.merge(attributes)
+    attributes.transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
+
+    type.new(attributes).validate!
+    record = type.new(id: type.upsert(attributes, unique_by: unique_by, returning: :id).rows.first.first)
+    label label => record if label
+    record
+  end
+
+  def label(**labels)
+    # TODO: Fix hardcoding of db/seeds instead of using Oaken.lookup_paths
+    location = caller_locations(1, 6).find { _1.path.match? /db\/seeds\// }
+
+    labels.each do |label, record|
+      class_eval "def #{label} = find(#{record.id})", location.path, location.lineno
+    end
+  end
+end

data/lib/oaken/test_setup.rb

@@ -0,0 +1,24 @@
+module Oaken::TestSetup
+  include Oaken::Seeds
+
+  def self.included(klass)
+    klass.fixtures # Rely on fixtures to setup a shared connection pool and wrap tests in transactions.
+    klass.parallelize_setup { Oaken.load_seed } # No need to truncate as parallel test databases are always empty.
+    klass.prepend BeforeSetup
+  end
+
+  module BeforeSetup
+    # We must inject late enough to call `should_parallelize?`, but before fixtures' `before_setup`.
+    #
+    # So we prepend into `before_setup` and later `super` to have fixtures wrap tests in transactions.
+    def before_setup
+      unless Minitest.parallel_executor.send(:should_parallelize?)
+        ActiveRecord::Tasks::DatabaseTasks.truncate_all # Mimic fixtures by truncating before inserting.
+        Oaken.load_seed
+      end
+
+      Oaken::TestSetup::BeforeSetup.remove_method :before_setup # Only run once, so remove before passing to fixtures in `super`.
+      super
+    end
+  end
+end

data/lib/oaken/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Oaken
-  VERSION = "0.2.0"
+  VERSION = "0.6.0"
 end

data/lib/oaken.rb

@@ -1,8 +1,40 @@
 # frozen_string_literal: true
 
-require_relative "oaken/version"
+require "oaken/version"
+require "pathname"
 
 module Oaken
   class Error < StandardError; end
-  # Your code goes here...
+
+  autoload :Seeds,     "oaken/seeds"
+  autoload :TestSetup, "oaken/test_setup"
+
+  module Stored
+    autoload :ActiveRecord, "oaken/stored/active_record"
+  end
+
+  singleton_class.attr_reader :lookup_paths
+  @lookup_paths = ["db/seeds"]
+
+  class Loader
+    def initialize(path)
+      @entries = Pathname.glob("#{path}{,/**/*}.{rb,sql}").sort
+    end
+
+    def load_onto(seeds)
+      @entries.each do |path|
+        ActiveRecord::Base.transaction do
+          case path.extname
+          when ".rb"  then seeds.class_eval path.read, path.to_s
+          when ".sql" then ActiveRecord::Base.connection.execute path.read
+          end
+        end
+      end
+    end
+  end
+
+  def self.prepare(&block) = Seeds.instance_eval(&block)
+  def self.load_seed = Rails.application.load_seed
 end
+
+require_relative "oaken/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oaken
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Kasper Timm Hansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-20 00:00:00.000000000 Z
+date: 2024-05-13 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -22,14 +22,20 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- lib/generators/oaken/convert/fixtures_generator.rb
 - lib/oaken.rb
+- lib/oaken/railtie.rb
+- lib/oaken/rspec_setup.rb
+- lib/oaken/seeds.rb
+- lib/oaken/stored/active_record.rb
+- lib/oaken/test_setup.rb
 - lib/oaken/version.rb
-homepage: https://kaspthrb.gumroad.com/l/open-source-retreat-summer-2023
+homepage: https://github.com/kaspth/oaken
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://kaspthrb.gumroad.com/l/open-source-retreat-summer-2023
+  homepage_uri: https://github.com/kaspth/oaken
   source_code_uri: https://github.com/kaspth/oaken
   changelog_uri: https://github.com/kaspth/oaken/blob/main/CHANGELOG.md
 post_install_message:
@@ -47,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.17
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: Oaken aims to blend your Fixtures/Factories and levels up your database seeds.