@swimmesberger/elarion-jsonrpc-client-generator 0.2.3-preview.67.1 → 0.2.3-preview.68.1

package/README.md

@@ -59,6 +59,39 @@ Result validation is enabled by default through `rpcResultSchemas`. Use `transfo
 
 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.
 
+## Error handling
+
+A JSON-RPC error from the server is thrown as a typed `RpcError` (`code`, `message`, optional `data`). 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:
+
+```ts
+import { RpcError, ElarionErrorCodes } from './generated/rpc-client'
+
+try {
+  await rpc.clients.get({ id })
+} catch (error) {
+  if (error instanceof RpcError && error.isNotFound) return renderNotFound()
+  throw error
+}
+```
+
+`isNotFound` (`-32001`), `isConflict` (`-32002`), `isForbidden` (`-32003`), `isBusinessRule` (`-32004`), and `isUnauthorized` (`-32005`) cover the Elarion application kinds; `isInvalidParams` (`-32602`) and `isInternalError` (`-32603`) cover `Validation`/`Internal`; and the standard `isParseError`/`isInvalidRequest`/`isMethodNotFound` getters stay available. The application codes are also exported as `ElarionErrorCodes` for `switch` statements.
+
+## Framework adapters
+
+The core client stays framework-neutral, but you can opt into a framework adapter emitted as a separate file. Pass `--framework tanstack-start` to also emit `start-adapter.ts` (needs the `@tanstack/react-start` peer dependency):
+
+```bash
+npx elarion-jsonrpc-client-generator --schema rpc-schema.json --out src/generated --framework tanstack-start
+```
+
+It exports `createStartRpcApi` — a `createRpcApi` with request-scoped cookie forwarding pre-wired for SSR — and `forwardRequestCookie`, the isomorphic headers function on its own. The core client never imports the adapter, so consumers that don't opt in stay framework-neutral and their output is byte-identical.
+
+```ts
+import { createStartRpcApi } from './generated/start-adapter'
+
+export const rpc = createStartRpcApi({ url: '/rpc' })
+```
+
 ## 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/cli.js

@@ -2,6 +2,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { generateRpcClientFiles } from './generate.js';
+const SUPPORTED_FRAMEWORKS = ['tanstack-start'];
 function parseArgs(argv) {
     const options = {
         schemaPath: 'rpc-schema.json',
@@ -47,6 +48,19 @@ function parseArgs(argv) {
             index += 1;
             continue;
         }
+        if (arg === '--framework') {
+            if (!SUPPORTED_FRAMEWORKS.includes(next)) {
+                throw new Error(`Unsupported framework ${next}. Supported: ${SUPPORTED_FRAMEWORKS.join(', ')}`);
+            }
+            options.framework = next;
+            index += 1;
+            continue;
+        }
+        if (arg === '--framework-adapter') {
+            options.frameworkAdapterFileName = next;
+            index += 1;
+            continue;
+        }
         if (arg === '--source-label') {
             options.sourceLabel = next;
             index += 1;
@@ -67,6 +81,9 @@ Options:
   --client <file>       Fetch client filename (default: rpc-client.ts)
   --session-client <file> Client-capability snapshot client + OpenFeature provider (default: session-client.ts;
                           emitted only when the schema exposes the elarion.session operation)
+  --framework <name>    Emit an opt-in framework adapter alongside the neutral core client.
+                          Supported: tanstack-start (needs the @tanstack/react-start peer dependency)
+  --framework-adapter <file> Framework adapter filename (default: start-adapter.ts)
   --source-label <text> Source label written into generated file headers
 `);
 }
@@ -82,16 +99,23 @@ function main() {
         schemasFileName: options.schemasFileName,
         clientFileName: options.clientFileName,
         sessionClientFileName: options.sessionClientFileName,
+        framework: options.framework,
+        frameworkAdapterFileName: options.frameworkAdapterFileName,
     });
     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');
-    let sessionNote = '';
+    const extraNotes = [];
     if (generated.sessionClientFileName !== undefined && generated.sessionClientSource !== undefined) {
         writeFileSync(resolve(outDir, generated.sessionClientFileName), generated.sessionClientSource, 'utf-8');
-        sessionNote = ` (+ ${generated.sessionClientFileName})`;
+        extraNotes.push(generated.sessionClientFileName);
+    }
+    if (generated.frameworkAdapterFileName !== undefined && generated.frameworkAdapterSource !== undefined) {
+        writeFileSync(resolve(outDir, generated.frameworkAdapterFileName), generated.frameworkAdapterSource, 'utf-8');
+        extraNotes.push(generated.frameworkAdapterFileName);
     }
-    console.log(`[jsonrpc-client-generator] Generated ${generated.methodCount} RPC method types and schemas${sessionNote} -> ${outDir}`);
+    const extraNote = extraNotes.length > 0 ? ` (+ ${extraNotes.join(', ')})` : '';
+    console.log(`[jsonrpc-client-generator] Generated ${generated.methodCount} RPC method types and schemas${extraNote} -> ${outDir}`);
 }
 main();

package/dist/generate.js

@@ -3,6 +3,7 @@ import { jsonSchemaToZod } from './json-schema-to-zod.js';
 import { stripNullable } from './json-schema.js';
 import { generateRpcClientSource } from './rpc-client-source.js';
 import { generateSessionClientSource } from './session-client-source.js';
+import { generateStartAdapterSource } from './start-adapter-source.js';
 const DEFAULT_GENERATED_BY = 'elarion-jsonrpc-client-generator';
 const DEFAULT_SOURCE_LABEL = 'rpc-schema.json';
 const DEFAULT_TYPES_FILE = 'rpc-types.ts';
@@ -10,6 +11,7 @@ const DEFAULT_SCHEMAS_FILE = 'rpc-schemas.ts';
 const DEFAULT_CLIENT_FILE = 'rpc-client.ts';
 const DEFAULT_SESSION_CLIENT_FILE = 'session-client.ts';
 const DEFAULT_SESSION_OPERATION = 'elarion.session';
+const DEFAULT_START_ADAPTER_FILE = 'start-adapter.ts';
 export { UnsupportedJsonSchemaError } from './json-schema.js';
 export function generateRpcClientFiles(schema, options = {}) {
     const generatedBy = options.generatedBy ?? DEFAULT_GENERATED_BY;
@@ -85,6 +87,12 @@ export function generateRpcClientFiles(schema, options = {}) {
             capabilities: schema.capabilities,
         })
         : undefined;
+    // The framework adapter (ADR-boundary: kept opt-in so the core client stays framework-neutral) is emitted only
+    // when a framework is requested, so an unopted schema produces byte-identical output.
+    const frameworkAdapterFileName = options.frameworkAdapterFileName ?? DEFAULT_START_ADAPTER_FILE;
+    const frameworkAdapterSource = options.framework === 'tanstack-start'
+        ? generateStartAdapterSource({ generatedBy, sourceLabel, clientFileName })
+        : undefined;
     return {
         methodCount: methods.length,
         typesFileName,
@@ -95,6 +103,8 @@ export function generateRpcClientFiles(schema, options = {}) {
         clientSource,
         sessionClientFileName: sessionClientSource === undefined ? undefined : sessionClientFileName,
         sessionClientSource,
+        frameworkAdapterFileName: frameworkAdapterSource === undefined ? undefined : frameworkAdapterFileName,
+        frameworkAdapterSource,
     };
 }
 function createContext(root, path) {

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

@@ -7,4 +7,5 @@ interface GenerateRpcClientSourceOptions {
     idempotentMethods: readonly string[];
 }
 export declare function generateRpcClientSource(options: GenerateRpcClientSourceOptions): string;
+export declare function moduleSpecifier(fileName: string): string;
 export {};

package/dist/rpc-client-source.js

@@ -131,6 +131,19 @@ export function generateRpcClientSource(options) {
         '  readonly error?: JsonRpcErrorObject',
         '}',
         '',
+        '// Elarion maps its transport-agnostic AppError kinds onto the JSON-RPC server-reserved range',
+        '// (-32000..-32099) via the framework default AppErrorMapper, so a frontend can branch on the kind',
+        '// directly instead of re-wrapping RpcError. These codes are a wire contract mirrored from the server',
+        "// (src/Elarion.JsonRpc/AppErrorMapper.cs) — keep both in sync. Validation reuses the standard -32602",
+        '// (isInvalidParams) and Internal reuses -32603 (isInternalError), so they are not repeated here.',
+        'export const ElarionErrorCodes = {',
+        '  notFound: -32001,',
+        '  conflict: -32002,',
+        '  forbidden: -32003,',
+        '  businessRule: -32004,',
+        '  unauthorized: -32005,',
+        '} as const',
+        '',
         'export class RpcError extends Error {',
         '  readonly code: number',
         '  readonly data?: unknown',
@@ -161,6 +174,28 @@ export function generateRpcClientSource(options) {
         '  get isInternalError() {',
         '    return this.code === -32603',
         '  }',
+        '',
+        '  // Elarion application-error kinds (see ElarionErrorCodes). isInvalidParams also covers Validation;',
+        '  // isInternalError also covers Internal.',
+        '  get isNotFound() {',
+        '    return this.code === ElarionErrorCodes.notFound',
+        '  }',
+        '',
+        '  get isConflict() {',
+        '    return this.code === ElarionErrorCodes.conflict',
+        '  }',
+        '',
+        '  get isForbidden() {',
+        '    return this.code === ElarionErrorCodes.forbidden',
+        '  }',
+        '',
+        '  get isBusinessRule() {',
+        '    return this.code === ElarionErrorCodes.businessRule',
+        '  }',
+        '',
+        '  get isUnauthorized() {',
+        '    return this.code === ElarionErrorCodes.unauthorized',
+        '  }',
         '}',
         '',
         'export class RpcTransportError extends Error {',
@@ -528,7 +563,7 @@ export function generateRpcClientSource(options) {
         '',
     ].join('\n');
 }
-function moduleSpecifier(fileName) {
+export function moduleSpecifier(fileName) {
     const withoutExtension = fileName.replace(/[.][cm]?tsx?$/, '');
     const relativePath = withoutExtension.startsWith('.')
         ? withoutExtension

package/dist/schema.d.ts

@@ -57,6 +57,14 @@ export interface GenerateRpcClientOptions {
     sessionClientFileName?: string;
     /** The operation name the client-capability snapshot is served under (default `elarion.session`). */
     sessionOperationName?: string;
+    /**
+     * Emit an opt-in framework adapter alongside the neutral core client. `tanstack-start` produces
+     * `start-adapter.ts` (request-scoped cookie forwarding via `@tanstack/react-start`). Omitted → no adapter,
+     * so output stays byte-identical for consumers that do not opt in.
+     */
+    framework?: 'tanstack-start';
+    /** Output filename for the framework adapter (default `start-adapter.ts`). */
+    frameworkAdapterFileName?: string;
 }
 export interface GeneratedRpcClientFiles {
     methodCount: number;
@@ -72,4 +80,10 @@ export interface GeneratedRpcClientFiles {
      */
     sessionClientFileName?: string;
     sessionClientSource?: string;
+    /**
+     * The opt-in framework adapter. Present only when `framework` is requested (e.g. `tanstack-start`); otherwise
+     * both fields are `undefined`.
+     */
+    frameworkAdapterFileName?: string;
+    frameworkAdapterSource?: string;
 }

package/dist/start-adapter-source.d.ts

@@ -0,0 +1,12 @@
+export interface GenerateStartAdapterSourceOptions {
+    generatedBy: string;
+    sourceLabel: string;
+    /** The core client filename the adapter imports from (default `rpc-client.ts`). */
+    clientFileName: string;
+}
+/**
+ * Emits the opt-in TanStack Start adapter (`start-adapter.ts`), produced only with `--framework tanstack-start`.
+ * It imports the framework-specific pieces (`@tanstack/react-start`) so the core generated client never does —
+ * a non-Start consumer neither installs nor imports this file, keeping the client's framework-neutral boundary.
+ */
+export declare function generateStartAdapterSource(options: GenerateStartAdapterSourceOptions): string;

package/dist/start-adapter-source.js

@@ -0,0 +1,73 @@
+import { moduleSpecifier } from './rpc-client-source.js';
+/**
+ * Emits the opt-in TanStack Start adapter (`start-adapter.ts`), produced only with `--framework tanstack-start`.
+ * It imports the framework-specific pieces (`@tanstack/react-start`) so the core generated client never does —
+ * a non-Start consumer neither installs nor imports this file, keeping the client's framework-neutral boundary.
+ */
+export function generateStartAdapterSource(options) {
+    const clientImport = moduleSpecifier(options.clientFileName);
+    return [
+        `// Auto-generated by ${options.generatedBy} — DO NOT EDIT`,
+        `// Source: ${options.sourceLabel}`,
+        '//',
+        '// Opt-in TanStack Start adapter (emitted only with `--framework tanstack-start`). Requires the',
+        '// `@tanstack/react-start` peer dependency. The core generated client never imports this module, so a',
+        '// consumer that does not opt in stays framework-neutral.',
+        "import { createIsomorphicFn } from '@tanstack/react-start'",
+        "import { getRequestHeader } from '@tanstack/react-start/server'",
+        `import { createRpcApi, type RpcApi, type RpcClientOptions, type RpcHeadersInit } from '${clientImport}'`,
+        '',
+        "// Forwards the incoming request's `cookie` during SSR so the RPC call runs as the signed-in user, and",
+        '// returns nothing in the browser. The read is isolated inside `createIsomorphicFn().server(...)` so the',
+        '// TanStack Start compiler strips both the read and the `@tanstack/react-start/server` import from the',
+        '// client bundle — a plain import (even one behind a `typeof window` guard) would fail `vite build` with',
+        '// `[import-protection] Import denied`.',
+        'export const forwardRequestCookie = createIsomorphicFn()',
+        '  .server((): RpcHeadersInit => {',
+        "    const cookie = getRequestHeader('cookie')",
+        '    return cookie ? { cookie } : {}',
+        '  })',
+        '  .client((): RpcHeadersInit => ({}))',
+        '',
+        '// Turnkey `createRpcApi` for a TanStack Start app: request-scoped cookie forwarding is pre-wired, and any',
+        '// `headers` you pass are layered on top (yours win on a conflict). Everything else in RpcClientOptions',
+        '// (url, fetch, idempotency, instrumentation, …) passes through unchanged.',
+        'export function createStartRpcApi(options: RpcClientOptions): RpcApi {',
+        '  const provided = options.headers',
+        '  return createRpcApi({',
+        '    ...options,',
+        '    headers: async (context) => {',
+        '      const cookie = await forwardRequestCookie()',
+        "      const extra = typeof provided === 'function' ? await provided(context) : provided",
+        '      return { ...toHeaderRecord(cookie), ...toHeaderRecord(extra) }',
+        '    },',
+        '  })',
+        '}',
+        '',
+        '// Normalizes any RpcHeadersInit (Headers, record, or entry tuples) to a plain record so the two sources',
+        '// can be merged with object spread.',
+        'function toHeaderRecord(init: RpcHeadersInit | undefined): Record<string, string> {',
+        '  const record: Record<string, string> = {}',
+        '  if (!init) {',
+        '    return record',
+        '  }',
+        '  if (init instanceof Headers) {',
+        '    init.forEach((value, key) => {',
+        '      record[key] = value',
+        '    })',
+        '    return record',
+        '  }',
+        '  if (Array.isArray(init)) {',
+        '    for (const [key, value] of init) {',
+        '      record[key] = value',
+        '    }',
+        '    return record',
+        '  }',
+        '  for (const [key, value] of Object.entries(init)) {',
+        '    record[key] = value',
+        '  }',
+        '  return record',
+        '}',
+        '',
+    ].join('\n');
+}

package/package.json

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