@swimmesberger/elarion-jsonrpc-client-generator 0.2.3-preview.83.1 → 0.2.3-preview.84.1

package/README.md

@@ -65,6 +65,18 @@ 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.
 
+## Client-event subscriptions
+
+When the schema carries an `events` block (the host registers Elarion client-event topics, ADR-0043), the generator additionally emits `events-client.ts`: `createElarionEvents(...)` multiplexes topic-typed subscriptions over one `EventSource`, validates incoming payloads with the generated Zod schemas (`rpcEventPayloadSchemas`), and exposes `$client.onConnected(...)` — fired on connect and every reconnect — as the "you may have missed events, re-query" signal. Event-free schemas produce byte-identical output with no events file.
+
+```ts
+import { createElarionEvents } from './generated/events-client'
+
+const events = createElarionEvents({ url: '/events' })
+events.invoicing.invoiceChanged.subscribe((evt) => refetch(evt.invoiceId))
+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 `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/cli.js

@@ -56,6 +56,11 @@ function parseArgs(argv) {
             index += 1;
             continue;
         }
+        if (arg === '--events-client') {
+            options.eventsClientFileName = next;
+            index += 1;
+            continue;
+        }
         if (arg === '--framework') {
             if (!SUPPORTED_FRAMEWORKS.includes(next)) {
                 throw new Error(`Unsupported framework ${next}. Supported: ${SUPPORTED_FRAMEWORKS.join(', ')}`);
@@ -89,6 +94,8 @@ 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)
+  --events-client <file>  Typed client-event subscription client (default: events-client.ts;
+                          emitted only when the schema declares an events block)
   --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)
@@ -127,6 +134,7 @@ function generateOnce(options) {
         schemasFileName: options.schemasFileName,
         clientFileName: options.clientFileName,
         sessionClientFileName: options.sessionClientFileName,
+        eventsClientFileName: options.eventsClientFileName,
         framework: options.framework,
         frameworkAdapterFileName: options.frameworkAdapterFileName,
     });
@@ -139,6 +147,10 @@ function generateOnce(options) {
         writeFileSync(resolve(outDir, generated.sessionClientFileName), generated.sessionClientSource, 'utf-8');
         extraNotes.push(generated.sessionClientFileName);
     }
+    if (generated.eventsClientFileName !== undefined && generated.eventsClientSource !== undefined) {
+        writeFileSync(resolve(outDir, generated.eventsClientFileName), generated.eventsClientSource, 'utf-8');
+        extraNotes.push(generated.eventsClientFileName);
+    }
     if (generated.frameworkAdapterFileName !== undefined && generated.frameworkAdapterSource !== undefined) {
         writeFileSync(resolve(outDir, generated.frameworkAdapterFileName), generated.frameworkAdapterSource, 'utf-8');
         extraNotes.push(generated.frameworkAdapterFileName);

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

@@ -0,0 +1,15 @@
+interface GenerateEventsClientSourceOptions {
+    generatedBy: string;
+    sourceLabel: string;
+    schemasFileName: string;
+    /** Sorted topic names from the schema's `events` block. */
+    topics: readonly string[];
+}
+/**
+ * Generates the typed client-event subscription client (ADR-0043) from the schema's `events` block: topic
+ * literal types, `z.infer` payload types over the Zod payload schemas (emitted into the schemas file), and
+ * an `EventSource` wrapper that multiplexes the authorized subscriptions over one connection. Emitted only
+ * when the schema declares events, so event-free schemas produce byte-identical output.
+ */
+export declare function generateEventsClientSource(options: GenerateEventsClientSourceOptions): string;
+export {};

package/dist/events-client-source.js

@@ -0,0 +1,314 @@
+import { moduleSpecifier } from './rpc-client-source.js';
+/**
+ * Generates the typed client-event subscription client (ADR-0043) from the schema's `events` block: topic
+ * literal types, `z.infer` payload types over the Zod payload schemas (emitted into the schemas file), and
+ * an `EventSource` wrapper that multiplexes the authorized subscriptions over one connection. Emitted only
+ * when the schema declares events, so event-free schemas produce byte-identical output.
+ */
+export function generateEventsClientSource(options) {
+    const schemasImport = moduleSpecifier(options.schemasFileName);
+    const topicTree = buildTopicTree(options.topics);
+    return [
+        `// Auto-generated by ${options.generatedBy} — DO NOT EDIT`,
+        `// Source: ${options.sourceLabel}`,
+        '',
+        "import type { z } from 'zod'",
+        `import { rpcEventPayloadSchemas } from '${schemasImport}'`,
+        '',
+        'export type RpcEventTopic = keyof typeof rpcEventPayloadSchemas & string',
+        'export type RpcEventPayload<T extends RpcEventTopic> = z.infer<(typeof rpcEventPayloadSchemas)[T]>',
+        '',
+        '// The structural surface of the platform EventSource this client needs — injectable for tests,',
+        '// polyfills, or a withCredentials/auth wrapper.',
+        'export interface ElarionEventSourceLike {',
+        '  addEventListener(type: string, listener: (event: { readonly data?: unknown }) => void): void',
+        '  close(): void',
+        '}',
+        '',
+        'export type ElarionEventSourceFactory = (url: string) => ElarionEventSourceLike',
+        '',
+        'export interface ElarionEventsOptions {',
+        '  readonly url: string | URL',
+        '  // Factory over the platform EventSource (defaults to globalThis.EventSource).',
+        '  readonly eventSource?: ElarionEventSourceFactory',
+        '  // Validate incoming payloads against the generated Zod payload schemas. Defaults to true.',
+        '  readonly validateEvents?: boolean',
+        '  // Called when an incoming event cannot be parsed or validated; the event is dropped either way.',
+        '  readonly onEventError?: (topic: RpcEventTopic, error: unknown) => void',
+        '}',
+        '',
+        'export interface ElarionEventSubscribeOptions {',
+        '  // Subscribe the topic within an application-defined resource scope (e.g. "customer:42"); the server',
+        '  // authorizes it fail-closed. Omitted, the subscription observes the global scope plus your own user scope.',
+        '  readonly resource?: string',
+        '}',
+        '',
+        'export type ElarionEventHandler<T extends RpcEventTopic> = (payload: RpcEventPayload<T>) => void',
+        'export type ElarionUnsubscribe = () => void',
+        '',
+        '// Client events are at-most-once hints: payloads carry ids/refs, and the client converges by re-running',
+        '// queries. Treat every onConnected callback (initial connect and every automatic reconnect) as "you may',
+        '// have missed events" and re-query — with TanStack Query, invalidate.',
+        'export interface ElarionEventsClient {',
+        '  subscribe<T extends RpcEventTopic>(topic: T, handler: ElarionEventHandler<T>): ElarionUnsubscribe',
+        '  subscribe<T extends RpcEventTopic>(',
+        '    topic: T,',
+        '    options: ElarionEventSubscribeOptions,',
+        '    handler: ElarionEventHandler<T>',
+        '  ): ElarionUnsubscribe',
+        '  // Fires on the server\'s elarion.connected control event — once per (re)connect.',
+        '  onConnected(handler: () => void): ElarionUnsubscribe',
+        '  close(): void',
+        '}',
+        '',
+        'export interface ElarionEventTopicApi<T extends RpcEventTopic> {',
+        '  subscribe(handler: ElarionEventHandler<T>): ElarionUnsubscribe',
+        '  subscribe(options: ElarionEventSubscribeOptions, handler: ElarionEventHandler<T>): ElarionUnsubscribe',
+        '}',
+        '',
+        'export interface ElarionEventsApi {',
+        '  readonly $client: ElarionEventsClient',
+        ...emitProperties(topicTree, 1),
+        '}',
+        '',
+        'const rpcEventTopicNames = [',
+        ...options.topics.map((topic) => `  ${JSON.stringify(topic)},`),
+        '] as const satisfies readonly RpcEventTopic[]',
+        '',
+        "const CONNECTED_EVENT_TYPE = 'elarion.connected'",
+        '',
+        'interface EventSubscriptionEntry {',
+        '  readonly topic: RpcEventTopic',
+        '  readonly resource?: string',
+        '  readonly handlers: Set<(payload: unknown) => void>',
+        '}',
+        '',
+        'export function createElarionEvents(options: ElarionEventsOptions): ElarionEventsApi {',
+        '  const client = createElarionEventsClient(options)',
+        '  const topics: Record<string, unknown> = {}',
+        '',
+        '  for (const topic of rpcEventTopicNames) {',
+        '    setTopicPath(topics, topic, {',
+        '      subscribe: (',
+        '        optionsOrHandler: ElarionEventSubscribeOptions | ElarionEventHandler<typeof topic>,',
+        '        maybeHandler?: ElarionEventHandler<typeof topic>',
+        '      ) => client.subscribe(topic, optionsOrHandler as ElarionEventSubscribeOptions, maybeHandler as ElarionEventHandler<typeof topic>),',
+        '    })',
+        '  }',
+        '',
+        '  return { ...topics, $client: client } as unknown as ElarionEventsApi',
+        '}',
+        '',
+        'export function createElarionEventsClient(options: ElarionEventsOptions): ElarionEventsClient {',
+        '  const createSource = options.eventSource ?? defaultEventSourceFactory',
+        '  const validateEvents = options.validateEvents ?? true',
+        '',
+        '  const subscriptions = new Map<string, EventSubscriptionEntry>()',
+        '  const connectedHandlers = new Set<() => void>()',
+        '  let source: ElarionEventSourceLike | undefined',
+        '  let reconnectScheduled = false',
+        '  let closed = false',
+        '',
+        '  // Subscription changes coalesce onto a microtask, so subscribing N topics during setup opens one',
+        '  // connection, not N. EventSource cannot change its URL, so a changed subscription set reconnects.',
+        '  function scheduleReconnect(): void {',
+        '    if (reconnectScheduled || closed) return',
+        '    reconnectScheduled = true',
+        '    queueMicrotask(() => {',
+        '      reconnectScheduled = false',
+        '      if (!closed) connect()',
+        '    })',
+        '  }',
+        '',
+        '  function connect(): void {',
+        '    source?.close()',
+        '    source = undefined',
+        '    if (subscriptions.size === 0) return',
+        '',
+        '    const requested = Array.from(subscriptions.values(), (entry) =>',
+        '      entry.resource === undefined ? { topic: entry.topic } : { topic: entry.topic, resource: entry.resource }',
+        '    ).sort(compareSubscriptions)',
+        '',
+        '    const next = createSource(appendSubscriptions(String(options.url), requested))',
+        '    for (const topic of new Set(Array.from(subscriptions.values(), (entry) => entry.topic))) {',
+        '      next.addEventListener(topic, (event) => dispatch(topic, event))',
+        '    }',
+        '    next.addEventListener(CONNECTED_EVENT_TYPE, () => {',
+        '      for (const handler of [...connectedHandlers]) handler()',
+        '    })',
+        '    source = next',
+        '  }',
+        '',
+        '  function dispatch(topic: RpcEventTopic, event: { readonly data?: unknown }): void {',
+        '    let payload: unknown',
+        '    try {',
+        '      payload = JSON.parse(String(event.data))',
+        '      if (validateEvents) {',
+        '        payload = rpcEventPayloadSchemas[topic].parse(payload)',
+        '      }',
+        '    } catch (error) {',
+        '      options.onEventError?.(topic, error)',
+        '      return',
+        '    }',
+        '',
+        '    // Handlers match by topic only: the server already filters by the connection\'s subscribed scopes,',
+        '    // but the wire frame carries no scope — handlers on the same topic see every matching event.',
+        '    for (const entry of subscriptions.values()) {',
+        '      if (entry.topic !== topic) continue',
+        '      for (const handler of [...entry.handlers]) handler(payload)',
+        '    }',
+        '  }',
+        '',
+        '  function subscribe<T extends RpcEventTopic>(',
+        '    topic: T,',
+        '    optionsOrHandler: ElarionEventSubscribeOptions | ElarionEventHandler<T>,',
+        '    maybeHandler?: ElarionEventHandler<T>',
+        '  ): ElarionUnsubscribe {',
+        "    const subscribeOptions = typeof optionsOrHandler === 'function' ? undefined : optionsOrHandler",
+        "    const handler = typeof optionsOrHandler === 'function' ? optionsOrHandler : maybeHandler",
+        "    if (typeof handler !== 'function') {",
+        "      throw new Error('subscribe requires a handler function.')",
+        '    }',
+        '    if (closed) {',
+        "      throw new Error('The events client is closed.')",
+        '    }',
+        '',
+        '    const key = subscriptionKey(topic, subscribeOptions?.resource)',
+        '    let entry = subscriptions.get(key)',
+        '    if (entry === undefined) {',
+        '      entry = { topic, resource: subscribeOptions?.resource, handlers: new Set() }',
+        '      subscriptions.set(key, entry)',
+        '      scheduleReconnect()',
+        '    }',
+        '',
+        '    // A fresh wrapper per call, so subscribing the same function twice yields two live subscriptions.',
+        '    const wrapped = (payload: unknown) => handler(payload as RpcEventPayload<T>)',
+        '    entry.handlers.add(wrapped)',
+        '    const current = entry',
+        '',
+        '    let active = true',
+        '    return () => {',
+        '      if (!active) return',
+        '      active = false',
+        '      current.handlers.delete(wrapped)',
+        '      if (current.handlers.size === 0 && subscriptions.get(key) === current) {',
+        '        subscriptions.delete(key)',
+        '        scheduleReconnect()',
+        '      }',
+        '    }',
+        '  }',
+        '',
+        '  return {',
+        "    subscribe: subscribe as ElarionEventsClient['subscribe'],",
+        '    onConnected(handler: () => void): ElarionUnsubscribe {',
+        '      connectedHandlers.add(handler)',
+        '      return () => {',
+        '        connectedHandlers.delete(handler)',
+        '      }',
+        '    },',
+        '    close(): void {',
+        '      closed = true',
+        '      source?.close()',
+        '      source = undefined',
+        '      subscriptions.clear()',
+        '      connectedHandlers.clear()',
+        '    },',
+        '  }',
+        '}',
+        '',
+        'function defaultEventSourceFactory(url: string): ElarionEventSourceLike {',
+        '  const ctor = (globalThis as { EventSource?: new (url: string) => ElarionEventSourceLike }).EventSource',
+        '  if (!ctor) {',
+        "    throw new Error('No EventSource implementation is available. Pass eventSource in createElarionEvents options.')",
+        '  }',
+        '  return new ctor(url)',
+        '}',
+        '',
+        '// The subscription set travels as one URL-encoded JSON query parameter (EventSource cannot POST), in a',
+        '// deterministic order so equal sets produce equal URLs.',
+        'function appendSubscriptions(',
+        '  url: string,',
+        '  requested: readonly { readonly topic: string; readonly resource?: string }[]',
+        '): string {',
+        "  const separator = url.includes('?') ? '&' : '?'",
+        '  return `${url}${separator}subscriptions=${encodeURIComponent(JSON.stringify(requested))}`',
+        '}',
+        '',
+        'function compareSubscriptions(',
+        '  left: { readonly topic: string; readonly resource?: string },',
+        '  right: { readonly topic: string; readonly resource?: string }',
+        '): number {',
+        '  if (left.topic !== right.topic) {',
+        '    return left.topic < right.topic ? -1 : 1',
+        '  }',
+        "  const leftResource = left.resource ?? ''",
+        "  const rightResource = right.resource ?? ''",
+        '  if (leftResource === rightResource) return 0',
+        '  return leftResource < rightResource ? -1 : 1',
+        '}',
+        '',
+        'function subscriptionKey(topic: string, resource: string | undefined): string {',
+        '  return resource === undefined ? topic : `${topic}\\u0000${resource}`',
+        '}',
+        '',
+        'function setTopicPath(root: Record<string, unknown>, topic: string, value: unknown): void {',
+        "  const segments = topic.split('.')",
+        '  let node = root',
+        '',
+        '  for (let index = 0; index < segments.length - 1; index += 1) {',
+        '    const segment = segments[index]',
+        '    const existing = node[segment]',
+        "    if (typeof existing === 'object' && existing !== null) {",
+        '      node = existing as Record<string, unknown>',
+        '      continue',
+        '    }',
+        '',
+        '    const next: Record<string, unknown> = {}',
+        '    node[segment] = next',
+        '    node = next',
+        '  }',
+        '',
+        '  node[segments[segments.length - 1] ?? topic] = value',
+        '}',
+        '',
+    ].join('\n');
+}
+function buildTopicTree(topics) {
+    const root = createTopicTreeNode();
+    for (const topic of topics) {
+        const segments = topic.split('.');
+        let node = root;
+        for (const segment of segments) {
+            let child = node.children.get(segment);
+            if (!child) {
+                child = createTopicTreeNode();
+                node.children.set(segment, child);
+            }
+            node = child;
+        }
+        node.topic = topic;
+    }
+    return root;
+}
+function createTopicTreeNode() {
+    return { children: new Map() };
+}
+function emitProperties(node, indent) {
+    const pad = '  '.repeat(indent);
+    return Array.from(node.children.entries())
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([segment, child]) => `${pad}readonly ${JSON.stringify(segment)}: ${emitNodeType(child, indent)}`);
+}
+function emitNodeType(node, indent) {
+    const childLines = emitProperties(node, indent + 1);
+    const childObject = childLines.length === 0
+        ? '{}'
+        : `{\n${childLines.join('\n')}\n${'  '.repeat(indent)}}`;
+    if (node.topic && childLines.length > 0) {
+        return `ElarionEventTopicApi<${JSON.stringify(node.topic)}> & ${childObject}`;
+    }
+    if (node.topic) {
+        return `ElarionEventTopicApi<${JSON.stringify(node.topic)}>`;
+    }
+    return childObject;
+}

package/dist/generate.js

@@ -1,3 +1,4 @@
+import { generateEventsClientSource } from './events-client-source.js';
 import { jsonSchemaToTypeScript } from './json-schema-to-ts.js';
 import { jsonSchemaToZod } from './json-schema-to-zod.js';
 import { collectFilePaths, stripNullable } from './json-schema.js';
@@ -12,6 +13,7 @@ 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';
+const DEFAULT_EVENTS_CLIENT_FILE = 'events-client.ts';
 export { UnsupportedJsonSchemaError } from './json-schema.js';
 export function generateRpcClientFiles(schema, options = {}) {
     const generatedBy = options.generatedBy ?? DEFAULT_GENERATED_BY;
@@ -64,6 +66,21 @@ export function generateRpcClientFiles(schema, options = {}) {
     schemasLines.push('');
     schemasLines.push('export type RpcResultSchemas = typeof rpcResultSchemas');
     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();
+    if (eventTopics.length > 0) {
+        schemasLines.push('export const rpcEventPayloadSchemas = {');
+        for (const topic of eventTopics) {
+            const definition = schema.events[topic];
+            const zodSchema = jsonSchemaToZod(stripNullable(definition.payload), createContext(definition.payload, `events.${topic}.payload`), 1);
+            schemasLines.push(`  ${JSON.stringify(topic)}: ${zodSchema},`);
+        }
+        schemasLines.push('} as const');
+        schemasLines.push('');
+        schemasLines.push('export type RpcEventPayloadSchemas = typeof rpcEventPayloadSchemas');
+        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.
@@ -104,6 +121,17 @@ export function generateRpcClientFiles(schema, options = {}) {
             capabilities: schema.capabilities,
         })
         : undefined;
+    // The typed client-event subscription client (ADR-0043) is emitted only when the schema declares an
+    // `events` block, so event-free schemas produce byte-identical output.
+    const eventsClientFileName = options.eventsClientFileName ?? DEFAULT_EVENTS_CLIENT_FILE;
+    const eventsClientSource = eventTopics.length > 0
+        ? generateEventsClientSource({
+            generatedBy,
+            sourceLabel,
+            schemasFileName,
+            topics: eventTopics,
+        })
+        : 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;
@@ -122,6 +150,8 @@ export function generateRpcClientFiles(schema, options = {}) {
         sessionClientSource,
         frameworkAdapterFileName: frameworkAdapterSource === undefined ? undefined : frameworkAdapterFileName,
         frameworkAdapterSource,
+        eventsClientFileName: eventsClientSource === undefined ? undefined : eventsClientFileName,
+        eventsClientSource,
     };
 }
 function createContext(root, path) {

package/dist/schema.d.ts

@@ -49,9 +49,18 @@ export interface RpcSchemaCapabilities {
     permissions?: RpcCapabilityPermission[];
     roles?: string[];
 }
+/**
+ * One client-event topic from the schema's `events` block (ADR-0043): the payload contract published on the
+ * topic. Delivery is at-most-once (SSE) — payloads are hints carrying ids/refs, not state.
+ */
+export interface RpcEventSchema {
+    payload: JsonSchema;
+}
 export interface RpcSchema {
     methods: Record<string, RpcMethodSchema>;
     capabilities?: RpcSchemaCapabilities;
+    /** Client-event topics by name, emitted by the server exporter when the host declares any (ADR-0043). */
+    events?: Record<string, RpcEventSchema>;
 }
 export interface GenerateRpcClientOptions {
     generatedBy?: string;
@@ -63,6 +72,8 @@ export interface GenerateRpcClientOptions {
     sessionClientFileName?: string;
     /** The operation name the client-capability snapshot is served under (default `elarion.session`). */
     sessionOperationName?: string;
+    /** Output filename for the client-event subscription client (default `events-client.ts`; emitted only when the schema declares events). */
+    eventsClientFileName?: 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,
@@ -92,4 +103,10 @@ export interface GeneratedRpcClientFiles {
      */
     frameworkAdapterFileName?: string;
     frameworkAdapterSource?: string;
+    /**
+     * The typed client-event subscription client (ADR-0043). Present only when the schema declares an `events`
+     * block; otherwise both fields are `undefined` and every other output stays byte-identical.
+     */
+    eventsClientFileName?: string;
+    eventsClientSource?: string;
 }

package/package.json

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