@ember-data/model 5.6.0-alpha.2 → 5.6.0-alpha.4

package/unstable-preview-types/-private/model.d.ts

@@ -1,7 +1,4 @@
 declare module '@ember-data/model/-private/model' {
-  /**
-    @module @ember-data/model
-   */
   import EmberObject from '@ember/object';
   import type { Snapshot } from '@ember-data/legacy-compat/-private';
   import type Store from '@ember-data/store';
@@ -35,392 +32,309 @@ declare module '@ember-data/model/-private/model' {
       _modelFactoryCache: FactoryCache;
   };
   /**
-    Base class from which Models can be defined.
-  
-    ```js
-    import Model, { attr } from '@ember-data/model';
-  
-    export default class User extends Model {
-      @attr name;
-    }
-    ```
-  
-    Models are used both to define the static schema for a
-    particular resource type as well as the class to instantiate
-    to present that data from cache.
-  
-    @class Model
-    @public
-    @extends Ember.EmberObject
-  */
+   * @noInheritDoc
+   */
   interface Model {
-      serialize<T extends MinimalLegacyRecord>(this: T, options?: Record<string, unknown>): unknown;
-      destroyRecord<T extends MinimalLegacyRecord>(this: T, options?: Record<string, unknown>): Promise<this>;
-      unloadRecord<T extends MinimalLegacyRecord>(this: T): void;
-      changedAttributes<T extends MinimalLegacyRecord>(this: T): ChangedAttributesHash;
-      rollbackAttributes<T extends MinimalLegacyRecord>(this: T): void;
-      _createSnapshot<T extends MinimalLegacyRecord>(this: T): Snapshot<T>;
-      save<T extends MinimalLegacyRecord>(this: T, options?: Record<string, unknown>): Promise<this>;
-      reload<T extends MinimalLegacyRecord>(this: T, options?: Record<string, unknown>): Promise<T>;
-      belongsTo<T extends Model, K extends keyof T & string>(this: T, prop: K & (K extends _MaybeBelongsToFields<T> ? K : never)): BelongsToReference<T, K>;
-      hasMany<T extends MinimalLegacyRecord, K extends MaybeHasManyFields<T>>(this: T, prop: K): HasManyReference<T, K>;
-      deleteRecord<T extends MinimalLegacyRecord>(this: T): void;
-  }
-  class Model extends EmberObject implements MinimalLegacyRecord {
-      store: Store;
-      ___recordState: RecordState;
-      ___private_notifications: object;
-      [RecordStore]: Store;
-      init(options: ModelCreateArgs): void;
-      destroy(): this;
       /**
-        If this property is `true` the record is in the `empty`
-        state. Empty is the first state all records enter after they have
-        been created. Most records created by the store will quickly
-        transition to the `loading` state if data needs to be fetched from
-        the server or the `created` state if the record is created on the
-        client. A record can also enter the empty state if the adapter is
-        unable to locate the record.
+        Create a JSON representation of the record, using the serialization
+        strategy of the store's adapter.
     
-        @property isEmpty
-        @public
-        @type {Boolean}
-        @readOnly
-      */
-      get isEmpty(): boolean;
-      /**
-        If this property is `true` the record is in the `loading` state. A
-        record enters this state when the store asks the adapter for its
-        data. It remains in this state until the adapter provides the
-        requested data.
+       `serialize` takes an optional hash as a parameter, currently
+        supported options are:
+    
+       - `includeId`: `true` if the record's ID should be included in the
+          JSON representation.
     
-        @property isLoading
         @public
-        @type {Boolean}
-        @readOnly
+        @param {Object} options
+        @return {Object} an object whose values are primitive JSON values only
       */
-      get isLoading(): boolean;
+      serialize<T extends MinimalLegacyRecord>(this: T, options?: Record<string, unknown>): unknown;
       /**
-        If this property is `true` the record is in the `loaded` state. A
-        record enters this state when its data is populated. Most of a
-        record's lifecycle is spent inside substates of the `loaded`
-        state.
+        Same as `deleteRecord`, but saves the record immediately.
     
         Example
     
-        ```javascript
-        let record = store.createRecord('model');
-        record.isLoaded; // true
+        ```js
+        import Component from '@glimmer/component';
     
-        const { content: { data: model } } = await store.request(findRecord({ type: 'model', id: '1' }));
-        model.isLoaded;
+        export default class extends Component {
+          delete = () => {
+            this.args.model.destroyRecord().then(function() {
+              this.transitionToRoute('model.index');
+            });
+          }
+        }
         ```
     
-        @property isLoaded
-        @public
-        @type {Boolean}
-        @readOnly
-      */
-      get isLoaded(): boolean;
-      /**
-        If this property is `true` the record is in the `dirty` state. The
-        record has local changes that have not yet been saved by the
-        adapter. This includes records that have been created (but not yet
-        saved) or deleted.
-    
-        Example
+        If you pass an object on the `adapterOptions` property of the options
+        argument it will be passed to your adapter via the snapshot
     
-        ```javascript
-        let record = store.createRecord('model');
-        record.hasDirtyAttributes; // true
+        ```js
+        record.destroyRecord({ adapterOptions: { subscribe: false } });
+        ```
     
-        const { content: { data: model } } = await store.request(findRecord({ type: 'model', id: '1' }));
+        ```js [app/adapters/post.js]
+        import MyCustomAdapter from './custom-adapter';
     
-        model.hasDirtyAttributes; // false
-        model.foo = 'some value';
-        model.hasDirtyAttributes; // true
+        export default class PostAdapter extends MyCustomAdapter {
+          deleteRecord(store, type, snapshot) {
+            if (snapshot.adapterOptions.subscribe) {
+              // ...
+            }
+            // ...
+          }
+        }
         ```
     
-        @since 1.13.0
-        @property hasDirtyAttributes
         @public
-        @type {Boolean}
-        @readOnly
+        @param {Object} options
+        @return {Promise} a promise that will be resolved when the adapter returns
+        successfully or rejected if the adapter returns with an error.
       */
-      get hasDirtyAttributes(): boolean;
+      destroyRecord<T extends MinimalLegacyRecord>(this: T, options?: Record<string, unknown>): Promise<this>;
       /**
-        If this property is `true` the record is in the `saving` state. A
-        record enters the saving state when `save` is called, but the
-        adapter has not yet acknowledged that the changes have been
-        persisted to the backend.
-    
-        Example
-    
-        ```javascript
-        let record = store.createRecord('model');
-        record.isSaving; // false
-        let promise = record.save();
-        record.isSaving; // true
-        promise.then(function() {
-          record.isSaving; // false
-        });
-        ```
+        Unloads the record from the store. This will not send a delete request
+        to your server, it just unloads the record from memory.
     
-        @property isSaving
         @public
-        @type {Boolean}
-        @readOnly
       */
-      get isSaving(): boolean;
+      unloadRecord<T extends MinimalLegacyRecord>(this: T): void;
       /**
-        If this property is `true` the record is in the `deleted` state
-        and has been marked for deletion. When `isDeleted` is true and
-        `hasDirtyAttributes` is true, the record is deleted locally but the deletion
-        was not yet persisted. When `isSaving` is true, the change is
-        in-flight. When both `hasDirtyAttributes` and `isSaving` are false, the
-        change has persisted.
+        Returns an object, whose keys are changed properties, and value is
+        an [oldProp, newProp] array.
+    
+        The array represents the diff of the canonical state with the local state
+        of the model. Note: if the model is created locally, the canonical state is
+        empty since the adapter hasn't acknowledged the attributes yet:
     
         Example
     
+        ```js [app/models/mascot.js]
+        import Model, { attr } from '@ember-data/model';
+    
+        export default class MascotModel extends Model {
+          @attr('string') name;
+          @attr('boolean', {
+            defaultValue: false
+          })
+          isAdmin;
+        }
+        ```
+    
         ```javascript
-        let record = store.createRecord('model');
-        record.isDeleted;    // false
-        record.deleteRecord();
+        let mascot = store.createRecord('mascot');
     
-        // Locally deleted
-        record.isDeleted;           // true
-        record.hasDirtyAttributes;  // true
-        record.isSaving;            // false
+        mascot.changedAttributes(); // {}
     
-        // Persisting the deletion
-        let promise = record.save();
-        record.isDeleted;    // true
-        record.isSaving;     // true
+        mascot.set('name', 'Tomster');
+        mascot.changedAttributes(); // { name: [undefined, 'Tomster'] }
     
-        // Deletion Persisted
-        promise.then(function() {
-          record.isDeleted;          // true
-          record.isSaving;           // false
-          record.hasDirtyAttributes; // false
+        mascot.set('isAdmin', true);
+        mascot.changedAttributes(); // { isAdmin: [undefined, true], name: [undefined, 'Tomster'] }
+    
+        mascot.save().then(function() {
+          mascot.changedAttributes(); // {}
+    
+          mascot.set('isAdmin', false);
+          mascot.changedAttributes(); // { isAdmin: [true, false] }
         });
         ```
     
-        @property isDeleted
         @public
-        @type {Boolean}
-        @readOnly
+        @return {Object} an object, whose keys are changed properties,
+          and value is an [oldProp, newProp] array.
       */
-      get isDeleted(): boolean;
+      changedAttributes<T extends MinimalLegacyRecord>(this: T): ChangedAttributesHash;
       /**
-        If this property is `true` the record is in the `new` state. A
-        record will be in the `new` state when it has been created on the
-        client and the adapter has not yet report that it was successfully
-        saved.
+        If the model `hasDirtyAttributes` this function will discard any unsaved
+        changes. If the model `isNew` it will be removed from the store.
     
         Example
     
         ```javascript
-        let record = store.createRecord('model');
-        record.isNew; // true
-    
-        record.save().then(function(model) {
-          model.isNew; // false
-        });
+        record.name; // 'Untitled Document'
+        record.set('name', 'Doc 1');
+        record.name; // 'Doc 1'
+        record.rollbackAttributes();
+        record.name; // 'Untitled Document'
         ```
     
-        @property isNew
+        @since 1.13.0
         @public
-        @type {Boolean}
-        @readOnly
       */
-      get isNew(): boolean;
+      rollbackAttributes<T extends MinimalLegacyRecord>(this: T): void;
       /**
-        If this property is `true` the record is in the `valid` state.
-    
-        A record will be in the `valid` state when the adapter did not report any
-        server-side validation failures.
-    
-        @property isValid
-        @public
-        @type {Boolean}
-        @readOnly
+        @private
       */
-      get isValid(): boolean;
+      _createSnapshot<T extends MinimalLegacyRecord>(this: T): Snapshot<T>;
       /**
-        If the record is in the dirty state this property will report what
-        kind of change has caused it to move into the dirty
-        state. Possible values are:
-    
-        - `created` The record has been created by the client and not yet saved to the adapter.
-        - `updated` The record has been updated by the client and not yet saved to the adapter.
-        - `deleted` The record has been deleted by the client and not yet saved to the adapter.
+        Save the record and persist any changes to the record to an
+        external source via the adapter.
     
         Example
     
         ```javascript
-        let record = store.createRecord('model');
-        record.dirtyType; // 'created'
+        record.set('name', 'Tomster');
+        record.save().then(function() {
+          // Success callback
+        }, function() {
+          // Error callback
+        });
         ```
     
-        @property dirtyType
-        @public
-        @type {String}
-        @readOnly
-      */
-      get dirtyType(): 'created' | 'updated' | 'deleted' | '';
-      /**
-        If `true` the adapter reported that it was unable to save local
-        changes to the backend for any reason other than a server-side
-        validation error.
-    
-        Example
+       If you pass an object using the `adapterOptions` property of the options
+       argument it will be passed to your adapter via the snapshot.
     
-        ```javascript
-        record.isError; // false
-        record.set('foo', 'valid value');
-        record.save().then(null, function() {
-          record.isError; // true
-        });
+        ```js
+        record.save({ adapterOptions: { subscribe: false } });
         ```
     
-        @property isError
-        @public
-        @type {Boolean}
-        @readOnly
-      */
-      get isError(): boolean;
-      set isError(v: boolean);
-      /**
-        If `true` the store is attempting to reload the record from the adapter.
-    
-        Example
+        ```js [app/adapters/post.js]
+        import MyCustomAdapter from './custom-adapter';
     
-        ```javascript
-        record.isReloading; // false
-        record.reload();
-        record.isReloading; // true
+        export default class PostAdapter extends MyCustomAdapter {
+          updateRecord(store, type, snapshot) {
+            if (snapshot.adapterOptions.subscribe) {
+              // ...
+            }
+            // ...
+          }
+        }
         ```
     
-        @property isReloading
         @public
-        @type {Boolean}
-        @readOnly
+        @param {Object} options
+        @return {Promise} a promise that will be resolved when the adapter returns
+        successfully or rejected if the adapter returns with an error.
       */
-      isReloading: boolean;
+      save<T extends MinimalLegacyRecord>(this: T, options?: Record<string, unknown>): Promise<this>;
       /**
-        All ember models have an id property. This is an identifier
-        managed by an external source. These are always coerced to be
-        strings before being used internally. Note when declaring the
-        attributes for a model it is an error to an id
-        attribute.
+        Reload the record from the adapter.
     
-        ```javascript
-        let record = store.createRecord('model');
-        record.id; // null
+        This will only work if the record has already finished loading.
     
-        const { content: { data: model } } = await store.request(findRecord({ type: 'model', id: '1' }));
-        model.id; // '1'
+        Example
+    
+        ```js
+        import Component from '@glimmer/component';
+    
+        export default class extends Component {
+          async reload = () => {
+            await this.args.model.reload();
+            // do something with the reloaded model
+          }
+        }
         ```
     
-        @property id
         @public
-        @type {String}
-      */
-      get id(): string | null;
-      set id(id: string | null);
-      toString(): string;
-      /**
-        @property currentState
-        @private
-        @type {Object}
+        @param {Object} options optional, may include `adapterOptions` hash which will be passed to adapter request
+    
+       @return {Promise} a promise that will be resolved with the record when the
+        adapter returns successfully or rejected if the adapter returns
+        with an error.
       */
-      get currentState(): RecordState;
-      set currentState(_v: RecordState);
+      reload<T extends MinimalLegacyRecord>(this: T, options?: Record<string, unknown>): Promise<T>;
       /**
-        The store service instance which created this record instance
+        Get the reference for the specified belongsTo relationship.
     
-       @property store
-        @public
-       */
-      /**
-        When the record is in the `invalid` state this object will contain
-        any errors returned by the adapter. When present the errors hash
-        contains keys corresponding to the invalid property names
-        and values which are arrays of Javascript objects with two keys:
+        For instance, given the following model
     
-        - `message` A string containing the error message from the backend
-        - `attribute` The name of the property associated with this error message
+        ```js [app/models/blog-post.js]
+        import Model, { belongsTo } from '@ember-data/model';
     
-        ```javascript
-        record.errors.length; // 0
-        record.set('foo', 'invalid value');
-        record.save().catch(function() {
-          record.errors.foo;
-          // [{message: 'foo should be a number.', attribute: 'foo'}]
-        });
+        export default class BlogPost extends Model {
+          @belongsTo('user', { async: true, inverse: null }) author;
+        }
         ```
     
-        The `errors` property is useful for displaying error messages to
-        the user.
+        Then the reference for the author relationship would be
+        retrieved from a record instance like so:
     
-        ```handlebars
-        <label>Username: <Input @value={{@model.username}} /> </label>
-        {{#each @model.errors.username as |error|}}
-          <div class="error">
-            {{error.message}}
-          </div>
-        {{/each}}
-        <label>Email: <Input @value={{@model.email}} /> </label>
-        {{#each @model.errors.email as |error|}}
-          <div class="error">
-            {{error.message}}
-          </div>
-        {{/each}}
+        ```js
+        blogPost.belongsTo('author');
         ```
     
+        A `BelongsToReference` is a low-level API that allows access
+        and manipulation of a belongsTo relationship.
     
-        You can also access the special `messages` property on the error
-        object to get an array of all the error strings.
+        It is especially useful when you're dealing with `async` relationships
+        as it allows synchronous access to the relationship data if loaded, as
+        well as APIs for loading, reloading the data or accessing available
+        information without triggering a load.
     
-        ```handlebars
-        {{#each @model.errors.messages as |message|}}
-          <div class="error">
-            {{message}}
-          </div>
-        {{/each}}
-        ```
+        It may also be useful when using `sync` relationships that need to be
+        loaded/reloaded with more precise timing than marking the
+        relationship as `async` and relying on autofetch would have allowed.
     
-        @property errors
-        @public
-        @type {Errors}
-      */
-      get errors(): Errors;
-      /**
-        This property holds the `AdapterError` object with which
-        last adapter operation was rejected.
+        However,keep in mind that marking a relationship as `async: false` will introduce
+        bugs into your application if the data is not always guaranteed to be available
+        by the time the relationship is accessed. Ergo, it is recommended when using this
+        approach to utilize `links` for unloaded relationship state instead of identifiers.
+    
+        Reference APIs are entangled with the relationship's underlying state,
+        thus any getters or cached properties that utilize these will properly
+        invalidate if the relationship state changes.
+    
+        References are "stable", meaning that multiple calls to retrieve the reference
+        for a given relationship will always return the same HasManyReference.
     
-        @property adapterError
         @public
-        @type {AdapterError}
+        @param {String} name of the relationship
+        @since 2.5.0
+        @return {BelongsToReference} reference for this relationship
       */
-      get adapterError(): unknown;
-      set adapterError(v: unknown);
+      belongsTo<T extends Model, K extends keyof T & string>(this: T, prop: K & (K extends _MaybeBelongsToFields<T> ? K : never)): BelongsToReference<T, K>;
       /**
-        Create a JSON representation of the record, using the serialization
-        strategy of the store's adapter.
+        Get the reference for the specified hasMany relationship.
     
-       `serialize` takes an optional hash as a parameter, currently
-        supported options are:
+        For instance, given the following model
     
-       - `includeId`: `true` if the record's ID should be included in the
-          JSON representation.
+        ```js [app/models/blog-post.js]
+        import Model, { hasMany } from '@ember-data/model';
+    
+        export default class BlogPost extends Model {
+          @hasMany('comment', { async: true, inverse: null }) comments;
+        }
+        ```
+    
+        Then the reference for the comments relationship would be
+        retrieved from a record instance like so:
+    
+        ```js
+        blogPost.hasMany('comments');
+        ```
+    
+        A `HasManyReference` is a low-level API that allows access
+        and manipulation of a hasMany relationship.
+    
+        It is especially useful when you are dealing with `async` relationships
+        as it allows synchronous access to the relationship data if loaded, as
+        well as APIs for loading, reloading the data or accessing available
+        information without triggering a load.
+    
+        It may also be useful when using `sync` relationships with `@ember-data/model`
+        that need to be loaded/reloaded with more precise timing than marking the
+        relationship as `async` and relying on autofetch would have allowed.
+    
+        However,keep in mind that marking a relationship as `async: false` will introduce
+        bugs into your application if the data is not always guaranteed to be available
+        by the time the relationship is accessed. Ergo, it is recommended when using this
+        approach to utilize `links` for unloaded relationship state instead of identifiers.
+    
+        Reference APIs are entangled with the relationship's underlying state,
+        thus any getters or cached properties that utilize these will properly
+        invalidate if the relationship state changes.
+    
+        References are "stable", meaning that multiple calls to retrieve the reference
+        for a given relationship will always return the same HasManyReference.
     
-        @method serialize
         @public
-        @param {Object} options
-        @return {Object} an object whose values are primitive JSON values only
+        @param {String} name of the relationship
+        @since 2.5.0
+        @return {HasManyReference} reference for this relationship
       */
-      notifyPropertyChange(prop: string): this;
+      hasMany<T extends MinimalLegacyRecord, K extends MaybeHasManyFields<T>>(this: T, prop: K): HasManyReference<T, K>;
       /**
         Marks the record as deleted but does not save it. You must call
         `save` afterwards if you want to persist it. You might use this
@@ -447,295 +361,389 @@ declare module '@ember-data/model/-private/model' {
         }
         ```
     
-        @method deleteRecord
         @public
       */
+      deleteRecord<T extends MinimalLegacyRecord>(this: T): void;
+  }
+  /**
+   * Base class from which Models can be defined.
+   *
+   * ::: code-group
+   *
+   * ```js [app/models/user.js]
+   * import Model, { attr, belongsTo, hasMany } from '@ember-data/model';
+   *
+   * export default class User extends Model {
+   *   @attr name;
+   *   @attr('number') age;
+   *   @hasMany('post', { async: true, inverse: null }) posts;
+   *   @belongsTo('group', { async: false, inverse: 'users' }) group;
+   * }
+   * ```
+   *
+   * ```ts [app/models/user.ts]
+   * import Model, { attr, belongsTo, hasMany, type AsyncHasMany } from '@ember-data/model';
+   * import type { NumberTransform } from '@ember-data/serializer/transform';
+   * import type Group from './group';
+   * import type Post from './post';
+   *
+   * export default class User extends Model {
+   *   @attr name: string;
+   *
+   *   @attr<NumberTransform>('number')
+   *   age: number;
+   *
+   *   @hasMany('post', { async: true, inverse: null })
+   *   posts: AsyncHasMany<Post>;
+   *
+   *   @belongsTo('group', { async: false, inverse: 'users' })
+   *   group: Group | null;
+   * }
+   * ```
+   *
+   * :::
+   *
+   * Models both define the schema for a resource type and provide
+   * the class to use as the reactive object for data of resource
+   * of that type.
+   *
+   * @noInheritDoc
+   */
+  class Model extends EmberObject implements MinimalLegacyRecord {
       /**
-        Same as `deleteRecord`, but saves the record immediately.
+       * The store service instance which created this record instance
+       */
+      store: Store;
+      /** @internal */
+      ___recordState: RecordState;
+      /** @internal */
+      ___private_notifications: object;
+      /** @internal */
+      [RecordStore]: Store;
+      /** @internal */
+      init(options: ModelCreateArgs): void;
+      /** @internal */
+      destroy(): this;
+      /**
+        If this property is `true` the record is in the `empty`
+        state. Empty is the first state all records enter after they have
+        been created. Most records created by the store will quickly
+        transition to the `loading` state if data needs to be fetched from
+        the server or the `created` state if the record is created on the
+        client. A record can also enter the empty state if the adapter is
+        unable to locate the record.
+    
+        @property isEmpty
+        @public
+        @readonly
+      */
+      get isEmpty(): boolean;
+      /**
+        If this property is `true` the record is in the `loading` state. A
+        record enters this state when the store asks the adapter for its
+        data. It remains in this state until the adapter provides the
+        requested data.
+    
+        @property isLoading
+        @public
+        @readonly
+      */
+      get isLoading(): boolean;
+      /**
+        If this property is `true` the record is in the `loaded` state. A
+        record enters this state when its data is populated. Most of a
+        record's lifecycle is spent inside substates of the `loaded`
+        state.
     
         Example
     
-        ```js
-        import Component from '@glimmer/component';
+        ```javascript
+        let record = store.createRecord('model');
+        record.isLoaded; // true
     
-        export default class extends Component {
-          delete = () => {
-            this.args.model.destroyRecord().then(function() {
-              this.transitionToRoute('model.index');
-            });
-          }
-        }
+        const { content: { data: model } } = await store.request(findRecord({ type: 'model', id: '1' }));
+        model.isLoaded;
         ```
     
-        If you pass an object on the `adapterOptions` property of the options
-        argument it will be passed to your adapter via the snapshot
+        @property isLoaded
+        @public
+        @readonly
+      */
+      get isLoaded(): boolean;
+      /**
+        If this property is `true` the record is in the `dirty` state. The
+        record has local changes that have not yet been saved by the
+        adapter. This includes records that have been created (but not yet
+        saved) or deleted.
     
-        ```js
-        record.destroyRecord({ adapterOptions: { subscribe: false } });
-        ```
+        Example
     
-        ```app/adapters/post.js
-        import MyCustomAdapter from './custom-adapter';
+        ```javascript
+        let record = store.createRecord('model');
+        record.hasDirtyAttributes; // true
     
-        export default class PostAdapter extends MyCustomAdapter {
-          deleteRecord(store, type, snapshot) {
-            if (snapshot.adapterOptions.subscribe) {
-              // ...
-            }
-            // ...
-          }
-        }
+        const { content: { data: model } } = await store.request(findRecord({ type: 'model', id: '1' }));
+    
+        model.hasDirtyAttributes; // false
+        model.foo = 'some value';
+        model.hasDirtyAttributes; // true
         ```
     
-        @method destroyRecord
+        @since 1.13.0
+        @property hasDirtyAttributes
         @public
-        @param {Object} options
-        @return {Promise} a promise that will be resolved when the adapter returns
-        successfully or rejected if the adapter returns with an error.
+        @readonly
       */
+      get hasDirtyAttributes(): boolean;
       /**
-        Unloads the record from the store. This will not send a delete request
-        to your server, it just unloads the record from memory.
+        If this property is `true` the record is in the `saving` state. A
+        record enters the saving state when `save` is called, but the
+        adapter has not yet acknowledged that the changes have been
+        persisted to the backend.
+    
+        Example
     
-        @method unloadRecord
+        ```javascript
+        let record = store.createRecord('model');
+        record.isSaving; // false
+        let promise = record.save();
+        record.isSaving; // true
+        promise.then(function() {
+          record.isSaving; // false
+        });
+        ```
+    
+        @property isSaving
         @public
+        @readonly
       */
+      get isSaving(): boolean;
       /**
-        Returns an object, whose keys are changed properties, and value is
-        an [oldProp, newProp] array.
-    
-        The array represents the diff of the canonical state with the local state
-        of the model. Note: if the model is created locally, the canonical state is
-        empty since the adapter hasn't acknowledged the attributes yet:
+        If this property is `true` the record is in the `deleted` state
+        and has been marked for deletion. When `isDeleted` is true and
+        `hasDirtyAttributes` is true, the record is deleted locally but the deletion
+        was not yet persisted. When `isSaving` is true, the change is
+        in-flight. When both `hasDirtyAttributes` and `isSaving` are false, the
+        change has persisted.
     
         Example
     
-        ```app/models/mascot.js
-        import Model, { attr } from '@ember-data/model';
+        ```javascript
+        let record = store.createRecord('model');
+        record.isDeleted;    // false
+        record.deleteRecord();
     
-        export default class MascotModel extends Model {
-          @attr('string') name;
-          @attr('boolean', {
-            defaultValue: false
-          })
-          isAdmin;
-        }
-        ```
+        // Locally deleted
+        record.isDeleted;           // true
+        record.hasDirtyAttributes;  // true
+        record.isSaving;            // false
     
-        ```javascript
-        let mascot = store.createRecord('mascot');
+        // Persisting the deletion
+        let promise = record.save();
+        record.isDeleted;    // true
+        record.isSaving;     // true
     
-        mascot.changedAttributes(); // {}
+        // Deletion Persisted
+        promise.then(function() {
+          record.isDeleted;          // true
+          record.isSaving;           // false
+          record.hasDirtyAttributes; // false
+        });
+        ```
     
-        mascot.set('name', 'Tomster');
-        mascot.changedAttributes(); // { name: [undefined, 'Tomster'] }
+        @property isDeleted
+        @public
+        @readonly
+      */
+      get isDeleted(): boolean;
+      /**
+        If this property is `true` the record is in the `new` state. A
+        record will be in the `new` state when it has been created on the
+        client and the adapter has not yet report that it was successfully
+        saved.
     
-        mascot.set('isAdmin', true);
-        mascot.changedAttributes(); // { isAdmin: [undefined, true], name: [undefined, 'Tomster'] }
+        Example
     
-        mascot.save().then(function() {
-          mascot.changedAttributes(); // {}
+        ```javascript
+        let record = store.createRecord('model');
+        record.isNew; // true
     
-          mascot.set('isAdmin', false);
-          mascot.changedAttributes(); // { isAdmin: [true, false] }
+        record.save().then(function(model) {
+          model.isNew; // false
         });
         ```
     
-        @method changedAttributes
+        @property isNew
+        @public
+        @readonly
+      */
+      get isNew(): boolean;
+      /**
+        If this property is `true` the record is in the `valid` state.
+    
+        A record will be in the `valid` state when the adapter did not report any
+        server-side validation failures.
+    
+        @property isValid
         @public
-        @return {Object} an object, whose keys are changed properties,
-          and value is an [oldProp, newProp] array.
+        @readonly
       */
+      get isValid(): boolean;
       /**
-        If the model `hasDirtyAttributes` this function will discard any unsaved
-        changes. If the model `isNew` it will be removed from the store.
+        If the record is in the dirty state this property will report what
+        kind of change has caused it to move into the dirty
+        state. Possible values are:
+    
+        - `created` The record has been created by the client and not yet saved to the adapter.
+        - `updated` The record has been updated by the client and not yet saved to the adapter.
+        - `deleted` The record has been deleted by the client and not yet saved to the adapter.
     
         Example
     
         ```javascript
-        record.name; // 'Untitled Document'
-        record.set('name', 'Doc 1');
-        record.name; // 'Doc 1'
-        record.rollbackAttributes();
-        record.name; // 'Untitled Document'
+        let record = store.createRecord('model');
+        record.dirtyType; // 'created'
         ```
     
-        @since 1.13.0
-        @method rollbackAttributes
+        @property dirtyType
         @public
+        @readonly
       */
+      get dirtyType(): 'created' | 'updated' | 'deleted' | '';
       /**
-        @method _createSnapshot
-        @private
-      */
-      /**
-        Save the record and persist any changes to the record to an
-        external source via the adapter.
+        If `true` the adapter reported that it was unable to save local
+        changes to the backend for any reason other than a server-side
+        validation error.
     
         Example
     
         ```javascript
-        record.set('name', 'Tomster');
-        record.save().then(function() {
-          // Success callback
-        }, function() {
-          // Error callback
+        record.isError; // false
+        record.set('foo', 'valid value');
+        record.save().then(null, function() {
+          record.isError; // true
         });
         ```
     
-       If you pass an object using the `adapterOptions` property of the options
-       argument it will be passed to your adapter via the snapshot.
-    
-        ```js
-        record.save({ adapterOptions: { subscribe: false } });
-        ```
-    
-        ```app/adapters/post.js
-        import MyCustomAdapter from './custom-adapter';
-    
-        export default class PostAdapter extends MyCustomAdapter {
-          updateRecord(store, type, snapshot) {
-            if (snapshot.adapterOptions.subscribe) {
-              // ...
-            }
-            // ...
-          }
-        }
-        ```
-    
-        @method save
+        @property isError
         @public
-        @param {Object} options
-        @return {Promise} a promise that will be resolved when the adapter returns
-        successfully or rejected if the adapter returns with an error.
+        @readonly
       */
+      get isError(): boolean;
+      set isError(v: boolean);
       /**
-        Reload the record from the adapter.
-    
-        This will only work if the record has already finished loading.
+        If `true` the store is attempting to reload the record from the adapter.
     
         Example
     
-        ```js
-        import Component from '@glimmer/component';
-    
-        export default class extends Component {
-          async reload = () => {
-            await this.args.model.reload();
-            // do something with the reloaded model
-          }
-        }
+        ```javascript
+        record.isReloading; // false
+        record.reload();
+        record.isReloading; // true
         ```
     
-        @method reload
+        @property isReloading
         @public
-        @param {Object} options optional, may include `adapterOptions` hash which will be passed to adapter request
-    
-       @return {Promise} a promise that will be resolved with the record when the
-        adapter returns successfully or rejected if the adapter returns
-        with an error.
+        @readonly
       */
-      attr(): void;
+      isReloading: boolean;
       /**
-        Get the reference for the specified belongsTo relationship.
-    
-        For instance, given the following model
-    
-        ```app/models/blog-post.js
-        import Model, { belongsTo } from '@ember-data/model';
-    
-        export default class BlogPost extends Model {
-          @belongsTo('user', { async: true, inverse: null }) author;
-        }
-        ```
+        All ember models have an id property. This is an identifier
+        managed by an external source. These are always coerced to be
+        strings before being used internally. Note when declaring the
+        attributes for a model it is an error to an id
+        attribute.
     
-        Then the reference for the author relationship would be
-        retrieved from a record instance like so:
+        ```javascript
+        let record = store.createRecord('model');
+        record.id; // null
     
-        ```js
-        blogPost.belongsTo('author');
+        const { content: { data: model } } = await store.request(findRecord({ type: 'model', id: '1' }));
+        model.id; // '1'
         ```
     
-        A `BelongsToReference` is a low-level API that allows access
-        and manipulation of a belongsTo relationship.
-    
-        It is especially useful when you're dealing with `async` relationships
-        as it allows synchronous access to the relationship data if loaded, as
-        well as APIs for loading, reloading the data or accessing available
-        information without triggering a load.
-    
-        It may also be useful when using `sync` relationships that need to be
-        loaded/reloaded with more precise timing than marking the
-        relationship as `async` and relying on autofetch would have allowed.
-    
-        However,keep in mind that marking a relationship as `async: false` will introduce
-        bugs into your application if the data is not always guaranteed to be available
-        by the time the relationship is accessed. Ergo, it is recommended when using this
-        approach to utilize `links` for unloaded relationship state instead of identifiers.
-    
-        Reference APIs are entangled with the relationship's underlying state,
-        thus any getters or cached properties that utilize these will properly
-        invalidate if the relationship state changes.
-    
-        References are "stable", meaning that multiple calls to retrieve the reference
-        for a given relationship will always return the same HasManyReference.
-    
-        @method belongsTo
+        @property id
         @public
-        @param {String} name of the relationship
-        @since 2.5.0
-        @return {BelongsToReference} reference for this relationship
       */
+      get id(): string | null;
+      set id(id: string | null);
+      toString(): string;
       /**
-        Get the reference for the specified hasMany relationship.
+        @property currentState
+        @private
+      */
+      get currentState(): RecordState;
+      set currentState(_v: RecordState);
+      /**
+        The store service instance which created this record instance
     
-        For instance, given the following model
+       @property store
+        @public
+       */
+      /**
+        When the record is in the `invalid` state this object will contain
+        any errors returned by the adapter. When present the errors hash
+        contains keys corresponding to the invalid property names
+        and values which are arrays of Javascript objects with two keys:
     
-        ```app/models/blog-post.js
-        import Model, { hasMany } from '@ember-data/model';
+        - `message` A string containing the error message from the backend
+        - `attribute` The name of the property associated with this error message
     
-        export default class BlogPost extends Model {
-          @hasMany('comment', { async: true, inverse: null }) comments;
-        }
+        ```javascript
+        record.errors.length; // 0
+        record.set('foo', 'invalid value');
+        record.save().catch(function() {
+          record.errors.foo;
+          // [{message: 'foo should be a number.', attribute: 'foo'}]
+        });
         ```
     
-        Then the reference for the comments relationship would be
-        retrieved from a record instance like so:
+        The `errors` property is useful for displaying error messages to
+        the user.
     
-        ```js
-        blogPost.hasMany('comments');
+        ```handlebars
+        <label>Username: <Input @value={{@model.username}} /> </label>
+        {{#each @model.errors.username as |error|}}
+          <div class="error">
+            {{error.message}}
+          </div>
+        {{/each}}
+        <label>Email: <Input @value={{@model.email}} /> </label>
+        {{#each @model.errors.email as |error|}}
+          <div class="error">
+            {{error.message}}
+          </div>
+        {{/each}}
         ```
     
-        A `HasManyReference` is a low-level API that allows access
-        and manipulation of a hasMany relationship.
-    
-        It is especially useful when you are dealing with `async` relationships
-        as it allows synchronous access to the relationship data if loaded, as
-        well as APIs for loading, reloading the data or accessing available
-        information without triggering a load.
-    
-        It may also be useful when using `sync` relationships with `@ember-data/model`
-        that need to be loaded/reloaded with more precise timing than marking the
-        relationship as `async` and relying on autofetch would have allowed.
     
-        However,keep in mind that marking a relationship as `async: false` will introduce
-        bugs into your application if the data is not always guaranteed to be available
-        by the time the relationship is accessed. Ergo, it is recommended when using this
-        approach to utilize `links` for unloaded relationship state instead of identifiers.
+        You can also access the special `messages` property on the error
+        object to get an array of all the error strings.
     
-        Reference APIs are entangled with the relationship's underlying state,
-        thus any getters or cached properties that utilize these will properly
-        invalidate if the relationship state changes.
+        ```handlebars
+        {{#each @model.errors.messages as |message|}}
+          <div class="error">
+            {{message}}
+          </div>
+        {{/each}}
+        ```
     
-        References are "stable", meaning that multiple calls to retrieve the reference
-        for a given relationship will always return the same HasManyReference.
+        @property errors
+        @public
+      */
+      get errors(): Errors;
+      /**
+        This property holds the `AdapterError` object with which
+        last adapter operation was rejected.
     
-        @method hasMany
+        @property adapterError
         @public
-        @param {String} name of the relationship
-        @since 2.5.0
-        @return {HasManyReference} reference for this relationship
       */
+      get adapterError(): unknown;
+      set adapterError(v: unknown);
+      notifyPropertyChange(prop: string): this;
+      /** @internal */
+      attr(): void;
       /**
        Given a callback, iterates over each of the relationships in the model,
        invoking the callback with the name of each relationship and its relationship
@@ -765,7 +773,7 @@ declare module '@ember-data/model/-private/model' {
     
        Example
     
-       ```app/serializers/application.js
+       ```js [app/serializers/application.js]
        import JSONSerializer from '@ember-data/serializer/json';
     
        export default class ApplicationSerializer extends JSONSerializer {
@@ -784,7 +792,6 @@ declare module '@ember-data/model/-private/model' {
       }
        ```
     
-       @method eachRelationship
        @public
        @param {Function} callback the callback to invoke
        @param {any} binding the value to which the callback's `this` should be bound
@@ -793,17 +800,10 @@ declare module '@ember-data/model/-private/model' {
       relationshipFor(name: string): LegacyRelationshipField | undefined;
       inverseFor(name: string): LegacyRelationshipField | null;
       eachAttribute<T>(callback: (this: NoInfer<T> | undefined, key: isSubClass<this> extends true ? MaybeAttrFields<this> : string, meta: LegacyAttributeField) => void, binding?: T): void;
-      static isModel: boolean;
       /**
-        Create should only ever be called by the store. To create an instance of a
-        `Model` in a dirty state use `store.createRecord`.
-    
-       To create instances of `Model` in a clean state, use `store.push`
-    
-        @method create
-        @private
-        @static
-      */
+       * @internal
+       */
+      static isModel: boolean;
       /**
        Represents the model's class name as a string. This can be used to look up the model's class name through
        `Store`'s modelFor method.
@@ -831,9 +831,7 @@ declare module '@ember-data/model/-private/model' {
        ```
        @property modelName
         @public
-       @type String
        @readonly
-       @static
       */
       static modelName: string;
       /**
@@ -841,7 +839,7 @@ declare module '@ember-data/model/-private/model' {
     
        For example, if you define a model like this:
     
-       ```app/models/post.js
+       ```js [app/models/post.js]
        import Model, { hasMany } from '@ember-data/model';
     
        export default class PostModel extends Model {
@@ -851,9 +849,7 @@ declare module '@ember-data/model/-private/model' {
     
        Calling `store.modelFor('post').typeForRelationship('comments', store)` will return `Comment`.
     
-       @method typeForRelationship
         @public
-       @static
        @param {String} name the name of the relationship
        @param {store} store an instance of Store
        @return {Model} the type of the relationship, or undefined
@@ -865,7 +861,7 @@ declare module '@ember-data/model/-private/model' {
     
        For example, if you define models like this:
     
-       ```app/models/post.js
+       ```js [app/models/post.js]
        import Model, { hasMany } from '@ember-data/model';
     
        export default class PostModel extends Model {
@@ -873,7 +869,7 @@ declare module '@ember-data/model/-private/model' {
         }
        ```
     
-       ```app/models/message.js
+       ```js [app/models/message.js]
        import Model, { belongsTo } from '@ember-data/model';
     
        export default class MessageModel extends Model {
@@ -886,9 +882,7 @@ declare module '@ember-data/model/-private/model' {
        store.modelFor('message').inverseFor('owner', store) // { type: 'post', name: 'comments', kind: 'hasMany' }
        ```
     
-       @method inverseFor
         @public
-       @static
        @param {String} name the name of the relationship
        @param {Store} store
        @return {Object} the inverse relationship, or null
@@ -903,7 +897,7 @@ declare module '@ember-data/model/-private/model' {
     
        For example, given the following model definition:
     
-       ```app/models/blog.js
+       ```js [app/models/blog.js]
        import Model, { belongsTo, hasMany } from '@ember-data/model';
     
        export default class BlogModel extends Model {
@@ -931,9 +925,7 @@ declare module '@ember-data/model/-private/model' {
     
        @property relationships
         @public
-       @static
-       @type Map
-       @readOnly
+       @readonly
        */
       static get relationships(): Map<string, LegacyRelationshipField[]>;
       /**
@@ -941,7 +933,7 @@ declare module '@ember-data/model/-private/model' {
        by the relationship kind. For example, given a model with this
        definition:
     
-       ```app/models/blog.js
+       ```js [app/models/blog.js]
        import Model, { belongsTo, hasMany } from '@ember-data/model';
     
        export default class BlogModel extends Model {
@@ -966,9 +958,7 @@ declare module '@ember-data/model/-private/model' {
     
        @property relationshipNames
         @public
-       @static
-       @type Object
-       @readOnly
+       @readonly
        */
       static get relationshipNames(): {
           hasMany: string[];
@@ -981,7 +971,7 @@ declare module '@ember-data/model/-private/model' {
     
        For example, given a model with this definition:
     
-       ```app/models/blog.js
+       ```js [app/models/blog.js]
        import Model, { belongsTo, hasMany } from '@ember-data/model';
     
        export default class BlogModel extends Model {
@@ -1003,9 +993,7 @@ declare module '@ember-data/model/-private/model' {
     
        @property relatedTypes
        @public
-       @static
-       @type Array
-       @readOnly
+       @readonly
        */
       static get relatedTypes(): string[];
       /**
@@ -1015,7 +1003,7 @@ declare module '@ember-data/model/-private/model' {
        For example, given a model with this
        definition:
     
-       ```app/models/blog.js
+       ```js [app/models/blog.js]
        import Model, { belongsTo, hasMany } from '@ember-data/model';
     
        export default class BlogModel extends Model {
@@ -1040,9 +1028,7 @@ declare module '@ember-data/model/-private/model' {
     
        @property relationshipsByName
         @public
-       @static
-       @type Map
-       @readOnly
+       @readonly
        */
       static get relationshipsByName(): Map<string, LegacyRelationshipField>;
       static get relationshipsObject(): Record<string, LegacyRelationshipField>;
@@ -1053,7 +1039,7 @@ declare module '@ember-data/model/-private/model' {
     
        For example:
     
-       ```app/models/blog.js
+       ```js [app/models/blog.js]
        import Model, { attr, belongsTo, hasMany } from '@ember-data/model';
     
        export default class BlogModel extends Model {
@@ -1083,9 +1069,7 @@ declare module '@ember-data/model/-private/model' {
     
        @property fields
         @public
-       @static
-       @type Map
-       @readOnly
+       @readonly
        */
       static get fields(): Map<string, 'attribute' | 'belongsTo' | 'hasMany'>;
       /**
@@ -1093,9 +1077,7 @@ declare module '@ember-data/model/-private/model' {
        invoking the callback with the name of each relationship and its relationship
        descriptor.
     
-       @method eachRelationship
         @public
-       @static
        @param {Function} callback the callback to invoke
        @param {any} binding the value to which the callback's `this` should be bound
        */
@@ -1106,16 +1088,13 @@ declare module '@ember-data/model/-private/model' {
        returned just once, regardless of how many different relationships it has
        with a model.
     
-       @method eachRelatedType
         @public
-       @static
        @param {Function} callback the callback to invoke
        @param {any} binding the value to which the callback's `this` should be bound
        */
       static eachRelatedType<T>(callback: (this: T | undefined, type: string) => void, binding?: T): void;
       /**
        *
-       * @method determineRelationshipType
        * @private
        * @deprecated
        */
@@ -1127,7 +1106,7 @@ declare module '@ember-data/model/-private/model' {
     
        Example
     
-       ```app/models/person.js
+       ```js [app/models/person.js]
        import Model, { attr } from '@ember-data/model';
     
        export default class PersonModel extends Model {
@@ -1154,9 +1133,7 @@ declare module '@ember-data/model/-private/model' {
     
        @property attributes
         @public
-       @static
-       @type {Map}
-       @readOnly
+       @readonly
        */
       static get attributes(): Map<string, LegacyAttributeField>;
       /**
@@ -1167,7 +1144,7 @@ declare module '@ember-data/model/-private/model' {
     
        Example
     
-       ```app/models/person.js
+       ```js [app/models/person.js]
        import Model, { attr } from '@ember-data/model';
     
        export default class PersonModel extends Model {
@@ -1193,9 +1170,7 @@ declare module '@ember-data/model/-private/model' {
     
        @property transformedAttributes
         @public
-       @static
-       @type {Map}
-       @readOnly
+       @readonly
        */
       static get transformedAttributes(): Map<string, string>;
       /**
@@ -1236,11 +1211,9 @@ declare module '@ember-data/model/-private/model' {
        // birthday {type: "date", kind: 'attribute', options: Object, parentType: function, name: "birthday"}
        ```
     
-       @method eachAttribute
         @public
        @param {Function} callback The callback to execute
        @param {Object} [binding] the value to which the callback's `this` should be bound
-       @static
        */
       static eachAttribute<T, Schema extends Model>(callback: (this: T | undefined, key: MaybeAttrFields<Schema>, attribute: LegacyAttributeField) => void, binding?: T): void;
       /**
@@ -1282,19 +1255,15 @@ declare module '@ember-data/model/-private/model' {
        // birthday date
        ```
     
-       @method eachTransformedAttribute
         @public
        @param {Function} callback The callback to execute
        @param {Object} [binding] the value to which the callback's `this` should be bound
-       @static
        */
       static eachTransformedAttribute<T, Schema extends Model>(callback: (this: T | undefined, key: Exclude<keyof Schema & string, keyof Model & string>, type: string) => void, binding?: T): void;
       /**
        Returns the name of the model class.
     
-       @method toString
         @public
-       @static
        */
       static toString(): string;
   }