object_forge 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83440b5319d1e909379d16b67830ad1f67f575358473dd4ba5914cb549c417b9
-  data.tar.gz: 279a5756a157f96252081cb60ce0541bdffdf1e21a25fe72db19b622c7d717e8
+  metadata.gz: 9481504e1456ec667e1c0182ecef5456cb2c9094b62ba6e09da62f0c1c79a00e
+  data.tar.gz: d2c2fdcfd6807211ea82987c998f4d2d8c6e0b1bbc334178330f97dfd8d7df7b
 SHA512:
-  metadata.gz: e16b3091daf563ffffbb5da39b50a6cc2298a288a1e71528ab9de905e0c959718555ff8d3b6b2a3478f094fa3ebff8727f0a95e97c6adef05d3c7abb1ae6676f
-  data.tar.gz: 04455c660052171b8a4456323b700f91805d0c05190329427baee1468b42ccfee3c315b79534f997b45a1f2cd716f85076e164f8007cad821f43047a5ea8fcbf
+  metadata.gz: 85b341cae5396f0eee11f00e6084bfbdc4561070c4657d3e7265570b48f195789c4a8763220d81f38f2dd4c31573a36064aecf346f9e6ffac8e07dbcbcf86720
+  data.tar.gz: dc7faa45a80ce51ac2b4f57f7a88134b8c6a44ad3889f06b896962aa6de711c7fee36b70b7952ba80e19b95d036e838c169abebc375712a76b29e21e7ff54815

data/README.md

@@ -0,0 +1,372 @@
+# ObjectForge
+
+[![Gem Version](https://badge.fury.io/rb/object_forge.svg?icon=si%3Arubygems)](https://rubygems.org/gems/object_forge)
+[![CI](https://github.com/trinistr/object_forge/actions/workflows/CI.yaml/badge.svg)](https://github.com/trinistr/object_forge/actions/workflows/CI.yaml)
+
+> [!TIP]
+> You may be viewing documentation for an older (or newer) version of the gem than intended. Look at [Changelog](https://github.com/trinistr/object_forge/blob/main/CHANGELOG.md) to see all versions, including unreleased changes.
+
+***
+
+**ObjectForge** is a small factory library for Ruby objects with minimal assumptions about framework, persistence, or runtime environment.
+
+It is designed for cases where factory-style object construction is useful, but Rails-oriented or database-oriented tooling is a poor fit. **ObjectForge** works well with plain Ruby objects, hashes, structs, and custom build flows.
+
+The library focuses on:
+- explicit configuration over hidden conventions
+- support for independent registries and standalone factories
+- replaceable components based on simple interfaces
+- usefulness both outside of tests and inside them
+
+If you need factory-style object generation without coupling it to Rails, ActiveRecord, or a particular application structure, **ObjectForge** might be for you.
+
+## Table of contents
+
+- [Motivation](#motivation)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Quick start](#quick-start)
+  - [Basics](#basics)
+  - [Independent forgeyards and forges](#independent-forgeyards-and-forges)
+  - [Molds: configuring object construction](#molds-configuring-object-construction)
+  - [After-build customization](#after-build-customization)
+  - [Performance tips](#performance-tips)
+- [Differences and limitations (compared to FactoryBot)](#differences-and-limitations-compared-to-factorybot)
+- [Current and planned features (roadmap)](#current-and-planned-features-roadmap)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Motivation
+
+Ruby already has well-known factory libraries, especially FactoryBot and Fabrication. Those tools are effective in many projects, particularly when working in Rails applications and persistence-oriented test setups.
+
+**ObjectForge** aims at a different problem space: building objects with a factory-style workflow while making as few assumptions as possible about framework, storage, object lifecycle, or application structure.
+
+**ObjectForge** is particularly useful when:
+- the objects being built are plain Ruby objects rather than database-backed records
+- object generation is needed outside of tests, such as in services, scripts, or fixtures
+- multiple independent sets of factories need to coexist in the same project
+- construction behavior should be explicit and configurable rather than hidden behind framework conventions
+
+The project is intentionally small in scope. Rather than trying to model every style of factory workflow, it focuses on a compact, understandable core:
+- a DSL for defining attributes, sequences, and traits
+- forges (factories) and forgeyards (registries)
+- several object molds (constructors)
+- a couple other helper components
+
+The goal is to have a simple, composable tool that you can easily reach for when heavier libraries don't fit or feel like overkill.
+
+## Installation
+
+Install with `gem`:
+```sh
+gem install object_forge
+```
+
+Or, if using Bundler, add to your Gemfile:
+```ruby
+gem "object_forge"
+```
+and run `bundle install`.
+
+## Usage
+
+> [!Note]
+> - Latest documentation from `main` branch is automatically deployed to [GitHub Pages](https://trinistr.github.io/object_forge).
+> - Documentation for published versions is available on [RubyDoc](https://rubydoc.info/gems/object_forge).
+
+### Quick start
+
+Create your domain logic class:
+```ruby
+class Rectangle
+  def initialize(length:, width:)
+    @length = length
+    @width = width
+  end
+
+  def area = @length * @width
+
+  def inspect = "[#{@length}x#{@width}]"
+end
+```
+
+Define a forge:
+```ruby
+require "object_forge"
+ObjectForge.define(:rectangle, Rectangle) do |f|
+  f.mold = ObjectForge::Molds::KeywordsMold.new
+
+  f.length { rand(1..100) }
+  f.width { rand(1..100) }
+
+  f.trait :square do |t|
+    t.width { length }
+  end
+end
+```
+
+Forge some objects!
+```ruby
+ObjectForge.forge(:rectangle) # => [63x27]
+ObjectForge.forge(:rectangle, :square) # => [56x56]
+ObjectForge.forge(:rectangle, width: 3333) # => [79x3333]
+ObjectForge.forge(:rectangle, :square, length: 123) # => [123x123]
+```
+
+### Basics
+
+In the simplest cases, **ObjectForge** can be used much like other factory libraries, with definitions living in a global object (`ObjectForge::DEFAULT_YARD`). In this case, methods are called directly on `ObjectForge` module.
+
+Forges are defined using a DSL:
+```ruby
+# Example class:
+Point = Struct.new(:id, :x, :y)
+
+ObjectForge.define(:point, Point) do |f|
+  # Attributes can be defined using `#attribute` method:
+  f.attribute(:x) do
+    # Inside attribute definitions, other attributes can be referenced by name, in any order!
+    rand(-delta..delta)
+  end
+  # `#[]` is an alias of `#attribute`:
+  f[:y] { rand(-delta..delta) }
+  # There is also the familiar shortcut using `method_missing`:
+  f.delta { 0.5 * amplitude }
+  # Notice how transient attributes don't require any special syntax:
+  f.amplitude { 1 }
+  # `#sequence` defines a sequenced attribute (starting with 1 by default):
+  f.sequence(:id, "a")
+  # Traits allow to group and reuse related values:
+  f.trait :z do
+    f.amplitude { 0 }
+    # Sequence values are forge-global, but traits can redefine blocks:
+    f.sequence(:id) { |id| "Z_#{id}" }  
+  end
+  # Trait's block can receive DSL object as a parameter:
+  f.trait :invalid do |tf|
+    tf.y { Float::NAN }
+    # `#[]` method inside attribute definition can be used to reference attributes:
+    tf.id { self[:x] }
+  end
+end
+```
+
+A forge builds objects, using attributes hash:
+```ruby
+ObjectForge.call(:point)
+  # => #<struct Point id="a", x=0.17176955469852973, y=0.3423901951181103>
+# Positional arguments define used traits:
+ObjectForge.build(:point, :z)
+  # => #<struct Point id="Z_b", x=0.0, y=0.0>
+# Attributes can be overridden with keyword arguments:
+ObjectForge.forge(:point, x: 10)
+  # => #<struct Point id="c", x=10, y=-0.3458802496120402>
+# Traits and overrides are combined in the given order:
+ObjectForge.call(:point, :z, :invalid, id: "NaN")
+  # => #<struct Point id="NaN", x=0.0, y=NaN>
+# A Proc override behaves the same as an attribute definition:
+ObjectForge.call(:point, :z, x: -> { rand(100..200) + delta })
+  # => #<struct Point id="Z_d", x=135.0, y=0.0>
+# A block can be passed to do something with the created object:
+ObjectForge.call(:point, :z) { puts "#{_1.id}: #{_1.x},#{_1.y}" }
+  # outputs "Z_e: 0.0,0.0"
+```
+> [!TIP]
+> Forging can be done through any of `#call`, `#forge`, or `#build` methods, they are aliases.
+
+### Independent forgeyards and forges
+
+It is possible and *encouraged* to create multiple forgeyards, each with its own set of forges:
+```ruby
+forgeyard = ObjectForge::Forgeyard.new
+forgeyard.define(:dot, Point) do |f|
+  f.sequence(:id, "a")
+  f.x { rand(-radius..radius) }
+  f.y { rand(-radius..radius) }
+  f.radius { 0.5 }
+  f.trait :z do f.radius { 0 } end
+end
+```
+
+Now, this forgeyard can be used just like the default one:
+```ruby
+forgeyard.forge(:dot, :z, id: "0")
+  # => #<struct Point id="0", x=0, y=0>
+```
+
+Note how the forge isn't registered in the default forgeyard:
+```ruby
+ObjectForge.forge(:dot)
+  # KeyError: key not found
+```
+
+If you find it more convenient not to use a forgeyard (for example, if you only need a single forge for your service), you can create individual forges:
+```ruby
+forge = ObjectForge::Forge.define(Point) do |f|
+  f.sequence(:id, "a")
+  f.x { rand(-radius..radius) }
+  f.y { rand(-radius..radius) }
+  f.radius { 0.5 }
+  f.trait :z do f.radius { 0 } end
+end
+```
+
+**Forge** has the same building interface as a **Forgeyard**, but it doesn't have the name argument:
+```ruby
+forge.build
+  # => #<struct Point id="a", x=0.3317733939650964, y=-0.1363936629550252>
+forge.forge(:z)
+  # => #<struct Point id="b", x=0, y=0>
+forge.(radius: 500)
+  # => #<struct Point id="c", x=-141, y=109>
+```
+
+### Molds: configuring object construction
+
+If you use core Ruby data containers, such as `Struct`, `Data` or even `Hash`, they will "just work". However, if a custom class is used, forging will probably fail, unless your class happens to take a hash of attributes in `#initialize`. It would be against the goal of **ObjectForge** to place requirements on your classes, and indeed there is a solution.
+
+Whenever you need to change how your objects are built, you specify a *mold*. Molds are just `call`able objects (including `Proc`s!) with specific arguments. They are set in forge definition:
+```ruby
+forge = ObjectForge::Forge.define(Point) do |f|
+  f.mold = ->(forge_target:, attributes:, **) do
+    forge_target.new(attributes[:id], attributes[:x].round(3), attributes[:y].round(3))
+  end
+  #... rest of the definition from the previous example
+end
+```
+
+Now the specified **mold** will be called to build your objects:
+```ruby
+forge.forge
+  # => #<struct Point id="a", x=0.331, y=-0.136>
+```
+
+Of course, you can abuse this to your heart's content. Look at the documentation for `ObjectForge::Molds` for inspiration.
+
+**ObjectForge** comes pre-equipped with a selection of molds for common cases:
+- `ObjectForge::Molds::SingleArgumentMold` (*the default*) calls `new(attributes)`, suitable for **ActiveModel**-style objects and **Dry::Struct**, as an example
+- `ObjectForge::Molds::KeywordsMold` calls `new(**attributes)`, suitable for **Data** and similar classes
+- `ObjectForge::Molds::HashMold` allows building **Hash** (including subclasses), providing a way to easily use build hashes
+- `ObjectForge::Molds::StructMold` handles all possible cases of `keyword_init` for **Struct**s
+
+> [!NOTE]
+> If you don't specify a mold, **ObjectForge** will infer one for core data containers, including **Hash**, **Struct**, and **Data** subclasses.
+
+> [!TIP]
+> It is recommended to use molds instances directly. Using classes causes memory churn and lowered performance. Not only that, but having a stateful mold is a code smell and probably represents a significant design issue.
+
+### After-build customization
+
+If there is a need to modify the object or perform additional actions after it is forged, there are two mechanisms you can employ:
+- after-forge hook
+- customization block
+
+After-forge hook is a `call`able object specified as part of forge definition. It runs every time forging happens:
+```ruby
+forge = ObjectForge::Forge.define(Rectangle) do |f|
+  # can also be specified as `after_build`
+  f.after_forge = ->(rect) { puts "Used #{rect.area} sq. units" }
+  #... rest of the definition from the Quick start example
+end
+forge.forge
+  # Used 621 sq. units
+  # => [23x27]
+```
+
+Customization block is an optional block argument to `#forge` and is only executed in that specific invocation:
+```ruby
+forge.forge { |rect| RectangleRepository.save(rect); puts "persisted!" }
+  # Used 621 sq. units
+  # persisted!
+  # => [23x27]
+```
+
+If both hook and block are used, the hook runs before the block. 
+
+### Performance tips
+
+**ObjectForge** is pretty fast for what it is. However, if you are worried, there are certain things that can be done to make it faster.
+- The easiest thing is to enable [**YJIT**](https://docs.ruby-lang.org/en/master/yjit/yjit_md.html). It will probably speed up your whole application, but be aware that it is not always suitable and may even degrade performance on some workloads. It *is* considered production-ready though.
+- Calling a **Forge** directly, instead of through **Forgeyard**, is faster due to not needing argument forwarding. This is consistent (but check on your system anyway!).
+- Using `self[:name]` instead of plain `name` inside attribute definitions does not engage dynamic method dispatch, which *should* be faster. However, micro-benchmarking does not show conclusive results.
+
+## Differences and limitations (compared to FactoryBot)
+
+If you are used to FactoryBot, be aware that there are quite a few differences in specifics.
+
+General:
+- The user (you) is responsible for loading forge definitions, there are no search paths. If **ObjectForge** is used in tests, it should be enough to add something like `Dir["spec/forges/**/*.rb].each { require _1 }` to your `spec_helper.rb` (or `rails_helper.rb`).
+- `Forgeyard.define` *is* the forge definition block, there is no separate `factory` block.
+
+Forge definition:
+- Class specification for a forge is non-optional, there is no assumption about the class name.
+- If the DSL block declares a block argument, `self` context is not changed, and DSL methods can't be called with an implicit receiver.
+- There is no forge inheritance or nesting.
+
+Attributes:
+- Currently, there is no concept of transient attributes. Attribute selection needs to be handled by the mold.
+- *There are no associations*. If nested objects are required, they should be created and set in the block for the attribute.
+
+Traits:
+- Traits can't be defined inside of other traits.
+- Traits can't be called from other traits. This may change in the future.
+- There are no default traits.
+
+Sequences:
+- There is no explicit way to define shared sequences, but a freestanding `Sequence` can be created manually and passed into `sequence` calls.
+- Sequences work with values implementing `#succ`, not `#next`, expressly prohibiting `Enumerator`. This may be relaxed in the future.
+
+## Current and planned features (roadmap)
+
+```mermaid
+kanban
+  [✅ Done]
+    [FactoryBot-like DSL: attributes, traits, sequences]
+    [Independent forges]
+    [Independent forgeyards]
+    [Default global forgeyard]
+    [Thread-safe behavior]
+    [Tapping into built objects for post-processing]
+    [Custom builders / molds]
+    [Built-in Hash, Struct, Data builders / molds]
+    [Ability to replace resolver]
+    [After-build hook]
+  [⚗️ To do]
+    [Transient attributes / attribute filtering]
+  [❔ Maybe, maybe not]
+    [Calling traits from traits]
+    [Default traits]
+    [Forge inheritance]
+    [Premade performance forge: static DSL, epsilon resolver]
+    [Enumerator compatibility in sequences]
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. If you will be running typing checks (RBS/Steep), also execute `rbs collection install`.
+
+Then, run `rake spec` to run the tests, `rake rubocop` to lint code and check style compliance, `rake rbs` to validate signatures or just `rake` to do everything above. There is also `rake steep` to check typing, and `rake docs` to generate YARD documentation.
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment, or `bin/benchmark` to run a benchmark script and generate a StackProf flamegraph.
+
+To install this gem onto your local machine, run `rake install`. To release a new version, run `rake version:{major|minor|patch}`, and then run `rake release`, which will push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/trinistr/object_forge.
+
+**Checklist for a new or updated feature**
+
+- Running `rake spec` reports 100% coverage (unless it's impossible to achieve in one run).
+- Running `rake rubocop` reports no offenses.
+- Running `rake steep` reports no new warnings or errors.
+- Tests cover the behavior and its interactions. 100% coverage *is not enough*, as it does not guarantee that all code paths are tested.
+- Documentation is up-to-date: generate it with `rake docs` and read it.
+- "*CHANGELOG.md*" lists the change if it has impact on users.
+- "*README.md*" is updated if the feature should be visible there, including the Kanban board.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT), see [LICENSE.txt](https://github.com/trinistr/object_forge/blob/main/LICENSE.txt).

data/lib/object_forge/crucible.rb

@@ -11,16 +11,34 @@ module ObjectForge
   #   but it's not a private API.
   #
   # @thread_safety Attribute resolution is idempotent,
-  #   but modifies instance variables, making it unsafe to share the Crucible
+  #   and using {.call} is thread-safe.
   # @since 0.1.0
   class Crucible < UnBasicObject
-    %i[rand].each { |m| private define_method(m, ::Object.instance_method(m)) }
+    class << self
+      # Resolve all attributes by calling their +Proc+s,
+      # using a new instance as evaluation context.
+      #
+      # @note This method destructively modifies initial attributes.
+      # @see #resolve!
+      # @thread_safety This method is thread-safe.
+      #
+      # @param attributes [Hash{Symbol => Proc, Any}] initial attributes
+      # @return [Hash{Symbol => Any}] resolved attributes
+      def call(attributes)
+        new(attributes).resolve!
+      end
+
+      alias resolve call
+    end
+
+    %i[rand].each { |m| private define_method(m, ::Kernel.instance_method(m)) }
 
     # @param attributes [Hash{Symbol => Proc, Any}] initial attributes
     def initialize(attributes)
       super()
       @attributes = attributes
       @resolved_attributes = ::Set.new
+      @resolving_attributes = []
     end
 
     # Resolve all attributes by calling their +Proc+s,
@@ -29,11 +47,13 @@ module ObjectForge
     # Attributes can freely refer to each other inside +Proc+s
     # through bareword names or +#[]+.
     # However, make sure to avoid cyclic dependencies:
-    # they aren't specially detected or handled, and will cause +SystemStackError+.
+    # they can't be resolved and will raise {CircularAttributeDependencyError}.
     #
     # @note This method destructively modifies initial attributes.
     #
     # @return [Hash{Symbol => Any}] resolved attributes
+    #
+    # @raise [CircularAttributeDependencyError] if a dependency cycle is detected
     def resolve!
       @attributes.each_key { |name| method_missing(name) }
       @attributes
@@ -52,27 +72,36 @@ module ObjectForge
     #     description: -> { name.downcase },
     #     duration: -> { rand(1000) }
     #   }
-    #   Crucible.new(attrs).resolve!
-    #   # => { name: "Name", description: "name", duration: 123 }
+    #   Crucible.call(attrs)
+    #     # => { name: "Name", description: "name", duration: 123 }
+    #
     # @example using conflicting and reserved names
     #   attrs = {
     #     "[]": -> { "Brackets" },
     #     "[]=": -> { "#{self[:[]]} are brackets" },
     #     "!": -> { "#{self[:[]=]}!" }
     #   }
-    #   Crucible.new(attrs).resolve!
-    #   # => { "[]": "Brackets", "[]=": "Brackets are brackets", "!": "Brackets are brackets!" }
+    #   Crucible.resolve(attrs)
+    #     # => { "[]": "Brackets", "[]=": "Brackets are brackets", "!": "Brackets are brackets!" }
     #
     # @param name [Symbol]
     # @return [Any]
-    def method_missing(name)
+    #
+    # @raise [CircularAttributeDependencyError] if a dependency cycle is detected
+    def method_missing(name) # rubocop:disable Metrics/MethodLength
       if @attributes.key?(name)
-        if @resolved_attributes.include?(name) || !(::Proc === @attributes[name])
-          @attributes[name]
-        else
-          @resolved_attributes << name
-          @attributes[name] = instance_exec(&@attributes[name])
+        if @resolving_attributes.include?(name)
+          raise_circular_dependency_error!(name)
+        elsif !@resolved_attributes.include?(name) && (::Proc === @attributes[name])
+          begin
+            @resolving_attributes << name
+            @attributes[name] = instance_exec(&@attributes[name])
+            @resolved_attributes << name
+          ensure
+            @resolving_attributes.pop
+          end
         end
+        @attributes[name]
       else
         super
       end
@@ -81,7 +110,14 @@ module ObjectForge
     alias [] method_missing
 
     def respond_to_missing?(name, _include_all)
-      @attributes.key?(name)
+      @attributes.key?(name) || super
+    end
+
+    def raise_circular_dependency_error!(name)
+      loop_start = @resolving_attributes.index(name)
+      loop = @resolving_attributes[loop_start..] # : Array[Symbol]
+      raise CircularAttributeDependencyError,
+            "attribute depends on itself: #{loop.join(" -> ")} -> #{name}"
     end
   end
 end