@openaddresses/batch-schema 9.3.0 → 10.0.0

package/.eslintrc.json

@@ -1,52 +1,10 @@
 {
-    "extends": "eslint:recommended",
+    "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+    "parser": "@typescript-eslint/parser",
+    "plugins": ["@typescript-eslint"],
     "root": true,
-    "env": {
-        "node": true
-    },
-    "globals": {
-        "Map": true,
-        "Promise": true
-    },
-    "parserOptions": {
-        "ecmaVersion": 13,
-        "sourceType": "module"
-    },
-    "plugins": [ "node" ],
     "rules": {
-        "no-console": 0,
-        "arrow-parens": [ "error", "always" ],
-        "no-var": "error",
-        "prefer-const": "error",
-        "array-bracket-spacing": [ "error", "never" ],
-        "comma-dangle": [ "error", "never" ],
-        "computed-property-spacing": [ "error", "never" ],
-        "eol-last": "error",
-        "eqeqeq": [ "error", "smart" ],
-        "indent": [ "error", 4, { "SwitchCase": 1 } ],
-        "no-confusing-arrow": [ "error", { "allowParens": false } ],
-        "no-extend-native": "error",
-        "no-mixed-spaces-and-tabs": "error",
-        "func-call-spacing": [ "error", "never" ],
-        "no-trailing-spaces": "error",
-        "no-unused-vars": "error",
-        "no-use-before-define": [ "error", "nofunc" ],
-        "object-curly-spacing": [ "error", "always" ],
-        "prefer-arrow-callback": "error",
-        "quotes": [ "error", "single", "avoid-escape" ],
-        "semi": [ "error", "always" ],
-        "space-infix-ops": "error",
-        "spaced-comment": [ "error", "always" ],
-        "keyword-spacing": [ "error", { "before": true, "after": true } ],
-        "template-curly-spacing": [ "error", "never" ],
-        "semi-spacing": "error",
-        "strict": "error",
-        "node/no-missing-require": "error",
-        "valid-jsdoc": ["error", {
-            "requireParamDescription": false,
-            "requireReturnDescription": false,
-            "requireReturnType": false,
-            "requireReturn": false
-        }]
+        "@typescript-eslint/ban-ts-comment": 1,
+        "@typescript-eslint/no-explicit-any": 1
     }
 }

package/.github/workflows/release.yml

@@ -9,13 +9,13 @@ jobs:
     build:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@v3
 
             - name: Get tag
               id: tag
               uses: dawidd6/action-get-tag@v1
 
-            - uses: actions/setup-node@v1
+            - uses: actions/setup-node@v4
               with:
                   node-version: 18
                   registry-url: https://registry.npmjs.org/
@@ -23,6 +23,9 @@ jobs:
             - name: npm install
               run: npm install
 
+            - name: npm build
+              run: npm run build
+
             - name: npm publish
               run: npm publish
               env:

package/CHANGELOG.md

@@ -10,6 +10,14 @@
 
 ## Version History
 
+### v10.0.0
+
+- :rocket: Very rough support for Typescript based routes
+
+### v9.4.0
+
+- :rocket: Add support for `private` key which will hide endpoint in swagger
+
 ### v9.3.0
 
 - :rocket: Coerce types on output

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 OpenAddresses
+Copyright (c) 2024 OpenAddresses
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 <h1 align=center>Batch-Schema</h1>
 
-<p align=center>Express Plugin for JSON Schema based routes</p>
+<p align=center>Express Plugin for [TypeBox](https://github.com/sinclairzx81/typebox) Request and Response Validation</p>
 
 ## Installation
 
@@ -11,13 +11,14 @@ npm i @openaddresses/batch-schema
 ## Example Usage
 
 ```js
-const path = require('path');
-const express = require('express');
-const { Schema } = require('@openaddresses/batch-schema');
+import express from 'express';
+import Schema from '@openaddresses/batch-schema';
+import { Type } from '@sinclair/typebox';
 
 const app = express();
 const schema = new Schema(express.Router(), {
-    schemas: path.resolve(__dirname, 'schemas')
+    logging: true,  // Enable Morgan Logging
+    limit: 50       // Body size for parsing JSON
 });
 
 app.use('/api', schema.router);
@@ -26,22 +27,25 @@ server();
 
 async function server() {
     await schema.post('/api/:param1/:param2', {
-        ':param1': 'integer',
-        ':param2': 'string',
-        query: 'query-json-schema.json',
-        body: 'body-json-schema.json',
-        res: 'result-body-json-schema.json'
+        query: Type.Object({
+            example: Type.Optional(Type.Uppercase(Type.String()))
+        }),
+        params: Type.Object({
+            param1: Type.String(),
+            param2: Type.Number(),
+        }),
+        body: Type.Object({
+            username: Type.String(),
+            password: Type.String(),
+        }),
+        res: Type.Object({
+            token: Type.String()
+        }),
     }, (req, res) => {
         return res.json({
-            note: 'I only return if the request meets the query & body schemas'
+            token: 'I only return if the request meets the query & body schemas'
         });
     });
-
-    // Handle Unmatched Routes
-    schema.not_found();
-
-    // Handle Validation Errors => JSON Middleware
-    schema.error();
 }
 ```
 

package/{routes/schema.js → lib/api.ts}

@@ -1,9 +1,15 @@
 import Err from '@openaddresses/batch-error';
+import Schema from './schema.js'
+import { OpenAPIV3 as Doc } from 'openapi-types'
+import { Type } from '@sinclair/typebox'
 
-export default async function router(schema) {
+export default async function router(schema: Schema) {
     await schema.get('/schema', {
-        query: 'req.query.ListSchema.json',
-        res: 'res.ListSchema.json',
+        query: Type.Object({
+            method: Type.Optional(Type.Uppercase(Type.Enum(Doc.HttpMethods))),
+            url: Type.Optional(Type.String())
+        }),
+        res: Type.Object({}),
         description: `
             List all JSON Schemas in use
             With no parameters this API will return a list of all the endpoints that have a form of schema validation
@@ -26,7 +32,8 @@ export default async function router(schema) {
     });
 
     await schema.get('/openapi', {
-        description: 'Return a OpenAPI Schema for the API'
+        description: 'Return a OpenAPI Schema for the API',
+        res: Type.Object({})
     }, async (req, res) => {
         try {
             return res.json(schema.docs.base);

package/lib/openapi.ts

@@ -0,0 +1,122 @@
+import { OpenAPIV3 as Doc } from 'openapi-types'
+import { RequestValidation } from './types.js';
+
+/**
+ * @class
+ */
+export default class Docs {
+    base: Doc.Document;
+
+    constructor(info?: {
+        title: string;
+        version: string;
+        [k: string]: string;
+    }) {
+        this.base = {
+            openapi: '3.0.3',
+            info: info || {
+                title: 'OpenAPI Schema',
+                version: '1.0.0'
+            },
+            paths: {}
+        };
+    }
+
+    push(
+        parsed: {
+            method: Doc.HttpMethods
+            path: string;
+        },
+        schemas: RequestValidation<any, any, any, any>
+    ): void {
+        const path: Array<string> = [];
+
+        for (let sec of parsed.path.split('/')) {
+            for (const lit of ['.', '-']) { // These chars are used literally and can't be part of a param name
+                const mini: Array<string> = [];
+                for (const s of sec.split(lit)) {
+                    if (s[0] === ':') mini.push(`{${s}}`);
+                    else mini.push(s);
+                }
+                sec = mini.join(lit);
+            }
+
+            path.push(sec);
+        }
+
+        const pathstr = path.join('/');
+
+        // @ts-ignore
+        if (this.base.paths[pathstr] && this.base.paths[pathstr][parsed.method]) throw new Error(`Duplicate Path: ${parsed.method}: ${parsed.path}`);
+
+        if (!schemas.private) {
+            if (!this.base.paths[pathstr]) this.base.paths[pathstr] = {};
+
+            const document: Doc.OperationObject = {
+                summary: schemas.description || 'No Description',
+                parameters: [],
+                tags: [schemas.group || 'Default'],
+                responses: {}
+            };
+
+            for (const key in schemas) {
+                if (key[0] === ':') {
+                    if (!document.parameters) document.parameters = [];
+                    document.parameters.push({
+                        in: 'path',
+                        name: key,
+                        schema: {
+                            type: schemas[key]
+                        },
+                        required: true
+                    });
+                }
+            }
+
+            if (schemas.query && schemas.query.type === 'object') {
+                for (const name in (schemas.query.properties || {})) {
+                    const query = schemas.query.properties[name];
+                    if (!document.parameters) document.parameters = [];
+                    document.parameters.push({
+                        in: 'query',
+                        name,
+                        schema: query,
+                        required: query.required || (schemas.query.required || []).includes(name),
+                        description: query.description || 'No Description'
+                    });
+                }
+            }
+
+            if (schemas.res) {
+                const response: Doc.ResponseObject =  {
+                    description: 'Successful Response',
+                    content: {
+                        'application/json': {
+                            schema: schemas.res
+                        }
+                    }
+                }
+                document.responses['200'] = response;
+            } else {
+                const response: Doc.ResponseObject =  {
+                    description: 'Successful Response'
+                }
+                document.responses['200'] = response;
+            }
+
+            if (schemas.body) {
+                document.requestBody = {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: schemas.body
+                        }
+                    }
+                };
+            }
+
+            // @ts-ignore
+            this.base.paths[pathstr][parsed.method] = document;
+        }
+    }
+}

package/lib/schema.ts

@@ -0,0 +1,293 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import morgan from 'morgan';
+import bodyparser from 'body-parser';
+import Err from '@openaddresses/batch-error';
+import { Static, TSchema } from '@sinclair/typebox';
+import { OpenAPIV3 as Doc } from 'openapi-types'
+import { Router, RequestHandler } from 'express'
+import { TypeCompiler } from '@sinclair/typebox/compiler';
+import type { ValueError } from '@sinclair/typebox/errors';
+import { RequestValidation } from './types.js';
+
+import SchemaAPI from './api.js';
+import Docs from './openapi.js';
+
+export type ErrorListItem = { type: 'Body' | 'Query' | 'Params'; errors: ValueError[] };
+
+/**
+ * @class
+ *
+ * @param {Object} router Express Router Object
+ * @param {Object} opts Options Object
+ * @param {boolean|string} [opts.morgan=true] disable logging with false
+ * @param {number} [opts.limit=50] body size limit in mb
+ *
+ * @param {URL} [opts.apidoc] apidoc file location
+ */
+export default class Schemas {
+    router: Router;
+    docs: Docs;
+    schemas: Map<string, RequestValidation<any, any, any, any>>
+
+    constructor(router: Router, opts: {
+        logging?: boolean;
+        limit?: number;
+    } = {}) {
+        if (!router) throw new Error('Router Param Required');
+
+        this.router = router;
+
+        if (opts.logging !== false) this.router.use(morgan('combined'));
+        this.router.use(bodyparser.urlencoded({ extended: true }));
+        this.router.use(bodyparser.json({ limit: `${opts.limit || 50}mb` }));
+
+        this.docs = new Docs();
+        this.schemas = new Map();
+    }
+
+    async api() {
+        await SchemaAPI(this);
+    }
+
+    /**
+     * Load routes directory. All .js files in the given directory will be loaded (ES Module)
+     * and the default method run
+     *
+     * @param {String}  dirpath     Directory to load
+     * @param {object}  config      Config Object
+     * @param {Object}  opts        Options Object
+     * @param {boolean} opts.silent     Squelch StdOut
+     */
+    async load<T>(dirpath: string | URL, config: T, opts: {
+        silent: boolean;
+    } = {
+        silent: false
+    }) {
+        if (dirpath instanceof URL) dirpath = dirpath.pathname;
+        else dirpath = String(dirpath);
+
+        const routes: Array<Promise<(schema: Schemas, config: T) => void>> = [];
+
+        // Load dynamic routes directory
+        for (const r of fs.readdirSync(dirpath)) {
+            if (!opts.silent) console.log(`ok - loaded routes/${r}`);
+            if (!['.ts', '.js'].includes(path.parse(r).ext)) continue;
+            routes.push((await import(path.resolve(dirpath, r))).default(this, config));
+        }
+
+        await Promise.all(routes);
+
+        this.not_found();
+    }
+
+    /**
+     * Load a blueprint into the router
+     *
+     * @param {Object}  bp_class    Blueprint Class with blueprint() fn
+     * @param {object}  config      Config Object
+     * @param {Object}  opts        Options Object
+     * @param {boolean} opts.silent     Squelch StdOut
+     */
+    async blueprint<T>(bp_class, config?: T, opts: {
+        silent: boolean;
+    } = { silent: false }) {
+        if (!opts.silent) console.log(`ok - loaded ${bp_class.name}`);
+        await bp_class.blueprint(this, config);
+    }
+
+    async get<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
+        path: string,
+        opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
+        handler: RequestHandler<Static<TParams>, any, Static<TBody>, Static<TQuery>>
+    ) {
+        try {
+            this.docs.push({ method: Doc.HttpMethods.GET, path: path }, opts);
+            this.schemas.set(`GET ${path}`, opts);
+
+            const paramsValidation = opts.params && TypeCompiler.Compile(opts.params);
+            const queryValidation = opts.query && TypeCompiler.Compile(opts.query);
+            if (opts.body) throw new Error(`Body not allowed`);
+
+            const _handler: RequestHandler = (req, res, next) => {
+                const errors: Array<ErrorListItem> = [];
+                if (paramsValidation && !paramsValidation.Check(req.params)) errors.push({ type: 'Params', errors: Array.from(paramsValidation.Errors(req.params)) });
+                if (queryValidation && !queryValidation.Check(req.query)) errors.push({ type: 'Query', errors: Array.from(queryValidation.Errors(req.query)) });
+                if (errors.length) return Err.respond(new Err(400, null, 'Validation Error'), res, errors);
+
+                return handler(req, res, next);
+            };
+
+            this.router.get(path, _handler);
+        } catch (err) {
+            throw new Error(`Get: ${path}: ` + err)
+        }
+    }
+
+    async delete<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
+        path: string,
+        opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
+        handler: RequestHandler<Static<TParams>, any, Static<TBody>, Static<TQuery>>
+    ) {
+        try {
+            this.docs.push({ method: Doc.HttpMethods.DELETE, path: path }, opts);
+            this.schemas.set(`DELETE ${path}`, opts);
+
+            const paramsValidation = opts.params && TypeCompiler.Compile(opts.params);
+            const queryValidation = opts.query && TypeCompiler.Compile(opts.query);
+            if (opts.body) throw new Error(`Body not allowed`);
+
+            const _handler: RequestHandler = (req, res, next) => {
+                const errors: Array<ErrorListItem> = [];
+                if (paramsValidation && !paramsValidation.Check(req.params)) errors.push({ type: 'Params', errors: Array.from(paramsValidation.Errors(req.params)) });
+                if (queryValidation && !queryValidation.Check(req.query)) errors.push({ type: 'Query', errors: Array.from(queryValidation.Errors(req.query)) });
+                if (errors.length) return Err.respond(new Err(400, null, 'Validation Error'), res, errors);
+
+                return handler(req, res, next);
+            };
+
+            this.router.get(path, _handler);
+        } catch (err) {
+            throw new Error(`Delete: ${path}: ` + String(err))
+        }
+    }
+
+    async post<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
+        path: string,
+        opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
+        handler: RequestHandler<Static<TParams>, any, Static<TBody>, Static<TQuery>>
+    ) {
+        try {
+            this.docs.push({ method: Doc.HttpMethods.POST, path: path }, opts);
+            this.schemas.set(`POST ${path}`, opts);
+
+            const paramsValidation = opts.params && TypeCompiler.Compile(opts.params);
+            const queryValidation = opts.query && TypeCompiler.Compile(opts.query);
+            const bodyValidation = opts.body && TypeCompiler.Compile(opts.body);
+
+            const _handler: RequestHandler = (req, res, next) => {
+                const errors: Array<ErrorListItem> = [];
+                if (paramsValidation && !paramsValidation.Check(req.params)) errors.push({ type: 'Params', errors: Array.from(paramsValidation.Errors(req.params)) });
+                if (queryValidation && !queryValidation.Check(req.query)) errors.push({ type: 'Query', errors: Array.from(queryValidation.Errors(req.query)) });
+                if (bodyValidation && !bodyValidation.Check(req.body)) errors.push({ type: 'Body', errors: Array.from(bodyValidation.Errors(req.body)) });
+                if (errors.length) return Err.respond(new Err(400, null, 'Validation Error'), res, errors);
+
+                return handler(req, res, next);
+            };
+
+            this.router.get(path, _handler);
+        } catch (err) {
+            throw new Error(`Post: ${path}: ` + String(err))
+        }
+    }
+
+    async patch<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
+        path: string,
+        opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
+        handler: RequestHandler<Static<TParams>, any, Static<TBody>, Static<TQuery>>
+    ) {
+        try {
+            this.docs.push({ method: Doc.HttpMethods.PATCH, path: path }, opts);
+            this.schemas.set(`PATCH ${path}`, opts);
+
+            const paramsValidation = opts.params && TypeCompiler.Compile(opts.params);
+            const queryValidation = opts.query && TypeCompiler.Compile(opts.query);
+            const bodyValidation = opts.body && TypeCompiler.Compile(opts.body);
+
+            const _handler: RequestHandler = (req, res, next) => {
+                const errors: Array<ErrorListItem> = [];
+                if (paramsValidation && !paramsValidation.Check(req.params)) errors.push({ type: 'Params', errors: Array.from(paramsValidation.Errors(req.params)) });
+                if (queryValidation && !queryValidation.Check(req.query)) errors.push({ type: 'Query', errors: Array.from(queryValidation.Errors(req.query)) });
+                if (bodyValidation && !bodyValidation.Check(req.body)) errors.push({ type: 'Body', errors: Array.from(bodyValidation.Errors(req.body)) });
+                if (errors.length) return Err.respond(new Err(400, null, 'Validation Error'), res, errors);
+
+                return handler(req, res, next);
+            };
+
+            this.router.get(path, _handler);
+        } catch (err) {
+            throw new Error(`Patch: ${path}: ` + String(err))
+        }
+    }
+
+    async put<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema, TResponse extends TSchema>(
+        path: string,
+        opts: RequestValidation<TParams, TQuery, TBody, TResponse> = {},
+        handler: RequestHandler<Static<TParams>, any, Static<TBody>, Static<TQuery>>
+    ) {
+        try {
+            this.docs.push({ method: Doc.HttpMethods.PUT, path: path }, opts);
+            this.schemas.set(`PUT ${path}`, opts);
+
+            const paramsValidation = opts.params && TypeCompiler.Compile(opts.params);
+            const queryValidation = opts.query && TypeCompiler.Compile(opts.query);
+            const bodyValidation = opts.body && TypeCompiler.Compile(opts.body);
+
+            const _handler: RequestHandler = (req, res, next) => {
+                const errors: Array<ErrorListItem> = [];
+                if (paramsValidation && !paramsValidation.Check(req.params)) errors.push({ type: 'Params', errors: Array.from(paramsValidation.Errors(req.params)) });
+                if (queryValidation && !queryValidation.Check(req.query)) errors.push({ type: 'Query', errors: Array.from(queryValidation.Errors(req.query)) });
+                if (bodyValidation && !bodyValidation.Check(req.body)) errors.push({ type: 'Body', errors: Array.from(bodyValidation.Errors(req.body)) });
+                if (errors.length) return Err.respond(new Err(400, null, 'Validation Error'), res, errors);
+
+                return handler(req, res, next);
+            };
+
+            this.router.get(path, _handler);
+        } catch (err) {
+            throw new Error(`Put: ${path}: ` + String(err))
+        }
+    }
+
+    not_found() {
+        this.router.all('*', (req, res) => {
+            return res.status(404).json({
+                status: 404,
+                message: 'API endpoint does not exist!',
+                messages: []
+            });
+        });
+    }
+
+
+    query(method: Doc.HttpMethods, url: string): {
+        query?: object;
+        body?: object;
+        res?: object;
+    } {
+        if (!this.schemas.has(`${method} ${url}`)) {
+            return {};
+        }
+
+        const schema = JSON.parse(JSON.stringify(this.schemas.get(`${method} ${url}`)));
+
+        return {
+            query: schema.query,
+            body: schema.body,
+            res: schema.res
+        };
+    }
+
+    list(): {
+        [k: string]: {
+            body: boolean;
+            query: boolean;
+            res: boolean;
+        }
+    } {
+        const lite = {};
+
+        for (const key of this.schemas.keys()) {
+            const schema = this.schemas.get(key);
+            if (!schema) continue;
+
+            lite[key] = {
+                body: !!schema.body,
+                query: !!schema.query,
+                res: !!schema.res
+            };
+        }
+
+        return lite;
+    }
+}

package/lib/types.ts

@@ -0,0 +1,32 @@
+import { Static, TSchema } from '@sinclair/typebox';
+import type { Request } from 'express';
+import type { ParamsDictionary } from 'express-serve-static-core';
+
+export type TypedRequest<TParams extends TSchema, TQuery extends TSchema, TBody extends TSchema> = Request<
+  Static<TParams>,
+  any,
+  Static<TBody>,
+  Static<TQuery>
+>;
+
+export type TypedRequestBody<TBody extends TSchema> = Request<ParamsDictionary, any, Static<TBody>, any>;
+export type TypedRequestParams<TParams extends TSchema> = Request<Static<TParams>, any, any, any>;
+export type TypedRequestQuery<TQuery extends TSchema> = Request<ParamsDictionary, any, any, Static<TQuery>>;
+
+export type TypedResponseBody<TResponse extends TSchema> = Static<TResponse>;
+
+export type RequestValidation<
+    TParams extends TSchema,
+    TQuery extends TSchema,
+    TBody extends TSchema,
+    TResponse extends TSchema
+> = {
+  private?: boolean;
+  name?: string;
+  group?: string;
+  description?: string;
+  params?: TParams;
+  query?: TQuery;
+  body?: TBody;
+  res?: TResponse
+};