toil 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8872978ce2bae67af8b5c87d3735d964e998336d
+  data.tar.gz: ba1f898bba5f18ab7be297ef17ed34f3394dac05
+SHA512:
+  metadata.gz: 11b1211e720a569863e24098483d94162a2bc112720300ca78df027d0574b79d8abcbf73d0bd28f20f4516454cb702493e5752865407d533bae65a095f7ab54a
+  data.tar.gz: dd08d2a0344f8dbacfacffcf6b933c683120a703149c9017674d18384b2b54d71413df90855f309c3e1efbf7301b6d64a7192961d7880cbf0f2d039746e0c6e3

data/LICENSE.txt

@@ -0,0 +1,18 @@
+Copyright (c) 2019 Joshua Hansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,171 @@
+# Toil
+
+## Introduction
+
+Apparently, the Ruby world needed yet another factory gem for testing. So, here it is.
+
+### Why not just use [insert significantly more popular factory gem here]?
+
+This gem was built to scratch a particular itch. Some of the larger projects I test have moved away from instantiating models directly and generally use service-like objects or function modules to create new models or other resources. While the resulting object is quite often some kind of ORM model, the creation often takes a lot of virtual attributes or even takes argument signatures that are something other than a hash. I've used [Fabrication](https://www.fabricationgem.org) for years, but adapting it to my current needs didn't work out as smoothly as I would have liked.
+
+So, here we are. I rolled my own.
+
+### What's with the name?
+
+Look, all the other names were gone. [Fabrication](https://www.fabricationgem.org) is already in use with a very nice website. [Machinist](https://github.com/notahat/machinist) is also taken. [factory_girl](https://github.com/thoughtbot/factory_bot) (ahem, sorry, _factory_bot_ since it got all [woke](https://thoughtbot.com/blog/factory_bot)) has a monopoly on factory_*. Even [Mike Perham](https://github.com/mperham) of [Sidekiq](https://sidekiq.org) fame is working on [Faktory](https://github.com/contribsys/faktory)—and while it has nothing to do with tests, I don't even have the obvious rename-with-a-wrong-spelling option out there without confusing people. I guess I could have gone with like Factori, Factoree, or like... never mind. Those clearly suck. Even Sweatshop, the original name, was taken.
+
+Tests are a toil. It's four letters. It was available.
+
+### Design Goals
+
+I use [Fabrication](https://www.fabricationgem.org) without any nesting to generate attributes. That's about it. Those attributes are then passed to service objects to make stuff. This means generating attributes doesn't have to know anything about dependencies. This works okay until:
+
+1. You're working with something other than hashes.
+2. You go to modify/extend your existing factory gem and realize it's not exactly the right tool for the job.
+
+I wanted a very small, simple codebase. This is really just a container for potentially dynamic attribute generation and methods for spitting out dependencies for tests. I also wanted a codebase that doesn't really care about what it's building. Whether you're using [Sequel](https://github.com/jeremyevans/sequel), [ActiveRecord](https://github.com/rails/rails/tree/master/activerecord), [ROM](https://rom-rb.org), or something that doesn't touch a database, it doesn't matter.
+
+This generates arguments, passes them to some sort of constructor or creator object (it's just got to respond to `call`), processes a few optional callbacks, and spits out your object. Simple, repetitive, and mind-numbing—sound familiar?
+
+## Installation
+
+Pretty standard gem stuff.
+
+```
+$ gem install toil
+```
+
+If you're using [Bundler](https://bundler.io) (and who isn't?) it's likely you'll add this to the `:test` group of your `Gemfile` like so:
+
+```
+group :test do
+  gem 'toil'
+end
+```
+
+Maybe include it in `:development` too. Whatever. You be you.
+
+## Usage
+
+While one of the primary goals is dealing with an array of arguments, a hash of attributes still works just as naturally and a lot of the DSL is very much biased in that direction.
+
+These examples will use [Faker](https://github.com/stympy/faker).
+
+### Registration
+
+Register a new prototype like so:
+
+```ruby
+Toil.register(:person, ->(*args) { Person.create(*args) }) do
+  name { Faker::Name.name }
+end
+```
+
+The second argument must respond to `call`, so a `proc` or `lambda` will work fine in instances where you have no constructor object.
+
+You can duplicate and extend existing prototypes passing a `Symbol`:
+
+```ruby
+Toil.register(:star_wars_character, :person) do
+  name { Faker::StarWars.character }
+end
+```
+### Arguments vs. Attributes
+
+The DSL is quite opinionated toward a single argument attribute hash. All the DSL methods effect the first hash in the arguments list. This means if you have two hashes, you'll have to make changes to the second in a more "manual" fashion.
+
+The `arg` and `arg_at` methods can be used to add or insert arguments when creating or duplicating a prototype. Overrides also account arrays to override arguments.
+
+It can get really complicated when duplicating factories. There's little reason to abuse this. An extremely common pattern is:
+
+`CreatorClass.call(object1, object2, attributes)`
+
+Basically, you have some related dependencies that don't get added as attributes (or maybe the attributes are optional). Whatever the case, these options exist to satisfy constructors that don't just take a hash of options.
+
+### Callbacks
+
+There are only two callbacks, `before_create` and `after_create`. Each time the method is invoked, a new callback is added to each stack. So, if you're duplicating an existing prototype, keep in mind you'll be adding more callbacks, not replacing existing ones.
+
+#### `before_create`
+
+This is meant to transform arguments being passed to the constructor in some way that requires context from existing arguments. A simple example would be that you wanted to create an email address from a randomly generated name.
+
+```ruby
+Toil.register(:person_with_email, :person) do
+  before_create do |attributes, *|
+    attributes[:email] = Faker::Internet.email(attributes[:name])
+  end
+end
+```
+
+Note: Arguments are passed as a single array, since you may want to mutate any possible arguments. If you plan on having a single attributes hash, remember to append your method with a splat like the example above.
+
+#### `after_create`
+
+The object created once attributes are passed to the constructor will always be yielded to `after_create`. Unlike `before_create` you don't have to pay any attention to what is returned. The same object will be yielded to every `after_create` callback. This is generally for adding relationships or processing state transitions on an object. For example:
+
+```ruby
+Toil.register(:pending_order, OrderCreator) do
+  # ...
+end
+
+Toil.register(:paid_order, :pending_order) do
+  after_create { |order| OrderPayer.call(order, amount: order.full_amount) }
+end
+```
+
+### What about relationships?
+
+You don't use nested attributes or arguments to build relationships. Dependencies and related resources should be created with other prototypes either as arguments or in `after_create` hooks. For example:
+
+```ruby
+Toil.register(:album, AlbumCreator)
+
+Toil.register(:rio_album, :album) do
+  artist { Toil.create(:duran_duran) }
+  tracks 9
+  release_date Date.new(1982, 5, 10)
+end
+
+Toil.register(:rio_album_multiplatinum, :rio_album) do
+  after_create do |obj|
+    2_000_000.times { Toil.create(:album_sale, album: obj) }
+  end
+end
+
+```
+
+### Creating Objects
+
+Use `create` to try and create an object of some sort. You pass in overrides, either as a hash or an array (it gets splatted). You can use this to add more arguments, or override defaults:
+
+```ruby
+Toil.create(:star_wars_character, name: 'James T. Kirk')
+```
+
+Overrides are resolved first, so if your prototypes create dependencies, they **will not** be created in addition to whatever override is passed in.
+
+## Contributing
+
+### Issue Guidelines
+
+GitHub issues are for bugs, not support. As of right now, there is no official support for this gem. You can try reaching out to the author, [Joshua Hansen](mailto:joshua@epicbanality.com?subject=Toil+sucks) if you're really stuck, but there's a pretty high chance that won't go anywhere at the moment or you'll get a response like this:
+
+> Hi. I'm super busy. It's nothing personal. Check the README first if you haven't already. If you don't find your answer there, it's time to start reading the source. Have fun! Let me know if I screwed something up.
+
+### Pull Request Guidelines
+
+* Include tests with your PRs.
+* Run `bundle exec rubocop` to ensure your style fits with the rest of the project.
+
+### Code of Conduct
+
+Sorry, I'm not woke.
+
+## License
+
+See [`LICENSE.txt`](LICENSE.txt).
+
+## What if I stop maintaining this?
+
+The codebase is pretty small. That was one of the main design goals. If you can figure out how to use it, I'm sure you can maintain it.

data/lib/toil.rb

@@ -0,0 +1,33 @@
+# frozen-string-literal: true
+
+require 'toil/prototype'
+
+module Toil
+  class << self
+    def call(prototype_name, *overrides)
+      self[prototype_name].call(*overrides)
+    end
+    alias create call
+
+    def [](prototype_name)
+      Prototype[prototype_name]
+    end
+
+    def register(prototype_name, obj = nil, &blk)
+      Prototype.register(prototype_name, obj, &blk)
+    end
+
+    def to_a(prototype_name, *overrides)
+      self[prototype_name].to_a(*overrides)
+    end
+    alias args to_a
+    alias arguments to_a
+
+    def to_h(prototype_name, overrides = {})
+      self[prototype_name].to_h(overrides)
+    end
+    alias atts to_h
+    alias attributes to_h
+    alias params to_h
+  end
+end

data/lib/toil/arguments.rb

@@ -0,0 +1,93 @@
+# frozen-string-literal: true
+
+require 'toil/attributes'
+
+module Toil
+  class Arguments
+    def initialize(args, &blk)
+      @args = __array__(args).map { |v| __arg__(v) }
+      __find_attributes__
+      instance_eval(&blk) if block_given?
+    end
+
+    def method_missing(m, *args, &blk)
+      attribute(m, args.first, &blk)
+    end
+
+    def arg(value = nil, &blk)
+      arg_at(@args.size, value, &blk)
+    end
+
+    def arg_at(index, value = nil, &blk)
+      @args[index] = __arg__(value, &blk)
+      __find_attributes__
+      @args[index]
+    end
+
+    def attribute(key, value = nil, &blk)
+      @attributes || arg({})
+      @attributes.__set__(key, value, &blk)
+    end
+
+    def attributes_at
+      @args.each_with_index { |v, i| return i if v == @attributes }
+      nil
+    end
+
+    def dup(&blk)
+      self.class.new(@args, &blk)
+    end
+
+    def [](key)
+      @attributes[key]
+    end
+
+    def to_a(*overrides)
+      @args.each_with_index.map do |a, i|
+        if overrides.size > i
+          __merge_or_override__(overrides[i], a)
+        elsif a.is_a?(Attributes)
+          a.to_h
+        else
+          a.call
+        end
+      end + Array(overrides[(@args.size)..-1])
+    end
+    alias to_ary to_a
+
+    def to_h(overrides = {})
+      @attributes.to_h(overrides)
+    end
+    alias to_hash to_h
+
+    private
+
+    def __arg__(arg, &blk)
+      return DynamicValue.new(&blk) if block_given?
+
+      case arg
+      when Attributes
+        arg.dup
+      when DynamicValue
+        arg
+      when Hash
+        Attributes.new(arg)
+      else
+        DynamicValue.new(arg)
+      end
+    end
+
+    def __array__(args)
+      args.is_a?(Array) ? args : [args]
+    end
+
+    def __find_attributes__
+      @attributes ||= @args.reverse.find { |v| v.is_a?(Attributes) }
+    end
+
+    def __merge_or_override__(override, arg)
+      return arg.to_h(override) if override.is_a?(Hash) && arg.is_a?(Attributes)
+      override
+    end
+  end
+end

data/lib/toil/attributes.rb

@@ -0,0 +1,37 @@
+# frozen-string-literal: true
+
+require 'toil/dynamic_value'
+
+module Toil
+  class Attributes
+    def initialize(hash = {}, &blk)
+      @attributes = hash.each_with_object({}) do |(k, v), h|
+        h[k] = v.is_a?(DynamicValue) ? v : DynamicValue.new(v)
+      end
+      instance_eval(&blk) if block_given?
+    end
+
+    def method_missing(m, *args, &blk)
+      __set__(m, args.first, &blk)
+    end
+
+    def dup(&blk)
+      self.class.new(@attributes, &blk)
+    end
+
+    def to_h(overrides = {})
+      @attributes.each_with_object({}) do |(k, v), h|
+        h[k] = v.call unless overrides.key?(k)
+      end.merge(overrides)
+    end
+    alias to_hash to_h
+
+    def [](key)
+      (v = @attributes[key]) && v.call
+    end
+
+    def __set__(key, value = nil, &blk)
+      @attributes[key] = DynamicValue.new(value, &blk)
+    end
+  end
+end

data/lib/toil/dynamic_value.rb

@@ -0,0 +1,26 @@
+# frozen-string-literal: true
+
+module Toil
+  class DynamicValue
+    def initialize(value = nil, &blk)
+      @static = false
+      @proc =
+        if block_given?
+          blk
+        elsif value.is_a?(Proc)
+          value
+        else
+          @static = true
+          proc { value }
+        end
+    end
+
+    def call
+      @proc.call
+    end
+
+    def static?
+      @static
+    end
+  end
+end

data/lib/toil/prototype.rb

@@ -0,0 +1,87 @@
+# frozen-string-literal: true
+
+require 'toil/arguments'
+
+module Toil
+  class Prototype
+    CALLBACKS = %i[after_create before_create].freeze
+    NO_ATTS_MSG = 'There are no attribute arguments for this prototype.'.freeze
+    AlreadyRegistered = Class.new(ArgumentError)
+    NoAttributesDefined = Class.new(RuntimeError)
+    NotRegistered = Class.new(ArgumentError)
+
+    @@registry = {}
+
+    class << self
+      def [](key)
+        raise NotRegistered, "`:#{key}` is not a registered prototype" unless
+          @@registry.key?(key)
+        @@registry[key]
+      end
+
+      def register(key, obj = nil, &blk)
+        key = key.to_sym
+        raise AlreadyRegistered, "`:#{key}` has already been registered" if
+          @@registry.key?(key)
+
+        @@registry[key] = obj.is_a?(Symbol) ? self[obj].dup(&blk) : new(obj, &blk)
+      end
+    end
+
+    def initialize(constructor, arguments = [], callbacks = {}, &blk)
+      @constructor = __constructor__(constructor)
+      @arguments = __arguments__(arguments)
+      @callbacks = __callbacks__(callbacks)
+      instance_eval(&blk) if block_given?
+    end
+
+    def call(*overrides)
+      __exec_callbacks__(:after_create, @constructor.(*to_a(*overrides)))
+    end
+
+    def method_missing(m, *args, &blk)
+      @arguments.public_send(m, *args, &blk)
+    end
+
+    def dup(&blk)
+      self.class.new(@constructor, @arguments, @callbacks, &blk)
+    end
+
+    def to_a(*overrides)
+      __exec_callbacks__(:before_create, @arguments.to_a(*overrides))
+    end
+    alias to_ary to_a
+
+    def to_h(overrides = {})
+      raise NoAttributesDefined, NO_ATTS_MSG unless (at = @arguments.attributes_at)
+      args = @arguments.to_a
+      args[at].merge!(overrides)
+      __exec_callbacks__(:before_create, args)[at]
+    end
+    alias to_hash to_h
+
+    CALLBACKS.each do |key|
+      define_method(key) { |&blk| @callbacks[key] += [blk] }
+    end
+
+    private
+
+    def __arguments__(args)
+      args.is_a?(Arguments) ? args.dup : Arguments.new(args)
+    end
+
+    def __callbacks__(callbacks)
+      CALLBACKS.each_with_object({}) { |k, h| h[k] = [] }.merge(callbacks)
+    end
+
+    def __constructor__(obj)
+      raise ArgumentError, 'Object does not respond to `call`' unless obj.respond_to?(:call)
+      obj
+    end
+
+    def __exec_callbacks__(key, args)
+      @callbacks[key].each { |clbk| clbk.(args) }
+      args
+    end
+  end
+end

data/lib/toil/sequence.rb

@@ -0,0 +1 @@
+# frozen-string-literal: true

data/lib/toil/version.rb

@@ -0,0 +1,12 @@
+# frozen-string-literal: true
+
+module Toil
+  MAJOR = 0
+  MINOR = 1
+  TINY  = 0
+  VERSION = [MAJOR, MINOR, TINY].join('.').freeze
+
+  def self.version
+    VERSION
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: toil
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joshua
+- Hansen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-03-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.56'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.56'
+description: Yet another factory library.
+email:
+- joshua@epicbanality.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/toil.rb
+- lib/toil/arguments.rb
+- lib/toil/attributes.rb
+- lib/toil/dynamic_value.rb
+- lib/toil/prototype.rb
+- lib/toil/sequence.rb
+- lib/toil/version.rb
+homepage: https://github.com/binarypaladin/toil
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.4
+signing_key: 
+specification_version: 4
+summary: Yet another factory library.
+test_files: []