@warp-drive/legacy 5.9.0-beta.0 → 5.9.0-beta.2

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

@@ -1,174 +0,0 @@
-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/declarations/model/-private/debug/assert-polymorphic-type.d.ts

@@ -1,5 +0,0 @@
-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/declarations/model/-private/errors.d.ts

@@ -1,289 +0,0 @@
-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/declarations/model/-private/has-many.d.ts

@@ -1,162 +0,0 @@
-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/declarations/model/-private/hooks.d.ts

@@ -1,10 +0,0 @@
-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/declarations/model/-private/legacy-relationships-support.d.ts

@@ -1,47 +0,0 @@
-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/declarations/model/-private/model-for-mixin.d.ts

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