diff --git a/.release-please-manifest.json b/.release-please-manifest.json index d27cd598..b47c3e93 100644 --- a/.release-please-manifest.json +++ b/.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", diff --git a/.vscode/project.code-workspace b/.vscode/project.code-workspace index 67f8e763..3fe4b7db 100644 --- a/.vscode/project.code-workspace +++ b/.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", diff --git a/packages/openapi-generators/README.md b/packages/openapi-generators/README.md new file mode 100644 index 00000000..3fbe88dc --- /dev/null +++ b/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 [options] +npx openapi-generators generate errors [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 `: 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, +}); +``` diff --git a/packages/openapi-helpers/api-extractor.generators.json b/packages/openapi-generators/api-extractor.json similarity index 62% rename from packages/openapi-helpers/api-extractor.generators.json rename to packages/openapi-generators/api-extractor.json index c6676d40..01ffe423 100644 --- a/packages/openapi-helpers/api-extractor.generators.json +++ b/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." + "reportFileName": "openapi-generators.api.md" } } diff --git a/packages/openapi-helpers/eslint.config.mjs b/packages/openapi-generators/eslint.config.mjs similarity index 100% rename from packages/openapi-helpers/eslint.config.mjs rename to packages/openapi-generators/eslint.config.mjs diff --git a/packages/openapi-helpers/package.json b/packages/openapi-generators/package.json similarity index 56% rename from packages/openapi-helpers/package.json rename to packages/openapi-generators/package.json index 561b7274..1814c9c2 100644 --- a/packages/openapi-helpers/package.json +++ b/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" } } diff --git a/packages/openapi-helpers/src/cli/entrypoint.mts b/packages/openapi-generators/src/cli/entrypoint.mts similarity index 96% rename from packages/openapi-helpers/src/cli/entrypoint.mts rename to packages/openapi-generators/src/cli/entrypoint.mts index aa8fca71..ecde6fde 100644 --- a/packages/openapi-helpers/src/cli/entrypoint.mts +++ b/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'); diff --git a/packages/openapi-helpers/src/common/constants.ts b/packages/openapi-generators/src/common/constants.ts similarity index 100% rename from packages/openapi-helpers/src/common/constants.ts rename to packages/openapi-generators/src/common/constants.ts diff --git a/packages/openapi-helpers/src/generator/generateErrors.ts b/packages/openapi-generators/src/generator/generateErrors.ts similarity index 100% rename from packages/openapi-helpers/src/generator/generateErrors.ts rename to packages/openapi-generators/src/generator/generateErrors.ts diff --git a/packages/openapi-helpers/src/generator/generateTypes.ts b/packages/openapi-generators/src/generator/generateTypes.ts similarity index 96% rename from packages/openapi-helpers/src/generator/generateTypes.ts rename to packages/openapi-generators/src/generator/generateTypes.ts index d101f982..a94a2620 100644 --- a/packages/openapi-helpers/src/generator/generateTypes.ts +++ b/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;\n'; /** diff --git a/packages/openapi-helpers/src/generator/index.ts b/packages/openapi-generators/src/generator/index.ts similarity index 100% rename from packages/openapi-helpers/src/generator/index.ts rename to packages/openapi-generators/src/generator/index.ts diff --git a/packages/openapi-generators/src/index.ts b/packages/openapi-generators/src/index.ts new file mode 100644 index 00000000..4681ea2c --- /dev/null +++ b/packages/openapi-generators/src/index.ts @@ -0,0 +1 @@ +export * from './generator/index.js'; diff --git a/packages/openapi-generators/tests/generator.spec.ts b/packages/openapi-generators/tests/generator.spec.ts new file mode 100644 index 00000000..0cd383be --- /dev/null +++ b/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); + }); +}); diff --git a/packages/openapi-helpers/tests/openapi3.yaml b/packages/openapi-generators/tests/openapi3.yaml similarity index 100% rename from packages/openapi-helpers/tests/openapi3.yaml rename to packages/openapi-generators/tests/openapi3.yaml diff --git a/packages/openapi-helpers/tests/test-with-errors.yaml b/packages/openapi-generators/tests/test-with-errors.yaml similarity index 100% rename from packages/openapi-helpers/tests/test-with-errors.yaml rename to packages/openapi-generators/tests/test-with-errors.yaml diff --git a/packages/openapi-helpers/tests/types.d.ts b/packages/openapi-generators/tests/types.d.ts similarity index 100% rename from packages/openapi-helpers/tests/types.d.ts rename to packages/openapi-generators/tests/types.d.ts diff --git a/packages/openapi-helpers/tsconfig.build.json b/packages/openapi-generators/tsconfig.build.json similarity index 100% rename from packages/openapi-helpers/tsconfig.build.json rename to packages/openapi-generators/tsconfig.build.json diff --git a/packages/openapi-helpers/tsconfig.json b/packages/openapi-generators/tsconfig.json similarity index 100% rename from packages/openapi-helpers/tsconfig.json rename to packages/openapi-generators/tsconfig.json diff --git a/packages/openapi-generators/typedoc.json b/packages/openapi-generators/typedoc.json new file mode 100644 index 00000000..3ab82e82 --- /dev/null +++ b/packages/openapi-generators/typedoc.json @@ -0,0 +1,3 @@ +{ + "tsconfig": "tsconfig.build.json" +} diff --git a/packages/openapi-helpers/vitest.config.ts b/packages/openapi-generators/vitest.config.ts similarity index 100% rename from packages/openapi-helpers/vitest.config.ts rename to packages/openapi-generators/vitest.config.ts diff --git a/packages/openapi-helpers/CHANGELOG.md b/packages/openapi-helpers/CHANGELOG.md deleted file mode 100644 index 9f41ee36..00000000 --- a/packages/openapi-helpers/CHANGELOG.md +++ /dev/null @@ -1,33 +0,0 @@ -# Changelog - -## [5.1.0](https://github.com/MapColonies/infra-packages/compare/openapi-helpers-v5.0.0...openapi-helpers-v5.1.0) (2026-01-22) - - -### 🎉 Features - -* **openapi-helpers:** add expectResponseStatusFactory for type-safe response status assertions ([#102](https://github.com/MapColonies/infra-packages/issues/102)) ([0cd0cfe](https://github.com/MapColonies/infra-packages/commit/0cd0cfe213ea014be1a6019cbdfff27abbbe80f9)) - - -### 🔗 Dependencies - -* **openapi-helpers:** update dependency @apidevtools/json-schema-ref-parser to v15 ([#37](https://github.com/MapColonies/infra-packages/issues/37)) ([bd36b84](https://github.com/MapColonies/infra-packages/commit/bd36b84c7adf3200fad6aa1578f7114eea94f945)) -* **openapi-helpers:** update dependency ora to v9 ([#39](https://github.com/MapColonies/infra-packages/issues/39)) ([2e95442](https://github.com/MapColonies/infra-packages/commit/2e95442a31a68a30653e44e7e0b69cb96de62441)) - -## [5.0.0](https://github.com/MapColonies/infra-packages/compare/openapi-helpers-v4.0.0...openapi-helpers-v5.0.0) (2026-01-18) - - -### ⚠ BREAKING CHANGES - -* **openapi-helpers:** changed node engine to 24 - -### 🎉 Features - -* **openapi-helpers:** added MAPCO-9027 ([#10](https://github.com/MapColonies/infra-packages/issues/10)) ([3f6a9e1](https://github.com/MapColonies/infra-packages/commit/3f6a9e1e6fcfc427342db12f6574ef5ad07083aa)) -* **openapi-helpers:** changed node engine to 24 ([17a83c3](https://github.com/MapColonies/infra-packages/commit/17a83c347e14ac3a8260770770b457b6f5dceb95)) -* **tracing-utils:** added ([#13](https://github.com/MapColonies/infra-packages/issues/13)) ([bbfca60](https://github.com/MapColonies/infra-packages/commit/bbfca60809416dc053081d1f27432b3c06584bb3)) - - -### 🔗 Dependencies - -* **global:** remove every use of catalog in prod ([#47](https://github.com/MapColonies/infra-packages/issues/47)) ([6f431ea](https://github.com/MapColonies/infra-packages/commit/6f431ea32c155887993b48f5334e851a4dce8fbc)) -* **openapi-helpers:** update dependency oas-normalize to v15 ([#38](https://github.com/MapColonies/infra-packages/issues/38)) ([bd0d7b6](https://github.com/MapColonies/infra-packages/commit/bd0d7b6e77b0196d12ae19c1a9759b84b684c766)) diff --git a/packages/openapi-helpers/README.md b/packages/openapi-helpers/README.md deleted file mode 100644 index 13071637..00000000 --- a/packages/openapi-helpers/README.md +++ /dev/null @@ -1,274 +0,0 @@ -# openapi-helpers - -This package contains scripts, types and functions to help you work with OpenAPI. - -## Installation - -Run the following commands: - -```bash -npm install --save-dev @map-colonies/openapi-helpers supertest prettier openapi-typescript @types/express -``` - -## 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: - -- ``: Path to the OpenAPI YAML or JSON file to use as the source schema. -- ``: 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 `: 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 generate types [options] -``` - -For example: - -```bash -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 [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 ` - 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, -}); -``` - -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. - -### Usage - -```typescript -import { TypedRequestHandlers } from '@map-colonies/openapi-helpers/typedRequestHandler'; -import type { paths, operations } from './src/openapi.d.ts'; - -// Initialize the TypedRequestHandlers with the paths and operations types -// This can be done in a separate file and exported, in the same file or even in the same line -type MyHandlers = TypedRequestHandlers; - -export class Controller { - // Define the handler for the operation based on method and path - public getResource: MyHandlers['GET /resource'] = (req, res) => { - res.status(httpStatus.OK).json({ id: 1, description: 'description', name: 'name' }); - }; - - // Define the handler for the operation based on the operation name - public getResource: MyHandlers['getResource'] = (req, res) => { - res.status(httpStatus.OK).json({ id: 1, description: 'description', name: 'name' }); - }; -} -``` - -## RequestSender - -The package contains a wrapper for the `supertest` package that provides autocomplete for all the requests to the API based on the OpenAPI schema. The RequestSender is initialized with the server's base URL and the OpenAPI schema and the types exported by `openapi-typescript`. - -```typescript -import { RequestSender } from '@map-colonies/openapi-helpers/requestSender'; -import type { paths, operations } from './src/openapi.d.ts'; - -const requestSender = await createRequestSender('path/to/openapi3.yaml', expressApp); -``` - -The requestSender object contains all the paths and operations defined in the OpenAPI schema. For example, to send a request to the `getUsers` operation with the `/users` path and with the `GET` method, you can use the following code: - -```typescript -const response = await requestSender.getUsers(); - -// or - -const response = await requestSender.sendRequest({ - method: 'get', - path: '/simple-request', -}); -``` - -The package supports all the operations defined in the OpenAPI schema, either by operation name, or by using the `sendRequest` function with the method, path and parameters. - -### Response Status Assertion - -The `expectResponseStatusFactory` provides TypeScript type narrowing for response status assertions in tests. This utility creates an assertion function that narrows the response type based on the expected status code, giving you full type safety when working with different response types. - -#### Usage - -```typescript -import { expectResponseStatusFactory } from '@map-colonies/openapi-helpers/requestSender'; -import type { ExpectResponseStatus } from '@map-colonies/openapi-helpers/requestSender'; -import { describe, it, expect } from 'vitest'; - -// Create the assertion function with the exported type -const expectResponseStatus: ExpectResponseStatus = expectResponseStatusFactory(expect); - -it('should return user data on success', async () => { - const response = await requestSender.getUser({ pathParams: { id: '123' } }); - - // Assert the status and narrow the type - expectResponseStatus(response, 200); - - // TypeScript now knows response is the 200 response type - // You can safely access response.body with full autocomplete - console.log(response.body.id); - console.log(response.body.name); -}); - -it('should handle error responses', async () => { - const response = await requestSender.getUser({ pathParams: { id: 'invalid' } }); - - if (response.status === 404) { - expectResponseStatus(response, 404); - // TypeScript knows this is a 404 response - console.log(response.body.error); - } -}); -``` - -> [!TIP] -> **Avoiding TS2775 Error**: When using `expectResponseStatusFactory`, you must provide an explicit type annotation using the exported `ExpectResponseStatus` type as shown above. This is required by TypeScript's strict mode for assertion functions. - -#### Reusable Setup - -To avoid repeating the setup in every test file, create a shared test utility: - -```typescript -// test/utils/assertions.ts -import { expectResponseStatusFactory } from '@map-colonies/openapi-helpers/requestSender'; -import type { ExpectResponseStatus } from '@map-colonies/openapi-helpers/requestSender'; -import { expect } from 'vitest'; - -export const expectResponseStatus: ExpectResponseStatus = expectResponseStatusFactory(expect); -``` - -Then import and use it in your tests: - -```typescript -// test/api.spec.ts -import { expectResponseStatus } from './utils/assertions'; - -it('should work', async () => { - const response = await requestSender.getUser({ pathParams: { id: '123' } }); - expectResponseStatus(response, 200); - // TypeScript knows the exact response type -}); -``` - -#### How it works - -The `expectResponseStatusFactory` takes an expect function (from your test framework) and returns a function that: - -1. Asserts that the response status matches the expected status -2. Narrows the TypeScript type of the response to only include the matching status code - -This is particularly useful when working with OpenAPI-generated types that have multiple possible response types (e.g., 200 success, 404 not found, 500 error). After calling `expectResponseStatus`, TypeScript will know exactly which response type you're working with. - -#### Benefits - -- **Type Safety**: Full TypeScript support with automatic type narrowing -- **Autocomplete**: Get accurate autocomplete for response body based on the status code -- **Test Clarity**: Combine assertion and type narrowing in a single function call -- **Prevents Errors**: Catch type mismatches at compile time instead of runtime - -> [!IMPORTANT] -> For the package to function properly, you need to make sure that the following values are configured in your `tsconfig.json` or `jsconfig.json` files under compilerOptions: -> -> - module: "NodeNext" -> - moduleResolution: "NodeNext" diff --git a/packages/openapi-helpers/etc/generators.openapi-helpers.api.md b/packages/openapi-helpers/etc/generators.openapi-helpers.api.md deleted file mode 100644 index 28205705..00000000 --- a/packages/openapi-helpers/etc/generators.openapi-helpers.api.md +++ /dev/null @@ -1,29 +0,0 @@ -## API Report File for "@map-colonies/openapi-helpers" - -> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). - -```ts - -import { SchemaObject } from 'openapi-typescript'; -import { TransformNodeOptions } from 'openapi-typescript'; -import { TransformObject } from 'openapi-typescript'; -import type { TypeNode } from 'typescript'; - -// @public -export function generateErrors(openapiPath: string, destinationPath: string, options: { - shouldFormat?: boolean; - includeMapping?: boolean; - includeErrorClasses?: boolean; -}): Promise; - -// @public -export function generateTypes(openapiPath: string, destinationPath: string, options: { - shouldFormat?: boolean; - addTypedRequestHandler?: boolean; - inject?: string; - transform?: (schemaObject: SchemaObject, metadata: TransformNodeOptions) => TypeNode | TransformObject | undefined; -}): Promise; - -// (No @packageDocumentation comment for this package) - -``` diff --git a/packages/openapi-helpers/etc/handler.openapi-helpers.api.md b/packages/openapi-helpers/etc/handler.openapi-helpers.api.md deleted file mode 100644 index 80d004c0..00000000 --- a/packages/openapi-helpers/etc/handler.openapi-helpers.api.md +++ /dev/null @@ -1,19 +0,0 @@ -## API Report File for "@map-colonies/openapi-helpers" - -> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). - -```ts -import type { OptionalKeys } from 'ts-essentials'; -import type { RequestHandler } from 'express'; - -// Warning: (ae-forgotten-export) The symbol "PathsTemplate" needs to be exported by the entry point typedRequestHandler.d.ts -// Warning: (ae-forgotten-export) The symbol "OperationsTemplate" needs to be exported by the entry point typedRequestHandler.d.ts -// Warning: (ae-forgotten-export) The symbol "OperationHandlers" needs to be exported by the entry point typedRequestHandler.d.ts -// Warning: (ae-forgotten-export) The symbol "PathHandlers" needs to be exported by the entry point typedRequestHandler.d.ts -// -// @public -export type TypedRequestHandlers = OperationHandlers & - PathHandlers; - -// (No @packageDocumentation comment for this package) -``` diff --git a/packages/openapi-helpers/src/common/types.ts b/packages/openapi-helpers/src/common/types.ts deleted file mode 100644 index e59803e9..00000000 --- a/packages/openapi-helpers/src/common/types.ts +++ /dev/null @@ -1,23 +0,0 @@ -/* eslint-disable @typescript-eslint/no-explicit-any */ -import type { WritableKeys } from 'ts-essentials'; - -export type AddIfNotNever = [U] extends [never] ? T : T & U; -export type PickWritable> = Pick>; - -export type Methods = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head' | 'options' | 'trace'; - -export type OperationsTemplate = Record; - -export type PathsTemplate = Record< - string, - { - parameters: { - query?: any; - header?: any; - path?: any; - cookie?: any; - }; - } & { - [key in Methods]?: OperationsTemplate; - } ->; diff --git a/packages/openapi-helpers/tsdoc-metadata.json b/packages/openapi-helpers/tsdoc-metadata.json deleted file mode 100644 index 74e45be2..00000000 --- a/packages/openapi-helpers/tsdoc-metadata.json +++ /dev/null @@ -1,11 +0,0 @@ -// This file is read by tools that parse documentation comments conforming to the TSDoc standard. -// It should be published with your NPM package. It should not be tracked by Git. -{ - "tsdocVersion": "0.12", - "toolPackages": [ - { - "packageName": "@microsoft/api-extractor", - "packageVersion": "7.55.2" - } - ] -} diff --git a/packages/openapi-helpers/tsdoc.json b/packages/openapi-helpers/tsdoc.json deleted file mode 100644 index 9154c14f..00000000 --- a/packages/openapi-helpers/tsdoc.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", - "extends": ["@microsoft/api-extractor/extends/tsdoc-base.json"], - "tagDefinitions": [ - { - "tagName": "@template", - "syntaxKind": "modifier" - }, - { - "tagName": "@interface", - "syntaxKind": "modifier" - } - ], - "supportForTags": { - "@template": true, - "@interface": true - } -} diff --git a/packages/openapi-helpers/typedoc.json b/packages/openapi-helpers/typedoc.json deleted file mode 100644 index 9dac291c..00000000 --- a/packages/openapi-helpers/typedoc.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "tsconfig": "tsconfig.build.json", - "entryPoints": ["src/requestSender/requestSender.ts", "src/typedRequestHandler/typedRequestHandler.ts"], - "out": "docs", - "excludeInternal": true, - "includeVersion": true, - "categorizeByGroup": true, - "navigation": { - "includeGroups": true - } -} diff --git a/packages/openapi-helpers/etc/sender.openapi-helpers.api.md b/packages/openapi-typed-request-sender/etc/openapi-typed-request-sender.api.md similarity index 53% rename from packages/openapi-helpers/etc/sender.openapi-helpers.api.md rename to packages/openapi-typed-request-sender/etc/openapi-typed-request-sender.api.md index 2403270c..fbe2c25c 100644 --- a/packages/openapi-helpers/etc/sender.openapi-helpers.api.md +++ b/packages/openapi-typed-request-sender/etc/openapi-typed-request-sender.api.md @@ -1,4 +1,4 @@ -## API Report File for "@map-colonies/openapi-helpers" +## API Report File for "@map-colonies/openapi-typed-request-sender" > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). @@ -12,29 +12,47 @@ import type { RequiredKeys } from 'ts-essentials'; import type * as supertest from 'supertest'; import type { WritableKeys } from 'ts-essentials'; -// Warning: (ae-forgotten-export) The symbol "PathsTemplate" needs to be exported by the entry point requestSender.d.ts -// Warning: (ae-forgotten-export) The symbol "OperationsTemplate" needs to be exported by the entry point requestSender.d.ts -// Warning: (ae-forgotten-export) The symbol "RequestSenderOptions" needs to be exported by the entry point requestSender.d.ts +// Warning: (ae-forgotten-export) The symbol "PathsTemplate" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "OperationsTemplate" needs to be exported by the entry point index.d.ts // // @public export function createRequestSender(openapiFilePath: Operations extends never ? never : string, app: express.Application, options?: RequestSenderOptions): Promise>; -// Warning: (ae-forgotten-export) The symbol "Response_2" needs to be exported by the entry point requestSender.d.ts +// Warning: (ae-forgotten-export) The symbol "Response_2" needs to be exported by the entry point index.d.ts // // @public export type ExpectResponseStatus = (res: TResponse, expectedStatus: TStatus) => asserts res is Extract; -// Warning: (ae-forgotten-export) The symbol "Expect" needs to be exported by the entry point requestSender.d.ts +// Warning: (ae-forgotten-export) The symbol "Expect" needs to be exported by the entry point index.d.ts // // @public export function expectResponseStatusFactory(expect: Expect): ExpectResponseStatus; -// Warning: (ae-forgotten-export) The symbol "OperationsNames" needs to be exported by the entry point requestSender.d.ts -// Warning: (ae-forgotten-export) The symbol "RequestOptions" needs to be exported by the entry point requestSender.d.ts -// Warning: (ae-forgotten-export) The symbol "OperationRequestOptional" needs to be exported by the entry point requestSender.d.ts -// Warning: (ae-forgotten-export) The symbol "OperationRequestRequired" needs to be exported by the entry point requestSender.d.ts +// @public (undocumented) +export type OperationsNames = keyof Operations; + +// @public (undocumented) +export type PathRequestOptions, undefined>> = RequestOptions & { + path: Path; + method: Method; +}; + +// Warning: (ae-forgotten-export) The symbol "AddIfNotNever" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "RequestOptionsWithoutPathParams" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "PathParamsObj" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +export type RequestOptions = AddIfNotNever, PathParamsObj>; + +// Warning: (ae-forgotten-export) The symbol "ResponseObjectToFlat" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +export type RequestReturn = Promise & Omit, 'body' | 'status'>> & supertest.Test; + +// Warning: (ae-forgotten-export) The symbol "OperationRequestOptional" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "OperationRequestRequired" needs to be exported by the entry point index.d.ts // // @public export type RequestSender = Prettify<{ @@ -43,9 +61,14 @@ export type RequestSender]: RequiredKeys> extends OptionalKeys> ? OperationRequestOptional : OperationRequestRequired; }>; +// @public +export interface RequestSenderOptions { + baseUrl?: string; +} + // Warnings were encountered during analysis: // -// src/requestSender/types.ts:89:5 - (ae-forgotten-export) The symbol "SendRequest" needs to be exported by the entry point requestSender.d.ts +// src/types.ts:81:5 - (ae-forgotten-export) The symbol "SendRequest" needs to be exported by the entry point index.d.ts // (No @packageDocumentation comment for this package) diff --git a/packages/openapi-typed-request-sender/package.json b/packages/openapi-typed-request-sender/package.json index 46275d4c..d9a23f48 100644 --- a/packages/openapi-typed-request-sender/package.json +++ b/packages/openapi-typed-request-sender/package.json @@ -18,6 +18,7 @@ "clean": "rimraf dist", "prepack": "turbo run build", "check-dist": "publint && attw --profile node16 --pack .", + "knip": "knip --directory ../.. --workspace packages/openapi-typed-request-sender", "api:check": "api-extractor run --verbose --config ./api-extractor.json", "api": "api-extractor run --local --verbose --config ./api-extractor.json" }, diff --git a/packages/openapi-typed-request-sender/typedoc.json b/packages/openapi-typed-request-sender/typedoc.json new file mode 100644 index 00000000..3ab82e82 --- /dev/null +++ b/packages/openapi-typed-request-sender/typedoc.json @@ -0,0 +1,3 @@ +{ + "tsconfig": "tsconfig.build.json" +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index fb312634..351203dd 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -530,7 +530,7 @@ importers: specifier: workspace:^ version: link:../../internal/vitest-config - packages/openapi-helpers: + packages/openapi-generators: dependencies: '@apidevtools/json-schema-ref-parser': specifier: ^15.0.0 @@ -541,9 +541,6 @@ importers: '@map-colonies/read-pkg': specifier: workspace:^ version: link:../read-pkg - '@types/express': - specifier: ^4.17.21 - version: 4.17.25 change-case: specifier: ^5.4.4 version: 5.4.4 @@ -553,21 +550,9 @@ importers: oas-normalize: specifier: ^15.0.0 version: 15.7.0 - openapi-typescript: - specifier: ^7.4.1 - version: 7.10.1(typescript@5.9.3) ora: specifier: ^9.0.0 version: 9.1.0 - prettier: - specifier: ^3.3.3 - version: 3.7.4 - supertest: - specifier: ^7.0.0 - version: 7.2.2 - ts-essentials: - specifier: ^10.1.1 - version: 10.1.1(typescript@5.9.3) yaml: specifier: ^2.8.0 version: 2.8.2 @@ -581,27 +566,18 @@ importers: '@microsoft/api-extractor': specifier: 'catalog:' version: 7.55.2(@types/node@24.10.9) - '@types/body-parser': - specifier: 1.19.6 - version: 1.19.6 '@types/node': specifier: 'catalog:' version: 24.10.9 - '@types/supertest': - specifier: 'catalog:' - version: 6.0.3 - body-parser: - specifier: 2.2.2 - version: 2.2.2 eslint: specifier: 'catalog:' version: 9.39.1(jiti@2.6.1) - express: - specifier: 5.2.1 - version: 5.2.1 - openapi-types: - specifier: 12.1.3 - version: 12.1.3 + openapi-typescript: + specifier: ^7.4.1 + version: 7.10.1(typescript@5.9.3) + prettier: + specifier: ^3.3.3 + version: 3.8.1 rimraf: specifier: 'catalog:' version: 6.1.2 @@ -4703,10 +4679,6 @@ packages: js-tokens@9.0.1: resolution: {integrity: sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==} - js-yaml@4.1.1: - resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==} - hasBin: true - js-yaml@4.2.0: resolution: {integrity: sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==} hasBin: true @@ -5390,16 +5362,6 @@ packages: resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==} engines: {node: '>= 0.8.0'} - prettier@3.7.4: - resolution: {integrity: sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA==} - engines: {node: '>=14'} - hasBin: true - - prettier@3.8.0: - resolution: {integrity: sha512-yEPsovQfpxYfgWNhCfECjG5AQaO+K3dp6XERmOepyPDVqcJm+bjyCVO3pmU+nAPe0N5dDvekfGezt/EIiRe1TA==} - engines: {node: '>=14'} - hasBin: true - prettier@3.8.1: resolution: {integrity: sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==} engines: {node: '>=14'} @@ -8211,7 +8173,7 @@ snapshots: colorette: 1.4.0 https-proxy-agent: 7.0.6(supports-color@10.2.2) js-levenshtein: 1.1.6 - js-yaml: 4.1.1 + js-yaml: 4.2.0 minimatch: 5.1.6 pluralize: 8.0.0 yaml-ast-parser: 0.0.43 @@ -10685,10 +10647,6 @@ snapshots: js-tokens@9.0.1: {} - js-yaml@4.1.1: - dependencies: - argparse: 2.0.1 - js-yaml@4.2.0: dependencies: argparse: 2.0.1 @@ -10712,7 +10670,7 @@ snapshots: js-yaml: 4.2.0 lodash: 4.17.23 minimist: 1.2.8 - prettier: 3.8.0 + prettier: 3.8.1 tinyglobby: 0.2.15 json-schema-traverse@0.4.1: {} @@ -11417,10 +11375,6 @@ snapshots: prelude-ls@1.2.1: {} - prettier@3.7.4: {} - - prettier@3.8.0: {} - prettier@3.8.1: {} pretty-format@26.6.2: diff --git a/release-please-config.json b/release-please-config.json index b1890fc1..cf0398a7 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -98,6 +98,10 @@ "package-name": "@map-colonies/openapi-express-viewer", "release-type": "node" }, + "packages/openapi-generators": { + "package-name": "@map-colonies/openapi-generators", + "release-type": "node" + }, "packages/openapi-helpers": { "package-name": "@map-colonies/openapi-helpers", "release-type": "node"