oaken 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43bfd3d777a6a7060eacfda4d23ee10bdb19932547bd6c52e82757b77e897d0e
-  data.tar.gz: 2c81615943933ca2a22f375f2d7afedd07078ea1ca4c71f609970273da5fe0a5
+  metadata.gz: 1eea7421c7a71e2be111c2a82448345d9913830db2405c9903f1e57bf4371e79
+  data.tar.gz: 185532dbf42d282773eed6fef3a1ec139f81d9fdc37490c6a3b69b80e88bd862
 SHA512:
-  metadata.gz: 2e13841a16e33779150ba1ba45cf7c4407f1d2f7ead9fb29ca886b93afe2a78fc3394c39899b1f550878b2e0f915f6ceeb52e80582c0fb167e3784a68f453002
-  data.tar.gz: 751a8d8613e43d1af6c5f76ab73be8ee6acc1aa1a6d2b0a3c58250540555d5da1503860e7f3d582d4107da097b840add7e186fe6067344c3bfabd8bc36b5a836
+  metadata.gz: abe8c9e3be55d73978fc6cebec2668c2c2b372999bf65cb76f1e8232f742375ae0c6268ce76d9ba31ef3761f650a67d928b9338c4d0bb3d676f338b837b8d1e9
+  data.tar.gz: 5a91439c28f1abd37ae78c9eec667f56b84162dbdd1078370c10df4eab911c36fc0d448e7390d2242d420eb259d0a3bd0a1a012e7125efb2cec01b9fb303ba58

data/README.md

@@ -1,103 +1,312 @@
 # Oaken
 
-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.
+Oaken is fixtures + factories + seeds for your Rails development & test environments.
+
+## Oaken is like fixtures, without the nightmare UX
+
+Oaken takes inspiration from Rails' fixtures' approach of storytelling about your app's object graph, but replaces the nightmare YAML-based UX with Ruby-based data scripts. This makes data much easier to reason about & connect the dots.
+
+In Oaken, you start by creating a root-level model, typically an Account, Team, or Organization etc. to group everything on, in a scenario. From your root-level model, you then start building your object graph by mirroring how your app works.
+
+So what comes next in your account flow? Maybe it's creating Users on the account.
+
+You can go further if you need to. Is the Account about selling something, like donuts? Maybe you add a menu and some items.
+
+It'll look like this:
+
+```ruby
+account = accounts.create :kaspers_donuts, name: "Kasper's Donuts"
+
+kasper   = users.create :kasper,   name: "Kasper",   email_address: "kasper@example.com",   accounts: [account]
+coworker = users.create :coworker, name: "Coworker", email_address: "coworker@example.com", accounts: [account]
+
+menu = menus.create(account:)
+plain_donut     = menu_items.create menu:, name: "Plain",     price_cents: 10_00
+sprinkled_donut = menu_items.create menu:, name: "Sprinkled", price_cents: 10_10
+```
+
+> [!NOTE]
+> `create` takes an optional symbol label. This makes the record accessible in tests, e.g. `users.create :kasper` lets tests do `setup { @kasper = users.kasper }`.
+
+With fixtures, this would be 4 different files in `test/fixtures` for `accounts`, `users`, `menus`, and `menu_items`. It would be ~20 lines of YAML versus ~6 lines of Ruby for this data.
+
+Another issue in fixture files, is that objects from different scenarios are all mixed together making it hard to get a picture of what's going on — even in small apps.
+
+Fixtures also require you to label every record and make them unique throughout your dataset — you have to be careful not to create clashes. This gets difficult to manage quickly and requires diligence on a team that's trying to ship.
+
+However, often the fact that a record is associated onto another is enough. So in Oaken, we let you skip naming every record. Notice how the `menus.create` & `menu_items.create` calls don't pass symbol labels. You can still get at them in tests though if you really need to with `accounts.kaspers_donuts.menus.first.menu_items.first`.
+
+<details>
+  <summary>See the fixtures version</summary>
+
+```yaml
+# test/fixtures/accounts.yml
+kaspers_donuts:
+  name: Kasper's Donuts
+
+# test/fixtures/users.yml
+kasper:
+  name: "Kasper"
+  email_address: "kasper@example.com"
+  accounts: kaspers_donuts
+
+coworker:
+  name: "Coworker"
+  email_address: "coworker@example.com"
+  accounts: kaspers_donuts
+
+# test/fixtures/menus.yml
+basic:
+  account: kaspers_donuts
+
+# test/fixtures/menu/items.yml
+plain_donut:
+  menu: basic
+  name: Plain
+  price_cents: 10_00
+
+sprinkled_donut:
+  menu: basic
+  name: Sprinkled
+  price_cents: 10_10
+```
+
+</details>
+
+### Oaken is like fixtures, we seed data before tests run
+
+The reason you go through all the trouble of massaging your fixture files is to have a stable named dataset across test runs that's relatively quick to load — so the database call cost is amortized across tests.
+
+Oaken mirrors this approach giving you stability in your dataset and the relative quickness to insert the data.
+
+For instance, if you have 10 tests that each need the same 2 records, Oaken puts them in the database once before tests run, same as fixtures.
+
+The tradeoff is that if you run just 1 test we'll still seed those 2 same records, but we'll also seed any other record you've added to the shared dataset that might not be needed in those tests.
+
+We rely on Rails' tests being wrapped in transactions so any changes are rolled back after the test case run.
+
+> [!NOTE]
+> It can be a good idea to structure your object graph so you won't need database records for your tests — reality can sometimes be far from that ideal state though. Oaken aims to make your present reality easier and something you can improve.
+
+## Oaken is unlike factories, focusing on shared datasets
+
+Factories can let you start an app easier. It's just this one factory for now, ok, easy enough.
+
+Over time, however, many teams find their factory based test suite slows to a crawl. Suddenly one factory ends up pulling in the rest of the app.
+
+Factories end up requiring a lot of diligence and passing just the right things in just-so to make managable.
+
+Oaken does away with this. See the sections on the fixtures comparisons above for how.
+
+> [!WARNING]
+> Full Disclaimer: while I have worked on systems using factories, I overall don't get it and the fixtures approach makes more sense to me despite the UX issues. I'm trying to support a partial factories approach here in Oaken, see the below section for that, and I'm open to ideas here.
+
+> [!TIP]
+> Oaken is compatible with FactoryBot and Fabrication, and they should be able to work together. I consider it a bug if there's compatibility issues, so please open an issue here if you find something.
+
+### Oaken is like factories, with dynamic defaults & helper methods
+
+See the sections on defaults & helpers below.
+
+The aim for Oaken is to have most of the feature set of factories for a fraction of the implementation complexity.
+
+## Oaken gives db/seeds.rb superpowers
+
+Oaken upgrades seeds in `db/seeds.rb`, so you can put together scenarios & reuse the development data in tests.
+
+This way, the data you see in your browser, is the same data you work with in tests to make your object graph easier to get — especially for people new to your codebase.
+
+So you get a cohesive & stable dataset with a story like fixtures & their fast loading. But you also get the dynamics of FactoryBot/Fabrication as well without making tons of one-off records to handle each case.
+
+The end result is you end up writing less data back & forth to the database because you aren’t cobbling stuff together.
 
 > 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)
 
-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.
+## Design goals
 
-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?
+### Consistent data & constrained Ruby
 
-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.
+We're using `accounts.create` and such instead of `Account.create!` to help enforce consistency & constrain your Ruby usage. This also allows for extra features like `defaults` and helpers that take way less to implement.
 
-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.
+### Pick up in 1 hour or less
 
-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.
+We don't want to be a costly DSL that takes ages to learn and relearn when you come back to it.
+
+We're aiming for a time-to-understand of less than an hour. Same goes for the internals, if you dive in, it should ideally take less than 1 hour to comprehend most of it.
+
+### Similar ideas to Pkl
+
+We share similar [sentiments to the Pkl configuration language](https://pkl-lang.org/main/current/introduction/comparison.html). You may find the ideas helpful before using Oaken.
+
+Oddly enough Oaken came out before Pkl, I just read the ideas here and went "yes, exactly!"
 
 ## Setup
 
-### Starting in development
+### Loading directories/files
+
+By default, `Oaken.loader` returns an `Oaken::Loader` instance to handle loading seed files.
+
+You can load a seed directory via `Oaken.loader.seed`. You can also load a file, it'll technically just be a match that happens to only hit one file.
+
+So if you call `Oaken.loader.seed :accounts`, we'll look within `db/seeds/` and `db/seeds/#{Rails.env}/` and match `accounts{,**/*}.rb`. So these files would be found:
+
+- accounts.rb
+- accounts/kaspers_donuts.rb
+- accounts/kaspers_donuts/deeply/nested/path.rb
+- accounts/demo.rb
+- and so on.
+
+> [!TIP]
+> You can call `Oaken.loader.glob` with a single identifier to see what files we'll match. > Some samples: `Oaken.loader.glob :accounts`, `Oaken.loader.glob "cases/pagination"`.
+
+> [!TIP]
+> Putting a file in the top-level `db/seeds` versus `db/seeds/development` or `db/seeds/test` means it's shared in both environments. See below for more tips.
+
+Any directories and/or single-file matches are loaded in the order they're specified. So `loader.seed :setup, :accounts` would first load setup and then accounts.
+
+> [!IMPORTANT]
+> Understanding and making effective use of Oaken's directory loading will pay dividends for your usage. You generally want to have 1 top-level directive `seed` call to dictate how seeding happens in e.g. `db/seeds.rb` and then let individual seed files load in no specified order within that.
+
+#### Using the `setup` phase
+
+When you call `Oaken.loader.seed` we'll also call `seed :setup` behind the scenes, though we'll only call this once. It's meant for common setup, like `defaults` and helpers.
+
+> [!IMPORTANT]
+> We recommend you don't use `create`/`upsert` directly in setup. Add the `defaults` and/or helpers that would be useful in the later seed files.
+
+Here's some files you could add:
+
+- db/seeds/setup.rb — particularly useful as a starting point.
+- db/seeds/setup/defaults.rb — loader and type-specific defaults.
+- db/seeds/setup/defaults/*.rb — you could split out more specific files.
+- db/seeds/setup/users.rb — a type specific file for its defaults/helpers, doesn't have to just be users.
+
+- db/seeds/development/setup.rb — some defaults/helpers we only want in development.
+- db/seeds/test/setup.rb — some defaults/helpers we only want in test.
+
+> [!TIP]
+> Remember, since we're using `seed` internally you can nest as deeply as you want to structure however works best. There's tons of flexibility in the `**/*` glob pattern `seed` uses.
+
+#### Directory recommendations & file tips
+
+Oaken has some directory recommendations to help strengthen your understanding of your object graph:
+
+- `db/seeds/data` for any data tables, like the plans a SaaS app has.
+- Group scenarios around your top-level root model, like `Account`, `Team`, or `Organization` and have a `db/seeds/accounts` directory.
+- `db/seeds/cases` for any specific cases, like pagination.
 
-You can set it up in `db/seeds.rb`, like this:
+If you follow all these conventions you could do this:
 
 ```ruby
-Oaken.prepare do
-  seed :accounts, :data
-end
+Oaken.loader.seed :data, :accounts, :cases
 ```
 
-This will look for deeply nested files to load in `db/seeds` and `db/seeds/#{Rails.env}` within the `accounts` and `data` directories.
+And here's some potential file suggestions you could take advantage of:
 
-Here's what they could look like:
+- db/seeds/data/plans.rb — put your SaaS plans in here.
+- db/seeds/test/data/plans.rb — some test specific plans, in case we need them.
 
-```ruby
-# db/seeds/accounts/kaspers_donuts.rb
-donuts = accounts.create :kaspers_donuts, name: "Kasper's Donuts"
+- db/seeds/cases/pagination.rb — group the seed code for generating pagination data here. NOTE: this could reference an account setup earlier.
+- db/seeds/test/cases/*.rb — any test specific cases.
+
+> [!TIP]
+> We're letting Oaken's loading do all the hard work here, we're just staging the loading phases by specifying the top-level order.
+
+##### Loading specific cases in tests only
+
+For the cases part, you may want to tweak it a bit more.
 
-kasper   = users.create :kasper,   name: "Kasper",   accounts: [donuts]
-coworker = users.create :coworker, name: "Coworker", accounts: [donuts]
+You could add any definitely shared cases in `db/seeds/cases`. Say you have a `db/seeds/cases/pagination.rb` case that can be shared between development and test.
 
-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
+If not, you can add environment specific ones in `db/seeds/development/cases/pagination.rb` and `db/seeds/test/cases/pagination.rb`.
 
-supporter = users.create name: "Super Supporter"
-orders.insert_all [user_id: supporter.id, item_id: plain_donut.id] * 10
+You could also avoid loading all the cases in the test environment like this:
 
-orders.insert_all \
-  10.times.map { { user_id: users.create(name: "Customer #{_1}").id, item_id: menu.items.sample.id } }
+```ruby
+Oaken.loader.seed :cases if Rails.env.development?
 ```
 
+Now you can load specific seeds in tests, like this:
+
 ```ruby
-# db/seeds/data/plans.rb
-plans.upsert :basic, title: "Basic", price_cents: 10_00
+class PaginationTest < ActionDispatch::IntegrationTest
+  setup { seed "cases/pagination" }
+end
 ```
 
-Seed files will generally use `create` and/or `insert`. Passing a symbol to name the record is useful when reusing the data in tests.
+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:
+>
+> - 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
+
+#### Configuring loaders
 
-Now you can run `bin/rails db:seed` and `bin/rails db:seed:replant`.
+You can customize the loading and loader as well:
 
-### Interlude: Directory Naming Conventions
+```ruby
+# config/initializers/oaken.rb
+# Call `with` to build a new loader. Here we're just passing the default internal options:
+loader = Oaken.loader.with(lookup_paths: "test/seeds") # Useful to pull from another directory, when migrating.
+loader = Oaken.loader.with(locator: Oaken::Loader::Type, provider: Oaken::Stored::ActiveRecord, context: Oaken::Seeds)
 
-Oaken has some chosen directory conventions to help strengthen your understanding of your object graph:
+Oaken.loader = loader # You can also replace Oaken's default loader.
+```
 
-- 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/test/cases` for any specific cases that are only used in some tests, like `pagination.rb`.
+> [!TIP]
+> `Oaken` delegates `Oaken::Loader`'s public instance methods to `loader`,
+> so `Oaken.seed` works and is really `Oaken.loader.seed`. Same goes for `Oaken.lookup_paths`, `Oaken.with`, `Oaken.glob` and more.
 
-### Using default attributes
+#### In db/seeds.rb
 
-You can set up default attributes that's applied to created/inserted records at different levels, like this:
+Call `loader.seed` and it'll follow the rules mentioned above:
 
 ```ruby
-Oaken.prepare do
-  # Assign broad global defaults for every type.
-  defaults name: -> { Faker::Name.name }, public_key: -> { SecureRandom.hex }
+# db/seeds.rb
+Oaken.loader.seed :setup, :accounts, :data
+Oaken.seed :setup, :accounts, :data # Or just this for short.
+```
 
-  # Assign a more specific default on one type, which overrides the global default above.
-  accounts.defaults name: -> { Faker::Business.name }
-end
+Both `bin/rails db:seed` and `bin/rails db:seed:replant` work as usual.
+
+#### In the console
+
+If you're in the `bin/rails console`, you can invoke the same `seed` method as in `db/seeds.rb`.
+
+```ruby
+Oaken.seed :setup, "cases/pagination"
 ```
 
+This is useful if you're working on hammering out a single seed script.
+
 > [!TIP]
-> `defaults` are particularly well suited for assigning generated data with [Faker](https://github.com/faker-ruby/faker).
+> Oaken wraps each file load in an `ActiveRecord::Base.transaction` so any invalid data rolls back the whole file.
 
-### Reusing data in tests
+#### In tests & specs
 
-With the setup above, Oaken can reuse the same data in tests like this:
+If you're using Rails' default minitest-based tests call this:
 
 ```ruby
 # test/test_helper.rb
 class ActiveSupport::TestCase
-  include Oaken::TestSetup
+  include Oaken.loader.test_setup
 end
 ```
 
-Now tests have access to `accounts.kaspers_donuts` and `users.kasper` etc. that were setup in the data scripts.
+We've got full support for Rails' test parallelization out of the box.
 
 > [!NOTE]
 > For RSpec, you can put this in `spec/rails_helper.rb`:
@@ -105,39 +314,138 @@ Now tests have access to `accounts.kaspers_donuts` and `users.kasper` etc. that
 > require "oaken/rspec_setup"
 > ```
 
-You can also load a specific seed, like this:
+### Writing Seed Data Scripts
+
+Oaken's data scripts are composed of table name looking methods corresponding to Active Record classes, which you can enhance with `defaults` and helper methods, then eventually calling `create` or `upsert` on them.
+
+#### Automatic & manual registry
+
+> [!IMPORTANT]
+> Ok, this bit is probably the most complex in Oaken. You can see the implementation in `Oaken::Seeds#method_missing` and then `Oaken::Loader::Type`.
+
+When you reference e.g. `accounts` we'll hit `Oaken::Seeds#method_missing` hook and:
+
+- locate a class using `loader.locate`, hitting `Oaken::Loader::Type.locate`.
+- If there's a match, call `loader.register Account, as: :accounts`.
+
+We'll respect namespaces up to 3 levels deep, so we'll try to match:
+
+- `menu_items` to `Menu::Item` or `MenuItem`.
+- `menu_item_details` to `Menu::Item::Detail`, `MenuItem::Detail`, `Menu::ItemDetail`, `MenuItemDetail`.
+- The third level which is going to be 2 separators ("::" or "") to the power of 3 levels, in other words 8 possible constants.
+
+You can skip this by calling `loader.register Menu::Item`, which we'll derive the method name via `name.tableize.tr("/", "_")` or you can call `register Menu::Item, as: :something_else` to have it however you want.
+
+#### `create`
+
+Internally, `create` calls `ActiveRecord::Base#create!` to fail early & prevent invalid records in your dataset. Runs create/save model callbacks.
 
 ```ruby
-class PaginationTest < ActionDispatch::IntegrationTest
-  setup { seed "cases/pagination" }
-end
+users.create name: "Someone"
 ```
 
-And in RSpec:
+Some records have uniqueness constraints, like a User's `email_address`, you can pass that via `unique_by`:
 
 ```ruby
-RSpec.describe "Pagination", type: :feature do
-  before { seed "cases/pagination" }
+users.create unique_by: :email_address, name: "First",  email_address: "someone@example.com"
+users.create unique_by: :email_address, name: "Second", email_address: "someone@example.com"
+```
+
+In the case of a uniqueness constraint clash, we'll `update!` the record, so here `name` is `"Second"`. Runs save/update model callbacks.
+
+> [!IMPORTANT]
+> We're trying to make `db:seed` rerunnable incrementally without needing to start from scratch. That's what the `update!` part is for. I'm still not entirely sure about it and I'm trying to figure out a better way to highlight what's going on to users.
+
+#### `upsert`
+
+Mirrors `ActiveRecord::Base#upsert`, allowing you to pass a `unique_by:` which must correspond to a unique database index. Does not run model callbacks.
+
+We'll instantiate and `validate!` the record to help prevent bad data hitting the database.
+
+Typically used for data tables, like so:
+
+```ruby
+# db/seeds/data/plans.rb
+plans.upsert :basic, unique_by: :title, title: "Basic", price_cents: 10_00
+```
+
+#### Using `defaults`
+
+You can set `defaults` that're applied on `create`/`upsert`, like this:
+
+```ruby
+# Assign loader-level defaults that's applied to every type.
+# Records only include defaults on attributes they have. So only records with a `public_key` attribute receive that and so on.
+loader.defaults name: -> { Faker::Name.name }, public_key: -> { SecureRandom.hex }
+
+# Assign specific defaults on one type, which overrides the loader `name` default from above.
+accounts.defaults name: -> { Faker::Business.name }, status: :active
+
+accounts.create # `name` comes from the `accounts.defaults` and `public_key` from `loader.defaults`.
+accounts.upsert # Same.
+
+users.create # `name` comes from `loader.defaults`.
+```
+
+> [!TIP]
+> It's best to be explicit in your dataset to tie things together with actual names, to make your object graph more cohesive. However, sometimes attributes can be filled in with [Faker](https://github.com/faker-ruby/faker) if they're not part of the "story".
+
+#### Defining helpers
+
+Oaken uses Ruby's [`singleton_methods`](https://rubyapi.org/3.4/o/object#method-i-singleton_methods) for helpers because it costs us 0 lines of code to write and maintain.
+
+In plain Ruby, they look like this:
+
+```ruby
+obj = Object.new
+def obj.hello = :yo
+obj.hello # => :yo
+obj.singleton_methods # => [:hello]
+```
+
+So you can do stuff like this on, say, a `users` instance:
+
+```ruby
+# Notice how we're using the `labeled_email` helper to compose `create_labeled` too:
+def users.create_labeled(label, email_address: labeled_email(label), **) = create(label, email_address:, **)
+def users.labeled_email(label) = "#{label}@example.com" # You don't have to use endless methods, they're fun though.
+```
+
+Now `create_labeled` & `labeled_email` are available everywhere the `users` instance is, in development and test!
+
+```ruby
+test "we definitely need this" do
+  assert_equal "person@example.com", users.labeled_email(:person)
 end
 ```
 
+Here's how you can provide a default `unique_by:` on all `users`:
+
+```ruby
+# We override the built-in `create` to provide the default. Yes, `super` works on overriden methods!
+def users.create(label = nil, unique_by: :email_address, **) = super
+```
+
+You could use this to provide `FactoryBot`-like helpers. Maybe adding a `factory` method?
+
 > [!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
+> It's still early days for these kind of helpers, so I'm still finding out what's possible with them. I'd love to know how you're using them on the Discussions tab.
+
+## Migration
 
-### Fixtures Converter
+### From fixtures
+
+#### Converter
 
 You can convert your Rails fixtures to Oaken's seeds by running:
 
-    $ bin/rails generate oaken:convert:fixtures
+```
+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`.
+This will convert anything in test/fixtures to db/seeds. E.g. `test/fixtures/users.yml` becomes `db/seeds/users.rb` and so on.
 
-### Disable fixtures
+#### 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:
@@ -156,6 +464,44 @@ The `test_framework` repeating is to preserve `:test_unit` or `:rspec` respectiv
 > [!NOTE]
 > If you're using `FactoryBot` as well, you don't need to do this since it already replaces fixtures for you.
 
+### From factories
+
+If you've got a mostly working FactoryBot or Fabrication setup you may not want to muck with that too much.
+
+However, you can grab some of the most shared records and shave off some significant runtime on your test suite.
+
+<blockquote class="bluesky-embed" data-bluesky-uri="at://did:plc:ps3ygxhsn4khcrxeutdosdqk/app.bsky.feed.post/3lfb5zdb3p22z" data-bluesky-cid="bafyreiadxun7yqw4efafqzwzv3h4t4mbrex7onlnxobfejhbt6t44fojni" data-bluesky-embed-color-mode="system"><p lang="en">It&#x27;s @erikaxel.bsky.social&#x27;s team! They shaved 5.5 minutes off their test suite.
+
+And that&#x27;s just the first batch integrating Oaken!<br><br><a href="https://bsky.app/profile/did:plc:ps3ygxhsn4khcrxeutdosdqk/post/3lfb5zdb3p22z?ref_src=embed">[image or embed]</a></p>&mdash; Kasper Timm Hansen (<a href="https://bsky.app/profile/did:plc:ps3ygxhsn4khcrxeutdosdqk?ref_src=embed">@kaspth.bsky.social</a>) <a href="https://bsky.app/profile/did:plc:ps3ygxhsn4khcrxeutdosdqk/post/3lfb5zdb3p22z?ref_src=embed">January 8, 2025 at 11:00 PM</a></blockquote>
+
+Set Oaken up for your tests like the setup section mentions, and then only add a setup directory and scenarios around the root-level model like an Account. Like this:
+
+```ruby
+# db/seeds.rb
+if Rails.env.test?
+  Oaken.loader.seed :setup, :accounts
+  return
+end
+```
+
+Then define some very basic account setup like the very top of the README mentions.
+
+Or maybe like this:
+
+```ruby
+# db/seeds/test/accounts/basic.rb
+accounts.create :basic, **FactoryBot.attributes_for(:account)
+
+# Maybe some extra necessary records on the account here.
+```
+
+Now tests can pass `account: accounts.basic` to other factories.
+
+Do the very minimum and go slow. Pick records that you know are 100% safe to share.
+
+> [!NOTE]
+> I'd love to improve these migration notes. Please file an issue if something is confusing. I'd also love to hear your experience in general.
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/lib/oaken/{type.rb → loader/type.rb}

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-class Oaken::Type < Struct.new(:name, :gsub)
+class Oaken::Loader::Type < Struct.new(:name, :gsub)
+  def self.locate(name) = self.for(name.to_s).locate
   def self.for(name) = new(name, name.classify.gsub(/(?<=[a-z])(?=[A-Z])/))
 
   def locate

data/lib/oaken/loader.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+class Oaken::Loader
+  class NoSeedsFoundError < ArgumentError; end
+
+  autoload :Type, "oaken/loader/type"
+
+  attr_reader :lookup_paths, :locator, :provider, :context
+  delegate :locate, to: :locator
+
+  def initialize(lookup_paths: nil, locator: Type, provider: Oaken::Stored::ActiveRecord, context: Oaken::Seeds)
+    @setup = nil
+    @lookup_paths, @locator, @provider, @context = Array(lookup_paths).dup, locator, provider, context
+    @defaults = {}.with_indifferent_access
+  end
+
+  # Instantiate a new loader with all its attributes and any specified `overrides`. See #new for defaults.
+  #
+  #   Oaken.loader.with(root: "test/fixtures") # `root` returns "test/fixtures" here
+  def with(**overrides)
+    self.class.new(lookup_paths:, locator:, provider:, context:, **overrides)
+  end
+
+  # Allow assigning defaults across types.
+  def defaults(**defaults) = @defaults.merge!(**defaults)
+  def defaults_for(*keys)  = @defaults.slice(*keys)
+
+  def test_setup
+    Oaken::TestSetup.new self
+  end
+
+  # Register a model class via `Oaken.loader.context`.
+  # Note: Oaken's auto-register means you don't need to call `register` often yourself.
+  #
+  #   register Account
+  #   register Account::Job
+  #   register Account::Job::Task
+  #
+  # Oaken uses `name.tableize.tr("/", "_")` for the method names, so they're
+  # `accounts`, `account_jobs`, and `account_job_tasks`, respectively.
+  #
+  # You can also pass an explicit `as:` option:
+  #
+  #   register User, as: :something_else
+  def register(type, as: nil)
+    stored = provider.new(self, type)
+    context.define_method(as || type.name.tableize.tr("/", "_")) { stored }
+  end
+
+  # Mirrors `bin/rails db:seed:replant`.
+  def replant_seed
+    ActiveRecord::Tasks::DatabaseTasks.truncate_all
+    load_seed
+  end
+
+  # Mirrors `bin/rails db:seed`.
+  def load_seed
+    Rails.application.load_seed
+  end
+
+  # 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.seed :accounts # Seeds from `db/seeds/accounts{,/**/*}.rb` and `db/seeds/<Rails.env>/accounts{,/**/*}.rb`
+  #
+  # 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(*identifiers)
+    setup
+
+    identifiers.flat_map { glob! _1 }.each { load_one _1 }
+    self
+  end
+
+  def glob(identifier)
+    Pathname.glob lookup_paths.map { File.join _1, "#{identifier}{,/**/*}.rb" }
+  end
+
+  def definition_location
+    # The first line referencing LABEL happens to be the line in the seed file.
+    caller_locations(3, 6).find { _1.base_label == LABEL }
+  end
+
+  private
+    def setup = @setup ||= glob(:setup).each { load_one _1 }
+
+    def glob!(identifier)
+      glob(identifier).then.find(&:any?) or raise NoSeedsFoundError, "found no seed files for #{identifier.inspect}"
+    end
+
+    def load_one(path)
+      context.class_eval path.read, path.to_s
+    end
+    LABEL = instance_method(:load_one).name.to_s
+end

data/lib/oaken/rspec_setup.rb

@@ -1,8 +1,5 @@
 RSpec.configure do |config|
-  config.include Oaken::Seeds
+  config.include Oaken.loader.context
   config.use_transactional_fixtures = true
-
-  config.before :suite do
-    Oaken.replant_seed
-  end
+  config.before(:suite) { Oaken.loader.replant_seed }
 end

data/lib/oaken/seeds.rb

@@ -1,15 +1,14 @@
 module Oaken::Seeds
-  extend self
+  def self.loader = Oaken.loader
+  singleton_class.delegate :seed, :register, to: :loader
+  delegate :seed, to: self
 
-  # 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
+  extend self
 
-  # Oaken's main auto-registering logic.
+  # Oaken's auto-registering logic.
   #
   # So when you first call e.g. `accounts.create`, we'll hit `method_missing` here
-  # and automatically call `register Account`.
+  # and automatically call `register Account, as: :accounts`.
   #
   # We'll also match partial and full nested namespaces:
   #
@@ -19,84 +18,34 @@ module Oaken::Seeds
   #
   # If you have classes that don't follow these naming conventions, you must call `register` manually.
   def self.method_missing(meth, ...)
-    if type = Oaken::Type.for(meth.to_s).locate
+    if type = loader.locate(meth)
       register type, as: meth
       public_send(meth, ...)
     else
       super
     end
   end
-  def self.respond_to_missing?(meth, ...) = Oaken::Type.for(meth.to_s).locate || super
+  def self.respond_to_missing?(meth, ...) = loader.locate(meth) || 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.
+  # Purely for decorative purposes to carve up seed files.
   #
-  #   register Account, Account::Job, Account::Job::Task
+  # `section` is defined as `def section(*, **) = block_given? && yield`, so you can use
+  # all of Ruby's method signature flexibility to help communicate structure better.
   #
-  # Oaken uses `name.tableize.tr("/", "_")` on the passed classes for the method names, so they're
-  # `accounts`, `account_jobs`, and `account_job_tasks`, respectively.
+  # Use positional & keyword arguments, blocks at multiple levels, or a combination.
   #
-  # You can also pass an explicit `as:` option, if you'd like:
+  #   section :basic
+  #   users.create name: "Someone"
   #
-  #   register User, as: :something_else
-  def self.register(*types, as: nil)
-    types.each do |type|
-      stored = provider.new(type) and define_method(as || type.name.tableize.tr("/", "_")) { 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(*identifiers)
-      Oaken::Loader.from(identifiers).load_onto self
-    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:
+  #   section :menus, quicksale: true
+  #
+  #   section do
+  #     # Leave name implicit and carve up visually with the indentation.
+  #     section something: :nested
   #
-  #   class PaginationTest < ActionDispatch::IntegrationTest
-  #     setup do
-  #       seed "cases/pagination" # Loads `db/seeds/{,test}/cases/pagination{,**/*}.rb`
+  #     section :another_level do
+  #       # We can keep going, but maybe we shouldn't.
   #     end
   #   end
-  delegate :seed, to: Oaken::Seeds
+  def self.section(*, **) = block_given? && yield
 end

data/lib/oaken/stored/active_record.rb

@@ -1,12 +1,13 @@
 class Oaken::Stored::ActiveRecord
-  def initialize(type)
-    @type = type
-    @attributes = Oaken::Seeds.defaults_for(*type.column_names)
+  def initialize(loader, type)
+    @loader, @type = loader, type
+    @attributes = loader.defaults_for(*type.column_names)
   end
   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
 
+  # Create a record in the database with the passed `attributes`.
   def create(label = nil, unique_by: nil, **attributes)
     attributes = attributes_for(**attributes)
 
@@ -14,47 +15,39 @@ class Oaken::Stored::ActiveRecord
     record   = type.find_by(finders)&.tap { _1.update!(**attributes) } if finders.any?
     record ||= type.create!(**attributes)
 
-    label label => record if label
+    _label label, record.id if label
     record
   end
 
+  # Upsert a record in the database with the passed `attributes`.
   def upsert(label = nil, unique_by: nil, **attributes)
     attributes = attributes_for(**attributes)
 
     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
+    _label label, record.id if label
     record
   end
 
-  # Build attributes used for `create`/`upsert`, applying any global and per-type `defaults`.
+  # Build attributes used for `create`/`upsert`, applying loader 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
+  #   loader.defaults name: -> { "Global" }, email_address: -> { … }
+  #   users.defaults name: -> { Faker::Name.name } # This `name` takes precedence on users.
   #
   #   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:
+  # Set defaults for all types:
   #
-  #   # db/seeds.rb
-  #   Oaken.prepare do
-  #     defaults name: -> { "Global" }, email_address: -> { … }
-  #     users.defaults name: -> { Faker::Name.name } # This `name` takes precedence on users.
-  #   end
+  #   loader.defaults name: -> { "Global" }, email_address: -> { … }
   #
-  # These defaults are used and evaluated in `create`/`upsert`/`attributes_for`.
+  # These defaults are used and evaluated in `create`/`upsert`/`attributes_for`, but you can override on a per-type basis:
   #
-  #   users.create # => Uses the users' default `name` and the global `email_address`
-  def defaults(**attributes)
-    @attributes = @attributes.merge(attributes)
-    @attributes
-  end
+  #   users.defaults name: -> { Faker::Name.name } # This `name` takes precedence on `users`.
+  #   users.create # => Uses the users' default `name` and the loader `email_address`
+  def defaults(**attributes) = @attributes = @attributes.merge(attributes)
 
   # Expose a record instance that's setup outside of using `create`/`upsert`. Like this:
   #
@@ -65,18 +58,15 @@ class Oaken::Stored::ActiveRecord
   #
   # Ruby's Hash argument forwarding also works:
   #
-  #   someone = users.create(name: "Someone")
-  #   someone_else = users.create(name: "Someone Else")
+  #   someone, someone_else = users.create(name: "Someone"), 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)
-    labels.each { |label, record| _label label, record.id }
-  end
+  def label(**labels) = labels.each { |label, record| _label label, record.id }
 
   private def _label(name, id)
-    raise ArgumentError, "you can only define labelled records outside of tests" \
-      unless location = Oaken::Loader.definition_location
+    location = @loader.definition_location or
+      raise ArgumentError, "you can only define labelled records outside of tests"
 
     class_eval "def #{name} = find(#{id.inspect})", location.path, location.lineno
   end

data/lib/oaken/test_setup.rb

@@ -1,22 +1,23 @@
-module Oaken::TestSetup
-  include Oaken::Seeds
+class Oaken::TestSetup < Module
+  def initialize(loader)
+    @loader = loader
 
-  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
+    instance = self
+    define_method :before_setup do
       # `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?) }
+      loader.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
+      instance.remove_method :before_setup # Only run once, so remove before passing to fixtures in `super`.
+      super()
     end
   end
+
+  def included(klass)
+    klass.fixtures # Rely on fixtures to setup a shared connection pool and wrap tests in transactions.
+    klass.include @loader.context
+    klass.parallelize_setup { @loader.load_seed } # No need to truncate as parallel test databases are always empty.
+  end
 end

data/lib/oaken/version.rb

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

data/lib/oaken.rb

@@ -6,57 +6,17 @@ require "pathname"
 module Oaken
   class Error < StandardError; end
 
+  autoload :Loader,    "oaken/loader"
   autoload :Seeds,     "oaken/seeds"
-  autoload :Type,      "oaken/type"
   autoload :TestSetup, "oaken/test_setup"
 
   module Stored
     autoload :ActiveRecord, "oaken/stored/active_record"
   end
 
-  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 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|
-      ActiveRecord::Base.transaction do
-        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)
-  end
-
-  def self.replant_seed
-    ActiveRecord::Tasks::DatabaseTasks.truncate_all
-    load_seed
-  end
-  def self.load_seed = Rails.application.load_seed
+  singleton_class.attr_accessor :loader
+  singleton_class.delegate *Loader.public_instance_methods(false), to: :loader
+  @loader = Loader.new lookup_paths: "db/seeds"
 end
 
 require_relative "oaken/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: oaken
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Kasper Timm Hansen
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-05-13 00:00:00.000000000 Z
 dependencies: []
+description:
 email:
 - hey@kaspth.com
 executables: []
@@ -22,12 +24,13 @@ files:
 - Rakefile
 - lib/generators/oaken/convert/fixtures_generator.rb
 - lib/oaken.rb
+- lib/oaken/loader.rb
+- lib/oaken/loader/type.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/type.rb
 - lib/oaken/version.rb
 homepage: https://github.com/kaspth/oaken
 licenses:
@@ -37,6 +40,7 @@ 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
@@ -51,7 +55,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Oaken aims to blend your Fixtures/Factories and levels up your database seeds.
 test_files: []