halva 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7540c00f3cbdde45eb5601db5fa7b21fd37da8c6f9f32a12d0f7b351a01c578
-  data.tar.gz: 858f12ed050776011ca688739717efe5ec31afc2a40940b256dfd52f0f7c15dd
+  metadata.gz: 3b7e22a105b03d70350b3e43d8c449edebf1eafc5dc348ebdc9d5247f9d9bf01
+  data.tar.gz: 96f911bb17f7fa41ff6ac293adb363eac38f5902f48cd08b9145a551ee554646
 SHA512:
-  metadata.gz: a887b14fff4b717594cb14b43371f797ddbe2650753261a578f8eab78dd372f78b2cc9618aaed2c3214d69eda63d19b39acb60590a6c8a6353746c4dd2559028
-  data.tar.gz: 329b6db4147b2646d7f613bacce0202cf1211af44376e7479ff8f917600a8a29c36dfb3bf7ae66a887858b300e4dd16c2d78499457ba184aaed09e8f80167ea7
+  metadata.gz: cf8aedb6cbddcbe4ff987ea66e0cca8840228aa5349fa6887643af6e7b248a8b64d440dde92de30ade4b7c22ef6ef4c9babeb7c781ff351d3aa0f8b56a8ee997
+  data.tar.gz: 7a2ff75eb11509ed050e36368b19ad4d55d8274fcd5db5588a3595bb193339f6a39c58f2d77d4909377050d410eaa9f608ef68b4d7f2772265685048e3ec7438

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    halva (0.2.0)
+    halva (0.4.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,13 +1,20 @@
 # Halva
 
-HAL-compliant serializer
+HAL-compliant decorator
 
 [![Ruby](https://github.com/denblackstache/halva/actions/workflows/main.yml/badge.svg)](https://github.com/denblackstache/halva/actions/workflows/main.yml) [![Gem Version](https://badge.fury.io/rb/halva.svg)](https://badge.fury.io/rb/halva)
 
-Links
+**Links**
 * [HAL - Hypertext Application Language](https://stateless.co/hal_specification.html)
 * [Specification Draft](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-08)
 
+**Goals**
+
+* No DSL
+* HAL-compliant
+* Not responsible for the whole presentation layer
+* Simple, extensible, self-discoverable
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -33,11 +40,25 @@ require 'halva'
 
 order = Order.find(1)
 Halva::Resource.from_model(order)
-               .embed(Halva::Resource.from_model(order.customer).build, :customer)
+               .embed(Halva::Resource.from_model(order.customer), :customer)
                .link(Halva::Link.new('/orders/1', :self))
                .link(Halva::Link.new('/orders/1/customer', :customer))
-               .build
-
+               .to_h
+
+# {
+#   :id => 1, 
+#   :name => "Order Example"
+#   :_embedded => {
+#     :customer => [{
+#       :id => 1, 
+#       :name => "Customer Example"
+#     }]
+#   }, 
+#   :_links => { 
+#     :self => {:href => "/orders/1"}, 
+#     :customer => {:href => "/orders/1/customer"} 
+#   }
+# }
 ```
 
 ### Representing a collection
@@ -47,11 +68,35 @@ require 'halva'
 
 orders = Order.find
 Halva::Resource.from_empty_model
-               .embed(orders.map { |order| Halva::Resource.from_model(order).build })
-               .link(Halva::Link.new('/orders?page=3', :next))
+               .embed(orders.map do |order|
+                 Halva::Resource.from_model(order)
+                                .link(Halva::Link.new("/orders/#{order.id}", :self))
+               end, :'acme:order')
                .link(Halva::Link.new('/orders?page=2', :self))
+               .link(Halva::Link.new('/orders?page=3', :next))
                .link(Halva::Link.new('/orders?page=1', :prev))
-               .build
+               .link(Halva::Curie.new('https://docs.acme.com/relations/{rel}', 'acme'))
+               .to_h
+
+# {
+#   :_embedded => {
+#     :"acme:order" => [{
+#       :id => 1, 
+#       :name => "Example"
+#       :_links => {:self => {:href => "/orders/1"} }
+#     }]
+#   }, 
+#   :_links => { 
+#     :self => {:href => "/orders/1?page=2"}, 
+#     :next => {:href => "/orders/1?page=3"}, 
+#     :prev => {:href => "/orders/1?page=1"},
+#     :curies => [{
+#       name: 'acme',
+#       href: 'https://docs.acme.com/relations/{rel}',
+#       templated: true
+#     }]
+#   }
+# }
 
 ```
 

data/halva.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Denis Semenenko']
   spec.email         = ['hypercoderx@gmail.com']
 
-  spec.summary       = 'HAL-compliant serializer'
+  spec.summary       = 'HAL-compliant decorator'
   spec.homepage      = 'https://github.com/denblackstache/halva'
   spec.license       = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')

data/lib/halva/curie.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Halva
+  # Compact URI Link Object
+  # See [HAL Draft](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal#section-8.2)
+  class Curie
+    attr_reader :relation, :href
+
+    # @param [String] href
+    # @param [String] name
+    def initialize(href, name)
+      @href = href
+      @relation = :curies
+      @link = Halva::Link.new(@href, @relation, { templated: true, name: name })
+    end
+
+    def to_h
+      @link.to_h
+    end
+  end
+end

data/lib/halva/link.rb

@@ -2,10 +2,20 @@
 
 module Halva
   # HAL Link Object
-  # https://datatracker.ietf.org/doc/html/draft-kelly-json-hal#section-5}
+  # See [HAL Draft](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal#section-5)
   class Link
-    attr_reader :relation, :href
+    attr_reader :relation
 
+    # @param [String] href
+    # @param [Symbol] relation
+    # @param [Hash] options (templated, type, deprecation, name, profile, title, hreflang)
+    # @option options [Boolean] :templated true when the Link Object's "href" property is a URI Template
+    # @option options [String] :type a hint to indicate the media type expected when dereferencing the target resource
+    # @option options [String] :deprecation indicate that the link is to be deprecated (i.e. removed) at a future date
+    # @option options [String] :name a secondary key for selecting Link Objects which share the same relation type
+    # @option options [String] :profile a URI that hints about the profile of the target resource
+    # @option options [String] :title label for the link with a human-readable identifier
+    # @option options [String] :hreflang indicate the language of the target resource
     def initialize(href, relation, options = {})
       @href = href
       @relation = relation.to_sym

data/lib/halva/resource.rb

@@ -2,10 +2,11 @@
 
 module Halva
   # HAL Resource object
-  # https://datatracker.ietf.org/doc/html/draft-kelly-json-hal#section-4
+  # See [HAL Draft](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal#section-4)
   class Resource
     EMBEDDED_KEY = :_embedded
     LINKS_KEY = :_links
+    CURIES_KEY = :curies
 
     def self.from_model(model)
       new(model.to_h)
@@ -16,7 +17,7 @@ module Halva
     end
 
     def initialize(model)
-      @model = model
+      @model = model.freeze
       @embedded = []
       @links = []
     end
@@ -31,22 +32,33 @@ module Halva
       self
     end
 
-    def build
+    def to_h
+      document = @model.dup
       unless @embedded.empty?
-        @model[EMBEDDED_KEY] = {} unless @model.key?(EMBEDDED_KEY)
+        document[EMBEDDED_KEY] = {} unless document.key?(EMBEDDED_KEY)
         @embedded.each do |emb|
-          @model[EMBEDDED_KEY][emb[:relation]] = emb[:resource]
+          is_collection = emb[:resource].is_a?(Enumerable)
+          document[EMBEDDED_KEY][emb[:relation]] = if is_collection
+                                                     emb[:resource].map(&:to_h)
+                                                   else
+                                                     emb[:resource].to_h
+                                                   end
         end
       end
 
       unless @links.empty?
-        @model[LINKS_KEY] = {} unless @model.key?(LINKS_KEY)
+        document[LINKS_KEY] = {} unless document.key?(LINKS_KEY)
         @links.each do |link|
-          @model[LINKS_KEY][link.relation] = link.to_h
+          if link.relation == CURIES_KEY
+            document[LINKS_KEY][CURIES_KEY] = [] unless document[LINKS_KEY].key?(CURIES_KEY)
+            document[LINKS_KEY][CURIES_KEY] << link.to_h
+          else
+            document[LINKS_KEY][link.relation] = link.to_h
+          end
         end
       end
 
-      @model.to_h
+      document
     end
   end
 end

data/lib/halva/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Halva
-  VERSION = '0.2.0'
+  VERSION = '0.4.0'
 end

data/lib/halva.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'halva/curie'
 require 'halva/link'
 require 'halva/resource'
 require 'halva/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: halva
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Denis Semenenko
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-21 00:00:00.000000000 Z
+date: 2023-02-25 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -30,6 +30,7 @@ files:
 - bin/setup
 - halva.gemspec
 - lib/halva.rb
+- lib/halva/curie.rb
 - lib/halva/link.rb
 - lib/halva/resource.rb
 - lib/halva/version.rb
@@ -58,5 +59,5 @@ requirements: []
 rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
-summary: HAL-compliant serializer
+summary: HAL-compliant decorator
 test_files: []