muina 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7322acdc8c2503f893db20260a561551cd9cc3350d07ccaa7c0a9b929ce7007
-  data.tar.gz: 29679c640cc94c29860a9237cf82bcd9fcb3c363481dbe214ccbe5b3ac8e5feb
+  metadata.gz: 87250c8fd172242920c2202f5a0bf6de8810d04872c21eb686b40a56262166d2
+  data.tar.gz: 91768a6bb9ed9d3421d330825ff304a57bbb76c3d4b544ab0483cfd69bc5979f
 SHA512:
-  metadata.gz: 3f2fec87c12b2e968d621663781b9e9e079f10fd6bda0e7d9aabadbeadbd01851de54eb1e393def47e63b066a3c0c62dcc1cf5f101e8b33bb68b9c10430c2f02
-  data.tar.gz: 1431602da952ac911732a3284c9a6f73383ddecb20c4b1fe2bb477a970c8724404c6097518a0ee5d8005d10cd631c03a519aebc032173f060af3fc5d4ae4ada8
+  metadata.gz: 0dbbc867a38c6c935678c4bd20f5c3d1412070ac57d6e555edcc48c9b0b36a3a83c94ac488f7ce6d01363585d0ac2154dbc3a81c94a9ba02419a44edcab49d5a
+  data.tar.gz: a20866b554d759d6be67c7926609138867833b7515dfbba39ed145fe76bf867bf7b3554559d8ccd40b9b36998b68fef180ee0671fc6b03bdff7d96a28617766f

data/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+### Added
+* `sorbet-runtime` dependency.
+* Proper documentation in code for `Muina::Maybe` and its subclasses.
+* Strictly typed `Muina::Maybe` and its subclasses.
+* Following sections to the `README`: 
+  * Installation
+  * Documentation
+  * Changelog
+  * Development Standards
+  * Supported Ruby Versions
+  * Contributing
+  * License
+
+
+### Removed
+* `muina` no longer uses `zeitwerk`.
+
+
+## [0.6.0] - 2024-06-08
+### Added
+* `Muina::Maybe#some` alias for `Muina::Maybe#return`.
+* `Muina::Error` as main error class.
+* `Muina::Maybe::UnwrappingError` for `Muina::Maybe::None#value!`.
+
+
+## [0.5.0] - 2024-06-03
+### Added
+* `Muina::Maybe::Some#==`
+* `Muina::Maybe::None#==`
+
+
+## [0.4.0] - 2024-06-02
+### Added
+* `Muina::Result`
+
+
+## [0.3.0] - 2024-06-02
+### Added
+* `Muina::Maybe`
+
+
+## [0.2.1] to [0.2.8] - 2021
+Changelog entries missing.
+
+
+## [0.2.0] - 2021-06-28
+### Added
+* Muina::Action: step based result returning services
+* Muina::Result#{value!,error!,and_then,or_else}: safe and unsafe ways of unwrapping values and errors
+
+### Removed
+* Muina::Result#{value,error}
+
+
+## [0.1.1] - 2021-06-22
+### Fixed
+* Add missing `zeitwerk` dependency to gemspec
+
+
+## [0.1.0] - 2021-06-21
+### Added
+* Muina::Params: self extracting typed params
+* Muina::PrivateCreation: mixin to make `.new` and `.allocate` private
+* Muina::Result: type safe result monad
+* Muina::Service: service object with typesafe constants and attributes
+* Muina::Value: typesafe immutable struct-like objects
+* `muina` CLI: to copy bundled rbi file

data/README.md

@@ -1 +1,45 @@
 # Muina
+[![Gem Version](http://img.shields.io/gem/v/muina.svg)][docs]
+
+`muina` is a gem that provides the `Maybe` monad.
+
+## Installation
+```
+bundle add muina
+```
+
+
+## Documentation
+[https://rubydoc.info/gems/muina][docs]
+
+
+## Changelog
+See [`CHANGELOG.md`](./CHANGELOG.md)
+
+
+## Development Standards
+This project uses several tools to enforce quality standards:
+* This project has no `rubocop` offenses and uses the style defined by
+  `rubocop-vaporyhumo`.
+* This project has `100%` test coverage.
+* This project has `100%` mutation test coverage.
+* This project has no significant code duplication.
+* This project is strictly typed using `sorbet`.
+
+
+## Supported Ruby Versions
+This gem supports Ruby `3.1` and newer versions.
+
+
+## Contributing
+If you find any issues with the documentation or encounter any unexpected errors
+please open a GitHub Issue in the repository.
+
+This project does not accept code contributions.
+
+
+## License
+See [`LICENSE`](./LICENSE)
+
+
+[docs]: https://rubygems.org/gems/muina

data/lib/muina/maybe/none.rb

@@ -1,65 +1,130 @@
+# typed: strict
 # frozen_string_literal: true
 
 module Muina
   class Maybe
+    # rubocop:disable Metrics/ClassLength
+
     class None < self
+      class << self
+        undef_method :some
+        undef_method :none
+      end
+
+      Elem = type_member
+      ElemT = type_template { { upper: Object } }
+
       private_class_method(:new)
-      def initialize
+      sig { void }
+      def initialize # rubocop:disable Lint/MissingSuper
         freeze
       end
 
+      sig { override.returns T::Boolean }
+      # (see Maybe#some?)
       def some?
         false
       end
 
+      sig { override.returns T::Boolean }
+      # (see Maybe#none?)
       def none?
         true
       end
 
+      sig { override.returns Elem }
+      # (see Maybe#value!)
       def value!
-        raise
+        raise UnwrappingError
       end
 
+      sig do
+        override.type_parameters(:Default)
+                .params(default: T.type_parameter(:Default))
+                .returns(T.any(Elem, T.type_parameter(:Default)))
+      end
+      # (see Maybe#value_or)
       def value_or(default)
         default
       end
 
-      def value_or_yield
+      sig do
+        override.type_parameters(:T)
+                .params(_blk: T.proc.returns(T.type_parameter(:T)))
+                .returns(T.any(Elem, T.type_parameter(:T)))
+      end
+      # (see Maybe#value_or_yield)
+      def value_or_yield(&_blk)
         yield
       end
 
-      def value_or_nil
-        nil
-      end
+      sig { override.returns(T.any(Elem, NilClass)) }
+      # (see Maybe#value_or_nil)
+      def value_or_nil; end
 
-      def and_then
+      sig { override.params(_blk: T.untyped).returns(T.self_type) }
+      # (see Maybe#and_then)
+      def and_then(&_blk)
         self
       end
 
-      def or_else
+      sig { override.params(_blk: T.untyped).returns(T.self_type) }
+      # (see Maybe#or_else)
+      def or_else(&_blk)
         yield
         self
       end
 
-      def map
+      sig do
+        override.type_parameters(:T)
+                .params(
+                  _blk: T.proc.params(arg0: Elem).returns(T.type_parameter(:T))
+                )
+                .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+      end
+      # (see Maybe#map)
+      def map(&_blk)
         self
       end
 
-      def map_none
+      sig do
+        override.type_parameters(:T)
+                .params(_blk: T.proc.returns(T.type_parameter(:T)))
+                .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+      end
+      # (see Maybe#map_none)
+      def map_none(&_blk)
         Maybe.return yield
       end
 
-      def bind
+      sig do
+        override.type_parameters(:T)
+                .params(
+                  _blk: T.proc.params(arg0: Elem).returns(Maybe[T.type_parameter(:T)])
+                )
+                .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+      end
+      # (see Maybe#bind)
+      def bind(&_blk)
         self
       end
 
-      def bind_none
+      sig do
+        override.type_parameters(:T)
+                .params(_blk: T.proc.returns(Maybe[T.type_parameter(:T)]))
+                .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+      end
+      # (see Maybe#bind_none)
+      def bind_none(&_blk)
         yield
       end
 
+      sig { override.params(other: T.untyped).returns(T::Boolean) }
+      # (see Maybe#==)
       def ==(other)
-        self.class == other.class
+        other.instance_of?(self.class)
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/muina/maybe/some.rb

@@ -1,67 +1,134 @@
+# typed: strict
 # frozen_string_literal: true
 
 module Muina
   class Maybe
+    # rubocop:disable Metrics/ClassLength
+
     class Some < self
-      def initialize(value)
+      class << self
+        undef_method :some
+        undef_method :none
+      end
+
+      Elem = type_member { { upper: Object } }
+      ElemT = type_template { { upper: Object } }
+
+      private_class_method(:new)
+      sig { params(value: Elem).void }
+      def initialize(value) # rubocop:disable Lint/MissingSuper
         @value = value
         freeze
       end
-      private_class_method(:new)
 
+      # (see Maybe#some?)
+      sig { override.returns T::Boolean }
       def some?
         true
       end
 
+      sig { override.returns T::Boolean }
+      # (see Maybe#none?)
       def none?
         false
       end
 
+      sig { override.returns Elem }
+      # (see Maybe#value!)
       def value!
         @value
       end
 
-      def value_or(default)
+      # (see Maybe#value_or)
+      sig do
+        override.type_parameters(:Default)
+                .params(_default: T.type_parameter(:Default))
+                .returns(T.any(Elem, T.type_parameter(:Default)))
+      end
+      def value_or(_default)
         @value
       end
 
-      def value_or_yield
+      sig do
+        override.type_parameters(:T)
+                .params(_blk: T.proc.returns(T.type_parameter(:T)))
+                .returns(T.any(Elem, T.type_parameter(:T)))
+      end
+      # (see Maybe#value_or_yield)
+      def value_or_yield(&_blk)
         @value
       end
 
+      sig { override.returns(T.any(Elem, NilClass)) }
+      # (see Maybe#value_or_nil)
       def value_or_nil
         @value
       end
 
-      def and_then
+      sig { override.params(_blk: T.untyped).returns(T.self_type) }
+      # (see Maybe#and_then)
+      def and_then(&_blk)
         yield(@value)
         self
       end
 
-      def or_else
+      sig { override.params(_blk: T.untyped).returns(T.self_type) }
+      # (see Maybe#or_else)
+      def or_else(&_blk)
         self
       end
 
-      def map
+      sig do
+        override.type_parameters(:T)
+                .params(
+                  _blk: T.proc.params(arg0: Elem).returns(T.type_parameter(:T))
+                )
+                .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+      end
+      # (see Maybe#map)
+      def map(&_blk)
         Maybe.return yield(@value)
       end
 
-      def map_none
+      sig do
+        override.type_parameters(:T)
+                .params(_blk: T.proc.returns(T.type_parameter(:T)))
+                .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+      end
+      # (see Maybe#map_none)
+      def map_none(&_blk)
         self
       end
 
-      def bind
+      sig do
+        override.type_parameters(:T)
+                .params(
+                  _blk: T.proc.params(arg0: Elem).returns(Maybe[T.type_parameter(:T)])
+                )
+                .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+      end
+      # (see Maybe#bind)
+      def bind(&_blk)
         yield(@value)
       end
 
-      def bind_none
+      sig do
+        override.type_parameters(:T)
+                .params(_blk: T.proc.returns(Maybe[T.type_parameter(:T)]))
+                .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+      end
+      # (see Maybe#bind_none)
+      def bind_none(&_blk)
         self
       end
 
+      sig { override.params(other: T.untyped).returns(T::Boolean) }
+      # (see Maybe#==)
       def ==(other)
         self.class == other.class &&
-          self.value! == other.value!
+          value! == other.value!
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/muina/maybe.rb

@@ -1,13 +1,203 @@
+# typed: strict
 # frozen_string_literal: true
 
 module Muina
+  # rubocop:disable Metrics/ClassLength
+
+  # @abstract
+  # @param [Elem] elem the type of element maybe contained inside the monad
   class Maybe
-    def self.return(value)
-      Some.__send__(:new, value)
+    extend T::Sig
+    extend T::Helpers
+    extend T::Generic
+
+    # Raised when trying to unwrap a {None} value
+    UnwrappingError = Class.new(Error)
+
+    Elem = type_member
+    ElemT = type_template { { upper: Object } }
+
+    abstract!
+
+    class << self
+      extend T::Sig
+
+      sig { params(value: ElemT).returns(Maybe::Some[ElemT]) }
+      # Returns a {Maybe::Some} wrapping the provided value.
+      #
+      # @param [Elem] value a value to wrap around a {Some} variant.
+      # @return [Some<Elem>]
+      def return(value)
+        Some.__send__(:new, T.unsafe(value))
+      end
+      alias some return
+
+      sig { returns(Maybe::None[NilClass]) }
+      # Returns a {Maybe::None}, a safer alternative to +nil+.
+      #
+      # @return [None]
+      def none
+        None.__send__(:new)
+      end
+    end
+
+    sig { abstract.returns T::Boolean }
+    # Returns +true+ if instance is of the {Some} variant, or +false+ if it is
+    # of the {None} variant.
+    #
+    # @return [true] if instance is of the {Some} variant
+    # @return [false] if instance is of the {None} variant
+    def some?
+    end
+
+    sig { abstract.returns T::Boolean }
+    # Returns +true+ if instance is of the {None} variant, or +false+ if it is
+    # of the {Some} variant.
+    #
+    # @return [true] if instance is of the {None} variant
+    # @return [false] if instance is of the {Some} variant
+    def none?
+    end
+
+    sig { abstract.returns Elem }
+    # Returns the contained value if instance is of the {Some} variant, or
+    # raises {UnwrappingError} if it is of the {None} variant.
+    #
+    # @return [Elem]
+    # @raise [UnwrappingError] if instance is of the {None} variant
+    def value!
+    end
+
+    sig do
+      abstract.type_parameters(:Default)
+              .params(default: T.type_parameter(:Default))
+              .returns(T.any(Elem, T.type_parameter(:Default)))
+    end
+    # Returns the contained value if instance is of the {Some} variant, or the
+    # provided +default+ value if it is of the {None} variant.
+    #
+    # @param [Object] default the value to be used if the instance is of the
+    #   {None} variant
+    # @return [Elem, Object]
+    def value_or(default)
+    end
+
+    sig do
+      abstract.type_parameters(:T)
+              .params(blk: T.proc.returns(T.type_parameter(:T)))
+              .returns(T.any(Elem, T.type_parameter(:T)))
+    end
+    # Returns the contained value if instance is of the {Some} variant, or runs
+    # the provided block and returns its result if it is of the {None} variant.
+    #
+    # @yieldreturn [Object]
+    # @return [Elem, yield]
+    def value_or_yield(&blk)
     end
 
-    def self.none
-      None.__send__(:new)
+    sig { abstract.returns(T.any(Elem, NilClass)) }
+    # Returns the contained value if instance is of the {Some} variant, or +nil+
+    # if it is of the {None} variant.
+    #
+    # @return [Elem, nil]
+    def value_or_nil
+    end
+
+    sig { abstract.params(_blk: T.untyped).returns(T.self_type) }
+    # Runs the provided block only if instance is of the {Some} variant,
+    # yielding the contained value.
+    # Always returns +self+.
+    #
+    # @yieldparam value [Elem] the contained value is passed to the block
+    # @return [self]
+    def and_then(&_blk)
+    end
+
+    sig { abstract.params(_blk: T.untyped).returns(T.self_type) }
+    # Runs the provided block only if instance is of the {None} variant,
+    # yielding no value to the block.
+    # Always returns +self+.
+    #
+    # @yield []
+    # @return [self]
+    def or_else(&_blk)
+    end
+
+    sig do
+      abstract.type_parameters(:T)
+              .params(
+                _blk: T.proc.params(arg0: Elem).returns(T.type_parameter(:T))
+              )
+              .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+    end
+    # If instance is of the {Some} variant, it passes the contained value to the
+    # block and returns a new {Some} instance containing the return value of the
+    # block; if instance is of the {None} variant, it returns itself.
+    #
+    # @yieldparam value [Elem] the contained value is passed to the block
+    # @yieldreturn [Object]
+    # @return [Maybe<yield>, None]
+    def map(&_blk)
+    end
+
+    sig do
+      abstract.type_parameters(:T)
+              .params(blk: T.proc.returns(T.type_parameter(:T)))
+              .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+    end
+    # If instance is of the {Some} variant, it returns itself; if instance is of
+    # the {None} variant it runs the block and returns a new {Some} instance
+    # containing the return value of the block.
+    #
+    # @yield []
+    # @yieldreturn [Object]
+    # @return [Maybe<yield>, self]
+    def map_none(&blk)
+    end
+
+    sig do
+      abstract.type_parameters(:T)
+              .params(
+                _blk: T.proc.params(arg0: Elem).returns(Maybe[T.type_parameter(:T)])
+              )
+              .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+    end
+    # If instance is of the {Some} variant, it yields the contained value to the
+    # block and it returns the return value of the block; if it is of the {None}
+    # variant, it returns itself.
+    #
+    # @yieldparam value [Elem] the contained value is passed to the block
+    # @yieldreturn [Maybe]
+    # @return [Maybe]
+    def bind(&_blk)
+    end
+
+    sig do
+      abstract.type_parameters(:T)
+              .params(blk: T.proc.returns(Maybe[T.type_parameter(:T)]))
+              .returns(T.any(Maybe[Elem], Maybe[T.type_parameter(:T)]))
+    end
+    # If instance is of the {None} variant, it runs the provided block and it
+    # returns its return value; if it is of the {Some} variant, it returns
+    # itself.
+    #
+    # @yield []
+    # @yieldreturn [Maybe]
+    # @return [Maybe]
+    def bind_none(&blk)
+    end
+
+    sig { abstract.params(other: T.untyped).returns(T::Boolean) }
+    # Returns +true+ if both instances are of the same variant, and the
+    # contained values are equal in the case of {Some}.
+    #
+    # @param [Maybe<Elem>] other
+    # @return [Boolean]
+    def ==(other)
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end
+
+require_relative 'maybe/some'
+require_relative 'maybe/none'

data/lib/muina/result/failure.rb

@@ -3,7 +3,7 @@
 module Muina
   class Result
     class Failure < self
-      def initialize(error)
+      def initialize(error) # rubocop:disable Lint/MissingSuper
         @error = error
         freeze
       end

data/lib/muina/result/success.rb

@@ -3,7 +3,7 @@
 module Muina
   class Result
     class Success < self
-      def initialize(value)
+      def initialize(value) # rubocop:disable Lint/MissingSuper
         @value = value
         freeze
       end

data/lib/muina/result.rb

@@ -13,3 +13,6 @@ module Muina
     end
   end
 end
+
+require_relative 'result/success'
+require_relative 'result/failure'

data/lib/muina/version.rb

@@ -1,6 +1,8 @@
+# typed: strict
 # frozen_string_literal: true
 
 module Muina
-  VERSION = '0.5.0'
+  # Gem version
+  VERSION = '0.7.0'
   public_constant :VERSION
 end

data/lib/muina.rb

@@ -1,10 +1,12 @@
+# typed: strict
 # frozen_string_literal: true
 
-require 'zeitwerk'
-loader = Zeitwerk::Loader.for_gem
-loader.setup
+require 'sorbet-runtime'
 
 module Muina
+  # Top level error class for {Muina}
+  Error = Class.new(StandardError)
 end
 
-loader.eager_load
+require_relative 'muina/maybe'
+require_relative 'muina/result'

metadata

@@ -1,36 +1,79 @@
 --- !ruby/object:Gem::Specification
 name: muina
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
-- vaporyhumo
+- rodrigovilina
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-03 00:00:00.000000000 Z
+date: 2024-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: zeitwerk
+  name: sorbet-runtime
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
-description: Monads and other stuff to help you write safer Ruby code
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: lollipop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-vaporyhumo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+description: Monads and other stuff to help you write safer Ruby code.
 email:
 - roanvilina@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/muina.rb
@@ -41,12 +84,12 @@ files:
 - lib/muina/result/failure.rb
 - lib/muina/result/success.rb
 - lib/muina/version.rb
-homepage: https://github.com/vaporyhumo/muina
+homepage: https://github.com/rodrigovilina/muina
 licenses:
 - Unlicense
 metadata:
-  homepage_uri: https://github.com/vaporyhumo/muina
-  changelog_uri: https://github.com/vaporyhumo/muina/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/rodrigovilina/muina
+  changelog_uri: https://github.com/rodrigovilina/muina/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -63,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.7
+rubygems_version: 3.5.15
 signing_key:
 specification_version: 4
 summary: Write safer Ruby code.