apigen-ts 0.0.3 → 0.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "apigen-ts",
-  "version": "0.0.3",
+  "version": "0.1.1",
   "license": "MIT",
   "author": "Vlad Pronsky <v.pronsky@gmail.com>",
   "repository": "vladkens/apigen-ts",
@@ -18,12 +18,11 @@
     "build": "rm -rf dist && pkgroll && cp ./src/_template.ts ./dist && ls -lah dist",
     "test": "uvu -r tsm test '\\.test\\.ts$'",
     "test-cov": "c8 --include=src yarn test",
-    "test-watch": "watchexec -c -e ts 'clear && yarn test'",
     "format": "prettier --write .",
-    "ci": "yarn test-cov && yarn build"
+    "ci": "tsc --noEmit && yarn test-cov && yarn build"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^1.4.1",
+    "@redocly/openapi-core": "^1.6.0",
     "@types/lodash-es": "^4.17.12",
     "@types/swagger2openapi": "^7.0.4",
     "array-utils-ts": "^0.1.2",
@@ -32,8 +31,8 @@
     "swagger2openapi": "^7.0.8"
   },
   "devDependencies": {
-    "@types/node": "^18.18.0",
-    "c8": "^8.0.1",
+    "@types/node": "^20.10.8",
+    "c8": "^9.0.0",
     "fetch-mock": "^9.11.0",
     "pkgroll": "^2.0.1",
     "prettier": "^3.1.0",
@@ -46,10 +45,22 @@
     "prettier": "^3.0.0",
     "typescript": "^5.0.0"
   },
-  "bin": {
-    "apigen-ts": "./dist/cli.js"
-  },
   "files": [
     "dist"
-  ]
+  ],
+  "main": "./dist/main.js",
+  "types": "./dist/main.d.cts",
+  "exports": {
+    "require": {
+      "types": "./dist/main.d.cts",
+      "default": "./dist/main.cjs"
+    },
+    "import": {
+      "types": "./dist/main.d.mts",
+      "default": "./dist/main.mjs"
+    }
+  },
+  "bin": {
+    "apigen-ts": "./dist/cli.js"
+  }
 }

package/readme.md

@@ -1,24 +1,30 @@
-# OpenAPI TypeScript client generator
+# apigen-ts
 
 <div align="center">
 
 [<img src="https://badgen.net/npm/v/apigen-ts" alt="version" />](https://npmjs.org/package/apigen-ts)
-[<img src="https://github.com/vladkens/apigen-ts/workflows/test/badge.svg" alt="test status" />](https://github.com/vladkens/apigen-ts/actions)
 [<img src="https://badgen.net/packagephobia/publish/apigen-ts" alt="size" />](https://packagephobia.now.sh/result?p=apigen-ts)
 [<img src="https://badgen.net/npm/dm/apigen-ts" alt="downloads" />](https://npmjs.org/package/apigen-ts)
 [<img src="https://badgen.net/github/license/vladkens/apigen-ts" alt="license" />](https://github.com/vladkens/apigen-ts/blob/main/LICENSE)
+[<img src="https://badgen.net/static/-/buy%20me%20a%20coffee/ff813f?icon=buymeacoffee&label" alt="donate" />](https://buymeacoffee.com/vladkens)
 
 </div>
 
+<div align="center">
+  <img src="./logo.svg" alt="apigen-ts logo" height="80" />
+  <div>TypeScript client generator from OpenAPI schema</div>
+</div>
+
 ## Features
 
-- Generates ready to use ApiClient with types (using `fetch`)
+- Generates ready to use `ApiClient` with types (using `fetch`)
 - Single output file, minimal third-party code
-- Load schema from JSON / YAML, locally and remote
+- Loads schemas from JSON / YAML, locally and remote
 - Ability to customize `fetch` with your custom function
-- Uses `type` instead of `interface`, so no problem with declaration merging
 - Automatic formating with Prettier
-- Parses dates automatically
+- Can parse dates from date-time format (`--parse-dates` flag)
+- Support OpenAPI v2, v3, v3.1
+- Can be used with npx as well
 
 ## Install
 
@@ -28,20 +34,22 @@ yarn install -D apigen-ts
 
 ## Usage
 
-### Generate
+### 1. Generate
 
 ```sh
 # From url
-yarn apigen-ts https://petstore3.swagger.io/api/v3/openapi.json ./api-generated.ts
+yarn apigen-ts https://petstore3.swagger.io/api/v3/openapi.json ./api-client.ts
 
 # From file
-yarn apigen-ts ./openapi.json ./api-generated.ts
+yarn apigen-ts ./openapi.json ./api-client.ts
 ```
 
-### Import
+Run `yarn apigen-ts --help` for more options. Examples of generated clients [here](./examples/).
+
+### 2. Import
 
-```typescript
-import { ApiClient } from "./api-generated"
+```ts
+import { ApiClient } from "./api-client"
 
 const api = new ApiClient({
   baseUrl: "https://example.com/api",
@@ -49,31 +57,104 @@ const api = new ApiClient({
 })
 ```
 
-### Use
+### 3. Use
 
-```typescript
+```ts
 // GET /pet/{petId}
 await api.pet.getPetById(1) // -> Pet
 
 // GET /pet/findByStatus?status=sold
 await api.pet.findPetsByStatus({ status: "sold" }) // -> Pets[]
 
-// PUT /user/{username}
-await api.user.updateUser("username", { firstName: "John" }) // second arg is body with type User
+// PUT /user/{username}; second arg body with type User
+await api.user.updateUser("username", { firstName: "John" })
 ```
 
 ## Advanced
 
 ### Login flow
 
-```typescript
+```ts
 const { token } = await api.auth.login({ usename, password })
 api.Config.headers = { Authorization: token }
 
 await api.protectedRoute.get() // here authenticated
 ```
 
-## Useful for development
+### Automatic date parsing
+
+```sh
+yarn apigen-ts ./openapi.json ./api-client.ts --parse-dates
+```
+
+```ts
+const pet = await api.pet.getPetById(1)
+const createdAt: Date = pet.createdAt // date parsed from string with format=date-time
+```
+
+### Errors handling
+
+An exception will be thrown for all unsuccessful return codes.
+
+```ts
+try {
+  const pet = await api.pet.getPetById(404)
+} catch (e) {
+  console.log(e) // parse error depend of your domain model, e is awaited response.json()
+}
+```
+
+Also you can define custom function to parse error:
+
+```ts
+class MyClient extends ApiClient {
+  async ParseError(rep: Response) {
+    // do what you want
+    return { code: "API_ERROR" }
+  }
+}
+
+try {
+  const api = MyClient()
+  const pet = await api.pet.getPetById(404)
+} catch (e) {
+  console.log(e) // e is { code: "API_ERROR" }
+}
+```
+
+### Node.js API
+
+Create file like `apigen.mjs` with content:
+
+```js
+import { apigen } from "apigen-ts"
+
+await apigen({
+  source: "https://petstore3.swagger.io/api/v3/openapi.json",
+  output: "./api-client.ts",
+  // everything below is optional
+  name: "MyApiClient", // default "ApiClient"
+  parseDates: true, // default false
+  resolveName(ctx, op, proposal) {
+    // proposal is [string, string] which represents module.funcName
+    if (proposal[0] === "users") return // will use default proposal
+
+    const [a, b] = op.name.split("/").slice(3, 5) // eg. /api/v1/store/items/search
+    return [a, `${op.method}_${b}`] // [store, 'get_items'] -> apiClient.store.get_items()
+  },
+})
+```
+
+Then run with: `node apigen.mjs`
+
+## Compare
+
+- [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen) ([npm](https://www.npmjs.com/package/openapi-typescript-codegen)): no single file mode [#1263](https://github.com/ferdikoomen/openapi-typescript-codegen/issues/1263#issuecomment-1502890838)
+- [openapi-typescript](https://github.com/drwpow/openapi-typescript) ([npm](https://www.npmjs.com/package/openapi-typescript)): low level api; no named types export to use in client code
+- [openapi-generator-cli](https://github.com/OpenAPITools/openapi-generator-cli) ([npm](https://www.npmjs.com/package/@openapitools/openapi-generator-cli)): wrapper around java lib
+- [swagger-typescript-api](https://github.com/acacode/swagger-typescript-api) ([npm](https://www.npmjs.com/package/swagger-typescript-api)): complicated configuration; user-api breaking changes between versions
+
+## Development
 
 - https://ts-ast-viewer.com
 - https://jsonschemalint.com