@warp-drive-mirror/core 5.10.0-alpha.10 → 5.10.0-alpha.13

package/README.md

@@ -8,13 +8,11 @@
     />
 </p>
 
-![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=version&style=flat&color=fdb155)
-![NPM Downloads](https://img.shields.io/npm/dm/ember-data.svg?style=flat&color=fdb155)
+![NPM Stable Version](https://img.shields.io/npm/v/%40warp-drive%2Fcore/latest?label=version&style=flat&color=fdb155)
+![NPM Downloads](https://img.shields.io/npm/dm/%40warp-drive%2Fcore.svg?style=flat&color=fdb155)
 ![License](https://img.shields.io/github/license/warp-drive-data/warp-drive.svg?style=flat&color=fdb155)
-[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=fdb155)](https://discord.gg/zT3asNS
-)
-[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S
-)
+[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=fdb155)](https://discord.gg/zT3asNS)
+[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S)
 
 <p align="center">
   <br>
@@ -42,10 +40,62 @@ rich applications &mdash; letting you ship better experiences more quickly witho
 
 <br>
 
+## Usage
+
+`useRecommendedStore` produces a Store class with the recommended defaults; pair it with a cache such as [@warp-drive-mirror/json-api](https://warp-drive.io/api/@warp-drive-mirror/json-api/).
+
+```ts
+import { useRecommendedStore } from '@warp-drive-mirror/core';
+import { JSONAPICache } from '@warp-drive-mirror/json-api';
+
+export const AppStore = useRecommendedStore({
+  cache: JSONAPICache,
+  schemas: [
+    // resource schemas, see https://warp-drive.io/guides/the-manual/schemas/
+  ],
+});
+```
+
+This package is framework-agnostic; the bindings live in `@warp-drive-mirror/ember`, `@warp-drive-mirror/react` and `@warp-drive/vue`. Schemas describe the shape of your resources; the [Schemas guide](https://warp-drive.io/guides/the-manual/schemas/) covers writing them, and the [Setup guide](https://warp-drive.io/guides/configuration/) shows how each framework provides the Store to components.
+
+<br>
+
 ---
 
 <br>
 
+## Documentation
+
+API docs for this package → [@warp-drive-mirror/core](https://warp-drive.io/api/@warp-drive-mirror/core/)
+
+- [Installation](https://warp-drive.io/guides/installation/): install `@warp-drive-mirror/core`, a cache and the reactivity package for your framework.
+- [Setup](https://warp-drive.io/guides/configuration/): configure the build plugin and create a Store with `useRecommendedStore`.
+- [Advanced Store Configuration](https://warp-drive.io/guides/configuration/advanced): build a Store class by hand, one piece at a time.
+- [Making Requests](https://warp-drive.io/guides/the-manual/requests/): `store.request`, request options and the handler chain.
+- [Builders](https://warp-drive.io/guides/the-manual/requests/builders): functions that return a request and a stable cache key.
+- [Handlers](https://warp-drive.io/guides/the-manual/requests/handlers): write a handler that transforms a response.
+- [Auth Handler](https://warp-drive.io/guides/the-manual/cookbook/auth-handlers): add JWT or CSRF tokens to outgoing requests with a handler.
+- [Typing Requests](https://warp-drive.io/guides/the-manual/requests/typing-requests): `withResponseType` and `withReactiveResponse`.
+- [Using the Response](https://warp-drive.io/guides/the-manual/requests/using-the-response): the `Future` a request returns, its errors and its content.
+- [Schemas](https://warp-drive.io/guides/the-manual/schemas/): how a schema turns cached data into reactive properties.
+- [ResourceSchemas](https://warp-drive.io/guides/the-manual/schemas/resources/): define a resource with `withDefaults`, choose its field kinds and register it.
+- [SimpleFields](https://warp-drive.io/guides/the-manual/schemas/simple-fields): declare primitive attributes as `field` kinds.
+- [Complex Fields](https://warp-drive.io/guides/the-manual/schemas/complex-fields): embed nested objects and lists with `schema-object` and `schema-array` fields.
+- [ObjectSchemas](https://warp-drive.io/guides/the-manual/schemas/object-schemas): define the identity-less schema a `schema-object` field points at.
+- [Traits](https://warp-drive.io/guides/the-manual/schemas/traits): share a group of fields across resources.
+- [Transformations](https://warp-drive.io/guides/the-manual/schemas/transformations): convert a field between its cache and app shapes.
+- [Derivations](https://warp-drive.io/guides/the-manual/schemas/derivations): define memoized, read-only `derived` fields.
+- [Caching](https://warp-drive.io/guides/the-manual/caching/): how the `CacheHandler` and the cache policy decide what to fetch and what to keep.
+- [Key Terminology](https://warp-drive.io/guides/the-manual/caching/key-terms): documents, resources and the names of their types.
+- [Reactivity](https://warp-drive.io/guides/the-manual/reactivity/): how ***Warp*Drive** uses signals to notify your UI.
+- [Reactive Control Flow](https://warp-drive.io/guides/the-manual/reactivity/control-flow): render a request's states with `getRequestState`.
+- [Async as Reactive State](https://warp-drive.io/guides/the-manual/reactivity/derivation): derive a promise's state with `getPromiseState`.
+- [Relationships](https://warp-drive.io/guides/the-manual/relational-data/): configure each kind of relationship.
+- [Debugging](https://warp-drive.io/guides/the-manual/debugging/): turn on debug logging at runtime or in the build config.
+- [TypeScript](https://warp-drive.io/guides/the-manual/typescript/): opt in to the alpha types, then follow the setup pages in order.
+
+<br>
+
 ## Code of Conduct
 
 Refer to the [Code of Conduct](https://github.com/warp-drive-data/warp-drive/blob/main/CODE_OF_CONDUCT.md) for community guidelines and inclusivity.
@@ -55,3 +105,63 @@ Refer to the [Code of Conduct](https://github.com/warp-drive-data/warp-drive/blo
 ### License
 
 This project is licensed under the [MIT License](LICENSE.md).
+
+### ♥️ Credits
+
+ <details>
+   <summary>Brought to you with ♥️ love by <a href="https://emberjs.com" title="EmberJS">🐹 Ember</a></summary>
+
+  <style type="text/css">
+    img.project-logo {
+       padding: 0 5em 1em 5em;
+       width: 100px;
+       border-bottom: 2px solid #bbb;
+       margin: 0 auto;
+       display: block;
+     }
+    details > summary {
+      font-size: 1.1rem;
+      line-height: 1rem;
+      margin-bottom: 1rem;
+    }
+    details {
+      font-size: 1rem;
+    }
+    details > summary strong {
+      display: inline-block;
+      padding: .2rem 0;
+      color: #000;
+      border-bottom: 3px solid #bbb;
+    }
+
+    details > details {
+      margin-left: 2rem;
+    }
+    details > details > summary {
+      font-size: 1rem;
+      line-height: 1rem;
+      margin-bottom: 1rem;
+    }
+    details > details > summary strong {
+      display: inline-block;
+      padding: .2rem 0;
+      color: #555;
+      border-bottom: 2px solid #555;
+    }
+    details > details {
+      font-size: .85rem;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      details > summary strong {
+        color: #fff;
+      }
+    }
+    @media (prefers-color-scheme: dark) {
+      details > details > summary strong {
+        color: #afaba0;
+      border-bottom: 2px solid #afaba0;
+      }
+    }
+  </style>
+</details>