🚀 GG-Express

GG-Express is an Express.js wrapper that enforces strong type requirements for GET, POST, PUT, and DELETE methods. It ensures that req.query and req.body follow strict structure definitions and automatically generates an apiConnector class file for easy use in front-end development. 🎉🎉🎉

✨ Features

• Strict Type Enforcement: Ensures that req.query and req.body follow the declared types.
• Auto-Generated API Connector: Automatically creates a static API class for strongly-typed parameters.
• Seamless Front-End Integration: Simplifies the connection between the back-end and front-end by enforcing consistency.

🔑 Key Points

• Strict Parameter Enforcement: GG-Express ensures only the declared parameters are accessible in req.body or req.query.
• Type-Safe Responses: Ensures that the backend responds with a structure that matches front-end expectations.
• API Connector Generation: It automatically generates a type-safe API connector class file for the front-end.

🛠 Installation

npm install gg-express

🧑‍💻 Use Case in Backend

import express from "express"
import GGExpress from "gg-express"
const app = express()

// Initialize GG-Express with backend and frontend file paths
const ggapp = new GGExpress(app, [
  "./server/output-path-for-apiConnector.ts", // Path to generate apiConnector.ts backend file
  "./myapp/output-path-for-apiConnector.ts", // Path to generate apiConnector.ts frontend file
])

// Example of a POST request with enforced parameters
ggapp.post(
  "/api/item",
  {
    requireParams: {
      parameter: { lotNumber: "number" },
      dataType: "arrayObject",
      structure: {
        id: "number",
        name: "string",
        price: "number",
      },
    },
    responseStructure: {
      parameter: { numberOfPeople: "number", itemName: "string" },
      dataType: "arrayObject",
      structure: {
        id: "number",
        name: "string",
      },
    },
  },
  (req, res, next) => {
    // Access only the required parameters declared above
    const data = req.body.data

    // Response structure follows the predefined format
    return res.json({
      message: "",
      status: "SUCCESS",
      data: [],
      parameter: {
        itemName: "",
        numberOfPeople: 2,
      },
    })
  }
)

// Start the server and generate the API files
app.listen(3000, () => {
  ggapp.generateAPIFiles() // Generates the apiConnector class for front-end use
})

📲 Use Case in Frontend • The apiConnector.ts file will be automatically generated by the GGExpress class you configured in the backend

import GGApi from "apiConnector.ts"

const api = new GGApi()
const response = await api.post("/api/item", {
  parameter: {
    lotNumber: 2,
  },
  data: [
    {
      id: 1032,
      name: "machete",
      price: 4599,
    },
  ],
})
console.log(response.data)
// Expected data structure:
//  parameter: { numberOfPeople: number, itemName: string },
//       structure: {
//         id: number,
//         name: string,
//       }[],
// }

🔑 Keywords

• Express.js
• TypeScript
• API wrapper
• Type-safe API
• Backend-frontend integration

GGExpressV3 generation and migration

Use one canonical output directory for generated V3 files:

import path from "path"
import express from "express"
import { z } from "zod"
import GGExpressV3 from "gg-express"

const app = express()
const outputDirectory = path.resolve(
  process.cwd(),
  "../my-app/src/app/api/generated/v3",
)
const hrApi = new GGExpressV3<"hr", "/api/v3">(app, "hr", {
  outputDirectory,
})

hrApi.get(
  "/api/v3/hr/employees",
  {
    requireParams: { data: z.object({ active: z.boolean() }) },
    responseStructure: z.array(z.object({ id: z.number() })),
  },
  async (req, res) => {
    res.json({ data: [], message: "" })
  },
)

// Generate only the interface when the consumer uses one generic API client.
await hrApi.generateAPIFiles({ generateConnector: false })

Each GGExpressV3 instance owns its route registry. An hr instance generates only HR routes, while a separate hotel instance generates only Hotel routes. Routes must begin with /api/v3/<appName>/ by default. Supply urlPrefix in the constructor options for a different runtime prefix. Boundary checking can be temporarily disabled with enforceAppUrlBoundary: false during migration.

The legacy multiple-output constructor remains supported:

const hrApi = new GGExpressV3<"hr", "/api/v3">(app, "hr", [
  "./server/generated",
  "./frontend/generated",
])

Multiple directories are retained for backward compatibility. New projects should generate into one canonical directory to avoid duplicate generated files.

The legacy array constructor preserves its signature and multiple-output behavior only. URL boundary validation is enabled by default for both constructor forms, so an existing consumer that registers another app's URL can now fail during startup. Use the canonical options form with enforceAppUrlBoundary: false only as a temporary migration step while those routes are moved to the correct instance.

Migration note

V3 route interfaces no longer include routes registered through other GGExpressV3 instances. This can expose incorrect downstream usage that imported, for example, an HR interface while calling a Hotel path. Update that consumer to use the interface belonging to the correct app. Duplicate method-and-URL pairs within one instance now throw during registration, and generated URLs are sorted for deterministic output.

Request schema failures are now forwarded to Express error middleware with next(error). The route handler is not invoked for an invalid request. Applications should register an Express error-handling middleware after their routes. Valid requests continue to reach the route handler normally.