@whook/cors

@whook/cors

A wrapper to provide CORS support to a Whook server

This Whook wrapper provides CORS support by adding it to your OpenAPI file and creating the routes that runs the OPTIONS method when you cannot do it at the proxy/gateway level.

Usage

To use this plugin, simply install it:

npm i @whook/cors;

Declare it in the src/index.ts file of your project:

  // ...

  $.register(
    constant('ROUTES_WRAPPERS_NAMES', [
+      'wrapRouteHandlerWithCORS',
      'wrapRouteHandlerWithAuthorization',
    ]),
  );

  // ...

  $.register(
    constant('WHOOK_PLUGINS', [
      ...WHOOK_DEFAULT_PLUGINS,
+      '@whook/cors',
      '@whook/authorization',
    ]),
  );

  // ...

Declare types in your src/whook.d.ts definition:

+ import {
+   type WhookCORSConfig,
+   type WhookCORSRouteConfig,
+ } from '@whook/cors';

declare module 'application-services' {

  // ...

  export interface AppConfig
-    extends WhookBaseConfigs {}
+    extends WhookBaseConfigs, WhookCORSConfig {}

  // ...
}

// ...

declare module '@whook/whook' {
  export interface WhookRouteConfig
-    extends WhookBaseRouteConfig {}
+    extends WhookBaseRouteConfig,
+      WhookCORSRouteConfig {}
}

And add the CORS config (usually in src/config/common/config.js):

// ...
import { type AppConfig } from 'application-services';

const CONFIG: AppConfig = {
  // ...
+   CORS: {
+     'Access-Control-Allow-Origin': '*',
+     'Access-Control-Allow-Methods': 'GET,POST,PUT,DELETE,OPTIONS',
+     'Access-Control-Allow-Headers': [
+       'Accept',
+       'Accept-Encoding',
+       'Accept-Language',
+       'Referrer',
+       'Content-Type',
+       'Content-Encoding',
+       'Authorization',
+       'Keep-Alive',
+       'User-Agent',
+     ].join(','),
+   },
};

export default CONFIG;

You should also use the wrapped error handler:

+ import {
+  initErrorHandlerWithCORS,
+  wrapDefinitionsWithCORS,
+} from '@whook/cors';

// ...

export async function prepareEnvironment<T extends Knifecycle<Dependencies>>(
    $: T = new Knifecycle() as T,
  ): Promise<T> {

//...

+  // Wrap the definitions for CORS
+  $.register(wrapDefinitionsWithCORS(initDefinitions));

+  // Add the CORS wrapped error handler
+  $.register(initErrorHandlerWithCORS);

  return $;
}

According to the kind of build you use, you may also declare it in your src/build.ts file:

  $.register(
    constant('INITIALIZER_PATH_MAP', {
      ...DEFAULT_BUILD_INITIALIZER_PATH_MAP,
      // MY_SERVICE: '@my/service_module_name',
      jwtToken: 'jwt-service/dist/index.js',
+      errorHandler: '@whook/cors/dist/services/errorHandler.js',
    }),
  );

To see a real example have a look at the @whook/example.

Note that you can define individual CORS values on the handler definitions usins the x-whook property.

API

Functions

wrapDefinitionsWithCORS(API) ⇒ Promise.<Object>

Augment an OpenAPI to also serve OPTIONS methods with the CORS added.

initOptionsWithCORS() ⇒ Promise.<Object>

A simple Whook handler that just returns a 200 OK HTTP response

wrapErrorHandlerForCORS(services) ⇒ Promise.<Object>

Wrap the error handler service as a last chance to add CORS

initWrapRouteHandlerWithCORS(services) ⇒ Promise.<Object>

Wrap a route handler to append CORS to response.

wrapDefinitionsWithCORS(API) ⇒ Promise.<Object>

Augment an OpenAPI to also serve OPTIONS methods with the CORS added.

Kind: global function
Returns: Promise.<Object> - The augmented OpenAPI object

Param	Type	Description
API	Object	The OpenAPI object

initOptionsWithCORS() ⇒ Promise.<Object>

A simple Whook handler that just returns a 200 OK HTTP response

Kind: global function
Returns: Promise.<Object> - The HTTP response object

wrapErrorHandlerForCORS(services) ⇒ Promise.<Object>

Wrap the error handler service as a last chance to add CORS

Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.

Param	Type	Default	Description
services	Object		The service dependencies
services.CORS	Object		A CORS object to be added to errors responses
[services.log]	Object	noop	An optional logging service

initWrapRouteHandlerWithCORS(services) ⇒ Promise.<Object>

Wrap a route handler to append CORS to response.

Kind: global function
Returns: Promise.<Object> - A promise of an object containing the reshaped env vars.

Param	Type	Default	Description
services	Object		The service dependencies
services.CORS	Object		A CORS object to be added to errors responses
[services.log]	Object	noop	An optional logging service

Authors

• Nicolas Froidure

License

MIT