@ember-data/model 5.4.0-alpha.30 → 5.4.0-alpha.32

package/unstable-preview-types/-private/record-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-state.d.ts","sourceRoot":"","sources":["../../src/-private/record-state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAC;AAI3C,OAAO,KAAK,mBAAmB,MAAM,kDAAkD,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kDAAkD,CAAC;AACrF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kCAAkC,CAAC;AAG9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAgB3D;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,kBAAkB,sBAwBhH;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,QAMxF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsCE;AACF,MAAM,CAAC,OAAO,OAAO,WAAW;IACtB,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,sBAAsB,CAAC;IACnC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,EAAE,EAAE,mBAAmB,CAAC;IAExB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC;IACb,cAAc,EAAE,YAAY,EAAE,CAAC;IAC/B,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,mBAAmB;IAoGvC,OAAO;IAIP,MAAM,CAAC,GAAG,EAAE,MAAM,IAAI,GAAG,MAAM;IAI/B,mBAAmB,CAAC,MAAM,EAAE,MAAM;IA+BlC,kBAAkB;IAQV,QAAQ,EAAE,OAAO,CAAC;IAE1B,IACI,SAAS,YAEZ;IAED,IACI,QAAQ,YAKX;IAED,IACI,OAAO,YAUV;IAED,IACI,OAAO,YAMV;IAED,IACI,KAAK,YAIR;IAED,IACI,SAAS,YAIZ;IAED,IACI,OAAO,YAEV;IAED,IACI,OAAO,YAMV;IAED,IACI,OAAO,YAOV;IAED,IACI,YAAY,YAMf;IAED,IACI,WAAW,YAEd;IAED,IACI,SAAS,yWA2CZ;IAED,IACI,SAAS,2CAqBZ;CACF"}

package/unstable-preview-types/-private/references/belongs-to.d.ts

@@ -0,0 +1,501 @@
+import type { ResourceEdge } from '@ember-data/graph/-private/edges/resource';
+import type { Graph } from '@ember-data/graph/-private/graph';
+import type Store from '@ember-data/store';
+import type { StableRecordIdentifier } from '@warp-drive/core-types';
+import type { TypeFromInstanceOrString } from '@warp-drive/core-types/record';
+import type { Links, Meta, SingleResourceDocument, SingleResourceRelationship } from '@warp-drive/core-types/spec/raw';
+import type { IsUnknown } from '../belongs-to';
+/**
+ 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
+ from `@ember-data/model` 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.
+
+ @class BelongsToReference
+ @public
+ */
+export default class BelongsToReference<T = unknown, K extends string = IsUnknown<T> extends true ? string : keyof T & string, Related = K extends keyof T ? Awaited<T[K]> : unknown> {
+    graph: Graph;
+    store: Store;
+    belongsToRelationship: ResourceEdge;
+    /**
+     * The field name on the parent record for this has-many relationship.
+     *
+     * @property {String} key
+     * @public
+     */
+    key: K;
+    /**
+     * The type of resource this relationship will contain.
+     *
+     * @property {String} type
+     * @public
+     */
+    type: TypeFromInstanceOrString<Related>;
+    ___token: object;
+    ___identifier: StableRecordIdentifier<TypeFromInstanceOrString<T>>;
+    ___relatedToken: object | null;
+    _ref: number;
+    constructor(store: Store, graph: Graph, parentIdentifier: StableRecordIdentifier<TypeFromInstanceOrString<T>>, belongsToRelationship: ResourceEdge, key: K);
+    destroy(): void;
+    /**
+     * The identifier of the record that this reference refers to.
+     * `null` if no related record is known.
+     *
+     * @property {StableRecordIdentifier | null} identifier
+     * @public
+     */
+    get identifier(): StableRecordIdentifier<TypeFromInstanceOrString<Related>> | null;
+    /**
+     The `id` of the record that this reference refers to. Together, the
+     `type()` and `id()` methods form a composite key for the identity
+     map. This can be used to access the id of an async relationship
+     without triggering a fetch that would normally happen if you
+     attempted to use `record.relationship.id`.
+  
+     Example
+  
+     ```javascript
+     // models/blog.js
+     import Model, { belongsTo } from '@ember-data/model';
+  
+     export default class BlogModel extends Model {
+      @belongsTo('user', { async: true, inverse: null }) user;
+     }
+  
+     let blog = store.push({
+        data: {
+          type: 'blog',
+          id: 1,
+          relationships: {
+            user: {
+              data: { type: 'user', id: 1 }
+            }
+          }
+        }
+      });
+     let userRef = blog.belongsTo('user');
+  
+     // get the identifier of the reference
+     if (userRef.remoteType() === "id") {
+        let id = userRef.id();
+      }
+     ```
+  
+     @method id
+     @public
+     @return {String} The id of the record in this belongsTo relationship.
+     */
+    id(): string | null;
+    /**
+     The link Ember Data will use to fetch or reload this belongs-to
+     relationship. By default it uses only the "related" resource linkage.
+  
+     Example
+  
+     ```javascript
+     // models/blog.js
+     import Model, { belongsTo } from '@ember-data/model';
+     export default Model.extend({
+        user: belongsTo('user', { async: true, inverse: null })
+      });
+  
+     let blog = store.push({
+        data: {
+          type: 'blog',
+          id: 1,
+          relationships: {
+            user: {
+              links: {
+                related: '/articles/1/author'
+              }
+            }
+          }
+        }
+      });
+     let userRef = blog.belongsTo('user');
+  
+     // get the identifier of the reference
+     if (userRef.remoteType() === "link") {
+        let link = userRef.link();
+      }
+     ```
+  
+     @method link
+     @public
+     @return {String} The link Ember Data will use to fetch or reload this belongs-to relationship.
+     */
+    link(): string | null;
+    /**
+     * any links that have been received for this relationship
+     *
+     * @method links
+     * @public
+     * @return
+     */
+    links(): Links | null;
+    /**
+     The meta data for the belongs-to relationship.
+  
+     Example
+  
+     ```javascript
+     // models/blog.js
+     import Model, { belongsTo } from '@ember-data/model';
+     export default Model.extend({
+        user: belongsTo('user', { async: true, inverse: null })
+      });
+  
+     let blog = store.push({
+        data: {
+          type: 'blog',
+          id: 1,
+          relationships: {
+            user: {
+              links: {
+                related: {
+                  href: '/articles/1/author'
+                },
+              },
+              meta: {
+                lastUpdated: 1458014400000
+              }
+            }
+          }
+        }
+      });
+  
+     let userRef = blog.belongsTo('user');
+  
+     userRef.meta() // { lastUpdated: 1458014400000 }
+     ```
+  
+     @method meta
+      @public
+     @return {Object} The meta information for the belongs-to relationship.
+     */
+    meta(): Meta | null;
+    _resource(): SingleResourceRelationship;
+    /**
+     This returns a string that represents how the reference will be
+     looked up when it is loaded. If the relationship has a link it will
+     use the "link" otherwise it defaults to "id".
+  
+     Example
+  
+     ```app/models/post.js
+     import Model, { hasMany } from '@ember-data/model';
+  
+     export default class PostModel extends Model {
+       @hasMany('comment', { async: true, inverse: null }) comments;
+     }
+     ```
+  
+     ```javascript
+     let post = store.push({
+       data: {
+         type: 'post',
+         id: 1,
+         relationships: {
+           comments: {
+             data: [{ type: 'comment', id: 1 }]
+           }
+         }
+       }
+     });
+  
+     let commentsRef = post.hasMany('comments');
+  
+     // get the identifier of the reference
+     if (commentsRef.remoteType() === "ids") {
+       let ids = commentsRef.ids();
+     } else if (commentsRef.remoteType() === "link") {
+       let link = commentsRef.link();
+     }
+     ```
+  
+     @method remoteType
+     @public
+     @return {String} The name of the remote type. This should either be `link` or `id`
+     */
+    remoteType(): 'link' | 'id';
+    /**
+     `push` can be used to update the data in the relationship and EmberData
+     will treat the new data as the canonical value of this relationship on
+     the backend. A value of `null` (e.g. `{ data: null }`) can be passed to
+     clear the relationship.
+  
+     Example model
+  
+     ```app/models/blog.js
+     import Model, { belongsTo } from '@ember-data/model';
+  
+     export default class BlogModel extends Model {
+        @belongsTo('user', { async: true, inverse: null }) user;
+      }
+     ```
+  
+     Setup some initial state, note we haven't loaded the user yet:
+  
+     ```js
+     const blog = store.push({
+        data: {
+          type: 'blog',
+          id: '1',
+          relationships: {
+            user: {
+              data: { type: 'user', id: '1' }
+            }
+          }
+        }
+     });
+  
+     const userRef = blog.belongsTo('user');
+     userRef.id(); // '1'
+     ```
+  
+     Update the state using `push`, note we can do this even without
+     having loaded the user yet by providing a resource-identifier.
+  
+     Both full a resource and a resource-identifier are supported.
+  
+     ```js
+     await userRef.push({
+        data: {
+          type: 'user',
+          id: '2',
+        }
+      });
+  
+      userRef.id(); // '2'
+     ```
+  
+     You may also pass in links and meta fore the relationship, and sideload
+     additional resources that might be required.
+  
+     ```js
+      await userRef.push({
+          data: {
+            type: 'user',
+            id: '2',
+          },
+          links: {
+            related: '/articles/1/author'
+          },
+          meta: {
+            lastUpdated: Date.now()
+          },
+          included: [
+            {
+              type: 'user-preview',
+              id: '2',
+              attributes: {
+                username: '@runspired'
+              }
+            }
+          ]
+        });
+      ```
+  
+     By default, the store will attempt to fetch the record if it is not loaded or its
+     resource data is not included in the call to `push` before resolving the returned
+     promise with the new state..
+  
+     Alternatively, pass `true` as the second argument to avoid fetching unloaded records
+     and instead the promise will resolve with void without attempting to fetch. This is
+     particularly useful if you want to update the state of the relationship without
+     forcing the load of all of the associated record.
+  
+     @method push
+     @public
+     @param {Object} doc a JSONAPI document object describing the new value of this relationship.
+     @param {Boolean} [skipFetch] if `true`, do not attempt to fetch unloaded records
+     @return {Promise<OpaqueRecordInstance | null | void>}
+    */
+    push(doc: SingleResourceDocument, skipFetch?: boolean): Promise<Related | null | void>;
+    /**
+     `value()` synchronously returns the current value of the belongs-to
+     relationship. Unlike `record.relationshipName`, calling
+     `value()` on a reference does not trigger a fetch if the async
+     relationship is not yet loaded. If the relationship is not loaded
+     it will always return `null`.
+  
+     Example
+  
+     ```javascript
+     // models/blog.js
+     import Model, { belongsTo } from '@ember-data/model';
+  
+     export default class BlogModel extends Model {
+       @belongsTo('user', { async: true, inverse: null }) user;
+     }
+  
+     let blog = store.push({
+        data: {
+          type: 'blog',
+          id: 1,
+          relationships: {
+            user: {
+              data: { type: 'user', id: 1 }
+            }
+          }
+        }
+      });
+     let userRef = blog.belongsTo('user');
+  
+     userRef.value(); // null
+  
+     // provide data for reference
+     userRef.push({
+        data: {
+          type: 'user',
+          id: 1,
+          attributes: {
+            username: "@user"
+          }
+        }
+      }).then(function(user) {
+        userRef.value(); // user
+      });
+     ```
+  
+     @method value
+      @public
+     @return {Model} the record in this relationship
+     */
+    value(): Related | null;
+    /**
+     Loads a record in a belongs-to relationship if it is not already
+     loaded. If the relationship is already loaded this method does not
+     trigger a new load.
+  
+     Example
+  
+     ```javascript
+     // models/blog.js
+     import Model, { belongsTo } from '@ember-data/model';
+  
+     export default class BlogModel extends Model {
+       @belongsTo('user', { async: true, inverse: null }) user;
+     }
+  
+     let blog = store.push({
+        data: {
+          type: 'blog',
+          id: 1,
+          relationships: {
+            user: {
+              data: { type: 'user', id: 1 }
+            }
+          }
+        }
+      });
+     let userRef = blog.belongsTo('user');
+  
+     userRef.value(); // null
+  
+     userRef.load().then(function(user) {
+        userRef.value() === user
+      });
+     ```
+  
+     You may also pass in an options object whose properties will be
+     fed forward. This enables you to pass `adapterOptions` into the
+     request given to the adapter via the reference.
+  
+     Example
+  
+     ```javascript
+     userRef.load({ adapterOptions: { isPrivate: true } }).then(function(user) {
+       userRef.value() === user;
+     });
+     ```
+     ```app/adapters/user.js
+     import Adapter from '@ember-data/adapter';
+  
+     export default class UserAdapter extends Adapter {
+       findRecord(store, type, id, snapshot) {
+         // In the adapter you will have access to adapterOptions.
+         let adapterOptions = snapshot.adapterOptions;
+       }
+     });
+     ```
+  
+     @method load
+      @public
+     @param {Object} options the options to pass in.
+     @return {Promise} a promise that resolves with the record in this belongs-to relationship.
+     */
+    load(options?: Record<string, unknown>): Promise<Related | null>;
+    /**
+     Triggers a reload of the value in this relationship. If the
+     remoteType is `"link"` Ember Data will use the relationship link to
+     reload the relationship. Otherwise it will reload the record by its
+     id.
+  
+     Example
+  
+     ```javascript
+     // models/blog.js
+     import Model, { belongsTo } from '@ember-data/model';
+  
+     export default class BlogModel extends Model {
+       @belongsTo('user', { async: true, inverse: null }) user;
+     }
+  
+     let blog = store.push({
+        data: {
+          type: 'blog',
+          id: 1,
+          relationships: {
+            user: {
+              data: { type: 'user', id: 1 }
+            }
+          }
+        }
+      });
+     let userRef = blog.belongsTo('user');
+  
+     userRef.reload().then(function(user) {
+        userRef.value() === user
+      });
+     ```
+  
+     You may also pass in an options object whose properties will be
+     fed forward. This enables you to pass `adapterOptions` into the
+     request given to the adapter via the reference. A full example
+     can be found in the `load` method.
+  
+     Example
+  
+     ```javascript
+     userRef.reload({ adapterOptions: { isPrivate: true } })
+     ```
+  
+     @method reload
+      @public
+     @param {Object} options the options to pass in.
+     @return {Promise} a promise that resolves with the record in this belongs-to relationship after the reload has completed.
+     */
+    reload(options?: Record<string, unknown>): Promise<Related | null>;
+}
+//# sourceMappingURL=belongs-to.d.ts.map

package/unstable-preview-types/-private/references/belongs-to.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"belongs-to.d.ts","sourceRoot":"","sources":["../../../src/-private/references/belongs-to.ts"],"names":[],"mappings":"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"}