graphql-activerecord 0.8.0.pre.alpha1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3a18a5d24f96c94faa11072b275606e9160f6ecb
-  data.tar.gz: fc4d9b955200937dddc40a03ed00ba8f063e5eb7
+  metadata.gz: 6cc30cdefc71e9c7880e6f49ed3a4817f69ab3ca
+  data.tar.gz: 25d052ad19f4b048ab4498afadf0c4472b1ec974
 SHA512:
-  metadata.gz: a34c305a0ccd72210795eb982206e53e6bf3c094339bc0bf62ab501eea5f41b62ed2860caa06b12c194fae102e64d9e71946bd7c68c4d4a4c73d5c122fd31e39
-  data.tar.gz: f1d52a786acc02b0e6f9c406ea4a1cebaa23c29d2760a3a5bc02122ff3b68475d2b95f8eb70409323fe35736e1dca9bafa67d198d2ac74a380d5f931c6ab6e25
+  metadata.gz: e5722b4fa3cd5a4dc07b868569e37213ba0c8552b5a17057c7859423c2ca8c9ad846796b6efa04f4bf98ec616d21f3bde880234a3655fd6b4f68ba0dd63b698f
+  data.tar.gz: 3c9ef697f0f9f16db19b80eb9bcdfeda3ad71bb46371cb497875b48a3bbdc8da159c6ef15f58e5bf612d7684d68ceea5dd58dbd7c23c7d8eb05fcbd7c091dfd1

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.7.2
+
+### Breaking Changes
+- Changed models are no longer reloaded when you call `save!` on a mutator

data/README.md

@@ -1,10 +1,104 @@
 # GraphQL::Models
 
-TODO: Write this. I promise, one day, I really will write some stuff here to describe this gem.
+This gem is designed to help you map Active Record models to GraphQL types, both for queries and mutations, using the [`graphql`](https://github.com/rmosolgo/graphql-ruby) gem. It assumes that you're using Rails, Relay and PostgreSQL.
+
+It extends the `define` methods for GraphQL object types to provide a simple syntax for adding fields that access attributes
+on your model. It also makes it easy to "flatten" models together across associations, or to create fields that just access
+the association as a separate object type.
+
+In the process, this gem also converts `snake_case` attribute names into `camelCase` field names. When you go to build a mutation
+using this gem, it knows how to revert that process, even in cases where the conversion isn't symmetric.
+
+Here's an example:
+```ruby
+EmployeeGraph = GraphQL::ObjectType.define do
+  name "Employee"
+
+  # Looks for an Active Record model called "Employee"
+  backed_by_model :employee do
+
+    # The gem will look at the data type for the attributes, and map them to GraphQL types
+    attr :title
+    attr :salary
+
+    # You can flatten fields across associations to simplify the schema. In this example, an
+    # Employee belongs to a Person.
+    proxy_to :person do
+      # These fields get converted to camel case (ie, firstName, lastName) on the schema
+      attr :first_name
+      attr :last_name
+      attr :email
+
+      # You can also provide the association itself as an object field. In this example, a
+      # Person has one Address. The gem assumes that the corresponding GraphQL object type
+      # is called "AddressGraph".
+      has_one :address
+    end
+  end
+end
+```
+
+You can also build a corresponding mutation, using a very similar syntax. Mutations are more complicated, since they involve
+not just changing the data, but also validating it. Here's an example:
+```ruby
+UpdateEmployeeMutation = GraphQL::Relay::Mutation.define do
+  name "UpdateEmployee"
+
+  input_field :id, !types.ID
+
+  # For mutations, you create a mutator definition. This will add the input fields to your
+  # mutation, and also return an object that you'll use in the resolver to perform the mutation.
+  # The parameters you pass are explained below.
+  mutator_definition = GraphQL::Models.define_mutator(self, Employee, null_behavior: :leave_unchanged) do
+    attr :title
+    attr :salary
+
+    proxy_to :person do
+      attr :first_name
+      attr :last_name
+      attr :email
+
+      # You can use nested input object types to allow making changes across associations with a single mutation.
+      # Unlike querying, you need to be explicit about what fields on associated objects can be changed.
+      nested :address, null_behavior: :set_null do
+        attr :line_1
+        attr :line_2
+        attr :city
+        attr :state
+        attr :postal_code  
+      end
+    end
+  end
+
+  return_field :employee, EmployeeGraph
+
+  resolve -> (inputs, context) {
+    # Fetch (or create) the model that the mutation should change
+    model = Employee.find(inputs[:id])
+
+    # Get the mutator
+    mutator = mutator_definition.mutator(model, inputs, context)
+
+    # Call `apply_changes` to update the models. This does not save the changes to the database yet:
+    mutator.apply_changes
+
+    # Let's validate the changes. This will raise an exception that can be caught in middleware:
+    mutator.validate!
+
+    # Verify that the user is allowed to make the changes. Explained below:
+    mutator.authorize!
+
+    # If that passes, let's save the changes and return the result
+    mutator.save!
+
+    { employee: model }
+  }
+end
+```
 
 ## Installation
 
-Add this line to your application's Gemfile:
+To get started, you should add this line to your application's Gemfile:
 
 ```ruby
 gem 'graphql-activerecord'
@@ -12,25 +106,223 @@ gem 'graphql-activerecord'
 
 And then execute:
 
-    $ bundle
+    $ bundle install
+
+Next, you need to supply a few callbacks. I put these inside of `config/initializers` in my Rails app:
+```ruby
+# This proc takes a Relay global ID, and returns the Active Record model. It can be the same as
+# the `object_to_id` proc that you use for global node identification:
+GraphQL::Models.model_from_id = -> (id, context) {
+  model_type, model_id = NodeHelpers.decode_id(id)
+  model_type.find(model_id)
+}
+
+# This proc essentially reverses that process:
+GraphQL::Models.id_for_model = -> (model_type_name, model_id) {
+  NodeHelpers.encode_id(model_type_name, model_id)
+}
+
+# This proc is used when you're authorizing changes to a model inside of a mutator:
+GraphQL::Models.authorize = -> (context, action, model) {
+  # Action will be either :create, :update, or :destroy
+  # Raise an exception if the action should not proceed
+  user = context['user']
+  model.authorize_changes!(action, user)
+}
+```
+
+Finally, you need to set a few options on your schema:
+```ruby
+Schema.query_execution_strategy = GraphQL::Batch::ExecutionStrategy
+Schema.mutation_execution_strategy = GraphQL::Batch::MutationExecutionStrategy
+Schema.middleware << GraphQL::Models::Middleware.new
+```
+
+## Other notes
+
+The code in this gem was originally part of our main codebase, before we extracted it. So there are a few places where some of
+of our own conventions leak through. Eventually, I'd like to clean these up, but you'll have to live with them for now.
 
-Or install it yourself as:
+### Database compatibility
 
-    $ gem install graphql-activerecord
+This gem uses `graphql-batch` to optimize loading associated models in your graph, so that you don't end up with lots of N+1
+queries. It tries to do that in a way that preserves things like scopes that change the order or filter the rows retrieved.
+
+Unfortunately, that means that it needs to build some custom SQL expressions, and they might not be compatible with every
+database engine. They should work correctly on PostgreSQL.
+
+### Naming of GraphQL types
+
+If your model is named `Something`, this gem assumes that the corresponding object type is called `SomethingGraph`, and it uses
+the Rails `String#constantize` method to find it. This is mainly needed when you're specifying associations on your object types.
+
+### Global ID's
+
+When you use the `has_one` or `has_many_array` helpers to output associations, the gem will also include a field that only
+returns the global ID's of the models. To do that, it calls a method named `gid` on the model. You'll need to provide that method
+for those fields to work. We do that by defining it in a concern that we include into `ActiveRecord::Base`:
+
+```ruby
+module ActiveRecordExtensions
+  extend ActiveSupport::Concern
+
+  def gid
+    NodeHelpers.encode_id(self.class.name, self.id)
+  end
+end
+
+ActiveRecord::Base.send(:include, ActiveRecordExtensions)
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### GraphQL Enum's
+
+Active Record allows you to define enum fields on your models. They're stored as integers, but treated as strings in your app.
+You can use a helper to automatically build GraphQL enum types for them:
+
+```ruby
+class MyModel < ActiveRecord::Base
+  enum status: [:active, :inactive]
+  graphql_enum :status
+end
+
+# You can access the auto-built type if you need to:
+MyModel.graphql_enum_types[:status]
+
+# When you use it inside of your GraphQL schema, it'll know to use the GraphQL enum type:
+MyModelGraph = GraphQL::ObjectType.define do
+  backed_by_model :my_model do
+    attr :status
+  end
+end
+```
+
+You can also manually specify the type to use, if you just want the type mapping behavior:
+```ruby
+  graphql_enum :status, type: StatusEnum
+```
+
+### Association helpers
+There are three helpers that you can use to build fields for associated models:
+
+- `has_one` can be used for either `belongs_to` or `has_one` associations
+- `has_many_array` will return all of the associated models as a GraphQL list
+- `has_many_connection` will return a paged connection of the associated models
+
+### Fields inside of `proxy_to` blocks
+You can also define ordinary fields inside of `proxy_to` blocks. When you do that, your field will receive the associated model
+as the object, instead of the original model. This is meant to allow you to take advantage of the optimized association loading
+that the gem provides:
+
+```ruby
+backed_by_model :employee do
+  proxy_to :person do
+    field :someCustomField, types.Int do
+      resolve -> (model, args, context) {
+        # model is an instance of Person, not Employee
+      }
+    end
+  end
+end
+```
+
+### Defining Mutations
+
+When you define a mutation, there are a few parameters that you need to pass. Here's an example:
+
+```ruby
+mutator_definition = GraphQL::Models.define_mutator(self, Employee, null_behavior: :leave_unchanged)
+```
+
+The parameters are:
+- The definer object: it needs this so that it can create the input fields. You should always pass `self` for this parameter.
+- The model class that the mutator is changing: it needs this so that it can map attributes to the correct input types.
+- `null_behavior`: this lets you choose how null values are treated. It's explained below.
+
+#### Virtual Attributes
+In your mutator, you can specify virtual attributes on your model, you just need to provide the type:
+```ruby
+attr :some_fake_attribute, type: types.String
+```
+
+#### null_behavior
+
+When you build a mutation, you have two options that control how null values are treated. They are meant to allow you
+to choose behavior similar to HTTP PATCH or HTTP POST, where you may want to update just part of a model without having to supply
+values for every field.
+
+You specify which option you'd like using the `null_behavior` parameter when defining the mutation:
+- `leave_unchanged` means that if the input field contains a null value, it is ignored
+- `set_null` means that if the input field contains a null value, the attribute will actually be set to `nil`
+
+##### set_null
+The `set_null` option is the simpler of the two, and you should probably default to using that option. When you pick this option,
+null values behave as you would expect: they cause the attribute to be set to `nil`.
+
+But another important side-effect is that the input fields on the mutation will be marked as non-nullable if the underlying
+database column is not nullable, or if there is an unconditional presence validator on that field.
+
+##### leave_unchanged
+If you select this option, any input fields that contain null values will be ignored. Instead, if you really do want to set a
+field to null, the gem adds a field called `unsetFields`. It takes an array of field names, and it will set all of those fields
+to null.
+
+If the field is not nullable in the database, or it has an unconditional presence validator, you cannot pass it to `unsetFields`.
+Also, if _all_ of the fields meet this criteria, the gem does not even create the `unsetFields` field.
+
+The important side-effect here is that `leave_unchanged` causes all of the input fields on the mutation to be nullable.
+
+### Mutations and has_many associations
+You can create mutations that update models across a `has_many` association, by using a `nested` block just like you would for
+`has_one` or `belongs_to` associations:
+
+```ruby
+nested :emergency_contacts, null_behavior: :set_null do
+  attr :first_name
+  attr :last_name
+  attr :phone
+end
+```
+
+By default, inputs are matched to associated models by position (ie, the first input to the first model, etc). However, if you
+have an attribute that should instead be used to match them, you can specify it:
+```ruby
+nested :emergency_contacts, find_by: :priority, null_behavior: :set_null do
+  attr :first_name
+  attr :last_name
+  attr :phone
+end
+```
+
+This causes the gem to automatically include `priority` as an input field. Unfortunately, the only field you _can't_ use is the
+`id` field, because the gem isn't smart enough to map global ID's to model ID's. (This will be supported eventually, though.)
+
+Also, an important note is that the gem assumes that you are passing up _all_ of the associated models, and not just some of
+them. It will destroy extra models, or create missing models.
+
+### Other things that need to be documented
+- Custom scalar types
+- `object_to_model`
+- Retrieving field metadata (for building an authorization middleware)
+- Validation error exceptions
+- Why all fields on query types are nullable
+
 
 ## Development
 
-TODO: Write development instructions here
+TODO: Write development instructions here 😬
+
+Current goals:
+- RSpec tests. Requires getting a dummy schema in place.
+- Clean up awkward integration points (ie, global node identification)
+- Deprecate and remove relation loader code
+- Compatibility with latest version of `graphql` gem
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/graphql-activerecord. This project is intended to be a 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](http://opensource.org/licenses/MIT).

data/graphql-activerecord.gemspec

@@ -19,10 +19,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "activesupport", "~> 4.2"
-  spec.add_runtime_dependency "activerecord", "~> 4.2"
-  spec.add_runtime_dependency "graphql", "~> 0.18.4"
-  spec.add_runtime_dependency "graphql-batch", "~> 0.2.4"
+  spec.add_runtime_dependency "activesupport", ">= 4.2", '< 5'
+  spec.add_runtime_dependency "activerecord", ">= 4.2", '< 5'
+  spec.add_runtime_dependency "graphql", ">= 0.18.4"
+  spec.add_runtime_dependency "graphql-batch", ">= 0.2.4"
 
   spec.add_development_dependency "bundler", "~> 1.11"
   spec.add_development_dependency "rake", "~> 10.0"

data/lib/graphql/models/mutator.rb

@@ -44,7 +44,7 @@ module GraphQL::Models
           end
         end
 
-        changed_models.reject(&:destroyed?).each(&:reload)
+        changed_models.reject(&:destroyed?)
       end
     end
   end

data/lib/graphql/models/version.rb

@@ -1,5 +1,5 @@
 module GraphQL
   module Models
-    VERSION = "0.8.0-alpha1"
+    VERSION = "0.8.0"
   end
 end

metadata

@@ -1,69 +1,81 @@
 --- !ruby/object:Gem::Specification
 name: graphql-activerecord
 version: !ruby/object:Gem::Version
-  version: 0.8.0.pre.alpha1
+  version: 0.8.0
 platform: ruby
 authors:
 - Ryan Foster
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-31 00:00:00.000000000 Z
+date: 2016-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: graphql
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.18.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.18.4
 - !ruby/object:Gem::Dependency
   name: graphql-batch
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.4
 - !ruby/object:Gem::Dependency
@@ -133,6 +145,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -195,9 +208,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.4.8