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

package/declarations/model/-private/references/belongs-to.d.ts

@@ -1,488 +0,0 @@
-import type { Store } from "@warp-drive/core";
-import type { Graph, ResourceEdge } from "@warp-drive/core/graph/-private";
-import type { ResourceKey } from "@warp-drive/core/types/identifier";
-import type { TypeFromInstance, TypeFromInstanceOrString } from "@warp-drive/core/types/record";
-import type { Links, Meta, SingleResourceDocument, SingleResourceRelationship } from "@warp-drive/core/types/spec/json-api-raw";
-import type { IsUnknown } from "../belongs-to.js";
-import type { MaybeBelongsToFields } from "../type-utils.js";
-/**
-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 `@warp-drive/legacy/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 `@warp-drive/legacy/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.
-
-@public
-*/
-export default class BelongsToReference<
-	T = unknown,
-	K extends string = IsUnknown<T> extends true ? string : MaybeBelongsToFields<T>,
-	Related = K extends keyof T ? Exclude<Awaited<T[K]>, null> : unknown
-> {
-	graph: Graph;
-	store: Store;
-	belongsToRelationship: ResourceEdge;
-	/**
-	* The field name on the parent record for this has-many relationship.
-	*
-	*/
-	key: K;
-	/**
-	* The type of resource this relationship will contain.
-	*
-	*/
-	type: TypeFromInstanceOrString<Related>;
-	___token: object;
-	___identifier: ResourceKey<TypeFromInstanceOrString<T>>;
-	___relatedToken: object | null;
-	_ref: number;
-	constructor(store: Store, graph: Graph, parentIdentifier: ResourceKey<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.
-	*
-	*/
-	get identifier(): ResourceKey<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 '@warp-drive/legacy/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();
-	}
-	```
-	
-	@public
-	@return The id of the record in this belongsTo relationship.
-	*/
-	id(): string | null;
-	/**
-	The link WarpDrive 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 '@warp-drive/legacy/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();
-	}
-	```
-	
-	@public
-	@return The link WarpDrive will use to fetch or reload this belongs-to relationship.
-	*/
-	link(): string | null;
-	/**
-	* any links that have been received for this relationship
-	*
-	* @public
-	* @return
-	*/
-	links(): Links | null;
-	/**
-	The meta data for the belongs-to relationship.
-	
-	Example
-	
-	```javascript
-	// models/blog.js
-	import { Model, belongsTo } from '@warp-drive/legacy/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 }
-	```
-	
-	@public
-	@return The meta information for the belongs-to relationship.
-	*/
-	meta(): Meta | null;
-	_resource(): SingleResourceRelationship<ResourceKey<TypeFromInstance<Related>>>;
-	/**
-	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
-	
-	```js [app/models/post.js]
-	import Model, { hasMany } from '@warp-drive/legacy/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();
-	}
-	```
-	
-	@public
-	@return 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 WarpDrive
-	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
-	
-	```js [app/models/blog.js]
-	import { Model, belongsTo } from '@warp-drive/legacy/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.
-	
-	@public
-	@param doc a JSONAPI document object describing the new value of this relationship.
-	@param skipFetch [optional] if `true`, do not attempt to fetch unloaded records
-	@return a promise that resolves with the record in this belongs-to relationship after the push has completed.
-	*/
-	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 '@warp-drive/legacy/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
-	});
-	```
-	
-	@public
-	@return 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 '@warp-drive/legacy/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;
-	});
-	```
-	```js [app/adapters/user.js]
-	import Adapter from '@warp-drive/legacy/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;
-	}
-	});
-	```
-	
-	@public
-	@param options the options to pass in.
-	@return 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"` WarpDrive 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 '@warp-drive/legacy/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 } })
-	```
-	
-	@public
-	@param options the options to pass in.
-	@return 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>;
-}