diff --git a/guides/manual/1-overview.md b/guides/manual/1-overview.md index 6757e2c387b..c43afbe3a31 100644 --- a/guides/manual/1-overview.md +++ b/guides/manual/1-overview.md @@ -18,9 +18,12 @@ We see this as one of the keys to scalability. Providing a stable framework for how data is requested, cached, mutated, and mocked allows developers to focus more time on the product requirements that matter. -This also means that a single WarpDrive configuration can power multiple web-apps -using varying frameworks sharing a single domain: bridging the gap between MPA -and SPA. +A single WarpDrive configuration can power multiple web-apps using differing +frameworks all sharing a single domain: bridging the gap between MPA and SPA. + +
+ +## A Very Brief History WarpDrive began in ~2006 as a suite of ORM-like data utilities in SproutCore that later evolved into EmberData. Beginning in ~2017 the team plotted a course towards @@ -51,14 +54,15 @@ quick to pickup the basics. Our patterns are portable and scalable, meaning that your app, team and data needs evolve we'll be right there with you. Because we are universal and also not tied to any API Format or backend architecture, -there's no lock-in. The data patterns you learn, the code you write is portable -between frontend frameworks and backends and can help smooth the evolution of both. +there's no lock-in. The data patterns you learn and the code you write is portable +between frontend frameworks and backend APIs and can help smooth the evolution of both. We're also not specific to a given frontend architecture. When serving on the same domain, you can dedupe and cache requests across multiple apps and tabs at once! This means we are as good for embedded content and MPAs as we are for SPAs. -Our core philosophy is to deliver value that lasts decades and evolves with your app. +Our core philosophy is to deliver value that lasts decades and evolves with your app, +helping you ship, iterate and deliver to your customers.
diff --git a/guides/manual/3-data.md b/guides/manual/3-data.md index fa250f130de..27c95f0c5fb 100644 --- a/guides/manual/3-data.md +++ b/guides/manual/3-data.md @@ -18,7 +18,33 @@ at each layer, making your application faster. Misalignment tends to occur when API and Application developers don't work together to understand requirements, or when the format in use is "lossy" (unable to accurately convey the full scope of -information being serialized) +information being serialized). + +We encourage the use of [JSON:API](https://jsonapi.org/) as the wire and cache format because unlike +most other formats in use today it encodes information about your data in a near-lossless and easily-cacheable manner. + +For the presentation format, we encourage applications to limit the amount of manual transformation +done. Applications should wherever possible align the interfaces of the data components expect to +the shape of the data available, rather than transforming data to fit into the component. This said, +WarpDrive offers powerful schema-defined transformation and derivation capabilities built-in to the +reactivity layer for presenting data from the cache. Handling transformation universally via schema +enables apps to align to component interfaces where needed in a safer, more performant manner. + +We'll explore these capabilities later on in the manual in the sections on [Presentation](./5-presentation.md) and [Schemas](./6-schemas.md). But first, lets take some time to look at some key +concepts surrounding the wire and cache format. + + +### StructuredDocuments + +### ResourceDocuments + +### Resources + +### CacheKeys + +### Membership + +### Fields
diff --git a/packages/schema-record/README.md b/packages/schema-record/README.md index ceb15a3b7cf..0fababf7ed7 100644 --- a/packages/schema-record/README.md +++ b/packages/schema-record/README.md @@ -25,11 +25,16 @@ SchemaRecord is: - ⚛️ Universal - ☢️ Reactive -This package provides a reactive capabilities for your resource data. It works together with a [*Warp***Drive**](https://github.com/emberjs/data/) [Cache](https://github.com/emberjs/data/blob/main/packages/core-types/src/cache.ts) and associated Schemas to simplify the most complex parts of your app's state management. +This package provides reactive capabilities for your resource data. +It works together with a [*Warp***Drive**](https://github.com/emberjs/data/) +[Cache](https://github.com/emberjs/data/blob/main/packages/core-types/src/cache.ts) +and associated Schemas to simplify the most complex parts of your +app's state management. ## Installation -Install using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/) +Install using your javascript package manager of choice. For instance +with [pnpm](https://pnpm.io/) ```cli pnpm add @warp-drive/schema-record @@ -46,14 +51,16 @@ pnpm add @warp-drive/schema-record ## Getting Started -If this package is how you are first learning about WarpDrive/EmberData, we recommend starting with learning about [Requests](https://github.com/emberjs/data/blob/main/packages/request/README.md) and the [Store](https://github.com/emberjs/data/blob/main/packages/store/README.md). +If this package is how you are first learning about WarpDrive/EmberData, we +recommend starting with learning about [Requests](https://github.com/emberjs/data/blob/main/packages/request/README.md) +and the [Store](https://github.com/emberjs/data/blob/main/packages/store/README.md). ## 🚀 Setup SchemaRecord integrates with WarpDrive via the Store's resource lifecycle hooks. -When EmberData needs to create a new presentation class to pair with some resource -data, it calls `instantiateRecord`. When it no longer needs that class, it will call -`teardownRecord`. +When WarpDrive needs to create a new record instance to give reactive access to +a resource in the cache, it calls `instantiateRecord`. When it no longer needs +that instance, it will call `teardownRecord`. ```diff import Store from '@ember-data/store'; @@ -78,17 +85,22 @@ class AppStore extends Store { } ``` -Any Store API that returns a record instance will use the hook shown above to instantiate a SchemaRecord once this configuration is done. After that, its up to you what SchemaRecord can do. +Any Store API that returns a record instance will use the hook shown above to +instantiate a SchemaRecord once this configuration is done. After that, its up +to you what SchemaRecord can do. ## Start Using ### About -SchemaRecord is a reactive object that transforms raw data from an associated cache into reactive data backed by Signals. +SchemaRecord is a reactive object that transforms raw data from an associated +cache into reactive data backed by Signals. -The shape of the object and the transformation of raw cache data into its reactive form is controlled by a resource schema. +The shape of the object and the transformation of raw cache data into its +reactive form is controlled by a resource schema. -For instance, lets say your API is a JSON:API and your store is using the JSONAPICache, and a request returns the following raw data: +For instance, lets say your API is a JSON:API and your store is using the +JSONAPICache, and a request returns the following raw data: ```ts { @@ -205,12 +217,17 @@ interface User { }> ``` -Note how based on the schema the reactive object we receive is able to produce `name` on user (despite no name field being in the cache), provide `$type` pulled from the identity of the resource, and flatten the individual attributes and relationships onto the record for easier use. +Note how based on the schema the reactive object we receive is able to produce +`name` on user (despite no name field being in the cache), provide `$type` +pulled from the identity of the resource, and flatten the individual attributes +and relationships onto the record for easier use. -Notice also how we typed this object with `readonly`. This is because while SchemaRecord instances are ***deeply reactive***, they are also ***immutable***. +Notice also how we typed this object with `readonly`. This is because while +SchemaRecord instances are ***deeply reactive***, they are also ***immutable***. -We can mutate a SchemaRecord only be explicitly asking permission to do so, and in the process gaining access to an editable copy. The immutable version will not show -any in-process edits made to this editable copy. +We can mutate a SchemaRecord only be explicitly asking permission to do so, and +in the process gaining access to an editable copy. The immutable version will +not show any in-process edits made to this editable copy. ```ts import { Checkout } from '@warp-drive/schema-record/record'; @@ -220,7 +237,9 @@ const editable = await user[Checkout](); ### Utilities -SchemaRecord provides a schema builder that simplifies setting up a couple of conventional fields like identity and `$type`. We can rewrite the schema definition above using this utility like so: +SchemaRecord provides a schema builder that simplifies setting up a couple of +conventional fields like identity and `$type`. We can rewrite the schema +definition above using this utility like so: ```ts import { withDefaults } from '@warp-drive/schema-record/schema';