fmrest 0.6.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 185e6173a3f500ea6fc8ad40df8f52ba538fdd8e3545537e947f19bfd79a3124
-  data.tar.gz: 89f5c6774366599e1baeef57662af77a3ceb5174abd58e6fd562c2aa29b85384
+  metadata.gz: 53c6e0d0260a3b825c031831136651a5f2252d8d0cebd8e2077919caf13d0fb6
+  data.tar.gz: 215b6d2a7735ce0a3109ae542f400aa0bee0d60f8808225fc4d77c52009c37d3
 SHA512:
-  metadata.gz: b7aa56e455da60fe7b571e2ce4d70ae118ca7ade57356cbdade2b0679f66d10e9d689a4bc3af5ddfb06dfc6d7395af35b0518c23077dbfb28a9e395b845e0841
-  data.tar.gz: c764ee1dc1962b3f6264ed6a4f26f0b88dd5c69cb62bca93dd269398c3e0d350ced4177b2842ce24136d7d0b84cb9a4809ce23ca1965b923fb91fc7b37ae39e1
+  metadata.gz: 4fdbb4dbc83ed0409e6680e8ffd028794ac01c07335ca43c95bd076e99359c17151b14634cb1a77bd41043ad104566ad5f820805de73d1f683aa957b02ad4fa5
+  data.tar.gz: 15966e4cc59a6bb9161f6edd6250beaa948d1c5c69ff911b3f2ca1eba2f782d79b8097c2038513e3ad4b84263b6b9e5f812cc7c37708a72f8a52d8db454b078f

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## Changelog
 
+### 0.10.0
+
+* Added `FmRest::StringDateAwareness` module to correct some issues when using
+  `FmRest::StringDate`
+* Added basic timezones support
+* Deprecated `class < FmRest::Spyke::Base(config_hash)` syntax in favor of
+  using `self.fmrest_config=`
+
+### 0.9.0
+
+* Added `FmRest::Spyke::Base.set_globals`
+
+### 0.8.0
+
+* Improved metadata when using `FmRest::Spyke::Model`. Metadata now uses
+  Struct/OpenStruct, so properties are accessible through `.property`, as well
+  as `[:property]`
+* Added batch-finders `.find_in_batches` and `.find_each` for
+* `FmRest::Spyke::Base`
+
+### 0.7.1
+
+* Made sure `Model.find_one` and `Model.find_some` work without needing to call
+  `Model.all` in between
+
+### 0.7.0
+
+* Added date coercion feature
+
 ### 0.6.0
 
 * Implemented session logout

data/README.md

@@ -105,6 +105,23 @@ You can also pass a `:log` option for basic request logging, see the section on
 `:username` is also aliased as `:account_name` to provide cross-compatibility
 with the ginjo-rfm gem.
 
+### Full list of available options
+
+Option              | Description                                | Format                      | Default
+--------------------|--------------------------------------------|-----------------------------|--------
+`:host`             | Hostname with optional port, e.g. `"example.com:9000"` | String          | None
+`:database`         |                                            | String                      | None
+`:username`         |                                            | String                      | None
+`:password`         |                                            | String                      | None
+`:ssl`              | SSL options to be forwarded to Faraday     | Faraday SSL options         | None
+`:proxy`            | Proxy options to be forwarded to Faraday   | Faraday proxy options       | None
+`:log`              | Log JSON responses to STDOUT               | Boolean                     | `false`
+`:coerce_dates`     | See section on [date fields](#date-fields) | Boolean \| `:hybrid` \| `:full` | `false`
+`:date_format`      | Date parsing format                        | String (FM date format)     | `"MM/dd/yyyy"`
+`:timestamp_format` | Timestmap parsing format                   | String (FM date format)     | `"MM/dd/yyyy HH:mm:ss"`
+`:time_format`      | Time parsing format                        | String (FM date format)     | `"HH:mm:ss"`
+`:timezone`         | The timezone for the FM server             | `:local` \| `:utc` \: `nil` | `nil`
+
 ### Default connection settings
 
 If you're only connecting to a single FM database you can configure it globally
@@ -122,6 +139,7 @@ FmRest.default_connection_settings = {
 This configuration will be used by default by `FmRest::V1.build_connection` as
 well as your models whenever you don't pass a configuration hash explicitly.
 
+
 ## Session token store
 
 By default fmrest-ruby will use a memory-based store for the session tokens.
@@ -178,7 +196,7 @@ FmRest.token_store = FmRest::TokenStore::Redis.new(redis: Redis.new, prefix: "my
 FmRest.token_store = FmRest::TokenStore::Redis.new(prefix: "my-fancy-prefix:", host: "10.0.1.1", port: 6380, db: 15)
 ```
 
-**NOTE:** redis-rb is not included as a gem dependency of fmrest-ruby, so you'll
+NOTE: redis-rb is not included as a gem dependency of fmrest-ruby, so you'll
 have to add it to your Gemfile.
 
 ### Moneta
@@ -215,9 +233,79 @@ FmRest.token_store = FmRest::TokenStore::Moneta.new(
 )
 ```
 
-**NOTE:** the moneta gem is not included as a dependency of fmrest-ruby, so
+NOTE: the moneta gem is not included as a dependency of fmrest-ruby, so
 you'll have to add it to your Gemfile.
 
+
+## Date fields
+
+Since the Data API uses JSON (wich doesn't provide a native date/time object),
+dates and timestamps are received in string format. By default fmrest-ruby
+leaves those string fields untouched, but it provides an opt-in feature to try
+to automatically "coerce" them into Ruby date objects.
+
+The connection option `:coerce_dates` controls this feature. Possible values
+are:
+
+* `:full` - whenever a string matches the given date/timestamp/time format,
+  convert them to `Date` or `DateTime` objects as appropriate
+* `:hybrid` or `true` - similar as above, but instead of converting to regular
+  `Date`/`DateTime` it converts strings to `FmRest::StringDate` and
+  `FmRest::StringDateTime`, "hybrid" classes provided by fmrest-ruby that
+  retain the functionality of `String` while also providing most the
+  functionality of `Date`/`DateTime` (more on this below)
+* `false` - disable date coercion entirely (default), leave original string
+  values untouched
+
+Enabling date coercion works with both basic fmrest-ruby connections and Spyke
+models (ORM).
+
+The connection options `:date_format`, `:timestamp_format` and `:time_format`
+control how to match and parse dates. You only need to provide these if you use
+a date/time localization different from American format (the default).
+
+Future versions of fmrest-ruby will provide better (and less heuristic) ways of
+specifying and/or detecting date fields (e.g. by requesting layout metadata or
+a DSL in model classes).
+
+### Hybrid string/date objects
+
+`FmRest::StringDate` and `FmRest::StringDateTime` are special classes that
+inherit from `String`, but internally parse and store a `Date` or `DateTime`,
+and delegate any methods not provided by `String` to those objects. In other
+words, they quack like a duck *and* bark like a dog.
+
+You can use these when you want fmrest-ruby to provide you with date objects,
+but you don't want to worry about date coercion of false positives (i.e. a
+string field that gets converted to `Date` because it just so matched the given
+date format).
+
+Be warned however that these classes come with a fair share of known gotchas
+(see GitHub wiki for more info). Some of those gothas can be removed by calling
+
+```ruby
+FmRest::StringDateAwareness.enable
+```
+
+Which will extend the core `Date` and `DateTime` classes to be aware of
+`FmRest::StringDate`, especially when calling `Date.===`, `Date.parse` or
+`Date._parse`.
+
+If you're working with ActiveRecord models this will also make them accept
+`FmRest::StringDate` values for date fields.
+
+### Timezones
+
+fmrest-ruby has basic timezone support. You can set the `:timezone` option in
+your connection settings to one of the following values:
+
+* `:local` - dates will be converted to your system local time offset (as
+  defined by `ENV["TZ"]`), or the timezone set by `Time.zone` if you're using
+  ActiveSupport
+* `:utc` - dates will be converted to UTC offset
+* `nil` - (default) ignore timezones altogether
+
+
 ## Spyke support (ActiveRecord-like ORM)
 
 [Spyke](https://github.com/balvig/spyke) is an ActiveRecord-like gem for
@@ -257,17 +345,6 @@ class Honeybee < FmRest::Spyke::Base
 end
 ```
 
-In this case you can pass the [`fmrest_config`](#modelfmrest_config) hash as an
-argument to `Base()`:
-
-```ruby
-class Honeybee < FmRest::Spyke::Base(host: "...", database: "...", username: "...", password: "...")
-end
-
-Honeybee.fmrest_config
-# => { host: "...", database: "...", username: "...", password: "..." }
-```
-
 All of Spyke's basic ORM operations work:
 
 ```ruby
@@ -490,7 +567,7 @@ Honeybee.limit(10)
 ```
 
 NOTE: You can also set a default limit value for a model class, see
-[Other notes on querying](#other-notes-on-querying).
+[other notes on querying](#other-notes-on-querying).
 
 You can also use `.limit` to set limits on portals:
 
@@ -662,15 +739,15 @@ the scope object:
 Honeybee.limit(10).sort(:name).find_some # => [<Honeybee...>, ...]
 ```
 
-If you want just a single result you can use `.find_one` instead (this will
+If you want just a single result you can use `.first` instead (this will
 force `.limit(1)`):
 
 ```ruby
-Honeybee.query(name: "Hutch").find_one # => <Honeybee...>
+Honeybee.query(name: "Hutch").first # => <Honeybee...>
 ```
 
 If you know the id of the record you should use `.find(id)` instead of
-`.query(id: id).find_one` (so that the sent request is
+`.query(id: id).first` (so that the sent request is
 `GET ../:layout/records/:id` instead of `POST ../:layout/_find`).
 
 ```ruby
@@ -681,6 +758,52 @@ Note also that if you use `.find(id)` your `.query()` parameters (as well as
 limit, offset and sort parameters) will be discarded as they're not supported
 by the single record endpoint.
 
+
+### Finding records in batches
+
+Sometimes you want to iterate over a very large number of records to do some
+processing, but requesting them all at once would result in one huge request to
+the Data API, and loading too many records in memory all at once.
+
+To mitigate this problem you can use `.find_in_batches` and `.find_each`. If
+you've used ActiveRecord you're probably familiar with how they operate:
+
+```ruby
+# Find records in batches of 100 each
+Honeybee.query(hive: "Queensville").find_in_batches(batch_size: 100) do |batch|
+  dispatch_bees(batch)
+end
+
+# Iterate over all records using batches
+Honeybee.query(hive: "Queensville").find_each(batch_size: 100) do |bee|
+  bee.dispatch
+end
+```
+
+`.find_in_batches` yields collections of records (batches), while `.find_each`
+yields individual records, but using batches behind the scenes.
+
+Both methods accept a block-less form in which case they return an
+`Enumerator`:
+
+```ruby
+batch_enum = Honeybee.find_in_batches
+
+batch = batch_enum.next # => Spyke::Collection
+
+batch_enum.each do |batch|
+  process_batch(batch)
+end
+
+record_enum = Honeybee.find_each
+
+record_enum.next # => Honeybee
+```
+
+NOTE: By its nature, batch processing is subject to race conditions if other
+processes are modifying the database.
+
+
 ### Container fields
 
 You can define container fields on your model class with `container`:
@@ -718,6 +841,7 @@ bee.photo.upload(filename_or_io) # Upload a file to the container
 * `:content_type` - The MIME content type to use (defaults to
   `application/octet-stream`)
 
+
 ### Script execution
 
 The Data API allows running scripts as part of many types of requests.
@@ -805,7 +929,7 @@ separately, under their matching key.
 ```ruby
 bee.save(script: { presort: "My Presort Script", after: "My Script" })
 
-Honeybee.last_request_metadata[:script]
+Honeybee.last_request_metadata.script
 # => { after: { result: "oh hi", error: "0" }, presort: { result: "lo", error: "0" } }
 ```
 
@@ -819,7 +943,7 @@ is performed on that scope.
 
 ```ruby
 # Find one Honeybee record executing a presort and after script
-Honeybee.script(presort: ["My Presort Script", "parameter"], after: "My Script").find_one
+Honeybee.script(presort: ["My Presort Script", "parameter"], after: "My Script").first
 ```
 
 The model class' `.last_request_metadata` will be set in case you need to get the result.
@@ -830,6 +954,33 @@ same metadata hash with script execution results. Note that this does not apply
 to retrieving single records, in that case you'll have to use
 `.last_request_metadata`.
 
+
+### Setting global field values
+
+You can call `.set_globals` on any `FmRest::Spyke::Base` model to set glabal
+field values on the database that model is configured for.
+
+You can pass it either a hash of fully qualified field names
+(table_name::field_name), or 1-level-deep nested hashes, with the outer being a
+table name and the inner keys being the field names:
+
+```ruby
+Honeybee.set_globals(
+  "beeTable::myVar"      => "value",
+  "beeTable::myOtherVar" => "also a value"
+)
+
+# Equivalent to the above example
+Honeybee.set_globals(beeTable: { myVar: "value", myOtherVar: "also a value" })
+
+# Combined
+Honeybee.set_globals(
+  "beeTable::myVar" => "value",
+  beeTable: { myOtherVar: "also a value" }
+)
+```
+
+
 ## Logging
 
 If using fmrest-ruby + Spyke in a Rails app pretty log output will be set up
@@ -883,7 +1034,7 @@ FM Data API reference: https://fmhelp.filemaker.com/docs/18/en/dataapi/
 | Log in using OAuth                  | No                            | No                               |
 | Log in to an external data source   | No                            | No                               |
 | Log in using a FileMaker ID account | No                            | No                               |
-| Log out                             | Yes                           | Yes
+| Log out                             | Yes                           | Yes                              |
 | Get product information             | Manual*                       | No                               |
 | Get database names                  | Manual*                       | No                               |
 | Get script names                    | Manual*                       | No                               |
@@ -898,25 +1049,12 @@ FM Data API reference: https://fmhelp.filemaker.com/docs/18/en/dataapi/
 | Get container data                  | Manual*                       | Yes                              |
 | Upload container data               | Manual*                       | Yes                              |
 | Perform a find request              | Manual*                       | Yes                              |
-| Set global field values             | Manual*                       | No                               |
+| Set global field values             | Manual*                       | Yes
 | Run a script                        | Manual*                       | Yes                              |
 | Run a script with another request   | Manual*                       | Yes                              |
 
 \* You can manually supply the URL and JSON to a `FmRest` connection.
 
-## TODO
-
-- [ ] Support for FM18 features
-- [ ] Better/simpler-to-use core Ruby API
-- [ ] Better API documentation and README
-- [ ] Oauth support
-- [x] Support for portal limit and offset
-- [x] More options for token storage
-- [x] Support for container fields
-- [x] Optional logging
-- [x] FmRest::Spyke::Base class for single inheritance (as alternative for mixin)
-- [x] Specs
-- [x] Support for portal data
 
 ## Gem development
 
@@ -931,6 +1069,7 @@ release a new version, update the version number in `version.rb`, and then run
 git commits and tags, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
+
 ## Contributing
 
 Bug reports and pull requests are welcome. This project is intended to be a
@@ -938,20 +1077,16 @@ safe, welcoming space for collaboration, and contributors are expected to
 adhere to the [Contributor Covenant](http://contributor-covenant.org) code of
 conduct.
 
+
 ## License
 
 The gem is available as open source under the terms of the
 [MIT License](https://opensource.org/licenses/MIT).
 See [LICENSE.txt](LICENSE.txt).
 
+
 ## Disclaimer
 
 This project is not sponsored by or otherwise affiliated with FileMaker, Inc,
 an Apple subsidiary. FileMaker is a trademark of FileMaker, Inc., registered in
 the U.S. and other countries.
-
-## Code of Conduct
-
-Everyone interacting in the fmrest-ruby project’s codebases, issue trackers,
-chat rooms and mailing lists is expected to follow the [code of
-conduct](CODE_OF_CONDUCT.md).

data/lib/fmrest/spyke.rb

@@ -8,7 +8,7 @@ rescue LoadError => e
 end
 
 require "fmrest"
-require "fmrest/spyke/json_parser"
+require "fmrest/spyke/spyke_formatter"
 require "fmrest/spyke/model"
 require "fmrest/spyke/base"
 

data/lib/fmrest/spyke/base.rb

@@ -8,6 +8,8 @@ module FmRest
 
     class << self
       def Base(config = nil)
+        warn "[DEPRECATION] Inheriting from `FmRest::Spyke::Base(config)` is deprecated and will be removed, inherit from `FmRest::Spyke::Base` (without arguments) and use `fmrest_config=` instead"
+
         if config
           return Class.new(::FmRest::Spyke::Base) do
                    self.fmrest_config = config

data/lib/fmrest/spyke/model.rb

@@ -7,6 +7,7 @@ require "fmrest/spyke/model/serialization"
 require "fmrest/spyke/model/associations"
 require "fmrest/spyke/model/orm"
 require "fmrest/spyke/model/container_fields"
+require "fmrest/spyke/model/global_fields"
 require "fmrest/spyke/model/http"
 require "fmrest/spyke/model/auth"
 
@@ -22,6 +23,7 @@ module FmRest
       include Associations
       include Orm
       include ContainerFields
+      include GlobalFields
       include Http
       include Auth
 

data/lib/fmrest/spyke/model/associations.rb

@@ -10,7 +10,7 @@ module FmRest
 
         included do
           # Keep track of portal options by their FM keys as we could need it
-          # to parse the portalData JSON in JsonParser
+          # to parse the portalData JSON in SpykeFormatter
           class_attribute :portal_options, instance_accessor: false, instance_predicate: false
 
           # class_attribute supports a :default option since ActiveSupport 5.2,
@@ -37,7 +37,7 @@ module FmRest
           def has_portal(name, options = {})
             create_association(name, Portal, options)
 
-            # Store options for JsonParser to use if needed
+            # Store options for SpykeFormatter to use if needed
             portal_key = options[:portal_key] || name
             self.portal_options = portal_options.merge(portal_key.to_s => options.dup.merge(name: name.to_s)).freeze
 

data/lib/fmrest/spyke/model/connection.rb

@@ -4,10 +4,19 @@ module FmRest
   module Spyke
     module Model
       module Connection
-        extend ::ActiveSupport::Concern
+        extend ActiveSupport::Concern
 
         included do
-          class_attribute :fmrest_config, instance_accessor: false, instance_predicate: false
+          class_attribute :fmrest_config, instance_writer: false, instance_predicate: false
+
+          # Overrides the fmrest_config reader created by class_attribute so we
+          # can default set the default at call time.
+          #
+          # This method gets overwriten in subclasses if self.fmrest_config= is
+          # called.
+          define_singleton_method(:fmrest_config) do
+            FmRest.default_connection_settings
+          end
 
           class_attribute :faraday_block, instance_accessor: false, instance_predicate: false
           class << self; private :faraday_block, :faraday_block=; end
@@ -38,15 +47,25 @@ module FmRest
           private
 
           def fmrest_connection
-            @fmrest_connection ||= FmRest::V1.build_connection(fmrest_config || FmRest.default_connection_settings) do |conn|
-              faraday_block.call(conn) if faraday_block
-
-              # Pass the class to JsonParser's initializer so it can have
-              # access to extra context defined in the model, e.g. a portal
-              # where name of the portal and the attributes prefix don't match
-              # and need to be specified as options to `portal`
-              conn.use FmRest::Spyke::JsonParser, self
-            end
+            @fmrest_connection ||=
+              begin
+                config = fmrest_config
+
+                FmRest::V1.build_connection(config) do |conn|
+                  faraday_block.call(conn) if faraday_block
+
+                  # Pass the class to SpykeFormatter's initializer so it can have
+                  # access to extra context defined in the model, e.g. a portal
+                  # where name of the portal and the attributes prefix don't match
+                  # and need to be specified as options to `portal`
+                  conn.use FmRest::Spyke::SpykeFormatter, self
+
+                  conn.use FmRest::V1::TypeCoercer, config
+
+                  # FmRest::Spyke::JsonParse expects symbol keys
+                  conn.response :json, parser_options: { symbolize_names: true }
+                end
+              end
           end
         end
       end