airctiverecord 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dfcc33cb71a75dadf8007c2f4acab0d9274d617fa5b6a3d97dd95061a155c42
-  data.tar.gz: 22b3443fdebc4ced36b670b02f77289b4749c204aed23b3719a8e30b65ee28b1
+  metadata.gz: ae3765d9f17173d90f9e6bbbce91fca4adaf5dbcf2543acacab671cb9ecb577c
+  data.tar.gz: ef36c911e89d741eb5f33d9a0bba89b2b866283e4f3d89cc447b089247ce36d4
 SHA512:
-  metadata.gz: 4cc51162eb066c606ae86b331bc793a0b34803d03298daa07abb6d8509649337c3369676ab2bcefb252730c0916520b45b6aad2b932af436229aee52d76c6171
-  data.tar.gz: 92988e793b0fdce815872a9fa64c9d7a60df73ef71deea731456e8e407b9f9a75fd5794986880a2f4c546c48f7818a988170e7d92d6aca5517fea17f219778a7
+  metadata.gz: c87e579fc0a84a2acfe7f6b9649606190672efec26d80c769432d5e135e80881cb3141410d8a0a3fabad55f48843883a345f667c08673889cae96fdcace44bc8
+  data.tar.gz: a110512bd802d6e5181bc982874ffce213a7c01f4055211a795deacaf0f888797cd68663fc7bdb3585318c80d2c182b93b125ba60f5b9a1f7be54ed754911004

data/README.md

@@ -106,6 +106,16 @@ user = User.first
 user = User.find_by(email: "alice@example.com")
 user = User.find_by!(email: "alice@example.com") # raises if not found
 
+# find or create
+user = User.find_or_create_by(email: "alice@example.com")
+user = User.find_or_create_by!(email: "alice@example.com") # raises on validation error
+
+# block is yielded to the new record only (not if found)
+user = User.find_or_create_by(email: "alice@example.com") do |u|
+  u.first_name = "Alice"
+  u.role = "admin"
+end
+
 # update
 user.update(first_name: "Alicia")
 user.first_name = "Alicia"
@@ -323,17 +333,21 @@ User.first(10)   # limit(10)
 
 **large tables**
 
-for tables with 25k+ records, process in batches:
+for tables with many records, use `find_each` or `find_in_batches`:
 
 ```ruby
-# batch processing
-offset = 0
-loop do
-  batch = User.limit(100).offset(offset).to_a
-  break if batch.empty?
-  batch.each { |user| process(user) }
-  offset += 100
+# process records one at a time (fetches in batches of 100 internally)
+User.where(active: true).find_each do |user|
+  process(user)
 end
+
+# process records in batches
+User.find_in_batches(batch_size: 50) do |batch|
+  bulk_import(batch)
+end
+
+# works with scopes and conditions
+User.active.admins.find_each(batch_size: 50) { |user| sync(user) }
 ```
 
 ## license

data/examples/associations_example.rb

@@ -12,26 +12,26 @@ BASE_KEY = ENV.fetch("AIRTABLE_BASE_KEY")
 class Team < AirctiveRecord::Base
   self.base_key = BASE_KEY
   self.table_name = "Teams"
-  
+
   attribute :name
   attribute :description
-  
+
   has_many :users
   has_one :leader, class_name: "User", foreign_key: "Leader"
-  
+
   validates :name, presence: true
 end
 
 class User < AirctiveRecord::Base
   self.base_key = BASE_KEY
   self.table_name = "Users"
-  
+
   attribute :name
   attribute :email
-  
+
   belongs_to :team
   has_many :tasks
-  
+
   validates :name, presence: true
   validates :email, presence: true
 end
@@ -39,17 +39,17 @@ end
 class Task < AirctiveRecord::Base
   self.base_key = BASE_KEY
   self.table_name = "Tasks"
-  
+
   attribute :title
   attribute :status
   attribute :description
-  
+
   belongs_to :user
   has_one :team, through: :user
-  
+
   validates :title, presence: true
   validates :status, inclusion: { in: %w[pending in_progress completed] }
-  
+
   scope :pending, -> { where("{Status} = 'pending'") }
   scope :completed, -> { where("{Status} = 'completed'") }
 end

data/examples/basic_usage.rb

@@ -11,33 +11,33 @@ Norairrecord.api_key = ENV.fetch("AIRTABLE_API_KEY")
 class User < AirctiveRecord::Base
   self.base_key = ENV.fetch("AIRTABLE_BASE_KEY")
   self.table_name = "Users"
-  
+
   # Define attributes
   attribute :name
   attribute :email
   attribute :age
   attribute :role
-  
+
   # Validations
   validates :name, presence: true
   validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
   validates :age, numericality: { greater_than: 0, less_than: 150 }, allow_nil: true
   validates :role, inclusion: { in: %w[admin user guest] }, allow_nil: true
-  
+
   # Callbacks
   before_save :normalize_email
   after_create :log_creation
-  
+
   # Scopes
   scope :admins, -> { where("{Role} = 'admin'") }
   scope :active, -> { where("{Active} = TRUE()") }
-  
+
   private
-  
+
   def normalize_email
     self.email = email.downcase.strip if email.present?
   end
-  
+
   def log_creation
     puts "Created user: #{name} (#{email})"
   end
@@ -86,6 +86,6 @@ puts "Name is now: #{user.name}"
 puts "\nTrying to create invalid user..."
 invalid_user = User.new(email: "not-an-email")
 puts "Valid? #{invalid_user.valid?}"
-puts "Errors: #{invalid_user.errors.full_messages.join(', ')}"
+puts "Errors: #{invalid_user.errors.full_messages.join(", ")}"
 
 puts "\nDone!"

data/examples/boolean_fields.rb

@@ -7,17 +7,17 @@ require "airctiverecord"
 class User < AirctiveRecord::Base
   self.base_key = "appTest123"
   self.table_name = "Users"
-  
+
   field :name, "Name"
   field :email, "Email"
   field :active, "Active", type: :boolean
   field :verified, "Verified", type: :boolean
   field :admin, "Admin", type: :boolean
-  
+
   scope :active, -> { where(active: true) }
   scope :verified, -> { where(verified: true) }
   scope :admins, -> { where(admin: true) }
-  
+
   def self.records(**params)
     puts "records(#{params.inspect})"
     []

data/examples/chainable_queries.rb

@@ -7,18 +7,18 @@ require "airctiverecord"
 class User < AirctiveRecord::Base
   self.base_key = "appTest123"
   self.table_name = "Users"
-  
+
   field :first_name, "First Name"
   field :email, "Email Address"
   field :role, "Role"
   field :active, "Active"
   field :age, "Age"
-  
+
   scope :active, -> { where(active: true) }
   scope :admins, -> { where(role: "admin") }
   scope :adults, -> { where("AND({Age} >= 18, {Age} < 65)") }
   scope :recent, -> { order(created_at: :desc).limit(10) }
-  
+
   def self.records(**params)
     puts "Would call Airtable API with:"
     puts params.inspect
@@ -44,7 +44,7 @@ User.where(age: 18..65).to_a
 puts
 
 puts "=== IN queries ==="
-User.where(role: ["admin", "moderator", "guest"]).to_a
+User.where(role: %w[admin moderator guest]).to_a
 puts
 
 puts "=== raw formulas still work ==="

data/examples/field_mapping_example.rb

@@ -11,7 +11,7 @@ Norairrecord.api_key = ENV.fetch("AIRTABLE_API_KEY", "test_key")
 class Contact < AirctiveRecord::Base
   self.base_key = ENV.fetch("AIRTABLE_BASE_KEY", "appTest123")
   self.table_name = "Contacts"
-  
+
   # Map Ruby attribute names to Airtable field names with spaces
   field :first_name, "First Name"
   field :last_name, "Last Name"
@@ -22,21 +22,21 @@ class Contact < AirctiveRecord::Base
   field :linkedin_url, "LinkedIn URL"
   field :date_added, "Date Added"
   field :is_vip, "VIP?"
-  
+
   # Validations using Ruby attribute names
   validates :first_name, :last_name, presence: true
   validates :email_address, format: { with: URI::MailTo::EMAIL_REGEXP }, allow_blank: true
   validates :phone_number, length: { minimum: 10 }, allow_blank: true
-  
+
   # Callbacks
   before_save :normalize_email
-  
+
   # Scopes
   scope :vip, -> { where("{VIP?} = TRUE()") }
   scope :with_email, -> { where("{Email Address} != ''") }
-  
+
   private
-  
+
   def normalize_email
     self.email_address = email_address&.downcase&.strip
   end

data/examples/readonly_fields.rb

@@ -10,15 +10,15 @@ end
 
 class Contact < AirpplicationRecord
   self.table_name = "Contacts"
-  
+
   field :name, "Name"
   field :email, "Email"
   field :company, "Company"
-  
+
   # lookup fields (pulled from linked Company record)
   field :company_name, "Company Name (from Company)", readonly: true
   field :company_address, "Company Address (from Company)", readonly: true
-  
+
   # formula fields (computed by airtable)
   field :full_name, "Full Name (formula)", readonly: true
 end
@@ -26,16 +26,16 @@ end
 contact = Contact.new(
   name: "Alice",
   email: "alice@example.com",
-  company_name: "Acme Corp"  # readonly field - silently ignored
+  company_name: "Acme Corp" # readonly field - silently ignored
 )
 
 puts "=== readonly fields are readable ==="
 contact.instance_variable_set(:@fields, {
-  "Name" => "Alice",
-  "Email" => "alice@example.com",
-  "Company Name (from Company)" => "Acme Corp",
-  "Full Name (formula)" => "Alice Smith"
-})
+                                "Name" => "Alice",
+                                "Email" => "alice@example.com",
+                                "Company Name (from Company)" => "Acme Corp",
+                                "Full Name (formula)" => "Alice Smith"
+                              })
 
 puts "company_name: #{contact.company_name}"
 puts "full_name: #{contact.full_name}"

data/examples/scope_isolation.rb

@@ -7,13 +7,13 @@ require "airctiverecord"
 class User < AirctiveRecord::Base
   self.base_key = "appTest123"
   self.table_name = "Users"
-  
+
   field :role, "Role"
   field :active, "Active"
-  
+
   scope :active, -> { where(active: true) }
   scope :admins, -> { where(role: "admin") }
-  
+
   def self.records(**params)
     puts "User.records called with: #{params.inspect}"
     []
@@ -23,13 +23,13 @@ end
 class Post < AirctiveRecord::Base
   self.base_key = "appTest123"
   self.table_name = "Posts"
-  
+
   field :status, "Status"
   field :featured, "Featured"
-  
+
   scope :published, -> { where(status: "published") }
   scope :featured, -> { where(featured: true) }
-  
+
   def self.records(**params)
     puts "Post.records called with: #{params.inspect}"
     []

data/lib/airctiverecord/associations.rb

@@ -8,13 +8,13 @@ module AirctiveRecord
       # just add activerecord-style defaults, norairrecord does the heavy lifting
       def has_many(name, options_arg = nil, **options_kwargs)
         options = options_arg || options_kwargs
-        
+
         if options[:through]
           define_has_many_through(name, options)
         else
           column = options[:column] || options[:foreign_key] || "#{name.to_s.singularize}_ids"
           klass = options[:class_name] || name.to_s.classify
-          
+
           super(name, { column: column, class: klass }.merge(options))
         end
       end
@@ -22,14 +22,14 @@ module AirctiveRecord
       def belongs_to(name, **options)
         column = options[:column] || options[:foreign_key] || "#{name}_id"
         klass = options[:class_name] || name.to_s.classify
-        
+
         super(name, { column: column, class: klass }.merge(options))
       end
 
       def has_one(name, **options)
         column = options[:column] || options[:foreign_key] || "#{name}_id"
         klass = options[:class_name] || name.to_s.classify
-        
+
         super(name, { column: column, class: klass }.merge(options))
       end
 

data/lib/airctiverecord/attribute_methods.rb

@@ -22,10 +22,10 @@ module AirctiveRecord
         airtable_field_name ||= attr_name
         readonly = options[:readonly] || options[:read_only]
         field_type = options[:type]
-        
+
         field_mappings[attr_name] = airtable_field_name
         readonly_fields << airtable_field_name if readonly
-        
+
         define_attribute_methods attr_name
 
         define_method(attr_name) do
@@ -35,14 +35,14 @@ module AirctiveRecord
 
         if readonly
           # readonly fields silently ignore sets (airtable rejects them anyway)
-          define_method("#{attr_name}=") do |value|
+          define_method("#{attr_name}=") do |_value|
             nil
           end
         else
           define_method("#{attr_name}=") do |value|
             field_name = self.class.field_mappings[attr_name]
             return if self[field_name] == value
-            
+
             send("#{attr_name}_will_change!") unless self[field_name] == value
             self[field_name] = value
           end
@@ -66,9 +66,7 @@ module AirctiveRecord
       end
     end
 
-    def attributes
-      fields
-    end
+    def attributes = fields
 
     def attributes=(attrs)
       attrs.each do |key, value|

data/lib/airctiverecord/base.rb

@@ -27,19 +27,19 @@ module AirctiveRecord
         @relation_class ||= Class.new(AirctiveRecord::Relation)
       end
 
-      def relation_class_name
-        "#{name}::Relation"
-      end
+      def relation_class_name = "#{name}::Relation"
     end
 
     def initialize(attributes = {}, **kwargs)
       # Extract id and created_at if present
       id = kwargs.delete(:id)
       created_at = kwargs.delete(:created_at)
-      
-      # Merge positional hash and kwargs to handle both styles
-      all_attrs = attributes.is_a?(Hash) ? attributes.merge(kwargs) : kwargs
-      
+
+      # Merge positional hash and kwargs to handle both styles.
+      # Call to_h to handle ActionController::Parameters, which is not a Hash subclass.
+      attr_hash = attributes.respond_to?(:to_h) ? attributes.to_h : {}
+      all_attrs = attr_hash.merge(kwargs)
+
       # Norairrecord::Table expects field names as STRING keys
       # We need to convert Ruby attribute names to Airtable field names
       mapped_attrs = {}
@@ -47,7 +47,7 @@ module AirctiveRecord
         field_name = self.class.field_mappings[key.to_s] || key.to_s
         mapped_attrs[field_name.to_s] = value # Ensure string keys
       end
-      
+
       # Call norairrecord's initialize properly
       if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.0.0")
         if mapped_attrs.empty?
@@ -58,7 +58,7 @@ module AirctiveRecord
       else
         super(mapped_attrs, id: id, created_at: created_at)
       end
-      
+
       clear_changes_information
     end
 
@@ -68,34 +68,31 @@ module AirctiveRecord
 
     def serializable_fields
       # exclude readonly fields from serialization
-      fields.reject { |k, v| self.class.readonly_fields.include?(k) }
+      fields.reject { |k, _v| self.class.readonly_fields.include?(k) }
     end
 
     def save(**options)
       return false unless valid?
-      
-      begin
-        run_callbacks :save do
-          if new_record?
-            run_callbacks :create do
-              super(**options)
-            end
-          else
-            run_callbacks :update do
-              super(**options)
-            end
+
+      run_callbacks :save do
+        if new_record?
+          run_callbacks :create do
+            super(**options)
+          end
+        else
+          run_callbacks :update do
+            super(**options)
           end
         end
-        changes_applied
-        true
-      rescue => e
-        false
       end
+      changes_applied
+      true
     end
 
     def save!(**options)
       raise RecordInvalid, errors.full_messages.join(", ") unless valid?
-      save(**options) || raise(RecordNotSaved, "Failed to save record")
+
+      save(**options)
     end
 
     def update(attributes)
@@ -110,6 +107,7 @@ module AirctiveRecord
 
     def reload
       return self if new_record?
+
       reloaded = self.class.find(id)
       @fields = reloaded.fields
       @created_at = reloaded.created_at
@@ -117,20 +115,12 @@ module AirctiveRecord
       self
     end
 
-    def persisted?
-      !new_record?
-    end
+    def persisted? = !new_record?
 
-    def to_param
-      id
-    end
+    def to_param = id
 
-    def to_key
-      persisted? ? [id] : nil
-    end
+    def to_key = persisted? ? [id] : nil
 
-    def to_model
-      self
-    end
+    def to_model = self
   end
 end

data/lib/airctiverecord/relation.rb

@@ -18,11 +18,9 @@ module AirctiveRecord
     # override to use field mappings when building airtable params
     def to_airtable_params
       params = {}
-      
+
       # filter
-      if @where_clause.any?
-        params[:filter] = @where_clause.to_airtable_formula
-      end
+      params[:filter] = @where_clause.to_airtable_formula if @where_clause.any?
 
       # sort - use field mappings
       if @order_values.any?
@@ -34,7 +32,7 @@ module AirctiveRecord
 
       # limit
       params[:max_records] = @limit_value if @limit_value
-      
+
       # offset
       params[:offset] = @offset_value if @offset_value
 

data/lib/airctiverecord/scoping.rb

@@ -5,22 +5,18 @@ module AirctiveRecord
     extend ActiveSupport::Concern
 
     class_methods do
-      # returns a chainable Relation object (model-specific!)
-      def all
-        relation_class.new(self)
-      end
+      # returns a chainable Relation object
+      def all = relation_class.new(self)
 
       # scopes are defined on the model's specific Relation class
       def scope(name, body)
-        unless body.respond_to?(:call)
-          raise ArgumentError, "The scope body needs to be callable."
-        end
+        raise ArgumentError, "The scope body needs to be callable." unless body.respond_to?(:call)
 
         # define on the class
         singleton_class.send(:define_method, name) do |*args|
           all.public_send(name, *args)
         end
-        
+
         # define on this model's Relation class
         relation_class.send(:define_method, name) do |*args|
           instance_exec(*args, &body)
@@ -28,41 +24,31 @@ module AirctiveRecord
       end
 
       # delegate finder methods to all
-      def where(conditions)
-        all.where(conditions)
-      end
+      def where(conditions) = all.where(conditions)
 
-      def order(*args)
-        all.order(*args)
-      end
+      def order(*args) = all.order(*args)
 
-      def limit(value)
-        all.limit(value)
-      end
+      def limit(value) = all.limit(value)
 
-      def offset(value)
-        all.offset(value)
-      end
+      def offset(value) = all.offset(value)
 
-      def find_by(conditions)
-        all.find_by(conditions)
-      end
+      def find_by(conditions) = all.find_by(conditions)
 
-      def find_by!(conditions)
-        all.find_by!(conditions)
-      end
+      def find_by!(conditions) = all.find_by!(conditions)
 
-      def first(limit = nil)
-        all.first(limit)
+      def find_or_create_by(conditions, &block)
+        find_by(conditions) || new(conditions).tap { |r| block&.call(r) }.tap(&:save)
       end
 
-      def last(limit = nil)
-        all.last(limit)
+      def find_or_create_by!(conditions, &block)
+        find_by(conditions) || new(conditions).tap { |r| block&.call(r) }.tap(&:save!)
       end
 
-      def count
-        all.count
-      end
+      def first(limit = nil) = all.first(limit)
+
+      def last(limit = nil) = all.last(limit)
+
+      def count = all.count
     end
   end
 end

data/lib/airctiverecord/validations.rb

@@ -18,6 +18,7 @@ module AirctiveRecord
 
     def save(**options)
       return false unless valid?
+
       super
     end
   end

data/lib/airctiverecord/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AirctiveRecord
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: airctiverecord
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - 24c02
@@ -9,20 +9,6 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: norairrecord
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.5'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: norairrecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 description: Provides a familiar ActiveRecord-like interface for Airtable, built on
   top of norairrecord with validations, callbacks, and associations.
 email: