SkimX

A Typescript library that use express and zod schemas to create web application and generate OpenAPI specification.

Install

Install via npm:

1npm install skimx

Usage

Server

Creates a Server that wraps an express instance

1import { Server } from 'skimx';
2
3const server = new Server();

.use()

Attach middlewares and/or handlers to the express instance.

1server.use(cors(), helmet());

You can also specify a custom error handler. For example:

1import { Request, Response, NextFunction } from 'express';
2
3const errorHandler = (
4  error: unknown,
5  req: Request,
6  res: Response,
7  next: NextFunction,
8) => {
9  console.log(error.message);
10  return res.status(500).json({ message: error.message });
11};
12
13server.use(errorHandler); // make sure that is is the last handler

.useRouters()

Attach a Router instance to the server.

1import { Server, Router } from 'skimx';
2
3const server = new Server();
4const router1 = new Router();
5const router2 = new Router();
6
7server.useRouters(router1, router2);

.listen()

Start the server on the given port.

1server.listen(3000, () => {
2  console.log('server is listening on port 3000');
3});

.close()

Stops the server from accepting new connections and keeps existing connections.

1server.close((error) => {
2  if (error) {
3    console.log(error.message);
4  }
5});

Router

Creates a Router that extends an express router with a schema.

Info: The Zod .openapi() extension is used to attach information to Zod schema using zod-openapi library.

1import { Router, z } from 'skimx';
2
3const router = new Router();
4
5const TodoSchema = z.object({
6  id: z.number(),
7  description: z.string(),
8});
9
10router.get(
11  '/v1/todos',
12  {
13    responses: {
14      200: {
15        description: 'A list of todos',
16        applicationJson: z.array(TodoSchema),
17      },
18    },
19  },
20  [], // middlewares
21  async (req, res, next) => {
22    const todos = await fetchTodos();
23    res.status(200).json(todos);
24  },
25);

The schema is an object that is used to:

• infer req.params, req.query and req.body types using Zod (z.infer)
• validates an incoming request using Zod schemas
• generates an OpenAPI specification for each route

Route middlewares and handlers

Sometimes a middleware (for example for a third party package) expects as input a request that needs to satisfy the Request express type.

If a route specify a request schema that does not satisfy the Request type, the typescript compiler gives you an error.

That's why a route can take as input an array of middlewares, where they don't need an inferred request type from the specified schema.

In this case, you have the flexibility to define handlers that needs to satisfy the Request object inside the middlewares array or you can specify them down below:

1router.post(
2  '/',
3  {
4    // req.query type is inferred from this property
5    // req.query.id is a number
6    query: z.object({ id: z.coerce.number() }),
7  },
8  // express cors middleware does not expect that req.query args are numbers
9  [cors()],
10  // multiple handlers that expect req.query.id to be a number
11  (req, res, next) => {
12    console.log(req.query);
13    next();
14  },
15  (req, res, next) => {
16    res.json({});
17  },
18);

.get()

Attach an endpoint with GET method to the router

1import { Router, z } from 'skimx';
2
3const router = new Router();
4
5const TodoSchema = z.object({
6  id: z.number(),
7  description: z.string(),
8});
9
10router.get(
11  '/v1/todos/:param',
12  {
13    // Specify the schema for req.params
14    params: z.object({ param: z.string() }),
15    // Specify the schema for req.query
16    query: z.object({ name: z.string() }),
17    // Specify the schema for req.headers
18    headers: z.object({ Authorization: z.string() }),
19    // Specify the schema for response
20    responses: {
21      200: {
22        description: 'A list of todos',
23        applicationJson: z.array(TodoSchema),
24      },
25    },
26  },
27  [], // middlewares
28  (req, res, next) => {
29    /* your code here */
30  },
31);

.post()

Attach an endpoint with POST method to the router

1import { Router, z } from 'skimx';
2
3const router = new Router();
4
5const TodoSchema = z.object({
6  id: z.number(),
7  description: z.string(),
8});
9
10router.post(
11  '/v1/todos/',
12  {
13    // Specify the schema for req.params
14    body: {
15      applicationJson: TodoSchema,
16    },
17    responses: {
18      201: {
19        description: 'The created todo',
20        applicationJson: TodoSchema,
21      },
22    },
23  },
24  [], // middlewares
25  (req, res, next) => {
26    /* your code here */
27  },
28);

generate

Generate OpenAPI specification.

1import { Server, generate } from 'skimx';
2
3const server = new Server();
4
5const schema = {
6  info: {
7    title: 'my spec',
8    version: '1.0.0',
9  },
10};
11
12// .....
13
14// Returns an object
15const spec = generateSpec({ schema, server });

write

Generate and write the specification to a file:

1import { Server, write } from 'skimx';
2
3const server = new Server();
4
5const schema = {
6  info: {
7    title: 'my spec',
8    version: '1.0.0',
9  },
10};
11
12// .....
13
14// Writes a file to the root of the project
15write({ schema, server, filename: 'openapi.yaml', format: 'yaml' });

Caveats

• Right now SkimX supports only OpenAPI version 3.1.0

Contributing

Contributions to SkimX are welcome! Whether it's bug reports, feature requests, or code contributions, please feel free to make your input.

License

SkimX is licensed under the MIT License.

Support

If you have any questions or encounter issues with SkimX, please open an issue on the GitHub repository. Our team will be happy to assist you.