@warp-drive/core 5.7.0-alpha.9 → 5.7.0-beta.0

package/declarations/reactive.d.ts

@@ -1,5 +1,281 @@
+/**
+* # About
+*
+* This module provides an implementation of reactive objects that a Store may use for creating
+* reactive representations of the raw data for requests, resources and their relationships
+* stored in the cache.
+*
+* - For configuring the store to use these reactive objects, see [The Setup Guide](/guides/1-configuration/2-setup/1-universal.md)
+* - For defining resource schemas, see [The Schema Guide](/guides)
+*
+* Any method that returns a record instance will use the `instantiateRecord`
+* hook configured above to instantiate a ReactiveResource once this is in place.
+* After that, its up to you what ReactiveResource can do.
+*
+* ## Modes
+*
+* ReactiveResource has two modes: `legacy` and `polaris`.
+*
+* **LegacyMode** can be used to emulate the behaviors and capabilities of WarpDrive's `Model` class,
+* and because there is little distinction between Model and a ReactiveResource in LegacyMode we refer
+* to both of these approaches as LegacyMode. This mode is the default experience in V5.
+*
+* In LegacyMode:
+*
+* - records are mutable
+* - local changes immediately reflect app wide
+* - records have all the APIs of Model (references, state props, currentState, methods etc)
+* - the continued use of `@warp-drive/legacy` is required (though most imports from it can be removed)
+* - `async: true` relationships are supported (but not recommended outside of [LinksMode](https://github.com/emberjs/data/blob/main/guides/relationships/features/links-mode.md))
+*
+* ---
+*
+* **PolarisMode** is an upcoming suite of features that will become the default experience in V6.
+*
+* In PolarisMode:
+*
+* - records are immutable, unless creating a new resource or explicitly checking out a record for editing
+* - local changes are isolated until committed, displaying only via the editable version of the record
+* - records have a more limited API, focused on only what is in their schema.
+* - some common operations may have more friction to perform because intended utilities are not yet available
+* - `async: true` relationships are not supported (see [LinksMode](https://github.com/emberjs/data/blob/main/guides/relationships/features/links-mode.md))
+* - The `@warp-drive/legacy` package is not required
+*
+* These modes are interopable. The reactive object (record) for a resource in PolarisMode can relate to
+* a record in LegacyMode and vice-versa. This interopability is true whether the record in LegacyMode is
+* a ReactiveResource or a Model.
+*
+* ---
+*
+* ## Basic Usage
+*
+* ReactiveResource is a reactive object that transforms raw data from an associated
+* cache into reactive data backed by Signals.
+*
+* The shape of the object and the transformation of raw cache data into its
+* reactive form is controlled by a resource schema.
+*
+* For instance, lets say your API is a [{JSON:API}](https://jsonapi.org) and your store is using
+* the Cache provided by [@warp-drive/json-api](/api/@warp-drive/json-api), and a request
+* returns the following raw data:
+*
+* ```ts
+* {
+*   data: {
+*     type: 'user',
+*     id: '1',
+*     attributes: { firstName: 'Chris', lastName: 'Thoburn' },
+*     relationships: { pets: { data: [{ type: 'dog', id: '1' }] }}
+*   },
+*   included: [
+*     {
+*       type: 'dog',
+*       id: '1',
+*       attributes: { name: 'Rey' },
+*       relationships: { owner: { data: { type: 'user', id: '1' }}}
+*     }
+*   ]
+* }
+* ```
+*
+* We could describe the `'user'` and `'dog'` resources in the above payload
+* with the following schemas:
+*
+* ```ts
+* store.schema.registerResources([
+*   {
+*     type: 'user',
+*     identity: { type: '@id', name: 'id' },
+*     fields: [
+*       {
+*         type: '@identity',
+*         name: '$type',
+*         kind: 'derived',
+*         options: { key: 'type' },
+*       },
+*       { kind: 'field', name: 'firstName' },
+*       { kind: 'field', name: 'lastName' },
+*       {
+*         kind: 'derived',
+*         name: 'name',
+*         type: 'concat',
+*         options: { fields: ['firstName', 'lastName'], separator: ' ' }
+*       },
+*       {
+*         kind: 'hasMany',
+*         name: 'pets',
+*         type: 'pet',
+*         options: {
+*           async: false,
+*           inverse: 'owner',
+*           polymorphic: true,
+*           linksMode: true,
+*         }
+*       }
+*     ]
+*   },
+*   {
+*     type: 'dog',
+*     identity: { type: '@id', name: 'id' },
+*     fields: [
+*       {
+*         type: '@identity',
+*         name: '$type',
+*         kind: 'derived',
+*         options: { key: 'type' },
+*       },
+*       { kind: 'field', name: 'name' },
+*       {
+*         kind: 'belongsTo',
+*         name: 'owner',
+*         type: 'user',
+*         options: {
+*           async: false,
+*           inverse: 'pets',
+*           as: 'pet',
+*           linksMode: true,
+*         }
+*       }
+*     ]
+*   }
+* ]);
+* ```
+*
+* With these schemas in place, the reactive objects that the store would
+* provide us whenever we encountered a `'user'` or a `'dog'` would be:
+*
+* ```ts
+* interface Pet {
+*   readonly id: string;
+*   readonly owner: User;
+* }
+*
+* interface Dog extends Pet {
+*   readonly $type: 'dog';
+*   readonly name: string;
+* }
+*
+* interface EditableUser {
+*   readonly $type: 'user';
+*   readonly id: string;
+*   firstName: string;
+*   lastName: string;
+*   readonly name: string;
+*   pets: Array<Dog | Pet>;
+* }
+*
+* interface User {
+*   readonly $type: 'user';
+*   readonly id: string;
+*   readonly firstName: string;
+*   readonly lastName: string;
+*   readonly name: string;
+*   readonly pets: Readonly<Array<Dog | Pet>>;
+*   [Checkout](): Promise<EditableUser>
+* }>
+* ```
+*
+* Note how based on the schema the reactive object we receive is able to produce
+* `name` on user (despite no name field being in the cache), provide `$type`
+* pulled from the identity of the resource, and flatten the individual attributes
+* and relationships onto the record for easier use.
+*
+* Notice also how we typed this object with `readonly`. This is because while
+* ReactiveResource instances are ***deeply reactive***, they are also ***immutable***.
+*
+* We can mutate a ReactiveResource only be explicitly asking permission to do so, and
+* in the process gaining access to an editable copy. The immutable version will
+* not show any in-process edits made to this editable copy.
+*
+* ```ts
+* import { Checkout } from '@warp-drive/schema-record';
+*
+* const editable = await user[Checkout]();
+* ```
+*
+* ## Utilities
+*
+* ReactiveResource provides a schema builder that simplifies setting up a couple of
+* conventional fields like identity and `$type`. We can rewrite the schema
+* definition above using this utility like so:
+*
+* ```ts
+* import { withDefaults } from '@warp-drive/core/reactive';
+*
+* store.schema.registerResources([
+*   withDefaults({
+*     type: 'user',
+*     fields: [
+*       { kind: 'field', name: 'firstName' },
+*       { kind: 'field', name: 'lastName' },
+*       {
+*         kind: 'derived',
+*         name: 'name',
+*         type: 'concat',
+*         options: { fields: ['firstName', 'lastName'], separator: ' ' }
+*       },
+*       {
+*         kind: 'hasMany',
+*         name: 'pets',
+*         type: 'pet',
+*         options: {
+*           async: false,
+*           inverse: 'owner',
+*           polymorphic: true,
+*           linksMode: true,
+*           resetOnRemoteUpdate: false,
+*         }
+*       }
+*     ]
+*   }),
+*   withDefaults({
+*     type: 'dog',
+*     fields: [
+*       { kind: 'field', name: 'name' },
+*       {
+*         kind: 'belongsTo',
+*         name: 'owner',
+*         type: 'user',
+*         options: {
+*           async: false,
+*           inverse: 'pets',
+*           as: 'pet',
+*           linksMode: true,
+*           resetOnRemoteUpdate: false,
+*         }
+*       }
+*     ]
+*   })
+* ]);
+* ```
+*
+* ## Type Support
+*
+* ### Resource Schemas
+*
+* - {@link PolarisResourceSchema}
+* - {@link LegacyResourceSchema}
+* - {@link ObjectSchema}
+*
+* ### Resource Schema Type Utils
+*
+* - {@link resourceSchema}
+* - {@link objectSchema}
+* - {@link isResourceSchema}
+* - {@link isLegacyResourceSchema}
+*
+* ### Field Schemas
+*
+* - {@link LegacyModeFieldSchema}
+* - {@link PolarisModeFieldSchema}
+*
+* @module
+*/
+import { checkout } from "./reactive/-private/record.js";
 export { instantiateRecord, teardownRecord } from "./reactive/-private/hooks.js";
 export { type CAUTION_MEGA_DANGER_ZONE_Extension, type ProcessedExtension, type ExtensionDef, type Transformation, SchemaService, withDefaults, fromIdentity, registerDerivations } from "./reactive/-private/schema.js";
-export { type ReactiveResource } from "./reactive/-private/record.js";
+export { commit, type ReactiveResource } from "./reactive/-private/record.js";
+export { checkout };
 export { Checkout } from "./reactive/-private/symbols.js";
 export { type ReactiveDocument } from "./reactive/-private/document.js";
+export { getExpensiveRequestSubscription } from "./store/-private/new-core-tmp/expensive-subscription.js";

package/declarations/request/-private/context.d.ts

@@ -1,4 +1,4 @@
-import type { StableDocumentIdentifier } from "../../types/identifier.js";
+import type { RequestKey } from "../../types/identifier.js";
 import type { ImmutableHeaders, ImmutableRequestInfo, RequestInfo, ResponseInfo } from "../../types/request.js";
 import type { DeferredStream, GodContext } from "./types.js";
 export declare function upgradeHeaders(headers: Headers | ImmutableHeaders): ImmutableHeaders;
@@ -26,16 +26,14 @@ export declare class ContextOwner {
 	setResponse(response: ResponseInfo | Response | null): void;
 }
 export declare class Context {
-	#private;
 	request: ImmutableRequestInfo;
 	id: number;
-	private _isCacheHandler;
-	private _finalized;
 	constructor(owner: ContextOwner, isCacheHandler: boolean);
 	setStream(stream: ReadableStream | Promise<ReadableStream | null>): void;
 	setResponse(response: ResponseInfo | Response | null): void;
-	setIdentifier(identifier: StableDocumentIdentifier): void;
+	setIdentifier(identifier: RequestKey): void;
 	get hasRequestedStream(): boolean;
+	/** @private */
 	_finalize(): void;
 }
 export type HandlerRequestContext = Context;

package/declarations/request/-private/fetch.d.ts

@@ -1,6 +1,6 @@
 import { type Context } from "./context.js";
-import type { HttpErrorProps } from "./utils.js";
-export type { HttpErrorProps };
+import type { FetchError } from "./utils.js";
+export type { FetchError };
 interface FastbootRequest extends Request {
 	protocol: string;
 	host: string;

package/declarations/request/-private/manager.d.ts

@@ -1,5 +1,5 @@
-import type { StableDocumentIdentifier } from "../../types/identifier.js";
-import type { RequestInfo } from "../../types/request.js";
+import type { RequestKey } from "../../types/identifier.js";
+import { type RequestInfo } from "../../types/request.js";
 import type { CacheHandler, Future, GenericCreateArgs, Handler, ManagedRequestPriority } from "./types.js";
 import { IS_CACHE_HANDLER } from "./utils.js";
 /**
@@ -90,27 +90,9 @@ import { IS_CACHE_HANDLER } from "./utils.js";
 * type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument;
 * ```
 *
-* @class RequestManager
 * @public
 */
 export declare class RequestManager {
-	#private;
-	/** @internal */
-	_hasCacheHandler: boolean;
-	/**
-	* A map of pending requests from request.id to their
-	* associated CacheHandler promise.
-	*
-	* This queue is managed by the CacheHandler
-	*
-	* @internal
-	*/
-	_pending: Map<number, Promise<unknown>>;
-	/** @internal */
-	_deduped: Map<StableDocumentIdentifier, {
-		priority: ManagedRequestPriority;
-		promise: Promise<unknown>;
-	}>;
 	constructor(options?: GenericCreateArgs);
 	/**
 	* Register a handler to use for primary cache intercept.
@@ -132,8 +114,6 @@ export declare class RequestManager {
 	* curry the request, or pass along a modified request.
 	*
 	* @public
-	* @param {Handler[]} newHandlers
-	* @return {ThisType}
 	*/
 	use(newHandlers: Handler[]): this;
 	/**
@@ -142,13 +122,8 @@ export declare class RequestManager {
 	* Returns a Future that fulfills with a StructuredDocument
 	*
 	* @public
-	* @param {RequestInfo} request
-	* @return {Future}
 	*/
-	request<
-		RT,
-		T = unknown
-	>(request: RequestInfo<RT, T>): Future<RT>;
+	request<RT>(request: RequestInfo<RT>): Future<RT>;
 	/**
 	* This method exists so that the RequestManager can be created
 	* can be created by container/factory systems that expect to
@@ -160,3 +135,24 @@ export declare class RequestManager {
 	*/
 	static create(options?: GenericCreateArgs): RequestManager;
 }
+/**
+* This type exists for internal use only for
+* where intimate contracts still exist either for
+* the Test Suite or for Legacy code.
+*
+* @private
+*/
+export interface PrivateRequestManager extends RequestManager {
+	/**
+	* A map of pending requests from request.id to their
+	* associated CacheHandler promise.
+	*
+	* This queue is managed by the CacheHandler
+	*
+	*/
+	_pending: Map<number, Promise<unknown>>;
+	_deduped: Map<RequestKey, {
+		priority: ManagedRequestPriority;
+		promise: Promise<unknown>;
+	}>;
+}

package/declarations/request/-private/types.d.ts

@@ -1,13 +1,15 @@
-/* eslint-disable no-irregular-whitespace */
-import type { StableDocumentIdentifier } from "../../types/identifier.js";
-import type { IS_FUTURE, RequestContext, RequestInfo, ResponseInfo, StructuredDataDocument } from "../../types/request.js";
+import type { Store } from "../../store/-private.js";
+import type { RequestKey } from "../../types/identifier.js";
+import type { RequestContext, RequestInfo, ResponseInfo, StructuredDataDocument } from "../../types/request.js";
+import type { RequestManager } from "./manager.js";
 export interface GodContext {
 	controller: AbortController;
 	response: ResponseInfo | null;
 	stream: ReadableStream | Promise<ReadableStream | null> | null;
 	hasRequestedStream: boolean;
 	id: number;
-	identifier: StableDocumentIdentifier | null;
+	identifier: RequestKey | null;
+	requester: RequestManager | Store;
 }
 export type Deferred<T> = {
 	resolve(v: T): void;
@@ -32,10 +34,12 @@ export type DeferredStream = {
 * @public
 */
 export interface Future<T> extends Promise<StructuredDataDocument<T>> {
-	[IS_FUTURE]: true;
 	/**
 	* Cancel this request by firing the {@link AbortController}'s signal.
 	*
+	* This method can be used as an action or event handler as its
+	* context is bound to the Future instance.
+	*
 	* @privateRemarks
 	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/abort)
 	*
@@ -46,8 +50,10 @@ export interface Future<T> extends Promise<StructuredDataDocument<T>> {
 	/**
 	* Get the response stream, if any, once made available.
 	*
+	* This method can be used as an action or event handler as its
+	* context is bound to the Future instance.
+	*
 	* @public
-	* @return {Promise<ReadableStream | null>}
 	*/
 	getStream(): Promise<ReadableStream | null>;
 	/**
@@ -55,28 +61,27 @@ export interface Future<T> extends Promise<StructuredDataDocument<T>> {
 	*  mostly useful for instrumentation and infrastructure.
 	*
 	* @param cb the callback to run
-	* @public
-	* @return {void}
 	*/
 	onFinalize(cb: () => void): void;
 	/**
 	* The identifier of the associated request, if any, as
 	* assigned by the CacheHandler.
-	*
-	* @property lid
-	* @type {StableDocumentIdentifier | null}
-	* @public
 	*/
-	lid: StableDocumentIdentifier | null;
+	lid: RequestKey | null;
 	/**
 	* The id of the associated request, if any, as assigned
 	* by the RequestManager
 	*
-	* @property id
-	* @type {Number}
-	* @public
+	* This is not unique across Manager instances and cannot
+	* be used to identify or dedupe requests.
 	*/
 	id: number;
+	/**
+	* The RequestManager or Store that initiated this request.
+	*
+	* @private
+	*/
+	requester: RequestManager | Store;
 }
 export type DeferredFuture<T> = {
 	resolve(v: StructuredDataDocument<T>): void;
@@ -191,8 +196,6 @@ const manager = new RequestManager()
 
 Handlers will be invoked in the order they are registered ("fifo", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.
 
-
-@class (Interface) Handler
 @public
 */
 export interface Handler {
@@ -202,20 +205,17 @@ export interface Handler {
 	* other handlers.
 	*
 	* @public
-	* @param context
-	* @param next
 	*/
 	request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T>;
 }
 /**
-* The CacheHandler is identical to other handlers ecxept that it
+* The CacheHandler is identical to other handlers except that it
 * is allowed to return a value synchronously. This is useful for
 * features like reducing microtask queueing when de-duping.
 *
 * A RequestManager may only have one CacheHandler, registered via
 * `manager.useCache(CacheHandler)`.
 *
-* @class (Interface) CacheHandler
 * @public
 */
 export interface CacheHandler {
@@ -225,8 +225,6 @@ export interface CacheHandler {
 	* other handlers.
 	*
 	* @public
-	* @param context
-	* @param next
 	*/
 	request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T> | T;
 }

package/declarations/request/-private/utils.d.ts

@@ -3,12 +3,54 @@ import { ContextOwner } from "./context.js";
 import type { DeferredFuture, Future, GodContext, Handler } from "./types.js";
 export declare const IS_CACHE_HANDLER: "___(unique) Symbol(IS_CACHE_HANDLER)";
 export declare function curryFuture<T>(owner: ContextOwner, inbound: Future<T>, outbound: DeferredFuture<T>): Future<T>;
-export interface HttpErrorProps extends DOMException {
+/**
+* Additional properties exposed on errors thrown by the
+* {@link Fetch | Fetch Handler}.
+*
+* In the case of an Abort or system/browser level issue,
+* this extends {@link DOMException}.
+*
+* Else it extends from {@link AggregateError} if the
+* response includes an array of errors, falling back
+* to {@link Error} as its base.
+*/
+export interface FetchError extends DOMException {
+	/**
+	* Alias for {@link FetchError.status | status}.
+	*
+	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/status)
+	*/
 	code: number;
+	/**
+	* The name associated to the {@link FetchError.status | status code}.
+	*
+	* Typically this will be of the formula `StatusTextError` for instance
+	* a 404 status with status text of `Not Found` would have the name
+	* `NotFoundError`.
+	*/
 	name: string;
+	/**
+	* The http status code associated to the returned error.
+	*
+	* Browser/System level network errors will often have an error code of `0` or `5`.
+	* Aborted requests will have an error code of `20`.
+	*
+	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/status)
+	*/
 	status: number;
+	/**
+	* The Status Text associated to the {@link FetchError.status | status code}
+	* for the error.
+	*
+	* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/statusText)
+	*
+	*/
 	statusText: string;
-	isRequestError: boolean;
+	/**
+	* A property signifying that an Error uses the {@link FetchError}
+	* interface.
+	*/
+	isRequestError: true;
 }
 export declare function enhanceReason(reason?: string): DOMException;
 export declare function handleOutcome<T>(owner: ContextOwner, inbound: Promise<T | StructuredDataDocument<T>>, outbound: DeferredFuture<T>): Future<T>;

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

@@ -3,17 +3,11 @@ import type { ImmutableRequestInfo, RequestContext } from "../../../types/reques
 import type { ResourceIdentifierObject } from "../../../types/spec/json-api-raw.js";
 import type { RequestSignature } from "../../../types/symbols.js";
 import type { Store } from "../store-service.js";
-export type LooseStoreRequestInfo<
-	RT = unknown,
-	T = unknown
-> = Omit<ImmutableRequestInfo<RT, T>, "records" | "headers" | typeof RequestSignature> & {
+export type LooseStoreRequestInfo<RT = unknown> = Omit<ImmutableRequestInfo<RT>, "records" | "headers" | typeof RequestSignature> & {
 	records?: ResourceIdentifierObject[];
 	headers?: Headers;
 };
-export type StoreRequestInput<
-	RT = unknown,
-	T = unknown
-> = ImmutableRequestInfo<RT, T> | LooseStoreRequestInfo<RT, T>;
+export type StoreRequestInput<RT = unknown> = ImmutableRequestInfo<RT> | LooseStoreRequestInfo<RT>;
 export interface StoreRequestContext extends RequestContext {
 	request: ImmutableRequestInfo & {
 		store: Store;

package/declarations/store/-private/cache-handler/types.d.ts

@@ -1,4 +1,4 @@
-import type { StableDocumentIdentifier } from "../../../types/identifier.js";
+import type { RequestKey } from "../../../types/identifier.js";
 import type { ImmutableRequestInfo, ResponseInfo } from "../../../types/request.js";
 import type { Store } from "../store-service.js";
 /**
@@ -27,11 +27,11 @@ export interface CachePolicy {
 	* and the cache will be updated before returning the response.
 	*
 	* @public
-	* @param {StableDocumentIdentifier} identifier
+	* @param {RequestKey} identifier
 	* @param {Store} store
 	* @return {Boolean} true if the request is considered hard expired
 	*/
-	isHardExpired(identifier: StableDocumentIdentifier, store: Store): boolean;
+	isHardExpired(identifier: RequestKey, store: Store): boolean;
 	/**
 	* Invoked if `isHardExpired` is false to determine if the request
 	* should be update behind the scenes if cache data is already available.
@@ -42,11 +42,11 @@ export interface CachePolicy {
 	* request is made to update the cache via the configured request handlers.
 	*
 	* @public
-	* @param {StableDocumentIdentifier} identifier
+	* @param {RequestKey} identifier
 	* @param {Store} store
 	* @return {Boolean} true if the request is considered soft expired
 	*/
-	isSoftExpired(identifier: StableDocumentIdentifier, store: Store): boolean;
+	isSoftExpired(identifier: RequestKey, store: Store): boolean;
 	/**
 	* Invoked when a request will be sent to the configured request handlers.
 	* This is invoked for both foreground and background requests.
@@ -55,11 +55,11 @@ export interface CachePolicy {
 	*
 	* @public
 	* @param {ImmutableRequestInfo} request
-	* @param {StableDocumentIdentifier | null} identifier
+	* @param {RequestKey | null} identifier
 	* @param {Store} store
 	* @return {void}
 	*/
-	willRequest?(request: ImmutableRequestInfo, identifier: StableDocumentIdentifier | null, store: Store): void;
+	willRequest?(request: ImmutableRequestInfo, identifier: RequestKey | null, store: Store): void;
 	/**
 	* Invoked when a request has been fulfilled from the configured request handlers.
 	* This is invoked for both foreground and background requests once the cache has
@@ -71,7 +71,7 @@ export interface CachePolicy {
 	* so that request subscriptions can reload when needed.
 	*
 	* ```ts
-	* store.notifications.notify(identifier, 'invalidated');
+	* store.notifications.notify(identifier, 'invalidated', null);
 	* ```
 	*
 	* This allows anything subscribed to the request to be notified of the change
@@ -90,9 +90,9 @@ export interface CachePolicy {
 	* @public
 	* @param {ImmutableRequestInfo} request
 	* @param {ImmutableResponse} response
-	* @param {StableDocumentIdentifier | null} identifier
+	* @param {RequestKey | null} identifier
 	* @param {Store} store
 	* @return {void}
 	*/
-	didRequest?(request: ImmutableRequestInfo, response: Response | ResponseInfo | null, identifier: StableDocumentIdentifier | null, store: Store): void;
+	didRequest?(request: ImmutableRequestInfo, response: Response | ResponseInfo | null, identifier: RequestKey | null, store: Store): void;
 }