@lyku/lockstep-client-ts

Generate fully-typed TypeScript HTTP clients from TsonSchema-based API definitions.

Overview

This package 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).

Installation

npm install @lyku/lockstep-client-ts

Requires @lyku/lockstep-core as a peer dependency for schema-to-type conversion.

API

generateTsClient(options: GenerateTsClientOptions): Promise<void>

Generates a TypeScript client file in the specified output directory.

import { generateTsClient } from '@lyku/lockstep-client-ts';
import { valhallaModels } from '@myapp/api-models';

await generateTsClient({
	models: valhallaModels,
	name: 'Valhalla',
	outputDir: './dist/libs/valhalla-client',
});

Options

| Option | Type | Required | Description | | ---------------- | ------------------------ | -------- | --------------------------------------------------------------- | | models | ExternalApiSpec | Yes | Record of endpoint names to ExternalApiModel definitions | | name | string | Yes | Client name (e.g., 'Valhalla'), used for generated type names | | outputDir | string | Yes | Directory to write index.ts into | | paramMapping | Record<string, string> | No | Map camelCase params to API-specific formats (e.g., dotted) | | apiKeyParam | string | No | Query parameter name for API key injection | | customMethods | Record<string, string> | No | Custom method implementations for complex endpoints | | defaultHeaders | Record<string, string> | No | Headers included in every request | | format | boolean | No | Format with Prettier (default: true) | | errorClassName | string | No | Custom error class name (default: ${Name}Error) | | cjs | boolean | No | Generate CommonJS output (default: false) |

validateApiSpec(spec: ExternalApiSpec): string[]

Validates an API specification and returns an array of error messages (empty if valid).

import { validateApiSpec } from '@lyku/lockstep-client-ts';

const errors = validateApiSpec(myModels);
if (errors.length > 0) {
	console.error('Invalid spec:', errors);
}

Key Types

type ExternalApiModel = {
	method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
	path: string;
	request?: TsonSchema;
	queryParams?: TsonSchema;
	pathParams?: readonly string[];
	response?: TsonSchema;
	authenticated?: boolean;
	description?: string;
};

type ExternalApiSpec = Record<string, ExternalApiModel>;

Generated Output

For a client named Valhalla, the generated index.ts contains:

• Request/Response types for every endpoint (e.g., RouteRequest, RouteResponse)
• Type map (ValhallaTypes) mapping endpoint names to their request/response pairs
• Error class (ValhallaError) extending Error with status code and body
• Client factory (createValhallaClient()) returning an object with typed methods for each endpoint
• Client type (ValhallaClient) inferred from the factory return type

The generated client uses fetch with AbortController for timeout support and handles JSON serialization/deserialization automatically.

Where it fits

Dependencies

• @lyku/lockstep-core (peer) -- schema-to-TypeScript-type conversion via tsonToType
• prettier -- optional output formatting

License

GPL-3.0