z.codec for freely converting between isomorphic data structures

[stefan-wullems]

Hey there, love v4 version. I was just looking for a zod plugin that would convert a zod schema to json schema for defining RxDB collections. I felt very lucky to come across the new beta update which includes exactly that.

My issue

I want to do something very basic, this is my schema

const note = z
          .interface({
            noteId: z.uuid(),
            body: z.string(),
            createdAt: z.iso.datetime().meta({ final: true }),
            topics: z.array(z.string()),
          })
          .meta({
            // RxDB attributes
            version: 0,
            indexes: ["createdAt", "noteId"],
            primaryKey: "noteId",
            keyCompression: true,
          })

Now what I want to do specifically has to do with the topics field. It's now as z.array(z.string()), which is fine, but ideally I want it to be z.set(z.string() because it simplifies my domain logic in a trivial way, but still I want it 👀 . However, z.set(z.string()) is not supported by .toJSONSchema because it is "unrepresentable".

I tried doing z.array(z.string()).transform((topics) => new Set(topics)) to start with a type that is representable and then do the conversion, but then when I pass this schema to .toJSONSchema I get the following error "Transforms cannot be represented in JSON Schema".

I can surpress these errors by calling .toJSONSchema with the { unrepresentable: "any"} option, but then I'd lose my type info.

It makes sense why it doesn't work. If the validation is used to validate data coming in from the database, such a transform would be fine, but then once I try to store it again, the transform doesn't make sense anymore. I wonder if this is the rationale behind it.

Of course I can solve this problem by having two separate schema's, one storage schema and one domain schema. The storage schema follows the rules that .toJSONSchema imposes while the domain schema can parse data to a more convenient format for business logic. This seems like a lot of repeating myself however.

What I want

Anyway, what I would really want is to have a schema that has codec like behavior (e.g. elm-codec, that allows me to convert freely between isomorphic data representations. Meaning I can use it as both a storage schema and a domain schema at the same time. Specifying how I want the two to map to each other.

An example would be something like this:

const noteCodec = z.codec(z
          .interface({
            noteId: z.uuid(),
            body: z.string(),
            createdAt: z.iso.datetime()
                .decode(z.date()).meta({ final: true }),
                ^^ new method
            topics: z.array(z.string()).decode(z.set(z.string()),
          })
          .meta({
            // RxDB attributes
            version: 0,
            indexes: ["createdAt", "noteId"],
            primaryKey: "noteId",
            keyCompression: true,
          }))

const inputSchema = z.toJSONSchema(noteCodec.input) // Works fine
z.toJSONSchema(noteCodec.output) // Throws "Sets cannot be represented in JSON Schema"

const domainNote =  noteCodec.decode({ 
    noteId: "18b664f2-5f34-427b-b30a-0dd8ff55dbd3", 
    body: "Hey", 
    createdAt: "20250411T105757Z",
    topic: ["Math", "Doomsday"]
})

const storageNote = noteCodec.encode({
    noteId: "18b664f2-5f34-427b-b30a-0dd8ff55dbd3", 
    body: "Hey", 
    createdAt: new Date()
    topic: new Set(["Math", "Doomsday"])
})

This would be useful to me in other scenarios as well.

const payloadCodec = z.interface({ body: z.string() }) 

const eventCodec = z.codec(
    z.interface({ 
        type: z.literal('create'), 
        payload: payloadCodec 
    }),
    payloadCodec,
    // Or something better idk
    { to: evt => evt.payload, 
       from: p => z.interface({ 
           type: z.literal('create'), 
           payload: payloadCodec 
       })
     },
)

const payloadFromEvent = eventCodec.decode
const eventFromPayload = eventCodec.encode