@warp-drive-mirror/ember 5.4.0-alpha.149 → 5.4.0-alpha.151

package/dist/index.js

@@ -70,6 +70,10 @@ function initializeDeferredDecorator(target, prop) {
     });
   }
 }
+
+/**
+ * @module @warp-drive-mirror/ember
+ */
 const RequestCache = new WeakMap();
 function isAbortError(error) {
   return error instanceof DOMException && error.name === 'AbortError';
@@ -84,8 +88,6 @@ async function watchStream(stream, state) {
   state._isPending = false;
   state._isStarted = true;
   state._startTime = performance.now();
-
-  // eslint-disable-next-line no-constant-condition
   while (true) {
     const {
       value,
@@ -129,6 +131,15 @@ async function watchStream(stream, state) {
   state._isComplete = true;
   state._isStarted = false;
 }
+
+/**
+ * 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
+ */
 class RequestLoadingState {
   _stream = null;
   _future;
@@ -305,6 +316,35 @@ class RequestLoadingState {
     this._future.abort();
   };
 }
+
+/**
+ * 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
+ */
 class RequestState {
   #request;
   #loadingState = null;
@@ -398,6 +438,65 @@ class RequestState {
     }
   }
 }
+
+/**
+ *
+ *
+ * `getRequestState` can be used in both JavaScript and Template contexts.
+ *
+ * ```ts
+ * import { getRequestState } from '@warp-drive-mirror/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-mirror/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.
+ *
+ * @method getRequestState
+ * @for @warp-drive-mirror/ember
+ * @static
+ * @public
+ * @param future
+ * @return {RequestState}
+ */
 function getRequestState(future) {
   let state = RequestCache.get(future);
   if (!state) {
@@ -406,7 +505,32 @@ function getRequestState(future) {
   }
   return state;
 }
+
+/**
+ * @module @warp-drive-mirror/ember
+ */
 const PromiseCache = new WeakMap();
+
+/**
+ * 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
+ */
 class PromiseState {
   static {
     decorateFieldV2(this.prototype, "result", [tracked], function () {
@@ -478,6 +602,65 @@ function isLegacyAwaitable(promise) {
 function getPromise(promise) {
   return isLegacyAwaitable(promise) ? promise.promise : promise;
 }
+
+/**
+ * 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-mirror/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-mirror/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.
+ *
+ * @method getPromiseState
+ * @for @warp-drive-mirror/ember
+ * @static
+ * @public
+ * @param {Promise<T> | Awaitable<T, E>} promise
+ * @return {PromiseState<T, E>}
+ */
 function getPromiseState(promise) {
   const _promise = getPromise(promise);
   let state = PromiseCache.get(_promise);
@@ -487,7 +670,24 @@ function getPromiseState(promise) {
   }
   return state;
 }
+
+/**
+ * @module @warp-drive-mirror/ember
+ */
 const and = (x, y) => Boolean(x && y);
+/**
+ * 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
+ */
 class Throw extends Component {
   constructor(owner, args) {
     super(owner, args);
@@ -502,6 +702,41 @@ class Throw extends Component {
     }), this);
   }
 }
+/**
+ * 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-mirror/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
+ */
 class Await extends Component {
   get state() {
     return getPromiseState(this.args.promise);
@@ -522,6 +757,10 @@ class Await extends Component {
     }), this);
   }
 }
+
+/**
+ * @module @warp-drive-mirror/ember
+ */
 function notNull(x) {
   macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
     if (!test) {
@@ -545,11 +784,221 @@ function isNeverString(val) {
   return val;
 }
 /**
- * The `<Request>` component is a powerful tool for managing data fetching and
- * state in your Ember application. It provides declarative reactive control-flow
- * for managing requests and state in your application.
+ * 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-mirror/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-mirror/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-mirror/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-mirror/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-mirror/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.
+ *
  *
- * @typedoc
+ * @class <Request />
+ * @public
  */
 class Request extends Component {
   static {