@swimmesberger/elarion-jsonrpc-client-generator 0.2.8-preview.158.1 → 0.2.8

package/README.md

@@ -96,7 +96,7 @@ events.$client.onConnected(() => refetchAll())
 
 ## Error handling
 
-A JSON-RPC error from the server is thrown as a typed `RpcError` (`code`, `message`, optional `data`). Elarion maps its
+A JSON-RPC error from the server is thrown as a typed `RpcError`: `code` (the stable string error code), `data` (its typed payload), `message`, and `rpcCode` (the numeric JSON-RPC code). Methods list their declared errors in the schema, so `RpcMethodError<'method'>` is a union discriminated by `code` with typed `data`, and `isRpcMethodError('method', error)` narrows a caught error. Elarion maps its
 `AppError` kinds onto the JSON-RPC server-reserved range, so the generated `RpcError` exposes a getter per kind — branch
 on the kind directly instead of re-wrapping:
 

package/dist/generate.js

@@ -35,6 +35,21 @@ export function generateRpcClientFiles(schema, options = {}) {
         typesLines.push(`  ${JSON.stringify(method)}: {`);
         typesLines.push(`    params: ${paramsType}`);
         typesLines.push(`    result: ${resultType}`);
+        const errorCodes = Object.keys(definition.errors ?? {}).sort();
+        if (errorCodes.length === 0) {
+            typesLines.push('    errors: {}');
+        }
+        else {
+            typesLines.push('    errors: {');
+            for (const code of errorCodes) {
+                const error = definition.errors[code];
+                const dataType = error.data === undefined
+                    ? 'undefined'
+                    : jsonSchemaToTypeScript(stripNullable(error.data), createContext(error.data, `methods.${method}.errors.${code}.data`), 3);
+                typesLines.push(`      ${JSON.stringify(code)}: { kind: ${JSON.stringify(error.kind)}; data: ${dataType} }`);
+            }
+            typesLines.push('    }');
+        }
         typesLines.push('  }');
     }
     typesLines.push('}');
@@ -66,6 +81,28 @@ export function generateRpcClientFiles(schema, options = {}) {
     schemasLines.push('');
     schemasLines.push('export type RpcResultSchemas = typeof rpcResultSchemas');
     schemasLines.push('');
+    // Typed error payload schemas (ADR-0080): per method, per declared code that carries a payload.
+    schemasLines.push('export const rpcErrorDataSchemas = {');
+    for (const method of methods) {
+        const errors = schema.methods[method].errors ?? {};
+        const entries = Object.keys(errors)
+            .sort()
+            .filter((code) => errors[code].data !== undefined)
+            .map((code) => {
+            const data = errors[code].data;
+            const zodSchema = jsonSchemaToZod(stripNullable(data), createContext(data, `methods.${method}.errors.${code}.data`), 2);
+            return `    ${JSON.stringify(code)}: ${zodSchema},`;
+        });
+        if (entries.length > 0) {
+            schemasLines.push(`  ${JSON.stringify(method)}: {`);
+            schemasLines.push(...entries);
+            schemasLines.push('  },');
+        }
+    }
+    schemasLines.push('} as const');
+    schemasLines.push('');
+    schemasLines.push('export type RpcErrorDataSchemas = typeof rpcErrorDataSchemas');
+    schemasLines.push('');
     // Client-event payload schemas (ADR-0043), emitted only when the schema declares events so event-free
     // schemas keep producing byte-identical output.
     const eventTopics = Object.keys(schema.events ?? {}).sort();
@@ -81,6 +118,13 @@ export function generateRpcClientFiles(schema, options = {}) {
         schemasLines.push('export type RpcEventPayloadSchemas = typeof rpcEventPayloadSchemas');
         schemasLines.push('');
     }
+    const errorCodesByMethod = {};
+    for (const method of methods) {
+        const codes = Object.keys(schema.methods[method].errors ?? {}).sort();
+        if (codes.length > 0) {
+            errorCodesByMethod[method] = codes;
+        }
+    }
     const idempotentMethods = methods.filter((method) => schema.methods[method].idempotent === true);
     // Where each method carries file payloads (x-elarion-file nodes), so the client can convert between
     // native File values and the base64 wire envelope. Methods without files are omitted entirely.
@@ -104,6 +148,7 @@ export function generateRpcClientFiles(schema, options = {}) {
         schemasFileName,
         methods,
         idempotentMethods,
+        errorCodesByMethod,
         paramsFilePaths,
         resultFilePaths,
     });

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

@@ -5,6 +5,8 @@ interface GenerateRpcClientSourceOptions {
     schemasFileName: string;
     methods: readonly string[];
     idempotentMethods: readonly string[];
+    /** The declared error codes per method (ADR-0080); methods without declared errors are omitted. */
+    errorCodesByMethod: Readonly<Record<string, readonly string[]>>;
     /** Property paths of file payloads per method ('*' = array items, [] = the value itself); omitted methods carry none. */
     paramsFilePaths: Readonly<Record<string, string[][]>>;
     resultFilePaths: Readonly<Record<string, string[][]>>;

package/dist/rpc-client-source.js

@@ -13,7 +13,7 @@ export function generateRpcClientSource(options) {
         `// Source: ${options.sourceLabel}`,
         '',
         `import type { RpcMethods } from '${typesImport}'`,
-        `import { rpcParamsSchemas, rpcResultSchemas } from '${schemasImport}'`,
+        `import { rpcErrorDataSchemas, rpcParamsSchemas, rpcResultSchemas } from '${schemasImport}'`,
         '',
         'export type RpcMethod = keyof RpcMethods & string',
         "export type RpcParams<M extends RpcMethod> = RpcMethods[M]['params']",
@@ -92,6 +92,13 @@ export function generateRpcClientSource(options) {
         '  | { readonly ok: true; readonly result: RpcResult<M> }',
         '  | { readonly ok: false; readonly error: RpcError }',
         '',
+        '// The declared error contract of a method (ADR-0080): a union of RpcError variants discriminated by the',
+        '// stable `code`, each with its typed `data`. Narrow with `error.code === ...` or `isRpcMethodError`.',
+        "export type RpcErrorCode<M extends RpcMethod> = keyof RpcMethods[M]['errors'] & string",
+        'export type RpcMethodError<M extends RpcMethod> = {',
+        '  [C in RpcErrorCode<M>]: RpcError<C, RpcMethods[M][\'errors\'][C] extends { data: infer D } ? D : never>',
+        '}[RpcErrorCode<M>]',
+        '',
         'export type BatchResult<T extends readonly BatchItem[]> = {',
         '  readonly [K in keyof T]: T[K] extends BatchItem<infer M> ? BatchItemResult<M> : never',
         '}',
@@ -113,6 +120,13 @@ export function generateRpcClientSource(options) {
         ...generateMethodNameLines(options.methods),
         `const rpcIdempotentMethods: ReadonlySet<RpcMethod> = new Set(${JSON.stringify(options.idempotentMethods)})`,
         '',
+        `const rpcErrorCodes: Partial<Record<RpcMethod, readonly string[]>> = ${JSON.stringify(options.errorCodesByMethod)}`,
+        '',
+        '/** True when `error` is an RpcError carrying one of the error codes `method` declares. */',
+        'export function isRpcMethodError<M extends RpcMethod>(method: M, error: unknown): error is RpcMethodError<M> {',
+        '  return error instanceof RpcError && (rpcErrorCodes[method]?.includes(error.code) ?? false)',
+        '}',
+        '',
         ...(hasFiles
             ? [
                 '// Where each method carries file payloads: property paths into params/results ("*" descends into',
@@ -157,57 +171,65 @@ export function generateRpcClientSource(options) {
         '  unauthorized: -32005,',
         '} as const',
         '',
-        'export class RpcError extends Error {',
-        '  readonly code: number',
-        '  readonly data?: unknown',
-        '',
-        '  constructor(code: number, message: string, data?: unknown) {',
+        '// Every error carries a stable string `code` (the contract clients branch on) and `data` (its typed',
+        '// payload). `rpcCode` is the numeric JSON-RPC code, which only encodes the coarse error kind.',
+        'export class RpcError<TCode extends string = string, TData = unknown> extends Error {',
+        '  /** The stable machine-readable error code, for example "token.malformed" or "not_found". */',
+        '  readonly code: TCode',
+        '  /** The typed error payload declared for this code; undefined when the error carries none. */',
+        '  readonly data: TData',
+        '  /** The numeric JSON-RPC error code (the coarse error kind, see ElarionErrorCodes). */',
+        '  readonly rpcCode: number',
+        '',
+        '  constructor(rpcCode: number, message: string, wireData?: unknown) {',
         '    super(message)',
         "    this.name = 'RpcError'",
-        '    this.code = code',
-        '    this.data = data',
+        '    this.rpcCode = rpcCode',
+        '    const envelope = readErrorData(wireData)',
+        '    this.code = (envelope?.code ?? defaultErrorCode(rpcCode)) as TCode',
+        '    this.data = envelope?.data as TData',
         '  }',
         '',
         '  get isParseError() {',
-        '    return this.code === -32700',
+        '    return this.rpcCode === -32700',
         '  }',
         '',
         '  get isInvalidRequest() {',
-        '    return this.code === -32600',
+        '    return this.rpcCode === -32600',
         '  }',
         '',
         '  get isMethodNotFound() {',
-        '    return this.code === -32601',
+        '    return this.rpcCode === -32601',
         '  }',
         '',
         '  get isInvalidParams() {',
-        '    return this.code === -32602',
+        '    return this.rpcCode === -32602',
         '  }',
         '',
         '  get isInternalError() {',
-        '    return this.code === -32603',
+        '    return this.rpcCode === -32603',
         '  }',
         '',
         '  // Elarion application-error kinds (see ElarionErrorCodes). isInvalidParams also covers Validation;',
         '  // isInternalError also covers Internal.',
         '  get isNotFound() {',
-        '    return this.code === ElarionErrorCodes.notFound',
+        '    return this.rpcCode === ElarionErrorCodes.notFound',
         '  }',
         '',
         '  get isConflict() {',
-        '    return this.code === ElarionErrorCodes.conflict',
+        '    return this.rpcCode === ElarionErrorCodes.conflict',
         '  }',
         '',
         '  get isForbidden() {',
-        '    return this.code === ElarionErrorCodes.forbidden',
+        '    return this.rpcCode === ElarionErrorCodes.forbidden',
         '  }',
         '',
         '  get isBusinessRule() {',
-        '    return this.code === ElarionErrorCodes.businessRule',
+        '    return this.rpcCode === ElarionErrorCodes.businessRule',
         '  }',
         '',
         '  get isUnauthorized() {',
-        '    return this.code === ElarionErrorCodes.unauthorized',
+        '    return this.rpcCode === ElarionErrorCodes.unauthorized',
         '  }',
         '}',
         '',
@@ -355,7 +377,7 @@ export function generateRpcClientSource(options) {
         '        // A spec-compliant server reports request-level failures (e.g. parse errors) with "id": null —',
         '        // surface the server error instead of a generic id-mismatch protocol error.',
         '        if (response.error && (response.id === null || response.id === undefined)) {',
-        '          throw toRpcError(response.error)',
+        '          throw toRpcError(response.error, method, validateResults)',
         '        }',
         '',
         '        if (!idsEqual(response.id, request.id)) {',
@@ -363,7 +385,7 @@ export function generateRpcClientSource(options) {
         '        }',
         '',
         '        if (response.error) {',
-        '          throw toRpcError(response.error)',
+        '          throw toRpcError(response.error, method, validateResults)',
         '        }',
         '',
         hasFiles
@@ -448,7 +470,11 @@ export function generateRpcClientSource(options) {
         '          }',
         '',
         '          if (response.error) {',
-        '            return { ok: false, error: toRpcError(response.error) }',
+        '            try {',
+        '              return { ok: false, error: toRpcError(response.error, method, validateResults) }',
+        '            } catch (error) {',
+        "              return { ok: false, error: new RpcError(-32603, 'Invalid RPC error payload.', { code: 'internal', data: error }) }",
+        '            }',
         '          }',
         '',
         '          try {',
@@ -456,7 +482,7 @@ export function generateRpcClientSource(options) {
             ? '            return { ok: true, result: parseResult(method, decodeFileResult(method, response.result)) }'
             : '            return { ok: true, result: parseResult(method, response.result) }',
         '          } catch (error) {',
-        "            return { ok: false, error: new RpcError(-32603, 'Invalid RPC result.', error) }",
+        "            return { ok: false, error: new RpcError(-32603, 'Invalid RPC result.', { code: 'internal', data: error }) }",
         '          }',
         '        }) as BatchResult<T>',
         '      } catch (error) {',
@@ -598,8 +624,48 @@ export function generateRpcClientSource(options) {
         '  )',
         '}',
         '',
-        'function toRpcError(error: JsonRpcErrorObject): RpcError {',
-        '  return new RpcError(error.code, error.message, error.data)',
+        'interface RpcErrorDataSchema {',
+        '  safeParse(value: unknown): { success: true } | { success: false; error: { message: string } }',
+        '}',
+        '',
+        'function toRpcError(error: JsonRpcErrorObject, method?: RpcMethod, validate = false): RpcError {',
+        '  const rpcError = new RpcError(error.code, error.message, error.data)',
+        '  // A declared payload is part of the contract: validate it like a result so clients can trust the typing.',
+        '  if (validate && method !== undefined) {',
+        '    const schemas = rpcErrorDataSchemas as Partial<Record<string, Partial<Record<string, RpcErrorDataSchema>>>>',
+        '    const schema = schemas[method]?.[rpcError.code]',
+        '    if (schema !== undefined) {',
+        '      const parsed = schema.safeParse(rpcError.data)',
+        '      if (!parsed.success) {',
+        '        throw new RpcProtocolError(',
+        '          `Error payload for code ${JSON.stringify(rpcError.code)} of ${JSON.stringify(method)} does not match its declared contract: ${parsed.error.message}`',
+        '        )',
+        '      }',
+        '    }',
+        '  }',
+        '  return rpcError',
+        '}',
+        '',
+        '// The wire shape of error.data is always { code, data? } (ADR-0080).',
+        'function readErrorData(value: unknown): { code: string; data?: unknown } | undefined {',
+        '  if (!isRecord(value) || typeof value.code !== ' + "'string'" + ') return undefined',
+        '  return { code: value.code, data: value.data }',
+        '}',
+        '',
+        '// Fallback for a server that sends no error.data: the default code of the numeric kind.',
+        'function defaultErrorCode(rpcCode: number): string {',
+        '  switch (rpcCode) {',
+        "    case -32700: return 'parse_error'",
+        "    case -32600: return 'invalid_request'",
+        "    case -32601: return 'method_not_found'",
+        "    case -32602: return 'invalid_params'",
+        "    case ElarionErrorCodes.notFound: return 'not_found'",
+        "    case ElarionErrorCodes.conflict: return 'conflict'",
+        "    case ElarionErrorCodes.forbidden: return 'forbidden'",
+        "    case ElarionErrorCodes.businessRule: return 'business_rule'",
+        "    case ElarionErrorCodes.unauthorized: return 'unauthorized'",
+        "    default: return 'internal'",
+        '  }',
         '}',
         '',
         'function isRecord(value: unknown): value is Record<string, unknown> {',

package/dist/schema.d.ts

@@ -26,9 +26,19 @@ export interface JsonSchema {
     minItems?: number;
     maxItems?: number;
 }
+/**
+ * One declared error of a method (ADR-0080): the kind it fails with (the kind's default code, for example
+ * `not_found`) and, when the error carries a typed payload, the schema of `error.data.data`.
+ */
+export interface RpcErrorSchema {
+    kind: string;
+    data?: JsonSchema;
+}
 export interface RpcMethodSchema {
     params: JsonSchema;
     result: JsonSchema;
+    /** The declared error contract, keyed by stable error code; omitted when the method declares none. */
+    errors?: Record<string, RpcErrorSchema>;
     idempotent?: boolean;
 }
 /** One structured permission from the schema's capability vocabulary ({resource}.{verb} plus its parts). */
@@ -39,7 +49,7 @@ export interface RpcCapabilityPermission {
 }
 /**
  * The capability vocabulary block emitted by the server exporter (ADR-0032): module names with the
- * `[ClientFeatures]` each exposes, the structured permission catalog, and role names. All optional — older
+ * client-exposed flag each declares, the structured permission catalog, and role names. All optional — older
  * schemas (or hosts without the session/authorization registrations) simply omit it.
  */
 export interface RpcSchemaCapabilities {

package/dist/session-client-source.js

@@ -26,7 +26,7 @@ function vocabularySection(capabilities) {
     }
     lines.push('');
     if (flagNames.length > 0) {
-        lines.push('/** Flag/variant names the backend exposes to the client (the union of every [ClientFeatures] list). */');
+        lines.push('/** Flag/variant names the backend exposes to the client (the union of every client-exposed flag declaration). */');
         lines.push('export const Flags = {');
         for (const name of flagNames)
             lines.push(`  ${q(name)}: ${q(name)},`);

package/package.json

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