1 | # Light-ning (Framework)
|
2 |
|
3 | <br>
|
4 |
|
5 | ``Light as a feather, fast as lightning...``
|
6 |
|
7 | ``Full ES5 support``
|
8 |
|
9 | ## "To the game, Sherlock!"
|
10 | <br>
|
11 |
|
12 | ```
|
13 | import app from 'light-ning';
|
14 | ```
|
15 | ```
|
16 | app.run()
|
17 | ```
|
18 |
|
19 | #### Important!
|
20 | <br>
|
21 |
|
22 | ``You need create the "controllers" and "routes" directories
|
23 | where are you calling "run" method.``
|
24 |
|
25 | *``create "controllers" directory only if you need to use actions in routes and controllers.``
|
26 |
|
27 | ```"routes" directory must include "index.js" file and import all your route-files therein:```
|
28 | <br>
|
29 |
|
30 | ```
|
31 | import './user'
|
32 | import './articles'
|
33 | ```
|
34 | etc.
|
35 |
|
36 | If your node js file (where are you calling "run" method)
|
37 | not in root directory, you need to set prefix before the "run":
|
38 | ```
|
39 | app.set('prefix', 'path to directory');
|
40 | app.run()
|
41 | ```
|
42 |
|
43 | ## Router:
|
44 | <br>
|
45 |
|
46 | ```
|
47 | import { Router } from 'light-ning';
|
48 | ```
|
49 |
|
50 | #### Actions
|
51 | <br>
|
52 |
|
53 | ```
|
54 | Router.routes('/user', [
|
55 | {
|
56 | method: 'GET',
|
57 | path: '/',
|
58 | action: 'User@index',
|
59 | },
|
60 | {
|
61 | method: 'GET',
|
62 | path: '/:id',
|
63 | action: 'User@show',
|
64 | },
|
65 | {
|
66 | method: 'POST',
|
67 | path: '/',
|
68 | action: 'User@create',
|
69 | },
|
70 | {
|
71 | method: 'PUT',
|
72 | path: '/:id',
|
73 | action: 'User@update',
|
74 | },
|
75 | {
|
76 | method: 'DELETE',
|
77 | path: '/:id',
|
78 | action: 'User@destroy',
|
79 | },
|
80 | ]);
|
81 |
|
82 | ```
|
83 |
|
84 | You'll can write ``method`` property
|
85 | in any register ``'POST'`` or ``'post'`` etc.
|
86 |
|
87 | Property "action" it's a path of two parts: ControllerName@Method.
|
88 | (It work only if you use Controllers).
|
89 |
|
90 | What action do:
|
91 | ``User@index`` equals ``UserController.index(req, res)``
|
92 | and pass object with ``req, res, etc.`` options in "index" method. [More below...](#controllers)
|
93 |
|
94 | #### Middlewares
|
95 | <br>
|
96 |
|
97 | ```
|
98 | Router.routes('/user', [
|
99 | {
|
100 | method: 'GET',
|
101 | path: '/',
|
102 | middleWares: [ firstFunc, secondFunc ],
|
103 | },
|
104 | ]);
|
105 | ```
|
106 |
|
107 | Middlewares performed in succession from left to right.
|
108 | For pass the course, you need call "next" in your middleware:
|
109 |
|
110 | ```
|
111 | const middleware = next => {
|
112 |
|
113 | if (true) {
|
114 | next();
|
115 | } else {
|
116 | throw new Error('access denied');
|
117 | }
|
118 |
|
119 | }
|
120 | ```
|
121 |
|
122 | You'll can pass data in your middleware like this:
|
123 |
|
124 | ```
|
125 | const middleware_1 = next => {
|
126 | if (true) {
|
127 | next(anyData);
|
128 | }
|
129 | }
|
130 | ```
|
131 | ```
|
132 | const middleware_2 = (data, next) => {
|
133 | console.log(data); // anyData
|
134 | }
|
135 | ```
|
136 | #### Important!
|
137 | <br>
|
138 |
|
139 | ``Do not place "middleWares" with "action" in one route. In this case, "middleWares" will be ignored.``
|
140 |
|
141 | ``Controllers and Methods names - can be any.``
|
142 |
|
143 | #### Guard
|
144 | <br>
|
145 |
|
146 | You'll can use guard property for add your guardian middleware.
|
147 |
|
148 | ```
|
149 | Router.routes('/user', [
|
150 | {
|
151 | method: 'GET',
|
152 | path: '/',
|
153 | guard: guardian,
|
154 | action: 'user@index'
|
155 | },
|
156 | ]);
|
157 |
|
158 | ```
|
159 |
|
160 | This route will not work until
|
161 | you call "next" in your guardian middleware:
|
162 |
|
163 | ```
|
164 | const guardian = ({req, next, response}) => {
|
165 |
|
166 | if (req.body.user === session.user) {
|
167 | next();
|
168 | } else {
|
169 | response({ code: 403 });
|
170 | }
|
171 |
|
172 | }
|
173 | ```
|
174 |
|
175 | ``guardian`` middleware get default ``req, res`` node js objects,
|
176 | ``next`` function for pass the course
|
177 | and custom ``response`` method for easy reponses.
|
178 | [More below...](#response)
|
179 |
|
180 | #### Root path
|
181 | <br>
|
182 |
|
183 | Setting the root path for group routes.
|
184 |
|
185 | ```
|
186 | Router.routes('/user', [
|
187 | ```
|
188 |
|
189 | ```
|
190 | {
|
191 | method: 'GET',
|
192 | path: '/',
|
193 | action: 'User@index',
|
194 | },
|
195 | {
|
196 | method: 'GET',
|
197 | path: '/:id',
|
198 | action: 'User@show',
|
199 | },
|
200 | ```
|
201 |
|
202 | This router create routes like:
|
203 |
|
204 | ```
|
205 | /user/
|
206 | /user/:id
|
207 | ```
|
208 | etc.
|
209 | <a name="controllers" id="controllers" href="controllers"></a>
|
210 |
|
211 | ## Controllers:
|
212 | <br>
|
213 |
|
214 | After route ``action: 'User@index'``, object with data get
|
215 | in controller. It looks like:
|
216 |
|
217 | ```
|
218 | {
|
219 | req: request, // default node js object
|
220 | res: response, // default node js object
|
221 | response: Response, // method for easy response
|
222 | }
|
223 | ```
|
224 |
|
225 |
|
226 | ```
|
227 | export default class UserController {
|
228 |
|
229 | index(data) {
|
230 | let {req, res} = data;
|
231 | }
|
232 |
|
233 | show({req, response}) {
|
234 | if (req.body.user === session.user) {
|
235 | return response({ data: session.user });
|
236 | }
|
237 |
|
238 | response({ code: 403 });
|
239 | }
|
240 | }
|
241 | ```
|
242 |
|
243 | If you not pass custom error into response object, they get
|
244 | default error from http-errors dictionary by status code.
|
245 | <a name="response" id="response" href="response"></a>
|
246 |
|
247 | Method "Response" has 3 params:
|
248 | ```
|
249 | {
|
250 | error: 'Are you ok?', // custom error
|
251 | code: 422, // status code
|
252 | data: []
|
253 | }
|
254 | ```
|
255 |
|
256 | #### Important!
|
257 | <br>
|
258 |
|
259 | * ``"error" must sending with "code" (code can sending without error)``
|
260 | * ``"data" must sending without "error" (in this case, data will be ignored)``
|
261 |
|
262 | ## Base Controller
|
263 |
|
264 | You'll can extend your controller from ``BaseController``:
|
265 | ```
|
266 | import { BaseController } from 'light-ning';
|
267 | ```
|
268 | ```
|
269 | export default class UserController extends BaseController {
|
270 |
|
271 | filter = ['password'];
|
272 |
|
273 | constructor() {
|
274 | super();
|
275 | }
|
276 |
|
277 | index({response}) {
|
278 | let user = {
|
279 | login: 'user',
|
280 | email: 'user@mail.com',
|
281 | password: 'secret'
|
282 | };
|
283 |
|
284 | let data = this.filtrate(user);
|
285 |
|
286 | console.log(data); // { login: 'user', email: 'user@mail.com' }
|
287 |
|
288 | response({ data: data });
|
289 | }
|
290 |
|
291 | };
|
292 |
|
293 | ```
|
294 |
|
295 | ``BaseController`` has method ``filtrate`` for easy filter data
|
296 | for response.
|
297 |
|
298 | ``filtrate`` works from ``filterMode`` (``'omit'`` by default).
|
299 | You'll can set 2 modes:
|
300 |
|
301 | * ``omit``
|
302 | * ``pick``
|
303 |
|
304 | their names speak for themselves.
|
305 |
|
306 | ```
|
307 | filter = ['password'];
|
308 | ```
|
309 | Omit mode:
|
310 | ```
|
311 | filterMode = 'omit';
|
312 | ```
|
313 | ```
|
314 | this.filtrate({
|
315 | login: 'user',
|
316 | password: 'secret'
|
317 | });
|
318 |
|
319 | // result: { login: 'user' }
|
320 | ```
|
321 | Pick mode:
|
322 | ```
|
323 | filterMode = 'pick';
|
324 | ```
|
325 | ```
|
326 | this.filtrate({
|
327 | login: 'user',
|
328 | password: 'secret'
|
329 | });
|
330 |
|
331 | // result: { password: 'secret' }
|
332 | ```
|
333 |
|
334 |
|
335 | ## Configure
|
336 | <bt>
|
337 |
|
338 | You'll can create ``config.json`` near your node js file
|
339 | (where are you calling "run" method) and set:
|
340 |
|
341 | ```
|
342 | {
|
343 | "port": your port
|
344 | }
|
345 | ```
|
346 |
|
347 | or you can set port in app:
|
348 |
|
349 | ```
|
350 | app.set('port', your port);
|
351 | app.run();
|
352 | ```
|
353 |
|
354 |
|
355 | ### [look source on github](https://github.com/sentiurin/light-ning)
|
356 |
|
357 |
|
\ | No newline at end of file |