@warp-drive-mirror/core 5.10.0-alpha.2 → 5.10.0-alpha.20

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>

package/dist/{-private-ffnwf62T.js → -private-BiuED7nc.js}

@@ -1,12 +1,14 @@
-import { t as getOrSetGlobal } from "./-private-CWh7qdp_.js";
+import { getOrSetGlobal } from "./types/-private.js";
 
-//#region src/reactive/-private/symbols.ts
+// src/reactive/-private/symbols.ts
 const SOURCE = getOrSetGlobal("SOURCE", Symbol("#source"));
 const Destroy = getOrSetGlobal("Destroy", Symbol.dispose || Symbol.for("Dispose"));
 /**
 * Symbol for the method used to request a mutable copy of an otherwise
 * immutable {@link ReactiveResource}.
 *
+* @summary Deprecated symbol-keyed method on a ReactiveResource that resolves with an editable copy;
+* use `checkout` instead.
 * @deprecated use the {@link checkout} utility function instead.
 */
 const Checkout = getOrSetGlobal("Checkout", Symbol("Checkout"));
@@ -17,6 +19,5 @@ const Commit = getOrSetGlobal("Commit", Symbol("Commit"));
 */
 const Context = getOrSetGlobal("Context", Symbol("Context"));
 
-//#endregion
 export { SOURCE as a, Destroy as i, Commit as n, Context as r, Checkout as t };
-//# sourceMappingURL=-private-ffnwf62T.js.map
+//# sourceMappingURL=-private-BiuED7nc.js.map

package/dist/{-private-ffnwf62T.js.map → -private-BiuED7nc.js.map}

@@ -1 +1 @@
-{"version":3,"file":"-private-ffnwf62T.js","names":["getOrSetGlobal","SOURCE","Symbol","Destroy","dispose","for","Checkout","Commit","Context"],"sources":["../src/reactive/-private/symbols.ts"],"sourcesContent":["///////////////////\n///// WARNING /////\n///////////////////\n\nimport { getOrSetGlobal } from '../../types/-private';\n\n// Great, got your attention with that warning didn't we?\n// Good. Here's the deal: typescript treats symbols as unique types.\n// If by accident a module creating a symbol is processed more than\n// once, the symbol will be different in each processing. This will\n// cause a type error.\n// It could also cause a runtime error if the symbol is used innapropriately.\n// However, this case is extremely hard to hit and would require other things\n// to go wrong first.\n//\n// So, why do the warning? And why do we lie about the types of the symbols?\n//\n// Because we intentionally create multiple copies of them within the types\n// at build time. This is because we rollup our d.ts files in order to give\n// our consumers a better experience.\n//\n// However, no tool today supports rolling up d.ts files with multiple entry\n// points correctly. The tool we use currently (vite-plugin-dts) uses @microsoft/api-extractor\n// which creates a fully unique stand-alone types file per-entry-point. Thus\n// every entry point that uses one of these symbols somewhere will have accidentally\n// created a new symbol type.\n//\n// This cast allows us to rollup these types using this tool while not encountering\n// the unique symbol type issue.\n//\n// Note that none of these symbols are part of the public API, these are used for\n// debugging DX and as a safe way to provide an intimate contract on public objects.\n\nexport const SOURCE: '___(unique) Symbol(SOURCE)' = getOrSetGlobal('SOURCE', Symbol('#source'));\n\nexport const Destroy: '___(unique) Symbol(Destroy)' = getOrSetGlobal(\n  'Destroy',\n  Symbol.dispose || Symbol.for('Dispose')\n);\n/**\n * Symbol for the method used to request a mutable copy of an otherwise\n * immutable {@link ReactiveResource}.\n *\n * @deprecated use the {@link checkout} utility function instead.\n */\nexport const Checkout: '___(unique) Symbol(Checkout)' = getOrSetGlobal('Checkout', Symbol('Checkout'));\nexport const Commit: '___(unique) Symbol(Commit)' = getOrSetGlobal('Commit', Symbol('Commit'));\n\n/**\n * Symbol used to stash the internal field/resource context (schema, store,\n * mutability, etc.) on a {@link ReactiveResource} or reactive field instance.\n */\nexport const Context: '___(unique) Symbol(Context)' = getOrSetGlobal('Context', Symbol('Context'));\n"],"mappings":";;;AAiCA,MAAaC,SAAuCD,eAAe,UAAUE,OAAO,SAAS,CAAC;AAE9F,MAAaC,UAAyCH,eACpD,WACAE,OAAOE,WAAWF,OAAOG,IAAI,SAAS,CACxC;;;;;;;AAOA,MAAaC,WAA2CN,eAAe,YAAYE,OAAO,UAAU,CAAC;AACrG,MAAaK,SAAuCP,eAAe,UAAUE,OAAO,QAAQ,CAAC;;;;;AAM7F,MAAaM,UAAyCR,eAAe,WAAWE,OAAO,SAAS,CAAC"}
+{"version":3,"file":"-private-BiuED7nc.js","names":["getOrSetGlobal","SOURCE","Symbol","Destroy","dispose","for","Checkout","Commit","Context"],"sources":["../src/reactive/-private/symbols.ts"],"sourcesContent":["///////////////////\n///// WARNING /////\n///////////////////\n\nimport { getOrSetGlobal } from '../../types/-private';\n\n// Great, got your attention with that warning didn't we?\n// Good. Here's the deal: typescript treats symbols as unique types.\n// If by accident a module creating a symbol is processed more than\n// once, the symbol will be different in each processing. This will\n// cause a type error.\n// It could also cause a runtime error if the symbol is used innapropriately.\n// However, this case is extremely hard to hit and would require other things\n// to go wrong first.\n//\n// So, why do the warning? And why do we lie about the types of the symbols?\n//\n// Because we intentionally create multiple copies of them within the types\n// at build time. This is because we rollup our d.ts files in order to give\n// our consumers a better experience.\n//\n// However, no tool today supports rolling up d.ts files with multiple entry\n// points correctly. The tool we use currently (vite-plugin-dts) uses @microsoft/api-extractor\n// which creates a fully unique stand-alone types file per-entry-point. Thus\n// every entry point that uses one of these symbols somewhere will have accidentally\n// created a new symbol type.\n//\n// This cast allows us to rollup these types using this tool while not encountering\n// the unique symbol type issue.\n//\n// Note that none of these symbols are part of the public API, these are used for\n// debugging DX and as a safe way to provide an intimate contract on public objects.\n\nexport const SOURCE: '___(unique) Symbol(SOURCE)' = getOrSetGlobal('SOURCE', Symbol('#source'));\n\nexport const Destroy: '___(unique) Symbol(Destroy)' = getOrSetGlobal(\n  'Destroy',\n  Symbol.dispose || Symbol.for('Dispose')\n);\n/**\n * Symbol for the method used to request a mutable copy of an otherwise\n * immutable {@link ReactiveResource}.\n *\n * @summary Deprecated symbol-keyed method on a ReactiveResource that resolves with an editable copy;\n * use `checkout` instead.\n * @deprecated use the {@link checkout} utility function instead.\n */\nexport const Checkout: '___(unique) Symbol(Checkout)' = getOrSetGlobal('Checkout', Symbol('Checkout'));\nexport const Commit: '___(unique) Symbol(Commit)' = getOrSetGlobal('Commit', Symbol('Commit'));\n\n/**\n * Symbol used to stash the internal field/resource context (schema, store,\n * mutability, etc.) on a {@link ReactiveResource} or reactive field instance.\n */\nexport const Context: '___(unique) Symbol(Context)' = getOrSetGlobal('Context', Symbol('Context'));\n"],"mappings":";;;AAiCA,MAAaC,SAAuCD,eAAe,UAAUE,OAAO,SAAS,CAAC;AAE9F,MAAaC,UAAyCH,eACpD,WACAE,OAAOE,WAAWF,OAAOG,IAAI,SAAS,CACxC;;;;;;;;;AASA,MAAaC,WAA2CN,eAAe,YAAYE,OAAO,UAAU,CAAC;AACrG,MAAaK,SAAuCP,eAAe,UAAUE,OAAO,QAAQ,CAAC;;;;;AAM7F,MAAaM,UAAyCR,eAAe,WAAWE,OAAO,SAAS,CAAC"}