@warp-drive/core 5.8.0-alpha.30 → 5.8.0-alpha.34

package/dist/unpkg/dev/declarations/reactive.d.ts

@@ -0,0 +1,287 @@
+/**
+* # 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/configuration/)
+* - For defining resource schemas, see [The Schema Guide](/guides/the-manual/schemas/)
+*
+* 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](/guides/the-manual/misc/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](/guides/the-manual/misc/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 {@link @warp-drive/json-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 { commit, type ReactiveResource } from "./reactive/-private/record.js";
+export { checkout };
+export { Checkout } from "./reactive/-private/symbols.js";
+export { type ReactiveDocument, type ReactiveDataDocument, type ReactiveErrorDocument } from "./reactive/-private/document.js";
+export { getExpensiveRequestSubscription } from "./store/-private/new-core-tmp/expensive-subscription.js";
+export { createRequestSubscription, getRequestState, type RequestState } from "./store/-private.js";
+export { getPromiseState, type PromiseState, type ResolvedPromise, type RejectedPromise, type PendingPromise } from "./store/-private/new-core-tmp/promise-state.js";
+export type { LegacyLiveArray } from "./store/-private/record-arrays/legacy-live-array.js";
+export type { LegacyManyArray } from "./store/-private/record-arrays/legacy-many-array.js";
+export type { LegacyQueryArray } from "./store/-private/record-arrays/legacy-query.js";
+export type { ReactiveResourceArray } from "./store/-private/record-arrays/resource-array.js";

package/dist/unpkg/dev/declarations/request/-private/context.d.ts

@@ -0,0 +1,39 @@
+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;
+export declare function cloneResponseProperties(response: Response): ResponseInfo;
+export declare class ContextOwner {
+	hasSetStream: boolean;
+	hasSetResponse: boolean;
+	hasSubscribers: boolean;
+	stream: DeferredStream;
+	response: ResponseInfo | null;
+	request: ImmutableRequestInfo;
+	enhancedRequest: ImmutableRequestInfo;
+	nextCalled: number;
+	god: GodContext;
+	controller: AbortController;
+	requestId: number;
+	isRoot: boolean;
+	constructor(request: RequestInfo, god: GodContext, isRoot?: boolean);
+	get hasRequestedStream(): boolean;
+	getResponse(): ResponseInfo | null;
+	getStream(): Promise<ReadableStream | null>;
+	abort(reason: DOMException): void;
+	setStream(stream: ReadableStream | Promise<ReadableStream | null> | null): void;
+	resolveStream(): void;
+	setResponse(response: ResponseInfo | Response | null): void;
+}
+export declare class Context {
+	request: ImmutableRequestInfo;
+	id: number;
+	constructor(owner: ContextOwner, isCacheHandler: boolean);
+	setStream(stream: ReadableStream | Promise<ReadableStream | null>): void;
+	setResponse(response: ResponseInfo | Response | null): void;
+	setIdentifier(identifier: RequestKey): void;
+	get hasRequestedStream(): boolean;
+	/** @private */
+	_finalize(): void;
+}
+export type HandlerRequestContext = Context;

package/dist/unpkg/dev/declarations/request/-private/debug.d.ts

@@ -0,0 +1,4 @@
+import type { RequestInfo } from "../../types/request.js";
+import { Context } from "./context.js";
+export declare function deepFreeze<T = unknown>(value: T): T;
+export declare function assertValidRequest(request: RequestInfo | Context, isTopLevel: boolean): asserts request is RequestInfo;

package/dist/unpkg/dev/declarations/request/-private/fetch.d.ts

@@ -0,0 +1,33 @@
+import { type Context } from "./context.js";
+import type { FetchError } from "./utils.js";
+export type { FetchError };
+interface FastbootRequest extends Request {
+	protocol: string;
+	host: string;
+}
+export interface FastBoot {
+	require(moduleName: string): unknown;
+	isFastBoot: boolean;
+	request: FastbootRequest;
+}
+/**
+* ```ts
+* import { Fetch } from '@warp-drive/core';
+* ```
+*
+* A basic Fetch Handler which converts a request into a
+* `fetch` call presuming the response to be `json`.
+*
+* ```ts
+* import { RequestManager, Fetch } from '@warp-drive/core';
+*
+* const manager = new RequestManager()
+*   .use([Fetch]);
+* ```
+*
+* @public
+*/
+declare const Fetch: {
+	request<T>(context: Context): Promise<T>;
+};
+export { Fetch };

package/dist/unpkg/dev/declarations/request/-private/future.d.ts

@@ -0,0 +1,7 @@
+import { type StructuredDocument } from "../../types/request.js";
+import type { ContextOwner } from "./context.js";
+import type { Deferred, DeferredFuture, Future } from "./types.js";
+export declare function isFuture<T>(maybe: unknown): maybe is Future<T>;
+export declare function createDeferred<T>(): Deferred<T>;
+export declare function upgradePromise<T>(promise: Promise<StructuredDocument<T>>, future: Future<T>): Future<T>;
+export declare function createFuture<T>(owner: ContextOwner): DeferredFuture<T>;

package/dist/unpkg/dev/declarations/request/-private/manager.d.ts

@@ -0,0 +1,158 @@
+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";
+/**
+* ## Import
+*
+* ```js
+* import { RequestManager } from '@warp-drive/core';
+* ```
+*
+* For complete usage guide see the [RequestManager Documentation](/guides/).
+*
+* ## How It Works
+*
+* ```ts
+* interface RequestManager {
+*   request<T>(req: RequestInfo): Future<T>;
+* }
+* ```
+*
+* A RequestManager provides a request/response flow in which configured
+* handlers are successively given the opportunity to handle, modify, or
+* pass-along a request.
+*
+* <img src="/images/handlers-all-labeled.gif" alt="RequestManager Flow Animation" width="100%" />
+*
+* For example:
+*
+* ::: code-group
+*
+* ```ts [Setup.ts]
+* import { RequestManager, Fetch } from '@warp-drive/core';
+* import { AutoCompress } from '@warp-drive/utilities/handlers';
+* import Auth from 'ember-simple-auth/handler';
+*
+* // ... create manager
+* const manager = new RequestManager()
+*    .use([Auth, new AutoCompress(), Fetch]); // [!code focus]
+* ```
+*
+* ```ts [Usage.ts]
+* import Config from './config';
+*
+* const { apiUrl } = Config;
+*
+* // ... execute a request
+* const response = await manager.request({
+*   url: `${apiUrl}/users`
+* });
+* ```
+*
+* :::
+*
+* ### Futures
+*
+* The return value of `manager.request` is a `Future`, which allows
+* access to limited information about the request while it is still
+* pending and fulfills with the final state when the request completes.
+*
+* A `Future` is cancellable via `abort`.
+*
+* Handlers may optionally expose a `ReadableStream` to the `Future` for
+* streaming data; however, when doing so the future should not resolve
+* until the response stream is fully read.
+*
+* ```ts
+* interface Future<T> extends Promise<StructuredDocument<T>> {
+*   abort(): void;
+*
+*   async getStream(): ReadableStream | null;
+* }
+* ```
+*
+* ### StructuredDocuments
+*
+* A Future resolves with a `StructuredDataDocument` or rejects with a `StructuredErrorDocument`.
+*
+* ```ts
+* interface StructuredDataDocument<T> {
+*   request: ImmutableRequestInfo;
+*   response: ImmutableResponseInfo;
+*   content: T;
+* }
+* interface StructuredErrorDocument extends Error {
+*   request: ImmutableRequestInfo;
+*   response: ImmutableResponseInfo;
+*   error: string | object;
+* }
+* type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument;
+* ```
+*
+* @public
+*/
+export declare class RequestManager {
+	constructor(options?: GenericCreateArgs);
+	/**
+	* Register a handler to use for primary cache intercept.
+	*
+	* Only one such handler may exist. If using the same
+	* RequestManager as the Store instance the Store
+	* registers itself as a Cache handler.
+	*
+	* @public
+	*/
+	useCache(cacheHandler: CacheHandler & {
+		[IS_CACHE_HANDLER]?: true;
+	}): this;
+	/**
+	* Register handler(s) to use when a request is issued.
+	*
+	* Handlers will be invoked in the order they are registered.
+	* Each Handler is given the opportunity to handle the request,
+	* curry the request, or pass along a modified request.
+	*
+	* @public
+	*/
+	use(newHandlers: Handler[]): this;
+	/**
+	* Issue a Request.
+	*
+	* Returns a Future that fulfills with a StructuredDocument
+	*
+	* @public
+	*/
+	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
+	* call a static `create` method to instantiate the class.
+	*
+	* Using `new RequestManager()` directly is preferred.
+	*
+	* @private
+	*/
+	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/dist/unpkg/dev/declarations/request/-private/promise-cache.d.ts

@@ -0,0 +1,28 @@
+export type CacheResult<
+	T = unknown,
+	E = unknown
+> = {
+	isError: true;
+	result: E;
+} | {
+	isError: false;
+	result: T;
+};
+export type Awaitable<
+	T = unknown,
+	E = unknown
+> = {
+	then: (onFulfilled: (value: T) => unknown, onRejected: (reason: E) => unknown) => unknown;
+	catch: (onRejected: (reason: E) => unknown) => unknown;
+	finally: (onFinally: () => unknown) => unknown;
+};
+export declare const PromiseCache: WeakMap<Awaitable, CacheResult>;
+export declare const RequestMap: Map<number, CacheResult>;
+export declare function setRequestResult(requestId: number, result: CacheResult): void;
+export declare function clearRequestResult(requestId: number): void;
+export declare function getRequestResult(requestId: number): CacheResult | undefined;
+export declare function setPromiseResult(promise: Promise<unknown> | Awaitable, result: CacheResult): void;
+export declare function getPromiseResult<
+	T,
+	E
+>(promise: Promise<T> | Awaitable<T, E>): CacheResult<T, E> | undefined;