moonflower 0.9.0

package/src/openapi/initOpenApiEngine.ts

@@ -0,0 +1,20 @@
+import Koa from 'koa'
+
+import { prepareOpenApiSpec } from './analyzerModule/analyzerModule'
+import { OpenApiRouter } from './router/OpenApiRouter'
+
+/**
+ * Middleware to initialize the openApi engine.
+ * Can be at any position in the middleware execution order.
+ * All files with routers or exposed models must be included in `props.sourceFilePaths`.
+ * @param props Paths to files to analyze, relative to project root.
+ */
+export const initOpenApiEngine = (props: Parameters<typeof prepareOpenApiSpec>[0]) => {
+	prepareOpenApiSpec(props)
+
+	const builtInRoutes = OpenApiRouter.routes()
+	const builtInAllowedMethods = OpenApiRouter.allowedMethods()
+	return (ctx: Koa.ParameterizedContext<any, any>, next: Koa.Next) => {
+		return builtInRoutes(ctx, () => builtInAllowedMethods(ctx, next))
+	}
+}

package/src/openapi/manager/OpenApiManager.ts

@@ -0,0 +1,153 @@
+import { Router } from '../../router/Router'
+import { EndpointData, ExposedModelData } from '../types'
+
+type UrlType = `${'http' | 'https'}://${string}.${string}`
+
+export type ApiDocsHeader = {
+	title: string
+	version: string
+	description?: string
+	termsOfService?: UrlType
+	contact?: {
+		name?: string
+		url?: UrlType
+		email?: string
+	}
+	license?: {
+		name?: string
+		url?: UrlType
+	}
+}
+
+export type ApiDocsPreferences = {
+	allowOptionalPathParams: boolean
+}
+
+export type ApiAnalysisStats = {
+	explicitRouterFiles: {
+		path: string
+		routers: {
+			name: string
+			endpoints: string[]
+		}[]
+	}[]
+	discoveredRouterFiles: {
+		path: string
+		routers: {
+			name: string
+			endpoints: string[]
+		}[]
+	}[]
+}
+
+export class OpenApiManager {
+	private static instance: OpenApiManager | null = null
+
+	private isInitialized = false
+	private registeredRouters: Router[] = []
+
+	constructor(
+		private apiDocsHeader: ApiDocsHeader,
+		private exposedModels: ExposedModelData[],
+		private endpoints: EndpointData[],
+		private preferences: ApiDocsPreferences,
+		private stats: ApiAnalysisStats
+	) {}
+
+	public isReady(): boolean {
+		return this.isInitialized
+	}
+
+	public hasExposedModel(name: string) {
+		return this.exposedModels.some((model) => model.name === name)
+	}
+
+	public getExposedModels() {
+		return this.exposedModels
+	}
+
+	public setExposedModels(models: ExposedModelData[]) {
+		this.exposedModels = models
+		return this
+	}
+
+	public setEndpoints(endpoints: EndpointData[]) {
+		this.endpoints = endpoints
+		return this
+	}
+
+	public markAsReady() {
+		this.isInitialized = true
+		return this
+	}
+
+	public getHeader(): ApiDocsHeader {
+		return this.apiDocsHeader
+	}
+
+	public setHeader(docs: ApiDocsHeader) {
+		this.apiDocsHeader = docs
+		return this
+	}
+
+	public getEndpoints() {
+		return this.endpoints
+	}
+
+	public getPreferences() {
+		return this.preferences
+	}
+
+	public setPreferences(preferences: ApiDocsPreferences) {
+		this.preferences = {
+			...preferences,
+		}
+		return this
+	}
+
+	public getStats() {
+		return this.stats
+	}
+
+	public setStats(stats: ApiAnalysisStats) {
+		this.stats = {
+			...stats,
+		}
+		return this
+	}
+
+	public getRouters(): readonly Router[] {
+		return this.registeredRouters
+	}
+
+	public registerRouters(routers: Router<any, any>[]) {
+		routers.forEach((r) => this.registeredRouters.push(r))
+		return this
+	}
+
+	public reset() {
+		this.exposedModels = []
+		this.endpoints = []
+	}
+
+	public static getInstance() {
+		if (!OpenApiManager.instance) {
+			OpenApiManager.instance = new OpenApiManager(
+				{
+					title: 'Default title',
+					version: '1.0.0',
+				},
+				[],
+				[],
+				{
+					allowOptionalPathParams: false,
+				},
+				{
+					discoveredRouterFiles: [],
+					explicitRouterFiles: [],
+				}
+			)
+		}
+		return OpenApiManager.instance
+	}
+}

package/src/openapi/router/OpenApiRouter.ts

@@ -0,0 +1,11 @@
+import { Router } from '../../router/Router'
+import { generateOpenApiSpec } from '../generatorModule/generatorModule'
+import { OpenApiManager } from '../manager/OpenApiManager'
+
+const router = new Router({ skipOpenApiAnalysis: true })
+
+router.get('/api-json', () => {
+	return generateOpenApiSpec(OpenApiManager.getInstance())
+})
+
+export const OpenApiRouter = router

package/src/openapi/types.ts

@@ -0,0 +1,86 @@
+import { ShapeOfType } from './analyzerModule/types'
+import { SchemaType } from './generatorModule/getSchema'
+
+type PathParam = {
+	name: string
+	in: 'query' | 'path' | 'header'
+	description: string
+	required: true | false | undefined
+}
+
+export type PathDefinition = {
+	summary?: string
+	description: string
+	operationId?: string
+	parameters: PathParam[]
+	requestBody: any
+	tags?: string[]
+	responses: Record<
+		string,
+		{
+			description: string
+			content?: {
+				'application/json': {
+					schema: {
+						oneOf: SchemaType[]
+					}
+				}
+			}
+		}
+	>
+}
+
+export type ExposedModelData = {
+	name: string
+	shape: string | ShapeOfType[]
+}
+
+export type EndpointData = {
+	method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+	path: string
+	sourceFilePath: string
+	name?: string
+	summary?: string
+	description?: string
+	tags?: string[]
+	requestPathParams: {
+		identifier: string
+		signature: string | ShapeOfType[]
+		optional: boolean
+		description?: string
+		errorMessage?: string
+	}[]
+	requestQuery: {
+		identifier: string
+		signature: string | ShapeOfType[]
+		optional: boolean
+		description?: string
+		errorMessage?: string
+	}[]
+	requestHeaders: {
+		identifier: string
+		signature: string | ShapeOfType[]
+		optional: boolean
+		description?: string
+		errorMessage?: string
+	}[]
+	rawBody?: {
+		signature: string | ShapeOfType[]
+		optional: boolean
+		description?: string
+		errorMessage?: string
+	}
+	objectBody: {
+		identifier: string
+		signature: string | ShapeOfType[]
+		optional: boolean
+		description?: string
+		errorMessage?: string
+	}[]
+	responses: {
+		status: number
+		signature: string | ShapeOfType[]
+		description?: string
+		errorMessage?: string
+	}[]
+}

package/src/router/Router.ts

@@ -0,0 +1,123 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+import KoaRouter from '@koa/router'
+import Koa from 'koa'
+
+import { OpenApiManager } from '../openapi/manager/OpenApiManager'
+import { ExtractedRequestParams } from '../utils/TypeUtils'
+import { responseValueToJson } from './responseValueToJson'
+
+type Props = {
+	skipOpenApiAnalysis: boolean
+}
+
+export class Router<StateT = Koa.DefaultState, ContextT = Koa.DefaultContext> {
+	public koaRouter: KoaRouter = new KoaRouter()
+
+	public constructor(props: Props = { skipOpenApiAnalysis: false }) {
+		if (!props.skipOpenApiAnalysis) {
+			const openApiManager = OpenApiManager.getInstance()
+			openApiManager.registerRouters([this])
+		}
+	}
+
+	public use(...middleware: Array<KoaRouter.Middleware<StateT, ContextT>>) {
+		// @ts-ignore
+		this.koaRouter.use(...middleware)
+		return this
+	}
+
+	public with<ResponseTypeT extends Record<string, any>>(
+		middleware: (ctx: Koa.ParameterizedContext<ContextT>) => ResponseTypeT
+	) {
+		type AugmentedData = ResponseTypeT extends Promise<any> ? Awaited<ResponseTypeT> : ResponseTypeT
+		this.koaRouter.use(async (ctx, next) => {
+			// @ts-ignore
+			const userData = await Promise.resolve(middleware(ctx))
+			Object.keys(userData).forEach((key) => {
+				ctx[key] = userData[key]
+			})
+			await next()
+		})
+		return this as Router<StateT, ContextT & AugmentedData>
+	}
+
+	public get<P extends string>(
+		path: P,
+		callback: KoaRouter.Middleware<StateT, ContextT & ExtractedRequestParams<P>>
+	) {
+		this.koaRouter.get(path, async (ctx) => {
+			// @ts-ignore
+			const responseValue = await callback(ctx, undefined)
+			ctx.body = responseValueToJson(responseValue)
+		})
+		return this
+	}
+
+	public post<P extends string>(
+		path: P,
+		callback: KoaRouter.Middleware<StateT, ContextT & ExtractedRequestParams<P>>
+	) {
+		this.koaRouter.post(path, async (ctx) => {
+			// @ts-ignore
+			const responseValue = await callback(ctx, undefined)
+			ctx.body = responseValueToJson(responseValue)
+		})
+		return this
+	}
+
+	public put<P extends string>(
+		path: P,
+		callback: KoaRouter.Middleware<StateT, ContextT & ExtractedRequestParams<P>>
+	) {
+		this.koaRouter.put(path, async (ctx) => {
+			// @ts-ignore
+			const responseValue = await callback(ctx, undefined)
+			ctx.body = responseValueToJson(responseValue)
+		})
+		return this
+	}
+
+	public delete<P extends string>(
+		path: P,
+		callback: KoaRouter.Middleware<StateT, ContextT & ExtractedRequestParams<P>>
+	) {
+		this.koaRouter.delete(path, async (ctx) => {
+			// @ts-ignore
+			const responseValue = await callback(ctx, undefined)
+			ctx.body = responseValueToJson(responseValue)
+		})
+		return this
+	}
+
+	public del<P extends string>(
+		path: P,
+		callback: KoaRouter.Middleware<StateT, ContextT & ExtractedRequestParams<P>>
+	) {
+		this.koaRouter.del(path, async (ctx) => {
+			// @ts-ignore
+			const responseValue = await callback(ctx, undefined)
+			ctx.body = responseValueToJson(responseValue)
+		})
+		return this
+	}
+
+	public patch<P extends string>(
+		path: P,
+		callback: KoaRouter.Middleware<StateT, ContextT & ExtractedRequestParams<P>>
+	) {
+		this.koaRouter.patch(path, async (ctx) => {
+			// @ts-ignore
+			const responseValue = await callback(ctx, undefined)
+			ctx.body = responseValueToJson(responseValue)
+		})
+		return this
+	}
+
+	public routes() {
+		return this.koaRouter.routes()
+	}
+
+	public allowedMethods() {
+		return this.koaRouter.allowedMethods()
+	}
+}

package/src/router/responseValueToJson.ts

@@ -0,0 +1,6 @@
+export const responseValueToJson = (value: any) => {
+	if (typeof value === 'string') {
+		return value
+	}
+	return JSON.stringify(value, (_, value) => (typeof value === 'bigint' ? value.toString() : value))
+}

package/src/setupTests.ts

@@ -0,0 +1,3 @@
+console.info = () => {
+	/* Empty */
+}

package/src/test/TestAppRouter.ts

@@ -0,0 +1,76 @@
+import {
+	BadRequestError,
+	EmailValidator,
+	NonEmptyStringValidator,
+	UnauthorizedError,
+	useQueryParams,
+} from '..'
+import { Router as RenamedRouter } from '../router/Router'
+
+const myRouter = new RenamedRouter()
+	.use((_, next) => next())
+	.with(() => {
+		const user = { id: '123' }
+		return {
+			user,
+		}
+	})
+
+myRouter.get('/test/hello', () => {
+	return {
+		greeting: 'hello world',
+	}
+})
+
+myRouter.get('/test/query', (ctx) => {
+	const { email, string } = useQueryParams(ctx, {
+		email: EmailValidator,
+		string: NonEmptyStringValidator,
+	})
+	return {
+		email,
+		string,
+	}
+})
+
+myRouter.post('/test/post', () => {
+	return 'post response'
+})
+
+myRouter.del('/test/del', () => {
+	// Empty
+})
+
+myRouter.delete('/test/delete', () => {
+	// Empty
+})
+
+myRouter.patch('/test/patch', () => {
+	return 'patch response'
+})
+
+myRouter.get('/test/error/generic', () => {
+	throw new Error('Generic error')
+})
+
+myRouter.get('/test/error/unauthorized', () => {
+	throw new UnauthorizedError('Test error')
+})
+
+myRouter.get('/test/error/badrequest', () => {
+	throw new BadRequestError('Test error')
+})
+
+myRouter.get('/test/get/bigint', () => {
+	return {
+		foo: BigInt(100),
+	}
+})
+
+myRouter.get('/test/get/middleware-data', (ctx) => {
+	return {
+		user: ctx.user,
+	}
+})
+
+export const TestAppRouter = myRouter

package/src/test/app.spec.ts

@@ -0,0 +1,130 @@
+import request from 'supertest'
+import { vi } from 'vitest'
+
+import { generateOpenApiSpec } from '../openapi/generatorModule/generatorModule'
+import { app } from './app'
+
+describe('TestAppRouter', () => {
+	it('handles get request correctly', async () => {
+		const response = await request(app.callback()).get('/test/hello')
+		expect(response.status).toBe(200)
+		expect(response.text).toBe(JSON.stringify({ greeting: 'hello world' }))
+	})
+
+	it('handles query params', async () => {
+		const response = await request(app.callback()).get('/test/query?email=test@test.com&string=someval')
+		expect(response.status).toBe(200)
+		expect(response.text).toBe(JSON.stringify({ email: 'test@test.com', string: 'someval' }))
+	})
+
+	it('handles incorrect method', async () => {
+		const response = await request(app.callback()).post('/test/hello')
+		expect(response.status).toBe(405)
+		expect(response.text).toBe('Method Not Allowed')
+	})
+
+	it('handles post request correctly', async () => {
+		const response = await request(app.callback()).post('/test/post')
+		expect(response.status).toBe(200)
+		expect(response.text).toBe('post response')
+	})
+
+	it('handles del request correctly', async () => {
+		const response = await request(app.callback()).del('/test/del')
+		expect(response.status).toBe(204)
+		expect(response.text).toBe('')
+	})
+
+	it('handles delete request correctly', async () => {
+		const response = await request(app.callback()).delete('/test/delete')
+		expect(response.status).toBe(204)
+		expect(response.text).toBe('')
+	})
+
+	it('handles patch request correctly', async () => {
+		const response = await request(app.callback()).patch('/test/patch')
+		expect(response.status).toBe(200)
+		expect(response.text).toBe('patch response')
+	})
+
+	it('rethrows a generic error', async () => {
+		const consoleError = console.error
+		console.error = vi.fn()
+		const response = await request(app.callback()).get('/test/error/generic')
+		expect(response.status).toBe(500)
+		expect(response.text).toBe('Internal Server Error')
+		console.error = consoleError
+	})
+
+	it('handles an unauthorized error correctly', async () => {
+		const response = await request(app.callback()).get('/test/error/unauthorized')
+		expect(response.status).toBe(401)
+		expect(response.text).toBe(JSON.stringify({ status: 401, reason: 'Unauthorized', message: 'Test error' }))
+	})
+
+	it('handles a bad request error correctly', async () => {
+		const response = await request(app.callback()).get('/test/error/badrequest')
+		expect(response.status).toBe(400)
+		expect(response.text).toBe(JSON.stringify({ status: 400, reason: 'Bad Request', message: 'Test error' }))
+	})
+
+	it('handles bigint return value correctly', async () => {
+		const response = await request(app.callback()).get('/test/get/bigint')
+		expect(response.status).toBe(200)
+		expect(response.text).toBe(JSON.stringify({ foo: '100' }))
+	})
+
+	it('includes middleware data from context', async () => {
+		const response = await request(app.callback()).get('/test/get/middleware-data')
+		expect(response.status).toBe(200)
+		expect(response.text).toBe(JSON.stringify({ user: { id: '123' } }))
+	})
+})
+
+describe('OpenApiRouter', () => {
+	it('sends the openapi spec', async () => {
+		const response = await request(app.callback()).get('/api-json')
+		expect(response.status).toBe(200)
+		const responseJson = JSON.parse(response.text) as ReturnType<typeof generateOpenApiSpec>
+		expect(responseJson.openapi).toBe('3.1.0')
+		expect(responseJson.info).toEqual({
+			title: 'Test title',
+			version: '1.0.0',
+			description: 'Test description',
+			termsOfService: 'http://example.com',
+			contact: {
+				name: 'QA Engineer',
+				url: 'http://best-qa.com',
+				email: 'admin@best-qa.com',
+			},
+			license: {
+				name: 'MIT',
+				url: 'http://best-qa.com/license',
+			},
+		})
+		expect(responseJson.paths['/test/hello']).toEqual({
+			get: {
+				description: '',
+				parameters: [],
+				responses: {
+					'200': {
+						description: '',
+						content: {
+							'application/json': {
+								schema: {
+									oneOf: [
+										{
+											type: 'object',
+											properties: { greeting: { type: 'string' } },
+											required: ['greeting'],
+										},
+									],
+								},
+							},
+						},
+					},
+				},
+			},
+		})
+	})
+})

package/src/test/app.ts

@@ -0,0 +1,43 @@
+import Koa from 'koa'
+import bodyParser from 'koa-bodyparser'
+import { resolve } from 'path'
+
+import { HttpErrorHandler, initOpenApiEngine, useApiHeader as useRenamedApiHeader } from '..'
+import { TestAppRouter } from './TestAppRouter'
+
+export const app = new Koa()
+
+useRenamedApiHeader({
+	title: 'Test title',
+	version: '1.0.0',
+	description: 'Test description',
+	termsOfService: 'http://example.com',
+	contact: {
+		name: 'QA Engineer',
+		url: 'http://best-qa.com',
+		email: 'admin@best-qa.com',
+	},
+	license: {
+		name: 'MIT',
+		url: 'http://best-qa.com/license',
+	},
+})
+
+app
+	.use(HttpErrorHandler)
+	.use(
+		bodyParser({
+			enableTypes: ['text', 'json', 'form'],
+		})
+	)
+	.use(TestAppRouter.routes())
+	.use(TestAppRouter.allowedMethods())
+	.use(
+		initOpenApiEngine({
+			tsconfigPath: './tsconfig.json',
+			sourceFileDiscovery: {
+				rootPath: resolve(__dirname, '.'),
+			},
+			sourceFilePaths: ['./src/test/TestAppRouter.ts'],
+		})
+	)

package/src/utils/TypeUtils.ts

@@ -0,0 +1,51 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+export type RemoveFirstFromTuple<T extends any[]> = T['length'] extends 0
+	? undefined
+	: ((...b: T) => void) extends (a: infer Q, ...b: infer I) => void
+	? I
+	: []
+
+export type SplitStringBy<S extends string, D extends string> = string extends S
+	? string[]
+	: S extends ''
+	? []
+	: S extends `${infer T}${D}${infer U}`
+	? [T, ...SplitStringBy<U, D>]
+	: [S]
+
+type PickParams<S extends string[], P extends string> = S['length'] extends 0
+	? []
+	: S[0] extends `${P}${string}`
+	? // @ts-ignore
+	  [S[0], ...PickParams<RemoveFirstFromTuple<S>, P>]
+	: // @ts-ignore
+	  PickParams<RemoveFirstFromTuple<S>, P>
+
+export type Substring<S extends string[]> = S['length'] extends 0
+	? []
+	: // @ts-ignore
+	  [SplitStringBy<S[0], ':'>[1], ...Substring<RemoveFirstFromTuple<S>>]
+
+export type ExtractedRequestParams<S extends string> = {
+	parsedPathParams: PickParams<SplitStringBy<S, '/'>, ':'>
+}
+
+export type CamelCase<S extends string> = S extends `${infer P1}_${infer P2}${infer P3}`
+	? `${Lowercase<P1>}${Uppercase<P2>}${CamelCase<P3>}`
+	: S extends `${infer P1}-${infer P2}${infer P3}`
+	? `${Lowercase<P1>}${Uppercase<P2>}${CamelCase<P3>}`
+	: S
+
+export type KeysToCamelCase<T> = {
+	[K in keyof T as CamelCase<string & K>]: T[K] extends Record<any, any> ? KeysToCamelCase<T[K]> : T[K]
+}
+
+type RemoveLeadingColon<S extends string> = S['length'] extends 0 ? never : SplitStringBy<S, ':'>[1]
+type RemoveTrailingQuestion<S extends string> = S['length'] extends 0 ? never : SplitStringBy<S, '?'>[0]
+export type CleanUpPathParam<S> = S extends string
+	? //@ts-ignore
+	  RemoveLeadingColon<RemoveTrailingQuestion<S>> extends string
+		? //@ts-ignore
+		  RemoveLeadingColon<RemoveTrailingQuestion<S>>
+		: ''
+	: never