Unexpected satisfies error for nested function

[ocavue]

I have two type definitions. One uses pure TypeScript, while the other uses valibot. I want to make sure that these two types are in sync, so we utilize the satisfies technique from #3.

I found an unexpected satisfies error in my code, as shown below.

Playground link

import * as v from 'valibot';

type GenericOutputSchema<TOutput> = v.BaseSchema<
  unknown,
  TOutput,
  v.BaseIssue<unknown>
>;

export type LogLevel = 'info' | 'debug' | 'warn';
export const LogLevelSchema = v.union([
  v.literal('debug'),
  v.literal('info'),
  v.literal('warn'),
]) satisfies GenericOutputSchema<LogLevel>;

export type LogHandler = (level: LogLevel) => void;
export const LogHandlerSchema = v.pipe(
  v.function(),
  v.args(v.tuple([LogLevelSchema])),
  v.returns(v.void()),
) satisfies GenericOutputSchema<LogHandler>;

export type OnLog = (logHandler: LogHandler) => void;
export const OnLogSchema = v.pipe(
  v.function(),
  v.args(v.tuple([LogHandlerSchema])),
  v.returns(v.void()),
) satisfies GenericOutputSchema<OnLog>;
//~~~~~~~~~
//Type 'SchemaWithPipe<readonly [FunctionSchema<undefined>, ArgsAction<(...args: unknown[]) => unknown, TupleSchema<[SchemaWithPipe<readonly [FunctionSchema<undefined>, ArgsAction<(...args: unknown[]) => unknown, TupleSchema<[UnionSchema<[LiteralSchema<"debug", undefined>, LiteralSchema<...>, LiteralSchema<...>], undefined>...' does not satisfy the expected type 'GenericOutputSchema<OnLog>'.
//  Types of property '"~standard"' are incompatible.
//    Type 'StandardProps<(...args: unknown[]) => unknown, (args_0: (...args: unknown[]) => unknown) => void>' is not assignable to type 'StandardProps<unknown, OnLog>'.
//      Type '(args_0: (...args: unknown[]) => unknown) => void' is not assignable to type 'OnLog'.
//        Types of parameters 'args_0' and 'logHandler' are incompatible.
//          Type 'LogHandler' is not assignable to type '(...args: unknown[]) => unknown'.
//            Types of parameters 'level' and 'args' are incompatible.
//              Type 'unknown' is not assignable to type 'LogLevel'. (1360)

export {};

[dosubot]

Hi @ocavue! I'm Dosu and I’m helping the valibot team.

The error with satisfies for nested function schemas in Valibot happens because Valibot's function schemas (using v.function(), v.args(), v.returns()) infer parameter types as unknown for nested functions. TypeScript's satisfies operator requires exact structural compatibility, so when your schema's inferred types use (...args: unknown[]) instead of the specific parameter types (like LogLevel), TypeScript reports a mismatch. This is a known limitation of Valibot's modular API and type inference design—currently, it doesn't propagate specific parameter types through nested function schemas, which makes satisfies checks fail for these cases. There isn't a documented workaround for this yet; it's a tradeoff for Valibot's modularity and bundle size focus see details in the Valibot thesis.

To reply, just mention @dosu.

---

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

[ocavue]

I kind of understand why this error occurs. Since the LogHandlerSchema will return a new function callback as output. In this output function, args and return value will be validated during runtime, thus the output function matches the type LogHandler. However, the input function (the logHandler function that the user provides) doesn't need to match LogHandler, thus it's ...args: unknown[]) => unknown.

const onLog: OnLog = (logHandler) => {
  return logHandler('debug');
};

console.log("The following v.parse will succeed");
const onLogParsed = v.parse(OnLogSchema, onLog);

function badLogHandler(level: LogLevel) {
  // This should return void but a string is returned
  return 'UNEXPECTED_RETURN_VALUE';
}
const logHandler = badLogHandler as LogHandler;

console.log("The following call will get a runtime error because UNEXPECTED_RETURN_VALUE");
onLogParsed(logHandler as (...args: unknown[]) => unknown);

So the question would be: how should I write my valibot schema definition so that the OnLogSchema and OnLog have the same shape (i.e., force the passed logHandler must match the type LogHandler).

[dosubot]

Valibot currently can't enforce that a function argument (like logHandler) matches a specific function type (like LogHandler) at the type level within nested function schemas. This is because Valibot's function schemas always infer input parameter types as unknown, so TypeScript's satisfies operator can't guarantee structural compatibility for nested functions with specific parameter types or return types see docs see thesis.

At runtime, Valibot will validate the arguments and return values when the function is called, but at compile time, the input function type remains (...args: unknown[]) => unknown. There isn't a built-in workaround to make OnLogSchema and OnLog have the exact same shape at the type level. If you need strict compile-time enforcement, you'll need to rely on manual TypeScript checks or custom type guards outside of Valibot.

If you want to ensure runtime safety, your current schema setup is correct: Valibot will throw if the function is called with invalid arguments or returns an invalid value. But for compile-time type safety of nested function types, this is a known limitation of Valibot's modular design see docs.

To reply, just mention @dosu.

---

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

[ocavue]

I guess I need to use this to assert the passed function matches the declared type (instead of (...args: unknown[]) => unknown)

export function vFunction<
  T extends (...args: any[]) => unknown,
>(): v.GenericSchema<T> {
  return v.function() as unknown as v.GenericSchema<T>;
}