@warp-drive/core 5.6.0-alpha.5 → 5.6.0-beta.1

package/declarations/store/-private/record-arrays/identifier-array.d.ts

@@ -0,0 +1,147 @@
+import type { BaseFinderOptions } from "../../../types.js";
+import type { LocalRelationshipOperation } from "../../../types/graph.js";
+import type { StableDocumentIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
+import type { TypeFromInstanceOrString } from "../../../types/record.js";
+import type { ImmutableRequestInfo } from "../../../types/request.js";
+import type { LegacyHasManyField, LinksModeHasManyField } from "../../../types/schema/fields.js";
+import type { Links, PaginationLinks } from "../../../types/spec/json-api-raw.js";
+import type { RecordArrayManager } from "../managers/record-array-manager.js";
+import type { WarpDriveSignal } from "../new-core-tmp/reactivity/internal.js";
+import { ARRAY_SIGNAL } from "../new-core-tmp/reactivity/internal.js";
+import type { Store } from "../store-service.js";
+import { NativeProxy } from "./native-proxy-type-fix.js";
+export declare const SOURCE: "___(unique) Symbol(#source)";
+export declare const MUTATE: "___(unique) Symbol(#update)";
+declare const IS_COLLECTION: "___(unique) Symbol(IS_COLLECTION)";
+export type IdentifierArrayCreateOptions<T = unknown> = {
+	identifiers: StableRecordIdentifier<TypeFromInstanceOrString<T>>[];
+	type?: TypeFromInstanceOrString<T>;
+	store: Store;
+	allowMutation: boolean;
+	manager: MinimumManager;
+	field?: LegacyHasManyField | LinksModeHasManyField;
+	links?: Links | PaginationLinks | null;
+	meta?: Record<string, unknown> | null;
+	identifier?: StableDocumentIdentifier | null;
+	[MUTATE]?(target: StableRecordIdentifier[], receiver: typeof NativeProxy<StableRecordIdentifier[], T[]>, prop: string, args: unknown[], _SIGNAL: WarpDriveSignal): unknown;
+};
+type PromiseTo<T> = Omit<Promise<T>, typeof Symbol.toStringTag>;
+type PromiseManyArray<T> = {
+	length: number;
+	content: IdentifierArray<T> | null;
+	promise: Promise<IdentifierArray<T>> | null;
+} & PromiseTo<IdentifierArray<T>>;
+export type MinimumManager = {
+	_syncArray: (array: IdentifierArray) => void;
+	mutate?(mutation: LocalRelationshipOperation): void;
+	reloadHasMany?<T>(key: string, options?: BaseFinderOptions): Promise<IdentifierArray<T>> | PromiseManyArray<T>;
+};
+/**
+A record array is an array that contains records of a certain type (or modelName).
+The record array materializes records as needed when they are retrieved for the first
+time. You should not create record arrays yourself. Instead, an instance of
+`RecordArray` or its subclasses will be returned by your application's store
+in response to queries.
+
+This class should not be imported and instantiated by consuming applications.
+
+@class RecordArray
+@public
+*/
+export interface IdentifierArray<T = unknown> extends Omit<Array<T>, "[]"> {
+	[IS_COLLECTION]: boolean;
+	[ARRAY_SIGNAL]: WarpDriveSignal;
+	[SOURCE]: StableRecordIdentifier[];
+}
+export declare class IdentifierArray<T = unknown> {
+	DEPRECATED_CLASS_NAME: string;
+	/**
+	The flag to signal a `RecordArray` is currently loading data.
+	Example
+	```javascript
+	let people = store.peekAll('person');
+	people.isUpdating; // false
+	people.update();
+	people.isUpdating; // true
+	```
+	@property isUpdating
+	@public
+	@type Boolean
+	*/
+	isUpdating: boolean;
+	isLoaded: boolean;
+	isDestroying: boolean;
+	isDestroyed: boolean;
+	_updatingPromise: Promise<IdentifierArray<T>> | null;
+	readonly identifier: StableDocumentIdentifier | null;
+	links: Links | PaginationLinks | null;
+	meta: Record<string, unknown> | null;
+	modelName?: TypeFromInstanceOrString<T>;
+	/**
+	The store that created this record array.
+	
+	@property store
+	@private
+	@type Store
+	*/
+	store: Store;
+	_manager: MinimumManager;
+	destroy(clear: boolean): void;
+	constructor(options: IdentifierArrayCreateOptions<T>);
+	/**
+	Used to get the latest version of all of the records in this array
+	from the adapter.
+	
+	Example
+	
+	```javascript
+	let people = store.peekAll('person');
+	people.isUpdating; // false
+	
+	people.update().then(function() {
+	people.isUpdating; // false
+	});
+	
+	people.isUpdating; // true
+	```
+	
+	@public
+	*/
+	update(): Promise<IdentifierArray<T>>;
+	/*
+	Update this Array and return a promise which resolves once the update
+	is finished.
+	*/
+	_update(): Promise<IdentifierArray<T>>;
+	// TODO deprecate
+	/**
+	Saves all of the records in the `RecordArray`.
+	
+	Example
+	
+	```javascript
+	let messages = store.peekAll('message');
+	messages.forEach(function(message) {
+	message.hasBeenSeen = true;
+	});
+	messages.save();
+	```
+	
+	@public
+	@return {Promise<IdentifierArray>} promise
+	*/
+	save(): Promise<IdentifierArray>;
+}
+export type CollectionCreateOptions = IdentifierArrayCreateOptions & {
+	manager: RecordArrayManager;
+	query: ImmutableRequestInfo | Record<string, unknown> | null;
+	isLoaded: boolean;
+};
+export declare class Collection<T = unknown> extends IdentifierArray<T> {
+	query: ImmutableRequestInfo | Record<string, unknown> | null;
+	_manager: RecordArrayManager;
+	constructor(options: CollectionCreateOptions);
+	_update(): Promise<Collection<T>>;
+	destroy(clear: boolean): void;
+}
+export {};

package/declarations/store/-private/record-arrays/many-array.d.ts

@@ -0,0 +1,197 @@
+import type { BaseFinderOptions, ModelSchema, StableRecordIdentifier } from "../../../types.js";
+import type { Cache } from "../../../types/cache.js";
+import type { TypedRecordInstance, TypeFromInstance, TypeFromInstanceOrString } from "../../../types/record.js";
+import type { LegacyHasManyField, LinksModeHasManyField } from "../../../types/schema/fields.js";
+import type { Links, PaginationLinks } from "../../../types/spec/json-api-raw.js";
+import type { CreateRecordProperties, Store } from "../store-service.js";
+import type { MinimumManager } from "./identifier-array.js";
+import { IdentifierArray } from "./identifier-array.js";
+export interface ManyArrayCreateArgs<T> {
+	identifiers: StableRecordIdentifier<TypeFromInstanceOrString<T>>[];
+	type: TypeFromInstanceOrString<T>;
+	store: Store;
+	allowMutation: boolean;
+	manager: MinimumManager;
+	field?: LegacyHasManyField | LinksModeHasManyField;
+	identifier: StableRecordIdentifier;
+	cache: Cache;
+	meta: Record<string, unknown> | null;
+	links: Links | PaginationLinks | null;
+	key: string;
+	isPolymorphic: boolean;
+	isAsync: boolean;
+	_inverseIsAsync: boolean;
+	isLoaded: boolean;
+}
+/**
+A `ManyArray` is a `MutableArray` that represents the contents of a has-many
+relationship.
+
+The `ManyArray` is instantiated lazily the first time the relationship is
+requested.
+
+This class is not intended to be directly instantiated by consuming applications.
+
+### Inverses
+
+Often, the relationships in Ember Data applications will have
+an inverse. For example, imagine the following models are
+defined:
+
+```js [app/models/post.js]
+import Model, { hasMany } from '@ember-data/model';
+
+export default class PostModel extends Model {
+@hasMany('comment') comments;
+}
+```
+
+```js [app/models/comment.js]
+import { Model, belongsTo } from '@warp-drive/legacy/model';
+
+export default class CommentModel extends Model {
+@belongsTo('post') post;
+}
+```
+
+If you created a new instance of `Post` and added
+a `Comment` record to its `comments` has-many
+relationship, you would expect the comment's `post`
+property to be set to the post that contained
+the has-many.
+
+We call the record to which a relationship belongs-to the
+relationship's _owner_.
+
+@class ManyArray
+@public
+*/
+export declare class RelatedCollection<T = unknown> extends IdentifierArray<T> {
+	isAsync: boolean;
+	/**
+	The loading state of this array
+	
+	@property isLoaded
+	@type {Boolean}
+	@public
+	*/
+	isLoaded: boolean;
+	/**
+	`true` if the relationship is polymorphic, `false` otherwise.
+	
+	@property isPolymorphic
+	@type {Boolean}
+	@private
+	*/
+	isPolymorphic: boolean;
+	_inverseIsAsync: boolean;
+	/**
+	Metadata associated with the request for async hasMany relationships.
+	
+	Example
+	
+	Given that the server returns the following JSON payload when fetching a
+	hasMany relationship:
+	
+	```js
+	{
+	"comments": [{
+	"id": 1,
+	"comment": "This is the first comment",
+	}, {
+	// ...
+	}],
+	
+	"meta": {
+	"page": 1,
+	"total": 5
+	}
+	}
+	```
+	
+	You can then access the meta data via the `meta` property:
+	
+	```js
+	let comments = await post.comments;
+	let meta = comments.meta;
+	
+	// meta.page => 1
+	// meta.total => 5
+	```
+	
+	@property meta
+	@type {Object | null}
+	@public
+	*/
+	meta: Record<string, unknown> | null;
+	/**
+	* Retrieve the links for this relationship
+	*
+	@property links
+	@type {Object | null}
+	@public
+	*/
+	links: Links | PaginationLinks | null;
+	identifier: StableRecordIdentifier;
+	cache: Cache;
+	_manager: MinimumManager;
+	store: Store;
+	key: string;
+	type: ModelSchema;
+	modelName: T extends TypedRecordInstance ? TypeFromInstance<T> : string;
+	constructor(options: ManyArrayCreateArgs<T>);
+	notify(): void;
+	/**
+	Reloads all of the records in the manyArray. If the manyArray
+	holds a relationship that was originally fetched using a links url
+	WarpDrive will revisit the original links url to repopulate the
+	relationship.
+	
+	If the ManyArray holds the result of a `store.query()` reload will
+	re-run the original query.
+	
+	Example
+	
+	```javascript
+	let user = store.peekRecord('user', '1')
+	await login(user);
+	
+	let permissions = await user.permissions;
+	await permissions.reload();
+	```
+	
+	@public
+	*/
+	reload(options?: BaseFinderOptions): Promise<this>;
+	/**
+	Create a child record within the owner
+	
+	@public
+	@param {Object} hash
+	@return {Model} record
+	*/
+	createRecord(hash: CreateRecordProperties<T>): T;
+	/**
+	Saves all of the records in the `ManyArray`.
+	
+	Note: this API can only be used in legacy mode with a configured Adapter.
+	
+	Example
+	
+	```javascript
+	const { content: { data: inbox } } = await store.request(findRecord({ type: 'inbox', id: '1' }));
+	
+	let messages = await inbox.messages;
+	messages.forEach((message) => {
+	message.isRead = true;
+	});
+	messages.save();
+	```
+	
+	@public
+	@return {PromiseArray} promise
+	*/
+	save: () => Promise<IdentifierArray<T>>;
+	/** @internal */
+	destroy(): void;
+}

package/declarations/store/-private/record-arrays/native-proxy-type-fix.d.ts

@@ -0,0 +1,126 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/*
+We redefine Proxy because the native Proxy type treats the `target` and
+`receiver` as the same type incorrectly.
+
+We ported this from Typescript's own Proxy types on 3/10/2024.
+*/
+interface ProxyHandler<T extends object> {
+	/**
+	* A trap method for a function call.
+	* @param target The original callable object which is being proxied.
+	* @internal
+	*/
+	apply?(target: T, thisArg: any, argArray: any[]): any;
+	/**
+	* A trap for the `new` operator.
+	* @param target The original object which is being proxied.
+	* @param newTarget The constructor that was originally called.
+	* @internal
+	*/
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+	construct?(target: T, argArray: any[], newTarget: Function): object;
+	/**
+	* A trap for `Object.defineProperty()`.
+	* @param target The original object which is being proxied.
+	* @return A `Boolean` indicating whether or not the property has been defined.
+	* @internal
+	*/
+	defineProperty?(target: T, property: string | symbol, attributes: PropertyDescriptor): boolean;
+	/**
+	* A trap for the `delete` operator.
+	* @param target The original object which is being proxied.
+	* @param p The name or `Symbol` of the property to delete.
+	* @return A `Boolean` indicating whether or not the property was deleted.
+	* @internal
+	*/
+	deleteProperty?(target: T, p: string | symbol): boolean;
+	/**
+	* A trap for getting a property value.
+	* @param target The original object which is being proxied.
+	* @param p The name or `Symbol` of the property to get.
+	* @param receiver The proxy or an object that inherits from the proxy.
+	* @internal
+	*/
+	get?(target: T, p: string | symbol, receiver: any): any;
+	/**
+	* A trap for `Object.getOwnPropertyDescriptor()`.
+	* @param target The original object which is being proxied.
+	* @param p The name of the property whose description should be retrieved.
+	* @internal
+	*/
+	getOwnPropertyDescriptor?(target: T, p: string | symbol): PropertyDescriptor | undefined;
+	/**
+	* A trap for the `[[GetPrototypeOf]]` internal method.
+	* @param target The original object which is being proxied.
+	* @internal
+	*/
+	getPrototypeOf?(target: T): object | null;
+	/**
+	* A trap for the `in` operator.
+	* @param target The original object which is being proxied.
+	* @param p The name or `Symbol` of the property to check for existence.
+	* @internal
+	*/
+	has?(target: T, p: string | symbol): boolean;
+	/**
+	* A trap for `Object.isExtensible()`.
+	* @param target The original object which is being proxied.
+	* @internal
+	*/
+	isExtensible?(target: T): boolean;
+	/**
+	* A trap for `Reflect.ownKeys()`.
+	* @param target The original object which is being proxied.
+	* @internal
+	*/
+	ownKeys?(target: T): ArrayLike<string | symbol>;
+	/**
+	* A trap for `Object.preventExtensions()`.
+	* @param target The original object which is being proxied.
+	* @internal
+	*/
+	preventExtensions?(target: T): boolean;
+	/**
+	* A trap for setting a property value.
+	* @param target The original object which is being proxied.
+	* @param p The name or `Symbol` of the property to set.
+	* @param receiver The object to which the assignment was originally directed.
+	* @return A `Boolean` indicating whether or not the property was set.
+	* @internal
+	*/
+	set?(target: T, p: string | symbol, newValue: any, receiver: any): boolean;
+	/**
+	* A trap for `Object.setPrototypeOf()`.
+	* @param target The original object which is being proxied.
+	* @param newPrototype The object's new prototype or `null`.
+	* @internal
+	*/
+	setPrototypeOf?(target: T, v: object | null): boolean;
+}
+interface ProxyConstructor {
+	/**
+	* Creates a revocable Proxy object.
+	* @param target A target object to wrap with Proxy.
+	* @param handler An object whose properties define the behavior of Proxy when an operation is attempted on it.
+	* @internal
+	*/
+	revocable<T extends object>(target: T, handler: ProxyHandler<T>): {
+		proxy: T;
+		revoke: () => void;
+	};
+	/**
+	* Creates a Proxy object. The Proxy object allows you to create an object that can be used in place of the
+	* original object, but which may redefine fundamental Object operations like getting, setting, and defining
+	* properties. Proxy objects are commonly used to log property accesses, validate, format, or sanitize inputs.
+	* @param target A target object to wrap with Proxy.
+	* @param handler An object whose properties define the behavior of Proxy when an operation is attempted on it.
+	* @internal
+	*/
+	new <
+		TSource extends object,
+		TTarget extends object
+	>(target: TSource, handler: ProxyHandler<TSource>): TTarget;
+}
+export declare const NativeProxy: ProxyConstructor;
+export {};