@swimmesberger/elarion-jsonrpc-client-generator 0.2.3-preview.76.1 → 0.2.3-preview.77.1

package/dist/generate.js

@@ -1,6 +1,6 @@
 import { jsonSchemaToTypeScript } from './json-schema-to-ts.js';
 import { jsonSchemaToZod } from './json-schema-to-zod.js';
-import { stripNullable } from './json-schema.js';
+import { collectFilePaths, 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';
@@ -65,6 +65,21 @@ export function generateRpcClientFiles(schema, options = {}) {
     schemasLines.push('export type RpcResultSchemas = typeof rpcResultSchemas');
     schemasLines.push('');
     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.
+    const paramsFilePaths = {};
+    const resultFilePaths = {};
+    for (const method of methods) {
+        const definition = schema.methods[method];
+        const params = collectFilePaths(stripNullable(definition.params), createContext(definition.params, `methods.${method}.params`));
+        if (params.length > 0) {
+            paramsFilePaths[method] = params;
+        }
+        const result = collectFilePaths(stripNullable(definition.result), createContext(definition.result, `methods.${method}.result`));
+        if (result.length > 0) {
+            resultFilePaths[method] = result;
+        }
+    }
     const clientSource = generateRpcClientSource({
         generatedBy,
         sourceLabel,
@@ -72,6 +87,8 @@ export function generateRpcClientFiles(schema, options = {}) {
         schemasFileName,
         methods,
         idempotentMethods,
+        paramsFilePaths,
+        resultFilePaths,
     });
     // The client-capability snapshot client + OpenFeature provider (ADR-0030) is emitted only when the host exposes
     // the session operation, so a schema without it produces byte-identical output. The schema's optional

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

@@ -4,6 +4,11 @@ export function jsonSchemaToTypeScript(schema, ctx, indent = 0) {
     const pad = '  '.repeat(indent);
     const nullable = isNullable(resolved);
     const base = baseType(resolved);
+    // The Elarion file envelope surfaces as a native File; the generated client converts to/from the
+    // base64 wire shape at the call boundary, so callers never see the envelope.
+    if (resolved['x-elarion-file'] === true) {
+        return nullable ? 'File | null | undefined' : 'File';
+    }
     if (resolved.enum) {
         const values = resolved.enum
             .filter((value) => value !== null)

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

@@ -3,6 +3,11 @@ export function jsonSchemaToZod(schema, ctx, indent = 0) {
     const resolved = resolveSchema(schema, ctx);
     const nullable = isNullable(resolved);
     const base = baseType(resolved);
+    // Schemas validate the user-facing shape: a file field is a native File on both sides of a call (the
+    // client encodes params after validation and decodes results before validation).
+    if (resolved['x-elarion-file'] === true) {
+        return nullish('z.instanceof(File)', nullable);
+    }
     if (resolved.enum) {
         const values = resolved.enum.filter((value) => value !== null);
         const allStrings = values.every((value) => typeof value === 'string');

package/dist/json-schema.d.ts

@@ -14,3 +14,10 @@ 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;
+/**
+ * Collects the property paths of every `x-elarion-file` node in a params/result schema (`[]` when the
+ * schema itself is the file, `'*'` for array items), so the generated client knows where to convert
+ * between native `File` values and the base64 wire envelope. Deterministic: property order follows the
+ * schema document.
+ */
+export declare function collectFilePaths(schema: JsonSchema, ctx: SchemaContext): string[][];

package/dist/json-schema.js

@@ -63,6 +63,32 @@ export function formatPropertyName(key) {
     }
     return JSON.stringify(key);
 }
+/**
+ * Collects the property paths of every `x-elarion-file` node in a params/result schema (`[]` when the
+ * schema itself is the file, `'*'` for array items), so the generated client knows where to convert
+ * between native `File` values and the base64 wire envelope. Deterministic: property order follows the
+ * schema document.
+ */
+export function collectFilePaths(schema, ctx) {
+    const paths = [];
+    visitFileNodes(schema, ctx, [], paths);
+    return paths;
+}
+function visitFileNodes(schema, ctx, prefix, paths) {
+    const resolved = resolveSchema(schema, ctx);
+    if (resolved['x-elarion-file'] === true) {
+        paths.push(prefix);
+        return;
+    }
+    if (resolved.items) {
+        visitFileNodes(stripNullable(resolved.items), childContext(ctx, 'items'), [...prefix, '*'], paths);
+    }
+    if (resolved.properties) {
+        for (const [key, property] of Object.entries(resolved.properties)) {
+            visitFileNodes(property, childContext(ctx, `properties.${key}`), [...prefix, key], paths);
+        }
+    }
+}
 function assertSupportedComposition(schema, path) {
     if (schema.oneOf) {
         throw new UnsupportedJsonSchemaError(path, 'oneOf is not supported');

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

@@ -5,6 +5,9 @@ interface GenerateRpcClientSourceOptions {
     schemasFileName: string;
     methods: readonly string[];
     idempotentMethods: 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[][]>>;
 }
 export declare function generateRpcClientSource(options: GenerateRpcClientSourceOptions): string;
 export declare function moduleSpecifier(fileName: string): string;

package/dist/rpc-client-source.js

@@ -5,6 +5,9 @@ export function generateRpcClientSource(options) {
     const typesImport = moduleSpecifier(options.typesFileName);
     const schemasImport = moduleSpecifier(options.schemasFileName);
     const methodTree = buildMethodTree(options.methods);
+    // File conversion is emitted only when the schema actually carries file payloads, so file-free schemas
+    // produce byte-identical output.
+    const hasFiles = Object.keys(options.paramsFilePaths).length > 0 || Object.keys(options.resultFilePaths).length > 0;
     return [
         `// Auto-generated by ${options.generatedBy} — DO NOT EDIT`,
         `// Source: ${options.sourceLabel}`,
@@ -110,6 +113,16 @@ export function generateRpcClientSource(options) {
         ...generateMethodNameLines(options.methods),
         `const rpcIdempotentMethods: ReadonlySet<RpcMethod> = new Set(${JSON.stringify(options.idempotentMethods)})`,
         '',
+        ...(hasFiles
+            ? [
+                '// Where each method carries file payloads: property paths into params/results ("*" descends into',
+                '// array items; an empty path means the value itself is the file). The client converts between',
+                '// native File values and the base64 wire envelope at exactly these positions.',
+                `const rpcParamsFilePaths: Partial<Record<RpcMethod, readonly (readonly string[])[]>> = ${JSON.stringify(options.paramsFilePaths)}`,
+                `const rpcResultFilePaths: Partial<Record<RpcMethod, readonly (readonly string[])[]>> = ${JSON.stringify(options.resultFilePaths)}`,
+                '',
+            ]
+            : []),
         'type JsonRpcId = string | number',
         '',
         'interface JsonRpcRequestEnvelope<M extends RpcMethod = RpcMethod> {',
@@ -328,8 +341,11 @@ export function generateRpcClientSource(options) {
         '      requestOptions?: RpcRequestOptions',
         '    ): Promise<RpcResult<M>> {',
         '      assertValidParams(method, params)',
+        ...(hasFiles ? ['      const wireParams = await encodeFileParams(method, params)'] : []),
         '      const idempotencyKey = resolveIdempotencyKey(method, requestOptions?.idempotencyKey)',
-        '      const request = createRequest(method, withIdempotencyKey(params, idempotencyKey), createId())',
+        hasFiles
+            ? '      const request = createRequest(method, withIdempotencyKey(wireParams, idempotencyKey), createId())'
+            : '      const request = createRequest(method, withIdempotencyKey(params, idempotencyKey), createId())',
         '      const context: RpcRequestContext = { methods: [method], batch: false }',
         '      const span = options.instrumentation?.startSpan(context)',
         '      try {',
@@ -343,7 +359,9 @@ export function generateRpcClientSource(options) {
         '          throw toRpcError(response.error)',
         '        }',
         '',
-        '        return parseResult(method, response.result)',
+        hasFiles
+            ? '        return parseResult(method, decodeFileResult(method, response.result))'
+            : '        return parseResult(method, response.result)',
         '      } catch (error) {',
         '        span?.setError(error)',
         '        throw error',
@@ -365,13 +383,29 @@ export function generateRpcClientSource(options) {
         '        assertValidParams(item.method, item.params)',
         '      }',
         '',
-        '      const requests = items.map((item) =>',
-        '        createRequest(',
-        '          item.method,',
-        '          withIdempotencyKey(item.params, resolveIdempotencyKey(item.method, item.idempotencyKey)),',
-        '          createId()',
-        '        )',
-        '      )',
+        ...(hasFiles
+            ? [
+                '      const requests: JsonRpcRequestEnvelope[] = []',
+                '      for (const item of items) {',
+                '        requests.push(createRequest(',
+                '          item.method,',
+                '          withIdempotencyKey(',
+                '            await encodeFileParams(item.method, item.params),',
+                '            resolveIdempotencyKey(item.method, item.idempotencyKey)',
+                '          ),',
+                '          createId()',
+                '        ))',
+                '      }',
+            ]
+            : [
+                '      const requests = items.map((item) =>',
+                '        createRequest(',
+                '          item.method,',
+                '          withIdempotencyKey(item.params, resolveIdempotencyKey(item.method, item.idempotencyKey)),',
+                '          createId()',
+                '        )',
+                '      )',
+            ]),
         '      const context: RpcRequestContext = { methods: items.map((item) => item.method), batch: true }',
         '      const span = options.instrumentation?.startSpan(context)',
         '      try {',
@@ -406,7 +440,9 @@ export function generateRpcClientSource(options) {
         '          }',
         '',
         '          try {',
-        '            return { ok: true, result: parseResult(method, response.result) }',
+        hasFiles
+            ? '            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) }",
         '          }',
@@ -447,6 +483,7 @@ export function generateRpcClientSource(options) {
         `  return { ...base, _meta: { ...existingMeta, [${JSON.stringify(IDEMPOTENCY_META_KEY)}]: key } }`,
         '}',
         '',
+        ...(hasFiles ? generateFileConversionLines() : []),
         'function setApiPath(root: Record<string, unknown>, method: string, value: unknown): void {',
         "  const segments = method.split('.')",
         '  let node = root',
@@ -641,3 +678,103 @@ function generateMethodNameLines(methods) {
         '',
     ];
 }
+// The runtime file-conversion block, emitted only for schemas that carry file payloads: native File values
+// convert to the Elarion base64 envelope ({ contentType, fileName?, data }) after params validation, and
+// results convert back before validation — so schemas and callers only ever see File. Every API used is
+// standard in browsers and Node 20+ (File, atob/btoa, Uint8Array).
+function generateFileConversionLines() {
+    return [
+        'interface RpcFileEnvelope {',
+        '  readonly contentType: string',
+        '  readonly fileName?: string',
+        '  readonly data: string',
+        '}',
+        '',
+        'async function encodeFileParams(method: RpcMethod, params: unknown): Promise<unknown> {',
+        '  const paths = rpcParamsFilePaths[method]',
+        '  if (!paths) return params',
+        '  let value = params',
+        '  for (const path of paths) {',
+        '    value = await encodeFilesAtPath(value, path, 0)',
+        '  }',
+        '  return value',
+        '}',
+        '',
+        'function decodeFileResult(method: RpcMethod, result: unknown): unknown {',
+        '  const paths = rpcResultFilePaths[method]',
+        '  if (!paths) return result',
+        '  let value = result',
+        '  for (const path of paths) {',
+        '    value = decodeEnvelopesAtPath(value, path, 0)',
+        '  }',
+        '  return value',
+        '}',
+        '',
+        'async function encodeFilesAtPath(value: unknown, path: readonly string[], index: number): Promise<unknown> {',
+        '  if (index === path.length) {',
+        '    return value instanceof File ? fileToEnvelope(value) : value',
+        '  }',
+        '',
+        '  const segment = path[index]',
+        "  if (segment === '*') {",
+        '    if (!Array.isArray(value)) return value',
+        '    return Promise.all(value.map((item) => encodeFilesAtPath(item, path, index + 1)))',
+        '  }',
+        '',
+        '  if (!isRecord(value) || value[segment] === undefined) return value',
+        '  return { ...value, [segment]: await encodeFilesAtPath(value[segment], path, index + 1) }',
+        '}',
+        '',
+        'function decodeEnvelopesAtPath(value: unknown, path: readonly string[], index: number): unknown {',
+        '  if (index === path.length) {',
+        '    return isFileEnvelope(value) ? envelopeToFile(value) : value',
+        '  }',
+        '',
+        '  const segment = path[index]',
+        "  if (segment === '*') {",
+        '    if (!Array.isArray(value)) return value',
+        '    return value.map((item) => decodeEnvelopesAtPath(item, path, index + 1))',
+        '  }',
+        '',
+        '  if (!isRecord(value) || value[segment] === undefined) return value',
+        '  return { ...value, [segment]: decodeEnvelopesAtPath(value[segment], path, index + 1) }',
+        '}',
+        '',
+        'function isFileEnvelope(value: unknown): value is RpcFileEnvelope {',
+        "  return isRecord(value) && typeof value['contentType'] === 'string' && typeof value['data'] === 'string'",
+        '}',
+        '',
+        'async function fileToEnvelope(file: File): Promise<RpcFileEnvelope> {',
+        '  const bytes = new Uint8Array(await file.arrayBuffer())',
+        "  const contentType = file.type || 'application/octet-stream'",
+        '  return file.name',
+        '    ? { contentType, fileName: file.name, data: bytesToBase64(bytes) }',
+        '    : { contentType, data: bytesToBase64(bytes) }',
+        '}',
+        '',
+        'function envelopeToFile(envelope: RpcFileEnvelope): File {',
+        "  return new File([base64ToBytes(envelope.data)], envelope.fileName ?? '', { type: envelope.contentType })",
+        '}',
+        '',
+        'function bytesToBase64(bytes: Uint8Array): string {',
+        "  let binary = ''",
+        '  const chunkSize = 0x8000',
+        '  for (let offset = 0; offset < bytes.length; offset += chunkSize) {',
+        '    binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize))',
+        '  }',
+        '  return btoa(binary)',
+        '}',
+        '',
+        // No return annotation: inference yields Uint8Array<ArrayBuffer> under TS 5.7+ (required by BlobPart)
+        // while staying valid for consumers on older TypeScript where Uint8Array is not generic.
+        'function base64ToBytes(base64: string) {',
+        '  const binary = atob(base64)',
+        '  const bytes = new Uint8Array(binary.length)',
+        '  for (let index = 0; index < binary.length; index += 1) {',
+        '    bytes[index] = binary.charCodeAt(index)',
+        '  }',
+        '  return bytes',
+        '}',
+        '',
+    ];
+}

package/dist/schema.d.ts

@@ -10,6 +10,12 @@ export interface JsonSchema {
     oneOf?: unknown[];
     anyOf?: unknown[];
     allOf?: unknown[];
+    /**
+     * Marks the Elarion binary-file envelope (`{ contentType, fileName?, data }`, base64 `data`), emitted by the
+     * server exporter for `ElarionFile` payloads. The generator maps it to a native `File`: params accept a
+     * `File`, results materialize one; the client converts to/from the wire envelope at the call boundary.
+     */
+    'x-elarion-file'?: boolean;
     minLength?: number;
     maxLength?: number;
     pattern?: string;

package/package.json

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