@swimmesberger/elarion-jsonrpc-client-generator 0.1.0-preview.10.1

package/README.md

@@ -0,0 +1,58 @@
+# @swimmesberger/elarion-jsonrpc-client-generator
+
+Generate TypeScript RPC method contracts, Zod result schemas, and a portable fetch-based JSON-RPC client from an Elarion `rpc-schema.json` export.
+
+```bash
+npm install --save-dev @swimmesberger/elarion-jsonrpc-client-generator
+npx elarion-jsonrpc-client-generator --schema rpc-schema.json --out src/generated
+```
+
+The generated files are:
+
+| File | Purpose |
+| --- | --- |
+| `rpc-types.ts` | `RpcMethods` interface mapping method names to params/result types. |
+| `rpc-schemas.ts` | `rpcResultSchemas` Zod map for runtime result validation. |
+| `rpc-client.ts` | Browser/Node.js fetch client with typed single calls, batching, headers, `AbortSignal`, JSON-RPC errors, and Zod-backed result validation. |
+
+The generated schema and client files import `zod`, so consuming applications should install `zod` as a runtime dependency.
+
+## Generated API client
+
+```ts
+import { createRpcApi } from './generated/rpc-client'
+
+const rpc = createRpcApi({
+  url: '/rpc',
+  headers: { Authorization: `Bearer ${token}` },
+})
+
+const abort = new AbortController()
+const client = await rpc.clients.get({ id: clientId }, { signal: abort.signal })
+```
+
+The generated API mirrors dotted JSON-RPC method names as nested properties, so `clients.get` becomes `rpc.clients.get(...)`. The file also exports the lower-level `createRpcClient(...)` generic transport for advanced cases.
+
+The API client uses `globalThis.fetch` in browsers and modern Node.js. Pass `fetch` explicitly for tests, older Node.js runtimes, server-function forwarding, or framework-specific transport wrappers:
+
+```ts
+const rpc = createRpcApi({
+  url: process.env.API_INTERNAL_URL + '/rpc',
+  fetch,
+  headers: async ({ batch, methods }) => ({
+    'X-RPC-Batch': String(batch),
+    'X-RPC-Methods': methods.join(','),
+  }),
+})
+```
+
+Batching uses generated request builders, so params and results stay tied to each RPC method. Batch results preserve input order even when the server returns JSON-RPC responses out of order. Each item returns either `{ ok: true, result }` or `{ ok: false, error }`, so one method failure does not reject the whole batch:
+
+```ts
+const [clientResult, projectsResult] = await rpc.$batch([
+  rpc.$request.clients.get({ id: clientId }),
+  rpc.$request.projects.list({ clientId }),
+] as const)
+```
+
+Result validation is enabled by default through `rpcResultSchemas`. Use `transformResult` for app-specific normalization before validation, or set `validateResults: false` when another layer validates responses.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { generateRpcClientFiles } from './generate.js';
+function parseArgs(argv) {
+    const options = {
+        schemaPath: 'rpc-schema.json',
+        outDir: 'src/generated',
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        const next = argv[index + 1];
+        if (arg === '--help' || arg === '-h') {
+            printHelp();
+            process.exit(0);
+        }
+        if (!next) {
+            throw new Error(`Missing value for ${arg}`);
+        }
+        if (arg === '--schema') {
+            options.schemaPath = next;
+            index += 1;
+            continue;
+        }
+        if (arg === '--out') {
+            options.outDir = next;
+            index += 1;
+            continue;
+        }
+        if (arg === '--types') {
+            options.typesFileName = next;
+            index += 1;
+            continue;
+        }
+        if (arg === '--schemas') {
+            options.schemasFileName = next;
+            index += 1;
+            continue;
+        }
+        if (arg === '--client') {
+            options.clientFileName = next;
+            index += 1;
+            continue;
+        }
+        if (arg === '--source-label') {
+            options.sourceLabel = next;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown argument ${arg}`);
+    }
+    return options;
+}
+function printHelp() {
+    console.log(`Usage: elarion-jsonrpc-client-generator [options]
+
+Options:
+  --schema <path>       Path to rpc-schema.json (default: rpc-schema.json)
+  --out <dir>           Output directory (default: src/generated)
+  --types <file>        TypeScript types filename (default: rpc-types.ts)
+  --schemas <file>      Zod schemas filename (default: rpc-schemas.ts)
+  --client <file>       Fetch client filename (default: rpc-client.ts)
+  --source-label <text> Source label written into generated file headers
+`);
+}
+function main() {
+    const options = parseArgs(process.argv.slice(2));
+    const schemaPath = resolve(process.cwd(), options.schemaPath);
+    const outDir = resolve(process.cwd(), options.outDir);
+    const raw = readFileSync(schemaPath, 'utf-8');
+    const schema = JSON.parse(raw);
+    const generated = generateRpcClientFiles(schema, {
+        sourceLabel: options.sourceLabel ?? basename(schemaPath),
+        typesFileName: options.typesFileName,
+        schemasFileName: options.schemasFileName,
+        clientFileName: options.clientFileName,
+    });
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(resolve(outDir, generated.typesFileName), generated.typesSource, 'utf-8');
+    writeFileSync(resolve(outDir, generated.schemasFileName), generated.schemasSource, 'utf-8');
+    writeFileSync(resolve(outDir, generated.clientFileName), generated.clientSource, 'utf-8');
+    console.log(`[jsonrpc-client-generator] Generated ${generated.methodCount} RPC method types and schemas -> ${outDir}`);
+}
+main();

package/dist/generate.d.ts

@@ -0,0 +1,4 @@
+import type { GeneratedRpcClientFiles, GenerateRpcClientOptions, RpcSchema } from './schema.js';
+export { UnsupportedJsonSchemaError } from './json-schema.js';
+export type { GeneratedRpcClientFiles, GenerateRpcClientOptions, JsonSchema, RpcSchema } from './schema.js';
+export declare function generateRpcClientFiles(schema: RpcSchema, options?: GenerateRpcClientOptions): GeneratedRpcClientFiles;

package/dist/generate.js

@@ -0,0 +1,75 @@
+import { jsonSchemaToTypeScript } from './json-schema-to-ts.js';
+import { jsonSchemaToZod } from './json-schema-to-zod.js';
+import { stripNullable } from './json-schema.js';
+import { generateRpcClientSource } from './rpc-client-source.js';
+const DEFAULT_GENERATED_BY = 'elarion-jsonrpc-client-generator';
+const DEFAULT_SOURCE_LABEL = 'rpc-schema.json';
+const DEFAULT_TYPES_FILE = 'rpc-types.ts';
+const DEFAULT_SCHEMAS_FILE = 'rpc-schemas.ts';
+const DEFAULT_CLIENT_FILE = 'rpc-client.ts';
+export { UnsupportedJsonSchemaError } from './json-schema.js';
+export function generateRpcClientFiles(schema, options = {}) {
+    const generatedBy = options.generatedBy ?? DEFAULT_GENERATED_BY;
+    const sourceLabel = options.sourceLabel ?? DEFAULT_SOURCE_LABEL;
+    const typesFileName = options.typesFileName ?? DEFAULT_TYPES_FILE;
+    const schemasFileName = options.schemasFileName ?? DEFAULT_SCHEMAS_FILE;
+    const clientFileName = options.clientFileName ?? DEFAULT_CLIENT_FILE;
+    const methods = Object.keys(schema.methods).sort();
+    const typesLines = [
+        `// Auto-generated by ${generatedBy} — DO NOT EDIT`,
+        `// Source: ${sourceLabel}`,
+        '',
+        'export interface RpcMethods {',
+    ];
+    for (const method of methods) {
+        const definition = schema.methods[method];
+        const paramsType = jsonSchemaToTypeScript(stripNullable(definition.params), createContext(definition.params, `methods.${method}.params`), 1);
+        const resultType = jsonSchemaToTypeScript(stripNullable(definition.result), createContext(definition.result, `methods.${method}.result`), 1);
+        typesLines.push(`  ${JSON.stringify(method)}: {`);
+        typesLines.push(`    params: ${paramsType}`);
+        typesLines.push(`    result: ${resultType}`);
+        typesLines.push('  }');
+    }
+    typesLines.push('}');
+    typesLines.push('');
+    const schemasLines = [
+        `// Auto-generated by ${generatedBy} — DO NOT EDIT`,
+        `// Source: ${sourceLabel}`,
+        '',
+        "import { z } from 'zod'",
+        '',
+        'export const rpcResultSchemas = {',
+    ];
+    for (const method of methods) {
+        const definition = schema.methods[method];
+        const zodSchema = jsonSchemaToZod(stripNullable(definition.result), createContext(definition.result, `methods.${method}.result`), 1);
+        schemasLines.push(`  ${JSON.stringify(method)}: ${zodSchema},`);
+    }
+    schemasLines.push('} as const');
+    schemasLines.push('');
+    schemasLines.push('export type RpcResultSchemas = typeof rpcResultSchemas');
+    schemasLines.push('');
+    const clientSource = generateRpcClientSource({
+        generatedBy,
+        sourceLabel,
+        typesFileName,
+        schemasFileName,
+        methods,
+    });
+    return {
+        methodCount: methods.length,
+        typesFileName,
+        schemasFileName,
+        clientFileName,
+        typesSource: typesLines.join('\n'),
+        schemasSource: schemasLines.join('\n'),
+        clientSource,
+    };
+}
+function createContext(root, path) {
+    return {
+        root,
+        path,
+        resolvingRefs: new Set(),
+    };
+}

package/dist/json-schema-to-ts.d.ts

@@ -0,0 +1,3 @@
+import type { JsonSchema } from './schema.js';
+import { type SchemaContext } from './json-schema.js';
+export declare function jsonSchemaToTypeScript(schema: JsonSchema, ctx: SchemaContext, indent?: number): string;

package/dist/json-schema-to-ts.js

@@ -0,0 +1,38 @@
+import { baseType, childContext, formatPropertyName, isNullable, resolveSchema, stripNullable, } from './json-schema.js';
+export function jsonSchemaToTypeScript(schema, ctx, indent = 0) {
+    const resolved = resolveSchema(schema, ctx);
+    const pad = '  '.repeat(indent);
+    const nullable = isNullable(resolved);
+    const base = baseType(resolved);
+    if (resolved.enum) {
+        const values = resolved.enum
+            .filter((value) => value !== null)
+            .map((value) => JSON.stringify(value));
+        const union = values.length > 0 ? values.join(' | ') : 'never';
+        return nullable ? `(${union}) | null | undefined` : union;
+    }
+    if (base === 'string') {
+        return nullable ? 'string | null | undefined' : 'string';
+    }
+    if (base === 'number' || base === 'integer') {
+        return nullable ? 'number | null | undefined' : 'number';
+    }
+    if (base === 'boolean') {
+        return nullable ? 'boolean | null | undefined' : 'boolean';
+    }
+    if (base === 'array' && resolved.items) {
+        const itemType = jsonSchemaToTypeScript(stripNullable(resolved.items), childContext(ctx, 'items'), indent);
+        return nullable ? `(${itemType})[] | null | undefined` : `${itemType}[]`;
+    }
+    if (base === 'object' && resolved.properties) {
+        const required = new Set(resolved.required ?? []);
+        const lines = Object.entries(resolved.properties).map(([key, property]) => {
+            const optional = required.has(key) ? '' : '?';
+            const propertyType = jsonSchemaToTypeScript(property, childContext(ctx, `properties.${key}`), indent + 1);
+            return `${pad}  ${formatPropertyName(key)}${optional}: ${propertyType}`;
+        });
+        const objectType = `{\n${lines.join('\n')}\n${pad}}`;
+        return nullable ? `${objectType} | null | undefined` : objectType;
+    }
+    return 'unknown';
+}

package/dist/json-schema-to-zod.d.ts

@@ -0,0 +1,3 @@
+import type { JsonSchema } from './schema.js';
+import { type SchemaContext } from './json-schema.js';
+export declare function jsonSchemaToZod(schema: JsonSchema, ctx: SchemaContext, indent?: number): string;

package/dist/json-schema-to-zod.js

@@ -0,0 +1,50 @@
+import { baseType, childContext, formatPropertyName, isNullable, resolveSchema, stripNullable, } from './json-schema.js';
+export function jsonSchemaToZod(schema, ctx, indent = 0) {
+    const resolved = resolveSchema(schema, ctx);
+    const nullable = isNullable(resolved);
+    const base = baseType(resolved);
+    if (resolved.enum) {
+        const values = resolved.enum.filter((value) => value !== null);
+        const allStrings = values.every((value) => typeof value === 'string');
+        let zodExpression;
+        if (allStrings && values.length > 0) {
+            zodExpression = `z.enum([${values.map((value) => JSON.stringify(value)).join(', ')}])`;
+        }
+        else {
+            const literals = values.map((value) => `z.literal(${JSON.stringify(value)})`);
+            zodExpression = literals.length === 1
+                ? literals[0]
+                : `z.union([${literals.join(', ')}])`;
+        }
+        return nullish(zodExpression, nullable);
+    }
+    if (base === 'string') {
+        return nullish('z.string()', nullable);
+    }
+    if (base === 'number' || base === 'integer') {
+        return nullish('z.number()', nullable);
+    }
+    if (base === 'boolean') {
+        return nullish('z.boolean()', nullable);
+    }
+    if (base === 'array' && resolved.items) {
+        const itemSchema = jsonSchemaToZod(stripNullable(resolved.items), childContext(ctx, 'items'), indent);
+        return nullish(`z.array(${itemSchema})`, nullable);
+    }
+    if (base === 'object' && resolved.properties) {
+        const required = new Set(resolved.required ?? []);
+        const pad = '  '.repeat(indent + 1);
+        const fields = Object.entries(resolved.properties).map(([key, property]) => {
+            let fieldSchema = jsonSchemaToZod(property, childContext(ctx, `properties.${key}`), indent + 1);
+            if (!required.has(key)) {
+                fieldSchema += '.optional()';
+            }
+            return `${pad}${formatPropertyName(key)}: ${fieldSchema},`;
+        });
+        return nullish(`z.object({\n${fields.join('\n')}\n${'  '.repeat(indent)}})`, nullable);
+    }
+    return 'z.unknown()';
+}
+function nullish(expression, nullable) {
+    return nullable ? `${expression}.nullish()` : expression;
+}

package/dist/json-schema.d.ts

@@ -0,0 +1,16 @@
+import type { JsonSchema } from './schema.js';
+export declare class UnsupportedJsonSchemaError extends Error {
+    readonly schemaPath: string;
+    constructor(schemaPath: string, message: string);
+}
+export interface SchemaContext {
+    root: JsonSchema;
+    path: string;
+    resolvingRefs: ReadonlySet<string>;
+}
+export declare function isNullable(schema: JsonSchema): boolean;
+export declare function baseType(schema: JsonSchema): string | undefined;
+export declare function stripNullable(schema: JsonSchema): JsonSchema;
+export declare function resolveSchema(schema: JsonSchema, ctx: SchemaContext): JsonSchema;
+export declare function childContext(ctx: SchemaContext, segment: string): SchemaContext;
+export declare function formatPropertyName(key: string): string;

package/dist/json-schema.js

@@ -0,0 +1,96 @@
+export class UnsupportedJsonSchemaError extends Error {
+    schemaPath;
+    constructor(schemaPath, message) {
+        super(`${schemaPath}: ${message}`);
+        this.schemaPath = schemaPath;
+        this.name = 'UnsupportedJsonSchemaError';
+    }
+}
+export function isNullable(schema) {
+    if (Array.isArray(schema.type)) {
+        return schema.type.includes('null');
+    }
+    if (schema.enum) {
+        return schema.enum.includes(null);
+    }
+    return false;
+}
+export function baseType(schema) {
+    if (Array.isArray(schema.type)) {
+        return schema.type.find((type) => type !== 'null');
+    }
+    return schema.type;
+}
+export function stripNullable(schema) {
+    const copy = { ...schema };
+    if (Array.isArray(copy.type)) {
+        const nonNull = copy.type.filter((type) => type !== 'null');
+        copy.type = nonNull.length === 1 ? nonNull[0] : nonNull;
+    }
+    if (copy.enum) {
+        copy.enum = copy.enum.filter((value) => value !== null);
+    }
+    return copy;
+}
+export function resolveSchema(schema, ctx) {
+    assertSupportedComposition(schema, ctx.path);
+    if (!schema.$ref) {
+        return schema;
+    }
+    if (!schema.$ref.startsWith('#/')) {
+        throw new UnsupportedJsonSchemaError(ctx.path, `only local JSON Pointer $ref values are supported (${schema.$ref})`);
+    }
+    if (ctx.resolvingRefs.has(schema.$ref)) {
+        throw new UnsupportedJsonSchemaError(ctx.path, `cyclic $ref detected (${schema.$ref})`);
+    }
+    const target = resolveJsonPointer(ctx.root, schema.$ref, ctx.path);
+    return resolveSchema(target, {
+        root: ctx.root,
+        path: `${ctx.path}${schema.$ref}`,
+        resolvingRefs: new Set([...ctx.resolvingRefs, schema.$ref]),
+    });
+}
+export function childContext(ctx, segment) {
+    return {
+        root: ctx.root,
+        path: `${ctx.path}.${segment}`,
+        resolvingRefs: ctx.resolvingRefs,
+    };
+}
+export function formatPropertyName(key) {
+    if (/^[A-Za-z_$][\w$]*$/.test(key)) {
+        return key;
+    }
+    return JSON.stringify(key);
+}
+function assertSupportedComposition(schema, path) {
+    if (schema.oneOf) {
+        throw new UnsupportedJsonSchemaError(path, 'oneOf is not supported');
+    }
+    if (schema.anyOf) {
+        throw new UnsupportedJsonSchemaError(path, 'anyOf is not supported');
+    }
+    if (schema.allOf) {
+        throw new UnsupportedJsonSchemaError(path, 'allOf is not supported');
+    }
+}
+function resolveJsonPointer(root, ref, path) {
+    const segments = ref
+        .slice(2)
+        .split('/')
+        .map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'));
+    let current = root;
+    for (const segment of segments) {
+        if (!isObjectRecord(current) || !(segment in current)) {
+            throw new UnsupportedJsonSchemaError(path, `could not resolve $ref ${ref}`);
+        }
+        current = current[segment];
+    }
+    if (!isObjectRecord(current)) {
+        throw new UnsupportedJsonSchemaError(path, `$ref ${ref} does not point to a schema object`);
+    }
+    return current;
+}
+function isObjectRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/rpc-client-source.d.ts

@@ -0,0 +1,9 @@
+interface GenerateRpcClientSourceOptions {
+    generatedBy: string;
+    sourceLabel: string;
+    typesFileName: string;
+    schemasFileName: string;
+    methods: readonly string[];
+}
+export declare function generateRpcClientSource(options: GenerateRpcClientSourceOptions): string;
+export {};

package/dist/rpc-client-source.js

@@ -0,0 +1,465 @@
+export function generateRpcClientSource(options) {
+    const typesImport = moduleSpecifier(options.typesFileName);
+    const schemasImport = moduleSpecifier(options.schemasFileName);
+    const methodTree = buildMethodTree(options.methods);
+    return [
+        `// Auto-generated by ${options.generatedBy} — DO NOT EDIT`,
+        `// Source: ${options.sourceLabel}`,
+        '',
+        `import type { RpcMethods } from '${typesImport}'`,
+        `import { rpcResultSchemas } from '${schemasImport}'`,
+        '',
+        'export type RpcMethod = keyof RpcMethods & string',
+        "export type RpcParams<M extends RpcMethod> = RpcMethods[M]['params']",
+        "export type RpcResult<M extends RpcMethod> = RpcMethods[M]['result']",
+        '',
+        'export type RpcFetchInput = string | URL | Request',
+        'export type RpcHeadersInit = Headers | Record<string, string> | readonly (readonly [string, string])[]',
+        'export type RpcFetch = (input: RpcFetchInput, init?: RequestInit) => Promise<Response>',
+        '',
+        'export interface RpcRequestContext {',
+        '  readonly methods: readonly RpcMethod[]',
+        '  readonly batch: boolean',
+        '}',
+        '',
+        'export type RpcHeaders =',
+        '  | RpcHeadersInit',
+        '  | ((context: RpcRequestContext) => RpcHeadersInit | Promise<RpcHeadersInit>)',
+        '',
+        'export interface RpcClientOptions {',
+        '  readonly url: string | URL',
+        '  readonly fetch?: RpcFetch',
+        '  readonly headers?: RpcHeaders',
+        '  readonly idGenerator?: () => string | number',
+        '  readonly validateResults?: boolean',
+        '  readonly transformResult?: <M extends RpcMethod>(method: M, result: unknown) => unknown',
+        '}',
+        '',
+        'export interface RpcRequestOptions {',
+        '  readonly signal?: AbortSignal',
+        '  readonly headers?: RpcHeadersInit',
+        '}',
+        '',
+        'export interface BatchItem<M extends RpcMethod = RpcMethod> {',
+        '  readonly method: M',
+        '  readonly params: RpcParams<M>',
+        '}',
+        '',
+        'export type BatchItemResult<M extends RpcMethod = RpcMethod> =',
+        '  | { readonly ok: true; readonly result: RpcResult<M> }',
+        '  | { readonly ok: false; readonly error: RpcError }',
+        '',
+        'export type BatchResult<T extends readonly BatchItem[]> = {',
+        '  readonly [K in keyof T]: T[K] extends BatchItem<infer M> ? BatchItemResult<M> : never',
+        '}',
+        '',
+        ...generateApiTypeLines(methodTree),
+        'export interface RpcClient {',
+        '  call<M extends RpcMethod>(',
+        '    method: M,',
+        '    params: RpcParams<M>,',
+        '    options?: RpcRequestOptions',
+        '  ): Promise<RpcResult<M>>',
+        '',
+        '  batch<const T extends readonly BatchItem[]>(',
+        '    items: T,',
+        '    options?: RpcRequestOptions',
+        '  ): Promise<BatchResult<T>>',
+        '}',
+        '',
+        ...generateMethodNameLines(options.methods),
+        'type JsonRpcId = string | number',
+        '',
+        'interface JsonRpcRequestEnvelope<M extends RpcMethod = RpcMethod> {',
+        "  readonly jsonrpc: '2.0'",
+        '  readonly method: M',
+        '  readonly params: RpcParams<M>',
+        '  readonly id: JsonRpcId',
+        '}',
+        '',
+        'interface JsonRpcErrorObject {',
+        '  readonly code: number',
+        '  readonly message: string',
+        '  readonly data?: unknown',
+        '}',
+        '',
+        'interface JsonRpcResponseEnvelope {',
+        '  readonly id?: JsonRpcId | null',
+        '  readonly result?: unknown',
+        '  readonly error?: JsonRpcErrorObject',
+        '}',
+        '',
+        'export class RpcError extends Error {',
+        '  constructor(',
+        '    public readonly code: number,',
+        '    message: string,',
+        '    public readonly data?: unknown',
+        '  ) {',
+        '    super(message)',
+        "    this.name = 'RpcError'",
+        '  }',
+        '',
+        '  get isParseError() {',
+        '    return this.code === -32700',
+        '  }',
+        '',
+        '  get isInvalidRequest() {',
+        '    return this.code === -32600',
+        '  }',
+        '',
+        '  get isMethodNotFound() {',
+        '    return this.code === -32601',
+        '  }',
+        '',
+        '  get isInvalidParams() {',
+        '    return this.code === -32602',
+        '  }',
+        '',
+        '  get isInternalError() {',
+        '    return this.code === -32603',
+        '  }',
+        '}',
+        '',
+        'export class RpcTransportError extends Error {',
+        '  constructor(',
+        '    public readonly status: number,',
+        '    public readonly statusText: string,',
+        '    public readonly body: string',
+        '  ) {',
+        '    super(`RPC transport error: ${status} ${statusText}`.trim())',
+        "    this.name = 'RpcTransportError'",
+        '  }',
+        '}',
+        '',
+        'export class RpcProtocolError extends Error {',
+        '  constructor(message: string) {',
+        '    super(message)',
+        "    this.name = 'RpcProtocolError'",
+        '  }',
+        '}',
+        '',
+        'export function createRpcApi(options: RpcClientOptions): RpcApi {',
+        '  const client = createRpcClient(options)',
+        '  const calls: Record<string, unknown> = {}',
+        '  const requests: Record<string, unknown> = {}',
+        '',
+        '  for (const method of rpcMethodNames) {',
+        '    setApiPath(calls, method, (params: unknown, requestOptions?: RpcRequestOptions) =>',
+        '      client.call(method, params as RpcParams<typeof method>, requestOptions))',
+        '    setApiPath(requests, method, (params: unknown) => ({',
+        '      method,',
+        '      params: params as RpcParams<typeof method>,',
+        '    }))',
+        '  }',
+        '',
+        '  return {',
+        '    ...calls,',
+        '    $client: client,',
+        '    $batch: client.batch,',
+        '    $request: requests,',
+        '  } as unknown as RpcApi',
+        '}',
+        '',
+        'export function createRpcClient(options: RpcClientOptions): RpcClient {',
+        '  const fetchImpl = options.fetch ?? globalThis.fetch',
+        '  if (!fetchImpl) {',
+        "    throw new Error('No fetch implementation is available. Pass fetch in createRpcClient options.')",
+        '  }',
+        '',
+        '  let nextId = 1',
+        '  const createId = options.idGenerator ?? (() => globalThis.crypto?.randomUUID?.() ?? String(nextId++))',
+        '  const validateResults = options.validateResults ?? true',
+        '',
+        '  async function post(payload: unknown, context: RpcRequestContext, requestOptions?: RpcRequestOptions): Promise<unknown> {',
+        '    const response = await fetchImpl(options.url, {',
+        "      method: 'POST',",
+        '      headers: await buildHeaders(options.headers, context, requestOptions?.headers),',
+        '      body: JSON.stringify(payload),',
+        '      signal: requestOptions?.signal,',
+        '    })',
+        '',
+        '    if (!response.ok) {',
+        '      throw new RpcTransportError(response.status, response.statusText, await response.text())',
+        '    }',
+        '',
+        '    return response.json()',
+        '  }',
+        '',
+        '  function parseResult<M extends RpcMethod>(method: M, result: unknown): RpcResult<M> {',
+        '    const transformed = options.transformResult?.(method, result) ?? result',
+        '    if (!validateResults) {',
+        '      return transformed as RpcResult<M>',
+        '    }',
+        '',
+        '    return rpcResultSchemas[method].parse(transformed) as RpcResult<M>',
+        '  }',
+        '',
+        '  return {',
+        '    async call<M extends RpcMethod>(',
+        '      method: M,',
+        '      params: RpcParams<M>,',
+        '      requestOptions?: RpcRequestOptions',
+        '    ): Promise<RpcResult<M>> {',
+        '      const request = createRequest(method, params, createId())',
+        '      const raw = await post(request, { methods: [method], batch: false }, requestOptions)',
+        '      const response = parseResponseEnvelope(raw)',
+        '      if (!idsEqual(response.id, request.id)) {',
+        "        throw new RpcProtocolError('JSON-RPC response id does not match request id.')",
+        '      }',
+        '',
+        '      if (response.error) {',
+        '        throw toRpcError(response.error)',
+        '      }',
+        '',
+        '      return parseResult(method, response.result)',
+        '    },',
+        '',
+        '    async batch<const T extends readonly BatchItem[]>(',
+        '      items: T,',
+        '      requestOptions?: RpcRequestOptions',
+        '    ): Promise<BatchResult<T>> {',
+        '      if (items.length === 0) {',
+        '        return [] as unknown as BatchResult<T>',
+        '      }',
+        '',
+        '      const requests = items.map((item) => createRequest(item.method, item.params, createId()))',
+        '      const raw = await post(',
+        '        requests,',
+        '        { methods: items.map((item) => item.method), batch: true },',
+        '        requestOptions',
+        '      )',
+        '',
+        '      if (!Array.isArray(raw)) {',
+        "        throw new RpcProtocolError('Expected JSON-RPC batch response array.')",
+        '      }',
+        '',
+        '      const responsesById = new Map<string, JsonRpcResponseEnvelope>()',
+        '      for (const item of raw) {',
+        '        const response = parseResponseEnvelope(item)',
+        '        if (response.id === undefined || response.id === null) {',
+        "          throw new RpcProtocolError('JSON-RPC batch response item is missing an id.')",
+        '        }',
+        '        const responseKey = idKey(response.id)',
+        '        if (responsesById.has(responseKey)) {',
+        "          throw new RpcProtocolError('JSON-RPC batch response contains a duplicate id.')",
+        '        }',
+        '        responsesById.set(responseKey, response)',
+        '      }',
+        '',
+        '      return requests.map((request, index) => {',
+        '        const method = items[index].method',
+        '        const response = responsesById.get(idKey(request.id))',
+        '        if (!response) {',
+        "          return { ok: false, error: new RpcError(-32603, 'Missing JSON-RPC batch response item.') }",
+        '        }',
+        '',
+        '        if (response.error) {',
+        '          return { ok: false, error: toRpcError(response.error) }',
+        '        }',
+        '',
+        '        try {',
+        '          return { ok: true, result: parseResult(method, response.result) }',
+        '        } catch (error) {',
+        "          return { ok: false, error: new RpcError(-32603, 'Invalid RPC result.', error) }",
+        '        }',
+        '      }) as BatchResult<T>',
+        '    },',
+        '  }',
+        '}',
+        '',
+        'function createRequest<M extends RpcMethod>(',
+        '  method: M,',
+        '  params: RpcParams<M>,',
+        '  id: JsonRpcId',
+        '): JsonRpcRequestEnvelope<M> {',
+        "  return { jsonrpc: '2.0', method, params, id }",
+        '}',
+        '',
+        'function setApiPath(root: Record<string, unknown>, method: string, value: unknown): void {',
+        "  const segments = method.split('.')",
+        '  let node = root',
+        '',
+        '  for (let index = 0; index < segments.length - 1; index += 1) {',
+        '    const segment = segments[index]',
+        '    const existing = node[segment]',
+        '    if (isObjectLike(existing)) {',
+        '      node = existing',
+        '      continue',
+        '    }',
+        '',
+        '    const next: Record<string, unknown> = {}',
+        '    node[segment] = next',
+        '    node = next',
+        '  }',
+        '',
+        '  node[segments[segments.length - 1] ?? method] = value',
+        '}',
+        '',
+        'async function buildHeaders(',
+        '  baseHeaders: RpcHeaders | undefined,',
+        '  context: RpcRequestContext,',
+        '  requestHeaders: RpcHeadersInit | undefined',
+        '): Promise<Headers> {',
+        '  const headers = new Headers()',
+        "  headers.set('Content-Type', 'application/json')",
+        '',
+        '  if (baseHeaders) {',
+        '    mergeHeaders(',
+        '      headers,',
+        "      typeof baseHeaders === 'function' ? await baseHeaders(context) : baseHeaders",
+        '    )',
+        '  }',
+        '',
+        '  if (requestHeaders) {',
+        '    mergeHeaders(headers, requestHeaders)',
+        '  }',
+        '',
+        '  return headers',
+        '}',
+        '',
+        'function mergeHeaders(target: Headers, source: RpcHeadersInit): void {',
+        '  if (source instanceof Headers) {',
+        '    source.forEach((value, key) => {',
+        '      target.set(key, value)',
+        '    })',
+        '    return',
+        '  }',
+        '',
+        '  if (Array.isArray(source)) {',
+        '    for (const [key, value] of source) {',
+        '      target.set(key, value)',
+        '    }',
+        '    return',
+        '  }',
+        '',
+        '  for (const [key, value] of Object.entries(source)) {',
+        '    target.set(key, value)',
+        '  }',
+        '}',
+        '',
+        'function idKey(id: JsonRpcId): string {',
+        '  return `${typeof id}:${String(id)}`',
+        '}',
+        '',
+        'function idsEqual(actual: JsonRpcId | null | undefined, expected: JsonRpcId): boolean {',
+        '  return actual === expected && typeof actual === typeof expected',
+        '}',
+        '',
+        'function parseResponseEnvelope(value: unknown): JsonRpcResponseEnvelope {',
+        '  if (!isRecord(value)) {',
+        "    throw new RpcProtocolError('Expected JSON-RPC response object.')",
+        '  }',
+        '',
+        '  const error = value.error',
+        '  if (error !== undefined && !isJsonRpcErrorObject(error)) {',
+        "    throw new RpcProtocolError('Invalid JSON-RPC error object.')",
+        '  }',
+        '',
+        '  const id = value.id',
+        '  if (id !== undefined && id !== null && typeof id !== ' + "'string'" + ' && typeof id !== ' + "'number'" + ') {',
+        "    throw new RpcProtocolError('Invalid JSON-RPC response id.')",
+        '  }',
+        '',
+        '  return { id, result: value.result, error }',
+        '}',
+        '',
+        'function isJsonRpcErrorObject(value: unknown): value is JsonRpcErrorObject {',
+        '  return (',
+        '    isRecord(value) &&',
+        "    typeof value.code === 'number' &&",
+        "    typeof value.message === 'string'",
+        '  )',
+        '}',
+        '',
+        'function toRpcError(error: JsonRpcErrorObject): RpcError {',
+        '  return new RpcError(error.code, error.message, error.data)',
+        '}',
+        '',
+        'function isRecord(value: unknown): value is Record<string, unknown> {',
+        "  return typeof value === 'object' && value !== null && !Array.isArray(value)",
+        '}',
+        '',
+        'function isObjectLike(value: unknown): value is Record<string, unknown> {',
+        "  return (typeof value === 'object' && value !== null) || typeof value === 'function'",
+        '}',
+        '',
+    ].join('\n');
+}
+function moduleSpecifier(fileName) {
+    const withoutExtension = fileName.replace(/[.][cm]?tsx?$/, '');
+    const relativePath = withoutExtension.startsWith('.')
+        ? withoutExtension
+        : `./${withoutExtension}`;
+    return `${relativePath}.js`;
+}
+function buildMethodTree(methods) {
+    const root = createMethodTreeNode();
+    for (const method of methods) {
+        const segments = method.split('.');
+        let node = root;
+        for (const segment of segments) {
+            let child = node.children.get(segment);
+            if (!child) {
+                child = createMethodTreeNode();
+                node.children.set(segment, child);
+            }
+            node = child;
+        }
+        node.method = method;
+    }
+    return root;
+}
+function createMethodTreeNode() {
+    return { children: new Map() };
+}
+function generateApiTypeLines(methodTree) {
+    return [
+        'export type RpcEndpoint<M extends RpcMethod> = (',
+        '  params: RpcParams<M>,',
+        '  options?: RpcRequestOptions',
+        ') => Promise<RpcResult<M>>',
+        '',
+        'export type RpcBatchRequest<M extends RpcMethod> = (params: RpcParams<M>) => BatchItem<M>',
+        '',
+        'export interface RpcApi {',
+        '  readonly $client: RpcClient',
+        "  readonly $batch: RpcClient['batch']",
+        '  readonly $request: RpcRequestApi',
+        ...emitProperties(methodTree, 'RpcEndpoint', 1),
+        '}',
+        '',
+        'export interface RpcRequestApi {',
+        ...emitProperties(methodTree, 'RpcBatchRequest', 1),
+        '}',
+        '',
+    ];
+}
+function emitProperties(node, endpointType, indent) {
+    const pad = '  '.repeat(indent);
+    return Array.from(node.children.entries())
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([segment, child]) => {
+        return `${pad}readonly ${JSON.stringify(segment)}: ${emitNodeType(child, endpointType, indent)}`;
+    });
+}
+function emitNodeType(node, endpointType, indent) {
+    const childLines = emitProperties(node, endpointType, indent + 1);
+    const childObject = childLines.length === 0
+        ? '{}'
+        : `{\n${childLines.join('\n')}\n${'  '.repeat(indent)}}`;
+    if (node.method && childLines.length > 0) {
+        return `${endpointType}<${JSON.stringify(node.method)}> & ${childObject}`;
+    }
+    if (node.method) {
+        return `${endpointType}<${JSON.stringify(node.method)}>`;
+    }
+    return childObject;
+}
+function generateMethodNameLines(methods) {
+    return [
+        'const rpcMethodNames = [',
+        ...methods.map((method) => `  ${JSON.stringify(method)},`),
+        '] as const satisfies readonly RpcMethod[]',
+        '',
+    ];
+}

package/dist/schema.d.ts

@@ -0,0 +1,36 @@
+export interface JsonSchema {
+    $ref?: string;
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: Array<string | number | boolean | null>;
+    format?: string;
+    default?: unknown;
+    oneOf?: unknown[];
+    anyOf?: unknown[];
+    allOf?: unknown[];
+}
+export interface RpcMethodSchema {
+    params: JsonSchema;
+    result: JsonSchema;
+}
+export interface RpcSchema {
+    methods: Record<string, RpcMethodSchema>;
+}
+export interface GenerateRpcClientOptions {
+    generatedBy?: string;
+    sourceLabel?: string;
+    typesFileName?: string;
+    schemasFileName?: string;
+    clientFileName?: string;
+}
+export interface GeneratedRpcClientFiles {
+    methodCount: number;
+    typesFileName: string;
+    schemasFileName: string;
+    clientFileName: string;
+    typesSource: string;
+    schemasSource: string;
+    clientSource: string;
+}

package/dist/schema.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@swimmesberger/elarion-jsonrpc-client-generator",
+  "version": "0.1.0-preview.10.1",
+  "description": "Generate TypeScript RPC contracts, Zod schemas, and a fetch client from Elarion JSON-RPC schema exports.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "elarion-jsonrpc-client-generator": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/generate.d.ts",
+      "import": "./dist/generate.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swimmesberger/Elarion.git",
+    "directory": "src/elarion-jsonrpc-client-generator"
+  },
+  "bugs": {
+    "url": "https://github.com/swimmesberger/Elarion/issues"
+  },
+  "homepage": "https://github.com/swimmesberger/Elarion#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}