oazapfts 4.3.3 → 4.4.1

package/README.md

@@ -4,13 +4,16 @@
 
 Generate TypeScript clients to tap into OpenAPI servers.
 
+![](https://avatars.githubusercontent.com/u/119607625?s=200&v=4)
+
 ## Features
 
 - **AST-based**:
   Unlike other code generators `oazapfts` does not use templates to generate code but uses TypeScript's built-in API to generate and pretty-print an abstract syntax tree.
-- **Fast**: The cli does not use any of the common Java-based tooling, so the code generation is super fast.
+- **Fast**: The CLI does not use any of the common Java-based tooling, so the code generation is super fast.
+- **Single file**: All functions and types are co-located in one single self-contained file.
 - **Tree-shakeable**: Individually exported functions allow you to bundle only the ones you actually use.
-- **Human friendly signatures**: The generated api methods don't leak an HTTP-specific implementation details. For example, all optional parameters are grouped together in one object, no matter whether they end up in the headers, path or query-string.
+- **Human friendly signatures**: The generated API methods don't leak any HTTP-specific implementation details. For example, all optional parameters are grouped together in one object, no matter whether they end up in the headers, path or query-string.
 
 ## Installation
 
@@ -18,7 +21,8 @@ Generate TypeScript clients to tap into OpenAPI servers.
 npm install oazapfts
 ```
 
-**NOTE:** With version 3.0.0 oazapfts has become a runtime dependency and the generated code does no longer include all the fetch logic.
+> **Note**
+> With version 3.0.0 oazapfts has become a runtime dependency and the generated code does no longer include all the fetch logic.
 
 ## Usage
 
@@ -36,36 +40,64 @@ Where `<spec>` is the URL or local path of an OpenAPI or Swagger spec (in either
 
 Use the `useEnumType` option to generate typescript enums instead of union of values.
 
-## Overriding the defaults
+## Consuming the generated API
 
-The generated file exports a `defaults` constant that can be used to override the `basePath`, provide a custom `fetch` implementation or to send additional headers with each request:
+For each operation defined in the spec the generated API will export a function with a name matching the `operationId`. If no ID is specified, a reasonable name is generated from the HTTP verb and the path.
 
 ```ts
-import * as api from "./api.ts";
-import nodeFetch from "node-fetch";
+import * as api from "./my-generated-api.ts";
+const res = api.getPetById(1);
+```
 
-api.default.basePath = "https://example.com/api";
+> **Note**
+> If your API is large, and you want to take advantage of tree-shaking to exclude unused code, use individual named imports instead:
 
-api.defaults.headers = {
-  access_token: "secret",
-};
+```ts
+import { getPetById } from "./my-generated-api.ts";
+```
 
-api.defaults.fetch = nodeFetch;
+## Fetch options
+
+The **last argument** of each function is an optional [`RequestOpts`](https://github.com/oazapfts/oazapfts/blob/27b296c6fc28fec4869f1b7e1a4a5585ebbd5ee9/src/runtime/index.ts#L5) object that can be used to pass options to the `fetch` call, for example to pass additional `headers` or an `AbortSignal` to cancel the request later on.
+
+```ts
+const res = getPetById(1, {
+  credentials: "include",
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+});
 ```
 
-## Consuming the generated API
+You can also use this to override the default `baseUrl` or to provide a custom `fetch` implementation.
+
+> **Note**
+> Instead of passing custom options to each function call, consider [overwriting the global defaults](#overriding-the-defaults).
+
+## Optimistic vs. explicit responses
+
+Oazapfts supports two different modes to handle results,
+an [explicit](#explicit-mode) mode (the default) and an [optimistic](#optimistic-mode) mode, that makes the response handling less verbose.
+
+## Explicit mode
+
+By default, each function returns an `ApiResponse` object that exposes the `status` code, response `headers` and the `data`.
 
-For each operation defined in the spec the generated API will export a function with a name matching the `operationId`. If no id is specified, a reasonable name is generated from the HTTP verb and the path.
+> **Note**
+> This mode is best suited for APIs that return different types for different response codes or APIs where you need to access not only the response body, but also the response headers. If your API is simple, and you don't need this flexibility, consider using the [optimistic mode](#optimistic-mode) instead.
 
-The **last argument** of each function is an optional `RequestOpts` object that can be used to pass options to the `fetch` call, for example to pass additional headers or an `AbortSignal` to cancel the request later on.
+In explicit mode, each function returns a Promise for an `ApiResponse` which is an object with a `status` and a `data` property, holding the HTTP status code and the properly typed data from the response body.
 
-Each function **returns** a Promise for an `ApiResponse` which is an object with a `status` and a `data` property, holding the HTTP status code and the properly typed data from the response body. Since an operation can return different types depending on the status code, the actual return type is a _union_ of all possible responses, discriminated by their status.
+Since an operation can return different types depending on the status code, the actual return type is a _union_ of all possible responses, discriminated by their status.
 
 Consider the following code generated from the `petstore.json` example:
 
 ```ts
-export function getPetById(petId: number, opts?: RequestOpts) {
-  return fetchJson<
+/**
+ * Find pet by ID
+ */
+export function getPetById(petId: number, opts?: Oazapfts.RequestOpts) {
+  return oazapfts.fetchJson<
     | {
         status: 200;
         data: Pet;
@@ -76,15 +108,14 @@ export function getPetById(petId: number, opts?: RequestOpts) {
       }
     | {
         status: 404;
-        data: string;
       }
-  >(`/pet/${petId}`, {
+  >(`/pet/${encodeURIComponent(petId)}`, {
     ...opts,
   });
 }
 ```
 
-In this case the `data` property is typed as `Pet|string`. We can use a type guard to narrow down the type to `Pet`:
+In this case, the `data` property is typed as `Pet|string`. We can use a type guard to narrow down the type to `Pet`:
 
 ```ts
 const res = await api.getPetById(1);
@@ -115,7 +146,7 @@ await handle(api.getPetById(1), {
 });
 ```
 
-The helper will throw an `HttpError` error for any unhanled status code unless you add a `default` handler:
+The helper will throw an `HttpError` error for any unhandled status code, unless you add a `default` handler:
 
 ```ts
 await handle(api.getPetById(1), {
@@ -128,9 +159,26 @@ await handle(api.getPetById(1), {
 });
 ```
 
-## Optimistic APIs
+## Optimistic mode
+
+You can opt into the _optimistic mode_ by using the `--optimistic` command line argument.
+
+In this mode, each function will return a Promise for the happy path, i.e. the type specified for the first `2xx` response.
+
+Looking back at our Pet Store example from above, consuming the response is now much easier and less verbose:
+
+```ts
+const pet = await api.getPetById(1);
+// pet is now typed as Pet!
+```
+
+In case of a response other than `200` the promise will be rejected with a `HttpError`.
 
-Instead of handling errors right in place we can also use the `ok` helper:
+## Mixing both modes
+
+Sometimes you might want to use the optimistic mode for some of your API calls, but need the full `ApiResponse` for others.
+
+In that case, you can use the `ok`-helper function to selectively apply optimistic response handling:
 
 ```ts
 import { ok } from "oazapfts";
@@ -138,21 +186,34 @@ import { ok } from "oazapfts";
 const pet = await ok(api.getPetById(1));
 ```
 
-With this pattern `pet` will be typed as `Pet` and a `HttpError` will be thrown in case of an error.
+## Overriding the defaults
 
-You can even turn your whole API into an optimistic one:
+The generated file exports a `defaults` constant that can be used to override the `basePath`, provide a custom `fetch` implementation or to send additional `headers` with each request. Basically, you can set a default for any [fetch option](https://developer.mozilla.org/en-US/docs/Web/API/fetch#options) you want.
 
 ```ts
-import { optimistic } from "oazapfts";
-import * as rawApi from "./api.ts";
+import * as api from "./api.ts";
+import nodeFetch from "node-fetch";
 
-const api = optimistic(rawApi);
-const pet = await api.getPetById(1);
+// Override the spec's basePath
+api.defaults.basePath = "https://example.com/api";
+
+// Send this header with each request
+api.defaults.headers = {
+  access_token: "secret",
+};
+
+// Include credentials in CORS requests, too
+api.defaults.credentials = "include";
+
+// Use this instead of the global fetch
+api.defaults.fetch = nodeFetch;
 ```
 
-### CLI
+## Alternatives and integrations
+
+If this library doesn't fit your needs, take a look at [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen) which follows a similar philosophy but creates many individual files instead of one single self-contained file.
 
-Since version 3.1.0 you can also use the `--optimistic` flag on the command line to generate an optimistic API by default.
+If your frontend uses React, take a look at [react-api-query](https://www.npmjs.com/package/react-api-query) which makes it easy to use an oazapfts client with React hooks in a convenient and type-safe way.
 
 ## About the name
 

package/lib/codegen/generate.d.ts

@@ -3,27 +3,29 @@ import { OpenAPIV3 } from "openapi-types";
 import { Opts } from ".";
 export declare const verbs: string[];
 type ContentType = "json" | "form" | "multipart";
-export declare const contentTypes: Record<string, ContentType>;
+export declare function isMimeType(s: unknown): boolean;
+export declare function isJsonMimeType(mime: string): boolean;
+export declare function getBodyFormatter(body?: OpenAPIV3.RequestBodyObject): ContentType | undefined;
 type SchemaObject = OpenAPIV3.SchemaObject & {
     const?: unknown;
 };
 /**
  * Get the name of a formatter function for a given parameter.
  */
-export declare function getFormatter({ style, explode, }: OpenAPIV3.ParameterObject): "form" | "deep" | "explode" | "space" | "pipe";
+export declare function getFormatter({ style, explode, content, }: OpenAPIV3.ParameterObject): "json" | "form" | "deep" | "explode" | "space" | "pipe";
 export declare function getOperationIdentifier(id?: string): string | undefined;
 /**
  * Create a method name for a given operation, either from its operationId or
  * the HTTP verb and path.
  */
 export declare function getOperationName(verb: string, path: string, operationId?: string): string;
-export declare function isNullable(schema: any): boolean;
-export declare function isReference(obj: any): obj is OpenAPIV3.ReferenceObject;
-export declare function getReference(spec: any, ref: string): any;
+export declare function isNullable(schema?: SchemaObject | OpenAPIV3.ReferenceObject): boolean | undefined;
+export declare function isReference(obj: unknown): obj is OpenAPIV3.ReferenceObject;
 /**
  * If the given object is a ReferenceObject, return the last part of its path.
  */
-export declare function getReferenceName(obj: any): string | undefined;
+export declare function getReferenceName(obj: unknown): string | undefined;
+export declare function toIdentifier(s: string): string;
 /**
  * Create a template string literal from the given OpenAPI urlTemplate.
  * Curly braces in the path are turned into identifier expressions,
@@ -69,12 +71,11 @@ export default class ApiGenerator {
     skip(tags?: string[]): boolean;
     getUniqueAlias(name: string): string;
     getEnumUniqueAlias(name: string, values: string): string;
-    getRefBasename(ref: string): string;
     /**
      * Create a type alias for the schema referenced by the given ReferenceObject
      */
     getRefAlias(obj: OpenAPIV3.ReferenceObject): ts.TypeReferenceNode;
-    getUnionType(variants: (OpenAPIV3.ReferenceObject | SchemaObject)[], discriminator?: OpenAPIV3.DiscriminatorObject): ts.TypeNode;
+    getUnionType(variants: (OpenAPIV3.ReferenceObject | SchemaObject)[], discriminator?: OpenAPIV3.DiscriminatorObject): ts.UnionTypeNode;
     /**
      * Creates a type node from a given schema.
      * Delegates to getBaseTypeFromSchema internally and
@@ -89,7 +90,7 @@ export default class ApiGenerator {
     /**
      * Creates literal type (or union) from an array of values
      */
-    getTypeFromEnum(values: unknown[]): ts.LiteralTypeNode | ts.KeywordTypeNode<ts.KeywordTypeSyntaxKind> | ts.UnionTypeNode;
+    getTypeFromEnum(values: unknown[]): ts.LiteralTypeNode | ts.UnionTypeNode;
     getEnumValuesString(values: string[]): string;
     getTrueEnum(schema: OpenAPIV3.NonArraySchemaObject, propName: string): ts.TypeReferenceNode;
     /**
@@ -97,11 +98,12 @@ export default class ApiGenerator {
      */
     getTypeFromProperties(props: {
         [prop: string]: SchemaObject | OpenAPIV3.ReferenceObject;
-    }, required?: string[], additionalProperties?: boolean | SchemaObject | OpenAPIV3.ReferenceObject): ts.TypeLiteralNode;
+    }, required?: string[], additionalProperties?: boolean | OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject): ts.TypeLiteralNode;
     getTypeFromResponses(responses: OpenAPIV3.ResponsesObject): ts.UnionTypeNode;
     getTypeFromResponse(resOrRef: OpenAPIV3.ResponseObject | OpenAPIV3.ReferenceObject): ts.TypeNode;
     getResponseType(responses?: OpenAPIV3.ResponsesObject): "json" | "text" | "blob";
-    getSchemaFromContent(content: any): any;
+    getSchemaFromContent(content: Record<string, OpenAPIV3.MediaTypeObject>): OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
+    getTypeFromParameter(p: OpenAPIV3.ParameterObject): ts.TypeNode;
     wrapResult(ex: ts.Expression): ts.Expression;
     generateApi(): ts.SourceFile;
 }