active_module 0.1.7 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 191f7c2deb3a07261247a4302436cc734541ab62c3db9dd742974d58320dd763
-  data.tar.gz: bd20cb4d1aa7b6437facfaefc8213485571497df5e9e607ce19d16b81db246b8
+  metadata.gz: 743570de05b5e510d10408fe3b95eaab2789e4432311538bda978bf52d893355
+  data.tar.gz: 72057e516212b80260b45fe9b2bd5c97530fc5f6ceaab42c0578d48581bf3b50
 SHA512:
-  metadata.gz: bc48c3f11e8f71321ab4abece1b5d58f671c96de7e494a5f2f7a8e55b9946c6e88af9e61970bdd2332eba12ee74dadec13485555dff0f05a4f74209c1327fd96
-  data.tar.gz: 126c9c4a2d885cadbe472dc23caa5025415f2806411e9eecce37a5b40c28ce990c5956246646292e9780b6f30d6f77705ab681899a7532940dbe0cfe59f2a471
+  metadata.gz: 7c4ee2bc7ae24fb246f9744f161088222af6c02d85c99d62e39f196257b90d24abcea21de0217ea578d8755acfd61bf4d078d9f7290f3cc0cc28110bca893cd9
+  data.tar.gz: '02582a7cbe08a616e35828e0537bacf41714cd4cfae0d5272188fb9feb8aa970c44670391b1cef6926781ebe53f28ce966a0eeda46d32e2149be22370cf19daf'

data/README.md

@@ -1,21 +1,23 @@
-# ActiveModule
 
-*"Let's turn modules and classes into first-class active record values!"*
+# active_module 
+![alt text](https://img.shields.io/badge/coverage-100%25-brightgreen)
+
+#### *Modules and Classes as first-class active record values!*
 
 ActiveModel/ActiveRecord implementation of the Module attribute type.
 
-- Allows storing a reference to a `Module` or `Class` (because they are modules) in a `:string` 
-database field in a safe and efficient way.
-- It automatically casts strings and symbols into modules when creating and querying objects.
-- Symbols or strings refer to the modules using unqualified names.
+- Allows storing a reference to a `Module` or `Class` in a `:string` database field
+- Automatically casts strings and symbols into modules when creating and querying objects
+- Symbols or strings refer to the modules using unqualified names
+- It is safe and efficient
 
 This is a very generic mechanism that enables many possible utilizations, for instance:
-- Strategy Pattern (composition-based polymorphism)
-- Rapid prototyping static domain objects
-- Static configuration management
-- Rich Java/C#-like enums
+- **Composition-based polymorphism (Strategy design pattern)**
+- **Rapid prototyping static domain objects**
+- **Static configuration management**
+- **Rich Java/C#-like enums**
 
-You can find examples of these in [Usage -> Examples :](#Examples) 
+You can find examples of these in [Usage -> Examples](#Examples).
 
 ## TL;DR
 
@@ -36,13 +38,24 @@ object.module_field = "Module"
 object.module_field #=> Nested::Module:Module
 ```
 
-And compare them like this (optional):
+Query them like this:
+```ruby 
+MyARObject.where(module_field: Nested::Module)
+MyARObject.where(module_field: :Module)
+MyARObject.where(module_field: "Module")
+object.module_field #=> Nested::Module:Module
+```
+
+And compare them like this:
+
 ```ruby 
+object.module_field == Nested::Module
+
 module MyNameSpace
   using ActiveModule::Comparison
 
-  object.module_field =~ :Module1
-  object.module_field =~ "Module1"
+  object.module_field =~ :Module
+  object.module_field =~ "Module"
 end
 ```
 
@@ -51,7 +64,7 @@ end
 Add to your gemfile - and if you are using rails - that's all you need:
 
 ```ruby
-gem 'active_module', "~>0.1"
+gem 'active_module', "~> 0.2"
 ```
 
 If you are not using rails, just issue this command after loading active record
@@ -73,11 +86,11 @@ ActiveRecord::Type.register(:active_module, ActiveModule::Base)
 Add a string field to the table you want to hold a module attribute in your migrations
 ```ruby
 create_table :my_ar_objects do |t|
-  t.string :module_field
+  t.string :module_field, index: true
 end
 ```
 
-Now given this module structure:
+Now given this random module hierarchy:
 ```ruby
 class MyARObject < ActiveRecord::Base
   module MyModule1; end
@@ -95,6 +108,16 @@ class MyARObject < ActiveRecord::Base
             possible_modules: [MyModule1, MyModule2, MyClass, MyClass::MyModule1]
 end
 ```
+
+Optionally, you can specify how to map your modules into the database 
+(the default is the module's fully qualified name):
+```ruby
+attribute :module_field, 
+          :active_module, 
+          possible_modules: [MyModule1, MyModule2, MyClass, MyClass::MyModule1]
+          mapping: {MyModule1 => "this is the db representation of module1"}
+```
+
 And this is it! Easy!<br>
 
 ### Assigning and querying module attributes
@@ -169,23 +192,28 @@ my_ar_object.module_field == MyClass::MyModule1
 
 ## Examples
 
-### Strategy Pattern (composition-based polymorphism)
+### Composition-based polymorphism (Strategy design pattern)
 
 [The Strategy design pattern](https://en.wikipedia.org/wiki/Strategy_pattern) allows composition based polymorphism. This enables runtime polymorphism (by changing the strategy in runtime), 
 and multiple-polymorphism (by composing an object of multiple strategies).
 
-If you want to use classes this will do:
+If you want to use classes this will do: 
 ```ruby
 class MyARObject < ActiveRecord::Base
-  attribute :strategy, :active_module, possible_modules: StrategySuperclass.subclasses
+  attribute :strategy_class, :active_module, possible_modules: StrategySuperclass.subclasses
+
+  def strategy
+    @strategy ||= strategy_class.new(some_args_from_the_instance)
+  end
 
   def run_strategy!(args)
-    strategy.new(some_args).call(other_args)
+    strategy.call(args)
   end
 end
 ```
 
-But if you are not in the mood to define a class hierarchy for it, you can use modules instead:
+But if you are not in the mood to define a class hierarchy for it (or if you are performance-savy),
+you may use modules instead:
 
 ```ruby
 class MyARObject < ActiveRecord::Base
@@ -214,6 +242,39 @@ MyARObject.create!(module_field: :Strategy1).run_strategy! #=> "strategy1 called
 MyARObject.create!(module_field: :Strategy2).run_strategy! #=> "strategy2 called"
 ```
 
+You can later easily promote these modules to classes if you need instance variables:
+
+```ruby
+class MyARObject < ActiveRecord::Base
+  class Strategy1
+    def self.call
+      self.new.call
+    end
+
+    def call
+      "strategy1 called"
+    end
+  end
+
+  module Strategy2
+    def self.call
+      "strategy2 called"
+    end
+  end
+
+  attribute :strategy, 
+            :active_module, 
+            possible_modules: [Strategy1, Strategy2]
+
+  def run_strategy!(some_args)
+    strategy.call(some_args, other_args)
+  end
+end
+
+MyARObject.create!(module_field: :Strategy1).run_strategy! #=> "strategy1 called"
+MyARObject.create!(module_field: :Strategy2).run_strategy! #=> "strategy2 called"
+```
+
 
 ### Rapid prototyping static domain objects
 

data/lib/active_module/base.rb

@@ -5,11 +5,35 @@ require_relative "modules_index"
 
 module ActiveModule
   class Base < ActiveModel::Type::Value
-    def initialize(possible_modules:)
-      @possible_modules = possible_modules
+    attr_reader :possible_modules, :mapping
+
+    def initialize(possible_modules_or_mapping = nil,
+                   possible_modules: [],
+                   mapping: {})
+      @possible_modules =
+        if possible_modules_or_mapping.is_a?(Array)
+          possible_modules_or_mapping + possible_modules
+        else
+          possible_modules
+        end
+      mapping_arg = if possible_modules_or_mapping.is_a?(Hash)
+                      possible_modules_or_mapping.merge(mapping)
+                    else
+                      mapping
+                    end
+      @mapping =
+        @possible_modules.each_with_object(mapping_arg.dup) do |mod, result|
+          result[mod] ||= mod.name
+        end
       super()
     end
 
+    def ==(other)
+      other.is_a?(Base) &&
+        possible_modules == other.possible_modules &&
+        mapping == other.mapping
+    end
+
     def type
       :active_module
     end
@@ -38,13 +62,11 @@ module ActiveModule
     end
 
     def serialize(module_instance)
-      module_instance && cast(module_instance).name
+      mapping[cast(module_instance)]
     end
 
     def deserialize(str)
-      str&.constantize
-    rescue NameError
-      nil
+      from_db[str]
     end
 
     private
@@ -78,5 +100,9 @@ module ActiveModule
     def modules_index
       @modules_index ||= ModulesIndex.new(@possible_modules)
     end
+
+    def from_db
+      @from_db ||= mapping.invert
+    end
   end
 end

data/lib/active_module/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveModule
-  VERSION = "0.1.7"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_module
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.2.0
 platform: ruby
 authors:
 - Pedro Rolo
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-18 00:00:00.000000000 Z
+date: 2024-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -19,7 +19,7 @@ dependencies:
         version: '9'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '9'
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -44,7 +44,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.15.0
-description: Let's turn modules and classes into first-class active record values!
+description: ActiveModel/ActiveRecord module attribute type implementation
 email:
 - pedrorolo@gmail.com
 executables: []
@@ -89,5 +89,5 @@ requirements: []
 rubygems_version: 3.5.7
 signing_key:
 specification_version: 4
-summary: ActiveModel/ActiveRecord module attribute type implementation
+summary: Modules and Classes as first-class active record values
 test_files: []