twitter_with_auto_pagination 0.6.2 → 0.7.0

data/lib/twitter_with_auto_pagination/rest/extension/replying.rb

@@ -0,0 +1,90 @@
+require 'twitter_with_auto_pagination/rest/utils'
+
+module TwitterWithAutoPagination
+  module REST
+    module Extension
+      module Replying
+        include TwitterWithAutoPagination::REST::Utils
+
+        def _extract_screen_names(tweets)
+          tweets.map do |t|
+            $1 if t.text =~ /^(?:\.)?@(\w+)( |\W)/ # include statuses starts with .
+          end.compact
+        end
+
+        def _retrieve_user_timeline(*args)
+          options = args.extract_options!
+          if args.empty?
+            user_timeline(options)
+          elsif uid_or_screen_name?(args[0])
+            user_timeline(args[0], options)
+          elsif args[0].kind_of?(Array) && args[0].all? { |t| t.respond_to?(:text) }
+            args[0]
+          else
+            raise ArgumentError
+          end
+        end
+
+        # users which specified user is replying
+        # in_reply_to_user_id and in_reply_to_status_id is not used because of distinguishing mentions from replies
+        def users_which_you_replied_to(*args)
+          options = args.extract_options!
+          instrument(__method__, nil, options) do
+            tweets = _retrieve_user_timeline(*args, options)
+            screen_names = _extract_screen_names(tweets)
+            result = users(screen_names, {super_operation: __method__}.merge(options))
+            if options.has_key?(:uniq) && !options[:uniq]
+              screen_names.map { |sn| result.find { |u| u.screen_name == sn } }.compact
+            else
+              result.uniq { |u| u.id }
+            end
+          end
+        rescue Twitter::Error::NotFound => e
+          e.message == 'No user matches for specified terms.' ? [] : (raise e)
+        rescue => e
+          logger.warn "#{__method__} #{args.inspect} #{e.class} #{e.message}"
+          raise e
+        end
+
+        alias replying users_which_you_replied_to
+
+        def _extract_uids(tweets)
+          tweets.map do |t|
+            t.user.id.to_i if t.text =~ /^(?:\.)?@(\w+)( |\W)/ # include statuses starts with .
+          end.compact
+        end
+
+        def _extract_users(tweets, uids)
+          uids.map { |uid| tweets.find { |t| t.user.id.to_i == uid.to_i } }.map { |t| t.user }.compact
+        end
+
+        def _retrieve_users_from_mentions_timeline(*args)
+          options = args.extract_options!
+          if args.empty? || (uid_or_screen_name?(args[0]) && authenticating_user?(args[0]))
+            mentions_timeline.map { |m| m.user }
+          else
+            searched_result = search('@' + user(args[0]).screen_name, options)
+            uids = _extract_uids(searched_result)
+            _extract_users(searched_result, uids)
+          end
+        end
+
+        # users which specified user is replied
+        # when user is login you had better to call mentions_timeline
+        def users_who_replied_to_you(*args)
+          options = args.extract_options!
+          instrument(__method__, nil, options) do
+            result = _retrieve_users_from_mentions_timeline(*args, options)
+            if options.has_key?(:uniq) && !options[:uniq]
+              result
+            else
+              result.uniq { |r| r.id }
+            end
+          end
+        end
+
+        alias replied users_who_replied_to_you
+      end
+    end
+  end
+end

data/lib/twitter_with_auto_pagination/rest/extension/unfollowing.rb

@@ -0,0 +1,29 @@
+require 'twitter_with_auto_pagination/rest/utils'
+
+module TwitterWithAutoPagination
+  module REST
+    module Extension
+      module Unfollowing
+        include TwitterWithAutoPagination::REST::Utils
+
+        def users_which_you_removed(past_me, cur_me)
+          instrument(__method__, nil) do
+            past_friends, cur_friends = _retrieve_friends(past_me, cur_me)
+            past_friends.to_a - cur_friends.to_a
+          end
+        end
+
+        alias unfollowing users_which_you_removed
+
+        def users_who_removed_you(past_me, cur_me)
+          instrument(__method__, nil) do
+            past_followers, cur_followers = _retrieve_followers(past_me, cur_me)
+            past_followers.to_a - cur_followers.to_a
+          end
+        end
+
+        alias unfollowed users_who_removed_you
+      end
+    end
+  end
+end

data/lib/twitter_with_auto_pagination/rest/favorites.rb

@@ -0,0 +1,20 @@
+require 'twitter_with_auto_pagination/rest/utils'
+
+module TwitterWithAutoPagination
+  module REST
+    module Favorites
+      include TwitterWithAutoPagination::REST::Utils
+
+      def favorites(*args)
+        # TODO call_count bug fix
+        options = {count: 100, call_count: 1}.merge(args.extract_options!)
+        args[0] = verify_credentials.id if args.empty?
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, args[0], options) do
+            collect_with_max_id(method(__method__).super_method, *args, options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twitter_with_auto_pagination/rest/friends_and_followers.rb

@@ -0,0 +1,94 @@
+require 'twitter_with_auto_pagination/rest/utils'
+
+module TwitterWithAutoPagination
+  module REST
+    module FriendsAndFollowers
+      include TwitterWithAutoPagination::REST::Utils
+
+      def friendship?(*args)
+        options = args.extract_options!
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, args) do
+            call_api(method(__method__).super_method, *args, options)
+          end
+        end
+      end
+
+      def friend_ids(*args)
+        options = {count: 5000, cursor: -1}.merge(args.extract_options!)
+        args[0] = verify_credentials.id if args.empty?
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, args[0], options) do
+            collect_with_cursor(method(__method__).super_method, *args, options)
+          end
+        end
+      end
+
+      def follower_ids(*args)
+        options = {count: 5000, cursor: -1}.merge(args.extract_options!)
+        args[0] = verify_credentials.id if args.empty?
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, args[0], options) do
+            collect_with_cursor(method(__method__).super_method, *args, options)
+          end
+        end
+      end
+
+      # specify reduce: false to use tweet for inactive_*
+      def friends(*args)
+        options = args.extract_options!
+        if options.delete(:serial)
+          _friends_serially(*args, options)
+        else
+          _friends_parallelly(*args, options)
+        end
+      end
+
+      def _friends_serially(*args)
+        options = {count: 200, include_user_entities: true, cursor: -1}.merge(args.extract_options!)
+        options[:reduce] = false unless options.has_key?(:reduce)
+        args[0] = verify_credentials.id if args.empty?
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(:friends, args[0], options) do
+            collect_with_cursor(method(:friends).super_method, *args, options)
+          end
+        end
+      end
+
+      def _friends_parallelly(*args)
+        options = {super_operation: __method__}.merge(args.extract_options!)
+        instrument(__method__, nil, options) do
+          users(friend_ids(*args, options).map { |id| id.to_i }, options)
+        end
+      end
+
+      # specify reduce: false to use tweet for inactive_*
+      def followers(*args)
+        options = args.extract_options!
+        if options.delete(:serial)
+          _followers_serially(*args, options)
+        else
+          _followers_parallelly(*args, options)
+        end
+      end
+
+      def _followers_serially(*args)
+        options = {count: 200, include_user_entities: true, cursor: -1}.merge(args.extract_options!)
+        options[:reduce] = false unless options.has_key?(:reduce)
+        args[0] = verify_credentials.id if args.empty?
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(:followers, args[0], options) do
+            collect_with_cursor(method(:followers).super_method, *args, options)
+          end
+        end
+      end
+
+      def _followers_parallelly(*args)
+        options = {super_operation: __method__}.merge(args.extract_options!)
+        instrument(__method__, nil, options) do
+          users(follower_ids(*args, options).map { |id| id.to_i }, options)
+        end
+      end
+    end
+  end
+end

data/lib/twitter_with_auto_pagination/rest/search.rb

@@ -0,0 +1,19 @@
+require 'twitter_with_auto_pagination/rest/utils'
+
+module TwitterWithAutoPagination
+  module REST
+    module Search
+      include TwitterWithAutoPagination::REST::Utils
+
+      def search(*args)
+        options = {count: 100, result_type: :recent, call_limit: 1}.merge(args.extract_options!)
+        options[:reduce] = false
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, args[0], options) do
+            collect_with_max_id(method(__method__).super_method, *args, options) { |response| response.attrs[:statuses] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twitter_with_auto_pagination/rest/timelines.rb

@@ -0,0 +1,37 @@
+require 'twitter_with_auto_pagination/rest/utils'
+
+module TwitterWithAutoPagination
+  module REST
+    module Timelines
+      include TwitterWithAutoPagination::REST::Utils
+
+      def home_timeline(*args)
+        options = {count: 200, include_rts: true, call_limit: 3}.merge(args.extract_options!)
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, verify_credentials.id, options) do
+            collect_with_max_id(method(__method__).super_method, options)
+          end
+        end
+      end
+
+      def user_timeline(*args)
+        options = {count: 200, include_rts: true, call_limit: 3}.merge(args.extract_options!)
+        args[0] = verify_credentials.id if args.empty?
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, args[0], options) do
+            collect_with_max_id(method(__method__).super_method, *args, options)
+          end
+        end
+      end
+
+      def mentions_timeline(*args)
+        options = {count: 200, include_rts: true, call_limit: 1}.merge(args.extract_options!)
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, verify_credentials.id, options) do
+            collect_with_max_id(method(__method__).super_method, options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twitter_with_auto_pagination/rest/uncategorized.rb

@@ -0,0 +1,83 @@
+require 'twitter_with_auto_pagination/rest/utils'
+
+module TwitterWithAutoPagination
+  module REST
+    module Uncategorized
+      include TwitterWithAutoPagination::REST::Utils
+
+      def usage_stats_wday_series_data(times)
+        wday_count = times.each_with_object((0..6).map { |n| [n, 0] }.to_h) do |time, memo|
+          memo[time.wday] += 1
+        end
+        wday_count.map { |k, v| [I18n.t('date.abbr_day_names')[k], v] }.map do |key, value|
+          {name: key, y: value, drilldown: key}
+        end
+      end
+
+      def usage_stats_wday_drilldown_series(times)
+        hour_count =
+          (0..6).each_with_object((0..6).map { |n| [n, nil] }.to_h) do |wday, wday_memo|
+            wday_memo[wday] =
+              times.select { |t| t.wday == wday }.map { |t| t.hour }.each_with_object((0..23).map { |n| [n, 0] }.to_h) do |hour, hour_memo|
+                hour_memo[hour] += 1
+              end
+          end
+        hour_count.map { |k, v| [I18n.t('date.abbr_day_names')[k], v] }.map do |key, value|
+          {name: key, id: key, data: value.to_a.map{|a| [a[0].to_s, a[1]] }}
+        end
+      end
+
+      def usage_stats_hour_series_data(times)
+        hour_count = times.each_with_object((0..23).map { |n| [n, 0] }.to_h) do |time, memo|
+          memo[time.hour] += 1
+        end
+        hour_count.map do |key, value|
+          {name: key.to_s, y: value, drilldown: key.to_s}
+        end
+      end
+
+      def usage_stats_hour_drilldown_series(times)
+        wday_count =
+          (0..23).each_with_object((0..23).map { |n| [n, nil] }.to_h) do |hour, hour_memo|
+            hour_memo[hour] =
+              times.select { |t| t.hour == hour }.map { |t| t.wday }.each_with_object((0..6).map { |n| [n, 0] }.to_h) do |wday, wday_memo|
+                wday_memo[wday] += 1
+              end
+          end
+        wday_count.map do |key, value|
+          {name: key.to_s, id: key.to_s, data: value.to_a.map{|a| [I18n.t('date.abbr_day_names')[a[0]], a[1]] }}
+        end
+      end
+
+      def twitter_addiction_series(times)
+        five_mins = 5.minutes
+        wday_expended_seconds =
+          (0..6).each_with_object((0..6).map { |n| [n, nil] }.to_h) do |wday, wday_memo|
+            target_times = times.select { |t| t.wday == wday }
+            wday_memo[wday] = target_times.empty? ? nil : target_times.each_cons(2).map {|a, b| (a - b) < five_mins ? a - b : five_mins }.sum
+          end
+        days = times.map{|t| t.to_date.to_s(:long) }.uniq.size
+        weeks = (days > 7) ? days / 7.0 : 1.0
+        wday_expended_seconds.map { |k, v| [I18n.t('date.abbr_day_names')[k], (v.nil? ? nil : v / weeks / 60)] }.map do |key, value|
+          {name: key, y: value}
+        end
+      end
+
+      def usage_stats(user, options = {})
+        n_days_ago = options.has_key?(:days) ? options[:days].days.ago : 100.years.ago
+        tweets = options.has_key?(:tweets) ? options.delete(:tweets) : user_timeline(user)
+        times =
+          # TODO Use user specific time zone
+          tweets.map { |t| ActiveSupport::TimeZone['Tokyo'].parse(t.created_at.to_s) }.
+            select { |t| t > n_days_ago }
+        [
+          usage_stats_wday_series_data(times),
+          usage_stats_wday_drilldown_series(times),
+          usage_stats_hour_series_data(times),
+          usage_stats_hour_drilldown_series(times),
+          twitter_addiction_series(times)
+        ]
+      end
+    end
+  end
+end

data/lib/twitter_with_auto_pagination/rest/users.rb

@@ -0,0 +1,62 @@
+require 'twitter_with_auto_pagination/rest/utils'
+require 'parallel'
+
+module TwitterWithAutoPagination
+  module REST
+    module Users
+      include TwitterWithAutoPagination::REST::Utils
+
+      def verify_credentials(*args)
+        options = {skip_status: true}.merge(args.extract_options!)
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, args) do
+            call_api(method(__method__).super_method, *args, options)
+          end
+        end
+      end
+
+      def user?(*args)
+        options = args.extract_options!
+        args[0] = verify_credentials.id if args.empty?
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, args[0], options) do
+            call_api(method(__method__).super_method, *args, options)
+          end
+        end
+      end
+
+      def user(*args)
+        options = args.extract_options!
+        args[0] = verify_credentials.id if args.empty?
+        instrument(__method__, nil, options) do
+          fetch_cache_or_call_api(__method__, args[0], options) do
+            call_api(method(__method__).super_method, *args, options)
+          end
+        end
+      end
+
+      # use compact, not use sort and uniq
+      # specify reduce: false to use tweet for inactive_*
+      # TODO Perhaps `old_users` automatically merges result...
+      def users(*args)
+        options = args.extract_options!
+        options[:reduce] = false
+        users_per_workers = args.first.compact.each_slice(100).to_a
+        processed_users = []
+        thread_size = [users_per_workers.size, 10].min
+
+        instrument(__method__, nil, options) do
+          Parallel.each_with_index(users_per_workers, in_threads: thread_size) do |users_per_worker, i|
+            _users = fetch_cache_or_call_api(__method__, users_per_worker, options) do
+              call_api(method(__method__).super_method, users_per_worker, options)
+            end
+
+            processed_users << {i: i, users: _users}
+          end
+        end
+
+        processed_users.sort_by { |p| p[:i] }.map { |p| p[:users] }.flatten.compact
+      end
+    end
+  end
+end

data/lib/twitter_with_auto_pagination/rest/utils.rb

@@ -0,0 +1,303 @@
+require 'hashie'
+require 'digest/md5'
+
+module TwitterWithAutoPagination
+  module REST
+    module Utils
+      # for backward compatibility
+      def uid
+        @uid || user.id.to_i
+      end
+
+      def __uid
+        ActiveSupport::Deprecation.warn(<<-MESSAGE.strip_heredoc)
+          `TwitterWithAutoPagination::Utils##{__method__}` is deprecated.
+        MESSAGE
+        uid
+      end
+
+      def __uid_i
+        ActiveSupport::Deprecation.warn(<<-MESSAGE.strip_heredoc)
+          `TwitterWithAutoPagination::Utils##{__method__}` is deprecated.
+        MESSAGE
+        uid
+      end
+
+      # for backward compatibility
+      def screen_name
+        @screen_name || user.screen_name
+      end
+
+      def __screen_name
+        ActiveSupport::Deprecation.warn(<<-MESSAGE.strip_heredoc)
+          `TwitterWithAutoPagination::Utils##{__method__}` is deprecated.
+        MESSAGE
+        screen_name
+      end
+
+      def uid_or_screen_name?(object)
+        object.kind_of?(String) || object.kind_of?(Integer)
+      end
+
+      def authenticating_user?(target)
+        user.id.to_i == user(target).id.to_i
+      end
+
+      def authorized_user?(target)
+        target_user = user(target)
+        !target_user.protected? || friendship?(user.id.to_i, target_user.id.to_i)
+      end
+
+      def credentials_hash
+        str = access_token + access_token_secret + consumer_key + consumer_secret
+        Digest::MD5.hexdigest(str)
+      end
+
+      def instrument(operation, key, options = nil)
+        payload = {operation: operation, key: key}
+        payload.merge!(options) if options.is_a?(Hash)
+        ActiveSupport::Notifications.instrument('call.twitter_with_auto_pagination', payload) { yield(payload) }
+      end
+
+      def call_api(method_obj, *args)
+        api_options = args.extract_options!
+        begin
+          self.call_count += 1
+          # TODO call without reduce, call_count
+          options = {method_name: method_obj.name, call_count: self.call_count, args: [*args, api_options]}
+          instrument('request', args[0], options) { method_obj.call(*args, api_options) }
+        rescue Twitter::Error::TooManyRequests => e
+          logger.warn "#{__method__}: #{options.inspect} #{e.class} Retry after #{e.rate_limit.reset_in} seconds."
+          raise e
+        rescue Twitter::Error::ServiceUnavailable, Twitter::Error::InternalServerError,
+          Twitter::Error::Forbidden, Twitter::Error::NotFound => e
+          logger.warn "#{__method__}: #{options.inspect} #{e.class} #{e.message}"
+          raise e
+        rescue => e
+          logger.warn "NEED TO CATCH! #{__method__}: #{options.inspect} #{e.class} #{e.message}"
+          raise e
+        end
+      end
+
+      # user_timeline, search
+      def collect_with_max_id(method_obj, *args)
+        options = args.extract_options!
+        call_limit = options.delete(:call_limit) || 3
+        last_response = call_api(method_obj, *args, options)
+        last_response = yield(last_response) if block_given?
+        return_data = last_response
+        call_count = 1
+
+        while last_response.any? && call_count < call_limit
+          options[:max_id] = last_response.last.kind_of?(Hash) ? last_response.last[:id] : last_response.last.id
+          last_response = call_api(method_obj, *args, options)
+          last_response = yield(last_response) if block_given?
+          return_data += last_response
+          call_count += 1
+        end
+
+        return_data.flatten
+      end
+
+      # friends, followers
+      def collect_with_cursor(method_obj, *args)
+        options = args.extract_options!
+        last_response = call_api(method_obj, *args, options).attrs
+        return_data = (last_response[:users] || last_response[:ids])
+
+        while (next_cursor = last_response[:next_cursor]) && next_cursor != 0
+          options[:cursor] = next_cursor
+          last_response = call_api(method_obj, *args, options).attrs
+          return_data += (last_response[:users] || last_response[:ids])
+        end
+
+        return_data
+      end
+
+      def file_cache_key(method_name, user, options = {})
+        delim = ':'
+        identifier =
+          case
+            when method_name == :verify_credentials
+              "hash-str#{delim}#{credentials_hash}"
+            when method_name == :search
+              "str#{delim}#{user.to_s}"
+            when method_name == :mentions_timeline
+              "#{user.kind_of?(Integer) ? 'id' : 'sn'}#{delim}#{user.to_s}"
+            when method_name == :home_timeline
+              "#{user.kind_of?(Integer) ? 'id' : 'sn'}#{delim}#{user.to_s}"
+            when method_name.in?([:users, :replying]) && options[:super_operation].present?
+              case
+                when user.kind_of?(Array) && user.first.kind_of?(Integer)
+                  "#{options[:super_operation]}-ids#{delim}#{Digest::MD5.hexdigest(user.join(','))}"
+                when user.kind_of?(Array) && user.first.kind_of?(String)
+                  "#{options[:super_operation]}-sns#{delim}#{Digest::MD5.hexdigest(user.join(','))}"
+                else raise "#{method_name.inspect} #{user.inspect}"
+              end
+            when user.kind_of?(Integer)
+              "id#{delim}#{user.to_s}"
+            when user.kind_of?(Array) && user.first.kind_of?(Integer)
+              "ids#{delim}#{Digest::MD5.hexdigest(user.join(','))}"
+            when user.kind_of?(Array) && user.first.kind_of?(String)
+              "sns#{delim}#{Digest::MD5.hexdigest(user.join(','))}"
+            when user.kind_of?(String)
+              "sn#{delim}#{user}"
+            when user.kind_of?(Twitter::User)
+              "user#{delim}#{user.id.to_s}"
+            else raise "#{method_name.inspect} #{user.inspect}"
+          end
+
+        "#{method_name}#{delim}#{identifier}"
+      end
+
+      def namespaced_key(method_name, user, options = {})
+        file_cache_key(method_name, user, options)
+      end
+
+      PROFILE_SAVE_KEYS = %i(
+          id
+          name
+          screen_name
+          location
+          description
+          url
+          protected
+          followers_count
+          friends_count
+          listed_count
+          favourites_count
+          utc_offset
+          time_zone
+          geo_enabled
+          verified
+          statuses_count
+          lang
+          status
+          profile_image_url_https
+          profile_banner_url
+          profile_link_color
+          suspended
+          verified
+          entities
+          created_at
+        )
+
+      STATUS_SAVE_KEYS = %i(
+        created_at
+        id
+        text
+        source
+        truncated
+        coordinates
+        place
+        entities
+        user
+        contributors
+        is_quote_status
+        retweet_count
+        favorite_count
+        favorited
+        retweeted
+        possibly_sensitive
+        lang
+      )
+
+      # encode
+      def encode_json(obj, caller_name, options = {})
+        options[:reduce] = true unless options.has_key?(:reduce)
+        case caller_name
+          when :user_timeline, :home_timeline, :mentions_timeline, :favorites # Twitter::Tweet
+            JSON.pretty_generate(obj.map { |o| o.attrs })
+
+          when :search # Hash
+            data =
+              if options[:reduce]
+                obj.map { |o| o.to_hash.slice(*STATUS_SAVE_KEYS) }
+              else
+                obj.map { |o| o.to_hash }
+              end
+            JSON.pretty_generate(data)
+
+          when :friends, :followers # Hash
+            data =
+              if options[:reduce]
+                obj.map { |o| o.to_hash.slice(*PROFILE_SAVE_KEYS) }
+              else
+                obj.map { |o| o.to_hash }
+              end
+            JSON.pretty_generate(data)
+
+          when :friend_ids, :follower_ids # Integer
+            JSON.pretty_generate(obj)
+
+          when :verify_credentials # Twitter::User
+            JSON.pretty_generate(obj.to_hash.slice(*PROFILE_SAVE_KEYS))
+
+          when :user # Twitter::User
+            JSON.pretty_generate(obj.to_hash.slice(*PROFILE_SAVE_KEYS))
+
+          when :users, :friends_parallelly, :followers_parallelly # Twitter::User
+            data =
+              if options[:reduce]
+                obj.map { |o| o.to_hash.slice(*PROFILE_SAVE_KEYS) }
+              else
+                obj.map { |o| o.to_hash }
+              end
+            JSON.pretty_generate(data)
+
+          when :user? # true or false
+            obj
+
+          when :friendship? # true or false
+            obj
+
+          else
+            raise "#{__method__}: caller=#{caller_name} key=#{options[:key]} obj=#{obj.inspect}"
+        end
+      end
+
+      # decode
+      def decode_json(json_str, caller_name, options = {})
+        obj = json_str.kind_of?(String) ? JSON.parse(json_str) : json_str
+        case
+          when obj.nil?
+            obj
+
+          when obj.kind_of?(Array) && obj.first.kind_of?(Hash)
+            obj.map { |o| Hashie::Mash.new(o) }
+
+          when obj.kind_of?(Array) && obj.first.kind_of?(Integer)
+            obj
+
+          when obj.kind_of?(Hash)
+            Hashie::Mash.new(obj)
+
+          when obj === true || obj === false
+            obj
+
+          when obj.kind_of?(Array) && obj.empty?
+            obj
+
+          else
+            raise "#{__method__}: caller=#{caller_name} key=#{options[:key]} obj=#{obj.inspect}"
+        end
+      end
+
+      def fetch_cache_or_call_api(method_name, user, options = {})
+        key = namespaced_key(method_name, user, options)
+
+        fetch_result =
+          if options[:cache] == :read
+            instrument('Cache Read(Force)', key, caller: method_name) { cache.read(key) }
+          else
+            cache.fetch(key, expires_in: 1.hour, race_condition_ttl: 5.minutes) do
+              block_result = yield
+              instrument('serialize', key, caller: method_name) { encode_json(block_result, method_name, options) }
+            end
+          end
+
+        instrument('deserialize', key, caller: method_name) { decode_json(fetch_result, method_name, options) }
+      end
+    end
+  end
+end