@warp-drive/core 5.7.0-alpha.2 → 5.7.0-alpha.21

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

@@ -0,0 +1,82 @@
+import type { ExtensionDef } from "../../../reactive.js";
+import { Context } from "../../../reactive/-private.js";
+import type { RequestKey, ResourceKey } from "../../../types/identifier.js";
+import type { ObjectValue } from "../../../types/json/raw.js";
+import type { CollectionField } from "../../../types/schema/fields.js";
+import type { SignalStore, WarpDriveSignal } from "../new-core-tmp/reactivity/internal.js";
+import type { Store } from "../store-service.js";
+import type { KeyType, MinimumManager } from "./-utils.js";
+import { NativeProxy } from "./native-proxy-type-fix.js";
+declare const IS_COLLECTION: "___(unique) Symbol(IS_COLLECTION)";
+type ProxiedMethod = (...args: unknown[]) => unknown;
+interface ReactiveResourceArrayCreateOptions {
+	// passed in
+	store: Store;
+	manager: MinimumManager;
+	editable: boolean;
+	source: ResourceKey[];
+	// reactive, passed in
+	data: ObjectValue | null;
+	// non-reactive, passed in
+	features: Record<string | symbol, unknown> | null;
+	extensions: Map<string | symbol, ExtensionDef> | null;
+	// not-accessible except by the context
+	options: Record<string, unknown> | null;
+	destroy: null | ((this: ReactiveResourceArray, clear: boolean) => void);
+	mutate: null | ((target: ResourceKey[], receiver: typeof NativeProxy<ResourceKey[], unknown[]>, prop: string, args: unknown[], _SIGNAL: WarpDriveSignal) => unknown);
+}
+interface ReactiveResourceArrayContext extends ReactiveResourceArrayCreateOptions {
+	destroy: (this: ReactiveResourceArray, clear: boolean) => void;
+	mutate: (target: ResourceKey[], receiver: typeof NativeProxy<ResourceKey[], unknown[]>, prop: string, args: unknown[], _SIGNAL: WarpDriveSignal) => unknown;
+	// generated
+	signals: SignalStore;
+	signal: WarpDriveSignal;
+	isDestroying: boolean;
+	isDestroyed: boolean;
+	transaction: boolean;
+	boundFns: Map<KeyType, ProxiedMethod>;
+}
+export interface ReactiveResourceArray<T = unknown> extends Omit<Array<T>, "[]"> {
+	/** @internal */
+	isDestroying: boolean;
+	/** @internal */
+	isDestroyed: boolean;
+	/** @internal */
+	destroy: (this: ReactiveResourceArray, clear: boolean) => void;
+	/** @internal */
+	[IS_COLLECTION]: boolean;
+	/** @internal */
+	[Context]: ReactiveResourceArrayContext;
+}
+export interface TargetArray extends Array<ResourceKey> {
+	/** @internal */
+	[Context]: ReactiveResourceArrayContext;
+}
+export declare function createReactiveResourceArray<T>(options: ReactiveResourceArrayCreateOptions): ReactiveResourceArray<T>;
+export declare function destroy(this: ReactiveResourceArray, clear: boolean): void;
+export interface ReactiveRequestCollectionCreateArgs {
+	// passed in
+	store: Store;
+	manager: MinimumManager;
+	source: ResourceKey[];
+	options: {
+		requestKey: RequestKey;
+	} | null;
+}
+export declare function createRequestCollection(config: ReactiveRequestCollectionCreateArgs): ReactiveResourceArray;
+export interface ReactiveRelatedCollectionCreateArgs {
+	// passed in
+	store: Store;
+	manager: MinimumManager;
+	source: ResourceKey[];
+	// not-accessible except by the context
+	options: {
+		resourceKey: ResourceKey;
+		path: string[];
+		field: CollectionField;
+	};
+	editable: boolean;
+	extensions: Map<string | symbol, ExtensionDef> | null;
+}
+export declare function createRelatedCollection(config: ReactiveRelatedCollectionCreateArgs): ReactiveResourceArray;
+export {};

package/declarations/store/-private/store-service.d.ts

@@ -2,7 +2,7 @@ import type { Graph } from "../../graph/-private.js";
 import type { Future } from "../../request.js";
 import type { RequestManager } from "../../request/-private/manager.js";
 import type { Cache } from "../../types/cache.js";
-import type { StableExistingRecordIdentifier, StableRecordIdentifier } from "../../types/identifier.js";
+import type { PersistedResourceKey, ResourceKey } from "../../types/identifier.js";
 import type { TypedRecordInstance, TypeFromInstance } from "../../types/record.js";
 import type { CollectionResourceDocument, EmptyResourceDocument, JsonApiDocument, ResourceIdentifierObject, SingleResourceDocument } from "../../types/spec/json-api-raw.js";
 import type { Type } from "../../types/symbols.js";
@@ -11,12 +11,12 @@ import type { OpaqueRecordInstance } from "../-types/q/record-instance.js";
 import type { SchemaService } from "../-types/q/schema-service.js";
 import type { StoreRequestInput } from "./cache-handler/handler.js";
 import type { CachePolicy } from "./cache-handler/types.js";
-import { IdentifierCache } from "./caches/identifier-cache.js";
 import { InstanceCache, storeFor } from "./caches/instance-cache.js";
+import { CacheKeyManager } from "./managers/cache-key-manager.js";
 import NotificationManager from "./managers/notification-manager.js";
 import { RecordArrayManager } from "./managers/record-array-manager.js";
 import { RequestStateService } from "./network/request-cache.js";
-import type { IdentifierArray } from "./record-arrays/identifier-array.js";
+import type { LegacyLiveArray } from "./record-arrays/legacy-live-array.js";
 export { storeFor };
 // We inline this list of methods to avoid importing EmberObject
 type EmberObjectKey = "_debugContainerKey" | "_super" | "addObserver" | "cacheFor" | "concatenatedProperties" | "decrementProperty" | "destroy" | "get" | "getProperties" | "incrementProperty" | "init" | "isDestroyed" | "isDestroying" | "mergedProperties" | "notifyPropertyChange" | "removeObserver" | "reopen" | "set" | "setProperties" | "toggleProperty" | "toString" | "willDestroy";
@@ -45,6 +45,9 @@ type MaybeHasId = {
 *
 */
 export type CreateRecordProperties<T = MaybeHasId & Record<string, unknown>> = T extends TypedRecordInstance ? Partial<FilteredKeys<T>> : T extends MaybeHasId ? MaybeHasId & Partial<FilteredKeys<T>> : MaybeHasId & Record<string, unknown>;
+export interface CreateContext {
+	lid?: string;
+}
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type ConstructorFunction = new (...args: any[]) => any;
 // eslint-disable-next-line @typescript-eslint/no-extraneous-class
@@ -76,7 +79,7 @@ export interface Store {
 	* @public
 	*/
 	// eslint-disable-next-line @typescript-eslint/no-unused-vars
-	instantiateRecord<T>(identifier: StableRecordIdentifier, createRecordArgs: {
+	instantiateRecord<T>(identifier: ResourceKey, createRecordArgs: {
 		[key: string]: unknown;
 	}): OpaqueRecordInstance;
 	/**
@@ -190,11 +193,11 @@ export interface Store {
 	*     return this._schema.hasResource(resource);
 	*   }
 	*
-	*   attributesDefinitionFor(identifier: RecordIdentifier | { type: string }): AttributesSchema {
+	*   attributesDefinitionFor(identifier: ResourceKey | { type: string }): AttributesSchema {
 	*     return this._schema.attributesDefinitionFor(identifier);
 	*   }
 	*
-	*   relationshipsDefinitionFor(identifier: RecordIdentifier | { type: string }): RelationshipsSchema {
+	*   relationshipsDefinitionFor(identifier: ResourceKey | { type: string }): RelationshipsSchema {
 	*     const schema = AbstractSchemas.get(identifier.type);
 	*     return schema || this._schema.relationshipsDefinitionFor(identifier);
 	*   }
@@ -244,11 +247,11 @@ export interface Store {
 	*     return this._schema.hasResource(resource);
 	*   }
 	*
-	*   attributesDefinitionFor(identifier: RecordIdentifier | { type: string }): AttributesSchema {
+	*   attributesDefinitionFor(identifier: ResourceKey | { type: string }): AttributesSchema {
 	*     return this._schema.attributesDefinitionFor(identifier);
 	*   }
 	*
-	*   relationshipsDefinitionFor(identifier: RecordIdentifier | { type: string }): RelationshipsSchema {
+	*   relationshipsDefinitionFor(identifier: ResourceKey | { type: string }): RelationshipsSchema {
 	*     const schema = AbstractSchemas.get(identifier.type);
 	*     return schema || this._schema.relationshipsDefinitionFor(identifier);
 	*   }
@@ -314,15 +317,16 @@ export declare class Store extends BaseClass {
 	/** @internal */
 	_schema: SchemaService;
 	/**
-	* Provides access to the IdentifierCache instance
+	* Provides access to the CacheKeyManager
 	* for this store.
 	*
-	* The IdentifierCache can be used to generate or
-	* retrieve a stable unique identifier for any resource.
+	* The CacheKeyManager can be used to generate or
+	* retrieve a stable unique CacheKey for any resource
+	* or request.
 	*
 	* @public
 	*/
-	readonly identifierCache: IdentifierCache;
+	readonly cacheKeyManager: CacheKeyManager;
 	/**
 	* Provides access to the requestManager instance associated
 	* with this Store instance.
@@ -353,7 +357,7 @@ export declare class Store extends BaseClass {
 	*
 	* Note, when defined, these methods will only be invoked if a
 	* cache key exists for the request, either because the request
-	* contains `cacheOptions.key` or because the [IdentifierCache](/ember-data/release/classes/IdentifierCache)
+	* contains `cacheOptions.key` or because the [CacheKeyManager](/ember-data/release/classes/CacheKeyManager)
 	* was able to generate a key for the request using the configured
 	* [generation method](/ember-data/release/functions/@ember-data%2Fstore/setIdentifierGenerationMethod).
 	*
@@ -362,12 +366,12 @@ export declare class Store extends BaseClass {
 	* ```ts
 	* store.lifetimes = {
 	*   // make the request and ignore the current cache state
-	*   isHardExpired(identifier: StableDocumentIdentifier): boolean {
+	*   isHardExpired(key: RequestKey): boolean {
 	*     return false;
 	*   }
 	*
 	*   // make the request in the background if true, return cache state
-	*   isSoftExpired(identifier: StableDocumentIdentifier): boolean {
+	*   isSoftExpired(key: RequestKey): boolean {
 	*     return false;
 	*   }
 	* }
@@ -417,6 +421,8 @@ export declare class Store extends BaseClass {
 	get isDestroyed(): boolean;
 	/** @internal */
 	set isDestroyed(value: boolean);
+	/** @deprecated use {@link Store.cacheKeyManager} */
+	get identifierCache(): CacheKeyManager;
 	/**
 	@private
 	*/
@@ -503,40 +509,77 @@ export declare class Store extends BaseClass {
 	*
 	* @public
 	*/
-	request<
-		RT,
-		T = unknown
-	>(requestConfig: StoreRequestInput<RT, T>): Future<RT>;
+	request<RT>(requestConfig: StoreRequestInput<RT>): Future<RT>;
 	/**
-	Create a new record in the current store. The properties passed
-	to this method are set on the newly created record.
+	Creates a new record in the current store.
+	
+	> [!CAUTION]
+	> This should not be used to mock records or to create
+	> a record representing data that could be fetched from
+	> the API.
 	
-	To create a new instance of a `Post`:
+	The properties passed to this method are set on
+	the newly created record.
+	
+	For instance: to create a new `post`:
 	
 	```js
 	store.createRecord('post', {
-	title: 'Ember is awesome!'
+	title: 'WarpDrive is Stellar!'
 	});
 	```
 	
-	To create a new instance of a `Post` that has a relationship with a `User` record:
+	Relationships can be set during create. For instance,
+	to create a new `post` that has an existing user as
+	it's author:
 	
 	```js
-	let user = this.store.peekRecord('user', '1');
+	const user = store.peekRecord('user', '1');
+	
 	store.createRecord('post', {
-	title: 'Ember is awesome!',
+	title: 'WarpDrive is Stellar!',
 	user: user
 	});
 	```
 	
+	### lid handling
+	
+	All new records are assigned an `lid` that can be used to handle
+	transactional saves of multiple records, or to link the data to
+	other data in scenarios involving eventual-consistency or remote
+	syncing.
+	
+	```ts
+	const post = store.createRecord('post', {
+	title: 'WarpDrive is Stellar!'
+	});
+	const { lid } = recordIdentifierFor(post);
+	```
+	
+	The `lid` defaults to a uuidv4 string.
+	
+	In order to support receiving knowledge about unpersisted creates
+	from other sources (say a different tab in the same web-browser),
+	createRecord allows for the `lid` to be provided as part of an
+	optional third argument. **If this lid already exists in the store
+	an error will be thrown.**
+	
+	```ts
+	const post = store.createRecord(
+	'post',
+	{ title: 'WarpDrive is Stellar!' },
+	{ lid: '4d47bb88-931f-496e-986d-c4888cef7373' }
+	);
+	```
+	
 	@public
-	@param {String} type the name of the resource
-	@param {Object} inputProperties a hash of properties to set on the
+	@param type the name of the resource
+	@param inputProperties a hash of properties to set on the
 	newly created record.
-	@return {Model} record
+	@return a record in the "isNew" state
 	*/
-	createRecord<T>(type: TypeFromInstance<T>, inputProperties: CreateRecordProperties<T>): T;
-	createRecord(type: string, inputProperties: CreateRecordProperties): OpaqueRecordInstance;
+	createRecord<T>(type: TypeFromInstance<T>, inputProperties: CreateRecordProperties<T>, context?: CreateContext): T;
+	createRecord(type: string, inputProperties: CreateRecordProperties, context?: CreateContext): OpaqueRecordInstance;
 	/**
 	For symmetry, a record can be deleted via the store.
 	
@@ -644,8 +687,8 @@ export declare class Store extends BaseClass {
 	@param {String} type the name of the resource
 	@return {RecordArray}
 	*/
-	peekAll<T>(type: TypeFromInstance<T>): IdentifierArray<T>;
-	peekAll(type: string): IdentifierArray;
+	peekAll<T>(type: TypeFromInstance<T>): LegacyLiveArray<T>;
+	peekAll(type: string): LegacyLiveArray;
 	/**
 	This method unloads all records in the store.
 	It schedules unloading to happen during the next run loop.
@@ -823,9 +866,9 @@ export declare class Store extends BaseClass {
 	
 	@private
 	@param {Object} jsonApiDoc
-	@return {StableRecordIdentifier|Array<StableRecordIdentifier>|null} identifiers for the primary records that had data loaded
+	@return {ResourceKey|Array<ResourceKey>|null} identifiers for the primary records that had data loaded
 	*/
-	_push(jsonApiDoc: JsonApiDocument, asyncFlush?: boolean): StableExistingRecordIdentifier | StableExistingRecordIdentifier[] | null;
+	_push(jsonApiDoc: JsonApiDocument, asyncFlush?: boolean): PersistedResourceKey | PersistedResourceKey[] | null;
 	/**
 	* Returns the cache instance associated to this Store, instantiates the Cache
 	* if necessary via `Store.createCache`

package/declarations/store/-private.d.ts

@@ -3,7 +3,7 @@ export { storeFor } from "./-private/store-service.js";
 export { recordIdentifierFor } from "./-private/caches/instance-cache.js";
 export { CacheHandler, type StoreRequestContext } from "./-private/cache-handler/handler.js";
 export { type CachePolicy } from "./-private/cache-handler/types.js";
-export { isStableIdentifier, isDocumentIdentifier } from "./-private/caches/identifier-cache.js";
+export { isResourceKey, isRequestKey } from "./-private/managers/cache-key-manager.js";
 export { constructResource } from "./-private/utils/construct-resource.js";
 export type { InstanceCache } from "./-private/caches/instance-cache.js";
 export type { FindRecordQuery, Request, SaveRecordMutation, RequestCacheRequestState, RequestStateService } from "./-private/network/request-cache.js";
@@ -12,17 +12,17 @@ export type { CreateRecordProperties } from "./-private/store-service.js";
 // to also eliminate
 export { coerceId, ensureStringId } from "./-private/utils/coerce-id.js";
 export type { NativeProxy } from "./-private/record-arrays/native-proxy-type-fix.js";
-export { IdentifierArray as LiveArray, Collection as CollectionRecordArray, SOURCE, MUTATE } from "./-private/record-arrays/identifier-array.js";
+export { type ReactiveResourceArray } from "./-private/record-arrays/resource-array.js";
+export { type LegacyLiveArray, type LegacyLiveArray as LiveArray } from "./-private/record-arrays/legacy-live-array.js";
+export { type LegacyQueryArray, type LegacyQueryArray as CollectionRecordArray } from "./-private/record-arrays/legacy-query.js";
 export { RecordArrayManager, fastPush } from "./-private/managers/record-array-manager.js";
 // leaked for private use / test use, should investigate removing
 export { _clearCaches } from "./-private/caches/instance-cache.js";
-export { peekCache, removeRecordDataFor } from "./-private/caches/cache-utils.js";
 // @ember-data/model needs these temporarily
 export { setRecordIdentifier, StoreMap } from "./-private/caches/instance-cache.js";
-export { setCacheFor } from "./-private/caches/cache-utils.js";
 export { normalizeModelName as _deprecatingNormalize } from "./-private/utils/normalize-model-name.js";
 export type { StoreRequestInput } from "./-private/cache-handler/handler.js";
-export { RelatedCollection } from "./-private/record-arrays/many-array.js";
+export { type LegacyManyArray, type LegacyManyArray as RelatedCollection, createLegacyManyArray } from "./-private/record-arrays/legacy-many-array.js";
 export { log, logGroup } from "./-private/debug/utils.js";
 export { getPromiseState, type PromiseState } from "./-private/new-core-tmp/promise-state.js";
 export { DISPOSE, createRequestSubscription, type SubscriptionArgs, type RequestSubscription } from "./-private/new-core-tmp/request-subscription.js";

package/declarations/store/-types/q/cache-capabilities-manager.d.ts

@@ -1,5 +1,5 @@
-import type { StableDocumentIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
-import type { IdentifierCache } from "../../-private/caches/identifier-cache.js";
+import type { RequestKey, ResourceKey } from "../../../types/identifier.js";
+import type { CacheKeyManager } from "../../-private/managers/cache-key-manager.js";
 import type { NotificationType } from "../../-private/managers/notification-manager.js";
 import type { SchemaService } from "./schema-service.js";
 /**
@@ -11,22 +11,21 @@ import type { SchemaService } from "./schema-service.js";
 *
 * This class cannot be directly instantiated.
 *
-* @class CacheCapabilitiesManager
 * @public
 */
 export type CacheCapabilitiesManager = {
 	/**
-	* Provides access to the IdentifierCache instance
+	* Provides access to the CacheKeyManager instance
 	* for this Store instance.
 	*
-	* The IdentifierCache can be used to peek, generate or
+	* The CacheKeyManager can be used to peek, generate or
 	* retrieve a stable unique identifier for any resource.
 	*
-	* @property identifierCache
-	* @type {IdentifierCache}
 	* @public
 	*/
-	identifierCache: IdentifierCache;
+	cacheKeyManager: CacheKeyManager;
+	/** @deprecated use {@link CacheCapabilitiesManager.cacheKeyManager} */
+	identifierCache: CacheKeyManager;
 	/**
 	* DEPRECATED - use the schema property
 	*
@@ -36,7 +35,7 @@ export type CacheCapabilitiesManager = {
 	* The SchemaService can be used to query for
 	* information about the schema of a resource.
 	*
-	* @deprecated
+	* @deprecated use {@link CacheCapabilitiesManager.schema}
 	* @public
 	*/
 	getSchemaDefinitionService(): SchemaService;
@@ -55,30 +54,25 @@ export type CacheCapabilitiesManager = {
 	* Update the `id` for the record corresponding to the identifier
 	* This operation can only be done for records whose `id` is `null`.
 	*
-	* @param {StableRecordIdentifier} identifier;
-	* @param {String} id;
 	* @public
 	*/
-	setRecordId(identifier: StableRecordIdentifier, id: string): void;
+	setRecordId(identifier: ResourceKey, id: string): void;
 	/**
 	* Signal to the store that the specified record may be considered fully
 	* removed from the cache. Generally this means that not only does no
 	* data exist for the identified resource, no known relationships still
 	* point to it either.
 	*
-	* @param {StableRecordIdentifier} identifier
 	* @public
 	*/
-	disconnectRecord(identifier: StableRecordIdentifier): void;
+	disconnectRecord(identifier: ResourceKey): void;
 	/**
 	* Use this method to determine if the Store has an instantiated record associated
 	* with an identifier.
 	*
-	* @param identifier
-	* @return {Boolean}
 	* @public
 	*/
-	hasRecord(identifier: StableRecordIdentifier): boolean;
+	hasRecord(identifier: ResourceKey): boolean;
 	/**
 	* Notify subscribers of the NotificationManager that cache state has changed.
 	*
@@ -87,13 +81,10 @@ export type CacheCapabilitiesManager = {
 	*
 	* No other namespaces currently expect the `key` argument.
 	*
-	* @param {StableRecordIdentifier} identifier
-	* @param {'attributes' | 'relationships' | 'identity' | 'errors' | 'meta' | 'state'} namespace
-	* @param {string|undefined} key
 	* @public
 	*/
-	notifyChange(identifier: StableRecordIdentifier, namespace: "added" | "removed", key: null): void;
-	notifyChange(identifier: StableDocumentIdentifier, namespace: "added" | "updated" | "removed", key: null): void;
-	notifyChange(identifier: StableRecordIdentifier, namespace: NotificationType, key: string | null): void;
-	notifyChange(identifier: StableRecordIdentifier | StableDocumentIdentifier, namespace: NotificationType | "added" | "removed" | "updated", key: string | null): void;
+	notifyChange(identifier: ResourceKey, namespace: "added" | "removed", key: null): void;
+	notifyChange(identifier: RequestKey, namespace: "added" | "updated" | "removed", key: null): void;
+	notifyChange(identifier: ResourceKey, namespace: NotificationType, key: string | null): void;
+	notifyChange(identifier: ResourceKey | RequestKey, namespace: NotificationType | "added" | "removed" | "updated", key: string | null): void;
 };

package/declarations/store/-types/q/identifier.d.ts

@@ -1,20 +1,23 @@
-import type { IdentifierBucket, StableIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
+import type { CacheKeyType, RequestKey, ResourceKey } from "../../../types/identifier.js";
 import type { ImmutableRequestInfo } from "../../../types/request.js";
 export interface GenerationMethod {
 	(data: ImmutableRequestInfo, bucket: "document"): string | null;
 	(data: unknown | {
 		type: string;
 	}, bucket: "record"): string;
-	(data: unknown, bucket: IdentifierBucket): string | null;
+	(data: unknown, bucket: CacheKeyType): string | null;
 }
 export type UpdateMethod = {
-	(identifier: StableRecordIdentifier, newData: unknown, bucket: "record"): void;
-	(identifier: StableIdentifier, newData: unknown, bucket: never): void;
+	(identifier: ResourceKey, newData: unknown, bucket: "record"): void;
+	(identifier: RequestKey, newData: unknown, bucket: "document"): void;
+	(identifier: {
+		lid: string;
+	}, newData: unknown, bucket: never): void;
 };
-export type ForgetMethod = (identifier: StableIdentifier | StableRecordIdentifier, bucket: IdentifierBucket) => void;
+export type ForgetMethod = (identifier: RequestKey | ResourceKey, bucket: CacheKeyType) => void;
 export type ResetMethod = () => void;
 export type KeyInfo = {
 	id: string | null;
 	type: string;
 };
-export type KeyInfoMethod = (resource: unknown, known: StableRecordIdentifier | null) => KeyInfo;
+export type KeyInfoMethod = (resource: unknown, known: ResourceKey | null) => KeyInfo;