jimpex 7.0.1 → 8.0.0

package/src/types/events.ts

@@ -0,0 +1,303 @@
+import type { Router, ExpressMiddlewareLike } from './express';
+import type { Controller, Middleware } from '../utils';
+import type { Jimpex } from '../app/jimpex';
+/**
+ * The base payload the events emitted by the application send.
+ *
+ * @template T  Extra properties beside the reference to the application.
+ * @group Services/Events
+ */
+export type EventPayload<T = Record<string, unknown>> = {
+  /**
+   * A reference to the application.
+   */
+  app: Jimpex;
+} & T;
+/**
+ * A dictionary with the events emitted by the application and their payloads.
+ *
+ * @group Services/Events
+ */
+export interface JimpexEvents {
+  /**
+   * Called right before creating the server and calling `listen` on it.
+   */
+  beforeStart: EventPayload;
+  /**
+   * Called once the server confirmed that is listening.
+   */
+  start: EventPayload;
+  /**
+   * Called after the controllers and middlewares have been mounted.
+   */
+  afterStart: EventPayload;
+  /**
+   * Called after the `onStart` callback has been called.
+   */
+  afterStartCallback: EventPayload;
+  /**
+   * Called before closing the server instance.
+   */
+  beforeStop: EventPayload;
+  /**
+   * Called after the server instance has been closed.
+   */
+  afterStop: EventPayload;
+  /**
+   * Called every time a new route is mounted in the application.
+   */
+  routeAdded: EventPayload<{ route: string }>;
+}
+/**
+ * The events emitted by the application.
+ *
+ * @group Services/Events
+ */
+export type JimpexEventName = keyof JimpexEvents;
+/**
+ * The type of the payload sent by a specific event.
+ *
+ * @template EventName  The literal type of the event, to obtain the type of the
+ *                      payload.
+ * @group Services/Events
+ */
+export type JimpexEventPayload<EventName extends JimpexEventName> =
+  JimpexEvents[EventName];
+/**
+ * A dictionary of the reducer events and their targets.
+ *
+ * @group Services/Events
+ */
+export interface JimpexReducerEventTargets {
+  /**
+   * It gets called before mounting a router/middleware for a specific route.
+   */
+  controllerWillBeMounted: Router | ExpressMiddlewareLike;
+  /**
+   * It gets called before using a middleware without route.
+   */
+  middlewareWillBeUsed: ExpressMiddlewareLike;
+}
+/**
+ * A dictionary of the payloads the reducer events the application uses.
+ *
+ * @group Services/Events
+ */
+export interface JimpexReducerEventPayloads {
+  /**
+   * It gets called before mounting a router/middleware for a specific route.
+   */
+  controllerWillBeMounted: EventPayload<{
+    /**
+     * The route in which the controller will be mounted.
+     */
+    route: string;
+    /**
+     * A reference for the controller/middleware before being "connected".
+     */
+    controller: Controller | Middleware;
+  }>;
+  /**
+   * It gets called before using a middleware without route.
+   */
+  middlewareWillBeUsed: EventPayload;
+}
+/**
+ * The reducer events used by the application.
+ *
+ * @group Services/Events
+ */
+export type JimpexReducerEventName = keyof JimpexReducerEventTargets;
+/**
+ * The type of the target of a specific reducer event.
+ *
+ * @template EventName  The literal type of the event, to obtain the type of the
+ *                      target.
+ * @group Services/Events
+ */
+export type JimpexReducerEventTarget<EventName extends JimpexReducerEventName> =
+  JimpexReducerEventTargets[EventName];
+/**
+ * The type of the payload of a specific reducer event.
+ *
+ * @template EventName  The literal type of the event, to obtain the type of the
+ *                      payload.
+ * @group Services/Events
+ */
+export type JimpexReducerEventPayload<EventName extends JimpexReducerEventName> =
+  JimpexReducerEventPayloads[EventName];
+/**
+ * The name of the events o reducer events emitted/used by the application.
+ * This generic type exists because the listener for both types are added using the same
+ * method.
+ *
+ * @group Services/Events
+ */
+export type JimpexEventNameLike = JimpexEventName | JimpexReducerEventName;
+/**
+ * The definition of a listener for an event or a reducer event.
+ *
+ * @template EventName  The literal type of the event, to validate whether the
+ *                      parameters should be for a reducer event or an event.
+ * @group Services/Events
+ */
+export type JimpexEventListener<EventName extends JimpexEventNameLike> =
+  EventName extends JimpexEventName
+    ? (payload: JimpexEventPayload<EventName>) => void
+    : EventName extends JimpexReducerEventName
+    ? (
+        target: JimpexReducerEventTarget<EventName>,
+        payload: JimpexReducerEventPayload<EventName>,
+      ) => JimpexReducerEventTarget<EventName>
+    : never;
+/**
+ * The `events` service Jimpex uses.
+ * This is an alternative declaration of the `EventsHub` class that uses the interfaces
+ * and types from this project.
+ *
+ * @group Services
+ * @group Services/Events
+ */
+export type Events = {
+  /**
+   * Adds a new event listener.
+   *
+   * @param event     The name of the event.
+   * @param listener  The listener function.
+   * @returns An unsubscribe function to remove the listener.
+   * @template EventName  The literal type of the event, to generate the type of the
+   *                      listener.
+   * @example
+   *
+   *   const unsubscribe = events.on('afterStart', ({ app }) => {
+   *     app.getLogger().info('Hello world!');
+   *     unsubscribe();
+   *   });
+   *
+   */
+  on: <EventName extends JimpexEventNameLike>(
+    eventName: EventName,
+    listener: JimpexEventListener<EventName>,
+  ) => () => boolean;
+  /**
+   * Adds an event listener that will only be executed once.
+   *
+   * @param event     The name of the event.
+   * @param listener  The listener function.
+   * @returns An unsubscribe function to remove the listener.
+   * @template EventName  The literal type of the event, to generate the type of the
+   *                      listener.
+   * @example
+   *
+   *   events.once('afterStart', ({ app }) => {
+   *     app.getLogger().info('Hello world!');
+   *     unsubscribe();
+   *   });
+   *
+   */
+  once: <EventName extends JimpexEventNameLike>(
+    eventName: EventName,
+    listener: JimpexEventListener<EventName>,
+  ) => () => boolean;
+  /**
+   * Emits an event and call all its listeners.
+   *
+   * @param event    The name of the events.
+   * @param payload  Context information for the event.
+   * @template EventName  The literal type of the event, to generate the type of the
+   *                      payload.
+   * @example
+   *
+   *   // Extend the interface to type the payload.
+   *   interface JimpexEvents {
+   *     myEvent: { message: string };
+   *   }
+   *   // Add the listener.
+   *   events.on('myEvent', ({ message }) => {
+   *     console.log('Event received:', message);
+   *   });
+   *   // Trigger the event.
+   *   events.emit('myEvent', { message: 'Hello' });
+   *   // prints "Event received: Hello"
+   *
+   */
+  emit: <EventName extends JimpexEventName>(
+    event: JimpexEventName,
+    payload: JimpexEventPayload<EventName>,
+  ) => void;
+  /**
+   * Asynchronously reduces a target using an event. It's like emit, but the event
+   * listeners return a modified (or not) version of the `target`.
+   *
+   * @param event    The name of the event.
+   * @param target   The variable to reduce with the reducers/listeners.
+   * @param payload  Context information for the event.
+   * @returns A version of the `target` processed by the listeners.
+   * @template EventName  The literal type of the event, to generate the types of the
+   *                      target and the payload.
+   * @example
+   *
+   *   // Extend the interface to type the target.
+   *   interface JimpexReducerEventTargets {
+   *     myReducer: unknown[];
+   *   }
+   *   // Extend the interface to type the payload.
+   *   interface JimpexReducerEventPayloads {
+   *     myReducer: {
+   *       message: string;
+   *     };
+   *   }
+   *   // Add the reducer.
+   *   events.on('myReducer', async (target, { message }) => {
+   *     const data = await fetch('https://api.example.com/' + message);
+   *     target.push(data);
+   *     return target;
+   *   });
+   *   // Trigger the event.
+   *   const result = await events.reduce('myReducer', [], { message: 'Hello' });
+   *   // result would be a list of data fetched from the API.
+   *
+   */
+  reduce: <EventName extends JimpexReducerEventName>(
+    event: JimpexReducerEventName,
+    target: JimpexReducerEventTarget<EventName>,
+    payload: JimpexReducerEventPayload<EventName>,
+  ) => Promise<JimpexReducerEventTarget<EventName>>;
+  /**
+   * Synchronously reduces a target using an event. It's like emit, but the events
+   * listener return a modified (or not) version of the `target`.
+   *
+   * @param event    The name of the event.
+   * @param target   The variable to reduce with the reducers/listeners.
+   * @param payload  Context information for the event.
+   * @returns A version of the `target` processed by the listeners.
+   * @template EventName  The literal type of the event, to generate the types of the
+   *                      target and the payload.
+   * @example
+   *
+   *   // Extend the interface to type the target.
+   *   interface JimpexReducerEventTargets {
+   *     myReducer: string[];
+   *   }
+   *   // Extend the interface to type the payload.
+   *   interface JimpexReducerEventPayloads {
+   *     myReducer: {
+   *       message: string;
+   *     };
+   *   }
+   *   // Add the reducer.
+   *   events.on('myReducer', (target, { message }) => {
+   *     target.push(message);
+   *     return target;
+   *   });
+   *   // Trigger the event.
+   *   events.reduce('event', [], 'Hello');
+   *   // returns ['Hello']
+   *
+   */
+  reduceSync: <EventName extends JimpexReducerEventName>(
+    event: JimpexReducerEventName,
+    target: JimpexReducerEventTarget<EventName>,
+    payload: JimpexReducerEventPayload<EventName>,
+  ) => JimpexReducerEventTarget<EventName>;
+};

package/src/types/express.ts

@@ -0,0 +1,21 @@
+import type { RequestHandler, ErrorRequestHandler } from 'express';
+
+export type { Express, Router, Request, Response, NextFunction } from 'express';
+
+export type ExpressMiddlewareLike = RequestHandler | ErrorRequestHandler;
+export type ExpressMiddleware = RequestHandler;
+export type AsyncExpressMiddleware = (
+  ...args: Parameters<ExpressMiddleware>
+) => Promise<void>;
+export type ExpressErrorHandler = ErrorRequestHandler;
+export type RouterMethod =
+  | 'all'
+  | 'get'
+  | 'head'
+  | 'post'
+  | 'patch'
+  | 'put'
+  | 'delete'
+  | 'connect'
+  | 'options'
+  | 'trace';

package/src/types/http.ts

@@ -0,0 +1,77 @@
+import type { Server as HTTPSServer } from 'https';
+import type { Server as HTTPServer } from 'http';
+import type { ServerOptions as SpdyServerOptions } from 'spdy';
+import type { Express } from './express';
+
+export type { Response as HTTPResponse } from 'node-fetch';
+
+export type { HTTPSServer, HTTPServer };
+/**
+ * @group Jimpex
+ */
+export type JimpexServer = Express | HTTPSServer;
+/**
+ * @group Jimpex
+ */
+export type JimpexServerInstance = HTTPServer | HTTPSServer;
+/**
+ * The paths to the SSL credentials. Depending on the application options, they can be
+ * relative to the project root, or the application executable, but they can't be
+ * absolute.
+ *
+ * @group Jimpex
+ */
+export type JimpexHTTPSCredentials = {
+  /**
+   * The path to the certificate authority file.
+   */
+  ca?: string;
+  /**
+   * The path to the certificate file.
+   */
+  cert?: string;
+  /**
+   * The path to the key file.
+   */
+  key?: string;
+};
+/**
+ * The options to enable HTTP2.
+ *
+ * @group Jimpex
+ */
+export type JimpexHTTP2Options = {
+  /**
+   * Whether or not to enable HTTP2.
+   */
+  enabled?: boolean;
+  /**
+   * Custom options for the Spdy server.
+   *
+   * @see {@link https://github.com/spdy-http2/node-spdy#options}
+   */
+  spdy?: SpdyServerOptions['spdy'];
+};
+/**
+ * The options to enable HTTPS.
+ *
+ * @group Jimpex
+ */
+export type JimpexHTTPSOptions = {
+  /**
+   * Whether or not to enable HTTPS.
+   */
+  enabled?: boolean;
+  /**
+   * The SSL credentials, and their location.
+   */
+  credentials?: JimpexHTTPSCredentials & {
+    /**
+     * If `true`, the credentials will be located relative to the project root, otherwise,
+     * they will be located relative to the application executable.
+     *
+     * @default false
+     */
+    onHome?: boolean;
+  };
+};

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export * from './events';
+export * from './express';
+export * from './http';
+export * from './options';
+export * from './utils';
+export * from './wootils';

package/src/types/options.ts

@@ -0,0 +1,248 @@
+import type { Config } from './wootils';
+import type { Jimpex } from '../app';
+/**
+ * The options for the application's configuration service.
+ *
+ * @see {@link https://www.npmjs.com/package/@homer0/simple-config}
+ * @group Jimpex
+ */
+export type JimpexConfigOptions = {
+  /**
+   * The default settings for the configuration. If no external configuration is used,
+   * this needs to include a `port` property.
+   */
+  default: unknown;
+  /**
+   * The name of the application, used for external configuration files.
+   *
+   * @default 'app'
+   */
+  name: string;
+  /**
+   * The path to where external configuration files are stored. Relative to the project
+   * root.
+   *
+   * @default 'config/'
+   */
+  path: string;
+  /**
+   * Whether the configuration files are inside a sub directory or not. If `true`, a
+   * configuration path would be `config/[app-name]/[file]`.
+   *
+   * @default false
+   */
+  hasFolder: boolean;
+  /**
+   * Whether or not to check for the environment variable and load a configuration file
+   * based on its value.
+   *
+   * @default true
+   */
+  loadFromEnvironment: boolean;
+  /**
+   * The name of the environment variable that will be used to set the active
+   * configuration.
+   *
+   * @default 'CONFIG'
+   */
+  environmentVariable: string;
+  /**
+   * The name of the default configuration file.
+   *
+   * @default '[app-name].config.js'
+   */
+  defaultConfigFilename: string;
+  /**
+   * The name format of other external configuration files.
+   *
+   * @default '[app-name].[config-name].config.js'
+   */
+  filenameFormat: string;
+};
+/**
+ * The options for the middleware that serves static files.
+ *
+ * @group Jimpex
+ */
+export type JimpexStaticsOptions = {
+  /**
+   * Whether or not to enable the middleware.
+   *
+   * @default true
+   */
+  enabled: boolean;
+  /**
+   * If `true`, the path to the statics folder will be relative to the project root
+   * directory, otherwise, it will be relative to the directory where the app executable
+   * file is located.
+   *
+   * @default false
+   */
+  onHome: boolean;
+  /**
+   * The name of both the route and the folder, relative to whatever you defined with the
+   * `onHome` option.
+   *
+   * @default 'statics'
+   */
+  route: string;
+  /**
+   * By default, the folder will be the same as the `route`,
+   * but you can use this option to define a relative path that won't affect the route.
+   *
+   * @default ''
+   */
+  folder?: string;
+};
+/**
+ * The options for the Express application.
+ *
+ * @group Jimpex
+ */
+export type JimpexExpressOptions = {
+  /**
+   * Whether or not to enable the `trust proxy` option.
+   *
+   * @default true
+   */
+  trustProxy: boolean;
+  /**
+   * Whether or not to remove the `x-powered-by` header.
+   *
+   * @default true
+   */
+  disableXPoweredBy: boolean;
+  /**
+   * Whether or not to add the `compression` middleware.
+   *
+   * @default true
+   */
+  compression: boolean;
+  /**
+   * Whether or not to add the `body-parser` middleware.
+   *
+   * @default true
+   */
+  bodyParser: boolean;
+  /**
+   * Whether or not to add the `multer` middleware.
+   *
+   * @see {@link https://www.npmjs.com/package/multer}
+   */
+  multer: boolean;
+};
+/**
+ * The options to configure the application executable path.
+ *
+ * @group Jimpex
+ */
+export type JimpexPathOptions = {
+  /**
+   * A "hardcoded" path to the application executable file.
+   *
+   * @default ''
+   */
+  appPath?: string;
+  /**
+   * If `true`, it will try to figure out the parent file path, and use its directory as
+   * the path.
+   *
+   * @default true
+   */
+  useParentPath: boolean;
+};
+/**
+ * The options to enable some of the default services Jimpex comes with.
+ *
+ * @group Jimpex
+ */
+export type JimpexServicesOptions = {
+  /**
+   * Whether or not to register all the `common` services: `appError`, `httpError`, and
+   * `sendFile`.
+   *
+   * @default true
+   */
+  common: boolean;
+  /**
+   * Whether or not to register the `http` services: `apiClient`, `http`, and
+   * `responsesBuilder`.
+   *
+   * @default true
+   */
+  http: boolean;
+  /**
+   * Whether or not to register the `utils` services: `ensureBearerToken`.
+   */
+  utils: boolean;
+};
+/**
+ * The format in which the application's health status can be returned.
+ * It's either a simple boolean, or a more detailed object.
+ *
+ * @group Jimpex
+ */
+export type JimpexHealthStatus =
+  | boolean
+  | {
+      isHealthy?: boolean;
+      services?: Record<string, boolean>;
+    };
+/**
+ * Returns the application health status. This is normally used by the `healthController`.
+ *
+ * @group Jimpex
+ */
+export type JimpexHealthCheckFn = (app: Jimpex) => Promise<JimpexHealthStatus>;
+/**
+ * The options to create a new instance of Jimpex.
+ *
+ * @group Jimpex
+ */
+export type JimpexOptions = {
+  /**
+   * The size limit for the requests payload.
+   *
+   * @default '15MB'
+   */
+  filesizeLimit: string;
+  /**
+   * Whether or not to call the `boot` method after initialization. This is useful if you
+   * want to register/overwrite services only on certain contexts, like a dev environment.
+   *
+   * @default true
+   */
+  boot: boolean;
+  /**
+   * The options to configure the application executable path.
+   */
+  path: JimpexPathOptions;
+  /**
+   * Options for the configuration service.
+   *
+   * @see {@link https://www.npmjs.com/package/@homer0/simple-config}
+   */
+  config: JimpexConfigOptions;
+  /**
+   * Options for the middleware that serves static files.
+   */
+  statics: JimpexStaticsOptions;
+  /**
+   * Options for the Express application.
+   */
+  express: JimpexExpressOptions;
+  /**
+   * Options to manage the default services.
+   */
+  services: JimpexServicesOptions;
+  /**
+   * A function that will be used to check the application health status.
+   */
+  healthCheck: JimpexHealthCheckFn;
+};
+/**
+ * The function called when the application starts listening for requests.
+ *
+ * @group Jimpex
+ */
+export type JimpexStartCallback = (config: Config) => void;

package/src/types/utils.ts

@@ -0,0 +1,52 @@
+/**
+ * A simple dictionary with unknown values.
+ *
+ * @group Utilities
+ */
+export type Dict = Record<string, unknown>;
+/**
+ * Utility to make a deep "partial" of an existing type.
+ *
+ * @template T  The type to make a partial of.
+ * @group Utilities
+ */
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends (infer U)[]
+    ? DeepPartial<U>[]
+    : T[P] extends object
+    ? DeepPartial<T[P]>
+    : T[P];
+};
+/**
+ * Utility to make a deep "readonly" of an existing type.
+ *
+ * @template T  The type to make a readonly of.
+ * @group Utilities
+ */
+export type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends (infer U)[]
+    ? DeepReadonly<U>[]
+    : T[P] extends object
+    ? DeepReadonly<T[P]>
+    : T[P];
+};
+/**
+ * Utility to remove string indexes from types.
+ *
+ * @template T  The type to remove string indexes from.
+ * @example
+ *
+ *   type Foo = {
+ *     a: string;
+ *     b: string;
+ *     [key: string]: string;
+ *   };
+ *   type Bar = RemoveStringIndexes<Foo>;
+ *   // Bar = {
+ *   //  a: string;
+ *   //  b: string;
+ *   // };
+ *
+ * @group Utilities
+ */
+export type NoStringIndex<T> = { [K in keyof T as string extends K ? never : K]: T[K] };

package/src/types/wootils.ts

@@ -0,0 +1,4 @@
+export type { PathUtils } from '@homer0/path-utils';
+export type { SimpleLogger as Logger } from '@homer0/simple-logger';
+export type { SimpleConfig as Config } from '@homer0/simple-config';
+export type { EventsHub } from '@homer0/events-hub';