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

package/README.md

@@ -0,0 +1,17 @@
+# @swimmesberger/elarion-jsonrpc-client-generator
+
+Generate TypeScript RPC method contracts and Zod result schemas 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. |
+
+The generated schema file imports `zod`, so consuming applications should install `zod` as a runtime dependency.

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,76 @@
+#!/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 === '--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)
+  --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,
+    });
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(resolve(outDir, generated.typesFileName), generated.typesSource, 'utf-8');
+    writeFileSync(resolve(outDir, generated.schemasFileName), generated.schemasSource, '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,63 @@
+import { jsonSchemaToTypeScript } from './json-schema-to-ts.js';
+import { jsonSchemaToZod } from './json-schema-to-zod.js';
+import { stripNullable } from './json-schema.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';
+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 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('');
+    return {
+        methodCount: methods.length,
+        typesFileName,
+        schemasFileName,
+        typesSource: typesLines.join('\n'),
+        schemasSource: schemasLines.join('\n'),
+    };
+}
+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/schema.d.ts

@@ -0,0 +1,33 @@
+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;
+}
+export interface GeneratedRpcClientFiles {
+    methodCount: number;
+    typesFileName: string;
+    schemasFileName: string;
+    typesSource: string;
+    schemasSource: 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.6.1",
+  "description": "Generate TypeScript RPC contracts and Zod result schemas 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"
+  }
+}