@lytical/app 1.0.8 → 1.0.10

package/README.md

@@ -200,34 +200,45 @@ import app, { app_evt } from './lib/app';
 // 1. create_server
 // 2. server_starting
 // 3. server_listening
-// 4. server_started
 
 app.once(app_evt.create_server, (cfg) => {
-  // modify (cfg) as needed, or remove this listener if not needed.
-  // for example, create a https server instead of http,
-  // and push async operations to fetch keys, to (cfg.wait_for).
-  // add middleware to (cfg.express), that applies to all routes, etc.
+  // set the event parameter (evt.server) property to provide the server instance of your choice.
+  //
+  // e.g.
+  //   evt.server = createHttpsServer(evt.express, my_https_options);
+  //
+  // a standard http server instance is created by default, if no server is provided.
+  //
+  // evt.root_route can be modified to change the root route where auto registered routes are mounted.
+  // default is '/api'.
+  //
+  // push async operations (Promise) that fetch encryption keys, ... into the event parameter (evt.wait_for.push(...)).
+  //
+  // add middleware into the pipeline (evt.express.use(...)), before auto registered routes are added.
+  //
+  // this is also the last chance to register dependencies in the ioc collection, before the container is created.
   console.log(`the root route is (${cfg.root_route})`);
 });
 
 app.once(app_evt.server_starting, (cfg) => {
-  // modify (cfg) as needed, or remove this listener if not needed.
-  // add middleware to this application after auto registered routes are added.
-  // for example error handling middleware, etc.
-  // push async operations to fetch settings from a database, to (cfg.wait_for).
-  // this is the last to register dependencies in the ioc collection before the server starts.
+  // use to modify the server listening configuration before it is started.
+  //
+  // all auto registered routes have been added at this point.
+  //
+  // you may add middleware to the app pipeline (evt.express.use(...)), after the auto registered routes.
+  // for example, to add error handling middleware, ...
+  //
+  // push async operations (Promise) that may fetch data or does some kind of i/o, ... into (evt.wait_for.push(...)).
+  //
+  // the ioc container is also ready at this point.
   console.log(`the hostname is (${cfg.hostname})`);
 });
 
 app.once(app_evt.server_listening, () => {
-  // remove this listener if not needed.
+  // emitted when the server is listening
+  //
   // use it to perform operations after the server starts listening.
-  // the ioc container is ready at this point.
-});
-
-app.once(app_evt.server_started, () => {
-  // remove this listener if not needed.
-  // use it to perform operations after the server has started.
+  // this is the last event from the app, when it's considered started.
 });
 
 app.start();

package/index.d.ts

@@ -4,30 +4,46 @@ import type { app_listening_cfg_t, app_server_cfg_t } from './types';
 /** events emitted by the app */
 export declare enum app_evt {
     /**
-     * use to create or modify the server before it is started
+     * set the event parameter (evt.server) property to provide the server instance of your choice.
      *
-     * for example, create a https server instead of http,
-     * and push async operations to fetch keys, to (cfg.wait_for).
-     * add middleware to (cfg.express), that applies to all routes, etc.
+     * e.g.
+     *   evt.server = createHttpsServer(evt.express, my_https_options);
+     *
+     * a standard http server instance is created by default, if no server is provided.
+     *
+     * evt.root_route can be modified to change the root route where auto registered routes are mounted.
+     * default is '/api'.
+     *
+     * push async operations (Promise) that fetch encryption keys, ... into the event parameter (evt.wait_for.push(...)).
+     *
+     * add middleware into the pipeline (evt.express.use(...)), before auto registered routes are added.
+     *
+     * this is also the last chance to register dependencies in the ioc collection, before the container is created.
      */
     create_server = "lyt-create-server",
     /**
-     * use to modify the server listening configuration before it is started
+     * use to modify the server listening configuration before it is started.
      *
-     * add middleware to this (cfg.express) after auto registered routes are added.
-     * for example error handling middleware, etc.
-     * push async operations to fetch settings from a database, to (cfg.wait_for).
-     * this is the last to register dependencies in the ioc collection before the server starts.
+     * all auto registered routes have been added at this point.
+     *
+     * you may add middleware to the app pipeline (evt.express.use(...)), after the auto registered routes.
+     * for example, to add error handling middleware, ...
+     *
+     * push async operations (Promise) that may fetch data or does some kind of i/o, ... into (evt.wait_for.push(...)).
+     *
+     * the ioc container is also ready at this point.
      */
     server_starting = "lyt-server-starting",
     /**
      * emitted when the server is listening
      *
      * use it to perform operations after the server starts listening.
-     * the ioc container is ready at this point.
+     * this is the last event from the app, when it's considered started.
      */
     server_listening = "lyt-server-listening",
     /**
+     * @deprecated use the (server_listening) event instead
+     *
      * emitted when the server has started
      *
      * use it to perform operations after the server has started.
@@ -38,10 +54,12 @@ export declare enum app_evt {
  * app class
  * @description
  * the main app class
+ *
+ * events are emitted in the following order:
+ *
  * @emits app_evt.create_server use to create or modify the server before it is started
  * @emits app_evt.server_starting use to modify the server listening configuration before it is started
  * @emits app_evt.server_listening emitted when the server is listening
- * @emits app_evt.server_started emitted when the server has started
  */
 export declare class app extends EventEmitter {
     once(event: app_evt.create_server, listener: (cfg: app_server_cfg_t) => void): this;
@@ -51,12 +69,11 @@ export declare class app extends EventEmitter {
     /**
      * start the app
      * @description
-     * starts the express app server
+     * starts the express app server (simular to run() in other frameworks)
      * app events occur in the following order:
      *   1. create_server
      *   2. server_starting
      *   3. server_listening
-     *   4. server_started
      */
     start(): Promise<void>;
 }

package/index.js

@@ -3,4 +3,4 @@
   (c) 2025 lytical, inc. all rights are reserved.
   lytical(r) is a registered trademark of lytical, inc.
   please refer to your license agreement on the use of this file.
-*/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)),yield collection_1.default.create_container(),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}`)}),this.emit(app_evt.server_started)})}}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:p,http_method:d}=u[e];if(_.length||d.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 d)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)}});p&&s.use(p),console.debug(`[@lytical/app] registered (${d}:${r}${n})\n               route handler: ${o.name}.${e}\n               dependencies: [${l}]\n               error handler: ${p?null!==(i=p.name)&&void 0!==i?i:"anonymous-error-handler":"default"}`),c.use(s);continue}const[f]=d;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: ${p?null!==(s=p.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: ${p?null!==(l=p.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;
+*/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

@@ -1,6 +1,6 @@
 {
   "name": "@lytical/app",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "a typescript api server library built for your express project, with dependency injection support and auto router registration",
   "main": "index.js",
   "private": false,
@@ -33,7 +33,7 @@
   },
   "license": "ISC",
   "peerDependencies": {
-    "@lytical/ioc": "^1.0.0",
+    "@lytical/ioc": "^1.0.5",
     "express": "^5.2.1"
   },
   "devDependencies": {