1605582242
In this post we’ll compare rich GraphQL clients that come with a normalized cache implementation and the generated WunderGraph clients that rely on HTTP caching.
As you might have already found out, WunderGraph uses persisted queries by default. With the WunderGraph code generator WunderGen you can generate a client that knows exactly how to invoke your previously registered operations. With the @cache
directive you’re able to configure that the response of an operation should be cached by the server & client. Cache Control headers will be set accordingly, including etags. This mechanism is fully compatible with all major browsers and CDN’s who implement caching according to the HTTP Caching RFC.
To illustrate this a bit better I’d like to introduce two example queries. The first one fetches a list of friends. The second one fetches some details about those friends.
Let’s consider we want to show a list of friends:
query Friends {
friends {
id
name
age
avatarURL
}
}
For each friend we’d like to be able to click on the friend in the list and open up a detail page:
query FriendByID {
friend(id: 123) {
id
name
age
avatarURL
}
}
You will recognize that we already have all the data for the detail page. So in an ideal scenario the client won’t have to make another request. This is possible thanks to cache normalization.
A smart normalized cache will identify the Friend entity and will recognize that the “FriendByID” query can be fulfilled using the data from the “Friends” query which we already ran.
What are the pros of this concept?
#graphql
1623297402
Looking at the previous architecture above, you might notice that there’s a one-to-one ratio of requests that come into the gateway and hit the underlying backend service.
If we wanted to reduce strain on the backend service, we could introduce a cache, preventing the need to fetch data that has already been fetched by the implementing service.
#graphql #graphql architecture #caching #caching strategies
1651813200
Why use this package over the other available Elm GraphQL packages? This is the only one that generates type-safe code for your entire schema. Check out this blog post, Type-Safe & Composable GraphQL in Elm, to learn more about the motivation for this library. (It's also the only type-safe library with Elm 0.18 or 0.19 support, see this discourse thread).
I built this package because I wanted to have something that:
See an example in action on Ellie. See more end-to-end example code in the examples/
folder.
dillonkearns/elm-graphql
is an Elm package and accompanying command-line code generator that creates type-safe Elm code for your GraphQL endpoint. You don't write any decoders for your API with dillonkearns/elm-graphql
, instead you simply select which fields you would like, similar to a standard GraphQL query but in Elm. For example, this GraphQL query
query {
human(id: "1001") {
name
homePlanet
}
}
would look like this in dillonkearns/elm-graphql
(the code in this example that is prefixed with StarWars
is auto-generated)
import Graphql.Operation exposing (RootQuery)
import Graphql.SelectionSet as SelectionSet exposing (SelectionSet)
import StarWars.Object
import StarWars.Object.Human as Human
import StarWars.Query as Query
import StarWars.Scalar exposing (Id(..))
query : SelectionSet (Maybe HumanData) RootQuery
query =
Query.human { id = Id "1001" } humanSelection
type alias HumanData =
{ name : String
, homePlanet : Maybe String
}
humanSelection : SelectionSet HumanData StarWars.Object.Human
humanSelection =
SelectionSet.map2 HumanData
Human.name
Human.homePlanet
GraphQL and Elm are a perfect match because GraphQL is used to enforce the types that your API takes as inputs and outputs, much like Elm's type system does within Elm. elm-graphql
simply bridges this gap by making your Elm code aware of your GraphQL server's schema. If you are new to GraphQL, graphql.org/learn/ is an excellent way to learn the basics.
After following the installation instructions to install the @dillonkearns/elm-graphql
NPM package and the proper Elm packages (see the Setup section for details). Once you've installed everything, running the elm-graphql
code generation tool is as simple as this:
npx elm-graphql https://elm-graphql.herokuapp.com --base StarWars --output examples/src
If headers are required, such as a Bearer Token, the --header
flag can be supplied.
npx elm-graphql https://elm-graphql.herokuapp.com --base StarWars --output examples/src --header 'headerKey: header value'
There is a thorough tutorial in the SelectionSet
docs. SelectionSet
s are the core concept in this library, so I recommend reading through the whole page (it's not very long!).
The examples/
folder is another great place to start.
If you want to learn more GraphQL basics, this is a great tutorial, and a short read: graphql.org/learn/
My Elm Conf 2018 talk goes into the philosophy behind dillonkearns/elm-graphql
(Skip to 13:06 to go straight to the dillonkearns/elm-graphql
demo).
elm-graphql
using the Scalar Codecs feature. If you're wondering why code is generated a certain way, you're likely to find an answer in the Frequently Asked Questions (FAQ).
There's a very helpful group of people in the #graphql channel in the Elm Slack. Don't hesitate to ask any questions about getting started, best practices, or just general GraphQL in there!
dillonkearns/elm-graphql
generates Elm code that allows you to build up type-safe GraphQL requests. Here are the steps to setup dillonkearns/elm-graphql
.
Add the dillonkearns/elm-graphql
elm package as a dependency in your elm.json
. You will also need to make sure that elm/json
is a dependency of your project since the generated code has lots of JSON decoders in it.
elm install dillonkearns/elm-graphql
elm install elm/json
Install the @dillonkearns/elm-graphql
command line tool through npm. This is what you will use to generate Elm code for your API. It is recommended that you save the @dillonkearns/elm-graphql
command line tool as a dev dependency so that everyone on your project is using the same version.
npm install --save-dev @dillonkearns/elm-graphql
# you can now run it locally using `npx elm-graphql`,
# or by calling it through an npm script as in this project's package.json
Run the @dillonkearns/elm-graphql
command line tool installed above to generate your code. If you used the --save-dev
method above, you can simply create a script in your package.json like the following:
{
"name": "star-wars-elm-graphql-project",
"version": "1.0.0",
"scripts": {
"api": "elm-graphql https://elm-graphql.herokuapp.com/api --base StarWars"
}
With the above in your package.json
, running npm run api
will generate dillonkearns/elm-graphql
code for you to call in ./src/StarWars/
. You can now use the generated code as in this Ellie example or in the examples
folder.
You can do real-time APIs using GraphQL Subscriptions and dillonkearns/elm-graphql
. Just wire in the framework-specific JavaScript code for opening the WebSocket connection through a port. Here's a live demo and its source code. The demo server is running Elixir/Absinthe.
Thank you Mario Martinez (martimatix) for all your feedback, the elm-format PR, and for the incredible logo design!
Thank you Mike Stock (mikeastock) for setting up Travis CI!
Thanks for the reserved words pull request @madsflensted!
A huge thanks to @xtian for doing the vast majority of the 0.19 upgrade work! :tada:
Thank you Josh Adams (@knewter) for the code example for Subscriptions with Elixir/Absinthe wired up through Elm ports!
Thank you Romario for adding OptionalArgument.map
!
Thank you Aaron White for your pull request to improve the performance and stability of the elm-format
step! 🎉
All core features are supported. That is, you can build any query or mutation with your dillonkearns/elm-graphql
-generated code, and it is guaranteed to be valid according to your server's schema.
dillonkearns/elm-graphql
will generate code for you to generate subscriptions and decode the responses, but it doesn't deal with the low-level details for how to send them over web sockets. To do that, you will need to use custom code or a package that knows how to communicate over websockets (or whichever protocol) to setup a subscription with your particular framework. See this discussion for why those details are not handled by this library directly.
I would love to hear feedback if you are using GraphQL Subscriptions. In particular, I'd love to see live code examples to drive any improvements to the Subscriptions design. Please ping me on Slack, drop a message in the #graphql channel, or open up a Github issue to discuss!
I would like to investigate generating helpers to make pagination simpler for Connections (based on the Relay Cursor Connections Specification). If you have ideas on this chime in on this thread.
See the full roadmap on Trello.
Author: dillonkearns
Source Code: https://github.com/dillonkearns/elm-graphql
License: View license
1659852060
Curly is a template language that completely separates structure and logic. Instead of interspersing your HTML with snippets of Ruby, all logic is moved to a presenter class.
Installing Curly is as simple as running gem install curly-templates
. If you're using Bundler to manage your dependencies, add this to your Gemfile
gem 'curly-templates'
Curly can also install an application layout file, replacing the .erb file commonly created by Rails. If you wish to use this, run the curly:install
generator.
$ rails generate curly:install
In order to use Curly for a view or partial, use the suffix .curly
instead of .erb
, e.g. app/views/posts/_comment.html.curly
. Curly will look for a corresponding presenter class named Posts::CommentPresenter
. By convention, these are placed in app/presenters/
, so in this case the presenter would reside in app/presenters/posts/comment_presenter.rb
. Note that presenters for partials are not prepended with an underscore.
Add some HTML to the partial template along with some Curly components:
<!-- app/views/posts/_comment.html.curly -->
<div class="comment">
<p>
{{author_link}} posted {{time_ago}} ago.
</p>
{{body}}
{{#author?}}
<p>{{deletion_link}}</p>
{{/author?}}
</div>
The presenter will be responsible for providing the data for the components. Add the necessary Ruby code to the presenter:
# app/presenters/posts/comment_presenter.rb
class Posts::CommentPresenter < Curly::Presenter
presents :comment
def body
SafeMarkdown.render(@comment.body)
end
def author_link
link_to @comment.author.name, @comment.author, rel: "author"
end
def deletion_link
link_to "Delete", @comment, method: :delete
end
def time_ago
time_ago_in_words(@comment.created_at)
end
def author?
@comment.author == current_user
end
end
The partial can now be rendered like any other, e.g. by calling
render 'comment', comment: comment
render comment
render collection: post.comments
Curly components are surrounded by curly brackets, e.g. {{hello}}
. They always map to a public method on the presenter class, in this case #hello
. Methods ending in a question mark can be used for conditional blocks, e.g. {{#admin?}} ... {{/admin?}}
.
Curly components can specify an identifier using the so-called dot notation: {{x.y.z}}
. This can be very useful if the data you're accessing is hierarchical in nature. One common example is I18n:
<h1>{{i18n.homepage.header}}</h1>
# In the presenter, the identifier is passed as an argument to the method. The
# argument will always be a String.
def i18n(key)
translate(key)
end
The identifier is separated from the component name with a dot. If the presenter method has a default value for the argument, the identifier is optional – otherwise it's mandatory.
In addition to an identifier, Curly components can be annotated with attributes. These are key-value pairs that affect how a component is rendered.
The syntax is reminiscent of HTML:
<div>{{sidebar rows=3 width=200px title="I'm the sidebar!"}}</div>
The presenter method that implements the component must have a matching keyword argument:
def sidebar(rows: "1", width: "100px", title:); end
All argument values will be strings. A compilation error will be raised if
You can define default values using Ruby's own syntax. Additionally, if the presenter method accepts arbitrary keyword arguments using the **doublesplat
syntax then all attributes will be valid for the component, e.g.
def greetings(**names)
names.map {|name, greeting| "#{name}: #{greeting}!" }.join("\n")
end
{{greetings alice=hello bob=hi}}
<!-- The above would be rendered as: -->
alice: hello!
bob: hi!
Note that since keyword arguments in Ruby are represented as Symbol objects, which are not garbage collected in Ruby versions less than 2.2, accepting arbitrary attributes represents a security vulnerability if your application allows untrusted Curly templates to be rendered. Only use this feature with trusted templates if you're not on Ruby 2.2 yet.
If there is some content you only want rendered under specific circumstances, you can use conditional blocks. The {{#admin?}}...{{/admin?}}
syntax will only render the content of the block if the admin?
method on the presenter returns true, while the {{^admin?}}...{{/admin?}}
syntax will only render the content if it returns false.
Both forms can have an identifier: {{#locale.en?}}...{{/locale.en?}}
will only render the block if the locale?
method on the presenter returns true given the argument "en"
. Here's how to implement that method in the presenter:
class SomePresenter < Curly::Presenter
# Allows rendering content only if the locale matches a specified identifier.
def locale?(identifier)
current_locale == identifier
end
end
Furthermore, attributes can be set on the block. These only need to be specified when opening the block, not when closing it:
{{#square? width=3 height=3}}
<p>It's square!</p>
{{/square?}}
Attributes work the same way as they do for normal components.
Sometimes you want to render one or more items within the current template, and splitting out a separate template and rendering that in the presenter is too much overhead. You can instead define the template that should be used to render the items inline in the current template using the collection block syntax.
Collection blocks are opened using an asterisk:
{{*comments}}
<li>{{body}} ({{author_name}})</li>
{{/comments}}
The presenter will need to expose the method #comments
, which should return a collection of objects:
class Posts::ShowPresenter < Curly::Presenter
presents :post
def comments
@post.comments
end
end
The template within the collection block will be used to render each item, and it will be backed by a presenter named after the component – in this case, comments
. The name will be singularized and Curly will try to find the presenter class in the following order:
Posts::ShowPresenter::CommentPresenter
Posts::CommentPresenter
CommentPresenter
This allows you some flexibility with regards to how you want to organize these nested templates and presenters.
Note that the nested template will only have access to the methods on the nested presenter, but all variables passed to the "parent" presenter will be forwarded to the nested presenter. In addition, the current item in the collection will be passed, as well as that item's index in the collection:
class Posts::CommentPresenter < Curly::Presenter
presents :post, :comment, :comment_counter
def number
# `comment_counter` is automatically set to the item's index in the collection,
# starting with 1.
@comment_counter
end
def body
@comment.body
end
def author_name
@comment.author.name
end
end
Collection blocks are an alternative to splitting out a separate template and rendering that from the presenter – which solution is best depends on your use case.
While collection blocks allow you to define the template that should be used to render items in a collection right within the parent template, context blocks allow you to define the template for an arbitrary context. This is very powerful, and can be used to define widget-style components and helpers, and provide an easy way to work with structured data. Let's say you have a comment form on your page, and you'd rather keep the template inline. A simple template could look like:
<!-- post.html.curly -->
<h1>{{title}}</h1>
{{body}}
{{@comment_form}}
<b>Name: </b> {{name_field}}<br>
<b>E-mail: </b> {{email_field}}<br>
{{comment_field}}
{{submit_button}}
{{/comment_form}}
Note that an @
character is used to denote a context block. Like with collection blocks, a separate presenter class is used within the block, and a simple convention is used to find it. The name of the context component (in this case, comment_form
) will be camel cased, and the current presenter's namespace will be searched:
class PostPresenter < Curly::Presenter
presents :post
def title; @post.title; end
def body; markdown(@post.body); end
# A context block method *must* take a block argument. The return value
# of the method will be used when rendering. Calling the block argument will
# render the nested template. If you pass a value when calling the block
# argument it will be passed to the presenter.
def comment_form(&block)
form_for(Comment.new, &block)
end
# The presenter name is automatically deduced.
class CommentFormPresenter < Curly::Presenter
# The value passed to the block argument will be passed in a parameter named
# after the component.
presents :comment_form
# Any parameters passed to the parent presenter will be forwarded to this
# presenter as well.
presents :post
def name_field
@comment_form.text_field :name
end
# ...
end
end
Context blocks were designed to work well with Rails' helper methods such as form_for
and content_tag
, but you can also work directly with the block. For instance, if you want to directly control the value that is passed to the nested presenter, you can call the call
method on the block yourself:
def author(&block)
content_tag :div, class: "author" do
# The return value of `call` will be the result of rendering the nested template
# with the argument. You can post-process the string if you want.
block.call(@post.author)
end
end
If you find yourself opening a context block just in order to use a single component, e.g. {{@author}}{{name}}{{/author}}
, you can use the shorthand syntax instead: {{author:name}}
. This works for all component types, e.g.
{{#author:admin?}}
<p>The author is an admin!</p>
{{/author:admin?}}
The syntax works for nested contexts as well, e.g. {{comment:author:name}}
. Any identifier and attributes are passed to the target component, which in this example would be {{name}}
.
Although most code in Curly presenters should be free of side effects, sometimes side effects are required. One common example is defining content for a content_for
block.
If a Curly presenter class defines a setup!
method, it will be called before the view is rendered:
class PostPresenter < Curly::Presenter
presents :post
def setup!
content_for :title, post.title
content_for :sidebar do
render 'post_sidebar', post: post
end
end
end
In order to have {{
appear verbatim in the rendered HTML, use the triple Curly escape syntax:
This is {{{escaped}}.
You don't need to escape the closing }}
.
If you want to add comments to your Curly templates that are not visible in the rendered HTML, use the following syntax:
{{! This is some interesting stuff }}
Presenters are classes that inherit from Curly::Presenter
– they're usually placed in app/presenters/
, but you can put them anywhere you'd like. The name of the presenter classes match the virtual path of the view they're part of, so if your controller is rendering posts/show
, the Posts::ShowPresenter
class will be used. Note that Curly is only used to render a view if a template can be found – in this case, at app/views/posts/show.html.curly
.
Presenters can declare a list of accepted variables using the presents
method:
class Posts::ShowPresenter < Curly::Presenter
presents :post
end
A variable can have a default value:
class Posts::ShowPresenter < Curly::Presenter
presents :post
presents :comment, default: nil
end
Any public method defined on the presenter is made available to the template as a component:
class Posts::ShowPresenter < Curly::Presenter
presents :post
def title
@post.title
end
def author_link
# You can call any Rails helper from within a presenter instance:
link_to author.name, profile_path(author), rel: "author"
end
private
# Private methods are not available to the template, so they're safe to
# use.
def author
@post.author
end
end
Presenter methods can even take an argument. Say your Curly template has the content {{t.welcome_message}}
, where welcome_message
is an I18n key. The following presenter method would make the lookup work:
def t(key)
translate(key)
end
That way, simple ``functions'' can be added to the Curly language. Make sure these do not have any side effects, though, as an important part of Curly is the idempotence of the templates.
Both layouts and content blocks (see content_for
) use yield
to signal that content can be inserted. Curly works just like ERB, so calling yield
with no arguments will make the view usable as a layout, while passing a Symbol will make it try to read a content block with the given name:
# Given you have the following Curly template in
# app/views/layouts/application.html.curly
#
# <html>
# <head>
# <title>{{title}}</title>
# </head>
# <body>
# <div id="sidebar">{{sidebar}}</div>
# {{body}}
# </body>
# </html>
#
class ApplicationLayout < Curly::Presenter
def title
"You can use methods just like in any other presenter!"
end
def sidebar
# A view can call `content_for(:sidebar) { "some HTML here" }`
yield :sidebar
end
def body
# The view will be rendered and inserted here:
yield
end
end
In order to make a Rails helper method available as a component in your template, use the exposes_helper
method:
class Layouts::ApplicationPresenter < Curly::Presenter
# The components {{sign_in_path}} and {{root_path}} are made available.
exposes_helper :sign_in_path, :root_path
end
Presenters can be tested directly, but sometimes it makes sense to integrate with Rails on some levels. Currently, only RSpec is directly supported, but you can easily instantiate a presenter:
SomePresenter.new(context, assigns)
context
is a view context, i.e. an object that responds to render
, has all the helper methods you expect, etc. You can pass in a test double and see what you need to stub out. assigns
is the hash containing the controller and local assigns. You need to pass in a key for each argument the presenter expects.
In order to test presenters with RSpec, make sure you have rspec-rails
in your Gemfile. Given the following presenter:
# app/presenters/posts/show_presenter.rb
class Posts::ShowPresenter < Curly::Presenter
presents :post
def body
Markdown.render(@post.body)
end
end
You can test the presenter methods like this:
# You can put this in your `spec_helper.rb`.
require 'curly/rspec'
# spec/presenters/posts/show_presenter_spec.rb
describe Posts::ShowPresenter, type: :presenter do
describe "#body" do
it "renders the post's body as Markdown" do
assign(:post, double(:post, body: "**hello!**"))
expect(presenter.body).to eq "<strong>hello!</strong>"
end
end
end
Note that your spec must be tagged with type: :presenter
.
Here is a simple Curly template – it will be looked up by Rails automatically.
<!-- app/views/posts/show.html.curly -->
<h1>{{title}}<h1>
<p class="author">{{author}}</p>
<p>{{description}}</p>
{{comment_form}}
<div class="comments">
{{comments}}
</div>
When rendering the template, a presenter is automatically instantiated with the variables assigned in the controller or the render
call. The presenter declares the variables it expects with presents
, which takes a list of variables names.
# app/presenters/posts/show_presenter.rb
class Posts::ShowPresenter < Curly::Presenter
presents :post
def title
@post.title
end
def author
link_to(@post.author.name, @post.author, rel: "author")
end
def description
Markdown.new(@post.description).to_html.html_safe
end
def comments
render 'comment', collection: @post.comments
end
def comment_form
if @post.comments_allowed?
render 'comment_form', post: @post
else
content_tag(:p, "Comments are disabled for this post")
end
end
end
Caching is handled at two levels in Curly – statically and dynamically. Static caching concerns changes to your code and templates introduced by deploys. If you do not wish to clear your entire cache every time you deploy, you need a way to indicate that some view, helper, or other piece of logic has changed.
Dynamic caching concerns changes that happen on the fly, usually made by your users in the running system. You wish to cache a view or a partial and have it expire whenever some data is updated – usually whenever a specific record is changed.
Because of the way logic is contained in presenters, caching entire views or partials by the data they present becomes exceedingly straightforward. Simply define a #cache_key
method that returns a non-nil object, and the return value will be used to cache the template.
Whereas in ERB you would include the cache
call in the template itself:
<% cache([@post, signed_in?]) do %>
...
<% end %>
In Curly you would instead declare it in the presenter:
class Posts::ShowPresenter < Curly::Presenter
presents :post
def cache_key
[@post, signed_in?]
end
end
Likewise, you can add a #cache_duration
method if you wish to automatically expire the fragment cache:
class Posts::ShowPresenter < Curly::Presenter
...
def cache_duration
30.minutes
end
end
In order to set any cache option, define a #cache_options
method that returns a Hash of options:
class Posts::ShowPresenter < Curly::Presenter
...
def cache_options
{ compress: true, namespace: "my-app" }
end
end
Static caching will only be enabled for presenters that define a non-nil #cache_key
method (see Dynamic Caching.)
In order to make a deploy expire the cache for a specific view, set the version
of the view to something new, usually by incrementing by one:
class Posts::ShowPresenter < Curly::Presenter
version 3
def cache_key
# Some objects
end
end
This will change the cache keys for all instances of that view, effectively expiring the old cache entries.
This works well for views, or for partials that are rendered in views that themselves are not cached. If the partial is nested within a view that is cached, however, the outer cache will not be expired. The solution is to register that the inner partial is a dependency of the outer one such that Curly can automatically deduce that the outer partial cache should be expired:
class Posts::ShowPresenter < Curly::Presenter
version 3
depends_on 'posts/comment'
def cache_key
# Some objects
end
end
class Posts::CommentPresenter < Curly::Presenter
version 4
def cache_key
# Some objects
end
end
Now, if the version
of Posts::CommentPresenter
is bumped, the cache keys for both presenters would change. You can register any number of view paths with depends_on
.
Curly integrates well with the caching mechanism in Rails 4 (or Cache Digests in Rails 3), so the dependencies defined with depends_on
will be tracked by Rails. This will allow you to deploy changes to your templates and have the relevant caches automatically expire.
Thanks to Zendesk for sponsoring the work on Curly.
Author: zendesk
Source code: https://github.com/zendesk/curly
1605582242
In this post we’ll compare rich GraphQL clients that come with a normalized cache implementation and the generated WunderGraph clients that rely on HTTP caching.
As you might have already found out, WunderGraph uses persisted queries by default. With the WunderGraph code generator WunderGen you can generate a client that knows exactly how to invoke your previously registered operations. With the @cache
directive you’re able to configure that the response of an operation should be cached by the server & client. Cache Control headers will be set accordingly, including etags. This mechanism is fully compatible with all major browsers and CDN’s who implement caching according to the HTTP Caching RFC.
To illustrate this a bit better I’d like to introduce two example queries. The first one fetches a list of friends. The second one fetches some details about those friends.
Let’s consider we want to show a list of friends:
query Friends {
friends {
id
name
age
avatarURL
}
}
For each friend we’d like to be able to click on the friend in the list and open up a detail page:
query FriendByID {
friend(id: 123) {
id
name
age
avatarURL
}
}
You will recognize that we already have all the data for the detail page. So in an ideal scenario the client won’t have to make another request. This is possible thanks to cache normalization.
A smart normalized cache will identify the Friend entity and will recognize that the “FriendByID” query can be fulfilled using the data from the “Friends” query which we already ran.
What are the pros of this concept?
#graphql
1622105190
One of the fastest ways to get up and running with GraphQL is to install Apollo Server as middleware on your new or existing HTTP server.
In this short post, we demonstrate how to use Apollo Server to create a GraphQL server with Express.js using the [apollo-server-express] package. At the end, we’ll discuss the tradeoffs of this approach.
#graphql #javascript #graphql.js #graphql.js tutorial