@warp-drive/legacy 5.9.0-alpha.21 → 5.9.0-alpha.22

package/declarations/compat/legacy-network-handler/minimum-adapter-interface.d.ts

@@ -1,528 +0,0 @@
-import type { Store } from "@warp-drive/core";
-import type { LegacyQueryArray } from "@warp-drive/core/store/-private";
-import type { ModelSchema } from "@warp-drive/core/types";
-import type { LegacyRelationshipField as RelationshipSchema } from "@warp-drive/core/types/schema/fields";
-import type { Snapshot } from "./snapshot.js";
-import type { SnapshotRecordArray } from "./snapshot-record-array.js";
-type Group = Snapshot[];
-/**
-* The raw payload shape returned by a legacy adapter's request methods,
-* prior to being normalized by a {@link MinimumSerializerInterface}.
-*/
-export type AdapterPayload = Record<string, unknown> | unknown[];
-/**
-* :::danger
-⚠️ **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
-{@link Handler} instead to be used with the {@link 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**.
-
-@class (Interface) Adapter
-@public
-*/
-export interface MinimumAdapterInterface {
-	/**
-	* `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`.
-	*
-	* @public
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {ModelSchema} schema An object with methods for accessing information about
-	*  the type, attributes and relationships of the primary type associated with the request.
-	* @param {String} id
-	* @param {Snapshot} snapshot
-	* @return {Promise} a promise resolving with resource data to feed to the associated serializer
-	*/
-	findRecord(store: Store, schema: ModelSchema, id: string, snapshot: Snapshot): Promise<AdapterPayload>;
-	/**
-	* `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`
-	*
-	* @public
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {ModelSchema} schema An object with methods for accessing information about
-	*  the type, attributes and relationships of the primary type associated with the request.
-	* @param {null} sinceToken This parameter is no longer used and will always be null.
-	* @param {SnapshotRecordArray} snapshotRecordArray an object containing any passed in options,
-	*  adapterOptions, and the ability to access a snapshot for each existing record of the type.
-	* @return {Promise} a promise resolving with resource data to feed to the associated serializer
-	*/
-	findAll(store: Store, schema: ModelSchema, sinceToken: null, snapshotRecordArray: SnapshotRecordArray): Promise<AdapterPayload>;
-	/**
-	* `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`.
-	*
-	* @public
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {ModelSchema} schema An object with methods for accessing information about
-	*  the type, attributes and relationships of the primary type associated with the request.
-	* @param {Object} query
-	* @param {LegacyQueryArray} recordArray
-	* @param {Object} options
-	* @return {Promise} a promise resolving with resource data to feed to the associated serializer
-	*/
-	query(store: Store, schema: ModelSchema, query: Record<string, unknown>, recordArray: LegacyQueryArray, options: {
-		adapterOptions?: unknown;
-	}): Promise<AdapterPayload>;
-	/**
-	* `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.
-	*
-	* @public
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {ModelSchema} schema An object with methods for accessing information about
-	*  the type, attributes and relationships of the primary type associated with the request.
-	* @param query
-	* @param options
-	* @return {Promise} a promise resolving with resource data to feed to the associated serializer
-	*/
-	queryRecord(store: Store, schema: ModelSchema, query: Record<string, unknown>, options: {
-		adapterOptions?: unknown;
-	}): Promise<AdapterPayload>;
-	/**
-	* `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](https://emberjs.github.io/rfcs/0465-record-data-errors.html)
-	*
-	* ```js
-	* let error = new Error(errorMessage);
-	*
-	* // these two properties combined
-	* // alert WarpDrive 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;
-	* ```
-	*
-	* @public
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {ModelSchema} schema An object with methods for accessing information about
-	*  the type, attributes and relationships of the primary type associated with the request.
-	* @param {Snapshot} snapshot
-	* @return {Promise} a promise resolving with resource data to feed to the associated serializer
-	*/
-	createRecord(store: Store, schema: ModelSchema, snapshot: Snapshot): Promise<AdapterPayload>;
-	/**
-	* `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](https://emberjs.github.io/rfcs/0465-record-data-errors.html)
-	*
-	* ```js
-	* let error = new Error(errorMessage);
-	*
-	* // these two properties combined
-	* // alert WarpDrive 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;
-	* ```
-	*
-	* @public
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {ModelSchema} schema An object with methods for accessing information about
-	*  the type, attributes and relationships of the primary type associated with the request.
-	* @param {Snapshot} snapshot
-	*/
-	updateRecord(store: Store, schema: ModelSchema, snapshot: Snapshot): Promise<AdapterPayload>;
-	/**
-	* `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.
-	*
-	* @public
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {ModelSchema} schema An object with methods for accessing information about
-	*  the type, attributes and relationships of the primary type associated with the request.
-	* @param {Snapshot} snapshot A Snapshot containing the record's current data
-	* @return
-	*/
-	deleteRecord(store: Store, schema: ModelSchema, snapshot: Snapshot): Promise<AdapterPayload>;
-	/**
-	* `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](https://jsonapi.org/format/#document-resource-object-related-resource-links).
-	*
-	* 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.
-	*
-	* @public
-	* @optional
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {Snapshot} snapshot A Snapshot containing the parent record's current data
-	* @param {String} relatedLink The link at which the associated resource might be found
-	* @param {RelationshipSchema} relationship
-	* @return {Promise} a promise resolving with resource data to feed to the associated serializer
-	*/
-	findBelongsTo?(store: Store, snapshot: Snapshot, relatedLink: string, relationship: RelationshipSchema): Promise<AdapterPayload>;
-	/**
-	* `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](https://jsonapi.org/format/#document-resource-object-related-resource-links).
-	*
-	* 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.
-	*
-	* @public
-	* @optional
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {Snapshot} snapshot A Snapshot containing the parent record's current data
-	* @param {String} relatedLink The link at which the associated resource collection might be found
-	* @param {RelationshipSchema} relationship
-	* @return {Promise} a promise resolving with resource data to feed to the associated serializer
-	*/
-	findHasMany?(store: Store, snapshot: Snapshot, relatedLink: string, relationship: RelationshipSchema): Promise<AdapterPayload>;
-	/**
-	* ⚠️ 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`
-	*
-	* @public
-	* @optional
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {ModelSchema} schema An object with methods for accessing information about
-	*  the type, attributes and relationships of the primary type associated with the request.
-	* @param {Array<string>} ids An array of the ids of the resources to fetch
-	* @param {Array<Snapshot>} snapshots An array of snapshots of the available data for the resources to fetch
-	* @return {Promise} a promise resolving with resource data to feed to the associated serializer
-	*/
-	findMany?(store: Store, schema: ModelSchema, ids: string[], snapshots: Snapshot[]): Promise<AdapterPayload>;
-	/**
-	* 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.
-	*
-	* ```js
-	* let id = generateNewId(type);
-	* let newRecord = store.createRecord(type, { id });
-	* ```
-	*
-	* @public
-	* @optional
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {String} type The type (or modelName) of record being created
-	* @param properties the properties passed as the second arg to `store.createRecord`
-	* @return {String} a string ID that should be unique (no other models of `type` in the cache should have this `id`)
-	*/
-	generateIdForRecord?(store: Store, type: string, properties: unknown): string;
-	/**
-	* 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.
-	*
-	* @property coalesceFindRequests [OPTIONAL]
-	* @public
-	* @optional
-	* @type {Boolean} true if the requests to find individual records should be coalesced, false otherwise
-	*/
-	coalesceFindRequests?: boolean;
-	/**
-	* ⚠️ 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 WarpDrive will call `findMany` once with all
-	* requested records as a single group when `coalesceFindRequests` is `true`.
-	*
-	* See also `findMany` and `coalesceFindRequests`
-	*
-	* @public
-	* @optional
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {Array<Snapshot>} snapshots An array of snapshots
-	* @return {Array<Array<Snapshot>>} An array of Snapshot arrays
-	*/
-	groupRecordsForFindMany?(store: Store, snapshots: Snapshot[]): Group[];
-	/**
-	* 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.
-	*
-	* ```js
-	* 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`.
-	*
-	* @public
-	* @optional
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {Snapshot} snapshot A Snapshot containing the record's current data
-	* @return {Boolean} true if the record should be reloaded immediately, false otherwise
-	*/
-	shouldReloadRecord?(store: Store, snapshot: Snapshot): boolean;
-	/**
-	* 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.
-	*
-	* ```js
-	* 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 LiveArray 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.
-	*
-	* @public
-	* @optional
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {SnapshotRecordArray} snapshotArray
-	* @return {Boolean} true if the a new request for all records of the type in SnapshotRecordArray should be made immediately, false otherwise
-	*/
-	shouldReloadAll?(store: Store, snapshotArray: SnapshotRecordArray): boolean;
-	/**
-	* 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.
-	*
-	* ```js
-	* 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`.
-	*
-	* @public
-	* @optional
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {Snapshot} snapshot A Snapshot containing the record's current data
-	* @return {Boolean} true if the record should be reloaded in the background, false otherwise
-	*/
-	shouldBackgroundReloadRecord?(store: Store, snapshot: Snapshot): boolean;
-	/**
-	* 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.
-	*
-	* ```js
-	* 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`.
-	*
-	* @public
-	* @optional
-	* @param {Store} store The store service that initiated the request being normalized
-	* @param {SnapshotRecordArray} snapshotArray
-	* @return {Boolean} true if the a new request for all records of the type in SnapshotRecordArray should be made in the background, false otherwise
-	*/
-	shouldBackgroundReloadAll?(store: Store, snapshotArray: SnapshotRecordArray): boolean;
-	/**
-	* 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.
-	*
-	* @public
-	* @optional
-	*/
-	destroy?(): void;
-}
-export {};