feat!: unified CLI generating TypeScript types and error classes from OpenAPI specifications (MAPCO-8469)

README.md

@@ -9,22 +9,132 @@ Run the following commands:
 npm install --save-dev @map-colonies/openapi-helpers supertest prettier openapi-typescript @types/express
 ```
 
-## types-generator
-The package contains a script that wraps the `openapi-typescript` package and generates types for the OpenAPI schema. The script also formats the generated types using `prettier`.
 
-The command structure is as follows:
+## CLI Usage
+
+The package provides a unified CLI for generating TypeScript types and error classes from OpenAPI specifications. All code generation is now performed using the `generate` command, which supports subcommands for types and errors.
+
+#### CLI Arguments Reference
+
+**Positional Arguments:**
+For both `generate types` and `generate errors` commands, the positional arguments are:
+
+- `<openapi-file>`: Path to the OpenAPI YAML or JSON file to use as the source schema.
+- `<output-file>`: Path to the file where the generated code will be written.
+
+These arguments are required and must be provided in the order shown.
+
+**Optional Arguments:**
+
+For `generate types`:
+- `-f, --format`: Format the generated types using Prettier
+- `-t, --add-typed-request-handler`: Add the TypedRequestHandler type to the generated types
+
+For `generate errors`:
+- `-f, --format`: Format the generated code using Prettier  
+- `-e, --errors-output <all|map|classes>`: Specify what to generate (default: all)
+  - `all`: generate both error classes and error code mapping
+  - `map`: generate only the error code mapping
+  - `classes`: generate only the error classes
+
+### Generate Types
+
+Generate TypeScript types from an OpenAPI schema:
 ```bash
-npx @map-colonies/openapi-helpers <input-file> <output-file> --format --add-typed-request-handler
+npx @map-colonies/openapi-helpers generate types <openapi-file> <output-file> [options]
 ```
 
 For example:
 ```bash
-npx @map-colonies/openapi-helpers ./openapi3.yaml ./src/openapi.d.ts --format --add-typed-request-handler
+npx @map-colonies/openapi-helpers generate types ./openapi3.yaml ./src/openapi.d.ts --format --add-typed-request-handler
+```
+
+Options:
+- `-f, --format` - Format the generated types using `prettier`.
+- `-t, --add-typed-request-handler` - Add the `TypedRequestHandler` type to the generated types.
+
+### Generate Errors
+
+Generate error classes and error code mappings from an OpenAPI schema:
+```bash
+npx @map-colonies/openapi-helpers generate errors <openapi-file> <output-file> [options]
+```
+
+For example:
+```bash
+npx @map-colonies/openapi-helpers generate errors ./openapi3.yaml ./src/errors.ts --format
+```
+
+
+Options:
+- `-f, --format` - Format the generated code using `prettier`.
+- `-e, --errors-output <all|map|classes>` - Specify what to generate:
+  - `all` (default): generate both error classes and error code mapping
+  - `map`: generate only the error code mapping
+  - `classes`: generate only the error classes
+
+### Help and Examples
+
+To see all available commands and options:
+```bash
+npx @map-colonies/openapi-helpers --help
+npx @map-colonies/openapi-helpers generate --help
+npx @map-colonies/openapi-helpers generate types --help
+npx @map-colonies/openapi-helpers generate errors --help
+```
+
+
+#### Example: Run all generations
+
+You can run both types and errors generation in sequence:
+```bash
+npx @map-colonies/openapi-helpers generate types ./openapi3.yaml ./src/openapi.d.ts --format --add-typed-request-handler
+npx @map-colonies/openapi-helpers generate errors ./openapi3.yaml ./src/errors.ts --format --errors-output all
+```
+
+
+
+## Programmatic Support
+
+
+> [!NOTE]
+> **Programmatic usage of the CLI (importing and using the generators directly) is only supported in ECMAScript modules (ESM).** CommonJS is not supported for direct imports.
+
+The code generators (`generateTypes.mts` and `generateErrors.mts`) now support functional programming patterns. You can inject custom transformation logic or AST manipulation by providing functional arguments, making the generators more flexible and composable for advanced use cases.
+
+
+### API Usage
+
+You can import and use the generators directly in your own scripts for full functional programming flexibility:
+
+```typescript
+import { generateTypes, generateErrors } from '@map-colonies/openapi-helpers/generators';
+
+// Generate types
+await generateTypes(
+  'openapi3.yaml',
+  'src/openapi.d.ts',
+  {
+    shouldFormat: true,
+    addTypedRequestHandler: true,
+    // inject?: string,
+    // transform?: (schemaObject, metadata) => ...
+  }
+);
+
+// Generate errors
+await generateErrors(
+  'openapi3.yaml',
+  'src/errors.ts',
+  {
+    shouldFormat: true,
+    includeMapping: true,
+    includeErrorClasses: true
+  }
+);
 ```
 
-### options
-- `--format` - format the generated types using `prettier`.
-- `--add-typed-request-handler` - add the `TypedRequestHandler` type to the generated types.
+You can pass custom `inject` or `transform` functions to `generateTypes` for advanced AST/code manipulation, enabling highly composable and functional workflows.
 
 ## TypedRequestHandler
 The package contains a wrapper for the `express` types package that provides autocomplete for all the request handlers to the API based on the OpenAPI schema. The TypedRequestHandler is initialized with the types generated by `openapi-typescript`, and is configured based on operation name or method and path.