@warp-drive-mirror/utilities 5.8.0-alpha.22 → 5.8.0-alpha.23

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

@@ -5,32 +5,49 @@ import type { FindRecordOptions, FindRecordRequestOptions, RemotelyAccessibleIde
 * 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,8 +65,13 @@ import type { FindRecordOptions, FindRecordRequestOptions, RemotelyAccessibleIde
 * ```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

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

@@ -2,6 +2,11 @@ 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";
 /**
+* :::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 { ConstrainedRequestOptions, CreateRequestOptions, DeleteRequestOpti
 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:

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/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,8 +134,13 @@ 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
@@ -304,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.
  *
@@ -387,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**
@@ -455,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:
@@ -531,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
@@ -603,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive-mirror/utilities",
-  "version": "5.8.0-alpha.22",
+  "version": "5.8.0-alpha.23",
   "description": "Utilities package for WarpDrive | Things your app might find useful",
   "keywords": [
     "ember-addon"
@@ -36,7 +36,7 @@
     }
   },
   "peerDependencies": {
-    "@warp-drive-mirror/core": "5.8.0-alpha.22"
+    "@warp-drive-mirror/core": "5.8.0-alpha.23"
   },
   "dependencies": {
     "@embroider/macros": "^1.18.1"
@@ -45,8 +45,8 @@
     "@babel/core": "^7.28.3",
     "@babel/plugin-transform-typescript": "^7.28.0",
     "@babel/preset-typescript": "^7.27.1",
-    "@warp-drive/internal-config": "5.8.0-alpha.22",
-    "@warp-drive-mirror/core": "5.8.0-alpha.22",
+    "@warp-drive/internal-config": "5.8.0-alpha.23",
+    "@warp-drive-mirror/core": "5.8.0-alpha.23",
     "decorator-transforms": "^2.3.0",
     "expect-type": "^1.2.2",
     "typescript": "^5.9.2",