Refactor

Author: drwpow

.gitignore

@@ -1,12 +1,5 @@
-.dccache
-.cache
 .DS_Store
-.idea/
-.nyc_output/
-**/generated/
-**/__snapshots__/
+test/fixtures/*.yaml
 coverage/
 dist
 node_modules
-yarn.lock
-yarn-error.log

.npmrc

@@ -8,14 +8,15 @@
 
 # 📘️ openapi-typescript
 
-🚀 Convert [OpenAPI](https://spec.openapis.org/oas/latest.html) schemas to TypeScript interfaces painlessly using pure Node.js. No Java, node-gyp, or running OpenAPI servers necessary. Uses [Prettier](https://npmjs.com/prettier) to format the output.
+🚀 Convert static [OpenAPI](https://spec.openapis.org/oas/latest.html) schemas to TypeScript types quickly using pure Node.js. Fast, lightweight, (almost) dependency-free, and no Java/node-gyp/running OpenAPI servers necessary.
 
 **Features**
 
-- ✅ Supports YAML and JSON
+- ✅ Supports YAML and JSON formats
+- ✅ Supports advanced OpenAPI 3.1 features like [discriminators](https://spec.openapis.org/oas/v3.1.0#discriminator-object)
 - ✅ Supports loading via remote URL (simple authentication supported with the `--auth` flag)
 - ✅ Supports remote references: `$ref: "external.yaml#components/schemas/User"`
-- ✅ Prettier formatting is fully customizable to match your existing code style.
+- ✅ Fetches remote schemas quickly using [undici](https://www.npmjs.com/package/undici)
 
 **Examples**
 
@@ -43,9 +44,7 @@ npx openapi-typescript "specs/**/*.yaml" --output schemas/
 # 🚀 specs/three.yaml -> schemas/specs/three.ts [250ms]
 ```
 
-_Note: if generating a single schema, `--output` must be a file (preferably `*.ts`). If using globs, `--output` must be a directory._
-
-_Thanks to [@sharmarajdaksh](https://github.com/sharmarajdaksh) for the glob feature!_
+_Thanks, [@sharmarajdaksh](https://github.com/sharmarajdaksh)!_
 
 #### ☁️ Reading specs from remote resource
 
@@ -56,9 +55,9 @@ npx openapi-typescript https://petstore3.swagger.io/api/v3/openapi.yaml --output
 # 🚀 https://petstore3.swagger.io/api/v3/openapi.yaml -> petstore.d.ts [650ms]
 ```
 
-_Thanks to [@psmyrdek](https://github.com/psmyrdek) for the remote spec feature!_
+_Thanks, [@psmyrdek](https://github.com/psmyrdek)!_
 
-#### Using in TypeScript
+#### 🟦 Using in TypeScript
 
 Import any top-level item from the generated spec to use it. It works best if you also alias types to save on typing:
 
@@ -70,7 +69,7 @@ type APIResponse = components["schemas"]["APIResponse"];
 
 Because OpenAPI schemas may have invalid TypeScript characters as names, the square brackets are a safe way to access every property.
 
-##### Operations
+##### 🏗️ Operations
 
 Operations can be imported directly by their [operationId](https://spec.openapis.org/oas/latest.html#operation-object):
 
@@ -80,9 +79,9 @@ import { operations } from "./generated-schema.ts";
 type getUsersById = operations["getUsersById"];
 ```
 
-_Thanks to [@gr2m](https://github.com/gr2m) for the operations feature!_
+_Thanks, [@gr2m](https://github.com/gr2m)!_
 
-#### openapi-typescript-fetch
+#### ⚾ openapi-typescript-fetch
 
 The generated spec can also be used with [openapi-typescript-fetch](https://www.npmjs.com/package/openapi-typescript-fetch) which implements a typed fetch client for openapi-typescript.
 
@@ -132,31 +131,96 @@ try {
 
 #### Outputting to stdout
 
-Simply omit the `--output` flag to return to stdout:
+Omit the `--output` flag to return to stdout:
 
 ```bash
 npx openapi-typescript schema.yaml
 ```
 
-#### CLI Options
-
-| Option                         | Alias | Default  | Description                                                                                                                             |
-| :----------------------------- | :---- | :------: | :-------------------------------------------------------------------------------------------------------------------------------------- |
-| `--output [location]`          | `-o`  | (stdout) | Where should the output file be saved?                                                                                                  |
-| `--auth [token]`               |       |          | (optional) Provide an auth token to be passed along in the request (only if accessing a private schema)                                 |
-| `--header`                     | `-x`  |          | (optional) Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the `key: value` pattern |
-| `--headersObject`              | `-h`  |          | (optional) Provide a JSON object as string of HTTP headers for remote schema request. This will take priority over `--header`           |
-| `--httpMethod`                 | `-m`  | `GET`    | (optional) Provide the HTTP Verb/Method for fetching a schema from a remote URL                                                         |
-| `--immutable-types`            | `-it` | `false`  | (optional) Generates immutable types (readonly properties and readonly array)                                                           |
-| `--additional-properties`      | `-ap` | `false`  | (optional) Allow arbitrary properties for all schema objects without `additionalProperties: false`                                      |
-| `--default-non-nullable`       |       | `false`  | (optional) Treat schema objects with default values as non-nullable                                                                     |
-| `--prettier-config [location]` | `-c`  |          | (optional) Path to your custom Prettier configuration for output                                                                        |
-| `--export-type`                |       | `false`  | (optional) Export `type` instead of `interface`                                                                                         |
-| `--support-array-length`       |       | `false`  | (optional) Generate tuples using array minItems / maxItems                                                                              |
-| `--make-paths-enum`            | `-pe` | `false`  | (optional) Generate an enum of endpoint paths                                                                                           |
-| `--path-params-as-types`       |       | `false`  | (optional) Substitute path parameter names with their respective types                                                                  |
-| `--alphabetize`                |       | `false`  | (optional) Sort types alphabetically                                                                                                    |
-| `--raw-schema`                 |       | `false`  | Generate TS types from partial schema (e.g. having `components.schema` at the top level)                                                |
+### Options
+
+The following flags can be appended to the CLI command.
+
+| Option                         | Alias | Default  | Description                                                                                                                  |
+| :----------------------------- | :---- | :------: | :--------------------------------------------------------------------------------------------------------------------------- |
+| `--output [location]`          | `-o`  | (stdout) | Where should the output file be saved?                                                                                       |
+| `--auth [token]`               |       |          | Provide an auth token to be passed along in the request (only if accessing a private schema)                                 |
+| `--header`                     | `-x`  |          | Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the `key: value` pattern |
+| `--headersObject`              | `-h`  |          | Provide a JSON object as string of HTTP headers for remote schema request. This will take priority over `--header`           |
+| `--httpMethod`                 | `-m`  | `GET`    | Provide the HTTP Verb/Method for fetching a schema from a remote URL                                                         |
+| `--immutable-types`            |       | `false`  | Generates immutable types (readonly properties and readonly array)                                                           |
+| `--additional-properties`      |       | `false`  | Allow arbitrary properties for all schema objects without `additionalProperties: false`                                      |
+| `--default-non-nullable`       |       | `false`  | Treat schema objects with default values as non-nullable                                                                     |
+| `--export-type`                | `-t`  | `false`  | Export `type` instead of `interface`                                                                                         |
+| `--path-params-as-types`       |       | `false`  | Allow dynamic string lookups on the `paths` object                                                                           |
+| `--support-array-length`       |       | `false`  | Generate tuples using array `minItems` / `maxItems`                                                                          |
+| `--alphabetize`                |       | `false`  | Sort types alphabetically                                                                                                    |
+
+#### `--path-params-as-types`
+
+By default, your URLs are preserved exactly as-written in your schema:
+
+```ts
+export interface paths {
+  '/user/{user_id}': components["schemas"]["User"];
+}
+```
+
+Which means your type lookups also have to match the exact URL:
+
+```ts
+import { paths } from './my-schema';
+
+const url = `/user/${id}`;
+type UserResponses = paths['/user/{user_id}']['responses'];
+```
+
+But when `--path-params-as-types` is enabled, you can take advantage of dynamic lookups like so:
+
+```ts
+import { paths } from './my-schema';
+
+const url = `/user/${id}`;
+type UserResponses = paths[url]['responses']; // automatically matches `paths['/user/{user_id}']`
+```
+
+Though this is a contrived example, you could use this feature to automatically infer typing based on the URL in a fetch client or in some other useful place in your application.
+
+_Thanks, [@Powell-v2](https://github.com/Powell-v2)!_
+
+#### `--support-array-length`
+
+This option is useful for generating tuples if an array type specifies `minItems` or `maxItems`.
+
+For example, given the following schema:
+
+```yaml
+components:
+  schemas:
+    TupleType
+      type: array
+      items:
+        type: string
+      minItems: 1
+      maxItems: 2
+```
+
+Enabling `--support-array-length` would change the typing like so:
+
+```diff
+  export interface components {
+    schemas: {
+-     TupleType: string[];
++     TupleType: [string] | [string, string];
+    };
+  }
+```
+
+This results in more explicit typechecking of array lengths.
+
+_Note: this has a reasonable limit, so for example `maxItems: 100` would simply flatten back down to `string[];`_
+
+_Thanks, [@kgtkr](https://github.com/kgtkr)!_
 
 ### 🐢 Node
 

README.md

@@ -24,7 +24,6 @@ Options
   --content-never              (optional) If supplied, an omitted reponse \`content\` property will be generated as \`never\` instead of \`unknown\`
   --additional-properties, -ap (optional) Allow arbitrary properties for all schema objects without "additionalProperties: false"
   --default-non-nullable       (optional) If a schema object has a default value set, don’t mark it as nullable
-  --prettier-config, -c        (optional) specify path to Prettier config file
   --raw-schema                 (optional) Parse as partial schema (raw components)
   --paths-enum, -pe            (optional) Generate an enum containing all API paths.
   --export-type                (optional) Export type instead of interface
@@ -38,6 +37,7 @@ const OUTPUT_FILE = "FILE";
 const OUTPUT_STDOUT = "STDOUT";
 const CWD = new URL(`file://${process.cwd()}/`);
 const EXT_RE = /\.[^.]+$/i;
+const HTTP_RE = /^https?:\/\//;
 
 const timeStart = process.hrtime();
 
@@ -53,24 +53,20 @@ const flags = parser(args, {
     "defaultNonNullable",
     "immutableTypes",
     "contentNever",
-    "rawSchema",
     "exportType",
     "supportArrayLength",
-    "makePathsEnum",
     "pathParamsAsTypes",
     "alphabetize",
   ],
   number: ["version"],
-  string: ["auth", "header", "headersObject", "httpMethod", "prettierConfig"],
+  string: ["auth", "header", "headersObject", "httpMethod"],
   alias: {
     additionalProperties: ["ap"],
     header: ["x"],
     headersObject: ["h"],
     httpMethod: ["m"],
     immutableTypes: ["it"],
     output: ["o"],
-    prettierConfig: ["c"],
-    makePathsEnum: ["pe"],
   },
   default: {
     httpMethod: "GET",
@@ -103,9 +99,6 @@ async function generateSchema(pathToSpec) {
     auth: flags.auth,
     defaultNonNullable: flags.defaultNonNullable,
     immutableTypes: flags.immutableTypes,
-    prettierConfig: flags.prettierConfig,
-    rawSchema: flags.rawSchema,
-    makePathsEnum: flags.makePathsEnum,
     contentNever: flags.contentNever,
     silent: output === OUTPUT_STDOUT,
     version: flags.version,
@@ -156,13 +149,8 @@ async function main() {
     console.info(`✨ ${BOLD}openapi-typescript ${packageJSON.version}${RESET}`); // only log if we’re NOT writing to stdout
   }
 
-  // error: --raw-schema
-  if (flags.rawSchema && !flags.version) {
-    throw new Error(`--raw-schema requires --version flag`);
-  }
-
   // handle remote schema, exit
-  if (/^https?:\/\//.test(pathToSpec)) {
+  if (HTTP_RE.test(pathToSpec)) {
     if (output !== "." && output === OUTPUT_FILE) fs.mkdirSync(outputDir, { recursive: true });
     await generateSchema(pathToSpec);
     return;