typed_operation 1.0.0.pre1 → 1.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff925e2cc5ce03a696a209e0ca61130bff94ddb6ce28f2670ebaaae18f1968ba
-  data.tar.gz: b14a0952694653f918135a57180c8c7746aeffcb14385d17aeef7a1283726e99
+  metadata.gz: 1337560f2bffbfd45574c1df5f007c951dba43293324c309c3409aab18e57f0c
+  data.tar.gz: 63deedbca3cde1fadb88668af46ec21652e17f9600d23c0e13c8b22429c05e0c
 SHA512:
-  metadata.gz: 0cb23aed491058bdefba04d75661ec4cb5110a2491ba9d4b3afc929d41e1863a09b9ac09b41bdbd6306856af6d5552f2c86c3057b53df3076d0674a9c1feafda
-  data.tar.gz: 143f6ba5a00d5cabadec3f7f326dc7a724fdd2666ca0dffa326cacf9f9af2f4dce797f77a727468cd919eb42a4b6de530105d6866e49797997c10ff5a36db9fe
+  metadata.gz: 0a8fdc89c772282de6c654365e18d7397532b84aebd738285499998c04c32906dc1e63961f5b47d139dfff532a458461dbe07a29bdfcda9f29d8132d645599df
+  data.tar.gz: cee03eb2c1e2d9100e657d98a1b70f6889b0e276251dd839f343586ff89f17287853224a487357343fc421ff6723686a2bf672c7ad53a058246668bb1d80a926

data/README.md

@@ -92,6 +92,8 @@ shelve.call(author_id: "1", isbn: false)
 
 ### Partially applying parameters
 
+Operations can also be partially applied and curried:
+
 ```ruby
 class TestOperation < ::TypedOperation::Base
   param :foo, String, positional: true
@@ -151,9 +153,14 @@ TestOperation.with("1").with(bar: "2").with(baz: 3).operation
 
 ## Documentation
 
-### Create an operation (subclass `TypedOperation::Base`)
+### Create an operation (subclass `TypedOperation::Base` or `TypedOperation::ImmutableBase`)
+
+Create an operation by subclassing `TypedOperation::Base` or `TypedOperation::ImmutableBase` and specifying the parameters the operation requires.
 
-Create an operation by subclassing `TypedOperation::Base` and specifying the parameters the operation requires.
+- `TypedOperation::Base` (uses `Literal::Struct`) is the parent class for an operation where the arguments are potentially mutable (ie not frozen).
+  No attribute writer methods are defined, so the arguments can not be changed after initialization, but the values passed in are not guaranteed to be frozen.
+- `TypedOperation::ImmutableBase` (uses `Literal::Data`) is the parent class for an operation where the arguments are immutable (frozen on initialization),
+  thus giving a somewhat stronger immutability guarantee (ie that the operation does not mutate its arguments).
 
 The subclass must implement the `#call` method which is where the operations main work is done.
 
@@ -161,11 +168,41 @@ The operation can also implement:
 
 - `#prepare` - called when the operation is initialized, and after the parameters have been set
 
+
 ### Specifying parameters (using `.param`)
 
 Parameters are specified using the provided class methods (`.positional_param` and `.named_param`), 
 or using the underlying `.param` method.
 
+Types are specified using the `literal` gem. In many cases this simply means providing the class of the
+expected type, but there are also some other useful types provided by `literal` (eg `Union`).
+
+These can be either accessed via the `Literal` module, eg `Literal::Types::BooleanType`:
+
+```ruby
+class MyOperation < ::TypedOperation::Base
+  param :name, String
+  param :age, Integer, optional: true
+  param :choices, Literal::Types::ArrayType.new(String)
+  param :chose, Literal::Types::BooleanType
+end
+
+MyOperation.new(name: "bob", choices: ["st"], chose: true)
+```
+
+or by including the `Literal::Types` module into your operation class, and using the aliases provided:
+
+```ruby
+class MyOperation < ::TypedOperation::Base
+  include Literal::Types
+  
+  param :name, String
+  param :age, _Nilable(Integer) # optional can also be specifed using `.optional`
+  param :choices, _Array(String)
+  param :chose, _Boolean
+end
+```
+
 Type constraints can be modified to make the parameter optional using `.optional`.
 
 #### Your own aliases
@@ -319,7 +356,7 @@ You can specify a block after a parameter definition to coerce the argument valu
 
 ```ruby
 param :name, String, &:to_s
-param :choice, Union(FalseClass, TrueClass) do |v|
+param :choice, Literal::Types::BooleanType do |v|
   v == "y"
 end
 ```
@@ -498,28 +535,27 @@ class MyOperation < ::TypedOperation::Base
 
   def call
     create_account.bind do |account|
-      associate_owner(account).bind do
-        account
-      end
+      associate_owner(account).map { account }
     end
   end
 
   private
 
   def create_account
-    # returns Literal::Success(account) or Literal::Failure(:cant_create)
+    # ...
+    # Literal::Failure.new(:cant_create_account)
     Literal::Success.new(account_name)
   end
   
   def associate_owner(account)
     # ...
     Literal::Failure.new(:cant_associate_owner)
+    # Literal::Success.new("ok")
   end
 end
 
 MyOperation.new(account_name: "foo", owner: "bar").call
 # => Literal::Failure(:cant_associate_owner)
-
 ```
 
 ### Using with `Dry::Monads`

data/Rakefile

@@ -1,3 +1,17 @@
-require "bundler/setup"
+# frozen_string_literal: true
 
 require "bundler/gem_tasks"
+require "bundler/setup"
+require "rake/testtask"
+
+ENV["NO_RAILS"] = "true"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/typed_operation/**/*_test.rb"]
+end
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/typed_operation/base.rb

@@ -1,106 +1,24 @@
 # frozen_string_literal: true
 
-require "literal"
-
 module TypedOperation
-  class Base < Literal::Data
-    class << self
-      def call(...)
-        new(...).call
-      end
+  class Base < Literal::Struct
+    extend Operations::Introspection
+    extend Operations::Parameters
+    extend Operations::PartialApplication
 
-      def with(...)
-        PartiallyApplied.new(self, ...).with
-      end
-      alias_method :[], :with
-
-      def curry
-        Curried.new(self)
-      end
-
-      def to_proc
-        method(:call).to_proc
-      end
-
-      # Method to define parameters for your operation.
-
-      # Parameter for keyword argument, or a positional argument if you use positional: true
-      # Required, but you can set a default or use optional: true if you want optional
-      def param(name, signature = :any, **options, &converter)
-        AttributeBuilder.new(self, name, signature, options).define(&converter)
-      end
-
-      # Alternative DSL
-
-      # Parameter for positional argument
-      def positional_param(name, signature = :any, **options, &converter)
-        param(name, signature, **options.merge(positional: true), &converter)
-      end
-
-      # Parameter for a keyword or named argument
-      def named_param(name, signature = :any, **options, &converter)
-        param(name, signature, **options.merge(positional: false), &converter)
-      end
-
-      # Wrap a type signature in a NilableType meaning it is optional to TypedOperation
-      def optional(type_signature)
-        NilableType.new(type_signature)
-      end
-
-      # Introspection methods
-
-      def positional_parameters
-        literal_attributes.filter_map { |name, attribute| name if attribute.positional? }
-      end
+    include Operations::Callable
+    include Operations::Lifecycle
+    include Operations::Deconstruct
 
-      def keyword_parameters
-        literal_attributes.filter_map { |name, attribute| name unless attribute.positional? }
-      end
-
-      def required_positional_parameters
-        required_parameters.filter_map { |name, attribute| name if attribute.positional? }
-      end
-
-      def required_keyword_parameters
-        required_parameters.filter_map { |name, attribute| name unless attribute.positional? }
-      end
-
-      def optional_positional_parameters
-        positional_parameters - required_positional_parameters
-      end
-
-      def optional_keyword_parameters
-        keyword_parameters - required_keyword_parameters
-      end
-
-      private
-
-      def required_parameters
-        literal_attributes.filter do |name, attribute|
-          attribute.default.nil? # Any optional parameters will have a default value/proc in their Literal::Attribute
-        end
+    class << self
+      def attribute(name, type, special = nil, reader: :public, writer: :public, positional: false, default: nil)
+        super(name, type, special, reader:, writer: false, positional:, default:)
       end
     end
 
-    def after_initialization
-      prepare if respond_to?(:prepare)
-    end
-
-    def call
-      raise InvalidOperationError, "You must implement #call"
-    end
-
-    def to_proc
-      method(:call).to_proc
-    end
-
-    def deconstruct
-      attributes.values
-    end
-
-    def deconstruct_keys(keys)
-      h = attributes.to_h
-      keys ? h.slice(*keys) : h
+    def with(...)
+      # copy to new operation with new attrs
+      self.class.new(**attributes.merge(...))
     end
   end
 end

data/lib/typed_operation/immutable_base.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  class ImmutableBase < Literal::Data
+    extend Operations::Introspection
+    extend Operations::Parameters
+    extend Operations::PartialApplication
+
+    include Operations::Callable
+    include Operations::Lifecycle
+    include Operations::Deconstruct
+  end
+end

data/lib/typed_operation/operations/attribute_builder.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    class AttributeBuilder
+      def initialize(typed_operation, parameter_name, type_signature, options)
+        @typed_operation = typed_operation
+        @name = parameter_name
+        @signature = type_signature
+        @optional = options[:optional]
+        @positional = options[:positional]
+        @reader = options[:reader] || :public
+        @default_key = options.key?(:default)
+        @default = options[:default]
+
+        prepare_type_signature_for_literal
+      end
+
+      def define(&converter)
+        @typed_operation.attribute(
+          @name,
+          @signature,
+          default: default_value_for_literal,
+          positional: @positional,
+          reader: @reader,
+          &converter
+        )
+      end
+
+      private
+
+      def prepare_type_signature_for_literal
+        @signature = Literal::Types::NilableType.new(@signature) if needs_to_be_nilable?
+        union_with_nil_to_support_nil_default
+        validate_positional_order_params! if @positional
+      end
+
+      # If already wrapped in a Nilable then don't wrap again
+      def needs_to_be_nilable?
+        @optional && !type_nilable?
+      end
+
+      def type_nilable?
+        @signature.is_a?(Literal::Types::NilableType)
+      end
+
+      def union_with_nil_to_support_nil_default
+        @signature = Literal::Union.new(@signature, NilClass) if has_default_value_nil?
+      end
+
+      def has_default_value_nil?
+        default_provided? && @default.nil?
+      end
+
+      def validate_positional_order_params!
+        # Optional ones can always be added after required ones, or before any others, but required ones must be first
+        unless type_nilable? || @typed_operation.optional_positional_parameters.empty?
+          raise ParameterError, "Cannot define required positional parameter '#{@name}' after optional positional parameters"
+        end
+      end
+
+      def default_provided?
+        @default_key
+      end
+
+      def default_value_for_literal
+        if has_default_value_nil? || type_nilable?
+          -> {}
+        else
+          @default
+        end
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/callable.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Callable
+      def self.included(base)
+        base.extend(CallableMethods)
+      end
+
+      module CallableMethods
+        def call(...)
+          new(...).call
+        end
+
+        def to_proc
+          method(:call).to_proc
+        end
+      end
+
+      include CallableMethods
+
+      def call
+        raise InvalidOperationError, "You must implement #call"
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/deconstruct.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Deconstruct
+      def deconstruct
+        attributes.values
+      end
+
+      def deconstruct_keys(keys)
+        h = attributes.to_h
+        keys ? h.slice(*keys) : h
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/introspection.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    # Introspection methods
+    module Introspection
+      def positional_parameters
+        literal_attributes.filter_map { |name, attribute| name if attribute.positional? }
+      end
+
+      def keyword_parameters
+        literal_attributes.filter_map { |name, attribute| name unless attribute.positional? }
+      end
+
+      def required_parameters
+        literal_attributes.filter do |name, attribute|
+          attribute.default.nil? # Any optional parameters will have a default value/proc in their Literal::Attribute
+        end
+      end
+
+      def required_positional_parameters
+        required_parameters.filter_map { |name, attribute| name if attribute.positional? }
+      end
+
+      def required_keyword_parameters
+        required_parameters.filter_map { |name, attribute| name unless attribute.positional? }
+      end
+
+      def optional_positional_parameters
+        positional_parameters - required_positional_parameters
+      end
+
+      def optional_keyword_parameters
+        keyword_parameters - required_keyword_parameters
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/lifecycle.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Lifecycle
+      def after_initialization
+        prepare if respond_to?(:prepare)
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/parameters.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    # Method to define parameters for your operation.
+    module Parameters
+      # Parameter for keyword argument, or a positional argument if you use positional: true
+      # Required, but you can set a default or use optional: true if you want optional
+      def param(name, signature = :any, **options, &converter)
+        AttributeBuilder.new(self, name, signature, options).define(&converter)
+      end
+
+      # Alternative DSL
+
+      # Parameter for positional argument
+      def positional_param(name, signature = :any, **options, &converter)
+        param(name, signature, **options.merge(positional: true), &converter)
+      end
+
+      # Parameter for a keyword or named argument
+      def named_param(name, signature = :any, **options, &converter)
+        param(name, signature, **options.merge(positional: false), &converter)
+      end
+
+      # Wrap a type signature in a NilableType meaning it is optional to TypedOperation
+      def optional(type_signature)
+        Literal::Types::NilableType.new(type_signature)
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/partial_application.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module PartialApplication
+      def with(...)
+        PartiallyApplied.new(self, ...).with
+      end
+      alias_method :[], :with
+
+      def curry
+        Curried.new(self)
+      end
+    end
+  end
+end

data/lib/typed_operation/version.rb

@@ -1,3 +1,3 @@
 module TypedOperation
-  VERSION = "1.0.0.pre1"
+  VERSION = "1.0.0.pre2"
 end

data/lib/typed_operation.rb

@@ -2,11 +2,19 @@ if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.2.0")
   require "polyfill-data"
 end
 
+require "literal"
+
 require "typed_operation/version"
 require "typed_operation/railtie" if defined?(Rails::Railtie)
-require "typed_operation/nilable_type"
-require "typed_operation/attribute_builder"
+require "typed_operation/operations/introspection"
+require "typed_operation/operations/parameters"
+require "typed_operation/operations/partial_application"
+require "typed_operation/operations/callable"
+require "typed_operation/operations/lifecycle"
+require "typed_operation/operations/deconstruct"
+require "typed_operation/operations/attribute_builder"
 require "typed_operation/curried"
+require "typed_operation/immutable_base"
 require "typed_operation/base"
 require "typed_operation/partially_applied"
 require "typed_operation/prepared"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typed_operation
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre1
+  version: 1.0.0.pre2
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-20 00:00:00.000000000 Z
+date: 2023-08-22 00:00:00.000000000 Z
 dependencies: []
 description: TypedOperation is a command pattern implementation where inputs can be
   defined with runtime type checks. Operations can be partially applied.
@@ -30,10 +30,16 @@ files:
 - lib/generators/typed_operation_generator.rb
 - lib/tasks/typed_operation_tasks.rake
 - lib/typed_operation.rb
-- lib/typed_operation/attribute_builder.rb
 - lib/typed_operation/base.rb
 - lib/typed_operation/curried.rb
-- lib/typed_operation/nilable_type.rb
+- lib/typed_operation/immutable_base.rb
+- lib/typed_operation/operations/attribute_builder.rb
+- lib/typed_operation/operations/callable.rb
+- lib/typed_operation/operations/deconstruct.rb
+- lib/typed_operation/operations/introspection.rb
+- lib/typed_operation/operations/lifecycle.rb
+- lib/typed_operation/operations/parameters.rb
+- lib/typed_operation/operations/partial_application.rb
 - lib/typed_operation/partially_applied.rb
 - lib/typed_operation/prepared.rb
 - lib/typed_operation/railtie.rb

data/lib/typed_operation/attribute_builder.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-module TypedOperation
-  class AttributeBuilder
-    def initialize(typed_operation, parameter_name, type_signature, options)
-      @typed_operation = typed_operation
-      @name = parameter_name
-      @signature = type_signature
-      @optional = options[:optional]
-      @positional = options[:positional]
-      @reader = options[:reader] || :public
-      @default_key = options.key?(:default)
-      @default = options[:default]
-
-      prepare_type_signature_for_literal
-    end
-
-    def define(&converter)
-      @typed_operation.attribute(
-        @name,
-        @signature,
-        default: default_value_for_literal,
-        positional: @positional,
-        reader: @reader,
-        &converter
-      )
-    end
-
-    private
-
-    def prepare_type_signature_for_literal
-      @signature = NilableType.new(@signature) if needs_to_be_nilable?
-      union_with_nil_to_support_nil_default
-      validate_positional_order_params! if @positional
-    end
-
-    # If already wrapped in a Nilable then don't wrap again
-    def needs_to_be_nilable?
-      @optional && !type_nilable?
-    end
-
-    def type_nilable?
-      @signature.is_a?(NilableType)
-    end
-
-    def union_with_nil_to_support_nil_default
-      @signature = Literal::Union.new(@signature, NilClass) if has_default_value_nil?
-    end
-
-    def has_default_value_nil?
-      default_provided? && @default.nil?
-    end
-
-    def validate_positional_order_params!
-      # Optional ones can always be added after required ones, or before any others, but required ones must be first
-      unless type_nilable? || @typed_operation.optional_positional_parameters.empty?
-        raise ParameterError, "Cannot define required positional parameter '#{@name}' after optional positional parameters"
-      end
-    end
-
-    def default_provided?
-      @default_key
-    end
-
-    def default_value_for_literal
-      if has_default_value_nil? || type_nilable?
-        -> {}
-      else
-        @default
-      end
-    end
-  end
-end

data/lib/typed_operation/nilable_type.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require "literal"
-
-module TypedOperation
-  class NilableType < Literal::Union
-    def initialize(*types)
-      @types = types + [NilClass]
-    end
-  end
-end