activerecord-null 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7367e3edc8eb1a5d3a539c08cb3ac8bc18a7334d36725edd397ca121adcd143c
-  data.tar.gz: 8e86346fcf08e650daeaacc39a70c213dce6cf63119317742fb0ecd5ffbdc142
+  metadata.gz: a56f2bfbaf5d498a54f2698e96dc1d460b6a9036ed1c6946e54bcbf724a782c9
+  data.tar.gz: 4575ab2f7ffabae11b05bf8429acb57c0810840fd7e996902691f4758d63ce81
 SHA512:
-  metadata.gz: 2ec01aaa257aebaf1e5f9773e9d9d54431a0ffedf51adba02426b18552dc1bd20e1f64f3a1613a797fe69330c510526383e295650db1720e50b66b67715d6d25
-  data.tar.gz: eaf8a7c1df7a95fb2a48f44f519a81f5961d5ab681daa93933e47f80f88a3bfe335061642da59ad14456245363af478e5f62bbc9ecb616a610273b54ec88f287
+  metadata.gz: 5f737ae853ffbdf31b4ef323e313f9a844f7b549d2bb3a7aa8d5547af94bfb0779b5d2f099a47b11f6ff4b3a48f163e842d68e8c3efb8b52e519a08ae30dc620
+  data.tar.gz: e0af61bf86c190fb5e5ccf05eb7d8ec13f0cbb51e59b48e36eb3e0be1b29f3925ea69e778e391c2b0b700d7e1e053ab801db4840fe4e1ae91a130772b98c3132

data/CHANGELOG.md

@@ -5,14 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.4] - 2025-11-19
+## [0.1.5] - 2025-11-19
+
+### Added
+
+- Void() method for defining non-singleton null objects (0e89194)
+- Model.void(attributes) for creating instances with attribute overrides (0e89194)
 
 ### Changed
 
-- Only initialize attributes when table exists (dba2ace)
+- Mimic module now delegates table_name to parent model (c6f3956)
+- Extracted create_null_class, setup_singleton_attributes, setup_instance_attributes helpers (b0a77f8)
+- Pass class_name to the Null() or Void() methods with an alternative class name. (d3284c4)
+
+## [0.1.5] - 2025-11-19
+
+### Added
 
-## [0.1.4] - 2025-11-19
+- Void() method for defining non-singleton null objects (0e89194)
+- Model.void(attributes) for creating instances with attribute overrides (0e89194)
 
 ### Changed
 
-- Only initialize attributes when table exists (dba2ace)
+- Mimic module now delegates table_name to parent model (c6f3956)
+- Extracted create_null_class, setup_singleton_attributes, setup_instance_attributes helpers (b0a77f8)
+- Pass class_name to the Null() or Void() methods with an alternative class name. (d3284c4)

data/README.md

@@ -68,6 +68,81 @@ class User < ApplicationRecord
 end
 ```
 
+Customize the null class name:
+
+```ruby
+class User < ApplicationRecord
+  Null(class_name: "Guest")
+  class << self
+    alias_method :null, :guest
+  end
+end
+
+User.guest # returns a User::Guest instance
+```
+
+### Void Objects
+
+While `Null` objects are singletons (one instance per model), `Void` objects are instantiable null objects that allow creating multiple instances with different attribute values.
+
+Define a void object for the model:
+
+```ruby
+class Product < ApplicationRecord
+  Void([:name] => "Unknown Product") do
+    def display_name
+      "Product: #{name}"
+    end
+  end
+end
+```
+
+Create instances with custom attributes:
+
+```ruby
+product1 = Product.void(name: "Widget")
+product2 = Product.void(name: "Gadget")
+
+product1.name # => "Widget"
+product2.name # => "Gadget"
+```
+
+Each call to `.void` returns a new instance:
+
+```ruby
+Product.void.object_id != Product.void.object_id # => true
+```
+
+Instance attributes override defaults:
+
+```ruby
+product = Product.void(name: "Custom")
+product.name # => "Custom" (overrides default "Unknown Product")
+
+default_product = Product.void
+default_product.name # => "Unknown Product" (uses default)
+```
+
+Void objects support the same features as Null objects:
+- Callable defaults (lambdas/procs)
+- Custom methods via block syntax
+- Association handling
+- All ActiveRecord query methods (`null?`, `persisted?`, etc.)
+- Custom class names via `class_name:` parameter
+
+```ruby
+class Product < ApplicationRecord
+  Void(class_name: "Placeholder")
+  class << self
+    alias_method :void, :placeholder
+  end
+end
+
+Product.placeholder # returns a Product::Placeholder instance
+```
+
+Use `Null` when you need a single shared null object instance. Use `Void` when you need multiple null object instances with different attribute values.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/activerecord/null/mimic.rb

@@ -14,7 +14,7 @@ module ActiveRecord
 
         def self.mimic_model_class = @mimic_model_class
 
-        def self.table_name = @mimic_model_class.to_s.tableize
+        def self.table_name = @mimic_model_class.table_name
 
         def self.primary_key = @mimic_model_class.primary_key
 

data/lib/activerecord/null/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   module Null
-    VERSION = "0.1.4"
+    VERSION = "0.1.5"
   end
 end

data/lib/activerecord/null.rb

@@ -12,44 +12,20 @@ module ActiveRecord
   #     extend ActiveRecord::Null
   #   end
   module Null
-    # Define a Null class for the given class.
-    #
-    # @example
-    #   class Business < ApplicationRecord
-    #     Null do
-    #       def name = "None"
-    #     end
-    #   end
-    #
-    #   Business.null # => #<Business::Null:0x0000000000000000>
-    #   Business.null.name # => "None"
-    #
-    #   class User < ApplicationRecord
-    #     Null([:name, :team_name] => "Unknown")
-    #   end
-    #
-    #   User.null.name # => "Unknown"
-    #   User.null.team_name # => "Unknown"
-    #
-    # @param inherit [Class] The class from which the Null object inherits attributes
-    # @param assignments [Array] The attributes to assign to the null object
-    def Null(inherit = self, assignments = {}, &)
-      if inherit.is_a?(Hash)
-        assignments = inherit
-        inherit = self
-      end
+    private
+
+    # Shared method to create Null or Void classes
+    def create_null_class(inherit, assignments, singleton:)
       null_class = Class.new do
         include ::ActiveRecord::Null::Mimic
 
         mimics inherit
 
-        include Singleton
-
-        # Store assignments for lazy initialization
-        @_null_assignments = assignments
+        # Store assignments
+        instance_variable_set(:@_assignments, assignments)
 
         class << self
-          attr_reader :_null_assignments
+          attr_reader :_assignments
 
           def method_missing(method, ...)
             mimic_model_class.respond_to?(method) ? mimic_model_class.send(method, ...) : super
@@ -58,7 +34,22 @@ module ActiveRecord
           def respond_to_missing?(method, include_private = false)
             mimic_model_class.respond_to?(method, include_private) || super
           end
+        end
+      end
+
+      if singleton
+        null_class.include(Singleton)
+        setup_singleton_attributes(null_class)
+      else
+        setup_instance_attributes(null_class)
+      end
 
+      null_class
+    end
+
+    def setup_singleton_attributes(null_class)
+      null_class.class_eval do
+        class << self
           # Override instance to initialize attributes lazily
           def instance
             initialize_attribute_methods unless @_attributes_initialized
@@ -68,21 +59,17 @@ module ActiveRecord
           private
 
           def initialize_attribute_methods
-            # Only initialize if table exists
             return unless mimic_model_class.table_exists?
 
-            # Define custom assignment methods first
-            if _null_assignments.any?
-              _null_assignments.each do |attributes, value|
+            if _assignments.any?
+              _assignments.each do |attributes, value|
                 define_attribute_methods(attributes, value:)
               end
             end
 
-            # Then define database attributes
             nil_assignments = mimic_model_class.attribute_names
-            # Remove custom assignments from database attributes
-            if _null_assignments.any?
-              _null_assignments.each do |attributes, _|
+            if _assignments.any?
+              _assignments.each do |attributes, _|
                 nil_assignments -= attributes
               end
             end
@@ -92,13 +79,125 @@ module ActiveRecord
           end
         end
       end
-      null_class.class_eval(&) if block_given?
+    end
+
+    def setup_instance_attributes(null_class)
+      null_class.class_eval do
+        def initialize(attributes = {})
+          @_instance_attributes = attributes
+          initialize_attribute_methods
+        end
+
+        private
+
+        def initialize_attribute_methods
+          return unless self.class.mimic_model_class.table_exists?
+
+          assignments = self.class._assignments
+
+          if assignments.any?
+            assignments.each do |attributes, default_value|
+              attributes.each do |attr|
+                attr_sym = attr.to_sym
+                next if respond_to?(attr_sym)
+
+                define_singleton_method(attr_sym) do
+                  if @_instance_attributes.key?(attr_sym)
+                    @_instance_attributes[attr_sym]
+                  elsif default_value.is_a?(Proc)
+                    instance_exec(&default_value)
+                  else
+                    default_value
+                  end
+                end
+              end
+            end
+          end
+
+          nil_assignments = self.class.mimic_model_class.attribute_names
+          if assignments.any?
+            assignments.each do |attributes, _|
+              nil_assignments -= attributes.map(&:to_s)
+            end
+          end
 
-      inherit.const_set(:Null, null_class)
+          nil_assignments.each do |attr|
+            attr_sym = attr.to_sym
+            next if respond_to?(attr_sym)
 
+            define_singleton_method(attr_sym) do
+              @_instance_attributes.key?(attr_sym) ? @_instance_attributes[attr_sym] : nil
+            end
+          end
+        end
+      end
+    end
+
+    public
+
+    # Define a Null class for the given class.
+    #
+    # @example
+    #   class Business < ApplicationRecord
+    #     Null do
+    #       def name = "None"
+    #     end
+    #   end
+    #
+    #   Business.null # => #<Business::Null:0x0000000000000000>
+    #   Business.null.name # => "None"
+    #
+    #   class User < ApplicationRecord
+    #     Null([:name, :team_name] => "Unknown")
+    #   end
+    #
+    #   User.null.name # => "Unknown"
+    #   User.null.team_name # => "Unknown"
+    #
+    # @param inherit [Class] The class from which the Null object inherits attributes
+    # @param assignments [Array] The attributes to assign to the null object
+    def Null(inherit = self, class_name: :Null, **assignments, &)
+      if inherit.is_a?(Hash)
+        assignments = inherit
+        inherit = self
+      end
+
+      null_class = create_null_class(inherit, assignments, singleton: true)
+      null_class.class_eval(&) if block_given?
+
+      inherit.const_set(class_name, null_class)
       inherit.define_singleton_method(:null) { null_class.instance }
     end
 
+    # Define a Void class for the given class.
+    # Unlike Null, Void objects are not singletons and can be instantiated
+    # multiple times with different attribute values.
+    #
+    # @example
+    #   class Product < ApplicationRecord
+    #     Void do
+    #       def display_name = "Product: #{name}"
+    #     end
+    #   end
+    #
+    #   product1 = Product.void(name: "Widget")
+    #   product2 = Product.void(name: "Gadget")
+    #
+    # @param inherit [Class] The class from which the Void object inherits attributes
+    # @param assignments [Hash] The default attributes to assign to void objects
+    def Void(inherit = self, class_name: :Void, **assignments, &)
+      if inherit.is_a?(Hash)
+        assignments = inherit
+        inherit = self
+      end
+
+      void_class = create_null_class(inherit, assignments, singleton: false)
+      void_class.class_eval(&) if block_given?
+
+      inherit.const_set(class_name, void_class)
+      inherit.define_singleton_method(:void) { |attributes = {}| void_class.new(attributes) }
+    end
+
     def self.extended(base)
       base.define_method(:null?) { false }
     end

data/test/activerecord/test_void.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+  extend ActiveRecord::Null
+end
+
+class Product < ApplicationRecord
+  self.table_name = "businesses" # Reuse existing table
+
+  Void([:name] => "Unknown Product") do
+    def display_name
+      "Product: #{name}"
+    end
+  end
+end
+
+class Comment < ApplicationRecord
+  self.table_name = "posts" # Reuse existing table
+
+  Void()
+end
+
+class ActiveRecord::TestVoid < Minitest::Spec
+  describe "Void class definition" do
+    it "creates Void constant on model" do
+      assert Product.const_defined?(:Void)
+    end
+
+    it "Void class includes Mimic" do
+      assert Product::Void.include?(ActiveRecord::Null::Mimic)
+    end
+
+    it "Void class does not include Singleton" do
+      refute Product::Void.include?(Singleton)
+    end
+
+    it "defines .void method on model" do
+      assert Product.respond_to?(:void)
+    end
+
+    it "Void can be defined without arguments" do
+      assert Comment.const_defined?(:Void)
+    end
+  end
+
+  describe ".void instantiation" do
+    it "returns new instance each time" do
+      void1 = Product.void
+      void2 = Product.void
+
+      assert_instance_of Product::Void, void1
+      assert_instance_of Product::Void, void2
+      refute_equal void1.object_id, void2.object_id
+    end
+
+    it "creates instance with no arguments" do
+      void_obj = Product.void
+
+      assert_instance_of Product::Void, void_obj
+    end
+
+    it "creates instance with empty hash" do
+      void_obj = Product.void({})
+
+      assert_instance_of Product::Void, void_obj
+    end
+  end
+
+  describe "attribute handling" do
+    it "returns default value from hash syntax" do
+      void_obj = Product.void
+
+      assert_equal "Unknown Product", void_obj.name
+    end
+
+    it "allows instance attributes to override defaults" do
+      void_obj = Product.void(name: "Custom Product")
+
+      assert_equal "Custom Product", void_obj.name
+    end
+
+    it "database attributes default to nil" do
+      # Assuming businesses table doesn't have a 'price' column
+      void_obj = Product.void
+
+      # Name has a default, so it should return that
+      assert_equal "Unknown Product", void_obj.name
+    end
+
+    it "supports multiple instances with different attributes" do
+      void1 = Product.void(name: "Product A")
+      void2 = Product.void(name: "Product B")
+
+      assert_equal "Product A", void1.name
+      assert_equal "Product B", void2.name
+    end
+
+    it "instance attributes don't affect class defaults" do
+      void1 = Product.void(name: "Modified")
+      void2 = Product.void
+
+      assert_equal "Modified", void1.name
+      assert_equal "Unknown Product", void2.name
+    end
+  end
+
+  describe "custom methods from block" do
+    it "block-defined methods are accessible" do
+      void_obj = Product.void
+
+      assert_respond_to void_obj, :display_name
+    end
+
+    it "block methods can access attributes" do
+      void_obj = Product.void(name: "Special")
+
+      assert_equal "Product: Special", void_obj.display_name
+    end
+
+    it "block methods work with defaults" do
+      void_obj = Product.void
+
+      assert_equal "Product: Unknown Product", void_obj.display_name
+    end
+  end
+
+  describe "type checking" do
+    it "is_a?(Model) returns true" do
+      void_obj = Product.void
+
+      assert void_obj.is_a?(Product)
+    end
+
+    it "is_a?(Model::Void) returns true" do
+      void_obj = Product.void
+
+      assert void_obj.is_a?(Product::Void)
+    end
+
+    it "null? returns true" do
+      void_obj = Product.void
+
+      assert void_obj.null?
+    end
+
+    it "persisted? returns false" do
+      void_obj = Product.void
+
+      refute void_obj.persisted?
+    end
+
+    it "new_record? returns false" do
+      void_obj = Product.void
+
+      refute void_obj.new_record?
+    end
+
+    it "destroyed? returns false" do
+      void_obj = Product.void
+
+      refute void_obj.destroyed?
+    end
+  end
+
+  describe "callable attribute values" do
+    it "supports callable defaults" do
+      test_class = Class.new(ApplicationRecord) do
+        def self.name
+          "CallableTest"
+        end
+
+        self.table_name = "users"
+
+        Void([:name] => -> { "Computed Name" })
+      end
+
+      void_obj = test_class.void
+
+      assert_equal "Computed Name", void_obj.name
+    end
+
+    it "callable defaults can access instance context" do
+      test_class = Class.new(ApplicationRecord) do
+        def self.name
+          "ContextTest"
+        end
+
+        self.table_name = "users"
+
+        Void([:name] => -> { "Hello" })
+
+        def greeting
+          "Welcome"
+        end
+      end
+
+      void_obj = test_class.void
+
+      assert_equal "Hello", void_obj.name
+    end
+  end
+
+  describe "integration with Null" do
+    it "Null and Void can coexist on same model" do
+      # Define both on a test class
+      test_class = Class.new(ApplicationRecord) do
+        def self.name
+          "TestModel"
+        end
+
+        self.table_name = "users"
+
+        Null([:name] => "Null Default")
+        Void([:name] => "Void Default")
+      end
+
+      null_obj = test_class.null
+      void_obj = test_class.void
+
+      assert_equal "Null Default", null_obj.name
+      assert_equal "Void Default", void_obj.name
+      assert_equal null_obj.object_id, test_class.null.object_id # Singleton
+      refute_equal void_obj.object_id, test_class.void.object_id # Not singleton
+    end
+  end
+
+  describe "model integration" do
+    it "respects table_name from parent model" do
+      assert_equal Product.table_name, Product::Void.table_name
+    end
+
+    it "respects primary_key from parent model" do
+      assert_equal "id", Product::Void.primary_key
+    end
+
+    it "has mimic_model_class reference" do
+      void_obj = Product.void
+
+      assert_equal Product, void_obj.mimic_model_class
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-null
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Jim Gay
@@ -41,6 +41,7 @@ files:
 - lib/activerecord/null/version.rb
 - test/activerecord/test_lazy_loading.rb
 - test/activerecord/test_null.rb
+- test/activerecord/test_void.rb
 - test/support/schema.rb
 - test/test_helper.rb
 homepage: https://github.com/SOFware/activerecord-null