jahuty 3.1.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2c235fb1ce67c99a9bf584d4e899802b3c63114b91331439a3d3832b721e28e
-  data.tar.gz: 1c3b9ed4d76d7b7bc9ae21dc975a4ff4bad728f7a1374f1e53a12c0b5307ae19
+  metadata.gz: 42d427523be1564e07087d282367b7c13b9e80ac7219522a26a86a04f6fd23e7
+  data.tar.gz: 5f164380a18fda536c08c918dbfaaba6aaffc02183cfb2e74c6944b3e0bc42c3
 SHA512:
-  metadata.gz: 1eef3b6308a8ff3f6b967840d51de4ea2281e3e144f81bdbc91009c2a81068522e50ded68c0dd20c89e070672899d26d393d371718472bd2f837e65520483677
-  data.tar.gz: e9e72191ea7766ab12ca962176f838f01129903bc28b7677e453a346726c5197ac1f4f225bdb85309f68d755c32adbec61a921eb0039f4582a04d9b171f071c8
+  metadata.gz: f5b8c35c587b3f26a7fce8830963c98c859307e444edf5a0b058695e954fc5ce1dd0220b25f99d874ed983f1c72474546b51a2294f718bbea0358198d01ce6f6
+  data.tar.gz: 6f037d7ee49936532c2bd2ed5ed6f91942352f95082da4af28bd390afd3bc0d0dfdcda847f2c4e4ad742e4b1702562c9c6cba6c0fd5df4c923756c4113aa3d6a

data/CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 3.2.0 - 2020-03-08
+
+* Added collections to the library with `all_renders` method. This was a rather large change and required adding new objects like `Action::Show`, refactoring old ones like `Resource::Factory`, and removing some objects like `Cache::Manager` and `Service::Factory` which added unnecessary complexity.
+* Added `snippet_id` to `Resource::Render` to help keep track of a render's parent snippet.
+
 ## 3.1.1 - 2020-02-26
 
 - Add support for extra, unused attributes returned by the API to support evolution.

data/README.md

@@ -26,7 +26,7 @@ jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
 puts jahuty.snippets.render YOUR_SNIPPET_ID
 ```
 
-You can also access the render's content with `to_s` or `content`:
+You can access the render's content with `to_s` or `content`:
 
 ```ruby
 jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
@@ -54,9 +54,19 @@ In an HTML view:
 </body>
 ```
 
+You can also use tags to render a collection of snippets with the `snippets.all_renders` method:
+
+```ruby
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
+
+renders = jahuty.snippets.all_renders 'YOUR_TAG'
+
+renders.each { |render| puts render }
+```
+
 ## Parameters
 
-You can [pass parameters](https://docs.jahuty.com/liquid/parameters) into your snippet using the `params` option:
+You can [pass parameters](https://docs.jahuty.com/liquid/parameters) into your renders using the `params` option:
 
 ```ruby
 jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
@@ -70,6 +80,30 @@ The parameters above would be equivalent to [assigning the variable](https://doc
 {% assign foo = "bar" %}
 ```
 
+If you're rendering a collection, the first dimension of the `params` key determines the parameters' scope. Use an asterisk key (`*`) to pass the same parameters to all snippets, or use a snippet id as key to pass parameters to a specific snippet.
+
+```ruby
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
+
+jahuty.snippets.all_renders 'YOUR_TAG', params: {
+  '*' => { foo: 'bar' },
+  '1' => { baz: 'qux' }
+}
+```
+
+This will pass the params `{ foo: 'bar' }` to all snippets, except for snippet `1`, which will be passed `{ foo: 'bar', baz: 'qux' }`.
+
+The two parameter lists will be merged recursively, and parameters for a specific snippet will take precedence over parameters for all snippets. For example, the parameter `foo` will be assigned the value `"bar"` for all snippets, except for snippet `1`, where it will be assigned the value `"qux"`:
+
+```ruby
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY')
+
+jahuty.snippets.all_renders 'YOUR_TAG', params: {
+  '*' => { foo: 'bar' },
+  '1' => { foo: 'qux' }
+}
+```
+
 ## Caching
 
 You can use caching to control how frequently this library requests the latest content from Jahuty's API.
@@ -133,22 +167,44 @@ jahuty = Jahuty::Client.new(
 )
 ```
 
-If this library's default `:expires_in` is set, it will take precedence over the default `:expires_is` of the caching implementation.
+If this library's default `:expires_in` is set, it will take precedence over the default `:expires_in` of the caching implementation.
 
 #### Configuring a render's `:expires_in`
 
-You can configure a single render's `:expires_in` by passing an integer number of seconds via its `:expires_in` configuration option:
+You can configure `:expires_in` for individual renders by passing an integer number of seconds via the render method's `:expires_in` configuration option:
 
 ```ruby
-# Default to the caching implementation's :expires_in for all renders.
-jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY', cache: cache)
+# Cache all renders 300 seconds (five minutes).
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY', cache: cache, expires_in: 300)
 
 # Except, cache this render for 60 seconds.
-render = jahuty.snippets.render(1, expires_in: 60)
+render = jahuty.snippets.render YOUR_SNIPPET_ID, expires_in: 60
+
+# Except, cache the renders in this collection for 120 seconds.
+render = jahuty.snippets.all_renders 'YOUR_TAG', expires_in: 120
 ```
 
 If a render's `:expires_in` is set, it will take precedence over the library's default `:expires_in` and the caching implementation's `:expires_in`.
 
+### Caching collections
+
+By default, this library will cache each render returned by `all_renders`:
+
+```ruby
+jahuty = Jahuty::Client.new(api_key: 'YOUR_API_KEY', cache: cache)
+
+# Sends a network request, caches each render, and returns the collection.
+jahuty.snippets.all_renders 'YOUR_TAG';
+
+# If this reder exists in the collection, the cached value will be used instead
+# of sending a network request for the latest version.
+jahuty.snippets.render YOUR_SNIPPET_ID;
+```
+
+This is a powerful feature, especially when combined with a persistent cache. Using the `all_renders` method, you can render and cache an arbitrarily large chunk of content with a single network request. Because any subsequent call to `render` a snippet in the collection will use its cached version, you can reduce the number of network requests to load your content.
+
+This method is even more powerful when combined with an asynchronous background job. When `all_renders` can be called outside your request cycle periodically, you can turn your cache into your content storage mechanism. You can render and cache dynamic content as frequently as you like without any hit to your application's response time.
+
 ### Disabling caching
 
 You can disable caching, even the default in-memory caching, by passing an `:expires_in` of zero (`0`) or a negative integer (e.g., `-1`) via any of the methods described above. For example:
@@ -159,7 +215,7 @@ jahuty1 = Jahuty::Client.new(api_key: 'YOUR_API_KEY', expires_in: 0)
 
 # Disable caching for this render.
 jahuty2 = Jahuty::Client.new(api_key: 'YOUR_API_KEY', expires_in: 60)
-jahuty2.snippets.render(1, expires_in: 0)
+jahuty2.snippets.render 1, expires_in: 0
 ```
 
 ## Errors

data/lib/jahuty.rb

@@ -3,12 +3,12 @@
 require 'jahuty/version'
 
 require 'jahuty/action/base'
+require 'jahuty/action/index'
 require 'jahuty/action/show'
 
 require 'jahuty/api/client'
 
 require 'jahuty/cache/facade'
-require 'jahuty/cache/manager'
 
 require 'jahuty/exception/error'
 
@@ -19,12 +19,15 @@ require 'jahuty/resource/problem'
 require 'jahuty/resource/render'
 require 'jahuty/resource/factory'
 
+require 'jahuty/response/handler'
+
 require 'jahuty/service/base'
 require 'jahuty/service/snippet'
-require 'jahuty/service/factory'
 
 require 'jahuty/client'
 
+require 'jahuty/util'
+
 module Jahuty
   BASE_URI = 'https://api.jahuty.com'
 end

data/lib/jahuty/action/index.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Jahuty
+  module Action
+    # Displays a collection of resources.
+    class Index < Base
+    end
+  end
+end

data/lib/jahuty/client.rb

@@ -7,30 +7,25 @@ module Jahuty
   class Client
     def initialize(api_key:, cache: nil, expires_in: nil)
       @api_key    = api_key
-      @cache      = cache || ::MiniCache::Store.new
+      @cache      = Cache::Facade.new(cache || ::MiniCache::Store.new)
       @expires_in = expires_in
-      @services   = Service::Factory.new(client: self)
+      @services   = {}
     end
 
     # Allows services to be accessed as properties (e.g., jahuty.snippets).
     def method_missing(name, *args, &block)
-      if args.empty? && @services.respond_to?(name)
-        @services.send(name)
+      if args.empty? && name == :snippets
+        unless @services.key?(name)
+          @services[name] = Service::Snippet.new(
+            client: self, cache: @cache, expires_in: @expires_in
+          )
+        end
+        @services[name]
       else
         super
       end
     end
 
-    def fetch(action, expires_in: nil)
-      @manager ||= Cache::Manager.new(
-        client: self,
-        cache: @cache,
-        expires_in: expires_in || @expires_in
-      )
-
-      @manager.fetch(action)
-    end
-
     def request(action)
       @requests ||= Request::Factory.new
 
@@ -40,17 +35,17 @@ module Jahuty
 
       response = @client.send(request)
 
-      @resources ||= Resource::Factory.new
+      @responses ||= Response::Handler.new
 
-      resource = @resources.call(action, response)
+      result = @responses.call(action, response)
 
-      raise Exception::Error.new(resource), 'API responded with a problem' if resource.is_a?(Resource::Problem)
+      raise Exception::Error.new(result), 'API problem' if result.is_a?(Resource::Problem)
 
-      resource
+      result
     end
 
     def respond_to_missing?(name, include_private = false)
-      @services.respond_to?(name, include_private) || super
+      name == :snippets || super
     end
   end
 end

data/lib/jahuty/request/factory.rb

@@ -2,16 +2,28 @@
 
 module Jahuty
   module Request
-    # Instantiates a request from an action. Currently, this is elementary. As
-    # we add actions, it will become more complicated.
+    # Instantiates a request from an action.
     class Factory
       def call(action)
         Base.new(
           method: 'get',
-          path: "snippets/#{action.id}/render",
+          path: path(action),
           params: action.params
         )
       end
+
+      private
+
+      def path(action)
+        case action
+        when ::Jahuty::Action::Show
+          "snippets/#{action.id}/render"
+        when ::Jahuty::Action::Index
+          'snippets/render'
+        else
+          raise ArgumentError, 'Action is not supported'
+        end
+      end
     end
   end
 end

data/lib/jahuty/resource/factory.rb

@@ -1,31 +1,20 @@
 # frozen_string_literal: true
 
-require 'json'
-
 module Jahuty
   module Resource
-    # Negotiates the resource to return given the requested action and the
-    # server's response.
+    # Instantiates and returns a resource.
     class Factory
       CLASSES = {
         problem: Problem.name,
         render: Render.name
       }.freeze
 
-      def call(action, response)
-        if success? response
-          resource_name = action.resource
-        elsif problem? response
-          resource_name = 'problem'
-        else
-          raise ArgumentError, 'Unexpected response'
-        end
-
-        resource_class = class_name(resource_name.to_sym)
+      def call(resource_name, payload)
+        klass = class_name(resource_name.to_sym)
 
-        payload = parse(response)
+        raise ArgumentError, "#{resource_name} missing" if klass.nil?
 
-        Object.const_get(resource_class).send(:from, **payload)
+        Object.const_get(klass).send(:from, **payload)
       end
 
       private
@@ -33,18 +22,6 @@ module Jahuty
       def class_name(resource_name)
         CLASSES[resource_name.to_sym]
       end
-
-      def problem?(response)
-        response.headers['Content-Type'] == 'application/problem+json'
-      end
-
-      def parse(response)
-        JSON.parse(response.body, symbolize_names: true)
-      end
-
-      def success?(response)
-        response.status.between?(200, 299)
-      end
     end
   end
 end

data/lib/jahuty/resource/render.rb

@@ -4,16 +4,18 @@ module Jahuty
   module Resource
     # A snippet's rendered content.
     class Render
-      attr_accessor :content
+      attr_accessor :content, :snippet_id
 
-      def initialize(content:)
+      def initialize(content:, snippet_id:)
         @content = content
+        @snippet_id = snippet_id
       end
 
       def self.from(data)
         raise ArgumentError.new, 'Key :content missing' unless data.key?(:content)
+        raise ArgumentError.new, 'Key :snippet_id missing' unless data.key?(:snippet_id)
 
-        Render.new(data.slice(:content))
+        Render.new(data.slice(:content, :snippet_id))
       end
 
       def to_s

data/lib/jahuty/response/handler.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Jahuty
+  module Response
+    # Inspects the response and returns the appropriate resource or collection.
+    class Handler
+      def call(action, response)
+        resource_name = name_resource action, response
+
+        payload = parse response
+
+        @resources ||= ::Jahuty::Resource::Factory.new
+
+        if collection?(action, payload)
+          payload.map { |data| @resources.call resource_name, data }
+        elsif resource?(action, payload)
+          @resources.call resource_name, payload
+        else
+          raise ArgumentError, 'Action and payload mismatch'
+        end
+      end
+
+      private
+
+      def collection?(action, payload)
+        action.is_a?(Action::Index) && payload.is_a?(::Array)
+      end
+
+      def name_resource(action, response)
+        if success? response
+          action.resource
+        elsif problem? response
+          'problem'
+        else
+          raise ArgumentError, 'Unexpected response'
+        end
+      end
+
+      def parse(response)
+        JSON.parse(response.body, symbolize_names: true)
+      end
+
+      def problem?(response)
+        response.headers['Content-Type'].include?('application/problem+json') &&
+          (response.status < 200 || response.status >= 300)
+      end
+
+      def resource?(action, payload)
+        !action.is_a?(Action::Index) && payload.is_a?(::Object)
+      end
+
+      def success?(response)
+        response.headers['Content-Type'].include?('application/json') &&
+          response.status.between?(200, 299)
+      end
+    end
+  end
+end

data/lib/jahuty/service/snippet.rb

@@ -4,12 +4,93 @@ module Jahuty
   module Service
     # A service for interacting with snippets.
     class Snippet < Base
-      def render(id, params: {}, expires_in: nil)
-        params = { params: params.to_json } unless params.empty?
+      def initialize(client:, cache:, expires_in: nil)
+        super(client: client)
 
-        action = ::Jahuty::Action::Show.new(id: id, resource: 'render', params: params)
+        @cache = cache
+        @expires_in = expires_in
+      end
+
+      def all_renders(tag, params: {}, expires_in: nil)
+        renders = index_renders tag: tag, params: params
+
+        cache_renders renders: renders, params: params, expires_in: expires_in
+
+        renders
+      end
+
+      def render(snippet_id, params: {}, expires_in: nil)
+        expires_in ||= @expires_in
+
+        key = cache_key snippet_id: snippet_id, params: params
+
+        render = @cache.read(key)
+
+        @cache.delete key unless render.nil? || cacheable?(expires_in)
+
+        if render.nil?
+          render = show_render snippet_id: snippet_id, params: params
+
+          @cache.write key, render, expires_in: expires_in if cacheable?(expires_in)
+        end
+
+        render
+      end
+
+      private
+
+      def cache_key(snippet_id:, params: {})
+        fingerprint = Digest::MD5.new
+        fingerprint << "snippets/#{snippet_id}/render/"
+        fingerprint << params.to_json
+
+        "jahuty_#{fingerprint.hexdigest}"
+      end
+
+      def cache_renders(renders:, params:, expires_in: nil)
+        expires_in ||= @expires_in
+
+        return unless cacheable?(expires_in)
+
+        global_params = params['*'] || {}
+
+        renders.each do |render|
+          local_params = params[render.snippet_id.to_s] || {}
+          render_params = ::Jahuty::Util.deep_merge global_params, local_params
+
+          key = cache_key snippet_id: render.snippet_id, params: render_params
+
+          @cache.write key, render, expires_in: expires_in
+        end
+      end
+
+      def cacheable?(expires_in)
+        expires_in.nil? || expires_in.positive?
+      end
+
+      def index_renders(tag:, params: {})
+        request_params = { tag: tag }
+        request_params[:params] = params.to_json unless params.empty?
+
+        action = ::Jahuty::Action::Index.new(
+          resource: 'render',
+          params: request_params
+        )
+
+        @client.request action
+      end
+
+      def show_render(snippet_id:, params: {})
+        request_params = {}
+        request_params[:params] = params.to_json unless params.empty?
+
+        action = ::Jahuty::Action::Show.new(
+          id: snippet_id,
+          resource: 'render',
+          params: request_params
+        )
 
-        @client.fetch action, expires_in: expires_in
+        @client.request action
       end
     end
   end

data/lib/jahuty/util.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jahuty
+  # Utility methods.
+  class Util
+    # Deeply merges two hashes like Rails.
+    #
+    # Ideally, the API and this library could use the same method to merge
+    # parameters. This library's method just needs to be deterministic and not
+    # collide distinct combinations.
+    #
+    # @see  https://github.com/rails/rails/blob/main/activesupport/lib/active_support/core_ext/hash/deep_merge.rb
+    def self.deep_merge(first_hash, other_hash, &block)
+      first_hash.merge!(other_hash) do |key, first_val, other_val|
+        if first_val.is_a?(Hash) && other_val.is_a?(Hash)
+          deep_merge(first_val, other_val, &block)
+        elsif block
+          yield(key, first_val, other_val)
+        else
+          other_val
+        end
+      end
+    end
+  end
+end

data/lib/jahuty/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jahuty
-  VERSION = '3.1.1'
+  VERSION = '3.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jahuty
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.2.0
 platform: ruby
 authors:
 - Jack Clayton
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-02-27 00:00:00.000000000 Z
+date: 2021-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -199,10 +199,10 @@ files:
 - jahuty.gemspec
 - lib/jahuty.rb
 - lib/jahuty/action/base.rb
+- lib/jahuty/action/index.rb
 - lib/jahuty/action/show.rb
 - lib/jahuty/api/client.rb
 - lib/jahuty/cache/facade.rb
-- lib/jahuty/cache/manager.rb
 - lib/jahuty/client.rb
 - lib/jahuty/exception/error.rb
 - lib/jahuty/request/base.rb
@@ -210,9 +210,10 @@ files:
 - lib/jahuty/resource/factory.rb
 - lib/jahuty/resource/problem.rb
 - lib/jahuty/resource/render.rb
+- lib/jahuty/response/handler.rb
 - lib/jahuty/service/base.rb
-- lib/jahuty/service/factory.rb
 - lib/jahuty/service/snippet.rb
+- lib/jahuty/util.rb
 - lib/jahuty/version.rb
 homepage: https://www.jahuty.com
 licenses:

data/lib/jahuty/cache/manager.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Jahuty
-  module Cache
-    # Fetches the requested action from the cache or API.
-    class Manager
-      def initialize(cache:, client:, expires_in: nil)
-        @client     = client
-        @cache      = Facade.new(cache)
-        @expires_in = expires_in
-      end
-
-      def fetch(action, expires_in: nil)
-        key   = key action
-        value = @cache.read key
-
-        @cache.delete key unless value.nil? || cacheable(expires_in)
-
-        if value.nil?
-          value = @client.request action
-          @cache.write key, value, expires_in: expires_in || @expires_in if cacheable(expires_in)
-        end
-
-        value
-      end
-
-      private
-
-      def cacheable(expires_in)
-        expires_in.nil? || expires_in.positive?
-      end
-
-      def key(action)
-        # We only build cache keys for show-render actions at this time.
-        unless action.is_a?(::Jahuty::Action::Show) && action.resource == 'render'
-          raise ArgumentError, 'Action must be show render'
-        end
-
-        fingerprint = Digest::MD5.new
-        fingerprint << "snippets/#{action.id}/render/"
-        fingerprint << action.params.to_json
-
-        "jahuty_#{fingerprint.hexdigest}"
-      end
-    end
-  end
-end

data/lib/jahuty/service/factory.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module Jahuty
-  module Service
-    # Instantiates the requested service and memoizes it for subsequent
-    # requests.
-    class Factory
-      CLASSES = {
-        snippets: Snippet.name
-      }.freeze
-
-      def initialize(client:)
-        @client   = client
-        @services = {}
-      end
-
-      def method_missing(name, *args, &block)
-        if args.empty? && class_name?(name)
-          unless @services.key?(name)
-            klass   = class_name(name)
-            service = Object.const_get(klass).send(:new, client: @client)
-            @services[name] = service
-          end
-
-          @services[name]
-        else
-          super
-        end
-      end
-
-      def respond_to_missing?(name, include_private = false)
-        class_name(name) || super
-      end
-
-      private
-
-      def class_name(service_name)
-        CLASSES[service_name]
-      end
-
-      def class_name?(service_name)
-        CLASSES.key?(service_name)
-      end
-    end
-  end
-end