Smart architecture for handling Types, Models and Schemas with TS and OAS3

[benediktdertinger]

UPDATE: TL;DR

1. How to reduce efforts in writing Mongoose models and then transforming them to Typescript types (for mongoose documents and pure types) and to schemas for validation and serialization?
2. How can we achieve OAS3 compatibility?
3. How to deal with types that differ for backend, frontend and shared usage?
   --> This article (5. Splitting the user model into backend and frontend representations) was helpful.

---

Hello everyone,

we are currently migrating huge APIs from Fastify 2.x to 3.x. While refactoring major parts we decided to us an feature-base architecture (e.g. user routes, services etc. in one folder) instead of separating by type (like controllers, services etc.).

src/user
  index.ts
  routes.ts
  service.ts

While doing so we realized we also have to put a lot of effort in writing pretty similar logic and structures for these things:

// Mongoose Schema & Model
const UserSchema = new mongoose.Schema<User>({
  firstName: {
    type: String,
  },
  password: {
    type: String,
    select: false,
  },
});

// User Interface
export interface UserType {
  firstName: string;
  password: string;
}

// User Interface Document (typing for usage after DB queries)
export interface User extends UserType, Document {}

// User Interface for responses of serialized objects (e.g. no password included and using `user.toJSON()`)
export interface UserObject {
  firstName: string;
}

// Route & Schemas
const userCreateSchema = {
    body: {
        tags: ['User'],
        summary: 'Create a new user',
        type: 'object',
        properties: {
            firstName: {
                type: 'string',
            },
            password: {
                type: 'string',
            },
        },
        required: ['firstName', 'password'],
    },
    response: {
        200: {
            description: 'Successful response',
            type: 'object',
            properties: {
                success: {type: 'boolean'},
                data: {
                    type: 'object',
                    properties: {
                      firstName: {
                          type: 'string',
                      },
                      // No password here
                    },
                },
            },
        },
    },
};
fastify.post<{ Body: User }>('/users', { schema: userCreateSchema }, async (req, reply) => userHandler.create(req.body.user));

Ideally these should be compatible with Open API Specification 3 (fastify-oas) in the end (which is working quite well when writing all the schemas).

There are some helpers like fluent-schema or json-schema-to-typescript but they all are limited in some way. JSON Schema for example does not allow for using variables (obviously) but is needed to create TS Types.

Before discussing detailed questions I was just wondering if there are already recommended workflows and architectures (besides the ones mentioned) to reduce efforts?

[Ethan-Arrowood]

Another tool you can try is typebox not sure if it exactly addresses your use case but is another really sweet tool for this kind of problem

[benediktdertinger]

Hi @Ethan-Arrowood,

thank you for pointing me in this direction <3

I added an Update section to understand the main aspects quicker.

1. I checked on wether typebox could be a suitable solution: It seems pretty promising for creating schemas but I was not able to add all the complexity needed for the Mongoose models. I therefore believe that we have to start by defining the Mongoose models and transform them into needed types and schemas.
   There are some options like mongoose-schema-jsonschema but typebox requires to use its own definition in the first place. Other options are outdated. Another option could be using mongoose-tsgen to create types from Mongoose models and this package (last publish 4 years ago) mongoose-jsonschema to create schemas.
2. Everything should be OAS compatible as long as we use schemas.
3. Regarding the different types needed for backend and frontend I found this article (5. Splitting the user model into backend and frontend representations) pretty helpful. I mean we did it pretty much the same way but it might help others (and they added some nice other tips).

Do you have any other ideas?

[jonvaljonathan]

hey @benediktdertinger did you ever find a solution to this problem?

[benediktdertinger]

We haven't found a more convenient solution yet to automate the process of creating json schemas and sharing types between backend and frontend (except for mono repos). But in general i found it to be very helpful to be as generic as possible and create base types and generics you can reuse and add together wherever needed.

// Combine types
export type ListingDefaultParams = OrderParam &
  PaginationParams;

// Schemas:
export const listingDefaultSchema = {
  type: 'object',
  properties: {
    ...orderDefaultSchema.properties,
    ...paginationDefaultSchema.properties,
  },
};

export const projectListSchema = {
  type: 'object',
  properties: {
    ...listingDefaultSchema.properties,
    ...distancesSchema.properties,
  },
};

[jonvaljonathan]

Thank you! I will look into both Typegoose and Prisma. This was very helpful!

[dphov]

@benediktdertinger Have you found the solution? I'm interested in this topic :)

[jonvaljonathan]

found

We use Typegoose now. Works well just watch-out for circular dependencies when setting it up!

[benediktdertinger]

@dphov we are using Typegoose as well and our process is pretty straight forward here (except for automatic creation of the json schemas).

[mcollina]

Don't use Mongoose. You are doing a relational model on top of a non-relational database.