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

package/declarations/signals/request-state.d.ts

@@ -1,372 +0,0 @@
-import type { Future } from "../request.js";
-import type { ImmutableRequestInfo, ResponseInfo, StructuredErrorDocument } from "../types/request.js";
-import type { PendingPromise, RejectedPromise, ResolvedPromise } from "./promise-state.js";
-/**
-* Lazily consumes the stream of a request, providing a number of
-* reactive properties that can be used to build UIs that respond
-* to the progress of a request.
-*
-* @hideconstructor
-*/
-export declare class RequestLoadingState {
-	promise: Promise<void> | null;
-	get isPending(): boolean;
-	get sizeHint(): number;
-	get stream(): ReadableStream | null;
-	get isStarted(): boolean;
-	get bytesLoaded(): number;
-	get startTime(): number;
-	get endTime(): number;
-	get lastPacketTime(): number;
-	get isComplete(): boolean;
-	get isCancelled(): boolean;
-	get isErrored(): boolean;
-	get error(): Error | null;
-	get elapsedTime(): number;
-	get completedRatio(): number;
-	get remainingRatio(): number;
-	get duration(): number;
-	get speed(): number;
-	constructor(future: Future<unknown>);
-	abort: () => void;
-}
-/**
-* The state of a request in the "pending"
-* state. This is the default initial state.
-*
-* Extends the {@link PendingPromise} interface.
-*
-*/
-export interface PendingRequest extends PendingPromise {
-	/**
-	* Whether the request is cancelled.
-	*
-	*/
-	isCancelled: false;
-	loadingState: RequestLoadingState;
-	request: null;
-	response: null;
-}
-/**
-* The state of a request in the "fulfilled" state.
-* This is the state of a request that has resolved
-* successfully.
-*
-* Extends the {@link ResolvedPromise} interface.
-*
-*/
-export interface ResolvedRequest<RT> extends ResolvedPromise<RT> {
-	/**
-	* Retries the request with high (blocking) priority. This is the
-	* same as having passed `cacheOptions.reload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	reload(): Future<RT>;
-	/**
-	* Retries the request with low (non-blocking) priority. This is the
-	* same as having passed `cacheOptions.backgroundReload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	refresh(usePolicy?: boolean): Future<RT>;
-	/**
-	* Whether the request is cancelled.
-	*
-	*/
-	isCancelled: false;
-	/**
-	* A lazily created {@link RequestLoadingState} instance
-	* which provides a number of reactive properties that can be used
-	* to build UIs that respond to the progress of a request.
-	*/
-	loadingState: RequestLoadingState;
-	request: ImmutableRequestInfo<RT> | null;
-	response: Response | ResponseInfo | null;
-}
-/**
-* The state of a request in the "rejected" state.
-* This is the state of a request that has rejected
-* with an error.
-*
-* Extends the {@link RejectedPromise} interface.
-*
-*/
-export interface RejectedRequest<
-	RT,
-	E extends StructuredErrorDocument = StructuredErrorDocument
-> extends RejectedPromise<E> {
-	/**
-	* Retries the request with high (blocking) priority. This is the
-	* same as having passed `cacheOptions.reload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	reload(): Future<RT>;
-	/**
-	* Retries the request with low (non-blocking) priority. This is the
-	* same as having passed `cacheOptions.backgroundReload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	refresh(usePolicy?: boolean): Future<RT>;
-	/**
-	* Whether the request is cancelled.
-	*
-	*/
-	isCancelled: false;
-	loadingState: RequestLoadingState;
-	request: ImmutableRequestInfo<RT> | null;
-	response: Response | ResponseInfo | null;
-}
-/**
-* The state of a request in the "cancelled" state.
-* This is the state of a promise that has been
-* cancelled.
-*
-*/
-export interface CancelledRequest<
-	RT,
-	E extends StructuredErrorDocument = StructuredErrorDocument
-> {
-	/**
-	* Retries the request with high (blocking) priority. This is the
-	* same as having passed `cacheOptions.reload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	reload(): Future<RT>;
-	/**
-	* Retries the request with low (non-blocking) priority. This is the
-	* same as having passed `cacheOptions.backgroundReload = true` on the original
-	* request.
-	*
-	* This will not change the existing request's state. To subscribe
-	* to the new request's state, use `getRequestState` on the returned
-	* {@link Future}.
-	*
-	* ```ts
-	* const future = state.reload();
-	* const state = getRequestState(future);
-	* ```
-	*
-	* It is safe to pass this around as an "action" or "event" handler
-	* as its context is bound.
-	*/
-	refresh(usePolicy?: boolean): Future<RT>;
-	/**
-	* The status of the request.
-	*
-	*/
-	status: "cancelled";
-	/**
-	* Whether the request is pending.
-	*
-	*/
-	isPending: false;
-	/**
-	* Whether the request is pending.
-	*
-	*/
-	isLoading: false;
-	/**
-	* Whether the request has resolved
-	* successfully.
-	*
-	*/
-	isSuccess: false;
-	/**
-	* Whether the request has rejected
-	* with an error.
-	*
-	*/
-	isError: true;
-	/**
-	* Once the request has resolved, this will
-	* be the value the request resolved to.
-	*
-	*/
-	value: null;
-	/**
-	* Once the request has resolved, this will
-	* be the value the request resolved to.
-	*
-	* @deprecated use `value` instead
-	*/
-	result: null;
-	/**
-	* Once the request has rejected, this will
-	* be the error the request rejected with.
-	*
-	*
-	* @deprecated use `reason` instead
-	*/
-	error: E;
-	/**
-	* Once the request has rejected, this will
-	* be the error the request rejected with.
-	*
-	*/
-	reason: E;
-	/**
-	* Whether the request is cancelled.
-	*
-	*/
-	isCancelled: true;
-	loadingState: RequestLoadingState;
-	request: ImmutableRequestInfo<RT> | null;
-	response: Response | ResponseInfo | null;
-}
-export interface PrivateRequestState {
-	_loadingState?: RequestLoadingState;
-	_request: Future<unknown>;
-}
-/**
-* RequestState extends the concept of {@link PromiseState} to provide a reactive
-* wrapper for a request {@link Future} which allows you write declarative code
-* around a Future's control flow.
-*
-* It is useful in both Template and JavaScript contexts, allowing you
-* to quickly derive behaviors and data from pending, error and success
-* states.
-*
-* The key difference between a {@link Promise} and a Future is that Futures provide
-* access to a {@link ReadableStream | stream} of their content, the {@link RequestKey} of the request (if any)
-* as well as the ability to attempt to {@link Future.abort | abort} the request.
-*
-* ```ts
-* interface Future<T> extends Promise<T>> {
-*   getStream(): Promise<ReadableStream>;
-*   abort(): void;
-*   lid: RequestKey | null;
-* }
-* ```
-*
-* These additional APIs allow us to craft even richer state experiences.
-*
-* To get the state of a request, use {@link getRequestState}.
-*
-* See also:
-* - {@link PendingRequest}
-* - {@link ResolvedRequest}
-* - {@link RejectedRequest}
-* - {@link CancelledRequest}
-*
-*/
-export type RequestState<
-	RT = unknown,
-	E extends StructuredErrorDocument = StructuredErrorDocument
-> = PendingRequest | ResolvedRequest<RT> | RejectedRequest<RT, E> | CancelledRequest<RT, E>;
-export declare function createRequestState<
-	RT,
-	E
->(future: Future<RT>): Readonly<RequestState<RT, StructuredErrorDocument<E>>>;
-/**
-* `getRequestState` can be used in both JavaScript and Template contexts.
-*
-* ```ts
-* import { getRequestState } from '@warp-drive/ember';
-*
-* const state = getRequestState(future);
-* ```
-*
-* For instance, we could write a getter on a component that updates whenever
-* the request state advances or the future changes, by combining the function
-* with the use of `@cached`
-*
-* ```ts
-* class Component {
-*   @cached
-*   get title() {
-*     const state = getRequestState(this.args.request);
-*     if (state.isPending) {
-*       return 'loading...';
-*     }
-*     if (state.isError) { return null; }
-*     return state.result.title;
-*   }
-* }
-* ```
-*
-* Or in a template as a helper:
-*
-* ```gjs
-* import { getRequestState } from '@warp-drive/ember';
-*
-* <template>
-*   {{#let (getRequestState @request) as |state|}}
-*     {{#if state.isPending}}
-*       <Spinner />
-*     {{else if state.isError}}
-*       <ErrorForm @error={{state.error}} />
-*     {{else}}
-*       <h1>{{state.result.title}}</h1>
-*     {{/if}}
-*   {{/let}}
-* </template>
-* ```
-*
-* If looking to use in a template, consider also the `<Request />` component
-* which offers a number of additional capabilities for requests *beyond* what
-* `RequestState` provides.
-*
-*/
-export declare function getRequestState<
-	RT,
-	E
->(future: Future<RT>): Readonly<RequestState<RT, StructuredErrorDocument<E>>>;

package/declarations/signals/request-subscription.d.ts

@@ -1,177 +0,0 @@
-import type { RequestManager, Store, StoreRequestInput } from "../index.js";
-import type { Future } from "../request.js";
-import type { StructuredErrorDocument } from "../types/request.js";
-import type { RequestState } from "./request-state.js";
-export declare const DISPOSE: "(symbol) dispose";
-export type AutorefreshBehaviorType = "online" | "interval" | "invalid";
-export type AutorefreshBehaviorCombos = boolean | AutorefreshBehaviorType | `${AutorefreshBehaviorType},${AutorefreshBehaviorType}` | `${AutorefreshBehaviorType},${AutorefreshBehaviorType},${AutorefreshBehaviorType}`;
-/**
-* Utilities to assist in recovering from the error.
-*/
-export interface RecoveryFeatures {
-	isOnline: boolean;
-	isHidden: boolean;
-	retry: () => Promise<void>;
-}
-/** @deprecated use {@link RecoveryFeatures} */
-export type ErrorFeatures = RecoveryFeatures;
-/**
-* Utilities for keeping the request fresh
-*/
-export interface ContentFeatures<RT> {
-	isOnline: boolean;
-	isHidden: boolean;
-	isRefreshing: boolean;
-	refresh: () => Promise<void>;
-	reload: () => Promise<void>;
-	abort?: () => void;
-	latestRequest?: Future<RT>;
-}
-export interface RequestArgs<
-	RT,
-	E
-> extends SubscriptionArgs<RT, E> {
-	subscription?: RequestSubscription<RT, E>;
-	/**
-	* The store instance to use for making requests. If contexts are available,
-	* the component will default to using the `store` on the context.
-	*
-	* This is required if the store is not available via context or should be
-	* different from the store provided via context.
-	*
-	*/
-	store?: Store | RequestManager;
-}
-export interface SubscriptionArgs<
-	RT,
-	E
-> {
-	/**
-	* The request to monitor. This should be a `Future` instance returned
-	* by either the `store.request` or `store.requestManager.request` methods.
-	*
-	*/
-	request?: Future<RT> | undefined | null;
-	/**
-	* A query to use for the request. This should be an object that can be
-	* passed to `store.request`. Use this in place of `@request` if you would
-	* like the component to also initiate the request.
-	*
-	*/
-	query?: StoreRequestInput<RT> | undefined | null;
-	/**
-	* The autorefresh behavior for the request. This can be a boolean, or any
-	* combination of the following values: `'online'`, `'interval'`, `'invalid'`.
-	*
-	* - `'online'`: Refresh the request when the browser comes back online
-	* - `'interval'`: Refresh the request at a specified interval
-	* - `'invalid'`: Refresh the request when the store emits an invalidation
-	*
-	* If `true`, this is equivalent to `'online,invalid'`.
-	*
-	* Defaults to `false`.
-	*
-	*/
-	autorefresh?: AutorefreshBehaviorCombos;
-	/**
-	* The number of milliseconds to wait before refreshing the request when the
-	* browser comes back online or the network becomes available.
-	*
-	* This also controls the interval at which the request will be refreshed if
-	* the `interval` autorefresh type is enabled.
-	*
-	* Defaults to `30_000` (30 seconds).
-	*
-	*/
-	autorefreshThreshold?: number;
-	/**
-	* The behavior of the request initiated by autorefresh. This can be one of
-	* the following values:
-	*
-	* - `'refresh'`: Refresh the request in the background
-	* - `'reload'`: Force a reload of the request
-	* - `'policy'` (**default**): Let the store's configured CachePolicy decide whether to
-	*    reload, refresh, or do nothing.
-	*
-	* Defaults to `'policy'`.
-	*
-	*/
-	autorefreshBehavior?: "refresh" | "reload" | "policy";
-}
-export interface RequestComponentArgs<
-	RT,
-	E
-> extends SubscriptionArgs<RT, E> {
-	/**
-	* The store instance to use for making requests. If contexts are available,
-	* the component will default to using the `store` on the context.
-	*
-	* This is required if the store is not available via context or should be
-	* different from the store provided via context.
-	*
-	*/
-	store?: Store | RequestManager;
-}
-export interface RequestSubscription<
-	RT,
-	E
-> {
-	/**
-	* The method to call when the component this subscription is attached to
-	* unmounts.
-	*/
-	[DISPOSE](): void;
-}
-/**
-* A reactive class
-*
-* @hideconstructor
-*/
-export declare class RequestSubscription<
-	RT,
-	E
-> {
-	/**
-	* Whether the browser reports that the network is online.
-	*/
-	isOnline: boolean;
-	/**
-	* Whether the browser reports that the tab is hidden.
-	*/
-	isHidden: boolean;
-	/**
-	* Whether the component is currently refreshing the request.
-	*/
-	isRefreshing: boolean;
-	/**
-	* The Store this subscription subscribes to or the RequestManager
-	* which issues this request.
-	*/
-	store: Store | RequestManager;
-	constructor(store: Store | RequestManager, args: SubscriptionArgs<RT, E>);
-	get isIdle(): boolean;
-	get autorefreshTypes(): Set<AutorefreshBehaviorType>;
-	/**
-	* Retry the request, reloading it from the server.
-	*/
-	retry: () => Promise<void>;
-	/**
-	* Refresh the request, updating it in the background.
-	*/
-	refresh: () => Promise<void>;
-	/**
-	* features to yield to the error slot of a component
-	*/
-	get errorFeatures(): RecoveryFeatures;
-	/**
-	* features to yield to the content slot of a component
-	*/
-	get contentFeatures(): ContentFeatures<RT>;
-	get request(): Future<RT>;
-	get reqState(): RequestState<RT, StructuredErrorDocument<E>>;
-	get result(): RT;
-}
-export declare function createRequestSubscription<
-	RT,
-	E
->(store: Store | RequestManager, args: SubscriptionArgs<RT, E>): RequestSubscription<RT, E>;

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

@@ -1,56 +0,0 @@
-import type { CacheHandler as CacheHandlerType } from "../../../request.js";
-import type { ImmutableRequestInfo, RequestContext } from "../../../types/request.js";
-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> = Omit<ImmutableRequestInfo<RT>, "records" | "headers" | typeof RequestSignature> & {
-	records?: ResourceIdentifierObject[];
-	headers?: Headers;
-};
-export type StoreRequestInput<RT = unknown> = ImmutableRequestInfo<RT> | LooseStoreRequestInfo<RT>;
-export interface StoreRequestContext extends RequestContext {
-	request: ImmutableRequestInfo & {
-		store: Store;
-	};
-}
-/**
-* A CacheHandler that adds support for using an WarpDrive Cache with a RequestManager.
-*
-* This handler will only run when a request has supplied a `store` instance. Requests
-* issued by the store via `store.request()` will automatically have the `store` instance
-* attached to the request.
-*
-* ```ts
-* requestManager.request({
-*   store: store,
-*   url: '/api/posts',
-*   method: 'GET'
-* });
-* ```
-*
-* When this handler elects to handle a request, it will return the raw `StructuredDocument`
-* unless the request has `[EnableHydration]` set to `true`. In this case, the handler will
-* return a `Document` instance that will automatically update the UI when the cache is updated
-* in the future and will hydrate any identifiers in the StructuredDocument into Record instances.
-*
-* When issuing a request via the store, [EnableHydration] is automatically set to `true`. This
-* means that if desired you can issue requests that utilize the cache without needing to also
-* utilize Record instances if desired.
-*
-* Said differently, you could elect to issue all requests via a RequestManager, without ever using
-* the store directly, by setting [EnableHydration] to `true` and providing a store instance. Not
-* necessarily the most useful thing, but the decoupled nature of the RequestManager and incremental-feature
-* approach of WarpDrive allows for this flexibility.
-*
-* ```ts
-* import { EnableHydration } from '@warp-drive/core/types/request';
-*
-* requestManager.request({
-*   store: store,
-*   url: '/api/posts',
-*   method: 'GET',
-*   [EnableHydration]: true
-* });
-*
-*/
-export declare const CacheHandler: CacheHandlerType;

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

@@ -1,84 +0,0 @@
-import type { RequestKey } from "../../../types/identifier.js";
-import type { ImmutableRequestInfo, ResponseInfo } from "../../../types/request.js";
-import type { Store } from "../store-service.js";
-/**
-* A service which an application may provide to the store via
-* the store's `lifetimes` property to configure the behavior
-* of the CacheHandler.
-*
-* The default behavior for request lifetimes is to never expire
-* unless manually refreshed via `cacheOptions.reload` or `cacheOptions.backgroundReload`.
-*
-* Implementing this service allows you to programatically define
-* when a request should be considered expired.
-*
-* @public
-*/
-export interface CachePolicy {
-	/**
-	* Invoked to determine if the request may be fulfilled from cache
-	* if possible.
-	*
-	* Note, this is only invoked if the request has a cache-key.
-	*
-	* If no cache entry is found or the entry is hard expired,
-	* the request will be fulfilled from the configured request handlers
-	* and the cache will be updated before returning the response.
-	*
-	* @public
-	* @return true if the request is considered hard expired
-	*/
-	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.
-	*
-	* Note, this is only invoked if the request has a cache-key.
-	*
-	* If true, the request will be fulfilled from cache while a backgrounded
-	* request is made to update the cache via the configured request handlers.
-	*
-	* @public
-	* @return true if the request is considered soft expired
-	*/
-	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.
-	*
-	* Note, this is invoked regardless of whether the request has a cache-key.
-	*
-	* @public
-	*/
-	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
-	* been updated.
-	*
-	* Note, this is invoked regardless of whether the request has a cache-key.
-	*
-	* It is best practice to notify the store of any requests marked as invalidated
-	* so that request subscriptions can reload when needed.
-	*
-	* ```ts
-	* store.notifications.notify(identifier, 'invalidated', null);
-	* ```
-	*
-	* This allows anything subscribed to the request to be notified of the change
-	*
-	* e.g.
-	*
-	* ```ts
-	* store.notifications.subscribe(identifier, (_, type) => {
-	*   if (type === 'invalidated') {
-	*     // do update
-	*   }
-	* });
-	* ```
-	*
-	*
-	* @public
-	*/
-	didRequest?(request: ImmutableRequestInfo, response: Response | ResponseInfo | null, identifier: RequestKey | null, store: Store): void;
-}