Enable unsafe keep a json specification when compeller is invoked

.gitignore

@@ -3,3 +3,5 @@ node_modules
 dist
 
 *.tgz
+
+tmp

__tests__/compiler.test.ts

@@ -1,3 +1,4 @@
+import { join } from 'path';
 import { compeller } from '../src';
 
 const spec = {
@@ -47,5 +48,20 @@ describe('API Compiler tests', () => {
         statusCode: '200',
       });
     });
+
+    it('keeps a local specification json when true', () => {
+      const stuff = compeller(spec, {
+        jsonSpecFile: join(__dirname, 'tmp', 'openapi.json'),
+      });
+
+      const { response } = stuff('/test', 'get');
+
+      const resp = response('200', { name: 'Type-safe reply' });
+
+      expect(resp).toEqual({
+        body: '{"name":"Type-safe reply"}',
+        statusCode: '200',
+      });
+    });
   });
 });

__tests__/file-utils/write-specification.test.ts

@@ -0,0 +1,14 @@
+import { writeSpecification } from '../../src/file-utils/write-specification';
+
+describe('writeSpecification', () => {
+  it('with directory and not file', () => {
+    writeSpecification('./tmp', {
+      info: {
+        title: 'spec',
+        version: '0.0.1',
+      },
+      openapi: '3.1.0',
+      paths: {},
+    });
+  });
+});

_templates/compeller/new/compeller.ejs.t

@@ -0,0 +1,7 @@
+---
+to: <%= directory %>/openapi/compeller.ts
+---
+import { compeller } from 'compeller'
+import { OpenAPISpecification } from './spec'
+
+cont compelled = compeller(OpenAPISpecification)

_templates/compeller/new/spec.ejs.t

@@ -10,7 +10,7 @@ export const OpenAPISpecification = {
   },
   openapi: '3.1.0',
   paths: {
-    'v1//version': {
+    'v1/version': {
       get: {
         responses: {
           '200': {

jest.config.js

@@ -5,7 +5,4 @@ module.exports = {
   },
   testEnvironment: 'node',
   modulePathIgnorePatterns: ['<rootDir>/.*/fixtures/', '<rootDir>/example/*'],
-  moduleNameMapper: {
-    '^compeller/(.*)$': '<rootDir>/src/$1',
-  },
 };

package.json

@@ -21,6 +21,7 @@
     "@swc/jest": "^0.2.17",
     "@tsconfig/node14": "^1.0.1",
     "@types/jest": "^27.4.0",
+    "@types/node": "^17.0.12",
     "embedme": "^1.22.0",
     "husky": "^7.0.0",
     "jest": "^27.4.7",

src/compeller.ts

@@ -1,6 +1,40 @@
 import Ajv, { JSONSchemaType } from 'ajv';
 import { FromSchema } from 'json-schema-to-ts';
 import { OpenAPIObject } from 'openapi3-ts';
+import { writeSpecification } from './file-utils/write-specification';
+
+export interface ICompellerOptions {
+  /**
+   * The content type for the responses, currently only 'application/json' is
+   * supported
+   */
+  contentType?: string;
+  /**
+   * If boolean the default file location will be used
+   *
+   * @default false
+   */
+  jsonSpecFile?: string | boolean;
+  /**
+   * Bind the relative path where compeller is used, to enable storing the
+   * specification along side the compeller entity
+   */
+  relativePath?: string;
+}
+
+/**
+ * For now this is a mask on the OpenAPIObject, but later some fields will
+ * become mandatory.
+ *
+ * This is to enforce configuration, and remove the option for some fields to
+ * be any type, which is not the desired behavior for compeller.
+ */
+export interface ICompellerOpenAPIObject extends OpenAPIObject {}
+
+const DEFAULT_OPTIONS: ICompellerOptions = {
+  contentType: 'application/json',
+  jsonSpecFile: false,
+};
 
 /**
  * The open API Compiler will take in an OpenAPI specification and return type-
@@ -10,17 +44,23 @@ import { OpenAPIObject } from 'openapi3-ts';
  * classes that define the Components and Schema's of the paths.
  *
  * @param {OpenAPIObject} spec - The OpenAPI specification document
- * @param {string} contentType - The content type of requests and responses
- * @default 'application/json'
+ * @param {ICompellerOptions} options - Compeller options
  * @returns
  */
 export const compeller = <
-  T extends OpenAPIObject,
+  T extends ICompellerOpenAPIObject,
   U extends string = 'application/json'
 >(
   spec: T,
-  contentType = 'application/json'
+  {
+    contentType = 'application/json',
+    jsonSpecFile = false,
+  }: ICompellerOptions = DEFAULT_OPTIONS
 ) => {
+  if (jsonSpecFile) {
+    writeSpecification(jsonSpecFile, spec);
+  }
+
   return <
     P extends keyof T['paths'],
     M extends keyof T['paths'][P],
@@ -32,6 +72,8 @@ export const compeller = <
     const path = route as string;
 
     /**
+     * Build a response object for the API with the required status and body
+     * format
      *
      * @param statusCode The response code that the API returns
      * @param body The JSON body for the API that is associated with that

src/file-utils/write-specification.ts

@@ -0,0 +1,37 @@
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { ICompellerOpenAPIObject, ICompellerOptions } from '../compeller';
+
+/**
+ * Write a JSON object to file if a valid path if provided
+ *
+ * @default `${__dirname}/openapi.json`
+ *
+ * @param jsonSpecFile If true a default path will be used as provided, other provide a fully qualified path
+ * @param spec The OpenAPI specification object
+ */
+export const writeSpecification = (
+  jsonSpecFile: ICompellerOptions['jsonSpecFile'],
+  spec: ICompellerOpenAPIObject
+) => {
+  let fileName;
+
+  if (['production', 'prod'].includes(process?.env?.NODE_ENV || '')) return;
+
+  try {
+    fileName =
+      typeof jsonSpecFile === 'string'
+        ? jsonSpecFile
+        : join(__dirname, 'openapi.json');
+
+    writeFileSync(fileName, JSON.stringify(spec, undefined, 2));
+  } catch (err) {
+    console.warn(
+      'Compeller could not write your schema to a file and has rescued to prevent unwanted runtime side-effects',
+      {
+        fileName,
+        error: err,
+      }
+    );
+  }
+};

yarn.lock

@@ -838,7 +838,7 @@
   dependencies:
     "@types/node" "*"
 
-"@types/node@*":
+"@types/node@*", "@types/node@^17.0.12":
   version "17.0.12"
   resolved "https://registry.yarnpkg.com/@types/node/-/node-17.0.12.tgz#f7aa331b27f08244888c47b7df126184bc2339c5"
   integrity sha512-4YpbAsnJXWYK/fpTVFlMIcUIho2AYCi4wg5aNPrG1ng7fn/1/RZfCIpRCiBX+12RVa34RluilnvCqD+g3KiSiA==