@warp-drive/ember 5.6.0-beta.0 → 5.6.0-beta.2

package/README.md

@@ -74,7 +74,7 @@ you should load data based on user interactions and route navigations, not from
 but what if you didn't need to use prop-drilling or contexts to access the result of a
 route based query?
 
-EmberData's RequestManager already allows for fulfillment from cache and for request 
+WarpDrive's RequestManager already allows for fulfillment from cache and for request 
 de-duping, so what if we could just pick up where we left off and use the result of a
 request right away if it already was fetched elsewhere?
 

package/addon-main.cjs

@@ -1,5 +1,5 @@
 'use strict';
 
-const { addonShim } = require('@warp-drive/build-config/addon-shim.cjs');
+const { addonShim } = require('@warp-drive/core/addon-shim.cjs');
 
 module.exports = addonShim(__dirname);

package/declarations/-private/await.d.ts

@@ -0,0 +1,81 @@
+import type Owner from "@ember/owner";
+import Component from "@glimmer/component";
+import type { Awaitable } from "@warp-drive/core/request";
+import { type PromiseState } from "@warp-drive/core/store/-private";
+export declare const and: (x: unknown, y: unknown) => boolean;
+interface ThrowSignature<E = Error | string | object> {
+	Args: {
+		error: E;
+	};
+}
+/**
+* The `<Throw />` component is used to throw an error in a template.
+*
+* That's all it does. So don't use it unless the application should
+* throw an error if it reaches this point in the template.
+*
+* ```hbs
+* <Throw @error={{anError}} />
+* ```
+*
+* @class <Throw />
+* @public
+*/ export declare class Throw<T> extends Component<ThrowSignature<T>> {
+	constructor(owner: Owner, args: ThrowSignature<T>["Args"]);
+}
+interface AwaitSignature<
+	T,
+	E = Error | string | object
+> {
+	Args: {
+		promise: Promise<T> | Awaitable<T, E>;
+	};
+	Blocks: {
+		pending: [];
+		error: [error: E];
+		success: [value: T];
+	};
+}
+/**
+* The <Await /> component allow you to utilize reactive control flow
+* for asynchronous states in your application.
+*
+* Await is ideal for handling "boundaries", outside which some state is
+* still allowed to be unresolved and within which it MUST be resolved.
+*
+* ```gjs
+* import { Await } from '@warp-drive/ember';
+*
+* <template>
+*   <Await @promise={{@request}}>
+*     <:pending>
+*       <Spinner />
+*     </:pending>
+*
+*     <:error as |error|>
+*       <ErrorForm @error={{error}} />
+*     </:error>
+*
+*     <:success as |result|>
+*       <h1>{{result.title}}</h1>
+*     </:success>
+*   </Await>
+* </template>
+* ```
+*
+* The <Await /> component requires that error states are properly handled.
+*
+* If no error block is provided and the promise rejects, the error will
+* be thrown.
+*
+* @class <Await />
+* @public
+*/ export declare class Await<
+	T,
+	E
+> extends Component<AwaitSignature<T, E>> {
+	get state(): Readonly<PromiseState<T, E>>;
+	get error(): E;
+	get result(): T;
+}
+export {};

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

@@ -0,0 +1,346 @@
+import Component from "@glimmer/component";
+import type { Store, StoreRequestInput } from "@warp-drive/core";
+import type { Future } from "@warp-drive/core/request";
+import type { RequestLoadingState, RequestState, RequestSubscription } from "@warp-drive/core/store/-private";
+import type { StructuredErrorDocument } from "@warp-drive/core/types/request";
+type AutorefreshBehaviorType = "online" | "interval" | "invalid";
+type AutorefreshBehaviorCombos = boolean | AutorefreshBehaviorType | `${AutorefreshBehaviorType},${AutorefreshBehaviorType}` | `${AutorefreshBehaviorType},${AutorefreshBehaviorType},${AutorefreshBehaviorType}`;
+type ContentFeatures<RT> = {
+	isOnline: boolean;
+	isHidden: boolean;
+	isRefreshing: boolean;
+	refresh: () => Promise<void>;
+	reload: () => Promise<void>;
+	abort?: () => void;
+	latestRequest?: Future<RT>;
+};
+interface RequestSignature<
+	RT,
+	T,
+	E
+> {
+	Args: {
+		/**
+		* The request to monitor. This should be a `Future` instance returned
+		* by either the `store.request` or `store.requestManager.request` methods.
+		*
+		*/ request?: Future<RT>;
+		/**
+		* 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, T>;
+		/**
+		* 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;
+		/**
+		* 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";
+	};
+	Blocks: {
+		/**
+		* The block to render when the component is idle and waiting to be given a request.
+		*
+		*/ idle: [];
+		/**
+		* The block to render when the request is loading.
+		*
+		*/ loading: [state: RequestLoadingState];
+		/**
+		* The block to render when the request was cancelled.
+		*
+		*/ cancelled: [error: StructuredErrorDocument<E>, features: {
+			isOnline: boolean;
+			isHidden: boolean;
+			retry: () => Promise<void>;
+		}];
+		/**
+		* The block to render when the request failed. If this block is not provided,
+		* the error will be rethrown.
+		*
+		* Thus it is required to provide an error block and proper error handling if
+		* you do not want the error to crash the application.
+		*
+		*/ error: [error: StructuredErrorDocument<E>, features: {
+			isOnline: boolean;
+			isHidden: boolean;
+			retry: () => Promise<void>;
+		}];
+		/**
+		* The block to render when the request succeeded.
+		*
+		*/ content: [value: RT, features: ContentFeatures<RT>];
+		always: [state: RequestState<RT, T, StructuredErrorDocument<E>>];
+	};
+}
+/**
+* The `<Request />` component is a powerful tool for managing data fetching and
+* state in your Ember application. It provides a declarative approach to reactive
+* control-flow for managing requests and state in your application.
+*
+* The `<Request />` component is ideal for handling "boundaries", outside which some
+* state is still allowed to be unresolved and within which it MUST be resolved.
+*
+* ## Request States
+*
+* `<Request />` has five states, only one of which will be active and rendered at a time.
+*
+* - `idle`: The component is waiting to be given a request to monitor
+* - `loading`: The request is in progress
+* - `error`: The request failed
+* - `content`: The request succeeded
+* - `cancelled`: The request was cancelled
+*
+* Additionally, the `content` state has a `refresh` method that can be used to
+* refresh the request in the background, which is available as a sub-state of
+* the `content` state.
+*
+* As with the `<Await />` component, if no error block is provided and the request
+* rejects, the error will be thrown. Cancellation errors are swallowed instead of
+* rethrown if no error block or cancellation block is present.
+*
+* ```gts
+* import { Request } from '@warp-drive/ember';
+*
+* <template>
+*   <Request @request={{@request}}>
+*     <:loading as |state|>
+*       <Spinner @percentDone={{state.completedRatio}} />
+*       <button {{on "click" state.abort}}>Cancel</button>
+*     </:loading>
+*
+*     <:error as |error state|>
+*       <ErrorForm @error={{error}} />
+*       <button {{on "click" state.retry}}>Retry</button>
+*     </:error>
+*
+*     <:content as |data state|>
+*       <h1>{{data.title}}</h1>
+*       {{#if state.isBackgroundReloading}}
+*         <SmallSpinner />
+*         <button {{on "click" state.abort}}>Cancel</button>
+*       {{else}}
+*         <button {{on "click" state.refresh}}>Refresh</button>
+*       {{/if}}
+*     </:content>
+*
+*     <:cancelled as |error state|>
+*       <h2>The Request was cancelled</h2>
+*       <button {{on "click" state.retry}}>Retry</button>
+*     </:cancelled>
+*
+*     <:idle>
+*       <button {{on "click" @kickOffRequest}}>Load Preview?</button>
+*     </:idle>
+*
+*   </Request>
+* </template>
+* ```
+*
+* ## Streaming Data
+*
+* The loading state exposes the download `ReadableStream` instance for consumption
+*
+* ```gjs
+* import { Request } from '@warp-drive/ember';
+*
+* <template>
+*   <Request @request={{@request}}>
+*     <:loading as |state|>
+*       <Video @stream={{state.stream}} />
+*     </:loading>
+*
+*     <:error as |error|>
+*       <ErrorForm @error={{error}} />
+*     </:error>
+*   </Request>
+* </template>
+* ```
+*
+* ## Retry
+*
+* Cancelled and error'd requests may be retried by calling the `retry` method.
+*
+* Retry will restart the state progression, using the loading, error, cancelled,
+* and content blocks as appropriate.
+*
+* ## Reloading
+*
+* The `reload` method will force the request to be fully re-executed, bypassing
+* cache and restarting the state progression through the loading, error, and
+* content blocks as appropriate.
+*
+* Background reload (refresh) is a special substate of the content state that
+* allows you to refresh the request in the background. This is useful for when
+* you want to update the data in the background without blocking the UI.
+*
+* Reload and refresh are available as methods on the `content` state.
+*
+* ```gjs
+* import { Request } from '@warp-drive/ember';
+*
+* <template>
+*   <Request @request={{@request}}>
+*     <:content as |data state|>
+*       <h1>{{data.title}}</h1>
+*       {{#if state.isBackgroundReloading}}
+*         <SmallSpinner />
+*         <button {{on "click" state.abort}}>Cancel</button>
+*       {{/if}}
+*
+*       <button {{on "click" state.refresh}}>Refresh</button>
+*       <button {{on "click" state.reload}}>Reload</button>
+*     </:content>
+*  </Request>
+* </template>
+* ```
+*
+* ## Advanced Reloading
+*
+* We can nest our usage of `<Request />` to handle more advanced
+* reloading scenarios.
+*
+* ```gjs
+* import { Request } from '@warp-drive/ember';
+*
+* <template>
+*   <Request @request={{@request}}>
+*     <:cancelled>
+*       <h2>The Request Cancelled</h2>
+*     </:cancelled>
+*
+*     <:error as |error|>
+*       <ErrorForm @error={{error}} />
+*     </:error>
+*
+*     <:content as |result state|>
+*       <Request @request={{state.latestRequest}}>
+*         <!-- Handle Background Request -->
+*       </Request>
+*
+*       <h1>{{result.title}}</h1>
+*
+*       <button {{on "click" state.refresh}}>Refresh</button>
+*     </:content>
+*   </Request>
+* </template>
+* ```
+*
+* ## Autorefresh
+*
+* `<Request />` supports automatic refresh and reload under certain conditions.
+*
+* - `online`: This occurs when a browser window or tab comes back to the foreground
+*   after being backgrounded or when the network reports as being online after
+*   having been offline.
+* - `interval`: This occurs when a specified amount of time has passed.
+* - `invalid`: This occurs when the store emits a notification that the request
+*   has become invalid.
+*
+* You can specify when autorefresh should occur by setting the `autorefresh` arg
+* to `true` or a comma-separated list of the above values.
+*
+* A value of `true` is equivalent to `'online,invalid'`.
+*
+* By default, an autorefresh will only occur if the browser was backgrounded or
+* offline for more than 30s before coming back available. This amount of time can
+* be tweaked by setting the number of milliseconds via `@autorefreshThreshold`.
+*
+* This arg also controls the interval at which the request will be refreshed
+* if the `interval` autorefresh type is enabled.
+*
+* Finally, the behavior of the request initiated by autorefresh can be adjusted
+* by setting the `autorefreshBehavior` arg to `'refresh'`, `'reload'`, or `'policy'`.
+*
+* - `'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.
+*
+* More advanced refresh and reload behaviors can be created by passing the reload and
+* refresh actions into another component. For instance, refresh could be set up on a
+* timer or on a websocket subscription.
+*
+*
+* ```gjs
+* import { Request } from '@warp-drive/ember';
+*
+* <template>
+*   <Request @request={{@request}}>
+*     <:content as |result state|>
+*       <h1>{{result.title}}</h1>
+*
+*       <Interval @period={{30_000}} @fn={{state.refresh}} />
+*       <Subscribe @channel={{@someValue}} @fn={{state.refresh}} />
+*     </:content>
+*   </Request>
+* </template>
+* ```
+*
+* If a matching request is refreshed or reloaded by any other component,
+* the `Request` component will react accordingly.
+*
+* ## Deduping
+*
+* The store dedupes requests by identity. If a request is made for the same identity
+* from multiple `<Request />` components, even if the request is not referentially the
+* same, only one actual request will be made.
+*
+*
+* @class <Request />
+* @public
+*/ export declare class Request<
+	RT,
+	T,
+	E
+> extends Component<RequestSignature<RT, T, E>> {
+	/**
+	* The store instance to use for making requests. If contexts are available, this
+	* will be the `store` on the context, else it will be the store service.
+	*
+	* @internal
+	*/ _store: Store;
+	get store(): Store;
+	_state: RequestSubscription<RT, T, E> | null;
+	get state(): RequestSubscription<RT, T, E>;
+	willDestroy(): void;
+}
+export {};

package/declarations/index.d.ts

@@ -0,0 +1,215 @@
+/**
+* <h3 align="center">⚛️ Data utilities for using <em style="color: lightgreen">Warp</em><strong style="color: magenta">Drive</strong> with 🐹 <em style="color: orange">Ember</em><em style="color: lightblue">.js</em></h3>
+*
+* ## Installation
+*
+* ```cli
+* pnpm install @warp-drive/ember
+* ```
+*
+* ## About
+*
+* This library provides reactive utilities for working with promises
+* and requests, building over these primitives to provide functions
+* and components that enable you to build robust performant apps with
+* elegant control flow.
+*
+* ## Using .hbs
+*
+* The components and utils this library exports are intended for use with Glimmer
+* Flavored JavaScript (gjs). To use them in handlebars files, your app should re-
+* export them. For instance:
+*
+* *app/components/await.ts*
+* ```ts
+* export { Await as default } from '@warp-drive/ember';
+* ```
+*
+* ```hbs
+* <Await @promise={{this.getTheData}}></Await>
+* ```
+*
+* This allows renaming them to avoid conflicts just by using a different filename
+* if desired:
+*
+* *app/components/warp-drive-await.ts*
+* ```ts
+* export { Await as default } from '@warp-drive/ember';
+* ```
+*
+* ```hbs
+* <WarpDriveAwait @promise={{this.getTheData}}></WarpDriveAwait>
+* ```
+*
+* @module
+*/
+export { Request } from "./-private/request.js";
+export { Await, Throw } from "./-private/await.js";
+/**
+* PromiseState provides a reactive wrapper for a promise which allows you write declarative
+* code around a promise'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.
+*
+* ```ts
+* interface PromiseState<T = unknown, E = unknown> {
+*   isPending: boolean;
+*   isSuccess: boolean;
+*   isError: boolean;
+*   result: T | null;
+*   error: E | null;
+* }
+* ```
+*
+* To get the state of a promise, use `getPromiseState`.
+*
+* @class PromiseState
+* @public
+*/
+/**
+* Returns a reactive state-machine for the provided promise or awaitable.
+*
+* Repeat calls to `getPromiseState` with the same promise will return the same state object
+* making is safe and easy to use in templates and JavaScript code to produce reactive
+* behaviors around promises.
+*
+* `getPromiseState` can be used in both JavaScript and Template contexts.
+*
+* ```ts
+* import { getPromiseState } from '@warp-drive/ember';
+*
+* const state = getPromiseState(promise);
+* ```
+*
+* For instance, we could write a getter on a component that updates whenever
+* the promise state advances or the promise changes, by combining the function
+* with the use of `@cached`
+*
+* ```ts
+* class Component {
+*   @cached
+*   get title() {
+*     const state = getPromiseState(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 { getPromiseState } from '@warp-drive/ember';
+*
+* <template>
+*   {{#let (getPromiseState @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 `<Await />` component.
+
+* @public
+* @param {Promise<T> | Awaitable<T, E>} promise
+* @return {PromiseState<T, E>}
+*/
+export { getPromiseState } from "@warp-drive/core/store/-private";
+/**
+* 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.
+*
+* @class RequestLoadingState
+* @public
+*/
+/**
+* RequestState extends the concept of PromiseState to provide a reactive
+* wrapper for a request `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 Promise and a Future is that Futures provide
+* access to a stream of their content, the identity of the request (if any)
+* as well as the ability to attempt to abort the request.
+*
+* ```ts
+* interface Future<T> extends Promise<T>> {
+*   getStream(): Promise<ReadableStream>;
+*   abort(): void;
+*   lid: StableDocumentIdentifier | null;
+* }
+* ```
+*
+* These additional APIs allow us to craft even richer state experiences.
+*
+* To get the state of a request, use `getRequestState`.
+*
+* @class RequestState
+* @public
+*/
+/**
+*
+*
+* `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 numbe of additional capabilities for requests *beyond* what
+* `RequestState` provides.
+*
+* @public
+* @param future
+* @return {RequestState}
+*/
+export { getRequestState, type RequestLoadingState } from "@warp-drive/core/store/-private";

package/declarations/install.d.ts

@@ -0,0 +1,6 @@
+import type { SignalHooks } from "@warp-drive/core/store/-private";
+export declare function buildSignalConfig(options: {
+	wellknown: {
+		Array: symbol | string;
+	};
+}): SignalHooks;