mortymer 0.0.11 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1aaae1b0260575ca60caeb8b676577f39766162d8127a6266e1c49e168e11265
-  data.tar.gz: 0f92cfaa12e157dcb4954259dd284b7b46f7305dd912d84a55fef597107997f7
+  metadata.gz: e1733f673e867c239bda30efbc34f45f7452ebbee12a702e201dffbcbb02f621
+  data.tar.gz: 9ff44dd993b2ed7a82971437048731e80cb97b1a15d96fbdeb758d9797b6f3e4
 SHA512:
-  metadata.gz: c5c3932bfb5b0daf315af6f8f4a1ef36b0a448229fd15b9c71f7c8699d8f41fcfeb8a5858686b55d6c7905628936908512e97537b6a5ec0024061f6b3f4bcd60
-  data.tar.gz: df393725ff3c29b36ede225c046f8f27cbfea156f09917cd1976b8c3188f9dafa5e57e0aa0876a378f7afda62ab0ea06b17f500d0f46f6d8caae18c249c13acf
+  metadata.gz: cd31959f30b91390ad9c40efb0fd18154e78829057df484a4b67c8efc5630f0ce97b3bfc47bff4c557bed421226311c6ad5cab077e1aa89da24d9b193defba51
+  data.tar.gz: b9b604148b9ff54cde6cb26bc15d2752e2f8542a9df414cc1d9feb466d8f5e803697336fbfbffab1fb51d8de7b14a5c8a69f53ce3a50638b9df1e4fc36943814

data/docs/guide/mortymer-dependency-injection.md

@@ -27,6 +27,9 @@ When you include `Mortymer::DependenciesDsl`, you get access to the `inject` dir
 1. Create an instance variable `@user_repository`
 2. Automatically initialize it with an instance of `UserRepository`
 
+The name of the injected variable is the snake_case version of the class we are injecting by default. So
+for example `Repositories::UserRepository` will result in an instance variable called `@user_repository`
+
 ### Custom Variable Names
 
 You can customize the instance variable name using the `as` option:
@@ -66,54 +69,61 @@ end
 
 ## Advanced Usage
 
-### Dependency Scopes
-
-Mortymer supports different scopes for dependencies:
-
-#### Singleton Scope (Default)
-
-By default, dependencies are singleton-scoped, meaning the same instance is shared across the application:
+Just with the basic information, Mortymer already provides a really powerful and
+expressive system to declare dependencies, but as it is, is just a Fancy Factory or Initializer
+for your classes. Where Dependency Injection really shines, is when you are able to control some
+other aspects of the dependency injection cycle. For example, Mortymer does not interfere with your
+usual object initialization.
 
 ```ruby
-class UserService
+class MyService
   include Mortymer::DependenciesDsl
+  inject Mailer
 
-  inject UserRepository # Singleton by default
-end
+  def initialize(user)
+    # At this point we can be sure that the @mailer instance
+    # is already defined
+    @mailer.send_email("Hello user", user.email)
+    @user = user
+  end
 ```
 
-#### Request Scope
+It might not be clear what is happening here. What is really doing Mortymer is
+wrapping the `#initialize` method with the dependency resolving algorithm and if
+any `kwarg` passed to the `#initialize` method matches the name of the injected
+dependency, then Mortymer will use that as the dependency instead.
 
-For dependencies that should be unique per request:
+This means that you can call your previous service as:
 
 ```ruby
-class UserService
-  include Mortymer::DependenciesDsl
-
-  inject UserRepository, scope: :request
-end
+MyService.new(User.first) # will use the Mailer class to instantiate the @mailer variable
+MyService.new(User.first, mailer: instance_double(Mailer))  # will override @mailer with an instance_double
 ```
 
-#### Transient Scope
+### Dependency Scopes
 
-For dependencies that should be newly instantiated every time:
+Mortymer supports different scopes for dependencies:
 
-```ruby
-class UserService
-  include Mortymer::DependenciesDsl
+- By default, dependencies are transient, meaning you will get a new fresh instance each time you ask for one
+- Dependencies might be singleton, meaning each injection will provide the same instance
+- Dependencies might be lazy, basically, a block that might compute a value for your dependency
 
-  inject UserRepository, scope: :transient
-end
-```
+To change a dependency's scope, you need to register it in the Mortymer DI Container
 
-### Factory Registration
+#### Singleton Scope
 
-You can register custom factory methods for your dependencies:
+```ruby
+Mortymer.container.register_constant(Mailer, SingletonMailer.new)
+```
+
+#### Lazy Scope
 
 ```ruby
-Mortymer.configure do |config|
-  config.register_factory(UserRepository) do
-    UserRepository.new(connection: DatabaseConnection.current)
+Mortymer.container.register_constant(MAILER_ADMIN_ADDRESS) do
+  if some_condition?
+    "admin+#{Time.current}@example.com"
+  else
+    "admin-ex@example.com"
   end
 end
 ```
@@ -129,6 +139,12 @@ module UserRepositoryInterface
   end
 end
 
+class UserService
+  include Mortymer::DependenciesDsl
+
+  inject UserRepositoryInterface, as: :repo
+end
+
 class PostgresUserRepository
   include UserRepositoryInterface
   # implementation
@@ -140,259 +156,9 @@ class MongoUserRepository
 end
 
 # Register implementation
-Mortymer.configure do |config|
-  config.register_implementation(UserRepositoryInterface, PostgresUserRepository)
-end
-
-class UserService
-  include Mortymer::DependenciesDsl
-
-  inject UserRepositoryInterface
-end
-```
-
-## Testing
-
-### Mocking Dependencies
-
-Mortymer makes it easy to mock dependencies in tests:
-
-```ruby
-RSpec.describe UserService do
-  let(:repository_mock) { instance_double(UserRepository) }
-  let(:mailer_mock) { instance_double(UserMailer) }
-
-  before do
-    Mortymer.stub_dependency(UserRepository, repository_mock)
-    Mortymer.stub_dependency(UserMailer, mailer_mock)
-  end
-
-  it "creates a user" do
-    service = UserService.new
-    expect(repository_mock).to receive(:create)
-    expect(mailer_mock).to receive(:send_welcome_email)
-
-    service.create_user(name: "John")
-  end
-end
-```
-
-### Test-Specific Implementations
-
-You can also register test-specific implementations:
-
-```ruby
-class TestUserRepository
-  include UserRepositoryInterface
-
-  def initialize
-    @users = {}
-  end
-
-  def find(id)
-    @users[id]
-  end
-end
-
-RSpec.describe UserService do
-  before do
-    Mortymer.register_implementation(UserRepositoryInterface, TestUserRepository)
-  end
-end
-```
-
-## Best Practices
-
-### 1. Keep Dependencies Explicit
-
-Always use explicit constant references rather than strings for dependencies:
-
-```ruby
-# Good
-inject UserRepository
-
-# Avoid
-inject "user_repository"
-```
-
-### 2. Use Meaningful Names
-
-Choose descriptive names for your dependencies:
-
-```ruby
-# Good
-inject UserRepository, as: :active_users_repository
-
-# Less Clear
-inject UserRepository, as: :repo
-```
-
-### 3. Group Related Dependencies
-
-Keep related dependencies together and organize them logically:
-
-```ruby
-class UserService
-  include Mortymer::DependenciesDsl
-
-  # Authentication dependencies
-  inject AuthenticationService
-  inject TokenGenerator
-
-  # User management dependencies
-  inject UserRepository
-  inject UserMailer
+Mortymer.container.register_constant(UserRepositoryInterface, PostgresUserRepository.new)
 
-  # Logging/Monitoring
-  inject Logger
-  inject MetricsCollector
-end
-```
-
-### 4. Interface Segregation
-
-Create focused interfaces for your dependencies:
-
-```ruby
-module UserReader
-  def find(id); end
-  def list; end
-end
-
-module UserWriter
-  def create(attributes); end
-  def update(id, attributes); end
-end
-
-class UserRepository
-  include UserReader
-  include UserWriter
-end
-
-class UserService
-  include Mortymer::DependenciesDsl
-
-  inject UserReader  # Only inject what you need
-end
-```
-
-## Common Patterns
-
-### Service Objects
-
-```ruby
-class CreateUser
-  include Mortymer::DependenciesDsl
-
-  inject UserRepository
-  inject UserMailer
-  inject UserValidator
-
-  def call(params)
-    @user_validator.validate!(params)
-    user = @user_repository.create(params)
-    @user_mailer.send_welcome_email(user)
-    user
-  end
-end
-```
-
-### Decorators
-
-```ruby
-class LoggedUserRepository
-  include Mortymer::DependenciesDsl
-
-  inject UserRepository
-  inject Logger
-
-  def find(id)
-    @logger.info("Finding user: #{id}")
-    result = @user_repository.find(id)
-    @logger.info("Found user: #{result&.id}")
-    result
-  end
-end
-```
-
-## Configuration
-
-### Global Configuration
-
-```ruby
-Mortymer.configure do |config|
-  # Register default implementations
-  config.register_implementation(UserRepositoryInterface, PostgresUserRepository)
-
-  # Register factories
-  config.register_factory(Logger) do
-    Logger.new($stdout).tap do |logger|
-      logger.level = Rails.env.production? ? :info : :debug
-    end
-  end
-
-  # Configure scopes
-  config.set_scope(UserSession, :request)
-end
-```
-
-### Environment-Specific Configuration
-
-```ruby
-# config/initializers/mortymer.rb
-Mortymer.configure do |config|
-  if Rails.env.test?
-    config.register_implementation(UserRepositoryInterface, TestUserRepository)
-  elsif Rails.env.development?
-    config.register_implementation(UserRepositoryInterface, DevUserRepository)
-  else
-    config.register_implementation(UserRepositoryInterface, ProductionUserRepository)
-  end
-end
+# Then you can instantiate
+UserService.new # will use the PostgresUserRepository implementation
+UserService.new(repo: MongoUserRepository.new) # override the dependency to use a different one
 ```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Circular Dependencies**
-
-```ruby
-# This will raise a CircularDependencyError
-class UserService
-  include Mortymer::DependenciesDsl
-  inject AccountService
-end
-
-class AccountService
-  include Mortymer::DependenciesDsl
-  inject UserService  # Circular dependency!
-end
-```
-
-Solution: Refactor to remove the circular dependency or use method injection.
-
-2. **Missing Dependencies**
-
-```ruby
-# This will raise a DependencyNotFoundError
-class UserService
-  include Mortymer::DependenciesDsl
-  inject NonExistentService
-end
-```
-
-Solution: Ensure all dependencies are properly registered or the constants exist.
-
-3. **Scope Conflicts**
-
-```ruby
-# This might cause issues
-class UserService
-  include Mortymer::DependenciesDsl
-  inject SessionManager, scope: :request  # Request-scoped
-  inject UserRepository  # Singleton-scoped
-end
-```
-
-Solution: Be careful mixing different scopes and ensure it makes sense for your use case.

data/docs/guide/type-system.md

@@ -0,0 +1,208 @@
+# Mortymer Type System Guide
+
+## Overview
+
+Mortymer provides a way to enforce the types contracts for inputs and
+outputs of your methods through the `Sigil` module that leverages `dry-types`
+to enable runtime type checking. Not only that, but, it also will try to coerce
+the given parameters to the declared type, and will check validation contracts
+and rules for your inputs and outputs. This is not intended to be a replacement
+for Type Checkers like Sorbet or Steep, but rather a nice utility to avoid guard
+code like:
+
+```ruby
+def func(params)
+  result = MyContract.new.call(params)
+  if result.errors.empty?
+    result[:age].to_i + 10
+  else
+    raise StandardError, result.errors
+  end
+end
+```
+
+The above snippet is really common when dealing with validation (you may use `#instance_of?` method as well,
+or strong parameters or whatever, but the essence is that you need to declare the shape of the data
+that comes in and out of your methods).
+
+Using Mortymer's Sigil, the above will translate to pretty much the following code:
+
+```ruby
+sign MyContract
+def func(params)
+  params.age + 10
+end
+
+func(MyContract.structify({age: 10})) # Will work
+func(age: 10)  # Will work, the params would be { age: 10 } which will be coerced and validated with MyCotnract
+func(age: "10") # Will also work, if MyContract is Coercing the age to Integer
+func(age: "asd") # will raise a meaningful error
+```
+
+## Basic Usage
+
+### Method Type Signatures
+
+The most basic form of type checking in Mortymer uses the `sign` directive:
+
+```ruby
+class Calculator
+  include Mortymer::Sigil
+
+  sign Types::Integer, Types::Integer, returns: Types::Integer
+  def add(a, b)
+    a + b
+  end
+end
+```
+
+When you include `Mortymer::Sigil`, you get access to the `sign` directive. This will:
+
+1. Check the types of all arguments when the method is called
+2. Verify the return type matches the specified type
+3. Raise a `TypeError` if any type mismatch occurs
+
+### Keyword Arguments
+
+You can specify types for keyword arguments using a hash syntax:
+
+```ruby
+class UserService
+  include Mortymer::Sigil
+
+  sign name: Types::String, age: Types::Integer, returns: Types::Hash
+  def create_user(name:, age:)
+    { name: name, age: age }
+  end
+end
+```
+
+### Array Types
+
+Mortymer supports type checking for arrays of specific types:
+
+```ruby
+class Calculator
+  include Mortymer::Sigil
+
+  sign Types::Array.of(Types::Integer), returns: Types::Integer
+  def sum(numbers)
+    numbers.sum
+  end
+end
+```
+
+## Advanced Usage
+
+### Contract Integration
+
+Mortymer's type system integrates seamlessly with Contracts for more complex validations:
+
+```ruby
+class AgeContract < Mortymer::Contract
+  params do
+    required(:age).value(Integer, gt?: 10)
+  end
+  compile!
+end
+
+class UserService
+  include Mortymer::Sigil
+
+  sign AgeContract, returns: Types::Hash
+  def process_age(params)
+    { processed_age: params.age * 2 }
+  end
+end
+```
+
+### Model Integration
+
+The type system works directly with Mortymer Models:
+
+```ruby
+class User < Mortymer::Model
+  attribute :name, String
+  attribute :age, Integer
+end
+
+class UserService
+  include Mortymer::Sigil
+
+  sign User, returns: User
+  def double_age(user)
+    User.new(name: user.name, age: user.age * 2)
+  end
+end
+```
+
+### Optional Return Types
+
+You can omit the return type if you don't want to enforce it:
+
+```ruby
+class StringService
+  include Mortymer::Sigil
+
+  sign Types::String
+  def uppercase(str)
+    str.upcase
+  end
+end
+```
+
+### Type Coercion
+
+The type system will attempt to coerce values when possible:
+
+```ruby
+class UserService
+  include Mortymer::Sigil
+
+  sign User, returns: User
+  def process_user(user_data)
+    # Will coerce a hash into a User model
+    user = user_data.is_a?(User) ? user_data : User.new(user_data)
+    User.new(name: user.name.upcase, age: user.age)
+  end
+end
+```
+
+## Error Handling
+
+When type checking fails, Mortymer raises descriptive errors:
+
+- `Mortymer::Sigil::TypeError` for type mismatches
+- `Mortymer::Contract::ContractError` for contract violations
+
+Example error messages:
+
+- "Invalid type for argument 0: expected Integer, got String"
+- "Invalid type for keyword argument name: expected String, got Integer"
+- "Invalid return type: expected String, got Integer"
+
+## Best Practices
+
+1. **Be Explicit**: Always specify types for critical method parameters
+2. **Use Contracts**: For complex validations, combine with Mortymer Contracts
+3. **Return Types**: Specify return types when the output type is important
+4. **Model Integration**: Use Mortymer Models for structured data
+5. **Error Handling**: Handle type errors at appropriate boundaries in your application
+
+## Type System Compatibility
+
+The type system maintains compatibility with other method hooks and Ruby features:
+
+```ruby
+class Service
+  include Mortymer::Sigil
+  include OtherModule # with method_added hooks
+
+  sign Types::String, returns: Types::String
+  def process(str)
+    str.upcase
+  end
+end
+```
+
+The type system will properly chain method hooks while maintaining type checking functionality.

data/lib/mortymer/api_metadata.rb

@@ -4,12 +4,14 @@ require_relative "dry_swagger"
 require_relative "endpoint_registry"
 require_relative "endpoint"
 require_relative "utils/string_transformations"
+require_relative "sigil"
 
 module Mortymer
   # Include this module in your classes to register
   # and configure your classes as API endpoints.
   module ApiMetadata
     def self.included(base)
+      base.include(Sigil)
       base.extend(ClassMethods)
     end
 
@@ -84,12 +86,22 @@ module Mortymer
         rails_wrap_method_with_no_params_call(method_name, input_class, handlers)
       end
 
-      def rails_wrap_method_with_no_params_call(method_name, input_class, handlers)
+      def rails_wrap_method_with_no_params_call(method_name, _input_class, handlers)
         original_method = instance_method(method_name)
         define_method(method_name) do
-          input = input_class.structify(params.to_unsafe_h.to_h.deep_transform_keys(&:to_sym))
+          # Delegate input handling and checking to Sigil. It will coerce and
+          # validate contracts and structs
+          input = params.to_unsafe_h.to_h.deep_transform_keys(&:to_sym)
           output = original_method.bind_call(self, input)
-          render json: output.to_h, status: :ok
+          # Output might not be validated, so if it is a hash, we will simple
+          # pass it through, otherwise we will call a to_h method
+          if output.respond_to?(:to_h)
+            render json: output.to_h, status: :ok
+          elsif output.respond_to?(:to_json)
+            render json: output.to_json, status: :ok
+          else
+            render json: output, status: :ok
+          end
         rescue StandardError => e
           handler = handlers.find { |h| e.is_a?(h[:exception]) }
           raise unless handler
@@ -105,6 +117,7 @@ module Mortymer
       end
 
       def register_endpoint(http_method, input_class, output_class, path, security)
+        sign input_class, returns: output_class
         @__endpoint_signature__ =
           {
             http_method: http_method,

data/lib/mortymer/configuration.rb

@@ -19,7 +19,7 @@ module Mortymer
   # Global configuration for Mortymer
   class Configuration
     attr_accessor :container, :serve_swagger, :swagger_title, :swagger_path, :swagger_root, :api_version,
-                  :api_description, :security_schemes, :api_prefix
+                  :api_description, :security_schemes, :api_prefix, :openapi_servers
 
     def initialize
       @container = Mortymer::Container.new
@@ -31,6 +31,7 @@ module Mortymer
       @api_version = "v1"
       @security_schemes = {}
       @api_prefix = "/api/v1"
+      @openapi_servers = []
     end
   end
 end

data/lib/mortymer/model.rb

@@ -16,7 +16,15 @@ module Mortymer
     end
 
     def self.structify(params)
-      call(params)
+      if params.instance_of?(self.class)
+        params
+      else
+        call(params)
+      end
+    end
+
+    def [](key)
+      @attributes[key.to_sym]
     end
   end
 end

data/lib/mortymer/openapi_generator.rb

@@ -10,18 +10,20 @@ module Mortymer
     include Utils::StringTransformations
 
     def initialize(prefix: "", title: "Rick on Rails API", version: "v1", description: "", registry: [], # rubocop:disable Metrics/ParameterLists
-                   security_schemes: {})
+                   security_schemes: {}, openapi_servers: [])
       @prefix = prefix
       @title = title
       @version = version
       @description = description
       @endpoints_registry = registry
       @security_schemes = security_schemes
+      @openapi_servers = openapi_servers
     end
 
     def generate
       {
         openapi: "3.0.1",
+        servers: @openapi_servers,
         info: { title: @title, version: @version, description: @description },
         paths: generate_paths,
         components: {

data/lib/mortymer/railtie.rb

@@ -28,7 +28,8 @@ module Mortymer
             version: Mortymer.config.api_version,
             description: Mortymer.config.api_description,
             security_schemes: Mortymer.config.security_schemes,
-            prefix: Mortymer.config.api_prefix
+            prefix: Mortymer.config.api_prefix,
+            openapi_servers: Mortymer.config.openapi_servers
           )
 
           # Save OpenAPI spec to public directory

data/lib/mortymer/sigil.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "types"
+
 module Mortymer
   # Sigil provides symbolic type checking for input and outputs
   # of method calls using dry-types
@@ -19,8 +21,9 @@ module Mortymer
 
       # Hook called when a method is defined
       def method_added(method_name)
-        return super if @pending_type_signature.nil?
-        return super if @processing_type_check
+        super
+        return if @pending_type_signature.nil?
+        return if @processing_type_check
 
         signature = @pending_type_signature
         @pending_type_signature = nil
@@ -79,9 +82,7 @@ module Mortymer
         end
 
         @processing_type_check = false
-
         # Call super to maintain compatibility with other method hooks
-        super
       end
     end
 

data/lib/mortymer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mortymer
-  VERSION = "0.0.11"
+  VERSION = "0.0.12"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mortymer
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.0.12
 platform: ruby
 authors:
 - Adrian Gonzalez
 bindir: exe
 cert_chain: []
-date: 2025-03-31 00:00:00.000000000 Z
+date: 2025-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-struct
@@ -95,6 +95,7 @@ files:
 - docs/guide/models.md
 - docs/guide/mortymer-dependency-injection.md
 - docs/guide/quick-start.md
+- docs/guide/type-system.md
 - docs/index.md
 - lib/mortymer.rb
 - lib/mortymer/api_metadata.rb