Merge pull request #870 from orbitjs/docs

Progress on v0.17 docs

website/docs/api/index.md

@@ -7,30 +7,124 @@ sidebar_position: 0.5
 custom_edit_url: null
 ---
 
-## Core Packages
+Orbit is distributed on npm through the
+[@orbit](https://www.npmjs.com/org/orbit) organization in several packages.
+This API reference is organized according to these packages.
 
-- [@orbit/core](./api/core)
-- [@orbit/coordinator](./api/coordinator)
-- [@orbit/data](./api/data)
-- [@orbit/identity-map](./api/identity-map)
-- [@orbit/immutable](./api/immutable)
-- [@orbit/serializers](./api/serializers)
-- [@orbit/utils](./api/utils)
-- [@orbit/validators](./api/validators)
+## Core libraries
 
-### Buckets
+Orbit consists of the following core libraries:
 
-- [@orbit/indexeddb-bucket](./api/indexeddb-bucket)
-- [@orbit/local-storage-bucket](./api/local-storage-bucket)
+- [@orbit/core](./core/index.md) - A core
+  set of primitives for performing, tracking, and responding to asynchronous
+  tasks, including:
 
-## Record-based Packages
+  - An event system that allows listeners to engage with the fulfillment of
+    events by returning promises.
 
-- [@orbit/records](./api/records)
-- [@orbit/record-cache](./api/record-cache)
+  - An asynchronous task processing queue.
 
-### Sources
+  - A log that tracks a history of changes and allows for revision and
+    interrogation.
 
-- [@orbit/indexeddb](./api/indexeddb)
-- [@orbit/jsonapi](./api/jsonapi)
-- [@orbit/local-storage](./api/local-storage)
-- [@orbit/memory](./api/memory)
+  - A bucket interface for persisting state. Used by logs and queues.
+
+- [@orbit/data](./data/index.md) - Applies the core Orbit primitives to data
+  sources. Includes the following:
+
+  - [`Source`](./data/classes/Source.md) - a base class that can be used to
+    abstract any source of data. Sources can be decorated as
+    [`@queryable`](./data/interfaces/Queryable.md),
+    [`@updatable`](./data/interfaces/Updatable.md), and/or
+    [`@syncable`](./data/interfaces/Syncable.md).
+
+  - [`Transform`](./data/interfaces/Transform.md) - composed of any number of
+    [`Operation`](./data/interfaces/Operation.md)s, a transform represents a set
+    of mutations to be applied transactionally.
+
+  - [`Query`](./data/interfaces/Query.md) - composed of one or more
+    [`QueryExpression`](./data/interfaces/QueryExpression.md)s, a query
+    represents a request for data.
+
+- [@orbit/records](./records/index.md) - Extends the general data concepts from
+  [@orbit/data](./data/index.md) to make record-specific classes and interfaces.
+  These include:
+
+  - `RecordSource` - a base class that extends `Source`.
+
+  - `RecordSchema` - define models, including attributes and
+    relationships.
+
+  - Operations that are specific to records (e.g. `addRecord`, `removeRecord`,
+    `addToHasMany`, etc.).
+
+  - Query expressions that are specific to records (e.g. `findRecord`,
+    `findRecords`, etc.).
+
+  - Tranform and query builders that use chainable terms to create operations
+    and expressions.
+
+- [@orbit/record-cache](./record-cache/index.md) - Everything you need to build
+   your own caches that hold data records (useful within record-specific
+   sources).
+
+- [@orbit/coordinator](./coordinator/index.md) -
+  A coordinator and set of coordination strategies for managing data flow and
+  keeping Orbit Data sources in sync.
+
+- [@orbit/serializers](./serializers/index.md) - A base set of serializers for
+  serializing / deserializing data types.
+
+- [@orbit/validators](./validators/index.md) - A set of validators for
+  validating primitive data and utilities for building higher order validators.
+
+- [@orbit/identity-map](./identity-map/index.md) - A simple identity map to
+  manage model instances.
+
+- [@orbit/immutable](./immutable/index.md) - A lightweight library of immutable
+  data structures.
+
+- [@orbit/utils](./utils/index.md) - A common set of utility functions used by
+  Orbit libs.
+
+## Record-specific data sources
+
+All of the following sources are based on [@orbit/records](./records/index.md).
+They provide uniform interfaces to query and mutate record-specific data:
+
+- [@orbit/memory](./memory/index.md) - An in-memory data source that supports
+  complex querying and updating. Because memory sources maintain data in
+  immutable data structures, they can be efficiently forked. Forked memory
+  sources can diverge from the master memory source, and then the changes can be
+  merged later.
+
+- [@orbit/jsonapi](./jsonapi/index.md) - Provides full CRUD support, including
+  complex querying, for a RESTful API that conforms to the
+  [JSON:API](http://jsonapi.org/) specification.
+
+- [@orbit/local-storage](./local-storage/index.md) - Persists records to local
+  storage.
+
+- [@orbit/indexeddb](./indexeddb/index.md) - Persists records to IndexedDB.
+
+These standard sources can provide guidance for building your own custom sources
+as well.
+
+## Persistence buckets
+
+Buckets are used to persist application state, such as queued requests and
+change logs. Standard buckets include:
+
+- [@orbit/local-storage-bucket](./local-storage-bucket/index.md) - Persists
+  state to local storage.
+
+- [@orbit/indexeddb-bucket](./indexeddb-bucket/index.md) - Persists state to
+  IndexedDB.
+
+## Additional libraries
+
+Some additional libraries related to Orbit, but not covered by these docs,
+include:
+
+- [ember-orbit](https://github.com/orbitjs/ember-orbit) - An Ember.js data
+  layer heavily inspired by Ember Data.

website/docs/coordination.md

@@ -101,7 +101,7 @@ strategies.
 
 ### Request strategies
 
-Request strategies participate in the [request flow](./data-flows). Every
+Request strategies participate in the [request flow](./data-flows.md). Every
 request strategy should be defined with:
 
 - `source` - the name of the observed source
@@ -174,7 +174,7 @@ coordinator.addStrategy(
 
 ### Sync strategies
 
-Sync strategies participate in the [sync flow](./data-flows). Every
+Sync strategies participate in the [sync flow](./data-flows.md). Every
 sync strategy should be defined with:
 
 - `source` - the name of the observed source

website/docs/data-sources.md

@@ -26,16 +26,16 @@ understanding of the domain-specific data they manage.
 Let's create a simple schema and memory source:
 
 ```javascript
-import { Schema } from "@orbit/data";
-import MemorySource from "@orbit/memory";
+import { RecordSchema } from '@orbit/records';
+import { MemorySource } from '@orbit/memory';
 
 // Create a schema
-const schema = new Schema({
+const schema = new RecordSchema({
   models: {
     planet: {
       attributes: {
-        name: { type: "string" },
-        classification: { type: "string" }
+        name: { type: 'string' },
+        classification: { type: 'string' }
       }
     }
   }
@@ -64,25 +64,25 @@ Let's look at an example of a simple mutation triggered by a call to `update`:
 ```javascript
 // Define a record
 const jupiter = {
-  type: "planet",
-  id: "jupiter",
+  type: 'planet',
+  id: 'jupiter',
   attributes: {
-    name: "Jupiter",
-    classification: "gas giant"
+    name: 'Jupiter',
+    classification: 'gas giant'
   }
 };
 
 // Observe and log all transforms
-memory.on("transform", t => {
-  console.log("transform", t);
+memory.on('transform', (t) => {
+  console.log('transform', t);
 });
 
 // Check the size of the transform log before updates
 console.log(`transforms: ${memory.transformLog.length}`);
 
 // Update the memory source with a transform that adds a record
 memory
-  .update(t => t.addRecord(jupiter))
+  .update((t) => t.addRecord(jupiter))
   .then(() => {
     // Verify that the transform log has grown
     console.log(`transforms: ${memory.transformLog.length}`);
@@ -92,29 +92,31 @@ memory
 The following should be logged as a result:
 
 ```javascript
-"transforms: 0",
-  "transform",
+'transforms: 0',
+  'transform',
   {
     operations: [
       {
-        op: "addRecord",
+        op: 'addRecord',
         record: {
-          type: "planet",
-          id: "jupiter",
+          type: 'planet',
+          id: 'jupiter',
           attributes: {
-            name: "Jupiter",
-            classification: "gas giant"
+            name: 'Jupiter',
+            classification: 'gas giant'
           }
         }
       }
     ],
     options: undefined,
-    id: "05e5d20e-02c9-42c4-a083-99662c647fd1"
+    id: '05e5d20e-02c9-42c4-a083-99662c647fd1'
   },
-  "transforms: 1";
+  'transforms: 1';
 ```
 
-> Want to learn more about updating data? [See the guide](./updating-data)
+:::info
+Want to learn more about updating data? [See the guide](./updating-data.md)
+:::
 
 ## Standard interfaces
 
@@ -127,16 +129,14 @@ sources:
 - `Queryable` - Allows sources to be queried via a `query` method that receives
   a query expression and returns a recordset as a result.
 
-- `Pushable` - Allows sources to be updated via a `push` method that takes a
-  transform and returns the results of the change and its side effects as an
-  array of transforms.
-
-- `Pullable` - Allows sources to be queried via a `pull` method that takes a
-  query expression and returns the results as an array of transforms.
-
 - `Syncable` - Applies a transform or transforms to a source via a `sync`
   method.
 
+:::caution
+The `Pullable` and `Pushable` interfaces have been deprecated in
+v0.17 and are scheduled to be removed in v0.18.
+:::
+
 ### Events
 
 All of the interfaces above emit events that share a common pattern. For an
@@ -174,21 +174,20 @@ be ignored by the emitter.
 
 ### Data flows
 
-The `Updatable`, `Queryable`, `Pushable`, and `Pullable` interfaces all
-participate in the "request flow", in which requests are made upstream and data
-flows back down.
+The `Updatable` and `Queryable` interfaces participate in the "request flow", in
+which requests are made upstream and data flows back down.
 
 The `Syncable` interface participates in the "sync flow", in which data flowing
 downstream is synchronized with other sources.
 
-> Want to learn more about data flows? [See the guide](./data-flows)
+> Want to learn more about data flows? [See the guide](./data-flows.md)
 
 ### Developer-facing interfaces
 
-Generally speaking, only the `Updatable` and `Queryable` interfaces are designed
-to be used directly by developers in most applications. The other interfaces are
-used to coordinate data requests and synchronization between sources.
+Generally speaking, developers will primarily interact the `Updatable` and
+`Queryable` interfaces. The `Syncable` interface is used primarily via
+coordination strategies.
 
-> See guides that cover [querying data](./querying-data),
-> [updating data](./updating-data), and
-> [configuring coordination strategies](./coordination).
+> See guides that cover [querying data](./querying-data.md),
+> [updating data](./updating-data.md), and
+> [configuring coordination strategies](./coordination.md).