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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphiti
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta.7
+  version: 2.0.0.beta.8
 platform: ruby
 authors:
 - Lee Richmond
@@ -129,30 +129,36 @@ dependencies:
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: kaminari
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '1.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -187,14 +193,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: '1.56'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: '1.56'
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
@@ -209,6 +215,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -230,9 +250,11 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".git-blame-ignore-revs"
 - ".github/probots.yml"
 - ".github/workflows/ci.yml"
 - ".github/workflows/docs.yml"
+- ".github/workflows/notify-example-app.yml"
 - ".github/workflows/release.yml"
 - ".gitignore"
 - ".npmrc"
@@ -255,52 +277,6 @@ files:
 - bin/console
 - bin/rspec
 - bin/setup
-- docs/concepts/backends-and-models.md
-- docs/concepts/endpoints.md
-- docs/concepts/links.md
-- docs/concepts/overview.md
-- docs/concepts/persisting.md
-- docs/concepts/relationships.md
-- docs/concepts/resources.md
-- docs/getting-started/first-api.md
-- docs/getting-started/installation.md
-- docs/intro.md
-- docs/js/authentication.md
-- docs/js/ddau.md
-- docs/js/extra-params.md
-- docs/js/index.md
-- docs/js/installation.md
-- docs/js/middleware.md
-- docs/js/models.md
-- docs/js/reads.md
-- docs/js/state-syncing.md
-- docs/js/writes.md
-- docs/reference/vandal.md
-- docs/reference/why.md
-- docs/topics/authorization.md
-- docs/topics/caching.md
-- docs/topics/customizing-sideloads.md
-- docs/topics/debugging.md
-- docs/topics/error-handling.md
-- docs/topics/etags.md
-- docs/topics/hopping-relationships.md
-- docs/topics/json-attributes.md
-- docs/topics/openstruct-models.md
-- docs/topics/remote-resources.md
-- docs/topics/testing.md
-- docs/topics/without-activerecord.md
-- docs/tutorial/index.md
-- docs/tutorial/step_0.md
-- docs/tutorial/step_1.md
-- docs/tutorial/step_2.md
-- docs/tutorial/step_3.md
-- docs/tutorial/step_4.md
-- docs/tutorial/step_5.md
-- docs/tutorial/step_6.md
-- docs/tutorial/step_7.md
-- docs/tutorial/step_8.md
-- docs/tutorial/step_9.md
-- docs/upgrading.md
 - exe/graphiti
 - gemfiles/.bundle/config
 - gemfiles/rails_7_1.gemfile
@@ -434,148 +410,6 @@ files:
 - lib/tasks/graphiti.rake
 - package-lock.json
 - package.json
-- website/.gitignore
-- website/README.md
-- website/docusaurus.config.js
-- website/package-lock.json
-- website/package.json
-- website/sidebars.js
-- website/src/css/custom.css
-- website/src/pages/markdown-page.mdx
-- website/static/.nojekyll
-- website/static/1.13/2019/03/31/graphiti-1-0.html
-- website/static/1.13/2019/05/08/graphiti-1-1.html
-- website/static/1.13/2019/05/20/graphiti-1-2.html
-- website/static/1.13/2019/10/14/tutorial.html
-- website/static/1.13/CNAME
-- website/static/1.13/README.md
-- website/static/1.13/assets/css/syntax.css
-- website/static/1.13/assets/favicons/android-chrome-192x192.png
-- website/static/1.13/assets/favicons/android-chrome-256x256.png
-- website/static/1.13/assets/favicons/apple-touch-icon.png
-- website/static/1.13/assets/favicons/browserconfig.xml
-- website/static/1.13/assets/favicons/favicon-16x16.png
-- website/static/1.13/assets/favicons/favicon-32x32.png
-- website/static/1.13/assets/favicons/favicon.ico
-- website/static/1.13/assets/favicons/mstile-150x150.png
-- website/static/1.13/assets/favicons/safari-pinned-tab.svg
-- website/static/1.13/assets/favicons/site.webmanifest
-- website/static/1.13/assets/img/backend.gif
-- website/static/1.13/assets/img/conformity.png
-- website/static/1.13/assets/img/error_payload.png
-- website/static/1.13/assets/img/fancy-cushion.png
-- website/static/1.13/assets/img/gh.png
-- website/static/1.13/assets/img/home-bg.jpg
-- website/static/1.13/assets/img/lifecycle.gif
-- website/static/1.13/assets/img/logo-500.png
-- website/static/1.13/assets/img/logo.png
-- website/static/1.13/assets/img/love-graffiti.jpg
-- website/static/1.13/assets/img/meta_total_count.png
-- website/static/1.13/assets/img/persist.jpg
-- website/static/1.13/assets/img/resource.gif
-- website/static/1.13/assets/img/rest-graffiti.jpg
-- website/static/1.13/assets/img/rest1.gif
-- website/static/1.13/assets/img/rest2.gif
-- website/static/1.13/assets/img/rest3.gif
-- website/static/1.13/assets/img/rethink-rest-graffiti.jpg
-- website/static/1.13/assets/img/sunrise.png
-- website/static/1.13/assets/img/why.png
-- website/static/1.13/assets/js/highlight.pack.js
-- website/static/1.13/assets/main.css
-- website/static/1.13/assets/main.css.map
-- website/static/1.13/bin/bundle
-- website/static/1.13/bin/jekyll
-- website/static/1.13/bin/kramdown
-- website/static/1.13/bin/listen
-- website/static/1.13/bin/rake
-- website/static/1.13/bin/rougify
-- website/static/1.13/bin/safe_yaml
-- website/static/1.13/bin/sass
-- website/static/1.13/bin/sass-convert
-- website/static/1.13/bin/scss
-- website/static/1.13/blog.html
-- website/static/1.13/cheatsheet.html
-- website/static/1.13/cookbooks/authorization.md
-- website/static/1.13/cookbooks/caching.md
-- website/static/1.13/cookbooks/customizing-sideloads.html
-- website/static/1.13/cookbooks/etags.md
-- website/static/1.13/cookbooks/hopping-relationships.html
-- website/static/1.13/cookbooks/json_attributes.md
-- website/static/1.13/cookbooks/openstruct-models.md
-- website/static/1.13/cookbooks/remote-resources.md
-- website/static/1.13/cookbooks/without-activerecord.html
-- website/static/1.13/features.html
-- website/static/1.13/feed.xml
-- website/static/1.13/guides/concepts/backends-and-models.html
-- website/static/1.13/guides/concepts/debugging.html
-- website/static/1.13/guides/concepts/endpoints.html
-- website/static/1.13/guides/concepts/error-handling.html
-- website/static/1.13/guides/concepts/links.html
-- website/static/1.13/guides/concepts/remote-resources.html
-- website/static/1.13/guides/concepts/resources.html
-- website/static/1.13/guides/concepts/testing.html
-- website/static/1.13/guides/getting-started/installation.html
-- website/static/1.13/guides/graphiti-rails-migration.html
-- website/static/1.13/guides/index.html
-- website/static/1.13/guides/overview.html
-- website/static/1.13/guides/upgrading-2-0.html
-- website/static/1.13/guides/upgrading.html
-- website/static/1.13/guides/vandal.html
-- website/static/1.13/guides/why.html
-- website/static/1.13/index.html
-- website/static/1.13/js/authentication.html
-- website/static/1.13/js/ddau.html
-- website/static/1.13/js/extra-params.html
-- website/static/1.13/js/index.html
-- website/static/1.13/js/installation.html
-- website/static/1.13/js/introduction.html
-- website/static/1.13/js/middleware.html
-- website/static/1.13/js/reads/fieldsets.html
-- website/static/1.13/js/reads/filtering.html
-- website/static/1.13/js/reads/includes.html
-- website/static/1.13/js/reads/index.html
-- website/static/1.13/js/reads/nested-queries.html
-- website/static/1.13/js/reads/pagination.html
-- website/static/1.13/js/reads/sorting.html
-- website/static/1.13/js/reads/statistics.html
-- website/static/1.13/js/state-syncing.html
-- website/static/1.13/js/writes/deferred.html
-- website/static/1.13/js/writes/dirty-tracking.html
-- website/static/1.13/js/writes/index.html
-- website/static/1.13/js/writes/nested.html
-- website/static/1.13/js/writes/validations.html
-- website/static/1.13/quickstart.html
-- website/static/1.13/template
-- website/static/1.13/tutorial/index.html
-- website/static/1.13/tutorial/step_0.html
-- website/static/1.13/tutorial/step_1.html
-- website/static/1.13/tutorial/step_2.html
-- website/static/1.13/tutorial/step_3.html
-- website/static/1.13/tutorial/step_4.html
-- website/static/1.13/tutorial/step_5.html
-- website/static/1.13/tutorial/step_6.html
-- website/static/1.13/tutorial/step_7.html
-- website/static/1.13/tutorial/step_8.html
-- website/static/1.13/tutorial/step_9.html
-- website/static/CNAME
-- website/static/assets/img/error_payload.png
-- website/static/assets/img/legacy/legacy-0378a3bb39.png
-- website/static/assets/img/legacy/legacy-05bbd3e5fd.png
-- website/static/assets/img/legacy/legacy-07aa104495.png
-- website/static/assets/img/legacy/legacy-0c75a16b3a.gif
-- website/static/assets/img/legacy/legacy-3076df6209.png
-- website/static/assets/img/legacy/legacy-7f6889bc89.png
-- website/static/assets/img/legacy/legacy-a2cc4363c3.png
-- website/static/assets/img/legacy/legacy-f67cfa89ab.png
-- website/static/assets/img/meta_total_count.png
-- website/static/img/docusaurus-social-card.jpg
-- website/static/img/docusaurus.png
-- website/static/img/favicon.ico
-- website/static/img/logo.png
-- website/static/img/logo.svg
-- website/static/img/undraw_docusaurus_mountain.svg
-- website/static/img/undraw_docusaurus_react.svg
-- website/static/img/undraw_docusaurus_tree.svg
 homepage: https://github.com/graphiti-api/graphiti
 licenses:
 - MIT

data/docs/concepts/backends-and-models.md

@@ -1,122 +0,0 @@
----
-title: 'Backends and Models'
----
-
-# Backends and Models
-
-A Resource queries a **Backend** and returns **Models** from what comes back. Graphiti serializes the Models.
-
-With ActiveRecord those are the same object. `Employee` is both the thing you query and the thing you render, and you can skip most of this page. It matters when they're separate: a search index, an HTTP service, a document store. Then the Backend is whatever you query, and the Model is whatever you hand back.
-
-## Scopes {#scopes}
-
-A **scope** is whatever your backend needs to run a query. Graphiti doesn't care what it is. For ActiveRecord it's an `ActiveRecord::Relation`. Here it's a plain hash:
-
-```ruby
-class EmployeeResource < ApplicationResource
-  self.adapter = Graphiti::Adapters::Null
-
-  attribute :name, :string
-
-  def base_scope
-    { conditions: {}, sort: {} }
-  end
-
-  filter :name do
-    eq do |scope, value|
-      scope[:conditions].merge!(value)
-      scope
-    end
-  end
-
-  sort :name do |scope, direction|
-    scope[:sort] = { name: direction }
-    scope
-  end
-
-  def resolve(scope)
-    results = Backend.query(scope)
-    results.map { |result| Employee.new(result) }
-  end
-end
-```
-
-`base_scope` is the starting point, each `filter` and `sort` block mutates it based on request params, and `resolve` runs the query and returns Models.
-
-**Every block must return the scope.** Returning the result of `merge!` or an assignment instead of the scope itself is the most common way to break this.
-
-Writing that per Resource gets old. Once the pattern stabilizes, move it into an [Adapter](/topics/without-activerecord#adapters) and Resources go back to being declarative:
-
-```ruby
-class EmployeeResource < ApplicationResource
-  self.adapter = BackendAdapter
-  attribute :name, :string
-end
-```
-
-## What a Model has to do {#model-requirements}
-
-**Respond to `id`, uniquely.** Graphiti uses `model.id` to tell records apart when rendering. Duplicate ids produce wrong output, not an error.
-
-If the underlying record has no id, generate one:
-
-```ruby
-def id
-  @id ||= SecureRandom.uuid
-end
-```
-
-**Respond to its readable attributes.** `attribute :name, :string` calls `model.name`. If your Model doesn't have that method, pass a block instead:
-
-```ruby
-attribute :name, :string do
-  @object.full_name
-end
-```
-
-**Include `ActiveModel::Validations` if you want validation errors.** Graphiti checks models on write requests and renders a [JSON:API errors payload](http://jsonapi.org/format/#errors) from `model.errors`. Without it, an invalid model saves silently:
-
-```ruby
-class Employee
-  include ActiveModel::Validations
-
-  validates :name, presence: true
-end
-```
-
-## Writing a Model {#model-implementations}
-
-Graphiti has no opinion here. A plain class works:
-
-```ruby
-class Employee
-  attr_accessor :id, :first_name, :last_name, :age
-
-  def initialize(attrs = {})
-    attrs.each_pair { |key, value| send(:"#{key}=", value) }
-  end
-end
-```
-
-[ActiveModel::Model](https://api.rubyonrails.org/classes/ActiveModel/Model.html) gives you the constructor and validations for free:
-
-```ruby
-class Employee
-  include ActiveModel::Model
-
-  attr_accessor :id, :first_name, :last_name, :age
-end
-```
-
-[Dry::Struct](https://dry-rb.org/gems/dry-struct) adds type enforcement, and dry-types is already a Graphiti dependency:
-
-```ruby
-class Employee < Dry::Struct
-  attribute :id, Types::Integer
-  attribute :first_name, Types::String
-  attribute :last_name, Types::String
-  attribute :age, Types::Integer
-end
-```
-
-`OpenStruct` also works and is what Graphiti uses internally for remote resources, but it fails quietly in ways the others don't. See [OpenStruct Models](/topics/openstruct-models) before reaching for it.

data/docs/concepts/endpoints.md

@@ -1,183 +0,0 @@
----
-title: 'Endpoints'
----
-
-## Overview {#overview}
-
-**Endpoints** expose and customize
-[Resources](/concepts/resources).
-
-Resources themselves can operate completely independently of a request or response:
-
-```ruby
-employees = EmployeeResource.all({
-  filter: { title: 'engineer' },
-  sort: '-created_at',
-  page: { size: 10 },
-  include: 'positions.department'
-})
-
-employees.map(&:first_name) # => ['Jane', 'John', ...]
-employees.to_json # => { employees: [{ ... }] }
-```
-
-And Resources connect to other Resources. Our graph of data is defined
-**outside** of the actual API.
-
-Endpoints expose this graph to the world. We might choose to have a `/employees` endpoint that can eager load comments (`?include=comments`), but never expose `/comments` directly. Or, we could do the opposite: expose lazy-loading `/comments`, but disallow eager loading from `/employees`. We can add caching rules, or add an `/exemplary_employees` endpoint with special query overrides.
-
-Finally, Endpoints are in charge of the [HTTP specification](https://tools.ietf.org/html/rfc2616):
-request processing, response codes, caching, MIME types, and so on. If you're thinking
-Rails, an Endpoint is the combination of a Route and Controller.
-
-### Endpoint Logic {#endpoint-logic}
-
-Often, you won't need to customize Endpoints - especially if you're
-using our [Rails Resource
-generator](/concepts/resources#generators). Endpoint logic mostly
-concerns:
-
-* Caching
-* Side-effect behavior specific to the endpoint (e.g.: sending a
-welcome email from `/users#create` but not `/admin/users#create`)
-* Authorization (e.g `before_action`)
-* Custom query parameter handling
-* Validation handling
-* Error handling
-* Limiting Resource behavior
-* Customizing Resource behavior
-
-If your logic falls elsewhere, consider a Resource or Model.
-
-### Rails Integration {#rails-integration}
-
-When using Rails, an endpoint is the combination of a Route and
-Controller:
-
-```ruby
-# config/routes.rb
-resources :posts, only: [:index]
-
-# app/controllers/posts_controller.rb
-class PostsController < ApplicationController
-  def index
-    posts = PostResource.all(params)
-    respond_with(posts)
-  end
-end
-```
-
-You'll note that Graphiti hooks into Rails with a mixin (set when using
-our application generator):
-
-```ruby
-class ApplicationController < ActionController::API
-  include Graphiti::Rails::Controller
-
-  # ... code ...
-end
-```
-
-This gives us [#sideload_allowlist](#sideload-allowlist) and sets the
-[context](/concepts/resources#context).
-
-## Customizing Resources {#customizing-resources}
-
-### Scope Overrides {#scope-overrides}
-
-One common use case for endpoints is customizing the Resource
-[base scope](/concepts/resources#base-scope). This causes a new
-"starting point" for query building.
-
-Consider the endpoints `/posts` (basic CRUD) and `/top_posts`. Though both are associated to PostResource, `/top_posts` ensures that only
-Posts with a certain number of upvotes get returned:
-
-```ruby
-def index
-  base_scope = Post.where("upvotes > ?", 100)
-  posts = PostResource.all(params, base_scope)
-  respond_with(posts)
-end
-```
-
-We're able to reuse all the other logic in PostResource - relationships,
-filters, sorts, etc - while only returning "Top Posts".
-
-### Sideload Allowlist {#sideload-allowlist}
-
-Resources define relationships to other resources. But we may not want
-all of those relationships exposed at a given endpoint.
-
-Let's say we've defined relationships:
-
-`Employee > Position > Department > Hardware > CostHistory`
-
-It's reasonable to get an Employee, their Positions, and Departments for
-those positions in a single request. But is it really valid to *also* pull down
-all the hardware, as well as all the historical data on the cost of that hardware,
-in a single request? Allowing the entire graph to be pulled down in a single request can cause excessive load on our
-servers (and this is probably a better fit for lazy-loading via
-[Links](/concepts/links)).
-
-Let's instead say that if we're entering the graph at `/employees`, the
-furthest we can go is Department:
-
-```ruby
-class EmployeesController < ApplicationController
-  self.sideload_allowlist = {
-    index: { positions: 'department' }
-  }
-
-  # ... code ...
-end
-```
-
-## Caching {#caching}
-
-### Etags {#etags}
-
-[ETags](https://robots.thoughtbot.com/introduction-to-conditional-http-caching-with-rails) are an important concept that is often overlooked. Etags tell browsers
-that the response to a GET request hasn't changed since the last request and
-can be safely pulled from the browser cache. If you care about sparse fieldsets,
-you should care about ETags - if you're limiting fields to reduce payload size,
-how about a payload size of **zero**?
-
-ETags are set by default in Rails, by checking the response body. This won't prevent queries from executing, but it will save clients from downloading the response again if nothing has changed.
-
-Let's manually set an ETag:
-
-```ruby
-def index
-  posts = PostResource.all(params)
-
-  if stale?(posts.data)
-    respond_with(posts)
-  end
-end
-```
-
-From the [documentation on #stale?](https://api.rubyonrails.org/classes/ActionController/ConditionalGet.html#method-i-stale-3F):
-
-> *In this case last_modified will be set by calling `maximum(:updated_at)` on the collection (the timestamp of the most recently updated record) and the etag by passing the object itself.*
-
-Also consider the use case where data is ingested hourly. We can avoid a
-query altogether by checking when the last ingestion ran:
-
-```ruby
-def index
-  if stale?(EmployeeIngestion.last)
-    employees = EmployeeResource.all(params)
-    respond_with(employees)
-  end
-end
-```
-
-> **CAVEAT**: When setting ETags, consider sideloads. In the above examples
-> we are checking to see the last update of an Employee, but we may be
-> sideloading (and filtering) Positions as well. Use custom endpoints or
-> [Sideload Allowlist](#sideload-allowlist) to mitigate this issue.
-
-## Testing  {#testing}
-
-If you have custom Endpoint logic, we suggest testing using an [API
-Test](/topics/testing#api-tests).