Using Mutative with Zod's readonly() schemas

[pawelwilczewski]

For my project, I am considering the best way of using Zod's .readonly() schemas with Mutative's development-only auto-freezing.

Please correct me if I'm wrong, but it appears that for optimal performance, we don't want to freeze the objects when using Mutative. However, since my objects are a result of parsing external data, I often have schemas which I declare readonly, i.e.:

export const mySchema = z.object({
    a: someOtherReadOnlySchema,
    b: z.string(),
    c: z.array(mediumSizeReadonlyObjectSchema).readonly(),
  }).readonly();

Since Zod's readonly() freezing behaviour does not change between development and production, I have two questions:

1. Is it a "big deal" that these initial objects are frozen - do frozen objects perform worse for repeated usage of Mutative on them? Schemas sometimes contain arrays of 50k+ objects, each with 10 keys.
2. Are there any best practices for this sort of scenario?

I suppose the ideal solution here is matching Zod's readonly behaviour with Mutative's, so it doesn't actually freeze in production, only in development. That doesn't seem to be an option, but if the idea is right, I may implement logic around Zod to facilitate that.

I am open to any suggestions (also swapping out Zod for anything that may be more suitable).

Edit: To answer this for my use case, I could run some benchmarks and compare. However, I am more interested in knowing the suggested approaches that I should default to when using this library.

[unadlib]

Hi, thanks for the detailed question and for explaining your use-case so clearly 🙌

Let me answer in two parts: how Mutative behaves with frozen objects, and what I’d recommend when combining it with Zod’s .readonly().

---

1. Are frozen initial objects a “big deal” for Mutative?

Short answer: no — Mutative is perfectly happy with Object.freeze base state.

A few details:

• Zod’s .readonly() parses the value and then calls Object.freeze() on the result.
• Mutative never mutates your base state. It wraps it in proxies and only writes into lazily created copies, so the fact that the base is frozen doesn’t conflict with how updates are performed.
• Reads from a frozen object are essentially the same cost as reads from a non-frozen one; the expensive part of Object.freeze is the act of freezing, not later access.

So:

• Re-using a large frozen object (arrays with 50k items, objects with ~10 keys each) as the base state for many Mutative updates is fine. Mutative’s work per update depends on what you actually change, not on whether the base is frozen.
• The main overhead you pay is at parse time, when Zod walks the tree and freezes it. That’s a one-off cost per parse.

You can see the general cost of deep freezing in Mutative’s own benchmarks: when we enable auto-freeze, throughput drops noticeably because every next state is frozen. In your case Zod is only freezing on input parsing, not on every update, so it’s significantly less problematic.

So unless you are:

• parsing extremely often and
• each parse involves huge graphs

…it’s usually not worth contorting your design just to avoid those frozen inputs.

---

2. Suggested practices with Zod .readonly() + Mutative

From Mutative’s side there’s nothing special you must do — frozen inputs are supported. The interesting question is how you want to balance:

• Runtime safety (catch accidental mutations outside Mutative)
• Performance (avoid unnecessary deep Object.freeze on very big structures)
• Type-level readonly in TypeScript

Here are a few patterns I’d recommend.

---

Option A – Keep .readonly() and don’t worry (simple + safe)

If you:

• parse once at the boundary (e.g. when data comes from the network), and
• then mostly operate on that data via Mutative

you can absolutely keep your current code:

export const mySchema = z.object({
  a: someOtherReadOnlySchema,
  b: z.string(),
  c: z.array(mediumSizeReadonlyObjectSchema).readonly(),
}).readonly();

Pros:

• Strong runtime guarantees: nobody can accidentally mutate parsed data outside Mutative.
• No extra Mutative complexity: it works with frozen base states as-is.
• The cost of Object.freeze happens once per parse.

Cons:

• You still pay the deep-freeze cost in production for those big arrays. Depending on your throughput requirements that may or may not matter.

If this performs well enough in your benchmarks, I’d honestly stick with it. It’s a very defensible default.

---

Option B – Type-level readonly, dev-only freezing

If you want Mutative’s “freeze only in development” philosophy while still using Zod, you can decouple:

• TypeScript readonly (always on)
• Runtime Object.freeze (dev-only)

Something like:

const mySchemaCore = z.object({
  a: someOtherReadOnlySchema,
  b: z.string(),
  c: z.array(mediumSizeReadonlyObjectSchema),
});

// Type is always readonly
export type MyData = Readonly<z.infer<typeof mySchemaCore>>;

// Runtime parser you actually use
export const parseMyData = (input: unknown): MyData => {
  const value = mySchemaCore.parse(input);

  if (process.env.NODE_ENV !== "production") {
    // Implement your own (possibly shallow) dev-only freeze
    return deepFreeze(value) as MyData;
  }

  return value as MyData;
};

Here deepFreeze can be your own simple helper (or even shallow Object.freeze if that’s enough for your invariants).

This gives you:

• Readonly types everywhere.
• Dev-only runtime freezing, aligned with Mutative’s recommended enableAutoFreeze in development, disable in production.

And you don’t rely on Zod’s .readonly() at runtime at all.

---

Option C – Dev-only .readonly() wrapper around Zod

If you like Zod’s .readonly() ergonomics and don’t care about its ZodReadonly type wrapper, you can also define:

const mySchemaCore = z.object({
  a: someOtherReadOnlySchema,
  b: z.string(),
  c: z.array(mediumSizeReadonlyObjectSchema),
});

export const mySchema =
  process.env.NODE_ENV === "production"
    ? mySchemaCore
    : mySchemaCore.readonly();

export type MyData = Readonly<z.infer<typeof mySchemaCore>>;

• In dev: you get actual Object.freezed values.
• In prod: you skip the freeze entirely.
• You still get a readonly type via Readonly<...>.

The only caveat is that z.infer<typeof mySchema> won’t be exactly your readonly type in production, so it’s better to export and use MyData everywhere instead of inferring from mySchema.

---

3. So what should I “default” to?

If I had to recommend a default for Mutative users:

1. Don’t worry about frozen base state from Mutative’s perspective — it’s supported and safe.

2. Start with the simple combination:

   • Use Zod .readonly() where you genuinely want runtime immutability for parsed external data.
   • Use Mutative with enableAutoFreeze in dev and disabled in prod.

3. If profiling shows that Zod’s deep freeze is a meaningful bottleneck for your 50k-element arrays:

   • Switch to Option B or C above to keep type safety while limiting Object.freeze to development.

You definitely don’t need to change validation libraries just to keep Mutative happy. Zod plays fine with Mutative; it’s just a question of how much runtime freezing you want to pay for.

If you end up with some benchmark numbers for “Zod .readonly() vs dev-only freeze wrapper” on those bigger arrays, I’d love to see them — we can link them from the docs for others with similar concerns.

[pawelwilczewski]

Thank you very much for the detailed response. This is very valuable and exactly answered my questions.

I will try my best to find some time to prepare benchmarks to reflect the performance of the options you listed (hopefully within the next week).

Thanks again!

[pawelwilczewski]

I managed to write up a little benchmark, which illustrates the points you made. The typing benefits/drawbacks of each option are not expressed here, but they are probably obvious to anyone interested in this topic.

https://jsbm.dev/JIla3dRXWkEMs

Results preview:

It's not exactly "Zod .readonly() vs dev-only freeze wrapper", but from the first two tests, you can derive how much you are paying for freezing in Zod.

Expectedly (I think), you pay less for autofreeze in mutative than freezing in Zod. I'd assume that's because you only freeze the parts that you "touch"? Example:

mutative.create(DATA.parsedMutable, (draft) => {
  draft.y = "hello"
}, { enableAutoFreeze: true })

Feel free to use any part of the benchmark/conversation in any way. Let me know if there could be something off with the benchmark too.

[unadlib]

Thanks a lot for taking the time to put this benchmark together and sharing it — this is super helpful.

I had a look at your cases and the results line up very nicely with the intuition:

• Zod’s .readonly() pays the freezing cost up-front on the entire parsed tree.
• Mutative’s enableAutoFreeze only freezes the parts of the tree that are actually “touched” (new or changed nodes), so the cost scales with how much you update rather than with the total size of the data.

So your interpretation:

you pay less for autofreeze in mutative than freezing in Zod, because you only freeze the parts that you "touch"

is exactly right. That’s the design goal behind Mutative’s auto-freeze behavior.

A few small notes / ideas in case you ever feel like extending the benchmark:

• It could be interesting to add a case where the update does rewrite most of the structure (e.g. mapping over all 50k items) — in that scenario Mutative will naturally get closer to the “freeze everything” cost, which helps show the trade-off more clearly.
• Likewise, a case that only tweaks a tiny part (e.g. one nested field) highlights how cheap auto-freeze can be relative to “freeze the whole input”.

But as it stands, this already illustrates the main point really well. I really appreciate that you also called out the type-level trade-offs separately — that’s usually what people care about next once they see the performance picture.

Thanks again for sharing your findings!