@warp-drive/core 5.9.0-beta.0 → 5.9.0-beta.2

package/declarations/reactive.d.ts

@@ -1,286 +0,0 @@
-/**
-* # 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 { createRequestSubscription, getRequestState, type RequestSubscription, type RequestLoadingState, type RequestState } from "./signals/-private.js";
-export { getPromiseState, type PromiseState, type ResolvedPromise, type RejectedPromise, type PendingPromise } from "./signals/-private.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/declarations/request/-private/context.d.ts

@@ -1,39 +0,0 @@
-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/declarations/request/-private/debug.d.ts

@@ -1,4 +0,0 @@
-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/declarations/request/-private/fetch.d.ts

@@ -1,33 +0,0 @@
-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/declarations/request/-private/future.d.ts

@@ -1,7 +0,0 @@
-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/declarations/request/-private/manager.d.ts

@@ -1,158 +0,0 @@
-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/declarations/request/-private/promise-cache.d.ts

@@ -1,28 +0,0 @@
-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;