@warp-drive/core 5.8.0-alpha.4 → 5.8.0-alpha.5

package/README.md

@@ -19,7 +19,7 @@
 [![Docs](./logos/docs-badge.svg)](https://api.emberjs.com/ember-data/release)
 [![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=FFC474)](https://discord.gg/zT3asNS
 )
-[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=FFC474)](https://discord.gg/n8BptgFzNt
+[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=FFC474)](https://discord.gg/PHBbnWJx5S
 )
 
 

package/declarations/reactive/-private/schema.d.ts

@@ -8,17 +8,22 @@ import type { WithPartial } from "../../types/utils.js";
 import type { ReactiveResource } from "./record.js";
 /**
 * Extensions allow providing non-schema driven behaviors to
-* reactive resources and arrays.
+* ReactiveResources, ReactiveArrays, and ReactiveObjects.
+*
+* This should only be used for temporary migration purposes
+* to the new schema system when migrating from either Model
+* or ModelFragments.
 */
 export interface CAUTION_MEGA_DANGER_ZONE_Extension {
 	/**
 	* Whether this extension extends the behaviors of objects
-	* or of arrays.
+	* (both ReactiveObjects and ReactiveResources) or of arrays.
 	*/
 	kind: "object" | "array";
 	/**
 	* The name of the extension, to be used when specifying
-	* either `objectExtensions` or `arrayExtensions`
+	* either `objectExtensions` or `arrayExtensions` on the
+	* field, ResourceSchema or ObjectSchema
 	*/
 	name: string;
 	/**
@@ -29,6 +34,74 @@ export interface CAUTION_MEGA_DANGER_ZONE_Extension {
 	*
 	* A constructable such as a Function or Class whose prototype
 	* will be iterated with getOwnPropertyNames.
+	*
+	* Examples:
+	*
+	* **An Object with methods**
+	*
+	* ```ts
+	* store.schema.CAUTION_MEGA_DANGER_ZONE_registerExtension({
+	*    kind: 'object',
+	*    name: 'do-thing-1',
+	*    features: {
+	*      doThingOne(this: { street: string }) {
+	*        return `do-thing-1:${this.street}`;
+	*      },
+	*      doThingTwo(this: { street: string }) {
+	*        return `do-thing-1:${this.street}`;
+	*      },
+	*    },
+	*  });
+	* ```
+	*
+	* **A class with getters, methods and decorated fields**
+	*
+	* ```ts
+	* class Features {
+	*   sayHello() {
+	*     return 'hello!';
+	*   }
+	*
+	*   @tracked trackedField = 'initial tracked value';
+	*
+	*   get realName() {
+	*     const self = this as unknown as { name: string };
+	*     return self.name;
+	*   }
+	*   set realName(v: string) {
+	*     const self = this as unknown as { name: string };
+	*     self.name = v;
+	*   }
+	*
+	*   get greeting() {
+	*     const self = this as unknown as { name: string };
+	*     return `hello ${self.name}!`;
+	*   }
+	*
+	*   @computed('name')
+	*   get salutation() {
+	*     const self = this as unknown as { name: string };
+	*     return `salutations ${self.name}!`;
+	*   }
+	*
+	*   @cached
+	*   get helloThere() {
+	*     const self = this as unknown as { name: string };
+	*     return `Well Hello There ${self.name}!`;
+	*   }
+	* }
+	*
+	* // non-decorated fields dont appear on class prototypes as they are instance only
+	* // @ts-expect-error
+	* Features.prototype.untrackedField = 'initial untracked value';
+	*
+	* store.schema.CAUTION_MEGA_DANGER_ZONE_registerExtension({
+	*   kind: 'object',
+	*   name: 'my-ext',
+	*   features: Features,
+	* });
+	* ```
+	*
 	*/
 	features: Record<string | symbol, unknown> | Function;
 }

package/declarations/store/-private/caches/instance-cache.d.ts

@@ -8,7 +8,7 @@ import type { CacheManager } from "../managers/cache-manager.js";
 import type { CreateRecordProperties, Store } from "../store-service.js";
 export declare function peekRecordIdentifier(record: OpaqueRecordInstance): ResourceKey | undefined;
 /**
-Retrieves the unique referentially-stable [RecordIdentifier](/ember-data/release/classes/ResourceKey)
+Retrieves the unique referentially-stable {@link ResourceKey}
 assigned to the given record instance.
 
 ```js
@@ -22,8 +22,7 @@ const { id, type, lid } = identifier;
 ```
 
 @public
-@param {Object} record a record instance previously obstained from the store.
-@return {ResourceKey}
+@param record a record instance previously obstained from the store.
 */
 export declare function recordIdentifierFor<T extends TypedRecordInstance>(record: T): ResourceKey<TypeFromInstance<T>>;
 export declare function recordIdentifierFor(record: OpaqueRecordInstance): ResourceKey;

package/declarations/store/-private/default-cache-policy.d.ts

@@ -2,6 +2,7 @@ import type { Cache } from "@warp-drive/core/types/cache";
 import type { RequestKey, ResourceKey } from "@warp-drive/core/types/identifier";
 import type { ImmutableRequestInfo, ResponseInfo, StructuredDocument } from "@warp-drive/core/types/request";
 import type { ResourceDocument } from "@warp-drive/core/types/spec/document";
+import type { CachePolicy } from "../-private.js";
 type UnsubscribeToken = object;
 type CacheOperation = "added" | "removed" | "updated" | "state";
 type DocumentCacheOperation = "invalidated" | "added" | "removed" | "updated" | "state";
@@ -28,6 +29,11 @@ type Store = {
 	cache: Cache;
 	notifications: NotificationManager;
 };
+/**
+* Interface of a parsed Cache-Control header value.
+*
+* - [MDN Cache-Control Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control)
+*/
 export interface CacheControlValue {
 	immutable?: boolean;
 	"max-age"?: number;
@@ -66,6 +72,8 @@ export interface CacheControlValue {
 * }
 * ```
 *
+* See also {@link CacheControlValue} and [Response Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#response_directives)
+*
 * @public
 * @param {String} header
 * @return {CacheControlValue}
@@ -74,16 +82,19 @@ export declare function parseCacheControl(header: string): CacheControlValue;
 /**
 * The configuration options for the {@link DefaultCachePolicy}
 *
-* ```ts
-* import { DefaultCachePolicy } from '@warp-drive/core/store';
+* ```ts [app/services/store.ts]
+* import { Store } from '@warp-drive/core';
+* import { DefaultCachePolicy } from '@warp-drive/core/store'; // [!code focus]
 *
-* new DefaultCachePolicy({
-*   // ... PolicyConfig Settings ... //
-* });
+* export default class AppStore extends Store {
+*   lifetimes = new DefaultCachePolicy({ // [!code focus:3]
+*     // ... PolicyConfig Settings ... //
+*   });
+* }
 * ```
 *
 */
-export type PolicyConfig = {
+export interface PolicyConfig {
 	/**
 	* the number of milliseconds after which a request is considered
 	* stale. If a request is issued again after this time, the request
@@ -211,64 +222,79 @@ export type PolicyConfig = {
 		*/
 		isExpired?: (request: StructuredDocument<ResourceDocument>) => boolean | null;
 	};
-};
+}
 /**
-* A basic CachePolicy that can be added to the Store service.
-*
-* Determines staleness based on time since the request was last received from the API
-* using the `date` header.
-*
-* Determines expiration based on configured constraints as well as a time based
-* expiration strategy based on the `date` header.
+* A basic {@link CachePolicy} that can be added to the Store service.
 *
-* In order expiration is determined by:
+* ```ts [app/services/store.ts]
+* import { Store } from '@warp-drive/core';
+* import { DefaultCachePolicy } from '@warp-drive/core/store'; // [!code focus]
 *
-* - Is explicitly invalidated
-* -  ↳ (if null) isExpired function \<IF Constraint Active>
-* -  ↳ (if null) X-WarpDrive-Expires header \<IF Constraint Active>
-* -  ↳ (if null) Cache-Control header \<IF Constraint Active>
-* -  ↳ (if null) Expires header \<IF Constraint Active>
-* -  ↳ (if null) Date header + apiCacheHardExpires \< current time
+* export default class AppStore extends Store {
+*   lifetimes = new DefaultCachePolicy({ // [!code focus:5]
+*     apiCacheSoftExpires: 30_000,
+*     apiCacheHardExpires: 60_000,
+*     // ... Other PolicyConfig Settings ... //
+*   });
+* }
+* ```
 *
-* Invalidates any request for which `cacheOptions.types` was provided when a createRecord
-* request for that type is successful.
+* :::tip 💡 TIP
+* Date headers do not have millisecond precision, so expiration times should
+* generally be larger than 1000ms.
+* :::
 *
-* For this to work, the `createRecord` request must include the `cacheOptions.types` array
-* with the types that should be invalidated, or its request should specify the ResourceKeys
-* of the records that are being created via `records`. Providing both is valid.
+* See also {@link PolicyConfig} for configuration options.
 *
-* > [!NOTE]
-* > only requests that had specified `cacheOptions.types` and occurred prior to the
-* > createRecord request will be invalidated. This means that a given request should always
-* > specify the types that would invalidate it to opt into this behavior. Abstracting this
-* > behavior via builders is recommended to ensure consistency.
+* ### The Mechanics
 *
-* This allows the Store's CacheHandler to determine if a request is expired and
-* should be refetched upon next request.
+* This policy determines staleness based on various configurable constraints falling back to a simple
+* check of the time elapsed since the request was last received from the API using the `date` header
+* from the last response.
 *
-* The `Fetch` handler provided by `@warp-drive/core` will automatically
+* :::tip 💡 TIP
+* The {@link Fetch} handler provided by `@warp-drive/core` will automatically
 * add the `date` header to responses if it is not present.
+* :::
 *
-* > [!NOTE]
-* > Date headers do not have millisecond precision, so expiration times should
-* > generally be larger than 1000ms.
+* - For manual override of reload see {@link RequestInfo.cacheOptions.reload | cacheOptions.reload}
+* - For manual override of background reload see {@link RequestInfo.cacheOptions.backgroundReload | cacheOptions.backgroundReload}
 *
-* Usage:
+* In order expiration is determined by:
 *
-* ```ts
-* import { Store } from '@warp-drive/core';
-* import { DefaultCachePolicy } from '@warp-drive/core/store';
+* ```md
+* Is explicitly invalidated by `cacheOptions.reload`
+*   ↳ (if falsey) if the request has been explicitly invalidated
+*      since the last request (see Automatic Invalidation below)
+*   ↳ (if false) (If Active) isExpired function
+*   ↳ (if null) (If Active) X-WarpDrive-Expires header
+*   ↳ (if null) (If Active) Cache-Control header
+*   ↳ (if null) (If Active) Expires header
+*   ↳ (if null) Date header + apiCacheHardExpires < current time
 *
-* export class AppStore extends Store {
-*   lifetimes = new DefaultCachePolicy({
-*     apiCacheSoftExpires: 30_000,
-*     apiCacheHardExpires: 60_000
-*   });
-* }
+*   -- <if above is false, a background request is issued if> --
+*
+*   ↳ is invalidated by `cacheOptions.backgroundReload`
+*   ↳ (if falsey) Date header + apiCacheSoftExpires < current time
 * ```
 *
-* In Testing environments, the `apiCacheSoftExpires` will always be `false`
-* and `apiCacheHardExpires` will use the `apiCacheSoftExpires` value.
+* ### Automatic Invalidation / Entanglement
+*
+* It also invalidates any request with an {@link RequestInfo.op | OpCode} of `"query"`
+* for which {@link RequestInfo.cacheOptions.types | cacheOptions.types} was provided
+* when a request with an `OpCode` of `"createRecord"` is successful and also includes
+* a matching type in its own `cacheOptions.types` array.
+
+* :::tip 💡 TIP
+* Abstracting this behavior via builders is recommended to ensure consistency.
+* :::
+*
+* ### Testing
+*
+* In Testing environments:
+*
+* - `apiCacheSoftExpires` will always be `false`
+* - `apiCacheHardExpires` will use the `apiCacheSoftExpires` value.
 *
 * This helps reduce flakiness and produce predictably rendered results in test suites.
 *
@@ -280,16 +306,7 @@ export type PolicyConfig = {
 *
 * @public
 */
-export declare class DefaultCachePolicy {
-	config: PolicyConfig;
-	_stores: WeakMap<Store, {
-		invalidated: Set<RequestKey>;
-		types: Map<string, Set<RequestKey>>;
-	}>;
-	_getStore(store: Store): {
-		invalidated: Set<RequestKey>;
-		types: Map<string, Set<RequestKey>>;
-	};
+export declare class DefaultCachePolicy implements CachePolicy {
 	constructor(config: PolicyConfig);
 	/**
 	* Invalidate a request by its CacheKey for the given store instance.

package/declarations/store/-private/managers/cache-capabilities-manager.d.ts

@@ -1,6 +1,6 @@
 import type { RequestKey, ResourceKey } from "../../../types/identifier.js";
 import type { CacheCapabilitiesManager as StoreWrapper } from "../../-types/q/cache-capabilities-manager.js";
-import type { SchemaService } from "../../-types/q/schema-service.js";
+import type { SchemaService } from "../../../types/schema/schema-service.js";
 import type { PrivateStore, Store } from "../store-service.js";
 import type { CacheKeyManager } from "./cache-key-manager.js";
 import type { NotificationType } from "./notification-manager.js";

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

@@ -8,7 +8,7 @@ import type { CollectionResourceDocument, EmptyResourceDocument, JsonApiDocument
 import type { Type } from "../../types/symbols.js";
 import type { CacheCapabilitiesManager } from "../-types/q/cache-capabilities-manager.js";
 import type { OpaqueRecordInstance } from "../-types/q/record-instance.js";
-import type { SchemaService } from "../-types/q/schema-service.js";
+import type { SchemaService } from "../../types/schema/schema-service.js";
 import type { StoreRequestInput } from "./cache-handler/handler.js";
 import type { CachePolicy } from "./cache-handler/types.js";
 import { InstanceCache, storeFor } from "./caches/instance-cache.js";
@@ -101,7 +101,7 @@ export interface Store {
 	* For Example, to use the default SchemaService for ReactiveResource
 	*
 	* ```ts
-	* import { SchemaService } from '@warp-drive/schema-record';
+	* import { SchemaService } from '@warp-drive/core/reactive';
 	*
 	* class extends Store {
 	*   createSchemaService() {
@@ -110,10 +110,10 @@ export interface Store {
 	* }
 	* ```
 	*
-	* Or to use the SchemaService for @ember-data/model
+	* Or to use the SchemaService for @warp-drive/legacy/model
 	*
 	* ```ts
-	* import { buildSchema } from '@ember-data/model';
+	* import { buildSchema } from '@warp-drive/legacy/model';
 	*
 	* class extends Store {
 	*   createSchemaService() {
@@ -125,13 +125,13 @@ export interface Store {
 	* If you wish to chain services, you must either
 	* instantiate each schema source directly or super to retrieve
 	* an existing service. For convenience, when migrating from
-	* `@ember-data/model` to `@warp-drive/schema-record` a
+	* `@warp-drive/legacy/model` to {@link ReactiveResource} a
 	* SchemaService is provided that handles this transition
 	* for you:
 	*
 	* ```ts
-	* import { DelegatingSchemaService } from '@ember-data/model/migration-support';
-	* import { SchemaService } from '@warp-drive/schema-record';
+	* import { DelegatingSchemaService } from '@warp-drive/legacy/model/migration-support';
+	* import { SchemaService } from '@warp-drive/core/reactive';
 	*
 	* class extends Store {
 	*   createSchemaService() {
@@ -176,7 +176,7 @@ export interface Store {
 	* For Example:
 	*
 	* ```ts
-	* import Store from '@ember-data/store';
+	* import { Store } from '@warp-drive/core';
 	*
 	* class SchemaDelegator {
 	*   constructor(schema) {
@@ -210,7 +210,6 @@ export interface Store {
 	* }
 	* ```
 	*
-	* @param {SchemaService} schema
 	* @deprecated
 	* @public
 	*/
@@ -230,7 +229,7 @@ export interface Store {
 	* For Example:
 	*
 	* ```ts
-	* import Store from '@ember-data/store';
+	* import { Store } from '@warp-drive/core';
 	*
 	* class SchemaDelegator {
 	*   constructor(schema) {
@@ -264,7 +263,6 @@ export interface Store {
 	* }
 	* ```
 	*
-	* @param {SchemaService} schema
 	* @deprecated
 	* @public
 	*/
@@ -321,20 +319,18 @@ export declare class Store extends BaseClass {
 	*/
 	readonly cacheKeyManager: CacheKeyManager;
 	/**
-	* Provides access to the requestManager instance associated
+	* Provides access to the {@link RequestManager} instance associated
 	* with this Store instance.
 	*
-	* When using `ember-data` this property is automatically
-	* set to an instance of `RequestManager`. When not using `ember-data`
-	* you must configure this property yourself, either by declaring
-	* it as a service or by initializing it.
+	* See also:
+	* - {@link Fetch}
+	* - {@link CacheHandlerInterface | CacheHandler (Interface)}
+	* - {@link CacheHandler | CacheHandler (Class)}
 	*
 	* ```ts
-	* import Store, { CacheHandler } from '@ember-data/store';
-	* import RequestManager from '@ember-data/request';
-	* import Fetch from '@ember-data/request/fetch';
+	* import { CacheHandler, Fetch, RequestManager, Store } from '@warp-drive/core';
 	*
-	* class extends Store {
+	* class AppStore extends Store {
 	*   requestManager = new RequestManager()
 	*    .use([Fetch])
 	*    .useCache(CacheHandler);
@@ -350,9 +346,9 @@ 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 [CacheKeyManager](/ember-data/release/classes/CacheKeyManager)
+	* contains `cacheOptions.key` or because the {@link CacheKeyManager}
 	* was able to generate a key for the request using the configured
-	* [generation method](/ember-data/release/functions/@ember-data%2Fstore/setIdentifierGenerationMethod).
+	* {@link setIdentifierGenerationMethod | generation method}.
 	*
 	* `isSoftExpired` will only be invoked if `isHardExpired` returns `false`.
 	*
@@ -557,14 +553,10 @@ export declare class Store extends BaseClass {
 	otherwise it will return `null`. A record is available if it has been fetched earlier, or
 	pushed manually into the store.
 	
-	See [findRecord](../methods/findRecord?anchor=findRecord) if you would like to request this record from the backend.
-	
-	_Note: This is a synchronous method and does not return a promise._
-	
 	**Example 1**
 	
-	```js
-	let post = store.peekRecord('post', '1');
+	```ts
+	const post = store.peekRecord('post', '1');
 	
 	post.id; // '1'
 	```
@@ -575,8 +567,8 @@ export declare class Store extends BaseClass {
 	
 	**Example 2**
 	
-	```js
-	let post = store.peekRecord({ type: 'post', id });
+	```ts
+	const post = store.peekRecord({ type: 'post', id: '1' });
 	post.id; // '1'
 	```
 	
@@ -590,40 +582,34 @@ export declare class Store extends BaseClass {
 	post.id; // '1'
 	```
 	
-	
 	@since 1.13.0
 	@public
-	@param {String|object} modelName - either a string representing the modelName or a ResourceIdentifier object containing both the type (a string) and the id (a string) for the record or an lid (a string) of an existing record
-	@param {String|Integer} id - optional only if the first param is a ResourceIdentifier, else the string id of the record to be retrieved.
-	@return {Model|null} record
+	@param type - either a string representing the modelName or a ResourceIdentifier object containing both the type (a string) and the id (a string) for the record or an lid (a string) of an existing record
+	@param id - optional only if the first param is a ResourceIdentifier, else the string id of the record to be retrieved.
 	*/
 	peekRecord<T>(type: TypeFromInstance<T>, id: string | number): T | null;
 	peekRecord(type: string, id: string | number): unknown | null;
 	peekRecord<T>(identifier: ResourceIdentifierObject<TypeFromInstance<T>>): T | null;
 	peekRecord(identifier: ResourceIdentifierObject): unknown | null;
 	/**
-	This method returns a filtered array that contains all of the
-	known records for a given type in the store.
+	This method returns the {@link LegacyLiveArray} that contains all of the
+	known records for a given type in the store. Each ResourceType has only
+	one LiveArray instance, so multiple calls to `peekAll` with the same type
+	will always return the same instance.
 	
-	Note that because it's just a filter, the result will contain any
+	Note that because it's a LiveArray, the result will contain any
 	locally created records of the type, however, it will not make a
-	request to the backend to retrieve additional records. If you
-	would like to request all the records from the backend please use
-	[store.findAll](../methods/findAll?anchor=findAll).
-	
-	Also note that multiple calls to `peekAll` for a given type will always
-	return the same `RecordArray`.
+	request to the backend to retrieve additional records.
 	
 	Example
 	
-	```javascript
-	let localPosts = store.peekAll('post');
+	```ts
+	const allPosts = store.peekAll('post');
 	```
 	
 	@since 1.13.0
 	@public
-	@param {String} type the name of the resource
-	@return {RecordArray}
+	@param type the name of the resource
 	*/
 	peekAll<T>(type: TypeFromInstance<T>): LegacyLiveArray<T>;
 	peekAll(type: string): LegacyLiveArray;
@@ -708,7 +694,7 @@ export declare class Store extends BaseClass {
 	For this model:
 	
 	```js [app/models/person.js]
-	import Model, { attr, hasMany } from '@ember-data/model';
+	import Model, { attr, hasMany } from '@warp-drive/legacy/model';
 	
 	export default class PersonRoute extends Route {
 	@attr('string') firstName;
@@ -775,23 +761,17 @@ export declare class Store extends BaseClass {
 	}
 	```
 	
-	If you're streaming data or implementing an adapter, make sure
-	that you have converted the incoming data into this form. The
-	store's [normalize](../methods/normalize?anchor=normalize) method is a convenience
-	helper for converting a json payload into the form Ember Data
-	expects.
-	
-	```js
-	store.push(store.normalize('person', data));
-	```
+	If you're streaming data, or implementing response handling, make sure
+	that you have converted the incoming data into this form.
 	
 	This method can be used both to push in brand new
 	records, as well as to update existing records.
 	
+	See also {@link Cache.patch}
+	
 	@public
-	@param {Object} data
-	@return the record(s) that was created or
-	updated.
+	@param data
+	@return the primary record(s) that created or updated.
 	*/
 	push(data: EmptyResourceDocument): null;
 	push<T>(data: SingleResourceDocument<TypeFromInstance<T>>): T;
@@ -803,8 +783,7 @@ export declare class Store extends BaseClass {
 	without creating materialized records.
 	
 	@private
-	@param {Object} jsonApiDoc
-	@return {ResourceKey|Array<ResourceKey>|null} identifiers for the primary records that had data loaded
+	@return identifiers for the primary records that had data loaded
 	*/
 	_push(jsonApiDoc: JsonApiDocument, asyncFlush?: boolean): PersistedResourceKey | PersistedResourceKey[] | null;
 	/**

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

@@ -1,7 +1,7 @@
 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";
+import type { SchemaService } from "../../../types/schema/schema-service.js";
 /**
 * CacheCapabilitiesManager provides encapsulated API access to the minimal
 * subset of the Store's functionality that Cache implementations