oaken 0.9.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26963660acac39f907c83e52191ce7e99e005e140df3bacf6ff70d7e02d17f49
-  data.tar.gz: 95227e2756e40db548630ac8e667192a8bb3d00230f1d8218dd595a68c6f2907
+  metadata.gz: db5000f2e4a4967a798e13a086a117bc52c4f0d17c8db2fc62050bf268754b8a
+  data.tar.gz: e81fc5bf8328905ebf5bdc73a37ca25b8e76c1902aacb40eaefa8df5141fc576
 SHA512:
-  metadata.gz: b61959db0e0a87609dbfb209c846a7696f051bd214cc125678499936c4879399eef9a37acdb0d65eeb1296b34d7c13142dd04bbc6ad23cb2137bcbefdf82a74f
-  data.tar.gz: 968f223df5ad49644a47c3fe3eeca04a62d51aeb0d9060ec3c04245428857ef6adc72fee5784c47570778ae95684b6347d80cdbc15d7877971240ece1d1281f0
+  metadata.gz: b970b6299f3d3555b074d78208e695f2abf971665b7a7e8aeca298f938dfc7be7262b0bb3f4d4ed2baf691570fef21e1efe1c7f7c89417c6346a4c25b5c31eda
+  data.tar.gz: f3fcd7ce30daf87d6c0add0636aff6a196e6624746fc4bce8fd420cf9bbbcbf0ca386cb00c54b6a99f05dcee44ff69e6fa3fd58bdb9731d0fa6d41193acb6496

data/README.md

@@ -2,6 +2,48 @@
 
 Oaken is fixtures + factories + seeds for your Rails development & test environments.
 
+You may want to head straight to the [examples](examples) directory.
+
+## Benefits
+
+- In development:
+  - Add conventions for `db/seeds.rb` that feel like Rails.
+  - Grouping by scenario: choose how to best group your data.
+  - Reveal your Domain Model: describe your object graph sequentially, helping developers see how your app works.
+  - Ruby-based recipe-like data scripts: setup accounts first, then attach users, then hang other models off of those.
+  - Raise modelling problems early: Oaken can help expose when something feels awkward or off to give you design clues.
+
+- In tests, reuse development seed data:
+  - Tests mirror what developers have already seen in their dev browser.
+  - Easier developer onboarding by building a proper mental model faster.
+  - Less code that's easier to maintain with more visibility into your object graph.
+
+### Benefits over factories
+
+- Fast tests! Seed shared records once and reuse them across tests, transactions rollback changes.
+  - One team saw a 3x speed increase over factories.
+  - Another shaved off 5min on their CI time with less than a days work, and they only scratched the surface.
+
+- Visibility into your system: factories optimize for isolation, which make it easy to get started, but becomes more complex over time.
+- Save 20 lines of setup per test case.
+  - Your mileage will vary, but this happened for a team that replaced factories with Oaken.
+  - You do DRY up your tests more for non-trivial systems because you write the Oaken seed for common cases once, rather than per-test/file.
+  
+- You can name things: don't lose hours debugging factory-based tests because everything's anonymous, like I have.
+- Less mental load: factories' structure requires you to put things together in your head. How many models and associations does one factory create?
+- DRY setup:
+
+Also worth noting that you 
+
+### Benefits over fixtures
+
+- Still fast tests! Oaken inserts data before tests run & wraps tests in transactions, just like fixtures.
+- No more YAML: use Ruby to lay out your object graph sequentially with better organization. You can even sketch it out in a `console`
+- Break out edge cases or complex scenarios: split data for edge cases or tricky test setups into their own cases, so you don't end up with a 500-line fixture file peppered with warts.
+- Way easier to reason about your object graph: no more chasing 10 files for 10 associations.
+- Less mental load: fixtures' structure requires you to put things together in your head.
+- Way condensed data setup: Oaken can dramatically cut down on some fixture files by letting you use helpers
+
 ## 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.
@@ -176,27 +218,27 @@ So if you call `Oaken.loader.seed :accounts`, we'll look within `db/seeds/` and
 > [!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.
+Any directories and/or single-file matches are loaded in the order they're specified. So `loader.seed :data, :accounts` would first load data 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.
+When you call `Oaken.seed`/`Oaken.loader.seed` we'll also call `seed :setup` for you behind the scenes, though we'll only call this once. It's meant for common setup, like setting `defaults` and defining 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.
+> 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/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.
+- `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.
@@ -287,8 +329,8 @@ Call `loader.seed` and it'll follow the rules mentioned above:
 
 ```ruby
 # db/seeds.rb
-Oaken.loader.seed :setup, :accounts, :data
-Oaken.seed :setup, :accounts, :data # Or just this for short.
+Oaken.loader.seed :data, :accounts
+Oaken.seed :data, :accounts # Or just this for short.
 ```
 
 Both `bin/rails db:seed` and `bin/rails db:seed:replant` work as usual.
@@ -298,7 +340,7 @@ Both `bin/rails db:seed` and `bin/rails db:seed:replant` work as usual.
 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"
+Oaken.seed "cases/pagination"
 ```
 
 This is useful if you're working on hammering out a single seed script.
@@ -329,15 +371,20 @@ We've got full support for Rails' test parallelization out of the box.
 
 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.
 
+#### Loading within the `context` module
+
+Oaken loads every seed file within the context of its `context` module. You can see it with `Oaken.loader.context`, or `Oaken.context` for short.
+
 #### 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`.
+> Ok, this bit is probably the most complex part 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`.
+- `loader.register` defines the `accounts` method on the `Oaken.loader.context` module, pointing to an instance of `Oaken::Stored::ActiveRecord`.
 
 We'll respect namespaces up to 3 levels deep, so we'll try to match:
 
@@ -380,6 +427,22 @@ Typically used for data tables, like so:
 plans.upsert :basic, unique_by: :title, title: "Basic", price_cents: 10_00
 ```
 
+#### `new`/`build`
+
+We've also got `new`/`build` in case you:
+
+- have a record that needs slightly more complex setup so you can't do `create`/`upsert`.
+- want a record that's not in the database during testing.
+
+Will have defaults applied via `attributes_for` internally.
+
+```ruby
+test "some test" do
+  user = users.new name: "Someone"
+  user = users.build name: "Someone"
+end
+```
+
 #### Using `defaults`
 
 You can set `defaults` that're applied on `create`/`upsert`, like this:
@@ -401,10 +464,42 @@ 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".
 
+#### Using `proxy`
+
+`proxy` lets you wrap and delegate scopes from the underlying record.
+
+So if you have this Active Record:
+
+```ruby
+class User < ApplicationRecord
+  enum :role, %w[admin mod plain].index_by(&:itself)
+
+  scope :cool, -> { where(cool: true) }
+end
+```
+
+You can then proxy the scopes and use them like this:
+
+```ruby
+users.proxy :admin, :mod, :plain
+users.proxy :cool
+
+users.create       # Has `role: "plain"`, assuming it's the default role.
+users.admin.create # Has `role: "admin"`
+users.mod.create   # Has `role: "mod"`
+users.cool.create  # Has `cool: true`
+
+# Chaining also works:
+users.cool.admin.create # Has `cool: true, role: "admin"`
+```
+
 #### 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.
 
+> [!NOTE]
+> 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.
+
 In plain Ruby, they look like this:
 
 ```ruby
@@ -430,6 +525,8 @@ test "we definitely need this" do
 end
 ```
 
+##### Providing `unique_by` everywhere
+
 Here's how you can provide a default `unique_by:` on all `users`:
 
 ```ruby
@@ -439,8 +536,66 @@ 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]
-> 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.
+##### Accessing other seeds via `context`
+
+You can access other seeds from within a helper by going through `Oaken.loader.context`/`Oaken.context`. We've got a shorthand so you can just write `context`, like this:
+
+```ruby
+# Set up a helper to ensure when we create an account we also have a default admin user.
+def accounts.bootstrap(name:, **)
+  create(name:, **).tap do
+    context.users.admin.create account: _1, name: "Primary Admin"
+  end
+end
+```
+
+#### Using `with` to group setup
+
+`with` allows you to group similar `create`/`upsert` calls & apply scoped defaults.
+
+##### `with` during setup
+
+During seeding setup, use `with` in the block form to group `create`/`upsert` calls, typically by an association you want to highlight.
+
+In this example, we're grouping menu items by their menu. We could write out each menu item `create` one by one and pass the menus explicitly just fine.
+
+However, grouping by the menu gets us an extra level of indentation to help reveal our intent.
+
+```ruby
+menu_items.with menu: menus.basic do
+  it.create :plain_donut, name: "Plain Donut"
+  it.create name: "Another Basic Donut"
+  # More `create` calls, which automatically go on the basic menu.
+end
+
+menu_items.with menu: menus.premium do
+  it.create :premium_donut, name: "Premium Donut"
+  # Other premium menu items.
+end
+```
+
+##### `with` in tests
+
+In tests `with` is also useful in the non-block form to apply more explicit scoped defaults used throughout the tests:
+
+```ruby
+setup do
+  @menu_items = menu_items.with menu: accounts.kaspers_donuts.menus.first, description: "Indulgent & delicious."
+end
+
+test "something" do
+  @menu_items.create # The menu item is created with the defaults above.
+  @menu_items.create menu: menus.premium # You can still override defaults like usual.
+end
+```
+
+##### How `with` scoping works
+
+To make this easier to understand, we'll use a general `menu_items` object and then a scoped `basic_items = menu_items.with menu: menus.basic` object.
+
+- Labels: go to the general object, `basic_items.create :plain_donut` will be reachable via `menu_items.plain_donut`.
+- Defaults: only stay on the `with` object, so `menu_items.create` won't set `menu: menus.basic`, but `basic_items.create` will.
+- Helper methods: any helper methods defined on `menu_items` can be called on `basic_items`. We recommend only defining helper methods on the general `menu_items` object.
 
 ## Migration
 
@@ -490,7 +645,7 @@ Set Oaken up for your tests like the setup section mentions, and then only add a
 ```ruby
 # db/seeds.rb
 if Rails.env.test?
-  Oaken.loader.seed :setup, :accounts
+  Oaken.seed :accounts
   return
 end
 ```
@@ -533,6 +688,10 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/kaspth/oaken. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/kaspth/oaken/blob/main/CODE_OF_CONDUCT.md).
 
+## Bug Report Template
+
+When reporting bugs, please use our bug report template at [examples/bug_report_template.rb](examples/bug_report_template.rb)
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/examples/bug_report_template.rb

@@ -0,0 +1,47 @@
+require "bundler/inline"; gemfile do
+  source "https://rubygems.org"
+
+  gem "debug"
+
+  gem "activerecord", require: "active_record"
+  gem "sqlite3"
+
+  gem "oaken" #, "0.9.1" # TODO: Lock to the version you're using.
+end
+
+require "active_support/testing/autorun"
+
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+
+  establish_connection adapter: "sqlite3", database: ":memory:"
+  singleton_class.delegate :create_table, to: :lease_connection
+end
+
+class User < ApplicationRecord
+  create_table :users do |t|
+    t.string :name, null: false
+  end
+end
+
+# TODO: Put extra models/tables here as needed. Feel free to update User too.
+
+ApplicationRecord.subclasses.each { Oaken.register _1 }
+
+class BugTest < ActiveSupport::TestCase
+  include Oaken.context
+
+  setup do
+    @user = users.create name: "Someone"
+  end
+
+  test "it fails if I try this" do
+    # debugger # Uncomment or place elsewhere to use debug.rb's debugger
+    assert_equal "Someone", @user.name
+  end
+
+  test "yet somehow it passes if I do this" do
+  end
+end

data/examples/donuts.rb

@@ -0,0 +1,141 @@
+require "bundler/inline"; gemfile do
+  source "https://rubygems.org"
+
+  gem "debug"
+
+  gem "activerecord", require: "active_record"
+  gem "sqlite3"
+  gem "bcrypt"
+
+  gem "oaken", path: ".."
+end
+
+require "active_support/testing/autorun"
+
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+
+  establish_connection adapter: "sqlite3", database: ":memory:"
+  singleton_class.delegate :create_table, to: :lease_connection
+end
+
+class Account < ApplicationRecord
+  create_table :accounts do |t|
+    t.string :name, null: false
+    t.timestamps
+  end
+end
+
+class User < ApplicationRecord
+  create_table :users do |t|
+    t.string :name, null: false
+    t.string :email_address, null: false
+    t.string :password_digest, null: false
+    t.string :role, default: "plain", null: false
+    t.timestamps
+
+    t.index :email_address, unique: true
+  end
+
+  has_secure_password
+
+  enum :role, %w[admin mod plain].index_by(&:itself)
+
+  has_many :administratorships
+  has_many :accounts, through: :administratorships
+end
+
+class Administratorship < ApplicationRecord
+  create_table :administratorships do |t|
+    t.references :account, null: false, index: true
+    t.references :user, null: false, index: true
+    t.timestamps
+  end
+
+  belongs_to :account
+  belongs_to :user
+end
+
+class Menu < ApplicationRecord
+  create_table :menus do |t|
+    t.references :account, null: false, index: true
+    t.timestamps
+  end
+
+  belongs_to :account
+end
+
+class Menu::Item < ApplicationRecord
+  create_table :menu_items do |t|
+    t.references :menu, null: false, index: true
+    t.string :name, null: false
+    t.integer :price_cents, null: false
+    t.timestamps
+  end
+
+  belongs_to :menu
+end
+
+# We have to override this for the single file script here, but you don't need this in apps.
+class Oaken::Loader
+  def definition_location = caller_locations(3, 1)&.first
+end
+
+# Simulate db/seeds.rb
+# Oaken.seed :accounts # Will load `db/seeds/{,<Rails.env>/}accounts**/*.rb`
+
+# Simulate db/seeds/setup.rb
+# In Rails apps `Oaken.context.class_eval` is automatic.
+Oaken.context.class_eval do
+  # Set general defaults across models. Only the models with these columns will use this default, e.g. `menu_items#price_cents`.
+  loader.defaults price_cents: 10_00
+
+  # Use the decorative `section` method to carve up files.
+  section users do
+    # password/password_confirmation are virtual columns generated via `has_secure_password`
+    users.defaults password: "password123456", password_confirmation: "password123456"
+
+    # Expose the `enum :role` scopes, so `users.admin.create` will set `role: "admin"`.
+    users.proxy :admin, :mod, :plain
+
+    # This defined helper method uses Ruby's built-in `singleton_methods`. Not to be conflated with `include Singleton`.
+    # So we're overriding the built-in create method to mark users as unique by their `email_address`.
+    def users.create(label = nil, unique_by: :email_address, **) = super
+  end
+end
+
+# Simulate an db/seeds/accounts/kaspers_donuts.rb file.
+# In Rails apps `Oaken.context.class_eval` is automatic.
+Oaken.context.class_eval do
+  account = accounts.create :kaspers_donuts, name: "Kasper's Donuts"
+
+  users.with accounts: [account] do
+    kasper   = it.admin.create :kasper, name: "Kasper",   email_address: "kasper@example.com"
+    coworker = it.mod.create :coworker, name: "Coworker", email_address: "coworker@example.com"
+  end
+
+  menu = menus.create(:basic, account:)
+  plain_donut     = menu_items.create menu:, name: "Plain" # Gets `price_cents: 10_00` from `loader.defaults`
+  sprinkled_donut = menu_items.create menu:, name: "Sprinkled", price_cents: 20_00
+end
+
+class OakenTest < ActiveSupport::TestCase
+  include Oaken.context # In real Rails apps you should include `Oaken.test_setup` instead.
+
+  setup do
+    @user = users.kasper
+    @menu_items = menu_items.with menu: menus.basic, name: "High Price", price_cents: 20_00
+  end
+
+  test "access seeded records" do
+    assert_equal "Kasper", @user.name
+
+    @menu_items.create.tap do |item|
+      assert_equal "High Price", item.name
+      assert_equal 20_00, item.price_cents
+      assert_equal menus.basic, item.menu
+    end
+  end
+end

data/lib/oaken/loader.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/hash/indifferent_access"
+
 class Oaken::Loader
   autoload :Type, "oaken/loader/type"
 
@@ -81,16 +83,17 @@ class Oaken::Loader
     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 }
+  def definition_location(start_frame:)
+    # Locate first frame not in `setup` phase. Rely on caller adjusting frame start to skip over their stack levels.
+    # Won't skip over helpers defined in non-setup seed files, though that's probably ok.
+    caller_locations(1 + start_frame, 4).find { !setup_files.member? _1.path }
   end
 
   private
+    def setup_files = @setup_files ||= setup.map(&:to_s).to_set
     def setup = @setup ||= glob(:setup).each { load_one _1 }
 
     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/stored/active_record.rb

@@ -1,11 +1,19 @@
 class Oaken::Stored::ActiveRecord
+  attr_reader :loader, :type
+  delegate :context, to: :loader
+
+  delegate :transaction, to: :type # For multi-db setups to help open a transaction on secondary connections.
+  delegate :find, :insert_all, :pluck, to: :type
+
+  attr_reader :labels
+
   def initialize(loader, type)
     @loader, @type = loader, type
     @attributes = loader.defaults_for(*type.column_names)
+
+    @labels = {}
+    @label_target = singleton_class # Capture target so labels in `with` calls go to our original instance.
   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)
@@ -29,6 +37,12 @@ class Oaken::Stored::ActiveRecord
     record
   end
 
+  # Build a new record with the passed `attributes`.
+  def new(**attributes)
+    type.new(**attributes_for(**attributes))
+  end
+  alias_method :build, :new
+
   # Build attributes used for `create`/`upsert`, applying loader and per-type `defaults`.
   #
   #   loader.defaults name: -> { "Global" }, email_address: -> { … }
@@ -39,6 +53,54 @@ class Oaken::Stored::ActiveRecord
     @attributes.merge(attributes).transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
   end
 
+  # `with` allows you to group similar `create`/`upsert` calls & apply scoped defaults.
+  #
+  # ### `with` during setup
+  #
+  # During seeding setup, use `with` in the block form to group `create`/`upsert` calls, typically by an association you want to highlight.
+  #
+  # In this example, we're grouping menu items by their menu. We could write out each menu item `create` one by one and pass the menus explicitly just fine.
+  #
+  # However, grouping by the menu gets us an extra level of indentation to help reveal our intent.
+  #
+  #   menu_items.with menu: menus.basic do
+  #     it.create :plain_donut, name: "Plain Donut"
+  #     it.create name: "Another Basic Donut"
+  #     # More `create` calls, which automatically go on the basic menu.
+  #   end
+  #
+  #   menu_items.with menu: menus.premium do
+  #     it.create :premium_donut, name: "Premium Donut"
+  #     # Other premium menu items.
+  #   end
+  #
+  # ### `with` in tests
+  #
+  # In tests `with` is also useful in the non-block form to apply more explicit scoped defaults used throughout the tests:
+  #
+  #   setup do
+  #     @menu_items = menu_items.with menu: accounts.kaspers_donuts.menus.first, description: "Indulgent & delicious."
+  #   end
+  #
+  #   test "something" do
+  #     @menu_items.create # The menu item is created with the defaults above.
+  #     @menu_items.create menu: menus.premium # You can still override defaults like usual.
+  #   end
+  #
+  # ### How `with` scoping works
+  #
+  # To make this easier to understand we'll use a general `menu_items` object and then a scoped `basic_items = menu_items.with menu: menus.basic` object.
+  #
+  # - Labels: go to the general object, `basic_items.create :plain_donut` will be reachable via `menu_items.plain_donut`.
+  # - Defaults: only stay on the `with` object, so `menu_items.create` won't set `menu: menus.basic`, but `basic_items.create` will.
+  # - Helper methods: any helper methods defined on `menu_items` can be called on `basic_items`. We recommend only defining helper methods on the general `menu_items` object.
+  def with(**defaults)
+    clone.tap do
+      _1.defaults(**defaults) unless defaults.empty?
+      yield _1 if block_given?
+    end
+  end
+
   # Set defaults for all types:
   #
   #   loader.defaults name: -> { "Global" }, email_address: -> { … }
@@ -49,6 +111,36 @@ class Oaken::Stored::ActiveRecord
   #   users.create # => Uses the users' default `name` and the loader `email_address`
   def defaults(**attributes) = @attributes = @attributes.merge(attributes)
 
+  # `proxy` lets you wrap and delegate scopes from the underlying record.
+  #
+  # So if you have this Active Record:
+  #
+  #   class User < ApplicationRecord
+  #     enum :role, %w[admin mod plain].index_by(&:itself)
+  #     scope :cool, -> { where(cool: true) }
+  #   end
+  #
+  # You can then proxy the scopes and use them like this:
+  #
+  #   users.proxy :admin, :mod, :plain
+  #   users.proxy :cool
+  #
+  #   users.create       # Has `role: "plain"`, assuming it's the default role.
+  #   users.admin.create # Has `role: "admin"`
+  #   users.mod.create   # Has `role: "mod"`
+  #   users.cool.create  # Has `cool: true`
+  #
+  #   # Chaining also works:
+  #   users.cool.admin.create # Has `cool: true, role: "admin"`
+  def proxy(*names) = names.each do |name|
+    define_singleton_method(name) { clone.rebind(type.public_send(name)) }
+  end
+
+  protected def rebind(type)
+    @type = type
+    self
+  end
+
   # Expose a record instance that's setup outside of using `create`/`upsert`. Like this:
   #
   #   users.label someone: User.create!(name: "Someone")
@@ -62,12 +154,17 @@ class Oaken::Stored::ActiveRecord
   #   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 }
+  def label(**labels) = labels.each { |label, record| _label label, record.id, location_frame_skip: 2 }
+
+  private def _label(name, id, location_frame_skip: 0)
+    labels.fetch name do
+      loc = loader.definition_location(start_frame: 4 + location_frame_skip) or
+        raise "Oaken can't find a source_location for this label: #{name}. Please open an issue and share what you're trying and a backtrace if you can."
 
-  private def _label(name, id)
-    location = @loader.definition_location or
-      raise ArgumentError, "you can only define labelled records outside of tests"
+      label_target.class_eval "def #{name} = find(labels.fetch(__method__))", loc.path, loc.lineno
+    end
 
-    class_eval "def #{name} = find(#{id.inspect})", location.path, location.lineno
+    labels[name] = id
   end
+  private attr_reader :label_target
 end

data/lib/oaken/version.rb

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

data/lib/oaken.rb

@@ -3,6 +3,8 @@
 require "oaken/version"
 require "pathname"
 
+require "active_support/core_ext/module/delegation"
+
 module Oaken
   class Error < StandardError; end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oaken
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Kasper Timm Hansen
@@ -20,6 +20,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/bug_report_template.rb
+- examples/donuts.rb
 - lib/generators/oaken/convert/fixtures_generator.rb
 - lib/oaken.rb
 - lib/oaken/loader.rb
@@ -45,7 +47,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="