oaken 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7a49242a569f0460aab42af0102a0aeec30095909c6362310b45e9ce0638c43
-  data.tar.gz: 218c22c32d91b4deaf4f3524f4a19daea964df126c3018b048a2a1119c679297
+  metadata.gz: 81f5e7a3ea1f5236b6e2726d1ecd24dee5698b59dc5e73f80ce618181b1dffe1
+  data.tar.gz: 6c4628800cdc44acd516a8e51a708fdee3d63ce506679fa5bc742b337da5c725
 SHA512:
-  metadata.gz: 40f50f45dd4bfc45b326aacc111792b30a178446e3f51b1db9b0e9c0f95f91d6b3269a28fc3aaf8d797d5def0c6a6f1dad0ae6d61e4d1fe44aed7b994fb66dda
-  data.tar.gz: 9c21c825239bf7bb910632abe86d6672f63dcf9fe50d0cdf42270f03aed09ff9cad3268e6e5ec70957717996193791a43c67d2cab803ad4e16efce313f29fed6
+  metadata.gz: 5257b630ef4ac76db5b9fceb161df47d71e1df3481d1fdcd45fb1ac35319a72568d084f6e48a158cca3217512382890d5919111f329b08798f388e46d4ff5014
+  data.tar.gz: 2b91b6caeede127715691ecdeab3b8355ba273d9105b11f52579f7c4da2dcfefb7bfbc243ee4cc7b7de2af6401e95e195b4c377d31502ddd0162043e243c07aa

data/README.md

@@ -1,6 +1,17 @@
 # Oaken
 
-Oaken is an alternative to fixtures and/or factories to manage your development, test and some production data using data scripts.
+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.
+
+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
 
@@ -16,7 +27,7 @@ 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.
+Here's what they could look like:
 
 ```ruby
 # db/seeds/accounts/kaspers_donuts.rb
@@ -38,12 +49,12 @@ orders.insert_all \
 
 ```ruby
 # db/seeds/data/plans.rb
-plans.insert :basic, title: "Basic", price_cents: 10_00
+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` — plus Oaken skips executing a seed file if it knows the file hasn't been changed since the last seeding. Speedy!
+Now you can run `bin/rails db:seed` and `bin/rails db:seed:replant`.
 
 ### Interlude: Directory Naming Conventions
 
@@ -53,45 +64,57 @@ Oaken has some chosen directory conventions to help strengthen your understandin
 - `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`.
 
+### Using default attributes
+
+You can set up default attributes that's applied to created/inserted records at different levels, like this:
+
+```ruby
+Oaken.prepare do
+  # Assign broad global defaults for every type.
+  defaults name: -> { Faker::Name.name }, public_key: -> { SecureRandom.hex }
+
+  # Assign a more specific default on one type, which overrides the global default above.
+  accounts.defaults name: -> { Faker::Business.name }
+end
+```
+
+> [!TIP]
+> `defaults` are particularly well suited for assigning generated data with [Faker](https://github.com/faker-ruby/faker).
+
 ### Reusing data in tests
 
-With the setup above, Oaken can reuse the same data in tests like so:
+With the setup above, Oaken can reuse the same data in tests like this:
 
 ```ruby
 # test/test_helper.rb
 class ActiveSupport::TestCase
-  include Oaken.seeds
-
-  # Override Minitest::Test#run to wrap each test in a transaction.
-  def run
-    result = nil
-    ActiveRecord::Base.transaction(requires_new: true) do
-      result = super
-      raise ActiveRecord::Rollback
-    end
-    result
-  end
+  include Oaken::TestSetup
 end
 ```
 
 Now tests have access to `accounts.kaspers_donuts` and `users.kasper` etc. that were setup in the data scripts.
 
+> [!NOTE]
+> For RSpec, you can put this in `spec/rails_helper.rb`:
+> ```ruby
+> require "oaken/rspec_setup"
+> ```
+
 You can also load a specific seed, like this:
 
 ```ruby
 class PaginationTest < ActionDispatch::IntegrationTest
-  seed "cases/pagination"
+  setup { seed "cases/pagination" }
 end
 ```
 
-### Resetting cache
-
-Oaken is still early days, so you may need to reset the cache that skips seed files. Pass `OAKEN_RESET` to clear it:
-
-```sh
-OAKEN_RESET=1 bin/rails db:seed
-OAKEN_RESET=1 bin/rails test
-```
+> [!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
 
@@ -113,7 +136,7 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Development
 
-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.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `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).
 

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

@@ -86,7 +86,7 @@ class Oaken::Convert::FixturesGenerator < Rails::Generators::Base
 
     code  = +"Oaken.prepare do\n"
     code << "  register #{namespaces.join(", ")}\n\n" if namespaces.any?
-    code << "  load :#{@root_model.plural}, :data\n"
+    code << "  seed :#{@root_model.plural}, :data\n"
     code << "end\n"
 
     inject_into_file "db/seeds.rb", code, before: /\A/

data/lib/oaken/railtie.rb

@@ -1,25 +1,5 @@
 class Oaken::Railtie < Rails::Railtie
-  initializer "oaken.defaults" do
+  initializer "oaken.lookup_paths" do
     Oaken.lookup_paths << "db/seeds/#{Rails.env}"
-    Oaken.store_path = Oaken.store_path.join(Rails.env)
-  end
-
-  rake_tasks do
-    namespace :oaken do
-      task("reset")     { Oaken.store_path.rmtree }
-      task("reset:all") { Oaken.store_path.dirname.rmtree }
-
-      task "reset:include_test" do
-        # Some db: tasks in development also manipulate the test database.
-        Oaken.store_path.sub("development", "test").rmtree if Rails.env.development?
-      end
-    end
-
-    task "db:drop"      => ["oaken:reset", "oaken:reset:include_test"]
-    task "db:purge"     => ["oaken:reset", "oaken:reset:include_test"]
-    task "db:purge:all" => ["oaken:reset:all"]
-
-    # db:seed:replant runs trunacte_all, after trial-and-error we need to hook into that and not the replant task.
-    task "db:truncate_all" => "oaken:purge"
   end
 end

data/lib/oaken/rspec_setup.rb

@@ -0,0 +1,10 @@
+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

@@ -1,41 +1,110 @@
 module Oaken::Seeds
   extend self
 
-  def self.respond_to_missing?(name, ...)
-    Oaken.inflector.classify(name).safe_constantize || super
-  end
+  # Allow assigning defaults across different types.
+  def self.defaults(**defaults) = attributes.merge!(**defaults)
+  def self.defaults_for(*keys) = attributes.slice(*keys)
+  def self.attributes = @attributes ||= {}.with_indifferent_access
 
+  # Oaken's main auto-registering logic.
+  #
+  # So when you first call e.g. `accounts.create`, we'll hit `method_missing` here
+  # and automatically call `register Account`.
+  #
+  # We'll also match partial and full nested namespaces like in this order:
+  #
+  #   accounts => Account
+  #   account_jobs => AccountJob | Account::Job
+  #   account_job_tasks => AccountJobTask | Account::JobTask | Account::Job::Task
+  #
+  # If you have classes that don't follow this naming convention, you must call `register` manually.
   def self.method_missing(meth, ...)
-    name = meth.to_s
-    if type = Oaken.inflector.classify(name).safe_constantize
-      register type, name
-      public_send(name, ...)
+    name = meth.to_s.classify
+    name = name.sub!(/(?<=[a-z])(?=[A-Z])/, "::") until name.nil? or type = name.safe_constantize
+
+    if type
+      register type
+      public_send(meth, ...)
     else
       super
     end
   end
+  def self.respond_to_missing?(name, ...) = name.to_s.classify.safe_constantize || super
 
-  def self.register(type, key = nil)
-    stored = provider.new(type, key) and define_method(stored.key) { stored }
+  # Register a model class to be accessible as an instance method via `include Oaken::Seeds`.
+  # Note: Oaken's auto-register via `method_missing` means it's less likely you need to call this manually.
+  #
+  #   register Account, Account::Job, Account::Job::Task
+  #
+  # Oaken uses the `table_name` of the passed classes for the method names, e.g. here they'd be
+  # `accounts`, `account_jobs`, and `account_job_tasks`, respectively.
+  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
 
-  singleton_class.attr_reader :loader
-  delegate :entry, to: :loader
-
-  module Loading
+  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.each do |path|
-        directories.each do |directory|
-          @loader = Oaken::Loader.new Pathname(path).join(directory.to_s)
-          @loader.load_onto Oaken::Seeds
-        end
+      Oaken.lookup_paths.product(directories).each do |path, directory|
+        load_from Pathname(path).join(directory.to_s)
       end
     end
-  end
-  extend Loading
 
-  def self.included(klass)
-    klass.extend Loading
+    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

@@ -1,8 +1,9 @@
-class Oaken::Stored::ActiveRecord < Struct.new(:type, :key)
-  def initialize(type, key = nil)
-    super(type, key || Oaken.inflector.tableize(type.name))
-    @attributes = {}
+class Oaken::Stored::ActiveRecord
+  def initialize(type)
+    @type, @key = type, type.table_name
+    @attributes = Oaken::Seeds.defaults_for(*type.column_names)
   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
 
@@ -11,30 +12,34 @@ class Oaken::Stored::ActiveRecord < Struct.new(:type, :key)
     @attributes
   end
 
-  def create(reader = nil, **attributes)
-    lineno = caller_locations(1, 1).first.lineno
-
+  def create(label = nil, unique_by: nil, **attributes)
     attributes = @attributes.merge(attributes)
     attributes.transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
 
-    type.create!(**attributes).tap do |record|
-      define_reader reader, record.id, lineno if reader
-    end
-  end
+    finders  = attributes.slice(*unique_by)
+    record   = type.find_by(finders)&.tap { _1.update!(**attributes) } if finders.any?
+    record ||= type.create!(**attributes)
 
-  def insert(reader = nil, **attributes)
-    lineno = caller_locations(1, 1).first.lineno
+    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!
-    type.insert(attributes).tap do
-      define_reader reader, type.where(attributes).pick(:id), lineno if reader
-    end
+    record = type.new(id: type.upsert(attributes, unique_by: unique_by, returning: :id).rows.first.first)
+    label label => record if label
+    record
   end
 
-  def define_reader(...)
-    Oaken::Seeds.entry.define_reader(self, ...)
+  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.5.0"
+  VERSION = "0.7.0"
 end

data/lib/oaken.rb

@@ -6,64 +6,30 @@ require "pathname"
 module Oaken
   class Error < StandardError; end
 
-  autoload :Seeds, "oaken/seeds"
-  autoload :Entry, "oaken/entry"
+  autoload :Seeds,     "oaken/seeds"
+  autoload :TestSetup, "oaken/test_setup"
 
   module Stored
     autoload :ActiveRecord, "oaken/stored/active_record"
   end
 
-  class Inflector
-    def tableize(string)
-      string.gsub(/(?<=[a-z])(?=[A-Z])/, "_").gsub("::", "_").tap(&:downcase!) << "s"
-    end
-
-    def classify(string)
-      string.chomp("s").gsub(/_([a-z])/) { $1.upcase }.sub(/^\w/, &:upcase)
-    end
-  end
-
-  singleton_class.attr_accessor :inflector
-  @inflector = Inflector.new
-
   singleton_class.attr_reader :lookup_paths
   @lookup_paths = ["db/seeds"]
 
-  singleton_class.attr_accessor :store_path
-  @store_path = Pathname.new "tmp/oaken/store"
-
   class Loader
-    attr_reader :entry
-
     def initialize(path)
-      @entries, @entry = Entry.within(path), nil
+      @entries = Pathname.glob("#{path}{,/**/*}.rb").sort
     end
 
-    def load_onto(seeds)
-      @entries.each do |entry|
-        @entry = entry
-        @entry.load_onto seeds
+    def load_onto(seeds) = @entries.each do |path|
+      ActiveRecord::Base.transaction do
+        seeds.class_eval path.read, path.to_s
       end
     end
   end
 
-  def self.transaction(&block)
-    ActiveRecord::Base.transaction(&block)
-  end
-
-  def self.prepare(&block)
-    store_path.rmtree if ENV["OAKEN_RESET"]
-    Seeds.instance_eval(&block)
-    Seeds
-  end
-
-  def self.seeds
-    unless defined?(@loaded)
-      @loaded = true
-      Rails.application.load_seed
-    end
-    Seeds
-  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.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Kasper Timm Hansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-16 00:00:00.000000000 Z
+date: 2024-06-30 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -24,10 +24,11 @@ files:
 - Rakefile
 - lib/generators/oaken/convert/fixtures_generator.rb
 - lib/oaken.rb
-- lib/oaken/entry.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://github.com/kaspth/oaken
 licenses:
@@ -52,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.10
 signing_key:
 specification_version: 4
 summary: Oaken aims to blend your Fixtures/Factories and levels up your database seeds.

data/lib/oaken/entry.rb

@@ -1,60 +0,0 @@
-require "digest/md5"
-require "pstore"
-
-class Oaken::Entry < DelegateClass(PStore)
-  def self.store_accessor(name)
-    define_method(name) { self[name] } and define_method("#{name}=") { |value| self[name] = value }
-  end
-  store_accessor :checksum
-  store_accessor :readers
-
-  def self.within(directory)
-    Pathname.glob("#{directory}{,/**/*}.{rb,sql}").sort.map { new _1 }
-  end
-
-  def initialize(pathname)
-    @file, @pathname = pathname.to_s, pathname
-    @computed_checksum = Digest::MD5.hexdigest(@pathname.read)
-
-    prepared_store_path = Oaken.store_path.join(pathname).tap { _1.dirname.mkpath }
-    super PStore.new(prepared_store_path)
-  end
-
-  def load_onto(seeds)
-    transaction do
-      if replay?
-        puts "Replaying #{@file}…"
-        readers.each do |key, *args|
-          define_reader(seeds.send(key), *args)
-        end
-      else
-        reset
-
-        case @pathname.extname
-        in ".rb"  then seeds.class_eval @pathname.read, @file
-        in ".sql" then ActiveRecord::Base.connection.execute @pathname.read
-        end
-      end
-    end
-  end
-
-  def transaction(&block)
-    super do
-      Oaken.transaction(&block)
-    end
-  end
-
-  def replay?
-    checksum == @computed_checksum
-  end
-
-  def reset
-    self.checksum = @computed_checksum
-    self.readers  = Set.new
-  end
-
-  def define_reader(stored, name, id, lineno)
-    stored.instance_eval "def #{name}; find #{id}; end", @file, lineno
-    readers << [stored.key, name, id, lineno]
-  end
-end