feat(openapi-generators): migrate generator to a dedicated package MAPCO-9759

.release-please-manifest.json

@@ -9,6 +9,7 @@
   "packages/js-logger": "5.0.0",
   "packages/read-pkg": "2.0.0",
   "packages/openapi-express-viewer": "4.1.0",
+  "packages/openapi-generators": "0.1.0",
   "packages/openapi-helpers": "5.1.0",
   "packages/openapi-typed-request-handler": "0.1.0",
   "packages/openapi-typed-request-sender": "0.1.0",

.vscode/project.code-workspace

@@ -48,14 +48,18 @@
       "name": "openapi-express-viewer",
       "path": "../packages/openapi-express-viewer",
     },
-    {
-      "name": "openapi-helpers",
-      "path": "../packages/openapi-helpers",
-    },
     {
       "name": "openapi-typed-request-handler",
       "path": "../packages/openapi-typed-request-handler",
     },
+    {
+      "name": "openapi-typed-request-sender",
+      "path": "../packages/openapi-typed-request-sender",
+    },
+    {
+      "name": "openapi-generators",
+      "path": "../packages/openapi-generators",
+    },
     {
       "name": "semantic-conventions",
       "path": "../packages/semantic-conventions",

packages/openapi-generators/README.md

@@ -0,0 +1,53 @@
+# openapi-generators
+
+CLI and programmatic API for generating TypeScript types and error classes from OpenAPI specifications.
+
+## Installation
+
+```bash
+npm install --save-dev @map-colonies/openapi-generators openapi-typescript prettier
+```
+
+## CLI Usage
+
+```bash
+npx openapi-generators generate types <openapi-file> <output-file> [options]
+npx openapi-generators generate errors <openapi-file> <output-file> [options]
+```
+
+### Generate Types
+
+Generate TypeScript types from an OpenAPI schema:
+
+```bash
+npx openapi-generators generate types ./openapi.yaml ./src/types.d.ts --format --add-typed-request-handler
+```
+
+Options:
+
+- `-f, --format`: Format the generated types using `prettier`.
+- `-t, --add-typed-request-handler`: Add the `TypedRequestHandlers` type to the generated types. This requires `@map-colonies/openapi-typed-request-handler` to be installed in the project.
+
+### Generate Errors
+
+Generate error classes and error code mappings from an OpenAPI schema:
+
+```bash
+npx openapi-generators generate errors ./openapi.yaml ./src/errors.ts --format
+```
+
+Options:
+
+- `-f, --format`: Format the generated code using `prettier`.
+- `-e, --errors-output <all|map|classes>`: Specify what to generate (default: `all`).
+
+## Programmatic Usage
+
+```typescript
+import { generateTypes, generateErrors } from '@map-colonies/openapi-generators';
+
+await generateTypes('openapi.yaml', 'src/types.d.ts', {
+  shouldFormat: true,
+  addTypedRequestHandler: true,
+});
+```

packages/openapi-helpers/api-extractor.generators.json → packages/openapi-generators/api-extractor.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
   "extends": "../../api-extractor.json",
-  "mainEntryPointFilePath": "dist/generator/index.d.ts",
+  "mainEntryPointFilePath": "dist/index.d.ts",
   "apiReport": {
     "enabled": true,
-    "reportFileName": "generators.<unscopedPackageName>"
+    "reportFileName": "openapi-generators.api.md"
   }
 }

packages/openapi-helpers/package.json → packages/openapi-generators/package.json

@@ -1,12 +1,12 @@
 {
-  "name": "@map-colonies/openapi-helpers",
-  "version": "5.1.0",
-  "description": "A package that provides utilities for working with openapi files",
-  "type": "commonjs",
+  "name": "@map-colonies/openapi-generators",
+  "version": "0.1.0",
+  "description": "CLI and programmatic API for code generation from OpenAPI specifications",
+  "type": "module",
   "exports": {
-    "./generators": {
-      "types": "./dist/generator/index.d.ts",
-      "default": "./dist/generator/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "bin": "./dist/cli/entrypoint.mjs",
@@ -19,11 +19,9 @@
     "clean": "rimraf dist",
     "prepack": "turbo run build",
     "check-dist": "publint && attw --profile node16 --pack .",
-    "knip": "knip --directory ../.. --workspace packages/openapi-helpers",
-    "api:check": "pnpm run generators:api:check",
-    "generators:api": "api-extractor run --local --verbose --config ./api-extractor.generators.json",
-    "generators:api:check": "api-extractor run --verbose --config ./api-extractor.generators.json",
-    "generate:test:types": "pnpm run build && node dist/generator/generateTypes.mjs tests/openapi3.yaml tests/types.d.ts"
+    "knip": "knip --directory ../.. --workspace packages/openapi-generators",
+    "api:check": "api-extractor run --verbose --config ./api-extractor.json",
+    "api": "api-extractor run --local --verbose --config ./api-extractor.json"
   },
   "repository": "github:MapColonies/infra-packages",
   "files": [
@@ -43,29 +41,23 @@
     "commander": "^15.0.0",
     "oas-normalize": "^15.0.0",
     "ora": "^9.0.0",
-    "ts-essentials": "^10.1.1",
     "yaml": "^2.8.0"
   },
   "peerDependencies": {
-    "@types/express": "^4.17.21",
     "openapi-typescript": "^7.4.1",
-    "prettier": "^3.3.3",
-    "supertest": "^7.0.0"
+    "prettier": "^3.3.3"
   },
   "devDependencies": {
     "@map-colonies/eslint-config": "workspace:^",
     "@map-colonies/tsconfig": "workspace:^",
-    "@types/supertest": "catalog:",
     "@types/node": "catalog:",
-    "@types/body-parser": "1.19.6",
-    "openapi-types": "12.1.3",
-    "body-parser": "2.2.2",
     "eslint": "catalog:",
-    "express": "5.2.1",
     "rimraf": "catalog:",
     "typescript": "catalog:",
     "vitest-config": "workspace:^",
     "vitest": "catalog:",
-    "@microsoft/api-extractor": "catalog:"
+    "@microsoft/api-extractor": "catalog:",
+    "openapi-typescript": "^7.4.1",
+    "prettier": "^3.3.3"
   }
 }

packages/openapi-helpers/src/cli/entrypoint.mts → packages/openapi-generators/src/cli/entrypoint.mts

@@ -14,7 +14,7 @@ function isErrorsOutput(value: string): value is ErrorsOutput {
 }
 
 const SECOND = 1000;
-program.name('openapi-helpers').description('Generate TypeScript types and error classes from OpenAPI specifications').version(PACKAGE_VERSION);
+program.name('openapi-generators').description('Generate TypeScript types and error classes from OpenAPI specifications').version(PACKAGE_VERSION);
 
 const command = program.command('generate').description('Generate code artifacts (types, error classes) from OpenAPI specifications');
 

packages/openapi-helpers/src/generator/generateTypes.ts → packages/openapi-generators/src/generator/generateTypes.ts

@@ -9,7 +9,7 @@ const FILE_HEADER = `${ESLINT_DISABLE}// This file was auto-generated. Do not ed
 // To update, run the error generation script again.\n\n`;
 
 const typedRequestHandlerImport =
-  "import type { TypedRequestHandlers as ImportedTypedRequestHandlers } from '@map-colonies/openapi-helpers/typedRequestHandler';\n";
+  "import type { TypedRequestHandlers as ImportedTypedRequestHandlers } from '@map-colonies/openapi-typed-request-handler';\n";
 const exportTypedRequestHandlers = 'export type TypedRequestHandlers = ImportedTypedRequestHandlers<paths, operations>;\n';
 
 /**

packages/openapi-generators/src/index.ts

@@ -0,0 +1 @@
+export * from './generator/index.js';

packages/openapi-generators/tests/generator.spec.ts

@@ -0,0 +1,18 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { describe, it, expect } from 'vitest';
+import { generateTypes } from '../src/generator/generateTypes.js';
+
+describe('generateTypes', () => {
+  it('should generate types from openapi3.yaml', async () => {
+    const openapiPath = path.join(__dirname, 'openapi3.yaml');
+    const destinationPath = path.join(__dirname, 'test-types.d.ts');
+
+    await generateTypes(openapiPath, destinationPath, { shouldFormat: true });
+
+    const content = await fs.readFile(destinationPath, 'utf-8');
+    expect(content).toContain('export type paths');
+
+    await fs.unlink(destinationPath);
+  });
+});

packages/openapi-generators/typedoc.json

@@ -0,0 +1,3 @@
+{
+  "tsconfig": "tsconfig.build.json"
+}