Mongoose TypeScript Converter

Description

Mongoose TypeScript Converter is a lightweight Node.js library designed to simplify Mongoose-to-TypeScript schema conversions. It allows developers to automatically generate TypeScript interfaces from Mongoose schemas, ensuring type safety and saving development time.

Features

• Converts Mongoose schemas to TypeScript interfaces
• Supports complex data types, including nested objects and arrays
• CLI support for easy integration in projects
• Option to start a documentation server to view generated types
• Middleware support for serving documentation in an existing Express app

Installation

Install the package via npm:

npm install mongoose-ts-converter

Or with yarn:

yarn add mongoose-ts-converter

Usage

Programmatic API

const { convertToTS } = require("mongoose-ts-converter")
const mongoose = require("mongoose")

const schema = new mongoose.Schema({
  username: { type: String, required: true },
  email: { type: String, required: true },
})

convertToTS(schema, "User").then((tsInterface) => {
  console.log(tsInterface)
})

CLI Usage

Run the following command to generate TypeScript interfaces from Mongoose models in your project:

npx mongoose-ts-converter --models ./path/to/models --output ./path/to/output

CLI Options

-m, --models <dir> - Directory containing your Mongoose model files
-o, --output <dir> - Directory to output the generated TypeScript files
--serve              Start a documentation server after generating schemas
--port <number>      Specify the port for the documentation server (default: 3000)

Example

Given a Mongoose model in the models directory:

// models/User.js
const mongoose = require("mongoose")

const userSchema = new mongoose.Schema({
  username: { type: String, required: true },
  email: { type: String, required: true },
})

module.exports = mongoose.model("User", userSchema)

Running the CLI will generate a TypeScript file in the output directory:

// output/User.d.ts
export interface User {
  username: string
  email: string
}

Starting the Documentation Server

To start a documentation server that serves the generated TypeScript schemas, add the --serve option:

npx mongoose-ts-converter --models ./path/to/models --output ./path/to/output --serve

Specify a custom port for the documentation server (default is 3000):

npx mongoose-ts-converter --models ./path/to/models --output ./path/to/output --serve --port 4000

After running the command, open your browser and go to:

http://localhost:<specified-port>

Use as Middleware

If you want to serve the documentation for generated TypeScript schemas as part of an existing Express application, you can use the docsRouter middleware:

Setup

1. First, generate the TypeScript schemas using either the CLI or convertToTS function and specify the output directory.
2. Include docsRouter from mongoose-ts-converter in your Express app, specifying the directory where the generated TypeScript files are stored.

Example

// app.js
const express = require("express");
const { docsRouter } = require("mongoose-ts-converter");

const app = express();
const PORT = 3000;

// Serve TypeScript documentation
app.use("/api-docs", docsRouter("./path/to/output"));

app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

In this setup

• Replace ./path/to/output with the actual path to the directory where TypeScript files are generated.
• Access your documentation at http://localhost:3000/api-docs.

JSON API for Schema Documentation

The createDocsRouter middleware also provides a JSON endpoint, which can be useful for frontend applications that need to access schema documentation programmatically.

JSON Endpoint

Once configured, the following endpoint will be available:

• GET /api-docs/json: Returns a JSON array of objects, each representing a TypeScript schema file with its filename (without extension) and content.

Example JSON Response

{
  "schemas": [
    {
      "file": "User",
      "content": "export interface User { username: string; email: string; }"
    },
    {
      "file": "Product",
      "content": "export interface Product { name: string; price: number; }"
    }
  ]
}

Frontend Integration

With this JSON API, you can easily fetch and display the generated TypeScript schemas on a frontend application or another service, enabling seamless access to your documentation.

License

This project is licensed under the MIT License.

Contact

For issues, questions, or contributions, please reach out to [email protected]