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

package/dist/unpkg/dev/declarations/model/-private/belongs-to.d.ts

@@ -0,0 +1,174 @@
+import type { TypeFromInstance } from "@warp-drive/core/types/record";
+export type IsUnknown<T> = unknown extends T ? true : false;
+export type RelationshipOptions<
+	T,
+	Async extends boolean
+> = {
+	async: Async;
+	inverse: null | (IsUnknown<T> extends true ? string : keyof NoNull<T> & string);
+	polymorphic?: boolean;
+	as?: string;
+	linksMode?: true;
+	resetOnRemoteUpdate?: boolean;
+};
+export type NoNull<T> = Exclude<T, null>;
+export type RelationshipDecorator<T> = <This>(target: This, key: string, desc?: PropertyDescriptor) => void;
+/**
+`belongsTo` is used to define One-To-One and One-To-Many, and One-To-None
+relationships on a {@link Model}.
+
+`belongsTo` takes a configuration hash as a second parameter, currently
+supported options are:
+
+- `async`: (*required*) A boolean value used to declare whether this is a sync (false) or async (true) relationship.
+- `inverse`: (*required*)  A string used to identify the inverse property on a related model, or `null`.
+- `polymorphic`: (*optional*) A boolean value to mark the relationship as polymorphic
+- `as`: (*optional*) A string used to declare the abstract type "this" record satisfies for polymorphism.
+
+### Examples
+
+To declare a **one-to-many** (or many-to-many) relationship, use
+`belongsTo` in combination with `hasMany`:
+
+```js
+// app/models/comment.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Comment extends Model {
+@belongsTo('post', { async: false, inverse: 'comments' }) post;
+}
+
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('comment', { async: false, inverse: 'post' }) comments;
+}
+```
+
+To declare a **one-to-one** relationship with managed inverses, use `belongsTo` for both sides:
+
+```js
+// app/models/author.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Author extends Model {
+@belongsTo('address', { async: true, inverse: 'owner' }) address;
+}
+
+// app/models/address.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Address extends Model {
+@belongsTo('author', { async: true, inverse: 'address' }) owner;
+}
+```
+
+To declare a **one-to-one** relationship without managed inverses, use `belongsTo` for both sides
+with `null` as the inverse:
+
+```js
+// app/models/author.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Author extends Model {
+@belongsTo('address', { async: true, inverse: null }) address;
+}
+
+// app/models/address.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Address extends Model {
+@belongsTo('author', { async: true, inverse: null }) owner;
+}
+```
+
+To declare a one-to-none relationship between two models, use
+`belongsTo` with inverse set to `null` on just one side::
+
+```js
+// app/models/person.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Person extends Model {
+@belongsTo('person', { async: false, inverse: null }) bestFriend;
+}
+```
+
+#### Sync vs Async Relationships
+
+WarpDrive fulfills relationships using resource data available in
+the cache.
+
+Sync relationships point directly to the known related resources.
+
+When a relationship is declared as async, if any of the known related
+resources have not been loaded, they will be fetched. The property
+on the record when accessed provides a promise that resolves once
+all resources are loaded.
+
+Async relationships may take advantage of links. On access, if the related
+link has not been loaded, or if any known resources are not available in
+the cache, the fresh state will be fetched using the link.
+
+In contrast to async relationship, accessing a sync relationship
+will error on access when any of the known related resources have
+not been loaded.
+
+If you are using `links` with sync relationships, you have to use
+the BelongsTo reference API to fetch or refresh related resources
+that aren't loaded. For instance, for a `bestFriend` relationship:
+
+```js
+person.belongsTo('bestFriend').reload();
+```
+
+#### Polymorphic Relationships
+
+To declare a polymorphic relationship, use `hasMany` with the `polymorphic`
+option set to `true`:
+
+```js
+// app/models/comment.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Comment extends Model {
+@belongsTo('commentable', { async: false, inverse: 'comments', polymorphic: true }) parent;
+}
+```
+
+`'commentable'` here is referred to as the "abstract type" for the polymorphic
+relationship.
+
+Polymorphic relationships with `inverse: null` will accept any type of record as their content.
+Polymorphic relationships with `inverse` set to a string will only accept records with a matching
+inverse relationships declaring itself as satisfying the abstract type.
+
+Below, 'as' is used to declare the that 'post' record satisfies the abstract type 'commentable'
+for this relationship.
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('comment', { async: false, inverse: 'parent', as: 'commentable' }) comments;
+}
+```
+
+Note: every Model that declares an inverse to a polymorphic relationship must
+declare itself exactly the same. This is because polymorphism is based on structural
+traits.
+
+Polymorphic to polymorphic relationships are supported. Both sides of the relationship
+must be declared as polymorphic, and the `as` option must be used to declare the abstract
+type each record satisfies on both sides.
+
+@public
+@param type the name of the related resource
+@param options a hash of options
+*/
+export declare function belongsTo(): never;
+export declare function belongsTo(type: string): never;
+export declare function belongsTo<T>(type: TypeFromInstance<NoNull<T>>, options: RelationshipOptions<T, boolean>): RelationshipDecorator<T>;
+export declare function belongsTo(type: string, options: RelationshipOptions<unknown, boolean>): RelationshipDecorator<unknown>;

package/dist/unpkg/dev/declarations/model/-private/debug/assert-polymorphic-type.d.ts

@@ -0,0 +1,5 @@
+import type { Store } from "@warp-drive/core";
+import type { UpgradedMeta } from "@warp-drive/core/graph/-private";
+import type { ResourceKey } from "@warp-drive/core/types/identifier";
+declare let assertPolymorphicType: (parentIdentifier: ResourceKey, parentDefinition: UpgradedMeta, addedIdentifier: ResourceKey, store: Store) => void;
+export { assertPolymorphicType };

package/dist/unpkg/dev/declarations/model/-private/errors.d.ts

@@ -0,0 +1,289 @@
+import { type NativeArray } from "@ember/array";
+import ArrayProxy from "@ember/array/proxy";
+import type RecordState from "./record-state.js";
+type ValidationError = {
+	attribute: string;
+	message: string;
+};
+interface ArrayProxyWithCustomOverrides<T> extends Omit<ArrayProxy<T>, "clear" | "content"> {
+	content: NativeArray<T>;
+	clear(): void;
+	_has(name: string): boolean;
+}
+declare const ArrayProxyWithCustomOverrides: new <T>() => ArrayProxyWithCustomOverrides<T>;
+/**
+Holds validation errors for a given record, organized by attribute names.
+
+This class is not directly instantiable.
+
+Every `Model` has an `errors` property that is an instance of
+`Errors`. This can be used to display validation error
+messages returned from the server when a `record.save()` rejects.
+
+For Example, if you had a `User` model that looked like this:
+
+```js [app/models/user.js]
+import { Model, attr } from '@warp-drive/legacy/model';
+
+export default class UserModel extends Model {
+@attr('string') username;
+@attr('string') email;
+}
+```
+And you attempted to save a record that did not validate on the backend:
+
+```javascript
+let user = store.createRecord('user', {
+username: 'tomster',
+email: 'invalidEmail'
+});
+user.save();
+```
+
+Your backend would be expected to return an error response that described
+the problem, so that error messages can be generated on the app.
+
+API responses will be translated into instances of `Errors` differently,
+depending on the specific combination of adapter and serializer used. You
+may want to check the documentation or the source code of the libraries
+that you are using, to know how they expect errors to be communicated.
+
+Errors can be displayed to the user by accessing their property name
+to get an array of all the error objects for that property. Each
+error object is a JavaScript object with two keys:
+
+- `message` A string containing the error message from the backend
+- `attribute` The name of the property associated with this error message
+
+```handlebars
+<label>Username: <Input @value={{@model.username}} /> </label>
+{{#each @model.errors.username as |error|}}
+<div class="error">
+{{error.message}}
+</div>
+{{/each}}
+
+<label>Email: <Input @value={{@model.email}} /> </label>
+{{#each @model.errors.email as |error|}}
+<div class="error">
+{{error.message}}
+</div>
+{{/each}}
+```
+
+You can also access the special `messages` property on the error
+object to get an array of all the error strings.
+
+```handlebars
+{{#each @model.errors.messages as |message|}}
+<div class="error">
+{{message}}
+</div>
+{{/each}}
+```
+
+@class Errors
+@public
+*/
+export declare class Errors extends ArrayProxyWithCustomOverrides<ValidationError> {
+	__record: {
+		currentState: RecordState;
+	};
+	/**
+	@property errorsByAttributeName
+	@type {MapWithDefault}
+	@private
+	*/
+	get errorsByAttributeName(): Map<string, NativeArray<ValidationError>>;
+	/**
+	Returns errors for a given attribute
+	
+	```javascript
+	let user = store.createRecord('user', {
+	username: 'tomster',
+	email: 'invalidEmail'
+	});
+	user.save().catch(function(){
+	user.errors.errorsFor('email'); // returns:
+	// [{attribute: "email", message: "Doesn't look like a valid email."}]
+	});
+	```
+	
+	@public
+	@param {String} attribute
+	@return {Array}
+	*/
+	errorsFor(attribute: string): NativeArray<ValidationError>;
+	/**
+	An array containing all of the error messages for this
+	record. This is useful for displaying all errors to the user.
+	
+	```handlebars
+	{{#each @model.errors.messages as |message|}}
+	<div class="error">
+	{{message}}
+	</div>
+	{{/each}}
+	```
+	
+	@property messages
+	@public
+	@type {Array}
+	*/
+	messages: string[];
+	/**
+	@property content
+	@type {Array}
+	@private
+	*/
+	get content(): NativeArray<ValidationError>;
+	/**
+	@private
+	*/
+	unknownProperty(attribute: string): NativeArray<ValidationError> | undefined;
+	/**
+	Total number of errors.
+	
+	@property length
+	@type {Number}
+	@public
+	@readonly
+	*/
+	/**
+	`true` if we have no errors.
+	
+	@property isEmpty
+	@type {Boolean}
+	@public
+	@readonly
+	*/
+	isEmpty: boolean;
+	/**
+	Manually adds errors to the record. This will trigger the `becameInvalid` event/ lifecycle method on
+	the record and transition the record into an `invalid` state.
+	
+	Example
+	```javascript
+	let errors = user.errors;
+	
+	// add multiple errors
+	errors.add('password', [
+	'Must be at least 12 characters',
+	'Must contain at least one symbol',
+	'Cannot contain your name'
+	]);
+	
+	errors.errorsFor('password');
+	// =>
+	// [
+	//   { attribute: 'password', message: 'Must be at least 12 characters' },
+	//   { attribute: 'password', message: 'Must contain at least one symbol' },
+	//   { attribute: 'password', message: 'Cannot contain your name' },
+	// ]
+	
+	// add a single error
+	errors.add('username', 'This field is required');
+	
+	errors.errorsFor('username');
+	// =>
+	// [
+	//   { attribute: 'username', message: 'This field is required' },
+	// ]
+	```
+	@public
+	@param {String} attribute - the property name of an attribute or relationship
+	@param {string[]|string} messages - an error message or array of error messages for the attribute
+	*/
+	add(attribute: string, messages: string[] | string): void;
+	/**
+	@private
+	*/
+	_findOrCreateMessages(attribute: string, messages: string | string[]): ValidationError[];
+	/**
+	Manually removes all errors for a given member from the record.
+	This will transition the record into a `valid` state, and
+	triggers the `becameValid` event and lifecycle method.
+	
+	Example:
+	
+	```javascript
+	let errors = user.errors;
+	errors.add('phone', ['error-1', 'error-2']);
+	
+	errors.errorsFor('phone');
+	// =>
+	// [
+	//   { attribute: 'phone', message: 'error-1' },
+	//   { attribute: 'phone', message: 'error-2' },
+	// ]
+	
+	errors.remove('phone');
+	
+	errors.errorsFor('phone');
+	// => undefined
+	```
+	@public
+	@param {String} member - the property name of an attribute or relationship
+	*/
+	remove(attribute: string): void;
+	/**
+	Manually clears all errors for the record.
+	This will transition the record into a `valid` state, and
+	will trigger the `becameValid` event and lifecycle method.
+	
+	Example:
+	
+	```javascript
+	let errors = user.errors;
+	errors.add('username', ['error-a']);
+	errors.add('phone', ['error-1', 'error-2']);
+	
+	errors.errorsFor('username');
+	// =>
+	// [
+	//   { attribute: 'username', message: 'error-a' },
+	// ]
+	
+	errors.errorsFor('phone');
+	// =>
+	// [
+	//   { attribute: 'phone', message: 'error-1' },
+	//   { attribute: 'phone', message: 'error-2' },
+	// ]
+	
+	errors.clear();
+	
+	errors.errorsFor('username');
+	// => undefined
+	
+	errors.errorsFor('phone');
+	// => undefined
+	
+	errors.messages
+	// => []
+	```
+	@public
+	*/
+	clear(): void;
+	/**
+	Checks if there are error messages for the given attribute.
+	
+	```js [app/controllers/user/edit.js]
+	export default class UserEditController extends Controller {
+	@action
+	save(user) {
+	if (user.errors.has('email')) {
+	return alert('Please update your email before attempting to save.');
+	}
+	user.save();
+	}
+	}
+	```
+	
+	@public
+	@param {String} attribute
+	@return {Boolean} true if there some errors on given attribute
+	*/
+	has(attribute: string): boolean;
+}
+export {};

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

@@ -0,0 +1,162 @@
+import type { TypeFromInstance } from "@warp-drive/core/types/record";
+import type { NoNull, RelationshipDecorator, RelationshipOptions } from "./belongs-to.js";
+/**
+`hasMany` is used to define Many-To-One and Many-To-Many, and Many-To-None
+relationships on a {@link Model}.
+
+`hasMany` takes a configuration hash as a second parameter, currently
+supported options are:
+
+- `async`: (*required*) A boolean value used to declare whether this is a sync (false) or async (true) relationship.
+- `inverse`: (*required*)  A string used to identify the inverse property on a related model, or `null`.
+- `polymorphic`: (*optional*) A boolean value to mark the relationship as polymorphic
+- `as`: (*optional*) A string used to declare the abstract type "this" record satisfies for polymorphism.
+
+### Examples
+
+To declare a **many-to-one** (or one-to-many) relationship, use
+`belongsTo` in combination with `hasMany`:
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('comment', { async: false, inverse: 'post' }) comments;
+}
+
+
+// app/models/comment.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Comment extends Model {
+@belongsTo('post', { async: false, inverse: 'comments' }) post;
+}
+```
+
+To declare a **many-to-many** relationship with managed inverses, use `hasMany` for both sides:
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('tag', { async: true, inverse: 'posts' }) tags;
+}
+
+// app/models/tag.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Tag extends Model {
+@hasMany('post', { async: true, inverse: 'tags' }) posts;
+}
+```
+
+To declare a **many-to-many** relationship without managed inverses, use `hasMany` for both sides
+with `null` as the inverse:
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('tag', { async: true, inverse: null }) tags;
+}
+
+// app/models/tag.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Tag extends Model {
+@hasMany('post', { async: true, inverse: null }) posts;
+}
+```
+
+To declare a many-to-none relationship between two models, use
+`hasMany` with inverse set to `null` on just one side::
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('category', { async: true, inverse: null }) categories;
+}
+```
+
+#### Sync vs Async Relationships
+
+WarpDrive fulfills relationships using resource data available in
+the cache.
+
+Sync relationships point directly to the known related resources.
+
+When a relationship is declared as async, if any of the known related
+resources have not been loaded, they will be fetched. The property
+on the record when accessed provides a promise that resolves once
+all resources are loaded.
+
+Async relationships may take advantage of links. On access, if the related
+link has not been loaded, or if any known resources are not available in
+the cache, the fresh state will be fetched using the link.
+
+In contrast to async relationship, accessing a sync relationship
+will error on access when any of the known related resources have
+not been loaded.
+
+If you are using `links` with sync relationships, you have to use
+the HasMany reference API to fetch or refresh related resources
+that aren't loaded. For instance, for a `comments` relationship:
+
+```js
+post.hasMany('comments').reload();
+```
+
+#### Polymorphic Relationships
+
+To declare a polymorphic relationship, use `hasMany` with the `polymorphic`
+option set to `true`:
+
+```js
+// app/models/comment.js
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class Comment extends Model {
+@belongsTo('commentable', { async: false, inverse: 'comments', polymorphic: true }) parent;
+}
+```
+
+`'commentable'` here is referred to as the "abstract type" for the polymorphic
+relationship.
+
+Polymorphic relationships with `inverse: null` will accept any type of record as their content.
+Polymorphic relationships with `inverse` set to a string will only accept records with a matching
+inverse relationships declaring itself as satisfying the abstract type.
+
+Below, 'as' is used to declare the that 'post' record satisfies the abstract type 'commentable'
+for this relationship.
+
+```js
+// app/models/post.js
+import { Model, hasMany } from '@warp-drive/legacy/model';
+
+export default class Post extends Model {
+@hasMany('comment', { async: false, inverse: 'parent', as: 'commentable' }) comments;
+}
+```
+
+Note: every Model that declares an inverse to a polymorphic relationship must
+declare itself exactly the same. This is because polymorphism is based on structural
+traits.
+
+Polymorphic to polymorphic relationships are supported. Both sides of the relationship
+must be declared as polymorphic, and the `as` option must be used to declare the abstract
+type each record satisfies on both sides.
+
+@public
+@param type the name of the related resource
+@param options a hash of options
+*/
+export declare function hasMany(): never;
+export declare function hasMany(type: string): never;
+export declare function hasMany<T>(type: TypeFromInstance<NoNull<T>>, options: RelationshipOptions<T, boolean>): RelationshipDecorator<T>;
+export declare function hasMany(type: string, options: RelationshipOptions<unknown, boolean>): RelationshipDecorator<unknown>;

package/dist/unpkg/dev/declarations/model/-private/hooks.d.ts

@@ -0,0 +1,10 @@
+import { type Store } from "@warp-drive/core/store/-private";
+import type { ResourceKey } from "@warp-drive/core/types/identifier";
+import type { TypeFromInstance } from "@warp-drive/core/types/record";
+import type { Model } from "./model.js";
+export declare function instantiateRecord(this: Store, identifier: ResourceKey, createRecordArgs?: {
+	[key: string]: unknown;
+}): Model;
+export declare function teardownRecord(record: Model): void;
+export declare function modelFor<T>(type: TypeFromInstance<T>): typeof Model | void;
+export declare function modelFor(type: string): typeof Model | void;

package/dist/unpkg/dev/declarations/model/-private/legacy-relationships-support.d.ts

@@ -0,0 +1,47 @@
+import type { Store } from "@warp-drive/core";
+import type { CollectionEdge, ResourceEdge, UpgradedMeta } from "@warp-drive/core/graph/-private";
+import type { LegacyManyArray } from "@warp-drive/core/store/-private";
+import type { BaseFinderOptions, ResourceKey } from "@warp-drive/core/types";
+import type { CollectionRelationship } from "@warp-drive/core/types/cache/relationship";
+import type { LocalRelationshipOperation } from "@warp-drive/core/types/graph";
+import type { OpaqueRecordInstance, TypeFromInstanceOrString } from "@warp-drive/core/types/record";
+import type { CollectionResourceRelationship, InnerRelationshipDocument, SingleResourceRelationship } from "@warp-drive/core/types/spec/json-api-raw";
+import type { MinimalLegacyRecord } from "./model-methods.js";
+import type { BelongsToProxyCreateArgs } from "./promise-belongs-to.js";
+import { PromiseBelongsTo } from "./promise-belongs-to.js";
+import type { HasManyProxyCreateArgs } from "./promise-many-array.js";
+import { PromiseManyArray } from "./promise-many-array.js";
+import BelongsToReference from "./references/belongs-to.js";
+import HasManyReference from "./references/has-many.js";
+export declare const LEGACY_SUPPORT: Map<ResourceKey | MinimalLegacyRecord, LegacySupport>;
+export declare function lookupLegacySupport(record: MinimalLegacyRecord): LegacySupport;
+/**
+* @hideconstructor
+*/
+export declare class LegacySupport {
+	identifier: ResourceKey;
+	constructor(record: MinimalLegacyRecord, identifier: ResourceKey);
+	/** @private */
+	_syncArray(array: LegacyManyArray): void;
+	mutate(mutation: LocalRelationshipOperation): void;
+	_findBelongsTo(key: string, resource: SingleResourceRelationship, relationship: ResourceEdge, options?: BaseFinderOptions): Promise<OpaqueRecordInstance | null>;
+	reloadBelongsTo(key: string, options?: BaseFinderOptions): Promise<OpaqueRecordInstance | null>;
+	getBelongsTo(key: string, options?: BaseFinderOptions): PromiseBelongsTo | OpaqueRecordInstance | null;
+	setDirtyBelongsTo(key: string, value: OpaqueRecordInstance | null): void;
+	_getCurrentState<T>(identifier: ResourceKey, field: string): [ResourceKey<TypeFromInstanceOrString<T>>[], CollectionRelationship];
+	getManyArray<T>(key: string, definition?: UpgradedMeta): LegacyManyArray<T>;
+	fetchAsyncHasMany(key: string, relationship: CollectionEdge, manyArray: LegacyManyArray, options?: BaseFinderOptions): Promise<LegacyManyArray>;
+	reloadHasMany<T>(key: string, options?: BaseFinderOptions): Promise<LegacyManyArray<T>> | PromiseManyArray<T>;
+	getHasMany(key: string, options?: BaseFinderOptions): PromiseManyArray | LegacyManyArray;
+	_updatePromiseProxyFor(kind: "hasMany", key: string, args: HasManyProxyCreateArgs): PromiseManyArray;
+	_updatePromiseProxyFor(kind: "belongsTo", key: string, args: BelongsToProxyCreateArgs): PromiseBelongsTo;
+	_updatePromiseProxyFor(kind: "belongsTo", key: string, args: {
+		promise: Promise<OpaqueRecordInstance | null>;
+	}): PromiseBelongsTo;
+	referenceFor(kind: "belongsTo", key: string): BelongsToReference;
+	referenceFor(kind: "hasMany", key: string): HasManyReference;
+	_findHasManyByJsonApiResource(resource: CollectionResourceRelationship, parentIdentifier: ResourceKey, relationship: CollectionEdge, options?: BaseFinderOptions): Promise<void | unknown[]> | void;
+	_findBelongsToByJsonApiResource(resource: SingleResourceRelationship, parentIdentifier: ResourceKey, relationship: ResourceEdge, options?: BaseFinderOptions): Promise<ResourceKey | null>;
+	destroy(): void;
+}
+export declare function areAllInverseRecordsLoaded(store: Store, resource: InnerRelationshipDocument): boolean;

package/dist/unpkg/dev/declarations/model/-private/model-for-mixin.d.ts

@@ -0,0 +1,3 @@
+import type { Store } from "@warp-drive/core";
+import { type ModelFactory } from "./model.js";
+export default function modelForMixin(store: Store, normalizedModelName: string): ModelFactory | undefined;