@art-suite/art-core-ts-communication-status 0.3.4 → 0.3.6
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/README.md +30 -27
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,11 +1,25 @@
|
|
|
1
1
|
# @art-suite/art-core-ts-communication-status
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
_When writing HTTP APIs, error handling doesn't need to be such a pain!_
|
|
4
|
+
|
|
5
|
+
Simplifies all API communication-related state down to just 9, human-readable AND machine-interptable statuses, 4 of which HTTP doesn't even handle!
|
|
6
|
+
|
|
7
|
+
- `"success"`
|
|
8
|
+
- `"missing"`
|
|
9
|
+
- `"clientFailure"`
|
|
10
|
+
- `"clientFailureNotAuthorized"`
|
|
11
|
+
- `"serverFailure"`
|
|
12
|
+
- `"networkFailure"`
|
|
13
|
+
- `"timeoutFailure"`
|
|
14
|
+
- `"aborted"`
|
|
15
|
+
- `"pending"`
|
|
4
16
|
|
|
5
17
|
## Why This Module?
|
|
6
18
|
|
|
7
19
|
HTTP status codes confound two distinct purposes: providing machine-actionable status codes and conveying semantic information about errors to humans. This dual purpose leads to complexity and confusion in client-side code that needs to handle different types of failures appropriately.
|
|
8
20
|
|
|
21
|
+
Further, not all errors are captured by the HTTP status codes - i.e. network failures.
|
|
22
|
+
|
|
9
23
|
This library teases apart these concerns by focusing solely on what software can act on. It reduces the complex space of HTTP status codes and other communication states into a small set of actionable categories that make client-side code simpler and more robust.
|
|
10
24
|
|
|
11
25
|
A comprehensive set of status types (simple enumerated strings e.g. "success") that cover all possible machine-actionable communication states, including situations HTTP status codes don't address (like network failures and aborted requests).
|
|
@@ -22,32 +36,17 @@ Basic usage:
|
|
|
22
36
|
|
|
23
37
|
```ts
|
|
24
38
|
import {
|
|
25
|
-
success,
|
|
26
|
-
serverFailure,
|
|
27
|
-
clientFailure,
|
|
28
|
-
clientFailureNotAuthorized,
|
|
29
|
-
missing,
|
|
30
|
-
networkFailure,
|
|
31
|
-
aborted,
|
|
32
|
-
pending,
|
|
33
39
|
isSuccess,
|
|
34
40
|
isServerFailure,
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
isMissing,
|
|
38
|
-
isNetworkFailure,
|
|
39
|
-
isAborted,
|
|
40
|
-
isPending,
|
|
41
|
+
success, // === "success"
|
|
42
|
+
missing, // === "missing"
|
|
41
43
|
} from "@art-suite/art-core-ts-communication-status";
|
|
42
44
|
|
|
43
45
|
// Handle success
|
|
44
|
-
if (isSuccess(status)) {
|
|
45
|
-
}
|
|
46
|
+
if (isSuccess(status)) {...}
|
|
46
47
|
|
|
47
48
|
// Simply handle all server failures
|
|
48
|
-
if (isServerFailure(status)) {
|
|
49
|
-
// Handle server failure
|
|
50
|
-
}
|
|
49
|
+
if (isServerFailure(status)) {...}
|
|
51
50
|
|
|
52
51
|
// or Handle multiple statues as a simple switch:
|
|
53
52
|
switch (status) {
|
|
@@ -64,28 +63,32 @@ switch (status) {
|
|
|
64
63
|
|
|
65
64
|
### Status Types
|
|
66
65
|
|
|
66
|
+
Status are strings, or you can import constants with the identical name referencing the strings:
|
|
67
|
+
|
|
67
68
|
- **Success Status:**
|
|
68
69
|
|
|
69
|
-
- `success` —
|
|
70
|
+
- `success` — hurray! (2xx)
|
|
70
71
|
|
|
71
72
|
- **Missing Status:**
|
|
72
73
|
|
|
73
|
-
- `missing` —
|
|
74
|
+
- `missing` — _resource not available_ (404, 501)
|
|
74
75
|
|
|
75
76
|
- **Client-side Failures:**
|
|
76
77
|
|
|
77
|
-
- `clientFailure` —
|
|
78
|
-
- `clientFailureNotAuthorized` —
|
|
78
|
+
- `clientFailure` — _client bug_ (4xx except 404, 505, 530)
|
|
79
|
+
- `clientFailureNotAuthorized` — _bad auth_ (401, 403, 407, 451, 511)
|
|
79
80
|
|
|
80
81
|
- **Server-side Failures:**
|
|
81
82
|
|
|
82
|
-
- `serverFailure` —
|
|
83
|
+
- `serverFailure` — _server/infra bug_ (5xx other than 501, 505, 511, 530)
|
|
83
84
|
|
|
84
|
-
- **Non HTTP Failure
|
|
85
|
+
- **Non HTTP Failure Statuses:**
|
|
85
86
|
- `networkFailure` — Network connectivity issues
|
|
87
|
+
- `timeoutFailure` - Request timed out
|
|
88
|
+
|
|
89
|
+
- **Liminal Statuses:** (not errors, not success)
|
|
86
90
|
- `aborted` — Request was cancelled
|
|
87
91
|
- `pending` — Request is in progress
|
|
88
|
-
- `timeoutFailure` - Request timed out
|
|
89
92
|
|
|
90
93
|
### Type Guards
|
|
91
94
|
|