feat: allow customizing schema combination

[EskiMojo14]

This allows extension like refinement and transformation.

const env = createEnv({
  server,
  client,
  shared,
  runtimeEnv: process.env,
  createFinalSchema: (shape) => z.object(shape).refine(extraCheck),
  // or
  createFinalSchema: (shape) => pipe(object(shape), check(extraCheck))
})

fixes #268
alternative approach to #169

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
t3-env	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 23, 2025 9:23pm

[vercel]

@EskiMojo14 is attempting to deploy a commit to the t3-oss Team on Vercel.

A member of the Team first needs to authorize it.

[juliusmarminge]

is this a user-breaking change?

[EskiMojo14]

CreateEnv is exported, so technically yes - in practicality I doubt anyone was relying on it

[juliusmarminge]

It's exported cause the other packages needs it. I should add some @internal jsdoc annotations to things

[juliusmarminge]

how does this work with extends? can you add some tests for that

[EskiMojo14]

can do - extends just assigns all of the properties to the final result from the schema, like it did before

[juliusmarminge]

what I was thinking of was more like what if you do some combinator that accesses server stuff, will that cause an "invalid server access" or not? I'd think not since you're not giving the proxy as the argument there right? also what are the types in that callback like, server variables will be undefined when the combinator runs on the client etc etc

[EskiMojo14]

see #240, the whole Proxy thing doesn't really work properly with extends - but that's irrelevant to createFinalSchema, because the proxy isn't applied until the schema is finished validating.

As for types, you're correct - it's currently typed to what it'd be on the server, like the rest of the library (client + server + shared). I don't know how much it would complicate things to mark the server variables as optional.

[EskiMojo14]

had a brainwave and opened #316 to fix #240

coming back to this - schemas have always been allowed to access any key they want, though that'll only include the ones that have already been checked with the current schema (not any extended ones), since the schema ditches unknown keys.

[juliusmarminge]

schemas have always been allowed to access any key they want

No since accessing a server var on the client would throw an error - so e.g if you'd chain on a toLower() you'd get the invalid access before. It seems here we'd get a "Cannot access property toLower of undefined" which feels suboptimal - but maybe I'm overthinking it

[EskiMojo14]

schemas have never been run on the output of presets, they were always run before it. they have always been passed the raw runtimeEnv option, and any presets were merged into the parsed result.

[EskiMojo14]

I understand the concern, but I don't think there's a good way to expose type-wise that the server variables might not be defined to the createFinalSchema callback. Best case, the schema result also reflects the server variables as optional (whereas they're currently always defined), worst case the inference breaks completely. We also can't wrap the intermediate parsed value in a Proxy since we don't have access to it.

We could possibly pass some sort of makeSafe function to the user that would make a Proxy, but that would need to be opt in.

createObjectSchema: (shape, { isServer, makeSafe }) => z.object(shape).refine((_env) => {
  const env = makeSafe(_env) // wraps in Proxy
  if (!isServer) env.SERVER_ENV // throws
  // ...
})