llull 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e0e20df9c2ad6bc3b999fdab13ce83dd7b31cf9c1faa5e64ab57386be60f948
+  data.tar.gz: 80fbc31fb798cfa5ade0b83d07d1f1fdfa2f459c597972d5de515ac0c3fdbfa4
+SHA512:
+  metadata.gz: c49f21eea1c1714c6db2a1b875bdae5a050a58f37c3586d83e73cad0c811ba64abe5c7a0c34be012ad4e2c0e714929fe80c45c3931f06ad991703dbe1c1fc64d
+  data.tar.gz: 746c6cf76d8e3ab28790872283cca0ed04efc2378c720774556921639cf04d219508caf5a40790809afe650f818a8be04436198272c28cff6ead1a420105624e

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Thomas Murphy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,371 @@
+# Llull
+
+Composable Result types for Ruby. Implements functional programming patterns inspired by [railway-oriented programming](https://fsharpforfunandprofit.com/rop/). Named after [Ramon Llull](https://en.wikipedia.org/wiki/Ramon_Llull), whose _ars combinatoria_ explored the systematic combination of concepts.
+
+## Overview
+
+Replace nested conditionals and exception handling:
+
+```ruby
+def create_order(params)
+  return { error: "Invalid params" } unless valid_params?(params)
+
+  user = User.find(params[:user_id])
+  return { error: "User not found" } unless user
+
+  begin
+    order = Order.create!(params.merge(user: user))
+    { success: true, order: order }
+  rescue ActiveRecord::RecordInvalid => e
+    { error: e.message }
+  end
+end
+```
+
+With composable operations:
+
+```ruby
+def create_order(params)
+  validate_params(params)
+    .and_then { |valid_params| find_user(valid_params) }
+    .and_then { |user, params| create_order_record(user, params) }
+    .tap_success { |order| send_confirmation(order) }
+end
+```
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'llull'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+Include `Llull` in your classes to access the `Success()` and `Failure()` constructors:
+
+```ruby
+class MyService
+  include Llull
+
+  def call(input)
+    Success(input)
+      .and_then { |data| process_data(data) }
+      .map { |result| format_result(result) }
+  end
+end
+```
+
+### Basic Result Operations
+
+#### Creating Results
+
+```ruby
+# Success with a value
+success = Success("hello world")
+success.success? # => true
+success.value    # => "hello world"
+
+# Failure with error type and data
+failure = Failure(:validation, "Email is required")
+failure.failure?    # => true
+failure.error_type  # => :validation
+failure.error_data  # => "Email is required"
+```
+
+#### Transforming Values
+
+```ruby
+# map: transform successful values
+Success(10).map { |x| x * 2 }  # => Success(20)
+Failure(:error, "oops").map { |x| x * 2 }  # => Failure(:error, "oops")
+
+# and_then: chain operations that return Results
+Success("hello")
+  .and_then { |str| Success(str.upcase) }
+  .and_then { |str| Success("#{str}!") }
+# => Success("HELLO!")
+```
+
+#### Error Recovery
+
+```ruby
+# or_else: recover with another Result-returning operation
+result = Failure(:primary_failed, "error")
+  .or_else { |type, data| Success("backup plan") }
+# => Success("backup plan")
+
+# recover: convert failure to success value
+result = Failure(:not_found, "User missing")
+  .recover { |type, data| "Default User" }
+# => Success("Default User")
+```
+
+#### Unwrapping Values
+
+```ruby
+# Unsafe unwrapping (raises on failure)
+Success("hello").unwrap!  # => "hello"
+Failure(:error, "oops").unwrap!  # => raises Llull::ResultError
+
+# Safe unwrapping with default
+Success("hello").unwrap_or("default")     # => "hello"
+Failure(:error, "oops").unwrap_or("default")  # => "default"
+
+# Dynamic default based on error
+Failure(:not_found, "User").value_or { |type, data| "Missing #{data}" }
+# => "Missing User"
+```
+
+### Rails Service Objects
+
+Complete example:
+
+```ruby
+class UserRegistrationService
+  include Llull
+
+  def call(params)
+    validate_params(params)
+      .and_then { |valid_params| check_email_uniqueness(valid_params) }
+      .and_then { |valid_params| create_user(valid_params) }
+      .tap_success { |user| send_welcome_email(user) }
+  end
+
+  private
+
+  def validate_params(params)
+    errors = []
+    errors << "Email is required" if params[:email].blank?
+    errors << "Invalid email format" unless params[:email]&.include?("@")
+    errors << "Password too short" if params[:password]&.length.to_i < 8
+
+    errors.empty? ? Success(params) : Failure(:validation, errors)
+  end
+
+  def check_email_uniqueness(params)
+    existing = User.find_by(email: params[:email])
+    existing ? Failure(:duplicate_email, "Email already taken") : Success(params)
+  end
+
+  def create_user(params)
+    user = User.new(params)
+    user.save ? Success(user) : Failure(:creation_failed, user.errors.full_messages)
+  end
+
+  def send_welcome_email(user)
+    WelcomeMailer.deliver_later(user)
+  end
+end
+```
+
+#### Controller Integration
+
+Controller usage:
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    UserRegistrationService.new.call(user_params)
+      .on_success { |user| redirect_to user, notice: "Welcome!" }
+      .on_failure(:validation) { |errors|
+        flash.now[:errors] = errors
+        render :new, status: :unprocessable_entity
+      }
+      .on_failure(:duplicate_email) { |message|
+        flash.now[:error] = message
+        render :new, status: :conflict
+      }
+      .on_failure { |type, data|
+        flash[:error] = "Registration failed"
+        redirect_to signup_path
+      }
+  end
+end
+```
+
+### Pattern Matching (Ruby 3+)
+
+Ruby 3+ pattern matching support:
+
+```ruby
+result = UserService.new.call(params)
+
+case result
+in [:success, user]
+  puts "Created user: #{user.email}"
+in [:failure, :validation, errors]
+  puts "Validation failed: #{errors.join(', ')}"
+in [:failure, error_type, data]
+  puts "Other error: #{error_type}"
+end
+
+# Or with hash patterns
+case result
+in { success: true, value: user }
+  puts "Success: #{user.email}"
+in { success: false, error_type: :validation }
+  puts "Validation error"
+end
+```
+
+### Advanced Pattern Matching DSL
+
+Complex error handling:
+
+```ruby
+PaymentService.new.call(order, payment_method).match do |m|
+  m.success { |payment| redirect_to_confirmation(payment) }
+  m.failure(:insufficient_funds) { |data| offer_payment_plan }
+  m.failure(:invalid_card) { |data| ask_for_different_card }
+  m.failure(:service_unavailable) { |data| try_again_later }
+  m.failure { |type, data| log_unexpected_error(type, data) }
+end
+```
+
+### Side Effects
+
+Execute side effects without affecting the Result chain:
+
+```ruby
+CreateOrderService.new.call(params)
+  .tap_success { |order| analytics.track("order_created", order.id) }
+  .tap_failure { |type, data| logger.error("Order failed: #{type}") }
+  .and_then { |order| PaymentService.new.call(order) }
+  .tap_success { |payment| send_receipt(payment) }
+```
+
+### Collection Operations
+
+Multiple Results:
+
+```ruby
+# Process multiple items, fail fast on first error
+user_data = [
+  { email: "user1@example.com", name: "Alice" },
+  { email: "user2@example.com", name: "Bob" },
+  { email: "user3@example.com", name: "Carol" }
+]
+
+results = user_data.map { |data| UserService.new.call(data) }
+all_users = collect(results)  # Success([user1, user2, user3]) or first Failure
+
+# Transform a collection with Results
+result = traverse(user_emails) do |email|
+  user = User.find_by(email: email)
+  user ? Success(user) : Failure(:not_found, email)
+end
+# => Success([user1, user2, ...]) or first Failure
+
+# Convert Result containing array into array of Results
+result = Success([1, 2, 3])
+individual_results = sequence(result)
+# => [Success(1), Success(2), Success(3)]
+
+failure_result = Failure(:error, "failed")
+sequence(failure_result)
+# => [Failure(:error, "failed")]
+
+# Partition mixed Results into successes and failures
+mixed_results = [
+  Success("good1"),
+  Failure(:error, "bad1"),
+  Success("good2")
+]
+successes, failures = partition(mixed_results)
+# successes => ["good1", "good2"]
+# failures => [[:error, "bad1"]]
+```
+
+### Error Recovery
+
+Multiple fallback strategies:
+
+```ruby
+PrimaryPaymentService.new.call(order)
+  .or_else { |type, data| BackupPaymentService.new.call(order) }
+  .or_else { |type, data| ManualReviewService.new.call(order) }
+  .recover { |type, data|
+    # Last resort: create pending order
+    order.update!(status: 'pending_payment')
+    order
+  }
+```
+
+### Integration with ActiveRecord
+
+```ruby
+class Order
+  def self.create_with_validation(params)
+    order = new(params)
+
+    if order.valid?
+      order.save ? Llull::Success(order) : Llull::Failure(:save_failed, order.errors)
+    else
+      Llull::Failure(:validation, order.errors.full_messages)
+    end
+  end
+end
+
+# Usage
+Order.create_with_validation(params)
+  .and_then { |order| PaymentService.new.call(order) }
+  .and_then { |payment| ShippingService.new.call(payment.order) }
+```
+
+## API Reference
+
+### Result Methods
+
+- `success?` / `failure?` - Check result status
+- `value` / `error_type` / `error_data` - Access result data
+- `map { |value| ... }` - Transform successful values
+- `and_then { |value| ... }` - Chain Result-returning operations
+- `or_else { |type, data| ... }` - Recover with Result-returning operation
+- `recover { |type, data| ... }` - Convert failure to success value
+- `unwrap!` - Extract value (raises on failure)
+- `unwrap_or(default)` - Extract value with default
+- `value_or { |type, data| ... }` - Extract value with dynamic default
+- `tap_success { |value| ... }` - Side effect on success
+- `tap_failure { |type, data| ... }` - Side effect on failure
+- `on_success { |value| ... }` - Rails-friendly success handler
+- `on_failure(type = nil) { |type, data| ... }` - Rails-friendly failure handler
+
+### Module Methods
+
+- `Success(value)` - Create successful Result
+- `Failure(type, data = nil)` - Create failed Result
+- `collect(results)` - Combine multiple Results
+- `traverse(collection) { |item| ... }` - Map collection to Results and collect
+- `sequence(result)` - Convert Result containing array to array of Results
+- `partition(results)` - Split array of Results into [successes, failures]
+
+### Pattern Matching Support
+
+Results work with Ruby 3+ pattern matching via `deconstruct` and `deconstruct_keys`.
+
+## Requirements
+
+- Ruby 3.2+
+- No external dependencies
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/llull.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/llull/pattern_matching.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Llull
+  # Pattern matching functionality for Result instances
+  module PatternMatching
+    # Pattern matching support for Ruby 3+ (array-style)
+    # @return [Array] deconstructed result for pattern matching
+    def deconstruct
+      success? ? [:success, value] : [:failure, error_type, error_data]
+    end
+
+    # Pattern matching support for Ruby 3+ (hash-style)
+    # @param keys [Array<Symbol>] requested keys for pattern matching
+    # @return [Hash] deconstructed result for hash pattern matching
+    def deconstruct_keys(_keys)
+      if success?
+        { success: true, value: value }
+      else
+        { success: false, error_type: error_type, error_data: error_data }
+      end
+    end
+
+    # Advanced pattern matching with DSL
+    # @param block [Proc] block that receives a Matcher for defining patterns
+    # @return [Object] the result of executing the matched handler
+    def match(&block)
+      matcher = Matcher.new(self)
+      block.call(matcher)
+      matcher.execute
+    end
+  end
+end

data/lib/llull/result.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require_relative "pattern_matching"
+
+# Llull provides composable Result types for Ruby applications.
+# Inspired by functional programming and railway-oriented programming patterns.
+module Llull
+  # Result represents the result of an operation that can either succeed or fail.
+  # It provides a functional programming approach to error handling without exceptions.
+  class Result
+    attr_reader :value, :error_type, :error_data
+
+    # @param success [Boolean] whether this is a success or failure
+    # @param value [Object] the successful value (nil for failures)
+    # @param error_type [Symbol] the type/category of error (nil for successes)
+    # @param error_data [Object] additional error data (nil for successes)
+    def initialize(success, value, error_type = nil, error_data = nil)
+      @success = success
+      @value = value
+      @error_type = error_type
+      @error_data = error_data
+      freeze
+    end
+
+    # @return [Boolean] true if this is a successful result
+    def success?
+      @success
+    end
+
+    # @return [Boolean] true if this is a failed result
+    def failure?
+      !@success
+    end
+
+    # Transform the value if successful, return self if failed
+    # @param block [Proc] transformation to apply to the value
+    # @return [Result] new Result with transformed value or original failure
+    def map(&block)
+      return self if failure?
+
+      Llull::Success(block.call(value))
+    rescue StandardError => e
+      Llull::Failure(:exception, e)
+    end
+
+    # Chain operations that return Results
+    # @param block [Proc] operation that returns a Result
+    # @return [Result] the result of the operation or original failure
+    def and_then(&block)
+      return self if failure?
+
+      begin
+        result = block.call(value)
+        raise TypeError, "Block must return a Result" unless result.is_a?(Result)
+
+        result
+      rescue TypeError
+        raise # Re-raise TypeError so it's not caught by the general rescue below
+      rescue StandardError => e
+        Llull::Failure(:exception, e)
+      end
+    end
+
+    alias flat_map and_then
+    alias bind and_then
+
+    # Recover from failure by chaining another Result-returning operation
+    # @param block [Proc] operation that takes (error_type, error_data) and returns a Result
+    # @return [Result] the result of recovery operation or original success
+    def or_else(&block)
+      return self if success?
+
+      result = block.call(error_type, error_data)
+      raise TypeError, "Block must return a Result" unless result.is_a?(Result)
+
+      result
+    rescue StandardError => e
+      Llull::Failure(:exception, e)
+    end
+
+    # Recover from failure by transforming error into a success value
+    # @param block [Proc] operation that takes (error_type, error_data) and returns a value
+    # @return [Result] Success with transformed value or original success
+    def recover(&block)
+      return self if success?
+
+      Llull::Success(block.call(error_type, error_data))
+    rescue StandardError => e
+      Llull::Failure(:exception, e)
+    end
+
+    # Extract the value, raising an exception if this is a failure
+    # @return [Object] the success value
+    # @raise [ResultError] if this is a failure
+    def unwrap!
+      raise ResultError.new(error_type, error_data) if failure?
+
+      value
+    end
+
+    # Extract the value or return a default if this is a failure
+    # @param default [Object] the default value to return on failure
+    # @return [Object] the success value or the default
+    def unwrap_or(default)
+      success? ? value : default
+    end
+
+    # Extract the value or call a block with error information if this is a failure
+    # @param block [Proc] operation that takes (error_type, error_data) and returns a value
+    # @return [Object] the success value or the result of the block
+    def value_or(&block)
+      success? ? value : block.call(error_type, error_data)
+    end
+
+    # Execute a side effect if successful, return self unchanged
+    # @param block [Proc] operation to execute with the success value
+    # @return [Result] self, unchanged
+    def tap_success(&block)
+      block.call(value) if success?
+      self
+    end
+
+    # Execute a side effect if failed, return self unchanged
+    # @param block [Proc] operation to execute with (error_type, error_data)
+    # @return [Result] self, unchanged
+    def tap_failure(&block)
+      block.call(error_type, error_data) if failure?
+      self
+    end
+
+    alias tap_error tap_failure
+
+    # Execute a block if successful, return self for chaining
+    # @param block [Proc] operation to execute with the success value
+    # @return [Result] self, unchanged
+    def on_success(&block)
+      block.call(value) if success?
+      self
+    end
+
+    # Execute a block if failed with optional error type matching, return self for chaining
+    # @param match_type [Symbol, nil] specific error type to match, or nil for any failure
+    # @param block [Proc] operation to execute with (error_type, error_data)
+    # @return [Result] self, unchanged
+    def on_failure(match_type = nil, &block)
+      block.call(error_type, error_data) if failure? && (match_type.nil? || match_type == error_type)
+      self
+    end
+
+    # Inspect method for better debugging
+    def inspect
+      if success?
+        "#<Llull::Result::Success(#{value.inspect})>"
+      else
+        "#<Llull::Result::Failure(#{error_type.inspect}, #{error_data.inspect})>"
+      end
+    end
+
+    def to_s
+      inspect
+    end
+
+    # Equality comparison
+    def ==(other)
+      return false unless other.is_a?(Result)
+
+      success? == other.success? &&
+        value == other.value &&
+        error_type == other.error_type &&
+        error_data == other.error_data
+    end
+
+    alias eql? ==
+
+    def hash
+      [self.class, success?, value, error_type, error_data].hash
+    end
+
+    include PatternMatching
+  end
+
+  # Matcher class for the pattern matching DSL
+  class Matcher
+    def initialize(result)
+      @result = result
+      @success_handlers = []
+      @failure_handlers = {}
+      @executed = false
+    end
+
+    # Register a handler for successful results
+    # @param block [Proc] handler that receives the success value
+    # @return [Matcher] self for chaining
+    def success(&block)
+      @success_handlers << block
+      self
+    end
+
+    # Register a handler for failed results
+    # @param type [Symbol, nil] specific error type to match, or nil for catch-all
+    # @param block [Proc] handler that receives (error_type, error_data) for catch-all
+    #               or just (error_data) for specific type matches
+    # @return [Matcher] self for chaining
+    def failure(type = nil, &block)
+      if type.nil?
+        @failure_handlers[:catch_all] = block
+      else
+        @failure_handlers[type] = block
+      end
+      self
+    end
+
+    # Execute the appropriate handler based on the result
+    # @return [Object] the result of executing the matched handler
+    def execute
+      return if @executed
+
+      @executed = true
+
+      if @result.success?
+        @success_handlers.each { |handler| handler.call(@result.value) }
+      elsif @failure_handlers.key?(@result.error_type)
+        # Try specific error type handler first
+        @failure_handlers[@result.error_type].call(@result.error_data)
+      elsif @failure_handlers.key?(:catch_all)
+        @failure_handlers[:catch_all].call(@result.error_type, @result.error_data)
+      end
+    end
+  end
+
+  # Custom exception for Result errors
+  class ResultError < StandardError
+    attr_reader :error_type, :error_data
+
+    def initialize(error_type, error_data)
+      @error_type = error_type
+      @error_data = error_data
+      super("Result failure: #{error_type} - #{error_data}")
+    end
+  end
+
+  # Constructor functions for creating Results
+  module_function
+
+  # Create a successful Result
+  # @param value [Object] the successful value
+  # @return [Result] a successful Result containing the value
+  def Success(value)
+    Result.new(true, value)
+  end
+
+  # Create a failed Result
+  # @param error_type [Symbol] the type/category of error
+  # @param error_data [Object] additional error information
+  # @return [Result] a failed Result containing the error information
+  def Failure(error_type, error_data = nil)
+    Result.new(false, nil, error_type, error_data)
+  end
+
+  # Collect multiple Results into a single Result
+  # Returns Success with array of all values if all Results are successful,
+  # otherwise returns the first Failure encountered
+  # @param results [Array<Result>] array of Results to collect
+  # @return [Result] Success with array of values or first Failure
+  def collect(results)
+    results.each do |result|
+      raise TypeError, "All elements must be Results" unless result.is_a?(Result)
+      return result if result.failure?
+    end
+    Llull::Success(results.map(&:value))
+  end
+
+  alias all collect
+
+  # Transform a collection by applying a function that returns Results
+  # Similar to collect but maps over input and collects the results
+  # @param collection [Array] input collection to transform
+  # @param block [Proc] function that takes an element and returns a Result
+  # @return [Result] Success with array of transformed values or first Failure
+  def traverse(collection, &)
+    results = collection.map(&)
+    collect(results)
+  end
+
+  # Convert a Result containing an array into an array of Results
+  # @param result [Result] Result containing an array value
+  # @return [Array<Result>] array of individual Results
+  def sequence(result)
+    raise TypeError, "Argument must be a Result" unless result.is_a?(Result)
+
+    if result.success?
+      raise TypeError, "Result value must be an Array" unless result.value.is_a?(Array)
+
+      result.value.map { |item| Llull::Success(item) }
+    else
+      [result] # Return array containing the single failure
+    end
+  end
+
+  # Partition an array of Results into successes and failures
+  # @param results [Array<Result>] array of Results to partition
+  # @return [Array] tuple of [success_values, failure_tuples]
+  #   where success_values is Array of successful values
+  #   and failure_tuples is Array of [error_type, error_data] pairs
+  def partition(results)
+    validate_results_array(results)
+
+    successes, failures = results.partition(&:success?)
+    [successes.map(&:value), failures.map { |f| [f.error_type, f.error_data] }]
+  end
+
+  private
+
+  # Validate that all elements in array are Results
+  # @param results [Array] array to validate
+  # @raise [TypeError] if any element is not a Result
+  def validate_results_array(results)
+    results.each do |result|
+      raise TypeError, "All elements must be Results" unless result.is_a?(Result)
+    end
+  end
+end

data/lib/llull/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Llull
+  VERSION = "0.2.0"
+end

data/lib/llull.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "llull/version"
+require_relative "llull/result"
+
+module Llull
+  class Error < StandardError; end
+
+  # Include the module functions so they're available when including Llull
+end

data/sig/llull.rbs

@@ -0,0 +1,93 @@
+module Llull
+  VERSION: String
+
+  class Result[out Value, out ErrorData]
+    @success: bool
+    @value: Value?
+    @error_type: Symbol?
+    @error_data: ErrorData?
+
+    def initialize: (bool success, Value? value, Symbol? error_type, ErrorData? error_data) -> void
+
+    def success?: () -> bool
+    def failure?: () -> bool
+    def value: () -> Value?
+    def error_type: () -> Symbol?
+    def error_data: () -> ErrorData?
+
+    # Monadic operations
+    def map: [NewValue] () { (Value) -> NewValue } -> Result[NewValue, ErrorData]
+    def and_then: [NewValue] () { (Value) -> Result[NewValue, ErrorData] } -> Result[NewValue, ErrorData]
+    def flat_map: [NewValue] () { (Value) -> Result[NewValue, ErrorData] } -> Result[NewValue, ErrorData]
+    def bind: [NewValue] () { (Value) -> Result[NewValue, ErrorData] } -> Result[NewValue, ErrorData]
+
+    # Recovery operations
+    def or_else: [NewValue] () { (Symbol, ErrorData) -> Result[NewValue, ErrorData] } -> Result[NewValue | Value, ErrorData]
+    def recover: [NewValue] () { (Symbol, ErrorData) -> NewValue } -> Result[NewValue | Value, ErrorData]
+
+    # Unwrapping
+    def unwrap!: () -> Value
+    def unwrap_or: [DefaultValue] (DefaultValue default) -> (Value | DefaultValue)
+    def value_or: [DefaultValue] () { (Symbol, ErrorData) -> DefaultValue } -> (Value | DefaultValue)
+
+    # Side effects
+    def tap_success: () { (Value) -> untyped } -> self
+    def tap_failure: () { (Symbol, ErrorData) -> untyped } -> self
+    def tap_error: () { (Symbol, ErrorData) -> untyped } -> self
+
+    # Rails-friendly helpers
+    def on_success: () { (Value) -> untyped } -> self
+    def on_failure: (?Symbol? match_type) { (Symbol, ErrorData) -> untyped } -> self
+
+    # Pattern matching support
+    def deconstruct: () -> [:success, Value] | [:failure, Symbol, ErrorData]
+    def deconstruct_keys: (Array[Symbol] keys) -> { success: bool, value: Value?, error_type: Symbol?, error_data: ErrorData? }
+
+    # Matching DSL
+    def match: [ReturnType] () { (Matcher[Value, ErrorData]) -> ReturnType } -> ReturnType
+
+    # Equality and inspection
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+    def inspect: () -> String
+    def to_s: () -> String
+  end
+
+  class Matcher[Value, ErrorData]
+    def initialize: (Result[Value, ErrorData] result) -> void
+    def success: () { (Value) -> untyped } -> self
+    def failure: (?Symbol? type) { (Symbol, ErrorData) -> untyped } | { (ErrorData) -> untyped } -> self
+    def execute: () -> untyped
+  end
+
+  class ResultError < StandardError
+    attr_reader error_type: Symbol
+    attr_reader error_data: untyped
+
+    def initialize: (Symbol error_type, untyped error_data) -> void
+  end
+
+  # Constructor functions
+  def self.Success: [Value] (Value value) -> Result[Value, untyped]
+  def self.Failure: [ErrorData] (Symbol error_type, ?ErrorData? error_data) -> Result[untyped, ErrorData]
+
+  # Collection operations
+  def self.collect: [Value, ErrorData] (Array[Result[Value, ErrorData]] results) -> Result[Array[Value], ErrorData]
+  def self.all: [Value, ErrorData] (Array[Result[Value, ErrorData]] results) -> Result[Array[Value], ErrorData]
+  def self.traverse: [Input, Value, ErrorData] (Array[Input] collection) { (Input) -> Result[Value, ErrorData] } -> Result[Array[Value], ErrorData]
+  def self.sequence: [Value, ErrorData] (Result[Array[Value], ErrorData] result) -> Array[Result[Value, ErrorData]]
+  def self.partition: [Value, ErrorData] (Array[Result[Value, ErrorData]] results) -> [Array[Value], Array[[Symbol, ErrorData]]]
+
+  # Module functions available when including Llull
+  def Success: [Value] (Value value) -> Result[Value, untyped]
+  def Failure: [ErrorData] (Symbol error_type, ?ErrorData? error_data) -> Result[untyped, ErrorData]
+  def collect: [Value, ErrorData] (Array[Result[Value, ErrorData]] results) -> Result[Array[Value], ErrorData]
+  def all: [Value, ErrorData] (Array[Result[Value, ErrorData]] results) -> Result[Array[Value], ErrorData]
+  def traverse: [Input, Value, ErrorData] (Array[Input] collection) { (Input) -> Result[Value, ErrorData] } -> Result[Array[Value], ErrorData]
+  def sequence: [Value, ErrorData] (Result[Array[Value], ErrorData] result) -> Array[Result[Value, ErrorData]]
+  def partition: [Value, ErrorData] (Array[Result[Value, ErrorData]] results) -> [Array[Value], Array[[Symbol, ErrorData]]]
+
+  class Error < StandardError
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: llull
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Thomas Murphy
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  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-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Inspired by railway-oriented programming, Llull provides chainable operations
+  that make complex business logic clear and maintainable.
+email:
+- thomaspmurphy@proton.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/llull.rb
+- lib/llull/pattern_matching.rb
+- lib/llull/result.rb
+- lib/llull/version.rb
+- sig/llull.rbs
+homepage: https://github.com/thomaspmurphy/llull
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/thomaspmurphy/llull
+  source_code_uri: https://github.com/thomaspmurphy/llull
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Composable result types for Ruby.
+test_files: []