A lightweight TypeScript library for assertion-based runtime data validation

30 pointsby nayajunimesh25 days ago35 comments(github.com)

Comments (9)

nayajunimesh•25 days ago

Most validation libraries like Zod create deep clones of your data during validation, which can impact performance in high-throughput applications. I built decode-kit to take a different approach: assertion-based validation that validates and narrows TypeScript types in-place, without any copying or transformation. Here's what the API looks like in practice:

import { object, string, number, validate } from "decode-kit";

// Example of untrusted data (e.g., from an API) const input: unknown = { id: 123, name: "Alice" };

// Validate the data (throws if validation fails) validate(input, object({ id: number(), name: string() }));

// `input` is now typed as { id: number; name: string } console.log(input.id, input.name);

When validation fails, decode-kit takes an equally thoughtful approach. Rather than being prescriptive about error formatting, it exposes a structured error system with an AST-like path that precisely indicates where validation failed. It does include a sensible default error message for debugging, but you can also traverse the error path to build whatever error handling approach fits your application - from simple logging to sophisticated user-facing messages.

The library also follows a fail-fast approach, immediately throwing when validation fails, which provides both better performance and clearer error messages by focusing on the first issue encountered.

I'd love to hear your thoughts and feedback on this approach.

•24 days ago

kenward•24 days ago

> fail-fast approach, immediately throwing when validation fails

would this mask any errors that would occur later in the validation?

nayajunimesh•24 days ago

With the fail-fast approach, yes - unless we introduce an option to collect all errors. In my own applications, I have found this to be a better default because the 'average' requests is valid and paying a constant overhead just to be thorough on rare invalid cases can be wasteful.

My overall takeaway has mostly been to not optimize for the worst case by default. Keep fail-fast as baseline for boundaries and hot paths, and selectively enable “collect all” where it demonstrably saves human time.

yencabulator•21 days ago

A useful counterexample, where one wants to see all errors, is validating form input. But it's very much ok to say your library is not meant for that use case!

nayajunimesh•21 days ago

That is a good point! How do you feel about fail-fast by default but being able to configure a validator to collect all errors (like Zod does by default)? Something like array(number(), { failFast: false });

We currently expose error as a tree structure so that it's easy to map an error to a value or build custom error messages (we only provide debug error message) and I haven't been able to come up with a satisfactory error API that accommodates multiple error paths, but you raise an excellent point. Thanks for pointing out.

yencabulator•21 days ago

My instinct is to say keep it small, simple & focused.

sizediterable•24 days ago

Need it be said https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-va...

tomjakubowski•24 days ago

Libraries like runtypes, zod, et al. market themselves as validation libraries, but they function as parsing libraries in the sense this article means: with them you "parse" untyped POJOs at the I/O boundary and get typed values (or a raised exception) out the other end.

Typescript language features like branded types, private constructors can make it so those values can only be constructed through the parse method.

They're really not much different, in terms of type safety*, from something like Serde.

*: they are of course different in other important ways -- like that Serde can flexibly work with all kinds of serialized formats.

nayajunimesh•24 days ago

We actually use the idea of branded types in one of the validators (iso8601), and I also understand that it doesn't replace fully transformed values.

https://github.com/nimeshnayaju/valleys?tab=readme-ov-file#i...

nayajunimesh•24 days ago

I understand completely, and the library is intentionally unopinionated in that regard. We simply ensure that the value passed matches the provided schema and ruleset and refine the type in-place.

In certain cases (like validating that an input is ISO8601 format), we refine the input type to a branded type (we have a Iso8601 branded type). At runtime it's just a string, but at compile time TypeScript treats it as a distinct type that can only be obtained through validation. But, it is still not transforming or parsing the data in the way that the blog post intends, which is by design.

https://github.com/nimeshnayaju/valleys?tab=readme-ov-file#i...

ale•24 days ago

Libraries like these are meant for runtime validation. I agree though. I prefer to use the compiler itself (tsc --noEmit) than recreating the validation logic.

mirekrusin•24 days ago

It doesn't compete with static type system, it complements it. Static type system in typescript can't do anything with unknown/any values that are crossing i/o boundary - they require runtime assertion to bring them into statically typed, safer world.

scottmas•25 days ago

The whole benefit over zod seems to be perf, so could you do some benchmarking? I wonder if it’s worth it

nayajunimesh•21 days ago

Hey, I did some benchmarks if you're interested - benchmarks results are in the README.md.

https://github.com/nimeshnayaju/zod (Fork of Zod's repo which already included benchmarks comparing Zod 4 against Zod 3, so I simply integrated my validation library)

https://github.com/nimeshnayaju/valibot-benchmarks (An unofficial benchmark suggested in another comment comparing Valibot against Zod)

nayajunimesh•24 days ago

Yes, the primary focus is memory efficiency; performance improvement is a side effect of that. From my own benchmarks, I have found that to be the case. If you're validating thousands of objects per second or working with memory constraints, the difference becomes quite significant. Happy to share the full benchmark code if you'd like to run them yourself!

•24 days ago

typeofhuman•24 days ago

You should include this benchmark in your repo and README if you want to build trust.

I think anything that declares itself as a performance improvement over the competition ought to prove it!

seabass•24 days ago

I was surprised by the source including a bunch of try/catch, which results in deopts for that code path as far as I understand, given that the stated benefit over Zod and other validators was that this should be run in performance critical code. I’d be curious to see benchmarks that show whether this is faster than zod, valibot, and zod4 mini in hot code paths.

nayajunimesh•24 days ago

We do use try/catch in a few places. However, in normal operations (valid input), no exceptions are thrown - the try/catch blocks are present in certain validators but do not execute their catch clauses. AFAIK, modern engines generally don’t impose large steady-state penalties merely for the presence of a try/catch when no exception is thrown; the measurable cost is usually when exceptions are actually thrown. When an element/property fails, the catch is used to construct precise error paths. That’s intentionally trading some failure-path overhead for better developer diagnostics.

In the new few days, I'll prepare benchmarks to compare with Zod and Valibot!

seabass•23 days ago

The information I have on this could be outdated, so take this with a grain of salt, but it used to be the case that in hot code paths the presence of a try/catch would force a deoptimization whether or not you throw. The optimizing compiler in v8, for example, would specifically not run on any functions containing try/catch due to its inability to speculatively inline the optimized code. If you're feeling up to it, you can prove whether that is still the case with `d8 --allow-natives-syntax --trace-deopt ./your-script.js` and sprinkle in some `%OptimizeFunctionOnNextCall` in your code. I did a quick search for `try {` in the zod 4 source and didn't see anything, so I suspect that the performance issues surrounding try/catch are still at least somewhat around, unless they are simply avoiding try/catch for code cleanliness which could totally be the case. Regardless, I'd encourage you to look into whether plain old boolean return values in your validators would work for your project. Just include the `throw` part without all the `try/catch` and the code itself will likely be simpler, faster, and easy for the JIT to optimize. Good luck on those benchmarks.

nayajunimesh•22 days ago

Hey, this comment was actually very helpful. While running benchmarks, I noticed my union validator was consistently underperforming, and your insight about try/catch deoptimization made it much easier to pinpoint the issue. I ended up updating the validation logic to not use try catch frivolously and I saw significant performance improvement.

For benchmarks, I forked Zod, which already included benchmarks comparing Zod 4 against Zod 3. Here are the results (in README.md) if you're interested:

https://github.com/nimeshnayaju/zod

I noticed significantly better performance than both Zod 3 and Zod 4 across most validation scenarios (especially validations that involved rules like min/max length, etc), with the exception of simple object parsing.

I also forked another benchmark suggested in a different comment if you're interested (I noticed similar results).

https://github.com/nimeshnayaju/valibot-benchmarks

CharlesW•24 days ago

OP, you could potentially leverage an existing benchmark suite: https://naruaway.github.io/valibot-benchmarks/

nayajunimesh•22 days ago

Hey, thanks for the link! I was able to add the library to the benchmark quite easily. Here's the fork if you're interested:

https://github.com/nimeshnayaju/valibot-benchmarks

I have included the results I obtained from running the benchmark in the README.md. I'd love for you to also take a look at the changed code to see if I may have missed something with the integration. Curious to hear your feedback too!

CharlesW•22 days ago

Nicely done, and thanks for following up!

nayajunimesh•24 days ago

Thank you, this is quite helpful. Will take a detailed look very soon!

typeofhuman•24 days ago

How do you know you're tool is more performant?

nayajunimesh•22 days ago

Hey, I did some benchmarks if you're interested - benchmarks results are in the README.md.

https://github.com/nimeshnayaju/zod (Fork of Zod's repo which already included benchmarks comparing Zod 4 against Zod 3, so I simply integrated my validation library)

https://github.com/nimeshnayaju/valibot-benchmarks (An unofficial benchmark suggested in another comment comparing Valibot against Zod)

gr4vityWall•24 days ago

It would be nice to provide some benchmarks comparing it to Zod, arktype, etc. Comparing it across different runtimes (Node.js, Bun, web browsers, etc.) would be great, too.

nayajunimesh•22 days ago

Hey, I did some benchmarks if you're interested - benchmarks results are in the README.md.

https://github.com/nimeshnayaju/zod (Fork of Zod's repo which already included benchmarks comparing Zod 4 against Zod 3, so I simply integrated my validation library)

https://github.com/nimeshnayaju/valibot-benchmarks (An unofficial benchmark from another user comparing Valibot against Zod)

gr4vityWall•21 days ago

Thanks, I appreciate that you added them. :)

They show a lot of potential and promising results. Any guess why Valley is slower for parsing objects with primitive values?

cluckindan•24 days ago

This would be way more powerful if there was a way to infer a validator from a TypeScript type.

jasonlernerman•24 days ago

arktype does this too!

matt-attack•24 days ago

Arktype is fantastic.

orangee•24 days ago

assertion-based API is a neat concept

revskill•24 days ago

Love it. I hate zod.

esafak•24 days ago

Why?

revskill•18 days ago

[dead]