diff --git a/README.md b/README.md index e3ddcc7d..c69f1841 100644 --- a/README.md +++ b/README.md @@ -193,6 +193,7 @@ NODE_ENV=cli npm run lerna -- publish # Authors - [Nicolas Froidure](http://insertafter.com/en/index.html) - [Vincent Da Silva](https://dasilvavincent.github.io/PortFolio/) +- [Ayoub HAD-DAD](https://github.com/AubHaddad) # License [MIT](https://github.com/nfroidure/whook/blob/main/LICENSE) diff --git a/package.json b/package.json index 256b9290..073937ac 100644 --- a/package.json +++ b/package.json @@ -70,6 +70,11 @@ "name": "Vincent Da Silva", "email": "dasilva.vincent.pro2@gmail.com", "url": "https://dasilvavincent.github.io/PortFolio/" + }, + { + "name": "Ayoub HAD-DAD", + "email": "aub.haddad@gmail.com", + "url": "https://github.com/AubHaddad" } ], "engines": { diff --git a/packages/whook-example/ARCHITECTURE.md b/packages/whook-example/ARCHITECTURE.md index 515eddc4..4287c9a2 100644 --- a/packages/whook-example/ARCHITECTURE.md +++ b/packages/whook-example/ARCHITECTURE.md @@ -18,6 +18,7 @@ 3. [MAIN_FILE_URL](#1133-main_file_url) 3. [TRANSACTIONS](#1133-transactions) 4. [WHOOK_PLUGINS](#1134-whook_plugins) + 4. [prepareCommand](#114-preparecommand) 2. [The build file](#12-the-build-file) 1. [The `runBuild` function](#121-the-`runbuild`-function) 2. [The `prepareBuildEnvironment` function](#122-the-`preparebuildenvironment`-function) @@ -208,6 +209,16 @@ You can also avoid Whook defaults by leaving it empty. +#### 1.1.4. prepareCommand + +The `prepareCommand` function is intended to prepare the commands + environment. It relies on the main environment but will be + used only by the commands, not the server or build scripts. + +[See in context](./src/index.ts#L209-L214) + + + ### 1.2. The build file Per convention a Whook server build file must export diff --git a/packages/whook-example/src/index.ts b/packages/whook-example/src/index.ts index ff0ff56c..83ca28e1 100644 --- a/packages/whook-example/src/index.ts +++ b/packages/whook-example/src/index.ts @@ -5,6 +5,7 @@ import { runServer as runBaseServer, prepareServer as prepareBaseServer, prepareEnvironment as prepareBaseEnvironment, + prepareCommand as prepareBaseCommand, initAutoload, initAPIDefinitions, } from '@whook/whook'; @@ -205,3 +206,18 @@ export async function prepareEnvironment( return $; } + +/* Architecture Note #1.1.4: prepareCommand + +The `prepareCommand` function is intended to prepare the commands + environment. It relies on the main environment but will be + used only by the commands, not the server or build scripts. +*/ + +export async function prepareCommand( + innerPrepareEnvironment: ($?: T) => Promise = prepareEnvironment, + $: T = new Knifecycle() as T, +): Promise { + // you can add here any logic bound to the commands only + return prepareBaseCommand(innerPrepareEnvironment, $); +} diff --git a/packages/whook/ARCHITECTURE.md b/packages/whook/ARCHITECTURE.md index ad546ab6..99eed392 100644 --- a/packages/whook/ARCHITECTURE.md +++ b/packages/whook/ARCHITECTURE.md @@ -16,8 +16,8 @@ 3. [`WHOOK_PLUGINS` and `PROJECT_SRC`](#33-`whook_plugins`-and-`project_src`) 4. [Logging](#34-logging) 5. [Initializers](#35-initializers) -4. [Base URL](#4-base-url) -5. [`$autoload` service](#5-`$autoload`-service) +4. [Commands preparation](#4-commands-preparation) +5. [Base URL](#5-base-url) 1. [Configuration auto loading](#51-configuration-auto-loading) 2. [Wrappers auto loading support](#52-wrappers-auto-loading-support) 1. [Injecting handlers](#521-injecting-handlers) @@ -34,11 +34,12 @@ 1. [WhookServiceMap](#571-whookservicemap) 1. [Initializer path mapping](#571-initializer-path-mapping) 2. [Plugins/project paths](#572-plugins/project-paths) -6. [IP detection](#6-ip-detection) -7. [Port detection](#7-port-detection) -9. [Plugins resolution](#9-plugins-resolution) +6. [`$autoload` service](#6-`$autoload`-service) +7. [IP detection](#7-ip-detection) +8. [Plugins resolution](#8-plugins-resolution) +9. [Port detection](#9-port-detection) 10. [Commands](#10-commands) -10. [API definitions loader](#10-api-definitions-loader) +11. [API definitions loader](#11-api-definitions-loader) ## 1. Server run @@ -136,24 +137,23 @@ Whook's embed a few default initializers proxied from -## 4. Base URL +## 4. Commands preparation -The `BASE_URL` service is intended to provide a base URL where - the API can be found at. It can be overriden directly via - injecting it but it is useful to have a usable URL while - debugging production environnement. +Whook expose `prepareCommand` function to create commands configuration +before effectively running them -[See in context](./src/services/BASE_URL.ts#L5-L10) +[See in context](./src/index.ts#L415-L418) -## 5. `$autoload` service +## 5. Base URL -The default Whook autoloader provides a simple way to - load the constants, services and handlers of a Whook - project automatically from the installed whook plugins. +The `BASE_URL` service is intended to provide a base URL where + the API can be found at. It can be overriden directly via + injecting it but it is useful to have a usable URL while + debugging production environnement. -[See in context](./src/services/_autoload.ts#L60-L64) +[See in context](./src/services/BASE_URL.ts#L5-L10) @@ -175,7 +175,7 @@ Loading the configuration files is done according to the `APP_ENV` We inject the `HANDLERS_WRAPPERS` in the `WRAPPERS` service so that they can be dynamically applied. -[See in context](./src/services/_autoload.ts#L203-L206) +[See in context](./src/services/_autoload.ts#L202-L205) @@ -194,7 +194,7 @@ We cannot inject the `API` in the auto loader since it is dynamically loaded so doing this during the auto loader initialization. -[See in context](./src/services/_autoload.ts#L118-L122) +[See in context](./src/services/_autoload.ts#L117-L121) @@ -230,7 +230,7 @@ Here, we reuse the Open API handler to generate the First of all the autoloader looks for constants in the previously loaded `APP_CONFIG` configurations hash. -[See in context](./src/services/_autoload.ts#L164-L167) +[See in context](./src/services/_autoload.ts#L163-L166) @@ -248,7 +248,7 @@ In such a hard life, Whook's make it simple to Here, we build the handlers map needed by the router by injecting every handler required by the API. -[See in context](./src/services/_autoload.ts#L182-L185) +[See in context](./src/services/_autoload.ts#L181-L184) @@ -257,7 +257,7 @@ Here, we build the handlers map needed by the router by injecting every In order to be able to easily substitute a service per another one can specify a mapping between a service and its substitution. -[See in context](./src/services/_autoload.ts#L149-L152) +[See in context](./src/services/_autoload.ts#L148-L151) @@ -265,7 +265,7 @@ In order to be able to easily substitute a service per another Whook exports a `WhookInitializerMap` type to help you ensure yours are valid. -[See in context](./src/services/_autoload.ts#L38-L40) +[See in context](./src/services/_autoload.ts#L39-L41) @@ -274,7 +274,7 @@ Whook exports a `WhookInitializerMap` type to help you ensure yours are valid. Finally, we either load the handler/service/wrapper module if none of the previous strategies applied. -[See in context](./src/services/_autoload.ts#L216-L219) +[See in context](./src/services/_autoload.ts#L215-L218) @@ -282,7 +282,7 @@ Finally, we either load the handler/service/wrapper module Whook exports a `WhookServiceMap` type to help you ensure yours are valid. -[See in context](./src/services/_autoload.ts#L33-L35) +[See in context](./src/services/_autoload.ts#L34-L36) @@ -291,7 +291,7 @@ Whook exports a `WhookServiceMap` type to help you ensure yours are valid. In order to be able to load a service from a given path map one can directly specify a path to use for its resolution. -[See in context](./src/services/_autoload.ts#L222-L225) +[See in context](./src/services/_autoload.ts#L221-L224) @@ -299,29 +299,30 @@ In order to be able to load a service from a given path map Trying to load services from plugins/project paths. -[See in context](./src/services/_autoload.ts#L234-L236) +[See in context](./src/services/_autoload.ts#L235-L237) -## 6. IP detection +## 6. `$autoload` service -If no `HOST` configuration is specified in dependencies nor in ENV, - this service detects the machine host automagically. +The default Whook autoloader provides a simple way to + load the constants, services and handlers of a Whook + project automatically from the installed whook plugins. -[See in context](./src/services/HOST.ts#L7-L10) +[See in context](./src/services/_autoload.ts#L61-L65) -## 7. Port detection +## 7. IP detection -If no `PORT` configuration is specified in dependencies nor in ENV, -this service detects a free port automagically. +If no `HOST` configuration is specified in dependencies nor in ENV, + this service detects the machine host automagically. -[See in context](./src/services/PORT.ts#L9-L12) +[See in context](./src/services/HOST.ts#L7-L10) -## 9. Plugins resolution +## 8. Plugins resolution Whook auto loader can look for initializers in a list of plugins defined in the `WHOOK_PLUGINS` constant. This @@ -333,6 +334,15 @@ Whook auto loader can look for initializers in a list of +## 9. Port detection + +If no `PORT` configuration is specified in dependencies nor in ENV, +this service detects a free port automagically. + +[See in context](./src/services/PORT.ts#L9-L12) + + + ## 10. Commands Whook's commands are CLI tools that you may need to create and @@ -361,7 +371,7 @@ npm run cli -- tsx ../whook/bin/whook.js ls -## 10. API definitions loader +## 11. API definitions loader The `API_DEFINITIONS` service provide a convenient way to gather your various API definitions from the handlers you diff --git a/packages/whook/bin/whook.js b/packages/whook/bin/whook.js index af04073d..882b507e 100755 --- a/packages/whook/bin/whook.js +++ b/packages/whook/bin/whook.js @@ -3,8 +3,8 @@ import path from 'path'; import runCLI from '../dist/cli.js'; -const { prepareEnvironment } = await import( +const { prepareCommand } = await import( path.join(process.cwd(), 'dist', 'index.js') ); -await runCLI(prepareEnvironment); +await runCLI(prepareCommand); diff --git a/packages/whook/src/index.ts b/packages/whook/src/index.ts index 11866643..350a0cc6 100644 --- a/packages/whook/src/index.ts +++ b/packages/whook/src/index.ts @@ -411,3 +411,23 @@ export async function prepareEnvironment( return $; } + +/* Architecture Note #4: Commands preparation +Whook expose `prepareCommand` function to create commands configuration +before effectively running them + */ +/** + * Prepare the Whook commands environment + * @param {Knifecycle} $ + * The Knifecycle instance to set the various services + * @returns Promise + * A promise of the Knifecycle instance + */ +export async function prepareCommand( + innerPrepareEnvironment: ($?: T) => Promise = prepareEnvironment, + $: T = new Knifecycle() as T, +): Promise { + $ = await innerPrepareEnvironment($); + // you can add here any logic bound to the commands only + return $; +} diff --git a/packages/whook/src/services/API_DEFINITIONS.ts b/packages/whook/src/services/API_DEFINITIONS.ts index e6601bd9..9b89e49e 100644 --- a/packages/whook/src/services/API_DEFINITIONS.ts +++ b/packages/whook/src/services/API_DEFINITIONS.ts @@ -24,7 +24,7 @@ export const DEFAULT_IGNORED_FILES_SUFFIXES = [ '.mjs.map', ]; -/* Architecture Note #10: API definitions loader +/* Architecture Note #11: API definitions loader The `API_DEFINITIONS` service provide a convenient way to gather your various API definitions from the handlers you created in the `src/handlers` folder. diff --git a/packages/whook/src/services/BASE_URL.ts b/packages/whook/src/services/BASE_URL.ts index c68f44c6..60a20b25 100644 --- a/packages/whook/src/services/BASE_URL.ts +++ b/packages/whook/src/services/BASE_URL.ts @@ -2,7 +2,7 @@ import { autoService, name } from 'knifecycle'; import { noop } from '../libs/utils.js'; import type { LogService } from 'common-services'; -/* Architecture Note #4: Base URL +/* Architecture Note #5: Base URL The `BASE_URL` service is intended to provide a base URL where the API can be found at. It can be overriden directly via injecting it but it is useful to have a usable URL while diff --git a/packages/whook/src/services/HOST.ts b/packages/whook/src/services/HOST.ts index 7fd20541..8a6d8a29 100644 --- a/packages/whook/src/services/HOST.ts +++ b/packages/whook/src/services/HOST.ts @@ -4,7 +4,7 @@ import type { ImporterService, LogService } from 'common-services'; const DEFAULT_ENV = {}; -/* Architecture Note #6: IP detection +/* Architecture Note #7: IP detection If no `HOST` configuration is specified in dependencies nor in ENV, this service detects the machine host automagically. */ diff --git a/packages/whook/src/services/PORT.ts b/packages/whook/src/services/PORT.ts index 9b891748..a77cbb66 100644 --- a/packages/whook/src/services/PORT.ts +++ b/packages/whook/src/services/PORT.ts @@ -6,7 +6,7 @@ const DEFAULT_ENV = {}; export type PortFinderModule = { getPortPromise: () => Promise }; -/* Architecture Note #7: Port detection +/* Architecture Note #9: Port detection If no `PORT` configuration is specified in dependencies nor in ENV, this service detects a free port automagically. */ diff --git a/packages/whook/src/services/WHOOK_RESOLVED_PLUGINS.ts b/packages/whook/src/services/WHOOK_RESOLVED_PLUGINS.ts index 0f8ccd46..d1ad066c 100644 --- a/packages/whook/src/services/WHOOK_RESOLVED_PLUGINS.ts +++ b/packages/whook/src/services/WHOOK_RESOLVED_PLUGINS.ts @@ -4,7 +4,7 @@ import { name, singleton, autoService } from 'knifecycle'; import { YError, printStackTrace } from 'yerror'; import type { ResolveService, LogService } from 'common-services'; -/* Architecture Note #9: Plugins resolution +/* Architecture Note #8: Plugins resolution Whook auto loader can look for initializers in a list of plugins defined in the `WHOOK_PLUGINS` constant. This diff --git a/packages/whook/src/services/_autoload.ts b/packages/whook/src/services/_autoload.ts index f3456959..15ac0f87 100644 --- a/packages/whook/src/services/_autoload.ts +++ b/packages/whook/src/services/_autoload.ts @@ -58,7 +58,7 @@ export type WhookAutoloadDependencies = WhookWrappersConfig & { log?: LogService; }; -/* Architecture Note #5: `$autoload` service +/* Architecture Note #6: `$autoload` service The default Whook autoloader provides a simple way to load the constants, services and handlers of a Whook project automatically from the installed whook plugins.