mayak 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c11b0f5c9288055fd9f0ca907a38e257b06b78fdd0f4e1185fafa8beae4fdcc2
+  data.tar.gz: f49566c5b0d830610843288c56ae001513a72b34b5beb75a9cb764998c0e6abd
+SHA512:
+  metadata.gz: b24805002d39350e5d6fa0f4b8bc501b6c576b34368bc90eca7af794f820f191e7c4e35c1487cb3083ddabd18e2dbb1929822801cd934eebeac298c4bb5d34d4
+  data.tar.gz: 87275eb153d98c62d264c20a51db6e99109ec519eb957fbf4728f3b0612686aa41f76f728090d332d72323d16e7a954751fb17ad23b1bf9bff3cf99eba20fef8

data/README.md

@@ -0,0 +1,33 @@
+# Mayak
+
+### Overview
+
+Mayak is a library which aims to provide abstractions for well typed programming in Ruby using Sorbet type checker. Mayak provides generic interfaces and utility classes for various applications, and as a foundation for other libraries.
+
+### Installation
+
+In order to use the library, add the following line to your `Gemfile`:
+
+```ruby
+gem 'mayak'
+```
+or install it via the following command:
+```ruby
+gem install 'mayak'
+```
+
+### Documentation
+
+Mayak consists from separate classes and interfaces as well as separate modules for specific domains.
+
+#### Caching
+
+[Documentation](./lib/mayak/caching/README.md)
+
+#### Monads
+
+[Documentation](./lib/mayak/monads/README.md)
+
+#### HTTP
+
+[Documentation](./lib/mayak/http/README.md)

data/lib/mayak/cache.rb

@@ -0,0 +1,35 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mayak
+  module Cache
+    extend T::Sig
+    extend T::Generic
+    extend T::Helpers
+
+    interface!
+
+    Key   = type_member
+    Value = type_member
+
+    sig { abstract.params(key: Key).returns(T.nilable(Value)) }
+    def read(key)
+    end
+
+    sig { abstract.params(key: Key, value: Value).void }
+    def write(key, value)
+    end
+
+    sig { abstract.params(key: Key, blk: T.proc.returns(Value)).returns(Value) }
+    def fetch(key, &blk)
+    end
+
+    sig { abstract.void }
+    def clear
+    end
+
+    sig { abstract.params(key: Key).void }
+    def delete(key)
+    end
+  end
+end

data/lib/mayak/caching/README.md

@@ -0,0 +1,100 @@
+# Caching
+
+Caching modules constist from `Mayak::Cache` and several implementations in `Mayak::Caching` module. `Mayak::Caching` provides in-memory caches using regular ruby hashes: an unbounded cache and a cache using LRU eviction policy.
+
+Usage of unbounded cache:
+```ruby
+unbounded_cache = Mayak::Caching::UnboundedCache[String, Integer].new
+unbounded_cache.write("foo", 10)
+unbounded_cache.write("bar", 20)
+
+unbounded_cache.read("foo") # 10
+unbounded_cache.read("bar") # 20
+unbounded_cache.read("baz") # nil
+
+unbounded_cache.delete("bar")
+unbounded_cache.read("bar") # nil
+
+unbounded_cache.fetch("foo") { 100 } # 10
+unbounded_cache.fetch("bar") { 100 } # 100
+unbounded_cache.fetch("bar") { 200 } # 100
+
+unbounded_cache.clear # 100
+unbounded_cache.read("foo") # nil
+unbounded_cache.read("bar") # nil
+```
+
+LRU cache has limited size: when the cache is full and a new element is added, some element is evicted using least recently used policy:
+
+```ruby
+lru_cache = Mayak::Caching::LRUCache[String, Integer].new(max_size: 3)
+
+lru_cache.write("key1", 1)
+lru_cache.write("key2", 2)
+lru_cache.write("key3", 3)
+
+lru_cache.read("key1") # 1
+lru_cache.read("key2") # 2
+lru_cache.read("key3") # 3
+
+lru_cache.write("key4", 4)
+lru_cache.read("key4") # 4
+lru_cache.read("key1") # nil
+```
+
+You can implement `Mayak::Cache` interface using a different store (for example default Rails cache) and use different implementations interchangeably:
+
+```ruby
+class RailsCache < T::Struct
+  extend T::Sig
+  extend T::Generic
+  extend T::Helpers
+
+  include Mayak::Cache
+
+  Key   = type_member
+  Value = type_member
+
+  const :converter, T.proc.params(value: T.untyped).returns(Value)
+
+  sig { override.params(key: Key).returns(T.nilable(Value)) }
+  def read(key)
+    converter.call(Rails.cache.read(key))
+  end
+
+  sig { override.params(key: Key, value: Value).void }
+  def write(key, value)
+    Rails.cache.write(key, value)
+  end
+
+  sig { override.params(key: Key, blk: T.proc.returns(Value)).returns(Value) }
+  def fetch(key, &blk)
+    converter.call(Rails.cache.fetch(key, &blk))
+  end
+
+  sig { override.void }
+  def clear
+    Rails.cache.clear
+  end
+
+  sig { override.params(key: Key).void }
+  def delete(key)
+    Rails.cache.delete(key)
+  end
+end
+
+class Service < T::Struct
+  extend T::Sig
+
+  const :cache, Mayak::Cache[String, String]
+end
+
+in_memory = Service.new(
+  cache: Mayak::Caching::UnboundedCache[String, String].new
+)
+rails_cache = Service.new(
+  cache: RailsCache[String, String].new(
+    converter: -> (value) { value.to_s }
+  )
+)
+```

data/lib/mayak/caching/lru_cache.rb

@@ -0,0 +1,76 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mayak
+  module Caching
+    class LRUCache
+      extend T::Sig
+      extend T::Generic
+      extend T::Helpers
+
+      include Mayak::Cache
+
+      Key   = type_member
+      Value = type_member
+
+      sig { returns(Integer) }
+      attr_reader :max_size
+
+      sig { params(max_size: Integer).void }
+      def initialize(max_size:)
+        @storage  = T.let({}, T::Hash[Key, Value])
+        if max_size <= 0
+          raise ArgumentError.new("max_size should be a positive integer")
+        end
+        @max_size = T.let(max_size, Integer)
+      end
+
+      sig { override.params(key: Key).returns(T.nilable(Value)) }
+      def read(key)
+        @storage[key]
+      end
+
+      sig { override.params(key: Key, value: Value).void }
+      def write(key, value)
+        if @storage.size == max_size && !@storage.key?(key)
+          evict!
+        elsif @storage.key?(key)
+          @storage.delete(key)
+        end
+        @storage[key] = value
+      end
+
+      sig { override.params(key: Key, blk: T.proc.returns(Value)).returns(Value) }
+      def fetch(key, &blk)
+        return T.must(@storage[key]) if @storage.has_key?(key)
+
+        value = blk.call
+        write(key, value)
+        value
+      end
+
+      sig { override.void }
+      def clear
+        @storage.clear
+      end
+
+      sig { override.params(key: Key).void }
+      def delete(key)
+        @storage.delete(key)
+      end
+      
+      private
+
+      sig { void }
+      def evict!
+        first_key = @storage.first&.first
+        case first_key
+        when NilClass
+          return
+        else
+          @storage.delete(first_key)
+        end
+      end
+    end
+  end
+end

data/lib/mayak/caching/unbounded_cache.rb

@@ -0,0 +1,51 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mayak
+  module Caching
+    class UnboundedCache
+      extend T::Sig
+      extend T::Generic
+      extend T::Helpers
+
+      include Mayak::Cache
+
+      Key   = type_member
+      Value = type_member
+
+      sig { void }
+      def initialize
+        @storage = T.let({}, T::Hash[Key, Value])
+      end
+
+      sig { override.params(key: Key).returns(T.nilable(Value)) }
+      def read(key)
+        @storage[key]
+      end
+
+      sig { override.params(key: Key, value: Value).void }
+      def write(key, value)
+        @storage[key] = value
+      end
+
+      sig { override.params(key: Key, blk: T.proc.returns(Value)).returns(Value) }
+      def fetch(key, &blk)
+        return T.must(@storage[key]) if @storage.has_key?(key)
+
+        value = blk.call
+        @storage[key] = value
+        value
+      end
+
+      sig { override.void }
+      def clear
+        @storage.clear
+      end
+
+      sig { override.params(key: Key).void }
+      def delete(key)
+        @storage.delete(key)
+      end
+    end
+  end
+end

data/lib/mayak/collections/README.md

@@ -0,0 +1,62 @@
+# Collections
+
+Set of performant type safe collections written in ruby.
+
+### Queue
+
+Regular parameterized FIFO queue with O(1) enqueue and dequeue operations. The difference between Mayak's Queue and standard library Queue is that former is plain data struture that doesn't block, while the latter is a synchronization multi-producer, multi-consumer queue.
+
+Usage:
+```ruby
+queue = Mayak::Collections::Queue[Integer].new
+
+# adds an element to the queue
+queue.enqueue(1)
+queue.enqueue(2)
+queue.enqueue(3)
+
+# returns first queue element without updating the queue
+queue.peak # 1
+
+# returns an element and remove it from collection
+queue.dequeue # 1
+queue.dequeue # 2
+queue.dequeue # 3
+queue.dequeue # nil
+
+# checks whether collection is empty
+queue.empty? # true
+queue.enqueue(1)
+queue.empty? # false
+```
+
+### Priority Queue
+
+Implements a queue where aach element has an associated priority. Elements with high priority are served before elements with low priority. The priority queue is parameterized with both element and priority types. Priority queue is initialized with a comparator function that returns a boolean value (true if a first argument is larger that a second).
+
+Usage:
+```ruby
+pqueue = Mayak::Collections::PriorityQueue[String, Integer].new { |a, b| a > b }
+
+# adds an element with a priority
+pqueue.enqueue("second", 8)
+pqueue.enqueue("third", 5)
+pqueue.enqueue("first", 10)
+# returns a pair of value and priority and remove it from the queue
+pqueue.dequeue # ["first", 10]
+pqueue.dequeue # ["second", 8]
+pqueue.dequeue # ["third", 5]
+
+# returns a first pair without removing it from the queue
+pqueue.peak # nil
+pqueue.enqueue("first", 10)
+pqueue.peak # ["first", 10]
+pqueue.dequeue # ["first", 10]
+
+pqueue.enqueue("second", 8)
+pqueue.enqueue("third", 5)
+pqueue.enqueue("first", 10)
+
+# returns an array containing all pairs preserving internal heap structure
+pqueue.to_a # [["first", 10], ["third", 5], ["second", 8]]
+```

data/lib/mayak/collections/priority_queue.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Mayak
+  module Collections
+    class PriorityQueue
+      extend T::Sig
+      extend T::Generic
+
+      Element  = type_member
+      Priority = type_member
+
+      sig { returns(Integer) }
+      attr_reader :size
+
+      sig { params(compare: T.proc.params(arg0: Priority, arg2: Priority).returns(T::Boolean)).void }
+      def initialize(&compare)
+        @array   = T.let([], T::Array[T.nilable([Element, Priority])])
+        @compare = T.let(compare, T.proc.params(arg0: Priority, arg2: Priority).returns(T::Boolean))
+        @size    = T.let(0, Integer)
+      end
+
+      sig { params(element: Element, priority: Priority).void }
+      def enqueue(element, priority)
+        @array[@size] = [element, priority]
+        @size += 1
+        sift_up(size - 1)
+      end
+
+      sig { returns(T.nilable([Element, Priority])) }
+      def dequeue
+        element_index = 0
+        result = @array[element_index]
+
+        if @size > 1
+          @size -= 1
+          @array[element_index] = @array[@size]
+          sift_down(element_index)
+        else
+          @size = 0
+        end
+
+        @array[@size] = nil
+
+        result
+      end
+
+      sig { returns(T.nilable([Element, Priority])) }
+      def peak
+        @array.first
+      end
+
+      sig { void }
+      def clear
+        @array = []
+        @size = 0
+      end
+
+      sig { returns(T::Array[[Element, Priority]]) }
+      def to_a
+        @array.compact
+      end
+
+      sig { returns(T::Boolean) }
+      def empty?
+        size == 0
+      end
+
+      private
+
+      sig { params(element_index: Integer).void }
+      def sift_up(element_index)
+        index = element_index
+
+        while !root?(index) && compare(index, parent_index(index))
+          swap(index, parent_index(index))
+          index = parent_index(index)
+        end
+      end
+
+      sig { params(element_index: Integer).void }
+      def sift_down(element_index)
+        index = element_index
+
+        loop do
+          left_index = left_child_index(index)
+          right_index = right_child_index(index)
+
+          if has_left_child(index) && compare(left_index, index)
+            swap(index, left_index)
+            index = left_index
+          elsif has_right_child(index) && compare(right_index, index)
+            swap(index, right_index)
+            index = right_index
+          else
+            break
+          end
+        end
+      end
+
+      sig { params(index1: Integer, index2: Integer).void }
+      def swap(index1, index2)
+        @array[index1], @array[index2] = @array[index2], @array[index1]
+      end
+
+      sig { params(index1: Integer, index2: Integer).returns(T::Boolean) }
+      def compare(index1, index2)
+        value1 = @array[index1]
+        value2 = @array[index2]
+
+        raise StandardError.new("index out of bound") if value1.nil? || value2.nil?
+
+        _, priority1 = value1
+        _, priority2 = value2
+
+        @compare.call(priority1, priority2)
+      end
+
+      sig { params(index: Integer).returns(T::Boolean) }
+      def has_parent(index)
+        index >= 1
+      end
+
+      sig { params(index: Integer).returns(Integer) }
+      def parent_index(index)
+        ((index - 1) / 2).floor
+      end
+
+      sig { params(index: Integer).returns(T::Boolean) }
+      def has_left_child(index)
+        left_child_index(index) < @size
+      end
+
+      sig { params(index: Integer).returns(Integer) }
+      def left_child_index(index)
+        index * 2 + 1
+      end
+
+      sig { params(index: Integer).returns(T::Boolean) }
+      def has_right_child(index)
+        right_child_index(index) < @size
+      end
+
+      sig { params(index: Integer).returns(Integer) }
+      def right_child_index(index)
+        index * 2 + 2
+      end
+
+      sig { params(index: Integer).returns(T::Boolean) }
+      def root?(index)
+        index == 0
+      end
+    end
+  end
+end

data/lib/mayak/collections/queue.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Mayak
+  module Collections
+    class Queue
+      extend T::Sig
+      extend T::Helpers
+      extend T::Generic
+
+      Value = type_member
+
+      class Node < T::Struct
+        extend T::Sig
+        extend T::Generic
+
+        Value = type_member
+
+        const :value, Value
+        prop  :next,  T.nilable(Node[Value])
+      end
+      private_constant :Node
+
+      sig { returns(Integer) }
+      attr_reader :size
+
+      sig { params(initial: T::Array[Value]).void }
+      def initialize(initial: [])
+        @head = T.let(nil, T.nilable(Node[Value]))
+        @tail = T.let(nil, T.nilable(Node[Value]))
+        @size = T.let(0, Integer)
+        initial.each { |element| enqueue(element) }
+      end
+
+      sig { params(element: Value).void }
+      def enqueue(element)
+        if @head.nil?
+          @head = Node[Value].new(value: element, next: nil)
+          @tail = @head
+          @size += 1
+        else
+          T.must(@tail).next = Node[Value].new(value: element, next: nil)
+          @tail = T.must(@tail).next
+          @size += 1
+        end
+      end
+
+      sig { returns(T.nilable(Value)) }
+      def peak
+        return if @head.nil?
+
+        @head.value
+      end
+
+      sig { returns(T.nilable(Value)) }
+      def dequeue
+        return if @size == 0
+        return if @head.nil?
+
+        element = @head.value
+        @head = @head.next
+        @size -= 1
+        @tail = nil if @size == 0
+        element
+      end
+
+      sig { returns(T::Boolean) }
+      def empty?
+        @size == 0
+      end
+    end
+  end
+end

data/lib/mayak/function.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+# typed: strict
+
+module Mayak
+  class Function
+    extend T::Sig
+    extend T::Helpers
+    extend T::Generic
+
+    Input  = type_member
+    Output = type_member
+
+    sig { returns(T.proc.params(input: Input).returns(Output)) }
+    attr_reader :blk
+
+    sig { params(blk: T.proc.params(input: Input).returns(Output)).void }
+    def initialize(&blk)
+      @blk = T.let(blk, T.proc.params(input: Input).returns(Output))
+    end
+
+    sig { params(input: Input).returns(Output) }
+    def call(input)
+      blk.call(input)
+    end
+
+    sig {
+      type_parameters(:Output2)
+        .params(another: Mayak::Function[Output, T.type_parameter(:Output2)])
+        .returns(Mayak::Function[Input, T.type_parameter(:Output2)])
+    }
+    def and_then(another)
+      Mayak::Function[Input, T.type_parameter(:Output2)].new { |a| another.call(blk.call(a)) }
+    end
+    alias >> and_then
+
+    sig {
+      type_parameters(:Input2)
+        .params(another: Mayak::Function[T.type_parameter(:Input2), Input])
+        .returns(Mayak::Function[T.type_parameter(:Input2), Output])
+    }
+    def compose(another)
+      Mayak::Function[T.type_parameter(:Input2), Output].new { |a| blk.call(another.call(a)) }
+    end
+    alias << compose
+  end
+end