feat: docs, tests and fixes for create/update/deleteRecord builders (#8849)

* WIP adding create-record builder docs

* Add more documentation for rest of builders handling save record

* Try to setup store in test app for builders

* Add tests, need some help here

* Add working test setup

* Had to comment out this assert - new record allowed to not have ID

* Fix lint and lock file

* Add missing docs classitems

* Add other tests, comment out saveRecord asserts

* add integration test for createRecord builder and fix CacheHandler

* add deleteRecord integration test, fix it to work

* add update-record test, expand delete-record test

* fix lint

* fixup new rollback

* cleanup asserts

* small fixes to docs

---------

Co-authored-by: Chris Thoburn <runspired@gmail.com>

Author: Baltazore

packages/active-record/src/-private/builders/find-record.ts

@@ -20,7 +20,7 @@ type FindRecordOptions = ConstrainedRequestOptions & {
 
 /**
  * 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.
+ * configured for the url and header expectations of most ActiveRecord APIs.
  *
  * **Basic Usage**
  *

packages/active-record/src/-private/builders/save-record.ts

@@ -24,6 +24,58 @@ function isExisting(identifier: StableRecordIdentifier): identifier is StableExi
   return 'id' in identifier && identifier.id !== null && 'type' in identifier && identifier.type !== null;
 }
 
+/**
+ * Builds request options to delete record for resources,
+ * configured for the url, method and header expectations of ActiveRecord APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { deleteRecord } from '@ember-data/active-record/request';
+ *
+ * const person = this.store.peekRecord('person', '1');
+ *
+ * // mark record as deleted
+ * store.deleteRecord(person);
+ *
+ * // persist deletion
+ * const data = await store.request(deleteRecord(person));
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's lifetimes service, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's lifetimes service,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { deleteRecord } from '@ember-data/active-record/request';
+ *
+ * const person = this.store.peekRecord('person', '1');
+ *
+ * // mark record as deleted
+ * store.deleteRecord(person);
+ *
+ * // persist deletion
+ * const options = deleteRecord(person, { namespace: 'api/v1' });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @method deleteRecord
+ * @public
+ * @static
+ * @for @ember-data/active-record/request
+ * @param record
+ * @param options
+ */
 export function deleteRecord(record: unknown, options: ConstrainedRequestOptions = {}): DeleteRequestOptions {
   const identifier = recordIdentifierFor(record);
   assert(`Expected to be given a record instance`, identifier);
@@ -52,10 +104,51 @@ export function deleteRecord(record: unknown, options: ConstrainedRequestOptions
   };
 }
 
+/**
+ * Builds request options to create new record for resources,
+ * configured for the url, method and header expectations of most ActiveRecord APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { createRecord } from '@ember-data/active-record/request';
+ *
+ * const person = this.store.createRecord('person', { name: 'Ted' });
+ * const data = await store.request(createRecord(person));
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's lifetimes service, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's lifetimes service,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { createRecord } from '@ember-data/active-record/request';
+ *
+ * const person = this.store.createRecord('person', { name: 'Ted' });
+ * const options = createRecord(person, { namespace: 'api/v1' });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @method createRecord
+ * @public
+ * @static
+ * @for @ember-data/active-record/request
+ * @param record
+ * @param options
+ */
 export function createRecord(record: unknown, options: ConstrainedRequestOptions = {}): CreateRequestOptions {
   const identifier = recordIdentifierFor(record);
   assert(`Expected to be given a record instance`, identifier);
-  assert(`Cannot delete a record that does not have an associated type and id.`, isExisting(identifier));
 
   const urlOptions: CreateRecordUrlOptions = {
     identifier: identifier,
@@ -80,13 +173,58 @@ export function createRecord(record: unknown, options: ConstrainedRequestOptions
   };
 }
 
+/**
+ * Builds request options to update existing record for resources,
+ * configured for the url, method and header expectations of most ActiveRecord APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { updateRecord } from '@ember-data/active-record/request';
+ *
+ * const person = this.store.peekRecord('person', '1');
+ * person.name = 'Chris';
+ * const data = await store.request(updateRecord(person));
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `patch` - Allows caller to specify whether to use a PATCH request instead of a PUT request, defaults to `false`.
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's lifetimes service, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's lifetimes service,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { updateRecord } from '@ember-data/active-record/request';
+ *
+ * const person = this.store.peekRecord('person', '1');
+ * person.name = 'Chris';
+ * const options = updateRecord(person, { patch: true });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @method updateRecord
+ * @public
+ * @static
+ * @for @ember-data/active-record/request
+ * @param record
+ * @param options
+ */
 export function updateRecord(
   record: unknown,
   options: ConstrainedRequestOptions & { patch?: boolean } = {}
 ): UpdateRequestOptions {
   const identifier = recordIdentifierFor(record);
   assert(`Expected to be given a record instance`, identifier);
-  assert(`Cannot delete a record that does not have an associated type and id.`, isExisting(identifier));
+  assert(`Cannot update a record that does not have an associated type and id.`, isExisting(identifier));
 
   const urlOptions: UpdateRecordUrlOptions = {
     identifier: identifier,

packages/json-api/src/-private/builders/save-record.ts

@@ -23,6 +23,58 @@ function isExisting(identifier: StableRecordIdentifier): identifier is StableExi
   return 'id' in identifier && identifier.id !== null && 'type' in identifier && identifier.type !== null;
 }
 
+/**
+ * Builds request options to delete record for resources,
+ * configured for the url, method and header expectations of most JSON:API APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { deleteRecord } from '@ember-data/json-api/request';
+ *
+ * const person = this.store.peekRecord('person', '1');
+ *
+ * // mark record as deleted
+ * store.deleteRecord(person);
+ *
+ * // persist deletion
+ * const data = await store.request(deleteRecord(person));
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's lifetimes service, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's lifetimes service,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { deleteRecord } from '@ember-data/json-api/request';
+ *
+ * const person = this.store.peekRecord('person', '1');
+ *
+ * // mark record as deleted
+ * store.deleteRecord(person);
+ *
+ * // persist deletion
+ * const options = deleteRecord(person, { namespace: 'api/v1' });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @method deleteRecord
+ * @public
+ * @static
+ * @for @ember-data/json-api/request
+ * @param record
+ * @param options
+ */
 export function deleteRecord(record: unknown, options: ConstrainedRequestOptions = {}): DeleteRequestOptions {
   const identifier = recordIdentifierFor(record);
   assert(`Expected to be given a record instance`, identifier);
@@ -52,10 +104,51 @@ export function deleteRecord(record: unknown, options: ConstrainedRequestOptions
   };
 }
 
+/**
+ * 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 { createRecord } from '@ember-data/json-api/request';
+ *
+ * const person = this.store.createRecord('person', { name: 'Ted' });
+ * const data = await store.request(createRecord(person));
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's lifetimes service, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's lifetimes service,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { createRecord } from '@ember-data/json-api/request';
+ *
+ * const person = this.store.createRecord('person', { name: 'Ted' });
+ * const options = createRecord(person, { namespace: 'api/v1' });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @method createRecord
+ * @public
+ * @static
+ * @for @ember-data/json-api/request
+ * @param record
+ * @param options
+ */
 export function createRecord(record: unknown, options: ConstrainedRequestOptions = {}): CreateRequestOptions {
   const identifier = recordIdentifierFor(record);
   assert(`Expected to be given a record instance`, identifier);
-  assert(`Cannot delete a record that does not have an associated type and id.`, isExisting(identifier));
 
   const urlOptions: CreateRecordUrlOptions = {
     identifier: identifier,
@@ -81,13 +174,58 @@ export function createRecord(record: unknown, options: ConstrainedRequestOptions
   };
 }
 
+/**
+ * Builds request options to update existing record for resources,
+ * configured for the url, method and header expectations of most JSON:API APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { updateRecord } from '@ember-data/json-api/request';
+ *
+ * const person = this.store.peekRecord('person', '1');
+ * person.name = 'Chris';
+ * const data = await store.request(updateRecord(person));
+ * ```
+ *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `patch` - Allows caller to specify whether to use a PATCH request instead of a PUT request, defaults to `false`.
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's lifetimes service, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's lifetimes service,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { updateRecord } from '@ember-data/json-api/request';
+ *
+ * const person = this.store.peekRecord('person', '1');
+ * person.name = 'Chris';
+ * const options = updateRecord(person, { patch: true });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @method updateRecord
+ * @public
+ * @static
+ * @for @ember-data/json-api/request
+ * @param record
+ * @param options
+ */
 export function updateRecord(
   record: unknown,
   options: ConstrainedRequestOptions & { patch?: boolean } = {}
 ): UpdateRequestOptions {
   const identifier = recordIdentifierFor(record);
   assert(`Expected to be given a record instance`, identifier);
-  assert(`Cannot delete a record that does not have an associated type and id.`, isExisting(identifier));
+  assert(`Cannot update a record that does not have an associated type and id.`, isExisting(identifier));
 
   const urlOptions: UpdateRecordUrlOptions = {
     identifier: identifier,

packages/json-api/src/-private/cache.ts

@@ -1117,6 +1117,7 @@ export default class JSONAPICache implements Cache {
 
     if (cached.isNew) {
       // > Note: Graph removal handled by unloadRecord
+      cached.isDeletionCommitted = true;
       cached.isDeleted = true;
       cached.isNew = false;
     }

packages/model/src/-private/model.d.ts

@@ -10,6 +10,7 @@ import type BelongsToReference from './references/belongs-to';
 import type { StableRecordIdentifier } from '@ember-data/types/q/identifier';
 import type { LegacySupport } from './legacy-relationships-support';
 import type { Cache } from '@ember-data/types/q/cache';
+import type RecordState from './record-state';
 
 export type ModelCreateArgs = {
   _createProps: Record<string, unknown>;
@@ -26,6 +27,8 @@ export type ModelCreateArgs = {
 class Model extends EmberObject {
   store: Store;
   errors: Errors;
+  currentState: RecordState;
+  adapterError?: Error;
   toString(): string;
   save(): Promise<this>;
   hasMany(key: string): HasManyReference;