airrel 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b961c23489f4318b5feaceb9dd0b278a402ae3361a7516b4f7f5c7514459843
+  data.tar.gz: 5635e4654a366fec1e9aff98394d99675dba861d8514845fbf75cd64ac88ba53
+SHA512:
+  metadata.gz: 0cd6592f458ad4aa04a3d43dcbf6d9fe737a9a10a8998b6efa9bc268bd119fa35e0303a8a76a9343007967111a8033fe6762228e966939d7ac97b944772a43a7
+  data.tar.gz: e406cf4797e68a2ee05765bf67cc0cd7900cfddb70d7530e88bbe17ee1dd62c1cc0c29fd2a89a80e6aa7838763f5882a5f073b7811f3e27c5b923ed7d56c2f21

data/.idea/.gitignore

@@ -0,0 +1,8 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

data/.idea/airrel.iml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RUBY_MODULE" version="4">
+  <component name="ModuleRunConfigurationManager">
+    <shared />
+  </component>
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/features" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/spec" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/test" isTestSource="true" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" scope="PROVIDED" name="ast (v2.4.3, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="bundler (v2.7.2, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="connection_pool (v2.5.4, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="date (v3.5.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="diff-lcs (v1.6.2, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="erb (v6.0.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday (v2.14.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday-net_http (v3.4.2, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday-net_http_persistent (v2.3.1, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="io-console (v0.8.1, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="irb (v1.15.3, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="json (v2.16.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="language_server-protocol (v3.17.0.5, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="lint_roller (v1.1.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="logger (v1.7.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="net-http (v0.8.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="net-http-persistent (v4.0.6, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="norairrecord (v0.2.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="parallel (v1.27.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="parser (v3.3.10.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="pp (v0.6.3, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="prettyprint (v0.2.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="prism (v1.6.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="psych (v5.2.6, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="racc (v1.8.1, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rainbow (v3.1.1, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rake (v13.3.1, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rdoc (v6.15.1, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="regexp_parser (v2.11.3, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="reline (v0.6.3, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec (v3.13.2, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-core (v3.13.6, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-expectations (v3.13.5, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-mocks (v3.13.7, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-support (v3.13.6, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rubocop (v1.81.7, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rubocop-ast (v1.48.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="ruby-progressbar (v1.13.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="stringio (v3.1.8, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="tsort (v0.2.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="unicode-display_width (v3.2.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="unicode-emoji (v4.1.0, mise: 3.4.3) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="uri (v1.1.1, mise: 3.4.3) [gem]" level="application" />
+  </component>
+</module>

data/.idea/misc.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectRootManager" version="2" project-jdk-name="mise: 3.4.3" project-jdk-type="RUBY_SDK" />
+</project>

data/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/airrel.iml" filepath="$PROJECT_DIR$/.idea/airrel.iml" />
+    </modules>
+  </component>
+</project>

data/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 24c02
+
+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,210 @@
+# Airrel
+
+arel-like relational algebra for airtable. it's like arel but AIR. get it?
+
+chainable queries that don't execute until you iterate. builds airtable formulas for you.
+
+## installation
+
+```ruby
+gem 'airrel'
+```
+
+## usage
+
+```ruby
+require 'airrel'
+require 'norairrecord'
+
+class User < Norairrecord::Table
+  self.base_key = "appXXX"
+  self.table_name = "Users"
+  
+  # add the relation magic
+  def self.all
+    Airrel::Relation.new(self)
+  end
+end
+
+# now you can chain!
+User.all.where(role: "admin").where(active: true).order(created_at: :desc).limit(10)
+
+# queries are lazy - nothing executes until you iterate
+users = User.all.where(role: "admin") # no API call yet
+users.each { |u| puts u["Name"] }     # now it executes
+
+# all the usual suspects
+User.all.where(age: 18..65)           # range queries
+User.all.where(role: ["admin", "mod"]) # IN queries  
+User.all.where(email: nil)            # BLANK() checks
+User.all.order(:name)                 # sorting
+User.all.order(name: :asc, age: :desc)
+User.all.limit(10)
+User.all.offset(20)
+
+# finder methods
+User.all.find_by(email: "test@example.com")
+User.all.find_by!(email: "test@example.com") # raises if not found
+User.all.first
+User.all.first(5)
+User.all.order(:created_at).last              # requires an order!
+User.all.count
+
+# raw formulas still work
+User.all.where("{Age} > 18")
+User.all.where("AND({Active} = TRUE(), {Role} = 'admin')")
+
+# inspect the query without executing
+User.all.where(role: "admin").to_airtable
+# => {:filter=>"AND({role} = 'admin')"}
+```
+
+## formula builder
+
+build complex airtable formulas programmatically:
+
+```ruby
+include Airrel::FormulaBuilder
+
+# basic predicates
+eq("Name", "Alice")           # => "{Name} = 'Alice'"
+neq("Age", 25)                # => "NOT({Age} = 25)"
+gt("Age", 18)                 # => "{Age} > 18"
+gte("Age", 18)                # => "{Age} >= 18"
+lt("Age", 65)                 # => "{Age} < 65"
+lte("Age", 65)                # => "{Age} <= 65"
+
+# boolean logic
+all(eq("Role", "admin"), eq("Active", true))
+any(eq("Role", "admin"), eq("Role", "moderator"))
+none(blank("Email"))
+
+# helpers
+blank("Email")                # => "{Email} = BLANK()"
+present("Email")              # => "NOT({Email} = BLANK())"
+find("Name", "Alice")         # => "FIND('Alice', {Name})"
+search("Tags", "important")   # => "SEARCH('important', {Tags})"
+
+# use in queries
+User.all.where(
+  all(
+    gte("Age", 18),
+    present("Email")
+  )
+)
+```
+
+## how it works
+
+`Airrel::Relation` is a lazy query builder. it:
+
+1. stores query state (where clauses, ordering, limits)
+2. doesn't execute until you iterate or call a terminal method
+3. returns new relation objects when you chain (immutable)
+4. converts everything to airtable API params when executed
+
+hash conditions get converted to airtable formulas:
+- `{ role: "admin" }` → `{role} = 'admin'`
+- `{ age: nil }` → `{age} = BLANK()`
+- `{ active: true }` → `{active} = TRUE()`
+- `{ age: 18..65 }` → `AND({age} >= 18, {age} <= 65)`
+- `{ role: ["admin", "mod"] }` → `OR({role} = 'admin', {role} = 'mod')`
+
+multiple where clauses get AND'd together:
+```ruby
+User.all.where(role: "admin").where(active: true)
+# => AND({role} = 'admin', {active} = TRUE())
+```
+
+## combining with field mappings
+
+if you're using field mappings (like in airctiverecord), you can pass them to the formula builder:
+
+```ruby
+field_mappings = { first_name: "First Name", last_name: "Last Name" }
+
+Airrel::FormulaBuilder.hash_to_formula(
+  { first_name: "Alice" },
+  field_mappings
+)
+# => "{First Name} = 'Alice'"
+```
+
+## security & escaping
+
+**string escaping**
+
+all string values are properly escaped for airtable formulas:
+- single and double quotes are backslash-escaped: `O'Reilly` → `'O\'Reilly'`
+- works for hash conditions, find/search helpers, and manual formula building
+
+```ruby
+User.where(name: "O'Reilly")
+# => {filter: "{name} = 'O\'Reilly'"}
+
+find("Name", "it's working")
+# => "FIND('it\'s working', {Name})"
+```
+
+**field names**
+
+field names are used as-is in `{fieldName}` syntax. if you're accepting user input for field names, validate them first - airtable field names can contain most characters but shouldn't contain `{` or `}`.
+
+**injection safety**
+
+because we properly escape all string values, formula injection attacks are prevented:
+
+```ruby
+User.where(name: "'; DROP TABLE users; --")
+# => {filter: "{name} = '\'; DROP TABLE users; --'"}
+# safe! airtable will look for a name with that exact string
+```
+
+## performance considerations
+
+**automatic optimizations**
+
+Airrel automatically optimizes common queries:
+
+```ruby
+User.first          # limit(1) - only loads 1 record
+User.last           # limit(1) with reversed order
+User.any?           # limit(1) - checks if at least 1 exists
+User.empty?         # !any? - same optimization
+User.first(10)      # limit(10) - only loads 10 records
+```
+
+**count is expensive**
+
+airtable doesn't have a count API, so `count` loads all matching records:
+
+```ruby
+User.where(role: "admin").count  # loads ALL admin users!
+```
+
+if you just need to check existence, use `any?` or `exists?`:
+
+```ruby
+User.where(role: "admin").any?   # only loads 1 record ✓
+```
+
+**pagination**
+
+by default, norairrecord paginates through all results. for large tables (25k+ records), consider:
+
+```ruby
+# process in batches
+User.limit(100).offset(0).each { |u| process(u) }
+User.limit(100).offset(100).each { |u| process(u) }
+
+# or disable pagination for a single page
+User.limit(100).without_pagination.to_a
+```
+
+**field selection**
+
+norairrecord supports field selection to reduce payload size (though not exposed in Airrel yet).
+
+## license
+
+MIT

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/demo.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "airrel"
+
+# fake norairrecord table for testing
+class User
+  def self.records(**params)
+    puts "Would call Airtable API with:"
+    puts params.inspect
+    []
+  end
+end
+
+# basic chaining
+puts "=== basic chaining ==="
+relation = Airrel::Relation.new(User)
+  .where(role: "admin")
+  .where(active: true)
+  .order(created_at: :desc)
+  .limit(10)
+
+puts relation.to_airtable
+puts
+
+# hash to formula conversion
+puts "=== hash to formula ==="
+puts Airrel::FormulaBuilder.hash_to_formula(email: "test@example.com", age: 25)
+puts Airrel::FormulaBuilder.hash_to_formula(age: 18..65)
+puts Airrel::FormulaBuilder.hash_to_formula(role: ["admin", "moderator"])
+puts Airrel::FormulaBuilder.hash_to_formula(deleted_at: nil)
+puts
+
+# formula builder helpers
+puts "=== formula builder helpers ==="
+include Airrel::FormulaBuilder
+
+puts eq("Name", "Alice")
+puts gt("Age", 18)
+puts all(eq("Role", "admin"), present("Email"))
+puts any(eq("Role", "admin"), eq("Role", "moderator"))
+puts
+
+# lazy execution
+puts "=== lazy execution ==="
+query = Airrel::Relation.new(User).where(role: "admin")
+puts "Query built (no API call yet)"
+puts "Iterating now..."
+query.each { |u| puts u }

data/lib/airrel/formula_builder.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Airrel
+  module FormulaBuilder
+    extend self
+
+    def hash_to_formula(conditions, field_mappings = {})
+      formulas = conditions.map do |key, value|
+        field_name = field_mappings[key.to_s] || key.to_s
+        build_predicate(field_name, value)
+      end
+
+      formulas.size == 1 ? formulas.first : "AND(#{formulas.join(', ')})"
+    end
+
+    def build_predicate(field, value)
+      case value
+      when nil
+        "{#{field}} = BLANK()"
+      when true
+        "{#{field}} = TRUE()"
+      when false
+        "{#{field}} = FALSE()"
+      when String
+        "{#{field}} = #{escape_string(value)}"
+      when Numeric
+        "{#{field}} = #{value}"
+      when Range
+        if value.exclude_end?
+          "AND({#{field}} >= #{escape_value(value.begin)}, {#{field}} < #{escape_value(value.end)})"
+        else
+          "AND({#{field}} >= #{escape_value(value.begin)}, {#{field}} <= #{escape_value(value.end)})"
+        end
+      when Array
+        # IN query - use OR
+        or_conditions = value.map { |v| build_predicate(field, v) }
+        "OR(#{or_conditions.join(', ')})"
+      else
+        # fallback - convert to string and escape
+        "{#{field}} = #{escape_string(value.to_s)}"
+      end
+    end
+
+    # escape a string value for use in airtable formulas
+    # airtable uses backslash escaping: \ escapes the next character
+    # so we need to escape backslashes first, then quotes
+    def escape_string(str)
+      # escape backslashes first (\ -> \\), then quotes (' -> \', " -> \")
+      escaped = str.to_s.gsub('\\', '\\\\\\\\').gsub(/['"]/, '\\\\\0')
+      "'#{escaped}'"
+    end
+
+    # escape any value (delegates to appropriate method)
+    def escape_value(value)
+      case value
+      when String
+        escape_string(value)
+      when Numeric
+        value.to_s
+      when nil
+        "BLANK()"
+      when true
+        "TRUE()"
+      when false
+        "FALSE()"
+      else
+        escape_string(value.to_s)
+      end
+    end
+
+    # helper methods for building formulas programmatically
+
+    def all(*formulas)
+      "AND(#{formulas.join(', ')})"
+    end
+
+    def any(*formulas)
+      "OR(#{formulas.join(', ')})"
+    end
+
+    def none(formula)
+      "NOT(#{formula})"
+    end
+
+    def eq(field, value)
+      build_predicate(field, value)
+    end
+
+    def neq(field, value)
+      none(eq(field, value))
+    end
+
+    def gt(field, value)
+      "{#{field}} > #{value}"
+    end
+
+    def gte(field, value)
+      "{#{field}} >= #{value}"
+    end
+
+    def lt(field, value)
+      "{#{field}} < #{value}"
+    end
+
+    def lte(field, value)
+      "{#{field}} <= #{value}"
+    end
+
+    def blank(field)
+      "{#{field}} = BLANK()"
+    end
+
+    def present(field)
+      none(blank(field))
+    end
+
+    def find(field, search_string)
+      "FIND(#{escape_string(search_string)}, {#{field}})"
+    end
+
+    def search(field, search_string)
+      "SEARCH(#{escape_string(search_string)}, {#{field}})"
+    end
+
+    # for multi-select fields (checks if array contains value)
+    def contains(field, value)
+      "FIND(#{escape_string(value.to_s)}, {#{field}})"
+    end
+
+    # check if multi-select contains ANY of the values
+    def contains_any(field, *values)
+      formulas = values.map { |v| contains(field, v) }
+      formulas.size == 1 ? formulas.first : any(*formulas)
+    end
+
+    # check if multi-select contains ALL of the values
+    def contains_all(field, *values)
+      formulas = values.map { |v| contains(field, v) }
+      formulas.size == 1 ? formulas.first : all(*formulas)
+    end
+  end
+end

data/lib/airrel/relation.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module Airrel
+  class Relation
+    include Enumerable
+
+    attr_reader :klass, :where_clause, :order_values, :limit_value, :offset_value
+
+    def initialize(klass)
+      @klass = klass
+      @where_clause = WhereClause.new
+      @order_values = []
+      @limit_value = nil
+      @offset_value = nil
+      @loaded = false
+      @records = nil
+    end
+
+    # chaining methods (return new relations)
+    
+    def where(conditions)
+      spawn.where!(conditions)
+    end
+
+    def where!(conditions)
+      @where_clause = @where_clause.merge(conditions)
+      self
+    end
+
+    def order(*args)
+      spawn.order!(*args)
+    end
+
+    def order!(*args)
+      @order_values += parse_order_args(args)
+      self
+    end
+
+    def limit(value)
+      spawn.limit!(value)
+    end
+
+    def limit!(value)
+      @limit_value = value
+      self
+    end
+
+    def offset(value)
+      spawn.offset!(value)
+    end
+
+    def offset!(value)
+      @offset_value = value
+      self
+    end
+
+    def reorder(*args)
+      spawn.reorder!(*args)
+    end
+
+    def reorder!(*args)
+      @order_values = parse_order_args(args)
+      self
+    end
+
+    # finder methods (execute queries)
+
+    def first(limit = nil)
+      if limit
+        # explicitly set limit to avoid loading more than needed
+        self.limit(limit).to_a
+      else
+        # only load 1 record
+        self.limit(1).to_a.first
+      end
+    end
+
+    def last(limit = nil)
+      # if no order specified, airtable returns oldest first by default
+      # so we need to explicitly reverse or it's meaningless
+      if @order_values.empty?
+        raise ArgumentError, "last requires an order to be specified (use .order(:created_at) or similar)"
+      end
+      
+      reversed = reverse_order
+      if limit
+        # only load what we need
+        reversed.limit(limit).to_a.reverse
+      else
+        # only load 1 record
+        reversed.limit(1).to_a.first
+      end
+    end
+
+    def find(id)
+      klass.find(id)
+    end
+
+    def find_by(conditions)
+      where(conditions).first
+    end
+
+    def find_by!(conditions)
+      # Raise error class that will be defined by the consumer (norairrecord)
+      error_class = defined?(Norairrecord::RecordNotFoundError) ? Norairrecord::RecordNotFoundError : StandardError
+      find_by(conditions) || raise(error_class, "Record not found")
+    end
+
+    def all
+      spawn
+    end
+
+    def to_a
+      load_records
+    end
+
+    alias to_ary to_a
+
+    def each(&block)
+      load_records.each(&block)
+    end
+
+    # batch iteration for large result sets
+    def find_each(batch_size: 100, &block)
+      find_in_batches(batch_size: batch_size) do |batch|
+        batch.each(&block)
+      end
+    end
+
+    def find_in_batches(batch_size: 100, &block)
+      current_offset = 0
+      
+      loop do
+        # create a new relation with limit and offset
+        batch_relation = spawn
+        batch_relation.instance_variable_set(:@limit_value, batch_size)
+        batch_relation.instance_variable_set(:@offset_value, current_offset)
+        
+        batch = batch_relation.to_a
+        break if batch.empty?
+        
+        yield batch
+        
+        break if batch.size < batch_size # last batch
+        current_offset += batch_size
+      end
+    end
+
+    def count
+      # airtable doesn't have a count API, but we can optimize by limiting fields
+      # or using exists? check for any?
+      load_records.size
+    end
+
+    def empty?
+      !any?
+    end
+
+    def any?
+      # optimize: only load 1 record to check existence
+      limit(1).load_records.any?
+    end
+    
+    def exists?
+      any?
+    end
+
+    # inspection
+
+    def inspect
+      entries = load_records.take(11).map!(&:inspect)
+      entries[10] = "..." if entries.size == 11
+
+      "#<#{self.class.name} [#{entries.join(', ')}]>"
+    end
+
+    def to_airtable
+      to_airtable_params
+    end
+    
+    def to_sql
+      to_airtable_params.inspect
+    end
+
+    # execution
+
+    def load
+      @records = exec_queries unless loaded?
+      self
+    end
+
+    def reload
+      reset
+      load
+    end
+
+    def loaded?
+      @loaded
+    end
+
+    def reset
+      @loaded = false
+      @records = nil
+      self
+    end
+
+    # disable automatic pagination for better control
+    def without_pagination
+      @paginate = false
+      self
+    end
+
+    protected
+
+    def spawn
+      clone.tap { |r| r.reset }
+    end
+
+    def load_records
+      load unless loaded?
+      @records
+    end
+
+    def exec_queries
+      @loaded = true
+      params = to_airtable_params
+      klass.records(**params)
+    end
+
+    def to_airtable_params
+      params = {}
+      
+      # filter
+      if @where_clause.any?
+        params[:filter] = @where_clause.to_airtable_formula
+      end
+
+      # sort
+      if @order_values.any?
+        params[:sort] = @order_values.map { |field, direction|
+          { field: field.to_s, direction: direction.to_s }
+        }
+      end
+
+      # limit
+      params[:max_records] = @limit_value if @limit_value
+      
+      # offset (airtable calls it offset in pagination)
+      params[:offset] = @offset_value if @offset_value
+      
+      # pagination control
+      params[:paginate] = @paginate if defined?(@paginate)
+
+      params
+    end
+
+    def reverse_order
+      spawn.tap do |r|
+        r.instance_variable_set(:@order_values, @order_values.map { |f, d| [f, d == :asc ? :desc : :asc] })
+      end
+    end
+
+    def parse_order_args(args)
+      args.flat_map do |arg|
+        case arg
+        when Hash
+          arg.map { |k, v| [k, normalize_direction(v)] }
+        when Symbol, String
+          [[arg, :asc]]
+        else
+          raise ArgumentError, "Invalid order argument: #{arg.inspect}"
+        end
+      end
+    end
+
+    def normalize_direction(direction)
+      case direction.to_s.downcase
+      when "asc", "ascending"
+        :asc
+      when "desc", "descending"
+        :desc
+      else
+        raise ArgumentError, "Invalid sort direction: #{direction}"
+      end
+    end
+  end
+end

data/lib/airrel/version.rb

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

data/lib/airrel/where_clause.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Airrel
+  class WhereClause
+    attr_reader :predicates
+
+    def initialize(predicates = [])
+      @predicates = predicates
+    end
+
+    def merge(conditions)
+      new_predicates = case conditions
+                       when Hash
+                         [FormulaBuilder.hash_to_formula(conditions)]
+                       when String
+                         [conditions]
+                       when Array
+                         conditions
+                       else
+                         [conditions.to_s]
+                       end
+
+      WhereClause.new(@predicates + new_predicates)
+    end
+
+    def any?
+      @predicates.any?
+    end
+
+    def to_airtable_formula
+      return nil if @predicates.empty?
+      return @predicates.first if @predicates.size == 1
+
+      "AND(#{@predicates.join(', ')})"
+    end
+
+    def inspect
+      @predicates.inspect
+    end
+  end
+end

data/lib/airrel.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "airrel/version"
+
+module Airrel
+  class Error < StandardError; end
+
+  autoload :Relation, "airrel/relation"
+  autoload :WhereClause, "airrel/where_clause"
+  autoload :FormulaBuilder, "airrel/formula_builder"
+end

data/sig/airrel.rbs

@@ -0,0 +1,4 @@
+module Airrel
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: airrel
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- 24c02
+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.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: chainable query interface for airtable formulas. it's like arel but AIR.
+  get it?
+email:
+- 163450896+24c02@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".idea/.gitignore"
+- ".idea/airrel.iml"
+- ".idea/misc.xml"
+- ".idea/modules.xml"
+- ".idea/vcs.xml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/demo.rb
+- lib/airrel.rb
+- lib/airrel/formula_builder.rb
+- lib/airrel/relation.rb
+- lib/airrel/version.rb
+- lib/airrel/where_clause.rb
+- sig/airrel.rbs
+homepage: https://github.com/24c02/airrel
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/24c02/airrel
+  source_code_uri: https://github.com/24c02/airrel
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: arel-like relational algebra for airtable
+test_files: []