remote_record 0.4.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 285bbd2e1d94c57c73399a83c336404b2eb190e4b08e14287671152cf36dc866
-  data.tar.gz: 9b3ce895695588e43516e86a9498ed64d33ad76771afa13e739835dc12175abb
+  metadata.gz: 8e59abdc5071a945f3bff2c49d9601fd0a5963fe8476c7df38cae943fe960e67
+  data.tar.gz: 469a8ba9bdbf28f3b5ab8a9ac8513dda3720bfb122d6adfb09639429454d0ee6
 SHA512:
-  metadata.gz: d9105b2bd550f9553e2c04c8caa2a1ca1933628e51c3ccf318bc19c62721be4302d1ca490f29ab194dee971642ebb045f102b8e5a8179e3362cb630c7ae8db0a
-  data.tar.gz: 24966ceeb7d708fedaf6413e98496c485f77314d1837ca15cc5d7db9cd1d2e6ed0f3c06d50f7f709cc77f430e36b3f66d18e09e3970b246813b3e2e1c057d528
+  metadata.gz: 7865d6b9f270fb7ffeeb2a8d7cfc7ce298cbfc94f7d1414848dc913b913f71762b1214ab95a9cf1c5e46dbefa9da371fbf25fdf9b75a22aceede815d998f54f7
+  data.tar.gz: 3c472901d7748ec97086a8e9516d8d8edcb10a49cc9a963f5615a146d431f26622c3020cb0367a17f13c5e4df75848c753cde2ac3da0dd06b471bd53dd7e215b

data/README.md

@@ -1,6 +1,20 @@
-# RemoteRecord
+![RemoteRecord: Ready-made remote resource structures.](doc/header.svg)
 
-Ready-made remote resource structures.
+---
+
+![Remote Record](https://github.com/raisedevs/remote_record/workflows/Remote%20Record/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/remote_record.svg)](https://badge.fury.io/rb/remote_record)
+
+Every API speaks a different language. Maybe it's REST, maybe it's SOAP, maybe
+it's GraphQL. Maybe it's got its own Ruby client, or maybe you need to roll your
+own. But what if you could just pretend it existed in your database?
+
+RemoteRecord provides a consistent ActiveRecord inspired interface for all of
+your application's APIs. Store remote resources by ID, and RemoteRecord will
+auto-populate instances of your ActiveRecord model with their attributes from
+the API. Whether you're dealing with a user on GitHub, a track on Spotify, a
+place on Google Maps, or a resource on your internal infrastructure, you can use
+RemoteRecord to wrap fetching it.
 
 ## Setup
 
@@ -110,7 +124,146 @@ caching by way of expiry or ETags, I recommend using `faraday-http-cache` for
 your clients and setting `memoize` to `false`. Remote Record will eventually
 gain support for caching.
 
+### `remote_all` and `remote_where`
+
+If you're able to fetch multiple records at once from the API, implement the
+`self.all` method on your remote record class. This should return an array of
+hashes that can be used to initialize a set of references.
+
+This can optionally take a block
+for authorization - note that it won't use the auth you've configured and that
+you'll always have to supply that inline. For example:
+
+```ruby
+module RemoteRecord
+  module GitHub
+    # :nodoc:
+    class User < RemoteRecord::Base
+      def get
+        client.user(remote_resource_id)
+      end
+
+      def self.all
+        Octokit::Client.new(access_token: yield).users
+      end
+
+      private
+
+      def client
+        Octokit::Client.new(access_token: authorization)
+      end
+    end
+  end
+end
+```
+
+Now you can call `remote_all` on remote reference classes that use
+`RemoteRecord::GitHub::User`, like this:
+
+```ruby
+GitHub::UserReference.remote_all { GITHUB_PERSONAL_ACCESS_TOKEN }
+```
+
+`remote_where` works in the same way, but with a parameter:
+
+```ruby
+module RemoteRecord
+  module GitHub
+    # :nodoc:
+    class User < RemoteRecord::Base
+      def get
+        client.user(remote_resource_id)
+      end
+
+      def self.all
+        Octokit::Client.new(access_token: yield).users
+      end
+
+      def self.where(query)
+        Octokit::Client.new(access_token: yield).search_users(query)
+      end
+
+      private
+
+      def client
+        Octokit::Client.new(access_token: authorization)
+      end
+    end
+  end
+end
+```
+
+Now you can call `remote_where` on remote reference classes that use
+`RemoteRecord::GitHub::User`, like this:
+
+```ruby
+GitHub::UserReference.remote_where('q=tom+repos:%3E42+followers:%3E1000') { GITHUB_PERSONAL_ACCESS_TOKEN }
+```
+
+It's recommended that you include something in `self.where` to filter incoming
+params. Ideally, you want to expose an interface that's as ActiveRecord-like as
+possible, e.g.:
+
+```ruby
+GitHub::UserReference.remote_where(q: 'tom', repos: '>42', followers: '>1000') { GITHUB_PERSONAL_ACCESS_TOKEN }
+```
+
+It's recommended that you write a `Transformer` to do this. Check out
+`RemoteRecord::Transformers::SnakeCase` for an example.
+
+### `initial_attrs`
+
+Behind the scenes, `remote_all` initializes references with a set of
+`initial_attrs`. You can do the same! If you've already fetched the data for an
+object, just pass it to `new` for your reference class under the
+`initial_attrs:`  keyword parameter, like this:
+
+```ruby
+todo = { id: 1, title: 'Hello world' }
+TodoReference.new(remote_resource_id: todo[:id], initial_attrs: todo)
+```
+
 ### Forcing a fresh request
 
 You might want to force a fresh request in some instances, even if you're using
 `memoize`. To do this, call `fresh` on a reference, and it'll be repopulated.
+
+### Skip fetching
+
+You might not want to make a request on initialize sometimes. In this case, pass
+`fetching: false` when creating or initializing references to make sure the
+resource isn't fetched.
+
+When querying for records using ActiveRecord alone, you might want to do so
+within a `no_fetching` context:
+
+```ruby
+TodoReference.no_fetching { |model| model.where(remote_resource_id: 1) }
+```
+
+Any records initialized within a `no_fetching` context won't be requested. It's
+sort of like a `Faraday` cage, pun entirely intended.
+
+If you're using `remote_all` or `remote_where` to fetch using your API, that'll
+automatically use this behind the scenes, then set `attrs` to the response
+value.
+
+### Finding a record without having its canonical ID
+
+On many platforms, you might find yourself searching for users by email or
+username. Those aren't canonical IDs - they could change. But searching for them
+by either of those things is a safe bet as a user, nine times out of ten.
+
+Similarly, you (or your users) might not always have a remote resource's ID
+upfront. You might, however, have something unique enough to discern it from
+other records, like a user-facing ID. A good example is a pull request reference
+on GitHub - using the repo name, owner's username, and pull request ID, you can
+find a pull request.
+
+Of course, that shouldn't be your canonical source, because two of those things
+could change. You could change your username, and you could rename the repo. But
+it's useful to be able to search by those things, right?
+
+Implement `find_by` on your remote_record class, and RemoteRecord will use it.
+If you don't, RemoteRecord will fall back to `remote_where`. This takes the same
+params as other class-level RemoteRecord methods, including an auth proc.

data/lib/remote_record.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'active_support/concern'
+require 'active_support/rescuable'
 require 'remote_record/base'
 require 'remote_record/class_lookup'
 require 'remote_record/config'

data/lib/remote_record/base.rb

@@ -3,14 +3,16 @@
 module RemoteRecord
   # Remote record classes should inherit from this class and define #get.
   class Base
+    include ActiveSupport::Rescuable
+
     def self.default_config
       Config.defaults.merge(remote_record_class: self)
     end
 
-    def initialize(reference, options)
+    def initialize(reference, options = default_config, initial_attrs = {})
       @reference = reference
-      @options = options.presence || default_config
-      @attrs = HashWithIndifferentAccess.new
+      @options = options
+      @attrs = HashWithIndifferentAccess.new(initial_attrs)
     end
 
     def method_missing(method_name, *_args, &_block)
@@ -27,10 +29,22 @@ module RemoteRecord
       raise NotImplementedError.new, '#get should return a hash of data that represents the remote record.'
     end
 
+    def self.all
+      raise NotImplementedError.new, '#all should return an array of hashes of data that represent remote records.'
+    end
+
+    def self.where(_params)
+      raise NotImplementedError.new, '#where should return an array of hashes of data that represent remote records.'
+    end
+
     def fetch
       @attrs.update(get)
     end
 
+    def attrs=(new_attrs)
+      @attrs.update(new_attrs)
+    end
+
     private
 
     def transform(data)

data/lib/remote_record/reference.rb

@@ -9,7 +9,9 @@ module RemoteRecord
   module Reference
     extend ActiveSupport::Concern
 
-    class_methods do
+    class_methods do # rubocop:disable Metrics/BlockLength
+      attr_accessor :fetching
+
       def remote_record_class
         ClassLookup.new(self).remote_record_class(
           remote_record_config.to_h[:remote_record_class]&.to_s
@@ -23,18 +25,90 @@ module RemoteRecord
       def remote_record_config
         Config.new
       end
+
+      def fetching
+        @fetching = true if @fetching.nil?
+        @fetching
+      end
+
+      # Disable fetching for all records initialized in the block.
+      def no_fetching
+        self.fetching = false
+        block_return_value = yield(self)
+        self.fetching = true
+        block_return_value
+      end
+
+      def remote_all(&authz_proc)
+        find_or_initialize_all(remote_record_class.all(&authz_proc))
+      end
+
+      def remote_where(params, &authz_proc)
+        find_or_initialize_all(remote_record_class.where(params, &authz_proc))
+      end
+
+      def remote_find_by(params, &authz_proc)
+        return remote_where(params, &authz_proc).first unless remote_record_class.respond_to?(:find_by)
+
+        resource = remote_record_class.find_by(params, &authz_proc)
+        new(remote_resource_id: resource['id'], initial_attrs: resource)
+      end
+
+      private
+
+      def find_or_initialize_all(remote_resources)
+        no_fetching do
+          pair_remote_resources_with_records(remote_resources) do |unsaved_resources, relation|
+            new_resources = unsaved_resources.map do |resource|
+              new(remote_resource_id: resource['id']).tap { |record| record.attrs = resource }
+            end
+            relation.to_a + new_resources
+          end
+        end
+      end
+
+      def pair_remote_resources_with_records(remote_resources)
+        # get resource ids
+        ids = remote_resource_ids(remote_resources)
+        # get what exists in the database
+        relation = where(remote_resource_id: ids)
+        # for each record, set its attrs
+        relation.map do |record|
+          record.attrs = remote_resources.find do |r|
+            r['id'].to_s == record.remote_resource_id.to_s
+          end
+        end
+        unsaved_resources = resources_without_persisted_references(remote_resources, relation)
+        yield(unsaved_resources, relation)
+      end
+
+      def remote_resource_ids(remote_resources)
+        remote_resources.map { |remote_resource| remote_resource['id'] }
+      end
+
+      def resources_without_persisted_references(remote_resources, relation)
+        remote_resources.reject do |resource|
+          relation.pluck(:remote_resource_id).include? resource['id']
+        end
+      end
     end
 
     # rubocop:disable Metrics/BlockLength
     included do
-      attr_accessor :fetching
+      include ActiveSupport::Rescuable
+      attribute :fetching, :boolean, default: -> { fetching }
+      attr_accessor :initial_attrs
 
       after_initialize do |reference|
-        reference.fetching = true if reference.fetching.nil?
+        reference.fetching = false if reference.initial_attrs.present?
         config = reference.class.remote_record_class.default_config.merge(
           reference.class.remote_record_config.to_h
         )
         reference.instance_variable_set('@remote_record_config', config)
+        reference.instance_variable_set('@instance',
+                                        @remote_record_config.remote_record_class.new(
+                                          self, @remote_record_config, reference.initial_attrs.presence || {}
+                                        ))
         reference.fetch_remote_resource
       end
 
@@ -52,6 +126,8 @@ module RemoteRecord
 
       def fetch_remote_resource
         instance.fetch if fetching
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        rescue_with_handler(e) || raise
       end
 
       def fresh
@@ -59,7 +135,7 @@ module RemoteRecord
         self
       end
 
-      private
+      delegate :attrs=, to: :@instance
 
       def instance
         @instance ||= @remote_record_config.remote_record_class.new(self, @remote_record_config)

data/lib/remote_record/transformers/base.rb

@@ -4,8 +4,11 @@ module RemoteRecord
   module Transformers
     # Base transformer class. Inherit from this and implement `#transform`.
     class Base
-      def initialize(data)
+      def initialize(data, direction = :up)
+        raise ArgumentError, 'The direction should be one of :up or :down.' unless %i[up down].include? direction
+
         @data = data
+        @direction = direction
       end
 
       def transform

data/lib/remote_record/transformers/snake_case.rb

@@ -15,14 +15,19 @@ module RemoteRecord
         when Array
           value.map { |v| convert_hash_keys(v) }
         when Hash
-          Hash[value.map { |k, v| [underscore_key(k), convert_hash_keys(v)] }]
+          Hash[value.map { |k, v| [transform_key(k), convert_hash_keys(v)] }]
         else
           value
         end
       end
 
-      def underscore_key(key)
-        key.to_s.underscore.to_sym
+      def transform_key(key)
+        case @direction
+        when :up
+          key.to_s.underscore.to_sym
+        when :down
+          key.to_s.camelize(:lower).to_sym
+        end
       end
     end
   end

data/lib/remote_record/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: remote_record
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Simon Fish
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-01-12 00:00:00.000000000 Z
+date: 2021-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -39,20 +39,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: database_cleaner
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement