@unireq/core 1.0.0 → 1.0.1
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 +98 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# @unireq/core
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@unireq/core)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
|
|
6
|
+
The core package provides the foundational building blocks for the Unireq ecosystem: client creation, policy composition, flow-control primitives, introspection, validation, and the DX-focused error catalog.
|
|
7
|
+
|
|
8
|
+
## Installation
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
pnpm add @unireq/core
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Quick Start
|
|
15
|
+
|
|
16
|
+
```typescript
|
|
17
|
+
import { client, retry, backoff } from '@unireq/core';
|
|
18
|
+
import { http, headers, timeout, parse } from '@unireq/http';
|
|
19
|
+
|
|
20
|
+
const api = client(
|
|
21
|
+
http('https://api.example.com'),
|
|
22
|
+
headers({ 'x-api-key': 'secret' }),
|
|
23
|
+
timeout(10_000),
|
|
24
|
+
retry(httpRetryPredicate(), [backoff()], { tries: 3 }),
|
|
25
|
+
parse.json(),
|
|
26
|
+
);
|
|
27
|
+
|
|
28
|
+
const user = await api.get('/users/42');
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Features
|
|
32
|
+
|
|
33
|
+
| Category | Symbols | Purpose |
|
|
34
|
+
| --- | --- | --- |
|
|
35
|
+
| Client factory | `client`, `Policy`, `Transport` | Create clients by composing transports + policies |
|
|
36
|
+
| Composition | `compose`, `either`, `match`, `policy`, `slot` | Build reusable middleware stacks |
|
|
37
|
+
| Flow control | `retry`, `backoff`, `circuitBreaker`, `throttle` | Resilience with retries, backoff, circuit breaking |
|
|
38
|
+
| Introspection | `inspect`, `inspectable`, `getHandlerGraph`, `log` | Trace policy graphs and structured logging |
|
|
39
|
+
| Validation | `validate`, `ValidationAdapter` | Guarantee typed responses with any schema library |
|
|
40
|
+
| Errors | `HttpError`, `TimeoutError`, `NetworkError` | Consistent error surface |
|
|
41
|
+
|
|
42
|
+
## Policy Composition
|
|
43
|
+
|
|
44
|
+
```typescript
|
|
45
|
+
import { compose, either } from '@unireq/core';
|
|
46
|
+
import { parse } from '@unireq/http';
|
|
47
|
+
import { xml } from '@unireq/xml';
|
|
48
|
+
|
|
49
|
+
const smartParser = compose(
|
|
50
|
+
either(
|
|
51
|
+
(ctx) => ctx.headers.accept?.includes('application/json') ?? false,
|
|
52
|
+
parse.json(),
|
|
53
|
+
xml(),
|
|
54
|
+
),
|
|
55
|
+
);
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Validation with Zod
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
import { client, validate } from '@unireq/core';
|
|
62
|
+
import { http, parse } from '@unireq/http';
|
|
63
|
+
import { z } from 'zod';
|
|
64
|
+
|
|
65
|
+
const UserSchema = z.object({
|
|
66
|
+
id: z.number(),
|
|
67
|
+
email: z.string().email(),
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
const zodAdapter = {
|
|
71
|
+
validate: (schema, data) => schema.parse(data),
|
|
72
|
+
};
|
|
73
|
+
|
|
74
|
+
const api = client(
|
|
75
|
+
http('https://api.example.com'),
|
|
76
|
+
parse.json(),
|
|
77
|
+
validate(UserSchema, zodAdapter),
|
|
78
|
+
);
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Error Handling
|
|
82
|
+
|
|
83
|
+
Every error extends `UnireqError` with a stable `code` string:
|
|
84
|
+
|
|
85
|
+
- `NetworkError` - DNS failures, connection resets, TLS issues
|
|
86
|
+
- `TimeoutError` - Request timeout exceeded
|
|
87
|
+
- `HttpError` - HTTP error responses
|
|
88
|
+
- `SerializationError` - Body parsing/encoding issues
|
|
89
|
+
- `DuplicatePolicyError` - Slot conflicts
|
|
90
|
+
- `MissingCapabilityError` - Transport lacks required capability
|
|
91
|
+
|
|
92
|
+
## Documentation
|
|
93
|
+
|
|
94
|
+
Full documentation available at [unireq.dev](https://oorabona.github.io/unireq/)
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
MIT
|