@openaddresses/batch-schema 9.4.0 → 10.0.1

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
+};

package/package.json

@@ -3,7 +3,7 @@
     "type": "module",
     "root": true,
     "main": "index.js",
-    "version": "9.4.0",
+    "version": "10.0.1",
     "description": "Strongly Validated JSON Schema support for address",
     "repository": "git@github.com:openaddresses/batch-schema",
     "author": "ingalls <nick@ingalls.ca>",
@@ -13,28 +13,33 @@
         "node": ">= 18"
     },
     "scripts": {
-        "test": "tape test/**.test.js",
-        "lint": "eslint index.js lib/**.js routes/**.js test/**.js",
-        "doc": "documentation build index.js -f html -o docs && documentation lint index.js"
+        "test": "ts-node-test test/**.test.ts",
+        "lint": "eslint index.ts lib/**.ts test/**.ts",
+        "build": "tsc",
+        "doc": "typedoc"
     },
     "dependencies": {
-        "@apidevtools/json-schema-ref-parser": "^10.0.0",
         "@openaddresses/batch-error": "^2.1.2",
-        "ajv": "^8.6.3",
-        "ajv-formats": "^2.1.1",
+        "@sinclair/typebox": "^0.32.14",
+        "@types/body-parser": "^1.19.5",
         "body-parser": "^1.20.0",
         "express": "^4.17.1",
-        "express-json-validator-middleware": "^3.0.0",
         "glob": "^10.0.0",
-        "morgan": "^1.10.0"
+        "morgan": "^1.10.0",
+        "openapi-types": "^12.1.3"
     },
     "peerDependencies": {
         "@openaddresses/batch-generic": "x.x.x"
     },
     "devDependencies": {
-        "documentation": "^14.0.1",
+        "@types/express": "^4.17.21",
+        "@typescript-eslint/eslint-plugin": "^7.0.1",
+        "@typescript-eslint/parser": "^7.0.1",
         "eslint": "^8.0.1",
         "eslint-plugin-node": "^11.0.0",
-        "tape": "^5.3.1"
+        "tape": "^5.3.1",
+        "ts-node-test": "^0.4.3",
+        "typedoc": "^0.25.8",
+        "typescript": "^5.3.3"
     }
 }

package/test/{schema.srv.test.js → schema.srv.test.ts}

@@ -3,20 +3,15 @@ import express from 'express';
 import Schema from '../index.js';
 
 const app = express();
-const schema = new Schema(express.Router(), {
-    api: true
-});
+const schema = new Schema(express.Router());
 
 app.use('/api', schema.router);
 
-let server = false;
+let server;
 
 test('start', (t) => {
-    server = app.listen(2000, async (err) => {
+    server = app.listen(2000, async () => {
         await schema.api();
-        schema.error();
-
-        t.error(err, 'no errors');
         t.end();
     });
 });
@@ -35,7 +30,7 @@ test('GET: api/schema', async (t) => {
             'GET /openapi': {
                 body: false,
                 query: false,
-                res: false
+                res: true
             }
         });
     } catch (err) {
@@ -53,16 +48,10 @@ test('GET: api/schema?method=FAKE', async (t) => {
 
         t.deepEquals(await res.json(), {
             status: 400,
-            message: 'validation error',
-            messages: [{
-                keyword: 'enum',
-                instancePath: '/method',
-                schemaPath: '#/properties/method/enum',
-                params: {
-                    allowedValues: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'CONNECT', 'OPTIONS', 'TRACE', 'PATCH']
-                },
-                message: 'must be equal to one of the allowed values'
-            }]
+            message: 'Validation Error',
+            messages: [
+                {"type":"Query","errors":[{"type":62,"schema":{"anyOf":[{"const":"GET","type":"string"},{"const":"PUT","type":"string"},{"const":"POST","type":"string"},{"const":"DELETE","type":"string"},{"const":"OPTIONS","type":"string"},{"const":"HEAD","type":"string"},{"const":"PATCH","type":"string"},{"const":"TRACE","type":"string"}]},"path":"/method","value":"fake","message":"Expected union value"}]}
+            ]
         });
     } catch (err) {
         t.error(err);
@@ -107,7 +96,7 @@ test('GET: api/schema?method=GET&url=/schema', async (t) => {
         const res = await fetch('http://localhost:2000/api/schema?method=GET&url=/schema');
 
         t.equals(res.status, 200, 'http: 200');
-        t.deepEquals(Object.keys(await res.json()).sort(), ['query', 'body', 'res'].sort());
+        t.deepEquals(Object.keys(await res.json()).sort(), ['query', 'res'].sort());
 
     } catch (err) {
         t.error(err, 'no error');

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+    "ts-node": {
+        "esm": true
+    },
+    "compilerOptions": {
+        "strict": true,
+        "skipLibCheck": true,
+        "module": "es2022",
+        "target": "es2022",
+        "esModuleInterop": true,
+        "noImplicitAny": false,
+        "moduleResolution": "node",
+        "sourceMap": true,
+        "outDir": "dist",
+        "baseUrl": ".",
+        "paths": {
+            "*": [
+                "node_modules/*"
+            ]
+        }
+    },
+    "include": [
+        "index.ts",
+        "lib/**.ts",
+        "test/**.ts"
+    ]
+}