@warp-drive/ember 5.4.0-alpha.150 → 5.4.0-alpha.152
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +457 -6
- package/dist/index.js.map +1 -1
- package/package.json +26 -26
- package/unstable-preview-types/-private/await.d.ts +53 -1
- package/unstable-preview-types/-private/await.d.ts.map +1 -1
- package/unstable-preview-types/-private/promise-state.d.ts +78 -0
- package/unstable-preview-types/-private/promise-state.d.ts.map +1 -1
- package/unstable-preview-types/-private/request-state.d.ts +94 -0
- package/unstable-preview-types/-private/request-state.d.ts.map +1 -1
- package/unstable-preview-types/-private/request.d.ts +309 -6
- package/unstable-preview-types/-private/request.d.ts.map +1 -1
- package/unstable-preview-types/index.d.ts +19 -0
- package/unstable-preview-types/index.d.ts.map +1 -1
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
declare module '@warp-drive/ember/-private/promise-state' {
|
|
2
2
|
import type { Awaitable } from '@ember-data/request';
|
|
3
|
+
/**
|
|
4
|
+
* PromiseState provides a reactive wrapper for a promise which allows you write declarative
|
|
5
|
+
* code around a promise's control flow. It is useful in both Template and JavaScript contexts,
|
|
6
|
+
* allowing you to quickly derive behaviors and data from pending, error and success states.
|
|
7
|
+
*
|
|
8
|
+
* ```ts
|
|
9
|
+
* interface PromiseState<T = unknown, E = unknown> {
|
|
10
|
+
* isPending: boolean;
|
|
11
|
+
* isSuccess: boolean;
|
|
12
|
+
* isError: boolean;
|
|
13
|
+
* result: T | null;
|
|
14
|
+
* error: E | null;
|
|
15
|
+
* }
|
|
16
|
+
* ```
|
|
17
|
+
*
|
|
18
|
+
* To get the state of a promise, use `getPromiseState`.
|
|
19
|
+
*
|
|
20
|
+
* @class PromiseState
|
|
21
|
+
* @public
|
|
22
|
+
*/
|
|
3
23
|
export class PromiseState<T = unknown, E = unknown> {
|
|
4
24
|
result: T | null;
|
|
5
25
|
error: E | null;
|
|
@@ -8,6 +28,64 @@ declare module '@warp-drive/ember/-private/promise-state' {
|
|
|
8
28
|
isError: boolean;
|
|
9
29
|
constructor(promise: Promise<T> | Awaitable<T, E>);
|
|
10
30
|
}
|
|
31
|
+
/**
|
|
32
|
+
* Returns a reactive state-machine for the provided promise or awaitable.
|
|
33
|
+
*
|
|
34
|
+
* Repeat calls to `getPromiseState` with the same promise will return the same state object
|
|
35
|
+
* making is safe and easy to use in templates and JavaScript code to produce reactive
|
|
36
|
+
* behaviors around promises.
|
|
37
|
+
*
|
|
38
|
+
* `getPromiseState` can be used in both JavaScript and Template contexts.
|
|
39
|
+
*
|
|
40
|
+
* ```ts
|
|
41
|
+
* import { getPromiseState } from '@warp-drive/ember';
|
|
42
|
+
*
|
|
43
|
+
* const state = getPromiseState(promise);
|
|
44
|
+
* ```
|
|
45
|
+
*
|
|
46
|
+
* For instance, we could write a getter on a component that updates whenever
|
|
47
|
+
* the promise state advances or the promise changes, by combining the function
|
|
48
|
+
* with the use of `@cached`
|
|
49
|
+
*
|
|
50
|
+
* ```ts
|
|
51
|
+
* class Component {
|
|
52
|
+
* @cached
|
|
53
|
+
* get title() {
|
|
54
|
+
* const state = getPromiseState(this.args.request);
|
|
55
|
+
* if (state.isPending) {
|
|
56
|
+
* return 'loading...';
|
|
57
|
+
* }
|
|
58
|
+
* if (state.isError) { return null; }
|
|
59
|
+
* return state.result.title;
|
|
60
|
+
* }
|
|
61
|
+
* }
|
|
62
|
+
* ```
|
|
63
|
+
*
|
|
64
|
+
* Or in a template as a helper:
|
|
65
|
+
*
|
|
66
|
+
* ```gjs
|
|
67
|
+
* import { getPromiseState } from '@warp-drive/ember';
|
|
68
|
+
*
|
|
69
|
+
* <template>
|
|
70
|
+
* {{#let (getPromiseState @request) as |state|}}
|
|
71
|
+
* {{#if state.isPending}} <Spinner />
|
|
72
|
+
* {{else if state.isError}} <ErrorForm @error={{state.error}} />
|
|
73
|
+
* {{else}}
|
|
74
|
+
* <h1>{{state.result.title}}</h1>
|
|
75
|
+
* {{/if}}
|
|
76
|
+
* {{/let}}
|
|
77
|
+
* </template>
|
|
78
|
+
* ```
|
|
79
|
+
*
|
|
80
|
+
* If looking to use in a template, consider also the `<Await />` component.
|
|
81
|
+
*
|
|
82
|
+
* @method getPromiseState
|
|
83
|
+
* @for @warp-drive/ember
|
|
84
|
+
* @static
|
|
85
|
+
* @public
|
|
86
|
+
* @param {Promise<T> | Awaitable<T, E>} promise
|
|
87
|
+
* @return {PromiseState<T, E>}
|
|
88
|
+
*/
|
|
11
89
|
export function getPromiseState<T = unknown, E = unknown>(promise: Promise<T> | Awaitable<T, E>): PromiseState<T, E>;
|
|
12
90
|
}
|
|
13
91
|
//# sourceMappingURL=promise-state.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"promise-state.d.ts","sourceRoot":"","sources":["../../src/-private/promise-state.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"promise-state.d.ts","sourceRoot":"","sources":["../../src/-private/promise-state.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKrD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IACvC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAQ;IACxB,KAAK,EAAE,CAAC,GAAG,IAAI,CAAQ;IACvB,SAAS,UAAQ;IACjB,SAAS,UAAS;IAClB,OAAO,UAAS;gBAEb,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC;CA8BlD;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAUnH"}
|
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
declare module '@warp-drive/ember/-private/request-state' {
|
|
2
2
|
import type { Future, ImmutableRequestInfo, ResponseInfo, StructuredErrorDocument } from '@ember-data/request';
|
|
3
|
+
/**
|
|
4
|
+
* Lazily consumes the stream of a request, providing a number of
|
|
5
|
+
* reactive properties that can be used to build UIs that respond
|
|
6
|
+
* to the progress of a request.
|
|
7
|
+
*
|
|
8
|
+
* @class RequestLoadingState
|
|
9
|
+
* @public
|
|
10
|
+
*/
|
|
3
11
|
export class RequestLoadingState {
|
|
4
12
|
_stream: TransformStream | null;
|
|
5
13
|
_future: Future<unknown>;
|
|
@@ -37,6 +45,34 @@ declare module '@warp-drive/ember/-private/request-state' {
|
|
|
37
45
|
constructor(future: Future<unknown>);
|
|
38
46
|
abort: () => void;
|
|
39
47
|
}
|
|
48
|
+
/**
|
|
49
|
+
* RequestState extends the concept of PromiseState to provide a reactive
|
|
50
|
+
* wrapper for a request `Future` which allows you write declarative code
|
|
51
|
+
* around a Future's control flow.
|
|
52
|
+
*
|
|
53
|
+
* It is useful in both Template and JavaScript contexts, allowing you
|
|
54
|
+
* to quickly derive behaviors and data from pending, error and success
|
|
55
|
+
* states.
|
|
56
|
+
*
|
|
57
|
+
* The key difference between a Promise and a Future is that Futures provide
|
|
58
|
+
* access to a stream of their content, the identity of the request (if any)
|
|
59
|
+
* as well as the ability to attempt to abort the request.
|
|
60
|
+
*
|
|
61
|
+
* ```ts
|
|
62
|
+
* interface Future<T> extends Promise<T>> {
|
|
63
|
+
* getStream(): Promise<ReadableStream>;
|
|
64
|
+
* abort(): void;
|
|
65
|
+
* lid: StableDocumentIdentifier | null;
|
|
66
|
+
* }
|
|
67
|
+
* ```
|
|
68
|
+
*
|
|
69
|
+
* These additional APIs allow us to craft even richer state experiences.
|
|
70
|
+
*
|
|
71
|
+
* To get the state of a request, use `getRequestState`.
|
|
72
|
+
*
|
|
73
|
+
* @class RequestState
|
|
74
|
+
* @public
|
|
75
|
+
*/
|
|
40
76
|
export class RequestState<T = unknown, RT = unknown> {
|
|
41
77
|
#private;
|
|
42
78
|
result: RT | null;
|
|
@@ -50,6 +86,64 @@ declare module '@warp-drive/ember/-private/request-state' {
|
|
|
50
86
|
get loadingState(): RequestLoadingState;
|
|
51
87
|
constructor(future: Future<RT>);
|
|
52
88
|
}
|
|
89
|
+
/**
|
|
90
|
+
*
|
|
91
|
+
*
|
|
92
|
+
* `getRequestState` can be used in both JavaScript and Template contexts.
|
|
93
|
+
*
|
|
94
|
+
* ```ts
|
|
95
|
+
* import { getRequestState } from '@warp-drive/ember';
|
|
96
|
+
*
|
|
97
|
+
* const state = getRequestState(future);
|
|
98
|
+
* ```
|
|
99
|
+
*
|
|
100
|
+
* For instance, we could write a getter on a component that updates whenever
|
|
101
|
+
* the request state advances or the future changes, by combining the function
|
|
102
|
+
* with the use of `@cached`
|
|
103
|
+
*
|
|
104
|
+
* ```ts
|
|
105
|
+
* class Component {
|
|
106
|
+
* @cached
|
|
107
|
+
* get title() {
|
|
108
|
+
* const state = getRequestState(this.args.request);
|
|
109
|
+
* if (state.isPending) {
|
|
110
|
+
* return 'loading...';
|
|
111
|
+
* }
|
|
112
|
+
* if (state.isError) { return null; }
|
|
113
|
+
* return state.result.title;
|
|
114
|
+
* }
|
|
115
|
+
* }
|
|
116
|
+
* ```
|
|
117
|
+
*
|
|
118
|
+
* Or in a template as a helper:
|
|
119
|
+
*
|
|
120
|
+
* ```gjs
|
|
121
|
+
* import { getRequestState } from '@warp-drive/ember';
|
|
122
|
+
*
|
|
123
|
+
* <template>
|
|
124
|
+
* {{#let (getRequestState @request) as |state|}}
|
|
125
|
+
* {{#if state.isPending}}
|
|
126
|
+
* <Spinner />
|
|
127
|
+
* {{else if state.isError}}
|
|
128
|
+
* <ErrorForm @error={{state.error}} />
|
|
129
|
+
* {{else}}
|
|
130
|
+
* <h1>{{state.result.title}}</h1>
|
|
131
|
+
* {{/if}}
|
|
132
|
+
* {{/let}}
|
|
133
|
+
* </template>
|
|
134
|
+
* ```
|
|
135
|
+
*
|
|
136
|
+
* If looking to use in a template, consider also the `<Request />` component
|
|
137
|
+
* which offers a numbe of additional capabilities for requests *beyond* what
|
|
138
|
+
* `RequestState` provides.
|
|
139
|
+
*
|
|
140
|
+
* @method getRequestState
|
|
141
|
+
* @for @warp-drive/ember
|
|
142
|
+
* @static
|
|
143
|
+
* @public
|
|
144
|
+
* @param future
|
|
145
|
+
* @return {RequestState}
|
|
146
|
+
*/
|
|
53
147
|
export function getRequestState<RT, T>(future: Future<RT>): RequestState<T, RT>;
|
|
54
148
|
}
|
|
55
149
|
//# sourceMappingURL=request-state.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"request-state.d.ts","sourceRoot":"","sources":["../../src/-private/request-state.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"request-state.d.ts","sourceRoot":"","sources":["../../src/-private/request-state.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,MAAM,EACN,oBAAoB,EACpB,YAAY,EAEZ,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAiE7B;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,EAAE,eAAe,GAAG,IAAI,CAAQ;IACvC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACzB,UAAU,UAAS;IACnB,QAAQ;IAgCR,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC5B,SAAS,SAAK;IACd,YAAY,SAAK;IAEjB,UAAU,SAAK;IACf,QAAQ,SAAK;IACb,eAAe,SAAK;IAEpB,UAAU,UAAQ;IAClB,UAAU,UAAS;IACnB,WAAW,UAAS;IACpB,YAAY,UAAS;IACrB,UAAU,UAAS;IACnB,MAAM,EAAE,KAAK,GAAG,IAAI,CAAQ;IAErC,IAAI,SAAS,IAAI,OAAO,CAGvB;IAED,IAAI,QAAQ,IAAI,MAAM,CAGrB;IAED,IAAI,MAAM,IAAI,cAAc,GAAG,IAAI,CASlC;IAED,IAAI,SAAS,IAAI,OAAO,CAGvB;IAED,IAAI,WAAW,IAAI,MAAM,CAGxB;IAED,IAAI,SAAS,IAAI,MAAM,CAGtB;IAED,IAAI,OAAO,IAAI,MAAM,CAGpB;IAED,IAAI,cAAc,IAAI,MAAM,CAG3B;IAED,IAAI,UAAU,IAAI,OAAO,CAGxB;IAED,IAAI,WAAW,IAAI,OAAO,CAGzB;IAED,IAAI,SAAS,IAAI,OAAO,CAGvB;IAED,IAAI,KAAK,IAAI,KAAK,GAAG,IAAI,CAGxB;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,KAAK,IAAI,MAAM,CAGlB;gBAEW,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC;IAInC,KAAK,QAAO,IAAI,CAEd;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO;;IAIxC,MAAM,EAAE,EAAE,GAAG,IAAI,CAAQ;IACzB,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAAQ;IAC7C,SAAS,UAAQ;IACjB,SAAS,UAAS;IAClB,OAAO,UAAS;IAChB,OAAO,EAAE,oBAAoB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAQ;IACnD,QAAQ,EAAE,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAQ;IAEzD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,YAAY,wBAMf;gBAEW,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;CAqC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,EAAE,EAAE,CAAC,CAS9E"}
|
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
declare module '@warp-drive/ember/-private/request' {
|
|
2
|
+
/**
|
|
3
|
+
* @module @warp-drive/ember
|
|
4
|
+
*/
|
|
5
|
+
import type Owner from '@ember/owner';
|
|
2
6
|
import Component from '@glimmer/component';
|
|
3
7
|
import type { Future, StructuredErrorDocument } from '@ember-data/request';
|
|
4
8
|
import type { StoreRequestInput } from '@ember-data/store';
|
|
5
9
|
import type Store from '@ember-data/store';
|
|
6
10
|
import type { RequestLoadingState, RequestState } from '@warp-drive/ember/-private/request-state.ts';
|
|
7
11
|
type AutorefreshBehaviorType = 'online' | 'interval' | 'invalid';
|
|
8
|
-
type AutorefreshBehaviorCombos =
|
|
12
|
+
type AutorefreshBehaviorCombos = boolean | AutorefreshBehaviorType | `${AutorefreshBehaviorType},${AutorefreshBehaviorType}` | `${AutorefreshBehaviorType},${AutorefreshBehaviorType},${AutorefreshBehaviorType}`;
|
|
9
13
|
type ContentFeatures<RT> = {
|
|
10
14
|
isOnline: boolean;
|
|
11
15
|
isHidden: boolean;
|
|
@@ -17,16 +21,91 @@ declare module '@warp-drive/ember/-private/request' {
|
|
|
17
21
|
};
|
|
18
22
|
interface RequestSignature<T, RT> {
|
|
19
23
|
Args: {
|
|
24
|
+
/**
|
|
25
|
+
* The request to monitor. This should be a `Future` instance returned
|
|
26
|
+
* by either the `store.request` or `store.requestManager.request` methods.
|
|
27
|
+
*
|
|
28
|
+
* @typedoc
|
|
29
|
+
*/
|
|
20
30
|
request?: Future<RT>;
|
|
31
|
+
/**
|
|
32
|
+
* A query to use for the request. This should be an object that can be
|
|
33
|
+
* passed to `store.request`. Use this in place of `@request` if you would
|
|
34
|
+
* like the component to also initiate the request.
|
|
35
|
+
*
|
|
36
|
+
* @typedoc
|
|
37
|
+
*/
|
|
21
38
|
query?: StoreRequestInput<T, RT>;
|
|
39
|
+
/**
|
|
40
|
+
* The store instance to use for making requests. If contexts are available,
|
|
41
|
+
* the component will default to using the `store` on the context.
|
|
42
|
+
*
|
|
43
|
+
* This is required if the store is not available via context or should be
|
|
44
|
+
* different from the store provided via context.
|
|
45
|
+
*
|
|
46
|
+
* @typedoc
|
|
47
|
+
*/
|
|
22
48
|
store?: Store;
|
|
49
|
+
/**
|
|
50
|
+
* The autorefresh behavior for the request. This can be a boolean, or any
|
|
51
|
+
* combination of the following values: `'online'`, `'interval'`, `'invalid'`.
|
|
52
|
+
*
|
|
53
|
+
* - `'online'`: Refresh the request when the browser comes back online
|
|
54
|
+
* - `'interval'`: Refresh the request at a specified interval
|
|
55
|
+
* - `'invalid'`: Refresh the request when the store emits an invalidation
|
|
56
|
+
*
|
|
57
|
+
* If `true`, this is equivalent to `'online,invalid'`.
|
|
58
|
+
*
|
|
59
|
+
* Defaults to `false`.
|
|
60
|
+
*
|
|
61
|
+
* @typedoc
|
|
62
|
+
*/
|
|
23
63
|
autorefresh?: AutorefreshBehaviorCombos;
|
|
64
|
+
/**
|
|
65
|
+
* The number of milliseconds to wait before refreshing the request when the
|
|
66
|
+
* browser comes back online or the network becomes available.
|
|
67
|
+
*
|
|
68
|
+
* This also controls the interval at which the request will be refreshed if
|
|
69
|
+
* the `interval` autorefresh type is enabled.
|
|
70
|
+
*
|
|
71
|
+
* Defaults to `30_000` (30 seconds).
|
|
72
|
+
*
|
|
73
|
+
* @typedoc
|
|
74
|
+
*/
|
|
24
75
|
autorefreshThreshold?: number;
|
|
76
|
+
/**
|
|
77
|
+
* The behavior of the request initiated by autorefresh. This can be one of
|
|
78
|
+
* the following values:
|
|
79
|
+
*
|
|
80
|
+
* - `'refresh'`: Refresh the request in the background
|
|
81
|
+
* - `'reload'`: Force a reload of the request
|
|
82
|
+
* - `'policy'` (**default**): Let the store's configured CachePolicy decide whether to
|
|
83
|
+
* reload, refresh, or do nothing.
|
|
84
|
+
*
|
|
85
|
+
* Defaults to `'policy'`.
|
|
86
|
+
*
|
|
87
|
+
* @typedoc
|
|
88
|
+
*/
|
|
25
89
|
autorefreshBehavior?: 'refresh' | 'reload' | 'policy';
|
|
26
90
|
};
|
|
27
91
|
Blocks: {
|
|
92
|
+
/**
|
|
93
|
+
* The block to render when the component is idle and waiting to be given a request.
|
|
94
|
+
*
|
|
95
|
+
* @typedoc
|
|
96
|
+
*/
|
|
28
97
|
idle: [];
|
|
98
|
+
/**
|
|
99
|
+
* The block to render when the request is loading.
|
|
100
|
+
*
|
|
101
|
+
* @typedoc
|
|
102
|
+
*/
|
|
29
103
|
loading: [state: RequestLoadingState];
|
|
104
|
+
/**
|
|
105
|
+
* The block to render when the request was cancelled.
|
|
106
|
+
*
|
|
107
|
+
* @typedoc
|
|
108
|
+
*/
|
|
30
109
|
cancelled: [
|
|
31
110
|
error: StructuredErrorDocument,
|
|
32
111
|
features: {
|
|
@@ -35,6 +114,15 @@ declare module '@warp-drive/ember/-private/request' {
|
|
|
35
114
|
retry: () => Promise<void>;
|
|
36
115
|
}
|
|
37
116
|
];
|
|
117
|
+
/**
|
|
118
|
+
* The block to render when the request failed. If this block is not provided,
|
|
119
|
+
* the error will be rethrown.
|
|
120
|
+
*
|
|
121
|
+
* Thus it is required to provide an error block and proper error handling if
|
|
122
|
+
* you do not want the error to crash the application.
|
|
123
|
+
*
|
|
124
|
+
* @typedoc
|
|
125
|
+
*/
|
|
38
126
|
error: [
|
|
39
127
|
error: StructuredErrorDocument,
|
|
40
128
|
features: {
|
|
@@ -43,16 +131,231 @@ declare module '@warp-drive/ember/-private/request' {
|
|
|
43
131
|
retry: () => Promise<void>;
|
|
44
132
|
}
|
|
45
133
|
];
|
|
134
|
+
/**
|
|
135
|
+
* The block to render when the request succeeded.
|
|
136
|
+
*
|
|
137
|
+
* @typedoc
|
|
138
|
+
*/
|
|
46
139
|
content: [value: RT, features: ContentFeatures<RT>];
|
|
47
140
|
always: [state: RequestState<T, RT>];
|
|
48
141
|
};
|
|
49
142
|
}
|
|
50
143
|
/**
|
|
51
|
-
* The `<Request
|
|
52
|
-
* state in your Ember application. It provides declarative reactive
|
|
53
|
-
* for managing requests and state in your application.
|
|
144
|
+
* The `<Request />` component is a powerful tool for managing data fetching and
|
|
145
|
+
* state in your Ember application. It provides a declarative approach to reactive
|
|
146
|
+
* control-flow for managing requests and state in your application.
|
|
147
|
+
*
|
|
148
|
+
* The `<Request />` component is ideal for handling "boundaries", outside which some
|
|
149
|
+
* state is still allowed to be unresolved and within which it MUST be resolved.
|
|
150
|
+
*
|
|
151
|
+
* ## Request States
|
|
152
|
+
*
|
|
153
|
+
* `<Request />` has five states, only one of which will be active and rendered at a time.
|
|
154
|
+
*
|
|
155
|
+
* - `idle`: The component is waiting to be given a request to monitor
|
|
156
|
+
* - `loading`: The request is in progress
|
|
157
|
+
* - `error`: The request failed
|
|
158
|
+
* - `content`: The request succeeded
|
|
159
|
+
* - `cancelled`: The request was cancelled
|
|
160
|
+
*
|
|
161
|
+
* Additionally, the `content` state has a `refresh` method that can be used to
|
|
162
|
+
* refresh the request in the background, which is available as a sub-state of
|
|
163
|
+
* the `content` state.
|
|
164
|
+
*
|
|
165
|
+
* As with the `<Await />` component, if no error block is provided and the request
|
|
166
|
+
* rejects, the error will be thrown. Cancellation errors are swallowed instead of
|
|
167
|
+
* rethrown if no error block or cancellation block is present.
|
|
168
|
+
*
|
|
169
|
+
* ```gts
|
|
170
|
+
* import { Request } from '@warp-drive/ember';
|
|
171
|
+
*
|
|
172
|
+
* <template>
|
|
173
|
+
* <Request @request={{@request}}>
|
|
174
|
+
* <:loading as |state|>
|
|
175
|
+
* <Spinner @percentDone={{state.completedRatio}} />
|
|
176
|
+
* <button {{on "click" state.abort}}>Cancel</button>
|
|
177
|
+
* </:loading>
|
|
178
|
+
*
|
|
179
|
+
* <:error as |error state|>
|
|
180
|
+
* <ErrorForm @error={{error}} />
|
|
181
|
+
* <button {{on "click" state.retry}}>Retry</button>
|
|
182
|
+
* </:error>
|
|
183
|
+
*
|
|
184
|
+
* <:content as |data state|>
|
|
185
|
+
* <h1>{{data.title}}</h1>
|
|
186
|
+
* {{#if state.isBackgroundReloading}}
|
|
187
|
+
* <SmallSpinner />
|
|
188
|
+
* <button {{on "click" state.abort}}>Cancel</button>
|
|
189
|
+
* {{else}}
|
|
190
|
+
* <button {{on "click" state.refresh}}>Refresh</button>
|
|
191
|
+
* {{/if}}
|
|
192
|
+
* </:content>
|
|
193
|
+
*
|
|
194
|
+
* <:cancelled as |error state|>
|
|
195
|
+
* <h2>The Request was cancelled</h2>
|
|
196
|
+
* <button {{on "click" state.retry}}>Retry</button>
|
|
197
|
+
* </:cancelled>
|
|
198
|
+
*
|
|
199
|
+
* <:idle>
|
|
200
|
+
* <button {{on "click" @kickOffRequest}}>Load Preview?</button>
|
|
201
|
+
* </:idle>
|
|
202
|
+
*
|
|
203
|
+
* </Request>
|
|
204
|
+
* </template>
|
|
205
|
+
* ```
|
|
206
|
+
*
|
|
207
|
+
* ## Streaming Data
|
|
208
|
+
*
|
|
209
|
+
* The loading state exposes the download `ReadableStream` instance for consumption
|
|
210
|
+
*
|
|
211
|
+
* ```gjs
|
|
212
|
+
* import { Request } from '@warp-drive/ember';
|
|
213
|
+
*
|
|
214
|
+
* <template>
|
|
215
|
+
* <Request @request={{@request}}>
|
|
216
|
+
* <:loading as |state|>
|
|
217
|
+
* <Video @stream={{state.stream}} />
|
|
218
|
+
* </:loading>
|
|
219
|
+
*
|
|
220
|
+
* <:error as |error|>
|
|
221
|
+
* <ErrorForm @error={{error}} />
|
|
222
|
+
* </:error>
|
|
223
|
+
* </Request>
|
|
224
|
+
* </template>
|
|
225
|
+
* ```
|
|
226
|
+
*
|
|
227
|
+
* ## Retry
|
|
228
|
+
*
|
|
229
|
+
* Cancelled and error'd requests may be retried by calling the `retry` method.
|
|
230
|
+
*
|
|
231
|
+
* Retry will restart the state progression, using the loading, error, cancelled,
|
|
232
|
+
* and content blocks as appropriate.
|
|
233
|
+
*
|
|
234
|
+
* ## Reloading
|
|
235
|
+
*
|
|
236
|
+
* The `reload` method will force the request to be fully re-executed, bypassing
|
|
237
|
+
* cache and restarting the state progression through the loading, error, and
|
|
238
|
+
* content blocks as appropriate.
|
|
239
|
+
*
|
|
240
|
+
* Background reload (refresh) is a special substate of the content state that
|
|
241
|
+
* allows you to refresh the request in the background. This is useful for when
|
|
242
|
+
* you want to update the data in the background without blocking the UI.
|
|
243
|
+
*
|
|
244
|
+
* Reload and refresh are available as methods on the `content` state.
|
|
245
|
+
*
|
|
246
|
+
* ```gjs
|
|
247
|
+
* import { Request } from '@warp-drive/ember';
|
|
248
|
+
*
|
|
249
|
+
* <template>
|
|
250
|
+
* <Request @request={{@request}}>
|
|
251
|
+
* <:content as |data state|>
|
|
252
|
+
* <h1>{{data.title}}</h1>
|
|
253
|
+
* {{#if state.isBackgroundReloading}}
|
|
254
|
+
* <SmallSpinner />
|
|
255
|
+
* <button {{on "click" state.abort}}>Cancel</button>
|
|
256
|
+
* {{/if}}
|
|
257
|
+
*
|
|
258
|
+
* <button {{on "click" state.refresh}}>Refresh</button>
|
|
259
|
+
* <button {{on "click" state.reload}}>Reload</button>
|
|
260
|
+
* </:content>
|
|
261
|
+
* </Request>
|
|
262
|
+
* </template>
|
|
263
|
+
* ```
|
|
264
|
+
*
|
|
265
|
+
* ## Advanced Reloading
|
|
266
|
+
*
|
|
267
|
+
* We can nest our usage of `<Request />` to handle more advanced
|
|
268
|
+
* reloading scenarios.
|
|
269
|
+
*
|
|
270
|
+
* ```gjs
|
|
271
|
+
* import { Request } from '@warp-drive/ember';
|
|
272
|
+
*
|
|
273
|
+
* <template>
|
|
274
|
+
* <Request @request={{@request}}>
|
|
275
|
+
* <:cancelled>
|
|
276
|
+
* <h2>The Request Cancelled</h2>
|
|
277
|
+
* </:cancelled>
|
|
278
|
+
*
|
|
279
|
+
* <:error as |error|>
|
|
280
|
+
* <ErrorForm @error={{error}} />
|
|
281
|
+
* </:error>
|
|
282
|
+
*
|
|
283
|
+
* <:content as |result state|>
|
|
284
|
+
* <Request @request={{state.latestRequest}}>
|
|
285
|
+
* <!-- Handle Background Request -->
|
|
286
|
+
* </Request>
|
|
287
|
+
*
|
|
288
|
+
* <h1>{{result.title}}</h1>
|
|
289
|
+
*
|
|
290
|
+
* <button {{on "click" state.refresh}}>Refresh</button>
|
|
291
|
+
* </:content>
|
|
292
|
+
* </Request>
|
|
293
|
+
* </template>
|
|
294
|
+
* ```
|
|
295
|
+
*
|
|
296
|
+
* ## Autorefresh
|
|
297
|
+
*
|
|
298
|
+
* `<Request />` supports automatic refresh and reload under certain conditions.
|
|
299
|
+
*
|
|
300
|
+
* - `online`: This occurs when a browser window or tab comes back to the foreground
|
|
301
|
+
* after being backgrounded or when the network reports as being online after
|
|
302
|
+
* having been offline.
|
|
303
|
+
* - `interval`: This occurs when a specified amount of time has passed.
|
|
304
|
+
* - `invalid`: This occurs when the store emits a notification that the request
|
|
305
|
+
* has become invalid.
|
|
306
|
+
*
|
|
307
|
+
* You can specify when autorefresh should occur by setting the `autorefresh` arg
|
|
308
|
+
* to `true` or a comma-separated list of the above values.
|
|
309
|
+
*
|
|
310
|
+
* A value of `true` is equivalent to `'online,invalid'`.
|
|
311
|
+
*
|
|
312
|
+
* By default, an autorefresh will only occur if the browser was backgrounded or
|
|
313
|
+
* offline for more than 30s before coming back available. This amount of time can
|
|
314
|
+
* be tweaked by setting the number of milliseconds via `@autorefreshThreshold`.
|
|
315
|
+
*
|
|
316
|
+
* This arg also controls the interval at which the request will be refreshed
|
|
317
|
+
* if the `interval` autorefresh type is enabled.
|
|
318
|
+
*
|
|
319
|
+
* Finally, the behavior of the request initiated by autorefresh can be adjusted
|
|
320
|
+
* by setting the `autorefreshBehavior` arg to `'refresh'`, `'reload'`, or `'policy'`.
|
|
321
|
+
*
|
|
322
|
+
* - `'refresh'`: Refresh the request in the background
|
|
323
|
+
* - `'reload'`: Force a reload of the request
|
|
324
|
+
* - `'policy'` (**default**): Let the store's configured CachePolicy decide whether to
|
|
325
|
+
* reload, refresh, or do nothing.
|
|
326
|
+
*
|
|
327
|
+
* More advanced refresh and reload behaviors can be created by passing the reload and
|
|
328
|
+
* refresh actions into another component. For instance, refresh could be set up on a
|
|
329
|
+
* timer or on a websocket subscription.
|
|
330
|
+
*
|
|
331
|
+
*
|
|
332
|
+
* ```gjs
|
|
333
|
+
* import { Request } from '@warp-drive/ember';
|
|
334
|
+
*
|
|
335
|
+
* <template>
|
|
336
|
+
* <Request @request={{@request}}>
|
|
337
|
+
* <:content as |result state|>
|
|
338
|
+
* <h1>{{result.title}}</h1>
|
|
339
|
+
*
|
|
340
|
+
* <Interval @period={{30_000}} @fn={{state.refresh}} />
|
|
341
|
+
* <Subscribe @channel={{@someValue}} @fn={{state.refresh}} />
|
|
342
|
+
* </:content>
|
|
343
|
+
* </Request>
|
|
344
|
+
* </template>
|
|
345
|
+
* ```
|
|
346
|
+
*
|
|
347
|
+
* If a matching request is refreshed or reloaded by any other component,
|
|
348
|
+
* the `Request` component will react accordingly.
|
|
349
|
+
*
|
|
350
|
+
* ## Deduping
|
|
351
|
+
*
|
|
352
|
+
* The store dedupes requests by identity. If a request is made for the same identity
|
|
353
|
+
* from multiple `<Request />` components, even if the request is not referentially the
|
|
354
|
+
* same, only one actual request will be made.
|
|
355
|
+
*
|
|
54
356
|
*
|
|
55
|
-
* @
|
|
357
|
+
* @class <Request />
|
|
358
|
+
* @public
|
|
56
359
|
*/
|
|
57
360
|
export class Request<T, RT> extends Component<RequestSignature<T, RT>> {
|
|
58
361
|
/**
|
|
@@ -140,7 +443,7 @@ declare module '@warp-drive/ember/-private/request' {
|
|
|
140
443
|
_originalQuery: StoreRequestInput<T, RT> | undefined;
|
|
141
444
|
_subscription: object | null;
|
|
142
445
|
_subscribedTo: object | null;
|
|
143
|
-
constructor(owner:
|
|
446
|
+
constructor(owner: Owner, args: RequestSignature<T, RT>['Args']);
|
|
144
447
|
beginPolling(): Promise<void>;
|
|
145
448
|
get isIdle(): boolean;
|
|
146
449
|
get autorefreshTypes(): Set<AutorefreshBehaviorType>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/-private/request.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/-private/request.ts"],"names":[],"mappings":"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"}
|
|
@@ -3,6 +3,25 @@
|
|
|
3
3
|
/// <reference path="./-private/await.d.ts" />
|
|
4
4
|
/// <reference path="./-private/request.d.ts" />
|
|
5
5
|
declare module '@warp-drive/ember' {
|
|
6
|
+
/**
|
|
7
|
+
* <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>
|
|
8
|
+
*
|
|
9
|
+
* ## Installation
|
|
10
|
+
*
|
|
11
|
+
* ```cli
|
|
12
|
+
* pnpm install @warp-drive/ember
|
|
13
|
+
* ```
|
|
14
|
+
*
|
|
15
|
+
* ## About
|
|
16
|
+
*
|
|
17
|
+
* This library provides reactive utilities for working with promises
|
|
18
|
+
* and requests, building over these primitives to provide functions
|
|
19
|
+
* and components that enable you to build robust performant apps with
|
|
20
|
+
* elegant control flow.
|
|
21
|
+
*
|
|
22
|
+
* @module @warp-drive/ember
|
|
23
|
+
* @main @warp-drive/ember
|
|
24
|
+
*/
|
|
6
25
|
export { getRequestState } from '@warp-drive/ember/-private/request-state';
|
|
7
26
|
export { getPromiseState } from '@warp-drive/ember/-private/promise-state';
|
|
8
27
|
export { Request } from '@warp-drive/ember/-private/request.gts';
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC"}
|