@warp-drive/core 5.6.0-beta.1 → 5.6.0-beta.2

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

@@ -1,8 +1,9 @@
-export { Store, storeFor } from "./-private/store-service.js";
+export { Store } from "./deprecated/store.js";
+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";
@@ -11,21 +12,24 @@ 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, type PrivateReactiveResourceArray } 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 test/legacy use. You will get in trouble for this.
+export { assertPrivateStore, isPrivateStore, type PrivateStore } from "./-private/store-service.js";
+export { assertPrivateCapabilities, type PrivateCacheCapabilitiesManager } from "./-private/managers/cache-capabilities-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";
+export { DISPOSE, createRequestSubscription, type RequestArgs, type SubscriptionArgs, type RequestComponentArgs, type RequestSubscription, type ContentFeatures, type RecoveryFeatures, type AutorefreshBehaviorCombos, type AutorefreshBehaviorType } from "./-private/new-core-tmp/request-subscription.js";
 export { getRequestState, type RequestLoadingState, type RequestCacheRequestState as RequestState } from "./-private/new-core-tmp/request-state.js";
-export { createMemo, type SignalHooks, waitFor } from "./-private/new-core-tmp/reactivity/configure.js";
-export { memoized, gate, entangleSignal, defineSignal, defineNonEnumerableSignal } from "./-private/new-core-tmp/reactivity/signal.js";
-export { ARRAY_SIGNAL, OBJECT_SIGNAL, Signals, type WarpDriveSignal, peekInternalSignal, withSignalStore, notifyInternalSignal, consumeInternalSignal, getOrCreateInternalSignal } from "./-private/new-core-tmp/reactivity/internal.js";
+export { type SignalHooks, waitFor } from "./-private/new-core-tmp/reactivity/configure.js";
+export { signal, memoized, gate, entangleSignal, entangleInitiallyStaleSignal, defineSignal, defineGate, defineNonEnumerableSignal } from "./-private/new-core-tmp/reactivity/signal.js";
+export { ARRAY_SIGNAL, OBJECT_SIGNAL, Signals, type WarpDriveSignal, peekInternalSignal, createInternalMemo, withSignalStore, notifyInternalSignal, consumeInternalSignal, getOrCreateInternalSignal } from "./-private/new-core-tmp/reactivity/internal.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;

package/declarations/store/-types/q/record-instance.d.ts

@@ -18,6 +18,5 @@ also allows WarpDrive to provide typechecking and intellisense for the record
 based on a special symbol prsent on record instances that implement the
 `TypedRecordInstance` interface.
 
-@internal
 */
 export type OpaqueRecordInstance = unknown;

package/declarations/store/-types/q/schema-service.d.ts

@@ -1,9 +1,9 @@
 import type { CAUTION_MEGA_DANGER_ZONE_Extension, ProcessedExtension } from "../../../reactive.js";
 import type { ExtensibleField } from "../../../reactive/-private/schema.js";
-import type { RecordIdentifier, StableRecordIdentifier } from "../../../types/identifier.js";
+import type { ResourceKey } from "../../../types/identifier.js";
 import type { ObjectValue } from "../../../types/json/raw.js";
 import type { Derivation, HashFn, Transformation } from "../../../types/schema/concepts.js";
-import type { ArrayField, DerivedField, FieldSchema, GenericField, HashField, LegacyAttributeField, LegacyRelationshipField, ObjectField, Schema } from "../../../types/schema/fields.js";
+import type { ArrayField, CacheableFieldSchema, DerivedField, FieldSchema, GenericField, HashField, IdentityField, LegacyAttributeField, LegacyRelationshipField, ObjectField, Schema, Trait } from "../../../types/schema/fields.js";
 export type AttributesSchema = Record<string, LegacyAttributeField>;
 export type RelationshipsSchema = Record<string, LegacyRelationshipField>;
 interface ObjectWithStringTypeProperty {
@@ -57,7 +57,6 @@ interface ObjectWithStringTypeProperty {
 * }
 * ```
 *
-* @class (Interface) SchemaService
 * @public
 */
 export interface SchemaService {
@@ -68,52 +67,47 @@ export interface SchemaService {
 	*
 	* @public
 	* @deprecated
-	* @param {String} type
-	* @return {Boolean}
 	*/
 	doesTypeExist?(type: string): boolean;
 	/**
 	* Queries whether the SchemaService recognizes `type` as a resource type
 	*
 	* @public
-	* @param {StableRecordIdentifier|ObjectWithStringTypeProperty} resource
-	* @return {Boolean}
 	*/
-	hasResource(resource: ObjectWithStringTypeProperty | StableRecordIdentifier): boolean;
+	hasResource(resource: ObjectWithStringTypeProperty | ResourceKey): boolean;
 	/**
 	* Queries whether the SchemaService recognizes `type` as a resource trait
 	*
 	* @public
-	* @param {String} type
-	* @return {Boolean}
 	*/
 	hasTrait(type: string): boolean;
 	/**
 	* Queries whether the given resource has the given trait
 	*
 	* @public
-	* @param {StableRecordIdentifier|ObjectWithStringTypeProperty} resource
-	* @param {String} trait
-	* @return {Boolean}
 	*/
-	resourceHasTrait(resource: ObjectWithStringTypeProperty | StableRecordIdentifier, trait: string): boolean;
+	resourceHasTrait(resource: ObjectWithStringTypeProperty | ResourceKey, trait: string): boolean;
 	/**
 	* Queries for the fields of a given resource type or resource identity.
 	*
 	* Should error if the resource type is not recognized.
 	*
 	* @public
-	* @param {StableRecordIdentifier|ObjectWithStringTypeProperty} resource
-	* @return {Map<string, FieldSchema>}
 	*/
-	fields(resource: ObjectWithStringTypeProperty | StableRecordIdentifier): Map<string, FieldSchema>;
+	fields(resource: ObjectWithStringTypeProperty | ResourceKey): Map<string, FieldSchema>;
+	/**
+	* Queries for the fields of a given resource type or resource identity.
+	*
+	* Should error if the resource type is not recognized.
+	*
+	* @public
+	*/
+	cacheFields?(resource: ObjectWithStringTypeProperty | ResourceKey): Map<string, Exclude<CacheableFieldSchema, IdentityField>>;
 	/**
 	* Returns the transformation registered with the name provided
 	* by `field.type`. Validates that the field is a valid transformable.
 	*
 	* @public
-	* @param {TransformableField|ObjectWithStringTypeProperty} field
-	* @return {Transformation}
 	*/
 	transformation(field: GenericField | ObjectField | ArrayField | ObjectWithStringTypeProperty): Transformation;
 	/**
@@ -121,8 +115,6 @@ export interface SchemaService {
 	* by `field.type`. Validates that the field is a valid HashField.
 	*
 	* @public
-	* @param {HashField|ObjectWithStringTypeProperty} field
-	* @return {HashFn}
 	*/
 	hashFn(field: HashField | ObjectWithStringTypeProperty): HashFn;
 	/**
@@ -130,18 +122,14 @@ export interface SchemaService {
 	* by `field.type`. Validates that the field is a valid DerivedField.
 	*
 	* @public
-	* @param {DerivedField|ObjectWithStringTypeProperty} field
-	* @return {Derivation}
 	*/
 	derivation(field: DerivedField | ObjectWithStringTypeProperty): Derivation;
 	/**
 	* Returns the schema for the provided resource type.
 	*
 	* @public
-	* @param {StableRecordIdentifier|ObjectWithStringTypeProperty} resource
-	* @return {ResourceSchema}
 	*/
-	resource(resource: ObjectWithStringTypeProperty | StableRecordIdentifier): Schema;
+	resource(resource: ObjectWithStringTypeProperty | ResourceKey): Schema;
 	/**
 	* Enables registration of multiple Schemas at once.
 	*
@@ -150,7 +138,6 @@ export interface SchemaService {
 	* or other sources just-in-time.
 	*
 	* @public
-	* @param {Schema[]} schemas
 	*/
 	registerResources(schemas: Schema[]): void;
 	/**
@@ -163,7 +150,6 @@ export interface SchemaService {
 	* or other sources just-in-time.
 	*
 	* @public
-	* @param {Schema} schema
 	*/
 	registerResource(schema: Schema): void;
 	/**
@@ -173,7 +159,6 @@ export interface SchemaService {
 	* attached to it's `[Type]` property.
 	*
 	* @public
-	* @param {Transformation} transform
 	*/
 	registerTransformation(transform: Transformation): void;
 	/**
@@ -183,7 +168,6 @@ export interface SchemaService {
 	* attached to it's `[Type]` property.
 	*
 	* @public
-	* @param {Derivation} derivation
 	*/
 	registerDerivation<
 		R,
@@ -197,10 +181,38 @@ export interface SchemaService {
 	* attached to it's `[Type]` property.
 	*
 	* @public
-	* @param {HashFn} hashfn
 	*/
 	registerHashFn(hashFn: HashFn): void;
 	/**
+	* Registers a {@link Trait} for use by resource schemas.
+	*
+	* Traits are re-usable collections of fields that can be composed to
+	* build up a resource schema. Often they represent polymorphic behaviors
+	* a resource should exhibit.
+	*
+	* When we finalize a resource, we walk its traits and apply their fields
+	* to the resource's fields. All specified traits must be registered by
+	* this time or an error will be thrown.
+	*
+	* Traits are applied left-to-right, with traits of traits being applied in the same
+	* way. Thus for the most part, application of traits is a post-order graph traversal
+	* problem.
+	*
+	* A trait is only ever processed once. If multiple traits (A, B, C) have the same
+	* trait (D) as a dependency, D will be included only once when first encountered by
+	* A.
+	*
+	* If a cycle exists such that trait A has trait B which has Trait A, trait A will
+	* be applied *after* trait B in production. In development a cycle error will be thrown.
+	*
+	* Fields are finalized on a "last wins principle". Thus traits appearing higher in
+	* the tree and further to the right of a traits array take precedence, with the
+	* resource's fields always being applied last and winning out.
+	*
+	* @public
+	*/
+	registerTrait?(trait: Trait): void;
+	/**
 	* DEPRECATED - use `fields` instead
 	*
 	* Returns definitions for all properties of the specified resource
@@ -240,10 +252,8 @@ export interface SchemaService {
 	*
 	* @public
 	* @deprecated
-	* @param {RecordIdentifier|ObjectWithStringTypeProperty} identifier
-	* @return {AttributesSchema}
 	*/
-	attributesDefinitionFor?(identifier: RecordIdentifier | ObjectWithStringTypeProperty): AttributesSchema;
+	attributesDefinitionFor?(key: ResourceKey | ObjectWithStringTypeProperty): AttributesSchema;
 	/**
 	* DEPRECATED - use `fields` instead
 	*
@@ -321,34 +331,48 @@ export interface SchemaService {
 	*
 	* @public
 	* @deprecated
-	* @param {RecordIdentifier|ObjectWithStringTypeProperty} identifier
-	* @return {RelationshipsSchema}
 	*/
-	relationshipsDefinitionFor?(identifier: RecordIdentifier | ObjectWithStringTypeProperty): RelationshipsSchema;
+	relationshipsDefinitionFor?(key: ResourceKey | ObjectWithStringTypeProperty): RelationshipsSchema;
 	/**
 	* Returns all known resource types
 	*
 	* @public
-	* @return {String[]}
 	*/
 	resourceTypes(): Readonly<string[]>;
 	/**
 	* Register an extension for either objects or arrays
+	*
+	* @public
 	*/
 	CAUTION_MEGA_DANGER_ZONE_registerExtension?(extension: CAUTION_MEGA_DANGER_ZONE_Extension): void;
 	/**
 	* Retrieve the extension map for a resource
+	*
+	* @public
 	*/
-	CAUTION_MEGA_DANGER_ZONE_resourceExtensions?(resource: StableRecordIdentifier | {
+	CAUTION_MEGA_DANGER_ZONE_resourceExtensions?(resource: ResourceKey | {
 		type: string;
 	}): null | ProcessedExtension["features"];
 	/**
 	* Retrieve the extension map for an object field
+	*
+	* @public
 	*/
-	CAUTION_MEGA_DANGER_ZONE_objectExtensions?(field: ExtensibleField): null | ProcessedExtension["features"];
+	CAUTION_MEGA_DANGER_ZONE_objectExtensions?(field: ExtensibleField, resolvedType: string | null): null | ProcessedExtension["features"];
 	/**
 	* Retrieve the extension map for an array field
+	*
+	* @public
 	*/
 	CAUTION_MEGA_DANGER_ZONE_arrayExtensions?(field: ExtensibleField): null | ProcessedExtension["features"];
+	/**
+	* Check if a specific extension has been registered previously
+	*
+	* @public
+	*/
+	CAUTION_MEGA_DANGER_ZONE_hasExtension?(ext: {
+		kind: "object" | "array";
+		name: string;
+	}): boolean;
 }
 export {};

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

@@ -1,12 +1,11 @@
 import type { Value } from "../../../types/json/raw.js";
-import type { Includes, TypedRecordInstance } from "../../../types/record.js";
-export interface BaseFinderOptions<T = unknown> {
+export interface BaseFinderOptions {
 	reload?: boolean;
 	backgroundReload?: boolean;
-	include?: T extends TypedRecordInstance ? Includes<T>[] : string | string[];
+	include?: string | string[];
 	adapterOptions?: Record<string, unknown>;
 }
-export interface FindRecordOptions<T = unknown> extends BaseFinderOptions<T> {
+export interface FindRecordOptions extends BaseFinderOptions {
 	/**
 	* Data to preload into the store before the request is made.
 	* This feature is *highly* discouraged and has no corresponding
@@ -25,8 +24,8 @@ export interface FindRecordOptions<T = unknown> extends BaseFinderOptions<T> {
 	preload?: Record<string, Value>;
 }
 export type QueryOptions = { [K in string | "adapterOptions"]? : K extends "adapterOptions" ? Record<string, unknown> : unknown };
-export type FindAllOptions<T = unknown> = BaseFinderOptions<T>;
-export type LegacyResourceQuery<T = unknown> = {
-	include?: T extends TypedRecordInstance ? Includes<T>[] : string | string[];
+export type FindAllOptions = BaseFinderOptions;
+export type LegacyResourceQuery = {
+	include?: string | string[];
 	[key: string]: Value | undefined;
 };