typed_operation 0.4.2 → 1.0.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5af7163e167fa37ba366469393a59d8ea25d4eede88472a7c739bee91e987d7
-  data.tar.gz: fb1de81a7eb3ce710c36355474c7f3b01e970c4696a82ede8fd680273cae1cb2
+  metadata.gz: ff925e2cc5ce03a696a209e0ca61130bff94ddb6ce28f2670ebaaae18f1968ba
+  data.tar.gz: b14a0952694653f918135a57180c8c7746aeffcb14385d17aeef7a1283726e99
 SHA512:
-  metadata.gz: fd8a364079683dbe13c02c6090a707499db4f847bf86c395baa80ffed3e7bc997b11ae545c2a7f20d9b2c46e66f9e4b3b5496776524fe70b276eef46eff33f88
-  data.tar.gz: 7a7cf690621318b56b44cfe8cf4d4231694d65befd2ee62dd1cfb53d283be653b41011de4ad77f9f46636eb0b4146093f37162f4059aa74afc8190f9a789b68e
+  metadata.gz: 0cb23aed491058bdefba04d75661ec4cb5110a2491ba9d4b3afc929d41e1863a09b9ac09b41bdbd6306856af6d5552f2c86c3057b53df3076d0674a9c1feafda
+  data.tar.gz: 143f6ba5a00d5cabadec3f7f326dc7a724fdd2666ca0dffa326cacf9f9af2f4dce797f77a727468cd919eb42a4b6de530105d6866e49797997c10ff5a36db9fe

data/README.md

@@ -1,33 +1,476 @@
 # TypedOperation
 
-An implementation of a Command pattern, which is callable, and can be partially applied (curried).
+An implementation of a Command pattern, which is callable, and can be partially applied.
 
-Inputs to the operation are specified as typed attributes using the `param` method.
+Inputs to the operation are specified as typed attributes (uses [`literal`](https://github.com/joeldrapper/literal)).
 
-Result format of the operation is up to you, but plays nicely with `Dry::Monads`. 
+Type of result of the operation is up to you, eg you could use [`literal` monads](https://github.com/joeldrapper/literal) or [`Dry::Monads`](https://dry-rb.org/gems/dry-monads/1.3/).
 
-### Examples:
+**Note the version described here (~ 1.0.0) is not yet released on Rubygems, it is waiting for a release of `literal`)**
 
-A base operation class:
+## Features
+
+- Operations can be **partially applied** or **curried**
+- Operations are **callable**
+- Operations can be **pattern matched** on
+- Parameters:
+  - specified with **type constraints** (uses `literal` gem)
+  - can be **positional** or **named**
+  - can be **optional**, or have **default** values
+  - can be **coerced** by providing a block
+
+### Example
+
+```ruby
+class ShelveBookOperation < ::TypedOperation::Base
+  # Parameters can be specified with `positional_param`/`named_param` or directly with the
+  # underlying `param` method.
+  
+  # Note that you may also like to simply alias the param methods to your own preferred names:
+  # `positional`/`named` or `arg`/`key` for example.
+  
+  # A positional parameter (positional argument passed to the operation when creating it).
+  positional_param :title, String
+  # Or if you prefer:
+  #   `param :title, String, positional: true`
+  
+  # A named parameter (keyword argument passed to the operation when creating it).
+  named_param :description, String
+  # Or if you prefer:
+  #   `param :description, String`
+
+  named_param :author_id, Integer, &:to_i
+  named_param :isbn, String
+  
+  # Optional parameters are specified by wrapping the type constraint in the `optional` method, or using the `optional:` option
+  named_param :shelf_code, optional(Integer)
+  # Or if you prefer:
+  #   `named_param :shelf_code, Integer, optional: true`
+
+  named_param :category, String, default: "unknown".freeze
+
+  # to setup (optional)
+  def prepare
+    raise ArgumentError, "ISBN is invalid" unless valid_isbn?
+  end
+
+  # The 'work' of the operation
+  def call
+    "Put away '#{title}' by author ID #{author_id}#{shelf_code ? " on shelf #{shelf_code}" : "" }"
+  end
+
+  private
+
+  def valid_isbn?
+    # ...
+    true
+  end
+end
+
+shelve = ShelveBookOperation.new("The Hobbit", description: "A book about a hobbit", author_id: "1", isbn: "978-0261103283")
+# => #<ShelveBookOperation:0x0000000108b3e490 @attributes={:title=>"The Hobbit", :description=>"A book about a hobbit", :author_id=>1, :isbn=>"978-0261103283", :shelf_code=>nil, :category=>"unknown"}, ...
+
+shelve.call
+# => "Put away 'The Hobbit' by author ID 1"
+
+shelve = ShelveBookOperation.with("The Silmarillion", description: "A book about the history of Middle-earth", shelf_code: 1)
+# => #<TypedOperation::PartiallyApplied:0x0000000103e6f560 ...
+
+shelve.call(author_id: "1", isbn: "978-0261102736")
+# => "Put away 'The Silmarillion' by author ID 1 on shelf 1"
+
+curried = shelve.curry
+# => #<TypedOperation::Curried:0x0000000108d98a10 ...
+
+curried.(1).("978-0261102736")
+# => "Put away 'The Silmarillion' by author ID 1 on shelf 1"
+
+shelve.call(author_id: "1", isbn: false)
+# => Raises an error because isbn is invalid
+# :in `initialize': Expected `false` to be of type: `String`. (Literal::TypeError)
+```
+
+### Partially applying parameters
+
+```ruby
+class TestOperation < ::TypedOperation::Base
+  param :foo, String, positional: true
+  param :bar, String
+  param :baz, String, &:to_s
+
+  def call = "It worked! (#{foo}, #{bar}, #{baz})"
+end
+
+# Invoking the operation directly
+TestOperation.("1", bar: "2", baz: 3)
+# => "It worked! (1, 2, 3)"
+
+# Partial application of parameters
+partially_applied = TestOperation.with("1").with(bar: "2")
+# => #<TypedOperation::PartiallyApplied:0x0000000110270248 @keyword_args={:bar=>"2"}, @operation_class=TestOperation, @positional_args=["1"]>
+
+# You can partially apply more than one parameter at a time, and chain calls to `.with`.
+# With all the required parameters set, the operation is 'prepared' and can be instantiated and called
+prepared = TestOperation.with("1", bar: "2").with(baz: 3)
+# => #<TypedOperation::Prepared:0x0000000110a9df38 @keyword_args={:bar=>"2", :baz=>3}, @operation_class=TestOperation, @positional_args=["1"]>
+
+# A 'prepared' operation can instantiated & called
+prepared.call
+# => "It worked! (1, 2, 3)"
+
+# You can provide additional parameters when calling call on a partially applied operation
+partially_applied.call(baz: 3)
+# => "It worked! (1, 2, 3)"
+
+# Partial application can be done using `.with or `.[]`
+TestOperation.with("1")[bar: "2", baz: 3].call
+# => "It worked! (1, 2, 3)"
+
+# Currying an operation, note that *all required* parameters must be provided an argument in order  
+TestOperation.curry.("1").("2").(3)
+# => "It worked! (1, 2, 3)"
+
+# You can also curry from an already partially applied operation, so you can set optional named parameters first.
+# Note currying won't let you set optional positional parameters.
+partially_applied = TestOperation.with("1")
+partially_applied.curry.("2").(3)
+# => "It worked! (1, 2, 3)"
+
+# > TestOperation.with("1").with(bar: "2").call
+# => Raises an error because it is PartiallyApplied and so can't be called (it is missing required args)
+#      "Cannot call PartiallyApplied operation TestOperation (key: test_operation), are you expecting it to be Prepared? (TypedOperation::MissingParameterError)"
+
+TestOperation.with("1").with(bar: "2").with(baz: 3).operation
+# same as > TestOperation.new("1", bar: "2", baz: 3)
+# => <TestOperation:0x000000014a0048a8 ...>
+
+# > TestOperation.with(foo: "1").with(bar: "2").operation
+# => Raises an error because it is PartiallyApplied so operation can't be instantiated
+#      "Cannot instantiate Operation TestOperation (key: test_operation), as it is only partially applied. (TypedOperation::MissingParameterError)"
+```
+
+## Documentation
+
+### Create an operation (subclass `TypedOperation::Base`)
+
+Create an operation by subclassing `TypedOperation::Base` and specifying the parameters the operation requires.
+
+The subclass must implement the `#call` method which is where the operations main work is done.
+
+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.
+
+Type constraints can be modified to make the parameter optional using `.optional`.
+
+#### Your own aliases
+
+Note that you may also like to alias the param methods to your own preferred names in a common base operation class.
+
+Some possible aliases are:
+- `positional`/`named`
+- `arg`/`key`
+ 
+For example:
+
+```ruby
+class ApplicationOperation < ::TypedOperation::Base
+  class << self
+    alias_method :arg, :positional_param
+    alias_method :key, :named_param
+  end
+end
+
+class MyOperation < ApplicationOperation
+  arg :name, String
+  key :age, Integer
+end
+
+MyOperation.new("Steve", age: 20)
+```
+
+#### Positional parameters (`positional: true` or `.positional_param`)
+
+Defines a positional parameter (positional argument passed to the operation when creating it).
+
+The following are equivalent:
+
+- `param <param_name>, <type>, positional: true, <**options>`
+- `positional_param <param_name>, <type>, <**options>`
+
+The `<para_name>` is a symbolic name, used to create the accessor method, and when deconstructing to a hash.
+
+The `<type>` constraint provides the expected type of the parameter (the type is a type signature compatible with `literal`).
+
+The `<options>` are:
+- `default:` - a default value for the parameter (can be a proc or a frozen value)
+- `optional:` - a boolean indicating whether the parameter is optional (default: false). Note you may prefer to use the 
+  `.optional` method instead of this option.
+
+**Note** when positional arguments are provided to the operation, they are matched in order of definition or positional
+params. Also note that you cannot define required positional parameters after optional ones.
+
+Eg
+
+```ruby
+class MyOperation < ::TypedOperation::Base
+  positional_param :name, String, positional: true
+  # Or alternatively => `param :name, String, positional: true` 
+  positional_param :age, Integer, default: -> { 0 }
+  
+  def call
+    puts "Hello #{name} (#{age})"
+  end
+end
+
+MyOperation.new("Steve").call 
+# => "Hello Steve (0)"
+
+MyOperation.with("Steve").call(20)
+# => "Hello Steve (20)"
+```
+
+#### Named (keyword) parameters
+
+Defines a named parameter (keyword argument passed to the operation when creating it).
+
+The following are equivalent:
+- `param <param_name>, <type>, <**options>`
+- `named_param <param_name>, <type>, <**options>`
+
+The `<para_name>` is a symbol, used as parameter name for the keyword arguments in the operation constructor, to
+create the accessor method and when deconstructing to a hash.
+
+The type constraint and options are the same as for positional parameters.
+
+```ruby
+class MyOperation < ::TypedOperation::Base
+  named_param :name, String
+  # Or alternatively => `param :name, String` 
+  named_param :age, Integer, default: -> { 0 }
+  
+  def call
+    puts "Hello #{name} (#{age})"
+  end
+end
+
+MyOperation.new(name: "Steve").call 
+# => "Hello Steve (0)"
+
+MyOperation.with(name: "Steve").call(age: 20)
+# => "Hello Steve (20)"
+```
+
+#### Using both positional and named parameters
+
+You can use both positional and named parameters in the same operation.
+
+```ruby
+class MyOperation < ::TypedOperation::Base
+  positional_param :name, String
+  named_param :age, Integer, default: -> { 0 }
+  
+  def call
+    puts "Hello #{name} (#{age})"
+  end
+end
+
+MyOperation.new("Steve").call 
+# => "Hello Steve (0)"
+
+MyOperation.new("Steve", age: 20).call
+# => "Hello Steve (20)"
+
+MyOperation.with("Steve").call(age: 20)
+# => "Hello Steve (20)"
+```
+
+#### Optional parameters (using `optional:` or `.optional`)
+
+Optional parameters are ones that do not need to be specified for the operation to be instantiated.
+
+An optional parameter can be specified by:
+- using the `optional:` option
+- using the `.optional` method around the type constraint
+
+```ruby
+class MyOperation < ::TypedOperation::Base
+  param :name, String
+  param :age, Integer, optional: true
+  param :nickname, optional(String)
+  # ...
+end
+
+MyOperation.new(name: "Steve")
+MyOperation.new(name: "Steve", age: 20)
+MyOperation.new(name: "Steve", nickname: "Steve-o")
+```
+
+This `.optional` class method effectively makes the type signature a union of the provided type and `NilClass`.
+
+#### Coercing parameters
+
+You can specify a block after a parameter definition to coerce the argument value.
+
+```ruby
+param :name, String, &:to_s
+param :choice, Union(FalseClass, TrueClass) do |v|
+  v == "y"
+end
+```
+
+#### Default values (with `default:`)
+
+You can specify a default value for a parameter using the `default:` option.
+
+The default value can be a proc or a frozen value. If the value is specified as `nil` then the default value is literally nil and the parameter is optional.
+
+```ruby
+param :name, String, default: "Steve".freeze
+param :age, Integer, default: -> { rand(100) }
+```
+
+If using the directive `# frozen_string_literal: true` then you string values are frozen by default.
+
+### Partially applying (fixing parameters) on an operation (using `.with`)
+
+`.with(...)` creates a partially applied operation with the provided parameters.
+
+It is aliased to `.[]` for an alternative syntax.
+
+Note that `.with` can take both positional and keyword arguments, and can be chained.
+
+**An important caveat about partial application is that type checking is not done until the operation is instantiated**
+
+```ruby
+MyOperation.new(123)
+# => Raises an error as the type of the first parameter is incorrect:
+#    Expected `123` to be of type: `String`. (Literal::TypeError)
+
+op = MyOperation.with(123)
+# => #<TypedOperation::Prepared:0x000000010b1d3358 ...
+#     Does **not raise** an error, as the type of the first parameter is not checked until the operation is instantiated
+
+op.call # or op.operation
+# => Now raises an error as the type of the first parameter is incorrect and operation is instantiated
+```
+
+### Calling an operation (using `.call`)
+
+An operation can be invoked by:
+
+- instantiating it with at least required params and then calling the `#call` method on the instance
+- once a partially applied operation has been prepared (all required parameters have been set), the call
+  method on TypedOperation::Prepared can be used to instantiate and call the operation.
+- once an operation is curried, the `#call` method on last TypedOperation::Curried in the chain will invoke the operation
+- calling `#call` on a partially applied operation and passing in any remaining required parameters
+
+See the many examples in this document.
+
+### Pattern matching on an operation
+
+`TypedOperation::Base` and `TypedOperation::PartiallyApplied` implement `deconstruct` and `deconstruct_keys` methods,
+so they can be pattern matched against.
+
+```ruby
+case MyOperation.new("Steve", age: 20)
+in MyOperation[name, age]
+  puts "Hello #{name} (#{age})"
+end
+
+case MyOperation.new("Steve", age: 20)
+in MyOperation[name:, age: 20]
+  puts "Hello #{name} (#{age})"
+end
+```
+
+### Introspection of parameters & other methods
+
+#### `.to_proc`
+
+Get a proc that calls `.call(...)`
+
+
+#### `#to_proc`
+
+Get a proc that calls the `#call` method on an operation instance
+
+#### `.prepared?`
+
+Check if an operation is prepared
+
+#### `.operation`
+
+Return an operation instance from a Prepared operation. Will raise if called on a PartiallyApplied operation
+
+#### `.positional_parameters`
+
+List of the names of the positional parameters, in order
+
+#### `.keyword_parameters`
+
+List of the names of the keyword parameters
+
+#### `.required_positional_parameters`
+
+List of the names of the required positional parameters, in order
+
+#### `.required_keyword_parameters`
+
+List of the names of the required keyword parameters
+
+#### `.optional_positional_parameters`
+
+List of the names of the optional positional parameters, in order
+
+#### `.optional_keyword_parameters`
+
+List of the names of the optional keyword parameters
+
+
+### Using with Rails
+
+You can use the provided generator to create an `ApplicationOperation` class in your Rails project.
+
+You can then extend this to add extra functionality to all your operations.
+
+This is an example of a `ApplicationOperation` in a Rails app that uses `Dry::Monads`:
 
 ```ruby
+# frozen_string_literal: true
+
 class ApplicationOperation < ::TypedOperation::Base
+  # We choose to use dry-monads for our operations, so include the required modules
   include Dry::Monads[:result, :do]
   
-  param :initiator, ::RegisteredUser, allow_nil: true
+  class << self
+    # Setup our own preferred names for the DSL methods
+    alias_method :positional, :positional_param
+    alias_method :named, :named_param
+  end
+  
+  # Parameters common to all Operations in this application
+  named :initiator, optional(::User)
 
   private
 
+  # We setup some helper methods for our operations to use
+  
   def succeeded(value)
     Success(value)
   end
 
   def failed_with_value(value, message: "Operation failed", error_code: nil)
-    failed(error_code || self.class.operation_key, message, value)
+    failed(error_code || operation_key, message, value)
   end
 
   def failed_with_message(message, error_code: nil)
-    failed(error_code || self.class.operation_key, message)
+    failed(error_code || operation_key, message)
   end
 
   def failed(error_code, message = "Operation failed", value = nil)
@@ -37,48 +480,77 @@ class ApplicationOperation < ::TypedOperation::Base
   def failed_with_code_and_value(error_code, value, message: "Operation failed")
     failed(error_code, message, value)
   end
-end
 
+  def operation_key
+    self.class.name
+  end
+end
 ```
 
-A simple operation:
+### Using with `literal` monads
+
+You can use the `literal` gem to provide a `Result` type for your operations.
 
 ```ruby
-class TestOperation < ::ApplicationOperation
-  param :foo, String
-  param :bar, String
-  param :baz, String, convert: true
+class MyOperation < ::TypedOperation::Base
+  param :account_name, String
+  param :owner, String
 
-  def prepare
-    # to setup (optional)
-    puts "lets go!"
+  def call
+    create_account.bind do |account|
+      associate_owner(account).bind do
+        account
+      end
+    end
+  end
+
+  private
+
+  def create_account
+    # returns Literal::Success(account) or Literal::Failure(:cant_create)
+    Literal::Success.new(account_name)
   end
   
-  def call
-    succeeded("It worked!")
-    # failed_with_message("It failed!")
+  def associate_owner(account)
+    # ...
+    Literal::Failure.new(:cant_associate_owner)
   end
 end
+
+MyOperation.new(account_name: "foo", owner: "bar").call
+# => Literal::Failure(:cant_associate_owner)
+
 ```
 
-```ruby
-TestOperation.(foo: "1", bar: "2", baz: 3)
-# => Success("It worked!")
+### Using with `Dry::Monads`
 
-TestOperation.with(foo: "1").with(bar: "2")
-# => #<TypedOperation::PartiallyApplied:0x000000014a655310 @applied_args={:foo=>"1", :bar=>"2"}, @operation=TestOperation>
+As per the example in [`Dry::Monads` documentation](https://dry-rb.org/gems/dry-monads/1.0/do-notation/)
 
-TestOperation.with(foo: "1").with(bar: "2").with(baz: 3)
-# => <TypedOperation::Prepared:0x000000012dac6498 @applied_args={:foo=>"1", :bar=>"2", :baz=>3}, @operation=TestOperation>
+```ruby
+class MyOperation < ::TypedOperation::Base
+  include Dry::Monads[:result]
+  include Dry::Monads::Do.for(:call)
 
-TestOperation.with(foo: "1").with(bar: "2").with(baz: 3).call
-# => Success("It worked!")
+  param :account_name, String
+  param :owner, ::Owner
+  
+  def call
+    account = yield create_account(account_name)
+    yield associate_owner(account, owner)
+
+    Success(account)
+  end
 
-TestOperation.with(foo: "1").with(bar: "2").with(baz: 3).operation
-# => <TestOperation:0x000000014a0048a8 @__attributes=#<TestOperation::TypedSchema foo="1" bar="2" baz="3">>
+  private
+  
+  def create_account(account_name)
+    # returns Success(account) or Failure(:cant_create)
+  end
+end
 ```
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -125,7 +597,13 @@ The default path is `app/operations`.
 The generator will also create a test file.
 
 ## Contributing
-Contribution directions go here.
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/stevegeek/typed_operation. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/stevegeek/typed_operation/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the TypedOperation project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/stevegeek/typed_operation/blob/master/CODE_OF_CONDUCT.md).

data/lib/generators/templates/operation.rb

@@ -4,8 +4,11 @@
 module <%= namespace_name %>
   class <%= name %> < ::ApplicationOperation
     # Replace with implementation...
-    param :required_param, String
-    param :an_optional_param, Integer, convert: true, allow_nil: true
+    positional_param :required_positional_param, String
+    param :required_named_param, String
+    param :an_optional_param, Integer, optional: true do |value|
+     value.to_i
+    end
 
     def prepare
       # Prepare...
@@ -20,8 +23,11 @@ end
 <% else %>
 class <%= name %> < ::ApplicationOperation
   # Replace with implementation...
-  param :required_param, String
-  param :an_optional_param, Integer, convert: true, allow_nil: true
+  positional_param :required_positional_param, String
+  param :required_named_param, String
+  param :an_optional_param, Integer, optional: true do |value|
+    value.to_i
+  end
 
   def prepare
     # Prepare...

data/lib/typed_operation/attribute_builder.rb

@@ -0,0 +1,73 @@
+# 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/base.rb

@@ -1,43 +1,88 @@
 # frozen_string_literal: true
 
-require "vident/typed"
-require "vident/typed/attributes"
+require "literal"
 
 module TypedOperation
-  class Base
-    include Vident::Typed::Attributes
-
+  class Base < Literal::Data
     class << self
       def call(...)
         new(...).call
       end
 
-      def curry(**args)
-        PartiallyApplied.new(self, **args).curry
+      def with(...)
+        PartiallyApplied.new(self, ...).with
+      end
+      alias_method :[], :with
+
+      def curry
+        Curried.new(self)
       end
-      alias_method :[], :curry
-      alias_method :with, :curry
 
       def to_proc
         method(:call).to_proc
       end
 
-      def operation_key
-        name.underscore.to_sym
-      end
+      # Method to define parameters for your operation.
 
-      # property are required by default, you can fall back to attribute or set allow_nil: true if you want optional
+      # 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)
-        attribute(name, signature, **{allow_nil: false}.merge(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
-    end
 
-    def initialize(**attributes)
-      begin
-        prepare_attributes(attributes)
-      rescue ::Dry::Struct::Error => e
-        raise ParameterError, e.message
+      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
+      end
+    end
+
+    def after_initialization
       prepare if respond_to?(:prepare)
     end
 
@@ -49,10 +94,13 @@ module TypedOperation
       method(:call).to_proc
     end
 
-    private
+    def deconstruct
+      attributes.values
+    end
 
-    def operation_key
-      self.class.operation_key
+    def deconstruct_keys(keys)
+      h = attributes.to_h
+      keys ? h.slice(*keys) : h
     end
   end
 end

data/lib/typed_operation/curried.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  class Curried
+    def initialize(operation_class, partial_operation = nil)
+      @operation_class = operation_class
+      @partial_operation = partial_operation || operation_class.with
+    end
+
+    def call(arg)
+      raise ArgumentError, "A prepared operation should not be curried" if @partial_operation.prepared?
+
+      next_partially_applied = if next_parameter_positional?
+        @partial_operation.with(arg)
+      else
+        @partial_operation.with(next_keyword_parameter => arg)
+      end
+      if next_partially_applied.prepared?
+        next_partially_applied.call
+      else
+        Curried.new(@operation_class, next_partially_applied)
+      end
+    end
+
+    def to_proc
+      method(:call).to_proc
+    end
+
+    private
+
+    def next_keyword_parameter
+      remaining = @operation_class.required_keyword_parameters - @partial_operation.keyword_args.keys
+      remaining.first
+    end
+
+    def next_parameter_positional?
+      @partial_operation.positional_args.size < @operation_class.required_positional_parameters.size
+    end
+  end
+end

data/lib/typed_operation/nilable_type.rb

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

data/lib/typed_operation/partially_applied.rb

@@ -2,34 +2,87 @@
 
 module TypedOperation
   class PartiallyApplied
-    def initialize(operation, **applied_args)
-      @operation = operation
-      @applied_args = applied_args
+    def initialize(operation_class, *positional_args, **keyword_args)
+      @operation_class = operation_class
+      @positional_args = positional_args
+      @keyword_args = keyword_args
     end
 
-    def curry(**params)
-      all_args = @applied_args.merge(params)
-      # check if required attrs are in @applied_args
-      required_keys = @operation.attribute_names.select do |name|
-        meta = @operation.attribute_metadata(name)
-        meta[:required] != false && !meta[:typed_attribute_options].key?(:default)
-      end
-      missing_keys = required_keys - all_args.keys
+    def with(*positional, **keyword)
+      all_positional = positional_args + positional
+      all_kw_args = keyword_args.merge(keyword)
+
+      validate_positional_arg_count!(all_positional.size)
 
-      if missing_keys.size > 0
-        # Partially apply the arguments
-        PartiallyApplied.new(@operation, **all_args)
+      if partially_applied?(all_positional, all_kw_args)
+        PartiallyApplied.new(operation_class, *all_positional, **all_kw_args)
       else
-        Prepared.new(@operation, **all_args)
+        Prepared.new(operation_class, *all_positional, **all_kw_args)
       end
     end
-    alias_method :[], :curry
-    alias_method :with, :curry
+    alias_method :[], :with
+
+    def curry
+      Curried.new(operation_class, self)
+    end
 
     def call(...)
-      prepared = curry(...)
+      prepared = with(...)
       return prepared.operation.call if prepared.is_a?(Prepared)
-      raise TypedOperation::MissingParameterError, "Cannot call PartiallyApplied operation #{@operation.name} (key: #{@operation.operation_key}), are you expecting it to be Prepared?"
+      raise MissingParameterError, "Cannot call PartiallyApplied operation #{operation_class.name} (key: #{operation_class.name}), are you expecting it to be Prepared?"
+    end
+
+    def operation
+      raise MissingParameterError, "Cannot instantiate Operation #{operation_class.name} (key: #{operation_class.name}), as it is only partially applied."
+    end
+
+    def prepared?
+      false
+    end
+
+    def to_proc
+      method(:call).to_proc
+    end
+
+    def deconstruct
+      positional_args + keyword_args.values
+    end
+
+    def deconstruct_keys(keys)
+      h = keyword_args.dup
+      positional_args.each_with_index { |v, i| h[positional_parameters[i]] = v }
+      keys ? h.slice(*keys) : h
+    end
+
+    attr_reader :positional_args, :keyword_args
+
+    private
+
+    attr_reader :operation_class
+
+    def required_positional_parameters
+      @required_positional_parameters ||= operation_class.required_positional_parameters
+    end
+
+    def required_keyword_parameters
+      @required_keyword_parameters ||= operation_class.required_keyword_parameters
+    end
+
+    def positional_parameters
+      @positional_parameters ||= operation_class.positional_parameters
+    end
+
+    def validate_positional_arg_count!(count)
+      if count > positional_parameters.size
+        raise ArgumentError, "Too many positional arguments provided for #{operation_class.name} (key: #{operation_class.name})"
+      end
+    end
+
+    def partially_applied?(all_positional, all_kw_args)
+      missing_positional = required_positional_parameters.size - all_positional.size
+      missing_keys = required_keyword_parameters - all_kw_args.keys
+
+      missing_positional > 0 || missing_keys.size > 0
     end
   end
 end

data/lib/typed_operation/prepared.rb

@@ -3,7 +3,11 @@
 module TypedOperation
   class Prepared < PartiallyApplied
     def operation
-      @operation.new(**@applied_args)
+      operation_class.new(*@positional_args, **@keyword_args)
+    end
+
+    def prepared?
+      true
     end
   end
 end

data/lib/typed_operation/version.rb

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

data/lib/typed_operation.rb

@@ -1,11 +1,20 @@
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.2.0")
+  require "polyfill-data"
+end
+
 require "typed_operation/version"
-require "typed_operation/railtie"
+require "typed_operation/railtie" if defined?(Rails::Railtie)
+require "typed_operation/nilable_type"
+require "typed_operation/attribute_builder"
+require "typed_operation/curried"
 require "typed_operation/base"
 require "typed_operation/partially_applied"
 require "typed_operation/prepared"
 
 module TypedOperation
   class InvalidOperationError < StandardError; end
+
   class MissingParameterError < ArgumentError; end
+
   class ParameterError < TypeError; end
 end

metadata

@@ -1,63 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: typed_operation
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 1.0.0.pre1
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-27 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '6.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '8.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '6.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '8.0'
-- !ruby/object:Gem::Dependency
-  name: vident-typed
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-- !ruby/object:Gem::Dependency
-  name: dry-initializer
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
+date: 2023-08-20 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.
 email:
@@ -78,7 +30,10 @@ 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/partially_applied.rb
 - lib/typed_operation/prepared.rb
 - lib/typed_operation/railtie.rb
@@ -97,14 +52,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.18
 signing_key:
 specification_version: 4
 summary: TypedOperation is a command pattern implementation