@ember-data/store 4.12.0-alpha.18 → 4.12.0-alpha.19

package/README.md

@@ -19,7 +19,8 @@
 
 This package provides [*Ember***Data**](https://github.com/emberjs/data/)'s `Store` class.
 
-The `Store` coordinates interaction between your application, the `Cache`, and sources of data (such as your `API` or a local persistence layer).
+The `Store` coordinates interaction between your application, a [Cache](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Cache),
+and sources of data (such as your API or a local persistence layer) accessed via a [RequestManager](https://github.com/emberjs/data/tree/main/packages/request).
 
 ```mermaid
 flowchart LR
@@ -57,15 +58,15 @@ After installing you will want to configure your first `Store`. Read more below
 
 ## 🔨 Creating A Store
 
-To use a `Store` we will need to do few things: add a `Cache` to store data **in-memory**, add an `Adapter` to fetch data from a source, and implement `instantiateRecord` to tell the store how to display the data for individual resources. 
+To use a `Store` we will need to do few things: add a [Cache](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Cache) to store data **in-memory**, add a [Handler](https://github.com/emberjs/data/tree/main/packages/request#handling-requests) to fetch data from a source, and implement `instantiateRecord` to tell the store how to display the data for individual resources. 
 
 > **Note** If you are using the package `ember-data` then a `JSON:API` cache and `instantiateRecord` are configured for you by default.
 
 ### Configuring A Cache
 
-To start, let's install a `JSON:API` cache. If your app uses `GraphQL` or `REST` other caches may better fit your data. You can author your own cache by creating one that conforms to the [spec]().
+To start, let's install a [JSON:API](https://jsonapi.org/) cache. If your app uses `GraphQL` or `REST` other caches may better fit your data. You can author your own cache by creating one that conforms to the [spec](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Cache).
 
-The package `@ember-data/json-api` provides a `JSON:API` cache we can use. After installing it, we can configure the store to use this cache.
+The package [@ember-data/json-api](https://github.com/emberjs/data/tree/main/packages/json-api) provides a [JSON:API](https://jsonapi.org/) cache we can use. After installing it, we can configure the store to use this cache.
 
 ```js
 import Store from '@ember-data/store';
@@ -80,9 +81,7 @@ class extends Store {
 
 Now that we have a `cache` let's setup something to handle fetching and saving data via our API.
 
-> **Note** [1] the cache from `@ember-data/json-api` is a special cache: if the package is present the `createCache` hook will automatically do the above wiring if the hook is not implemented. We still recommend implementing the hook.
->
-> **Note** [2] The `ember-data` package automatically includes the `@ember-data/json-api` cache for you.
+> **Note** The `ember-data` package automatically includes and configures the `@ember-data/json-api` cache for you.
 
 ### Handling Requests
 
@@ -93,7 +92,7 @@ To start, let's install the `FetchManager` from `@ember-data/request` and the ba
 > **Note** If your app uses `GraphQL`, `REST` or different conventions for `JSON:API` than your cache expects, other handlers may better fit your data. You can author your own handler by creating one that conforms to the [handler interface](https://github.com/emberjs/data/tree/main/packages/request#handling-requests).
 
 ```ts
-import Store from '@ember-data/store';
+import Store, { CacheHandler } from '@ember-data/store';
 import RequestManager from '@ember-data/request';
 import Fetch from '@ember-data/request/fetch';
 
@@ -102,6 +101,7 @@ export default class extends Store {
     super(...arguments);
     this.requestManager = new RequestManager();
     this.requestManager.use([Fetch]);
+    this.requestManager.useCache(CacheHandler);
   }
 }
 ```
@@ -113,12 +113,14 @@ Alternatively if you have configured the `RequestManager` to be a service you ma
 *app/services/request.js*
 ```ts
 import RequestManager from '@ember-data/request';
+import { CacheHandler } from '@ember-data/store';
 import Fetch from '@ember-data/request/fetch';
 
 export default class extends RequestManager {
   constructor(createArgs) {
     super(createArgs);
     this.use([Fetch]);
+    this.useCache(CacheHandler);
   }
 }
 ```
@@ -135,7 +137,8 @@ export default class extends Store {
 
 ### Presenting Data from the Cache
 
-Now that we have a source and a cach for our data, we need to configure how the Store delivers that data back to our application. We do this via the hook `instantiateRecord`, which allows us to transform the data for a resource before handing it to the application.
+Now that we have a source and a cach for our data, we need to configure how the Store delivers that data back to our application. We do this via the hook [instantiateRecord](https://api.emberjs.com/ember-data/release/classes/Store/methods/instantiateRecord%20(hook)?anchor=instantiateRecord%20(hook)),
+which allows us to transform the data for a resource before handing it to the application.
 
 A naive way to present the data would be to return it as JSON. Typically instead this hook will be used to add reactivity and make each unique resource a singleton, ensuring that if the cache updates our presented data will reflect the new state.
 
@@ -182,6 +185,5 @@ Typically you will choose an existing record implementation such as `@ember-data
 
 Because of the boundaries around instantiation and the cache, record implementations should be capable of interop both with each other and with any `Cache`. Due to this, if needed an application can utilize multiple record implementations and multiple cache implementations either to support enhanced features for only a subset of records or to be able to incrementally migrate from one record/cache to another record or cache.
 
-> Note: [1] `@ember-data/model` is a special record implementation: currently, if the package is present the `instantiateRecord` hook will automatically do the above wiring if the hook is not implemented.
->
-> Note: [2] The `ember-data` package automatically includes the `@ember-data/model` implementation for you.
+> **Note:** The `ember-data` package automatically includes the `@ember-data/model`
+> package and configures it for you.

package/addon/-private.js

@@ -1 +1 @@
-export { f as AdapterPopulatedRecordArray, C as CacheHandler, j as IDENTIFIER_ARRAY_TAG, I as IdentifierArray, M as MUTATE, I as RecordArray, R as RecordArrayManager, h as SOURCE, S as Store, _ as _clearCaches, e as coerceId, k as fastPush, i as isStableIdentifier, n as normalizeModelName, g as notifyArray, p as peekCache, r as recordIdentifierFor, l as removeRecordDataFor, c as setIdentifierForgetMethod, a as setIdentifierGenerationMethod, d as setIdentifierResetMethod, b as setIdentifierUpdateMethod, s as storeFor } from "./index-0d52354f";
+export { f as AdapterPopulatedRecordArray, C as CacheHandler, j as IDENTIFIER_ARRAY_TAG, I as IdentifierArray, M as MUTATE, I as RecordArray, R as RecordArrayManager, h as SOURCE, S as Store, _ as _clearCaches, e as coerceId, k as fastPush, i as isStableIdentifier, n as normalizeModelName, g as notifyArray, p as peekCache, r as recordIdentifierFor, l as removeRecordDataFor, c as setIdentifierForgetMethod, a as setIdentifierGenerationMethod, d as setIdentifierResetMethod, b as setIdentifierUpdateMethod, s as storeFor } from "./index-44832181";

package/addon/{index-0d52354f.js → index-44832181.js}

@@ -907,16 +907,12 @@ function unsubscribe(token) {
   }
 }
 
-/*
-  Currently only support a single callback per identifier
-*/
-
 /**
  * The NotificationManager provides the ability to subscribe to
  * changes to Cache state.
  *
  * This Feature is what allows EmberData to create subscriptions that
- * work with any framework or change notification system.
+ * work with any framework or change-notification system.
  *
  * @class NotificationManager
  * @public
@@ -930,20 +926,30 @@ class NotificationManager {
   }
 
   /**
-   * Subscribe to changes for a given resource identifier
+   * Subscribe to changes for a given resource identifier, resource addition/removal, or document addition/removal.
    *
    * ```ts
-   * interface NotificationCallback {
+   * export type CacheOperation = 'added' | 'removed' | 'updated' | 'state';
+   *
+   * export interface NotificationCallback {
    *   (identifier: StableRecordIdentifier, notificationType: 'attributes' | 'relationships', key?: string): void;
    *   (identifier: StableRecordIdentifier, notificationType: 'errors' | 'meta' | 'identity' | 'state'): void;
    *   (identifier: StableRecordIdentifier, notificationType: NotificationType, key?: string): void;
    * }
+   * export interface ResourceOperationCallback {
+   *   // resource updates
+   *   (identifier: StableRecordIdentifier, notificationType: CacheOperation): void;
+   * }
+   * export interface DocumentOperationCallback {
+   *   // document updates
+   *   (identifier: StableDocumentIdentifier, notificationType: CacheOperation): void;
+   * }
    * ```
    *
    * @method subscribe
    * @public
-   * @param {StableRecordIdentifier} identifier
-   * @param {NotificationCallback} callback
+   * @param {StableDocumentIdentifier | StableRecordIdentifier | 'resource' | 'document'} identifier
+   * @param {NotificationCallback | ResourceOperationCallback | DocumentOperationCallback} callback
    * @returns {UnsubscribeToken} an opaque token to be used with unsubscribe
    */
 
@@ -1397,7 +1403,6 @@ class NonSingletonCacheManager {
   }
   // Cache Management
   // ================
-
   /**
    * Cache the response to a request
    *
@@ -3498,7 +3503,6 @@ var _dec, _class$1, _descriptor$1;
   @extends Ember.ArrayProxy
   @uses Ember.PromiseProxyMixin
 */
-
 let PromiseArray = (_dec = reads('content.meta'), (_class$1 = class PromiseArray extends PromiseArrayProxy {
   constructor(...args) {
     super(...args);
@@ -3638,6 +3642,10 @@ function convertToInt(prop) {
   return num % 1 === 0 ? num : null;
 }
 let Tag = (_class = class Tag {
+  /*
+   * whether this was part of a transaction when last mutated
+   */
+
   constructor() {
     _initializerDefineProperty(this, "ref", _descriptor, this);
     this.shouldReset = false;
@@ -3712,6 +3720,22 @@ let IdentifierArray = (_class3 = class IdentifierArray {
   [NOTIFY]() {
     notifyArray(this);
   }
+
+  /**
+   The modelClass represented by this record array.
+    @property type
+    @public
+    @deprecated
+   @type {subclass of Model}
+   */
+
+  /**
+    The store that created this record array.
+     @property store
+    @private
+    @type Store
+    */
+
   destroy() {
     this.isDestroying = true;
     // changing the reference breaks the Proxy
@@ -4710,12 +4734,23 @@ function sync(array, changes) {
   }
 }
 
+/**
+ * @module @ember-data/store
+ */
 const Touching = Symbol('touching');
 const RequestPromise = Symbol('promise');
 function hasRecordIdentifier(op) {
   return 'recordIdentifier' in op;
 }
-class RequestCache {
+
+/**
+ * The RequestStateService is used to track the state of requests
+ * for fetching or updating known resource identifies that are inflight.
+ *
+ * @class RequestStateService
+ * @public
+ */
+class RequestStateService {
   constructor(store) {
     this._pending = Object.create(null);
     this._done = new Map();
@@ -4727,7 +4762,7 @@ class RequestCache {
   _clearEntries(identifier) {
     this._done.delete(identifier);
   }
-  enqueue(promise, queryRequest) {
+  _enqueue(promise, queryRequest) {
     let query = queryRequest.data[0];
     if (hasRecordIdentifier(query)) {
       let lid = query.recordIdentifier.lid;
@@ -4826,18 +4861,66 @@ class RequestCache {
       this._done.set(identifier, requests);
     });
   }
+
+  /**
+   * Subscribe to requests for a given resource identity.
+   *
+   * The callback will receive the current state of the request.
+   *
+   * ```ts
+   * interface RequestState {
+   *   state: 'pending' | 'fulfilled' | 'rejected';
+   *   type: 'query' | 'mutation';
+   *   request: Request;
+   *   response?: { data: unknown };
+   * }
+   * ```
+   *
+   * Note: It should be considered dangerous to use this API for more than simple
+   * state derivation or debugging. The `request` and `response` properties are poorly
+   * spec'd and may change unexpectedly when shifting what Handlers are in use or how
+   * requests are issued from the Store.
+   *
+   * We expect to revisit this API in the near future as we continue to refine the
+   * RequestManager ergonomics, as a simpler but more powerful direct integration
+   * with the RequestManager for these purposes is likely to be a better long-term
+   * design.
+   *
+   * @method subscribeForRecord
+   * @public
+   * @param {StableRecordIdentifier} identifier
+   * @param {(state: RequestState) => void} callback
+   */
   subscribeForRecord(identifier, callback) {
     if (!this._subscriptions[identifier.lid]) {
       this._subscriptions[identifier.lid] = [];
     }
     this._subscriptions[identifier.lid].push(callback);
   }
+
+  /**
+   * Retrieve all active requests for a given resource identity.
+   *
+   * @method getPendingRequestsForRecord
+   * @public
+   * @param {StableRecordIdentifier} identifier
+   * @returns {RequestState[]} an array of request states for any pending requests for the given identifier
+   */
   getPendingRequestsForRecord(identifier) {
     if (this._pending[identifier.lid]) {
       return this._pending[identifier.lid];
     }
     return [];
   }
+
+  /**
+   * Retrieve the last completed request for a given resource identity.
+   *
+   * @method getLastRequestForRecord
+   * @public
+   * @param {StableRecordIdentifier} identifier
+   * @returns {RequestState | null} the state of the most recent request for the given identifier
+   */
   getLastRequestForRecord(identifier) {
     let requests = this._done.get(identifier);
     if (requests) {
@@ -4854,6 +4937,27 @@ class RequestCache {
 // hello world
 
 let _Cache;
+
+/**
+ * A Store coordinates interaction between your application, a [Cache](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Cache),
+ * and sources of data (such as your API or a local persistence layer)
+ * accessed via a [RequestManager](https://github.com/emberjs/data/tree/main/packages/request).
+ *
+ * ```app/services/store.js
+ * import Store from '@ember-data/store';
+ *
+ * export default class extends Store {}
+ * ```
+ *
+ * Most Ember applications will only have a single `Store` configured as a Service
+ * in this manner. However, setting up multiple stores is possible, including using
+ * each as a unique service.
+ *
+
+  @class Store
+  @public
+*/
+
 class Store {
   /**
    * Provides access to the NotificationManager associated
@@ -4879,6 +4983,80 @@ class Store {
   get schema() {
     return this.getSchemaDefinitionService();
   }
+
+  /**
+   * Provides access to the IdentifierCache instance
+   * for this store.
+   *
+   * The IdentifierCache can be used to generate or
+   * retrieve a stable unique identifier for any resource.
+   *
+   * @property {IdentifierCache} identifierCache
+   * @public
+   */
+
+  /**
+   * Provides access to the requestManager instance associated
+   * with this Store instance.
+   *
+   * When using `ember-data` this property is automatically
+   * set to an instance of `RequestManager`. When not using `ember-data`
+   * you must configure this property yourself, either by declaring
+   * it as a service or by initializing it.
+   *
+   * ```ts
+   * import Store, { CacheHandler } from '@ember-data/store';
+   * import RequestManager from '@ember-data/request';
+   * import Fetch from '@ember/data/request/fetch';
+   *
+   * class extends Store {
+   *   constructor() {
+   *     super(...arguments);
+   *     this.requestManager = new RequestManager();
+   *     this.requestManager.use([Fetch]);
+   *     this.requestManager.useCache(CacheHandler);
+   *   }
+   * }
+   * ```
+   *
+   * @public
+   * @property {RequestManager} requestManager
+   */
+
+  /**
+   * A Property which an App may set to provide a Lifetimes Service
+   * to control when a cached request becomes stale.
+   *
+   * Note, when defined, these methods will only be invoked if a
+   * cache key exists for the request, either because the request
+   * contains `cacheOptions.key` or because the [IdentifierCache](/ember-data/release/classes/IdentifierCache)
+   * was able to generate a key for the request using the configured
+   * [generation method](/ember-data/release/functions/@ember-data%2Fstore/setIdentifierGenerationMethod).
+   *
+   * `isSoftExpired` will only be invoked if `isHardExpired` returns `false`.
+   *
+   * ```ts
+   * store.lifetimes = {
+   *   // make the request and ignore the current cache state
+   *   isHardExpired(identifier: StableDocumentIdentifier): boolean {
+   *     return false;
+   *   }
+   *
+   *   // make the request in the background if true, return cache state
+   *   isSoftExpired(identifier: StableDocumentIdentifier): boolean {
+   *     return false;
+   *   }
+   * }
+   * ```
+   *
+   * @public
+   * @property {LivetimesService|undefined} lifetimes
+   */
+
+  // Private
+
+  // DEBUG-only properties
+
   /**
     @method init
     @private
@@ -4896,7 +5074,7 @@ class Store {
     });
 
     // private
-    this._requestCache = new RequestCache(this);
+    this._requestCache = new RequestStateService(this);
     this._instanceCache = new InstanceCache(this);
     this._adapterCache = Object.create(null);
     this._serializerCache = Object.create(null);