@tramvai/papi 2.94.7 → 2.94.9
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 +5 -157
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,170 +5,18 @@ sidebar_position: 4
|
|
|
5
5
|
|
|
6
6
|
# Papi
|
|
7
7
|
|
|
8
|
-
Library for creating and working with papi handlers.
|
|
8
|
+
Library for creating and working with papi handlers.
|
|
9
|
+
|
|
10
|
+
Complete information about papi feature you can find [here](03-features/016-papi.md)
|
|
9
11
|
|
|
10
12
|
## Installation
|
|
11
13
|
|
|
12
14
|
You need to install `@tramvai/papi`
|
|
13
15
|
|
|
14
|
-
```bash
|
|
15
|
-
|
|
16
|
+
```bash
|
|
17
|
+
npx tramvai add @tramvai/papi
|
|
16
18
|
```
|
|
17
19
|
|
|
18
20
|
## Explanation
|
|
19
21
|
|
|
20
22
|
Library mostly provides strong typings to papi handlers and most of the logic of integration it to the tramvai app is done by [@tramvai/module-server](references/modules/server.md)
|
|
21
|
-
|
|
22
|
-
## Api
|
|
23
|
-
|
|
24
|
-
### createPapiMethod
|
|
25
|
-
|
|
26
|
-
Options:
|
|
27
|
-
|
|
28
|
-
- `path` - specifies the path of url that current papi should handle. Required when specifying papi in tramvai DI, and not used when specified through file api.
|
|
29
|
-
- `method` - specified HTTP-method that is acceptable by current papi. By default, it equals to "all"
|
|
30
|
-
- `handler` - see [handler](#handler)
|
|
31
|
-
- `deps` - any DI deps that papi may require
|
|
32
|
-
- `options` - additional options that controls how current papi works
|
|
33
|
-
- `timeout` - timeout for executing current papi. If timeout exceeded request is resolved with Execution timeout error.
|
|
34
|
-
|
|
35
|
-
#### handler
|
|
36
|
-
|
|
37
|
-
Function that handles actual request and should return. It accepts the details of the request and should return the response
|
|
38
|
-
|
|
39
|
-
Details of the request are passed with first parameter when handler is called. You can see available properties in typings when specifying papi method. It should provide most of the data that might be required to handle the request.
|
|
40
|
-
|
|
41
|
-
Additionally, though `this` passed data that bounded to papi method:
|
|
42
|
-
|
|
43
|
-
- `deps` - resolved deps that were specified when defining papi method. Deps are resolved with [Child DI Container](concepts/di.md#container-is-a-child), so do not use it for creating caches as it won't work.
|
|
44
|
-
- `log` - instance of [LOGGER_TOKEN](references/modules/log.md#logger_token) bounded with current papi method
|
|
45
|
-
|
|
46
|
-
### isPapiMethod
|
|
47
|
-
|
|
48
|
-
Type guard to check is passed object is papi handler
|
|
49
|
-
|
|
50
|
-
## How to
|
|
51
|
-
|
|
52
|
-
### Create simple papi
|
|
53
|
-
|
|
54
|
-
```tsx
|
|
55
|
-
import { createPapiMethod } from '@tramvai/papi';
|
|
56
|
-
|
|
57
|
-
export const papi = createPapiMethod({
|
|
58
|
-
// will handle requests to `/app/papi/my/papi` (actual url depends on setup)
|
|
59
|
-
path: '/my/papi',
|
|
60
|
-
// only requests with GET http method will be handled
|
|
61
|
-
method: 'get',
|
|
62
|
-
// function to return response to the client
|
|
63
|
-
async handler() {
|
|
64
|
-
return 'test';
|
|
65
|
-
},
|
|
66
|
-
});
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
### Use parameters of the request
|
|
70
|
-
|
|
71
|
-
```tsx
|
|
72
|
-
import { createPapiMethod } from '@tramvai/papi';
|
|
73
|
-
|
|
74
|
-
export const papi = createPapiMethod({
|
|
75
|
-
async handler({ parsedUrl: { query }, cookies }) {
|
|
76
|
-
const { a, b } = query;
|
|
77
|
-
const { testCookie } = cookie;
|
|
78
|
-
|
|
79
|
-
return {
|
|
80
|
-
testCookie,
|
|
81
|
-
a,
|
|
82
|
-
b,
|
|
83
|
-
};
|
|
84
|
-
},
|
|
85
|
-
});
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
### Settings headers and status
|
|
89
|
-
|
|
90
|
-
It can be done with [responseManager](references/tokens/common.md#responsemanager-tokens)
|
|
91
|
-
|
|
92
|
-
```tsx
|
|
93
|
-
import { createPapiMethod } from '@tramvai/papi';
|
|
94
|
-
|
|
95
|
-
export const papi = createPapiMethod({
|
|
96
|
-
async handler({ responseManager }) {
|
|
97
|
-
responseManager.setHeader('content-type', 'text/html');
|
|
98
|
-
responseManager.setStatus(200);
|
|
99
|
-
|
|
100
|
-
return `<html>...</html>`;
|
|
101
|
-
},
|
|
102
|
-
});
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
### Use deps
|
|
106
|
-
|
|
107
|
-
```tsx
|
|
108
|
-
import { createPapiMethod } from '@tramvai/papi';
|
|
109
|
-
|
|
110
|
-
export const papi = createPapiMethod({
|
|
111
|
-
async handler() {
|
|
112
|
-
const { cookieManager } = this.deps;
|
|
113
|
-
|
|
114
|
-
cookieManager.set({ name: 'b', value: 'abc', expires: 35 });
|
|
115
|
-
|
|
116
|
-
return 'response';
|
|
117
|
-
},
|
|
118
|
-
deps: {
|
|
119
|
-
cookieManager: COOKIE_MANAGER_TOKEN,
|
|
120
|
-
},
|
|
121
|
-
});
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
### Use cache with deps
|
|
125
|
-
|
|
126
|
-
Deps are resolved with ChildContainer that means they are getting resolved on every request in order to provide request specific info. To use any of deps that should outlive scope of the request you should use provider that was initialized with [scope=SINGLETON](concepts/di.md#root-container)
|
|
127
|
-
|
|
128
|
-
For example, if you want to use some papi specific cache you should create new token and provide the cache instance with that token and with option `scope: Scope.SINGLETON`
|
|
129
|
-
|
|
130
|
-
```tsx
|
|
131
|
-
import { createToken, Scope, provide } from '@tinkoff/dippy';
|
|
132
|
-
import { createApp } from '@tramvai/core';
|
|
133
|
-
import { createPapiMethod } from '@tramvai/papi';
|
|
134
|
-
import { Cache, CREATE_CACHE_TOKEN } from '@tramvai/tokens-common';
|
|
135
|
-
|
|
136
|
-
export const PAPI_CACHE_TOKEN = createToken<Cache<string>>('app papi cache');
|
|
137
|
-
|
|
138
|
-
const app = createApp({
|
|
139
|
-
// ...,
|
|
140
|
-
providers: [
|
|
141
|
-
// ...,
|
|
142
|
-
provide({
|
|
143
|
-
provide: PAPI_CACHE_TOKEN,
|
|
144
|
-
scope: Scope.SINGLETON,
|
|
145
|
-
useFactory: ({ createCache }) => {
|
|
146
|
-
return createCache('memory');
|
|
147
|
-
},
|
|
148
|
-
deps: {
|
|
149
|
-
createCache: CREATE_CACHE_TOKEN,
|
|
150
|
-
},
|
|
151
|
-
}),
|
|
152
|
-
],
|
|
153
|
-
});
|
|
154
|
-
|
|
155
|
-
export const papi = createPapiMethod({
|
|
156
|
-
async handler({ parsedUrl: { query } }) {
|
|
157
|
-
const { cacheKey } = query;
|
|
158
|
-
const { cache } = this.deps;
|
|
159
|
-
|
|
160
|
-
if (cache.has(cacheKey)) {
|
|
161
|
-
return cache.get(cacheKey);
|
|
162
|
-
}
|
|
163
|
-
|
|
164
|
-
const result = heavyComputation();
|
|
165
|
-
|
|
166
|
-
cache.set(cacheKey, result);
|
|
167
|
-
|
|
168
|
-
return result;
|
|
169
|
-
},
|
|
170
|
-
deps: {
|
|
171
|
-
cache: PAPI_CACHE_TOKEN,
|
|
172
|
-
},
|
|
173
|
-
});
|
|
174
|
-
```
|