active_force 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6de1df55a3215360cd78f76fa3f55d05ca9e8f9f9603d5ab4257667a5fd961a5
-  data.tar.gz: e85f2ae5bd075070adc261ec3a6d566eea2f9cf19c4d4423fa1b859cafdabcc4
+  metadata.gz: 1647fdc453090811c384514ae857c83b686dc966e2af5e47af3a6dc67e42059d
+  data.tar.gz: 515a98a5715c24359739d76730758b728a9cbf1b8c0cbf2b3c1bb5a355a21c9e
 SHA512:
-  metadata.gz: 5268395d3fcc92a705b909026b6de6deb36b4c6a9b622d0ee63307ed08d16142e96abca2bafb902c55fca02955d75c34aa3348eb84fc14c47784d3548b492f89
-  data.tar.gz: 3ea676afd55bb62601e211250c487a86e7902f1dee1f8b6fdc41410b903ce2052e5a4f893cc869798ba3bf5c1270aad2c84ea21c24dd137909e494e7c0564ff9
+  metadata.gz: 48115b7a0df0201a24f477ba2f658e692824337a78c0d288afd3c056b42fccaaf065e1e3ab296fa16bda1f2f2eaf82ff1322adcea6d9d6a9f82c2318cea15d98
+  data.tar.gz: a7b6dacca6775374b089cc9022462c470d8103d63792c7e7668ccd3e082446b0429a2d54d0e3392694c0e25ea25139916d11bc9f0080659faea6e7eaa0e41541

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.idea

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Not released
 
+## 0.20.0
+
+- Change `.first` to not query the API if records have already been retrieved (https://github.com/Beyond-Finance/active_force/pull/73)
+- Bugfix: Transform NULL values for SF Bulk API, which expects "#N/A" (https://github.com/Beyond-Finance/active_force/pull/74)
+
+## 0.19.0
+
+- Bulk API methods. (https://github.com/Beyond-Finance/active_force/pull/65)
+
 ## 0.18.0
 
 - Fix eager loading of scoped associations. (https://github.com/Beyond-Finance/active_force/pull/67)

data/README.md

@@ -194,7 +194,7 @@ Comment.includes(:post)
 
 It is possible to eager load multi level associations
 
-In order to utilize multi level eager loads, the API version should be set to 58.0 or higher when instantiating a Restforce client 
+In order to utilize multi level eager loads, the API version should be set to 58.0 or higher when instantiating a Restforce client
 
 ```ruby
 Restforce.new({api_version: '58.0'})
@@ -212,8 +212,8 @@ Comment.includes({post: {owner: :account}})
 Summing the values of a column:
 ```ruby
 Transaction.where(offer_id: 'ABD832024').sum(:amount)
-#=> This will query "SELECT SUM(Amount__c) 
-#                    FROM Transaction__c 
+#=> This will query "SELECT SUM(Amount__c)
+#                    FROM Transaction__c
 #                    WHERE offer_id = 'ABD832024'"
 ```
 
@@ -249,6 +249,22 @@ accounts = Account.where(web_enabled: 1).limit(2)
 with data from another API, and will only query the other API once.
 ```
 
+### Bulk Jobs
+
+For more information about usage and limits of the Salesforce Bulk API see the [docs][4].
+
+Convenience class methods have been added to `ActiveForce::SObject` to make it possible to utilize the Salesforce Bulk API v2.0.
+The methods are: `bulk_insert_all`, `bulk_update_all`, & `bulk_delete_all`.  They all expect input as an Array of attributes as a Hash:
+```ruby
+[
+  { id: '11111111', attribute1: 'value1', attribute2: 'value2'},
+  { id: '22222222', attribute1: 'value3', attribute2: 'value4'},
+]
+```
+The attributes will be mapped back to what's expected on the SF side automatically. The response is a `ActiveForce::Bulk::JobResult` object
+which can access `successful` & `failed` results, has some `stats`, and the original `job` object that was used to create and process the
+Bulk job.
+
 ### Model generator
 
 When using rails, you can generate a model with all the fields you have on your SFDC table by running:
@@ -268,4 +284,5 @@ When using rails, you can generate a model with all the fields you have on your
  [1]: http://www.salesforce.com
  [2]: https://github.com/ejholmes/restforce
  [3]: https://github.com/bkeepers/dotenv
+ [4]: https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_0.htm
 

data/lib/active_force/bulk/job.rb

@@ -0,0 +1,136 @@
+require 'active_force/bulk/job_result'
+
+module ActiveForce
+  module Bulk
+    class Job
+      attr_reader :operation, :records, :state, :object, :content_url
+      attr_accessor :id
+
+      STATES = {
+        Open: 'Open',
+        UploadComplete: 'UploadComplete',
+        InProgress: 'InProgress',
+        JobComplete: 'JobComplete',
+        Failed: 'Failed',
+        Aborted: 'Aborted',
+        Deleted: 'Deleted'
+      }.freeze
+
+      OPERATIONS = %i[insert delete hardDelete update upsert]
+
+      def initialize(operation:, object:, id: nil, records: nil)
+        @operation = operation.to_sym
+        @object = object
+        @id = id
+        @records = records
+        @state = nil
+        @content_url = nil
+        initialize_state_methods
+      end
+
+      def create
+        request_body = default_job_options.merge(operation: operation, object: object)
+        response = client.post("#{ingest_path}/", request_body)
+        update_attributes_from(response)
+        response
+      end
+
+      def upload
+        headers = {"Content-Type": 'text/csv'}
+        response = client.put(content_url, records.to_csv, headers)
+        response
+      end
+
+      def result
+        ActiveForce::Bulk::JobResult.new(job: self)
+      end
+
+      def self.run(...)
+        job = new(...)
+        job.create
+        job.upload
+        job.run
+        job
+      end
+
+      def failed_results
+        client.get("#{ingest_path}/#{id}/failedResults/")
+      end
+
+      def successful_results
+        client.get("#{ingest_path}/#{id}/successfulResults/")
+      end
+
+      def info
+        response = client.get("#{ingest_path}/#{id}")
+        update_attributes_from(response)
+        response
+      end
+
+      def run
+        change_state(STATES[:UploadComplete])
+      end
+
+      def abort
+        change_state(STATES[:Aborted])
+      end
+
+      def delete
+        response = client.delete("#{ingest_path}/#{id}")
+        response
+      end
+
+      def finished?
+        job_complete? || failed? || aborted?
+      end
+
+      private
+      attr_writer :state, :object, :operation, :content_url
+
+
+      def ingest_path
+        "/services/data/v#{client.options[:api_version]}/jobs/ingest"
+      end
+
+      def client
+        @client ||= ActiveForce.sfdc_client
+      end
+
+      def default_job_options
+        {
+          columnDelimiter: 'COMMA',
+          contentType: 'CSV',
+          lineEnding: 'LF',
+        }
+      end
+
+      def change_state(value)
+        request_body = {state: value}
+        headers = {"Content-Type": "application/json"}
+        response = client.patch("#{ingest_path}/#{id}", request_body, headers)
+        update_attributes_from(response)
+        response
+      end
+
+      def update_attributes_from(response)
+        return unless response.body.present?
+
+        %i[id state object operation contentUrl].each do |attr|
+          self.send("#{attr.to_s.underscore}=", response.body[attr.to_s]) if response.body[attr.to_s].present?
+        end
+      end
+
+      # Defines question methods for various states of the job, e.g. #open?, #in_progress?, etc.
+      def initialize_state_methods
+        STATES.values.each do |state|
+          state_method = <<-STATE_METHOD
+            def #{state.to_s.underscore}?
+              @state == '#{state}'
+            end
+          STATE_METHOD
+          self.class_eval(state_method)
+        end
+      end
+    end
+  end
+end

data/lib/active_force/bulk/job_result.rb

@@ -0,0 +1,48 @@
+module ActiveForce
+  module Bulk
+    class JobResult
+      attr_reader :job, :failed, :successful, :stats, :errors
+
+      def initialize(job:)
+        @job = job
+        @stats = result_from_job_info
+        @failed = failed_results
+        @successful = successful_results
+        @errors = errors_from_failed_results
+      end
+
+      def success?
+        failed.blank? && successful.present?
+      end
+
+      private
+      attr_writer :errors, :failed, :successful
+
+      def errors_from_failed_results
+        return [] if @stats[:number_records_failed].zero? || self.failed.blank?
+
+        self.errors = self.failed.pluck('sf__Error').uniq
+      end
+
+      def failed_results
+        return [] if @stats[:number_records_failed].zero?
+
+        response = job.failed_results
+        self.failed = CSV.parse(response.body, headers: true).map(&:to_h)
+      end
+
+      def successful_results
+        response = job.successful_results
+        self.successful = CSV.parse(response.body, headers: true).map(&:to_h)
+      end
+
+      def job_info
+        job.info
+      end
+
+      def result_from_job_info
+        job_info&.body.slice('numberRecordsProcessed', 'numberRecordsFailed', 'totalProcessingTime').transform_keys { |k| k.to_s.underscore.to_sym }
+      end
+    end
+  end
+end

data/lib/active_force/bulk/records.rb

@@ -0,0 +1,42 @@
+require 'csv'
+
+module ActiveForce
+  module Bulk
+    class Records
+      NULL_VALUE = '#N/A'.freeze
+
+      attr_reader :headers, :data
+      def initialize(headers:, data:)
+        @headers = headers
+        @data = data
+      end
+
+      def to_csv
+        CSV.generate(String.new, headers: headers, write_headers: true) do |csv|
+          data.each { |row| csv << row }
+        end
+      end
+
+      def self.parse_from_attributes(records)
+        # Sorting ensures that the headers line up with the values for the CSV
+        headers = records.first.keys.sort.map(&:to_s)
+        data = records.map do |r|
+           r.transform_values { |v| transform_value_for_sf(v) }.sort.pluck(-1)
+        end
+        new(headers: headers, data: data)
+      end
+
+      # SF expects a special value for setting a column to be NULL.
+      def self.transform_value_for_sf(value)
+        case value
+        when NilClass
+          NULL_VALUE
+        when Time
+          value.iso8601
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/active_force/bulk.rb

@@ -0,0 +1,47 @@
+require 'active_force/bulk/job'
+require 'active_force/bulk/records'
+
+module ActiveForce
+  module Bulk
+    class TimeoutError < Timeout::Error; end
+    TIMEOUT_MESSAGE = 'Bulk job execution expired based on timeout of %{timeout} seconds'.freeze
+
+    def bulk_insert_all(attributes, options={})
+      run_bulk_job(:insert, attributes, options)
+    end
+
+    def bulk_update_all(attributes, options={})
+      run_bulk_job(:update, attributes, options)
+    end
+
+    def bulk_delete_all(attributes, options={})
+      run_bulk_job(:delete, attributes, options)
+    end
+
+    private
+
+    def default_options
+      {
+        timeout: 30,
+        sleep: 0.02 # short sleep so we can end our poll loop more quickly
+      }
+    end
+
+    def run_bulk_job(operation, attributes, options)
+      runtime_options = default_options.merge(options)
+      records = Records.parse_from_attributes(translate_to_sf(attributes))
+      job = Job.run(operation: operation, object: self.table_name, records: records)
+      Timeout.timeout(runtime_options[:timeout], ActiveForce::Bulk::TimeoutError, TIMEOUT_MESSAGE % runtime_options) do
+        until job.finished? do
+          job.info
+          sleep(runtime_options[:sleep])
+        end
+      end
+      job.result
+    end
+
+    def translate_to_sf(attributes)
+      attributes.map{ |r| self.mapping.translate_to_sf(r) }
+    end
+  end
+end

data/lib/active_force/query.rb

@@ -78,7 +78,15 @@ module ActiveForce
     end
 
     def first
-      limit 1
+      if @records
+        clone_and_set_instance_variables(
+          size: 1,
+          records: [@records.first],
+          decorated_records: [@decorated_records&.first]
+        )
+      else
+        limit(1)
+      end
     end
 
     def last(limit = 1)
@@ -126,9 +134,9 @@ module ActiveForce
 
       def clone_and_set_instance_variables instance_variable_hash={}
         clone = self.clone
-        clone.instance_variable_set(:@decorated_records, nil)
-        clone.instance_variable_set(:@records, nil)
-        instance_variable_hash.each { |k,v| clone.instance_variable_set("@#{k.to_s}", v) }
+        { decorated_records: nil, records: nil }
+          .merge(instance_variable_hash)
+          .each { |k,v| clone.instance_variable_set("@#{k.to_s}", v) }
         clone
       end
   end

data/lib/active_force/sobject.rb

@@ -1,6 +1,7 @@
 require 'active_model'
 require 'active_force/active_query'
 require 'active_force/association'
+require 'active_force/bulk'
 require 'active_force/mapping'
 require 'yaml'
 require 'forwardable'
@@ -19,6 +20,7 @@ module ActiveForce
     extend ActiveModel::Callbacks
     include ActiveModel::Serializers::JSON
     extend ActiveForce::Association
+    extend ActiveForce::Bulk
 
 
     define_model_callbacks :build, :create, :update, :save, :destroy

data/lib/active_force/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveForce
-  VERSION = '0.18.0'
+  VERSION = '0.20.0'
 end

data/lib/active_force.rb

@@ -3,6 +3,7 @@ require 'active_model/type/salesforce/percent'
 require 'active_force/version'
 require 'active_force/sobject'
 require 'active_force/query'
+require 'active_force/bulk'
 
 module ActiveForce
 

data/spec/active_force/bulk/job_result_spec.rb

@@ -0,0 +1,116 @@
+require 'spec_helper'
+
+describe ActiveForce::Bulk::JobResult do
+  subject { described_class.new(job: job)}
+  let(:job) { instance_double(ActiveForce::Bulk::Job)}
+
+  let(:failed_results_response) do
+    Faraday::Response.new(status: 200, response_body: "\"sf__Id\",\"sf__Error\"\n\"45678\",\"Something failed.\"")
+  end
+
+  let(:successful_results_response) do
+    Faraday::Response.new(status: 200, response_body: "\"sf__Id\",\"sf__Error\"\n\"12354\",\"false\"\n")
+  end
+
+  let(:successful_info) do
+    {"id"=>"22222222222222",
+      "operation"=>"update",
+      "object"=>"FooBar__c",
+      "createdById"=>"11111111111111111",
+      "createdDate"=>"2023-09-22T16:39:09.000+0000",
+      "systemModstamp"=>"2023-09-22T16:39:13.000+0000",
+      "state"=>"JobComplete",
+      "concurrencyMode"=>"Parallel",
+      "contentType"=>"CSV",
+      "apiVersion"=>58.0,
+      "jobType"=>"V2Ingest",
+      "lineEnding"=>"LF",
+      "columnDelimiter"=>"COMMA",
+      "numberRecordsProcessed"=>1,
+      "numberRecordsFailed"=>0,
+      "retries"=>0,
+      "totalProcessingTime"=>713,
+      "apiActiveProcessingTime"=>323,
+      "apexProcessingTime"=>3}
+  end
+
+  let(:failed_info) do
+    {"id"=>"33333333333333",
+      "operation"=>"update",
+      "object"=>"FooBar__c",
+      "createdById"=>"11111111111111111",
+      "createdDate"=>"2023-09-22T16:39:09.000+0000",
+      "systemModstamp"=>"2023-09-22T16:39:13.000+0000",
+      "state"=>"JobComplete",
+      "concurrencyMode"=>"Parallel",
+      "contentType"=>"CSV",
+      "apiVersion"=>58.0,
+      "jobType"=>"V2Ingest",
+      "lineEnding"=>"LF",
+      "columnDelimiter"=>"COMMA",
+      "numberRecordsProcessed"=>1,
+      "numberRecordsFailed"=>1,
+      "retries"=>0,
+      "totalProcessingTime"=>713,
+      "apiActiveProcessingTime"=>323,
+      "apexProcessingTime"=>3}
+  end
+
+  let(:successful_job_info_response) do
+    Faraday::Response.new(status: 200, response_body: successful_info)
+  end
+
+  let(:failed_job_info_response) do
+    Faraday::Response.new(status: 200, response_body: failed_info)
+  end
+
+  before do
+    allow(job).to receive(:failed_results).and_return(failed_results_response)
+    allow(job).to receive(:successful_results).and_return(successful_results_response)
+    allow(job).to receive(:info).and_return(successful_job_info_response)
+  end
+
+  describe '::new' do
+    it 'uses the passed in job object to pull job info' do
+      expect(subject.stats[:total_processing_time]).to eq successful_info['totalProcessingTime']
+      expect(subject.stats[:number_records_processed]).to eq successful_info['numberRecordsProcessed']
+      expect(subject.stats[:number_records_failed]).to eq successful_info['numberRecordsFailed']
+      expect(subject.failed).to be_empty
+      expect(subject.successful.size).to eq 1
+    end
+  end
+
+  describe '#success?' do
+    context 'when no failed results' do
+      it 'returns true' do
+        expect(subject.success?).to be true
+      end
+    end
+    context 'when there are failed results' do
+      before do
+        allow(job).to receive(:info).and_return(failed_job_info_response)
+      end
+      it 'returns false' do
+        expect(subject.success?).to be false
+      end
+    end
+  end
+
+  describe '#errors' do
+    context 'when there are failed results' do
+      before do
+        allow(job).to receive(:info).and_return(failed_job_info_response)
+      end
+      it 'returns an array of errors' do
+        expect(subject.errors).to eq ['Something failed.']
+      end
+    end
+
+    context 'when there are no failed results' do
+      it 'returns an empty array' do
+        expect(subject.errors).to eq []
+      end
+    end
+  end
+end
+

data/spec/active_force/bulk/job_spec.rb

@@ -0,0 +1,113 @@
+require 'spec_helper'
+
+describe ActiveForce::Bulk::Job do
+  subject { described_class.new(**args)}
+  let(:args) { { operation: operation, object: object, id: id, records: records } }
+  let(:operation) { described_class::OPERATIONS.sample }
+  let(:object) { 'Whizbang__c' }
+  let(:id) { nil }
+  let(:records) { instance_double(ActiveForce::Bulk::Records) }
+  let(:sfdc_client) { spy(ActiveForce.sfdc_client.class)}
+  let(:state) { 'Open' }
+  let(:api_version) { '58.0' }
+  let(:ingest_url) { "/services/data/v#{api_version}/jobs/ingest" }
+
+  before do
+    allow(ActiveForce).to receive(:sfdc_client).and_return(sfdc_client)
+    allow(sfdc_client).to receive(:options).and_return({api_version: api_version})
+    allow(records).to receive(:to_csv)
+  end
+
+  describe '#finished?' do
+    let(:finished_state) { described_class::STATES.slice(:JobComplete, :Failed, :Aborted).values.sample }
+    let(:unfinished_state) { described_class::STATES.except(:JobComplete, :Failed, :Aborted).values.sample }
+
+    context 'when job is in one of the finished states' do
+      it 'returns true' do
+        job = subject
+        job.instance_variable_set(:@state, finished_state)
+        expect(job.finished?).to be true
+      end
+    end
+
+    context 'when job is NOT in one of the finished states' do
+      it 'returns false' do
+        job = subject
+        job.instance_variable_set(:@state, unfinished_state)
+        expect(job.finished?).to be false
+      end
+    end
+  end
+
+  describe '::run' do
+    let(:job) { spy(described_class)}
+
+    before do
+      allow(described_class).to receive(:new).and_return(job)
+    end
+
+    it 'creates, uploads, and runs the job via the SF API' do
+      described_class.run(**args)
+      expect(job).to have_received(:create)
+      expect(job).to have_received(:upload)
+      expect(job).to have_received(:run)
+    end
+  end
+
+  describe '#run' do
+    it 'PATCHs the job state to SF API to run the job' do
+      subject.run
+      expect(sfdc_client).to have_received(:patch).with("#{ingest_url}/#{id}", {state: described_class::STATES[:UploadComplete]}, anything)
+    end
+  end
+
+  describe '#abort' do
+    it 'PATCHs the job state to SF API to abort the job' do
+      subject.abort
+      expect(sfdc_client).to have_received(:patch).with("#{ingest_url}/#{id}", {state: described_class::STATES[:Aborted]}, anything)
+    end
+  end
+
+  describe '#delete' do
+    it 'DELETEs the job from SF API' do
+      subject.delete
+      expect(sfdc_client).to have_received(:delete).with("#{ingest_url}/#{id}")
+    end
+  end
+
+  describe '#failed_results' do
+    it 'GETs job info from SF API' do
+      subject.failed_results
+      expect(sfdc_client).to have_received(:get).with("#{ingest_url}/#{id}/failedResults/")
+    end
+  end
+
+  describe '#successful_results' do
+    it 'GETs successful results from SF API' do
+      subject.successful_results
+      expect(sfdc_client).to have_received(:get).with("#{ingest_url}/#{id}/successfulResults/")
+    end
+  end
+
+  describe '#info' do
+    it 'GETs job info from SF API' do
+      subject.info
+      expect(sfdc_client).to have_received(:get).with("#{ingest_url}/#{id}")
+    end
+  end
+
+  describe '#upload' do
+    it 'PUTs CSV to SF API to upload records to job' do
+      subject.upload
+      expect(sfdc_client).to have_received(:put).with(subject.content_url, anything, hash_including("Content-Type": 'text/csv'))
+    end
+  end
+
+  describe '#create' do
+    it 'POSTs to SF API to create a job' do
+      subject.create
+      expect(sfdc_client).to have_received(:post).with("#{ingest_url}/", hash_including(operation: operation, object: object))
+    end
+  end
+end
+

data/spec/active_force/bulk/record_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe ActiveForce::Bulk::Records do
+  subject { described_class.new(headers: headers, data: data)}
+  let(:headers) { %w[header1 header2] }
+  let(:data) do
+    [
+      %w[value1 value2],
+      %w[value3 value4],
+    ]
+  end
+
+  describe '#to_csv' do
+    it 'returns CSV with headers' do
+      expect(subject.to_csv).to eq "header1,header2\nvalue1,value2\nvalue3,value4\n"
+    end
+  end
+
+  describe '::parse_from_attributes' do
+    subject { described_class.parse_from_attributes(attributes) }
+    let(:attributes) do
+      [
+        { header1: 'value1', header2: 'value2'},
+        { header1: 'value3', header2: 'value4'},
+      ]
+    end
+    it 'parses array of hash attributes into Records object with headers and data' do
+      records = subject
+      expect(records).to be_a described_class
+      expect(records.headers).to eq headers
+      expect(records.data).to eq data
+    end
+
+    context 'when there are NULL values' do
+      let(:attributes) do
+        [
+          { header1: nil, header2: 'value2'},
+          { header1: 'value3', header2: nil},
+        ]
+      end
+      let(:data) do
+        [
+          %w[#N/A value2],
+          %w[value3 #N/A],
+        ]
+      end
+
+      it 'substitutes the expected SF value for NULL' do
+        records = subject
+        expect(records.data).to eq data
+      end
+    end
+  end
+end

data/spec/active_force/bulk_spec.rb

@@ -0,0 +1,110 @@
+require 'spec_helper'
+
+# Set up a new SObject to test the mixin.
+class FooBarSObject < ActiveForce::SObject
+  field :id, from: 'Id'
+  field :baz_id, from: 'Baz_id__c'
+end
+
+describe ActiveForce::Bulk do
+  subject { FooBarSObject }
+  let(:attributes) do
+    [
+      {id: 1, baz_id: 1 },
+      {id: 2, baz_id: 1 },
+      {id: 3, baz_id: 2 },
+    ]
+  end
+  let(:job) { double(ActiveForce::Bulk::Job) }
+  let(:timeout_message) { /Bulk job execution expired based on timeout of/ }
+  before do
+    allow(job).to receive(:result)
+  end
+
+  describe '::bulk_insert_all' do
+    before do
+      allow(ActiveForce::Bulk::Job).to receive(:run).with(hash_including(operation: :insert)).and_return(job)
+    end
+
+    it 'runs a bulk insert job' do
+      allow(job).to receive(:finished?).and_return(true)
+      subject.bulk_insert_all(attributes)
+    end
+
+    context 'when job takes a while to run' do
+      it 'polls job info until job is finished' do
+        allow(job).to receive(:finished?).and_return(false, false, true)
+        allow(job).to receive(:info)
+        subject.bulk_insert_all(attributes)
+      end
+    end
+
+    context 'when job run exceeds timeout' do
+      it 'raises error' do
+        allow(job).to receive(:finished?).and_return(false)
+        allow(job).to receive(:info)
+        expect do
+          subject.bulk_insert_all(attributes, timeout: 0.1)
+        end.to raise_error(ActiveForce::Bulk::TimeoutError, timeout_message)
+      end
+    end
+  end
+
+  describe '::bulk_update_all' do
+    before do
+      allow(ActiveForce::Bulk::Job).to receive(:run).with(hash_including(operation: :update)).and_return(job)
+    end
+
+    it 'runs a bulk insert job' do
+      allow(job).to receive(:finished?).and_return(true)
+      subject.bulk_update_all(attributes)
+    end
+
+    context 'when job takes a while to run' do
+      it 'polls job info until job is finished' do
+        allow(job).to receive(:finished?).and_return(false, false, true)
+        allow(job).to receive(:info)
+        subject.bulk_update_all(attributes)
+      end
+    end
+
+    context 'when job run exceeds timeout' do
+      it 'raises error' do
+        allow(job).to receive(:finished?).and_return(false)
+        allow(job).to receive(:info)
+        expect do
+          subject.bulk_update_all(attributes, timeout: 0.1)
+        end.to raise_error(ActiveForce::Bulk::TimeoutError, timeout_message)
+      end
+    end
+  end
+
+  describe '::bulk_delete_all' do
+    before do
+      allow(ActiveForce::Bulk::Job).to receive(:run).with(hash_including(operation: :delete)).and_return(job)
+    end
+
+    it 'runs a bulk insert job' do
+      allow(job).to receive(:finished?).and_return(true)
+      subject.bulk_delete_all(attributes)
+    end
+
+    context 'when job takes a while to run' do
+      it 'polls job info until job is finished' do
+        allow(job).to receive(:finished?).and_return(false, false, true)
+        allow(job).to receive(:info)
+        subject.bulk_delete_all(attributes)
+      end
+    end
+
+    context 'when job run exceeds timeout' do
+      it 'raises error' do
+        allow(job).to receive(:finished?).and_return(false)
+        allow(job).to receive(:info)
+        expect do
+          subject.bulk_delete_all(attributes, timeout: 0.1)
+        end.to raise_error(ActiveForce::Bulk::TimeoutError, timeout_message)
+      end
+    end
+  end
+end

data/spec/active_force/query_spec.rb

@@ -165,6 +165,22 @@ describe ActiveForce::Query do
       expect(query.to_s).to eq "SELECT Id, name, etc FROM table_name"
       expect(new_query.to_s).to eq 'SELECT Id, name, etc FROM table_name LIMIT 1'
     end
+
+    it "does not query if records have already been fetched" do
+      query = ActiveForce::Query.new 'table_name'
+      query.instance_variable_set(:@records, %w[foo bar])
+      query.instance_variable_set(:@decorated_records, %w[foo bar])
+      expect(query).not_to receive(:limit)
+      expect(query).to receive(:clone_and_set_instance_variables).with(size: 1, records: ['foo'], decorated_records: ['foo'])
+      query.first
+    end
+
+    it 'queries the api if it has not been queried yet' do
+      query = ActiveForce::Query.new 'table_name'
+      query.instance_variable_set(:@records, nil)
+      expect(query).to receive(:limit)
+      query.first
+    end
   end
 
   describe '.last' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_force
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Eloy Espinaco
@@ -11,7 +11,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-02 00:00:00.000000000 Z
+date: 2023-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -155,6 +155,10 @@ files:
 - lib/active_force/association/has_many_association.rb
 - lib/active_force/association/has_one_association.rb
 - lib/active_force/association/relation_model_builder.rb
+- lib/active_force/bulk.rb
+- lib/active_force/bulk/job.rb
+- lib/active_force/bulk/job_result.rb
+- lib/active_force/bulk/records.rb
 - lib/active_force/field.rb
 - lib/active_force/mapping.rb
 - lib/active_force/query.rb
@@ -170,6 +174,10 @@ files:
 - spec/active_force/active_query_spec.rb
 - spec/active_force/association/relation_model_builder_spec.rb
 - spec/active_force/association_spec.rb
+- spec/active_force/bulk/job_result_spec.rb
+- spec/active_force/bulk/job_spec.rb
+- spec/active_force/bulk/record_spec.rb
+- spec/active_force/bulk_spec.rb
 - spec/active_force/callbacks_spec.rb
 - spec/active_force/field_spec.rb
 - spec/active_force/mapping_spec.rb
@@ -216,6 +224,10 @@ test_files:
 - spec/active_force/active_query_spec.rb
 - spec/active_force/association/relation_model_builder_spec.rb
 - spec/active_force/association_spec.rb
+- spec/active_force/bulk/job_result_spec.rb
+- spec/active_force/bulk/job_spec.rb
+- spec/active_force/bulk/record_spec.rb
+- spec/active_force/bulk_spec.rb
 - spec/active_force/callbacks_spec.rb
 - spec/active_force/field_spec.rb
 - spec/active_force/mapping_spec.rb