graphiti 2.0.0.beta.7 → 2.0.0.beta.8

data/docs/tutorial/step_2.md

@@ -1,312 +0,0 @@
----
-title: 'Step 2'
----
-
-## Step 2: Has Many
-
-> [View the Code](https://github.com/graphiti-api/employee_directory/compare/step_1_employees...step_2_positions)
-
-We'll be adding the database table `positions`:
-
-<table class="table table-small text-center">
-  <thead>
-    <tr>
-      <th class="text-center">id</th>
-      <th class="text-center">employee_id</th>
-      <th class="text-center">title</th>
-      <th class="text-center">active</th>
-      <th class="text-center">historical_index</th>
-      <th class="text-center">created_at</th>
-      <th class="text-center">updated_at</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>1</td>
-      <td>900</td>
-      <td>Engineer</td>
-      <td>true</td>
-      <td>1</td>
-      <td>2018-09-04</td>
-      <td>2018-09-04</td>
-    </tr>
-    <tr>
-      <td>2</td>
-      <td>900</td>
-      <td>Intern</td>
-      <td>true</td>
-      <td>2</td>
-      <td>2018-09-04</td>
-      <td>2018-09-04</td>
-    </tr>
-    <tr>
-      <td>3</td>
-      <td>800</td>
-      <td>Manager</td>
-      <td>true</td>
-      <td>1</td>
-      <td>2018-09-04</td>
-      <td>2018-09-04</td>
-    </tr>
-  </tbody>
-</table>
-
-Because this table tracks all historical positions, we have the
-`historical_index` column. This tells the order the employee moved through each position, where `1` is most recent.
-
-### The Rails Stuff 🚂
-
-Generate the `Position` model:
-
-```bash
-$ bin/rails g model Position title:string active:boolean historical_index:integer employee:belongs_to
-$ bin/rails db:migrate
-```
-
-Update the `Employee` model with the association, too:
-
-```ruby
-# app/models/employee.rb
-has_many :positions
-```
-
-And update our seed data:
-
-```ruby
-# db/seeds.rb
-[Employee, Position].each(&:delete_all)
-
-100.times do
-  employee = Employee.create! first_name: Faker::Name.first_name,
-    last_name: Faker::Name.last_name,
-    age: rand(20..80)
-
-  (1..2).each do |i|
-    employee.positions.create! title: Faker::Job.title,
-      historical_index: i,
-      active: i == 1
-  end
-end
-```
-
-```bash
-$ bin/rails db:seed
-```
-
-### The Graphiti Stuff 🎨
-
-Let's start by running the same command as before to create
-`PositionResource`:
-
-```bash
-$ bin/rails g graphiti:resource Position title:string active:boolean
-```
-
-We'll need to add the association, just like ActiveRecord:
-
-```ruby
-# app/resources/employee_resource.rb
-has_many :positions
-```
-
-...and a corresponding filter:
-
-```ruby
-# app/resources/position_resource.rb
-filter :employee_id, :integer
-```
-
-If you visit `/api/v1/employees`, you'll see a number of HTTP
-[Links](https://www.graphiti.dev/guides/concepts/links)
-that allow lazy-loading positions. Or, if you visit
-`/api/v1/employees?include=positions`, you'll load the employees and
-positions in a single request. We'll dig a bit deeper into this logic
-in the section below.
-
-Before we get there, let's revisit the `historical_index` column. For now, let's
-treat this as an implementation detail that the API should not expose -
-let's say we want to support sorting on this attribute but nothing else:
-
-```ruby
-attribute :historical_index, :integer, only: [:sortable]
-```
-
-We're almost done, but if you run your tests you'll see two outstanding
-errors. This is because Rails requires `belongs_to` associations by default. We can't save a `Position` without its corresponding `Employee`.
-
-We can solve this in three ways:
-
-* Turn this off globally, with [config.active_record.belongs_to_required_by_default](https://edgeguides.rubyonrails.org/configuring.html#configuring-active-record). You may want to do this in test-mode only.
-* Turn this off for the specific association: `belongs_to :employee, optional: true`.
-* Associate an `Employee` as part of the API request.
-
-We'll take for the last option. Look at
-`spec/resources/position/writes_spec.rb`:
-
-```ruby
-RSpec.describe PositionResource, type: :resource do
-  describe 'creating' do
-    let(:payload) do
-      {
-        data: {
-          type: 'positions',
-          attributes: { }
-        }
-      }
-    end
-
-    let(:instance) do
-      PositionResource.build(payload)
-    end
-
-    it 'works' do
-      expect {
-        expect(instance.save).to eq(true)
-      }.to change { Position.count }.by(1)
-    end
-  end
-end
-```
-
-When running our tests, let's make sure the `historical_index` column
-reflects the order we created the positions. This code recalculates
-everything after a record is saved:
-
-```ruby
-# spec/factories/position.rb
-FactoryBot.define do
-  factory :position do
-    employee
-
-    title { Faker::Job.title }
-
-    after(:create) do |position|
-      unless position.historical_index
-        scope = Position
-          .where(employee_id: position.employee.id)
-          .order(created_at: :desc)
-        scope.each_with_index do |p, index|
-          p.update_attribute(:historical_index, index + 1)
-        end
-      end
-    end
-  end
-end
-```
-
-Let's associate an `Employee`. Start by seeding the data:
-
-```ruby
-let!(:employee) { create(:employee) }
-```
-
-And associate via `relationships`:
-
-```ruby
-let(:payload) do
-  {
-    data: {
-      type: 'positions',
-      attributes: { },
-      relationships: {
-        employee: {
-          data: {
-            id: employee.id.to_s,
-            type: 'employees'
-          }
-        }
-      }
-    }
-  }
-end
-```
-
-To ensure the `PositionResource` will process this relationship, the
-last step is to add it:
-
-```ruby
-# app/resources/position_resource.rb
-belongs_to :employee
-```
-
-This will associate the `Position` to the `Employee` as part of the
-creation process. The test should now pass - make the same change to
-`spec/api/v1/positions/create_spec.rb` to get a fully-passing test
-suite.
-
-#### Digging Deeper 🧐
-
-Why did we need the `employee_id` filter above? To explain that, let's dive deeper into the logic connecting Resources.
-
-If you hit `/api/v1/employees`, you'll see a number of
-[Links](https://www.graphiti.dev/guides/concepts/links) in the
-response. These are useful for lazy-loading, but the same logic
-applies to eager loading. Let's take a look at a Link to see how these
-Resources connect together:
-
-```ruby
-{
-  ...
-  relationships: {
-    positions: {
-      links: {
-        related: "http://localhost:3000/api/v1/positions?filter[employee_id]=1"
-      }
-    }
-  }
-  ...
-}
-```
-
-The salient bit: `/positions?filter[employee_id]=1`. In other words,
-fetch all Positions for the given Employee id.That means, whether we're lazy-loading data in separate requests or
-eager-loading in a single request, **the same logic fires
-under-the-hood**:
-
-```ruby
-PositionResource.all({
-  filter: { employee_id: 1 }
-})
-```
-
-This means we need `filter :employee_id, :integer` to satisfy the query.
-
-We can customize the logic connecting Resources in a few different
-ways. First some simple options:
-
-```ruby
-has_many :positions, foreign_key: :emp_id, primary_key: :eid
-```
-
-So far so good. The logic, and corresponding Link, both update as you'd
-expect (though we'd of course need a corresponding `filter :emp_id, :integer` on `PositionResource`).
-
-Those options are just simple versions of parameter customization.
-You can customize parameters connecting Resources with the `params` block:
-
-```ruby
-has_many :positions do
-  params do |hash, employees|
-    hash[:filter] # => { employee_id: employees.map(&:id) }
-    hash[:filter][:active] = true
-    hash[:sort] = '-created_at'
-  end
-end
-```
-
-Customizing these params affects the Link as well as the eager-load
-logic. Remember the parameters here should reflect the JSON:API
-specification, or anything `PositionResource.all` accepts.
-
-These are the most common options, but there's a bunch more. Check
-out the [Resource Relationships Guide](/concepts/relationships) to dig even deeper.
-
-
-
-  <h2 id="next">
-    <a href="/tutorial/step_3">
-      NEXT - 
-      <small>Step 3: Belongs To</small>
-      &raquo;
-    </a>
-  </h2>

data/docs/tutorial/step_3.md

@@ -1,142 +0,0 @@
----
-title: 'Step 3'
----
-
-### Step 3: Belongs To
-
-> [View the Diff](https://github.com/graphiti-api/employee_directory/compare/step_2_positions...step_3_departments)
-
-We'll be adding the database table `departments`:
-
-<table class="table table-small text-center">
-  <thead>
-    <tr>
-      <th class="text-center">id</th>
-      <th class="text-center">name</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>1</td>
-      <td>Engineering</td>
-    </tr>
-    <tr>
-      <td>2</td>
-      <td>Safety</td>
-    </tr>
-    <tr>
-      <td>3</td>
-      <td>QA</td>
-    </tr>
-  </tbody>
-</table>
-
-We'll also be adding a `department_id:integer` foreign key column to the `positions` table.
-
-### The Rails Stuff 🚂
-
-Generate the `Department` model:
-
-```bash
-$ bin/rails g model Department name:string
-```
-
-To add the foreign key to `positions`:
-
-```bash
-$ bin/rails g migration add_department_id_to_positions
-```
-
-```ruby
-class AddDepartmentIdToPositions < ActiveRecord::Migration[7.1]
-  def change
-    add_foreign_key :positions, :departments
-  end
-end
-```
-
-Update the database:
-
-```bash
-$ bin/rails db:migrate
-```
-
-Update our seed file:
-
-```ruby
-[Employee, Position, Department].each(&:delete_all)
-
-engineering = Department.create! name: 'Engineering'
-safety = Department.create! name: 'Safety'
-qa = Department.create! name: 'QA'
-departments = [engineering, safety, qa]
-
-100.times do
-  employee = Employee.create! first_name: Faker::Name.first_name,
-    last_name: Faker::Name.last_name,
-    age: rand(20..80)
-
-  (1..2).each do |i|
-    employee.positions.create! title: Faker::Job.title,
-      historical_index: i,
-      active: i == 1,
-      department: departments.sample
-  end
-end
-```
-
-Make sure to update `spec/factories/departments.rb` with randomized
-data. Then, since this is also a required relationship, update
-`spec/factories/positions.rb` to always seed a department when we ask to
-create a position:
-
-```ruby
-factory :position do
-  employee
-  department
-
-  # ... code ...
-end
-```
-
-### The Graphiti Stuff 🎨
-
-You should be used to this by now:
-
-```bash
-bin/rails g graphiti:resource Department name:string
-```
-
-Add the association:
-
-```ruby
-# app/resources/position_resource.rb
-belongs_to :department
-```
-
-And review the end of [Step 2](/tutorial/step_2) to get all your specs
-passing (add the department to the request payload). Practice makes perfect!
-
-#### Digging Deeper 🧐
-
-We didn't need a filter like we did in step two. That's
-because the primary key connecting the Resources is `id` by
-default. In other words, the Link would be something like:
-
-```bash
-/departments?filter[id]=1
-```
-
-Which we get out-of-the-📦
-
-But remember, you can customize these relationships just like the
-previous `has_many` section.
-
-
-  <h2 id="next">
-    <a href="/tutorial/step_4">
-      NEXT - 
-      <small>Step 4: Customizing Queries</small>
-      &raquo;
-    </a>
-  </h2>

data/docs/tutorial/step_4.md

@@ -1,135 +0,0 @@
----
-title: 'Step 4'
----
-
-### Step 4: Customizing Queries
-
-> [View the Diff](https://github.com/graphiti-api/employee_directory/compare/step_3_departments...step_4_customizations)
-
-So far, we've done fairly straightforward queries. If a user filters on
-`first_name`:
-
-`/api/v1/employees?filter[first_name]=Foo`
-
-We'll query the equivalent database column:
-
-```ruby
-Employee.where(first_name: 'Foo')
-```
-
-But what if there's more complex logic? Let's say we want to sort
-Employees on their `title` - which comes from the `positions` table.
-How would that work?
-
-### The Rails Stuff 🚂
-
-First, we need to get data for an Employee's **current** position.
-Let's start by defining what `current` means
-
-```ruby
-# app/models/position.rb
-scope :current, -> { where(historical_index: 1) }
-```
-
-> See the [ActiveRecord Scopes](https://guides.rubyonrails.org/active_record_querying.html#scopes) documentation if you're unfamiliar with this concept.
-
-Reference this scope in a new association:
-
-```ruby
-has_one :current_position,
-  -> { current },
-  class_name: 'Position'
-```
-
-Before moving on, let's review what we need to do. The `ActiveRecord`
-code for sorting Employees on their current position's title would be:
-
-```ruby
-Employee.joins(:current_position).merge(Position.order(title: :asc))
-```
-
-Let's wire this up to Graphiti:
-
-### The Graphiti Stuff 🎨
-
-We're only going to **sort** and **filter** on the `title` attribute -
-never display or persist. So start by defining the attribute as such:
-
-```ruby
-attribute :title, :string, only: [:filterable, :sortable]
-```
-
-Then the `sort` DSL to place our custom query:
-
-```ruby
-# app/resources/employee_resource.rb
-sort :title do |scope, direction|
-  scope.joins(:current_position).merge(Position.order(title: direction))
-end
-```
-
-That's it! When a request to sort on the title comes in, we'll alter our
-scope to join on the `positions` table, and order based on the current position `title`.
-
-The solution for filtering is similar:
-
-```ruby
-# app/resources/employee_resource.rb
-filter :title do
-  eq do |scope, value|
-    scope.joins(:current_position).merge(Position.where(title: value))
-  end
-end
-```
-
-We can now filter on title:
-
-`/api/v1/employees?filter[title]=Foo`
-
-Let's do one more example - how would we order Employees by department
-name? We *could* start the same way:
-
-```ruby
-attribute :department_name, :string, only: [:sortable]
-```
-
-But if we're ***only*** sorting, this is actually redundant. Whenever we
-use the `sort` or `filter` DSL, we're creating a sort-only or
-filter-only attribute under the hood. So let's define everything in one
-shot:
-
-```ruby
-sort :department_name, :string do |scope, value|
-  scope.joins(current_position: :department)
-    .merge(Department.order(name: value))
-end
-```
-
-Remember: you only need to pass the type as the second argument when an
-attribute doesn't already exist. And if you ever get an error saying
-something is unfilterable or unsortable, check to see if you've already
-defined a filter-only or sort-only attribute using these methods.
-
-#### Digging Deeper 🧐
-
-There's a critical part of Graphiti that makes everything easier: start
-by imagining it doesn't exist.
-
-In other words, the meat of the logic above had nothing to do with
-Graphiti code - we're "wiring up" independent ActiveRecord
-queries. If you're ever confused about query logic, get things working
-without Graphiti first.
-
-We could have changed the above to ActiveRecord scopes like
-`.order_by_title(title)`, making the wiring code even simpler. Consider
-doing this when the logic is reusable or particlar complex, but be aware
-of the tradeoffs of [double-testing units](https://www.graphiti.dev/guides/concepts/testing#double-testing-units).
-
-
-  <h2 id="next">
-    <a href="/tutorial/step_5">
-      NEXT - 
-      <small>Step 5: Has One</small>
-      &raquo;
-    </a>
-  </h2>

data/docs/tutorial/step_5.md

@@ -1,69 +0,0 @@
----
-title: 'Step 5'
----
-
-### Step 5: Has One
-
-> [View the Diff](https://github.com/graphiti-api/employee_directory/compare/step_4_customizations...step_5_has_one)
-
-In the last step, we introduced the concept of a "current position" to
-the model layer. Let's now expose that relationship to the API.
-
-### The Rails Stuff 🚂
-
-We already defined a `Position.current` scope that we'll re-use -
-let's just make a small tweak to support the opposite use case as
-well:
-
-```ruby
-scope :current, ->(bool) {
-  clause = { historical_index: 1 }
-  bool ? where(clause) : where.not(clause)
-}
-```
-
-### The Graphiti Stuff 🎨
-
-You might already have an idea how this might work from the prior step
-- we'll use the `params` block to customize the relationship. The `has_one` macro ensures the result is treated as a single object and
-not an array.
-
-```ruby
-# app/resources/employee_resource.rb
-has_one :current_position, resource: PositionResource do
-  params do |hash|
-    hash[:filter][:current] = true
-  end
-end
-```
-
-Which means we'll have to implement that filter - re-using the
-ActiveRecord scope we already defined!
-
-```ruby
-filter :current, :boolean do
-  eq { |scope, value| scope.current(value) }
-end
-```
-
-#### Digging Deeper 🧐
-
-In this example, we're able to return only a single record because we
-have a `historical_index` column. If this column didn't exist - maybe we're just ordering on `created_at` and taking the first record - we'd
-have a problem. What if we were loading 20 employees and wanted the
-`current_position` of each - what SQL would limit the resultset
-correctly?
-
-We call this a [faux has_one](/concepts/relationships#faux-has-one) and there's nothing easily done here. Graphiti will ensure only one record
-is returned by the API, but the query will take longer and loading extra
-records will eat memory. If there are lots of records in the
-association, look into adding a column like `historical_index`.
-
-
-  <h2 id="next">
-    <a href="/tutorial/step_6">
-      NEXT - 
-      <small>Step 6: Customizing Writes</small>
-      &raquo;
-    </a>
-  </h2>