-
Notifications
You must be signed in to change notification settings - Fork 643
/
api-controller.ts
276 lines (252 loc) · 10 KB
/
api-controller.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
/* eslint-disable max-len */
/* eslint no-unused-vars: 0 */
import populator from '../utils/populator/populator'
import ViewHelpers from '../utils/view-helpers/view-helpers'
import { CurrentAdmin } from '../../current-admin.interface'
import AdminBro from '../../admin-bro'
import { ActionContext, ActionRequest, RecordActionResponse, ActionResponse, BulkActionResponse } from '../actions/action.interface'
import ConfigurationError from '../utils/errors/configuration-error'
import NotFoundError from '../utils/errors/not-found-error'
import { requestParser } from '../utils/request-parser'
import { SearchActionResponse } from '../actions/search/search-action'
/**
* Controller responsible for the auto-generated API: `/admin_root/api/...`, where
* _admin_root_ is the `rootPath` given in {@link AdminBroOptions}.
*
* The best way to utilise it is to use {@link ApiClient} on the frontend.
*
* ### Available API endpoints
*
* <div class='table-container'>
*
* | Endpoint | Method | Description |
* |--------------------------|-----------------------|-------------|
* | .../api/resources/{resourceId}/actions/{action} | {@link ApiController#resourceAction} | Perform customized resource action |
* | .../api/resources/{resourceId}/records/{recordId}/{action} | {@link ApiController#recordAction} | Perform customized record action |
* | .../api/resources/{resourceId}/bulk/{action}?recordIds={recordIds} | {@link ApiController#bulkAction} | Perform customized bulk action |
* | .../api/pages/{pageName}_ | {@link ApiController#page} | Perform customized page action |
* | .../api/dashboard_ | {@link ApiController#dashboard} | Perform customized dashboard action |
*
* </div>
*
* ### Responsibility
*
* In general this controllers takes handler functions you define in {@link AdminBroOptions} and:
* - find all the [context information]{@link ActionContext} which is needed by the action
* and is passed to the {@link Action#handler}, {@link Action#before} and {@link Action#after}
* - checks if action can be invoked by particular user {@link Action#isAccessible}
* - invokes {@link Action#before} and {@link Action#after} hooks
*
* You probably don't want to modify it, but you can call its methods by using {@link ApiClient}
*
* @hideconstructor
*/
class ApiController {
private _admin: AdminBro
private currentAdmin: CurrentAdmin
/**
* @param {Object} options
* @param {AdminBroOptions} options.admin
* @param {CurrentAdmin} [currentAdmin]
*/
constructor({ admin }, currentAdmin) {
this._admin = admin
this.currentAdmin = currentAdmin
}
/**
* Returns context for given action
* @private
*
* @param {ActionRequest} request request object
* @return {Promise<ActionContext>} action context
*/
async getActionContext(request: ActionRequest): Promise<ActionContext> {
const { resourceId, action: actionName } = request.params
const h = new ViewHelpers(this._admin)
const resource = this._admin.findResource(resourceId)
const action = resource.decorate().actions[actionName]
return {
resource,
action,
h,
currentAdmin: this.currentAdmin,
_admin: this._admin,
...this._admin.translateFunctions,
}
}
/**
* Search records by query string.
*
* Handler function responsible for a _.../api/resources/{resourceId}/search/{query}_ route
*
* @param {ActionRequest} request with __params.query__ set
* @param {any} response
*
* @return {Promise<SearchActionResponse>} found records
*/
async search(request: ActionRequest, response): Promise<SearchActionResponse> {
request.params.action = 'search'
// eslint-disable-next-line no-console
console.log([
'Using ApiController#search is deprecated in favour of resourceAction',
'It will be removed in the next version',
].join('\n'))
return this.resourceAction(request, response) as Promise<SearchActionResponse>
}
/**
* Performs a customized {@link Action resource action}.
* To call it use {@link ApiClient#resourceAction} method.
*
* Handler function responsible for a _.../api/resources/{resourceId}/actions/{action}_
*
* @param {ActionRequest} originalRequest
* @param {any} response object from the plugin (i.e. admin-bro-expressjs)
*
* @return {Promise<ActionResponse>} action response
*/
async resourceAction(originalRequest: ActionRequest, response: any): Promise<ActionResponse> {
const actionContext = await this.getActionContext(originalRequest)
const request = requestParser(originalRequest, actionContext.resource)
return actionContext.action.handler(request, response, actionContext)
}
/**
* Performs a customized {@link Action record action}.
* To call it use {@link ApiClient#recordAction} method.
*
* Handler function responsible for a _.../api/resources/{resourceId}/records/{recordId}/{action}_
*
* @param {ActionRequest} originalRequest
* @param {any} response
*
* @return {Promise<RecordActionResponse>} action response
* @throws ConfigurationError When given record action doesn't return {@link RecordJSON}
* @throws ConfigurationError when action handler doesn't return Promise<{@link RecordActionResponse}>
*/
async recordAction(originalRequest: ActionRequest, response: any): Promise<RecordActionResponse> {
const { recordId, resourceId } = originalRequest.params
const actionContext = await this.getActionContext(originalRequest)
const request = requestParser(originalRequest, actionContext.resource)
if (!recordId) {
throw new NotFoundError([
'You have to pass recordId to the recordAction',
].join('\n'), 'Action#handler')
}
let record = await actionContext.resource.findOne(recordId)
if (!record) {
throw new NotFoundError([
`record with given id: "${recordId}" cannot be found in resource "${resourceId}"`,
].join('\n'), 'Action#handler')
}
[record] = await populator([record])
actionContext.record = record
const jsonWithRecord = await actionContext.action.handler(request, response, actionContext)
const isValidRecord = !!(jsonWithRecord && jsonWithRecord.record && jsonWithRecord.record.recordActions)
const anErrorWasHandled = jsonWithRecord && jsonWithRecord.notice && jsonWithRecord.notice.type === 'error'
if (isValidRecord || anErrorWasHandled) {
return jsonWithRecord
}
throw new ConfigurationError(
'handler of a recordAction should return a RecordJSON object',
'Action#handler',
)
}
/**
* Performs a customized {@link Action bulk action}.
* To call it use {@link ApiClient#bulkAction} method.
*
* Handler function responsible for a _.../api/resources/{resourceId}/bulk/{action}?recordIds={recordIds}_
*
* @param {ActionRequest} request
* @param {any} response
*
* @return {Promise<BulkActionResponse>} action response
* @throws NotFoundError when recordIds are missing in query or they don't exists in
* the database
* @throws ConfigurationError when action handler doesn't return Promise<{@link BulkActionResponse}>
*/
async bulkAction(originalRequest: ActionRequest, response: any): Promise<BulkActionResponse> {
const { resourceId } = originalRequest.params
const { recordIds } = originalRequest.query || {}
const actionContext = await this.getActionContext(originalRequest)
const request = requestParser(originalRequest, actionContext.resource)
if (!recordIds) {
throw new NotFoundError([
'You have to pass "recordIds" to the bulkAction via search params: ?recordIds=...',
].join('\n'), 'Action#handler')
}
let records = await actionContext.resource.findMany(recordIds.split(','))
if (!records || !records.length) {
throw new NotFoundError([
`record with given id: "${recordIds}" cannot be found in resource "${resourceId}"`,
].join('\n'), 'Action#handler')
}
records = await populator(records)
const jsonWithRecord = await actionContext.action.handler(request, response, { ...actionContext, records })
if (jsonWithRecord && jsonWithRecord.records) {
return jsonWithRecord
}
throw new ConfigurationError(
'handler of a bulkAction should return an Array of RecordJSON object',
'Action#handler',
)
}
/**
* Gets optional data needed by the dashboard.
* To call it use {@link ApiClient#getDashboard} method.
*
* Handler function responsible for a _.../api/dashboard_
*
* @param {ActionRequest} request
* @param {any} response
*
* @return {Promise<any>} action response
*/
async dashboard(request: any, response: any): Promise<any> {
const h = new ViewHelpers(this._admin)
const handler = this._admin.options.dashboard && this._admin.options.dashboard.handler
if (handler) {
return handler(request, response, {
h,
currentAdmin: this.currentAdmin,
_admin: this._admin,
})
}
return {
message: [
'You can override this method by setting up dashboard.handler',
'function in AdminBro options',
].join('\n'),
}
}
/**
* Gets optional data needed by the page.
* To call it use {@link ApiClient#getPage} method.
*
* Handler function responsible for a _.../api/pages/{pageName}_
*
* @param {ActionRequest} request
* @param {any} response
*
* @return {Promise<any>} action response
*/
async page(request: any, response: any): Promise<any> {
const h = new ViewHelpers(this._admin)
const { pages = {} } = this._admin.options
const { pageName } = request.params
const { handler } = (pages[pageName] || {})
if (handler) {
return handler(request, response, {
h,
currentAdmin: this.currentAdmin,
_admin: this._admin,
})
}
return {
message: [
'You can override this method by setting up pages[pageName].handler',
'function in AdminBro options',
].join('\n'),
}
}
}
export default ApiController