@eventferry/schema-registry 3.2.3 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @eventferry/schema-registry
 
+## 3.3.0
+
+### Minor Changes
+
+- d983d90: Schema Registry serializer gains three production-grade controls without breaking the existing API:
+
+  - **Subject naming strategy** — `subjectStrategy: "TopicNameStrategy" | "RecordNameStrategy" | "TopicRecordNameStrategy"` mirrors Confluent's three built-ins. The two record-based strategies take a `recordName: (record, isKey) => string` resolver. Default stays `TopicNameStrategy`; the existing `subject` callable still wins when set (now optionally receiving `(topic, isKey, record)` — the single-arg legacy form keeps working).
+  - **Avro key serialization** — new `keySchemas` option + `serializeKey(record): Promise<Buffer | null>` method. Returns `null` for keyless records (matching the kafka "no key" semantics) and uses the `-key` subject by default. Key and value subject ids cache independently. Not wired into the relay automatically — call it from your publish glue when you want Avro-encoded keys instead of UTF-8 strings.
+  - **`autoRegister: false`** — never call `register()`, always resolve schemas via `getLatestSchemaId` on the computed subject. Locally supplied `schemas` / `keySchemas` bytes become docs-only in this mode. Matches `auto.register.schemas=false` on every Confluent client, for production clusters where schemas are managed out-of-band.
+
 ## 3.2.3
 
 ### Patch Changes

package/README.md

@@ -32,6 +32,64 @@ Topics without a configured schema use the subject's latest registered schema
 (default subject: `${topic}-value`). On the consumer, decode with the same client:
 `await registry.decode(message.value)`.
 
+## Subject naming strategies
+
+Pick one of Confluent's three built-in strategies (default `TopicNameStrategy`):
+
+```ts
+new SchemaRegistrySerializer({
+  host,
+  subjectStrategy: "RecordNameStrategy",     // subject = recordName
+  // or: "TopicRecordNameStrategy"           // subject = `${topic}-${recordName}`
+  recordName: (record) => `com.example.${record.aggregateType}.Created`,
+});
+```
+
+`recordName` is required for the `RecordName` and `TopicRecordName` strategies — typical implementation reads `${namespace}.${name}` from your avsc.
+
+Need full control? Skip the preset and pass an explicit `subject` function:
+
+```ts
+new SchemaRegistrySerializer({
+  host,
+  subject: (topic, isKey, record) => `acme.${topic}.${isKey ? "key" : "value"}`,
+});
+```
+
+## Avro key serialization
+
+Configure per-topic key schemas and call `serializeKey` from your publish path:
+
+```ts
+const serializer = new SchemaRegistrySerializer({
+  host,
+  schemas:    { "orders.created": { type: "AVRO", schema: valueAvsc } },
+  keySchemas: { "orders.created": { type: "AVRO", schema: keyAvsc } },
+});
+
+// Inside your custom publish glue:
+const encodedValue = await serializer.serialize(record);
+const encodedKey   = await serializer.serializeKey(record); // null when record.key is null
+```
+
+The relay does NOT call `serializeKey` automatically — Avro keys are an application-level convention, and adding them silently would break consumers expecting UTF-8 string keys. Wire it in your publish path explicitly.
+
+Key and value subjects cache their schema ids independently — registering one doesn't affect the other.
+
+## Auto-register toggle
+
+For production clusters where schemas are managed out-of-band (Confluent Cloud, regulated environments), turn auto-registration off:
+
+```ts
+new SchemaRegistrySerializer({
+  host,
+  schemas: { /* ignored when autoRegister is false */ },
+  autoRegister: false,
+});
+```
+
+With `autoRegister: false`, the serializer ALWAYS resolves by `getLatestSchemaId` on the computed subject — locally supplied `schemas` / `keySchemas` bytes are ignored. Matches the Confluent client's `auto.register.schemas=false`.
+
 📖 **Full documentation:** [github.com/SametGoktepe/eventferry](https://github.com/SametGoktepe/eventferry#readme)
 
 ## License

package/dist/index.cjs

@@ -39,8 +39,13 @@ var DEFAULT_CONTENT_TYPE = "application/vnd.confluent.avro";
 var SchemaRegistrySerializer = class {
   contentType;
   schemas;
-  subject;
+  keySchemas;
+  subjectStrategy;
+  recordName;
+  subjectFn;
   host;
+  autoRegister;
+  // Keyed by `${topic}:${isKey}` to keep value- and key-subject ids distinct.
   idCache = /* @__PURE__ */ new Map();
   registry;
   constructor(opts) {
@@ -52,25 +57,74 @@ var SchemaRegistrySerializer = class {
     this.registry = opts.registry ?? null;
     this.host = opts.host ?? null;
     this.schemas = opts.schemas ?? {};
-    this.subject = opts.subject ?? ((topic) => `${topic}-value`);
+    this.keySchemas = opts.keySchemas ?? {};
+    this.subjectStrategy = opts.subjectStrategy ?? "TopicNameStrategy";
+    this.recordName = opts.recordName ?? null;
+    this.subjectFn = opts.subject ?? null;
     this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;
+    this.autoRegister = opts.autoRegister ?? true;
   }
   async serialize(record) {
     const registry = await this.getRegistry();
-    const id = await this.schemaId(registry, record.topic);
+    const subject = this.resolveSubject(record, false);
+    const id = await this.schemaId(registry, subject, this.schemas[record.topic], false, record.topic);
     return registry.encode(id, record.payload);
   }
-  schemaId(registry, topic) {
-    const cached = this.idCache.get(topic);
+  /**
+   * Avro-encode the record's KEY using the registered key schema. Returns
+   * `null` when the record has no key (kafkajs/confluent treat null keys
+   * as the producer-side "no key" signal).
+   *
+   * Not part of the core `Serializer` interface — callers wire it into
+   * their publish path manually when they want Avro keys instead of raw
+   * UTF-8 strings.
+   */
+  async serializeKey(record) {
+    if (record.key === null || record.key === void 0) return null;
+    const registry = await this.getRegistry();
+    const subject = this.resolveSubject(record, true);
+    const id = await this.schemaId(
+      registry,
+      subject,
+      this.keySchemas[record.topic],
+      true,
+      record.topic
+    );
+    return registry.encode(id, record.key);
+  }
+  /**
+   * Resolve the subject for this (record, isKey) tuple. Order of
+   * precedence: explicit `subject` function → `subjectStrategy` preset.
+   */
+  resolveSubject(record, isKey) {
+    if (this.subjectFn) return this.subjectFn(record.topic, isKey, record);
+    switch (this.subjectStrategy) {
+      case "TopicNameStrategy":
+        return `${record.topic}-${isKey ? "key" : "value"}`;
+      case "RecordNameStrategy":
+        return this.recordNameFor(record, isKey);
+      case "TopicRecordNameStrategy":
+        return `${record.topic}-${this.recordNameFor(record, isKey)}`;
+    }
+  }
+  recordNameFor(record, isKey) {
+    if (!this.recordName) {
+      throw new Error(
+        `SchemaRegistrySerializer: subjectStrategy "${this.subjectStrategy}" requires a \`recordName\` resolver.`
+      );
+    }
+    return this.recordName(record, isKey);
+  }
+  schemaId(registry, subject, spec, isKey, topic) {
+    const cacheKey = `${topic}:${isKey ? "key" : "value"}`;
+    const cached = this.idCache.get(cacheKey);
     if (cached) return cached;
-    const subject = this.subject(topic);
-    const spec = this.schemas[topic];
-    const lookup = spec ? registry.register({ type: spec.type, schema: spec.schema }, { subject }).then((r) => r.id) : registry.getLatestSchemaId(subject);
+    const lookup = spec && this.autoRegister ? registry.register({ type: spec.type, schema: spec.schema }, { subject }).then((r) => r.id) : registry.getLatestSchemaId(subject);
     const guarded = lookup.catch((err) => {
-      this.idCache.delete(topic);
+      this.idCache.delete(cacheKey);
       throw err;
     });
-    this.idCache.set(topic, guarded);
+    this.idCache.set(cacheKey, guarded);
     return guarded;
   }
   async getRegistry() {

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/serializer.ts"],"sourcesContent":["export * from \"./serializer.js\";\n","import type { OutboxRecord, Serializer } from \"@eventferry/core\";\n\nexport type SchemaType = \"AVRO\" | \"PROTOBUF\" | \"JSON\";\n\nexport interface SchemaSpec {\n  type: SchemaType;\n  /** Schema definition string (avsc JSON / .proto / JSON Schema). */\n  schema: string;\n}\n\n/**\n * The subset of a Confluent Schema Registry client this serializer uses. The\n * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.\n */\nexport interface SchemaRegistryClient {\n  register(\n    schema: { type: string; schema: string },\n    opts?: { subject: string },\n  ): Promise<{ id: number }>;\n  getLatestSchemaId(subject: string): Promise<number>;\n  encode(registryId: number, payload: unknown): Promise<Buffer>;\n}\n\nexport interface SchemaRegistrySerializerOptions {\n  /** Inject a ready client (tests, custom config). */\n  registry?: SchemaRegistryClient;\n  /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */\n  host?: string;\n  /** Per-topic schema to register. Topics omitted here use the subject's latest. */\n  schemas?: Record<string, SchemaSpec>;\n  /** Subject naming. Default TopicNameStrategy: `${topic}-value`. */\n  subject?: (topic: string) => string;\n  /** content-type header value. Default \"application/vnd.confluent.avro\". */\n  contentType?: string;\n}\n\nconst DEFAULT_CONTENT_TYPE = \"application/vnd.confluent.avro\";\n\n/**\n * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry\n * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s\n * `serializer` option. The schema id per topic is resolved once and cached.\n */\nexport class SchemaRegistrySerializer implements Serializer {\n  readonly contentType: string;\n  private readonly schemas: Record<string, SchemaSpec>;\n  private readonly subject: (topic: string) => string;\n  private readonly host: string | null;\n  private readonly idCache = new Map<string, Promise<number>>();\n  private registry: SchemaRegistryClient | null;\n\n  constructor(opts: SchemaRegistrySerializerOptions) {\n    if (!opts.registry && !opts.host) {\n      throw new Error(\n        \"SchemaRegistrySerializer requires either a `registry` client or a `host`.\",\n      );\n    }\n    this.registry = opts.registry ?? null;\n    this.host = opts.host ?? null;\n    this.schemas = opts.schemas ?? {};\n    this.subject = opts.subject ?? ((topic) => `${topic}-value`);\n    this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;\n  }\n\n  async serialize(record: OutboxRecord): Promise<Buffer> {\n    const registry = await this.getRegistry();\n    const id = await this.schemaId(registry, record.topic);\n    return registry.encode(id, record.payload);\n  }\n\n  private schemaId(\n    registry: SchemaRegistryClient,\n    topic: string,\n  ): Promise<number> {\n    const cached = this.idCache.get(topic);\n    if (cached) return cached;\n\n    const subject = this.subject(topic);\n    const spec = this.schemas[topic];\n    const lookup = spec\n      ? registry\n          .register({ type: spec.type, schema: spec.schema }, { subject })\n          .then((r) => r.id)\n      : registry.getLatestSchemaId(subject);\n\n    // Cache the in-flight promise so concurrent first calls don't double-register;\n    // drop it on failure so a transient error can be retried.\n    const guarded = lookup.catch((err) => {\n      this.idCache.delete(topic);\n      throw err;\n    });\n    this.idCache.set(topic, guarded);\n    return guarded;\n  }\n\n  private async getRegistry(): Promise<SchemaRegistryClient> {\n    if (this.registry) return this.registry;\n    const mod = await importSchemaRegistry();\n    this.registry = new mod.SchemaRegistry({ host: this.host as string });\n    return this.registry;\n  }\n}\n\nasync function importSchemaRegistry(): Promise<{\n  SchemaRegistry: new (cfg: { host: string }) => SchemaRegistryClient;\n}> {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    return (await import(\"@kafkajs/confluent-schema-registry\")) as any;\n  } catch {\n    throw new Error(\n      'SchemaRegistrySerializer with `host` needs the \"@kafkajs/confluent-schema-registry\" package. Run: npm i @kafkajs/confluent-schema-registry',\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACoCA,IAAM,uBAAuB;AAOtB,IAAM,2BAAN,MAAqD;AAAA,EACjD;AAAA,EACQ;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAU,oBAAI,IAA6B;AAAA,EACpD;AAAA,EAER,YAAY,MAAuC;AACjD,QAAI,CAAC,KAAK,YAAY,CAAC,KAAK,MAAM;AAChC,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,SAAK,WAAW,KAAK,YAAY;AACjC,SAAK,OAAO,KAAK,QAAQ;AACzB,SAAK,UAAU,KAAK,WAAW,CAAC;AAChC,SAAK,UAAU,KAAK,YAAY,CAAC,UAAU,GAAG,KAAK;AACnD,SAAK,cAAc,KAAK,eAAe;AAAA,EACzC;AAAA,EAEA,MAAM,UAAU,QAAuC;AACrD,UAAM,WAAW,MAAM,KAAK,YAAY;AACxC,UAAM,KAAK,MAAM,KAAK,SAAS,UAAU,OAAO,KAAK;AACrD,WAAO,SAAS,OAAO,IAAI,OAAO,OAAO;AAAA,EAC3C;AAAA,EAEQ,SACN,UACA,OACiB;AACjB,UAAM,SAAS,KAAK,QAAQ,IAAI,KAAK;AACrC,QAAI,OAAQ,QAAO;AAEnB,UAAM,UAAU,KAAK,QAAQ,KAAK;AAClC,UAAM,OAAO,KAAK,QAAQ,KAAK;AAC/B,UAAM,SAAS,OACX,SACG,SAAS,EAAE,MAAM,KAAK,MAAM,QAAQ,KAAK,OAAO,GAAG,EAAE,QAAQ,CAAC,EAC9D,KAAK,CAAC,MAAM,EAAE,EAAE,IACnB,SAAS,kBAAkB,OAAO;AAItC,UAAM,UAAU,OAAO,MAAM,CAAC,QAAQ;AACpC,WAAK,QAAQ,OAAO,KAAK;AACzB,YAAM;AAAA,IACR,CAAC;AACD,SAAK,QAAQ,IAAI,OAAO,OAAO;AAC/B,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,cAA6C;AACzD,QAAI,KAAK,SAAU,QAAO,KAAK;AAC/B,UAAM,MAAM,MAAM,qBAAqB;AACvC,SAAK,WAAW,IAAI,IAAI,eAAe,EAAE,MAAM,KAAK,KAAe,CAAC;AACpE,WAAO,KAAK;AAAA,EACd;AACF;AAEA,eAAe,uBAEZ;AACD,MAAI;AAEF,WAAQ,MAAM,OAAO,oCAAoC;AAAA,EAC3D,QAAQ;AACN,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/serializer.ts"],"sourcesContent":["export * from \"./serializer.js\";\n","import type { OutboxRecord, Serializer } from \"@eventferry/core\";\n\nexport type SchemaType = \"AVRO\" | \"PROTOBUF\" | \"JSON\";\n\nexport interface SchemaSpec {\n  type: SchemaType;\n  /** Schema definition string (avsc JSON / .proto / JSON Schema). */\n  schema: string;\n}\n\n/**\n * Subject naming strategy. Mirrors Confluent's three built-ins:\n *\n * - `\"TopicNameStrategy\"` (default) — `${topic}-value` / `${topic}-key`.\n *   The conventional default; one schema per (topic, isKey) tuple.\n * - `\"RecordNameStrategy\"` — `${recordName}`. Same record type can flow\n *   on multiple topics. Requires a `recordName` resolver.\n * - `\"TopicRecordNameStrategy\"` — `${topic}-${recordName}`. Multiple record\n *   types per topic. Requires a `recordName` resolver.\n *\n * Set `subject` (function form) to override entirely.\n */\nexport type SubjectNameStrategy =\n  | \"TopicNameStrategy\"\n  | \"RecordNameStrategy\"\n  | \"TopicRecordNameStrategy\";\n\n/**\n * The subset of a Confluent Schema Registry client this serializer uses. The\n * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.\n */\nexport interface SchemaRegistryClient {\n  register(\n    schema: { type: string; schema: string },\n    opts?: { subject: string },\n  ): Promise<{ id: number }>;\n  getLatestSchemaId(subject: string): Promise<number>;\n  encode(registryId: number, payload: unknown): Promise<Buffer>;\n}\n\nexport interface SchemaRegistrySerializerOptions {\n  /** Inject a ready client (tests, custom config). */\n  registry?: SchemaRegistryClient;\n  /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */\n  host?: string;\n  /** Per-topic VALUE schema to register. Topics omitted here use the subject's latest. */\n  schemas?: Record<string, SchemaSpec>;\n  /**\n   * Per-topic KEY schema. When set, `serializeKey(record)` Avro-encodes\n   * the record key for the matching topic. Topics omitted here fall back\n   * to the subject's latest (or, with `autoRegister: false`, ALWAYS the\n   * subject's latest).\n   */\n  keySchemas?: Record<string, SchemaSpec>;\n  /**\n   * Subject naming strategy preset. Default `\"TopicNameStrategy\"`.\n   * Setting `subject` (function) overrides this entirely.\n   */\n  subjectStrategy?: SubjectNameStrategy;\n  /**\n   * Resolve the schema's record name (used by `RecordNameStrategy` and\n   * `TopicRecordNameStrategy`). REQUIRED when `subjectStrategy` is set to\n   * one of those — throws on first serialize if absent.\n   *\n   * Typical implementation: read `${namespace}.${name}` from the avsc you\n   * already supply via `schemas` / `keySchemas`.\n   */\n  recordName?: (record: OutboxRecord, isKey: boolean) => string;\n  /**\n   * Custom subject function — overrides BOTH `subjectStrategy` and\n   * `recordName`. Receives `(topic, isKey, record)` for full flexibility.\n   *\n   * Backwards-compatible with the single-argument legacy form\n   * `(topic) => string` — extra args are ignored by JavaScript.\n   */\n  subject?: (\n    topic: string,\n    isKey?: boolean,\n    record?: OutboxRecord,\n  ) => string;\n  /** content-type header value. Default \"application/vnd.confluent.avro\". */\n  contentType?: string;\n  /**\n   * Auto-register schemas when one is supplied via `schemas` / `keySchemas`.\n   * Default `true` — matches Confluent client behavior.\n   *\n   * Set to `false` for production clusters where schemas are managed\n   * out-of-band (Confluent Cloud, regulated environments). With\n   * autoRegister off, the serializer ALWAYS resolves by `getLatestSchemaId`\n   * on the computed subject — and the locally-supplied schema bytes are\n   * ignored.\n   */\n  autoRegister?: boolean;\n}\n\nconst DEFAULT_CONTENT_TYPE = \"application/vnd.confluent.avro\";\n\n/**\n * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry\n * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s\n * `serializer` option. The schema id per (topic, isKey) tuple is resolved once\n * and cached.\n *\n * Also exposes `serializeKey(record)` for users who want Avro-encoded message\n * keys — call it manually when building the publish path; the relay does NOT\n * call it automatically (key encoding is application-level by convention).\n */\nexport class SchemaRegistrySerializer implements Serializer {\n  readonly contentType: string;\n  private readonly schemas: Record<string, SchemaSpec>;\n  private readonly keySchemas: Record<string, SchemaSpec>;\n  private readonly subjectStrategy: SubjectNameStrategy;\n  private readonly recordName:\n    | ((record: OutboxRecord, isKey: boolean) => string)\n    | null;\n  private readonly subjectFn:\n    | ((topic: string, isKey?: boolean, record?: OutboxRecord) => string)\n    | null;\n  private readonly host: string | null;\n  private readonly autoRegister: boolean;\n  // Keyed by `${topic}:${isKey}` to keep value- and key-subject ids distinct.\n  private readonly idCache = new Map<string, Promise<number>>();\n  private registry: SchemaRegistryClient | null;\n\n  constructor(opts: SchemaRegistrySerializerOptions) {\n    if (!opts.registry && !opts.host) {\n      throw new Error(\n        \"SchemaRegistrySerializer requires either a `registry` client or a `host`.\",\n      );\n    }\n    this.registry = opts.registry ?? null;\n    this.host = opts.host ?? null;\n    this.schemas = opts.schemas ?? {};\n    this.keySchemas = opts.keySchemas ?? {};\n    this.subjectStrategy = opts.subjectStrategy ?? \"TopicNameStrategy\";\n    this.recordName = opts.recordName ?? null;\n    this.subjectFn = opts.subject ?? null;\n    this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;\n    this.autoRegister = opts.autoRegister ?? true;\n  }\n\n  async serialize(record: OutboxRecord): Promise<Buffer> {\n    const registry = await this.getRegistry();\n    const subject = this.resolveSubject(record, false);\n    const id = await this.schemaId(registry, subject, this.schemas[record.topic], false, record.topic);\n    return registry.encode(id, record.payload);\n  }\n\n  /**\n   * Avro-encode the record's KEY using the registered key schema. Returns\n   * `null` when the record has no key (kafkajs/confluent treat null keys\n   * as the producer-side \"no key\" signal).\n   *\n   * Not part of the core `Serializer` interface — callers wire it into\n   * their publish path manually when they want Avro keys instead of raw\n   * UTF-8 strings.\n   */\n  async serializeKey(record: OutboxRecord): Promise<Buffer | null> {\n    if (record.key === null || record.key === undefined) return null;\n    const registry = await this.getRegistry();\n    const subject = this.resolveSubject(record, true);\n    const id = await this.schemaId(\n      registry,\n      subject,\n      this.keySchemas[record.topic],\n      true,\n      record.topic,\n    );\n    return registry.encode(id, record.key);\n  }\n\n  /**\n   * Resolve the subject for this (record, isKey) tuple. Order of\n   * precedence: explicit `subject` function → `subjectStrategy` preset.\n   */\n  private resolveSubject(record: OutboxRecord, isKey: boolean): string {\n    if (this.subjectFn) return this.subjectFn(record.topic, isKey, record);\n    switch (this.subjectStrategy) {\n      case \"TopicNameStrategy\":\n        return `${record.topic}-${isKey ? \"key\" : \"value\"}`;\n      case \"RecordNameStrategy\":\n        return this.recordNameFor(record, isKey);\n      case \"TopicRecordNameStrategy\":\n        return `${record.topic}-${this.recordNameFor(record, isKey)}`;\n    }\n  }\n\n  private recordNameFor(record: OutboxRecord, isKey: boolean): string {\n    if (!this.recordName) {\n      throw new Error(\n        `SchemaRegistrySerializer: subjectStrategy \"${this.subjectStrategy}\" requires a \\`recordName\\` resolver.`,\n      );\n    }\n    return this.recordName(record, isKey);\n  }\n\n  private schemaId(\n    registry: SchemaRegistryClient,\n    subject: string,\n    spec: SchemaSpec | undefined,\n    isKey: boolean,\n    topic: string,\n  ): Promise<number> {\n    const cacheKey = `${topic}:${isKey ? \"key\" : \"value\"}`;\n    const cached = this.idCache.get(cacheKey);\n    if (cached) return cached;\n\n    // autoRegister=false → ALWAYS resolve by latest; the local spec\n    // (if any) is ignored. Matches Confluent's auto.register.schemas=false.\n    const lookup =\n      spec && this.autoRegister\n        ? registry\n            .register({ type: spec.type, schema: spec.schema }, { subject })\n            .then((r) => r.id)\n        : registry.getLatestSchemaId(subject);\n\n    // Cache the in-flight promise so concurrent first calls don't double-register;\n    // drop it on failure so a transient error can be retried.\n    const guarded = lookup.catch((err) => {\n      this.idCache.delete(cacheKey);\n      throw err;\n    });\n    this.idCache.set(cacheKey, guarded);\n    return guarded;\n  }\n\n  private async getRegistry(): Promise<SchemaRegistryClient> {\n    if (this.registry) return this.registry;\n    const mod = await importSchemaRegistry();\n    this.registry = new mod.SchemaRegistry({ host: this.host as string });\n    return this.registry;\n  }\n}\n\nasync function importSchemaRegistry(): Promise<{\n  SchemaRegistry: new (cfg: { host: string }) => SchemaRegistryClient;\n}> {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    return (await import(\"@kafkajs/confluent-schema-registry\")) as any;\n  } catch {\n    throw new Error(\n      'SchemaRegistrySerializer with `host` needs the \"@kafkajs/confluent-schema-registry\" package. Run: npm i @kafkajs/confluent-schema-registry',\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -6,6 +6,19 @@ interface SchemaSpec {
     /** Schema definition string (avsc JSON / .proto / JSON Schema). */
     schema: string;
 }
+/**
+ * Subject naming strategy. Mirrors Confluent's three built-ins:
+ *
+ * - `"TopicNameStrategy"` (default) — `${topic}-value` / `${topic}-key`.
+ *   The conventional default; one schema per (topic, isKey) tuple.
+ * - `"RecordNameStrategy"` — `${recordName}`. Same record type can flow
+ *   on multiple topics. Requires a `recordName` resolver.
+ * - `"TopicRecordNameStrategy"` — `${topic}-${recordName}`. Multiple record
+ *   types per topic. Requires a `recordName` resolver.
+ *
+ * Set `subject` (function form) to override entirely.
+ */
+type SubjectNameStrategy = "TopicNameStrategy" | "RecordNameStrategy" | "TopicRecordNameStrategy";
 /**
  * The subset of a Confluent Schema Registry client this serializer uses. The
  * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.
@@ -27,29 +40,92 @@ interface SchemaRegistrySerializerOptions {
     registry?: SchemaRegistryClient;
     /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */
     host?: string;
-    /** Per-topic schema to register. Topics omitted here use the subject's latest. */
+    /** Per-topic VALUE schema to register. Topics omitted here use the subject's latest. */
     schemas?: Record<string, SchemaSpec>;
-    /** Subject naming. Default TopicNameStrategy: `${topic}-value`. */
-    subject?: (topic: string) => string;
+    /**
+     * Per-topic KEY schema. When set, `serializeKey(record)` Avro-encodes
+     * the record key for the matching topic. Topics omitted here fall back
+     * to the subject's latest (or, with `autoRegister: false`, ALWAYS the
+     * subject's latest).
+     */
+    keySchemas?: Record<string, SchemaSpec>;
+    /**
+     * Subject naming strategy preset. Default `"TopicNameStrategy"`.
+     * Setting `subject` (function) overrides this entirely.
+     */
+    subjectStrategy?: SubjectNameStrategy;
+    /**
+     * Resolve the schema's record name (used by `RecordNameStrategy` and
+     * `TopicRecordNameStrategy`). REQUIRED when `subjectStrategy` is set to
+     * one of those — throws on first serialize if absent.
+     *
+     * Typical implementation: read `${namespace}.${name}` from the avsc you
+     * already supply via `schemas` / `keySchemas`.
+     */
+    recordName?: (record: OutboxRecord, isKey: boolean) => string;
+    /**
+     * Custom subject function — overrides BOTH `subjectStrategy` and
+     * `recordName`. Receives `(topic, isKey, record)` for full flexibility.
+     *
+     * Backwards-compatible with the single-argument legacy form
+     * `(topic) => string` — extra args are ignored by JavaScript.
+     */
+    subject?: (topic: string, isKey?: boolean, record?: OutboxRecord) => string;
     /** content-type header value. Default "application/vnd.confluent.avro". */
     contentType?: string;
+    /**
+     * Auto-register schemas when one is supplied via `schemas` / `keySchemas`.
+     * Default `true` — matches Confluent client behavior.
+     *
+     * Set to `false` for production clusters where schemas are managed
+     * out-of-band (Confluent Cloud, regulated environments). With
+     * autoRegister off, the serializer ALWAYS resolves by `getLatestSchemaId`
+     * on the computed subject — and the locally-supplied schema bytes are
+     * ignored.
+     */
+    autoRegister?: boolean;
 }
 /**
  * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry
  * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s
- * `serializer` option. The schema id per topic is resolved once and cached.
+ * `serializer` option. The schema id per (topic, isKey) tuple is resolved once
+ * and cached.
+ *
+ * Also exposes `serializeKey(record)` for users who want Avro-encoded message
+ * keys — call it manually when building the publish path; the relay does NOT
+ * call it automatically (key encoding is application-level by convention).
  */
 declare class SchemaRegistrySerializer implements Serializer {
     readonly contentType: string;
     private readonly schemas;
-    private readonly subject;
+    private readonly keySchemas;
+    private readonly subjectStrategy;
+    private readonly recordName;
+    private readonly subjectFn;
     private readonly host;
+    private readonly autoRegister;
     private readonly idCache;
     private registry;
     constructor(opts: SchemaRegistrySerializerOptions);
     serialize(record: OutboxRecord): Promise<Buffer>;
+    /**
+     * Avro-encode the record's KEY using the registered key schema. Returns
+     * `null` when the record has no key (kafkajs/confluent treat null keys
+     * as the producer-side "no key" signal).
+     *
+     * Not part of the core `Serializer` interface — callers wire it into
+     * their publish path manually when they want Avro keys instead of raw
+     * UTF-8 strings.
+     */
+    serializeKey(record: OutboxRecord): Promise<Buffer | null>;
+    /**
+     * Resolve the subject for this (record, isKey) tuple. Order of
+     * precedence: explicit `subject` function → `subjectStrategy` preset.
+     */
+    private resolveSubject;
+    private recordNameFor;
     private schemaId;
     private getRegistry;
 }
 
-export { type SchemaRegistryClient, SchemaRegistrySerializer, type SchemaRegistrySerializerOptions, type SchemaSpec, type SchemaType };
+export { type SchemaRegistryClient, SchemaRegistrySerializer, type SchemaRegistrySerializerOptions, type SchemaSpec, type SchemaType, type SubjectNameStrategy };

package/dist/index.d.ts

@@ -6,6 +6,19 @@ interface SchemaSpec {
     /** Schema definition string (avsc JSON / .proto / JSON Schema). */
     schema: string;
 }
+/**
+ * Subject naming strategy. Mirrors Confluent's three built-ins:
+ *
+ * - `"TopicNameStrategy"` (default) — `${topic}-value` / `${topic}-key`.
+ *   The conventional default; one schema per (topic, isKey) tuple.
+ * - `"RecordNameStrategy"` — `${recordName}`. Same record type can flow
+ *   on multiple topics. Requires a `recordName` resolver.
+ * - `"TopicRecordNameStrategy"` — `${topic}-${recordName}`. Multiple record
+ *   types per topic. Requires a `recordName` resolver.
+ *
+ * Set `subject` (function form) to override entirely.
+ */
+type SubjectNameStrategy = "TopicNameStrategy" | "RecordNameStrategy" | "TopicRecordNameStrategy";
 /**
  * The subset of a Confluent Schema Registry client this serializer uses. The
  * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.
@@ -27,29 +40,92 @@ interface SchemaRegistrySerializerOptions {
     registry?: SchemaRegistryClient;
     /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */
     host?: string;
-    /** Per-topic schema to register. Topics omitted here use the subject's latest. */
+    /** Per-topic VALUE schema to register. Topics omitted here use the subject's latest. */
     schemas?: Record<string, SchemaSpec>;
-    /** Subject naming. Default TopicNameStrategy: `${topic}-value`. */
-    subject?: (topic: string) => string;
+    /**
+     * Per-topic KEY schema. When set, `serializeKey(record)` Avro-encodes
+     * the record key for the matching topic. Topics omitted here fall back
+     * to the subject's latest (or, with `autoRegister: false`, ALWAYS the
+     * subject's latest).
+     */
+    keySchemas?: Record<string, SchemaSpec>;
+    /**
+     * Subject naming strategy preset. Default `"TopicNameStrategy"`.
+     * Setting `subject` (function) overrides this entirely.
+     */
+    subjectStrategy?: SubjectNameStrategy;
+    /**
+     * Resolve the schema's record name (used by `RecordNameStrategy` and
+     * `TopicRecordNameStrategy`). REQUIRED when `subjectStrategy` is set to
+     * one of those — throws on first serialize if absent.
+     *
+     * Typical implementation: read `${namespace}.${name}` from the avsc you
+     * already supply via `schemas` / `keySchemas`.
+     */
+    recordName?: (record: OutboxRecord, isKey: boolean) => string;
+    /**
+     * Custom subject function — overrides BOTH `subjectStrategy` and
+     * `recordName`. Receives `(topic, isKey, record)` for full flexibility.
+     *
+     * Backwards-compatible with the single-argument legacy form
+     * `(topic) => string` — extra args are ignored by JavaScript.
+     */
+    subject?: (topic: string, isKey?: boolean, record?: OutboxRecord) => string;
     /** content-type header value. Default "application/vnd.confluent.avro". */
     contentType?: string;
+    /**
+     * Auto-register schemas when one is supplied via `schemas` / `keySchemas`.
+     * Default `true` — matches Confluent client behavior.
+     *
+     * Set to `false` for production clusters where schemas are managed
+     * out-of-band (Confluent Cloud, regulated environments). With
+     * autoRegister off, the serializer ALWAYS resolves by `getLatestSchemaId`
+     * on the computed subject — and the locally-supplied schema bytes are
+     * ignored.
+     */
+    autoRegister?: boolean;
 }
 /**
  * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry
  * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s
- * `serializer` option. The schema id per topic is resolved once and cached.
+ * `serializer` option. The schema id per (topic, isKey) tuple is resolved once
+ * and cached.
+ *
+ * Also exposes `serializeKey(record)` for users who want Avro-encoded message
+ * keys — call it manually when building the publish path; the relay does NOT
+ * call it automatically (key encoding is application-level by convention).
  */
 declare class SchemaRegistrySerializer implements Serializer {
     readonly contentType: string;
     private readonly schemas;
-    private readonly subject;
+    private readonly keySchemas;
+    private readonly subjectStrategy;
+    private readonly recordName;
+    private readonly subjectFn;
     private readonly host;
+    private readonly autoRegister;
     private readonly idCache;
     private registry;
     constructor(opts: SchemaRegistrySerializerOptions);
     serialize(record: OutboxRecord): Promise<Buffer>;
+    /**
+     * Avro-encode the record's KEY using the registered key schema. Returns
+     * `null` when the record has no key (kafkajs/confluent treat null keys
+     * as the producer-side "no key" signal).
+     *
+     * Not part of the core `Serializer` interface — callers wire it into
+     * their publish path manually when they want Avro keys instead of raw
+     * UTF-8 strings.
+     */
+    serializeKey(record: OutboxRecord): Promise<Buffer | null>;
+    /**
+     * Resolve the subject for this (record, isKey) tuple. Order of
+     * precedence: explicit `subject` function → `subjectStrategy` preset.
+     */
+    private resolveSubject;
+    private recordNameFor;
     private schemaId;
     private getRegistry;
 }
 
-export { type SchemaRegistryClient, SchemaRegistrySerializer, type SchemaRegistrySerializerOptions, type SchemaSpec, type SchemaType };
+export { type SchemaRegistryClient, SchemaRegistrySerializer, type SchemaRegistrySerializerOptions, type SchemaSpec, type SchemaType, type SubjectNameStrategy };

package/dist/index.js

@@ -3,8 +3,13 @@ var DEFAULT_CONTENT_TYPE = "application/vnd.confluent.avro";
 var SchemaRegistrySerializer = class {
   contentType;
   schemas;
-  subject;
+  keySchemas;
+  subjectStrategy;
+  recordName;
+  subjectFn;
   host;
+  autoRegister;
+  // Keyed by `${topic}:${isKey}` to keep value- and key-subject ids distinct.
   idCache = /* @__PURE__ */ new Map();
   registry;
   constructor(opts) {
@@ -16,25 +21,74 @@ var SchemaRegistrySerializer = class {
     this.registry = opts.registry ?? null;
     this.host = opts.host ?? null;
     this.schemas = opts.schemas ?? {};
-    this.subject = opts.subject ?? ((topic) => `${topic}-value`);
+    this.keySchemas = opts.keySchemas ?? {};
+    this.subjectStrategy = opts.subjectStrategy ?? "TopicNameStrategy";
+    this.recordName = opts.recordName ?? null;
+    this.subjectFn = opts.subject ?? null;
     this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;
+    this.autoRegister = opts.autoRegister ?? true;
   }
   async serialize(record) {
     const registry = await this.getRegistry();
-    const id = await this.schemaId(registry, record.topic);
+    const subject = this.resolveSubject(record, false);
+    const id = await this.schemaId(registry, subject, this.schemas[record.topic], false, record.topic);
     return registry.encode(id, record.payload);
   }
-  schemaId(registry, topic) {
-    const cached = this.idCache.get(topic);
+  /**
+   * Avro-encode the record's KEY using the registered key schema. Returns
+   * `null` when the record has no key (kafkajs/confluent treat null keys
+   * as the producer-side "no key" signal).
+   *
+   * Not part of the core `Serializer` interface — callers wire it into
+   * their publish path manually when they want Avro keys instead of raw
+   * UTF-8 strings.
+   */
+  async serializeKey(record) {
+    if (record.key === null || record.key === void 0) return null;
+    const registry = await this.getRegistry();
+    const subject = this.resolveSubject(record, true);
+    const id = await this.schemaId(
+      registry,
+      subject,
+      this.keySchemas[record.topic],
+      true,
+      record.topic
+    );
+    return registry.encode(id, record.key);
+  }
+  /**
+   * Resolve the subject for this (record, isKey) tuple. Order of
+   * precedence: explicit `subject` function → `subjectStrategy` preset.
+   */
+  resolveSubject(record, isKey) {
+    if (this.subjectFn) return this.subjectFn(record.topic, isKey, record);
+    switch (this.subjectStrategy) {
+      case "TopicNameStrategy":
+        return `${record.topic}-${isKey ? "key" : "value"}`;
+      case "RecordNameStrategy":
+        return this.recordNameFor(record, isKey);
+      case "TopicRecordNameStrategy":
+        return `${record.topic}-${this.recordNameFor(record, isKey)}`;
+    }
+  }
+  recordNameFor(record, isKey) {
+    if (!this.recordName) {
+      throw new Error(
+        `SchemaRegistrySerializer: subjectStrategy "${this.subjectStrategy}" requires a \`recordName\` resolver.`
+      );
+    }
+    return this.recordName(record, isKey);
+  }
+  schemaId(registry, subject, spec, isKey, topic) {
+    const cacheKey = `${topic}:${isKey ? "key" : "value"}`;
+    const cached = this.idCache.get(cacheKey);
     if (cached) return cached;
-    const subject = this.subject(topic);
-    const spec = this.schemas[topic];
-    const lookup = spec ? registry.register({ type: spec.type, schema: spec.schema }, { subject }).then((r) => r.id) : registry.getLatestSchemaId(subject);
+    const lookup = spec && this.autoRegister ? registry.register({ type: spec.type, schema: spec.schema }, { subject }).then((r) => r.id) : registry.getLatestSchemaId(subject);
     const guarded = lookup.catch((err) => {
-      this.idCache.delete(topic);
+      this.idCache.delete(cacheKey);
       throw err;
     });
-    this.idCache.set(topic, guarded);
+    this.idCache.set(cacheKey, guarded);
     return guarded;
   }
   async getRegistry() {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/serializer.ts"],"sourcesContent":["import type { OutboxRecord, Serializer } from \"@eventferry/core\";\n\nexport type SchemaType = \"AVRO\" | \"PROTOBUF\" | \"JSON\";\n\nexport interface SchemaSpec {\n  type: SchemaType;\n  /** Schema definition string (avsc JSON / .proto / JSON Schema). */\n  schema: string;\n}\n\n/**\n * The subset of a Confluent Schema Registry client this serializer uses. The\n * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.\n */\nexport interface SchemaRegistryClient {\n  register(\n    schema: { type: string; schema: string },\n    opts?: { subject: string },\n  ): Promise<{ id: number }>;\n  getLatestSchemaId(subject: string): Promise<number>;\n  encode(registryId: number, payload: unknown): Promise<Buffer>;\n}\n\nexport interface SchemaRegistrySerializerOptions {\n  /** Inject a ready client (tests, custom config). */\n  registry?: SchemaRegistryClient;\n  /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */\n  host?: string;\n  /** Per-topic schema to register. Topics omitted here use the subject's latest. */\n  schemas?: Record<string, SchemaSpec>;\n  /** Subject naming. Default TopicNameStrategy: `${topic}-value`. */\n  subject?: (topic: string) => string;\n  /** content-type header value. Default \"application/vnd.confluent.avro\". */\n  contentType?: string;\n}\n\nconst DEFAULT_CONTENT_TYPE = \"application/vnd.confluent.avro\";\n\n/**\n * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry\n * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s\n * `serializer` option. The schema id per topic is resolved once and cached.\n */\nexport class SchemaRegistrySerializer implements Serializer {\n  readonly contentType: string;\n  private readonly schemas: Record<string, SchemaSpec>;\n  private readonly subject: (topic: string) => string;\n  private readonly host: string | null;\n  private readonly idCache = new Map<string, Promise<number>>();\n  private registry: SchemaRegistryClient | null;\n\n  constructor(opts: SchemaRegistrySerializerOptions) {\n    if (!opts.registry && !opts.host) {\n      throw new Error(\n        \"SchemaRegistrySerializer requires either a `registry` client or a `host`.\",\n      );\n    }\n    this.registry = opts.registry ?? null;\n    this.host = opts.host ?? null;\n    this.schemas = opts.schemas ?? {};\n    this.subject = opts.subject ?? ((topic) => `${topic}-value`);\n    this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;\n  }\n\n  async serialize(record: OutboxRecord): Promise<Buffer> {\n    const registry = await this.getRegistry();\n    const id = await this.schemaId(registry, record.topic);\n    return registry.encode(id, record.payload);\n  }\n\n  private schemaId(\n    registry: SchemaRegistryClient,\n    topic: string,\n  ): Promise<number> {\n    const cached = this.idCache.get(topic);\n    if (cached) return cached;\n\n    const subject = this.subject(topic);\n    const spec = this.schemas[topic];\n    const lookup = spec\n      ? registry\n          .register({ type: spec.type, schema: spec.schema }, { subject })\n          .then((r) => r.id)\n      : registry.getLatestSchemaId(subject);\n\n    // Cache the in-flight promise so concurrent first calls don't double-register;\n    // drop it on failure so a transient error can be retried.\n    const guarded = lookup.catch((err) => {\n      this.idCache.delete(topic);\n      throw err;\n    });\n    this.idCache.set(topic, guarded);\n    return guarded;\n  }\n\n  private async getRegistry(): Promise<SchemaRegistryClient> {\n    if (this.registry) return this.registry;\n    const mod = await importSchemaRegistry();\n    this.registry = new mod.SchemaRegistry({ host: this.host as string });\n    return this.registry;\n  }\n}\n\nasync function importSchemaRegistry(): Promise<{\n  SchemaRegistry: new (cfg: { host: string }) => SchemaRegistryClient;\n}> {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    return (await import(\"@kafkajs/confluent-schema-registry\")) as any;\n  } catch {\n    throw new Error(\n      'SchemaRegistrySerializer with `host` needs the \"@kafkajs/confluent-schema-registry\" package. Run: npm i @kafkajs/confluent-schema-registry',\n    );\n  }\n}\n"],"mappings":";AAoCA,IAAM,uBAAuB;AAOtB,IAAM,2BAAN,MAAqD;AAAA,EACjD;AAAA,EACQ;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAU,oBAAI,IAA6B;AAAA,EACpD;AAAA,EAER,YAAY,MAAuC;AACjD,QAAI,CAAC,KAAK,YAAY,CAAC,KAAK,MAAM;AAChC,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,SAAK,WAAW,KAAK,YAAY;AACjC,SAAK,OAAO,KAAK,QAAQ;AACzB,SAAK,UAAU,KAAK,WAAW,CAAC;AAChC,SAAK,UAAU,KAAK,YAAY,CAAC,UAAU,GAAG,KAAK;AACnD,SAAK,cAAc,KAAK,eAAe;AAAA,EACzC;AAAA,EAEA,MAAM,UAAU,QAAuC;AACrD,UAAM,WAAW,MAAM,KAAK,YAAY;AACxC,UAAM,KAAK,MAAM,KAAK,SAAS,UAAU,OAAO,KAAK;AACrD,WAAO,SAAS,OAAO,IAAI,OAAO,OAAO;AAAA,EAC3C;AAAA,EAEQ,SACN,UACA,OACiB;AACjB,UAAM,SAAS,KAAK,QAAQ,IAAI,KAAK;AACrC,QAAI,OAAQ,QAAO;AAEnB,UAAM,UAAU,KAAK,QAAQ,KAAK;AAClC,UAAM,OAAO,KAAK,QAAQ,KAAK;AAC/B,UAAM,SAAS,OACX,SACG,SAAS,EAAE,MAAM,KAAK,MAAM,QAAQ,KAAK,OAAO,GAAG,EAAE,QAAQ,CAAC,EAC9D,KAAK,CAAC,MAAM,EAAE,EAAE,IACnB,SAAS,kBAAkB,OAAO;AAItC,UAAM,UAAU,OAAO,MAAM,CAAC,QAAQ;AACpC,WAAK,QAAQ,OAAO,KAAK;AACzB,YAAM;AAAA,IACR,CAAC;AACD,SAAK,QAAQ,IAAI,OAAO,OAAO;AAC/B,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,cAA6C;AACzD,QAAI,KAAK,SAAU,QAAO,KAAK;AAC/B,UAAM,MAAM,MAAM,qBAAqB;AACvC,SAAK,WAAW,IAAI,IAAI,eAAe,EAAE,MAAM,KAAK,KAAe,CAAC;AACpE,WAAO,KAAK;AAAA,EACd;AACF;AAEA,eAAe,uBAEZ;AACD,MAAI;AAEF,WAAQ,MAAM,OAAO,oCAAoC;AAAA,EAC3D,QAAQ;AACN,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/serializer.ts"],"sourcesContent":["import type { OutboxRecord, Serializer } from \"@eventferry/core\";\n\nexport type SchemaType = \"AVRO\" | \"PROTOBUF\" | \"JSON\";\n\nexport interface SchemaSpec {\n  type: SchemaType;\n  /** Schema definition string (avsc JSON / .proto / JSON Schema). */\n  schema: string;\n}\n\n/**\n * Subject naming strategy. Mirrors Confluent's three built-ins:\n *\n * - `\"TopicNameStrategy\"` (default) — `${topic}-value` / `${topic}-key`.\n *   The conventional default; one schema per (topic, isKey) tuple.\n * - `\"RecordNameStrategy\"` — `${recordName}`. Same record type can flow\n *   on multiple topics. Requires a `recordName` resolver.\n * - `\"TopicRecordNameStrategy\"` — `${topic}-${recordName}`. Multiple record\n *   types per topic. Requires a `recordName` resolver.\n *\n * Set `subject` (function form) to override entirely.\n */\nexport type SubjectNameStrategy =\n  | \"TopicNameStrategy\"\n  | \"RecordNameStrategy\"\n  | \"TopicRecordNameStrategy\";\n\n/**\n * The subset of a Confluent Schema Registry client this serializer uses. The\n * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.\n */\nexport interface SchemaRegistryClient {\n  register(\n    schema: { type: string; schema: string },\n    opts?: { subject: string },\n  ): Promise<{ id: number }>;\n  getLatestSchemaId(subject: string): Promise<number>;\n  encode(registryId: number, payload: unknown): Promise<Buffer>;\n}\n\nexport interface SchemaRegistrySerializerOptions {\n  /** Inject a ready client (tests, custom config). */\n  registry?: SchemaRegistryClient;\n  /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */\n  host?: string;\n  /** Per-topic VALUE schema to register. Topics omitted here use the subject's latest. */\n  schemas?: Record<string, SchemaSpec>;\n  /**\n   * Per-topic KEY schema. When set, `serializeKey(record)` Avro-encodes\n   * the record key for the matching topic. Topics omitted here fall back\n   * to the subject's latest (or, with `autoRegister: false`, ALWAYS the\n   * subject's latest).\n   */\n  keySchemas?: Record<string, SchemaSpec>;\n  /**\n   * Subject naming strategy preset. Default `\"TopicNameStrategy\"`.\n   * Setting `subject` (function) overrides this entirely.\n   */\n  subjectStrategy?: SubjectNameStrategy;\n  /**\n   * Resolve the schema's record name (used by `RecordNameStrategy` and\n   * `TopicRecordNameStrategy`). REQUIRED when `subjectStrategy` is set to\n   * one of those — throws on first serialize if absent.\n   *\n   * Typical implementation: read `${namespace}.${name}` from the avsc you\n   * already supply via `schemas` / `keySchemas`.\n   */\n  recordName?: (record: OutboxRecord, isKey: boolean) => string;\n  /**\n   * Custom subject function — overrides BOTH `subjectStrategy` and\n   * `recordName`. Receives `(topic, isKey, record)` for full flexibility.\n   *\n   * Backwards-compatible with the single-argument legacy form\n   * `(topic) => string` — extra args are ignored by JavaScript.\n   */\n  subject?: (\n    topic: string,\n    isKey?: boolean,\n    record?: OutboxRecord,\n  ) => string;\n  /** content-type header value. Default \"application/vnd.confluent.avro\". */\n  contentType?: string;\n  /**\n   * Auto-register schemas when one is supplied via `schemas` / `keySchemas`.\n   * Default `true` — matches Confluent client behavior.\n   *\n   * Set to `false` for production clusters where schemas are managed\n   * out-of-band (Confluent Cloud, regulated environments). With\n   * autoRegister off, the serializer ALWAYS resolves by `getLatestSchemaId`\n   * on the computed subject — and the locally-supplied schema bytes are\n   * ignored.\n   */\n  autoRegister?: boolean;\n}\n\nconst DEFAULT_CONTENT_TYPE = \"application/vnd.confluent.avro\";\n\n/**\n * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry\n * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s\n * `serializer` option. The schema id per (topic, isKey) tuple is resolved once\n * and cached.\n *\n * Also exposes `serializeKey(record)` for users who want Avro-encoded message\n * keys — call it manually when building the publish path; the relay does NOT\n * call it automatically (key encoding is application-level by convention).\n */\nexport class SchemaRegistrySerializer implements Serializer {\n  readonly contentType: string;\n  private readonly schemas: Record<string, SchemaSpec>;\n  private readonly keySchemas: Record<string, SchemaSpec>;\n  private readonly subjectStrategy: SubjectNameStrategy;\n  private readonly recordName:\n    | ((record: OutboxRecord, isKey: boolean) => string)\n    | null;\n  private readonly subjectFn:\n    | ((topic: string, isKey?: boolean, record?: OutboxRecord) => string)\n    | null;\n  private readonly host: string | null;\n  private readonly autoRegister: boolean;\n  // Keyed by `${topic}:${isKey}` to keep value- and key-subject ids distinct.\n  private readonly idCache = new Map<string, Promise<number>>();\n  private registry: SchemaRegistryClient | null;\n\n  constructor(opts: SchemaRegistrySerializerOptions) {\n    if (!opts.registry && !opts.host) {\n      throw new Error(\n        \"SchemaRegistrySerializer requires either a `registry` client or a `host`.\",\n      );\n    }\n    this.registry = opts.registry ?? null;\n    this.host = opts.host ?? null;\n    this.schemas = opts.schemas ?? {};\n    this.keySchemas = opts.keySchemas ?? {};\n    this.subjectStrategy = opts.subjectStrategy ?? \"TopicNameStrategy\";\n    this.recordName = opts.recordName ?? null;\n    this.subjectFn = opts.subject ?? null;\n    this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;\n    this.autoRegister = opts.autoRegister ?? true;\n  }\n\n  async serialize(record: OutboxRecord): Promise<Buffer> {\n    const registry = await this.getRegistry();\n    const subject = this.resolveSubject(record, false);\n    const id = await this.schemaId(registry, subject, this.schemas[record.topic], false, record.topic);\n    return registry.encode(id, record.payload);\n  }\n\n  /**\n   * Avro-encode the record's KEY using the registered key schema. Returns\n   * `null` when the record has no key (kafkajs/confluent treat null keys\n   * as the producer-side \"no key\" signal).\n   *\n   * Not part of the core `Serializer` interface — callers wire it into\n   * their publish path manually when they want Avro keys instead of raw\n   * UTF-8 strings.\n   */\n  async serializeKey(record: OutboxRecord): Promise<Buffer | null> {\n    if (record.key === null || record.key === undefined) return null;\n    const registry = await this.getRegistry();\n    const subject = this.resolveSubject(record, true);\n    const id = await this.schemaId(\n      registry,\n      subject,\n      this.keySchemas[record.topic],\n      true,\n      record.topic,\n    );\n    return registry.encode(id, record.key);\n  }\n\n  /**\n   * Resolve the subject for this (record, isKey) tuple. Order of\n   * precedence: explicit `subject` function → `subjectStrategy` preset.\n   */\n  private resolveSubject(record: OutboxRecord, isKey: boolean): string {\n    if (this.subjectFn) return this.subjectFn(record.topic, isKey, record);\n    switch (this.subjectStrategy) {\n      case \"TopicNameStrategy\":\n        return `${record.topic}-${isKey ? \"key\" : \"value\"}`;\n      case \"RecordNameStrategy\":\n        return this.recordNameFor(record, isKey);\n      case \"TopicRecordNameStrategy\":\n        return `${record.topic}-${this.recordNameFor(record, isKey)}`;\n    }\n  }\n\n  private recordNameFor(record: OutboxRecord, isKey: boolean): string {\n    if (!this.recordName) {\n      throw new Error(\n        `SchemaRegistrySerializer: subjectStrategy \"${this.subjectStrategy}\" requires a \\`recordName\\` resolver.`,\n      );\n    }\n    return this.recordName(record, isKey);\n  }\n\n  private schemaId(\n    registry: SchemaRegistryClient,\n    subject: string,\n    spec: SchemaSpec | undefined,\n    isKey: boolean,\n    topic: string,\n  ): Promise<number> {\n    const cacheKey = `${topic}:${isKey ? \"key\" : \"value\"}`;\n    const cached = this.idCache.get(cacheKey);\n    if (cached) return cached;\n\n    // autoRegister=false → ALWAYS resolve by latest; the local spec\n    // (if any) is ignored. Matches Confluent's auto.register.schemas=false.\n    const lookup =\n      spec && this.autoRegister\n        ? registry\n            .register({ type: spec.type, schema: spec.schema }, { subject })\n            .then((r) => r.id)\n        : registry.getLatestSchemaId(subject);\n\n    // Cache the in-flight promise so concurrent first calls don't double-register;\n    // drop it on failure so a transient error can be retried.\n    const guarded = lookup.catch((err) => {\n      this.idCache.delete(cacheKey);\n      throw err;\n    });\n    this.idCache.set(cacheKey, guarded);\n    return guarded;\n  }\n\n  private async getRegistry(): Promise<SchemaRegistryClient> {\n    if (this.registry) return this.registry;\n    const mod = await importSchemaRegistry();\n    this.registry = new mod.SchemaRegistry({ host: this.host as string });\n    return this.registry;\n  }\n}\n\nasync function importSchemaRegistry(): Promise<{\n  SchemaRegistry: new (cfg: { host: string }) => SchemaRegistryClient;\n}> {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    return (await import(\"@kafkajs/confluent-schema-registry\")) as any;\n  } catch {\n    throw new Error(\n      'SchemaRegistrySerializer with `host` needs the \"@kafkajs/confluent-schema-registry\" package. Run: npm i @kafkajs/confluent-schema-registry',\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventferry/schema-registry",
-  "version": "3.2.3",
+  "version": "3.3.0",
   "description": "Confluent Schema Registry serializer for @eventferry (Avro/Protobuf/JSON Schema)",
   "type": "module",
   "main": "./dist/index.cjs",