object_forge 0.3.0 → 0.4.1

data/lib/object_forge/molds.rb

@@ -4,42 +4,47 @@ module ObjectForge
   # This module provides a collection of predefined molds to be used in common cases.
   #
   # Mold is an object that knows how to take a hash of attributes
-  # and create an object from them. Molds are +#call+able objects
+  # 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:, **)+.
+  # All molds must have the following +#call+ signature: +call(forge_target:, attributes:, **)+.
   # The extra keywords are ignored for possibility of future extensions.
   #
   # @example A very basic FactoryBot replacement
-  #   creator = ->(forged:, attributes:, **) do
-  #     instance = forged.new
+  #   creator = ->(forge_target:, attributes:, **) do
+  #     instance = forge_target.new
   #     attributes.each_pair { instance.public_send(:"#{_1}=", _2) }
   #     instance.save!
   #   end
-  #   creator.call(forged: User, attributes: { name: "John", age: 30 })
+  #
+  #   creator.call(forge_target: User, attributes: { name: "John", age: 30 })
   #     # => <User name="John" age=30>
+  #
   # @example Using a mold to serialize collection of objects (contrivedly)
-  #   dumpy = ->(forged:, attributes:, **) do
+  #   dumpy = ->(forge_target:, attributes:, **) do
   #     Enumerator.new(attributes.size) do |y|
-  #       attributes.each_pair { y << forged.dump(_1 => _2) }
+  #       attributes.each_pair { y << forge_target.dump(_1 => _2) }
   #     end
   #   end
-  #   dumpy.call(forged: JSON, attributes: {a:1, b:2}).to_a
+  #
+  #   dumpy.call(forge_target: JSON, attributes: {a:1, b:2}).to_a
   #     # => ["{\"a\":1}", "{\"b\":2}"]
-  #   dumpy.call(forged: YAML, attributes: {a:1, b:2}).to_a
+  #   dumpy.call(forge_target: YAML, attributes: {a:1, b:2}).to_a
   #     # => ["---\n:a: 1\n", "---\n:b: 2\n"]
+  #
   # @example Abstract factory pattern (kind of)
   #   class FurnitureFactory
-  #     def call(forged:, attributes:, **)
-  #       concrete_factory = concrete_factory(forged)
+  #     def call(forge_target:, attributes:, **)
+  #       concrete_factory = concrete_factory(forge_target)
   #       attributes[:pieces].map do |piece|
   #         concrete_factory.public_send(piece, attributes.dig(:color, piece))
   #       end
   #     end
+  #
   #     private def concrete_factory(style)
   #       case style
   #       when :hitech
@@ -49,20 +54,70 @@ module ObjectForge
   #       end
   #     end
   #   end
-  #   FurnitureFactory.new.call(forged: :hitech, attributes: {
+  #
+  #   FurnitureFactory.new.call(forge_target: :hitech, attributes: {
   #     pieces: [:chair, :table], color: { chair: :black, table: :white }
   #   })
   #     # => [<#HiTech::Chair color=:black>, <#HiTech::Table color=:white>]
+  #
   # @example Abusing molds
-  #   printer = ->(forged:, attributes:, **) { PP.pp(attributes, forged) }
-  #   printer.call(forged: $stderr, attributes: {a:1, b:2})
+  #   printer = ->(forge_target:, attributes:, **) { PP.pp(attributes, forge_target) }
+  #   printer.call(forge_target: $stderr, attributes: {a:1, b:2})
   #     # outputs "{:a=>1, :b=>2}" to $stderr
   #
+  # @example Abuse above is just not enough, we need something even better
+  #   class Character
+  #     attr_reader :hp
+  #
+  #     def initialize(hp)
+  #       @hp = hp
+  #       @damage_factory = ObjectForge::Forge.new(self, DamageParameters.new)
+  #     end
+  #
+  #     def hit(damage)
+  #       if damage <= 0
+  #         @damage_factory.call(:shielded, apply: ->(damage) { @hp -= damage })
+  #       else
+  #         @damage_factory.call(amount: damage, apply: ->(damage) { @hp -= damage })
+  #       end
+  #     end
+  #
+  #     def heal(amount)
+  #       @damage_factory.call(amount: amount, apply: ->(amount) { @hp += amount }) if amount >= 0
+  #     end
+  #
+  #     def die!
+  #       puts "Character died!"
+  #     end
+  #   end
+  #
+  #   class DamageParameters
+  #     def attributes = {}
+  #     def traits = { shielded: { amount: 1 } }
+  #     def options
+  #       {
+  #         crucible: lambda(&:itself),
+  #         mold: ->(forge_target:, attributes:, **) {
+  #           attributes[:apply].call(attributes[:amount])
+  #           forge_target
+  #         },
+  #         after_build: ->(forge_target) { forge_target.die! if forge_target.hp <= 0 }
+  #       }
+  #     end
+  #   end
+  #
+  #   mc = Character.new(100)
+  #   mc.hit(50)
+  #   mc.heal(25)
+  #   mc.hit(-10)
+  #   mc.hit(75)
+  #     # outputs "Character died!"
+  #
   # @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.
+    # Get maybe appropriate mold for the given forge target.
     #
     # Currently provides specific recognition for:
     # - subclasses of +Struct+ ({StructMold}),
@@ -70,18 +125,18 @@ module ObjectForge
     # - +Hash+ and subclasses ({HashMold}).
     # Other objects just get {SingleArgumentMold}.
     #
-    # @param forged [Class, Any]
+    # @param forge_target [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
+    def self.mold_for(forge_target)
+      if ::Class === forge_target
+        if forge_target < ::Struct
           StructMold.new
-        elsif defined?(::Data) && forged < ::Data
+        elsif defined?(::Data) && forge_target < ::Data
           KeywordsMold.new
-        elsif forged <= ::Hash
+        elsif forge_target <= ::Hash
           HashMold.new
         else
           SingleArgumentMold.new
@@ -97,12 +152,10 @@ module ObjectForge
     # 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+
+    # @raise [ObjectInterfaceError] if +mold+ does not respond to or implement +#call+
     #
     # @thread_safety Thread-safe.
     # @since 0.3.0
@@ -112,7 +165,7 @@ module ObjectForge
       elsif ::Class === mold && mold.public_method_defined?(:call)
         WrappedMold.new(mold)
       else
-        raise MoldError, "mold must respond to or implement #call"
+        raise ObjectInterfaceError, "mold must respond to or implement #call"
       end
     end
   end

data/lib/object_forge/sequence.rb

@@ -25,10 +25,10 @@ module ObjectForge
     #
     # @param initial [#succ] initial value for the sequence
     #
-    # @raise [ArgumentError] if +initial+ does not respond to #succ
+    # @raise [ObjectInterfaceError] if +initial+ does not respond to #succ
     def initialize(initial)
       unless initial.respond_to?(:succ)
-        raise ArgumentError, "initial value must respond to #succ, #{initial.class} given"
+        raise ObjectInterfaceError, "initial value must respond to #succ"
       end
 
       @initial = initial

data/lib/object_forge/version.rb

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

data/lib/object_forge.rb

@@ -4,53 +4,113 @@ require_relative "object_forge/forgeyard"
 require_relative "object_forge/sequence"
 require_relative "object_forge/version"
 
-# A simple all-purpose factory library with minimal assumptions.
+# A small factory library for Ruby objects with minimal assumptions about framework, persistence,
+# or runtime environment.
 #
 # These are the main classes you should be aware of:
+# - {Forge} is a factory for objects.
+#   Usually created through {Forgeyard#define} or {Forge.define}
+#   using a DSL similar to FactoryBot, Forges can be used standalone,
+#   or as a part of a Forgeyard.
 # - {Forgeyard} is a registry of named related Forges.
 #   A Forgeyard allows to {Forgeyard#define} a Forge,
 #   and {Forgeyard#forge} a new object using a defined Forge.
-# - {Forge} is a factory for objects.
-#   Usually created through {Forgeyard#define}/{Forge.define} in a manner similar to FactoryBot,
-#   Forges can be used standalone, or as a part of a Forgeyard.
-# - {Sequence} is a representation of a sequence of values.
-#   They are usually used implicitly through {ForgeDSL#sequence},
-#   but can be created explicitly to be shared (or used outside of ObjectForge).
+# - {Molds} are object constructors used by {Forge}s.
+#   Several common molds are shipped with ObjectForge, but you
+#   will probably find it useful to create your own.
 #
-# Additionally, successful use may depend on understanding these:
+# Successful use may also depend on understanding these:
 # - {ForgeDSL} is a block-based DSL inspired by FactoryBot and ROM::Factory.
 #   It allows defining arbitrary attributes (possibly using sequences),
 #   with support for traits (collections of attributes with non-default values).
+# - {Sequence} is a representation of a sequence of values.
+#   They are usually used implicitly through {ForgeDSL#sequence},
+#   but can be created explicitly to be shared (or used outside of ObjectForge).
 # - {Crucible} is used to resolve attributes.
-# - {Molds} are objects used to instantiate objects in {Forge}.
+#
+# *ObjectForge* itself provides a top-level convenience API for working with a singular
+# {DEFAULT_YARD} when you expect to never need more than one Forgeyard, such as in test suites.
 #
 # @example Quick example
 #   Frobinator = Struct.new(:frob, :inator, keyword_init: true)
-#   # Forge's name and forged class are completely independent.
+#
+#   # Forge's name and target class are completely independent.
 #   ObjectForge.define(:frobber, Frobinator) do |f|
 #     f.frob { "Frob" + inator.call }
 #     f.inator { -> { "inator" } }
+#
 #     f.trait :static do |tf|
 #       tf.frob { "Static" }
 #     end
 #   end
+#
 #   # These methods are aliases:
 #   ObjectForge.forge(:frobber)
-#   # => #<struct Frobinator frob="Frobinator", inator=#<Proc:...>>
+#     # => #<struct Frobinator frob="Frobinator", inator=#<Proc:...>>
 #   ObjectForge.build(:frobber, frob: -> { "Frob" + inator }, inator: "orn")
-#   # => #<struct Frobinator frob="Froborn", inator="orn">
+#     # => #<struct Frobinator frob="Froborn", inator="orn">
 #   ObjectForge.call(:frobber, :static, inator: "Value")
-#   # => #<struct Frobinator frob="Static", inator="Value">
+#     # => #<struct Frobinator frob="Static", inator="Value">
+#
+# @example A more involved example
+#   require "logger"
+#
+#   # A custom mold is needed for Logger because it has positional and keyword parameters.
+#   logger_mold = ->(forge_target:, attributes:, **) {
+#     forge_target.new(
+#       attributes[:file],
+#       *attributes[:rotation],
+#       **attributes.slice(:level, :progname, :formatter)
+#     )
+#   }
+#
+#   # This is a one-off, universal factory, so using a Forgeyard is not needed.
+#   $logger_factory = ObjectForge::Forge.define(Logger) do |f|
+#     f.mold = logger_mold
+#     # Default crucible is almost always good enough, but let's use a simpler and faster resolver.
+#     f.crucible = ->(attributes) { attributes.transform_values { _1.is_a?(Proc) ? _1.call : _1 } }
+#
+#     f.file { $stderr }
+#
+#     f.trait :stdout do |tf|
+#       tf.file { $stdout }
+#     end
+#
+#     f.trait :logfiles do |tf|
+#       require "date"
+#       tf.file { "log-#{Date.today}.log" }
+#       tf.rotation { "daily" }
+#     end
+#   end
+#
+#   class MyClass
+#     def initialize
+#       @logger = $logger_factory.build(:stdout, progname: self.class)
+#     end
+#
+#     def call
+#       @logger.info("called!")
+#     end
+#   end
+#
+#   MyClass.new.call
+#     # outputs "I, [2026-05-25T13:56:33.533669 #206330]  INFO -- MyClass: called!" to $stdout
 module ObjectForge
-  # Base error class for ObjectForge.
+  # Base domain error class for ObjectForge.
   # @since 0.1.0
   class Error < StandardError; end
   # 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
+  # Error raised when attribute resolution surfaces a circular dependency.
+  # @since 0.4.0
+  class CircularAttributeDependencyError < Error; end
+
+  # Error raised when object does not conform to expected interface,
+  # most commonly lacking +#call+.
+  # @note This class inherits from +TypeError+, not {Error}.
+  # @since 0.4.0
+  class ObjectInterfaceError < ::TypeError; end
 
   # Default {Forgeyard} that is used by {.define} and {.forge}.
   #
@@ -58,51 +118,53 @@ module ObjectForge
   #   @note
   #     Default forgeyard is intended to be useful for non-shareable code,
   #     like simple application tests and specs.
-  #     It should not be used in application code, and never in gems.
+  #     It should not be used in application code, especially in gems.
   # @since 0.1.0
   DEFAULT_YARD = Forgeyard.new
 
-  # @overload sequence(initial)
   # Create a sequence, to be used wherever it needs to be.
   #
   # @see Sequence.new
   # @since 0.1.0
   #
-  # @param initial [#succ, Sequence]
-  # @return [Sequence]
+  # @overload sequence(initial)
+  #   @param initial [#succ, Sequence]
+  #   @return [Sequence]
   def self.sequence(...)
     Sequence.new(...)
   end
 
-  # @overload define(name, forged, &)
   # Define and create a forge in {DEFAULT_YARD}.
   #
   # @!macro default_forgeyard
   # @see Forgeyard#define
   # @since 0.1.0
   #
-  # @param name [Symbol] forge name
-  # @param forged [Class, Any] class or object to forge
-  # @yieldparam f [ForgeDSL]
-  # @yieldreturn [void]
-  # @return [Forge] forge
+  # @overload define(name, forge_target)
+  #   @param name [Symbol] name to register forge under
+  #   @param forge_target [Class, Any] class or object to forge
+  #   @yieldparam dsl [ForgeDSL]
+  #   @yieldreturn [void]
+  #   @return [Forge] forge
   def self.define(...)
     DEFAULT_YARD.define(...)
   end
 
-  # @overload forge(name, *traits, **overrides, &)
   # Build an instance using a forge from {DEFAULT_YARD}.
   #
   # @!macro default_forgeyard
   # @see Forgeyard#forge
   # @since 0.1.0
   #
-  # @param name [Symbol] name of the forge
-  # @param traits [Array<Symbol>] traits to apply
-  # @param overrides [Hash{Symbol => Any}] attribute overrides
-  # @yieldparam object [Any] forged instance
-  # @yieldreturn [void]
-  # @return [Any] built instance
+  # @overload forge(name, *traits, **overrides)
+  #   @param name [Symbol] name of the forge
+  #   @param traits [Array<Symbol>] traits to apply
+  #   @param overrides [Hash{Symbol => Any}] attribute overrides
+  #   @yieldparam object [Any] forged instance
+  #   @yieldreturn [void]
+  #   @return [Any] forged instance
+  #   @raise [ArgumentError] if a trait name is unknown
+  #   @raise [KeyError] if forge with the specified name is not registered
   def self.forge(...)
     DEFAULT_YARD.forge(...)
   end

data/sig/object_forge/molds.rbs

@@ -3,15 +3,7 @@ module ObjectForge
     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
-    end
-
-    class KeywordsMold
-      include ObjectForge::_Mold
-    end
+      : (ObjectForge::forge_target) -> ObjectForge::mold
 
     class WrappedMold
       interface _MoldClass[T]
@@ -25,43 +17,53 @@ module ObjectForge
       def initialize: (_MoldClass[ObjectForge::mold] wrapped_mold) -> void
     end
 
+    class SingleArgumentMold
+      include ObjectForge::_Mold
+    end
+
+    class KeywordsMold
+      include ObjectForge::_Mold
+    end
+
     class StructMold
       interface _StructSubclass[T]
         def new
           : (*untyped) -> T
           | (**untyped) -> T
-          | (Hash[Symbol, untyped]) -> T
+          | (Hash[Symbol, ObjectForge::attribute]) -> T
         def members: -> Array[Symbol]
         def keyword_init?: -> bool?
       end
 
       RUBY_FEATURE_AUTO_KEYWORDS: bool
+
       attr_reader lax: bool
+      alias lax? lax
 
       def initialize: (?lax: bool) -> void
 
       def call
-        : [T < Struct] (forged: _StructSubclass[T], attributes: Hash[Symbol, untyped], **untyped) -> T
+        : [T < Struct] (forge_target: _StructSubclass[T], attributes: Hash[Symbol, ObjectForge::attribute], **untyped) -> T
       
       private
       
       def build_struct_with_unspecified_keyword_init
-        : [T < Struct] (_StructSubclass[T] forged, Hash[Symbol, untyped] attributes) -> T
+        : [T < Struct] (_StructSubclass[T] forge_target, Hash[Symbol, ObjectForge::attribute] attributes) -> T
     end
 
     class HashMold
       interface _HashSubclass[T]
-        def []: (Hash[untyped, untyped]) -> T
+        def []: (Hash[Symbol, ObjectForge::attribute]) -> T
       end
 
-      attr_reader default: untyped?
+      attr_reader default: ObjectForge::attribute
       attr_reader default_proc: Proc?
 
       def initialize
-        : (?untyped? default_value) ?{ (Hash[untyped, untyped] hash, untyped key) -> untyped} -> void
+        : [T < Hash] (?ObjectForge::attribute default_value) ?{ (T hash, untyped key) -> ObjectForge::attribute} -> void
       
       def call
-        : [T < Hash] (forged: _HashSubclass[T], attributes: Hash[Symbol, untyped], **untyped) -> T
+        : [T < Hash] (forge_target: _HashSubclass[T], attributes: Hash[Symbol, ObjectForge::attribute], **untyped) -> T
     end
   end
 end