@drarzter/kafka-client 0.10.0 → 0.11.0

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import {
+  ConfluentTransport,
   HEADER_CORRELATION_ID,
   HEADER_DELAYED_TARGET,
   HEADER_DELAYED_UNTIL,
@@ -13,7 +14,6 @@ import {
   KafkaProcessingError,
   KafkaRetryExhaustedError,
   KafkaValidationError,
-  SchemaRegistryClient,
   awsMskIamProvider,
   buildEnvelopeHeaders,
   consumerOptionsFromEnv,
@@ -24,7 +24,6 @@ import {
   getEnvelopeContext,
   kafkaClientConfigFromEnv,
   mergeConsumerOptions,
-  registrySchema,
   resolveSecurityOptions,
   runWithEnvelopeContext,
   startOutboxRelay,
@@ -33,7 +32,12 @@ import {
   toMskIamPolicy,
   topic,
   versionedSchema
-} from "./chunk-CMO7SMVK.mjs";
+} from "./chunk-OR7TPAAE.mjs";
+import {
+  JsonSerde,
+  SchemaRegistryClient,
+  registrySchema
+} from "./chunk-PQVBRDNV.mjs";
 import {
   __decorateClass,
   __decorateParam
@@ -238,6 +242,7 @@ KafkaHealthIndicator = __decorateClass([
   Injectable2()
 ], KafkaHealthIndicator);
 export {
+  ConfluentTransport,
   HEADER_CORRELATION_ID,
   HEADER_DELAYED_TARGET,
   HEADER_DELAYED_UNTIL,
@@ -249,6 +254,7 @@ export {
   InMemoryDedupStore,
   InMemoryOutboxStore,
   InjectKafkaClient,
+  JsonSerde,
   KAFKA_CLIENT,
   KAFKA_SUBSCRIBER_METADATA,
   KafkaClient,

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/nest/kafka.module.ts","../src/nest/kafka.constants.ts","../src/nest/kafka.explorer.ts","../src/nest/kafka.decorator.ts","../src/nest/kafka.health.ts"],"sourcesContent":["import { Module, DynamicModule, Provider, Logger } from \"@nestjs/common\";\nimport { DiscoveryModule } from \"@nestjs/core\";\nimport {\n  KafkaClient,\n  ClientId,\n  GroupId,\n  TopicMapConstraint,\n  KafkaInstrumentation,\n  KafkaClientOptions,\n} from \"../client/kafka.client\";\nimport { getKafkaClientToken } from \"./kafka.constants\";\nimport { KafkaExplorer } from \"./kafka.explorer\";\n\n/** Shared configuration fields for both `register()` and `registerAsync()`. */\ninterface KafkaModuleBaseOptions {\n  /** Optional name for multi-client setups. Must match `@InjectKafkaClient(name)`. */\n  name?: string;\n  /** If true, makes KAFKA_CLIENT available globally without importing KafkaModule in every feature module. */\n  isGlobal?: boolean;\n}\n\n/** Synchronous configuration for `KafkaModule.register()`. */\nexport interface KafkaModuleOptions extends KafkaModuleBaseOptions {\n  /** Unique Kafka client identifier. */\n  clientId: ClientId;\n  /** Consumer group identifier. */\n  groupId: GroupId;\n  /** List of Kafka broker addresses. */\n  brokers: string[];\n  /** Auto-create topics via admin on first use (send/consume). Useful for development. */\n  autoCreateTopics?: boolean;\n  /** When `true`, string topic keys are validated against any schema previously registered via a TopicDescriptor. Default: `true`. */\n  strictSchemas?: boolean;\n  /** Number of partitions for auto-created topics. Default: `1`. */\n  numPartitions?: number;\n  /** Client-wide instrumentation hooks (e.g. OTel). Applied to both send and consume paths. */\n  instrumentation?: KafkaInstrumentation[];\n  /** Called when a message is dropped without being sent to a DLQ. @see `KafkaClientOptions.onMessageLost` */\n  onMessageLost?: KafkaClientOptions[\"onMessageLost\"];\n  /** Called whenever a consumer group rebalance occurs. @see `KafkaClientOptions.onRebalance` */\n  onRebalance?: KafkaClientOptions[\"onRebalance\"];\n  /** Transactional producer ID — must be unique per process/replica. @see `KafkaClientOptions.transactionalId` */\n  transactionalId?: KafkaClientOptions[\"transactionalId\"];\n  /** Recover the Lamport clock from these topics on startup. @see `KafkaClientOptions.clockRecovery` */\n  clockRecovery?: KafkaClientOptions[\"clockRecovery\"];\n  /** Delay producer sends when consumer lag exceeds a threshold. @see `KafkaClientOptions.lagThrottle` */\n  lagThrottle?: KafkaClientOptions[\"lagThrottle\"];\n  /** Client-wide TTL expiry callback. @see `KafkaClientOptions.onTtlExpired` */\n  onTtlExpired?: KafkaClientOptions[\"onTtlExpired\"];\n  /** Custom transport implementation (e.g. `FakeTransport` in tests). @see `KafkaClientOptions.transport` */\n  transport?: KafkaClientOptions[\"transport\"];\n  /** Transport security (TLS + SASL, incl. MSK IAM / GCP OAUTHBEARER). @see `KafkaClientOptions.security` */\n  security?: KafkaClientOptions[\"security\"];\n}\n\n/** Async configuration for `KafkaModule.registerAsync()` with dependency injection. */\nexport interface KafkaModuleAsyncOptions extends KafkaModuleBaseOptions {\n  imports?: any[];\n  useFactory: (\n    ...args: any[]\n  ) => KafkaModuleOptions | Promise<KafkaModuleOptions>;\n  inject?: any[];\n}\n\n/**\n * NestJS dynamic module for registering type-safe Kafka clients.\n * Use `register()` for static config or `registerAsync()` for DI-based config.\n */\n@Module({})\nexport class KafkaModule {\n  /** Register a Kafka client with static options. */\n  static register<T extends TopicMapConstraint<T>>(\n    options: KafkaModuleOptions,\n  ): DynamicModule {\n    const token = getKafkaClientToken(options.name);\n\n    const kafkaClientProvider: Provider = {\n      provide: token,\n      useFactory: () => KafkaModule.buildClient<T>(options),\n    };\n\n    return {\n      global: options.isGlobal ?? false,\n      module: KafkaModule,\n      imports: [DiscoveryModule],\n      providers: [kafkaClientProvider, KafkaExplorer],\n      exports: [kafkaClientProvider],\n    };\n  }\n\n  /** Register a Kafka client with async/factory-based options. */\n  static registerAsync<T extends TopicMapConstraint<T>>(\n    asyncOptions: KafkaModuleAsyncOptions,\n  ): DynamicModule {\n    const token = getKafkaClientToken(asyncOptions.name);\n\n    const kafkaClientProvider: Provider = {\n      provide: token,\n      useFactory: async (...args: any[]): Promise<KafkaClient<T>> =>\n        KafkaModule.buildClient<T>(await asyncOptions.useFactory(...args)),\n      inject: asyncOptions.inject || [],\n    };\n\n    return {\n      global: asyncOptions.isGlobal ?? false,\n      module: KafkaModule,\n      imports: [...(asyncOptions.imports || []), DiscoveryModule],\n      providers: [kafkaClientProvider, KafkaExplorer],\n      exports: [kafkaClientProvider],\n    };\n  }\n\n  private static async buildClient<T extends TopicMapConstraint<T>>(\n    options: KafkaModuleOptions,\n  ): Promise<KafkaClient<T>> {\n    const client = new KafkaClient<T>(\n      options.clientId,\n      options.groupId,\n      options.brokers,\n      {\n        autoCreateTopics: options.autoCreateTopics,\n        strictSchemas: options.strictSchemas,\n        numPartitions: options.numPartitions,\n        instrumentation: options.instrumentation,\n        onMessageLost: options.onMessageLost,\n        onRebalance: options.onRebalance,\n        transactionalId: options.transactionalId,\n        clockRecovery: options.clockRecovery,\n        lagThrottle: options.lagThrottle,\n        onTtlExpired: options.onTtlExpired,\n        transport: options.transport,\n        security: options.security,\n        logger: new Logger(`KafkaClient:${options.clientId}`),\n      },\n    );\n    await client.connectProducer();\n    return client;\n  }\n}\n","/** Default DI token for the Kafka client. */\nexport const KAFKA_CLIENT = \"KAFKA_CLIENT\";\n\n/** Returns the DI token for a named (or default) Kafka client instance. */\nexport const getKafkaClientToken = (name?: string): string =>\n  name ? `KAFKA_CLIENT_${name}` : KAFKA_CLIENT;\n","import { Inject, Injectable, OnModuleInit, Logger } from \"@nestjs/common\";\nimport { DiscoveryService, ModuleRef } from \"@nestjs/core\";\nimport { KafkaClient } from \"../client/kafka.client\";\nimport {\n  KAFKA_SUBSCRIBER_METADATA,\n  KafkaSubscriberMetadata,\n} from \"./kafka.decorator\";\nimport { getKafkaClientToken } from \"./kafka.constants\";\n\ninterface SubscriberEntry extends KafkaSubscriberMetadata {\n  methodName: string | symbol;\n}\n\n/**\n * Process-level registry of already-wired subscriptions, keyed by provider\n * instance. Every `KafkaModule.register()` call contributes its own\n * `KafkaExplorer`, and each explorer scans ALL providers — without this guard\n * a multi-client app would wire every `@SubscribeTo` handler once per\n * registered module (duplicate consumers / \"called twice\" startup errors).\n * Keyed by instance (not constructor) so separate Nest apps in one process\n * (e.g. tests) still wire their own instances independently.\n */\nconst wiredSubscriptions = new WeakMap<object, Set<string>>();\n\n/** Discovers `@SubscribeTo()` decorators and wires them to their Kafka clients on startup. */\n@Injectable()\nexport class KafkaExplorer implements OnModuleInit {\n  private readonly logger = new Logger(KafkaExplorer.name);\n\n  constructor(\n    @Inject(DiscoveryService)\n    private readonly discoveryService: DiscoveryService,\n    @Inject(ModuleRef)\n    private readonly moduleRef: ModuleRef,\n  ) {}\n\n  /**\n   * Scan all NestJS providers for `@SubscribeTo()` metadata and wire each decorated\n   * method to its Kafka client via `startConsumer` or `startBatchConsumer`.\n   *\n   * Called automatically by the NestJS lifecycle — do not invoke manually.\n   */\n  async onModuleInit() {\n    const providers = this.discoveryService.getProviders();\n\n    for (const wrapper of providers) {\n      const { instance } = wrapper;\n      if (!instance || typeof instance !== \"object\") continue;\n\n      const metadata: SubscriberEntry[] | undefined = Reflect.getMetadata(\n        KAFKA_SUBSCRIBER_METADATA,\n        instance.constructor,\n      );\n\n      if (!metadata || metadata.length === 0) continue;\n\n      for (const entry of metadata) {\n        const token = getKafkaClientToken(entry.clientName);\n\n        const entryKey = `${token}:${String(entry.methodName)}`;\n        let wired = wiredSubscriptions.get(instance);\n        if (!wired) {\n          wired = new Set();\n          wiredSubscriptions.set(instance, wired);\n        }\n        if (wired.has(entryKey)) continue; // already wired by another KafkaExplorer instance\n        wired.add(entryKey);\n\n        let client: KafkaClient<any>;\n\n        try {\n          client = this.moduleRef.get(token, { strict: false });\n        } catch {\n          this.logger.error(\n            `KafkaClient \"${entry.clientName || \"default\"}\" not found for @SubscribeTo on ${instance.constructor.name}.${String(entry.methodName)}`,\n          );\n          continue;\n        }\n\n        const handler = (instance as any)[entry.methodName].bind(instance);\n\n        const consumerOptions = { ...entry.options };\n        if (entry.schemas) {\n          consumerOptions.schemas = entry.schemas;\n        }\n\n        if (entry.batch) {\n          await client.startBatchConsumer(\n            entry.topics as any,\n            async (envelopes: any[], meta: any) => {\n              await handler(envelopes, meta);\n            },\n            consumerOptions,\n          );\n        } else {\n          await client.startConsumer(\n            entry.topics as any,\n            async (envelope: any) => {\n              await handler(envelope);\n            },\n            consumerOptions,\n          );\n        }\n\n        this.logger.log(\n          `Registered @SubscribeTo(${entry.topics.join(\", \")})${entry.batch ? \" [batch]\" : \"\"} on ${instance.constructor.name}.${String(entry.methodName)}`,\n        );\n      }\n    }\n  }\n}\n","import { Inject } from \"@nestjs/common\";\nimport { getKafkaClientToken } from \"./kafka.constants\";\nimport { ConsumerOptions } from \"../client/kafka.client\";\nimport { TopicDescriptor, SchemaLike } from \"../client/message/topic\";\n\n/** Reflect metadata key used to store `@SubscribeTo` entries on a class constructor. */\nexport const KAFKA_SUBSCRIBER_METADATA = \"KAFKA_SUBSCRIBER_METADATA\";\n\n/** Internal shape stored per `@SubscribeTo()` decoration on a class. */\nexport interface KafkaSubscriberMetadata {\n  /** Resolved topic name strings (descriptors are unwrapped to their `__topic` string). */\n  topics: string[];\n  /** Per-topic schema validators extracted from `TopicDescriptor` objects (if any). */\n  schemas?: Map<string, SchemaLike>;\n  /** Additional consumer options forwarded to `startConsumer` / `startBatchConsumer`. */\n  options?: ConsumerOptions;\n  /** Named client identifier — resolves to `KAFKA_CLIENT_<clientName>` in the DI container. */\n  clientName?: string;\n  /** When `true`, routes to `startBatchConsumer` instead of `startConsumer`. */\n  batch?: boolean;\n  /** Name of the decorated method on the provider class. */\n  methodName?: string | symbol;\n}\n\n/** Inject a `KafkaClient` instance. Pass a name to target a specific named client. */\nexport const InjectKafkaClient = (name?: string): ParameterDecorator =>\n  Inject(getKafkaClientToken(name));\n\n/**\n * Method decorator that auto-subscribes the decorated method to one or more Kafka topics\n * when the NestJS module initialises.\n *\n * The decorated method receives a fully-decoded `EventEnvelope` for each message\n * (or an array of envelopes + `BatchMeta` when `batch: true`).\n *\n * @param topics One or more topic names or `TopicDescriptor` objects. Schemas embedded in\n *   descriptors are automatically extracted and forwarded to the consumer.\n * @param options Consumer and routing options:\n *   - All `ConsumerOptions` fields (`groupId`, `retry`, `dlq`, `fromBeginning`, …)\n *   - `clientName` — target a named `KafkaClient` (resolves `KAFKA_CLIENT_<name>` from the DI container)\n *   - `batch` — use `startBatchConsumer` instead of `startConsumer`\n *\n * @example\n * ```ts\n * @SubscribeTo('orders.created', { groupId: 'orders-svc', retry: { maxRetries: 3 } })\n * async handleOrder(envelope: EventEnvelope<Order>) { ... }\n *\n * @SubscribeTo(OrdersTopic, { batch: true })\n * async handleBatch(envelopes: EventEnvelope<Order>[], meta: BatchMeta) { ... }\n * ```\n */\nexport const SubscribeTo = (\n  topics:\n    | string\n    | string[]\n    | TopicDescriptor\n    | TopicDescriptor[]\n    | (string | TopicDescriptor)[],\n  options?: ConsumerOptions & { clientName?: string; batch?: boolean },\n): MethodDecorator => {\n  const arr = Array.isArray(topics) ? topics : [topics];\n  const topicsArray = arr.map((t) => (typeof t === \"string\" ? t : t.__topic));\n\n  // Extract schemas from descriptors that have them\n  const schemas = new Map<string, SchemaLike>();\n  for (const t of arr) {\n    if (typeof t !== \"string\" && t.__schema) {\n      schemas.set(t.__topic, t.__schema);\n    }\n  }\n\n  const { clientName, batch, ...consumerOptions } = options || {};\n\n  return (target, propertyKey, _descriptor) => {\n    const existing: KafkaSubscriberMetadata[] =\n      Reflect.getMetadata(KAFKA_SUBSCRIBER_METADATA, target.constructor) || [];\n\n    Reflect.defineMetadata(\n      KAFKA_SUBSCRIBER_METADATA,\n      [\n        ...existing,\n        {\n          topics: topicsArray,\n          schemas: schemas.size > 0 ? schemas : undefined,\n          options: Object.keys(consumerOptions).length\n            ? consumerOptions\n            : undefined,\n          clientName,\n          batch,\n          methodName: propertyKey,\n        },\n      ],\n      target.constructor,\n    );\n  };\n};\n","import { Injectable } from \"@nestjs/common\";\nimport type {\n  IKafkaClient,\n  KafkaHealthResult,\n  TopicMapConstraint,\n} from \"../client/types\";\nexport type { KafkaHealthResult } from \"../client/types\";\n\n/** Health check service. Call `check(client)` to verify broker connectivity. */\n@Injectable()\nexport class KafkaHealthIndicator {\n  async check<T extends TopicMapConstraint<T>>(\n    client: IKafkaClient<T>,\n  ): Promise<KafkaHealthResult> {\n    return client.checkStatus();\n  }\n}\n"],"mappings":"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","names":["Logger","Inject","Inject","Logger","Injectable","Injectable"]}
+{"version":3,"sources":["../src/nest/kafka.module.ts","../src/nest/kafka.constants.ts","../src/nest/kafka.explorer.ts","../src/nest/kafka.decorator.ts","../src/nest/kafka.health.ts"],"sourcesContent":["import { Module, DynamicModule, Provider, Logger } from \"@nestjs/common\";\nimport { DiscoveryModule } from \"@nestjs/core\";\nimport {\n  KafkaClient,\n  ClientId,\n  GroupId,\n  TopicMapConstraint,\n  KafkaInstrumentation,\n  KafkaClientOptions,\n} from \"../client/kafka.client\";\nimport { getKafkaClientToken } from \"./kafka.constants\";\nimport { KafkaExplorer } from \"./kafka.explorer\";\n\n/** Shared configuration fields for both `register()` and `registerAsync()`. */\ninterface KafkaModuleBaseOptions {\n  /** Optional name for multi-client setups. Must match `@InjectKafkaClient(name)`. */\n  name?: string;\n  /** If true, makes KAFKA_CLIENT available globally without importing KafkaModule in every feature module. */\n  isGlobal?: boolean;\n}\n\n/** Synchronous configuration for `KafkaModule.register()`. */\nexport interface KafkaModuleOptions extends KafkaModuleBaseOptions {\n  /** Unique Kafka client identifier. */\n  clientId: ClientId;\n  /** Consumer group identifier. */\n  groupId: GroupId;\n  /** List of Kafka broker addresses. */\n  brokers: string[];\n  /** Auto-create topics via admin on first use (send/consume). Useful for development. */\n  autoCreateTopics?: boolean;\n  /** When `true`, string topic keys are validated against any schema previously registered via a TopicDescriptor. Default: `true`. */\n  strictSchemas?: boolean;\n  /** Number of partitions for auto-created topics. Default: `1`. */\n  numPartitions?: number;\n  /** Client-wide instrumentation hooks (e.g. OTel). Applied to both send and consume paths. */\n  instrumentation?: KafkaInstrumentation[];\n  /** Called when a message is dropped without being sent to a DLQ. @see `KafkaClientOptions.onMessageLost` */\n  onMessageLost?: KafkaClientOptions[\"onMessageLost\"];\n  /** Called whenever a consumer group rebalance occurs. @see `KafkaClientOptions.onRebalance` */\n  onRebalance?: KafkaClientOptions[\"onRebalance\"];\n  /** Transactional producer ID — must be unique per process/replica. @see `KafkaClientOptions.transactionalId` */\n  transactionalId?: KafkaClientOptions[\"transactionalId\"];\n  /** Recover the Lamport clock from these topics on startup. @see `KafkaClientOptions.clockRecovery` */\n  clockRecovery?: KafkaClientOptions[\"clockRecovery\"];\n  /** Delay producer sends when consumer lag exceeds a threshold. @see `KafkaClientOptions.lagThrottle` */\n  lagThrottle?: KafkaClientOptions[\"lagThrottle\"];\n  /** Client-wide TTL expiry callback. @see `KafkaClientOptions.onTtlExpired` */\n  onTtlExpired?: KafkaClientOptions[\"onTtlExpired\"];\n  /** Custom transport implementation (e.g. `FakeTransport` in tests). @see `KafkaClientOptions.transport` */\n  transport?: KafkaClientOptions[\"transport\"];\n  /** Transport security (TLS + SASL, incl. MSK IAM / GCP OAUTHBEARER). @see `KafkaClientOptions.security` */\n  security?: KafkaClientOptions[\"security\"];\n}\n\n/** Async configuration for `KafkaModule.registerAsync()` with dependency injection. */\nexport interface KafkaModuleAsyncOptions extends KafkaModuleBaseOptions {\n  imports?: any[];\n  useFactory: (\n    ...args: any[]\n  ) => KafkaModuleOptions | Promise<KafkaModuleOptions>;\n  inject?: any[];\n}\n\n/**\n * NestJS dynamic module for registering type-safe Kafka clients.\n * Use `register()` for static config or `registerAsync()` for DI-based config.\n */\n@Module({})\nexport class KafkaModule {\n  /** Register a Kafka client with static options. */\n  static register<T extends TopicMapConstraint<T>>(\n    options: KafkaModuleOptions,\n  ): DynamicModule {\n    const token = getKafkaClientToken(options.name);\n\n    const kafkaClientProvider: Provider = {\n      provide: token,\n      useFactory: () => KafkaModule.buildClient<T>(options),\n    };\n\n    return {\n      global: options.isGlobal ?? false,\n      module: KafkaModule,\n      imports: [DiscoveryModule],\n      providers: [kafkaClientProvider, KafkaExplorer],\n      exports: [kafkaClientProvider],\n    };\n  }\n\n  /** Register a Kafka client with async/factory-based options. */\n  static registerAsync<T extends TopicMapConstraint<T>>(\n    asyncOptions: KafkaModuleAsyncOptions,\n  ): DynamicModule {\n    const token = getKafkaClientToken(asyncOptions.name);\n\n    const kafkaClientProvider: Provider = {\n      provide: token,\n      useFactory: async (...args: any[]): Promise<KafkaClient<T>> =>\n        KafkaModule.buildClient<T>(await asyncOptions.useFactory(...args)),\n      inject: asyncOptions.inject || [],\n    };\n\n    return {\n      global: asyncOptions.isGlobal ?? false,\n      module: KafkaModule,\n      imports: [...(asyncOptions.imports || []), DiscoveryModule],\n      providers: [kafkaClientProvider, KafkaExplorer],\n      exports: [kafkaClientProvider],\n    };\n  }\n\n  private static async buildClient<T extends TopicMapConstraint<T>>(\n    options: KafkaModuleOptions,\n  ): Promise<KafkaClient<T>> {\n    const client = new KafkaClient<T>(\n      options.clientId,\n      options.groupId,\n      options.brokers,\n      {\n        autoCreateTopics: options.autoCreateTopics,\n        strictSchemas: options.strictSchemas,\n        numPartitions: options.numPartitions,\n        instrumentation: options.instrumentation,\n        onMessageLost: options.onMessageLost,\n        onRebalance: options.onRebalance,\n        transactionalId: options.transactionalId,\n        clockRecovery: options.clockRecovery,\n        lagThrottle: options.lagThrottle,\n        onTtlExpired: options.onTtlExpired,\n        transport: options.transport,\n        security: options.security,\n        logger: new Logger(`KafkaClient:${options.clientId}`),\n      },\n    );\n    await client.connectProducer();\n    return client;\n  }\n}\n","/** Default DI token for the Kafka client. */\nexport const KAFKA_CLIENT = \"KAFKA_CLIENT\";\n\n/** Returns the DI token for a named (or default) Kafka client instance. */\nexport const getKafkaClientToken = (name?: string): string =>\n  name ? `KAFKA_CLIENT_${name}` : KAFKA_CLIENT;\n","import { Inject, Injectable, OnModuleInit, Logger } from \"@nestjs/common\";\nimport { DiscoveryService, ModuleRef } from \"@nestjs/core\";\nimport { KafkaClient } from \"../client/kafka.client\";\nimport {\n  KAFKA_SUBSCRIBER_METADATA,\n  KafkaSubscriberMetadata,\n} from \"./kafka.decorator\";\nimport { getKafkaClientToken } from \"./kafka.constants\";\n\ninterface SubscriberEntry extends KafkaSubscriberMetadata {\n  methodName: string | symbol;\n}\n\n/**\n * Process-level registry of already-wired subscriptions, keyed by provider\n * instance. Every `KafkaModule.register()` call contributes its own\n * `KafkaExplorer`, and each explorer scans ALL providers — without this guard\n * a multi-client app would wire every `@SubscribeTo` handler once per\n * registered module (duplicate consumers / \"called twice\" startup errors).\n * Keyed by instance (not constructor) so separate Nest apps in one process\n * (e.g. tests) still wire their own instances independently.\n */\nconst wiredSubscriptions = new WeakMap<object, Set<string>>();\n\n/** Discovers `@SubscribeTo()` decorators and wires them to their Kafka clients on startup. */\n@Injectable()\nexport class KafkaExplorer implements OnModuleInit {\n  private readonly logger = new Logger(KafkaExplorer.name);\n\n  constructor(\n    @Inject(DiscoveryService)\n    private readonly discoveryService: DiscoveryService,\n    @Inject(ModuleRef)\n    private readonly moduleRef: ModuleRef,\n  ) {}\n\n  /**\n   * Scan all NestJS providers for `@SubscribeTo()` metadata and wire each decorated\n   * method to its Kafka client via `startConsumer` or `startBatchConsumer`.\n   *\n   * Called automatically by the NestJS lifecycle — do not invoke manually.\n   */\n  async onModuleInit() {\n    const providers = this.discoveryService.getProviders();\n\n    for (const wrapper of providers) {\n      const { instance } = wrapper;\n      if (!instance || typeof instance !== \"object\") continue;\n\n      const metadata: SubscriberEntry[] | undefined = Reflect.getMetadata(\n        KAFKA_SUBSCRIBER_METADATA,\n        instance.constructor,\n      );\n\n      if (!metadata || metadata.length === 0) continue;\n\n      for (const entry of metadata) {\n        const token = getKafkaClientToken(entry.clientName);\n\n        const entryKey = `${token}:${String(entry.methodName)}`;\n        let wired = wiredSubscriptions.get(instance);\n        if (!wired) {\n          wired = new Set();\n          wiredSubscriptions.set(instance, wired);\n        }\n        if (wired.has(entryKey)) continue; // already wired by another KafkaExplorer instance\n        wired.add(entryKey);\n\n        let client: KafkaClient<any>;\n\n        try {\n          client = this.moduleRef.get(token, { strict: false });\n        } catch {\n          this.logger.error(\n            `KafkaClient \"${entry.clientName || \"default\"}\" not found for @SubscribeTo on ${instance.constructor.name}.${String(entry.methodName)}`,\n          );\n          continue;\n        }\n\n        const handler = (instance as any)[entry.methodName].bind(instance);\n\n        const consumerOptions = { ...entry.options };\n        if (entry.schemas) {\n          consumerOptions.schemas = entry.schemas;\n        }\n\n        if (entry.batch) {\n          await client.startBatchConsumer(\n            entry.topics as any,\n            async (envelopes: any[], meta: any) => {\n              await handler(envelopes, meta);\n            },\n            consumerOptions,\n          );\n        } else {\n          await client.startConsumer(\n            entry.topics as any,\n            async (envelope: any) => {\n              await handler(envelope);\n            },\n            consumerOptions,\n          );\n        }\n\n        this.logger.log(\n          `Registered @SubscribeTo(${entry.topics.join(\", \")})${entry.batch ? \" [batch]\" : \"\"} on ${instance.constructor.name}.${String(entry.methodName)}`,\n        );\n      }\n    }\n  }\n}\n","import { Inject } from \"@nestjs/common\";\nimport { getKafkaClientToken } from \"./kafka.constants\";\nimport { ConsumerOptions } from \"../client/kafka.client\";\nimport { TopicDescriptor, SchemaLike } from \"../client/message/topic\";\n\n/** Reflect metadata key used to store `@SubscribeTo` entries on a class constructor. */\nexport const KAFKA_SUBSCRIBER_METADATA = \"KAFKA_SUBSCRIBER_METADATA\";\n\n/** Internal shape stored per `@SubscribeTo()` decoration on a class. */\nexport interface KafkaSubscriberMetadata {\n  /** Resolved topic name strings (descriptors are unwrapped to their `__topic` string). */\n  topics: string[];\n  /** Per-topic schema validators extracted from `TopicDescriptor` objects (if any). */\n  schemas?: Map<string, SchemaLike>;\n  /** Additional consumer options forwarded to `startConsumer` / `startBatchConsumer`. */\n  options?: ConsumerOptions;\n  /** Named client identifier — resolves to `KAFKA_CLIENT_<clientName>` in the DI container. */\n  clientName?: string;\n  /** When `true`, routes to `startBatchConsumer` instead of `startConsumer`. */\n  batch?: boolean;\n  /** Name of the decorated method on the provider class. */\n  methodName?: string | symbol;\n}\n\n/** Inject a `KafkaClient` instance. Pass a name to target a specific named client. */\nexport const InjectKafkaClient = (name?: string): ParameterDecorator =>\n  Inject(getKafkaClientToken(name));\n\n/**\n * Method decorator that auto-subscribes the decorated method to one or more Kafka topics\n * when the NestJS module initialises.\n *\n * The decorated method receives a fully-decoded `EventEnvelope` for each message\n * (or an array of envelopes + `BatchMeta` when `batch: true`).\n *\n * @param topics One or more topic names or `TopicDescriptor` objects. Schemas embedded in\n *   descriptors are automatically extracted and forwarded to the consumer.\n * @param options Consumer and routing options:\n *   - All `ConsumerOptions` fields (`groupId`, `retry`, `dlq`, `fromBeginning`, …)\n *   - `clientName` — target a named `KafkaClient` (resolves `KAFKA_CLIENT_<name>` from the DI container)\n *   - `batch` — use `startBatchConsumer` instead of `startConsumer`\n *\n * @example\n * ```ts\n * @SubscribeTo('orders.created', { groupId: 'orders-svc', retry: { maxRetries: 3 } })\n * async handleOrder(envelope: EventEnvelope<Order>) { ... }\n *\n * @SubscribeTo(OrdersTopic, { batch: true })\n * async handleBatch(envelopes: EventEnvelope<Order>[], meta: BatchMeta) { ... }\n * ```\n */\nexport const SubscribeTo = (\n  topics:\n    | string\n    | string[]\n    | TopicDescriptor\n    | TopicDescriptor[]\n    | (string | TopicDescriptor)[],\n  options?: ConsumerOptions & { clientName?: string; batch?: boolean },\n): MethodDecorator => {\n  const arr = Array.isArray(topics) ? topics : [topics];\n  const topicsArray = arr.map((t) => (typeof t === \"string\" ? t : t.__topic));\n\n  // Extract schemas from descriptors that have them\n  const schemas = new Map<string, SchemaLike>();\n  for (const t of arr) {\n    if (typeof t !== \"string\" && t.__schema) {\n      schemas.set(t.__topic, t.__schema);\n    }\n  }\n\n  const { clientName, batch, ...consumerOptions } = options || {};\n\n  return (target, propertyKey, _descriptor) => {\n    const existing: KafkaSubscriberMetadata[] =\n      Reflect.getMetadata(KAFKA_SUBSCRIBER_METADATA, target.constructor) || [];\n\n    Reflect.defineMetadata(\n      KAFKA_SUBSCRIBER_METADATA,\n      [\n        ...existing,\n        {\n          topics: topicsArray,\n          schemas: schemas.size > 0 ? schemas : undefined,\n          options: Object.keys(consumerOptions).length\n            ? consumerOptions\n            : undefined,\n          clientName,\n          batch,\n          methodName: propertyKey,\n        },\n      ],\n      target.constructor,\n    );\n  };\n};\n","import { Injectable } from \"@nestjs/common\";\nimport type {\n  IKafkaClient,\n  KafkaHealthResult,\n  TopicMapConstraint,\n} from \"../client/types\";\nexport type { KafkaHealthResult } from \"../client/types\";\n\n/** Health check service. Call `check(client)` to verify broker connectivity. */\n@Injectable()\nexport class KafkaHealthIndicator {\n  async check<T extends TopicMapConstraint<T>>(\n    client: IKafkaClient<T>,\n  ): Promise<KafkaHealthResult> {\n    return client.checkStatus();\n  }\n}\n"],"mappings":"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","names":["Logger","Inject","Inject","Logger","Injectable","Injectable"]}

package/dist/serde.d.ts

@@ -0,0 +1,157 @@
+import type { MessageSerde, SerdeContext } from "./client/message/serde";
+import type { SchemaRegistryClient } from "./client/message/schema-registry";
+export { JsonSerde } from "./client/message/serde";
+export type { MessageSerde, SerdeContext } from "./client/message/serde";
+export { SchemaRegistryClient } from "./client/message/schema-registry";
+/** Injectable dynamic-import function — overridable in tests. */
+type ImportFn = (specifier: string) => Promise<any>;
+/** Options common to the registry-backed serdes. */
+interface RegistrySerdeCommonOptions {
+    /** Schema Registry client used to resolve/register schema ids. */
+    registry: SchemaRegistryClient;
+    /**
+     * Subject name. Defaults to Confluent `TopicNameStrategy`
+     * (`<topic>-value` / `<topic>-key`). Provide a literal string or a
+     * function of the {@link SerdeContext} to override.
+     */
+    subject?: string | ((ctx: SerdeContext) => string);
+    /**
+     * Register `schema` on first serialize to obtain its id (dev-friendly).
+     * Default `false` → the id is resolved via `getLatestSchema(subject)`.
+     */
+    autoRegister?: boolean;
+    /** @internal Injectable dynamic import for tests. */
+    importFn?: ImportFn;
+}
+/** Options for {@link avroSerde}. */
+export interface AvroSerdeOptions extends RegistrySerdeCommonOptions {
+    /**
+     * Avro schema (JSON string or object) used to serialize, and as the
+     * write-schema fallback. Required to serialize; deserialize resolves the
+     * writer schema from the registry via the wire-format id.
+     */
+    schema?: string | object;
+}
+/**
+ * Confluent-wire-format **Avro** serde backed by a Schema Registry.
+ *
+ * Produces/consumes the exact byte layout Java/Go clients use, so this library
+ * interoperates with them through a shared registry:
+ *
+ * ```
+ * [magic 0x00][schema id: 4-byte big-endian][avro binary]
+ * ```
+ *
+ * Uses the optional peer dependency [`avsc`](https://www.npmjs.com/package/avsc)
+ * via dynamic import — install it to enable Avro:
+ *
+ * ```bash
+ * npm install avsc
+ * ```
+ *
+ * - **serialize**: resolves the subject from the context, obtains the schema id
+ *   (`registerSchema` when `autoRegister`, else `getLatestSchema`), Avro-encodes
+ *   `value` against `schema`, and frames the bytes.
+ * - **deserialize**: reads the magic byte + big-endian id, resolves the writer
+ *   schema via `registry.getSchemaById(id)` (cached forever), and Avro-decodes
+ *   the remainder. The reader schema equals the writer schema in v1 — full
+ *   reader-schema resolution / schema evolution is a future enhancement.
+ *
+ * The parsed `avsc` type is cached per schema string so repeated messages don't
+ * re-parse the schema.
+ *
+ * @example
+ * ```ts
+ * import { avroSerde } from '@drarzter/kafka-client/serde';
+ * import { SchemaRegistryClient } from '@drarzter/kafka-client';
+ *
+ * const registry = new SchemaRegistryClient({ baseUrl: 'http://localhost:8081' });
+ * const orderSchema = {
+ *   type: 'record',
+ *   name: 'Order',
+ *   fields: [{ name: 'orderId', type: 'string' }, { name: 'amount', type: 'double' }],
+ * };
+ *
+ * // Per-topic:
+ * const Orders = topic('orders')
+ *   .serde(avroSerde({ registry, schema: orderSchema }))
+ *   .type<Order>();
+ *
+ * // Client-wide:
+ * const kafka = new KafkaClient(id, group, brokers, {
+ *   serde: avroSerde({ registry, schema: orderSchema }),
+ * });
+ * ```
+ */
+export declare function avroSerde(options: AvroSerdeOptions): MessageSerde;
+/** Options for {@link protobufSerde}. */
+export interface ProtobufSerdeOptions extends RegistrySerdeCommonOptions {
+    /**
+     * Fully-qualified Protobuf message name to encode/decode,
+     * e.g. `"com.acme.orders.Order"`.
+     */
+    messageType: string;
+    /**
+     * `.proto` source string defining {@link ProtobufSerdeOptions.messageType}.
+     * Required to serialize; deserialize resolves the writer `.proto` from the
+     * registry via the wire-format id.
+     */
+    schema?: string;
+}
+/**
+ * Confluent-wire-format **Protobuf** serde backed by a Schema Registry.
+ *
+ * Produces/consumes the exact byte layout Java/Go clients use:
+ *
+ * ```
+ * [magic 0x00][schema id: 4-byte big-endian][message-index][protobuf binary]
+ * ```
+ *
+ * The **message-index** identifies which message type within the `.proto` file
+ * was used. For the first/top-level message type (index `[0]`) Confluent writes
+ * the single byte `0x00`. This serde implements that top-level case only —
+ * multiple/nested message types are a documented v1 limitation and cause a
+ * clear error on deserialize.
+ *
+ * Uses the optional peer dependency
+ * [`protobufjs`](https://www.npmjs.com/package/protobufjs) via dynamic import —
+ * install it to enable Protobuf:
+ *
+ * ```bash
+ * npm install protobufjs
+ * ```
+ *
+ * - **serialize**: obtains the schema id (`registerSchema` when `autoRegister`,
+ *   else `getLatestSchema`), encodes `value` with the `protobufjs` `Type`, and
+ *   frames it with the `0x00` message-index byte.
+ * - **deserialize**: reads the magic byte + big-endian id + message-index (which
+ *   must be the single `0x00` byte), resolves the writer `.proto` via
+ *   `registry.getSchemaById(id)` (cached forever), and decodes the remainder.
+ *
+ * The parsed `protobufjs` `Type` is cached per schema string so repeated
+ * messages don't re-parse the `.proto`.
+ *
+ * @example
+ * ```ts
+ * import { protobufSerde } from '@drarzter/kafka-client/serde';
+ * import { SchemaRegistryClient } from '@drarzter/kafka-client';
+ *
+ * const registry = new SchemaRegistryClient({ baseUrl: 'http://localhost:8081' });
+ * const proto = `
+ *   syntax = "proto3";
+ *   message Order { string orderId = 1; double amount = 2; }
+ * `;
+ *
+ * // Per-topic:
+ * const Orders = topic('orders')
+ *   .serde(protobufSerde({ registry, schema: proto, messageType: 'Order' }))
+ *   .type<Order>();
+ *
+ * // Client-wide:
+ * const kafka = new KafkaClient(id, group, brokers, {
+ *   serde: protobufSerde({ registry, schema: proto, messageType: 'Order' }),
+ * });
+ * ```
+ */
+export declare function protobufSerde(options: ProtobufSerdeOptions): MessageSerde;
+//# sourceMappingURL=serde.d.ts.map

package/dist/serde.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serde.d.ts","sourceRoot":"","sources":["../src/serde.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAI7E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAKxE,iEAAiE;AACjE,KAAK,QAAQ,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAqEpD,oDAAoD;AACpD,UAAU,0BAA0B;IAClC,kEAAkE;IAClE,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,YAAY,KAAK,MAAM,CAAC,CAAC;IACnD;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAiB,SAAQ,0BAA0B;IAClE;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CA4DjE;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAqB,SAAQ,0BAA0B;IACtE;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,YAAY,CAiFzE"}

package/dist/serde.js

@@ -0,0 +1,308 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/serde.ts
+var serde_exports = {};
+__export(serde_exports, {
+  JsonSerde: () => JsonSerde,
+  SchemaRegistryClient: () => SchemaRegistryClient,
+  avroSerde: () => avroSerde,
+  protobufSerde: () => protobufSerde
+});
+module.exports = __toCommonJS(serde_exports);
+var import_node_module = require("module");
+
+// src/client/message/serde.ts
+var JsonSerde = class {
+  /** JSON-stringify the validated payload. Returns a UTF-8 string. */
+  serialize(value) {
+    return JSON.stringify(value);
+  }
+  /** JSON-parse UTF-8 wire bytes into an object. */
+  deserialize(data) {
+    return JSON.parse(data.toString("utf8"));
+  }
+};
+
+// src/client/message/schema-registry.ts
+var SchemaRegistryClient = class {
+  constructor(options) {
+    this.options = options;
+    if (!options.baseUrl) {
+      throw new Error("SchemaRegistryClient: baseUrl is required");
+    }
+    this.fetchFn = options.fetchFn ?? fetch;
+    this.cacheTtlMs = options.cacheTtlMs ?? 3e5;
+  }
+  options;
+  fetchFn;
+  cacheTtlMs;
+  latestCache = /* @__PURE__ */ new Map();
+  /**
+   * `id → schema` cache. Schema ids are immutable in a Confluent-compatible
+   * registry (a given id always maps to the same schema string), so entries
+   * are cached for the lifetime of the client with no TTL.
+   */
+  byIdCache = /* @__PURE__ */ new Map();
+  headers() {
+    const h = {
+      "Content-Type": "application/vnd.schemaregistry.v1+json"
+    };
+    if (this.options.auth) {
+      const { username, password } = this.options.auth;
+      h["Authorization"] = "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
+    }
+    return h;
+  }
+  async request(method, path, body) {
+    const url = `${this.options.baseUrl.replace(/\/$/, "")}${path}`;
+    const res = await this.fetchFn(url, {
+      method,
+      headers: this.headers(),
+      ...body !== void 0 && { body: JSON.stringify(body) }
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `SchemaRegistry ${method} ${path} failed: ${res.status} ${res.statusText}${text ? ` \u2014 ${text}` : ""}`
+      );
+    }
+    return await res.json();
+  }
+  /** Fetch the latest schema registered under `subject`. Cached for `cacheTtlMs`. */
+  async getLatestSchema(subject) {
+    const cached = this.latestCache.get(subject);
+    if (cached && cached.expiresAt > Date.now()) return cached.value;
+    const raw = await this.request("GET", `/subjects/${encodeURIComponent(subject)}/versions/latest`);
+    const value = {
+      id: raw.id,
+      version: raw.version,
+      schema: raw.schema
+    };
+    this.latestCache.set(subject, {
+      value,
+      expiresAt: Date.now() + this.cacheTtlMs
+    });
+    return value;
+  }
+  /**
+   * Fetch a schema by its globally unique registry id (`GET /schemas/ids/{id}`).
+   *
+   * Used by the Avro/Protobuf serdes on the deserialize path: the writer schema
+   * id is read from the Confluent wire-format prefix, then resolved here. Results
+   * are cached forever (schema ids are immutable), so a given id triggers exactly
+   * one registry round-trip regardless of how many messages reference it.
+   */
+  async getSchemaById(id) {
+    const cached = this.byIdCache.get(id);
+    if (cached) return cached;
+    const raw = await this.request(
+      "GET",
+      `/schemas/ids/${id}`
+    );
+    const value = { id, schema: raw.schema, schemaType: raw.schemaType };
+    this.byIdCache.set(id, value);
+    return value;
+  }
+  /** Fetch a specific schema version of a subject. */
+  async getSchemaVersion(subject, version) {
+    const raw = await this.request(
+      "GET",
+      `/subjects/${encodeURIComponent(subject)}/versions/${version}`
+    );
+    return { id: raw.id, version: raw.version, schema: raw.schema };
+  }
+  /**
+   * Register a schema under `subject` (idempotent — re-registering the same
+   * schema returns the existing id). Returns the registry-assigned schema id.
+   */
+  async registerSchema(subject, schema, schemaType = "JSON") {
+    this.latestCache.delete(subject);
+    return this.request(
+      "POST",
+      `/subjects/${encodeURIComponent(subject)}/versions`,
+      { schema, schemaType }
+    );
+  }
+  /**
+   * Test `schema` against the subject's compatibility policy without registering.
+   * Returns `true` when the registry reports the schema as compatible.
+   */
+  async checkCompatibility(subject, schema, schemaType = "JSON") {
+    const res = await this.request(
+      "POST",
+      `/compatibility/subjects/${encodeURIComponent(subject)}/versions/latest`,
+      { schema, schemaType }
+    );
+    return res.is_compatible;
+  }
+};
+
+// src/serde.ts
+var MAGIC_BYTE = 0;
+var defaultImport = async (specifier) => {
+  const base = typeof __filename !== "undefined" ? __filename : `${process.cwd()}/index.js`;
+  const req = (0, import_node_module.createRequire)(base);
+  const mod = req(specifier);
+  return mod?.default ?? mod;
+};
+function resolveSubject(ctx, subject) {
+  if (typeof subject === "function") return subject(ctx);
+  if (typeof subject === "string") return subject;
+  return `${ctx.topic}-${ctx.isKey ? "key" : "value"}`;
+}
+function readWireHeader(data, serdeName) {
+  if (data.length < 5) {
+    throw new Error(
+      `${serdeName}: message too short to be Confluent-framed (need >= 5 bytes, got ${data.length}).`
+    );
+  }
+  const magic = data[0];
+  if (magic !== MAGIC_BYTE) {
+    throw new Error(
+      `${serdeName}: unexpected magic byte 0x${(magic ?? 0).toString(16).padStart(2, "0")} (expected 0x00). The message is not Confluent wire-format \u2014 check the producer's serializer.`
+    );
+  }
+  const id = data.readInt32BE(1);
+  return { id, offset: 5 };
+}
+function frame(id, ...payloadParts) {
+  const header = Buffer.alloc(5);
+  header.writeUInt8(MAGIC_BYTE, 0);
+  header.writeInt32BE(id, 1);
+  return Buffer.concat([header, ...payloadParts]);
+}
+function avroSerde(options) {
+  const importFn = options.importFn ?? defaultImport;
+  const schemaString = options.schema === void 0 ? void 0 : typeof options.schema === "string" ? options.schema : JSON.stringify(options.schema);
+  const typeCache = /* @__PURE__ */ new Map();
+  let avscMod;
+  async function loadAvsc() {
+    if (avscMod) return avscMod;
+    try {
+      avscMod = await importFn("avsc");
+    } catch {
+      throw new Error(
+        "avroSerde: package 'avsc' is not installed. Run `npm install avsc` to enable Avro serialization."
+      );
+    }
+    return avscMod;
+  }
+  async function typeFor(schemaStr) {
+    const cached = typeCache.get(schemaStr);
+    if (cached) return cached;
+    const avsc = await loadAvsc();
+    const type = avsc.Type.forSchema(JSON.parse(schemaStr));
+    typeCache.set(schemaStr, type);
+    return type;
+  }
+  return {
+    async serialize(value, ctx) {
+      if (schemaString === void 0) {
+        throw new Error(
+          "avroSerde: `schema` is required to serialize \u2014 pass the Avro schema (JSON string or object) in the serde options."
+        );
+      }
+      const subject = resolveSubject(ctx, options.subject);
+      const id = options.autoRegister ? (await options.registry.registerSchema(subject, schemaString, "AVRO")).id : (await options.registry.getLatestSchema(subject)).id;
+      const type = await typeFor(schemaString);
+      const payload = type.toBuffer(value);
+      return frame(id, payload);
+    },
+    async deserialize(data, _ctx) {
+      const { id, offset } = readWireHeader(data, "avroSerde");
+      const registered = await options.registry.getSchemaById(id);
+      const type = await typeFor(registered.schema);
+      return type.fromBuffer(data.subarray(offset));
+    }
+  };
+}
+function protobufSerde(options) {
+  const importFn = options.importFn ?? defaultImport;
+  const typeCache = /* @__PURE__ */ new Map();
+  let protobufMod;
+  async function loadProtobuf() {
+    if (protobufMod) return protobufMod;
+    try {
+      protobufMod = await importFn("protobufjs");
+    } catch {
+      throw new Error(
+        "protobufSerde: package 'protobufjs' is not installed. Run `npm install protobufjs` to enable Protobuf serialization."
+      );
+    }
+    return protobufMod;
+  }
+  async function typeFor(protoSource) {
+    const cacheKey = `${protoSource}::${options.messageType}`;
+    const cached = typeCache.get(cacheKey);
+    if (cached) return cached;
+    const protobuf = await loadProtobuf();
+    const parsed = protobuf.parse(protoSource);
+    const type = parsed.root.lookupType(options.messageType);
+    typeCache.set(cacheKey, type);
+    return type;
+  }
+  return {
+    async serialize(value, ctx) {
+      if (options.schema === void 0) {
+        throw new Error(
+          "protobufSerde: `schema` is required to serialize \u2014 pass the .proto source string in the serde options."
+        );
+      }
+      const subject = resolveSubject(ctx, options.subject);
+      const id = options.autoRegister ? (await options.registry.registerSchema(
+        subject,
+        options.schema,
+        "PROTOBUF"
+      )).id : (await options.registry.getLatestSchema(subject)).id;
+      const type = await typeFor(options.schema);
+      const payload = Buffer.from(
+        type.encode(type.create(value)).finish()
+      );
+      const messageIndex = Buffer.from([0]);
+      return frame(id, messageIndex, payload);
+    },
+    async deserialize(data, _ctx) {
+      const { id, offset } = readWireHeader(data, "protobufSerde");
+      const indexByte = data[offset];
+      if (indexByte !== 0) {
+        throw new Error(
+          `protobufSerde: nested/multiple message types are not supported in v1 (message-index byte was 0x${(indexByte ?? 0).toString(16).padStart(2, "0")}, expected 0x00 for the top-level message type).`
+        );
+      }
+      const registered = await options.registry.getSchemaById(id);
+      const type = await typeFor(registered.schema);
+      const decoded = type.decode(data.subarray(offset + 1));
+      return type.toObject(decoded, {
+        longs: String,
+        enums: String,
+        bytes: Buffer,
+        defaults: true
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  JsonSerde,
+  SchemaRegistryClient,
+  avroSerde,
+  protobufSerde
+});
+//# sourceMappingURL=serde.js.map