@hey-api/openapi-ts 0.31.0 → 0.32.0

package/README.md

@@ -100,14 +100,29 @@ Alternatively, you can use `openapi-ts.config.js` and configure the export state
 
 ### Clients
 
-We provide a variety of possible clients to use when generating your `openapi-ts` client. If one is not specified by the user, we will try to infer the client to use. If the inferred client is not correct, you can set it with the client config parameter. The following are available:
+By default, `openapi-ts` will try to guess your client based on your project dependencies. If we don't get it right, you can specify the desired client
 
-- `angular`: An [Angular](https://angular.io/) client using [RxJS](https://rxjs.dev/).
-- `axios`: An [Axios](https://axios-http.com/docs/intro) client.
-- `fetch`: A [Fetch API](https://developer.mozilla.org/docs/Web/API/Fetch_API) client.
-    > NOTE: The Fetch API is experimental in Node.js 18+ and was stabilized in [Node.js v21](https://nodejs.org/docs/latest-v21.x/api/globals.html#fetch)
-- `node`: A [Node.js](https://nodejs.org/) client using [node-fetch](https://www.npmjs.com/package/node-fetch).
-- `xhr`: A [XMLHttpRequest](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest) client.
+```mjs
+/** @type {import('@hey-api/openapi-ts').UserConfig} */
+export default {
+  client: 'fetch',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+}
+```
+
+We support these clients:
+
+- [angular](https://angular.io/) (using [RxJS](https://rxjs.dev/))
+- [axios](https://axios-http.com/)
+- [fetch](https://developer.mozilla.org/docs/Web/API/Fetch_API)
+
+We also support the legacy Node.js and XHR clients:
+
+- [node](https://nodejs.org/) (using [node-fetch](https://www.npmjs.com/package/node-fetch))
+- [xhr](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest)
+
+> ⚠️ You might not need a `node` client. Fetch API is [experimental](https://nodejs.org/docs/latest-v18.x/api/globals.html#fetch) in Node.js v18 and [stable](https://nodejs.org/docs/latest-v21.x/api/globals.html#fetch) in Node.js v21. We recommend upgrading to the latest Node.js version.
 
 ### Formatting
 
@@ -141,18 +156,18 @@ You can also prevent your client from being processed by linters by adding your
 
 ### Enums
 
-We do not generate TypeScript [enums](https://www.typescriptlang.org/docs/handbook/enums.html) because they are not standard JavaScript and pose [typing challenges](https://dev.to/ivanzm123/dont-use-enums-in-typescript-they-are-very-dangerous-57bh). If you want to iterate through possible field values without manually typing arrays, you can export enums by running
+If you need to iterate through possible field values without manually typing arrays, you can export enums with
 
 ```mjs
 /** @type {import('@hey-api/openapi-ts').UserConfig} */
 export default {
-  enums: true,
+  enums: 'javascript',
   input: 'path/to/openapi.json',
   output: 'src/client',
 }
 ```
 
-This will export your enums as plain JavaScript objects. For example, `Foo` will generate the following
+This will export enums as plain JavaScript objects. For example, `Foo` would become
 
 ```ts
 export const FooEnum = {
@@ -161,39 +176,21 @@ export const FooEnum = {
 } as const;
 ```
 
-### Config API
+We discourage generating [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html) because they are not standard JavaScript and pose [typing challenges](https://dev.to/ivanzm123/dont-use-enums-in-typescript-they-are-very-dangerous-57bh). If you really need TypeScript enums, you can export them with
 
-```sh
-$ openapi-ts --help
-
-  Usage: openapi-ts [options]
-
-  Options:
-    -V, --version             output the version number
-    -i, --input <value>       OpenAPI specification, can be a path, url or string content (required)
-    -o, --output <value>      Output directory (required)
-    -c, --client <value>      HTTP client to generate [fetch, xhr, node, axios, angular] (default: "fetch")
-    --name <value>            Custom client class name
-    --useOptions <value>      Use options instead of arguments (default: true)
-    --base <value>            Manually set base in OpenAPI config instead of inferring from server value
-    --enums                   Generate JavaScript objects from enum definitions (default: false)
-    --exportCore <value>      Write core files to disk (default: true)
-    --exportServices <value>  Write services to disk [true, false, regexp] (default: true)
-    --exportModels <value>    Write models to disk [true, false, regexp] (default: true)
-    --exportSchemas <value>   Write schemas to disk (default: true)
-    --format                  Process output folder with formatter?
-    --no-format               Disable processing output folder with formatter
-    --lint                    Process output folder with linter?
-    --no-lint                 Disable processing output folder with linter
-    --no-operationId          Use path URL to generate operation ID
-    --postfixServices         Service name postfix (default: "Service")
-    --postfixModels           Model name postfix
-    --request <value>         Path to custom request file
-    --useDateType <value>     Output Date instead of string for the format "date-time" in the models (default: false)
-    --useLegacyEnums          Generate Typescript enum definitions (default: false)
-    -h, --help                display help for command
+```mjs
+/** @type {import('@hey-api/openapi-ts').UserConfig} */
+export default {
+  enums: 'typescript',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+}
 ```
 
+### Config API
+
+You can view the complete list of options in the [UserConfig](./src/types/config.ts) interface.
+
 ## Interceptors
 
 Interceptors (middleware) can be used to modify requests before they're sent or responses before they're returned to the rest of your application. Below is an example request interceptor

package/bin/index.js

@@ -15,35 +15,66 @@ const params = program
     .option('-i, --input <value>', 'OpenAPI specification (path, url, or string content)')
     .option('-o, --output <value>', 'Output directory')
     .option('-c, --client <value>', 'HTTP client to generate [angular, axios, fetch, node, xhr]')
-    .option('--name <value>', 'Custom client class name')
-    .option('--useOptions [value]', 'Use options instead of arguments')
+    .option('-d, --debug', 'Run in debug mode?')
     .option('--base [value]', 'Manually set base in OpenAPI config instead of inferring from server value')
-    .option('--enums', 'Generate JavaScript objects from enum definitions')
-    .option('--exportCore <value>', 'Write core files to disk')
-    .option('--exportServices <value>', 'Write services to disk')
-    .option('--exportModels <value>', 'Write models to disk')
-    .option('--exportSchemas <value>', 'Write schemas to disk')
-    .option('--format', 'Process output folder with formatter?')
-    .option('--no-format', 'Disable processing output folder with formatter')
-    .option('--lint', 'Process output folder with linter?')
-    .option('--no-lint', 'Disable processing output folder with linter')
-    .option('--operationId', 'Use operationd ID?')
-    .option('--no-operationId', 'Use path URL to generate operation ID')
-    .option('--postfixServices <value>', 'Service name postfix')
-    .option('--serviceResponse [value]', 'Define shape of returned value from service calls')
-    .option('--useDateType <value>', 'Output Date instead of string for the format "date-time" in the models')
+    .option('--enums <value>', 'Export enum definitions (javascript, typescript)')
+    .option('--exportCore [value]', 'Write core files to disk')
+    .option('--exportModels [value]', 'Write models to disk')
+    .option('--exportSchemas [value]', 'Write schemas to disk')
+    .option('--exportServices [value]', 'Write services to disk')
+    .option('--format [value]', 'Process output folder with formatter?')
+    .option('--lint [value]', 'Process output folder with linter?')
+    .option('--name <value>', 'Custom client class name')
+    .option('--operationId [value]', 'Use operationd ID?')
     .option('--postfixModels <value>', 'Model name postfix')
+    .option('--postfixServices <value>', 'Service name postfix')
     .option('--request <value>', 'Path to custom request file')
-    .option('--write', 'Write files to disk? (used for testing)')
-    .option('--no-write', 'Skip writing files to disk (used for testing)')
-    .option('--useLegacyEnums', 'Generate Typescript enum definitions')
+    .option('--serviceResponse [value]', 'Define shape of returned value from service calls')
+    .option('--useDateType [value]', 'Output Date instead of string for the format "date-time" in the models')
+    .option('--useOptions [value]', 'Use options instead of arguments')
+    .option('--write [value]', 'Write files to disk? (used for testing)')
     .parse(process.argv)
     .opts();
 
+const stringToBoolean = value => {
+    if (value === 'true') {
+        return true;
+    }
+    if (value === 'false') {
+        return false;
+    }
+    return value;
+};
+
+const processParams = (obj, keys) => {
+    const result = {};
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === 'string') {
+            result[key] = stringToBoolean(value);
+        }
+    }
+    return result;
+};
+
 async function start() {
     try {
         const { createClient } = await import(new URL('../dist/node/index.js', import.meta.url));
-        await createClient(params);
+        await createClient({
+            ...params,
+            ...processParams(params, [
+                'exportCore',
+                'exportModels',
+                'exportSchemas',
+                'exportServices',
+                'format',
+                'lint',
+                'operationId',
+                'useDateType',
+                'useOptions',
+                'write',
+            ]),
+        });
         process.exit(0);
     } catch (error) {
         console.error(error);

package/dist/node/index.d.ts

@@ -9,10 +9,20 @@ interface UserConfig {
      */
     client?: 'angular' | 'axios' | 'fetch' | 'node' | 'xhr';
     /**
-     * Generate JavaScript objects from enum definitions?
+     * Run in debug mode?
      * @default false
      */
-    enums?: boolean;
+    debug?: boolean;
+    /**
+     * Export enum definitions?
+     * @default false
+     */
+    enums?: 'javascript' | 'typescript' | false;
+    /**
+     * Generate an experimental build?
+     * @default false
+     */
+    experimental?: boolean;
     /**
      * Generate core client classes?
      * @default true
@@ -89,11 +99,6 @@ interface UserConfig {
      * @default true
      */
     useOptions?: boolean;
-    /**
-     * Generate Typescript enum definitions
-     * @default false
-     */
-    useLegacyEnums?: boolean;
     /**
      * Write the files to disk (true or false)
      * @default true