halchemy 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85abce8ddfb00cc4480ced1de3389c20a8bb748c60f4fc58e9243023db4b0b18
-  data.tar.gz: 2186d43bab992f50781ca85c8f6de07fc6830558feb92d1725713900765f19ab
+  metadata.gz: 1dd3f79bb5a2f73f4b79dd138835a211febcfb627d1a20608e1a2ed81d6a4f30
+  data.tar.gz: e228d136ae6ec38a4edabf90f37ea70bf6382f11ef47d9ee51371329bccc9339
 SHA512:
-  metadata.gz: 6d9f59078d27bb6979f9607ab4de03adfb09cce40f5ab8e0a1aee2ca24d54151cfb3922b5ae92c3f812e2ba8f00c5e2a624851e488ab82dacf74cbc6b8540118
-  data.tar.gz: 71f971e665b96b864565ec04c95230589d34776b8997e0caea8ead21aaf728963a42f3326ca5a3b3d21fe5feb29dcd06a0ee0f689559f495f21681bf26851981
+  metadata.gz: 673f337aef6da5b24374367ff6aded12ef2d31f4736814f2b112e6122f49480f21737f303fba64ef4bdc1d6b8003d41465daec15adb6459e1ab98efd06382498
+  data.tar.gz: 2639ee8b448e0fc4b9709a7fdce799bbd2a2e6db1412005961a27d8ecc84d73e36df68f293c681359f87fff5ed056cd4306eebbf6e5f54606865c1a74c4dc3ed

data/__tests__/common.rb

@@ -20,7 +20,7 @@ After do
 end
 
 
-ROOT_JSON = {
+HOME_JSON = {
   _links: {
     self: { href: "/" },
     resource1: { href: "/path/to/resource1" },
@@ -41,7 +41,7 @@ RESOURCE_JSON = {
 Given(/^a HAL resource$/) do
   stub_for_hal_resource_scenarios
   @api = Halchemy::Api.new BASE_URL
-  @root_resource = @api.root.get
+  @home_resource = @api.home.get
 end
 
 # @return [void]
@@ -51,7 +51,7 @@ def stub_for_hal_resource_scenarios
     "Etag" => "from header"
   }
 
-  stub_request(:get, BASE_URL).to_return(body: ROOT_JSON, headers: headers)
+  stub_request(:get, BASE_URL).to_return(body: HOME_JSON, headers: headers)
   stub_request(:get, %r{\A#{BASE_URL}/path(/.*)?\z}).to_return(status: 200, body: RESOURCE_JSON, headers: headers)
 end
 

data/__tests__/configurable/base_url.rb

@@ -14,9 +14,9 @@ And(/^is later changed to a (.*)$/) do |new_base_url|
   @api.base_url = new_base_url
 end
 
-When(/^I GET the root resource$/) do
+When(/^I GET the home resource$/) do
   @methods_used = [:get]
-  @api.root.get
+  @api.home.get
 end
 
 When(/^a request is given a (.*)$/) do |relative_url|

data/__tests__/make_http_requests/follow_link_relations.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 When(/^I make a request using its link relations$/) do
-  @requests = make_requests(ALL_METHODS, @api.follow(@root_resource).to("resource1"))
+  @requests = make_requests(ALL_METHODS, @api.follow(@home_resource).to("resource1"))
 end
 
 Then(/^the href of the link is used for the request$/) do
@@ -14,7 +14,7 @@ When(/^I make a request to a link relation the resource does not have$/) do
   @error = {}
   ALL_METHODS.each do |method|
     @error[method] = nil
-    @api.follow(@root_resource).to("non-existent").public_send(method)
+    @api.follow(@home_resource).to("non-existent").public_send(method)
   rescue KeyError => e
     @error[method] = e
   end
@@ -28,7 +28,7 @@ Then(/^the request fails, informing me of the issue$/) do
 end
 
 When(/^I ask for the links it has$/) do
-  @links = @root_resource.links
+  @links = @home_resource.links
 end
 
 Then(/^I get a list of its relations$/) do
@@ -38,8 +38,8 @@ Then(/^I get a list of its relations$/) do
 end
 
 When(/^I ask if it has a link relation$/) do
-  @true_if_exists = @root_resource.rel?("self")
-  @false_if_not_exists = @root_resource.rel?("not-a-rel")
+  @true_if_exists = @home_resource.rel?("self")
+  @false_if_not_exists = @home_resource.rel?("not-a-rel")
 end
 
 Then(/^it tells me whether it does or not$/) do
@@ -58,7 +58,7 @@ When(/^I use an object my language uses to represent JSON as the payload of a re
   }
 
   @payload = data.to_json
-  @requests = make_requests(PAYLOAD_METHODS, @api.follow(@root_resource).to("resource1"), @payload)
+  @requests = make_requests(PAYLOAD_METHODS, @api.follow(@home_resource).to("resource1"), @payload)
 end
 
 Then(/^the request body is properly formatted JSON$/) do
@@ -70,12 +70,12 @@ end
 
 When(/^I use data type that is not an object but is valid as JSON, e\.g\. (.*)$/) do |data|
   @payload = data
-  @requests = make_requests(PAYLOAD_METHODS, @api.follow(@root_resource).to("resource1"), @payload)
+  @requests = make_requests(PAYLOAD_METHODS, @api.follow(@home_resource).to("resource1"), @payload)
 end
 
 When(/^the payload of a request is has (.*) of a different (.*)$/) do |data, content_type|
   @payload = data
-  @requests = make_requests(PAYLOAD_METHODS, @api.follow(@root_resource).to("resource1"), data, content_type)
+  @requests = make_requests(PAYLOAD_METHODS, @api.follow(@home_resource).to("resource1"), data, content_type)
 end
 
 Then(/^the request is made with the correct (.*) and (.*) header$/) do |data, content_type|

data/__tests__/make_http_requests/http_response_details.rb

@@ -3,7 +3,7 @@
 When(/^I make a request$/) do
   @resource = {}
   ALL_METHODS.each do |method|
-    @resource[method] = @api.follow(@root_resource).to("resource1").public_send(method)
+    @resource[method] = @api.follow(@home_resource).to("resource1").public_send(method)
   end
 end
 
@@ -41,7 +41,7 @@ When(/^the request I made fails: (.*)$/) do |failure|
 
   @resource = {}
   ALL_METHODS.each do |method|
-    @resource[method] = @api.follow(@root_resource).to("resource1").public_send(method)
+    @resource[method] = @api.follow(@home_resource).to("resource1").public_send(method)
   end
 end
 
@@ -58,3 +58,27 @@ Then(/^I can access the error details$/) do
     end
   end
 end
+
+When(/^I make a request that returns JSON in the body$/) do
+  response_body = {
+    "_status" => "ERR",
+    "_error" => {
+      "code" => 404,
+      "message" => "The requested URL was not found on the server. /
+                    If you entered the URL manually please check your spelling and try again."
+    }
+  }.to_json
+  stub_request(:any, /.*/).to_return(body: response_body, status: 404)
+
+  @resource = {}
+  ALL_METHODS.each do |method|
+    @resource[method] = @api.follow(@home_resource).to("resource1").public_send(method)
+  end
+end
+
+Then(/^I can use the body in the way my language supports JSON$/) do
+  ALL_METHODS.each do |method|
+    response = @resource[method]._halchemy.response
+    expect(  response.body.respond_to?("to_json")  ).to be true
+  end
+end

data/__tests__/make_http_requests/optimistic_concurrency.rb

@@ -3,8 +3,8 @@
 Given(/^a modifiable HAL resource$/) do
   stub_for_hal_resource_scenarios
   @api = Halchemy::Api.new BASE_URL
-  root_resource = @api.root.get
-  @resource = @api.follow(root_resource).to("resource1").get
+  home_resource = @api.home.get
+  @resource = @api.follow(home_resource).to("resource1").get
 end
 
 When(/^I request a change to the resource$/) do

data/__tests__/make_http_requests/with_headers.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 When(/^I specify additional headers for a request$/) do
-  requester = @api.follow(@root_resource).to("resource1").with_headers({ "X-CustomHeader" => "custom value" })
+  requester = @api.follow(@home_resource).to("resource1").with_headers({ "X-CustomHeader" => "custom value" })
   @requests = make_requests(ALL_METHODS, requester)
 end
 
@@ -16,12 +16,12 @@ end
 Given(/^I have made a request with additional headers$/) do
   stub_for_hal_resource_scenarios
   @api = Halchemy::Api.new BASE_URL
-  @root_resource = @api.root.get
-  @api.follow(@root_resource).to("resource1").with_headers({ "X-CustomHeader" => "custom value" }).get
+  @home_resource = @api.home.get
+  @api.follow(@home_resource).to("resource1").with_headers({ "X-CustomHeader" => "custom value" }).get
 end
 
 When(/^I make a new request without headers$/) do
-  @requests = make_requests(ALL_METHODS, @api.follow(@root_resource).to("resource1"))
+  @requests = make_requests(ALL_METHODS, @api.follow(@home_resource).to("resource1"))
 end
 
 Then(/^the previous request's headers are not included$/) do

data/__tests__/make_http_requests/with_parameters.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 When(/^I supply (.*)$/) do |parameters|
-  requester = @api.follow(@root_resource).to("resource1").with_parameters(JSON.parse(parameters))
+  requester = @api.follow(@home_resource).to("resource1").with_parameters(JSON.parse(parameters))
   @requests = make_requests(ALL_METHODS, requester)
 end
 

data/__tests__/use_resources/iterate_collections.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 Given(/^a HAL resource that has a field which is a collection of objects in HAL format$/) do
-  @resource = Halchemy::HalResource.new.merge!(JSON.parse({
+  @resource = Halchemy::HalResource.from_hash(JSON.parse({
+    _links: {
+      self: { href: "/" }
+    },
     _items: [
       {
         field: "alpha",
@@ -15,8 +18,7 @@ Given(/^a HAL resource that has a field which is a collection of objects in HAL
         field: "delta",
         _links: { self: { href: "/resource/delta" } }
       }
-    ],
-    _links: { self: { href: "/resource" } }
+    ]
   }.to_json))
 end
 
@@ -32,7 +34,7 @@ Then(/^each item is a HAL resource$/) do
 end
 
 When(/^I try to iterate as a collection a field in the resource that does not exist$/) do
-  @root_resource.collection("_items").reduce(false) { |all_hal, item| all_hal || item.is_a?(Halchemy::HalResource) }
+  @home_resource.collection("_items").reduce(false) { |all_hal, item| all_hal || item.is_a?(Halchemy::HalResource) }
 rescue KeyError => e
   @error = e
 end
@@ -43,7 +45,7 @@ Then(/^it throws an exception telling me that the field does not exist$/) do
 end
 
 Given(/^a HAL resource with a non-collection field$/) do
-  @resource = Halchemy::HalResource.new.merge!(JSON.parse({
+  @resource = Halchemy::HalResource.from_hash(JSON.parse({
     _id: "3a834-34f9f03-39b843",
     _links: { self: { href: "/resource" } }
   }.to_json))
@@ -61,7 +63,7 @@ Then(/^it throws an exception telling me that the field is not a collection$/) d
 end
 
 Given(/^a HAL resource that has a field which is a collection, but not of HAL formatted objects$/) do
-  @resource = Halchemy::HalResource.new.merge!(JSON.parse({
+  @resource = Halchemy::HalResource.from_hash(JSON.parse({
     _items: [
       {
         make: "Ford Mustang"

data/__tests__/use_resources/use_embedded.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+Given(/^a HalResource with an embedded property containing both a single resource and a resource collection$/) do
+  @resource = Halchemy::HalResource.from_hash( JSON.parse({
+     _id: "39402",
+     memberName: "Pat Doe",
+     address: "123 Main St.",
+     _links: {
+       self: { href: "/members/39402" },
+       library: { href: "/libraries/2389" },
+       books: { href: "/members/39402/books" }
+     },
+     _embedded: {
+       library: {
+         name: "Essex County Library",
+         _links: {
+           self: { href: "/libraries/2389" }
+         }
+       },
+       book: [
+         {
+           title: "Stephen's Kingdom",
+           edition: "1st",
+           _links: {
+             self: { href: "/books/3845" }
+           }
+         },
+         {
+           title: "Nature Valley",
+           edition: "paperback",
+           _links: {
+             self: { href: "/books/8842" }
+           }
+         }
+       ]
+     }
+  }.to_json))
+end
+
+
+When(/^I retrieve the embedded resource with the (.*) rel$/) do |rel|
+  @fetched = @resource.embedded(rel)
+rescue KeyError => e
+  @exception = e
+end
+
+
+Then(/^I should receive a single HalResource instance$/) do
+  expect(@fetched).to be_a Halchemy::HalResource
+end
+
+
+And(/^the resource should contain the expected data for the library$/) do
+  expect(@fetched["name"]).to eq("Essex County Library")
+end
+
+
+Then(/^I should receive a collection of HalResource instances$/) do
+  expect(@fetched).to be_a Array
+  expect(@fetched).to all(be_a(Halchemy::HalResource))
+end
+
+
+And(/^the resource should contain the expected book data$/) do
+  titles = ["Stephen's Kingdom", "Nature Valley"]
+  titles.each_with_index do |title, index|
+    expect(title).to eq @fetched[index]["title"]
+  end
+end
+
+
+When(/^I retrieve the embedded resource with rel (.*) and expect (.*)$/) do |rel, multiplicity|
+  @fetched = @resource.embedded(
+    rel,
+    expect: multiplicity == "many" ? Halchemy::Multiplicity::MANY : Halchemy::Multiplicity::ONE
+  )
+rescue TypeError => e
+  @exception = e
+end
+
+
+When(/^I call embedded_one with rel library$/) do
+  @fetched = @resource.embedded_one("library")
+end
+
+
+When(/^I call embedded_many with rel book$/) do
+  @fetched = @resource.embedded_many("book")
+end
+
+
+Then(/^an error should be raised indicating a type mismatch$/) do
+  expect(@exception).to be_a(TypeError)
+end
+
+Then(/^an error should be raised indicating the resource is not found$/) do
+  expect(@exception).to be_a(KeyError)
+end

data/lib/halchemy/api.rb

@@ -28,10 +28,13 @@ module Halchemy
       @headers.merge!(headers)
     end
 
-    def root = using_endpoint("/", is_root: true)
+    def home = using_endpoint("/", is_home: true)
 
-    def using_endpoint(target, is_root: false)
-      if is_root
+    # root is deprecated and will be removed in an upcoming release, please use home instead
+    def root = using_endpoint("/", is_home: true)
+
+    def using_endpoint(target, is_home: false)
+      if is_home
         ReadOnlyRequester.new(self, target)
       else
         Requester.new(self, target)
@@ -112,7 +115,7 @@ module Halchemy
       resource = if json.nil?
                    Resource.new
                  elsif HalResource.hal?(json)
-                   HalResource.new.merge! json
+                   HalResource.from_hash json
                  else
                    Resource.new.merge! json
                  end

data/lib/halchemy/requester.rb

@@ -3,7 +3,7 @@
 require "uri_template"
 
 module Halchemy
-  # The results of a Follower#to is a Requester.  In the case of a GET for the root resource, the Requester is Read Only
+  # The results of a Follower#to is a Requester.  In the case of a GET for the home resource, the Requester is Read Only
   # Otherwise it is a full Requester.  Both requester types share much in common.  This is defined in BaseRequester
   class BaseRequester
     LIST_STYLE_HANDLERS = {
@@ -126,7 +126,7 @@ module Halchemy
     end
   end
 
-  # The result of GET on the root URL is a ReadOnlyRequester, i.e. only
+  # The result of GET on the home URL is a ReadOnlyRequester, i.e. only
   # GET, HEAD, and OPTIONS are permitted
   class ReadOnlyRequester < BaseRequester
     def get

data/lib/halchemy/resource.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module Halchemy
+  module Multiplicity
+    ONE = :one
+    MANY = :many
+  end
+
   # The Resource class extends a Hash to include a metadata object containing details
   # about the HTTP request and response.  This lets the metadata stay "out of the way" allowing
   # the client code to use the result of a request directly as a resource without losing access
@@ -36,6 +41,23 @@ module Halchemy
       true
     end
 
+    def initialize(*args)
+      super
+      raise ArgumentError, "Not a WELL-formed HAL resource" unless HalResource.hal?(self)
+    end
+
+    def self.from_hash(json)
+      obj = allocate
+      obj.merge!(json) if json.is_a?(Hash)
+      raise ArgumentError, "Not a well-FORMED HAL resource" unless HalResource.hal?(obj)
+
+      obj
+    end
+
+    def to_s
+      "<HalResource href='#{dig("_links", "self", "href")}' >"
+    end
+
     def rel?(rel_name)
       self["_links"].key?(rel_name)
     end
@@ -44,6 +66,14 @@ module Halchemy
       self["_links"].keys ||= []
     end
 
+    def embedded_rel?(rel_name)
+      self["_embedded"].key?(rel_name)
+    end
+
+    def embedded_rels
+      self["_embedded"]&.keys || []
+    end
+
     def raise_for_syntax_error(field)
       unless keys.include?(field)
         raise KeyError, "Field '#{field}' does not exist, so cannot be iterated as a collection"
@@ -60,9 +90,49 @@ module Halchemy
             raise TypeError, "The '#{field}' collection contains non-HAL formatted objects"
           end
 
-          y.yield Halchemy::HalResource.new.merge!(item)
+          y.yield Halchemy::HalResource.from_hash(item)
         end
       end
     end
+
+    # @param [string] rel_name
+    # @param [Symbol, nil] expect
+    # @return [Halchemy::HalResource, Array<Halchemy::HalResource>]
+    def embedded(rel_name, expect: nil)
+      val = dig("_embedded", rel_name)
+      raise KeyError, "No embedded resource found for rel '#{rel_name}'" if val.nil?
+
+      if expect == Multiplicity::MANY
+        raise TypeError, "Expected array for rel '#{rel_name}', got #{val.class}" unless val.is_a?(Array)
+
+        return val.map { |item| HalResource.from_hash(item) }
+      elsif expect == Multiplicity::ONE
+        raise TypeError, "Expected object for rel '#{rel_name}', got #{val.class}" unless val.is_a?(Hash)
+
+        return HalResource.from_hash(val)
+      end
+
+      if val.is_a?(Array)
+        val.map { |item| HalResource.from_hash(item) }
+      elsif val.is_a?(Hash)
+        HalResource.from_hash(val)
+      else
+        raise TypeError, "Invalid embedded value for rel '#{rel_name}': expected object or array, got #{val.class}"
+      end
+    end
+
+    def embedded_many(rel_name)
+      result = embedded(rel_name, expect: Multiplicity::MANY)
+      raise TypeError, "Expected array for embedded '#{rel_name}', got #{result.class}" unless result.is_a?(Array)
+
+      result
+    end
+
+    def embedded_one(rel_name)
+      result = embedded(rel_name, expect: Multiplicity::ONE)
+      raise TypeError, "Expected object for rel '#{rel_name}', got #{result.class}" unless result.is_a?(Hash)
+
+      result
+    end
   end
 end

data/lib/halchemy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Halchemy
-  VERSION = "1.0.3"
+  VERSION = "1.0.5"
 end

data/sig/halchemy/api.rbs

@@ -23,7 +23,7 @@ module Halchemy
 
     def request: -> (Resource | HalResource)
 
-    def root: -> BaseRequester
+    def home: -> BaseRequester
 
     def using_endpoint: -> BaseRequester
 

data/sig/halchemy/hal_resource.rbs

@@ -1,9 +1,20 @@
 module Halchemy
   class HalResource
+    def self.from_hash: -> HalResource
+
     def self.hal?: -> bool
 
     def collection: -> Enumerator[HalResource]
 
+    def embedded:  (Symbol | nil) -> (HalResource | Array[HalResource])
+
+    def embedded_many:  -> Array[HalResource]
+    def embedded_one:  -> HalResource
+
+    def embedded_rel?: -> bool
+
+    def embedded_rels: -> Array[String]
+
     def links: -> Array[String]
 
     def raise_for_syntax_error: -> void

data/sig/halchemy/multiplicity.rbs

@@ -0,0 +1,6 @@
+module Halchemy
+  module Multiplicity
+    ONE: Symbol
+    MANY: Symbol
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: halchemy
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.5
 platform: ruby
 authors:
 - Michael Ottoson
 bindir: exe
 cert_chain: []
-date: 2025-01-27 00:00:00.000000000 Z
+date: 2025-03-31 00:00:00.000000000 Z
 dependencies: []
 description: Do you have an API that serves data following the HAL specification?  The
   **halchemy** library makes it easy for your client to make the most of that API.
@@ -39,6 +39,7 @@ files:
 - __tests__/make_http_requests/with_parameters.rb
 - __tests__/make_http_requests/with_templates.rb
 - __tests__/use_resources/iterate_collections.rb
+- __tests__/use_resources/use_embedded.rb
 - bdd
 - lib/halchemy.rb
 - lib/halchemy/api.rb
@@ -64,13 +65,13 @@ files:
 - sig/halchemy/http_model/request.rbs
 - sig/halchemy/http_model/response.rbs
 - sig/halchemy/metadata.rbs
+- sig/halchemy/multiplicity.rbs
 - sig/halchemy/read_only_requester.rbs
 - sig/halchemy/requester.rbs
 - sig/halchemy/resource.rbs
 - sig/matchers.rbs
 - sig/patterns.rbs
 - test.sh
-- "~halchemy"
 homepage: https://github.com/pointw-dev/halchemy
 licenses:
 - MIT

data/~halchemy

@@ -1,2 +0,0 @@
-[halchemy]
-parameters_list_style = comma