@warp-drive-mirror/ember 5.8.0-alpha.3 → 5.8.0-alpha.32

package/README.md

@@ -1,26 +1,47 @@
 <p align="center">
   <img
     class="project-logo"
-    src="./logos/NCC-1701-a-blue.svg#gh-light-mode-only"
+    src="./logos/logo-yellow-slab.svg"
     alt="WarpDrive"
-    width="120px"
-    title="WarpDrive" />
-  <img
-    class="project-logo"
-    src="./logos/NCC-1701-a.svg#gh-dark-mode-only"
-    alt="WarpDrive"
-    width="120px"
-    title="WarpDrive" />
+    width="180px"
+    title="WarpDrive"
+    />
 </p>
 
-<h3 align="center">:electron: 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>
-<h4 align="center">And of course, <em style="color: orange">Ember</em><strong style="color: lightblue">Data</strong> too! </h4>
+![NPM Stable Version](https://img.shields.io/npm/v/ember-data/latest?label=version&style=flat&color=fdb155)
+![NPM Downloads](https://img.shields.io/npm/dm/ember-data.svg?style=flat&color=fdb155)
+![License](https://img.shields.io/github/license/warp-drive-data/warp-drive.svg?style=flat&color=fdb155)
+[![EmberJS Discord Community Server](https://img.shields.io/badge/EmberJS-grey?logo=discord&logoColor=fdb155)](https://discord.gg/zT3asNS
+)
+[![WarpDrive Discord Server](https://img.shields.io/badge/WarpDrive-grey?logo=discord&logoColor=fdb155)](https://discord.gg/PHBbnWJx5S
+)
+
+<h3 align="center">Signals Integration and Component API for using <em>Warp</em><strong>Drive</strong> with 🐹 <em style="color: orange">Ember.js</em></h3>
+
+***Warp*Drive** makes it easy to build scalable, fast, feature
+rich applications &mdash; letting you ship better experiences more quickly without re-architecting your app or API. ***Warp*Drive** is:
+
+- 🌌 Seamless Reactivity in any Framework
+- ⚡️ Committed to Best-In-Class Performance
+- 💚 Typed
+- ⚛️ Works with any API
+- 🌲 Focused on being as tiny as possible
+- 🚀 SSR Ready
+- 🐹 Built with ♥️ by [Ember](https://emberjs.com)
+
+<br>
+<br>
+
+*Get Started* → [Guides](https://warp-drive.io/guides/)
+
+<br>
 
 ---
 
-```sh
-pnpm install @warp-drive-mirror/ember
-```
+<br>
+
+# @warp-drive-mirror/ember
+
 
 **Tagged Releases**
 
@@ -568,7 +589,7 @@ export { Await as default } from '@warp-drive-mirror/ember';
     img.project-logo {
        padding: 0 5em 1em 5em;
        width: 100px;
-       border-bottom: 2px solid #0969da;
+       border-bottom: 2px solid #bbb;
        margin: 0 auto;
        display: block;
      }
@@ -584,7 +605,7 @@ export { Await as default } from '@warp-drive-mirror/ember';
       display: inline-block;
       padding: .2rem 0;
       color: #000;
-      border-bottom: 3px solid #0969da;
+      border-bottom: 3px solid #bbb;
     }
 
     details > details {

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

@@ -1,7 +1,7 @@
 import type Owner from "@ember/owner";
 import Component from "@glimmer/component";
+import { type PromiseState } from "@warp-drive-mirror/core/reactive";
 import type { Awaitable } from "@warp-drive-mirror/core/request";
-import { type PromiseState } from "@warp-drive-mirror/core/store/-private";
 export declare const and: (x: unknown, y: unknown) => boolean;
 interface ThrowSignature<E = Error | string | object> {
 	Args: {
@@ -14,11 +14,11 @@ interface ThrowSignature<E = Error | string | object> {
 * 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
+* ```gts
 * <Throw @error={{anError}} />
 * ```
 *
-* @class <Throw />
+* @category Components
 * @public
 */ export declare class Throw<T> extends Component<ThrowSignature<T>> {
 	constructor(owner: Owner, args: ThrowSignature<T>["Args"]);
@@ -37,13 +37,13 @@ interface AwaitSignature<
 	};
 }
 /**
-* The <Await /> component allow you to utilize reactive control flow
+* 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
+* ```gts
 * import { Await } from '@warp-drive-mirror/ember';
 *
 * <template>
@@ -63,12 +63,12 @@ interface AwaitSignature<
 * </template>
 * ```
 *
-* The <Await /> component requires that error states are properly handled.
+* 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 />
+* @category Components
 * @public
 */ export declare class Await<
 	T,

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

@@ -118,7 +118,7 @@ interface RequestSignature<
 *
 * The loading state exposes the download `ReadableStream` instance for consumption
 *
-* ```gjs
+* ```gts
 * import { Request } from '@warp-drive-mirror/ember';
 *
 * <template>
@@ -153,7 +153,7 @@ interface RequestSignature<
 *
 * Reload and refresh are available as methods on the `content` state.
 *
-* ```gjs
+* ```gts
 * import { Request } from '@warp-drive-mirror/ember';
 *
 * <template>
@@ -177,7 +177,7 @@ interface RequestSignature<
 * We can nest our usage of `<Request />` to handle more advanced
 * reloading scenarios.
 *
-* ```gjs
+* ```gts
 * import { Request } from '@warp-drive-mirror/ember';
 *
 * <template>
@@ -239,7 +239,7 @@ interface RequestSignature<
 * timer or on a websocket subscription.
 *
 *
-* ```gjs
+* ```gts
 * import { Request } from '@warp-drive-mirror/ember';
 *
 * <template>
@@ -263,7 +263,7 @@ interface RequestSignature<
 * from multiple `<Request />` components, even if the request is not referentially the
 * same, only one actual request will be made.
 *
-*
+* @category Components
 * @public
 */ export declare class Request<
 	RT,

package/declarations/index.d.ts

@@ -1,215 +1,8 @@
 /**
-* <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
-*
-* ```sh
-* pnpm install @warp-drive-mirror/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-mirror/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-mirror/ember';
-* ```
-*
-* ```hbs
-* <WarpDriveAwait @promise={{this.getTheData}}></WarpDriveAwait>
-* ```
-*
 * @module
+* @mergeModuleWith <project>
 */
 export { Request, type ContentFeatures, type RecoveryFeatures } 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-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.
-
-* @public
-* @param {Promise<T> | Awaitable<T, E>} promise
-* @return {PromiseState<T, E>}
-*/
-export { getPromiseState } from "@warp-drive-mirror/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: RequestKey | 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-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.
-*
-* @public
-* @param future
-* @return {RequestState}
-*/
-export { getRequestState, createRequestSubscription, type RequestLoadingState } from "@warp-drive-mirror/core/store/-private";
+export { getRequestState, createRequestSubscription, type RequestLoadingState, type RequestState } from "@warp-drive-mirror/core/store/-private";
+export { getPromiseState, type PromiseState } from "@warp-drive-mirror/core/reactive";

package/dist/index.js

@@ -1,8 +1,10 @@
 import { service } from '@ember/service';
 import Component from '@glimmer/component';
 import { macroCondition, getGlobalConfig, moduleExists, importSync } from '@embroider/macros';
-import { getPromiseState, DISPOSE, createRequestSubscription, memoized } from '@warp-drive-mirror/core/store/-private';
-export { createRequestSubscription, getPromiseState, getRequestState } from '@warp-drive-mirror/core/store/-private';
+import { DISPOSE, createRequestSubscription, memoized } from '@warp-drive-mirror/core/store/-private';
+export { createRequestSubscription, getRequestState } from '@warp-drive-mirror/core/store/-private';
+import { getPromiseState } from '@warp-drive-mirror/core/reactive';
+export { getPromiseState } from '@warp-drive-mirror/core/reactive';
 import { precompileTemplate } from '@ember/template-compilation';
 import { setComponentTemplate } from '@ember/component';
 import templateOnly from '@ember/component/template-only';
@@ -14,11 +16,11 @@ const and = (x, y) => Boolean(x && y);
  * 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
+ * ```gts
  * <Throw @error={{anError}} />
  * ```
  *
- * @class <Throw />
+ * @category Components
  * @public
  */
 class Throw extends Component {
@@ -41,13 +43,13 @@ class Throw extends Component {
   }
 }
 /**
- * The <Await /> component allow you to utilize reactive control flow
+ * 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
+ * ```gts
  * import { Await } from '@warp-drive-mirror/ember';
  *
  * <template>
@@ -67,12 +69,12 @@ class Throw extends Component {
  * </template>
  * ```
  *
- * The <Await /> component requires that error states are properly handled.
+ * 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 />
+ * @category Components
  * @public
  */
 class Await extends Component {
@@ -249,7 +251,7 @@ const DefaultChrome = setComponentTemplate(precompileTemplate("{{yield}}", {
  *
  * The loading state exposes the download `ReadableStream` instance for consumption
  *
- * ```gjs
+ * ```gts
  * import { Request } from '@warp-drive-mirror/ember';
  *
  * <template>
@@ -284,7 +286,7 @@ const DefaultChrome = setComponentTemplate(precompileTemplate("{{yield}}", {
  *
  * Reload and refresh are available as methods on the `content` state.
  *
- * ```gjs
+ * ```gts
  * import { Request } from '@warp-drive-mirror/ember';
  *
  * <template>
@@ -308,7 +310,7 @@ const DefaultChrome = setComponentTemplate(precompileTemplate("{{yield}}", {
  * We can nest our usage of `<Request />` to handle more advanced
  * reloading scenarios.
  *
- * ```gjs
+ * ```gts
  * import { Request } from '@warp-drive-mirror/ember';
  *
  * <template>
@@ -370,7 +372,7 @@ const DefaultChrome = setComponentTemplate(precompileTemplate("{{yield}}", {
  * timer or on a websocket subscription.
  *
  *
- * ```gjs
+ * ```gts
  * import { Request } from '@warp-drive-mirror/ember';
  *
  * <template>
@@ -394,7 +396,7 @@ const DefaultChrome = setComponentTemplate(precompileTemplate("{{yield}}", {
  * from multiple `<Request />` components, even if the request is not referentially the
  * same, only one actual request will be made.
  *
- *
+ * @category Components
  * @public
  */
 class Request extends Component {

package/dist/unpkg/dev/declarations/-private/await.d.ts

@@ -0,0 +1,81 @@
+import type Owner from "@ember/owner";
+import Component from "@glimmer/component";
+import { type PromiseState } from "@warp-drive-mirror/core/reactive";
+import type { Awaitable } from "@warp-drive-mirror/core/request";
+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.
+*
+* ```gts
+* <Throw @error={{anError}} />
+* ```
+*
+* @category Components
+* @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.
+*
+* ```gts
+* 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.
+*
+* @category Components
+* @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 {};