@warp-drive/legacy 5.8.0-alpha.30 → 5.8.0-alpha.32

package/dist/unpkg/prod/declarations/model/-private/references/has-many.d.ts

@@ -0,0 +1,500 @@
+import type { Store } from "@warp-drive/core";
+import type { CollectionEdge, Graph } from "@warp-drive/core/graph/-private";
+import type { RelatedCollection as ManyArray } from "@warp-drive/core/store/-private";
+import type { BaseFinderOptions } from "@warp-drive/core/types";
+import type { ResourceKey } from "@warp-drive/core/types/identifier";
+import type { TypeFromInstanceOrString } from "@warp-drive/core/types/record";
+import type { CollectionResourceDocument, CollectionResourceRelationship, ExistingResourceObject, LinkObject, Meta, PaginationLinks } from "@warp-drive/core/types/spec/json-api-raw";
+import type { IsUnknown } from "../belongs-to.js";
+import type { MaybeHasManyFields } from "../type-utils.js";
+interface ResourceIdentifier {
+	links?: {
+		related?: string | LinkObject;
+	};
+	meta?: Meta;
+}
+type ArrayItemType<T> = T extends (infer U)[] ? U : never;
+/**
+A `HasManyReference` is a low-level API that allows access
+and manipulation of a hasMany 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.
+
+@class HasManyReference
+@public
+*/
+export default class HasManyReference<
+	T = unknown,
+	K extends string = IsUnknown<T> extends true ? string : MaybeHasManyFields<T>,
+	Related = K extends keyof T ? ArrayItemType<Awaited<T[K]>> : unknown
+> {
+	graph: Graph;
+	store: Store;
+	hasManyRelationship: CollectionEdge;
+	/**
+	* The field name on the parent record for this has-many relationship.
+	*
+	* @property key
+	* @type {String}
+	* @public
+	*/
+	key: K;
+	/**
+	* The type of resource this relationship will contain.
+	*
+	* @property type
+	* @type {String}
+	* @public
+	*/
+	type: TypeFromInstanceOrString<Related>;
+	___token: object;
+	___identifier: ResourceKey<TypeFromInstanceOrString<T>>;
+	___relatedTokenMap: Map<ResourceKey, object>;
+	_ref: number;
+	constructor(store: Store, graph: Graph, parentIdentifier: ResourceKey<TypeFromInstanceOrString<T>>, hasManyRelationship: CollectionEdge, key: K);
+	/**
+	* An array of identifiers for the records that this reference refers to.
+	*
+	* @property identifiers
+	* @type {ResourceKey[]}
+	* @public
+	*/
+	get identifiers(): ResourceKey<TypeFromInstanceOrString<Related>>[];
+	_resource(): CollectionResourceRelationship;
+	/**
+	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 {String} The name of the remote type. This should either be `link` or `ids`
+	*/
+	remoteType(): "link" | "ids";
+	/**
+	`ids()` returns an array of the record IDs in this relationship.
+	
+	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');
+	
+	commentsRef.ids(); // ['1']
+	```
+	
+	@public
+	@return {Array} The ids in this has-many relationship
+	*/
+	ids(): Array<string | null>;
+	/**
+	The link Ember Data 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 {String} The link Ember Data 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(): PaginationLinks | null;
+	/**
+	The meta data for the has-many relationship.
+	
+	Example
+	
+	```javascript
+	// models/blog.js
+	import { Model, hasMany } from '@warp-drive/legacy/model';
+	export default Model.extend({
+	users: hasMany('user', { async: true, inverse: null })
+	});
+	
+	let blog = store.push({
+	data: {
+	type: 'blog',
+	id: 1,
+	relationships: {
+	users: {
+	links: {
+	related: {
+	href: '/articles/1/authors'
+	},
+	},
+	meta: {
+	lastUpdated: 1458014400000
+	}
+	}
+	}
+	}
+	});
+	
+	let usersRef = blog.hasMany('user');
+	
+	usersRef.meta() // { lastUpdated: 1458014400000 }
+	```
+	
+	@public
+	@return {Object|null} The meta information for the belongs-to relationship.
+	*/
+	meta(): Meta | null;
+	/**
+	`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. An empty array will signify the canonical value should be
+	empty.
+	
+	Example model
+	
+	```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;
+	}
+	```
+	
+	Setup some initial state, note we haven't loaded the comments yet:
+	
+	```js
+	const post = store.push({
+	data: {
+	type: 'post',
+	id: '1',
+	relationships: {
+	comments: {
+	data: [{ type: 'comment', id: '1' }]
+	}
+	}
+	}
+	});
+	
+	const commentsRef = post.hasMany('comments');
+	commentsRef.ids(); // ['1']
+	```
+	
+	Update the state using `push`, note we can do this even without
+	having loaded these comments yet by providing resource identifiers.
+	
+	Both full resources and resource identifiers are supported.
+	
+	```js
+	await commentsRef.push({
+	data: [
+	{ type: 'comment', id: '2' },
+	{ type: 'comment', id: '3' },
+	]
+	});
+	
+	commentsRef.ids(); // ['2', '3']
+	```
+	
+	For convenience, you can also pass in an array of resources or resource identifiers
+	without wrapping them in the `data` property:
+	
+	```js
+	await commentsRef.push([
+	{ type: 'comment', id: '4' },
+	{ type: 'comment', id: '5' },
+	]);
+	
+	commentsRef.ids(); // ['4', '5']
+	```
+	
+	When using the `data` property, you may also include other resource data via included,
+	as well as provide new links and meta to the relationship.
+	
+	```js
+	await commentsRef.push({
+	links: {
+	related: '/posts/1/comments'
+	},
+	meta: {
+	total: 2
+	},
+	data: [
+	{ type: 'comment', id: '4' },
+	{ type: 'comment', id: '5' },
+	],
+	included: [
+	{ type: 'other-thing', id: '1', attributes: { foo: 'bar' },
+	]
+	});
+	```
+	
+	By default, the store will attempt to fetch any unloaded records before resolving
+	the returned promise with the ManyArray.
+	
+	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 records.
+	
+	@public
+	@param {Array|Object} doc a JSONAPI document object describing the new value of this relationship.
+	@param {Boolean} [skipFetch] if `true`, do not attempt to fetch unloaded records
+	@return {Promise<ManyArray | void>}
+	*/
+	push(doc: ExistingResourceObject[] | CollectionResourceDocument, skipFetch?: boolean): Promise<ManyArray<Related> | void>;
+	_isLoaded(): boolean;
+	/**
+	`value()` synchronously returns the current value of the has-many
+	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
+	
+	```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');
+	
+	post.comments.then(function(comments) {
+	commentsRef.value() === comments
+	})
+	```
+	
+	@public
+	@return {ManyArray}
+	*/
+	value(): ManyArray<Related> | null;
+	/**
+	Loads the relationship if it is not already loaded.  If the
+	relationship is already loaded this method does not trigger a new
+	load. This causes a request to the specified
+	relationship link or reloads all items currently in the relationship.
+	
+	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');
+	
+	commentsRef.load().then(function(comments) {
+	//...
+	});
+	```
+	
+	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
+	commentsRef.load({ adapterOptions: { isPrivate: true } })
+	.then(function(comments) {
+	//...
+	});
+	```
+	
+	```js [app/adapters/comment.js]
+	export default ApplicationAdapter.extend({
+	findMany(store, type, id, snapshots) {
+	// In the adapter you will have access to adapterOptions.
+	let adapterOptions = snapshots[0].adapterOptions;
+	}
+	});
+	```
+	
+	@public
+	@param {Object} options the options to pass in.
+	@return {Promise} a promise that resolves with the ManyArray in
+	this has-many relationship.
+	*/
+	load(options?: BaseFinderOptions): Promise<ManyArray<Related>>;
+	/**
+	Reloads this has-many relationship. This causes a request to the specified
+	relationship link or reloads all items currently in the relationship.
+	
+	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');
+	
+	commentsRef.reload().then(function(comments) {
+	//...
+	});
+	```
+	
+	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
+	commentsRef.reload({ adapterOptions: { isPrivate: true } })
+	```
+	
+	@public
+	@param {Object} options the options to pass in.
+	@return {Promise} a promise that resolves with the ManyArray in this has-many relationship.
+	*/
+	reload(options?: BaseFinderOptions): Promise<ManyArray<Related>>;
+}
+export declare function isMaybeResource(object: ExistingResourceObject | ResourceIdentifier): object is ExistingResourceObject;

package/dist/unpkg/prod/declarations/model/-private/schema-provider.d.ts

@@ -0,0 +1,56 @@
+import type { Store } from "@warp-drive/core";
+import type { SchemaService } from "@warp-drive/core/types";
+import type { ResourceKey } from "@warp-drive/core/types/identifier";
+import type { ObjectValue } from "@warp-drive/core/types/json/raw";
+import type { Derivation, HashFn, Transformation } from "@warp-drive/core/types/schema/concepts";
+import type { ArrayField, DerivedField, GenericField, HashField, LegacyField, ObjectField, ObjectSchema, ResourceSchema } from "@warp-drive/core/types/schema/fields";
+import type { ModelFactory, ModelStore } from "./model.js";
+type AttributesSchema = ReturnType<Exclude<SchemaService["attributesDefinitionFor"], undefined>>;
+type RelationshipsSchema = ReturnType<Exclude<SchemaService["relationshipsDefinitionFor"], undefined>>;
+export interface ModelSchemaProvider {
+	attributesDefinitionFor(resource: ResourceKey | {
+		type: string;
+	}): AttributesSchema;
+	relationshipsDefinitionFor(resource: ResourceKey | {
+		type: string;
+	}): RelationshipsSchema;
+	doesTypeExist(type: string): boolean;
+}
+export declare class ModelSchemaProvider implements SchemaService {
+	constructor(store: ModelStore);
+	resourceTypes(): Readonly<string[]>;
+	hasTrait(type: string): boolean;
+	resourceHasTrait(resource: ResourceKey | {
+		type: string;
+	}, trait: string): boolean;
+	transformation(field: GenericField | ObjectField | ArrayField | {
+		type: string;
+	}): Transformation;
+	derivation(field: DerivedField | {
+		type: string;
+	}): Derivation;
+	hashFn(field: HashField | {
+		type: string;
+	}): HashFn;
+	resource(resource: ResourceKey | {
+		type: string;
+	}): ResourceSchema | ObjectSchema;
+	registerResources(schemas: Array<ResourceSchema | ObjectSchema>): void;
+	registerResource(schema: ResourceSchema | ObjectSchema): void;
+	registerTransformation(transform: Transformation): void;
+	registerDerivation<
+		R,
+		T,
+		FM extends ObjectValue | null
+	>(derivation: Derivation<R, T, FM>): void;
+	registerHashFn(hashFn: HashFn): void;
+	fields(resource: ResourceKey | {
+		type: string;
+	}): Map<string, LegacyField>;
+	hasResource(resource: {
+		type: string;
+	}): boolean;
+}
+export declare function buildSchema(store: Store): SchemaService;
+export declare function getModelFactory(store: ModelStore, type: string): ModelFactory | null;
+export {};

package/dist/unpkg/prod/declarations/model/-private/type-utils.d.ts

@@ -0,0 +1,57 @@
+import type { RelatedCollection } from "@warp-drive/core/store/-private";
+import type { TypedRecordInstance } from "@warp-drive/core/types/record";
+import type { Type } from "@warp-drive/core/types/symbols";
+import type { Model } from "./model.js";
+import type { PromiseBelongsTo } from "./promise-belongs-to.js";
+import type { PromiseManyArray } from "./promise-many-array.js";
+type ExcludeNull<T> = Exclude<T, null> extends never ? T : Exclude<T, null>;
+type GetMappedKey<
+	M,
+	V
+> = { [K in keyof M]-? : ExcludeNull<M[K]> extends V ? K : never }[keyof M] & string;
+/**
+* Get the keys of fields that are maybe defined as `belongsTo` relationships
+*
+* "Maybe" because getter/computed fields might be returning values that look
+* like relationships, but are not.
+*
+*/
+export type MaybeBelongsToFields<ThisType> = _TrueKeys<ThisType> extends never ? string : _MaybeBelongsToFields<ThisType>;
+export type _MaybeBelongsToFields<ThisType> = GetMappedKey<ThisType, PromiseBelongsTo | TypedRecordInstance>;
+/**
+* Get the keys of fields that are maybe defined as `hasMany` relationships
+*
+* "Maybe" because getter/computed fields might be returning values that look
+* like relationships, but are not.
+*
+*/
+export type MaybeHasManyFields<ThisType> = _TrueKeys<ThisType> extends never ? string : _MaybeHasManyFields<ThisType>;
+type _MaybeHasManyFields<ThisType> = GetMappedKey<ThisType, RelatedCollection | PromiseManyArray>;
+/**
+* Get the keys of fields that are maybe defined as `attr` fields
+*
+* "Maybe" because getter/computed fields might be returning values that look
+* like attributes, but are not.
+*
+* This is computed by excluding the keys that are defined as `belongsTo` or `hasMany`
+* as well as the keys on EmberObject and the Model base class
+*
+*/
+export type MaybeAttrFields<ThisType> = Exclude<_TrueKeys<ThisType>, _MaybeBelongsToFields<ThisType> | _MaybeHasManyFields<ThisType>>;
+/**
+* Get the keys of fields that are maybe defined as relationships
+*
+* "Maybe" because getter/computed fields might be returning values that look
+* like relationships, but are not.
+*
+*/
+export type MaybeRelationshipFields<ThisType> = _TrueKeys<ThisType> extends never ? string : _MaybeBelongsToFields<ThisType> | _MaybeHasManyFields<ThisType>;
+type _TrueKeys<ThisType> = Exclude<keyof ThisType & string, (keyof Model & string) | typeof Type>;
+export type isSubClass<ThisType> = _TrueKeys<ThisType> extends never ? false : true;
+/**
+* Get the keys of all fields defined on the given subclass of Model
+* that don't exist on EmberObject or Model.
+*
+*/
+export type SubclassKeys<ThisType> = _TrueKeys<ThisType> extends never ? string : _TrueKeys<ThisType>;
+export {};

package/dist/unpkg/prod/declarations/model/-private/util.d.ts

@@ -0,0 +1,5 @@
+export type DecoratorPropertyDescriptor = (PropertyDescriptor & {
+	initializer?: () => unknown;
+}) | undefined;
+export declare function isElementDescriptor(args: unknown[]): args is [object, string, DecoratorPropertyDescriptor];
+export declare function normalizeModelName(type: string): string;

package/dist/unpkg/prod/declarations/model/-private.d.ts

@@ -0,0 +1,8 @@
+export { type MinimalLegacyRecord } from "./-private/model-methods.js";
+export type { ModelStore } from "./-private/model.js";
+export { Errors } from "./-private/errors.js";
+export type { LegacyManyArray as ManyArray } from "@warp-drive/core/store/-private";
+export { PromiseBelongsTo } from "./-private/promise-belongs-to.js";
+export { PromiseManyArray } from "./-private/promise-many-array.js";
+export { lookupLegacySupport, LEGACY_SUPPORT } from "./-private/legacy-relationships-support.js";
+export type { MaybeHasManyFields, MaybeBelongsToFields, MaybeRelationshipFields } from "./-private/type-utils.js";