@swimmesberger/elarion-jsonrpc-client-generator 0.2.3-preview.59.1 → 0.2.3-preview.60.1

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+Generate TypeScript RPC method contracts, Zod params/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
@@ -12,8 +12,8 @@ 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. |
+| `rpc-schemas.ts` | `rpcParamsSchemas` and `rpcResultSchemas` Zod maps for runtime params/result validation. |
+| `rpc-client.ts` | Browser/Node.js fetch client with typed single calls, batching, headers, `AbortSignal`, JSON-RPC errors, and Zod-backed params/result validation. |
 
 The generated schema and client files import `zod`, so consuming applications should install `zod` as a runtime dependency.
 
@@ -57,6 +57,8 @@ const [clientResult, projectsResult] = await rpc.$batch([
 
 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.
 
+Params validation is also enabled by default through `rpcParamsSchemas`: single calls and batch items are checked against the exported schema's constraints (lengths, ranges, patterns, formats) before the request is sent, and a failure throws `RpcParamsValidationError` locally — naming the method, with the underlying Zod error as `cause` — so tier-1 contract violations never reach the wire. Set `validateParams: false` to opt out.
+
 ## Client-side tracing
 
 The generated client never imports an OpenTelemetry SDK. Instead it exposes an optional `instrumentation` hook so client-side tracing stays a host decision and adds zero dependencies. The client calls `startSpan` once per request (and once per batch), reads the returned span's `headers` to inject trace context into the outgoing request, then calls `setError`/`end` as the request settles:

package/dist/generate.js

@@ -38,8 +38,18 @@ export function generateRpcClientFiles(schema, options = {}) {
         '',
         "import { z } from 'zod'",
         '',
-        'export const rpcResultSchemas = {',
+        'export const rpcParamsSchemas = {',
     ];
+    for (const method of methods) {
+        const definition = schema.methods[method];
+        const zodSchema = jsonSchemaToZod(stripNullable(definition.params), createContext(definition.params, `methods.${method}.params`), 1);
+        schemasLines.push(`  ${JSON.stringify(method)}: ${zodSchema},`);
+    }
+    schemasLines.push('} as const');
+    schemasLines.push('');
+    schemasLines.push('export type RpcParamsSchemas = typeof rpcParamsSchemas');
+    schemasLines.push('');
+    schemasLines.push('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);

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

@@ -19,17 +19,17 @@ export function jsonSchemaToZod(schema, ctx, indent = 0) {
         return nullish(zodExpression, nullable);
     }
     if (base === 'string') {
-        return nullish('z.string()', nullable);
+        return nullish(stringSchema(resolved), nullable);
     }
     if (base === 'number' || base === 'integer') {
-        return nullish('z.number()', nullable);
+        return nullish(numberSchema(resolved, base), 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);
+        return nullish(arraySchema(`z.array(${itemSchema})`, resolved), nullable);
     }
     if (base === 'object' && resolved.properties) {
         const required = new Set(resolved.required ?? []);
@@ -48,3 +48,59 @@ export function jsonSchemaToZod(schema, ctx, indent = 0) {
 function nullish(expression, nullable) {
     return nullable ? `${expression}.nullish()` : expression;
 }
+// Constraint keywords apply to the inner type in a deterministic modifier order — base type, then
+// `.int()`, then bounds (min-side before max-side), then format/regex refinements — with `.nullish()`
+// always appended last by the caller.
+function stringSchema(schema) {
+    let expression = 'z.string()';
+    if (schema.minLength !== undefined) {
+        expression += `.min(${schema.minLength})`;
+    }
+    if (schema.maxLength !== undefined) {
+        expression += `.max(${schema.maxLength})`;
+    }
+    if (schema.format === 'uuid') {
+        expression += '.uuid()';
+    }
+    else if (schema.format === 'email') {
+        expression += '.email()';
+    }
+    else if (schema.format === 'uri') {
+        expression += '.url()';
+    }
+    if (schema.pattern !== undefined) {
+        // new RegExp(<JSON string literal>) is deterministic and safe for any pattern content (slashes,
+        // quotes, backslashes) — a /.../ regex literal would need its own escaping rules.
+        expression += `.regex(new RegExp(${JSON.stringify(schema.pattern)}))`;
+    }
+    return expression;
+}
+function numberSchema(schema, base) {
+    let expression = 'z.number()';
+    if (base === 'integer') {
+        expression += '.int()';
+    }
+    if (schema.minimum !== undefined) {
+        expression += `.gte(${schema.minimum})`;
+    }
+    if (schema.exclusiveMinimum !== undefined) {
+        expression += `.gt(${schema.exclusiveMinimum})`;
+    }
+    if (schema.maximum !== undefined) {
+        expression += `.lte(${schema.maximum})`;
+    }
+    if (schema.exclusiveMaximum !== undefined) {
+        expression += `.lt(${schema.exclusiveMaximum})`;
+    }
+    return expression;
+}
+function arraySchema(expression, schema) {
+    let result = expression;
+    if (schema.minItems !== undefined) {
+        result += `.min(${schema.minItems})`;
+    }
+    if (schema.maxItems !== undefined) {
+        result += `.max(${schema.maxItems})`;
+    }
+    return result;
+}

package/dist/rpc-client-source.js

@@ -10,7 +10,7 @@ export function generateRpcClientSource(options) {
         `// Source: ${options.sourceLabel}`,
         '',
         `import type { RpcMethods } from '${typesImport}'`,
-        `import { rpcResultSchemas } from '${schemasImport}'`,
+        `import { rpcParamsSchemas, rpcResultSchemas } from '${schemasImport}'`,
         '',
         'export type RpcMethod = keyof RpcMethods & string',
         "export type RpcParams<M extends RpcMethod> = RpcMethods[M]['params']",
@@ -61,6 +61,9 @@ export function generateRpcClientSource(options) {
         '  readonly fetch?: RpcFetch',
         '  readonly headers?: RpcHeaders',
         '  readonly idGenerator?: () => string | number',
+        '  // Validate request params against the generated Zod params schemas before sending. Defaults to true;',
+        '  // a failure throws RpcParamsValidationError locally without hitting the wire.',
+        '  readonly validateParams?: boolean',
         '  readonly validateResults?: boolean',
         '  readonly transformResult?: <M extends RpcMethod>(method: M, result: unknown) => unknown',
         '  readonly instrumentation?: RpcInstrumentation',
@@ -181,6 +184,19 @@ export function generateRpcClientSource(options) {
         '  }',
         '}',
         '',
+        '// Thrown locally (before the request reaches the wire) when params fail the generated Zod',
+        '// params schema. `cause` carries the underlying Zod error with the structured issues.',
+        'export class RpcParamsValidationError extends Error {',
+        '  readonly method: RpcMethod',
+        '',
+        '  constructor(method: RpcMethod, cause: unknown) {',
+        '    const detail = cause instanceof Error ? `: ${cause.message}` : ' + "'.'",
+        '    super(`Invalid params for RPC method ${JSON.stringify(method)}${detail}`, { cause })',
+        "    this.name = 'RpcParamsValidationError'",
+        '    this.method = method',
+        '  }',
+        '}',
+        '',
         'export function createRpcApi(options: RpcClientOptions): RpcApi {',
         '  const client = createRpcClient(options)',
         '  const calls: Record<string, unknown> = {}',
@@ -211,6 +227,7 @@ export function generateRpcClientSource(options) {
         '',
         '  let nextId = 1',
         '  const createId = options.idGenerator ?? (() => globalThis.crypto?.randomUUID?.() ?? String(nextId++))',
+        '  const validateParams = options.validateParams ?? true',
         '  const validateResults = options.validateResults ?? true',
         '  const idempotencyEnabled = options.idempotency?.enabled ?? true',
         '  const generateIdempotencyKey = options.idempotency?.generateKey ?? defaultIdempotencyKey',
@@ -244,6 +261,22 @@ export function generateRpcClientSource(options) {
         '    return response.json()',
         '  }',
         '',
+        '  // Pre-flight params validation runs on the caller-supplied params, before the idempotency key is',
+        '  // merged into params._meta (the params schema does not know _meta) and before any request is built,',
+        '  // so a failure never reaches the wire. The original params object is sent unchanged — Zod object',
+        '  // parsing strips unknown keys, so the parse output is deliberately discarded.',
+        '  function assertValidParams<M extends RpcMethod>(method: M, params: RpcParams<M>): void {',
+        '    if (!validateParams) {',
+        '      return',
+        '    }',
+        '',
+        '    try {',
+        '      rpcParamsSchemas[method].parse(params)',
+        '    } catch (error) {',
+        '      throw new RpcParamsValidationError(method, error)',
+        '    }',
+        '  }',
+        '',
         '  function parseResult<M extends RpcMethod>(method: M, result: unknown): RpcResult<M> {',
         '    const transformed = options.transformResult?.(method, result) ?? result',
         '    if (!validateResults) {',
@@ -259,6 +292,7 @@ export function generateRpcClientSource(options) {
         '      params: RpcParams<M>,',
         '      requestOptions?: RpcRequestOptions',
         '    ): Promise<RpcResult<M>> {',
+        '      assertValidParams(method, params)',
         '      const idempotencyKey = resolveIdempotencyKey(method, requestOptions?.idempotencyKey)',
         '      const request = createRequest(method, withIdempotencyKey(params, idempotencyKey), createId())',
         '      const context: RpcRequestContext = { methods: [method], batch: false }',
@@ -291,6 +325,11 @@ export function generateRpcClientSource(options) {
         '        return [] as unknown as BatchResult<T>',
         '      }',
         '',
+        '      // Validate every item before building any request, so an invalid batch never partially sends.',
+        '      for (const item of items) {',
+        '        assertValidParams(item.method, item.params)',
+        '      }',
+        '',
         '      const requests = items.map((item) =>',
         '        createRequest(',
         '          item.method,',

package/dist/schema.d.ts

@@ -10,6 +10,15 @@ export interface JsonSchema {
     oneOf?: unknown[];
     anyOf?: unknown[];
     allOf?: unknown[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    minItems?: number;
+    maxItems?: number;
 }
 export interface RpcMethodSchema {
     params: JsonSchema;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swimmesberger/elarion-jsonrpc-client-generator",
-  "version": "0.2.3-preview.59.1",
+  "version": "0.2.3-preview.60.1",
   "description": "Generate TypeScript RPC contracts, Zod schemas, and a fetch client from Elarion JSON-RPC schema exports.",
   "license": "Apache-2.0",
   "type": "module",