Codecs composition: how to nest one into another?

[0x009922]

Using Zod v4.1.11.

I have class PublicKey, which is encoded as string. On top of it, I have Set<PublicKey>, which is encoded (in JSON) as string[].

Question: how to define codec of Set<PublicKey> while reusing the codec of class PublicKey?

Here is sample PublicKey and PublicKeyCodec:

class PublicKey {
  #algorithm: string;
  #payload: string;

  public static parse(str: string): PublicKey {
    const [alg, payload] = str.split("#");
    return new PublicKey(alg, payload);
  }

  public constructor(alg: string, payload: string) {
    this.#algorithm = alg;
    this.#payload = payload;
  }

  public toString(): string {
    return `${this.#algorithm}#${this.#payload}`;
  }
}

const PublicKeyCodec = z.codec(
  z.string(),
  z.instanceof(PublicKey),
  {
    encode: (x) => x.toString(),
    decode: (x) => PublicKey.parse(x),
  },
);

This works as expected. However, this does not work:

const PublicKeySetCodec = z.codec(
  z.array(PublicKeyCodec),
  z.set(PublicKeyCodec),
  {
    // Zod expects: (value: Set<string>) => PublicKey[]
    encode: (x) => [...x],
    // Zod expects: (value: PublicKey[]) => Set<string>
    decode: (x) => new Set(x),
  },
);

As a workaround, I can duplicate the contents of PublicKeyCodec:

const PublicKeySetCodec2 = z.codec(
  z.array(z.string()),
  z.set(z.instanceof(PublicKey)),
  {
    encode: (x) => [...x].map(y => y.toString()),
    decode: (x) => new Set(x.map(y => PublicKey.parse(y))),
  },
);

Is there a way of doing so while treating PublicKeyCodec as a black box?

[dosubot[bot]]

Hi @0x009922! I'm Dosu and I’m helping the zod team.

I'm a bot trained on Zod's codebase and issues.

In Zod v4.1.11, codecs are fully composable in arrays and objects, but there isn't a built-in way to automatically compose encode/decode logic for container types like Set<T> by treating an inner codec as a black box. Each codec must define its own encode/decode logic, so you can't directly "nest" one codec inside another and have the encode/decode steps automatically chained for you. This is a current design decision in Zod v4—see this discussion.

To avoid duplicating logic, you can define reusable encode/decode helpers outside of Zod and use them in your container codec. For example:

// Reuse PublicKeyCodec's encode/decode
const encodePublicKey = PublicKeyCodec.encode;
const decodePublicKey = PublicKeyCodec.decode;

const PublicKeySetCodec = z.codec(
  z.array(z.string()),
  z.set(z.instanceof(PublicKey)),
  {
    encode: (set) => [...set].map(encodePublicKey),
    decode: (arr) => new Set(arr.map(decodePublicKey)),
  }
);

This way, you treat PublicKeyCodec as a black box and avoid duplicating its logic. For more on codec composition, see the official docs and the related GitHub issue.

If this answers your question, please close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[0x009922]

@dosu No, this violates using PublicKeyCodec as a black box. You define input of the set codec as z.array(z.string()), which leaks the knowledge that PublicKeyCodec's encoded representation is string. Same for the output.

If there was a way to get the underlying "input" and "output" schemas of the child codec, that could solve the problem, I guess. For example:

const PublicKeySetCodec = z.codec(
  z.array(PublicKeyCodec.inputSchema),
  z.set(PublicKeyCodec.outputSchema),
  { ... }
);

[dosubot[bot]]

You're correct—Zod codecs in v4.1.11 do not expose their input or output schemas as public properties like inputSchema or outputSchema, so you can't compose container codecs in a fully black-box way without knowing the internal representation of the child codec. Each codec must be defined with its own explicit schemas, and there isn't a built-in API for introspecting or extracting these from another codec instance for composition (docs, issue #5252).

The best workaround is to keep your encode/decode logic DRY by reusing the encode/decode functions from your inner codec, but you still need to specify the schemas explicitly at the container level. This is a current design decision in Zod v4.

If this answers your question, please close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[0x009922]

I see. Well, this is fine.

I'd close this discussion after a human reply to confirm that this is a final decision and there are indeed no better workarounds.

[julienmonnard]

Hello! I'm not sure I will answer your question completely, but I saw your discussion as I'm taking a look at nested codecs as well.
Your last suggestion caught my attention because I think here is a way to get the input and output schemas that you would like to access. As this is not directly documented, I am not sure they are considered "public", but they do exist.
Based on your last code snippet, this seems to work (at least at the type level, I didn't test the runtime)

const PublicKeySetCodec = z.codec(
  z.array(PublicKeyCodec.in),
  z.set(PublicKeyCodec.out),
  { ... }
);

Feel free to discard my comment if I'm off topic, I just thought this might help 🙂

[0x009922]

Thank you very much @julienmonnard!

This works perfectly both on type-level and in runtime. This is exactly what I was looking for!

Thank you for your help 😄