@swimmesberger/elarion-jsonrpc-client-generator 0.2.3-preview.40.1 → 0.2.3-preview.41.1

package/dist/generate.js

@@ -49,12 +49,14 @@ export function generateRpcClientFiles(schema, options = {}) {
     schemasLines.push('');
     schemasLines.push('export type RpcResultSchemas = typeof rpcResultSchemas');
     schemasLines.push('');
+    const idempotentMethods = methods.filter((method) => schema.methods[method].idempotent === true);
     const clientSource = generateRpcClientSource({
         generatedBy,
         sourceLabel,
         typesFileName,
         schemasFileName,
         methods,
+        idempotentMethods,
     });
     return {
         methodCount: methods.length,

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

@@ -4,6 +4,7 @@ interface GenerateRpcClientSourceOptions {
     typesFileName: string;
     schemasFileName: string;
     methods: readonly string[];
+    idempotentMethods: readonly string[];
 }
 export declare function generateRpcClientSource(options: GenerateRpcClientSourceOptions): string;
 export {};

package/dist/rpc-client-source.js

@@ -1,3 +1,6 @@
+// The framework-owned params._meta key that carries the idempotency key (matches the server's
+// IdempotencyKeyNames.MetaKey).
+const IDEMPOTENCY_META_KEY = 'dev.wimmesberger.elarion/idempotencyKey';
 export function generateRpcClientSource(options) {
     const typesImport = moduleSpecifier(options.typesFileName);
     const schemasImport = moduleSpecifier(options.schemasFileName);
@@ -42,6 +45,17 @@ export function generateRpcClientSource(options) {
         '  startSpan(context: RpcRequestContext): RpcClientSpan | undefined',
         '}',
         '',
+        '// Automatic idempotency-key attachment. For operations the server marked [Idempotent], the client puts a',
+        '// generated key in `params._meta` so a retry is deduplicated server-side. On by default; note that any',
+        '// retry layer above this client (e.g. TanStack Query) must own key stability — generate the key once at the',
+        '// operation boundary and pass it via `RpcRequestOptions.idempotencyKey`, so all retries reuse the same key.',
+        'export interface RpcIdempotencyOptions {',
+        '  // Attach a key by default to idempotent operations. Defaults to true.',
+        '  readonly enabled?: boolean',
+        '  // Key factory (defaults to crypto.randomUUID with a fallback). Called once per logical call.',
+        '  readonly generateKey?: () => string',
+        '}',
+        '',
         'export interface RpcClientOptions {',
         '  readonly url: string | URL',
         '  readonly fetch?: RpcFetch',
@@ -50,16 +64,22 @@ export function generateRpcClientSource(options) {
         '  readonly validateResults?: boolean',
         '  readonly transformResult?: <M extends RpcMethod>(method: M, result: unknown) => unknown',
         '  readonly instrumentation?: RpcInstrumentation',
+        '  readonly idempotency?: RpcIdempotencyOptions',
         '}',
         '',
         'export interface RpcRequestOptions {',
         '  readonly signal?: AbortSignal',
         '  readonly headers?: RpcHeadersInit',
+        '  // Override the idempotency key for this call: a fixed key (reuse across your own retries), or `false` to',
+        '  // send no key. When omitted, an idempotent operation gets an auto-generated key.',
+        '  readonly idempotencyKey?: string | false',
         '}',
         '',
         'export interface BatchItem<M extends RpcMethod = RpcMethod> {',
         '  readonly method: M',
         '  readonly params: RpcParams<M>',
+        '  // Per-item idempotency key override (see RpcRequestOptions.idempotencyKey).',
+        '  readonly idempotencyKey?: string | false',
         '}',
         '',
         'export type BatchItemResult<M extends RpcMethod = RpcMethod> =',
@@ -85,6 +105,8 @@ export function generateRpcClientSource(options) {
         '}',
         '',
         ...generateMethodNameLines(options.methods),
+        `const rpcIdempotentMethods: ReadonlySet<RpcMethod> = new Set(${JSON.stringify(options.idempotentMethods)})`,
+        '',
         'type JsonRpcId = string | number',
         '',
         'interface JsonRpcRequestEnvelope<M extends RpcMethod = RpcMethod> {',
@@ -190,6 +212,17 @@ export function generateRpcClientSource(options) {
         '  let nextId = 1',
         '  const createId = options.idGenerator ?? (() => globalThis.crypto?.randomUUID?.() ?? String(nextId++))',
         '  const validateResults = options.validateResults ?? true',
+        '  const idempotencyEnabled = options.idempotency?.enabled ?? true',
+        '  const generateIdempotencyKey = options.idempotency?.generateKey ?? defaultIdempotencyKey',
+        '',
+        '  function resolveIdempotencyKey<M extends RpcMethod>(',
+        '    method: M,',
+        '    override: string | false | undefined',
+        '  ): string | undefined {',
+        '    if (override === false) return undefined',
+        "    if (typeof override === 'string') return override",
+        '    return idempotencyEnabled && rpcIdempotentMethods.has(method) ? generateIdempotencyKey() : undefined',
+        '  }',
         '',
         '  async function post(',
         '    payload: unknown,',
@@ -226,7 +259,8 @@ export function generateRpcClientSource(options) {
         '      params: RpcParams<M>,',
         '      requestOptions?: RpcRequestOptions',
         '    ): Promise<RpcResult<M>> {',
-        '      const request = createRequest(method, params, createId())',
+        '      const idempotencyKey = resolveIdempotencyKey(method, requestOptions?.idempotencyKey)',
+        '      const request = createRequest(method, withIdempotencyKey(params, idempotencyKey), createId())',
         '      const context: RpcRequestContext = { methods: [method], batch: false }',
         '      const span = options.instrumentation?.startSpan(context)',
         '      try {',
@@ -257,7 +291,13 @@ export function generateRpcClientSource(options) {
         '        return [] as unknown as BatchResult<T>',
         '      }',
         '',
-        '      const requests = items.map((item) => createRequest(item.method, item.params, 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 {',
@@ -309,10 +349,28 @@ export function generateRpcClientSource(options) {
         '',
         'function createRequest<M extends RpcMethod>(',
         '  method: M,',
-        '  params: RpcParams<M>,',
+        '  params: unknown,',
         '  id: JsonRpcId',
         '): JsonRpcRequestEnvelope<M> {',
-        "  return { jsonrpc: '2.0', method, params, id }",
+        "  return { jsonrpc: '2.0', method, params: params as RpcParams<M>, id }",
+        '}',
+        '',
+        'function defaultIdempotencyKey(): string {',
+        '  const uuid = globalThis.crypto?.randomUUID?.()',
+        '  if (uuid) return uuid',
+        '  return `idem-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`',
+        '}',
+        '',
+        '// Merges the idempotency key into params._meta without mutating the input object; no-op when no key.',
+        'function withIdempotencyKey(params: unknown, key: string | undefined): unknown {',
+        '  if (key === undefined) return params',
+        "  const base = params && typeof params === 'object' && !Array.isArray(params)",
+        '    ? (params as Record<string, unknown>)',
+        '    : {}',
+        "  const existingMeta = base['_meta'] && typeof base['_meta'] === 'object' && !Array.isArray(base['_meta'])",
+        "    ? (base['_meta'] as Record<string, unknown>)",
+        '    : {}',
+        `  return { ...base, _meta: { ...existingMeta, [${JSON.stringify(IDEMPOTENCY_META_KEY)}]: key } }`,
         '}',
         '',
         'function setApiPath(root: Record<string, unknown>, method: string, value: unknown): void {',

package/dist/schema.d.ts

@@ -14,6 +14,7 @@ export interface JsonSchema {
 export interface RpcMethodSchema {
     params: JsonSchema;
     result: JsonSchema;
+    idempotent?: boolean;
 }
 export interface RpcSchema {
     methods: Record<string, RpcMethodSchema>;

package/package.json

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