@warp-drive/core 5.7.0-alpha.0 → 5.7.0-alpha.2

package/declarations/store/deprecated/store.d.ts

@@ -0,0 +1,788 @@
+import type { TypeFromInstance } from "../../types/record.js";
+import type { ResourceIdentifierObject } from "../../types/spec/json-api-raw.js";
+import type { CollectionRecordArray, LiveArray } from "../-private.js";
+import { Store } from "../-private/store-service.js";
+import type { FindAllOptions, FindRecordOptions, LegacyResourceQuery, ModelSchema, QueryOptions } from "./-private.js";
+import { RecordReference } from "./-private.js";
+/////////////// IMPORTANT ///////////////////
+///// Move Module Augmentation Into The /////
+///// Legacy Package Once Removed Here  /////
+/////////////////////////////////////////////
+declare module "../-private/store-service" {
+	interface Store {
+		/**
+		This method returns a record for a given identifier or type and id combination.
+		
+		The `findRecord` method will always resolve its promise with the same
+		object for a given identifier or type and `id`.
+		
+		The `findRecord` method will always return a **promise** that will be
+		resolved with the record.
+		
+		**Example 1**
+		
+		```js [app/routes/post.js]
+		export default class PostRoute extends Route {
+		model({ post_id }) {
+		return this.store.findRecord('post', post_id);
+		}
+		}
+		```
+		
+		**Example 2**
+		
+		`findRecord` can be called with a single identifier argument instead of the combination
+		of `type` (modelName) and `id` as separate arguments. You may recognize this combo as
+		the typical pairing from [JSON:API](https://jsonapi.org/format/#document-resource-object-identification)
+		
+		```js [app/routes/post.js]
+		export default class PostRoute extends Route {
+		model({ post_id: id }) {
+		return this.store.findRecord({ type: 'post', id });
+		}
+		}
+		```
+		
+		**Example 3**
+		
+		If you have previously received an lid via an Identifier for this record, and the record
+		has already been assigned an id, you can find the record again using just the lid.
+		
+		```js [app/routes/post.js]
+		store.findRecord({ lid });
+		```
+		
+		If the record is not yet available, the store will ask the adapter's `findRecord`
+		method to retrieve and supply the necessary data. If the record is already present
+		in the store, it depends on the reload behavior _when_ the returned promise
+		resolves.
+		
+		### Preloading
+		
+		You can optionally `preload` specific attributes and relationships that you know of
+		by passing them via the passed `options`.
+		
+		For example, if your Ember route looks like `/posts/1/comments/2` and your API route
+		for the comment also looks like `/posts/1/comments/2` if you want to fetch the comment
+		without also fetching the post you can pass in the post to the `findRecord` call:
+		
+		```js [app/routes/post-comments.js]
+		export default class PostRoute extends Route {
+		model({ post_id, comment_id: id }) {
+		return this.store.findRecord({ type: 'comment', id, { preload: { post: post_id }} });
+		}
+		}
+		```
+		
+		In your adapter you can then access this id without triggering a network request via the
+		snapshot:
+		
+		```js [app/adapters/application.js]
+		export default class Adapter {
+		
+		findRecord(store, schema, id, snapshot) {
+		let type = schema.modelName;
+		
+		if (type === 'comment')
+		let postId = snapshot.belongsTo('post', { id: true });
+		
+		return fetch(`./posts/${postId}/comments/${id}`)
+		.then(response => response.json())
+		}
+		}
+		
+		static create() {
+		return new this();
+		}
+		}
+		```
+		
+		This could also be achieved by supplying the post id to the adapter via the adapterOptions
+		property on the options hash.
+		
+		```js [app/routes/post-comments.js]
+		export default class PostRoute extends Route {
+		model({ post_id, comment_id: id }) {
+		return this.store.findRecord({ type: 'comment', id, { adapterOptions: { post: post_id }} });
+		}
+		}
+		```
+		
+		```js [app/adapters/application.js]
+		export default class Adapter {
+		findRecord(store, schema, id, snapshot) {
+		let type = schema.modelName;
+		
+		if (type === 'comment')
+		let postId = snapshot.adapterOptions.post;
+		
+		return fetch(`./posts/${postId}/comments/${id}`)
+		.then(response => response.json())
+		}
+		}
+		
+		static create() {
+		return new this();
+		}
+		}
+		```
+		
+		If you have access to the post model you can also pass the model itself to preload:
+		
+		```javascript
+		let post = await store.findRecord('post', '1');
+		let comment = await store.findRecord('comment', '2', { post: myPostModel });
+		```
+		
+		### Reloading
+		
+		The reload behavior is configured either via the passed `options` hash or
+		the result of the adapter's `shouldReloadRecord`.
+		
+		If `{ reload: true }` is passed or `adapter.shouldReloadRecord` evaluates
+		to `true`, then the returned promise resolves once the adapter returns
+		data, regardless if the requested record is already in the store:
+		
+		```js
+		store.push({
+		data: {
+		id: 1,
+		type: 'post',
+		revision: 1
+		}
+		});
+		
+		// adapter#findRecord resolves with
+		// [
+		//   {
+		//     id: 1,
+		//     type: 'post',
+		//     revision: 2
+		//   }
+		// ]
+		store.findRecord('post', '1', { reload: true }).then(function(post) {
+		post.revision; // 2
+		});
+		```
+		
+		If no reload is indicated via the above mentioned ways, then the promise
+		immediately resolves with the cached version in the store.
+		
+		### Background Reloading
+		
+		Optionally, if `adapter.shouldBackgroundReloadRecord` evaluates to `true`,
+		then a background reload is started, which updates the records' data, once
+		it is available:
+		
+		```js
+		// app/adapters/post.js
+		import ApplicationAdapter from "./application";
+		
+		export default class PostAdapter extends ApplicationAdapter {
+		shouldReloadRecord(store, snapshot) {
+		return false;
+		},
+		
+		shouldBackgroundReloadRecord(store, snapshot) {
+		return true;
+		}
+		});
+		
+		// ...
+		
+		store.push({
+		data: {
+		id: 1,
+		type: 'post',
+		revision: 1
+		}
+		});
+		
+		let blogPost = store.findRecord('post', '1').then(function(post) {
+		post.revision; // 1
+		});
+		
+		// later, once adapter#findRecord resolved with
+		// [
+		//   {
+		//     id: 1,
+		//     type: 'post',
+		//     revision: 2
+		//   }
+		// ]
+		
+		blogPost.revision; // 2
+		```
+		
+		If you would like to force or prevent background reloading, you can set a
+		boolean value for `backgroundReload` in the options object for
+		`findRecord`.
+		
+		```js [app/routes/post/edit.js]
+		export default class PostEditRoute extends Route {
+		model(params) {
+		return this.store.findRecord('post', params.post_id, { backgroundReload: false });
+		}
+		}
+		```
+		
+		If you pass an object on the `adapterOptions` property of the options
+		argument it will be passed to your adapter via the snapshot
+		
+		```js [app/routes/post/edit.js]
+		export default class PostEditRoute extends Route {
+		model(params) {
+		return this.store.findRecord('post', params.post_id, {
+		adapterOptions: { subscribe: false }
+		});
+		}
+		}
+		```
+		
+		```js [app/adapters/post.js]
+		import MyCustomAdapter from './custom-adapter';
+		
+		export default class PostAdapter extends MyCustomAdapter {
+		findRecord(store, type, id, snapshot) {
+		if (snapshot.adapterOptions.subscribe) {
+		// ...
+		}
+		// ...
+		}
+		}
+		```
+		
+		See [peekRecord](../methods/peekRecord?anchor=peekRecord) to get the cached version of a record.
+		
+		### Retrieving Related Model Records
+		
+		If you use an adapter such as Ember's default
+		[`JSONAPIAdapter`](/ember-data/release/classes/JSONAPIAdapter)
+		that supports the [JSON API specification](http://jsonapi.org/) and if your server
+		endpoint supports the use of an
+		['include' query parameter](http://jsonapi.org/format/#fetching-includes),
+		you can use `findRecord()` or `findAll()` to automatically retrieve additional records related to
+		the one you request by supplying an `include` parameter in the `options` object.
+		
+		For example, given a `post` model that has a `hasMany` relationship with a `comment`
+		model, when we retrieve a specific post we can have the server also return that post's
+		comments in the same request:
+		
+		```js [app/routes/post.js]
+		export default class PostRoute extends Route {
+		model(params) {
+		return this.store.findRecord('post', params.post_id, { include: ['comments'] });
+		}
+		}
+		```
+		
+		```js [app/adapters/application.js]
+		export default class Adapter {
+		findRecord(store, schema, id, snapshot) {
+		let type = schema.modelName;
+		
+		if (type === 'post')
+		let includes = snapshot.adapterOptions.include;
+		
+		return fetch(`./posts/${postId}?include=${includes}`)
+		.then(response => response.json())
+		}
+		}
+		
+		static create() {
+		return new this();
+		}
+		}
+		```
+		
+		In this case, the post's comments would then be available in your template as
+		`model.comments`.
+		
+		Multiple relationships can be requested using an `include` parameter consisting of a
+		list of relationship names, while nested relationships can be specified
+		using a dot-separated sequence of relationship names. So to request both the post's
+		comments and the authors of those comments the request would look like this:
+		
+		```js [app/routes/post.js]
+		export default class PostRoute extends Route {
+		model(params) {
+		return this.store.findRecord('post', params.post_id, { include: ['comments','comments.author'] });
+		}
+		}
+		```
+		
+		### Retrieving Specific Fields by Type
+		
+		If your server endpoint supports the use of a ['fields' query parameter](https://jsonapi.org/format/#fetching-sparse-fieldsets),
+		you can use pass those fields through to your server.  At this point in time, this requires a few manual steps on your part.
+		
+		1. Implement `buildQuery` in your adapter.
+		
+		```js [app/adapters/application.js]
+		buildQuery(snapshot) {
+		let query = super.buildQuery(...arguments);
+		
+		let { fields } = snapshot.adapterOptions;
+		
+		if (fields) {
+		query.fields = fields;
+		}
+		
+		return query;
+		}
+		```
+		
+		2. Then pass through the applicable fields to your `findRecord` request.
+		
+		Given a `post` model with attributes body, title, publishDate and meta, you can retrieve a filtered list of attributes.
+		
+		```js [app/routes/post.js]
+		export default class extends Route {
+		model(params) {
+		return this.store.findRecord('post', params.post_id, { adapterOptions: { fields: { post: 'body,title' } });
+		}
+		}
+		```
+		
+		Moreover, you can filter attributes on related models as well. If a `post` has a `belongsTo` relationship to a user,
+		just include the relationship key and attributes.
+		
+		```js [app/routes/post.js]
+		export default class extends Route {
+		model(params) {
+		return this.store.findRecord('post', params.post_id, { adapterOptions: { fields: { post: 'body,title', user: 'name,email' } });
+		}
+		}
+		```
+		
+		@public
+		@deprecated use {@link Store.request} instead
+		@until 6.0
+		@since 1.13.0
+		@param type - either a string representing the name of the resource or a ResourceIdentifier object containing both the type (a string) and the id (a string) for the record or an lid (a string) of an existing record
+		@param id - optional object with options for the request only if the first param is a ResourceIdentifier, else the string id of the record to be retrieved
+		@param options - if the first param is a string this will be the optional options for the request. See examples for available options.
+		*/
+		findRecord<T>(type: TypeFromInstance<T>, id: string | number, options?: FindRecordOptions<T>): Promise<T>;
+		/** @deprecated */
+		findRecord(type: string, id: string | number, options?: FindRecordOptions): Promise<unknown>;
+		/** @deprecated */
+		findRecord<T>(resource: ResourceIdentifierObject<TypeFromInstance<T>>, options?: FindRecordOptions<T>): Promise<T>;
+		/** @deprecated */
+		findRecord(resource: ResourceIdentifierObject, options?: FindRecordOptions): Promise<unknown>;
+		/**
+		`findAll` asks the adapter's `findAll` method to find the records for the
+		given type, and returns a promise which will resolve with all records of
+		this type present in the store, even if the adapter only returns a subset
+		of them.
+		
+		```js [app/routes/authors.js]
+		export default class AuthorsRoute extends Route {
+		model(params) {
+		return this.store.findAll('author');
+		}
+		}
+		```
+		
+		_When_ the returned promise resolves depends on the reload behavior,
+		configured via the passed `options` hash and the result of the adapter's
+		`shouldReloadAll` method.
+		
+		### Reloading
+		
+		If `{ reload: true }` is passed or `adapter.shouldReloadAll` evaluates to
+		`true`, then the returned promise resolves once the adapter returns data,
+		regardless if there are already records in the store:
+		
+		```js
+		store.push({
+		data: {
+		id: 'first',
+		type: 'author'
+		}
+		});
+		
+		// adapter#findAll resolves with
+		// [
+		//   {
+		//     id: 'second',
+		//     type: 'author'
+		//   }
+		// ]
+		store.findAll('author', { reload: true }).then(function(authors) {
+		authors.getEach('id'); // ['first', 'second']
+		});
+		```
+		
+		If no reload is indicated via the above mentioned ways, then the promise
+		immediately resolves with all the records currently loaded in the store.
+		
+		### Background Reloading
+		
+		Optionally, if `adapter.shouldBackgroundReloadAll` evaluates to `true`,
+		then a background reload is started. Once this resolves, the array with
+		which the promise resolves, is updated automatically so it contains all the
+		records in the store:
+		
+		```js [app/adapters/application.js]
+		import Adapter from '@ember-data/adapter';
+		
+		export default class ApplicationAdapter extends Adapter {
+		shouldReloadAll(store, snapshotsArray) {
+		return false;
+		},
+		
+		shouldBackgroundReloadAll(store, snapshotsArray) {
+		return true;
+		}
+		});
+		
+		// ...
+		
+		store.push({
+		data: {
+		id: 'first',
+		type: 'author'
+		}
+		});
+		
+		let allAuthors;
+		store.findAll('author').then(function(authors) {
+		authors.getEach('id'); // ['first']
+		
+		allAuthors = authors;
+		});
+		
+		// later, once adapter#findAll resolved with
+		// [
+		//   {
+		//     id: 'second',
+		//     type: 'author'
+		//   }
+		// ]
+		
+		allAuthors.getEach('id'); // ['first', 'second']
+		```
+		
+		If you would like to force or prevent background reloading, you can set a
+		boolean value for `backgroundReload` in the options object for
+		`findAll`.
+		
+		```js [app/routes/post/edit.js]
+		export default class PostEditRoute extends Route {
+		model() {
+		return this.store.findAll('post', { backgroundReload: false });
+		}
+		}
+		```
+		
+		If you pass an object on the `adapterOptions` property of the options
+		argument it will be passed to you adapter via the `snapshotRecordArray`
+		
+		```js [app/routes/posts.js]
+		export default class PostsRoute extends Route {
+		model(params) {
+		return this.store.findAll('post', {
+		adapterOptions: { subscribe: false }
+		});
+		}
+		}
+		```
+		
+		```js [app/adapters/post.js]
+		import MyCustomAdapter from './custom-adapter';
+		
+		export default class UserAdapter extends MyCustomAdapter {
+		findAll(store, type, sinceToken, snapshotRecordArray) {
+		if (snapshotRecordArray.adapterOptions.subscribe) {
+		// ...
+		}
+		// ...
+		}
+		}
+		```
+		
+		See [peekAll](../methods/peekAll?anchor=peekAll) to get an array of current records in the
+		store, without waiting until a reload is finished.
+		
+		### Retrieving Related Model Records
+		
+		If you use an adapter such as Ember's default
+		[`JSONAPIAdapter`](/ember-data/release/classes/JSONAPIAdapter)
+		that supports the [JSON API specification](http://jsonapi.org/) and if your server
+		endpoint supports the use of an
+		['include' query parameter](http://jsonapi.org/format/#fetching-includes),
+		you can use `findAll()` to automatically retrieve additional records related to
+		those requested by supplying an `include` parameter in the `options` object.
+		
+		For example, given a `post` model that has a `hasMany` relationship with a `comment`
+		model, when we retrieve all of the post records we can have the server also return
+		all of the posts' comments in the same request:
+		
+		```js [app/routes/posts.js]
+		export default class PostsRoute extends Route {
+		model() {
+		return this.store.findAll('post', { include: ['comments'] });
+		}
+		}
+		```
+		Multiple relationships can be requested using an `include` parameter consisting of a
+		list or relationship names, while nested relationships can be specified
+		using a dot-separated sequence of relationship names. So to request both the posts'
+		comments and the authors of those comments the request would look like this:
+		
+		```js [app/routes/posts.js]
+		export default class PostsRoute extends Route {
+		model() {
+		return this.store.findAll('post', { include: ['comments','comments.author'] });
+		}
+		}
+		```
+		
+		See [query](../methods/query?anchor=query) to only get a subset of records from the server.
+		
+		@public
+		@deprecated use {@link Store.request} instead
+		@until 6.0
+		@since 1.13.0
+		@param type the name of the resource
+		@param options
+		*/
+		findAll<T>(type: TypeFromInstance<T>, options?: FindAllOptions<T>): Promise<LiveArray<T>>;
+		/** @deprecated */
+		findAll(type: string, options?: FindAllOptions): Promise<LiveArray>;
+		/**
+		This method delegates a query to the adapter. This is the one place where
+		adapter-level semantics are exposed to the application.
+		
+		Each time this method is called a new request is made through the adapter.
+		
+		Exposing queries this way seems preferable to creating an abstract query
+		language for all server-side queries, and then require all adapters to
+		implement them.
+		
+		---
+		
+		If you do something like this:
+		
+		```javascript
+		store.query('person', { page: 1 });
+		```
+		
+		The request made to the server will look something like this:
+		
+		```
+		GET "/api/v1/person?page=1"
+		```
+		
+		---
+		
+		If you do something like this:
+		
+		```javascript
+		store.query('person', { ids: ['1', '2', '3'] });
+		```
+		
+		The request made to the server will look something like this:
+		
+		```
+		GET "/api/v1/person?ids%5B%5D=1&ids%5B%5D=2&ids%5B%5D=3"
+		decoded: "/api/v1/person?ids[]=1&ids[]=2&ids[]=3"
+		```
+		
+		This method returns a promise, which is resolved with a
+		[`Collection`](/ember-data/release/classes/Collection)
+		once the server returns.
+		
+		@public
+		@deprecated use {@link Store.request} instead
+		@until 6.0
+		@since 1.13.0
+		@param type the name of the resource
+		@param query a query to be used by the adapter
+		@param options optional, may include `adapterOptions` hash which will be passed to adapter.query
+		*/
+		query<T>(type: TypeFromInstance<T>, query: LegacyResourceQuery<T>, options?: QueryOptions): Promise<CollectionRecordArray<T>>;
+		/** @deprecated */
+		query(type: string, query: LegacyResourceQuery, options?: QueryOptions): Promise<CollectionRecordArray>;
+		/**
+		This method makes a request for one record, where the `id` is not known
+		beforehand (if the `id` is known, use [`findRecord`](../methods/findRecord?anchor=findRecord)
+		instead).
+		
+		This method can be used when it is certain that the server will return a
+		single object for the primary data.
+		
+		Each time this method is called a new request is made through the adapter.
+		
+		Let's assume our API provides an endpoint for the currently logged in user
+		via:
+		
+		```
+		// GET /api/current_user
+		{
+		user: {
+		id: 1234,
+		username: 'admin'
+		}
+		}
+		```
+		
+		Since the specific `id` of the `user` is not known beforehand, we can use
+		`queryRecord` to get the user:
+		
+		```javascript
+		store.queryRecord('user', {}).then(function(user) {
+		let username = user.username;
+		// do thing
+		});
+		```
+		
+		The request is made through the adapters' `queryRecord`:
+		
+		```js [app/adapters/user.js]
+		import Adapter from '@ember-data/adapter';
+		import $ from 'jquery';
+		
+		export default class UserAdapter extends Adapter {
+		queryRecord(modelName, query) {
+		return $.getJSON('/api/current_user');
+		}
+		}
+		```
+		
+		Note: the primary use case for `store.queryRecord` is when a single record
+		is queried and the `id` is not known beforehand. In all other cases
+		`store.query` and using the first item of the array is likely the preferred
+		way:
+		
+		```
+		// GET /users?username=unique
+		{
+		data: [{
+		id: 1234,
+		type: 'user',
+		attributes: {
+		username: "unique"
+		}
+		}]
+		}
+		```
+		
+		```javascript
+		store.query('user', { username: 'unique' }).then(function(users) {
+		return users.firstObject;
+		}).then(function(user) {
+		let id = user.id;
+		});
+		```
+		
+		This method returns a promise, which resolves with the found record.
+		
+		If the adapter returns no data for the primary data of the payload, then
+		`queryRecord` resolves with `null`:
+		
+		```
+		// GET /users?username=unique
+		{
+		data: null
+		}
+		```
+		
+		```javascript
+		store.queryRecord('user', { username: 'unique' }).then(function(user) {
+		// user is null
+		});
+		```
+		
+		@public
+		@deprecated use {@link Store.request} instead
+		@until 6.0
+		@since 1.13.0
+		@param type
+		@param query an opaque query to be used by the adapter
+		@param options optional, may include `adapterOptions` hash which will be passed to adapter.queryRecord
+		@return promise which resolves with the found record or `null`
+		*/
+		queryRecord<T>(type: TypeFromInstance<T>, query: LegacyResourceQuery<T>, options?: QueryOptions): Promise<T | null>;
+		/** @deprecated */
+		queryRecord(type: string, query: LegacyResourceQuery, options?: QueryOptions): Promise<unknown | null>;
+		/**
+		Get the reference for the specified record.
+		
+		Example
+		
+		```javascript
+		let userRef = store.getReference('user', '1');
+		
+		// check if the user is loaded
+		let isLoaded = userRef.value() !== null;
+		
+		// get the record of the reference (null if not yet available)
+		let user = userRef.value();
+		
+		// get the identifier of the reference
+		if (userRef.remoteType() === 'id') {
+		let id = userRef.id();
+		}
+		
+		// load user (via store.find)
+		userRef.load().then(...)
+		
+		// or trigger a reload
+		userRef.reload().then(...)
+		
+		// provide data for reference
+		userRef.push({ id: 1, username: '@user' }).then(function(user) {
+		userRef.value() === user;
+		});
+		```
+		
+		@public
+		@deprecated use {@link Store.request} for loading and {@link Store.cache} for direct data insertion instead
+		@until 6.0
+		@since 2.5.0
+		@param resource - modelName (string) or Identifier (object)
+		@param id
+		*/
+		getReference(resource: string | ResourceIdentifierObject, id: string | number): RecordReference;
+		/**
+		Returns the schema for a particular resource type (modelName).
+		
+		When used with Model from @ember-data/model the return is the model class,
+		but this is not guaranteed.
+		
+		If looking to query attribute or relationship information it is
+		recommended to use `getSchemaDefinitionService` instead. This method
+		should be considered legacy and exists primarily to continue to support
+		Adapter/Serializer APIs which expect it's return value in their method
+		signatures.
+		
+		The class of a model might be useful if you want to get a list of all the
+		relationship names of the model, see
+		[`relationshipNames`](/ember-data/release/classes/Model?anchor=relationshipNames)
+		for example.
+		
+		@public
+		@deprecated use {@link Store.schema} instead
+		@until 6.0
+		@param type
+		*/
+		modelFor<T>(type: TypeFromInstance<T>): ModelSchema<T>;
+		/** @deprecated */
+		modelFor(type: string): ModelSchema;
+		/**
+		* Trigger a save for a Record.
+		*
+		* Returns a promise resolving with the same record when the save is complete.
+		*
+		* @deprecated use {@link Store.request} instead
+		* @until 6.0
+		* @public
+		* @param record
+		* @param options
+		*/
+		saveRecord<T>(record: T, options?: Record<string, unknown>): Promise<T>;
+	}
+}
+export { Store };