graphiti 2.0.0.beta.2 → 2.0.0.beta.4

data/docs/topics/without-activerecord.md

@@ -0,0 +1,324 @@
+---
+title: 'Usage Without ActiveRecord'
+---
+
+# Usage Without ActiveRecord
+Graphiti was built to be used with any ORM or datastore, from PostgreSQL
+to elasticsearch to `Net::HTTP`. In fact, Graphiti itself is tested with
+Plain Old Ruby Objects (POROs).
+
+This cookbook will show how to customize a resource around a particular datastore, and how to package those
+customizations into a reusable adapter. We'll use an in-memory datastore
+and Plain Old Ruby Objects (POROs) here, but the lessons apply to any
+datastore.
+
+For working code, see [this branch of the sample application](https://github.com/graphiti-api/employee_directory/blob/poro/app/resources/post_resource.rb).
+
+We'll start with this PORO model:
+
+```ruby
+class Post
+  # Define getters/setters
+  # e.g. post.title = 'foo'
+  ATTRS = [:id, :title]
+  ATTRS.each { |a| attr_accessor(a) }
+
+  # Instantiate with hash of attributes
+  # e.g. Post.new(title: 'foo')
+  def initialize(attrs = {})
+    attrs.each_pair { |k,v| send(:"#{k}=", v) }
+  end
+
+  # This part only needed for our particular
+  # persistence implementation; you may not need it
+  # e.g. post.attributes # => { title: 'foo' }
+  def attributes
+    {}.tap do |attrs|
+      ATTRS.each do |name|
+        attrs[name] = send(name)
+      end
+    end
+  end
+end
+```
+
+And this in-memory datastore:
+
+```ruby
+# If we were working with more than just Posts, we'd need a 'type'
+# field here as well, to simulate a table name.
+DATA = [
+  { id: 1, title: 'Graphiti' },
+  { id: 2, title: 'is' },
+  { id: 3, title: 'super' },
+  { id: 4, title: 'dope' }
+]
+```
+
+## Resource Overrides {#resource-overrides}
+
+If it's your first time with a new ORM or datastore, we recommend
+putting the logic in the Resource first. Once things are working *and*
+there are multiple uses of the same overrides, package them into an
+Adapter.
+
+```ruby
+class PostResource < ApplicationResource
+  self.adapter = Graphiti::Adapters::Null
+
+  attribute :title, :string
+
+  def base_scope
+    {}
+  end
+
+  def resolve(scope)
+    DATA.map { |d| Post.new(d) }
+  end
+end
+```
+
+Here we're using the `Null` adapter, which acts as a dumb pass-through.
+This can be helpful when you just want to get running for a simple use
+case and don't want errors around features you haven't implemented yet.
+But it can also be confusing when you expect certain codepaths to
+be hit. Mostly just be aware of `Null`'s behavior, or use `Graphiti::Adapters::Abstract` to get helpful errors around what's not
+implemented.
+
+We're also supplying an explicit `base_scope`. This is the beginning
+query object we'll modify as params come in. In the case of
+ActiveRecord, we might want an `ActiveRecord::Relation` like `Post.all`. For our example, we'll modify a simple ruby hash (keep in
+mind the premise of building a hash of options and passing it off to a
+client can apply to any datastore).
+
+Finally, we're [resolving that scope](/concepts/resources#resolve),
+returning the full dataset for now. The contract of `#resolve` is to return an array of model instances, hence `DATA.map { |d| Post.new(d)
+}`.
+
+#### Sorting {#sorting}
+
+```ruby
+sort_all do |scope, attribute, direction|
+  scope[:sort].merge!(attribute: att, direction: dir)
+end
+
+def base_scope
+  { sort: {} }
+end
+
+def resolve(scope)
+  if sort = scope[:sort].presence
+    data = DATA.sort_by { |d| d[sort[:attribute].to_sym] }
+    data = data.reverse if sort[:direction] == :desc
+  end
+  DATA.map { |d| Post.new(d) }
+end
+```
+
+We modified the base scope with a default hash key, `:sort`. When the
+user requests sorting, we record this by merging into the hash. We can
+then reference that information on the scope when resolving.
+
+Note the `sort_all` scope block, in fact all scope blocks, must return the scope.
+
+#### Paginating {#paginating}
+
+```ruby
+paginate do |scope, current_page, per_page|
+  scope.merge!(current_page: current, per_page: per)
+end
+
+def resolve(scope)
+  # ... sorting ...
+  start = (scope[:current_page] - 1) * scope[:per_page]
+  stop  = start + scope[:per_page]
+  data  = data[start...stop]
+  # ... return models ...
+end
+```
+
+Again: merge into the scope, then reference the scope data when
+resolving.
+
+#### Filtering {#filtering}
+
+```ruby
+filter :title, only: [:eq] do
+  eq do |scope, value|
+    scope[:filters][attribute] = value
+    scope
+  end
+end
+
+def base_scope(*)
+  { sort: {}, filters: {} }
+end
+
+def resolve(scope)
+  # ... sorting ...
+  scope[:filters].each_pair do |k, v|
+    data = data.select { |d| d[k.to_sym].in?(v) }
+  end
+  # ... pagination ...
+  # ... return models ...
+end
+```
+
+Same as above examples. Again, we must return the scope object
+from the filter function.
+
+#### Persisting {#persisting}
+
+All at once:
+
+```ruby
+# Instantiate a model for #create
+def build(model_class)
+  model_class.new
+end
+
+# Used for create/update
+def assign_attributes(model, attributes)
+  attributes.each_pair do |k, v|
+    model.send(:"#{k}=", v)
+  end
+end
+
+# Used for create/update
+def save(model)
+  attrs = model.attributes.dup
+  attrs[:id] ||= DATA.length + 1
+  if existing = DATA.find { |d| d[:id].to_s == attrs[:id].to_s }
+    existing.merge!(attrs)
+  else
+    DATA << attrs
+  end
+  model
+end
+
+# Used for destroy
+def delete(model)
+  DATA.reject! { |d| d[:id].to_s == model.id.to_s }
+  model
+end
+```
+
+These are the overrides for persistence operations. You are encouraged
+**not** to override `create/update/destroy` directly and instead use
+[Persistence Lifecycle Hooks](/concepts/persisting#persistence-lifecycle-hooks).
+
+## Adapters {#adapters}
+
+OK so we have all our read and write operations working correctly. But
+if we had multiple Resources all using an in-memory datastore, you'd see
+this logic repeated all over the place. Let's create an adapter to [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)
+up this logic.
+
+There isn't much more to do than copy/paste what we've already done.
+Let's start with our `base_scope`, sorting, and pagination:
+
+```ruby
+class POROAdapter < Graphiti::Adapters::Abstract
+  def base_scope(*)
+    { sort: {}, filters: {} }
+  end
+
+  def paginate(scope, current, per)
+    scope.merge!(current_page: current, per_page: per)
+  end
+
+  def order(scope, att, dir)
+    scope[:sort].merge!(attribute: att, direction: dir)
+    scope
+  end
+
+  def resolve(scope)
+    data = DATA
+    if sort = scope[:sort].presence
+      data = data.sort_by { |d| d[sort[:attribute].to_sym] }
+      data = data.reverse if sort[:direction] == :desc
+    end
+    start = (scope[:current_page] - 1) * scope[:per_page]
+    stop  = start + scope[:per_page]
+    data  = data[start...stop]
+
+    data.map { |d| resource.model.new(d) }
+  end
+end
+```
+
+There's really nothing here we haven't seen before. We're taking the
+code we originally wrote, and sticking it into the interface defined by
+`Graphiti::Adapters::Abstract`.
+
+There's a *little* more to do with filtering:
+
+```ruby
+def filter(scope, attribute, value)
+  scope[:filters][attribute] = value
+  scope
+end
+alias :filter_string_eq :filter
+alias :filter_integer_eq :filter
+alias :filter_date_eq :filter
+# ... etc ...
+```
+
+The logic is the same, but we have a separate method for each filter
+operator. This allows us to query differently based on the type - for
+instance, ActiveRecord will default to case-insensitive for strings, but
+straight equality for integers. If you don't need operator-specific
+logic, just `alias` as you see here.
+
+You may want to limit the default operators we expect to work with a
+given type. Let's say your backend allows straight equality for strings,
+but doesn't support `prefix`, `suffix`, etc. You can specify this in
+your adapter:
+
+```ruby
+def self.default_operators
+  super.tap do |built_in|
+    built_in[:string] = [:eq]
+  end
+end
+
+# or avoid super altogether
+
+def self.default_operators
+  {
+    string: [:eq],
+    integer: [:eq]
+    # ... etc ...
+  }
+end
+```
+
+**That's it for reads**. For writes, I'll post the entire adapter code
+below - again, it's just copy/pasting what we already wrote into a
+slightly different format.
+
+```ruby
+def destroy(model)
+  Post::DATA.reject! { |d| d[:id].to_s == model.id.to_s }
+  model
+end
+
+def save(model)
+  attrs = model.attributes.dup
+  attrs[:id] ||= Post::DATA.length + 1
+  if existing = Post::DATA.find { |d| d[:id].to_s == attrs[:id].to_s }
+    existing.merge!(attrs)
+  else
+    Post::DATA << attrs
+  end
+  model
+end
+
+# For wrapping persistence operations in a DB transactions
+# Our in-memory DB doesn't have transactions, so just yield
+def transaction(*)
+  yield
+end
+```
+
+That's really it. [See the working code in Employee Directory here](https://github.com/graphiti-api/employee_directory/blob/poro/app/resources/post_resource.rb).

data/docs/tutorial/index.md

@@ -0,0 +1,58 @@
+---
+title: 'Tutorial'
+---
+
+<p align="center">
+  <img src="/assets/img/legacy/legacy-0c75a16b3a.gif" />
+</p>
+
+# Tutorial
+This tutorial serves as a deeper-dive into Graphiti development,
+building an Employee Directory application. We purposefully built this
+to illustrate common - but non-trivial - scenarios present in many
+applications.
+
+You'll need Ruby 3.2+ and Rails 7.1+ installed. Step 0 starts from an empty directory, so nothing else is assumed.
+
+A core concept of Graphiti is **Test-First** - the most pleasant way to
+develop Graphiti is by starting with an [integration test](/topics/testing). But that can add a lot of noise to a tutorial like this. Though we'll occasionally touch on testing - and the git diffs at the top of each section contain the necessary tests - we won't test first for the purposes of this tutorial.
+
+
+### Server Side: Rails
+
+[Rails Sample Application](https://github.com/graphiti-api/employee_directory)
+
+* [Step 0: Bootstrapping](/tutorial/step_0)
+* [Step 1: Initial Resource](/tutorial/step_1)
+* [Step 2: Has Many](/tutorial/step_2)
+* [Step 3: Belongs To](/tutorial/step_3)
+* [Step 4: Customizing Queries](/tutorial/step_4)
+* [Step 5: Has One](/tutorial/step_5)
+* [Step 6: Customizing Writes](/tutorial/step_6)
+* [Step 7: Many-to-Many](/tutorial/step_7)
+* [Step 8: Polymorphic
+Relationships](/tutorial/step_8)
+* [Step 9: Polymorphic Resources](/tutorial/step_9)
+
+
+
+### Client Side: VueJS (diff-only)
+
+[VueJS Sample Application](https://github.com/graphiti-api/employee-directory-vue)
+
+
+* [Step 0: Setup](https://github.com/graphiti-api/employee-directory-vue/commit/be690c3038380e17e326935d595a0b83fc8004f9)
+  * Run after `vue create employee-directory-vue` using [Vue CLI](https://cli.vuejs.org).
+* [Step 1: Define Models](https://github.com/graphiti-api/employee-directory-vue/compare/step_0_setup...step_1_models)
+* [Step 2: Data Grid](https://github.com/graphiti-api/employee-directory-vue/compare/step_1_models...step_2_data_grid)
+* [Step 3: Relationships](https://github.com/graphiti-api/employee-directory-vue/compare/step_2_data_grid...step_3_includes)
+* [Step 4: Filtering](https://github.com/graphiti-api/employee-directory-vue/compare/step_3_includes...step_4_filtering)
+* [Step 5: Sorting](https://github.com/graphiti-api/employee-directory-vue/compare/step_4_filtering...step_5_sorting)
+* [Step 6: Total Count](https://github.com/graphiti-api/employee-directory-vue/compare/step_5_sorting...step_6_stats)
+* [Step 7: Pagination](https://github.com/graphiti-api/employee-directory-vue/compare/step_6_stats...step_7_pagination)
+* [Step 8: Basic Form Setup](https://github.com/graphiti-api/employee-directory-vue/compare/step_7_pagination...step_8_basic_form_setup)
+* [Step 9: Dropdown](https://github.com/graphiti-api/employee-directory-vue/compare/step_8_basic_form_setup...step_9_dropdown)
+* [Step 10: Nested Form Submission](https://github.com/graphiti-api/employee-directory-vue/compare/step_9_dropdown...step_10_nested_create)
+* [Step 11: Validation Errors](https://github.com/graphiti-api/employee-directory-vue/compare/step_10_nested_create...step_11_validations)
+* [Step 12: Nested Destroy](https://github.com/graphiti-api/employee-directory-vue/compare/step_11_validations...step_12_nested_destroy)
+* [Step 13: Vue-Specific Glue Code](https://github.com/graphiti-api/employee-directory-vue/compare/step_12_nested_destroy...step_13_vue)

data/docs/tutorial/step_0.md

@@ -0,0 +1,107 @@
+---
+title: 'Step 0'
+---
+
+## Step 0: Bootstrapping
+
+> [View the Code](https://github.com/graphiti-api/employee_directory/commit/e2552ce212c68b41a3eb8161deb822fff3e159d6)
+
+Let's start by creating a new Rails project. For help with an existing
+project, check out [Installation: From
+Scratch](/getting-started/installation).
+
+We'll use the `-m` option to install from a template, which will add a few gems and apply some setup boilerplate. Accept all the default options.
+
+```bash
+$ rails new employee_directory --api -m https://raw.githubusercontent.com/graphiti-api/graphiti_rails_template/master/all.rb
+$ cd employee_directory
+```
+
+> Note: if a network issue prevents you from pointing to this URL directly, you can download the file and and run this command as `-m /path/to/template`
+
+Feel free to run `git diff` to see what the generator did, otherwise commit the result. You can now head to [Step 1: Basic Resource](/tutorial/step_1), or continue reading to better understand the code.
+
+#### Digging Deeper 🧐
+
+You'll see some boilerplate in `config/routes.rb`:
+
+```ruby
+scope path: ApplicationResource.endpoint_namespace, defaults: { format: :jsonapi } do
+  # your routes go here
+end
+```
+
+This tells Rails that our API routes will be be prefixed - `/api/v1` by default. It also says that if no extension is in the URL (`.json`, `.xml`, etc), default
+to the [JSONAPI Specification](http://jsonapi.org).
+
+Let's look at the above `ApplicationResource`:
+
+```ruby
+class ApplicationResource < Graphiti::Resource
+  self.abstract_class = true
+
+  # We'll be using ActiveRecord
+  self.adapter = Graphiti::Adapters::ActiveRecord
+
+  # Links are generated from base_url + endpoint_namespace
+  self.base_url = Rails.application.routes
+    .default_url_options[:host]
+  self.endpoint_namespace = '/api/v1'
+end
+```
+
+This should be pretty self-explanatory except for
+
+```ruby
+self.base_url = Rails.application.routes
+  .default_url_options[:host]
+```
+
+This is configured in `config/application.rb`:
+
+```ruby
+module EmployeeDirectory
+  class Application < Rails::Application
+    routes.default_url_options[:host] = ENV.fetch('HOST', 'http://localhost:3000')
+    # ... code ...
+  end
+end
+```
+
+When deriving and validating [Links](/concepts/links), we'll use the `HOST` variable if
+present, falling back to the Rails development default of
+`http://localhost:3000`. This means our Links will look like:
+
+```ruby
+"#{ENV['HOST']}/#{ApplicationRecord.endpoint_namespace}/#{Resource.type}"
+```
+
+For example:
+
+```ruby
+http://my-website.com/api/v1/employees
+```
+
+Read more in the [Links Guide](/concepts/links).
+
+Finally, there's some boilerplate in `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::API
+  # Support JSON, XML, JSON:API
+  include Graphiti::Rails::Responders
+end
+```
+
+This gets `respond_with` working, via the [Responders gem](https://github.com/plataformatec/responders). To render simple nested JSON like default Rails, we'll only need to add `.json` to the URL.
+
+That's it for basic setup!
+
+
+  <h2 id="next">
+    <a href="/tutorial/step_1">
+      NEXT - 
+      <small>Step 1: Basic Resource</small>
+      &raquo;
+    </a>
+  </h2>

data/docs/tutorial/step_1.md

@@ -0,0 +1,199 @@
+---
+title: 'Step 1'
+---
+
+## Step 1: Basic Resource
+
+> [View the Diff](https://github.com/graphiti-api/employee_directory/commit/45c1c92e14fb1c3a47b8ed246ceb2cba50e97c72)
+
+We'll be working with a single database table, `employees`:
+
+<table class="table table-small">
+  <thead>
+    <tr>
+      <th>id</th>
+      <th>first_name</th>
+      <th>last_name</th>
+      <th>age</th>
+      <th>created_at</th>
+      <th>updated_at</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td>Homer</td>
+      <td>Simpson</td>
+      <td>39</td>
+      <td>2018-09-04</td>
+      <td>2018-09-04</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>Waylon</td>
+      <td>Smithers</td>
+      <td>65</td>
+      <td>2018-09-04</td>
+      <td>2018-09-04</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td>Monty</td>
+      <td>Burns</td>
+      <td>123</td>
+      <td>2018-09-04</td>
+      <td>2018-09-04</td>
+    </tr>
+  </tbody>
+</table>
+
+### The Rails Stuff 🚂
+
+Use the built-in generator to create the database table
+and corresponding `ActiveRecord` model:
+
+```bash
+$ bin/rails g model Employee first_name:string last_name:string age:integer
+$ bin/rails db:migrate
+```
+
+Now let's seed some random development data, using [Faker](https://github.com/stympy/faker) (which was installed in [Step 0](/tutorial/step_0)):
+
+```ruby
+# db/seeds.rb
+Employee.delete_all # Ensure the DB is cleaned each run
+
+100.times do
+  Employee.create! first_name: Faker::Name.first_name,
+    last_name: Faker::Name.last_name,
+    age: rand(20..80)
+end
+```
+
+Run this seed file with
+
+```bash
+$ bin/rails db:seed
+```
+
+### The Graphiti Stuff 🎨
+
+Just like Rails, Graphiti has built-in generators. Let's generate
+the corresponding Resource for our `Employee` model:
+
+```bash
+$ bin/rails g graphiti:resource Employee first_name:string last_name:string age:integer created_at:datetime updated_at:datetime
+```
+
+This generated a few things, but for now let's focus on
+`EmployeeResource`:
+
+```ruby
+class EmployeeResource < ApplicationResource
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :age, :integer
+  attribute :created_at, :datetime, writable: false
+  attribute :updated_at, :datetime, writable: false
+end
+```
+
+This code defined the [RESTful Resource](https://restful-api-design.readthedocs.io/en/latest/resources.html) we want our API to expose. Let's run our server and see what it does:
+
+```bash
+$ bin/rails s
+```
+
+Visit `localhost:3000/api/v1/employees`. You should see a [JSONAPI Response](http://jsonapi.org):
+
+<br />
+
+![jsonapi](/assets/img/legacy/legacy-0378a3bb39.png)
+
+<br />
+
+If you find the payload a little intimidating, add `.json` to the URL for a more traditional response, or `.xml` for XML. Both are different **renderings** of the same `EmployeeResource`.
+
+`Resources` are comprised of `Attribute`s:
+
+```ruby
+# app/resources/employee_resource.rb
+attribute :first_name, :string
+```
+
+Each attribute defines behavior for:
+
+* Reading (display)
+* Writing
+* Sorting
+* Filtering
+* Fieldsets
+
+Let's start with simple display, turning `first_name` into all capital
+letters:
+
+```ruby
+# app/resources/employee_resource.rb
+attribute :first_name, :string do
+  # @object is your model instance
+  @object.first_name.upcase
+end
+```
+
+This is the most important thing to understand about Resources: they are just a collection of defaults, all of which can be overridden. `attribute :first_name` is shorthand for `attribute :first_name do @object.first_name end`.
+
+We'll go into further Resource customizations over the course of this tutorial. For now, undo the capitalization change above, and verify our out-of-the-box defaults: the same filter, sort, and pagination capabilities you exercised in the [Quickstart](/getting-started/first-api#querying) work here too, just against `employees` instead of `posts`. See the [Overview guide](/concepts/overview) for the full capability reference.
+
+Write operations are easiest to verify with integration tests, which were created when we generated our Resource: an **API Spec** covering the request/response cycle, and a **Resource Spec** covering the Resource's logic directly. See the [Testing Guide](/topics/testing) for what these look like and how they differ. The example there uses the same `create` payload shape the generator produced for `EmployeeResource`.
+
+Before we run these specs, we need to edit our [factories](https://github.com/thoughtbot/factory_bot) to ensure
+dynamic, randomized data. Let's change this:
+
+```ruby
+# spec/factories/employee.rb
+
+FactoryBot.define do
+  factory :employee do
+    first_name { "MyString" }
+    last_name { "MyString" }
+    age { 1 }
+  end
+end
+```
+
+To
+
+```ruby
+# spec/factories/employee.rb
+
+FactoryBot.define do
+  factory :employee do
+    first_name { Faker::Name.first_name }
+    last_name { Faker::Name.last_name }
+    age { rand(20..80) }
+  end
+end
+```
+
+Now run the generated specs:
+
+```bash
+$ bundle exec rspec
+```
+
+You'll see 11 tests pass, with 3 pending. One of the pending specs was
+autogenerated by rails - you can delete `spec/models/employee_spec.rb`
+for now.
+
+That leaves us with two "update" specs. These are marked pending so you
+can manage the data yourself. Follow the comments in these specs to add
+attributes and get them passing.
+
+
+  <h2 id="next">
+    <a href="/tutorial/step_2">
+      NEXT - 
+      <small>Step 2: Has Many</small>
+      &raquo;
+    </a>
+  </h2>