airctiverecord 0.2.0

data/examples/associations_example.rb

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "airctiverecord"
+
+# Configure Airtable API
+Norairrecord.api_key = ENV.fetch("AIRTABLE_API_KEY")
+BASE_KEY = ENV.fetch("AIRTABLE_BASE_KEY")
+
+# Define models with associations
+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
+
+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
+
+# Example usage (uncomment to run with actual Airtable data):
+
+# Find a team and its users
+# team = Team.first
+# puts "Team: #{team.name}"
+# puts "Members:"
+# team.users.each do |user|
+#   puts "  - #{user.name} (#{user.email})"
+# end
+# puts "Leader: #{team.leader&.name}"
+
+# Find a user and their tasks
+# user = User.find_by(email: "alice@example.com")
+# puts "\n#{user.name}'s tasks:"
+# user.tasks.pending.each do |task|
+#   puts "  - #{task.title} [#{task.status}]"
+# end
+
+# Create associations
+# team = Team.first
+# new_user = User.create!(
+#   name: "Bob Johnson",
+#   email: "bob@example.com",
+#   team: team
+# )
+# puts "Created user #{new_user.name} in team #{team.name}"
+
+# has_many through example
+# task = Task.first
+# puts "Task '#{task.title}' belongs to team: #{task.team&.name}"
+
+puts "Association examples ready (uncomment code to run)"

data/examples/basic_usage.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "airctiverecord"
+
+# Configure Airtable API
+Norairrecord.api_key = ENV.fetch("AIRTABLE_API_KEY")
+
+# Define a User model
+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
+end
+
+# Example: Create a new user
+puts "Creating a new user..."
+user = User.new(
+  name: "Alice Smith",
+  email: "ALICE@EXAMPLE.COM", # Will be normalized
+  age: 30,
+  role: "admin"
+)
+
+if user.valid?
+  puts "User is valid!"
+  # Uncomment to actually save:
+  # user.save
+  # puts "User saved with ID: #{user.id}"
+else
+  puts "Validation errors:"
+  user.errors.full_messages.each { |msg| puts "  - #{msg}" }
+end
+
+# Example: Query users
+puts "\nQuerying users..."
+# Uncomment to run actual queries:
+# all_users = User.all
+# admin_users = User.admins
+# specific_user = User.find_by(email: "alice@example.com")
+
+# Example: Update a user
+puts "\nUpdating a user..."
+# Uncomment to run:
+# user = User.first
+# user.update(name: "Alice Johnson")
+
+# Example: Dirty tracking
+puts "\nDirty tracking example..."
+user.name = "Alice Johnson"
+puts "Name changed? #{user.name_changed?}"
+puts "Name was: #{user.name_was}"
+puts "Name is now: #{user.name}"
+
+# Example: Invalid user
+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 "\nDone!"

data/examples/boolean_fields.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+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})"
+    []
+  end
+end
+
+puts "=== boolean field with type: :boolean ==="
+user = User.new(
+  name: "Alice",
+  active: true,
+  verified: false,
+  admin: nil
+)
+
+puts "active: #{user.active.inspect}"
+puts "active?: #{user.active?}"
+
+puts "\nverified: #{user.verified.inspect}"
+puts "verified?: #{user.verified?}"
+
+puts "\nadmin (nil): #{user.admin.inspect}"
+puts "admin?: #{user.admin?} (falsy)"
+
+puts "\n=== regular field (no type specified) ==="
+puts "name: #{user.name.inspect}"
+puts "name?: #{user.name?} (presence check)"
+
+puts "\n=== scopes with booleans ==="
+User.active.to_a
+puts
+
+User.active.verified.admins.to_a

data/examples/chainable_queries.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+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
+    puts
+    []
+  end
+end
+
+puts "=== chainable queries ==="
+User.where(role: "admin").where(active: true).order(first_name: :asc).limit(10).to_a
+puts
+
+puts "=== scopes chain! ==="
+User.active.admins.recent.to_a
+puts
+
+puts "=== hash queries with field mappings ==="
+User.where(first_name: "Alice", email: "alice@example.com").to_a
+puts
+
+puts "=== range queries ==="
+User.where(age: 18..65).to_a
+puts
+
+puts "=== IN queries ==="
+User.where(role: ["admin", "moderator", "guest"]).to_a
+puts
+
+puts "=== raw formulas still work ==="
+User.where("{Age} > 18").where(active: true).to_a
+puts
+
+puts "=== lazy loading ==="
+query = User.where(role: "admin")
+puts "Query built (no API call yet)"
+puts "Calling to_airtable:"
+puts query.to_airtable
+puts "\nNow iterating:"
+query.each { |u| puts u }

data/examples/field_mapping_example.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "airctiverecord"
+
+# Configure Airtable API
+Norairrecord.api_key = ENV.fetch("AIRTABLE_API_KEY", "test_key")
+
+# Example: Mapping Airtable fields with spaces to Ruby-friendly names
+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"
+  field :email_address, "Email Address"
+  field :phone_number, "Phone Number (Mobile)"
+  field :company_name, "Company Name"
+  field :job_title, "Job Title"
+  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
+end
+
+# Example usage
+puts "Creating a contact with field mappings..."
+contact = Contact.new(
+  first_name: "Jane",
+  last_name: "Smith",
+  email_address: "JANE.SMITH@EXAMPLE.COM",
+  phone_number: "555-123-4567",
+  company_name: "Acme Corp",
+  job_title: "Senior Engineer",
+  is_vip: true
+)
+
+puts "\nContact attributes (Ruby names):"
+puts "  First Name: #{contact.first_name}"
+puts "  Last Name: #{contact.last_name}"
+puts "  Email: #{contact.email_address}"
+puts "  Phone: #{contact.phone_number}"
+puts "  Company: #{contact.company_name}"
+puts "  VIP?: #{contact.is_vip}"
+
+puts "\nValidation:"
+if contact.valid?
+  puts "  ✓ Contact is valid"
+else
+  puts "  ✗ Validation errors:"
+  contact.errors.full_messages.each { |msg| puts "    - #{msg}" }
+end
+
+puts "\nDirty tracking with field mappings:"
+contact.first_name = "Janet"
+puts "  first_name changed? #{contact.first_name_changed?}"
+puts "  first_name was: #{contact.first_name_was}"
+puts "  first_name is now: #{contact.first_name}"
+puts "  Changes: #{contact.changes.inspect}"
+
+puts "\nPresence checking:"
+puts "  first_name present? #{contact.first_name?}"
+puts "  linkedin_url present? #{contact.linkedin_url?}"
+
+puts "\nActual Airtable fields (what gets sent to Airtable):"
+puts "  #{contact.fields.inspect}"
+
+puts "\nField mappings:"
+puts "  #{Contact.field_mappings.inspect}"
+
+# Example with invalid data
+puts "\n\nCreating invalid contact..."
+invalid_contact = Contact.new(
+  email_address: "not-an-email",
+  phone_number: "123" # too short
+)
+
+puts "Valid? #{invalid_contact.valid?}"
+puts "Errors:"
+invalid_contact.errors.full_messages.each { |msg| puts "  - #{msg}" }
+
+puts "\nDone!"

data/examples/readonly_fields.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "airctiverecord"
+
+class AirpplicationRecord < AirctiveRecord::Base
+  self.base_key = "appTest123"
+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
+
+contact = Contact.new(
+  name: "Alice",
+  email: "alice@example.com",
+  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"
+})
+
+puts "company_name: #{contact.company_name}"
+puts "full_name: #{contact.full_name}"
+
+puts "\n=== trying to set readonly field ==="
+contact.company_name = "Evil Corp"
+puts "company_name after set: #{contact.company_name} (unchanged)"
+
+puts "\n=== serializable_fields excludes readonly ==="
+puts "fields: #{contact.fields.keys}"
+puts "serializable_fields: #{contact.serializable_fields.keys}"
+
+puts "\n=== readonly_fields list ==="
+puts "Contact.readonly_fields: #{Contact.readonly_fields.to_a.inspect}"

data/examples/scope_isolation.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+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}"
+    []
+  end
+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}"
+    []
+  end
+end
+
+puts "=== User has its own scopes ==="
+puts "User relation class: #{User.relation_class.object_id}"
+puts "User scopes: #{User.relation_class.instance_methods(false).sort}"
+puts
+
+puts "=== Post has its own scopes ==="
+puts "Post relation class: #{Post.relation_class.object_id}"
+puts "Post scopes: #{Post.relation_class.instance_methods(false).sort}"
+puts
+
+puts "=== Different relation classes ==="
+puts "Same class? #{User.relation_class == Post.relation_class}"
+puts
+
+puts "=== User.active.admins ==="
+User.active.admins.to_a
+puts
+
+puts "=== Post.published.featured ==="
+Post.published.featured.to_a
+puts
+
+puts "=== Trying to call Post scope on User (should fail) ==="
+begin
+  User.all.published.to_a
+  puts "ERROR: Should have raised NoMethodError!"
+rescue NoMethodError => e
+  puts "✓ Correctly raised: #{e.message}"
+end

data/lib/airctiverecord/associations.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module AirctiveRecord
+  module Associations
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # 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
+
+      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
+
+      private
+
+      def define_has_many_through(name, options)
+        through = options[:through]
+        source = options[:source] || name.to_s.singularize
+
+        define_method(name) do
+          send(through).flat_map { |record| Array(record.send(source)) }.compact
+        end
+      end
+    end
+  end
+end

data/lib/airctiverecord/attribute_methods.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module AirctiveRecord
+  module AttributeMethods
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveModel::AttributeMethods
+    end
+
+    class_methods do
+      def field_mappings
+        @field_mappings ||= {}
+      end
+
+      def readonly_fields
+        @readonly_fields ||= Set.new
+      end
+
+      def field(attr_name, airtable_field_name = nil, **options)
+        attr_name = attr_name.to_s
+        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
+          field_name = self.class.field_mappings[attr_name]
+          self[field_name]
+        end
+
+        if readonly
+          # readonly fields silently ignore sets (airtable rejects them anyway)
+          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
+        end
+
+        # ? method - different behavior for booleans vs other fields
+        if field_type == :boolean
+          # boolean: returns the actual boolean value
+          define_method("#{attr_name}?") do
+            field_name = self.class.field_mappings[attr_name]
+            !!self[field_name]
+          end
+        else
+          # regular: checks presence
+          define_method("#{attr_name}?") do
+            field_name = self.class.field_mappings[attr_name]
+            value = self[field_name]
+            !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
+          end
+        end
+      end
+    end
+
+    def attributes
+      fields
+    end
+
+    def attributes=(attrs)
+      attrs.each do |key, value|
+        if respond_to?("#{key}=")
+          send("#{key}=", value)
+        else
+          self[key.to_s] = value
+        end
+      end
+    end
+
+    def read_attribute(attr_name)
+      field_name = self.class.field_mappings[attr_name.to_s] || attr_name.to_s
+      self[field_name]
+    end
+
+    def write_attribute(attr_name, value)
+      field_name = self.class.field_mappings[attr_name.to_s] || attr_name.to_s
+      self[field_name] = value
+    end
+
+    def attribute_present?(attr_name)
+      value = read_attribute(attr_name)
+      !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
+    end
+  end
+end