lutaml-hal 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d002eb57e4807e4895639a338e4ad48ec6f18f21b238a4316d9f01f125442eb
-  data.tar.gz: f25f410b3ede494dff1dcef66ca9f4882d8dad3fa1d7bd71432ad2a62d6ab449
+  metadata.gz: 173922c9afbab790441aa0b40fc7a2401c78c72cbcc55d8cf3a7de737e12ea88
+  data.tar.gz: 8fdde395a4ac1898f2df9a259210127a3955e8d49d6b2cf3b710649daae0d3d7
 SHA512:
-  metadata.gz: ef84a386363fa0d7b4337b1150983e4dbe7aa7bdd56829a34c2ad581e7a773a22369254dd9d20985952308afa0d6be778053dd6db3d6957db84676f47d7fee1f
-  data.tar.gz: fe63bbe1f11cb5924eb8246958ee5c06d1a6a6325392a4e4dfe07e1b03f593c57d549942ddca833715d8ec14d5a39cabdc73804a2b5ae2a5a2a2c99474dd27b3
+  metadata.gz: b9bfd6e3a62e7359b4e0ad38ed72b3f300d23640d44f31942a5a178ef0bec5617d1d6202360bc9ec6cee10ff911e62a81752659ed5820c25e731e8304dbd7158
+  data.tar.gz: 6b256a2a898e2ed123c267ac7ee93780e0aa77b3715832e9f15856c0d9f600b1d05d080d469569060c086d348fc9a294d5d9eff6c6269c838d0ecd9883988eb5

data/Gemfile

@@ -6,7 +6,8 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'rake'
-gem 'rspec', '~> 3.12'
+gem 'rspec'
 gem 'rubocop'
-
-gem 'lutaml-model', git: 'https://github.com/lutaml/lutaml-model.git'
+gem 'rubocop-performance'
+gem 'rubocop-rake'
+gem 'rubocop-rspec'

data/README.adoc

@@ -552,16 +552,28 @@ You can define endpoints for collections (index) and individual resources
 
 The `add_endpoint` method takes the following parameters:
 
+
 `id`:: A unique identifier for the endpoint.
+
 `type`:: The type of endpoint, which can be `index` or `resource`.
-`url`:: The URL of the endpoint, which can include path parameters.
-`model`:: The class of the resource that will be fetched from the API.
-The class must inherit from `Lutaml::Hal::Resource`.
 
+`url`:: The URL of the endpoint, which can include path parameters.
++
 In the `url`, you can use interpolation parameters, which will be replaced with
 the actual values when fetching the resource. The interpolation parameters are
 defined in the `url` string using curly braces `{}`.
 
+`model`:: The class of the resource that will be fetched from the API.
+The class must inherit from `Lutaml::Hal::Resource`.
+
+`query_params`:: (optional) A hash defining query parameters that should be
+appended to the URL when fetching the resource. Supports parameter templates
+using curly braces `{}` for dynamic values.
++
+This is essential for APIs that require query parameters for pagination,
+filtering, or other functionality where the same base URL needs different query
+parameters to access different resources or views.
+
 The `add_endpoint` method will automatically handle the URL resolution and fetch
 the resource from the API.
 
@@ -592,6 +604,35 @@ register.add_endpoint( <1>
 <5> The `model` is the class of the resource that will be fetched from
     the API. The class must inherit from `Lutaml::Hal::Resource`.
 
+
+.Example of registering and using query parameters
+[example]
+====
+[source,ruby]
+----
+# Register an endpoint that supports pagination via query parameters
+register.add_endpoint(
+  id: :product_index,
+  type: :index,
+  url: '/products',
+  model: ProductIndex,
+  query_params: {
+    'page' => '{page}',
+    'items' => '{items}'
+  }
+)
+
+# Fetch the first page with 10 items per page
+page_1 = register.fetch(:product_index, page: 1, items: 10)
+# => client.get('/products?page=1&items=10')
+
+# Fetch the second page with 5 items per page
+page_2 = register.fetch(:product_index, page: 2, items: 5)
+# => client.get('/products?page=2&items=5')
+----
+====
+
+
 .Example of registering the Product class to both index and resource endpoints
 [example]
 ====
@@ -614,6 +655,34 @@ register.add_endpoint(
 ====
 
 
+.Example of using query_params for pagination
+[example]
+====
+[source,ruby]
+----
+# Register an endpoint that supports pagination via query parameters
+register.add_endpoint(
+  id: :product_index_paginated,
+  type: :index,
+  url: '/products',
+  model: ProductIndex,
+  query_params: {
+    'page' => '{page}',
+    'items' => '{items}'
+  }
+)
+
+# Fetch the first page with 10 items per page
+page_1 = register.fetch(:product_index_paginated, page: 1, items: 10)
+# => client.get('/products?page=1&items=10')
+
+# Fetch the second page with 5 items per page
+page_2 = register.fetch(:product_index_paginated, page: 2, items: 5)
+# => client.get('/products?page=2&items=5')
+----
+====
+
+
 [[defining_hal_page_models]]
 === Defining HAL page models
 
@@ -920,12 +989,87 @@ product_2_related_1 = product_2.links.related.first.realize
 
 === Handling HAL pages / pagination
 
+==== General
+
 The `Lutaml::Hal::Page` class is used to handle pagination in HAL APIs.
 
 As described in <<defining_hal_page_models>>, subclassing the `Page` class
 provides pagination capabilities, including the management of links to navigate
 through pages of resources.
 
+==== Pagination navigation methods
+
+The `Page` class provides several convenience methods for navigating through
+paginated results:
+
+`#next_page`:: Returns the next page link if available, `nil` otherwise.
+
+`#prev_page`:: Returns the previous page link if available, `nil` otherwise.
+
+`#first_page`:: Returns the first page link if available, `nil` otherwise.
+
+`#last_page`:: Returns the last page link if available, `nil` otherwise.
+
+These methods return `Link` objects that can be realized using the `realize` method:
+
+[source,ruby]
+----
+# Navigate to next page
+if current_page.next_page
+  next_page = current_page.next_page.realize
+end
+
+# Navigate to previous page
+if current_page.prev_page
+  prev_page = current_page.prev_page.realize
+end
+
+# Jump to first or last page
+first_page = current_page.first_page.realize if current_page.first_page
+last_page = current_page.last_page.realize if current_page.last_page
+----
+
+==== Pagination helper methods
+
+The `Page` class also provides helper methods to check the availability of
+navigation links:
+
+`#has_next?`:: Returns `true` if there is a next page available, `false`
+otherwise.
+
+`#has_prev?`:: Returns `true` if there is a previous page available, `false`
+otherwise.
+
+`#has_first?`:: Returns `true` if there is a first page link available, `false`
+otherwise.
+
+`#has_last?`:: Returns `true` if there is a last page link available, `false`
+otherwise.
+
+`#total_pages`:: Returns the total number of pages (alias for the `pages`
+attribute).
+
+
+==== Exhaustive pagination
+
+For scenarios where you need to process all pages of results, you can combine
+the pagination methods:
+
+[source,ruby]
+----
+current_page = register.fetch(:resource_index)
+
+while current_page
+  # Process current page
+  puts "Processing page #{current_page.page} of #{current_page.total_pages}"
+
+  # Move to next page
+  current_page = current_page.next
+end
+----
+
+
+==== Usage
 
 .Usage example of the Page class
 [example]
@@ -980,11 +1124,33 @@ page_1
 #                next: #<ResourceIndexLink href: "/resources?page=2&items=10">,
 #                last: #<ResourceIndexLink href: "/resources?page=10&items=10">>>
 
+# Check if navigation is available
+page_1.has_next?    # => true
+page_1.has_prev?    # => false
+page_1.total_pages  # => 10
+
+# Navigate using convenience methods
+page_2 = page_1.next
+# => client.get('/resources?page=2&items=10')
+# => #<ResourceIndex page: 2, pages: 10, limit: 10, total: 100, ...>
+
+page_2.has_prev?    # => true
+page_2.has_next?    # => true
+
+# Navigate back to first page
+first_page = page_2.first
+# => client.get('/resources?page=1&items=10')
+
+# Jump to last page
+last_page = page_2.last
+# => client.get('/resources?page=10&items=10')
+
+# Alternative: using link realization (original method)
 # Without a GlobalRegister
-page_2 = page.links.next.realize(register)
+page_2 = page_1.links.next.realize(register)
 
 # With a GlobalRegister
-page_2 = page.links.next.realize
+page_2 = page_1.links.next.realize
 
 # => client.get('/resources?page=2&items=10')
 # => #<ResourceIndex page: 2, pages: 10, limit: 10, total: 100,

data/lib/lutaml/hal/model_register.rb

@@ -16,11 +16,11 @@ module Lutaml
       end
 
       # Register a model with its base URL pattern
-      def add_endpoint(id:, type:, url:, model:)
+      def add_endpoint(id:, type:, url:, model:, query_params: nil)
         @models ||= {}
 
         raise "Model with ID #{id} already registered" if @models[id]
-        if @models.values.any? { |m| m[:url] == url && m[:type] == type }
+        if @models.values.any? { |m| m[:url] == url && m[:type] == type && m[:query_params] == query_params }
           raise "Duplicate URL pattern #{url} for type #{type}"
         end
 
@@ -28,7 +28,8 @@ module Lutaml
           id: id,
           type: type,
           url: url,
-          model: model
+          model: model,
+          query_params: query_params
         }
       end
 
@@ -38,7 +39,7 @@ module Lutaml
         raise 'Client not configured' unless client
 
         url = interpolate_url(endpoint[:url], params)
-        response = client.get(url)
+        response = client.get(build_url_with_query_params(url, endpoint[:query_params], params))
 
         realized_model = endpoint[:model].from_json(response.to_json)
 
@@ -103,12 +104,82 @@ module Lutaml
         end
       end
 
+      def build_url_with_query_params(base_url, query_params_template, params)
+        return base_url unless query_params_template
+
+        query_params = []
+        query_params_template.each do |param_name, param_template|
+          # If the template is like {page}, look for the param in the passed params
+          if param_template.is_a?(String) && param_template.match?(/\{(.+)\}/)
+            param_key = param_template.match(/\{(.+)\}/)[1]
+            query_params << "#{param_name}=#{params[param_key.to_sym]}" if params[param_key.to_sym]
+          end
+        end
+
+        query_params.any? ? "#{base_url}?#{query_params.join('&')}" : base_url
+      end
+
       def find_matching_model_class(href)
         @models.values.find do |model_data|
-          matches_url?(model_data[:url], href)
+          matches_url_with_params?(model_data, href)
         end&.[](:model)
       end
 
+      def matches_url_with_params?(model_data, href)
+        pattern = model_data[:url]
+        query_params = model_data[:query_params]
+
+        return false unless pattern && href
+
+        uri = parse_href_uri(href)
+        pattern_path = extract_pattern_path(pattern)
+
+        return false unless path_matches?(pattern_path, uri.path)
+        return true unless query_params
+
+        query_params_match?(query_params, parse_query_params(uri.query))
+      end
+
+      def parse_href_uri(href)
+        full_href = href.start_with?('http') ? href : "#{client&.api_url}#{href}"
+        URI.parse(full_href)
+      end
+
+      def extract_pattern_path(pattern)
+        pattern.split('?').first
+      end
+
+      def path_matches?(pattern_path, href_path)
+        if href_path.start_with?('/') && client&.api_url
+          path_pattern = extract_path(pattern_path)
+          pattern_match?(path_pattern, href_path) || pattern_match?(pattern_path, href_path)
+        else
+          pattern_match?(pattern_path, href_path)
+        end
+      end
+
+      def query_params_match?(expected_params, actual_params)
+        expected_params.all? do |param_name, param_pattern|
+          actual_value = actual_params[param_name]
+          next false unless actual_value
+
+          template_param?(param_pattern) || actual_value == param_pattern.to_s
+        end
+      end
+
+      def template_param?(param_pattern)
+        param_pattern.is_a?(String) && param_pattern.match?(/\{.+\}/)
+      end
+
+      def parse_query_params(query_string)
+        return {} unless query_string
+
+        query_string.split('&').each_with_object({}) do |param, hash|
+          key, value = param.split('=', 2)
+          hash[key] = value if key
+        end
+      end
+
       def matches_url?(pattern, href)
         return false unless pattern && href
 
@@ -134,8 +205,8 @@ module Lutaml
 
         # Convert {param} to wildcards for matching
         pattern_with_wildcards = pattern.gsub(/\{[^}]+\}/, '*')
-        # Convert * wildcards to regex pattern
-        regex = Regexp.new("^#{pattern_with_wildcards.gsub('*', '[^/]+')}$")
+        # Convert * wildcards to regex pattern - use .+ instead of [^/]+ to match query parameters
+        regex = Regexp.new("^#{pattern_with_wildcards.gsub('*', '.+')}$")
 
         Hal.debug_log("pattern_match?: regex: #{regex.inspect}")
         Hal.debug_log("pattern_match?: href to match #{url}")

data/lib/lutaml/hal/page.rb

@@ -32,6 +32,144 @@ module Lutaml
           end
         end
       end
+
+      # Returns the next page of results, or nil if on the last page
+      #
+      # @return [Object, nil] The next page instance or nil
+      def next
+        return nil unless links.next
+
+        links.next.realize
+      end
+
+      # Returns the previous page of results, or nil if on the first page
+      #
+      # @return [Object, nil] The previous page instance or nil
+      def prev
+        # If the API provides a prev link, use it
+        return links.prev.realize if links.prev
+
+        # If we're on page 1, there's no previous page
+        return nil if page <= 1
+
+        # Construct the previous page URL manually
+        prev_page_url = construct_page_url(page - 1)
+        return nil unless prev_page_url
+
+        # Use the HAL register to fetch the previous page
+        register_name = instance_variable_get("@#{Lutaml::Hal::REGISTER_ID_ATTR_NAME}")
+        return nil unless register_name
+
+        hal_register = Lutaml::Hal::GlobalRegister.instance.get(register_name)
+        return nil unless hal_register
+
+        hal_register.resolve_and_cast(nil, prev_page_url)
+      end
+
+      # Returns the first page of results
+      #
+      # @return [Object, nil] The first page instance or nil
+      def first
+        return nil unless links.first
+
+        links.first.realize
+      end
+
+      # Returns the last page of results
+      #
+      # @return [Object, nil] The last page instance or nil
+      def last
+        return nil unless links.last
+
+        links.last.realize
+      end
+
+      # Returns the total number of pages
+      #
+      # @return [Integer] The total number of pages
+      def total_pages
+        pages
+      end
+
+      # Checks if there is a next page available
+      #
+      # @return [Boolean] true if next page exists, false otherwise
+      def next?
+        !links.next.nil?
+      end
+
+      # Checks if there is a previous page available
+      #
+      # @return [Boolean] true if previous page exists, false otherwise
+      def prev?
+        !links.prev.nil?
+      end
+
+      # Checks if there is a first page link available
+      #
+      # @return [Boolean] true if first page link exists, false otherwise
+      def first?
+        !links.first.nil?
+      end
+
+      # Checks if there is a last page link available
+      #
+      # @return [Boolean] true if last page link exists, false otherwise
+      def last?
+        !links.last.nil?
+      end
+
+      # Returns the next page link, or nil if on the last page
+      #
+      # @return [Object, nil] The next page link or nil
+      def next_page
+        links.next
+      end
+
+      # Returns the previous page link, or nil if on the first page
+      #
+      # @return [Object, nil] The previous page link or nil
+      def prev_page
+        links.prev
+      end
+
+      # Returns the first page link
+      #
+      # @return [Object, nil] The first page link or nil
+      def first_page
+        links.first
+      end
+
+      # Returns the last page link
+      #
+      # @return [Object, nil] The last page link or nil
+      def last_page
+        links.last
+      end
+
+      private
+
+      # Constructs a URL for a specific page based on the current page's URL pattern
+      #
+      # @param target_page [Integer] The page number to construct URL for
+      # @return [String, nil] The constructed URL or nil if unable to construct
+      def construct_page_url(target_page)
+        # Try to get a reference URL from next, first, or last links
+        reference_url = links.next&.href || links.first&.href || links.last&.href
+        return nil unless reference_url
+
+        # Parse the reference URL and modify the page parameter
+        uri = URI.parse(reference_url)
+        query_params = URI.decode_www_form(uri.query || '')
+
+        # Update the page parameter
+        query_params = query_params.reject { |key, _| key == 'page' }
+        query_params << ['page', target_page.to_s]
+
+        # Reconstruct the URL
+        uri.query = URI.encode_www_form(query_params)
+        uri.to_s
+      end
     end
   end
 end

data/lib/lutaml/hal/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Hal
-    VERSION = '0.1.5'
+    VERSION = '0.1.6'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-hal
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-13 00:00:00.000000000 Z
+date: 2025-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday