@warp-drive-mirror/utilities 5.8.0-alpha.9 → 5.8.0-beta.1

package/README.md

@@ -1,27 +1,23 @@
-<h1 align="center">
-  <img
-    class="project-logo"
-    src="./logos/github-header.svg#gh-light-mode-only"
-    alt="WarpDrive | Boldly go where no app has gone before"
-    title="WarpDrive | Boldly go where no app has gone before"
-    />
+<p align="center">
   <img
     class="project-logo"
-    src="./logos/github-header.svg#gh-dark-mode-only"
-    alt="WarpDrive | Boldly go where no app has gone before"
-    title="WarpDrive | Boldly go where no app has gone before"
+    src="./logos/logo-yellow-slab.svg"
+    alt="WarpDrive"
+    width="180px"
+    title="WarpDrive"
     />
-</h1>
+</p>
 
-![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=version&style=flat&color=FFC474)
-![NPM Downloads](https://img.shields.io/npm/dm/ember-data.svg?style=flat&color=FFC474)
-![License](https://img.shields.io/github/license/emberjs/data.svg?style=flat&color=FFC474)
-[![Docs](./logos/docs-badge.svg)](https://docs.warp-drive.io)
-[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=FFC474)](https://discord.gg/zT3asNS
+![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)
+![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=FFC474)](https://discord.gg/PHBbnWJx5S
+[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S
 )
 
+# @warp-drive-mirror/utilities
+
 
 <br>
 
@@ -31,14 +27,6 @@ Utilities that Apps building with <em>Warp</em><strong>Drive</strong> may find u
 
 <br>
 
-## Installation
-
-```sh
-pnpm add -E @warp-drive-mirror/utilities
-```
-
-<br>
-
 ## Documentation
 
 *Get Started* → [Guides](https://docs.warp-drive.io)
@@ -48,7 +36,7 @@ pnpm add -E @warp-drive-mirror/utilities
 
 ## Code of Conduct
 
-Refer to the [Code of Conduct](https://github.com/emberjs/data/blob/main/CODE_OF_CONDUCT.md) for community guidelines and inclusivity.
+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.
 
 <br>
 

package/declarations/-private/active-record/find-record.d.ts

@@ -1,9 +1,6 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive";
 import type { TypeFromInstance } from "@warp-drive-mirror/core/types/record";
 import type { FindRecordOptions, FindRecordRequestOptions, RemotelyAccessibleIdentifier } from "@warp-drive-mirror/core/types/request";
-import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
-export type FindRecordResultDocument<T> = Omit<SingleResourceDataDocument<T>, "data"> & {
-	data: T;
-};
 /**
 * Builds request options to fetch a single resource by a known id or identifier
 * configured for the url and header expectations of most ActiveRecord APIs.
@@ -59,7 +56,9 @@ export type FindRecordResultDocument<T> = Omit<SingleResourceDataDocument<T>, "d
 * @param identifier
 * @param options
 */
-export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T>, T>;
 export declare function findRecord(identifier: RemotelyAccessibleIdentifier, options?: FindRecordOptions): FindRecordRequestOptions;
-export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T>, T>;
 export declare function findRecord(type: string, id: string, options?: FindRecordOptions): FindRecordRequestOptions;
+/** @deprecated use {@link ReactiveDataDocument} instead */
+export type FindRecordResultDocument<T> = ReactiveDataDocument<T>;

package/declarations/-private/active-record/query.d.ts

@@ -1,7 +1,7 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive";
 import type { QueryParamsSource } from "@warp-drive-mirror/core/types/params";
 import type { TypeFromInstance } from "@warp-drive-mirror/core/types/record";
 import type { ConstrainedRequestOptions, QueryRequestOptions } from "@warp-drive-mirror/core/types/request";
-import type { CollectionResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
 /**
 * Builds request options to query for resources, usually by a primary
 * type, configured for the url and header expectations of most ActiveRecord APIs.
@@ -49,5 +49,5 @@ import type { CollectionResourceDataDocument } from "@warp-drive-mirror/core/typ
 * @param query
 * @param options
 */
-export declare function query<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<CollectionResourceDataDocument<T>>;
+export declare function query<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<ReactiveDataDocument<T[]>>;
 export declare function query(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions;

package/declarations/-private/active-record/save-record.d.ts

@@ -1,6 +1,6 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive";
 import type { TypedRecordInstance } from "@warp-drive-mirror/core/types/record";
 import type { ConstrainedRequestOptions, CreateRequestOptions, DeleteRequestOptions, UpdateRequestOptions } from "@warp-drive-mirror/core/types/request";
-import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
 /**
 * Builds request options to delete record for resources,
 * configured for the url, method and header expectations of ActiveRecord APIs.
@@ -140,7 +140,7 @@ export declare function updateRecord<
 	RT extends TypedRecordInstance = T
 >(record: T, options?: ConstrainedRequestOptions & {
 	patch?: boolean;
-}): UpdateRequestOptions<SingleResourceDataDocument<RT>, T>;
+}): UpdateRequestOptions<ReactiveDataDocument<RT>, T>;
 export declare function updateRecord(record: unknown, options?: ConstrainedRequestOptions & {
 	patch?: boolean;
 }): UpdateRequestOptions;

package/declarations/-private/json-api/find-record.d.ts

@@ -1,36 +1,53 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive";
 import type { TypeFromInstance } from "@warp-drive-mirror/core/types/record";
 import type { FindRecordOptions, FindRecordRequestOptions, RemotelyAccessibleIdentifier } from "@warp-drive-mirror/core/types/request";
-import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
 /**
 * Builds request options to fetch a single resource by a known id or identifier
 * configured for the url and header expectations of most JSON:API APIs.
 *
-* **Basic Usage**
+* :::tabs
+*
+* == Basic Usage
 *
 * ```ts
 * import { findRecord } from '@warp-drive-mirror/utilities/json-api';
+* import type { Person } from '#/data/types';
 *
-* const data = await store.request(findRecord('person', '1'));
+* const result = await store.request(
+*   findRecord<Person>('person', '1')
+* );
 * ```
 *
-* **With Options**
+* == With Options
 *
 * ```ts
 * import { findRecord } from '@warp-drive-mirror/utilities/json-api';
+* import type { Person } from '#/data/types';
 *
-* const options = findRecord('person', '1', { include: ['pets', 'friends'] });
-* const data = await store.request(options);
+* const data = await store.request(
+*   findRecord<Person>(
+*     'person', '1',
+*     { include: ['pets', 'friends'] }
+*   )
+* );
 * ```
 *
-* **With an Identifier**
+* == With an Identifier
 *
 * ```ts
 * import { findRecord } from '@warp-drive-mirror/utilities/json-api';
+* import type { Person } from '#/data/types';
 *
-* const options = findRecord({ type: 'person', id: '1' }, { include: ['pets', 'friends'] });
-* const data = await store.request(options);
+* const data = await store.request(
+*   findRecord<Person>(
+*     { type: 'person', id: '1' },
+*     { include: ['pets', 'friends'] }
+*   )
+* );
 * ```
 *
+* :::
+*
 * **Supplying Options to Modify the Request Behavior**
 *
 * The following options are supported:
@@ -48,18 +65,20 @@ import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/s
 * ```ts
 * import { findRecord } from '@warp-drive-mirror/utilities/json-api';
 *
-* const options = findRecord('person', '1', { include: ['pets', 'friends'] }, { namespace: 'api/v2' });
-* const data = await store.request(options);
+* const data = await store.request(
+*   findRecord(
+*     'person', '1',
+*     { include: ['pets', 'friends'] },
+*     { namespace: 'api/v2' }
+*   )
+* );
 * ```
 *
 * @public
-* @param identifier
-* @param options
 */
-export type FindRecordResultDocument<T> = Omit<SingleResourceDataDocument<T>, "data"> & {
-	data: T;
-};
-export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T>, T>;
 export declare function findRecord(identifier: RemotelyAccessibleIdentifier, options?: FindRecordOptions): FindRecordRequestOptions;
-export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T>, T>;
 export declare function findRecord(type: string, id: string, options?: FindRecordOptions): FindRecordRequestOptions;
+/** @deprecated use {@link ReactiveDataDocument} */
+export type FindRecordResultDocument<T> = ReactiveDataDocument<T>;

package/declarations/-private/json-api/query.d.ts

@@ -1,7 +1,7 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive";
 import type { QueryParamsSource } from "@warp-drive-mirror/core/types/params";
 import type { TypedRecordInstance, TypeFromInstance } from "@warp-drive-mirror/core/types/record";
 import type { ConstrainedRequestOptions, PostQueryRequestOptions, QueryRequestOptions } from "@warp-drive-mirror/core/types/request";
-import type { CollectionResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
 /**
 * Builds request options to query for resources, usually by a primary
 * type, configured for the url and header expectations of most JSON:API APIs.
@@ -49,11 +49,8 @@ import type { CollectionResourceDataDocument } from "@warp-drive-mirror/core/typ
 * ```
 *
 * @public
-* @param identifier
-* @param query
-* @param options
 */
-export declare function query<T extends TypedRecordInstance>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<CollectionResourceDataDocument<T>>;
+export declare function query<T extends TypedRecordInstance>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<ReactiveDataDocument<T[]>>;
 export declare function query(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions;
 /**
 * Builds request options to query for resources, usually by a primary
@@ -99,5 +96,5 @@ export declare function query(type: string, query?: QueryParamsSource, options?:
 * @param query
 * @param options
 */
-export declare function postQuery<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): PostQueryRequestOptions<CollectionResourceDataDocument<T>>;
+export declare function postQuery<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): PostQueryRequestOptions<ReactiveDataDocument<T[]>>;
 export declare function postQuery(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): PostQueryRequestOptions;

package/declarations/-private/json-api/save-record.d.ts

@@ -1,7 +1,12 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive.js";
 import type { TypedRecordInstance } from "@warp-drive-mirror/core/types/record";
 import type { ConstrainedRequestOptions, CreateRequestOptions, DeleteRequestOptions, UpdateRequestOptions } from "@warp-drive-mirror/core/types/request";
-import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
 /**
+* :::warning ⚠️ **These Mutation Builders DO NOT Set The Request Body**
+* While this may come as a surprise, the app providing the body ensures that only
+* desired and correctly formatted data is sent with the request.
+* :::
+*
 * Builds request options to delete record for resources,
 * configured for the url, method and header expectations of most JSON:API APIs.
 *
@@ -53,16 +58,31 @@ import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/s
 export declare function deleteRecord<T>(record: T, options?: ConstrainedRequestOptions): DeleteRequestOptions<T>;
 export declare function deleteRecord(record: unknown, options?: ConstrainedRequestOptions): DeleteRequestOptions;
 /**
+* :::warning ⚠️ **These Mutation Builders DO NOT Set The Necessary Request Body**
+* While this may come as a surprise, the app providing the body ensures that only
+* desired and correctly formatted data is sent with the request.
+* :::
+*
 * Builds request options to create new record for resources,
 * configured for the url, method and header expectations of most JSON:API APIs.
 *
 * **Basic Usage**
 *
 * ```ts
+* import { cacheKeyFor } from '@warp-drive-mirror/core';
 * import { createRecord } from '@warp-drive-mirror/utilities/json-api';
-*
-* const person = store.createRecord('person', { name: 'Ted' });
-* const data = await store.request(createRecord(person));
+* import type { Person } from '#/data/types';
+*
+* const person = store.createRecord<Person>('person', { name: 'Ted' });
+* const init = createRecord(person);
+* init.body = JSON.stringify(
+*  {
+*    // it's likely you will want to transform this data
+*    // somewhat
+*    data: store.cache.peek(cacheKeyFor(person))
+*  }
+* );
+* const data = await store.request(init);
 * ```
 *
 * **Supplying Options to Modify the Request Behavior**
@@ -94,19 +114,34 @@ export declare function deleteRecord(record: unknown, options?: ConstrainedReque
 export declare function createRecord<T>(record: T, options?: ConstrainedRequestOptions): CreateRequestOptions<T>;
 export declare function createRecord(record: unknown, options?: ConstrainedRequestOptions): CreateRequestOptions;
 /**
+* :::warning ⚠️ **These Mutation Builders DO NOT Set The Necessary Request Body**
+* While this may come as a surprise, the app providing the body ensures that only
+* desired and correctly formatted data is sent with the request.
+* :::
+*
 * Builds request options to update existing record for resources,
 * configured for the url, method and header expectations of most JSON:API APIs.
 *
-* **Basic Usage**
+* **Example Usage**
 *
 * ```ts
+* import { cacheKeyFor } from '@warp-drive-mirror/core';
 * import { updateRecord } from '@warp-drive-mirror/utilities/json-api';
-*
-* const person = store.peekRecord('person', '1');
-* person.name = 'Chris';
-* const data = await store.request(updateRecord(person));
+* import type { EditablePerson } from '#/data/types';
+*
+* const mutable = await checkout<EditablePerson>(person);
+* mutable.name = 'Chris';
+* const init = updateRecord(mutable);
+*
+* init.body = JSON.stringify(
+*  // it's likely you will want to transform this data
+*  // somewhat, or serialize only specific properties instead
+*  serializePatch(store.cache, cacheKeyFor(mutable))
+* );
+* const data = await store.request(init);
 * ```
 *
+*
 * **Supplying Options to Modify the Request Behavior**
 *
 * The following options are supported:
@@ -140,7 +175,7 @@ export declare function updateRecord<
 	RT extends TypedRecordInstance = T
 >(record: T, options?: ConstrainedRequestOptions & {
 	patch?: boolean;
-}): UpdateRequestOptions<SingleResourceDataDocument<RT>, T>;
+}): UpdateRequestOptions<ReactiveDataDocument<RT>, T>;
 export declare function updateRecord(record: unknown, options?: ConstrainedRequestOptions & {
 	patch?: boolean;
 }): UpdateRequestOptions;

package/declarations/-private/json-api/serialize.d.ts

@@ -16,6 +16,13 @@ export type JsonApiResourcePatch = {
 	relationships?: Record<string, ChangedRelationshipData>;
 };
 /**
+* :::warning ⚠️ **This util often won't produce the necessary body for a {json:api} request**
+*
+* While this may come as a surprise, they are intended to serialize cache state for more
+* generalized usage. {json:api} has a large variance in acceptable shapes, and only your
+* app can ensure that the body is correctly formatted and contains all necessary data.
+* :::
+*
 * Serializes the current state of a resource or array of resources for use with POST or PUT requests.
 *
 * @public
@@ -30,7 +37,14 @@ export declare function serializeResources(cache: Cache, identifiers: ResourceKe
 	data: ResourceObject[];
 };
 /**
-* Serializes changes to a resource for use with PATCH requests.
+* :::warning ⚠️ **This util often won't produce the necessary body for a {json:api} request**
+*
+* While this may come as a surprise, they are intended to serialize cache state for more
+* generalized usage. {json:api} has a large variance in acceptable shapes, and only your
+* app can ensure that the body is correctly formatted and contains all necessary data.
+* :::
+*
+* Serializes changes to a resource. Useful for use with building bodies for PATCH requests.
 *
 * Only attributes which are changed are serialized.
 * Only relationships which are changed are serialized.

package/declarations/-private/rest/find-record.d.ts

@@ -1,6 +1,6 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive";
 import type { TypeFromInstance } from "@warp-drive-mirror/core/types/record";
 import type { FindRecordOptions, FindRecordRequestOptions, RemotelyAccessibleIdentifier } from "@warp-drive-mirror/core/types/request";
-import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
 /**
 * Builds request options to fetch a single resource by a known id or identifier
 * configured for the url and header expectations of most REST APIs.
@@ -53,13 +53,10 @@ import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/s
 * ```
 *
 * @public
-* @param identifier
-* @param options
 */
-export type FindRecordResultDocument<T> = Omit<SingleResourceDataDocument<T>, "data"> & {
-	data: T;
-};
-export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T>, T>;
 export declare function findRecord(identifier: RemotelyAccessibleIdentifier, options?: FindRecordOptions): FindRecordRequestOptions;
-export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<ReactiveDataDocument<T>, T>;
 export declare function findRecord(type: string, id: string, options?: FindRecordOptions): FindRecordRequestOptions;
+/** @deprecated use {@link ReactiveDataDocument} instead */
+export type FindRecordResultDocument<T> = ReactiveDataDocument<T>;

package/declarations/-private/rest/query.d.ts

@@ -1,7 +1,7 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive";
 import type { QueryParamsSource } from "@warp-drive-mirror/core/types/params";
 import type { TypeFromInstance } from "@warp-drive-mirror/core/types/record";
 import type { ConstrainedRequestOptions, QueryRequestOptions } from "@warp-drive-mirror/core/types/request";
-import type { CollectionResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
 /**
 * Builds request options to query for resources, usually by a primary
 * type, configured for the url and header expectations of most REST APIs.
@@ -49,5 +49,5 @@ import type { CollectionResourceDataDocument } from "@warp-drive-mirror/core/typ
 * @param query
 * @param options
 */
-export declare function query<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<CollectionResourceDataDocument<T>>;
+export declare function query<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<ReactiveDataDocument<T[]>>;
 export declare function query(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions;

package/declarations/-private/rest/save-record.d.ts

@@ -1,6 +1,6 @@
+import type { ReactiveDataDocument } from "@warp-drive-mirror/core/reactive";
 import type { TypedRecordInstance } from "@warp-drive-mirror/core/types/record";
 import type { ConstrainedRequestOptions, CreateRequestOptions, DeleteRequestOptions, UpdateRequestOptions } from "@warp-drive-mirror/core/types/request";
-import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/spec/document";
 /**
 * Builds request options to delete record for resources,
 * configured for the url, method and header expectations of REST APIs.
@@ -140,7 +140,7 @@ export declare function updateRecord<
 	RT extends TypedRecordInstance = T
 >(record: T, options?: ConstrainedRequestOptions & {
 	patch?: boolean;
-}): UpdateRequestOptions<SingleResourceDataDocument<RT>, T>;
+}): UpdateRequestOptions<ReactiveDataDocument<RT>, T>;
 export declare function updateRecord(record: unknown, options?: ConstrainedRequestOptions & {
 	patch?: boolean;
 }): UpdateRequestOptions;

package/dist/active-record.js

@@ -88,6 +88,8 @@ function findRecord(arg1, arg2, arg3) {
   };
 }
 
+/** @deprecated use {@link ReactiveDataDocument} instead */
+
 /**
  * Builds request options to query for resources, usually by a primary
  * type, configured for the url and header expectations of most ActiveRecord APIs.

package/dist/json-api.js

@@ -74,32 +74,49 @@ function setBuildURLConfig(config) {
  * Builds request options to fetch a single resource by a known id or identifier
  * configured for the url and header expectations of most JSON:API APIs.
  *
- * **Basic Usage**
+ * :::tabs
+ *
+ * == Basic Usage
  *
  * ```ts
  * import { findRecord } from '@warp-drive-mirror/utilities/json-api';
+ * import type { Person } from '#/data/types';
  *
- * const data = await store.request(findRecord('person', '1'));
+ * const result = await store.request(
+ *   findRecord<Person>('person', '1')
+ * );
  * ```
  *
- * **With Options**
+ * == With Options
  *
  * ```ts
  * import { findRecord } from '@warp-drive-mirror/utilities/json-api';
- *
- * const options = findRecord('person', '1', { include: ['pets', 'friends'] });
- * const data = await store.request(options);
+ * import type { Person } from '#/data/types';
+ *
+ * const data = await store.request(
+ *   findRecord<Person>(
+ *     'person', '1',
+ *     { include: ['pets', 'friends'] }
+ *   )
+ * );
  * ```
  *
- * **With an Identifier**
+ * == With an Identifier
  *
  * ```ts
  * import { findRecord } from '@warp-drive-mirror/utilities/json-api';
- *
- * const options = findRecord({ type: 'person', id: '1' }, { include: ['pets', 'friends'] });
- * const data = await store.request(options);
+ * import type { Person } from '#/data/types';
+ *
+ * const data = await store.request(
+ *   findRecord<Person>(
+ *     { type: 'person', id: '1' },
+ *     { include: ['pets', 'friends'] }
+ *   )
+ * );
  * ```
  *
+ * :::
+ *
  * **Supplying Options to Modify the Request Behavior**
  *
  * The following options are supported:
@@ -117,13 +134,16 @@ function setBuildURLConfig(config) {
  * ```ts
  * import { findRecord } from '@warp-drive-mirror/utilities/json-api';
  *
- * const options = findRecord('person', '1', { include: ['pets', 'friends'] }, { namespace: 'api/v2' });
- * const data = await store.request(options);
+ * const data = await store.request(
+ *   findRecord(
+ *     'person', '1',
+ *     { include: ['pets', 'friends'] },
+ *     { namespace: 'api/v2' }
+ *   )
+ * );
  * ```
  *
  * @public
- * @param identifier
- * @param options
  */
 
 function findRecord(arg1, arg2, arg3) {
@@ -154,6 +174,8 @@ function findRecord(arg1, arg2, arg3) {
   };
 }
 
+/** @deprecated use {@link ReactiveDataDocument} */
+
 /**
  * Builds request options to query for resources, usually by a primary
  * type, configured for the url and header expectations of most JSON:API APIs.
@@ -201,9 +223,6 @@ function findRecord(arg1, arg2, arg3) {
  * ```
  *
  * @public
- * @param identifier
- * @param query
- * @param options
  */
 
 function query(type,
@@ -307,6 +326,11 @@ function isExisting(identifier) {
 }
 
 /**
+ * :::warning ⚠️ **These Mutation Builders DO NOT Set The Request Body**
+ * While this may come as a surprise, the app providing the body ensures that only
+ * desired and correctly formatted data is sent with the request.
+ * :::
+ *
  * Builds request options to delete record for resources,
  * configured for the url, method and header expectations of most JSON:API APIs.
  *
@@ -390,16 +414,31 @@ function deleteRecord(record, options = {}) {
 }
 
 /**
+ * :::warning ⚠️ **These Mutation Builders DO NOT Set The Necessary Request Body**
+ * While this may come as a surprise, the app providing the body ensures that only
+ * desired and correctly formatted data is sent with the request.
+ * :::
+ *
  * Builds request options to create new record for resources,
  * configured for the url, method and header expectations of most JSON:API APIs.
  *
  * **Basic Usage**
  *
  * ```ts
+ * import { cacheKeyFor } from '@warp-drive-mirror/core';
  * import { createRecord } from '@warp-drive-mirror/utilities/json-api';
- *
- * const person = store.createRecord('person', { name: 'Ted' });
- * const data = await store.request(createRecord(person));
+ * import type { Person } from '#/data/types';
+ *
+ * const person = store.createRecord<Person>('person', { name: 'Ted' });
+ * const init = createRecord(person);
+ * init.body = JSON.stringify(
+ *  {
+ *    // it's likely you will want to transform this data
+ *    // somewhat
+ *    data: store.cache.peek(cacheKeyFor(person))
+ *  }
+ * );
+ * const data = await store.request(init);
  * ```
  *
  * **Supplying Options to Modify the Request Behavior**
@@ -458,19 +497,34 @@ function createRecord(record, options = {}) {
 }
 
 /**
+ * :::warning ⚠️ **These Mutation Builders DO NOT Set The Necessary Request Body**
+ * While this may come as a surprise, the app providing the body ensures that only
+ * desired and correctly formatted data is sent with the request.
+ * :::
+ *
  * Builds request options to update existing record for resources,
  * configured for the url, method and header expectations of most JSON:API APIs.
  *
- * **Basic Usage**
+ * **Example Usage**
  *
  * ```ts
+ * import { cacheKeyFor } from '@warp-drive-mirror/core';
  * import { updateRecord } from '@warp-drive-mirror/utilities/json-api';
- *
- * const person = store.peekRecord('person', '1');
- * person.name = 'Chris';
- * const data = await store.request(updateRecord(person));
+ * import type { EditablePerson } from '#/data/types';
+ *
+ * const mutable = await checkout<EditablePerson>(person);
+ * mutable.name = 'Chris';
+ * const init = updateRecord(mutable);
+ *
+ * init.body = JSON.stringify(
+ *  // it's likely you will want to transform this data
+ *  // somewhat, or serialize only specific properties instead
+ *  serializePatch(store.cache, cacheKeyFor(mutable))
+ * );
+ * const data = await store.request(init);
  * ```
  *
+ *
  * **Supplying Options to Modify the Request Behavior**
  *
  * The following options are supported:
@@ -534,6 +588,13 @@ function updateRecord(record, options = {}) {
 }
 
 /**
+ * :::warning ⚠️ **This util often won't produce the necessary body for a {json:api} request**
+ *
+ * While this may come as a surprise, they are intended to serialize cache state for more
+ * generalized usage. {json:api} has a large variance in acceptable shapes, and only your
+ * app can ensure that the body is correctly formatted and contains all necessary data.
+ * :::
+ *
  * Serializes the current state of a resource or array of resources for use with POST or PUT requests.
  *
  * @public
@@ -606,7 +667,14 @@ function _serializeResource(cache, identifier) {
 }
 
 /**
- * Serializes changes to a resource for use with PATCH requests.
+ * :::warning ⚠️ **This util often won't produce the necessary body for a {json:api} request**
+ *
+ * While this may come as a surprise, they are intended to serialize cache state for more
+ * generalized usage. {json:api} has a large variance in acceptable shapes, and only your
+ * app can ensure that the body is correctly formatted and contains all necessary data.
+ * :::
+ *
+ * Serializes changes to a resource. Useful for use with building bodies for PATCH requests.
  *
  * Only attributes which are changed are serialized.
  * Only relationships which are changed are serialized.