loqate 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1f1396b79c0115311d766dd1b8fb7f4b0325596d27293d1b1d4af7c0d3d4a29
-  data.tar.gz: e2a275316138017ec971b0a4412e8cc92a872983a523067c33c1ea2c88785de3
+  metadata.gz: fff6b4e7b798fed1a00eb2acfa53ffd3997820f815e1ef780ab46d4e8efbb68b
+  data.tar.gz: d442998133eaafc167db8a823b87703021bbf72c061237cac7a0dbb659d9a271
 SHA512:
-  metadata.gz: abf8817900f777554ded8b558dd43e4f94ebead001fb53c9ac012e8d462f7b4c3926e86a00ea1ac3d5b9230376c19af03931d08c4a0c684bf137369dd8ce332b
-  data.tar.gz: 470d80e084b048173e3ae34d230227308c2855fbb2fa26be93897464ba9c9fd9a0490f0ee9062302107315f4ecb168db50c39e6799af009e492af223b2dad2b2
+  metadata.gz: d57781e89b7743e9c315d97e821cb31d56b0a1b2458cf1d2a640908e9d6e9bd45f8d64f155b63ccd2b704fa1b1b9b71bf700acd7c10ac08afcdf3c1e99e62020
+  data.tar.gz: 794e2d39014cc609fb708989785c74c551ad895bff4565b2f00cc67351353587b2bf3974c91fec54b53e02a7fb44668529c79058318444e8f5bbd00ba1985edd

data/.yardstick.yml

@@ -47,6 +47,7 @@ rules:
       - Loqate::Result::Failure#failure?
       - Loqate::Result#code
       - Loqate::Result#value
+      - Loqate::Result::Failure#error
   ReturnTag:
     enabled: true
     exclude:
@@ -60,9 +61,9 @@ rules:
       - Loqate::AddressGateway#client
       - Loqate::AddressGateway#mapper
       - Loqate::AddressGateway#error_mapper
-      - Loqate::AddressGateway#build_errors_from
-      - Loqate::AddressGateway#build_address_from
-      - Loqate::AddressGateway#build_detailed_addresses_from
+      - Loqate::AddressGateway#build_error_from
+      - Loqate::AddressGateway#build_addresses_from
+      - Loqate::AddressGateway#build_detailed_address_from
       - Loqate::Client#configuration
       - Loqate::Client#authenticate_params
       - Loqate::Client#format_params
@@ -73,6 +74,7 @@ rules:
       - Loqate::Util#underscore
       - Loqate::Error#attributes
       - Loqate::Gateway#client
+      - Loqate::Result::Failure#error
   Summary::Presence:
     enabled: true
     exclude:
@@ -86,9 +88,9 @@ rules:
       - Loqate::AddressGateway#client
       - Loqate::AddressGateway#mapper
       - Loqate::AddressGateway#error_mapper
-      - Loqate::AddressGateway#build_errors_from
-      - Loqate::AddressGateway#build_address_from
-      - Loqate::AddressGateway#build_detailed_addresses_from
+      - Loqate::AddressGateway#build_error_from
+      - Loqate::AddressGateway#build_addresses_from
+      - Loqate::AddressGateway#build_detailed_address_from
       - Loqate::Client#configuration
       - Loqate::Client#authenticate_params
       - Loqate::Client#format_params
@@ -96,6 +98,7 @@ rules:
       - Loqate::DetailedAddress#==
       - Loqate::Error#attributes
       - Loqate::Gateway#client
+      - Loqate::Result::Failure#error
   Summary::Length:
     enabled: false
   Summary::Delimiter:

data/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2018-11-10
+### Changed
+- `address.retrieve` and `address.find` return a single error, not an array with a single item
+- `address.retrieve` returns a single address, not an array of addresses
+- `Loqate::Error` inherits from `StandardError` so that it can be raised as an exception
+- Improved the documentation of `Success` and `Failure`
+
+## Added
+- `find!` to find an address or raise an exception
+- `retrieve!` to retrieve the details of an address or raise an exception
+- Aliased `Failure#value` to `Failure#error`
+
+## Fixed
+- Fixed the documentation of `AddressGateway`
+
 ## [0.2.0] - 2018-10-31
 ### Added
 - VCR and WebMock to record HTTP interactions
@@ -20,4 +35,5 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Initial core functionality
 - Codebase maintenance tools
 
-[0.2.0]: https://github.com/wilsonsilva/memoria/compare/v0.1.0...v0.2.0
+[0.3.0]: https://github.com/wilsonsilva/loqate/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/wilsonsilva/loqate/compare/v0.1.0...v0.2.0

data/README.md

@@ -38,7 +38,41 @@ To get started, initialize an API gateway with [your API key](https://account.lo
 gateway = Loqate::Gateway.new(api_key: '<YOUR_API_KEY>')
 ```
 
-Every call to a gateway method will return a `Loqate::Result` object, which will respond to `success?` and `failure?`.
+### Bang Methods
+
+Most methods have a bang and a non-bang version (e.g. `gateway.address.find` and `gateway.address.find!`).
+The non-bang version will either return a `Loqate::Success` or an `Loqate::Failure`. The bang version will
+either return the desired resource, or it will raise an exception.
+
+#### Example of using non-bang method
+
+```ruby
+result = gateway.address.find(text: 'EC1Y 8AF', country: 'GB', limit: 5)
+
+if result.success?
+  addresses = result.value
+  addresses.first.id # => 'GB|RM|B|8144611'
+else
+  error = result.error
+  puts "Error retrieving the address: #{error.description}. Resolution: #{error.resolution}"
+end
+
+result.failure? # => false
+```
+
+#### Example of using bang method
+
+```ruby
+begin
+  addresses = gateway.address.find!(text: 'EC1Y 8AF', country: 'GB', limit: 5)
+  addresses.first.id # => 'GB|RM|B|8144611'
+rescue Loqate::Error => e
+  puts "Error retrieving the address: #{e.description}. Resolution: #{e.resolution}"
+end
+```
+
+It is recommended that you use the bang methods when you assume that the data is valid and do not expect validations
+to fail. Otherwise, use the non-bang methods.
 
 ### Address API
 
@@ -56,9 +90,6 @@ selection.
 ```ruby
 result = gateway.address.find(text: 'EC1Y 8AF', country: 'GB', limit: 5)
 
-result.success? # => true
-result.failure? # => false
-
 addresses = result.value
 addresses.first.id # => 'GB|RM|B|8144611'
 ```
@@ -68,15 +99,10 @@ addresses.first.id # => 'GB|RM|B|8144611'
 ```ruby
 result = gateway.address.retrieve(id: 'GB|RM|B|8144611')
 
-result.success? # => true
-result.failure? # => false
-
-addresses = result.value
-address = addresses.first
-
-address.city        # 'London' 
-address.line1       # '148 Warner Road'
-address.postal_code # 'E17 7EA'
+address = result.value
+address.city           # 'London' 
+address.line1          # '148 Warner Road'
+address.postal_code    # 'E17 7EA'
 ```
 
 ## Development

data/ROADMAP.md

@@ -7,6 +7,7 @@
 - [ ] Logging
 - [x] Domain error handling
 - [x] Configuration
+- [ ] Unwrap request results
 - [ ] Validate request parameters
 - [ ] API/Service versioning
 - [ ] Integration with RSpec

data/lib/loqate/address_gateway.rb

@@ -46,33 +46,79 @@ module Loqate
     # @example Retrieving an address in the UK
     #   address = address_gateway.find(countries: 'GB', text: 'Scrubs Lane')
     #
-    # @return [Array<Address>] A list of addresses
+    # @return [Result] A result wrapping a list of addresses
     #
     def find(options)
       response = client.get(FIND_ENDPOINT, options)
 
-      response.errors? && build_errors_from(response.items) || build_address_from(response.items)
+      response.errors? && build_error_from(response.items.first) || build_addresses_from(response.items)
     end
 
     # Returns the full address details based on the id.
     #
     # @param [Hash] options The options to retrieve the address.
     # @option options [String] :id The Id from a Find method to retrieve the details for.
-    # @option options [String] :field_1_format a.
-    # @option options [String] :field_2_format b.
-    # @option options [String] :field_3_format c.
-    # @option options [String] :field_4_format d.
-    # @option options [String] :field_5_format e.
+    # @option options [String] :field_1_format Format of a custom address field.
+    # @option options [String] :field_2_format Format of a custom address field.
+    # @option options [String] :field_3_format Format of a custom address field.
+    # @option options [String] :field_4_format Format of a custom address field.
+    # @option options [String] :field_5_format Format of a custom address field.
     #
     # @example Retrieving the details of an address
     #   detailed_address = gateway.retrieve(id: 'GB|RM|ENG|6RB-NW10')
     #
-    # @return [Array<DetailedAddress>] A list of detailed addresses
+    # @return [Result] A result wrapping a detailed address
     #
     def retrieve(options)
       response = client.get(RETRIEVE_ENDPOINT, options)
 
-      response.errors? && build_errors_from(response.items) || build_detailed_addresses_from(response.items)
+      response.errors? && build_error_from(response.items.first) || build_detailed_address_from(response.items.first)
+    end
+
+    # Find addresses and places.
+    #
+    # @param [Hash] options The options to find an address or a list of addresses.
+    # @option options [String] :text The search text to find. Ideally a postcode or the start of the address.
+    # @option options [String] countries A comma separated list of ISO 2 or 3 character country codes to limit
+    #   the search within.
+    # @option options [String] origin A starting location for the search. This can be the name or ISO 2 or 3 character
+    #   code of a country, WGS84 coordinates (comma separated) or IP address to search from.
+    # @option options [String] container A container for the search. This should only be another Id previously returned
+    #   from this service when the Type of the result was not 'Address'.
+    # @option options [Integer] limit The maximum number of results to return.
+    # @option options [String] language The preferred language for results. This should be a 2 or 4 character language
+    #   code e.g. (en, fr, en-gb, en-us etc).
+    #
+    # @example Retrieving addresses in the UK
+    #   addresses = address_gateway.find!(countries: 'GB', text: 'Scrubs Lane')
+    #
+    # @raise [Error] If the result is not a success
+    #
+    # @return [Array<Address>] A list of addresses
+    #
+    def find!(options)
+      unwrap_result_or_raise { find(options) }
+    end
+
+    # Returns the full address details based on the id.
+    #
+    # @param [Hash] options The options to retrieve the address.
+    # @option options [String] :id The Id from a Find method to retrieve the details for.
+    # @option options [String] :field_1_format Format of a custom address field.
+    # @option options [String] :field_2_format Format of a custom address field.
+    # @option options [String] :field_3_format Format of a custom address field.
+    # @option options [String] :field_4_format Format of a custom address field.
+    # @option options [String] :field_5_format Format of a custom address field.
+    #
+    # @example Retrieving the details of an address
+    #   detailed_address = gateway.retrieve!(id: 'GB|RM|ENG|6RB-NW10')
+    #
+    # @raise [Error] If the result is not a success
+    #
+    # @return [DetailedAddress] A detailed address
+    #
+    def retrieve!(options)
+      unwrap_result_or_raise { retrieve(options) }
     end
 
     private
@@ -81,20 +127,20 @@ module Loqate
     attr_reader :client, :mapper, :error_mapper
 
     # @api private
-    def build_errors_from(items)
-      errors = error_mapper.map(items)
-      Failure(errors)
+    def build_error_from(item)
+      error = error_mapper.map_one(item)
+      Failure(error)
     end
 
     # @api private
-    def build_address_from(items)
+    def build_addresses_from(items)
       address = mapper.map(items, Address)
       Success(address)
     end
 
     # @api private
-    def build_detailed_addresses_from(items)
-      detailed_address = mapper.map(items, DetailedAddress)
+    def build_detailed_address_from(item)
+      detailed_address = mapper.map_one(item, DetailedAddress)
       Success(detailed_address)
     end
   end

data/lib/loqate/error.rb

@@ -1,6 +1,6 @@
 module Loqate
   # Generic error returned from an API call
-  class Error
+  class Error < StandardError
     # Unique identifier for the error
     #
     # @return [Integer]
@@ -33,6 +33,8 @@ module Loqate
     # @param [String] resolution How to solve the error
     #
     def initialize(id:, description:, cause:, resolution:)
+      super(description)
+
       @id = id
       @cause = cause
       @resolution = resolution

data/lib/loqate/mappers/error_mapper.rb

@@ -14,12 +14,18 @@ module Loqate
       # @return [Array<Error>] An array of errors
       #
       def map(items)
-        items.map do |item|
-          attributes = item.transform_keys { |attribute| Util.underscore(attribute) }
-          attributes[:id] = attributes.delete(:error).to_i
+        items.map { |item| map_one(item) }
+      end
+
+      # Creates an error from an API response
+      #
+      # @return [Error] A concrete instance of Error
+      #
+      def map_one(item)
+        attributes = item.transform_keys { |attribute| Util.underscore(attribute) }
+        attributes[:id] = attributes.delete(:error).to_i
 
-          Loqate::Error.new(attributes)
-        end
+        Loqate::Error.new(attributes)
       end
     end
   end

data/lib/loqate/mappers/generic_mapper.rb

@@ -15,10 +15,19 @@ module Loqate
       # @return An array of objects of the given class
       #
       def map(items, object_class)
-        items.map do |item|
-          attributes = item.transform_keys { |attribute| Util.underscore(attribute) }
-          object_class.new(attributes)
-        end
+        items.map { |item| map_one(item, object_class) }
+      end
+
+      # Creates a single object from an API response. The object will be an instance of +object_class+.
+      #
+      # @param [Class] object_class Class of the final object
+      # @param [Hash] item Attributes to instantiate the final object
+      #
+      # @return An object of the given class
+      #
+      def map_one(item, object_class)
+        attributes = item.transform_keys { |attribute| Util.underscore(attribute) }
+        object_class.new(attributes)
       end
     end
   end

data/lib/loqate/result.rb

@@ -31,7 +31,7 @@ module Loqate
     class Success < Result
       # Always true
       #
-      # @return [Boolean]
+      # @return [TrueClass]
       #
       def success?
         true
@@ -39,7 +39,7 @@ module Loqate
 
       # Always false
       #
-      # @return [Boolean]
+      # @return [FalseClass]
       #
       def failure?
         false
@@ -50,7 +50,7 @@ module Loqate
     class Failure < Result
       # Always false
       #
-      # @return [Boolean]
+      # @return [FalseClass]
       #
       def success?
         false
@@ -58,11 +58,13 @@ module Loqate
 
       # Always true
       #
-      # @return [Boolean]
+      # @return [TrueClass]
       #
       def failure?
         true
       end
+
+      alias error value
     end
 
     # Utility methods to conveniently return +Success+ or +Failure+ results.
@@ -97,6 +99,43 @@ module Loqate
       def Failure(value, code: nil)
         Failure.new(value: value, code: code)
       end
+
+      # Unwraps a Result object. Returns the unwrapped value if the result is successful or raise
+      # an exception otherwise.
+      #
+      # @example When the given block returns a success
+      #   class Action
+      #     include Loqate::Result::Mixin
+      #
+      #     def call
+      #       Success('the value')
+      #     end
+      #   end
+      #
+      #   operation.unwrap_result_or_raise { call } # => 'the value'
+      #
+      # @example When the given block returns a failure
+      #   class Action
+      #     include Loqate::Result::Mixin
+      #
+      #     def call
+      #       Failure(StandardError.new)
+      #     end
+      #   end
+      #
+      #   operation.unwrap_result_or_raise { call } # => raises StandardError
+      #
+      # @raise [Object] If the result is not a success.
+      #
+      # @return [Object] The unwrapped object.
+      #
+      def unwrap_result_or_raise
+        result = yield
+
+        raise result.error if result.failure?
+
+        result.value
+      end
     end
   end
 end

data/lib/loqate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Loqate
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: loqate
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Wilson Silva
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-31 00:00:00.000000000 Z
+date: 2018-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http