oaken 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5de0c10ab76ddbee3960eda8a9cbf2c8a5b9e1065ded625761c3333a5e3682da
-  data.tar.gz: 42f27cb3adcc4c4d73d8267dcf7f1e30e0923b2773626001e4689fa166cd132d
+  metadata.gz: 43bfd3d777a6a7060eacfda4d23ee10bdb19932547bd6c52e82757b77e897d0e
+  data.tar.gz: 2c81615943933ca2a22f375f2d7afedd07078ea1ca4c71f609970273da5fe0a5
 SHA512:
-  metadata.gz: f933b1ae38aa3b27cd9682282e64fa7e13f1818fa9133c90023d2d0addc5ed3f8f38fc9cac51e55b6b572db7b928fd1890ad4f25881f0c5c7391888dc42e12cc
-  data.tar.gz: 5cddcfc3d65ed8299bb15be1c716e0165bac2f35c4a885f7a80ae0eab1b83085b3883f8edd62df55cba182957a667186b5f6778b3a47d2debc15e4a465666956
+  metadata.gz: 2e13841a16e33779150ba1ba45cf7c4407f1d2f7ead9fb29ca886b93afe2a78fc3394c39899b1f550878b2e0f915f6ceeb52e80582c0fb167e3784a68f453002
+  data.tar.gz: 751a8d8613e43d1af6c5f76ab73be8ee6acc1aa1a6d2b0a3c58250540555d5da1503860e7f3d582d4107da097b840add7e186fe6067344c3bfabd8bc36b5a836

data/README.md

@@ -3,7 +3,7 @@
 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.
 
 > But seriously; Oaken is one of the single greatest tools I've added to my belt in the past year
-> 
+>
 > It's made cross-environment shared data, data prepping for demos, edge-case tests, and overall development much more reliable & shareable across a team
 > [@tcannonfodder](https://github.com/tcannonfodder)
 
@@ -67,7 +67,7 @@ Oaken has some chosen directory conventions to help strengthen your understandin
 
 - 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`.
+- `db/seeds/test/cases` for any specific cases that are only used in some tests, like `pagination.rb`.
 
 ### Using default attributes
 
@@ -113,6 +113,14 @@ class PaginationTest < ActionDispatch::IntegrationTest
 end
 ```
 
+And in RSpec:
+
+```ruby
+RSpec.describe "Pagination", type: :feature do
+  before { 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:
 >
@@ -129,6 +137,25 @@ You can convert your Rails fixtures to Oaken's seeds by running:
 
 This will convert anything in test/fixtures to db/seeds. E.g. `test/fixtures/users.yml` becomes `db/seeds/users.rb`.
 
+### Disable fixtures
+
+IF you've fully converted to Oaken you may no longer want fixtures when running Rails' generators,
+so you can disable generating them in `config/application.rb` like this:
+
+```ruby
+module YourApp
+  class Application < Rails::Application
+    # We prefer Oaken to fixtures, so we disable them here.
+    config.app_generators { _1.test_framework _1.test_framework, fixture: false }
+  end
+end
+```
+
+The `test_framework` repeating is to preserve `:test_unit` or `:rspec` respectively.
+
+> [!NOTE]
+> If you're using `FactoryBot` as well, you don't need to do this since it already replaces fixtures for you.
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/lib/oaken/railtie.rb

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

data/lib/oaken/rspec_setup.rb

@@ -3,8 +3,6 @@ RSpec.configure do |config|
   config.use_transactional_fixtures = true
 
   config.before :suite do
-    # Mimic fixtures by truncating before inserting.
-    ActiveRecord::Tasks::DatabaseTasks.truncate_all
-    Oaken.load_seed
+    Oaken.replant_seed
   end
 end

data/lib/oaken/seeds.rb

@@ -11,36 +11,37 @@ module Oaken::Seeds
   # 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:
+  # We'll also match partial and full nested namespaces:
   #
   #   accounts => Account
-  #   account_jobs => AccountJob | Account::Job
-  #   account_job_tasks => AccountJobTask | Account::JobTask | Account::Job::Task
+  #   account_jobs => Account::Job | AccountJob
+  #   account_job_tasks => Account::JobTask | Account::Job::Task | AccountJob::Task | AccountJobTask
   #
-  # If you have classes that don't follow this naming convention, you must call `register` manually.
+  # If you have classes that don't follow these naming conventions, you must call `register` manually.
   def self.method_missing(meth, ...)
-    name = meth.to_s.classify
-    name = name.sub!(/(?<=[a-z])(?=[A-Z])/, "::") until name.nil? or type = name.safe_constantize
-
-    if type
-      register type
+    if type = Oaken::Type.for(meth.to_s).locate
+      register type, as: meth
       public_send(meth, ...)
     else
       super
     end
   end
-  def self.respond_to_missing?(name, ...) = name.to_s.classify.safe_constantize || super
+  def self.respond_to_missing?(meth, ...) = Oaken::Type.for(meth.to_s).locate || super
 
   # 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
+  # Oaken uses `name.tableize.tr("/", "_")` on the passed classes for the method names, so they're
   # `accounts`, `account_jobs`, and `account_job_tasks`, respectively.
-  def self.register(*types)
+  #
+  # You can also pass an explicit `as:` option, if you'd like:
+  #
+  #   register User, as: :something_else
+  def self.register(*types, as: nil)
     types.each do |type|
-      stored = provider.new(type) and define_method(stored.key) { stored }
+      stored = provider.new(type) and define_method(as || type.name.tableize.tr("/", "_")) { stored }
     end
   end
   def self.provider = Oaken::Stored::ActiveRecord
@@ -62,17 +63,8 @@ module Oaken::Seeds
     #   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
+    def seed(*identifiers)
+      Oaken::Loader.from(identifiers).load_onto self
     end
 
     # `section` is purely for decorative purposes to carve up `Oaken.prepare` and seed files.

data/lib/oaken/stored/active_record.rb

@@ -1,20 +1,14 @@
 class Oaken::Stored::ActiveRecord
   def initialize(type)
-    @type, @key = type, type.table_name
+    @type = type
     @attributes = Oaken::Seeds.defaults_for(*type.column_names)
   end
-  attr_reader :type, :key
+  attr_reader :type
   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 }
+    attributes = attributes_for(**attributes)
 
     finders  = attributes.slice(*unique_by)
     record   = type.find_by(finders)&.tap { _1.update!(**attributes) } if finders.any?
@@ -25,8 +19,7 @@ class Oaken::Stored::ActiveRecord
   end
 
   def upsert(label = nil, unique_by: nil, **attributes)
-    attributes = @attributes.merge(attributes)
-    attributes.transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
+    attributes = attributes_for(**attributes)
 
     type.new(attributes).validate!
     record = type.new(id: type.upsert(attributes, unique_by: unique_by, returning: :id).rows.first.first)
@@ -34,12 +27,57 @@ class Oaken::Stored::ActiveRecord
     record
   end
 
+  # Build attributes used for `create`/`upsert`, applying any global and per-type `defaults`.
+  #
+  #   # db/seeds.rb
+  #   Oaken.prepare do
+  #     defaults name: -> { "Global" }, email_address: -> { … }
+  #     users.defaults name: -> { Faker::Name.name } # This `name` takes precedence on users.
+  #   end
+  #
+  #   users.attributes_for(email_address: "user@example.com") # => { name: "Some Faker Name", email_address: "user@example.com" }
+  def attributes_for(**attributes)
+    @attributes.merge(attributes).transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
+  end
+
+  # Set defaults for this type:
+  #
+  #   # db/seeds.rb
+  #   Oaken.prepare do
+  #     defaults name: -> { "Global" }, email_address: -> { … }
+  #     users.defaults name: -> { Faker::Name.name } # This `name` takes precedence on users.
+  #   end
+  #
+  # These defaults are used and evaluated in `create`/`upsert`/`attributes_for`.
+  #
+  #   users.create # => Uses the users' default `name` and the global `email_address`
+  def defaults(**attributes)
+    @attributes = @attributes.merge(attributes)
+    @attributes
+  end
+
+  # Expose a record instance that's setup outside of using `create`/`upsert`. Like this:
+  #
+  #   users.label someone: User.create!(name: "Someone")
+  #   users.label someone: FactoryBot.create(:user, name: "Someone")
+  #
+  # Now `users.someone` returns the record instance.
+  #
+  # Ruby's Hash argument forwarding also works:
+  #
+  #   someone = users.create(name: "Someone")
+  #   someone_else = users.create(name: "Someone Else")
+  #   users.label someone:, someone_else:
+  #
+  # Note: `users.method(:someone).source_location` also points back to the file and line of the `label` call.
   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 { |label, record| _label label, record.id }
+  end
+
+  private def _label(name, id)
+    raise ArgumentError, "you can only define labelled records outside of tests" \
+      unless location = Oaken::Loader.definition_location
 
-    labels.each do |label, record|
-      class_eval "def #{label} = find(#{record.id})", location.path, location.lineno
-    end
+    class_eval "def #{name} = find(#{id.inspect})", location.path, location.lineno
   end
 end

data/lib/oaken/test_setup.rb

@@ -12,10 +12,8 @@ module Oaken::TestSetup
     #
     # 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
+      # `should_parallelize?` is only defined when Rails' test `parallelize` macro has been called.
+      Oaken.replant_seed unless Minitest.parallel_executor.then { _1.respond_to?(:should_parallelize?, true) && _1.send(:should_parallelize?) }
 
       Oaken::TestSetup::BeforeSetup.remove_method :before_setup # Only run once, so remove before passing to fixtures in `super`.
       super

data/lib/oaken/type.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Oaken::Type < Struct.new(:name, :gsub)
+  def self.for(name) = new(name, name.classify.gsub(/(?<=[a-z])(?=[A-Z])/))
+
+  def locate
+    possible_consts.filter_map(&:safe_constantize).first
+  end
+
+  def possible_consts
+    separator_matrixes.fetch(gsub.count).map { |seps| gsub.with_index { seps[_2] } }
+  rescue KeyError
+    raise ArgumentError, "can't resolve #{name} to an object, please call register manually"
+  end
+
+  private
+    # TODO: Remove after dropping Ruby 3.1 support
+    if Enumerator.respond_to?(:product)
+      def self.product(...) = Enumerator.product(...)
+    else
+      def self.product(first = nil, *rest) = first&.product(*rest) || [[]]
+    end
+
+    separator_matrixes = (0..3).to_h { |size| [size, product(*[["::", ""]].*(size)).lazy] }
+    define_method(:separator_matrixes) { separator_matrixes }
+end

data/lib/oaken/version.rb

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

data/lib/oaken.rb

@@ -7,6 +7,7 @@ module Oaken
   class Error < StandardError; end
 
   autoload :Seeds,     "oaken/seeds"
+  autoload :Type,      "oaken/type"
   autoload :TestSetup, "oaken/test_setup"
 
   module Stored
@@ -16,9 +17,22 @@ module Oaken
   singleton_class.attr_reader :lookup_paths
   @lookup_paths = ["db/seeds"]
 
+  def self.glob(identifier)
+    patterns = lookup_paths.map { File.join _1, "#{identifier}{,/**/*}.rb" }
+
+    Pathname.glob(patterns).tap do |found|
+      raise NoSeedsFoundError, "found no seed files for #{identifier.inspect}" if found.none?
+    end
+  end
+  NoSeedsFoundError = Class.new ArgumentError
+
   class Loader
-    def initialize(path)
-      @entries = Pathname.glob("#{path}{,/**/*}.rb").sort
+    def self.from(identifiers)
+      new identifiers.flat_map { Oaken.glob _1 }
+    end
+
+    def initialize(entries)
+      @entries = entries
     end
 
     def load_onto(seeds) = @entries.each do |path|
@@ -26,9 +40,22 @@ module Oaken
         seeds.class_eval path.read, path.to_s
       end
     end
+
+    def self.definition_location
+      # Trickery abounds! Due to Ruby's `caller_locations` + our `load_onto`'s `class_eval` above
+      # we can use this format to detect the location in the seed file where the call came from.
+      caller_locations(2, 8).find { _1.label.match? /block .*?load_onto/ }
+    end
   end
 
-  def self.prepare(&block) = Seeds.instance_eval(&block)
+  def self.prepare(&block)
+    Seeds.instance_eval(&block)
+  end
+
+  def self.replant_seed
+    ActiveRecord::Tasks::DatabaseTasks.truncate_all
+    load_seed
+  end
   def self.load_seed = Rails.application.load_seed
 end
 

metadata

@@ -1,16 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oaken
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Kasper Timm Hansen
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description:
 email:
 - hey@kaspth.com
 executables: []
@@ -29,6 +27,7 @@ files:
 - lib/oaken/seeds.rb
 - lib/oaken/stored/active_record.rb
 - lib/oaken/test_setup.rb
+- lib/oaken/type.rb
 - lib/oaken/version.rb
 homepage: https://github.com/kaspth/oaken
 licenses:
@@ -38,7 +37,6 @@ metadata:
   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:
 rdoc_options: []
 require_paths:
 - lib
@@ -53,8 +51,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.18
-signing_key:
+rubygems_version: 3.6.8
 specification_version: 4
 summary: Oaken aims to blend your Fixtures/Factories and levels up your database seeds.
 test_files: []