@swimmesberger/elarion-jsonrpc-client-generator 0.2.17 → 0.2.18

package/README.md

@@ -76,7 +76,10 @@ before validation, or set `validateResults: false` when another layer validates
 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.
+contract violations never reach the wire. Set `validateParams: false` to opt out. The error's `fieldErrors` groups the
+issue messages by field path in the server's `ValidationErrorData.fieldErrors` notation (`"address.street"`,
+`"lines[1].sku"`, `""` for the params object), and a constraint's explicit server message
+(`x-elarion-error-messages` in the schema) is the message of its Zod check.
 
 ## Client-event subscriptions
 

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

@@ -13,13 +13,13 @@ export function jsonSchemaToZod(schema, ctx, indent = 0) {
         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(', ')}])`;
+            zodExpression = `z.enum([${values.map((value) => JSON.stringify(value)).join(', ')}]${paramsArg(resolved, 'enum')})`;
         }
         else {
             const literals = values.map((value) => `z.literal(${JSON.stringify(value)})`);
             zodExpression = literals.length === 1
-                ? literals[0]
-                : `z.union([${literals.join(', ')}])`;
+                ? `z.literal(${JSON.stringify(values[0])}${paramsArg(resolved, 'enum')})`
+                : `z.union([${literals.join(', ')}]${paramsArg(resolved, 'enum')})`;
         }
         return nullish(zodExpression, nullable);
     }
@@ -56,30 +56,46 @@ export function jsonSchemaToZod(schema, ctx, indent = 0) {
 function nullish(expression, nullable) {
     return nullable ? `${expression}.nullish()` : expression;
 }
+// A Zod check call carrying, as its last argument, the explicit DataAnnotations message the server exporter
+// attached to the check's JSON Schema keyword. Checks take the plain-string message form, which Zod v3 and v4
+// both accept without deprecation. No message → no argument, so message-free schemas stay byte-identical.
+function check(name, args, schema, keyword) {
+    const message = errorMessage(schema, keyword);
+    return `.${name}(${(message === undefined ? args : [...args, JSON.stringify(message)]).join(', ')})`;
+}
+// Schema constructors (z.enum, z.literal, z.union) take the message as `{ message }`, the one params form
+// Zod v3 (no string shorthand there) and v4 share.
+function paramsArg(schema, keyword) {
+    const message = errorMessage(schema, keyword);
+    return message === undefined ? '' : `, { message: ${JSON.stringify(message)} }`;
+}
+function errorMessage(schema, keyword) {
+    return schema['x-elarion-error-messages']?.[keyword];
+}
 // 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})`;
+        expression += check('min', [String(schema.minLength)], schema, 'minLength');
     }
     if (schema.maxLength !== undefined) {
-        expression += `.max(${schema.maxLength})`;
+        expression += check('max', [String(schema.maxLength)], schema, 'maxLength');
     }
     if (schema.format === 'uuid') {
-        expression += '.uuid()';
+        expression += check('uuid', [], schema, 'format');
     }
     else if (schema.format === 'email') {
-        expression += '.email()';
+        expression += check('email', [], schema, 'format');
     }
     else if (schema.format === 'uri') {
-        expression += '.url()';
+        expression += check('url', [], schema, 'format');
     }
     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)}))`;
+        expression += check('regex', [`new RegExp(${JSON.stringify(schema.pattern)})`], schema, 'pattern');
     }
     return expression;
 }
@@ -89,26 +105,26 @@ function numberSchema(schema, base) {
         expression += '.int()';
     }
     if (schema.minimum !== undefined) {
-        expression += `.gte(${schema.minimum})`;
+        expression += check('gte', [String(schema.minimum)], schema, 'minimum');
     }
     if (schema.exclusiveMinimum !== undefined) {
-        expression += `.gt(${schema.exclusiveMinimum})`;
+        expression += check('gt', [String(schema.exclusiveMinimum)], schema, 'exclusiveMinimum');
     }
     if (schema.maximum !== undefined) {
-        expression += `.lte(${schema.maximum})`;
+        expression += check('lte', [String(schema.maximum)], schema, 'maximum');
     }
     if (schema.exclusiveMaximum !== undefined) {
-        expression += `.lt(${schema.exclusiveMaximum})`;
+        expression += check('lt', [String(schema.exclusiveMaximum)], schema, 'exclusiveMaximum');
     }
     return expression;
 }
 function arraySchema(expression, schema) {
     let result = expression;
     if (schema.minItems !== undefined) {
-        result += `.min(${schema.minItems})`;
+        result += check('min', [String(schema.minItems)], schema, 'minItems');
     }
     if (schema.maxItems !== undefined) {
-        result += `.max(${schema.maxItems})`;
+        result += check('max', [String(schema.maxItems)], schema, 'maxItems');
     }
     return result;
 }

package/dist/rpc-client-source.js

@@ -258,15 +258,46 @@ export function generateRpcClientSource(options) {
         '// params schema. `cause` carries the underlying Zod error with the structured issues.',
         'export class RpcParamsValidationError extends Error {',
         '  readonly method: RpcMethod',
+        '  // The issue messages keyed by field path in the server notation of ValidationErrorData.fieldErrors',
+        '  // ("address.street", "items[1].name"; "" for the params object itself), so one form helper can mark',
+        '  // fields for a local failure and for a server validation RpcError alike.',
+        '  readonly fieldErrors: Record<string, string[]>',
         '',
         '  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',
+        '    this.fieldErrors = issueFieldErrors(cause)',
         '  }',
         '}',
         '',
+        '// Groups Zod issues (v3 and v4 share the `issues: { path, message }[]` shape) by field path: member',
+        '// names join with ".", array indexes become "[i]" — the notation of the server\'s field-error keys.',
+        'function issueFieldErrors(cause: unknown): Record<string, string[]> {',
+        "  const issues = (cause as { issues?: unknown } | null | undefined)?.issues",
+        '  if (!Array.isArray(issues)) {',
+        '    return {}',
+        '  }',
+        '',
+        '  // A Map, then Object.fromEntries: a field named like an Object.prototype member stays an own key.',
+        '  const fieldErrors = new Map<string, string[]>()',
+        '  for (const issue of issues as readonly { path?: readonly PropertyKey[]; message?: unknown }[]) {',
+        "    let key = ''",
+        '    for (const segment of issue.path ?? []) {',
+        "      key += typeof segment === 'number' ? `[${segment}]` : key === '' ? String(segment) : `.${String(segment)}`",
+        '    }',
+        '    const messages = fieldErrors.get(key)',
+        '    if (messages) {',
+        '      messages.push(String(issue.message))',
+        '    } else {',
+        '      fieldErrors.set(key, [String(issue.message)])',
+        '    }',
+        '  }',
+        '',
+        '  return Object.fromEntries(fieldErrors)',
+        '}',
+        '',
         'export function createRpcApi(options: RpcClientOptions): RpcApi {',
         '  const client = createRpcClient(options)',
         '  const calls: Record<string, unknown> = {}',

package/dist/schema.d.ts

@@ -25,6 +25,13 @@ export interface JsonSchema {
     exclusiveMaximum?: number;
     minItems?: number;
     maxItems?: number;
+    /**
+     * Explicit error messages of the DataAnnotations behind the constraint keywords, keyed by keyword (for example
+     * `{ pattern: 'Code must be three capital letters.' }`), emitted by the server exporter only for attributes
+     * that declare a message. The generator passes each one to the matching Zod check, so client-side
+     * pre-validation reports the server's text.
+     */
+    'x-elarion-error-messages'?: Record<string, string>;
 }
 /**
  * One declared error of a method (ADR-0080): the kind it fails with (the kind's default code, for example

package/package.json

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