@lytical/app 1.0.9 → 1.0.11
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 +44 -25
- package/index.d.ts +30 -13
- package/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@ a typescript api server library built for your express project, with dependency
|
|
|
13
13
|
install packages:
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
|
-
npm install @lytical/app
|
|
16
|
+
npm install @lytical/app express
|
|
17
17
|
```
|
|
18
18
|
|
|
19
19
|
after installing, configure your `tsconfig.json` file to enable decorators.
|
|
@@ -72,7 +72,8 @@ for the above project structure:
|
|
|
72
72
|
}
|
|
73
73
|
```
|
|
74
74
|
|
|
75
|
-
a simple project template / example can be found in github
|
|
75
|
+
a simple project template / example can be found in github\
|
|
76
|
+
(https://github.com/lytical/ts-app-example)
|
|
76
77
|
|
|
77
78
|
## usage
|
|
78
79
|
|
|
@@ -145,7 +146,8 @@ import { example_middleware_class } from '../middleware/example-mw';
|
|
|
145
146
|
|
|
146
147
|
/**
|
|
147
148
|
* Example route class
|
|
148
|
-
* Use for router class(es)
|
|
149
|
+
* Use for router class(es) to auto app.use() registration for
|
|
150
|
+
* routes; dependent middleware; and dependency injection
|
|
149
151
|
*/
|
|
150
152
|
@app_route({ route: '/example' })
|
|
151
153
|
export class example_route_class {
|
|
@@ -173,7 +175,7 @@ export class example_route_class {
|
|
|
173
175
|
],
|
|
174
176
|
// you may indicate an error handler middleware at the route level.
|
|
175
177
|
// the default error handler will be used if not indicated here.
|
|
176
|
-
error_handler: example_error_handler
|
|
178
|
+
error_handler: example_error_handler,
|
|
177
179
|
})
|
|
178
180
|
post_handler(rqs: Request, rsp: Response, nxt: NextFunction) {
|
|
179
181
|
rsp.json({ body: rqs.body, locals: rsp.locals }).end();
|
|
@@ -200,43 +202,60 @@ import app, { app_evt } from './lib/app';
|
|
|
200
202
|
// 1. create_server
|
|
201
203
|
// 2. server_starting
|
|
202
204
|
// 3. server_listening
|
|
203
|
-
// 4. server_started
|
|
204
205
|
|
|
205
206
|
app.once(app_evt.create_server, (cfg) => {
|
|
206
|
-
//
|
|
207
|
-
//
|
|
208
|
-
|
|
209
|
-
//
|
|
207
|
+
// set the event parameter (evt.server) property to
|
|
208
|
+
// provide the server instance of your choice.
|
|
209
|
+
|
|
210
|
+
// e.g.
|
|
211
|
+
// evt.server = createHttpsServer(evt.express, my_https_options);
|
|
212
|
+
|
|
213
|
+
// a standard http server instance is created by default,
|
|
214
|
+
// if no server is provided.
|
|
215
|
+
|
|
216
|
+
// evt.root_route can be modified to change the root route
|
|
217
|
+
// where auto registered routes are mounted.
|
|
218
|
+
|
|
219
|
+
// default is '/api'.
|
|
220
|
+
|
|
221
|
+
// push async operations (Promise) that fetch encryption keys, ...
|
|
222
|
+
// into the event parameter (evt.wait_for.push(...)).
|
|
223
|
+
|
|
224
|
+
// add middleware into the pipeline (evt.express.use(...)),
|
|
225
|
+
// before auto registered routes are added.
|
|
226
|
+
|
|
227
|
+
// this is also the last chance to register dependencies
|
|
228
|
+
// in the ioc collection, before the container is created.
|
|
210
229
|
console.log(`the root route is (${cfg.root_route})`);
|
|
211
230
|
});
|
|
212
231
|
|
|
213
232
|
app.once(app_evt.server_starting, (cfg) => {
|
|
214
|
-
//
|
|
215
|
-
|
|
216
|
-
//
|
|
217
|
-
|
|
218
|
-
//
|
|
233
|
+
// use to modify the server listening configuration before it is started.
|
|
234
|
+
|
|
235
|
+
// all auto registered routes have been added at this point.
|
|
236
|
+
|
|
237
|
+
// you may add middleware to the app pipeline (evt.express.use(...)),
|
|
238
|
+
// after the auto registered routes.
|
|
239
|
+
|
|
240
|
+
// for example, to add error handling middleware, ...
|
|
241
|
+
|
|
242
|
+
// push async operations (Promise) that may fetch data or
|
|
243
|
+
// does some kind of i/o, ... into (evt.wait_for.push(...)).
|
|
244
|
+
|
|
245
|
+
// the ioc container is also ready at this point.
|
|
219
246
|
console.log(`the hostname is (${cfg.hostname})`);
|
|
220
247
|
});
|
|
221
248
|
|
|
222
249
|
app.once(app_evt.server_listening, () => {
|
|
223
|
-
//
|
|
250
|
+
// emitted when the server is listening
|
|
251
|
+
|
|
224
252
|
// use it to perform operations after the server starts listening.
|
|
225
|
-
// the
|
|
226
|
-
});
|
|
227
|
-
|
|
228
|
-
app.once(app_evt.server_started, () => {
|
|
229
|
-
// remove this listener if not needed.
|
|
230
|
-
// use it to perform operations after the server has started.
|
|
253
|
+
// this is the last event from the app, when it's considered started.
|
|
231
254
|
});
|
|
232
255
|
|
|
233
256
|
app.start();
|
|
234
257
|
```
|
|
235
258
|
|
|
236
|
-
## documentation
|
|
237
|
-
|
|
238
|
-
todo: working on this right now...
|
|
239
|
-
|
|
240
259
|
stay tuned! i have more packages to come.`
|
|
241
260
|
|
|
242
261
|
_lytical(r) is a registered trademark of lytical, inc. all rights are reserved._
|
package/index.d.ts
CHANGED
|
@@ -4,30 +4,46 @@ import type { app_listening_cfg_t, app_server_cfg_t } from './types';
|
|
|
4
4
|
/** events emitted by the app */
|
|
5
5
|
export declare enum app_evt {
|
|
6
6
|
/**
|
|
7
|
-
*
|
|
7
|
+
* set the event parameter (evt.server) property to provide the server instance of your choice.
|
|
8
8
|
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
9
|
+
* e.g.
|
|
10
|
+
* evt.server = createHttpsServer(evt.express, my_https_options);
|
|
11
|
+
*
|
|
12
|
+
* a standard http server instance is created by default, if no server is provided.
|
|
13
|
+
*
|
|
14
|
+
* evt.root_route can be modified to change the root route where auto registered routes are mounted.
|
|
15
|
+
* default is '/api'.
|
|
16
|
+
*
|
|
17
|
+
* push async operations (Promise) that fetch encryption keys, ... into the event parameter (evt.wait_for.push(...)).
|
|
18
|
+
*
|
|
19
|
+
* add middleware into the pipeline (evt.express.use(...)), before auto registered routes are added.
|
|
20
|
+
*
|
|
21
|
+
* this is also the last chance to register dependencies in the ioc collection, before the container is created.
|
|
12
22
|
*/
|
|
13
23
|
create_server = "lyt-create-server",
|
|
14
24
|
/**
|
|
15
|
-
* use to modify the server listening configuration before it is started
|
|
25
|
+
* use to modify the server listening configuration before it is started.
|
|
16
26
|
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
27
|
+
* all auto registered routes have been added at this point.
|
|
28
|
+
*
|
|
29
|
+
* you may add middleware to the app pipeline (evt.express.use(...)), after the auto registered routes.
|
|
30
|
+
* for example, to add error handling middleware, ...
|
|
31
|
+
*
|
|
32
|
+
* push async operations (Promise) that may fetch data or does some kind of i/o, ... into (evt.wait_for.push(...)).
|
|
33
|
+
*
|
|
34
|
+
* the ioc container is also ready at this point.
|
|
21
35
|
*/
|
|
22
36
|
server_starting = "lyt-server-starting",
|
|
23
37
|
/**
|
|
24
38
|
* emitted when the server is listening
|
|
25
39
|
*
|
|
26
40
|
* use it to perform operations after the server starts listening.
|
|
27
|
-
* the
|
|
41
|
+
* this is the last event from the app, when it's considered started.
|
|
28
42
|
*/
|
|
29
43
|
server_listening = "lyt-server-listening",
|
|
30
44
|
/**
|
|
45
|
+
* @deprecated use the (server_listening) event instead
|
|
46
|
+
*
|
|
31
47
|
* emitted when the server has started
|
|
32
48
|
*
|
|
33
49
|
* use it to perform operations after the server has started.
|
|
@@ -38,10 +54,12 @@ export declare enum app_evt {
|
|
|
38
54
|
* app class
|
|
39
55
|
* @description
|
|
40
56
|
* the main app class
|
|
57
|
+
*
|
|
58
|
+
* events are emitted in the following order:
|
|
59
|
+
*
|
|
41
60
|
* @emits app_evt.create_server use to create or modify the server before it is started
|
|
42
61
|
* @emits app_evt.server_starting use to modify the server listening configuration before it is started
|
|
43
62
|
* @emits app_evt.server_listening emitted when the server is listening
|
|
44
|
-
* @emits app_evt.server_started emitted when the server has started
|
|
45
63
|
*/
|
|
46
64
|
export declare class app extends EventEmitter {
|
|
47
65
|
once(event: app_evt.create_server, listener: (cfg: app_server_cfg_t) => void): this;
|
|
@@ -51,12 +69,11 @@ export declare class app extends EventEmitter {
|
|
|
51
69
|
/**
|
|
52
70
|
* start the app
|
|
53
71
|
* @description
|
|
54
|
-
* starts the express app server
|
|
72
|
+
* starts the express app server (simular to run() in other frameworks)
|
|
55
73
|
* app events occur in the following order:
|
|
56
74
|
* 1. create_server
|
|
57
75
|
* 2. server_starting
|
|
58
76
|
* 3. server_listening
|
|
59
|
-
* 4. server_started
|
|
60
77
|
*/
|
|
61
78
|
start(): Promise<void>;
|
|
62
79
|
}
|
package/index.js
CHANGED
|
@@ -3,4 +3,4 @@
|
|
|
3
3
|
(c) 2025 lytical, inc. all rights are reserved.
|
|
4
4
|
lytical(r) is a registered trademark of lytical, inc.
|
|
5
5
|
please refer to your license agreement on the use of this file.
|
|
6
|
-
*/var __createBinding=this&&this.__createBinding||(Object.create?function(e,t,r,o){void 0===o&&(o=r);var n=Object.getOwnPropertyDescriptor(t,r);n&&!("get"in n?!t.__esModule:n.writable||n.configurable)||(n={enumerable:!0,get:function(){return t[r]}}),Object.defineProperty(e,o,n)}:function(e,t,r,o){void 0===o&&(o=r),e[o]=t[r]}),__setModuleDefault=this&&this.__setModuleDefault||(Object.create?function(e,t){Object.defineProperty(e,"default",{enumerable:!0,value:t})}:function(e,t){e.default=t}),__importStar=this&&this.__importStar||function(){var ownKeys=function(e){return ownKeys=Object.getOwnPropertyNames||function(e){var t=[];for(var r in e)Object.prototype.hasOwnProperty.call(e,r)&&(t[t.length]=r);return t},ownKeys(e)};return function(e){if(e&&e.__esModule)return e;var t={};if(null!=e)for(var r=ownKeys(e),o=0;o<r.length;o++)"default"!==r[o]&&__createBinding(t,e,r[o]);return __setModuleDefault(t,e),t}}(),__awaiter=this&&this.__awaiter||function(e,t,r,o){return new(r||(r=Promise))(function(n,a){function fulfilled(e){try{step(o.next(e))}catch(e){a(e)}}function rejected(e){try{step(o.throw(e))}catch(e){a(e)}}function step(e){var t;e.done?n(e.value):(t=e.value,t instanceof r?t:new r(function(e){e(t)})).then(fulfilled,rejected)}step((o=o.apply(e,t||[])).next())})},__asyncValues=this&&this.__asyncValues||function(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t,r=e[Symbol.asyncIterator];return r?r.call(e):(e="function"==typeof __values?__values(e):e[Symbol.iterator](),t={},verb("next"),verb("throw"),verb("return"),t[Symbol.asyncIterator]=function(){return this},t);function verb(r){t[r]=e[r]&&function(t){return new Promise(function(o,n){(function(e,t,r,o){Promise.resolve(o).then(function(t){e({value:t,done:r})},t)})(o,n,(t=e[r](t)).done,t.value)})}}},__importDefault=this&&this.__importDefault||function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0}),exports.app=exports.app_evt=void 0,exports.app_middleware_dependency=app_middleware_dependency,exports.app_route=app_route,exports.app_route_handler=app_route_handler;const node_http_1=require("node:http"),node_stream_1=require("node:stream"),promises_1=require("node:fs/promises"),node_path_1=require("node:path"),express_1=__importDefault(require("express")),find_root_1=__importDefault(require("find-root")),ioc_1=require("@lytical/ioc"),collection_1=__importDefault(require("@lytical/ioc/collection"));var app_evt;!function(e){e.create_server="lyt-create-server",e.server_starting="lyt-server-starting",e.server_listening="lyt-server-listening",e.server_started="lyt-server-started"}(app_evt||(exports.app_evt=app_evt={}));const _app=(0,express_1.default)(),_root_route=express_1.default.Router({mergeParams:!0});class app extends node_stream_1.EventEmitter{once(e,t){return super.once(e,t)}start(){return __awaiter(this,void 0,void 0,function*(){var e,t;const r={express:_app,root_route:"/api",wait_for:[]};r.express.use((e,t,r)=>{t.set("X-Powered-By","powered by lytical(r) enterprise solutions, and express"),t.set("X-Lyt-Version","1.0.0"),r()}),console.log("[@lytical/app] creating http server..."),this.emit(app_evt.create_server,r),r.wait_for.length&&(yield Promise.all(r.wait_for)),_app.use(null!==(e=r.root_route)&&void 0!==e?e:"/api",_root_route);const o=null!==(t=r.server)&&void 0!==t?t:(0,node_http_1.createServer)(r.express);yield _register_routes();const n={express:r.express,hostname:process.env.HOSTNAME||"localhost",port:process.env.PORT?parseInt(process.env.PORT,10):3e3,server:o,wait_for:[]};this.emit(app_evt.server_starting,n),n.wait_for.length&&(yield Promise.all(n.wait_for)),
|
|
6
|
+
*/var __createBinding=this&&this.__createBinding||(Object.create?function(e,t,r,o){void 0===o&&(o=r);var n=Object.getOwnPropertyDescriptor(t,r);n&&!("get"in n?!t.__esModule:n.writable||n.configurable)||(n={enumerable:!0,get:function(){return t[r]}}),Object.defineProperty(e,o,n)}:function(e,t,r,o){void 0===o&&(o=r),e[o]=t[r]}),__setModuleDefault=this&&this.__setModuleDefault||(Object.create?function(e,t){Object.defineProperty(e,"default",{enumerable:!0,value:t})}:function(e,t){e.default=t}),__importStar=this&&this.__importStar||function(){var ownKeys=function(e){return ownKeys=Object.getOwnPropertyNames||function(e){var t=[];for(var r in e)Object.prototype.hasOwnProperty.call(e,r)&&(t[t.length]=r);return t},ownKeys(e)};return function(e){if(e&&e.__esModule)return e;var t={};if(null!=e)for(var r=ownKeys(e),o=0;o<r.length;o++)"default"!==r[o]&&__createBinding(t,e,r[o]);return __setModuleDefault(t,e),t}}(),__awaiter=this&&this.__awaiter||function(e,t,r,o){return new(r||(r=Promise))(function(n,a){function fulfilled(e){try{step(o.next(e))}catch(e){a(e)}}function rejected(e){try{step(o.throw(e))}catch(e){a(e)}}function step(e){var t;e.done?n(e.value):(t=e.value,t instanceof r?t:new r(function(e){e(t)})).then(fulfilled,rejected)}step((o=o.apply(e,t||[])).next())})},__asyncValues=this&&this.__asyncValues||function(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t,r=e[Symbol.asyncIterator];return r?r.call(e):(e="function"==typeof __values?__values(e):e[Symbol.iterator](),t={},verb("next"),verb("throw"),verb("return"),t[Symbol.asyncIterator]=function(){return this},t);function verb(r){t[r]=e[r]&&function(t){return new Promise(function(o,n){(function(e,t,r,o){Promise.resolve(o).then(function(t){e({value:t,done:r})},t)})(o,n,(t=e[r](t)).done,t.value)})}}},__importDefault=this&&this.__importDefault||function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0}),exports.app=exports.app_evt=void 0,exports.app_middleware_dependency=app_middleware_dependency,exports.app_route=app_route,exports.app_route_handler=app_route_handler;const node_http_1=require("node:http"),node_stream_1=require("node:stream"),promises_1=require("node:fs/promises"),node_path_1=require("node:path"),express_1=__importDefault(require("express")),find_root_1=__importDefault(require("find-root")),ioc_1=require("@lytical/ioc"),collection_1=__importDefault(require("@lytical/ioc/collection"));var app_evt;!function(e){e.create_server="lyt-create-server",e.server_starting="lyt-server-starting",e.server_listening="lyt-server-listening",e.server_started="lyt-server-started"}(app_evt||(exports.app_evt=app_evt={}));const _app=(0,express_1.default)(),_root_route=express_1.default.Router({mergeParams:!0});class app extends node_stream_1.EventEmitter{once(e,t){return super.once(e,t)}start(){return __awaiter(this,void 0,void 0,function*(){var e,t;const r={express:_app,root_route:"/api",wait_for:[]};r.express.use((e,t,r)=>{t.set("X-Powered-By","powered by lytical(r) enterprise solutions, and express"),t.set("X-Lyt-Version","1.0.0"),r()}),console.log("[@lytical/app] creating http server..."),this.emit(app_evt.create_server,r),r.wait_for.length&&(yield Promise.all(r.wait_for)),_app.use(null!==(e=r.root_route)&&void 0!==e?e:"/api",_root_route);const o=null!==(t=r.server)&&void 0!==t?t:(0,node_http_1.createServer)(r.express);yield _register_routes(),yield collection_1.default.create_container();const n={express:r.express,hostname:process.env.HOSTNAME||"localhost",port:process.env.PORT?parseInt(process.env.PORT,10):3e3,server:o,wait_for:[]};this.emit(app_evt.server_starting,n),n.wait_for.length&&(yield Promise.all(n.wait_for)),o.listen(n.port,n.hostname,n.backlog,()=>{this.emit(app_evt.server_listening),console.log(`[@lytical/app] server started on port ${n.port}; hostname ${n.hostname}`)})})}}function _register_routes(){return __awaiter(this,void 0,void 0,function*(){var e,t,r,o,n;const a=process.cwd(),{main:i}=null!==(n=yield Promise.resolve(`${(0,node_path_1.join)((0,find_root_1.default)(a),"package.json")}`).then(e=>__importStar(require(e))))&&void 0!==n?n:{};if(i){const n=yield(0,promises_1.glob)(i);try{for(var s,l=!0,c=__asyncValues(n);!(e=(s=yield c.next()).done);l=!0){o=s.value,l=!1;const e=o;console.log(`[@lytical/app] registering routes in module (${e})...`),yield Promise.resolve(`${(0,node_path_1.join)(a,e)}`).then(e=>__importStar(require(e)))}}catch(e){t={error:e}}finally{try{l||e||!(r=c.return)||(yield r.call(c))}finally{if(t)throw t.error}}}})}exports.app=app;const route_handler_method=Symbol("lyt-app-api-route-handler-method");function app_middleware_dependency(e,...t){return{middleware:e,arg:t}}function app_route({route:e,arg:t}){const r=e;return o=>{var n,a,i,s,l;const c=express_1.default.Router({mergeParams:!0}),u=null!==(n=o.prototype[route_handler_method])&&void 0!==n?n:{};for(const e of Object.keys(u)){const{route:n,dependency:_,error_handler:d,http_method:p}=u[e];if(_.length||p.length>1){const s=express_1.default.Router({mergeParams:!0}),l=[];for(let e of _){if("function"==typeof e){s.use(e),l.push(e.name||"anonymous-middleware");continue}const{middleware:t,arg:r}=e;s.use((e,o,n)=>{try{return(0,ioc_1.ioc_create_instance)(t,...null!=r?r:[]).default(e,o,n)}catch(e){n(e)}}),l.push(null!==(a=t.name)&&void 0!==a?a:"anonymous-middleware")}for(const r of p)s[r.toLowerCase()]?s[r.toLowerCase()](n,(r,n,a)=>{try{const i=(0,ioc_1.ioc_create_instance)(o,...null!=t?t:[]);return(0,ioc_1.ioc_invoke_method)(i[e],i,r,n,a)}catch(e){a(e)}}):s.use(n,(n,a,i)=>{if(r.toUpperCase()!==n.method)return i();try{const r=(0,ioc_1.ioc_create_instance)(o,...null!=t?t:[]);return(0,ioc_1.ioc_invoke_method)(r[e],r,n,a,i)}catch(e){i(e)}});d&&s.use(d),console.debug(`[@lytical/app] registered (${p}:${r}${n})\n route handler: ${o.name}.${e}\n dependencies: [${l}]\n error handler: ${d?null!==(i=d.name)&&void 0!==i?i:"anonymous-error-handler":"default"}`),c.use(s);continue}const[f]=p;f?(c[f.toLowerCase()]?c[f.toLowerCase()](n,(r,n,a)=>{try{const i=(0,ioc_1.ioc_create_instance)(o,...null!=t?t:[]);return(0,ioc_1.ioc_invoke_method)(i[e],i,r,n,a)}catch(e){a(e)}}):c.use(n,(r,n,a)=>{if(f.toUpperCase()!==r.method)return a();try{const i=(0,ioc_1.ioc_create_instance)(o,...null!=t?t:[]);return(0,ioc_1.ioc_invoke_method)(i[e],i,r,n,a)}catch(e){a(e)}}),console.debug(`[@lytical/app] registered (${f}:${r}${n})\n route handler: ${o.name}.${e} \n error handler: ${d?null!==(s=d.name)&&void 0!==s?s:"anonymous-error-handler":"default"}`)):(c.use(n,(r,n,a)=>{try{const i=(0,ioc_1.ioc_create_instance)(o,...null!=t?t:[]);return(0,ioc_1.ioc_invoke_method)(i[e],i,r,n,a)}catch(e){a(e)}}),console.debug(`[@lytical/app] registered (ALL-METHODS:${r}${n})\n route handler: ${o.name}.${e}\n error handler: ${d?null!==(l=d.name)&&void 0!==l?l:"anonymous-error-handler":"default"}`))}return _root_route.use(e,c),o}}function app_route_handler(e){return(t,r,o)=>{var n;switch(e.dependency?Array.isArray(e.dependency)||(e.dependency=[e.dependency]):e.dependency=[],typeof e.http_method){case"undefined":e.http_method=[];break;case"string":e.http_method=[e.http_method]}const a=null!==(n=t[route_handler_method])&&void 0!==n?n:{};return a[r]=e,t[route_handler_method]=a,o}}exports.default=new app;
|
package/package.json
CHANGED