@warp-drive/ember 0.0.1 → 0.0.3

package/LICENSE.md

@@ -1,11 +1,23 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (C) 2017-2023 Ember.js contributors
-Portions Copyright (C) 2011-2017 Tilde, Inc. and contributors.
-Portions Copyright (C) 2011 LivingSocial Inc.
+Copyright (c) 2017-2025 Ember.js and contributors
+Copyright (c) 2011-2017 Tilde, Inc. and contributors
+Copyright (c) 2011 LivingSocial Inc.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,13 @@
 <p align="center">
   <img
     class="project-logo"
-    src="./NCC-1701-a-blue.svg#gh-light-mode-only"
+    src="./logos/NCC-1701-a-blue.svg#gh-light-mode-only"
     alt="WarpDrive"
     width="120px"
     title="WarpDrive" />
   <img
     class="project-logo"
-    src="./NCC-1701-a.svg#gh-dark-mode-only"
+    src="./logos/NCC-1701-a.svg#gh-dark-mode-only"
     alt="WarpDrive"
     width="120px"
     title="WarpDrive" />

package/dist/index.js

@@ -70,6 +70,10 @@ function initializeDeferredDecorator(target, prop) {
     });
   }
 }
+
+/**
+ * @module @warp-drive/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/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.
+ *
+ * @method getRequestState
+ * @for @warp-drive/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/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/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.
+ *
+ * @method getPromiseState
+ * @for @warp-drive/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,25 @@ function getPromiseState(promise) {
   }
   return state;
 }
+
+/**
+ * @module @warp-drive/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 +703,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/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 +758,11 @@ class Await extends Component {
     }), this);
   }
 }
+
+/**
+ * @module @warp-drive/ember
+ */
+
 function notNull(x) {
   macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
     if (!test) {
@@ -545,11 +786,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/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.
+ *
  *
- * @typedoc
+ * @class <Request />
+ * @public
  */
 class Request extends Component {
   static {
@@ -790,9 +1241,40 @@ class Request extends Component {
             {
               const latest = this.store.requestManager._deduped.get(requestId);
               const priority = latest?.priority;
+              const state = this.reqState;
               if (!priority) {
+                // if there is no priority, we have completed whatever request
+                // was occurring and so we are no longer refreshing (if we were)
                 this.isRefreshing = false;
-              } else if (priority.blocking) {
+              } else if (priority.blocking && !state.isLoading) {
+                // if we are blocking, there is an active request for this identity
+                // that MUST be fulfilled from network (not cache).
+                // Thus this is not "refreshing" because we should clear out and
+                // block on this request.
+                //
+                // we receive state notifications when either a request initiates
+                // or completes.
+                //
+                // In the completes case: we may receive the state notification
+                // slightly before the request is finalized because the NotificationManager
+                // may sync flush it (and thus deliver it before the microtask completes)
+                //
+                // In the initiates case: we aren't supposed to receive one unless there
+                // is no other request in flight for this identity.
+                //
+                // However, there is a race condition here where the completed
+                // notification can trigger an update that generates a new request
+                // thus giving us an initiated notification before the older request
+                // finalizes.
+                //
+                // When this occurs, if the triggered update happens to have caused
+                // a new request to be made for the same identity AND that request
+                // is the one passed into this component as the @request arg, then
+                // getRequestState will return the state of the new request.
+                // We can detect this by checking if the request state is "loading"
+                // as outside of this case we would have a completed request.
+                //
+                // That is the reason for the `&& !state.isLoading` check above.
                 // TODO should we just treat this as refreshing?
                 this.isRefreshing = false;
                 this.maybeUpdate('policy', true);