@lyku/lockstep-client-ts 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +100 -0
  2. package/package.json +39 -0
package/README.md ADDED
@@ -0,0 +1,100 @@
1
+ # ts-codegen
2
+
3
+ Generate fully-typed TypeScript HTTP clients from TsonSchema-based API definitions.
4
+
5
+ ## Overview
6
+
7
+ `ts-codegen` takes a set of external API model definitions (request/response schemas, HTTP methods, path patterns) and produces a complete, self-contained TypeScript HTTP client file. It is used within the Lyku monorepo to generate typed clients for third-party APIs such as Valhalla (routing), Pelias (geocoding), TomTom (maps), and OTP (transit).
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ npm install ts-codegen
13
+ # or as a workspace dependency
14
+ pnpm add ts-codegen
15
+ ```
16
+
17
+ Requires `@lyku/lockstep-core` as a peer dependency for schema-to-type conversion.
18
+
19
+ ## API
20
+
21
+ ### `generateTsClient(options: GenerateTsClientOptions): Promise<void>`
22
+
23
+ Generates a TypeScript client file in the specified output directory.
24
+
25
+ ```typescript
26
+ import { generateTsClient } from 'ts-codegen';
27
+ import { valhallaModels } from '@lyku/valhalla-models';
28
+
29
+ await generateTsClient({
30
+ models: valhallaModels,
31
+ name: 'Valhalla',
32
+ outputDir: './dist/libs/valhalla-handles-ts',
33
+ });
34
+ ```
35
+
36
+ #### Options
37
+
38
+ | Option | Type | Required | Description |
39
+ | ---------------- | ------------------------ | -------- | --------------------------------------------------------------- |
40
+ | `models` | `ExternalApiSpec` | Yes | Record of endpoint names to `ExternalApiModel` definitions |
41
+ | `name` | `string` | Yes | Client name (e.g., `'Valhalla'`), used for generated type names |
42
+ | `outputDir` | `string` | Yes | Directory to write `index.ts` into |
43
+ | `paramMapping` | `Record<string, string>` | No | Map camelCase params to API-specific formats (e.g., dotted) |
44
+ | `apiKeyParam` | `string` | No | Query parameter name for API key injection |
45
+ | `customMethods` | `Record<string, string>` | No | Custom method implementations for complex endpoints |
46
+ | `defaultHeaders` | `Record<string, string>` | No | Headers included in every request |
47
+ | `format` | `boolean` | No | Format with Prettier (default: `true`) |
48
+ | `errorClassName` | `string` | No | Custom error class name (default: `${Name}Error`) |
49
+ | `cjs` | `boolean` | No | Generate CommonJS output (default: `false`) |
50
+
51
+ ### `validateApiSpec(spec: ExternalApiSpec): string[]`
52
+
53
+ Validates an API specification and returns an array of error messages (empty if valid).
54
+
55
+ ```typescript
56
+ import { validateApiSpec } from 'ts-codegen';
57
+
58
+ const errors = validateApiSpec(myModels);
59
+ if (errors.length > 0) {
60
+ console.error('Invalid spec:', errors);
61
+ }
62
+ ```
63
+
64
+ ### Key Types
65
+
66
+ ```typescript
67
+ type ExternalApiModel = {
68
+ method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
69
+ path: string;
70
+ request?: TsonSchema;
71
+ queryParams?: TsonSchema;
72
+ pathParams?: readonly string[];
73
+ response?: TsonSchema;
74
+ authenticated?: boolean;
75
+ description?: string;
76
+ };
77
+
78
+ type ExternalApiSpec = Record<string, ExternalApiModel>;
79
+ ```
80
+
81
+ ## Generated Output
82
+
83
+ For a client named `Valhalla`, the generated `index.ts` contains:
84
+
85
+ - **Request/Response types** for every endpoint (e.g., `RouteRequest`, `RouteResponse`)
86
+ - **Type map** (`ValhallaTypes`) mapping endpoint names to their request/response pairs
87
+ - **Error class** (`ValhallaError`) extending `Error` with status code and body
88
+ - **Client factory** (`createValhallaClient()`) returning an object with typed methods for each endpoint
89
+ - **Client type** (`ValhallaClient`) inferred from the factory return type
90
+
91
+ The generated client uses `fetch` with `AbortController` for timeout support and handles JSON serialization/deserialization automatically.
92
+
93
+ ## Dependencies
94
+
95
+ - `@lyku/lockstep-core` (peer) -- schema-to-TypeScript-type conversion via `tsonToType`
96
+ - `prettier` -- optional output formatting
97
+
98
+ ## License
99
+
100
+ GPL-3.0
package/package.json ADDED
@@ -0,0 +1,39 @@
1
+ {
2
+ "name": "@lyku/lockstep-client-ts",
3
+ "version": "1.0.0",
4
+ "description": "Generate fully-typed TypeScript HTTP clients from TsonSchema-based API definitions",
5
+ "type": "module",
6
+ "main": "./index.js",
7
+ "types": "./index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./index.d.ts",
11
+ "import": "./index.js",
12
+ "require": "./index.cjs"
13
+ }
14
+ },
15
+ "files": [
16
+ "index.js",
17
+ "index.cjs",
18
+ "index.d.ts"
19
+ ],
20
+ "keywords": [
21
+ "typescript",
22
+ "codegen",
23
+ "api-client",
24
+ "http-client",
25
+ "openapi",
26
+ "tson",
27
+ "lockstep",
28
+ "type-safe"
29
+ ],
30
+ "author": "Lyku",
31
+ "license": "GPL-3.0",
32
+ "dependencies": {
33
+ "prettier": "^3.0.0"
34
+ },
35
+ "devDependencies": {
36
+ "typescript": "^5.0.0"
37
+ },
38
+ "module": "./src/index.js"
39
+ }