object_forge 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83440b5319d1e909379d16b67830ad1f67f575358473dd4ba5914cb549c417b9
-  data.tar.gz: 279a5756a157f96252081cb60ce0541bdffdf1e21a25fe72db19b622c7d717e8
+  metadata.gz: bd0b538c878ddc72f9041187f1612a1d779b55d7d7a4a72bb8be9c2c22d36073
+  data.tar.gz: 0cd2ec6ea0594f13f1780eb503220d5313489657d6aa31e771d075d1ceef4c9b
 SHA512:
-  metadata.gz: e16b3091daf563ffffbb5da39b50a6cc2298a288a1e71528ab9de905e0c959718555ff8d3b6b2a3478f094fa3ebff8727f0a95e97c6adef05d3c7abb1ae6676f
-  data.tar.gz: 04455c660052171b8a4456323b700f91805d0c05190329427baee1468b42ccfee3c315b79534f997b45a1f2cd716f85076e164f8007cad821f43047a5ea8fcbf
+  metadata.gz: 63431e04ef6c32990268ba7545564c964a72b72b23b9469315479d696c42a4106b24dd490a80481182f04b41e91cc78614f1de177f3516bb66d965c0f71b7df9
+  data.tar.gz: 1ed2a7e317671bb416bad5960d2bb227332ccf911d936835802470f785d98975223f3bf2070ebd7ca212b84932e773d1844bf64a718d857f8fc514c3cf2516e5

data/README.md

@@ -0,0 +1,293 @@
+# 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** provides a familiar way to build objects in any context with minimal assumptions about usage environment.
+- It is not connected to any framework and, indeed, has nothing to do with a database.
+- To use, just define some factories and call them wherever you need, be it in tests, console, or application code.
+- If you need, almost any part of the process can be easily replaced with a custom solution.
+
+## Table of contents
+
+- [Motivation (why *another* another factory gem?)](#motivation-why-another-another-factory-gem)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basics](#basics)
+  - [Separate forgeyards and forges](#separate-forgeyards-and-forges)
+  - [Molds: customized forging](#molds-customized-forging)
+  - [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 (why *another* another factory gem?)
+
+There are a bunch of gems that provide object generation functionality, chief among them [FactoryBot](https://github.com/thoughtbot/factory_bot) and [Fabrication](https://fabricationgem.org/).
+However, such gems make a lot of assumptions about why, how and what for they will be used, making them complicated and, at the same time, severely limited. Such assumptions commonly are:
+- assuming that every Ruby project is a Rails project;
+- assuming that "generating objects" equates "saving records to database";
+- assuming that objects are mutable and provide attribute writers;
+- assuming that streamlined object generation is only useful for testing;
+- (related to the previous point) assuming that there will never be a need to
+  have more than one configuration of a library in the same project;
+- assuming that adding global methods or objects is a good idea.
+
+I notice that there is also a problem of thinking that Rails's "convention-over-configuration" approach is always appropriate, but then making configuration convoluted, instead of making it easy for the user to do the things they want in the way they want in the first place.
+
+There are some projects that tried to address these issues, like [Progenitor](https://github.com/pavlos/progenitor) (the closest to **ObjectForge**) and [Workbench](https://github.com/leadtune/workbench), but they still didn't manage to go around the pitfalls.
+Most factory projects are also quite dead, having not been updated in *many* years.
+
+## Installation
+
+Install with `gem`:
+```sh
+gem install object_forge
+```
+
+Or, if using Bundler, add to your Gemfile:
+```ruby
+gem "object_forge"
+```
+
+## 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).
+
+### Basics
+
+In the simplest cases, **ObjectForge** can be used much like other factory libraries, with definitions living in a global object (`ObjectForge::DEFAULT_YARD`).
+
+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)
+  # => #<Point:0x00007f6109dcad40 @id="a", @x=0.17176955469852973, @y=0.3423901951181103>
+# Positional arguments define used traits:
+ObjectForge.build(:point, :z)
+  # => #<Point:0x00007f61099e7980 @id="Z_b", @x=0.0, @y=0.0>
+# Attributes can be overridden with keyword arguments:
+ObjectForge.forge(:point, x: 10)
+  # => #<Point:0x00007f6109aabf88 @id="c", @x=10, @y=-0.3458802496120402>
+# Traits and overrides are combined in the given order:
+ObjectForge.call(:point, :z, :invalid, id: "NaN")
+  # => #<Point:0x00007f6109b82e48 @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 })
+  # => #<Point:0x00007f6109932418 @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.
+
+### Separate 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(:point, 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(:point, :z, id: "0")
+  # => #<Point:0x00007f6109b719e0 @id="0", @x=0, @y=0>
+```
+
+Note how the forge isn't registered in the default forgeyard:
+```ruby
+ObjectForge.forge(:point)
+  # ArgumentError: unknown forge: point
+```
+
+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.(:z, id: "0")
+  # => #<Point:0x00007f6109b719e0 @id="0", @x=0, @y=0>
+```
+
+**Forge** has the same building interface as a **Forgeyard**, but it doesn't have the name argument:
+```ruby
+forge.build
+  # => #<Point:0x00007f610deae578 @id="a", @x=0.3317733939650964, @y=-0.1363936629550252>
+forge.forge(:z)
+  # => #<Point:0x00007f61099f6520 @id="b", @x=0, @y=0>
+forge.(radius: 500)
+  # => #<Point:0x00007f6109960048 @id="c", @x=-141, @y=109>
+```
+
+### Molds: customized forging
+
+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 *really* bad if **ObjectForge** placed 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 specified in forge definition:
+```ruby
+forge = ObjectForge::Forge.define(Point) do |f|
+  f.mold = ->(forged:, attributes:, **) do
+    puts "Pointing at #{attributes[:x]},#{attributes[:y]}"
+    forged.new(attributes[:id], attributes[:x], attributes[:y])
+  end
+  #... rest of the definition
+end
+```
+
+Now the specified **mold** will be called to build your objects:
+```ruby
+forge.forge
+  # Pointing at 0.3317733939650964,-0.1363936629550252
+  # => #<Point:0x00007f610deae578 @id="a", @x=0.3317733939650964, @y=-0.1363936629550252>
+```
+
+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 **Dry::Struct**, for 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 hashes to carry data;
+- `ObjectForge::Molds::StructMold` handles all possible cases of `keyword_init` for **Struct** subclasses.
+
+> [!TIP]
+> **HashMold** and **StructMold** will be used automatically, based on the forged class, if you don't specify any mold.
+
+
+I strongly recommend directly using mold instances and not classes. Doing this prevents memory churn which causes performance issues. Not only that, but having a stateful mold is a code smell and probably represents a significant design issue.
+
+### 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, you don't need to nest it inside another `factory` block.
+- There is no forge inheritance or nesting, though it may be added in the future.
+
+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.
+
+Attributes:
+- For now, transient attributes have no difference to regular ones, they just aren't set in the final object.
+- *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. (I feel that nesting is needlessly confusing.)
+- 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, unless you pass the same object yourself to multiple `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]
+  [⚗️ To do]
+    [Ability to replace resolver]
+    [After-build hook]
+  [❔Under consideration]
+    [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. 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

@@ -14,7 +14,7 @@ module ObjectForge
   #   but modifies instance variables, making it unsafe to share the Crucible
   # @since 0.1.0
   class Crucible < UnBasicObject
-    %i[rand].each { |m| private define_method(m, ::Object.instance_method(m)) }
+    %i[rand].each { |m| private define_method(m, ::Kernel.instance_method(m)) }
 
     # @param attributes [Hash{Symbol => Proc, Any}] initial attributes
     def initialize(attributes)

data/lib/object_forge/forge.rb

@@ -21,14 +21,13 @@ module ObjectForge
     #   Attributes belonging to traits.
     #   @return [Hash{Symbol => Hash{Symbol => Any}}]
     #
-    # @!attribute [r] mold
-    #   An object that knows how to build the instance.
-    #   Must have a +call+ method that takes a class and a hash of attributes.
-    #   @since 0.2.0
-    #   @return [#call, nil]
-    Parameters = Struct.new(:attributes, :traits, :mold, keyword_init: true)
-
-    MOLD_MOLD = Molds::MoldMold.new.freeze
+    # @!attribute [r] settings
+    #   A forge's settings.
+    #   Must include a +:mold+ key, containing an object that knows how to build the instance
+    #   with a +call+ method that takes a class and a hash of attributes.
+    #   @since 0.3.0
+    #   @return [Hash{Symbol => Any}]
+    Parameters = Struct.new(:attributes, :traits, :settings, keyword_init: true)
 
     # Define (and create) a forge using DSL.
     #
@@ -55,12 +54,13 @@ module ObjectForge
 
     # @param forged [Class, Any] class or object to forge
     # @param parameters [Parameters, ForgeDSL] forge parameters
-    # @param name [Symbol, nil] forge name
+    # @param name [Symbol, nil] forge name;
+    #   only used for identification purposes
     def initialize(forged, parameters, name: nil)
       @name = name
       @forged = forged
       @parameters = parameters
-      @mold = parameters.mold || MOLD_MOLD.call(forged: forged)
+      @mold = determine_mold(forged, parameters.settings[:mold])
     end
 
     # Forge a new instance.
@@ -92,10 +92,32 @@ module ObjectForge
     end
 
     alias build forge
-    alias [] forge
+    alias call forge
 
     private
 
+    # Get appropriate mold based on parameters.
+    #
+    # If +mold+ is already set, it will be used directly, or,
+    # if it is Class, it will be wrapped in {Molds::WrappedMold} if posssible.
+    # If +nil+, a mold will be selected based on +forged+ class.
+    #
+    # @param forged [Class, Any]
+    # @param mold [#call, Class, nil]
+    # @return [#call]
+    #
+    # @raise [MoldError]
+    #
+    # @since 0.3.0
+    def determine_mold(forged, mold)
+      Molds.wrap_mold(mold) || Molds.mold_for(forged)
+    end
+
+    # Resolve attributes using default attributes, specified traits and overrides.
+    #
+    # @param traits [Array<Symbol>]
+    # @param overrides [Hash{Symbol => Any}]
+    # @return [Hash{Symbol => Any}]
     def resolve_attributes(traits, overrides)
       attributes = @parameters.attributes.merge(*@parameters.traits.values_at(*traits), overrides)
       Crucible.new(attributes).resolve!

data/lib/object_forge/forge_dsl.rb

@@ -27,8 +27,8 @@ module ObjectForge
     # @return [Hash{Symbol => Hash{Symbol => Proc}}] trait definitions
     attr_reader :traits
 
-    # @return [#call, nil] forge mold
-    attr_reader :mold
+    # @return [Hash{Symbol => Any}] settings for forge, such as mold
+    attr_reader :settings
 
     # Define forge's parameters through DSL.
     #
@@ -39,6 +39,7 @@ module ObjectForge
     #
     # @example with block parameter
     #   ForgeDSL.new do |f|
+    #     f.mold = ObjectForge::Molds::KeywordsMolds.new
     #     f.attribute(:name) { "Name" }
     #     f[:description] { name.upcase }
     #     f.duration { rand(1000) }
@@ -46,6 +47,7 @@ module ObjectForge
     #
     # @example without block parameter
     #   ForgeDSL.new do
+    #     self.mold = ::ObjectForge::Molds::KeywordsMolds.new
     #     attribute(:name) { "Name" }
     #     self[:description] { name.upcase }
     #     duration { rand(1000) }
@@ -58,49 +60,53 @@ module ObjectForge
       @attributes = {}
       @sequences = {}
       @traits = {}
+      @settings = {}
 
       dsl.arity.zero? ? instance_exec(&dsl) : yield(self)
 
       freeze
     end
 
-    # Freezes the instance, including +attributes+, +sequences+ and +traits+.
+    # Freezes the instance, including +settings+, +attributes+, +sequences+ and +traits+.
     # Prevents further responses through +#method_missing+.
     #
     # @note Called automatically in {#initialize}.
     #
     # @return [self]
     def freeze
-      ::Object.instance_method(:freeze).bind_call(self)
+      ::Kernel.instance_method(:freeze).bind_call(self)
       @attributes.freeze
       @sequences.freeze
       @traits.freeze
-      @mold.freeze
+      @settings.freeze
       self
     end
 
-    # Set the forge mold.
+    # Set a value for a forge's setting.
     #
-    # Mold is an object that knows how to take a hash of attributes
-    # and create an object from them.
-    # It can also be a class with +#call+, in which case a new mold will be instantiated
-    # automatically for each build. If a single instance is enough,
-    # please call +.new+ yourself once.
+    # Possible settings depend on used forge, but for default {Forge} a +mold+ is expected.
     #
-    # @since 0.2.0
+    # It is also possible to set settings through +method_missing+, using name with a +=+ suffix.
     #
-    # @param mold [Class, #call, nil]
-    # @return [Class, #call, nil]
+    # @see Molds
     #
-    # @raise [DSLError] if +mold+ does not respond to or implement +#call+
-    def mold=(mold)
-      if nil == mold || mold.respond_to?(:call) # rubocop:disable Style/YodaCondition
-        @mold = mold
-      elsif ::Class === mold && mold.public_method_defined?(:call)
-        @mold = Molds::WrappedMold.new(mold)
-      else
-        raise DSLError, "mold must respond to or implement #call"
+    # @example
+    #   f.setting(:mold, ->(forged:, attributes:, **) { forge.new(**attributes) })
+    #   f.mold = ObjectForge::Molds::SingleArgumentMold.new
+    #
+    # @param name [Sumbol] setting name
+    # @param value [Any] value for the setting
+    # @return [Symbol] setting name
+    #
+    # @raise [ArgumentError] if +name+ is not a Symbol
+    def setting(name, value)
+      unless ::Symbol === name
+        raise ::ArgumentError, "setting name must be a Symbol, #{name.class} given"
       end
+
+      @settings[name] = value
+
+      name
     end
 
     # Define an attribute, possibly transient.
@@ -255,26 +261,30 @@ module ObjectForge
 
     private
 
-    # Define an attribute using a shorthand.
+    # Define an attribute (like +name+) or set a setting (like +name=+) using a shorthand.
     #
-    # Can not be used to define attributes with reserved names.
+    # Can not be used with reserved names.
     # Trying to use a conflicting name will lead to usual issues
     # with calling random methods.
-    # When in doubt, use {#attribute} or {#[]} instead.
+    # When in doubt, use {#attribute} or {#setting} instead.
     #
     # Reserved names are:
-    # - all names ending in +?+, +!+ or +=+
+    # - all names ending in +?+, +!+
     # - all names starting with a non-word ASCII character
     #   (operators, +`+, +[]+, +[]=+)
     # - +rand+
     #
-    # @param name [Symbol] attribute name
+    # @param name [Symbol] attribute or setting name
+    # @param value [Any] value for setting
     # @yieldreturn [Any] attribute value
-    # @return [Symbol] attribute name
+    # @return [Symbol] attribute or setting name
     #
     # @raise [DSLError] if a reserved +name+ is used
-    def method_missing(name, **nil, &)
-      return super if frozen?
+    def method_missing(name, value = nil, **nil, &)
+      return super(name) if frozen?
+      if valid_setting_method?(name)
+        return setting(name[...-1].to_sym, value) # steep:ignore NoMethod
+      end
       return attribute(name, &) if respond_to_missing?(name, false)
 
       raise DSLError, "#{name.inspect} is a reserved name (in #{name.inspect})"
@@ -283,7 +293,11 @@ module ObjectForge
     def respond_to_missing?(name, _include_all)
       return false if frozen?
 
-      !name.end_with?("?", "!", "=") && !name.match?(/\A(?=\p{ASCII})\P{Word}/) && name != :rand
+      !name.end_with?("?", "!") && !name.match?(/\A(?=\p{ASCII})\P{Word}/) && name != :rand
+    end
+
+    def valid_setting_method?(name)
+      name.match?(/\A\p{Word}.*=\z/)
     end
   end
 end

data/lib/object_forge/forgeyard.rb

@@ -45,6 +45,16 @@ module ObjectForge
       @forges.put_if_absent(name, forge) || forge
     end
 
+    # Retrieve a forge by name.
+    #
+    # @param name [Symbol] name of the forge
+    # @return [Forge] registered forge
+    #
+    # @raise [KeyError] if forge with the specified name is not registered
+    def [](name)
+      @forges.fetch(name)
+    end
+
     # Build an instance using a forge.
     #
     # @see Forge#forge
@@ -58,10 +68,10 @@ module ObjectForge
     #
     # @raise [KeyError] if forge with the specified name is not registered
     def forge(name, ...)
-      @forges.fetch(name).[](...)
+      @forges.fetch(name).call(...)
     end
 
     alias build forge
-    alias [] forge
+    alias call forge
   end
 end

data/lib/object_forge/molds/keywords_mold.rb

@@ -4,7 +4,8 @@ module ObjectForge
   module Molds
     # Basic mold which calls +forged.new(**attributes)+.
     #
-    # Can be used instead of {SingleArgumentMold},
+    # Can be used instead of {SingleArgumentMold}
+    # due to how keyword arguments are treated in Ruby,
     # but performance is about 1.5 times worse.
     #
     # @thread_safety Thread-safe.

data/lib/object_forge/molds/struct_mold.rb

@@ -12,6 +12,8 @@ module ObjectForge
       # Does Struct automatically use keyword initialization
       # when +keyword_init+ is not specified / +nil+?
       #
+      # This should be true on Ruby 3.2.0 and later.
+      #
       # @return [Boolean]
       RUBY_FEATURE_AUTO_KEYWORDS = (::Struct.new(:a, :b).new(a: 1, b: 2).a == 1)
 

data/lib/object_forge/molds/wrapped_mold.rb

@@ -7,6 +7,8 @@ module ObjectForge
     # Wrapping a mold class is useful when its +#call+ is stateful,
     # making it unsafe to use multiple times or in shared environments.
     #
+    # This mold is usually automatically used through {Molds.wrap_mold}.
+    #
     # @thread_safety Thread-safe if {wrapped_mold} does not use global state.
     # @since 0.2.0
     class WrappedMold

data/lib/object_forge/molds.rb

@@ -3,14 +3,16 @@
 module ObjectForge
   # This module provides a collection of predefined molds to be used in common cases.
   #
-  # Molds are +#call+able objects responsible for actually building objects produced by factories
+  # Mold is an object that knows how to take a hash of attributes
+  # and create an object from them. Molds are +#call+able objects
+  # responsible for actually building objects produced by factories
   # (or doing other, interesting things with them (truly, only the code review is the limit!)).
   # They are supposed to be immutable, shareable, and persistent:
   # initialize once, use for the whole runtime.
   #
   # A simple mold can easily be just a +Proc+.
   # All molds must have the following +#call+ signature: +call(forged:, attributes:, **)+.
-  # The extra keywords are for future extensions.
+  # The extra keywords are ignored for possibility of future extensions.
   #
   # @example A very basic FactoryBot replacement
   #   creator = ->(forged:, attributes:, **) do
@@ -59,5 +61,59 @@ module ObjectForge
   # @since 0.2.0
   module Molds
     Dir["#{__dir__}/molds/*.rb"].each { require_relative _1 }
+
+    # Get maybe appropriate mold for the given +forged+ class or object.
+    #
+    # Currently provides specific recognition for:
+    # - subclasses of +Struct+ ({StructMold}),
+    # - subclasses of +Data+ ({KeywordsMold}),
+    # - +Hash+ and subclasses ({HashMold}).
+    # Other objects just get {SingleArgumentMold}.
+    #
+    # @param forged [Class, Any]
+    # @return [#call] an instance of a mold
+    #
+    # @thread_safety Thread-safe.
+    # @since 0.3.0
+    def self.mold_for(forged)
+      if ::Class === forged
+        if forged < ::Struct
+          StructMold.new
+        elsif defined?(::Data) && forged < ::Data
+          KeywordsMold.new
+        elsif forged <= ::Hash
+          HashMold.new
+        else
+          SingleArgumentMold.new
+        end
+      else
+        SingleArgumentMold.new
+      end
+    end
+
+    # Wrap mold if needed.
+    #
+    # If +mold+ is +nil+ or a +call+able object, returns it.
+    # If it is a Class with +#call+, wraps it in {WrappedMold}.
+    # Otherwise, raises an error.
+    #
+    # @since 0.3.0
+    #
+    # @param mold [Class, #call, nil]
+    # @return [#call, nil]
+    #
+    # @raise [DSLError] if +mold+ does not respond to or implement +#call+
+    #
+    # @thread_safety Thread-safe.
+    # @since 0.3.0
+    def self.wrap_mold(mold)
+      if mold.nil? || mold.respond_to?(:call)
+        mold # : ObjectForge::mold?
+      elsif ::Class === mold && mold.public_method_defined?(:call)
+        WrappedMold.new(mold)
+      else
+        raise MoldError, "mold must respond to or implement #call"
+      end
+    end
   end
 end

data/lib/object_forge/un_basic_object.rb

@@ -34,13 +34,14 @@ module ObjectForge
     # @!method to_s
     #   @see Object#to_s
     #   @return [String]
-    %i[class eql? freeze frozen? hash inspect is_a? respond_to? to_s].each do |m|
-      define_method(m, ::Object.instance_method(m))
+    %i[class eql? freeze frozen? hash inspect is_a? kind_of? respond_to? to_s].each do |m|
+      define_method(m, ::Kernel.instance_method(m))
     end
-    alias kind_of? is_a?
     # @!endgroup
 
-    %i[block_given? raise].each { |m| private define_method(m, ::Object.instance_method(m)) }
+    %i[block_given? raise respond_to_missing?].each do |m|
+      private define_method(m, ::Kernel.instance_method(m))
+    end
 
     # @!macro pp_support
     #   Support for +pp+ (and IRB).

data/lib/object_forge/version.rb

@@ -2,5 +2,5 @@
 
 module ObjectForge
   # Current version
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/object_forge.rb

@@ -22,6 +22,7 @@ require_relative "object_forge/version"
 #   It allows defining arbitrary attributes (possibly using sequences),
 #   with support for traits (collections of attributes with non-default values).
 # - {Crucible} is used to resolve attributes.
+# - {Molds} are objects used to instantiate objects in {Forge}.
 #
 # @example Quick example
 #   Frobinator = Struct.new(:frob, :inator, keyword_init: true)
@@ -38,7 +39,7 @@ require_relative "object_forge/version"
 #   # => #<struct Frobinator frob="Frobinator", inator=#<Proc:...>>
 #   ObjectForge.build(:frobber, frob: -> { "Frob" + inator }, inator: "orn")
 #   # => #<struct Frobinator frob="Froborn", inator="orn">
-#   ObjectForge[:frobber, :static, inator: "Value"]
+#   ObjectForge.call(:frobber, :static, inator: "Value")
 #   # => #<struct Frobinator frob="Static", inator="Value">
 module ObjectForge
   # Base error class for ObjectForge.
@@ -47,6 +48,9 @@ module ObjectForge
   # Error raised when a mistake is made in using DSL.
   # @since 0.1.0
   class DSLError < Error; end
+  # Error raised when object can not be used as a mold.
+  # @since 0.3.0
+  class MoldError < Error; end
 
   # Default {Forgeyard} that is used by {.define} and {.forge}.
   #
@@ -104,9 +108,7 @@ module ObjectForge
   end
 
   class << self
-    # @since 0.1.0
     alias build forge
-    # @since 0.1.0
-    alias [] forge
+    alias call forge
   end
 end

data/sig/object_forge/molds.rbs

@@ -1,14 +1,9 @@
 module ObjectForge
-  interface _Mold
-    def call
-      : (forged: untyped, attributes: Hash[Symbol, untyped], **untyped) -> untyped
-  end
-
   module Molds
-    class MoldMold
-      def call
-        : (forged: untyped, **untyped) -> ObjectForge::_Mold
-    end
+    def self.wrap_mold
+      : ((ObjectForge::mold | Class | nil) mold) -> ObjectForge::mold?
+    def self.mold_for
+      : (ObjectForge::_Forgable forged) -> ObjectForge::mold
 
     class SingleArgumentMold
       include ObjectForge::_Mold

data/sig/object_forge.rbs

@@ -1,5 +1,5 @@
 module ObjectForge
-  type mold = ObjectForge::_RespondTo & ObjectForge::_Mold
+  type mold = Object & ObjectForge::_Mold
   type sequenceable = ObjectForge::_RespondTo & ObjectForge::_Sequenceable
 
   interface _RespondTo
@@ -15,13 +15,19 @@ module ObjectForge
   interface _ForgeParameters
     def attributes: () -> Hash[Symbol, untyped]
     def traits: () -> Hash[Symbol, Hash[Symbol, untyped]]
-    def mold: () -> ObjectForge::mold?
+    def settings: () -> Hash[Symbol, untyped]
+  end
+  interface _Mold
+    def call
+      : (forged: untyped, attributes: Hash[Symbol, untyped], **untyped) -> untyped
   end
 
   class Error < StandardError
   end
   class DSLError < Error
   end
+  class MoldError < Error
+  end
 
   VERSION: String
   DEFAULT_YARD: ObjectForge::Forgeyard
@@ -35,6 +41,10 @@ module ObjectForge
 
   def self.forge
     : (Symbol name, *Symbol traits, **untyped overrides) ?{ (untyped) -> void } -> ObjectForge::_Forgable
+  def self.build
+    : (Symbol name, *Symbol traits, **untyped overrides) ?{ (untyped) -> void } -> ObjectForge::_Forgable
+  def self.call
+    : (Symbol name, *Symbol traits, **untyped overrides) ?{ (untyped) -> void } -> ObjectForge::_Forgable
 end
 
 class ObjectForge::Sequence
@@ -63,11 +73,14 @@ class ObjectForge::Forgeyard
 
   def register
     : (Symbol name, ObjectForge::Forge forge) -> ObjectForge::Forge
+  
+  def []
+    : (Symbol name) -> ObjectForge::Forge
 
   def forge
     : (Symbol name, *Symbol traits, **untyped overrides) ?{ (untyped) -> void } -> ObjectForge::_Forgable
   alias build forge
-  alias [] forge
+  alias call forge
 end
 
 class ObjectForge::Forge
@@ -78,8 +91,6 @@ class ObjectForge::Forge
       : (attributes: Hash[Symbol, untyped], traits: Hash[Symbol, Hash[Symbol, untyped]]) -> void
   end
 
-  MOLD_MOLD: ObjectForge::Molds::MoldMold
-
   attr_reader forged: ObjectForge::_Forgable
   attr_reader name: Symbol
 
@@ -93,10 +104,13 @@ class ObjectForge::Forge
   def forge
     : (*Symbol traits, **untyped overrides) ?{ (untyped) -> void } -> ObjectForge::_Forgable
   alias build forge
-  alias [] forge
+  alias call forge
 
   private
 
+  def determine_mold
+    : (ObjectForge::_Forgable forged, ObjectForge::mold mold) -> ObjectForge::mold
+
   def resolve_attributes
     : (Array[Symbol] traits, Hash[Symbol, untyped] overrides) -> Hash[Symbol, untyped]
 end
@@ -109,6 +123,7 @@ class ObjectForge::ForgeDSL < ObjectForge::UnBasicObject
   @attributes: Hash[Symbol, Proc]
   @sequences: Hash[Symbol, ObjectForge::Sequence]
   @traits: Hash[Symbol, Hash[Symbol, Proc]]
+  @settings: Hash[Symbol, untyped]
 
   def initialize
     : () { (ObjectForge::ForgeDSL) -> void } -> void
@@ -116,8 +131,8 @@ class ObjectForge::ForgeDSL < ObjectForge::UnBasicObject
 
   def freeze: -> self
 
-  def mold=
-    : (ObjectForge::mold) -> void
+  def setting
+    : (Symbol name, untyped value) -> Symbol
 
   def attribute
     : (Symbol name) { [self: ObjectForge::Crucible] -> untyped } -> Symbol
@@ -140,8 +155,9 @@ class ObjectForge::ForgeDSL < ObjectForge::UnBasicObject
 
   def respond_to_missing?
     : (Symbol name, bool include_all) -> bool
-
-  def rand: [T] (?(Float | Integer | Range[T])) -> (Float | Integer | T)
+  
+  def valid_setting_method?
+    : (Symbol name) -> bool
 end
 
 class ObjectForge::Crucible < ObjectForge::UnBasicObject
@@ -178,8 +194,9 @@ class ObjectForge::UnBasicObject < BasicObject
   def inspect: -> String
 
   def is_a?: (Module klass) -> bool
+  def kind_of?: (Module klass) -> bool
 
-  def respond_to?: (Symbol name, ?bool include_private) -> bool
+  def respond_to?: (Symbol name, ?bool include_all) -> bool
 
   def to_s: -> String
 
@@ -192,4 +209,6 @@ class ObjectForge::UnBasicObject < BasicObject
   def block_given?: -> bool
 
   def raise: (_Exception exception, ?String message, ?Array[String] backtrace, ?cause: _Exception) -> void
+
+  def respond_to_missing?: (Symbol name, bool include_all) -> bool
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: object_forge
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
-- Alexandr Bulancov
-autorequire:
+- Alexander Bulancov
 bindir: exe
 cert_chain: []
-date: 2025-08-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -31,11 +30,12 @@ description: |
   To use, just define some factories and call them wherever you need,
   be it in tests, console, or application code.
   If needed, almost any part of the process can be easily replaced with a custom solution.
-email:
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
+- README.md
 - lib/object_forge.rb
 - lib/object_forge/crucible.rb
 - lib/object_forge/forge.rb
@@ -44,7 +44,6 @@ files:
 - lib/object_forge/molds.rb
 - lib/object_forge/molds/hash_mold.rb
 - lib/object_forge/molds/keywords_mold.rb
-- lib/object_forge/molds/mold_mold.rb
 - lib/object_forge/molds/single_argument_mold.rb
 - lib/object_forge/molds/struct_mold.rb
 - lib/object_forge/molds/wrapped_mold.rb
@@ -59,14 +58,15 @@ licenses:
 metadata:
   homepage_uri: https://github.com/trinistr/object_forge
   bug_tracker_uri: https://github.com/trinistr/object_forge/issues
-  documentation_uri: https://rubydoc.info/gems/object_forge/0.2.0
-  source_code_uri: https://github.com/trinistr/object_forge/tree/v0.2.0
-  changelog_uri: https://github.com/trinistr/object_forge/blob/v0.2.0/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/object_forge/0.3.0
+  source_code_uri: https://github.com/trinistr/object_forge/tree/v0.3.0
+  changelog_uri: https://github.com/trinistr/object_forge/blob/v0.3.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options:
 - "--tag"
 - thread_safety:Thread safety
+- "--main"
+- README.md
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -80,8 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A simple factory for objects with minimal assumptions.
 test_files: []

data/lib/object_forge/molds/mold_mold.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-module ObjectForge
-  module Molds
-    # Special "mold" that returns appropriate mold for the given forged object.
-    # Probably not the best fit though.
-    #
-    # Currently provides specific recognition for:
-    # - subclasses of +Struct+ ({StructMold}),
-    # - subclasses of +Data+ ({KeywordsMold}),
-    # - +Hash+ and subclasses ({HashMold}).
-    # Other objects just get {SingleArgumentMold}.
-    #
-    # @thread_safety Thread-safe.
-    # @since 0.2.0
-    class MoldMold
-      # Get maybe appropriate mold for the given forged object.
-      #
-      # @param forged [Class, Any]
-      # @return [#call] an instance of a mold
-      def call(forged:, **_)
-        # rubocop:disable Style/YodaCondition
-        if ::Class === forged
-          if ::Struct > forged
-            StructMold.new
-          elsif defined?(::Data) && ::Data > forged
-            KeywordsMold.new
-          elsif ::Hash >= forged
-            HashMold.new
-          else
-            SingleArgumentMold.new
-          end
-        else
-          SingleArgumentMold.new
-        end
-        # rubocop:enable Style/YodaCondition
-      end
-    end
-  end
-end