activemodel-datastore 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4d8d2d055a0934bc97f36c9c46a0ef375d30aa4d
+  data.tar.gz: 9640f7bb31c42d4a9c0f7e5d981cd75a20c847a7
+SHA512:
+  metadata.gz: fcf58339c5a1e7afc910fc5c3db2b7334af33d194c38966f0b3b875c9b7cec36e6ce83f5a2514b4e0673b92bc50892a981658e912db6bff5a2ab0891cc0753c4
+  data.tar.gz: 13fb3b0621cd3b906156c0ef4e027c54edd20dc6b1cf98a9d34250961e45fa60ea4e89e34a5892f6892e4f5c8cdeb92138a3d1ec9caffb948a6f1afbc6179844

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+### 0.1.0 / 2017-03-27
+
+Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Agrimatics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,340 @@
+Active Model Datastore
+===================================
+
+Makes the [google-cloud-datastore](https://github.com/GoogleCloudPlatform/google-cloud-ruby/tree/master/google-cloud-datastore) gem compliant with [active_model](https://github.com/rails/rails/tree/master/activemodel) conventions and compatible with your Rails 5 applications. 
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+Why would you want to use Google's NoSQL [Cloud Datastore](https://cloud.google.com/datastore) 
+with Rails? 
+
+When you want a Rails app backed by a managed, massively-scalable datastore solution. Cloud Datastore 
+automatically handles sharding and replication, providing you with a highly available and durable 
+database that scales automatically to handle your applications' load.
+ 
+## Table of contents
+ 
+- [Setup](#setup)
+- [Model Example](#model)
+- [Controller Example](#controller)
+- [Retrieving Entities](#queries)
+- [Example Rails App](#rails)
+- [Development and Test](#development)
+- [Nested Forms](#nested)
+- [Work In Progress](#wip)
+ 
+## <a name="setup"></a>Setup
+ 
+Generate your Rails app without ActiveRecord:
+ 
+```bash
+rails new my_app -O
+```
+
+To install, add this line to your `Gemfile` and run `bundle install`:
+ 
+```ruby
+gem 'activemodel-datastore'
+```
+  
+Google Cloud requires a Project ID and Service Account Credentials to connect to the Datastore API.
+ 
+*Follow the [activation instructions](https://cloud.google.com/datastore/docs/activate) to use the Google Cloud Datastore API.*
+
+Set your project id in an `ENV` variable named `GCLOUD_PROJECT`.
+
+To locate your project ID:
+
+1. Go to the Cloud Platform Console.
+2. From the projects list, select the name of your project.
+3. On the left, click Dashboard. The project name and ID are displayed in the Dashboard.
+
+When running on Google Cloud Platform environments the Service Account credentials will be discovered automatically. 
+When running on other environments (such as AWS or Heroku), the Service Account credentials need to be 
+specified in two additional `ENV` variables named `SERVICE_ACCOUNT_CLIENT_EMAIL` and `SERVICE_ACCOUNT_PRIVATE_KEY`.
+
+```bash
+SERVICE_ACCOUNT_PRIVATE_KEY = -----BEGIN PRIVATE KEY-----\nMIIFfb3...5dmFtABy\n-----END PRIVATE KEY-----\n
+SERVICE_ACCOUNT_CLIENT_EMAIL = web-app@app-name.iam.gserviceaccount.com
+```
+
+On Heroku the `ENV` variables can be set under 'Settings' -> 'Config Variables'.
+ 
+## <a name="model"></a>Model Example
+ 
+Let's start by implementing the model:
+
+```ruby
+class User
+  include ActiveModel::Datastore
+
+  attr_accessor :email, :name, :enabled, :state
+
+  before_validation :set_default_values
+  before_save { puts '** something can happen before save **'}
+  after_save { puts '** something can happen after save **'}
+
+  validates :email, format: { with: /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i }
+  validates :name, presence: true, length: { maximum: 30 }
+
+  def entity_properties
+    %w[email name enabled]
+  end
+
+  def set_default_values
+    default_property_value :enabled, true
+  end
+
+  def format_values
+    format_property_value :role, :integer
+  end
+end
+```
+
+Using `attr_accessor` the attributes of the model are defined. Validations and Callbacks all work 
+as you would expect. However, `entity_properties` is new. Data objects in Cloud Datastore
+are known as entities. Entities are of a kind. An entity has one or more named properties, each
+of which can have one or more values. Think of them like this:
+* 'Kind' (which is your table)
+* 'Entity' (which is the record from the table)
+* 'Property' (which is the attribute of the record)
+
+The `entity_properties` method defines an Array of the properties that belong to the entity in
+cloud datastore. With this approach, Rails deals solely with ActiveModel objects. The objects are
+converted to/from entities as needed during save/query operations.
+
+We have also added the ability to set default property values and type cast the format of values
+for entities.
+
+## <a name="controller"></a>Controller Example
+
+Now on to the controller! A scaffold generated controller works out of the box:
+
+```ruby
+class UsersController < ApplicationController
+  before_action :set_user, only: [:show, :edit, :update, :destroy]
+
+  def index
+    @users = User.all
+  end
+
+  def show
+  end
+
+  def new
+    @user = User.new
+  end
+
+  def edit
+  end
+
+  def create
+    @user = User.new(user_params)
+    respond_to do |format|
+      if @user.save
+        format.html { redirect_to @user, notice: 'User was successfully created.' }
+      else
+        format.html { render :new }
+      end
+    end
+  end
+
+  def update
+    respond_to do |format|
+      if @user.update(user_params)
+        format.html { redirect_to @user, notice: 'User was successfully updated.' }
+      else
+        format.html { render :edit }
+      end
+    end
+  end
+
+  def destroy
+    @user.destroy
+    respond_to do |format|
+      format.html { redirect_to users_url, notice: 'User was successfully destroyed.' }
+    end
+  end
+
+  private
+
+  def set_user
+    @user = User.find(params[:id])
+  end
+
+  def user_params
+    params.require(:user).permit(:email, :name)
+  end
+end
+```
+
+## <a name="queries"></a>Retrieving Entities
+
+Queries entities using the provided options. When a limit option is provided queries up to the limit 
+and returns results with a cursor.
+```ruby
+users = User.all(options = {})
+
+parent = CloudDatastore.dataset.key('Parent', 12345)
+users = User.all(ancestor: parent)
+
+users = User.all(ancestor: parent, where: ['name', '=', 'Bryce'])
+
+users = User.all(where: [['name', '=', 'Ian'], ['enabled', '=', true]])
+
+users, cursor = User.all(limit: 7)
+
+# @param [Hash] options The options to construct the query with.
+#
+# @option options [Google::Cloud::Datastore::Key] :ancestor Filter for inherited results.
+# @option options [String] :cursor Sets the cursor to start the results at.
+# @option options [Integer] :limit Sets a limit to the number of results to be returned.
+# @option options [String] :order Sort the results by property name.
+# @option options [String] :desc_order Sort the results by descending property name.
+# @option options [Array] :select Retrieve only select properties from the matched entities.
+# @option options [Array] :where Adds a property filter of arrays in the format[name, operator, value].
+```
+
+Find entity by id - this can either be a specific id (1), a list of ids (1, 5, 6), or an array of ids ([5, 6, 10]). 
+The parent key is optional.
+```ruby
+user = User.find(1)
+
+parent = CloudDatastore.dataset.key('Parent', 12345)
+user = User.find(1, parent: parent)
+
+users = User.find(1, 2, 3)
+```
+
+Finds the first entity matching the specified condition.
+```ruby
+user = User.find_by(name: 'Joe')
+
+user = User.find_by(name: 'Bryce', ancestor: parent)
+```
+
+## <a name="rails"></a>Example Rails App
+
+There is an example Rails 5 app in the test directory [here](https://github.com/Agrimatics/activemodel-datastore/tree/master/test/support/datastore_example_rails_app) 
+
+## <a name="development"></a>Development and Test
+
+Install the Google Cloud SDK.
+
+    $ curl https://sdk.cloud.google.com | bash
+    
+You can check the version of the SDK and the components installed with:
+
+    $ gcloud components list
+    
+Install the Cloud Datastore Emulator, which provides local emulation of the production Cloud 
+Datastore environment and the gRPC API. However, you'll need to do a small amount of configuration 
+before running the application against the emulator, see [here.](https://cloud.google.com/datastore/docs/tools/datastore-emulator)
+    
+    $ gcloud components install cloud-datastore-emulator 
+    
+Add the following line to your ~/.bash_profile:
+        
+    export PATH="~/google-cloud-sdk/platform/cloud-datastore-emulator:$PATH"
+        
+Restart your shell:
+        
+    exec -l $SHELL    
+
+To create the local development datastore execute the following from the root of the project:
+
+    $ cloud_datastore_emulator create tmp/local_datastore
+    
+To create the local test datastore execute the following from the root of the project:
+    
+    $ cloud_datastore_emulator create tmp/test_datastore
+
+To start the local Cloud Datastore emulator:
+
+    $ ./start-local-datastore.sh
+    
+## <a name="nested"></a>Nested Forms
+
+Adds support for nested attributes to ActiveModel. Heavily inspired by 
+Rails ActiveRecord::NestedAttributes.
+
+Nested attributes allow you to save attributes on associated records along with the parent.
+It's used in conjunction with fields_for to build the nested form elements.
+
+See Rails ActionView::Helpers::FormHelper::fields_for for more info.
+
+*NOTE*: Unlike ActiveRecord, the way that the relationship is modeled between the parent and
+child is not enforced. With NoSQL the relationship could be defined by any attribute, or with
+denormalization exist within the same entity. This library provides a way for the objects to
+be associated yet saved to the datastore in any way that you choose.
+
+You enable nested attributes by defining an `:attr_accessor` on the parent with the pluralized 
+name of the child model.
+
+Nesting also requires that a `<association_name>_attributes=` writer method is defined in your
+parent model. If an object with an association is instantiated with a params hash, and that
+hash has a key for the association, Rails will call the `<association_name>_attributes=`
+method on that object. Within the writer method call `assign_nested_attributes`, passing in
+the association name and attributes.
+
+Let's say we have a parent Recipe with Ingredient children.
+
+Start by defining within the Recipe model:
+* an attr_accessor of `:ingredients`
+* a writer method named `ingredients_attributes=`
+* the `validates_associated` method can be used to validate the nested objects
+
+Example:
+
+```ruby
+class Recipe
+  attr_accessor :ingredients
+  validates :ingredients, presence: true
+  validates_associated :ingredients
+
+  def ingredients_attributes=(attributes)
+    assign_nested_attributes(:ingredients, attributes)
+  end
+end
+```
+
+You may also set a `:reject_if` proc to silently ignore any new record hashes if they fail to
+pass your criteria. For example:
+
+```ruby
+class Recipe
+ def ingredients_attributes=(attributes)
+   reject_proc = proc { |attributes| attributes['name'].blank? }
+   assign_nested_attributes(:ingredients, attributes, reject_if: reject_proc)
+ end
+end
+```
+
+ Alternatively,`:reject_if` also accepts a symbol for using methods:
+
+```ruby
+class Recipe
+  def ingredients_attributes=(attributes)
+    reject_proc = proc { |attributes| attributes['name'].blank? }
+    assign_nested_attributes(:ingredients, attributes, reject_if: reject_recipes)
+  end
+
+  def reject_recipes(attributes)
+    attributes['name'].blank?
+  end
+end
+```
+
+Within the parent model `valid?` will validate the parent and associated children and
+`nested_models` will return the child objects. If the nested form submitted params contained
+a truthy `_destroy` key, the appropriate nested_models will have `marked_for_destruction` set
+to True.
+
+## <a name="wip"></a>Work In Progress
+
+TODO: document datastore eventual consistency and mitigation using ancestor queries and entity groups.
+
+TODO: document indexes.
+
+TODO: document using the datastore emulator to generate the index.yaml.
+
+TODO: document the change tracking implementation.

data/lib/active_model/datastore.rb

@@ -0,0 +1,519 @@
+##
+# = Active Model Datastore
+#
+# Makes the google-cloud-datastore gem compliant with active_model conventions and compatible with
+# your Rails 5+ applications.
+#
+# Let's start by implementing the model:
+#
+#   class User
+#     include ActiveModel::Datastore
+#
+#     attr_accessor :email, :name, :enabled, :state
+#
+#     before_validation :set_default_values
+#     before_save { puts '** something can happen before save **' }
+#     after_save { puts '** something can happen after save **' }
+#
+#     validates :email, format: { with: /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i }
+#     validates :name, presence: true, length: { maximum: 30 }
+#
+#     def entity_properties
+#       %w[email name enabled]
+#     end
+#
+#     def set_default_values
+#       default_property_value :enabled, true
+#     end
+#
+#     def format_values
+#       format_property_value :role, :integer
+#     end
+#   end
+#
+# Using `attr_accessor` the attributes of the model are defined. Validations and Callbacks all work
+# as you would expect. However, `entity_properties` is new. Data objects in Google Cloud Datastore
+# are known as entities. Entities are of a kind. An entity has one or more named properties, each
+# of which can have one or more values. Think of them like this:
+# * 'Kind' (which is your table)
+# * 'Entity' (which is the record from the table)
+# * 'Property' (which is the attribute of the record)
+#
+# The `entity_properties` method defines an Array of the properties that belong to the entity in
+# cloud datastore. With this approach, Rails deals solely with ActiveModel objects. The objects are
+# converted to/from entities as needed during save/query operations.
+#
+# We have also added the ability to set default property values and type cast the format of values
+# for entities.
+#
+# Now on to the controller! A scaffold generated controller works out of the box:
+#
+#   class UsersController < ApplicationController
+#     before_action :set_user, only: [:show, :edit, :update, :destroy]
+#
+#     def index
+#       @users = User.all
+#     end
+#
+#     def show
+#     end
+#
+#     def new
+#       @user = User.new
+#     end
+#
+#     def edit
+#     end
+#
+#     def create
+#       @user = User.new(user_params)
+#       respond_to do |format|
+#         if @user.save
+#           format.html { redirect_to @user, notice: 'User was successfully created.' }
+#         else
+#           format.html { render :new }
+#         end
+#       end
+#     end
+#
+#     def update
+#       respond_to do |format|
+#         if @user.update(user_params)
+#           format.html { redirect_to @user, notice: 'User was successfully updated.' }
+#         else
+#           format.html { render :edit }
+#         end
+#       end
+#     end
+#
+#     def destroy
+#       @user.destroy
+#       respond_to do |format|
+#         format.html { redirect_to users_url, notice: 'User was successfully destroyed.' }
+#       end
+#     end
+#
+#     private
+#
+#     def set_user
+#       @user = User.find(params[:id])
+#     end
+#
+#     def user_params
+#       params.require(:user).permit(:email, :name)
+#     end
+#   end
+#
+module ActiveModel::Datastore
+  extend ActiveSupport::Concern
+  include ActiveModel::Model
+  include ActiveModel::Dirty
+  include ActiveModel::Validations
+  include ActiveModel::Validations::Callbacks
+  include ActiveModel::Datastore::NestedAttr
+  include ActiveModel::Datastore::TrackChanges
+
+  included do
+    private_class_method :query_options, :query_sort, :query_property_filter, :find_all_entities
+    define_model_callbacks :save, :update, :destroy
+    attr_accessor :id
+  end
+
+  def entity_properties
+    []
+  end
+
+  ##
+  # Used by ActiveModel for determining polymorphic routing.
+  #
+  def persisted?
+    id.present?
+  end
+
+  ##
+  # Sets a default value for the property if not currently set.
+  #
+  # Example:
+  #   default_property_value :state, 0
+  #
+  # is equivalent to:
+  #   self.state = state.presence || 0
+  #
+  # Example:
+  #   default_property_value :enabled, false
+  #
+  # is equivalent to:
+  #   self.enabled = false if enabled.nil?
+  #
+  def default_property_value(attr, value)
+    if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      send("#{attr.to_sym}=", value) if send(attr.to_sym).nil?
+    else
+      send("#{attr.to_sym}=", send(attr.to_sym).presence || value)
+    end
+  end
+
+  ##
+  # Converts the type of the property.
+  #
+  # Example:
+  #   format_property_value :weight, :float
+  #
+  # is equivalent to:
+  #   self.weight = weight.to_f if weight.present?
+  #
+  def format_property_value(attr, type)
+    return unless send(attr.to_sym).present?
+    case type.to_sym
+    when :float
+      send("#{attr.to_sym}=", send(attr.to_sym).to_f)
+    when :integer
+      send("#{attr.to_sym}=", send(attr.to_sym).to_i)
+    else
+      raise ArgumentError, 'Supported types are :float, :integer'
+    end
+  end
+
+  ##
+  # Builds the Cloud Datastore entity with attributes from the Model object.
+  #
+  # @return [Entity] The updated Google::Cloud::Datastore::Entity.
+  #
+  def build_entity(parent = nil)
+    entity = CloudDatastore.dataset.entity self.class.name, id
+    entity.key.parent = parent if parent.present?
+    entity_properties.each do |attr|
+      entity[attr] = instance_variable_get("@#{attr}")
+    end
+    entity
+  end
+
+  def save(parent = nil)
+    save_entity(parent)
+  end
+
+  ##
+  # For compatibility with libraries that require the bang method version (example, factory_girl).
+  # If you require a save! method that supports parents (ancestor queries), override this method
+  # in your own code with something like this:
+  #
+  #   def save!
+  #     parent = nil
+  #     if account_id.present?
+  #       parent = CloudDatastore.dataset.key 'Parent' + self.class.name, account_id.to_i
+  #     end
+  #     msg = 'Failed to save the entity'
+  #     save_entity(parent) || raise(ActiveModel::Datastore::EntityNotSavedError, msg)
+  #   end
+  #
+  def save!
+    save_entity || raise(EntityNotSavedError, 'Failed to save the entity')
+  end
+
+  def update(params)
+    assign_attributes(params)
+    return unless valid?
+    run_callbacks :update do
+      entity = build_entity
+      self.class.retry_on_exception? { CloudDatastore.dataset.save entity }
+    end
+  end
+
+  def destroy
+    run_callbacks :destroy do
+      key = CloudDatastore.dataset.key self.class.name, id
+      self.class.retry_on_exception? { CloudDatastore.dataset.delete key }
+    end
+  end
+
+  private
+
+  def save_entity(parent = nil)
+    return unless valid?
+    run_callbacks :save do
+      entity = build_entity(parent)
+      success = self.class.retry_on_exception? { CloudDatastore.dataset.save entity }
+      self.id = entity.key.id if success
+      success
+    end
+  end
+
+  # Methods defined here will be class methods when 'include ActiveModel::Datastore'.
+  module ClassMethods
+    ##
+    # Retrieves an entity by id or name and by an optional parent.
+    #
+    # @param [Integer or String] id_or_name The id or name value of the entity Key.
+    # @param [Google::Cloud::Datastore::Key] parent The parent Key of the entity.
+    #
+    # @return [Entity, nil] a Google::Cloud::Datastore::Entity object or nil.
+    #
+    def find_entity(id_or_name, parent = nil)
+      key = CloudDatastore.dataset.key name, id_or_name
+      key.parent = parent if parent.present?
+      retry_on_exception { CloudDatastore.dataset.find key }
+    end
+
+    ##
+    # Retrieves the entities for the provided ids by key and by an optional parent.
+    # The find_all method returns LookupResults, which is a special case Array with
+    # additional values. LookupResults are returned in batches, and the batch size is
+    # determined by the Datastore API. Batch size is not guaranteed. It will be affected
+    # by the size of the data being returned, and by other forces such as how distributed
+    # and/or consistent the data in Datastore is. Calling `all` on the LookupResults retrieves
+    # all results by repeatedly loading #next until #next? returns false. The `all` method
+    # returns an enumerator unless passed a block. We iterate on the enumerator to return
+    # the model entity objects.
+    #
+    # @param [Integer, String] ids_or_names One or more ids to retrieve.
+    # @param [Google::Cloud::Datastore::Key] parent The parent Key of the entity.
+    #
+    # @return [Array<Entity>] an array of Google::Cloud::Datastore::Entity objects.
+    #
+    def find_entities(*ids_or_names, parent: nil)
+      ids_or_names = ids_or_names.flatten.compact.uniq
+      lookup_results = find_all_entities(ids_or_names, parent)
+      lookup_results.all.collect { |x| x }
+    end
+
+    ##
+    # Queries entities from Cloud Datastore by named kind and using the provided options.
+    # When a limit option is provided queries up to the limit and returns results with a cursor.
+    #
+    # This method may make several API calls until all query results are retrieved. The `run`
+    # method returns a QueryResults object, which is a special case Array with additional values.
+    # QueryResults are returned in batches, and the batch size is determined by the Datastore API.
+    # Batch size is not guaranteed. It will be affected by the size of the data being returned,
+    # and by other forces such as how distributed and/or consistent the data in Datastore is.
+    # Calling `all` on the QueryResults retrieves all results by repeatedly loading #next until
+    # #next? returns false. The `all` method returns an enumerator which from_entities iterates on.
+    #
+    # Be sure to use as narrow a search criteria as possible. Please use with caution.
+    #
+    # @param [Hash] options The options to construct the query with.
+    #
+    # @option options [Google::Cloud::Datastore::Key] :ancestor Filter for inherited results.
+    # @option options [String] :cursor Sets the cursor to start the results at.
+    # @option options [Integer] :limit Sets a limit to the number of results to be returned.
+    # @option options [String] :order Sort the results by property name.
+    # @option options [String] :desc_order Sort the results by descending property name.
+    # @option options [Array] :select Retrieve only select properties from the matched entities.
+    # @option options [Array] :where Adds a property filter of arrays in the format
+    #   [name, operator, value].
+    #
+    # @return [Array<Model>, String] An array of ActiveModel results
+    #
+    # or if options[:limit] was provided:
+    #
+    # @return [Array<Model>, String] An array of ActiveModel results and a cursor that
+    #   can be used to query for additional results.
+    #
+    def all(options = {})
+      next_cursor = nil
+      query = build_query(options)
+      query_results = retry_on_exception { CloudDatastore.dataset.run query }
+      if options[:limit]
+        next_cursor = query_results.cursor if query_results.size == options[:limit]
+        return from_entities(query_results.all), next_cursor
+      end
+      from_entities(query_results.all)
+    end
+
+    ##
+    # Find entity by id - this can either be a specific id (1), a list of ids (1, 5, 6),
+    # or an array of ids ([5, 6, 10]). The parent key is optional.
+    #
+    # @param [Integer] ids One or more ids to retrieve.
+    # @param [Google::Cloud::Datastore::Key] parent The parent key of the entity.
+    #
+    # @return [Model, nil] An ActiveModel object or nil for a single id.
+    # @return [Array<Model>] An array of ActiveModel objects for more than one id.
+    #
+    def find(*ids, parent: nil)
+      expects_array = ids.first.is_a?(Array)
+      ids = ids.flatten.compact.uniq.map(&:to_i)
+
+      case ids.size
+      when 0
+        raise EntityError, "Couldn't find #{name} without an ID"
+      when 1
+        entity = find_entity(ids.first, parent)
+        model_entity = from_entity(entity)
+        expects_array ? [model_entity].compact : model_entity
+      else
+        lookup_results = find_all_entities(ids, parent)
+        from_entities(lookup_results.all)
+      end
+    end
+
+    ##
+    # Finds the first entity matching the specified condition.
+    #
+    # @param [Hash] args In which the key is the property and the value is the value to look for.
+    # @option args [Google::Cloud::Datastore::Key] :ancestor filter for inherited results
+    #
+    # @return [Model, nil] An ActiveModel object or nil.
+    #
+    # @example
+    #   User.find_by(name: 'Joe')
+    #   User.find_by(name: 'Bryce', ancestor: parent)
+    #
+    def find_by(args)
+      query = CloudDatastore.dataset.query name
+      query.ancestor(args[:ancestor]) if args[:ancestor]
+      query.limit(1)
+      query.where(args.keys[0].to_s, '=', args.values[0])
+      query_results = retry_on_exception { CloudDatastore.dataset.run query }
+      from_entity(query_results.first)
+    end
+
+    ##
+    # Translates an Enumerator of Datastore::Entity objects to ActiveModel::Model objects.
+    #
+    # Results provided by the dataset `find_all` or `run query` will be a Dataset::LookupResults or
+    # Dataset::QueryResults object. Invoking `all` on those objects returns an enumerator.
+    #
+    # @param [Enumerator] entities An enumerator representing the datastore entities.
+    #
+    def from_entities(entities)
+      raise ArgumentError, 'Entities param must be an Enumerator' unless entities.is_a? Enumerator
+      entities.map { |entity| from_entity(entity) }
+    end
+
+    ##
+    # Translates between Datastore::Entity objects and ActiveModel::Model objects.
+    #
+    # @param [Entity] entity Entity from Cloud Datastore.
+    # @return [Model] The translated ActiveModel object.
+    #
+    def from_entity(entity)
+      return if entity.nil?
+      model_entity = new
+      model_entity.id = entity.key.id unless entity.key.id.nil?
+      model_entity.id = entity.key.name unless entity.key.name.nil?
+      entity.properties.to_hash.each do |name, value|
+        model_entity.send "#{name}=", value if model_entity.respond_to? "#{name}="
+      end
+      model_entity.reload!
+      model_entity
+    end
+
+    def exclude_from_index(entity, boolean)
+      entity.properties.to_h.keys.each do |value|
+        entity.exclude_from_indexes! value, boolean
+      end
+    end
+
+    ##
+    # Constructs a Google::Cloud::Datastore::Query.
+    #
+    # @param [Hash] options The options to construct the query with.
+    #
+    # @option options [Google::Cloud::Datastore::Key] :ancestor Filter for inherited results.
+    # @option options [String] :cursor Sets the cursor to start the results at.
+    # @option options [Integer] :limit Sets a limit to the number of results to be returned.
+    # @option options [String] :order Sort the results by property name.
+    # @option options [String] :desc_order Sort the results by descending property name.
+    # @option options [Array] :select Retrieve only select properties from the matched entities.
+    # @option options [Array] :where Adds a property filter of arrays in the format
+    #   [name, operator, value].
+    #
+    # @return [Query] A datastore query.
+    #
+    def build_query(options = {})
+      query = CloudDatastore.dataset.query name
+      query_options(query, options)
+    end
+
+    def retry_on_exception?(max_retry_count = 5)
+      retries = 0
+      sleep_time = 0.25
+      begin
+        yield
+      rescue => e
+        return false if retries >= max_retry_count
+        puts "\e[33mRescued exception #{e.message.inspect}, retrying in #{sleep_time}\e[0m"
+        # 0.25, 0.5, 1, 2, and 4 second between retries.
+        sleep sleep_time
+        retries += 1
+        sleep_time *= 2
+        retry
+      end
+    end
+
+    def retry_on_exception(max_retry_count = 5)
+      retries = 0
+      sleep_time = 0.25
+      begin
+        yield
+      rescue => e
+        raise e if retries >= max_retry_count
+        puts "\e[33mRescued exception #{e.message.inspect}, retrying in #{sleep_time}\e[0m"
+        # 0.25, 0.5, 1, 2, and 4 second between retries.
+        sleep sleep_time
+        retries += 1
+        sleep_time *= 2
+        retry
+      end
+    end
+
+    def log_google_cloud_error
+      yield
+    rescue Google::Cloud::Error => e
+      puts "\e[33m[#{e.message.inspect}]\e[0m"
+      raise e
+    end
+
+    # **************** private ****************
+
+    def query_options(query, options)
+      query.ancestor(options[:ancestor]) if options[:ancestor]
+      query.cursor(options[:cursor]) if options[:cursor]
+      query.limit(options[:limit]) if options[:limit]
+      query_sort(query, options)
+      query.select(options[:select]) if options[:select]
+      query_property_filter(query, options)
+    end
+
+    ##
+    # Adds sorting to the results by a property name if included in the options.
+    #
+    def query_sort(query, options)
+      query.order(options[:order]) if options[:order]
+      query.order(options[:desc_order], :desc) if options[:desc_order]
+      query
+    end
+
+    ##
+    # Adds property filters to the query if included in the options.
+    # Accepts individual or nested Arrays:
+    #   [['superseded', '=', false], ['email', '=', 'something']]
+    #
+    def query_property_filter(query, options)
+      if options[:where]
+        opts = options[:where]
+        if opts[0].is_a?(Array)
+          opts.each do |opt|
+            query.where(opt[0], opt[1], opt[2]) unless opt.nil?
+          end
+        else
+          query.where(opts[0], opts[1], opts[2])
+        end
+      end
+      query
+    end
+
+    ##
+    # Finds entities by keys using the provided array items. Results provided by the
+    # dataset `find_all` is a Dataset::LookupResults object.
+    #
+    # @param [Array<Integer>, Array<String>] ids_or_names An array of ids or names.
+    #
+    #
+    def find_all_entities(ids_or_names, parent)
+      keys = ids_or_names.map { |id| CloudDatastore.dataset.key name, id }
+      keys.map { |key| key.parent = parent } if parent.present?
+      retry_on_exception { CloudDatastore.dataset.find_all keys }
+    end
+  end
+end