@akilin/api-kit 0.1.0 → 0.2.0
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 +13 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -46,6 +46,8 @@ export function useApi() {
|
|
|
46
46
|
|
|
47
47
|
```ts
|
|
48
48
|
// in a component
|
|
49
|
+
import { errorCodes, type User } from './api-types.g';
|
|
50
|
+
|
|
49
51
|
const api = useApi();
|
|
50
52
|
|
|
51
53
|
api.get<User>('/users/1')
|
|
@@ -60,11 +62,18 @@ api.get<User>('/users/1')
|
|
|
60
62
|
traces, not one render's.
|
|
61
63
|
- The handler gets the whole error, with its `code`, `status`, `field`, `headers` and `traceId` as well as `payload`.
|
|
62
64
|
- Pass the code from the generated `errorCodes` (or as a string literal). Its literal type selects the payload type; a
|
|
63
|
-
value typed `string` doesn't.
|
|
65
|
+
value typed `string` doesn't compile.
|
|
64
66
|
- Policies are fixed when the client is created, so they can't call React hooks: call a router instance or
|
|
65
67
|
`location` (see [Global error policies](#global-error-policies)).
|
|
66
68
|
- Type annotations you write yourself still take the map: `ApiError<AppErrors>`, `ApiResult<User, AppErrors>`.
|
|
67
69
|
|
|
70
|
+
The request and response types come from the generated file too, beside `AppErrors`: the generator writes every JSON
|
|
71
|
+
request body type and 2xx response body type of the API's endpoints, and the types nested in them, under their C#
|
|
72
|
+
names. Import them from there rather than declaring your own, so the compiler reports a DTO that changed on the
|
|
73
|
+
server once the file is regenerated. `User`, `Order` and the other types in the examples here are such generated
|
|
74
|
+
types. The client doesn't tie a route to its types: a call names the type it reads (`api.get<User>('/users/1')`), and
|
|
75
|
+
the body you pass is typed by your own annotation (`const form: CreateUser = …`).
|
|
76
|
+
|
|
68
77
|
`baseUrl` and the per-call url are joined with exactly one `/`, whichever side has it: `/api/` + `/users` and `/api` +
|
|
69
78
|
`users` both fetch `/api/users`. A url that is empty or starts with `?`/`#` is appended as it is (`/api/users` +
|
|
70
79
|
`?page=2`). An absolute per-call url (`https://files.example.com/a.pdf`, `//host/…`) is fetched as it is, without
|
|
@@ -134,7 +143,9 @@ fails as kind `unexpected`.
|
|
|
134
143
|
(`error.headers?.get('Retry-After')`).
|
|
135
144
|
|
|
136
145
|
`PagedData<T>` is the body of a paged list, as the server's `PagedData<T>` (package `akilin.ApiKit`) writes it:
|
|
137
|
-
`api.get<PagedData<User>>('/users', { query: { pageNumber: 2 } })` resolves with `{ data, totalPages }`.
|
|
146
|
+
`api.get<PagedData<User>>('/users', { query: { pageNumber: 2 } })` resolves with `{ data, totalPages }`. Import it
|
|
147
|
+
from this package (`import type { PagedData } from '@akilin/api-kit'`): the generated file imports it from here too
|
|
148
|
+
when one of its types has a `PagedData` member, and doesn't declare one of its own.
|
|
138
149
|
|
|
139
150
|
## Per-call handlers
|
|
140
151
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@akilin/api-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Library-agnostic TypeScript API client for akilin.ApiKit (RFC 9457 Problem Details) APIs. Personal project — not intended for use by others; no support or stability guarantees.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "akilin",
|