ract 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 48ebc9d97681afc2240e5001650e74d7250e76d20eb181955b402192377c8ca8
+  data.tar.gz: 8c121a49a43a61beff3a8f5f068997585951fbb4acd6e4432b89e8cad571ba0d
+SHA512:
+  metadata.gz: 4b82bcf08d12aa28ffd6ac36f66572cb9b40a6a82e5f364d09eb37adbf0e79a7d7ac9f32a608dbd04dd62439487193ddd32ac3bca5d5a07f5d31de1306f8633b
+  data.tar.gz: b6cf72683bd4a7bdf7b7fd7756af98726627c56321ca65938663d47bd8469d8982031d97b2786f347ad4894f27eb255a43ef6766e2870a71cb1f4c42738e4284

data/.editorconfig

@@ -0,0 +1,12 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = false
+insert_final_newline = false

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# CHANGELOG
+
+## [Unreleased]
+

data/Gemfile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'
+
+group :test do
+  gem 'pry', '~> 0.15.2'
+  gem 'minitest', '~> 5.16'
+  gem 'minitest-reporters', '~> 1.6'
+  gem 'minitest-hooks'
+  gem 'rspec'
+  gem 'simplecov', '~> 0.22.0', require: false
+  gem 'simplecov-console', '~> 0.9.3', require: false
+  gem 'standard', '~> 1.49'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Thadeu Esteves Jr
+
+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,213 @@
+<h1 style="z-index: 999;">Ract</h1>
+
+<center>
+  <img src="./images/ract-no-bg.png" alt="Ract Logo" width="65%" style="position: relative; margin-top: -50px; z-index: -1; mix-blend-mode: overlay;">
+</center>
+
+Ract is a lightweight Promise implementation for Ruby, providing a clean and intuitive way to handle asynchronous operations. It follows a similar pattern to JavaScript Promises, making it easy to write non-blocking code with proper error handling.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```ruby
+gem 'ract'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+or using add
+
+```bash
+$ bundle add ract
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install ract
+```
+
+## Usage
+
+```ruby
+require 'ract'
+```
+
+### Basic Usage
+
+Create a new promise with a block that will be executed asynchronously:
+
+```ruby
+# Create a promise that resolves with a value
+promise = Ract.new { 42 } # or just Ract { 42 }
+
+# Create a promise that might reject with an error
+promise = Ract.new do
+  if success_condition
+    "Success result"
+  else
+    raise "Something went wrong"
+  end
+end
+```
+
+### Handling Promise Resolution
+
+Use `.then` to handle successful resolution:
+
+```ruby
+promise = Ract.new { 42 }
+
+promise.then do |value|
+  puts "The answer is #{value}"
+end
+```
+
+### Error Handling
+
+Use `.rescue` (or its alias `.catch`) to handle rejections:
+
+```ruby
+promise = Ract.new { raise "Something went wrong" }
+
+promise
+  .then { |value| puts "This won't be called" }
+  .rescue { |error| puts "Error: #{error.message}" }
+```
+
+### Chaining Promises
+
+Promises can be chained for sequential asynchronous operations:
+
+```ruby
+Ract.new { fetch_user(user_id) }
+  .then { |user| fetch_posts(user.id) }
+  .and_then { |posts| render_posts(posts) }
+  .rescue { |error| handle_error(error) }
+  .catch { |error| handle_error(error) }
+```
+
+### Waiting for Resolution
+
+If you need to wait for a promise to resolve, use `.await`:
+
+```ruby
+promise = Ract.new { time_consuming_operation }
+result = promise.await  # Blocks until the promise resolves
+```
+
+### Creating Pre-resolved Promises
+
+Create already resolved or rejected promises:
+
+```ruby
+# Already resolved promise
+promise = Ract.resolve(42)
+
+# Already rejected promise
+promise = Ract.reject("Something went wrong")
+```
+
+### Combining Multiple Promises
+
+Wait for multiple promises to complete:
+
+```ruby
+# Wait for all promises to resolve (will raise an error if any promise rejects)
+promises = [Ract.new { task1 }, Ract.new { task2 }]
+combined = Ract.all(promises)
+
+# Wait for all promises to resolve (will not raise errors, returns results with status)
+combined = Ract.all(promises, raise_on_error: false)
+
+# Get results when all are settled (resolved or rejected)
+results = Ract.all_settled(promises)
+```
+
+### Using block
+
+You can use a block to receive result
+
+```ruby
+tasks = [ ract { "mylogs" } ]
+
+Ract.take(tasks) { p it }
+# ["mylogs"]
+```
+
+This update properly explains that:
+
+1. By default, `Ract.all` will raise an error if any of the promises are rejected
+2. You can set `raise_on_error: false` to get all results regardless of whether they resolved or rejected
+3. Alternatively, you can use `Ract.all_settled` to get results for all promises whether they resolved or rejected
+
+### Immediate Execution
+
+If you need to execute a block immediately with the current value, regardless of the promise state:
+
+```ruby
+promise = Ract.new { 42 }
+promise.then { |value| puts "Current value: #{value}" }
+```
+
+### Async/Await Pattern
+
+Ract supports an async/await pattern similar to JavaScript:
+
+```ruby
+# Define an async method
+async def fetch_data
+  user = fetch_user(user_id)
+  posts = fetch_posts(user.id)
+  comments = fetch_comments(posts.first.id)
+
+  return { user: user, posts: posts, comments: comments }
+end
+
+# Use the async method
+result = fetch_data.await
+```
+
+### Examples using many callable promises
+
+```ruby
+class Dynamo
+  async def self.get_item(table, key)
+    { Item: {} }
+  end
+end
+
+tasks = [
+  Dynamo.get_item_async('users', 1),
+  Dynamo.get_item_async('posts', 1),
+  Dynamo.get_item_async('comments', 1)
+]
+
+result_all = Ract.all(tasks, raise_on_error: false) 
+result_taken = Ract.take(tasks, raise_on_error: false) 
+
+p result_all
+# [{ Item: {} }, { Item: {} }, { Item: {} }]
+
+p result_taken
+# [{ Item: {} }, { Item: {} }, { Item: {} }]
+```
+
+## 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/thadeu/ract.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,19 @@
+# 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
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'spec'
+  t.libs << 'lib'
+  t.test_files = FileList['spec/**/*_spec.rb']
+end
+
+task default: %i[spec test rubocop]

data/lib/ract/async.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true # :rdoc
+
+class Ract
+  module Async
+    def self.included(base)
+      base.include(ClassMethods)
+    end
+
+    def self.extended(base)
+      base.extend(ClassMethods)
+    end
+
+    def Ract
+      Ract.new { yield }
+    end
+
+    module ClassMethods
+      def ract
+        Ract { yield }
+      end
+
+      def async(method_name)
+        if method_defined?(method_name)
+          original_method = instance_method(method_name)
+
+          define_method("#{method_name}_async") do |*args, **kwargs, &block|
+            Ract { original_method.bind(self).call(*args, **kwargs, &block) }
+          end
+        elsif singleton_methods.include?(method_name)
+          define_singleton_method("#{method_name}_async") do |*args, **kwargs, &block|
+            Ract { send(method_name, *args, **kwargs, &block) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ract/batch.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true # :rdoc
+
+class Ract
+  class Batch
+    attr_reader :promises, :remaining
+
+    def initialize(promises)
+      @promises = promises.keep_if { |promise| promise.is_a?(Ract) }
+      @queue = Thread::Queue.new
+      @remaining = promises.size
+    end
+
+    def run!(&block)
+      return if @promises.empty?
+
+      create_threads
+      process_results(&block)
+    end
+
+    def create_threads
+      @promises.each_with_index do |promise, index|
+        Thread.new do
+          try_block!(promise)
+
+          promise.then do |value|
+            @queue << [:success, index, value]
+          end&.rescue do |reason|
+            @queue << [:error, index, reason]
+          end
+        rescue StandardError => e
+          @queue << [:error, index, e]
+        end
+      end
+    end
+
+    def process_results(&block)
+      while @remaining.positive?
+        block.call(@queue.pop)
+        @remaining -= 1
+      end
+    end
+
+    def try_block!(promise)
+      return unless promise.respond_to?(:execute_block)
+      return unless promise.state == Ract::PENDING
+
+      promise.execute_block
+    end
+  end
+end

data/lib/ract/ract.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+class Ract
+  class Error < StandardError; end
+  class Rejected < StandardError; end
+
+  PENDING = :pending
+  FULFILLED = :fulfilled
+  REJECTED = :rejected
+
+  attr_reader :state, :value, :reason
+
+  def initialize(value = nil, auto_execute: false, &block)
+    @state = PENDING
+    @value = value
+    @reason = nil
+    @mutex = Mutex.new
+    @condition = ConditionVariable.new
+
+    @callbacks = []
+    @error_callbacks = []
+    @block = block
+
+    if block_given? && auto_execute
+      execute_block
+    end
+  end
+
+  def execute_block
+    return unless @block
+
+    begin
+      resolve(@block.call)
+    rescue StandardError => e
+      reject(e)
+    end
+  end
+
+  def fulfilled?
+    @state == FULFILLED
+  end
+
+  def rejected?
+    @state == REJECTED
+  end
+
+  def await
+    raise Rejected, @reason.to_s if @state == REJECTED
+
+    resolve
+
+    @value
+  end
+
+  def resolve(value = nil)
+    synchronize do
+      return if @state != PENDING
+
+      @state = FULFILLED
+      @value = value.nil? && @block ? @block.call : value
+      @condition&.broadcast
+      execute_callbacks
+    end
+  end
+
+  def reject(reason = nil)
+    synchronize do
+      return if @state != PENDING
+
+      @state = REJECTED
+      @reason = reason
+      @condition&.broadcast
+      execute_error_callbacks
+    end
+  end
+
+  def then(&block)
+    return self unless block_given?
+
+    if @state == PENDING
+      execute_block
+      @callbacks << block
+    end
+
+    return self if @state == REJECTED
+
+    begin
+      block.call(@value)
+    rescue StandardError => e
+      @state = REJECTED
+      @reason = e
+      reject(e)
+    end
+
+    self
+  end
+  alias and_then then
+
+  def rescue(&block)
+    return self unless block_given?
+
+    if @state == PENDING
+      execute_block
+      @error_callbacks << block
+    end
+
+    if @state == REJECTED
+      block.call(@reason)
+    end
+
+    self
+  end
+  alias catch rescue
+
+  class << self
+    include SingleMethods
+  end
+
+  private
+
+  def execute_callbacks
+    callbacks = @callbacks.dup
+    @callbacks.clear
+    callbacks.each { |callback| callback.call(@value) }
+  end
+
+  def execute_error_callbacks
+    callbacks = @error_callbacks.dup
+    @error_callbacks.clear
+    callbacks.each { |callback| callback.call(@reason) }
+  end
+
+  def synchronize(&block)
+    @mutex.synchronize(&block)
+  end
+end
+
+Object.include Ract::Async
+Module.extend Ract::Async

data/lib/ract/result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true # :rdoc
+
+class Ract
+  class Result
+    include Enumerable
+
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def deconstruct
+      [@value]
+    end
+
+    def deconstruct_keys(_keys)
+      { value: @value, count: @value.size }
+    end
+
+    def and_then(&block)
+      return self unless block_given?
+
+      block.call(@value)
+
+      self
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      @value.each(&block)
+
+      self
+    end
+  end
+end

data/lib/ract/settled.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true # :rdoc
+
+class Ract
+  class Settled
+    attr_reader :type, :raise_on_error
+
+    def initialize(promises, type: :all, raise_on_error: true)
+      @results = Array.new(promises.size)
+      @batch = Batch.new(promises)
+      @type = type
+      @raise_on_error = raise_on_error
+    end
+
+    def run!
+      return Result.new([]) if @batch.promises.empty?
+
+      @batch.run! do |type, index, value|
+        case type
+        when :success
+          @results[index] = success_row(value)
+        when :error
+          raise Rejected, value if @raise_on_error && @type == :all
+
+          @results[index] = rejected_row(value)
+        end
+      end
+
+      Result.new(@results)
+    end
+
+    def success_row(value)
+      return value if @type == :all
+
+      { status: Ract::FULFILLED, value: value }
+    end
+
+    def rejected_row(reason)
+      return reason if @type == :all
+
+      { status: Ract::REJECTED, reason: reason }
+    end
+  end
+end

data/lib/ract/single_methods.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true # :rdoc
+
+class Ract
+  module SingleMethods
+    def resolve(value = nil, auto_execute: false)
+      new(auto_execute: true) { value }.await
+    end
+
+    def reject(reason = nil, auto_execute: false)
+      new(auto_execute: true) { raise Rejected, reason }.await
+    end
+
+    def all(promises, raise_on_error: true, auto_execute: false, &block)
+      return [] if promises.empty?
+
+      result = Settled.new(promises, raise_on_error: raise_on_error).run!
+
+      block.call(result.value) if block_given?
+
+      result.value
+    end
+    alias take all
+
+    def all_settled(promises, auto_execute: false, &block)
+      return [] if promises.empty?
+
+      result = Settled.new(promises, type: :all_settled).run!
+
+      block.call(result.value) if block_given?
+
+      result.value
+    end
+  end
+end

data/lib/ract/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true # :rdoc
+
+class Ract
+  VERSION = "0.1.0"
+end

data/lib/ract.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'ract/version'
+require 'ract/batch'
+require 'ract/result'
+require 'ract/settled'
+require 'ract/async'
+require 'ract/single_methods'
+require 'ract/ract'
+
+# A lightweight Promise implementation for Ruby
+#
+# == Usage
+#
+# You can use `Ract.new` or `Ract` to create a new promise
+#
+#   Ract.new { 1 }
+#
+#   Ract { 1 }
+#
+# You can use `async` to define an async method
+#     class ComplexTask
+#       async def self.execute(...)
+#         new(...).execute
+#       end
+#
+#       def initialize(...)
+#       end
+#
+#       def execute
+#       end
+#
+#       async def call
+#         # your complex logic
+#       end
+#     end
+#
+# If you use with color async method, you must be use with suffix _async, for example:
+# This will create another method with _async suffix, to encapsulate the logic in a Thread
+#
+#    ComplexTask.call_async
+#
+#    ComplexTask.execute_async
+#
+# You can use `ract` or `go` to define a method that returns a promise
+#
+#   def call
+#     ract { 1 }
+#   end
+#
+#   def call
+#     go { 1 }
+#   end
+#
+#   def call
+#     Ract { 1 }
+#   end
+#
+# == Multiple Racts
+#
+# You can use `Ract.take` to perform multiple promises together
+#
+#   tasks = [ Ract { 1 }, Ract.new { 2 } ]
+#
+# Running your tasks using .take
+#
+#   result = Ract.take(tasks)
+#
+# after that you will have an array with results
+#
+#   p result -> [1, 2]
+#
+class Ract
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: ract
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thadeu Esteves Jr
+bindir: exe
+cert_chain: []
+date: 2025-04-17 00:00:00.000000000 Z
+dependencies: []
+description: A simple and lightweight gem to wrapper Threads(Promises) like JavaScript
+  in Ruby, adding a color to Ruby Threads
+email:
+- tadeuu@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".rspec"
+- ".ruby-version"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- images/little-kernel-no-bg.png
+- images/ract-flow.png
+- images/ract-no-bg.png
+- lib/ract.rb
+- lib/ract/async.rb
+- lib/ract/batch.rb
+- lib/ract/ract.rb
+- lib/ract/result.rb
+- lib/ract/settled.rb
+- lib/ract/single_methods.rb
+- lib/ract/version.rb
+homepage: https://github.com/thadeu/ract-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/thadeu/ract-rb
+  source_code_uri: https://github.com/thadeu/ract-rb
+  changelog_uri: https://github.com/thadeu/ract-rb/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A simple and lightweight gem to wrapper Threads(Promises) like JavaScript
+  in Ruby
+test_files: []