@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.
Files changed (2) hide show
  1. package/README.md +13 -2
  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.1.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",