is this a user-breaking change?

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

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

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

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

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

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.

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.

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

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.

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
  // ...
})

unrelated, might be time to split this file up soon 😅

might be an interesting idea to consolidate the tests, just passing different schema definitions when calling

runSmokeTest({ foo: v.string() });

runSmokeTest({ foo: z.string() });

The errors are reported a bit differently so would need to take that into account but yea, definitely should have some shared tests

@juliusmarminge what about something like this?

made ^ into a library for fun

nice! feel free to use it here :) - can be a follow-up pr