Merge pull request #182 from AubHaddad/feat/prepareCommand

feat(@whook/whook): add prepareCommand function

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)

package.json

@@ -70,6 +70,11 @@
       "name": "Vincent Da Silva",
       "email": "[email protected]",
       "url": "https://dasilvavincent.github.io/PortFolio/"
+    },
+    {
+      "name": "Ayoub HAD-DAD",
+      "email": "[email protected]",
+      "url": "https://github.com/AubHaddad"
     }
   ],
   "engines": {

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

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<T extends Knifecycle>(
 
   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<T extends Knifecycle>(
+  innerPrepareEnvironment: ($?: T) => Promise<T> = prepareEnvironment,
+  $: T = new Knifecycle() as T,
+): Promise<T> {
+  // you can add here any logic bound to the commands only
+  return prepareBaseCommand(innerPrepareEnvironment, $);
+}

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,15 +257,15 @@ 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)
 
 
 
 #### 5.6.1. WhookInitializerMap
 
 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,15 +274,15 @@ 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)
 
 
 
 #### 5.7.1. WhookServiceMap
 
 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,37 +291,38 @@ 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)
 
 
 
 #### 5.7.2. Plugins/project paths
 
 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

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);

packages/whook/src/index.ts

@@ -411,3 +411,23 @@ export async function prepareEnvironment<T extends Knifecycle>(
 
   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<Knifecycle>
+ * A promise of the Knifecycle instance
+ */
+export async function prepareCommand<T extends Knifecycle>(
+  innerPrepareEnvironment: ($?: T) => Promise<T> = prepareEnvironment,
+  $: T = new Knifecycle() as T,
+): Promise<T> {
+  $ = await innerPrepareEnvironment($);
+  // you can add here any logic bound to the commands only
+  return $;
+}

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.

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

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.
 */

packages/whook/src/services/PORT.ts

@@ -6,7 +6,7 @@ const DEFAULT_ENV = {};
 
 export type PortFinderModule = { getPortPromise: () => Promise<number> };
 
-/* 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.
 */

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

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.