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

data/docs/intro.md

@@ -0,0 +1,307 @@
+---
+id: intro
+title: 'Graphiti'
+sidebar_label: 'Overview'
+sidebar_position: 0
+slug: /
+---
+
+# Graphiti
+
+:::info These are the 2.0 docs
+Graphiti 2.0 folds `graphiti-rails`, `graphiti_spec_helpers` and `graphiti_errors` into the main gem, and requires Ruby 3.2+ and ActiveSupport 7.1+. Rails is optional, and 7.1+ if you use it. Coming from 1.x? Start with the **[2.0 upgrade guide](/upgrading)**. Docs for 1.x are in the version picker.
+:::
+
+Graphiti sits on top of your models and exposes them over a [JSON:API](https://jsonapi.org)-compliant interface. You define Resources instead of controllers and serializers, and get filtering, sorting, pagination, sparse fieldsets, statistics, and nested reads and writes across relationships, all over one endpoint.
+
+Here is the whole loop. A Resource declares what's exposed:
+
+```ruby title="app/resources/employee_resource.rb"
+class EmployeeResource < ApplicationResource
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :age, :integer
+
+  has_many :positions
+end
+```
+
+The controller hands it the request params and renders the result:
+
+```ruby title="app/controllers/employees_controller.rb"
+class EmployeesController < ApplicationController
+  def index
+    employees = EmployeeResource.all(params)
+
+    respond_to do |format|
+      format.jsonapi { render(jsonapi: employees) }
+      format.json    { render(json: employees) }
+      format.xml     { render(xml: employees) }
+    end
+  end
+
+  def show
+    employee = EmployeeResource.find(params)
+    authorize employee.data # pundit. .data is the model itself
+    render(jsonapi: employee)
+  end
+end
+```
+
+A client asks for employees and their positions in one request:
+
+```http title="Request"
+GET /api/v1/employees?include=positions
+```
+
+```json title="Response"
+{
+  "data": [
+    {
+      "id": "1",
+      "type": "employees",
+      "attributes": {
+        "first_name": "Jane",
+        "last_name": "Doe",
+        "age": 34
+      },
+      "relationships": {
+        "positions": {
+          "data": [
+            { "type": "positions", "id": "1" },
+            { "type": "positions", "id": "2" }
+          ]
+        }
+      }
+    }
+  ],
+  "included": [
+    {
+      "id": "1",
+      "type": "positions",
+      "attributes": { "title": "Engineer" }
+    },
+    {
+      "id": "2",
+      "type": "positions",
+      "attributes": { "title": "Senior Engineer" }
+    }
+  ]
+}
+```
+
+That same Resource also serves `?filter[age][gt]=30`, `?sort=-age`, `?page[size]=10`, `?fields[employees]=first_name`, and `?stats[total]=count`, without writing any of them.
+
+The same proxy renders all three formats, so `/employees.jsonapi`, `/employees.json` and `/employees.xml` all work off one action.
+
+`.all` and `.find` return that proxy, so nothing has been queried yet. `.data` is where you reach the model, and also where per-record authorization goes. See [Authorization](/topics/authorization#integrating-with-pundit).
+
+If repeating that `respond_to` block gets old, the optional [`responders`](https://github.com/heartcombo/responders) integration collapses it to `respond_with(employees)`. See [Installation](/getting-started/installation#responders).
+
+## The whole Resource API
+
+Every Resource is a collection of defaults, and you can override any of them. Below is one Resource with those defaults written out the long way, the entire surface area on a single page. You wouldn't write this much by hand. It's here so you can see what's available.
+
+### ApplicationResource
+
+Every Resource inherits from an `ApplicationResource`, the same way models inherit from `ApplicationRecord`. This is where cross-cutting configuration lives, so individual Resources stay small. It's also the right place to put helpers like `current_user`, which guards throughout your API can then call.
+
+```ruby title="app/resources/application_resource.rb"
+class ApplicationResource < Graphiti::Resource
+  # Required when there's no corresponding model
+  self.abstract_class = true
+
+  # Subclasses override as needed
+  self.adapter = Graphiti::Adapters::ActiveRecord
+
+  # Flip any of these to lock down every Resource at once,
+  # e.g. a read-only API
+  self.attributes_readable_by_default = true
+  self.attributes_writable_by_default = true
+  self.attributes_sortable_by_default = true
+  self.attributes_filterable_by_default = true
+
+  # Used for link generation
+  self.base_url = Rails.application.routes.default_url_options[:host]
+  self.endpoint_namespace = '/api/v1'
+
+  def current_user
+    context.current_user
+  end
+end
+```
+
+### A Resource
+
+An individual Resource declares its attributes and relationships, plus anything about it that differs from the defaults:
+
+```ruby
+class EmployeeResource < ApplicationResource
+  # Both inferred from the class name. Set them only when they differ
+  self.model = Employee
+  self.type = :employees # the JSONAPI type
+
+  self.default_sort = [{ name: :desc }] # default nil
+  self.default_page_size = 10           # default 20
+
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :hired_at, :datetime, writable: false
+
+  has_many :positions
+end
+```
+
+That is a complete, working Resource. Everything below is how you override a piece of it.
+
+### Attributes
+
+```ruby
+# Each flag defaults to the corresponding class-level setting
+attribute :name, :string,
+  readable: self.attributes_readable_by_default,
+  writable: self.attributes_writable_by_default,
+  sortable: self.attributes_sortable_by_default,
+  filterable: self.attributes_filterable_by_default
+
+# Alter display
+# @object is your model instance
+attribute :name, :string do
+  @object.name.upcase
+end
+```
+
+### Sorting
+
+```ruby
+# Pass a type - sort :name, :string - if no attribute is defined
+sort :name do |scope, dir|
+  scope.order(name: dir)
+end
+```
+
+### Filtering
+
+```ruby
+# Pass a type - filter :name, :string - if no attribute is defined
+filter :name do
+  # All of these operators have not_ equivalents, e.g. not_eq
+  # Imagine ".where.not" instead of ".where"
+
+  eq do |scope, value|
+    scope.where("lower(name) IN ?", value.map(&:downcase))
+  end
+
+  eql do |scope, value|
+    scope.where(name: value)
+  end
+
+  prefix do |scope, value|
+    value.each do |v|
+      scope = scope.where('lower(name) LIKE ?', "#{v.downcase}%")
+    end
+    scope
+  end
+
+  suffix do |scope, value|
+    value.each do |v|
+      scope = scope.where('lower(name) LIKE ?', "%#{v.downcase}")
+    end
+    scope
+  end
+
+  match do |scope, value|
+    value.each do |v|
+      scope = scope.where('lower(name) LIKE ?', "%#{v.downcase}%")
+    end
+    scope
+  end
+end
+
+# Comparison operators, for integer, float, datetime, etc
+filter :age, :integer do
+  eq do |scope, value|
+    scope.where(age: value)
+  end
+
+  gt do |scope, value|
+    value.each { |v| scope = scope.where('age > ?', v) }
+    scope
+  end
+
+  gte do |scope, value|
+    value.each { |v| scope = scope.where('age >= ?', v) }
+    scope
+  end
+
+  lt do |scope, value|
+    value.each { |v| scope = scope.where('age < ?', v) }
+    scope
+  end
+
+  lte do |scope, value|
+    value.each { |v| scope = scope.where('age <= ?', v) }
+    scope
+  end
+end
+```
+
+Filters receive an array of values by default, which is why each operator above iterates. Pass `single: true` to accept one value instead.
+
+### Querying
+
+```ruby
+# Passed to sort, filter, paginate, etc
+# Apply global logic here: only return active Employees,
+# scope results to the current user, and so on
+def base_scope
+  Employee.all
+end
+
+# Must execute the query and return an array of Model instances
+def resolve(scope)
+  scope.to_a
+end
+```
+
+### Persisting
+
+Your adapter handles writes for you, so most Resources define nothing here. Reach for [lifecycle hooks](/concepts/persisting#persistence-lifecycle-hooks) when you need to intervene:
+
+```ruby
+before_attributes do |attributes|
+  # before attributes are assigned to the model
+end
+
+before_save do |model|
+  # assigned, but not yet persisted
+end
+
+before_commit do |model|
+  # saved and validated, still inside the transaction
+end
+```
+
+The model you inspect is the model that saves. Attributes are assigned up front, so you can hold the model, check it, and change it before anything is written. The instance you were handed is the one that gets persisted:
+
+```ruby
+employee = EmployeeResource.build(payload)
+
+employee.data           # the model, attributes already assigned, nothing written yet
+employee.data.valid?    # inspect it, or modify it
+employee.save           # persists that same instance
+```
+
+Updates work the same way, reading the persisted record until you apply the payload:
+
+```ruby
+proxy = EmployeeResource.find(payload)
+proxy.data.first_name       # => "asdf", straight from the database
+proxy.assign_attributes(payload)
+proxy.data.first_name       # => "Jane", assigned but still unsaved
+proxy.save(action: :update)
+```
+
+## Upgrading from 1.x
+
+The [2.0 upgrade guide](/upgrading) covers the whole migration: the three gems that folded into core, the deprecated spellings that still work but warn, and the two real behavior changes. Controllers now opt in via `Graphiti::Rails::Controller`, and `around_persistence` receives the model rather than an attributes hash.

data/docs/js/authentication.md

@@ -0,0 +1,63 @@
+---
+title: 'Authentication'
+sidebar_position: 7
+---
+
+### Authentication
+
+Spraypaint supports [JSON Web Tokens](https://jwt.io/introduction). These can
+be set manually, or automatically fetched from `localStorage`.
+
+To set manually:
+
+```typescript
+ApplicationRecord.jwt = 'myt0k3n'
+```
+> All requests will now send the header:<br />
+> `Authorization: Token token="myt0k3n"`.
+
+To set via `localStorage`, store the token with a key of `jwt` and it will be set automatically. To customize the `localStorage` key:
+
+```typescript
+ApplicationRecord.jwtStorage = "authtoken"
+```
+
+...or to opt-out of `localStorage` altogether:
+
+```typescript
+ApplicationRecord.jwtStorage = false
+```
+
+You can control the format of the header that is sent to the
+server:
+
+```typescript
+  class ApplicationRecord extends SpraypaintBase {
+    // ... code ...
+    static generateAuthHeader(token) {
+      return `Bearer ${token}`
+    }
+  }
+```
+
+```javascript
+  var ApplicationRecord = SpraypaintBase.extend({
+    // ... code ...
+    static: {
+      generateAuthHeader: function(token) {
+        return "Bearer " + token;
+      }
+    }
+  });
+```
+
+Finally, if your server returns a refreshed JWT within the `X-JWT` header, it will be used in all subsequent requests (and `localStorage`
+will be updated automatically if you're using it).
+
+  <h2 id="next">
+    <a href="/js/state-syncing">
+      NEXT:
+      <small>State Syncing</small>
+      &raquo;
+    </a>
+  </h2>

data/docs/js/ddau.md

@@ -0,0 +1,20 @@
+---
+title: 'Ddau'
+sidebar_position: 9
+---
+
+### Data Down, Actions Up
+
+It's a [popular pattern](http://www.samselikoff.com/blog/data-down-actions-up) to pass data **down** to components, avoid modifying state within the component, and instead pass **actions up** to modify state. This can make complex applications easier to track and reason about, and you'll see it in client-side frameworks like React.
+
+To follow this pattern, use `#dup()` when passing down to your component:
+
+```bash
+<my-component something="model.dup()" />
+```
+
+This will create a new instance of the model with all the same state.
+Avoid modifying this instance in your component and instead pass
+**actions up**.
+
+When opting-in to [state-syncing](/js/state-syncing) these instances will sync-up whenever one of these is instances is persisted. You won't have to worry about updating the child component when the parent instance is saved.

data/docs/js/extra-params.md

@@ -0,0 +1,41 @@
+---
+title: 'Extra Params'
+sidebar_position: 10
+---
+
+### Extra Params
+
+Sometimes you need to submit params that are not standard jsonapi params. One great example would be
+`https://yourdomain.com/users?debug=true` which is not a param for the `UserResource` you may have, but
+might enable functionality in your controller as needed.
+
+Invoking it is pretty straightforward, just invoke `extraParams` and pass in params and values you wish
+to add to your API call when executed.
+
+
+```typescript
+YourRecord.extraParams({ debug: true })
+```
+
+One common way to use this globally is to put this into a base class so it can be chained as part of 
+every resource.
+
+```typescript
+  @Model
+  export class ApplicationRecord extends SpraypaintBase {
+    static withDebug<T extends ApplicationRecord>(): Scope<T> {
+      return this.extraParams({ debug: true }) as Scope<T>;
+    }
+  }
+  // unfortunately you will need to pass in the 
+  // implementing class' type as a generic
+  UserRecord.withDebug<UserRecord>().all()
+```
+```javascript
+  const ApplicationRecord = SpraypaintBase.extend({
+    static: {
+      withDebug: () => this.extraParams({ debug: true });
+    }
+  })
+  UserRecord.withDebug().all()
+```

data/docs/js/index.md

@@ -0,0 +1,112 @@
+---
+title: 'Index'
+sidebar_position: 1
+---
+
+<h1>
+  Spraypaint
+  <small>the isomorphic, framework-agnostic Graphiti ORM</small>
+</h1>
+
+### Why Spraypaint?
+
+Contracts like JSONAPI and GraphQL treat the API like a database. When querying a database, we have two options:
+
+  * Type the low-level query language directly (in the database world, this would be hand-typing SQL).
+  * Use an ORM (like Rails's `ActiveRecord`, Phoenix's `Ecto`, Django's `DjangoORM`, or Node's `Sequelize`).
+
+While both options have pros and cons, we tend to think ORMs have two overwhelming benefits: ***ease of use*** and ***composable queries***. We'll explore both these concepts in other sections.
+
+So, we want a javascript ORM for our JSONAPI "database". Because `ActiveRecord` is arguably the most well-known ORM, we've tried to match its interface to make this library accessible to new users. That said, you'll find we've tried to favor *explicitness* over *implicitness* in order to avoid common `ActiveRecord` pitfalls.
+
+            <span>Typescript</span>
+              <span>Javascript</span>
+```typescript
+// Spraypaint is like "ActiveRecord in Javascript". It can:
+//
+// * Deeply nest reads and writes
+// * Automatically handle validation errors
+// * Replace *ux patterns
+// * ...and much more!
+
+// define models
+@Model()
+class ApplicationRecord extends SpraypaintBase {
+  static baseUrl = "http://my-api.com"
+  static apiNamespace = "/api/v1"
+}
+
+@Model()
+class Person extends ApplicationRecord {
+  static jsonapiType = "people"
+
+  @Attr() firstName: string
+  @Attr() lastName: string
+
+  get fullName() {
+    return `${this.firstName} ${this.lastName}`
+  }
+}
+
+// execute queries
+Person
+  .where({ first_name: 'John' })
+  .order({ created_at: 'desc' })
+  .per(10).page(2)
+  .includes({ jobs: 'company' })
+  .select({ people: ['first_name', 'last_name'] })
+
+// persist data
+let person = new Person({ firstName: 'Jane' })
+person.save()
+```
+
+```javascript
+// Spraypaint is like "ActiveRecord in Javascript". It can:
+//
+// * Deeply nest reads and writes
+// * Automatically handle validation errors
+// * Replace *ux patterns
+// * ...and much more!
+
+var spnt = require('spraypaint/dist/spraypaint')
+
+// define models
+const ApplicationRecord = spnt.JSORMBase.extend({
+  static: {
+    baseUrl: 'http://my-api.com',
+    apiNamespace: '/api/v1'
+  }
+})
+
+const Person = ApplicationRecord.extend({
+  attrs: {
+    firstName: spnt.attr(),
+    lastName: spnt.attr()
+  },
+  methods: {
+    fullName: function() {
+      return this.firstName + ' ' + this.lastName;
+    }
+  }
+})
+
+// execute queries
+Person
+  .where({ first_name: 'John' })
+  .order({ created_at: 'desc' })
+  .per(10).page(2)
+  .includes({ jobs: 'company' })
+  .select({ people: ['first_name', 'last_name'] })
+
+// persist data
+var person = new Person({ firstName: 'Jane' })
+person.save()
+```
+
+### Where to Go Next
+
+  * [Installation](/js/installation) - install spraypaint and connect it to your API
+  * [Models](/js/models) - define models, attributes, and relationships
+  * [Reads](/js/reads) - query your API with a composable, ActiveRecord-like interface
+  * [Writes](/js/writes) - create, update, and destroy records

data/docs/js/installation.md

@@ -0,0 +1,120 @@
+---
+title: 'Installation'
+sidebar_position: 2
+---
+
+### Installation
+
+Installation is straightforward. Since we use `fetch` underneath the hood, we recommend installing alongside a `fetch` polyfill.
+
+If using `yarn`:
+
+```bash
+$ yarn add spraypaint isomorphic-fetch
+```
+
+If using `npm`:
+
+```bash
+$ npm install spraypaint isomorphic-fetch
+```
+
+Now import it:
+
+```typescript
+import {
+  Model,
+  SpraypaintBase,
+  Attr,
+  BelongsTo,
+  HasMany
+  // etc
+} from "spraypaint"
+```
+
+```javascript
+const {
+  SpraypaintBase,
+  attr,
+  belongsTo,
+  hasMany
+  // etc
+} = require("spraypaint/dist/spraypaint")
+```
+
+...or, if you're avoiding JS modules, `spraypaint` will be available as a global in the browser.
+
+### Typescript
+
+Spraypaint works with modern TypeScript. Depending on your `tsconfig.json` settings, you may need a `!` after each attribute and relationship declaration:
+
+```typescript
+@Attr first_name!: string
+@HasMany() positions!: Position[]
+```
+
+This is because of [Strict Class Initialization](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#strict-class-initialization) - `strictPropertyInitialization` expects every declared class field to be assigned in the constructor, which Spraypaint's decorators handle at runtime rather than at construction time. For the purposes of Spraypaint, we don't need this check. Remove the need for `!` (as the rest of these guides do) by setting
+
+`"strictPropertyInitialization": false`
+
+in `tsconfig.json`.
+
+### Connecting to the API
+
+Just like `ActiveRecord`, our models will inherit from a base class that holds connection information (`ApplicationRecord`, or `ActiveRecord::Base` in Rails < 5):
+
+```typescript
+@Model()
+class ApplicationRecord extends SpraypaintBase {
+  static baseUrl = "http://my-api.com"
+  static apiNamespace = "/api/v1"
+}
+```
+
+```javascript
+const ApplicationRecord = SpraypaintBase.extend({
+  static: {
+    baseUrl: "http://my-api.com",
+    apiNamespace: "/api/v1"
+  }
+})
+```
+
+All URLs follow the following pattern:
+
+  * `baseUrl` + `apiNamespace` + `jsonapiType`
+
+As you can see above, typically `baseUrl` and `apiNamespace` are set on a top-level `ApplicationRecord` (though any subclass can override). `jsonapiType`, however, is set per-model - see [Models](/js/models) for how to define it.
+
+> **TIP**: Avoid CORS and use relative paths by setting `baseUrl` to `""`
+
+> **TIP**: You can always use the `endpoint` option to override this pattern and set the endpoint manually.
+
+#### Setting Application Name
+
+It can be helpful to send the name of your client application in request headers. With this information, servers can keep track of which clients are hitting which APIs.
+
+To do this:
+
+```typescript
+@Model()
+class Person extends ApplicationRecord {
+  static clientApplication = "sales-backend"
+}
+```
+
+```javascript
+const Person = ApplicationRecord.extend({
+  static: {
+    clientApplication: "sales-backend"
+  }
+})
+```
+
+  <h2 id="next">
+    <a href="/js/models">
+      NEXT:
+      <small>Models</small>
+      &raquo;
+    </a>
+  </h2>