mortymer 0.0.2

data/docs/guide/quick-start.md

@@ -0,0 +1,190 @@
+# Quick Start
+
+This guide will help you get started with Mortymer in just a few minutes.
+We'll create a simple API endpoint that demonstrates the core features of Mortymer
+by integrating it in a Rails API, let's call it Rails and Mortymer.
+
+## Basic Setup
+
+First, let's create a new Rails application (skip this if you already have one):
+
+```bash
+rails new my_api --api
+cd my_api
+```
+
+## Installation
+
+Add Mortymer to your Gemfile:
+
+```ruby
+gem 'morty'
+```
+
+Then install it:
+
+```bash
+bundle install
+```
+
+Mortymer requires that every class is autoloaded for it to work. This is deafault rails
+behavior when running in production, but it is disabled by default on development, so,
+we first need to enable eager load
+
+```ruby
+# config/environments/development.rb
+Rails.application.configure do
+  # Settings specified here will take precedence over those in config/application.rb.
+
+  config.eager_load = true # This line is false by default, change it to true
+
+  # other configs hers ...
+end
+```
+
+In rails environments, Mortymer can automatically create the routes for you, it is not necessary
+that you register them one by one.
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  Mortymer::Rails::Routes.new(self).mount_controllers
+end
+```
+
+## Creating Your First API
+
+Let's build a simple book API to demonstrate Mortymer's key features.
+
+### 1. Define Your Type
+
+Create a Book type that defines the structure of your data:
+
+```ruby
+# app/types/book.rb
+class Book < Mortymer::Model
+  attribute :id, Integer
+  attribute :title, String
+  attribute :author, String
+  attribute :published_year, Integer
+end
+```
+
+### 2. Create a Service
+
+Create a service to handle business logic:
+
+```ruby
+# app/services/book_service.rb
+class BookService
+  def initialize
+    @books = []
+  end
+
+  def create_book(title:, author:, published_year:)
+    book = Book.new(
+      id: next_id,
+      title: title,
+      author: author,
+      published_year: published_year
+    )
+    @books << book
+    book
+  end
+
+  def list_books
+    @books
+  end
+
+  private
+
+  def next_id
+    @books.length + 1
+  end
+end
+```
+
+### 3. Create a Controller
+
+Set up your API controller with Mortymer's features:
+
+```ruby
+# app/controllers/api/books_controller.rb
+module Api
+  class BooksController < ApplicationController
+    inject BookService, as: :books
+
+    class Empty < Mortymer::Model
+    end
+
+    class ListAllBooksOutput < Mortymer::Model
+      attribute :books, Array.of(Book)
+    end
+
+    class CreateBookInput < Mortymer::Model
+      attribute :title, String
+      attribute :author, String
+      attribute :published_year, Coercible::Integer
+    end
+
+    # GET /api/books
+    get input: Empty, output: ListAllBooksOutput
+    def list_all_books(_params)
+      ListAllBooksOutput.new(books: @books.list_books)
+    end
+
+    # POST /api/books
+    post input: CreateBookInput, output: Book
+    def create_book(params)
+      @books.create_book(
+        title: params.title,
+        author: params.author,
+        published_year: params.published_year
+      )
+    end
+  end
+end
+```
+
+## Testing Your API
+
+Start your Rails server:
+
+```bash
+rails server
+```
+
+Create a new book:
+
+```bash
+curl -X POST http://localhost:3000/api/books \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "The Ruby Way",
+    "author": "Hal Fulton",
+    "published_year": 2015
+  }'
+```
+
+List all books:
+
+```bash
+curl http://localhost:3000/api/books
+```
+
+## Key Features Demonstrated
+
+This simple example showcases several of Mortymer's powerful features:
+
+- ✨ **Type System**: Strong typing with `Mortymer::Models` which are powered by `Dry::Struct`
+- 🔌 **Dependency Injection**: Clean service injection with `inject :book_service`
+- ✅ **Parameter Validation**: Built-in request validation in controllers
+
+## Next Steps
+
+Now that you have a basic understanding of Mortymer, you might want to explore:
+
+- [Type System](./type-system.md) - Learn more about Mortymer's type system
+- [Dependency Injection](./dependency-injection.md) - Deep dive into DI patterns
+- [Controllers](./controllers.md) - Advanced controller features
+- [API Metadata](./api-metadata.md) - API documentation capabilities

data/docs/index.md

@@ -0,0 +1,26 @@
+---
+home: true
+layout: home
+
+hero:
+  name: "Morty"
+  text: "Modern Ruby API Development"
+  tagline: Build type-safe, documented, and maintainable APIs using the ruby ecosystem you love.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/introduction
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/yourusername/morty
+
+features:
+  - title: Type Safety
+    details: Built-in type validation and schema generation using dry-types
+  - title: OpenAPI Documentation
+    details: Automatic OpenAPI (Swagger) documentation generation from your code
+  - title: Rails Integration
+    details: Seamless integration with Ruby on Rails for robust API development
+  - title: Dependency Injection
+    details: Clean and testable code with built-in dependency injection support
+---

data/lib/mortymer/api_metadata.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "dry_swagger"
+require_relative "endpoint_registry"
+require_relative "endpoint"
+require_relative "utils/string_transformations"
+
+module Mortymer
+  # Include this module in your classes to register
+  # and configure your classes as API endpoints.
+  module ApiMetadata
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # The DSL
+    module ClassMethods
+      def get(input:, output:, path: nil)
+        register_endpoint(:get, input, output, path)
+      end
+
+      def post(input:, output:, path: nil)
+        register_endpoint(:post, input, output, path)
+      end
+
+      def put(input:, output:, path: nil)
+        register_endpoint(:put, input, output, path)
+      end
+
+      def delete(input:, output:, path: nil)
+        register_endpoint(:delete, input, output, path)
+      end
+
+      private
+
+      def method_added(method_name)
+        super
+        return unless @__endpoint_signature__
+
+        EndpointRegistry.registry << Endpoint.new(**@__endpoint_signature__.merge(
+          name: reflect_method_name(method_name), action: method_name
+        ))
+        input_class = @__endpoint_signature__[:input_class]
+        @__endpoint_signature__ = nil
+        return unless defined?(::Rails) && ::Rails.application.config.morty.wrap_methods
+
+        rails_wrap_method_with_no_params_call(method_name, input_class)
+      end
+
+      def rails_wrap_method_with_no_params_call(method_name, input_class)
+        original_method = instance_method(method_name)
+        define_method(method_name) do
+          input = input_class.new(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
+        end
+      end
+
+      def register_endpoint(http_method, input_class, output_class, path)
+        @__endpoint_signature__ =
+          {
+            http_method: http_method,
+            input_class: input_class,
+            output_class: output_class,
+            path: path,
+            controller_class: self
+          }
+      end
+
+      def reflect_method_name(method_name)
+        if %i[call execute].include?(method_name)
+          name
+        else
+          "#{name}##{method_name}"
+        end
+      end
+    end
+  end
+end

data/lib/mortymer/container.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Mortymer
+  # Base container for dependency injection
+  class Container
+    class Error < StandardError; end
+    class DependencyError < Error; end
+    class NotFoundError < Error; end
+
+    class << self
+      # Initialize the container storage
+      def registry
+        @registry ||= {}
+      end
+
+      # Register a constant with its implementation
+      # @param constant [Class] The constant to register
+      # @param implementation [Object] The implementation to register
+      def register_constant(constant, implementation = nil, &block)
+        key = constant_to_key(constant)
+        registry[key] = block || implementation
+      end
+
+      # Resolve a constant to its implementation
+      # @param constant [Class] The constant to resolve
+      # @param resolution_stack [Array] Stack of constants being resolved to detect cycles
+      # @return [Object] The resolved implementation
+      def resolve_constant(constant, resolution_stack = []) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+        key = constant_to_key(constant)
+
+        # Check for circular dependencies
+        if resolution_stack.include?(key)
+          raise DependencyError, "Circular dependency detected: #{resolution_stack.join(" -> ")} -> #{key}"
+        end
+
+        # Return cached instance if available
+        return registry[key] if registry[key] && !registry[key].is_a?(Class) && !registry[key].is_a?(Proc)
+
+        implementation = registry[key]
+
+        # If not registered, try to resolve the constant from string/symbol
+        if !implementation && (constant.is_a?(String) || constant.is_a?(Symbol))
+          begin
+            const_name = constant.to_s
+            implementation = Object.const_get(const_name)
+            registry[key] = implementation
+          rescue NameError
+            raise NotFoundError, "No implementation found for #{key}"
+          end
+        end
+
+        # If not registered, try to auto-resolve the constant if it's a class
+        if !implementation && constant.is_a?(Class)
+          implementation = constant
+          registry[key] = implementation
+        end
+
+        raise NotFoundError, "No implementation found for #{key}" unless implementation
+
+        # Add current constant to resolution stack
+        resolution_stack.push(key)
+
+        result = resolve_implementation(implementation, key, resolution_stack)
+
+        resolution_stack.pop
+        result
+      end
+
+      private
+
+      # Resolve the actual implementation
+      def resolve_implementation(implementation, key, resolution_stack)
+        case implementation
+        when Proc
+          result = instance_exec(&implementation)
+          registry[key] = result
+          result
+        when Class
+          resolve_class(implementation, key, resolution_stack)
+        else
+          implementation
+        end
+      end
+
+      # Resolve a class implementation with its dependencies
+      def resolve_class(klass, key, resolution_stack)
+        instance = if klass.respond_to?(:dependencies)
+                     inject_dependencies(klass, resolution_stack)
+                   else
+                     klass.new
+                   end
+        registry[key] = instance
+        instance
+      end
+
+      # Inject dependencies into a new instance
+      def inject_dependencies(klass, resolution_stack)
+        deps = klass.dependencies.map do |dep|
+          { var_name: dep[:var_name], value: resolve_constant(dep[:constant], resolution_stack.dup) }
+        end
+
+        instance = klass.new
+        deps.each do |dep|
+          instance.instance_variable_set("@#{dep[:var_name]}", dep[:value])
+        end
+        instance
+      end
+
+      # Convert a constant to a container registration key
+      # @param constant [Class] The constant to convert
+      # @return [String] The container registration key
+      def constant_to_key(constant)
+        key = if constant.is_a?(String) || constant.is_a?(Symbol)
+                constant.to_s
+              else
+                constant.name
+              end
+        Utils::StringTransformations.underscore(key.split("::").join("_"))
+      end
+    end
+  end
+end

data/lib/mortymer/dependencies_dsl.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "utils/string_transformations"
+
+module Mortymer
+  # A simple dsl to declare class dependencies for injection
+  module DependenciesDsl
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+      base.prepend(
+        Module.new do
+          def initialize(*args, **kwargs)
+            send(:inject_dependencies, kwargs)
+            super(*args, **kwargs)
+          end
+        end
+      )
+    end
+
+    # Included module class methods
+    module ClassMethods
+      # Store dependencies for the class
+      def dependencies
+        @dependencies ||= []
+      end
+
+      # Declare a dependency
+      # @param constant [Class] The constant to inject
+      # @param as: [Symbol] The instance variable name
+      def inject(constant, as: nil)
+        var_name = (as || infer_var_name(constant)).to_s
+        dependencies << { constant: constant, var_name: var_name }
+      end
+
+      private
+
+      # Infer the instance variable name from the constant
+      def infer_var_name(constant)
+        Utils::StringTransformations.underscore(constant.name.split("::").last)
+      end
+    end
+
+    # Included module instance methods
+    module InstanceMethods
+      private
+
+      # Inject all declared dependencies
+      # @param overrides [Hash] Optional dependency overrides for named dependencies
+      def inject_dependencies(overrides = {})
+        self.class.dependencies.each do |dep|
+          value = if overrides.key?(dep[:var_name].to_sym)
+                    overrides[dep[:var_name].to_sym]
+                  else
+                    Container.resolve_constant(dep[:constant])
+                  end
+
+          instance_variable_set("@#{dep[:var_name]}", value)
+        rescue Container::NotFoundError => e
+          raise Container::DependencyError, "Failed to inject dependency #{dep[:constant]}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/mortymer/dry_swagger.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "dry_struct_parser/struct_schema_parser"
+require "dry_validation_parser/validation_schema_parser"
+require "dry/swagger/documentation_generator"
+require "dry/swagger/errors/missing_hash_schema_error"
+require "dry/swagger/errors/missing_type_error"
+require "dry/swagger/config/configuration"
+require "dry/swagger/config/swagger_configuration"
+require "dry/swagger/railtie" if defined?(Rails)

data/lib/mortymer/endpoint.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Mortymer
+  # Represents an endpoint in a given system
+  class Endpoint
+    attr_reader :http_method, :path, :input_class, :output_class, :controller_class, :action, :name
+
+    def initialize(opts = {})
+      @http_method = opts[:http_method]
+      @input_class = opts[:input_class]
+      @output_class = opts[:output_class]
+      @name = opts[:name]
+      @path = opts[:path] || infer_path_from_class
+      @controller_class = opts[:controller_class]
+      @action = opts[:action]
+    end
+
+    def routeable?
+      [@input_class, @http_method, @output_class, @path].none?(&:nil?)
+    end
+
+    def api_name
+      Utils::StringTransformations.underscore(name.gsub("::", "/")).gsub(/_endpoint$/, "").split("#").first
+    end
+
+    def controller_name
+      Utils::StringTransformations.underscore(@name.split("#").first.split("::").join("/"))
+    end
+
+    def infer_path_from_class
+      # Remove 'Endpoint' suffix if present and convert to path
+      "/" + @name.split("#").first.split("::").map do |s|
+        Utils::StringTransformations.underscore(s).gsub(/_endpoint$/, "").gsub(/_controller$/, "")
+      end.join("/")
+    end
+
+    def generate_openapi_schema # rubocop:disable Metrics/MethodLength
+      return unless defined?(@input_class) && defined?(@output_class)
+
+      input_schema = Dry::Swagger::DocumentationGenerator.new.from_struct(@input_class)
+      responses = {
+        "200" => {
+          description: "Successful response",
+          content: {
+            "application/json" => {
+              schema: class_ref(@output_class)
+            }
+          }
+        }
+      }
+
+      # Add 422 response if there are required properties or non-string types that need coercion
+      if validations?(input_schema)
+        responses["422"] = {
+          description: "Validation Failed - Invalid parameters or coercion error",
+          content: {
+            "application/json": {
+              schema: error422_ref
+            }
+          }
+        }
+      end
+
+      {
+        path.to_s => {
+          http_method.to_s => {
+            operation_id: operation_id,
+            parameters: generate_parameters,
+            requestBody: generate_request_body,
+            responses: responses
+          }
+        }
+      }
+    end
+
+    private
+
+    def validations?(schema)
+      return false unless schema
+
+      # Check if there are any required properties
+      has_required = schema[:required]&.any?
+
+      # Check if there are any properties that need type coercion (non-string types)
+      has_coercions = schema[:properties]&.any? do |_, property|
+        type = property[:type]
+        type && type != "string" # Any non-string type will need coercion
+      end
+
+      has_required || has_coercions
+    end
+
+    def generate_parameters
+      return [] unless @input_class && %i[get delete].include?(@http_method)
+
+      schema = Dry::Swagger::DocumentationGenerator.new.from_struct(@input_class)
+      schema[:properties]&.map do |name, property|
+        {
+          name: name,
+          in: "query",
+          schema: property,
+          required: schema[:required]&.include?(name)
+        }
+      end || []
+    end
+
+    def generate_request_body
+      return unless @input_class && %i[post put].include?(@http_method)
+
+      {
+        required: true,
+        content: {
+          "application/json" => {
+            schema: class_ref(@input_class)
+          }
+        }
+      }
+    end
+
+    def class_ref(klass)
+      { "$ref": "#/components/schemas/#{klass.name.split("::").last}" }
+    end
+
+    def error422_ref
+      { "$ref": "#/components/schemas/Error422" }
+    end
+
+    def operation_id
+      names_map = {
+        post: :create,
+        put: :update,
+        delete: :destroy,
+        get: :get
+      }
+
+      "#{names_map[@http_method]}_#{controller_name.split("/").last.gsub(/_controller$/, "")}"
+    end
+  end
+end

data/lib/mortymer/endpoint_registry.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mortymer
+  # A global registry of all defined endpoints
+  class EndpointRegistry
+    class << self
+      def registry
+        @registry ||= []
+      end
+
+      def get_matcher(path, method)
+        @registry.find { |e| e.path.to_s == path.to_s && e.http_method.to_s == method.to_s }
+      end
+    end
+  end
+end

data/lib/mortymer/model.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Mortymer
+  # A base model for defining schemas
+  class Model < Dry::Struct
+    include Dry.Types()
+  end
+end