oaken 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 160e746d1605f0e227c7084ce39ee6e05837cfe4288de735b4407c39a45d4fbe
-  data.tar.gz: 9510c077a7f0f7bad0ebc56bfb6306cf2465253a04d6c19f28009a3552a47719
+  metadata.gz: f7a49242a569f0460aab42af0102a0aeec30095909c6362310b45e9ce0638c43
+  data.tar.gz: 218c22c32d91b4deaf4f3524f4a19daea964df126c3018b048a2a1119c679297
 SHA512:
-  metadata.gz: 393bd015fadfb6e806a49f43be92fbf764d89c15577f91963361cef6d8221ba8cbd2992c0edba6b38920831dbe3299482b12c3c46e1b2f5b593617ce8c697ccf
-  data.tar.gz: 3e6480a0ef119fa5929f44a6481359d7247ff4da4b4fcbc45225c90e98ad1c0897857f63d29c685b2a6af70f663724606360bb9487802fc9ac5995b8930ead9f
+  metadata.gz: 40f50f45dd4bfc45b326aacc111792b30a178446e3f51b1db9b0e9c0f95f91d6b3269a28fc3aaf8d797d5def0c6a6f1dad0ae6d61e4d1fe44aed7b994fb66dda
+  data.tar.gz: 9c21c825239bf7bb910632abe86d6672f63dcf9fe50d0cdf42270f03aed09ff9cad3268e6e5ec70957717996193791a43c67d2cab803ad4e16efce313f29fed6

data/README.md

@@ -1,22 +1,119 @@
 # Oaken
 
-The gem we're building in the Open Source Retreat https://kaspthrb.gumroad.com/l/open-source-retreat
+Oaken is an alternative to fixtures and/or factories to manage your development, test and some production data using data scripts.
 
-## Installation
+## Setup
+
+### Starting in development
+
+You can set it up in `db/seeds.rb`, like this:
+
+```ruby
+Oaken.prepare do
+  seed :accounts, :data
+end
+```
+
+This will look for deeply nested files to load in `db/seeds` and `db/seeds/#{Rails.env}` within the `accounts` and `data` directories.
+
+Here's what they could look like.
+
+```ruby
+# db/seeds/accounts/kaspers_donuts.rb
+donuts = accounts.create :kaspers_donuts, name: "Kasper's Donuts"
+
+kasper   = users.create :kasper,   name: "Kasper",   accounts: [donuts]
+coworker = users.create :coworker, name: "Coworker", accounts: [donuts]
+
+menu = menus.create account: donuts
+plain_donut     = menu_items.create menu: menu, name: "Plain",     price_cents: 10_00
+sprinkled_donut = menu_items.create menu: menu, name: "Sprinkled", price_cents: 10_10
+
+supporter = users.create name: "Super Supporter"
+orders.insert_all [user_id: supporter.id, item_id: plain_donut.id] * 10
+
+orders.insert_all \
+  10.times.map { { user_id: users.create(name: "Customer #{_1}").id, item_id: menu.items.sample.id } }
+```
+
+```ruby
+# db/seeds/data/plans.rb
+plans.insert :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!
+
+### Interlude: Directory Naming Conventions
+
+Oaken has some chosen directory conventions to help strengthen your understanding of your object graph:
+
+- Have a directory for your top-level model, like `Account`, `Team`, `Organization`, that's why we have `db/seeds/accounts` above.
+- `db/seeds/data` for any data tables, like the plans a SaaS app has.
+- `db/seeds/tests/cases` for any specific cases that are only used in some tests, like `pagination.rb`.
+
+### Reusing data in tests
+
+With the setup above, Oaken can reuse the same data in tests like so:
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+```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
+end
+```
+
+Now tests have access to `accounts.kaspers_donuts` and `users.kasper` etc. that were setup in the data scripts.
+
+You can also load a specific seed, like this:
+
+```ruby
+class PaginationTest < ActionDispatch::IntegrationTest
+  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
+```
+
+### Fixtures Converter
+
+You can convert your Rails fixtures to Oaken's seeds by running:
+
+    $ bin/rails generate oaken:convert:fixtures
+
+This will convert anything in test/fixtures to db/seeds. E.g. `test/fixtures/users.yml` becomes `db/seeds/users.rb`.
+
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ bundle add oaken
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ gem install oaken
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `cd test/dummy` and `bin/rails test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
@@ -30,4 +127,21 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Oaken project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kaspth/oaken/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Oaken project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/kaspth/oaken/blob/main/CODE_OF_CONDUCT.md).
+
+## Support
+
+Initial development is supported in part by:
+
+<a href="https://arrows.to">
+ <img src="https://user-images.githubusercontent.com/56947/258236465-06c692a7-738e-44bd-914e-fecc697317ce.png" />
+</a>
+
+And by:
+
+- [Alexandre Ruban](https://github.com/alexandreruban)
+- [Lars Kronfält](https://github.com/larkro)
+- [Manuel Costa Reis](https://github.com/manuelfcreis)
+- [Thomas Cannon](https://github.com/tcannonfodder)
+
+As a sponsor you're welcome to submit a pull request to add your own name here.

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

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

data/lib/oaken/entry.rb

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

data/lib/oaken/railtie.rb

@@ -0,0 +1,25 @@
+class Oaken::Railtie < Rails::Railtie
+  initializer "oaken.defaults" 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/seeds.rb

@@ -0,0 +1,41 @@
+module Oaken::Seeds
+  extend self
+
+  def self.respond_to_missing?(name, ...)
+    Oaken.inflector.classify(name).safe_constantize || super
+  end
+
+  def self.method_missing(meth, ...)
+    name = meth.to_s
+    if type = Oaken.inflector.classify(name).safe_constantize
+      register type, name
+      public_send(name, ...)
+    else
+      super
+    end
+  end
+
+  def self.register(type, key = nil)
+    stored = provider.new(type, key) and define_method(stored.key) { stored }
+  end
+  def self.provider = Oaken::Stored::ActiveRecord
+
+  singleton_class.attr_reader :loader
+  delegate :entry, to: :loader
+
+  module Loading
+    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
+      end
+    end
+  end
+  extend Loading
+
+  def self.included(klass)
+    klass.extend Loading
+  end
+end

data/lib/oaken/stored/active_record.rb

@@ -0,0 +1,40 @@
+class Oaken::Stored::ActiveRecord < Struct.new(:type, :key)
+  def initialize(type, key = nil)
+    super(type, key || Oaken.inflector.tableize(type.name))
+    @attributes = {}
+  end
+  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(reader = nil, **attributes)
+    lineno = caller_locations(1, 1).first.lineno
+
+    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
+
+  def insert(reader = nil, **attributes)
+    lineno = caller_locations(1, 1).first.lineno
+
+    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
+  end
+
+  def define_reader(...)
+    Oaken::Seeds.entry.define_reader(self, ...)
+  end
+end

data/lib/oaken/version.rb

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

data/lib/oaken.rb

@@ -1,8 +1,69 @@
 # frozen_string_literal: true
 
-require_relative "oaken/version"
+require "oaken/version"
+require "pathname"
 
 module Oaken
   class Error < StandardError; end
-  # Your code goes here...
+
+  autoload :Seeds, "oaken/seeds"
+  autoload :Entry, "oaken/entry"
+
+  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
+    end
+
+    def load_onto(seeds)
+      @entries.each do |entry|
+        @entry = entry
+        @entry.load_onto seeds
+      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
 end
+
+require_relative "oaken/railtie" if defined?(Rails::Railtie)

metadata

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