cacheql 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: edd0f07beea907b403ceae1832e967d3f1a01aee
-  data.tar.gz: b3cae9fa387ee21cd4ea3349e843bc2eea1a314f
+  metadata.gz: 4b63b557dc02328918c18828fc532653ff77096d
+  data.tar.gz: 9309e2b0986da06f49a2ce6ad90fb88928d2a57e
 SHA512:
-  metadata.gz: ef17ab966525e39a38e8c4968d99e44541d4e6fd0cea8735f6abf5279b40b7129af6a74c7be510654f1f7c6316684046c81f416a40965c6a95125b02e7a6670b
-  data.tar.gz: 3065ca7f8150a353a7895c528494dcee87283a2c3687f4903930e45c10c42d820437b4d6edaa9a0ef3ee86c78f28e34b61316ee64c878bb693e908856e764992
+  metadata.gz: cfd0715295b686bebf91fddd605e1c1193a7ca2fc0ec9bbb63559231c9f1a274bf169f18571caa481e417c9b909ae79a41033cc1b13e1314cafeac00f9dcaf22
+  data.tar.gz: 0cf778191eb26d2bb6af7a1ec8978fbebc608101fd40dc15d50d92cf5ccce20c4ecc6c5d029c7e1588880cfcb4ddcf8f54e82077844e27dcdba0fea5bd32bca2

data/README.md

@@ -1,8 +1,11 @@
 # CacheQL
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/cacheql`. To experiment with that code, run `bin/console` for an interactive prompt.
+Need to cache and instrument your GraphQL code in Ruby? Look no further!
 
-TODO: Delete this and the text above, and describe your gem
+This is a collection of utilities for [graphql-ruby](http://graphql-ruby.org)
+that were collected from various places on GitHub + docs.
+
+This code was extracted from [Chatterbug](https://chatterbug.com). Check out the talk from [Railsconf 2018](https://speakerdeck.com/qrush/the-graphql-way-a-new-path-for-json-apis) about this gem!
 
 ## Installation
 
@@ -22,7 +25,127 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+There's four major parts to this gem:
+
+### Cache helpers
+
+Need to cache a single resolve function? Wrap it in `CacheQL`:
+
+``` ruby
+resolve CacheQL -> (obj, args, ctx) {
+  # run expensive operation
+  # this resolve function's result will be cached on obj.cache_key
+}
+```
+
+Want to cache the entire response after GraphQL has generated it? Try this in
+your controller:
+
+``` ruby
+def execute
+  # other graphql stuff...
+
+  FIELDS = %w(users curriculum)
+  render json: CacheQL.fetch(FIELDS, query, variables) { |document|
+    YourSchema.execute(
+      document: document,
+      variables: variables,
+      context: { },
+      operation_name: params[:operationName]).to_h
+  }
+end
+```
+
+This will cache the entire response when the query includes `FIELDS`.
+
+### Loaders
+
+These are all based off of community-written examples using [graphql-batch](https://github.com/Shopify/graphql-batch).
+These will reduce N+1 queries in your GraphQL code.
+
+Before using loaders, you'll have to [use `GraphQL::Batch`](https://github.com/Shopify/graphql-batch#basic-usage) as a plugin in your schema:
+
+``` ruby
+YourSchema = GraphQL::Schema.define do
+  query YourQueryType
+
+  use GraphQL::Batch
+end
+```
+
+Batch up `belongs_to` calls:
+
+``` ruby
+# when obj has a belongs_to :language
+
+resolve -> (obj, args, ctx) {
+  CacheQL::RecordLoader.for(Language).load(obj.language_id)
+}
+```
+
+Batch up `belongs_to polymorphic: true` calls:
+
+``` ruby
+# when obj has a belongs_to :respondable, polymorphic: true
+
+resolve -> (obj, args, ctx) {
+  CacheQL::PolymorphicKeyLoader.for(Response, :respondable).load(obj.respondable)
+}
+```
+
+Batch up entire associations:
+
+``` ruby
+# when obj has_many :clozes
+
+resolve -> (obj, args, ctx) {
+  CacheQL::AssociationLoader.for(obj.class, :clozes).load(obj)
+}
+```
+
+### Logging
+
+Want to get your GraphQL fields logging locally? In your controller, add:
+
+
+``` ruby
+around_action :log_field_instrumentation
+
+private
+
+def log_field_instrumentation(&block)
+  CacheQL::FieldInstrumentation.log(&block)
+end
+```
+
+This will then spit out timing logs for each field run during each request.
+For example:
+
+```
+[CacheQL::Tracing] User.displayLanguage took 7.591ms
+[CacheQL::Tracing] User.createdAt took 0.117ms
+[CacheQL::Tracing] User.intercomHash took 0.095ms
+[CacheQL::Tracing] User.id took 0.09ms
+[CacheQL::Tracing] User.friendlyTimezone took 0.087ms
+[CacheQL::Tracing] User.utmContent took 0.075ms
+[GraphQL::Tracing] User.timezone took 0.048ms
+[CacheQL::Tracing] User.email took 0.046ms
+[CacheQL::Tracing] User.name took 0.042ms
+[CacheQL::Tracing] Query.currentUser took 0.041ms
+```
+
+### Instrumentation
+
+This gem includes an instrumenter for [Scout](https://scoutapp.com) that will
+show the timing breakdown of each field in your metrics. Assuming you have Scout
+setup, add to your schema:
+
+
+``` ruby
+YourSchema = GraphQL::Schema.define do
+  instrument :field, CacheQL::FieldInstrumentation.new(ScoutApm::Tracer)
+end
+```
 
 ## Development
 

data/cacheql.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = %q{Various GraphQL caching / instrumentation tools}
   spec.description   = spec.summary
-  spec.homepage      = "https://github.com/chatterbug/cacheql"
+  spec.homepage      = "https://github.com/chatterbugapp/cacheql"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|

data/lib/cacheql/version.rb

@@ -1,3 +1,3 @@
 module CacheQL
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cacheql
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Nick Quaranto
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-12 00:00:00.000000000 Z
+date: 2018-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql-batch
@@ -133,7 +133,7 @@ files:
 - lib/cacheql/record_loader.rb
 - lib/cacheql/resolve_wrapper.rb
 - lib/cacheql/version.rb
-homepage: https://github.com/chatterbug/cacheql
+homepage: https://github.com/chatterbugapp/cacheql
 licenses:
 - MIT
 metadata: {}