airrecord 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e5fbb9f72ea43cf78e32e2a6dbfb0138b5732f3171cfe4416630b84e26d643e
-  data.tar.gz: b232483322295e61cd75a09cb56a04a67e673b01ecd27b8aee551e54b91ee45e
+  metadata.gz: 1224190a9be6b7349af9ab26640516b13961d88bc3b42d188c5879777e90fe04
+  data.tar.gz: 119beef65efdc6d110cc4e5c1865e92308c3e2a043b0e2e853484480488307d2
 SHA512:
-  metadata.gz: ce0d4a831cd0e2de8d5725b7ad66298ed061d920ee713b2bb0a54bde1c17e5b123e5edc00760b832c1f36ae2f3586bf1cc218fb4982bea265fbc6703c897d358
-  data.tar.gz: 115ab85c06ad0934d11e9f8d1a246a155f374300f60cf4c32019c3624e72794ea01d659464649b440ff793296ac2ce9b757feea3d41644fcf10b33770da10ead
+  metadata.gz: 577ae326c6cb761f7557c9b75a6a3e1fc46373aba67b6300430d9d0efac54e21eea30885237d40c233ef1c33f2d4bd3766984f0697211ebbff8bd6d7af160bcf
+  data.tar.gz: 11c1ce89e39a1f0e66f8c3b34cbf53eb21f69a2e91f98ae5460af85f1df2b62e37a1c01940263da8dba7c0499e822f8a3280ef55345cc93f76401c2d36579252

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 1.0.0 (unreleased)
+
+* 1.0.0 will introduce breaking changes, including removing support for symbols. To update, change snake-case symbols to their correct column names (for example, `record["First Name"]` instead of `record[:first_name]`)
+
+# 0.2.5
+
+* Deprecate using symbols instead of strings
+
 # 0.2.4
 
 * Don't flag as dirty if change is equal

data/README.md

@@ -20,7 +20,7 @@ class Tea < Airrecord::Table
   self.base_key = "app1"
   self.table_name = "Teas"
 
-  has_many :brews, class: 'Brew', column: "Brews"
+  has_many "Brews", class: 'Brew', column: "Brews"
 
   def self.chinese
     all(filter: '{Country} = "China"')
@@ -31,11 +31,11 @@ class Tea < Airrecord::Table
   end
 
   def location
-    [self[:village], self[:country], self[:region]].compact.join(", ")
+    [self["Village"], self["Country"], self["Region"]].compact.join(", ")
   end
 
   def green?
-    self[:type] == "Green"
+    self["Type"] == "Green"
   end
 end
 
@@ -43,22 +43,22 @@ class Brew < Airrecord::Table
   self.base_key = "app1"
   self.table_name = "Brews"
 
-  belongs_to :tea, class: 'Tea', column: 'Tea'
+  belongs_to "Tea", class: 'Tea', column: 'Tea'
 
   def self.hot
     all(filter: "{Temperature} > 90")
   end
 
   def done_brewing?
-    self[:created_at] + self[:duration] > Time.now
+    self["Created At"] + self["Duration"] > Time.now
   end
 end
 
 teas = Tea.all
 tea = teas.first
-tea[:country] # access atribute
+tea["Country"] # access atribute
 tea.location # instance methods
-tea[:brews] # associated brews
+tea["Brews"] # associated brews
 ```
 
 A short-hand API for definitions and more ad-hoc querying is also available:
@@ -67,7 +67,7 @@ A short-hand API for definitions and more ad-hoc querying is also available:
 Tea = Airrecord.table("api_key", "app_key", "Teas")
 
 Tea.all.each do |record|
-  puts "#{record.id}: #{record[:name]}"
+  puts "#{record.id}: #{record["Name"]}"
 end
 
 Tea.find("rec3838")
@@ -107,7 +107,7 @@ class Tea < Airrecord::Table
   self.table_name = "Teas"
 
   def location
-    [self[:village], self[:country], self[:region]].compact.join(", ")
+    [self["Village"], self["Country"], self["Region"]].compact.join(", ")
   end
 end
 ```
@@ -130,13 +130,13 @@ To use `filterbyFormula` to filter returned records:
 
 ```ruby
 # Retrieve all teas from China
-Tea.all(filter: '{Country} == "China"')
+Tea.all(filter: '{Country} = "China"')
 
 # Retrieve all teas created in the past week
 Tea.all(filter: "DATETIME_DIFF(CREATED_TIME(), TODAY(), 'days') < 7")
 
 # Retrieve all teas that don't have a country defined
-Tea.all(filter: "{Country} == \"\"")
+Tea.all(filter: "{Country} = \"\"")
 ```
 
 This filtering can, of course, also be done in Ruby directly after calling
@@ -158,17 +158,16 @@ The `sort` option can be used to sort results returned from the Airtable API.
 
 ```ruby
 # Sort teas by the Name column in ascending order
-Tea.all(sort: { Name: "asc" })
+Tea.all(sort: { "Name" => "asc" })
 
 # Sort teas by Type (green, black, oolong, ..) in descending order
-Tea.all(sort: { Type: "desc" })
+Tea.all(sort: { "Type" => "desc" })
 
 # Sort teas by price in descending order
-Tea.all(sort: { Price: "desc" })
+Tea.all(sort: { "Price" => "desc" })
 ```
 
-Note again that the key _must_ be the full column name. Snake-cased variants do
-not work here.
+Note again that the key _must_ be the full column name.
 
 As mentioned above, by default Airrecord will return results from all pages.
 This can be slow if you have 1000s of records. You may wish to use the `view`
@@ -181,7 +180,7 @@ calls. Airrecord will _always_ fetch the maximum possible amount of records
 Tea.all(paginate: false)
 
 # Give me only the most recent teas
-Tea.all(sort: { "Created At": "desc" }, paginate: false)
+Tea.all(sort: { "Created At" => "desc" }, paginate: false)
 ```
 
 ### Creating
@@ -192,16 +191,15 @@ Creating a new record is done through `#create`.
 tea = Tea.new("Name" => "Feng Gang", "Type" => "Green", "Country" => "China")
 tea.create # creates the record
 tea.id # id of the new record
-tea[:name] # "Feng Gang", accessed through snake-cased name
+tea["Name"] # "Feng Gang"
 ```
 
-Note that when instantiating the new record the column names (keys of the passed
-named parameters) need to match the exact column names in Airtable, otherwise
-Airrecord will throw an error that no column matches it.
+Note that column names need to match the exact column names in Airtable,
+otherwise Airrecord will throw an error that no column matches it.
 
-In the future I hope to provide more convient names for these (snake-cased),
-however, this is error-prone without a proper schema API from Airtable which has
-still not been released.
+_Earlier versions of airrecord provided methods for snake-cased column names
+and symbols, however this proved error-prone without a proper schema API from
+Airtable which has still not been released._
 
 ### Updating
 
@@ -210,11 +208,7 @@ Airtable with `#save`.
 
 ```ruby
 tea = Tea.find("someid")
-tea[:name] = "Feng Gang Organic"
-
-# Since the Village column is not set, we do not have access to a snake-cased
-# variant since the mapping is not determined. For all we know, the correct column
-# name could be "VilLlaGe". Therefore, we must use the proper column name.
+tea["Name"] = "Feng Gang Organic"
 tea["Village"] = "Feng Gang"
 
 tea.save # persist to Airtable
@@ -236,7 +230,7 @@ providing the URL. Unfortunately, it does not allow uploading directly.
 
 ```ruby
 word = World.find("cantankerous")
-word["Pronounciation"] = [{url: "https://s3.ca-central-1.amazonaws.com/word-pronunciations/cantankerous.mp3}]
+word["Pronounciation"] = [{url: "https://s3.ca-central-1.amazonaws.com/word-pronunciations/cantankerous.mp3"}]
 word.save
 ```
 
@@ -274,14 +268,14 @@ class Tea < Airrecord::Table
   self.base_key = "app1"
   self.table_name = "Teas"
 
-  has_many :brews, class: 'Brew', column: "Brews"
+  has_many "Brews", class: 'Brew', column: "Brews"
 end
 
 class Brew < Airrecord::Table
   self.base_key = "app1"
   self.table_name = "Brews"
 
-  belongs_to :tea, class: 'Tea', column: 'Tea'
+  belongs_to "Tea", class: 'Tea', column: 'Tea'
 end
 ```
 
@@ -296,14 +290,14 @@ To retrieve records from associations to a record:
 
 ```ruby
 tea = Tea.find('rec84')
-tea[:brews] # brews associated with tea
+tea["Brews"] # brews associated with tea
 ```
 
 This in turn works the other way too:
 
 ```ruby
 brew = Brew.find('rec849')
-brew[:tea] # the associated tea instance
+brew["Tea"] # the associated tea instance
 ```
 
 ### Creating associated records
@@ -313,7 +307,8 @@ You can easily associate records with each other:
 ```ruby
 tea = Tea.find('rec849829')
 # This will create a brew associated with the specific tea
-Brew.create("Tea" => tea, "Temperature" => "80", "Time" => "4m", "Rating" => "5")
+brew = Brew.new("Tea" => tea, "Temperature" => "80", "Time" => "4m", "Rating" => "5")
+brew.create
 ```
 
 ### Ad-hoc API
@@ -327,20 +322,12 @@ around.
 Tea = Airrecord.table("api_key", "app_key", "Teas")
 
 Tea.all.each do |record|
-  puts "#{record.id}: #{record[:name]}"
+  puts "#{record.id}: #{record["Name"]}"
 end
 
 Tea.find("rec3838")
 ```
 
-### Snake-cased helper methods
-
-When retrieving an existing record from Airtable, snake-cased helper names are
-available to index attributes. These are _only_ available on retrieved records,
-and _only_ if the column was set. If it's `nil`, it will not exist. That means
-if you want to set column that has a `nil` value for a column type, you'll have
-to fully type it out.
-
 ### Production Middlewares
 
 For production use-cases, it's worth considering adding retries and circuit

data/airrecord.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = %q{Airtable client}
   spec.description   = %q{Airtable client to make Airtable interactions a breeze}
-  spec.homepage      = "https://github.com/sirupsen/airtable"
+  spec.homepage      = "https://github.com/sirupsen/airrecord"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

data/lib/airrecord/table.rb

@@ -8,10 +8,24 @@ module Airrecord
   # Right now I bet there's a bunch of bugs around similar named column keys (in
   # terms of capitalization), it's inconsistent and non-obvious that `create`
   # doesn't use the same column keys as everything else.
+  #
+  # 2018-11-01
+  # deprecate_symbols: long-term plan is to force everyone to use raw strings,
+  # to match the Airtable behavior. For now we'll just warn when using symbols
+  # with a deprecation notice.
+
   class Table
+    def deprecate_symbols
+      self.class.deprecate_symbols
+    end
+
     class << self
       attr_accessor :base_key, :table_name, :api_key, :associations
 
+      def deprecate_symbols
+        warn Kernel.caller.first + ": warning: Using symbols with airrecord is deprecated."
+      end
+      
       def client
         @@clients ||= {}
         @@clients[api_key] ||= Client.new(api_key)
@@ -20,7 +34,7 @@ module Airrecord
       def has_many(name, options)
         @associations ||= []
         @associations << {
-          field: name.to_sym,
+          field: name.to_sym, # todo: deprecate_symbols
         }.merge(options)
       end
 
@@ -49,6 +63,7 @@ module Airrecord
 
         if sort
           options[:sort] = sort.map { |field, direction|
+            deprecate_symbols if field.is_a? Symbol
             { field: field.to_s, direction: direction }
           }
         end
@@ -106,8 +121,10 @@ module Airrecord
       value = nil
 
       if fields[key]
+        deprecate_symbols if key.is_a? Symbol
         value = fields[key]
       elsif column_mappings[key]
+        deprecate_symbols if key.is_a? Symbol
         value = fields[column_mappings[key]]
       end
 
@@ -125,11 +142,13 @@ module Airrecord
     end
 
     def []=(key, value)
+      deprecate_symbols if key.is_a? Symbol
       if fields[key]
         return if fields[key] == value # no-op
         @updated_keys << key
         fields[key] = value
       elsif column_mappings[key]
+        deprecate_symbols
         return if fields[column_mappings[key]] == value # no-op
         @updated_keys << column_mappings[key]
         fields[column_mappings[key]] = value
@@ -196,19 +215,25 @@ module Airrecord
           value = [ value ] unless value.is_a?(Enumerable)
           assocs = value.map { |assoc|
             assoc.respond_to?(:id) ? assoc.id : assoc
-          }               
+          }
           [key, assocs]
         else
           [key, value]
         end
         }]
     end
-    
+
     def ==(other)
       self.class == other.class &&
         serializable_fields == other.serializable_fields
     end
 
+    alias_method :eql?, :==
+
+    def hash
+      serializable_fields.hash
+    end
+
     protected
 
     def association(key)
@@ -221,15 +246,15 @@ module Airrecord
 
     def fields=(fields)
       @updated_keys = []
-      @column_mappings = Hash[fields.keys.map { |key| [underscore(key), key] }]
+      @column_mappings = Hash[fields.keys.map { |key| [underscore(key), key] }] # TODO remove (deprecate_symbols)
       @fields = fields
     end
 
-    def self.underscore(key)
+    def self.underscore(key) # TODO remove (deprecate_symbols)
       key.to_s.strip.gsub(/\W+/, "_").downcase.to_sym
     end
 
-    def underscore(key)
+    def underscore(key) # TODO remove (deprecate_symbols)
       self.class.underscore(key)
     end
 
@@ -249,6 +274,7 @@ module Airrecord
         value
       end
     end
+
   end
 
   def self.table(api_key, base_key, table_name)

data/lib/airrecord/version.rb

@@ -1,3 +1,3 @@
 module Airrecord
-  VERSION = "0.2.4"
+  VERSION = "0.2.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: airrecord
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - Simon Eskildsen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-15 00:00:00.000000000 Z
+date: 2018-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -115,7 +115,7 @@ files:
 - lib/airrecord/client.rb
 - lib/airrecord/table.rb
 - lib/airrecord/version.rb
-homepage: https://github.com/sirupsen/airtable
+homepage: https://github.com/sirupsen/airrecord
 licenses:
 - MIT
 metadata: {}