graphiti 2.0.0.beta.6 → 2.0.0.beta.8

data/docs/js/reads.md

@@ -1,494 +0,0 @@
----
-title: 'Reads'
-sidebar_position: 4
----
-
-The interface for read operations is a simpler version of the [ActiveRecord Query Interface](http://guides.rubyonrails.org/active_record_querying.html). Instead of generating SQL, we'll be generating JSONAPI requests.
-
-## Basic Finders
-
-Execute queries with `.all()`, `find()`, or `.first()`:
-
-```typescript
-let response = await Post.all()
-response.data // array of Post instances
-```
-```javascript
-Post.all().then(function(response) {
-  response.data // array of Post instances
-});
-```
-<blockquote class="url">
-  <p>GET /posts</p>
-</blockquote>
-
-```typescript
-let response = await Post.find(123)
-response.data // Post instance
-```
-```javascript
-Post.find(123).then(function(response) {
-  response.data // Post instance
-});
-```
-<blockquote class="url">
-  <p>GET /posts/123</p>
-</blockquote>
-
-```typescript
-let response = await Post.first()
-response.data // Post instance
-```
-```javascript
-Post.first().then(function(response) {
-  response.data // Post instance
-});
-```
-<blockquote class="url">
-  <p>GET /posts?page[size]=1</p>
-</blockquote>
-
-## Composable Queries with Scopes
-
-The beauty of ORMs is their ability to compose queries. We'll be doing this by chaining together `Scope`s (query fragments). All of the methods you see on this page can be chained together - the request will not fire until the chain ends with `all()`, `first()`, or `find`. Example:
-
-```typescript
-let scope = Post.order({ name: "desc" })
-
-if (someCheckboxIsChecked) {
-  scope = scope.where({ important: true })
-} else {
-  scope = scope.where({ important: false })
-}
-
-scope.all() // request fires
-```
-
-```javascript
-var scope = Post.order({ name: "desc" });
-
-if (someCheckboxIsChecked) {
-  scope = scope.where({ important: true });
-} else {
-  scope = scope.where({ important: false });
-}
-
-scope.all() // request fires
-```
-<blockquote class="url">
-  <p>/posts?sort=-name&filter[important]=true</p>
-  <p>/posts?sort=-name&filter[important]=false</p>
-</blockquote>
-
-In practice, you'll probably have some scopes you want to re-use across different contexts. A best practice is to store these scopes as class methods (static methods) in the model:
-
-```typescript
-class Post extends ApplicationRecord {
-  // ... code ...
-  static superImportant() {
-    return this
-      .where({ ranking_gt: 8 })
-      .order({ ranking: 'desc' })
-      .stats({ total 'count' })
-  }
-}
-
-// get 10 super important posts
-let scope = Post.superImportant().per(10)
-scope.all() // fire query
-```
-
-```javascript
-const Post = ApplicationRecord.extend({
-  // ... code ...
-  static: {
-    superImportant() {
-      return this
-        .where({ ranking_gt: 8 })
-        .order({ ranking: 'desc' })
-        .stats({ total 'count' })
-    }
-  }
-})
-
-// get 10 super important posts
-var scope = Post.superImportant().per(10);
-scope.all() // fire query
-```
-<blockquote class="url">
-<p>/posts?sort=-ranking&stats[total]=count&page[size]=10&filter[ranking_gt]=8</p>
-</blockquote>
-
-## Metadata
-
-The [meta information](http://jsonapi.org/format/#document-meta) of the JSONAPI response is available as a POJO on the response:
-
-```typescript
-let response = await Post.all()
-response.meta // { stats: { total: { count: 100 } } }
-```
-```javascript
-await Post.all().then(function(response) {
-  response.meta // { stats: { total: { count: 100 } } }
-})
-```
-
-## Promises and Async/Await
-
-The result of `all()`, `first()` or `find` is a [Promise](https://developers.google.com/web/fundamentals/primers/promises). The promise will resolve to a `Response` object.
-
-A `Response` object has three keys - `data`, `meta`, and `raw`. `data` - the one you'll be using the most - will be a `Model` instance (or array of `Model`) instances. `meta` will be the [Meta Information](http://jsonapi.org/format/#document-meta) returned by the API (mostly used for statistics in our case). `raw` is only used to introspect the raw response document.
-
-```typescript
-Post.all().then((response) => {
-  response.data // array of Post instances
-  response.meta // js object from the server
-  response.raw // js response document
-})
-```
-
-```javascript
-Post.all().then(function(response) {
-  response.data // array of Post instances
-  response.meta // js object from the server
-  response.raw // js response document
-});
-```
-<blockquote class="url">
-  <p>/posts</p>
-</blockquote>
-
-Hopefully you're running in an environment that supports ES7's [Async/Await](https://hackernoon.com/6-reasons-why-javascripts-async-await-blows-promises-away-tutorial-c7ec10518dd9). This makes things even easier:
-
-```typescript
-let { data } = await Post.all()
-data // array of Post instances
-
-// alternatively
-
-let posts = (await Post.all()).data
-posts // array of Post instances
-```
-<blockquote class="url">
-  <p>/posts</p>
-</blockquote>
-
-## Filtering
-
-Use `#where()` to apply filters:
-
-```typescript
-Post.where({ important: true }).all()
-```
-<blockquote class="url">
-  <p>/posts?filter[important]=true</p>
-</blockquote>
-
-`#where()` clauses can be chained together. If the same key is seen twice, it will be overridden:
-
-```typescript
-Post
-  .where({ important: true })
-  .where({ ranking: 10 })
-  .where({ important: false })
-  .all()
-```
-<blockquote class="url">
-  <p>/posts?filter[important]=false&filter[ranking]=10</p>
-</blockquote>
-
-`#where()` clauses are based on **server implementation**. The key should be exactly as the server understands it. Here are some common conventions we promote:
-
-```typescript
-// id greater than 5
-Post.where({ id_gt: 5 }).all()
-
-// id greater than or equal to 5
-Post.where({ id_gte: 5 }).all()
-
-// id less than 5
-Post.where({ id_lt: 5 }).all()
-
-// id less or equal to 5
-Post.where({ id_lte: 5 }).all()
-
-// title starts with "foo"
-Post.where({ title: { prefix: "foo" } }).all()
-
-// OR these two values
-Post.where({ status_or: ['draft', 'review'] })
-
-// AND these two values (default)
-Post.where({ status: ['draft', 'review'] })
-```
-
-### Escaping Values
-
-[Graphiti treats a comma as a delimiter of multiple values](/concepts/resources#escaping-values). To escape the comma and tell Graphiti this is a single value, wrap it in `{{curlies}}`:
-
-```typescript
-Post.where({ title: "{{Hello World, here I am}}" })
-```
-
-## Sorting
-
-Use `#order()` to sort.
-
-If passed a string, it will default to **ascending**:
-
-```typescript
-Post.order("title").all()
-```
-<blockquote class="url">
-  <p>/posts?sort=title</p>
-</blockquote>
-
-
-Otherwise, pass an object:
-
-```typescript
-Post.order({ title: "desc" }).all()
-```
-<blockquote class="url">
-  <p>/posts?sort=-title</p>
-</blockquote>
-
-For multisort, chain multiple `#order()` clauses:
-
-```typescript
-Post
-  .order({ title: "desc" })
-  .order("ranking")
-  .all()
-```
-<blockquote class="url">
-  <p>/posts?sort=-title,ranking</p>
-</blockquote>
-
-## Pagination
-
-Use `#per()` to set the limit per page:
-
-```typescript
-Post.per(10).all()
-```
-<blockquote class="url">
-  <p>/posts?page[size]=10</p>
-</blockquote>
-
-Use `#page()` to set the current page:
-
-```typescript
-Post.page(5).all()
-```
-<blockquote class="url">
-  <p>/posts?page[number]=5</p>
-</blockquote>
-
-When chained together (10 per page, the 5th page):
-
-```typescript
-Post.page(5).per(10).all()
-```
-<blockquote class="url">
-  <p>/posts?page[size]=10&page[number]=5</p>
-</blockquote>
-
-## Fieldsets
-
-### Sparse Fieldsets
-
-Use `#select()` to limit the fields returned by the server:
-
-```typescript
-Post.select(['title', 'status']).all()
-```
-<blockquote class="url">
-  <p>/posts?fields[posts]=title,status</p>
-</blockquote>
-
-When dealing with relationships, it may be easier to pass an object, where the key is the corresponding JSONAPI type. This will be exactly what's sent to the server in `?fields`:
-
-```typescript
-Post.select({
-  posts: ['title', 'status'],
-  comments: ['created_at']
-}).all()
-```
-<blockquote class="url">
-  <p>/posts?fields[posts]=title,status&fields[comments]=created_at</p>
-</blockquote>
-
-### Extra Fieldsets
-
-Use `#selectExtra()` to explicitly request a field that doesn't usually come back (often computationally expensive):
-
-```typescript
-Post.selectExtra(['highlights', 'cumulative_ranking']).all()
-```
-<blockquote class="url">
-  <p>/posts?extra_fields[posts]=highlights,cumulative_ranking</p>
-</blockquote>
-
-Just like the `select` example above, feel free to pass an object specifying the fields for each relationship.
-
-## Includes
-
-Use `#includes()` to ["sideload"](http://jsonapi.org/format/#fetching-includes) associations:
-
-```typescript
-Post.includes("comments").all()
-```
-<blockquote class="url">
-  <p>/posts?include=comments</p>
-</blockquote>
-
-You can also pass an array of associations:
-
-```typescript
-Post.includes(["blog", "comments"]).all()
-```
-<blockquote class="url">
-  <p>/posts?include=blog,comments</p>
-</blockquote>
-
-Or an object for nested associations:
-
-```typescript
-Post.includes(["blog", { comments: "author" }]).all()
-```
-<blockquote class="url">
-  <p>/posts?include=blog,comments.author</p>
-</blockquote>
-
-## Nested Queries
-
-We can nest all read operations at any level of the graph. Let's say we wanted to fetch all `Post`s and their `Comment`s...but only return comments that are `active`, sorted by `created_at` descending. We can create a `Comment` scope as normal, then `#merge()` it into our `Post` scope:
-
-```typescript
-let commentScope = Comment
-  .where({ active: true })
-  .order({ created_at: "desc" })
-Post
-  .includes("comments")
-  .merge({ comments: commentScope })
-  .all()
-```
-
-```javascript
-var commentScope = Comment
-  .where({ active: true })
-  .order({ created_at: "desc" })
-Post
-  .includes("comments")
-  .merge({ comments: commentScope })
-  .all()
-```
-<blockquote class="url">
-  <p>/posts?include=comments&filter[comments][active]=true&sort=-comments.active</p>
-</blockquote>
-
-Because this can get verbose, it's often desirable to store it on the class:
-
-```typescript
-class Comment extends ApplicationRecord {
-  // ... code ...
-  static recent() {
-    return this
-      .where({ active: true })
-      .order({ created_at: "desc" })
-  }
-}
-
-Post.merge({ comments: Comment.recent() }).all()
-```
-
-```javascript
-const Comment = ApplicationRecord.extend({
-  // ... code ...
-  static: {
-    recent: function() {
-      return this
-        .where({ active: true })
-        .order({ created_at: "desc" })
-    }
-  }
-})
-
-Post
-  .includes("comments")
-  .merge({ comments: Comment.recent() })
-  .all()
-```
-
-Any number of scopes can be merged in. Just remember to `#include()` and `#merge()` relationship names **as the server understands them**:
-
-```typescript
-class Dog extends ApplicationRecord {
-  @BelongsTo() person: Person
-}
-
-// We've modeled this as Dog > person in javascript
-// And Person is jsonapiType "people"
-// But the server defined the relationship as "owner"
-Dog.includes("owner").merge({ owner: Person.limitedFields() })
-```
-
-```javascript
-const Dog = ApplicationRecord.extend({
-  // ... code ...
-  methods: {
-    person: belongsTo()
-  }
-})
-
-// We've modeled this as Dog > person in javascript
-// And Person is jsonapiType "people"
-// But the server defined the relationship as "owner"
-Dog.includes("owner").merge({ owner: Person.limitedFields() })
-```
-
-## Statistics
-
-Use `#stats()` to request statistics. Access stats within `meta`:
-
-```typescript
-let { data } = await Post.stats({ total: "count" }).all()
-data.meta.stats.total.count // the total count
-```
-
-```javascript
-Post.stats({ total: "count" }).all().then(function(response) {
-  response.meta.stats.total.count // the total count
-})
-```
-<blockquote class="url">
-  <p>/posts?stats[total]=count</p>
-</blockquote>
-
-Stats are always independent of pagination. If you request the total count, you'll get the total count even if you're limiting to 10 per page. This means to get **only** statistics - avoid returning `Post` instances altogether - request `0` results per page:
-
-```typescript
-let { data } = await Post.per(0)stats({ total: "count" }).all()
-data.meta.stats.total.count // the total count
-```
-
-```javascript
-Post
-  .per(0)
-  .stats({ total: "count" })
-  .all().then(function(response) {
-    response.meta.stats.total.count // the total count
-  })
-```
-<blockquote class="url">
-  <p>/posts?stats[total]=count&page[size]=0</p>
-</blockquote>
-
-  <h2 id="next">
-    <a href="/js/writes">
-      NEXT:
-      <small>Writes</small>
-      &raquo;
-    </a>
-  </h2>

data/docs/js/state-syncing.md

@@ -1,100 +0,0 @@
----
-title: 'State Syncing'
-sidebar_position: 8
----
-
-### State Syncing
-
-You may have encountered state management libraries like
-[Redux](https://redux.js.org) or [Vuex](https://vuex.vuejs.org/en/intro.html). These are fantastic libraries, but their usefulness is lessened with Spraypaint. As a full-fledged model layer, Spraypaint manages state for you, automatically.
-
-If you opt-in to this feature:
-
-```typescript
-ApplicationRecord.sync = true
-```
-
-Instances will sync up whenever the server tells us about updated state.
-Consider the scenario where an instance is initially loaded, then separately polled in the background:
-
-```typescript
-  let person = (await Person.find(1)).data
-
-  let poll = () => {
-    await Person.find(1)
-    setTimeout(poll, 1000)
-  }
-  poll()
-```
-
-```javascript
-  Person.find(1).then(function(response) {
-    var person = response.data;
-  });
-
-  var poll = function() {
-    Person.find(1);
-    setTimeout(poll, 1000);
-  }
-  poll()
-```
-
-Our `poll()` function **never assigns or updates `person`**. But if the server returns an updated `name` attribute, **`person.name` will be automatically updated**. This is true even if `person.name`
-is bound in 17 different nested components.
-
-Instances can still update their attributes independently - we only sync
-when the server returns updated data:
-
-```typescript
-  let instanceA = (await Person.find(1)).data
-  let instanceB = (await Person.find(1)).data
-
-  instanceA.name // "Jane"
-  instanceB.name // "Jane"
-
-  instanceB.name = "Silvia"
-  instanceA.name // "Jane"
-  instanceB.name // "Silvia"
-
-  await instanceB.save()
-  instanceA.name // "Silvia"
-  instanceB.name // "Silvia"
-```
-
-```javascript
-  var instanceA, instanceB;
-  Person.find(1).then(function(response) {
-    instanceA = response.data;
-  });
-  Person.find(1).then(function(response) {
-    instanceB = response.data;
-  });
-
-  instanceA.name // "Jane"
-  instanceB.name // "Jane"
-
-  instanceB.name = "Silvia"
-  instanceA.name // "Jane"
-  instanceB.name // "Silvia"
-
-  instanceB.save().then(function() {
-    instanceA.name // "Silvia"
-    instanceB.name // "Silvia"
-  });
-```
-
-#### Gotchas
-
-Under the hood, instances are listening for updates from a central data
-store. This means that you'll want to remove listeners whenever you no
-longer need the instance - otherwise it will never be garbage collected
-properly. To remove a listener:
-
-```typescript
-instance.unlisten()
-```
-
-In practice, when developing in a SPA, you'll want to `#unlisten()`
-whenever a view is destroyed and model instances no longer need to be referenced. If
-you are using VueJS, this is done automatically by adding [spraypaint-vue](https://github.com/graphiti-api/spraypaint-vue)
-to your application.