API Docs for: 5.4.0-alpha.29+64fa97fc
Show:

<Interface> Adapter Class

⚠️ This is LEGACY documentation for a feature that is no longer encouraged to be used. If starting a new app or thinking of implementing a new adapter, consider writing a Handler instead to be used with the RequestManager

The following documentation describes the methods an adapter should implement with descriptions around when an application might expect these methods to be called.

Methods that are not required are marked as optional.

Methods

createRecord

(
  • store
  • schema
  • snapshot
)
Promise public

adapter.createRecord takes a request to create a resource of a given type and should return a Promise which fulfills with data for the newly created resource.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to createRecord, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data for the record.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

If the adapter rejects or throws an error the record will enter an error state and the attributes that had attempted to be saved will still be considered dirty.

InvalidErrors

When rejecting a createRecord request due to validation issues during save (typically a 422 status code), you may throw an InvalidError.

Throwing an InvalidError makes per-attribute errors available for records to use in the UI as needed. Records can also use this information to mark themselves as being in an invalid state. For more reading see the RecordData Errors RFC

let error = new Error(errorMessage);

// these two properties combined
// alert EmberData to this error being for
// invalid properties on the record during
// the request
error.isAdapterError = true;
error.code = 'InvalidError';

// A JSON:API formatted array of errors
// See https://jsonapi.org/format/#errors
error.errors = [];

throw error;

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • schema ModelSchema

    An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

  • snapshot Snapshot

Returns:

Promise:

a promise resolving with resource data to feed to the associated serializer

deleteRecord

(
  • store
  • schema
  • snapshot
)
public

adapter.deleteRecord takes a request to delete a resource of a given type and should return a Promise which resolves when that deletion is complete.

Usually the response will be empty, but you may include additional updates in the response. The response will be fed to the associated serializer's normalizeResponse method with the requestType set to deleteRecord, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

If the adapter rejects or errors the record will need to be saved again once the reason for the error is addressed in order to persist the deleted state.

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • schema ModelSchema

    An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

  • snapshot Snapshot

    A Snapshot containing the record's current data

Returns:

destroy [OPTIONAL]

() public

In some situations the adapter may need to perform cleanup when destroyed, that cleanup can be done in destroy.

If not implemented, the store does not inform the adapter of destruction.

findAll

(
  • store
  • schema
  • sinceToken
  • snapshotRecordArray
)
Promise public

adapter.findAll takes a request for resources of a given type and should return a Promise which fulfills with a collection of resource data matching that type.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to findAll, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing records for type. Existing records for the type will not be removed.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

adapter.findAll is called whenever store.findAll is asked to reload or backgroundReload. The records in the response are merged with the contents of the store. Existing records for the type will not be removed.

See also shouldReloadAll and shouldBackgroundReloadAll

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • schema ModelSchema

    An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

  • sinceToken Null

    This parameter is no longer used and will always be null.

  • snapshotRecordArray SnapshotRecordArray

    an object containing any passed in options, adapterOptions, and the ability to access a snapshot for each existing record of the type.

Returns:

Promise:

a promise resolving with resource data to feed to the associated serializer

findBelongsTo [OPTIONAL]

(
  • store
  • snapshot
  • relatedLink
  • relationship
)
Promise public

adapter.findBelongsTo takes a request to fetch a related resource located at a relatedLink and should return a Promise which fulfills with data for a single resource.

⚠️ This method is only called if the store previously received relationship information for a resource containing a related link.

If the cache does not have a link for the relationship then findRecord will be used if a type and id for the related resource is known.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to findBelongsTo, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • snapshot Snapshot

    A Snapshot containing the parent record's current data

  • relatedLink String

    The link at which the associated resource might be found

  • relationship RelationshipSchema

Returns:

Promise:

a promise resolving with resource data to feed to the associated serializer

findhasMany [OPTIONAL]

(
  • store
  • snapshot
  • relatedLink
  • relationship
)
Promise public

adapter.findHasMany takes a request to fetch a related resource collection located at a relatedLink and should return a Promise which fulfills with data for that collection.

⚠️ This method is only called if the store previously received relationship information for a resource containing a related link.

If the cache does not have a link for the relationship but the type and id of related resources are known then findRecord will be used for each individual related resource.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to findHasMany, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • snapshot Snapshot

    A Snapshot containing the parent record's current data

  • relatedLink String

    The link at which the associated resource collection might be found

  • relationship RelationshipSchema

Returns:

Promise:

a promise resolving with resource data to feed to the associated serializer

findMany [OPTIONAL]

(
  • store
  • schema
  • ids
  • snapshots
)
Promise public

⚠️ This Method is only called if coalesceFindRequests is true. The array passed to it is determined by the adapter's groupRecordsForFindMany method, and will be called once per group returned.

adapter.findMany takes a request to fetch a collection of resources and should return a Promise which fulfills with data for that collection.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to findMany, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

See also groupRecordsForFindMany and coalesceFindRequests

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • schema ModelSchema

    An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

  • ids Array

    An array of the ids of the resources to fetch

  • snapshots Array

    An array of snapshots of the available data for the resources to fetch

Returns:

Promise:

a promise resolving with resource data to feed to the associated serializer

findRecord

(
  • store
  • schema
  • id
  • snapshot
)
Promise public

adapter.findRecord takes a request for a resource of a given type and id combination and should return a Promise which fulfills with data for a single resource matching that type and id.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to findRecord, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data for the record.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

adapter.findRecord is called whenever the store needs to load, reload, or backgroundReload the resource data for a given type and id.

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • schema ModelSchema

    An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

  • id String
  • snapshot Snapshot

Returns:

Promise:

a promise resolving with resource data to feed to the associated serializer

generateIdForRecord [OPTIONAL]

(
  • store
  • type
  • properties
)
String public

This method provides the ability to generate an ID to assign to a new record whenever store.createRecord is called if no id was provided.

Alternatively you can pass an id into the call to store.createRecord directly.

let id = generateNewId(type);
let newRecord = store.createRecord(type, { id });

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • type String

    The type (or modelName) of record being created

  • properties Object

    the properties passed as the second arg to store.createRecord

Returns:

String:

a string ID that should be unique (no other models of type in the cache should have this id)

groupRecordsForFindMany [OPTIONAL]

(
  • store
  • snapshots
)
Array> public

⚠️ This Method is only called if coalesceFindRequests is true.

This method allows for you to split pending requests for records into multiple findMany requests. It receives an array of snapshots where each snapshot represents a unique record requested via store.findRecord during the most recent runloop that was not found in the cache or needs to be reloaded. It should return an array of groups.

A group is an array of snapshots meant to be fetched together by a single findMany request.

By default if this method is not implemented EmberData will call findMany once with all requested records as a single group when coalesceFindRequests is true.

See also findMany and coalesceFindRequests

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • snapshots Array

    An array of snapshots

Returns:

Array>:

An array of Snapshot arrays

query

(
  • store
  • schema
  • query
  • recordArray
  • options
)
Promise public

adapter.query takes a request for resources of a given type and should return a Promise which fulfills with a collection of resource data matching that type.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to query, which should return a JSON:API document.

As with findAll, the final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing records for type.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

adapter.query is called whenever store.query is called or a previous query result is asked to reload.

Existing records for the type will not be removed. The key difference is in the result returned by the store. For findAll the result is all known records of the type, while for query it will only be the records returned from adapter.query.

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • schema ModelSchema

    An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

  • query Object
  • recordArray Collection
  • options Object

Returns:

Promise:

a promise resolving with resource data to feed to the associated serializer

queryRecord

(
  • store
  • schema
  • query
  • options
)
Promise public

adapter.queryRecord takes a request for resource of a given type and should return a Promise which fulfills with data for a single resource matching that type.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to queryRecord, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data for the returned record.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • schema ModelSchema

    An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

  • query Object
  • options Object

Returns:

Promise:

a promise resolving with resource data to feed to the associated serializer

shouldBackgroundReloadAll [OPTIONAL]

(
  • store
  • snapshotArray
)
Boolean public

When store.findAll(<type>) is called and a reload is not initiated, the adapter is presented the opportunity to trigger a new non-blocking (background) request for records of that type

Users may explicitly declare that this background request should/should not occur by passing backgroundReload: true or backgroundReload: false as an option to the request respectively.

store.findAll('user', { backgroundReload: false })

The default behavior if this method is not implemented and the option is not specified is to perform a reload, the same as a return of true.

Parameters:

Returns:

Boolean:

true if the a new request for all records of the type in SnapshotRecordArray should be made in the background, false otherwise

shouldBackgroundReloadRecord [OPTIONAL]

(
  • store
  • snapshot
)
Boolean public

When a record is already available in the store and is requested again via store.findRecord, and the record does not need to be reloaded prior to return, this method provides the ability to specify whether a refresh of the data for the reload should be scheduled to occur in the background.

Users may explicitly declare a record should/should not be background reloaded by passing backgroundReload: true or backgroundReload: false as an option to the request respectively.

store.findRecord('user', '1', { backgroundReload: false })

If the backgroundReload option is not present, this method will be called to determine whether a backgroundReload should be performed.

The default behavior if this method is not implemented and the option was not specified is to background reload, the same as a return of true.

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • snapshot Snapshot

    A Snapshot containing the record's current data

Returns:

Boolean:

true if the record should be reloaded in the background, false otherwise

shouldReloadAll [OPTIONAL]

(
  • store
  • snapshotArray
)
Boolean public

When store.findAll(<type>) is called without a reload option, the adapter is presented the opportunity to trigger a new request for records of that type.

If reload is specified as an option in the request (true or false) this method will not be called.

store.findAll('user', { reload: false })

The default behavior if this method is not implemented and the option is not specified is to not reload, the same as a return of false.

Note: the Promise returned by store.findAll resolves to the same RecordArray instance returned by store.peekAll for that type, and will include all records in the store for the given type, including any previously existing records not returned by the reload request.

Parameters:

Returns:

Boolean:

true if the a new request for all records of the type in SnapshotRecordArray should be made immediately, false otherwise

shouldReloadRecord [OPTIONAL]

(
  • store
  • snapshot
)
Boolean public

When a record is already available in the store and is requested again via store.findRecord, and reload is not specified as an option in the request, this method is called to determine whether the record should be reloaded prior to returning the result.

If reload is specified as an option in the request (true or false) this method will not be called.

store.findRecord('user', '1', { reload: false })

The default behavior if this method is not implemented and the option is not specified is to not reload, the same as a return of false.

See also the documentation for shouldBackgroundReloadRecord which defaults to true.

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • snapshot Snapshot

    A Snapshot containing the record's current data

Returns:

Boolean:

true if the record should be reloaded immediately, false otherwise

updateRecord

(
  • store
  • schema
  • snapshot
)
public

adapter.updateRecord takes a request to update a resource of a given type and should return a Promise which fulfills with the updated data for the resource.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to updateRecord, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data for the record.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

If the adapter rejects or throws an error the record will enter an error state and the attributes that had attempted to be saved will still be considered dirty.

InvalidErrors

When rejecting a createRecord request due to validation issues during save (typically a 422 status code), you may throw an InvalidError.

Throwing an InvalidError makes per-attribute errors available for records to use in the UI as needed. Records can also use this information to mark themselves as being in an invalid state. For more reading see the RecordData Errors RFC

let error = new Error(errorMessage);

// these two properties combined
// alert EmberData to this error being for
// invalid properties on the record during
// the request
error.isAdapterError = true;
error.code = 'InvalidError';

// A JSON:API formatted array of errors
// See https://jsonapi.org/format/#errors
error.errors = [];

throw error;

Parameters:

  • store Store

    The store service that initiated the request being normalized

  • schema ModelSchema

    An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

  • snapshot Snapshot

Properties

coalesceFindRequests [OPTIONAL]

Boolean true if the requests to find individual records should be coalesced, false otherwise public

If your adapter implements findMany, setting this to true will cause findRecord requests triggered within the same runloop to be coalesced into one or more calls to adapter.findMany. The number of calls made and the records contained in each call can be tuned by your adapter's groupRecordsForHasMany method.

Implementing coalescing using this flag and the associated methods does not always offer the right level of correctness, timing control or granularity. If your application would be better suited coalescing across multiple types, coalescing for longer than a single runloop, or with a more custom request structure, coalescing within your application adapter may prove more effective.