moonflower 0.9.0

package/.eslintrc.js

@@ -0,0 +1,26 @@
+module.exports = {
+	root: true,
+	parser: '@typescript-eslint/parser',
+	parserOptions: {
+		project: 'tsconfig.json',
+		tsconfigRootDir: __dirname,
+		sourceType: 'module',
+	},
+	plugins: ['simple-import-sort', 'unused-imports', '@typescript-eslint/eslint-plugin'],
+	extends: ['plugin:@typescript-eslint/recommended', 'prettier', 'plugin:prettier/recommended'],
+	root: true,
+	env: {
+		node: true,
+		jest: true,
+	},
+	ignorePatterns: ['**/dist/**', '*.md'],
+	rules: {
+		'@typescript-eslint/interface-name-prefix': 'off',
+		'@typescript-eslint/explicit-function-return-type': 'off',
+		'@typescript-eslint/explicit-module-boundary-types': 'off',
+		'@typescript-eslint/no-explicit-any': 'off',
+		'@typescript-eslint/no-namespace': 'off',
+		'simple-import-sort/imports': 'error',
+		'simple-import-sort/exports': 'error',
+	},
+}

package/.prettierrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+	semi: false,
+	singleQuote: true,
+	printWidth: 110,
+	useTabs: true,
+}
+

package/README.md

@@ -0,0 +1,383 @@
+# Moonflower
+
+> This section is work-in-progress.
+
+Moonflower is a TypeScript-first [Koa Router](https://www.npmjs.com/package/koa-router) extension that allows for automatic [OpenAPI](https://www.openapis.org/what-is-openapi) spec generation directly from backend code, without any extra work. Combined with an ORM like [Prisma.js](https://www.npmjs.com/package/prisma) and an API client generator on frontend, it allows for creation of end-to-end type safe REST API.
+
+Moonflower provides type safe 'hooks' that handle runtime validation and return clean types with minimal boilerplate. 
+
+## Feature Overview
+
+- React hooks inspired Node.js backend REST API
+- Fully type safe definitions for path, query and header params, request body and response
+- Minimal boilerplate code
+- Out-of-the-box OpenAPI 3.1.0 spec generation
+
+## Usage example
+
+Every variable and parameter in this example is fully typed.
+
+```ts
+const router = new Router()
+
+router.post('/auth', (ctx) => {
+    useApiEndpoint({
+        name: 'createAccount',
+        summary: 'Registration endpoint',
+        description: 'Creates a new user account with provided credentials',
+    })
+
+    const body = useRequestBody(ctx, {
+        email: EmailValidator,
+        username: NonEmptyStringValidator,
+        password: NonEmptyStringValidator,
+    })
+
+    const user = UserService.register(body.email, body.username, body.password)
+    const token = TokenService.generateJwtToken(user)
+
+    return {
+        accessToken: token,
+    }
+})
+```
+
+Outputs the following spec (parts omitted for brevity):
+
+```json
+"/auth": {
+    "post": {
+        "operationId": "createAccount",
+        "summary": "Registration endpoint",
+        "description": "Creates a new user account with provided credentials",
+        "parameters": [],
+        "requestBody": {
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "type": "object",
+                        "properties": {
+                            "email": {
+                                "type": "string"
+                            },
+                            "username": {
+                                "type": "string"
+                            },
+                            "password": {
+                                "type": "string"
+                            }
+                        },
+                        "required": [
+                            "email",
+                            "username",
+                            "password"
+                        ]
+                    }
+                },
+            }
+        },
+        "responses": {
+            "200": {
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "oneOf": [{
+                                "type": "object",
+                                "properties": {
+                                    "accessToken": {
+                                        "type": "string"
+                                    }
+                                },
+                                "required": [
+                                    "accessToken"
+                                ]
+                            }]
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## Getting Started
+
+> This package requires a TypeScript based project. OpenAPI spec is created through parsing the TypeScript AST and can't be done in plain JS projects.
+
+Install dependencies:
+
+```bash
+yarn add moonflower koa @koa/router koa-bodyparser
+```
+
+Create a Koa instance with required middleware
+
+```ts
+import Koa from 'koa'
+import bodyParser from 'koa-bodyparser'
+import { HttpErrorHandler, initOpenApiEngine, Router } from 'moonflower'
+
+const app = new Koa()
+const myRouter = new Router()
+
+myRouter.get('/api/hello', (ctx) => {
+    /* Unlike in Koa, all endpoints must do a plain return.
+     * However, Koa context is still available for edge cases.
+     */
+    return {
+        greeting: 'hello world',
+    }
+})
+
+app
+    // Returns standard HTTP errors for common requests
+    .use(HttpErrorHandler)
+    .use(
+        // Required for requests with body
+        bodyParser({
+            enableTypes: ['text', 'json', 'form'],
+        })
+    )
+    // Register the router in Koa
+    .use(myRouter.routes())
+    .use(myRouter.allowedMethods())
+    .use(
+        // Enables collection of OpenAPI spec from code
+        initOpenApiEngine({
+            tsconfigPath: './tsconfig.json',
+        })
+    )
+```
+
+### Planned features
+
+- Support for list query params
+- Support for thrown errors in OpenApi engine
+- Support for binary data responses
+- Support for multipart form data
+
+### Known issues
+
+- Exported models are referenced by name only, leading to potential name collisions
+
+# Hooks
+> This section is work-in-progress.
+
+```ts
+// Dangling hooks
+useApiHeader({...})
+
+// Endpoint hooks
+const params = usePathParams(ctx, {...})
+const query = useQueryParams(ctx, {...})
+const body = useRequestBody(ctx, {...})
+const rawBody = useRequestRawBody(ctx, {...})
+```
+
+# Validators
+
+Validators are run for every parameter received from the client. Failed validation or an error thrown during validation will return 400 Bad Request to the user.
+
+**Example:**
+
+```ts
+const query = useQueryParams(ctx, {
+    name: RequiredParam(StringValidator),
+    fooBar: OptionalParam<{ foo: string; bar: string }>({
+        parse: (v) => JSON.parse(v),
+        validate: (v) => !!v.foo && !!v.bar
+    }),
+})
+
+query.name   // type is 'string'
+query.fooBar // type is '{ foo: string; bar: string } | undefined'
+```
+
+## Built-in validators
+
+The most common validators are available out-of-the-box.
+
+```ts
+const query = useQueryParams(ctx, {
+    myNumber: NumberValidator,
+    myString: StringValidator,
+    myBoolean: BooleanValidator,
+})
+
+query.myNumber  // type is 'number'
+query.myString  // type is 'string'
+query.myBoolean // type is 'boolean'
+```
+
+## Required and optional parameters
+```ts
+const query = useQueryParams(ctx, {
+    predefinedBool: BooleanValidator,
+    optionalBool: OptionalParam(BooleanValidator),
+    customBool: RequiredParam({
+        parse: (v) => v === '1',
+    }),
+    customOptionalBool: OptionalParam({
+        parse: (v) => v === '1',
+    }),
+})
+
+query.predefinedBool     // type is 'boolean'
+query.optionalBool       // type is 'boolean | undefined'
+query.customBool         // type is 'boolean'
+query.customOptionalBool // type is 'boolean | undefined'
+```
+
+## Custom validators
+
+Custom validators are simple objects that can be defined either inline, or elsewhere for reusability.
+
+### Inline
+
+```ts
+const query = useQueryParams(ctx, {
+    numberInRange: RequiredParam({
+        parse: (v) => Number(v),
+        validate: (v) => !isNaN(v) && v >= 0 && v <= 100,
+    }),
+    optionalBoolean: OptionalParam({
+        parse: (v) => v === '1',
+    }),
+})
+
+query.numberInRange   // type is 'number'
+query.optionalBoolean // type is 'boolean | undefined'
+```
+
+### Using Zod
+
+Zod schemas are compatible with validators, allowing you to directly use them to define runtime validation.
+
+```ts
+const body = useRequestBody(ctx, {
+    email: RequiredParam(z.string().email()),
+    password: RequiredParam(z.string()),
+})
+
+const { email, password } = body
+```
+
+## Anatomy of a validator
+
+A validator contains a number of functions that are useful to check and transform incoming data.
+
+### Parse
+
+> `parse: (v: string) => T extends any`
+
+The only required function of a validator. It takes the raw input param and transforms it into correct data type. The return type of `parse` will match the one specified in the `RequiredParam` or `OptionalParam` generics, or will be used to infer the type.
+
+Make sure that it returns a correctly typed object.
+
+### Validate
+
+> `validate: (v: T) => boolean`
+
+This function is called on incoming data after it is parsed. 
+
+Returning `false` or any falsy value will cause the validation to fail, and `400 Bad Request` to be sent back to the client.
+
+### Prevalidate
+
+> `prevalidate: (v: string) => boolean`
+
+This function is called on incoming data before it is parsed. Useful in cases where rehydration function is slow (i.e. includes a DB read), and some premature validation is desired. In most cases, however, `validate` is preferred.
+
+The behaviour is identical to `validate`, aside from the call order.
+
+### Type inference
+
+In many cases, type of the parameter can be inferred from the return value of `parse` function. For more complex objects, it is possible to specify the type with `as ...` clause:
+
+
+```ts
+useQueryParams(ctx, {
+    fooBar: RequiredParam({
+        prevalidate: (v) => v.length > 5,
+        parse: (v) => JSON.parse(v) as { foo: string; bar: string },
+        validate: (v) => !!v.foo && !!v.bar
+    }),
+})
+```
+
+Alternatively, the expected type can be mentioned in `RequiredParam`, `OptionalParam` or `PathParam` generics:
+
+```ts
+useQueryParams(ctx, {
+    fooBar: RequiredParam<{ foo: string; bar: string }>({
+        prevalidate: (v) => v.length > 5,
+        parse: (v) => JSON.parse(v),
+        validate: (v) => !!v.foo && !!v.bar
+    }),
+})
+```
+
+### Avoid
+
+While the following is valid code, the type of the parameter can't be inferred as TS will not parse this as Validator type. The type of `validate` will be `(v: any) => boolean`, which is unsafe.
+
+```ts
+useQueryParams(ctx, {
+    myParam: {
+        parse: (v) => Number(v),
+        validate: (v) => v > 0,
+        optional: false,
+    },
+})
+```
+
+# Path params
+
+Path params have extra binding to the endpoint path. Only the properties mentioned in the path can be used.
+
+```ts
+router.get('/user/:userId', (ctx) => {
+    const params = usePathParams(ctx, {
+        userId: StringValidator,   // valid
+        username: StringValidator, // 'username' is not a path param
+    })
+
+    params.userId  // type is 'string'
+}
+```
+
+## Optional path params
+
+Following standard Koa way of defining an optional param, a param marked by a question mark is considered optional.
+
+```ts
+router.get('/user/:userId?', (ctx) => {
+    const params = usePathParams(ctx, {
+        userId: StringValidator,
+    })
+
+    params.userId  // type is 'string | undefined'
+}
+```
+
+## Custom path parameters
+
+As parameter optionaliy is defined in a path, `RequiredParam` and `OptionalParam` will be ignored. To reduce confusion, `PathParam` is available.
+
+```ts
+router.get('/user/:numberId', (ctx) => {
+    usePathParams(ctx, {
+        numberId: PathParam({
+            parse: (v) => Number(v),
+            validate: (v) => !isNaN(v) && v >= 0 && v <= 100,
+        })
+    })
+}
+```
+
+## Escape hatch
+
+All Koa and Koa Router APIs are still available in case some functionality is unavailable through Moonflower. Endpoints provide a `ctx` prop, and the router expose `koaRouter` which is raw underlying router implementation.
+
+However, avoiding Moonflower's API will degrade the quality of the generated spec.

package/cli/cli.ts

@@ -0,0 +1,59 @@
+import * as fs from 'fs'
+import * as path from 'path'
+import yargs, { ArgumentsCamelCase } from 'yargs'
+import { hideBin } from 'yargs/helpers'
+
+import { prepareOpenApiSpec } from '../src/openapi/analyzerModule/analyzerModule'
+import { generateOpenApiSpec } from '../src/openapi/generatorModule'
+import { OpenApiManager } from '../src/openapi/manager/OpenApiManager'
+import { printAnalysisStats } from './prettyprint'
+
+const originalConsole = console.info
+console.info = (message, ...args) => {
+	originalConsole(`${message}`, ...args)
+}
+
+yargs(hideBin(process.argv))
+	.showHelpOnFail(true)
+	.command({
+		command: 'openapi <targetPath>',
+		describe: 'Generates the current openapi spec into a specified file path',
+		builder: {
+			targetPath: {
+				describe: 'Target path',
+				demandOption: true,
+				type: 'string',
+				coerce: (f) => path.resolve(f),
+			},
+
+			tsConfigPath: {
+				describe: 'tsconfig',
+				type: 'string',
+				coerce: (f) => path.resolve(f),
+			},
+		},
+
+		handler(argv: ArgumentsCamelCase<{ targetPath: string; tsConfigPath?: string }>) {
+			if (fs.existsSync(argv.targetPath)) {
+				console.error(`[Error] File already exists at ${argv.targetPath}`)
+				return
+			}
+
+			if (argv.tsConfigPath && !fs.existsSync(argv.tsConfigPath)) {
+				console.error(`[Error] Unable to find a tsconfig file at ${argv.tsConfigPath}`)
+				return
+			}
+
+			prepareOpenApiSpec({
+				tsconfigPath: argv.tsConfigPath ?? 'tsconfig.json',
+			})
+
+			const manager = OpenApiManager.getInstance()
+			printAnalysisStats(manager.getStats())
+
+			const spec = generateOpenApiSpec(manager)
+			fs.writeFileSync(argv.targetPath, JSON.stringify(spec))
+		},
+	})
+	.demandCommand()
+	.parse()

package/cli/entry.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/cli/cli.js')

package/cli/prettyprint.ts

@@ -0,0 +1,16 @@
+import { ApiAnalysisStats } from '../src/openapi/manager/OpenApiManager'
+
+export const printAnalysisStats = (stats: ApiAnalysisStats) => {
+	stats.explicitRouterFiles.forEach((file) => printRouterFile(file))
+	stats.discoveredRouterFiles.forEach((file) => printRouterFile(file))
+}
+
+export const printRouterFile = (file: ApiAnalysisStats['discoveredRouterFiles'][number]) => {
+	console.info(`${file.path}`)
+	file.routers.forEach((r) => {
+		console.info(`└ ${r.name}`)
+		r.endpoints.forEach((e) => {
+			console.info(`  └ ${e}`)
+		})
+	})
+}

package/dist/cli/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../cli/cli.ts"],"names":[],"mappings":""}

package/dist/cli/cli.js

@@ -0,0 +1,79 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yargs_1 = __importDefault(require("yargs"));
+const helpers_1 = require("yargs/helpers");
+const analyzerModule_1 = require("../src/openapi/analyzerModule/analyzerModule");
+const generatorModule_1 = require("../src/openapi/generatorModule");
+const OpenApiManager_1 = require("../src/openapi/manager/OpenApiManager");
+const prettyprint_1 = require("./prettyprint");
+const originalConsole = console.info;
+console.info = (message, ...args) => {
+    originalConsole(`${message}`, ...args);
+};
+(0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
+    .showHelpOnFail(true)
+    .command({
+    command: 'openapi <targetPath>',
+    describe: 'Generates the current openapi spec into a specified file path',
+    builder: {
+        targetPath: {
+            describe: 'Target path',
+            demandOption: true,
+            type: 'string',
+            coerce: (f) => path.resolve(f),
+        },
+        tsConfigPath: {
+            describe: 'tsconfig',
+            type: 'string',
+            coerce: (f) => path.resolve(f),
+        },
+    },
+    handler(argv) {
+        var _a;
+        if (fs.existsSync(argv.targetPath)) {
+            console.error(`[Error] File already exists at ${argv.targetPath}`);
+            return;
+        }
+        if (argv.tsConfigPath && !fs.existsSync(argv.tsConfigPath)) {
+            console.error(`[Error] Unable to find a tsconfig file at ${argv.tsConfigPath}`);
+            return;
+        }
+        (0, analyzerModule_1.prepareOpenApiSpec)({
+            tsconfigPath: (_a = argv.tsConfigPath) !== null && _a !== void 0 ? _a : 'tsconfig.json',
+        });
+        const manager = OpenApiManager_1.OpenApiManager.getInstance();
+        (0, prettyprint_1.printAnalysisStats)(manager.getStats());
+        const spec = (0, generatorModule_1.generateOpenApiSpec)(manager);
+        fs.writeFileSync(argv.targetPath, JSON.stringify(spec));
+    },
+})
+    .demandCommand()
+    .parse();

package/dist/cli/prettyprint.d.ts

@@ -0,0 +1,4 @@
+import { ApiAnalysisStats } from '../src/openapi/manager/OpenApiManager';
+export declare const printAnalysisStats: (stats: ApiAnalysisStats) => void;
+export declare const printRouterFile: (file: ApiAnalysisStats['discoveredRouterFiles'][number]) => void;
+//# sourceMappingURL=prettyprint.d.ts.map

package/dist/cli/prettyprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prettyprint.d.ts","sourceRoot":"","sources":["../../cli/prettyprint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAA;AAExE,eAAO,MAAM,kBAAkB,UAAW,gBAAgB,SAGzD,CAAA;AAED,eAAO,MAAM,eAAe,SAAU,gBAAgB,CAAC,uBAAuB,CAAC,CAAC,MAAM,CAAC,SAQtF,CAAA"}

package/dist/cli/prettyprint.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printRouterFile = exports.printAnalysisStats = void 0;
+const printAnalysisStats = (stats) => {
+    stats.explicitRouterFiles.forEach((file) => (0, exports.printRouterFile)(file));
+    stats.discoveredRouterFiles.forEach((file) => (0, exports.printRouterFile)(file));
+};
+exports.printAnalysisStats = printAnalysisStats;
+const printRouterFile = (file) => {
+    console.info(`${file.path}`);
+    file.routers.forEach((r) => {
+        console.info(`└ ${r.name}`);
+        r.endpoints.forEach((e) => {
+            console.info(`  └ ${e}`);
+        });
+    });
+};
+exports.printRouterFile = printRouterFile;

package/dist/src/errors/BaseHttpError.d.ts

@@ -0,0 +1,13 @@
+import { StatusCodes } from 'http-status-codes';
+export interface HttpError {
+    status: StatusCodes;
+    reason: string;
+    message: string;
+}
+export declare class BaseHttpError extends Error implements HttpError {
+    status: StatusCodes;
+    message: string;
+    reason: string;
+    constructor(status: StatusCodes, message: string);
+}
+//# sourceMappingURL=BaseHttpError.d.ts.map

package/dist/src/errors/BaseHttpError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseHttpError.d.ts","sourceRoot":"","sources":["../../../src/errors/BaseHttpError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEhE,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,WAAW,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CACf;AAED,qBAAa,aAAc,SAAQ,KAAM,YAAW,SAAS;IAGzC,MAAM,EAAE,WAAW;IAAS,OAAO,EAAE,MAAM;IAFvD,MAAM,EAAE,MAAM,CAAA;gBAEF,MAAM,EAAE,WAAW,EAAS,OAAO,EAAE,MAAM;CAI9D"}

package/dist/src/errors/BaseHttpError.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseHttpError = void 0;
+const http_status_codes_1 = require("http-status-codes");
+class BaseHttpError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.message = message;
+        this.reason = (0, http_status_codes_1.getReasonPhrase)(status);
+    }
+}
+exports.BaseHttpError = BaseHttpError;

package/dist/src/errors/HttpErrorHandler.d.ts

@@ -0,0 +1,3 @@
+import Koa from 'koa';
+export declare const HttpErrorHandler: (ctx: Koa.ParameterizedContext, next: Koa.Next) => Promise<void>;
+//# sourceMappingURL=HttpErrorHandler.d.ts.map

package/dist/src/errors/HttpErrorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpErrorHandler.d.ts","sourceRoot":"","sources":["../../../src/errors/HttpErrorHandler.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,KAAK,CAAA;AAIrB,eAAO,MAAM,gBAAgB,QAAe,IAAI,oBAAoB,QAAQ,IAAI,IAAI,kBAenF,CAAA"}

package/dist/src/errors/HttpErrorHandler.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpErrorHandler = void 0;
+const BaseHttpError_1 = require("./BaseHttpError");
+const HttpErrorHandler = async (ctx, next) => {
+    try {
+        await next();
+    }
+    catch (err) {
+        if (err instanceof BaseHttpError_1.BaseHttpError) {
+            ctx.status = err.status;
+            ctx.body = {
+                status: err.status,
+                reason: err.reason,
+                message: err.message,
+            };
+        }
+        else {
+            throw err;
+        }
+    }
+};
+exports.HttpErrorHandler = HttpErrorHandler;